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

# Ghostlight Dungeon Session Zero

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
L2–L4 they consume are deferred by ruling, not dropped. Plan step 15 in
`notes/ghostlight-implementation-plan.md` carries the deferred pass order.

## Ownership

Session Zero is Ghostlight Dungeon's concept and Dungeon's authority. Dungeon
is a consumer of the Ghostlight library. Session Zero consumes library
capabilities through their generic surfaces and adds nothing Dungeon-shaped
to the library: no Vault registry, player, slider, starting location, or
Session Zero phase exists in the library vocabulary.

The library capabilities it needs are specified, consumer-neutral, in
`ghostlight-world-ontology.md` under "Elaboration lenses and detail rules
(target)": the stock lens set and weights, detail rules, per-world evidence
binding, and elaborator sessions in Draft. Other consumers use the same
capabilities with their own policy; Delvehold, for one, starts from a
`Uniform` detail rule.

The world kernel lives in the `ghostlight` library crate
(`crates/ghostlight/`); `ghostlight-dungeon` consumes it across a public
boundary and cannot reach its internals.

## 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 the eight stock lenses works on it.

## The flow

1. **Choose a Vault.** The player picks from Vaults the Dungeon operator has
   admitted. A Dungeon 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. Dungeon binds the chosen Vault as the world's evidence source.
2. **Describe the experience.** The player writes what they want. A model
   reads that description and proposes weights for the eight stock lenses. The
   proposal fills the sliders; the player adjusts them. Dungeon submits only
   the numbers and the description, which becomes the world brief.
3. **Create.** Dungeon creates a library world with title, brief, the stock
   lens set and weights, and Dungeon's detail rule with no anchor yet. No
   player subject is declared yet, so every place sits at the rule's floor.
4. **Sketch.** Dungeon's seed session authors a coarse world from the Vault:
   regions, routes with travel costs, institutions, populations.
5. **Choose a start.** The player picks a sketch place. Dungeon submits one
   owner patch declaring the player's human-controlled subject there, and pins
   that subject as the first anchor of its detail rule.
6. **Elaborate.** The library's elaborator sessions run, pulled toward the
   anchors by distance.
7. **Activate** when the player chooses. Dungeon never makes activation wait
   on a count.
8. **Play.** As the player travels, the library's derived demand follows the
   anchor and detail follows the player.

## Dungeon policy

- **Lenses:** the library's stock set of eight, weighted by the player's
  sliders. The owner may change weights in Draft and Active; later sessions use
  the new weights.
- **Detail rule:** `ByDistance`, anchored on important subjects, the player
  first. Recommended levels: within 60 minutes, persons, institutions, and
  populations; within 1 day, institutions and populations; beyond, institutions
  only; lookahead 120 minutes. Tuned on the road. Which other subjects Dungeon
  pins, and when, is Dungeon policy not yet decided.
- **Travel:** Dungeon's seed authors a travel affordance for persons, and the
  Eve surface projects one control per affordance a player's subject holds.

## Authority map (Dungeon)

- **Owner:** Dungeon's runtime owns Session Zero's flow, the Vault registry,
  the weight proposal, the player principal, anchor pinning, and the Eve
  surface. Every world change it makes is an ordinary library command.
- **Inputs:** the authenticated player, the admitted Vault list, the player's
  description and slider values, the chosen start place.
- **Outputs:** library world creation, seed and owner patches, rule and
  weight changes, activation, and Eve projections.
- **Derived state:** the slider proposal, the Session Zero step a player is on
  (derived from the library snapshot's phase, rule anchors, and structure), and
  every projection.
- **Forbidden writers:** Dungeon writing world state other than through
  library commands; the proposal model submitting weights without the
  player's command; a Vault path in any payload; any Dungeon identifier,
  schema, or policy entering the library vocabulary.

## Cut line (Dungeon)

- `GHOSTLIGHT_SEED_VAULT_ROOT` as the only Vault: Dungeon's Vault registry
  replaces it.
- The `world.create` payload fields for jurisdiction roots and permille, when
  the library's detail rule replaces them.
- The genesis human subject: Dungeon declares its player at the chosen start.

## Verification (Dungeon)

1. A player-chosen Vault id resolves only to an admitted Vault and scope; an
   unknown id or a path is refused before anything is spent.
2. The slider proposal changes nothing until the player submits weights.
3. The start choice declares exactly one player subject, at a sketch place,
   once, in Draft, and pins it as the rule's first anchor.
4. Activation succeeds with nonzero deficits.
5. 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.

## Pass order

Library passes L0 through L4 are in plan step 15; L0 is the kernel
extraction. Dungeon passes follow them:

1. Vault registry, world creation with Vault id, brief, lens weights, and
   detail rule.
2. The Session Zero Eve surface: Vault choice, description, slider proposal,
   sliders, sketch, start choice, activation.
3. Travel affordance and per-affordance player controls. This pass closes the
   playtest gate.