Docs and comments: README leads with the kernel and says the Dungeon is parked at the tag; AGENTS, status lines, kernel comments

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Meta Vens 2026-10-22 23:56:56 +02:00
commit ef11427e24
10 changed files with 50 additions and 58 deletions

View file

@ -5,7 +5,8 @@
Ghostlight is a Rust world kernel and the play daemon built on it. Models Ghostlight is a Rust world kernel and the play daemon built on it. Models
propose; the kernel admits or refuses. The same kernel is meant to run the propose; the kernel admits or refuses. The same kernel is meant to run the
simulation behind Aetheria's public story, a persistent cast and storylets, as simulation behind Aetheria's public story, a persistent cast and storylets, as
well as Ghostlight Dungeon, the single-player DM-led client. `README.md` says well as Ghostlight Dungeon, the single-player DM-led client (parked at
tag `parked/ghostlight-eve-surface`). `README.md` says
what exists today and what does not. what exists today and what does not.
## Where State Lives ## Where State Lives
@ -55,28 +56,20 @@ what exists today and what does not.
- Kernel: `crates/ghostlight/src/`. Its vocabulary and current mechanism: - Kernel: `crates/ghostlight/src/`. Its vocabulary and current mechanism:
`docs/architecture/ghostlight-world-ontology.md`. The consumer contract: `docs/architecture/ghostlight-world-ontology.md`. The consumer contract:
`docs/architecture/ghostlight-world-consumer-api.md`. `docs/architecture/ghostlight-world-consumer-api.md`.
- Dungeon daemon: `crates/ghostlight-dungeon/src/` (`runtime.rs` for routes and - Parked Dungeon (daemon, play table, Eve surface, browser host, Idunn recipe):
commands, `play.rs` for the play table, `eve.rs` for the surface). tag `parked/ghostlight-eve-surface`; not on main.
Interface authority: `docs/architecture/ghostlight-eve-native-interface.md`.
- Persona membrane: `crates/ghostlight-persona-projection/src/lib.rs`. - Persona membrane: `crates/ghostlight-persona-projection/src/lib.rs`.
- Browser host: `web/`. Claude SDK sidecar: `sidecar/claude-sdk/`. - Claude SDK sidecar: `sidecar/claude-sdk/`.
- Architecture rationale: `docs/architecture/ghostlight-dungeon-mvp.md`. - Architecture rationale (the parked Dungeon's): `docs/architecture/ghostlight-dungeon-mvp.md`.
`notes/ghostlight-implementation-plan.md` is the historical plan of the 2026-09 `notes/ghostlight-implementation-plan.md` is the historical plan of the 2026-09
rebuild, not the current plan. rebuild, not the current plan.
## Build, Verify, Deploy ## Build, Verify, Deploy
Ghostlight Dungeon ships to Linux on Yggdrasil. Idunn freezes an exact commit, Nothing deploys from this repo: the Idunn target `ghostlight` is retired and no
runs the locked native Linux tests, builds the daemon and web projection in recipe exists on main. Kernel and verse tests run on Linux on Yggdrasil (the
pinned containers, and seals the release. The steps are `ygg-verify` stopgap), not on the workstation; a Windows compile is not evidence
`deployment/idunn/recipe.toml`; the owning runbook is about Linux, so say which host you used. Do not run `idunn up ghostlight`.
`gamecult-ops/runbooks/ghostlight-dungeon-yggdrasil.md`.
You are probably reading this on a Windows workstation. That is where the shell
is, not where the artifact runs. A Windows compile is not evidence about the
Linux release; build for the target, or let the deploy path's builder do it, and
say which one you used. Heavy builds and test runs go to Yggdrasil, not the
workstation. Deploy only through Idunn (`idunn up ghostlight`).
For infrastructure, SSH, Idunn, Odin, or Heimdall work, consult For infrastructure, SSH, Idunn, Odin, or Heimdall work, consult
`F:\Projects\gamecult-ops` before acting. `F:\Projects\gamecult-ops` before acting.

View file

@ -2,7 +2,7 @@
**Ghostlight is a world kernel: typed world state that a language model can **Ghostlight is a world kernel: typed world state that a language model can
propose changes to and can never write.** The valuable part is propose changes to and can never write.** The valuable part is
`crates/ghostlight`. The dungeon game in this repo is one client of it. `crates/ghostlight`. The Dungeon game, one client of it, is parked (below).
**The thesis.** World state is typed documents. Every change to it, and every **The thesis.** World state is typed documents. Every change to it, and every
narrative dependency on it, is an operation in a closed, predefined algebra. narrative dependency on it, is an operation in a closed, predefined algebra.
@ -13,7 +13,7 @@ committed. A model-as-game-master holds the world in a context window and
drifts; here the world is a digest-chained journal that survives restarts and drifts; here the world is a digest-chained journal that survives restarts and
cannot be talked into contradicting itself. cannot be talked into contradicting itself.
**Use it as a structured state backend.** Do not judge it by the dungeon's **Use it as a structured state backend.** Do not judge it by the parked Dungeon's
prose. The kernel is a library; prose comes from whichever model you plug into prose. The kernel is a library; prose comes from whichever model you plug into
its ports. its ports.
@ -30,7 +30,8 @@ its ports.
algebra, and what the reducer checks. algebra, and what the reducer checks.
- `docs/architecture/ghostlight-world-consumer-api.md`: the contract for a - `docs/architecture/ghostlight-world-consumer-api.md`: the contract for a
program that reads a world and proposes changes to the characters it controls program that reads a world and proposes changes to the characters it controls
(`POST /cultnet/world-patch`, served by the Dungeon daemon). (`POST /cultnet/world-patch`; no process on main serves that door, a host serves
`ghostlight::admit_document`).
Start with those two documents, then `cargo doc -p ghostlight --open`. Start with those two documents, then `cargo doc -p ghostlight --open`.
@ -70,18 +71,12 @@ advances it a number of ticks under a token cap, reporting per tick what each
faction did and what it cost. Nothing loads AetheriaLore prose, models faction did and what it cost. Nothing loads AetheriaLore prose, models
storylets, or produces episodes yet. Targets: `notes/ghostlight-verse-target.md`. storylets, or produces episodes yet. Targets: `notes/ghostlight-verse-target.md`.
## The dungeon harness ## Ghostlight Dungeon (parked)
`crates/ghostlight-dungeon` is a single-player, DM-led game on one world: free The single-player, DM-led client and its daemon, Eve play surface and browser
text in, a Persona's prose out, an Interpreter lowering that prose to proposals host are parked at tag `parked/ghostlight-eve-surface`. Nothing is deployed and
the kernel decides. Status: it is deployed on Yggdrasil under Idunn, but it is a nothing on main serves HTTP. The Dungeon returns when Thing 2 gives it a UI
product under repair, not a demo to judge the kernel by. Its play-session (follow-up `dungeon-ui-on-thing2`); the rebuild starts from the tag.
defects are open (`notes/ghostlight-verse-map.md`, probed 2026-10-09), its
storyteller is a small local model by default, and a live run with a hosted model
waits on an operator key. An agent that runs it as a game master and finds the
narration incoherent has most likely measured an empty affordance catalog or the model,
not the kernel. Sign-in is
Heimdall's, so it does not serve an anonymous visitor.
## Repo map ## Repo map
@ -89,14 +84,10 @@ Heimdall's, so it does not serve an anonymous visitor.
|---|---| |---|---|
| `crates/ghostlight/` | The sealed kernel library. | | `crates/ghostlight/` | The sealed kernel library. |
| `crates/ghostlight-persona-projection/` | Membrane between structured state and a prose-only Persona. | | `crates/ghostlight-persona-projection/` | Membrane between structured state and a prose-only Persona. |
| `crates/ghostlight-dungeon/` | The `ghostlight-dungeon` daemon: HTTP and Eve routes, play table, CultMesh publication, Idunn health. |
| `crates/ghostlight-verse/` | The `ghostlight-verse` operator command line (`genesis`, `run`). | | `crates/ghostlight-verse/` | The `ghostlight-verse` operator command line (`genesis`, `run`). |
| `web/` | Thin Eve browser host and Heimdall access adapter; owns no product state. |
| `sidecar/claude-sdk/` | Node process serving `claude`-prefixed models to the kernel; a stopgap for a direct Messages API port. | | `sidecar/claude-sdk/` | Node process serving `claude`-prefixed models to the kernel; a stopgap for a direct Messages API port. |
| `deployment/idunn/recipe.toml` | The steps Idunn runs to test, build and seal a release. |
| `vendor/eve/` | Git submodule supplying the Eve browser lowering. |
| `AGENTS.md` | Invariants and where things are. | | `AGENTS.md` | Invariants and where things are. |
| `docs/architecture/ghostlight-dungeon-mvp.md` | The authority architecture. | | `docs/architecture/ghostlight-dungeon-mvp.md` | The parked Dungeon's authority architecture (design record). |
| `notes/` | The verse campaign's target and map, the handoff pointer, local smoke notes. | | `notes/` | The verse campaign's target and map, the handoff pointer, local smoke notes. |
`docs/public-architecture/`, `docs/articles/` and `docs/product/` are design `docs/public-architecture/`, `docs/articles/` and `docs/product/` are design
@ -106,32 +97,25 @@ running machine. Pages ending in `-cut.md` or `-postmortem.md` are dated history
## Build and test ## Build and test
The release target is Linux on Yggdrasil; a Windows build says nothing about it. Nothing deploys from this repo. Linux verification runs on Yggdrasil, not on a
The recipe's steps are the verification: workstation:
```sh ```sh
git submodule update --init vendor/eve cargo build --locked --workspace
cargo test --locked -p ghostlight-persona-projection cargo test --locked -p ghostlight-persona-projection
cargo test --locked -p ghostlight cargo test --locked -p ghostlight
cargo test --locked -p ghostlight-dungeon --bin ghostlight-dungeon cargo test --locked -p ghostlight-verse
cargo build --locked --release -p ghostlight-dungeon --bin ghostlight-dungeon
npm --prefix web ci && npm --prefix web test && npm --prefix web run build
``` ```
The kernel alone needs only `cargo test -p ghostlight`. The sidecar has The kernel alone needs only `cargo test -p ghostlight`. The sidecar has
`npm run sdk:build` and `npm run sdk:test`. Four Dungeon tests are `#[ignore]`d `npm run sdk:build` and `npm run sdk:test`. The acceptance test
because they drive the vendored browser lowering through `controllers::tests::real_local_model_cognition_modes_commit_speech` is ignored
`tools/eve_client_bridge.mjs` and need Node beside cargo; the release acceptance by default and needs a real model.
test `controllers::tests::real_local_model_cognition_modes_commit_speech` is
ignored by default and needs a real model.
Run the Dungeon locally with `npm run dungeon:run` or Inference is routed by model name: `local/` goes to an OpenAI-compatible
`cargo run -p ghostlight-dungeon -- --state-root PATH`; configuration is by loopback endpoint, `claude` to the SDK sidecar, and the verse runner's `hosted/`
`GHOSTLIGHT_*` environment variables (the recipe's `required_environment` lists to an https endpoint. Ghostlight never reads, stores or forwards a model
the deployment ones). Inference is routed by model name: `local/` goes to an credential beyond a key file named at run time.
OpenAI-compatible loopback endpoint, `claude` to the SDK sidecar, and the verse
runner's `hosted/` to an https endpoint. Ghostlight never reads, stores or
forwards a model credential beyond a key file named at run time.
Runtime documents are MessagePack-backed CultCache. JSON appears only at schema Runtime documents are MessagePack-backed CultCache. JSON appears only at schema
publication, browser, model-provider and diagnostic boundaries. publication, browser, model-provider and diagnostic boundaries.

View file

@ -80,7 +80,7 @@ const HANDLE_SEPARATOR: &str = "__";
const PERSONA_WORD_BUDGET: usize = 180; const PERSONA_WORD_BUDGET: usize = 180;
const CONTROLLER_WORK_ROW: &str = "controller_work.v18"; const CONTROLLER_WORK_ROW: &str = "controller_work.v18";
/// The `controller-work` state slot's schema. `pub` so a deploy recipe (or a /// The `controller-work` state slot's schema. `pub` so a deploy recipe (or a
/// test pinning one, e.g. `ghostlight-dungeon`'s recipe-drift test) can check /// test pinning one) can check
/// itself against this constant instead of hand-copying the version number. /// itself against this constant instead of hand-copying the version number.
pub const CONTROLLER_WORK_SCHEMA: &str = "ghostlight.controller_work.v18"; pub const CONTROLLER_WORK_SCHEMA: &str = "ghostlight.controller_work.v18";

View file

@ -7916,7 +7916,8 @@ mod tests {
}; };
/// Owner: `WorldPatch::sets_persona_of_existing_subject`. Consumer: /// Owner: `WorldPatch::sets_persona_of_existing_subject`. Consumer:
/// `ghostlight-dungeon`'s play agent (PA.f61), which refuses a /// `ghostlight-dungeon`'s play agent (PA.f61, parked at
/// `parked/ghostlight-eve-surface`), which refuses a
/// `set_persona_material` run whose patch answers true here, since /// `set_persona_material` run whose patch answers true here, since
/// `WorldPatch`'s own fields are `pub(crate)` and Dungeon may not parse /// `WorldPatch`'s own fields are `pub(crate)` and Dungeon may not parse
/// its JSON to decide the question itself. /// its JSON to decide the question itself.

View file

@ -1606,7 +1606,8 @@ mod tests {
// PA.f75: `communicate` was removed from `PLAY_TOOLS`; Dungeon drops it // PA.f75: `communicate` was removed from `PLAY_TOOLS`; Dungeon drops it
// from its own list too. This is now the complete 24-tool list. // from its own list too. This is now the complete 24-tool list.
// PA.f88: this is the library's own test fixture, kept in sync by hand. // PA.f88: this is the library's own test fixture, kept in sync by hand.
// Dungeon's `PLAY_TOOLS` in `ghostlight-dungeon/src/play.rs` is the // Dungeon's `PLAY_TOOLS` in `ghostlight-dungeon/src/play.rs` (parked at
// `parked/ghostlight-eve-surface`) is the
// single policy owner of what the play agent may actually call; this // single policy owner of what the play agent may actually call; this
// copy pins nothing there and is not read by production code. // copy pins nothing there and is not read by production code.
const PLAY_TOOLS: &[&str] = &[ const PLAY_TOOLS: &[&str] = &[

View file

@ -1,5 +1,7 @@
# Ghostlight authority architecture # Ghostlight authority architecture
> Status: the Dungeon daemon described here is parked at tag `parked/ghostlight-eve-surface` (2026-10-22); it is not on main.
## Status ## Status
This document is the adopted rebuild target for the Ghostlight runtime. It is This document is the adopted rebuild target for the Ghostlight runtime. It is

View file

@ -1,5 +1,7 @@
# Ghostlight Dungeon play agent (plan step 16) # Ghostlight Dungeon play agent (plan step 16)
> Status: the Dungeon daemon described here is parked at tag `parked/ghostlight-eve-surface` (2026-10-22); it is not on main.
## Status ## Status
Target, adopted 2026-09-22. Not implemented. The means will be in Target, adopted 2026-09-22. Not implemented. The means will be in

View file

@ -1,5 +1,7 @@
# Ghostlight Dungeon Session Zero # Ghostlight Dungeon Session Zero
> Status: the Dungeon daemon described here is parked at tag `parked/ghostlight-eve-surface` (2026-10-22); it is not on main.
Status: adopted direction, 2026-09-15. Not implemented. Its role as the Status: adopted direction, 2026-09-15. Not implemented. Its role as the
playtest gate is superseded (operator, 2026-09-22) by the play agent, playtest gate is superseded (operator, 2026-09-22) by the play agent,
`ghostlight-play-agent.md` (plan step 16). D1–D3 and the library passes `ghostlight-play-agent.md` (plan step 16). D1–D3 and the library passes

View file

@ -63,6 +63,11 @@ attributed proposal — is not part of this pass; see "Not in this pass" below.
## Transport ## Transport
Status: the HTTP door below lived in the Dungeon daemon's `api_router` and is
parked with it at tag `parked/ghostlight-eve-surface`; no process on main serves
it. `ghostlight::admit_document` and `encode_receipt` are the contract a host
serves.
`POST /cultnet/world-patch`, declared beside `/cultnet/snapshot` in `POST /cultnet/world-patch`, declared beside `/cultnet/snapshot` in
`api_router` (`runtime.rs`). The handler gates loopback and content type `api_router` (`runtime.rs`). The handler gates loopback and content type
(`application/msgpack`) exactly as the snapshot route does, then hands the (`application/msgpack`) exactly as the snapshot route does, then hands the

View file

@ -1,5 +1,7 @@
# Ghostlight Verse: Map # Ghostlight Verse: Map
> Status: Dungeon, eve.rs and the bridge-test references below are parked at tag `parked/ghostlight-eve-surface`; line refs are to that tag.
Campaign `ghostlight-verse`, target `ghostlight-verse:target:r3` Campaign `ghostlight-verse`, target `ghostlight-verse:target:r3`
(`notes/ghostlight-verse-target.md`). This page holds body facts, the model (`notes/ghostlight-verse-target.md`). This page holds body facts, the model
page and rationale only. Cut specs, questions, rulings and follow-ups live in page and rationale only. Cut specs, questions, rulings and follow-ups live in