Ghostlight/docs/public-architecture/index.md

51 lines
2.1 KiB
Markdown
Raw Normal View History

---
title: Architecture
description: A public reference for Ghostlight's persistent-world simulation, agent pipeline, and authority boundaries.
---
Ghostlight is a persistent generative-agent engine. Models propose perceptions,
decisions, interpretations, and bounded worldbuilding operations; deterministic
code decides what those proposals are allowed to mean; one revisioned
`WorldKernel` commits canonical change.
This reference describes the implemented Ghostlight Dungeon body and the
consumer-neutral machinery being prepared for Delvehold. It distinguishes live
code from planned scale work. In particular, the 240-cell ceiling is an active
attention budget, not a claim that the world contains only 240 subjects. The
current full-world target is approximately 2,400 potentially acting entities
under roughly ten-percent active cover.
## Read the machine
- [[Architecture at a glance]] — the organs and the main dataflow.
- [[Authority and state]] — who is allowed to decide and persist what.
- [[Runtime pipelines]] — Session Zero, compilation, foreground turns,
strategic simulation, elaboration, and newspapers.
- [[Agents and model stages]] — every production agent and model stage, its
inputs, output, model class, authority, and downstream gate.
## The compact rule
```text
source evidence + canonical state
↓ projection
model proposal
↓ deterministic validation
typed mutation or refusal
↓ WorldKernel
atomic state + event + receipt commit
```
A model response is never world truth merely because it is well written or
well typed. Receipts bind every accepted inference to its exact stage and world
snapshot. Invalid, stale, or partially illegal work leaves canonical state
unchanged.
## Scope
Give the world library a sealed public boundary Completes the move begun in the previous commit, which does not build on its own. `ghostlight` is now a library crate with an explicit public surface; `ghostlight-dungeon` is a consumer that reaches the kernel through it and cannot reach past it. Deleted first: `mod world;`, the nine unused re-exports, the `#[cfg(test)]` re-export block, `fixture_controller_opportunities`, the five inference `fixture_*` items, Dungeon's own `VerifiedPrincipalEvidence`, and Dungeon's direct `ghostlight-persona-projection` dependency. The seal. `WorldKernel`, `WorldState`, `reduce`, `apply_effect`, `CommandEnvelope`, `AuthenticatedCaller`, the journal writer, every ID `issue()`, and `ScopeDigest::fixture` carry no `pub` of any kind and no feature gate; the crate declares no `[features]`, so no build configuration can lift them. Ten `compile_fail` doc-tests stand outside the crate and pin each one to its error code. The principal seam. The library owns `VerifiedPrincipalEvidence` with a public `new`; `mailbox` still bounds it by `valid_until` at ingress. A Dungeon test counts the minters in production source and fails at anything but one. The port contract (Q1-7). `PreparedInference::prepare` (renamed from the free `prepare_invocation`), `InferenceOutput::new`, and `InferenceFault::{retryable, recovery_required, integrity_violation}` are now the port's public constructors, so a consumer-implemented `InferencePort` can answer without test-only wrappers. `TracingInferencePort` is an ungated decorator. The tick-ordering test (Q1-8) derives its cover from a real active world through `derive_cover` and asserts two cells; its ordering and shared-tick assertions are unchanged. Behaviour is unchanged. The library's 420 unit tests are the base `world::` set with the prefix stripped — the names diff empty. Dungeon keeps all 49 of its names and gains two Soul tests the boundary requires. No schema string, digest preimage, or store layout is touched. Windows verification only; the Linux release is Idunn's build. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-16 02:06:07 +02:00
The public reference follows the current source in `crates/ghostlight` (the
library) and `crates/ghostlight-dungeon` (the daemon that consumes it).
Research plans and older fixture pipelines remain in the repository but are not
presented as live runtime stages. Physical model names are deployment choices;
the architecture names the stable logical tiers: Fast, Balanced, and Capable.