Ghostlight/docs/architecture/ghostlight-session-zero.md

Ghostlight Session Zero

Status: adopted direction, 2026-09-15. Not implemented. Plan step 15 in notes/ghostlight-implementation-plan.md carries the pass order.

Objective

A player chooses a Vault, says what kind of experience they want, and gets a world seeded from that Vault. The world is dense where they stand and sketched where they don't, and it grows detail ahead of them as they travel. The flavor of the world comes from how often each of eight titled elaborators works on it.

Session Zero is the player-facing name for a world's Draft phase. It is not a separate owner: WorldKernel owns Draft and Active alike (ghostlight-dungeon-mvp.md), and every step below is an ordinary command or an elaborator patch through the one reducer.

The flow

1. Choose a Vault. The player picks from Vaults the operator has admitted. A Vault entry names its root and the scope a player may read, for example Kalsa's Public. The payload carries a Vault id, never a path.
2. Describe the experience. The player writes what they want. A model reads that description and proposes eight title weights. The proposal fills the sliders; the player adjusts them. The kernel receives only the numbers and the description, which becomes the world brief.
3. Create. world.create stores title, brief, Vault id, title weights, and the detail profile (below). The player's subject is not declared yet.
4. Sketch. The seed lane authors a coarse world from the Vault: regions, routes with travel costs, institutions, populations. It places no detail ring because no start exists yet.
5. Choose a start. The player picks a place from the sketch. The kernel declares the player's subject there, controlled by that player.
6. Elaborate. The swarm runs, pulled toward the start by distance.
7. Activate when the player chooses. Activation never waits on a count.
8. Play. The swarm keeps running in Active. As the player travels, the demand around them moves and detail follows.

Titles are lenses

The eight titles return under their original names and meanings:

Title	Reaches for
Patina	ordinary objects, customs, nicknames, local jokes
Charter	government, law, offices, selection, succession, redress
Ledger	resources, labor, trade, infrastructure, scarcity, class pressure
Hearth	kinship, daily life, care, obligation, belonging
Tangle	factions, alliances, rivalries, leverage
Veil	secrets, rumors, misinformation, taboos, unevenly held knowledge
Ember	disputes, hazards, instability, escalation, urgent pressure
Numen	religion, magic, ritual, awe, cosmology, the genuinely strange

A title is a lens: brief text plus an emphasis over the operation catalog (Ledger leads with custody and dependency operations, Veil with knowledge and channels, Charter with authority and selection). Every title receives the whole derived tool catalog. A title cannot refuse, verify, or rank another title's work, and no title has a quota.

The titles owned no depth before the ontology existed; the typed components give each a real target. Patina writes PersonaMaterial and ordinary affordances. Ledger writes custody, dependencies, and route costs. Hearth writes commitments and reads. Tangle writes relations, pressure, and authority. Veil writes knowledge scoping and channels. Ember writes pressure and commitments with near dues. Charter writes authority, selection, and redress. Numen writes facts, affordances, and material with the strange in it.

The swarm

Up to GHOSTLIGHT_CONTROLLER_MAX_CONCURRENT elaborator sessions run at once. Each session:

1. takes the head of the derived elaboration demand (below);
2. draws a title by the world's weights from a sampler seeded by world id and session ordinal, recorded on the session;
3. retrieves evidence from the world's Vault for the demand's referents;
4. builds one patch under that title's lens, confined to the demand's ground;
5. submits; a refusal continues the same conversation, as today.

Concurrency conflicts resolve as they do now: patches bind to scope digests, the mailbox serializes commits, and an overlapping patch repairs.

Distance-weighted demand

The detail target depends on travel distance from the player, not on a fixed share per region.

• Distance is the least route cost, in travel minutes, from any human-controlled subject's position to a place, over open routes that subject could traverse. It uses the same route walk as reachable in action.rs, factored to return a cost map. A place without routes takes the distance of its nearest routed container. Before a start exists, every place is far.

• Detail profile, stored at creation, is a small set of bands by distance:

  Band	Distance	Target
  Near	within near minutes	persons, institutions, populations
  Middle	within middle minutes	institutions and populations
  Far	beyond	institutions only

  Each band names a density per place. The profile replaces WorldScaleIntent jurisdiction permille; overall targets per kind remain.

• Demand is derived in snapshot, never stored: open causal boundaries and per-place deficits against the band target, ordered by distance and then by the kernel's existing boundary order. A place approaching the player raises its band, which raises its deficit, which puts it at the head.

• Lookahead: the near band is measured from where the player could be after lookahead minutes of travel, so detail arrives before the player.

• Individuation: when a population's place enters the near band, IndividuationRequired derives for it, and a session materializes named members from it. A city sketched as a handful of factions gets its people as the player approaches.

Authority map

• Owner: WorldKernel. It admits every patch, derives distance, demand, and deficits in snapshot, and declares the player's subject at the chosen start.
• Inputs: Vault id, brief, title weights, and detail profile from world.create; the start place from world.choose_start; canonical positions, routes, and costs; elaborator patches.
• Outputs: commits, receipts, and the derived demand and deficit rows on the snapshot.
• Derived state: distance maps, demand order, deficits, title draws, and the model's slider proposal. The title recorded on a session and receipt is evaluation evidence.
• Forbidden writers: a title as an authority, admission input, or quota; a per-title verifier; the slider-proposal model writing weights without the player's command; demand or distance stored as world state; an elaborator writing outside its demand's ground; a count gating activation; a Vault path in any payload.
• Shared paths: Draft and Active run the same swarm, the same demand derivation, and the same patch admission. The seed lane's sketch is one owner patch through the same reducer. Player travel, NPC travel, and time all move demand only through committed positions.
• Confinement ground: a session's ground is the place subtree of the demand it answers: the boundary's place, the deficit row's place, or the population's place. SystemCapability::Elaborator { jurisdiction } carries that ground. Authored jurisdiction roots are no longer the unit of confinement.

Cut line

Deleted or replaced before the new behavior is called complete:

• WorldScaleIntent jurisdiction permille and authored jurisdiction roots as confinement units; per-kind targets survive inside the detail profile;
• JurisdictionKey::Uncovered as a deficit row, since every place has a distance;
• the sequential one-session-per-jurisdiction sweep in elaboration.rs;
• NullEvidenceSource on the Active elaborator lane: Active elaboration reads the world's Vault;
• GHOSTLIGHT_SEED_VAULT_ROOT as the only Vault: an operator Vault registry replaces it;
• genesis declaration of the human subject in The Commons, and The Commons if nothing else needs it;
• "Draft answers nothing" for the elaborator lane: Draft sessions answer derived demand once a start exists.

Subtraction budget

Net additive by: the title enum and lens text, a weight vector and detail profile on world creation, a seeded sampler, a cost-map route walk shared with reachable, demand derivation, one start command, and a Vault registry. Cut against it: permille distribution, authored jurisdiction roots, the Uncovered row, the per-jurisdiction sweep, the single-root Vault variable, genesis human placement, and the null evidence source. No verifier, quota, scheduler service, or stored demand is added.

Build budget

Proving host: the Windows workstation, ghostlight-dungeon crate tests, plus sidecar schema fixtures if tool descriptions change. The Linux release is Idunn's build and is not touched by these passes. Road proof uses the local live smoke with the SDK sidecar.

Verification

1. The same patch submitted under two titles produces the same admission result; a title never appears in a mismatch.
2. The sampler, seeded identically, draws the same title sequence, and its frequencies follow the weights over a fixed draw count.
3. A zero weight never draws; all-zero weights are refused at creation.
4. Moving a human subject changes demand order without a commit; demand is absent from WorldState.
5. A place entering the near band moves to the head of demand; a place leaving it keeps its admitted structure.
6. An elaborator patch outside its demand's ground is refused.
7. An Active elaboration patch cites Vault receipts from the world's Vault scope and never from outside it.
8. Activation succeeds with nonzero deficits.
9. world.choose_start declares exactly one human-controlled subject at a sketch place, once, in Draft.
10. Road: a seeded world on the SDK route shows persons near the start, institutions far from it, and new persons at a place after the player's subject travels toward it.

Decisions the operator owns

• Weight changes after creation. Recommend: the owner may change weights in Draft and Active through one command; later sessions use the new weights and admitted structure stays.
• Title emphasis versus a title-restricted catalog. Recommend emphasis with the whole catalog, measured by per-title operation counts on the road. A restricted catalog would make the title decide what may be added.
• Band values. Recommend near 60 minutes, middle 1 day, lookahead 120 minutes, tuned on the road.
• Multiple players. Distance is already defined over every human subject; multi-player membership is a separate cut.

Pass order

1. Titles as lenses and the weighted swarm over today's demand.
2. Vault registry, world.create with Vault id, brief, and weights, and Vault evidence on the Active lane.
3. Detail profile, distance-weighted demand, world.choose_start, and the permille and root cuts.
4. Individuation in the near band.
5. The Session Zero Eve surface: Vault choice, description, slider proposal, sliders, sketch, start choice, activate; plus a travel affordance and per-affordance player controls. This pass closes the playtest gate.