Ghostlight/README.md

Ghostlight

Ghostlight builds persistent generative people and worlds. Its active product is Ghostlight Dungeon: a Vault-grounded narrative simulation in which places, knowledge, relationships, institutions, clocks, and consequences survive beyond the model's current context.

The project began as a research and fixture pipeline for socially persistent Aetheria agents. That material remains useful regression evidence. The live machine is now a Rust runtime with typed campaign state, one canonical world authority, bounded Persona projection, fiction-first action resolution, and a multiresolution agency graph for keeping large settings active at finite cost.

What Ghostlight Owns

• WorldKernel is the sole owner of committed campaign state and revisions.
• Every player command, NPC action, strategic tick, wait, import, and reload enters the same validated campaign mailbox and atomic CultCache commit path.
• Vault evidence grounds world compilation; branch-local invention remains distinct from canon.
• Projector → Persona → Interpreter turns produce proposals. Models never commit world state.
• Knowledge, perception, capability, location, custody, and authority are validated against the exact actor proposing an action.
• Fiction-first d20 resolution treats player text as an attempt rather than an accomplished fact.
• Multiresolution Gestalts keep people, institutions, and factions active under a bounded Persona-cell budget without merging rivals into one mind or erasing named individuals.
• Away-time simulation advances clocks and remote agency without puppeting or directly harming an absent player character.
• CultMesh publishes typed service and Eve/CultUI state; the browser lowers that surface and does not become a second state authority.

Current Status

Ghostlight Dungeon is implemented and deployed as a private Starfire-hosted playtest harness. The current acceptance surface covers:

• source-grounded world compilation with approval previews;
• persistent campaigns, forks, resets, exports, and isolated invite sessions;
• parallel affected-character Projector/Persona/Interpreter waves;
• impossible-action refusal, assessed stakes, server-side rolls, and receipted commits;
• strategic clocks, away-time catch-up, institution activity, migration, and information-channel-aware news;
• connected cohesive and arena simulation covers at budgets from 1 to 32;
• Gestalt materialisation, folding, member deltas, migration, and later rematerialisation of the same person;
• atomic rejection of malformed, stale, or semantically invalid model waves;
• provider, token, cache, latency, validation, state-version, and build receipts;
• exact-build deployment and restart verification on Starfire.

The immediate forge work is pressure-testing whether multiresolution Gestalts produce satisfying setting-wide activity, callbacks, and surprises per token, then running the two-tester paid-alpha path. The public site is provisional; checkout is not live.

Multiplayer Intention

The first paid alpha remains single-player. Multiplayer is an intended extension of the existing authority model, not a separate chat mode.

A campaign will continue to have one WorldKernel. Authenticated human sessions will control distinct canonical actors, and every human or Persona proposal will enter the same campaign mailbox. Each player receives a perception-specific narrative projection; private knowledge is never unioned into a party prompt. Splitting the party therefore changes occupancy and perception without creating contradictory copies of the world.

The durable intention and unresolved social-policy questions are recorded in docs/architecture/ghostlight-dungeon-multiplayer-intention.md. It does not expand the current MVP acceptance promise.

Architecture

The shortest reliable re-entry path is:

• docs/architecture/ghostlight-dungeon-mvp.md: runtime authority, compiler, action loop, persistence, hosting, and security;
• docs/architecture/ghostlight-multiresolution-agency.md: dynamic Gestalt partitioning, cohesive and arena cells, fairness, and atomic strategic waves;
• notes/ghostlight-current-system-map.md: current implemented pipeline;
• notes/ghostlight-implementation-plan.md: live sequence and next pressure tests;
• state/map.yaml: canonical human-readable project state.

Repository Shape

• crates/ghostlight-dungeon/: Rust daemon, kernel, compiler, persistence, provider stages, web lowerer, and acceptance harnesses;
• crates/ghostlight-persona-projection/: generalized projection membrane owned by Ghostlight and consumed by Epiphany;
• docs/architecture/: durable contracts and authority maps;
• docs/articles/: accessible public explanations;
• notes/: implementation planning, handoff, and current-system maps;
• schemas/: published JSON Schemas for typed boundary documents;
• examples/: earlier fixtures and regression material;
• state/: human-readable project memory plus older research-pipeline state;
• tools/: state, validation, and fixture helpers.

Runtime documents and campaign exports use MessagePack-backed CultCache .cc. JSON exists at schema publication, browser, MCP, model-provider, and diagnostic boundaries; it is not the canonical hosted state store.

Useful Commands

cargo test --workspace
npm run state:status
npm run state:prepare-compaction
npm run schema:validate

For Codex-driven work, read AGENTS.md before changing the repository. It owns the persistence, grounding, verification, and handoff discipline.