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
|
||||
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
|
||||
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.
|
||||
|
||||
## Where State Lives
|
||||
|
|
@ -55,28 +56,20 @@ what exists today and what does not.
|
|||
- Kernel: `crates/ghostlight/src/`. Its vocabulary and current mechanism:
|
||||
`docs/architecture/ghostlight-world-ontology.md`. The consumer contract:
|
||||
`docs/architecture/ghostlight-world-consumer-api.md`.
|
||||
- Dungeon daemon: `crates/ghostlight-dungeon/src/` (`runtime.rs` for routes and
|
||||
commands, `play.rs` for the play table, `eve.rs` for the surface).
|
||||
Interface authority: `docs/architecture/ghostlight-eve-native-interface.md`.
|
||||
- Parked Dungeon (daemon, play table, Eve surface, browser host, Idunn recipe):
|
||||
tag `parked/ghostlight-eve-surface`; not on main.
|
||||
- Persona membrane: `crates/ghostlight-persona-projection/src/lib.rs`.
|
||||
- Browser host: `web/`. Claude SDK sidecar: `sidecar/claude-sdk/`.
|
||||
- Architecture rationale: `docs/architecture/ghostlight-dungeon-mvp.md`.
|
||||
- Claude SDK sidecar: `sidecar/claude-sdk/`.
|
||||
- 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
|
||||
rebuild, not the current plan.
|
||||
|
||||
## Build, Verify, Deploy
|
||||
|
||||
Ghostlight Dungeon ships to Linux on Yggdrasil. Idunn freezes an exact commit,
|
||||
runs the locked native Linux tests, builds the daemon and web projection in
|
||||
pinned containers, and seals the release. The steps are
|
||||
`deployment/idunn/recipe.toml`; the owning runbook is
|
||||
`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`).
|
||||
Nothing deploys from this repo: the Idunn target `ghostlight` is retired and no
|
||||
recipe exists on main. Kernel and verse tests run on Linux on Yggdrasil (the
|
||||
`ygg-verify` stopgap), not on the workstation; a Windows compile is not evidence
|
||||
about Linux, so say which host you used. Do not run `idunn up ghostlight`.
|
||||
|
||||
For infrastructure, SSH, Idunn, Odin, or Heimdall work, consult
|
||||
`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
|
||||
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
|
||||
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
|
||||
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
|
||||
its ports.
|
||||
|
||||
|
|
@ -30,7 +30,8 @@ its ports.
|
|||
algebra, and what the reducer checks.
|
||||
- `docs/architecture/ghostlight-world-consumer-api.md`: the contract for a
|
||||
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`.
|
||||
|
||||
|
|
@ -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
|
||||
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
|
||||
text in, a Persona's prose out, an Interpreter lowering that prose to proposals
|
||||
the kernel decides. Status: it is deployed on Yggdrasil under Idunn, but it is a
|
||||
product under repair, not a demo to judge the kernel by. Its play-session
|
||||
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.
|
||||
The single-player, DM-led client and its daemon, Eve play surface and browser
|
||||
host are parked at tag `parked/ghostlight-eve-surface`. Nothing is deployed and
|
||||
nothing on main serves HTTP. The Dungeon returns when Thing 2 gives it a UI
|
||||
(follow-up `dungeon-ui-on-thing2`); the rebuild starts from the tag.
|
||||
|
||||
## Repo map
|
||||
|
||||
|
|
@ -89,14 +84,10 @@ Heimdall's, so it does not serve an anonymous visitor.
|
|||
|---|---|
|
||||
| `crates/ghostlight/` | The sealed kernel library. |
|
||||
| `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`). |
|
||||
| `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. |
|
||||
| `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. |
|
||||
| `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. |
|
||||
|
||||
`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
|
||||
|
||||
The release target is Linux on Yggdrasil; a Windows build says nothing about it.
|
||||
The recipe's steps are the verification:
|
||||
Nothing deploys from this repo. Linux verification runs on Yggdrasil, not on a
|
||||
workstation:
|
||||
|
||||
```sh
|
||||
git submodule update --init vendor/eve
|
||||
cargo build --locked --workspace
|
||||
cargo test --locked -p ghostlight-persona-projection
|
||||
cargo test --locked -p ghostlight
|
||||
cargo test --locked -p ghostlight-dungeon --bin ghostlight-dungeon
|
||||
cargo build --locked --release -p ghostlight-dungeon --bin ghostlight-dungeon
|
||||
npm --prefix web ci && npm --prefix web test && npm --prefix web run build
|
||||
cargo test --locked -p ghostlight-verse
|
||||
```
|
||||
|
||||
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
|
||||
because they drive the vendored browser lowering through
|
||||
`tools/eve_client_bridge.mjs` and need Node beside cargo; the release acceptance
|
||||
test `controllers::tests::real_local_model_cognition_modes_commit_speech` is
|
||||
ignored by default and needs a real model.
|
||||
`npm run sdk:build` and `npm run sdk:test`. The acceptance 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
|
||||
`cargo run -p ghostlight-dungeon -- --state-root PATH`; configuration is by
|
||||
`GHOSTLIGHT_*` environment variables (the recipe's `required_environment` lists
|
||||
the deployment ones). Inference is routed by model name: `local/` goes to an
|
||||
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.
|
||||
Inference is routed by model name: `local/` goes to an 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
|
||||
publication, browser, model-provider and diagnostic boundaries.
|
||||
|
|
|
|||
|
|
@ -80,7 +80,7 @@ const HANDLE_SEPARATOR: &str = "__";
|
|||
const PERSONA_WORD_BUDGET: usize = 180;
|
||||
const CONTROLLER_WORK_ROW: &str = "controller_work.v18";
|
||||
/// 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.
|
||||
pub const CONTROLLER_WORK_SCHEMA: &str = "ghostlight.controller_work.v18";
|
||||
|
||||
|
|
|
|||
|
|
@ -7916,7 +7916,8 @@ mod tests {
|
|||
};
|
||||
|
||||
/// 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
|
||||
/// `WorldPatch`'s own fields are `pub(crate)` and Dungeon may not parse
|
||||
/// its JSON to decide the question itself.
|
||||
|
|
|
|||
|
|
@ -1606,7 +1606,8 @@ mod tests {
|
|||
// PA.f75: `communicate` was removed from `PLAY_TOOLS`; Dungeon drops it
|
||||
// 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.
|
||||
// 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
|
||||
// copy pins nothing there and is not read by production code.
|
||||
const PLAY_TOOLS: &[&str] = &[
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# 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
|
||||
|
||||
This document is the adopted rebuild target for the Ghostlight runtime. It is
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# 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
|
||||
|
||||
Target, adopted 2026-09-22. Not implemented. The means will be in
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# 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
|
||||
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
|
||||
|
|
|
|||
|
|
@ -63,6 +63,11 @@ attributed proposal — is not part of this pass; see "Not in this pass" below.
|
|||
|
||||
## 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
|
||||
`api_router` (`runtime.rs`). The handler gates loopback and content type
|
||||
(`application/msgpack`) exactly as the snapshot route does, then hands the
|
||||
|
|
|
|||
|
|
@ -1,5 +1,7 @@
|
|||
# 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`
|
||||
(`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
|
||||
|
|
|
|||
Loading…
Reference in a new issue