# Living Dungeon metadata contract

`cinder-vault.json` is the renderer-independent source for the first-playtest
cards and trackers. It describes game objects and complete rules text; it does
not prescribe card dimensions, bleed, fonts, artwork, or printer settings.

## Design goals

- Every object has a stable lowercase kebab-case `id`.
- Printed names and labels may change without breaking references.
- Every Encounter card has complete Magic characteristics and a deterministic
  automa fallback.
- Rooms and trackers are visibly scenario objects rather than Magic
  permanents.
- Simulation values are explicitly labeled approximations and never replace
  card rules text.
- No field asserts ownership, proxy production, purchase, or physical assembly.

## Top-level shape

The schema-1 document contains:

- `identity`: scenario id, title, revision, status, pod compatibility, and
  design language.
- `mode`: player count, life and vitality values, gate floors, shared rules,
  and win/loss limits.
- `zones`: Dungeon library, Reserve, battlefield, graveyard, exile, Room, and
  tracker definitions.
- `keywords`: exact reminder text for custom terms such as Heartbound,
  roombound, Focus, and Sealed.
- `turn_structure`: ordered round and Dungeon-turn steps.
- `automa_protocol`: exhaustive Focus bands, target-protocol ids, tie breaks,
  and blocker ordering consumed by Encounter and token metadata.
- `rooms`: fixed scenario order, vitality range, setup, static rules, four
  exhaustive d20 bands, completion, and automa notes.
- `boss`: boss identity and complete phase objects.
- `encounter_cards`: every Monster, Hazard, and Tactic with `quantity`; the
  quantities must sum to 30.
- `trackers`: every noncard state component with range, initial value, and
  reminder text.
- `references`: player and operator aid cards.
- `simulation`: transparent abstractions used by the local scenario and pacing
  model.

## Encounter cards

All Encounter cards require:

- `id`, `name`, `quantity`, `minimum_stage`, `kind`, `mana_cost`, `mana_value`,
  `colors`, `type_line`, `rules_text`, `flavor_text`, and `automa`.
- Monsters additionally require string `power` and `toughness`.
- `kind` is one of `monster`, `hazard`, or `tactic`.
- `minimum_stage` is 1–4 and assigns the card to a chapter. At setup, stage 1
  becomes the Encounter library and unopened chapters remain scenario objects.
  When a later stage opens, shuffle its chapter and put it on top of the
  existing Encounter library.
- Optional `casting_window = "second-dungeon-turn"` makes a combat Tactic
  uncastable during the first Dungeon turn; automa skips it in Reserve.
- `mana_value` must match the declared generic `mana_cost`. `colors` records
  the card's actual color characteristic for protection and color-sensitive
  effects.
- `automa` declares a target protocol, legal fallback, casting notes, and any
  fixed X or mode selection.
- `simulation` records coarse pressure values. These are for comparative
  pacing only and have no rules authority.

Rules text uses controller-neutral Magic wording whenever practical. A card
stolen or cast by an adventurer should produce a coherent reversed effect.
Room-specific narration belongs in flavor text or automa notes, not hidden
rules.

## Rooms

Rooms are not permanents. Each Room requires:

- `id`, `name`, `sequence`, `vitality_ceiling`, `vitality_floor`, `setup`,
  `static_rules`, `lair_roll`, `completion`, and `flavor_text`.
- `lair_roll` has exactly four contiguous bands covering 1 through 20 once:
  1, 2–9, 10–19, and 20.
- Every spawned object references an Encounter id or an explicitly declared
  token dummy.
- Setup cannot deal immediate Party damage.

Boss phase objects follow the same vitality-boundary model but reference the
boss rather than appearing in the Room array.

## Trackers and dummies

A tracker specifies `id`, `name`, `minimum`, `maximum`, `initial`, `step`, and
`reminder`. A binary marker uses 0–1. A positional marker such as Focus uses a
string `values` list instead of a numeric range.

Token dummies live in `tokens`. A dummy includes the copiable characteristics
needed for play—name, colors, card types, subtypes, power/toughness when it is a
creature, rules text, and whether it is roombound. This includes the ordinary
Depth land tokens used to make land-count and land-entry text function. Art
direction is optional descriptive metadata only.

## Validation boundary

`scripts/validate-dungeon.mjs` validates schema, identities, counts, contiguous
roll bands, vitality gates, references, automa fallbacks, trackers, and source
privacy. `scripts/simulate-dungeon.py` consumes only the validated public
metadata and its disclosed abstraction profile. It executes scenario zones,
chapters, Reserve cadence, gates, timing, and high-level Encounter state while
leaving hands, mana, priority, target legality, and exact combat to paper play.
`simulation-guide.md` documents its reproducible CLI, confidence intervals,
structured traces, paired-seed sweeps, and export formats. Neither script reads
collection, proxy, purchase, price, location, or private-note data.