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:
parent
f40bbaac13
commit
ef11427e24
10 changed files with 50 additions and 58 deletions
27
AGENTS.md
27
AGENTS.md
|
|
@ -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.
|
||||||
|
|
|
||||||
58
README.md
58
README.md
|
|
@ -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.
|
||||||
|
|
|
||||||
|
|
@ -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";
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -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.
|
||||||
|
|
|
||||||
|
|
@ -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] = &[
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue