Ghostlight/docs/architecture/corpus-coverage-ledger.md

# Corpus Coverage Ledger

The corpus coverage ledger is the project-level index for accepted and planned
Aetheria training fixtures.

Its job is not to store story content. Its job is to keep the corpus honest:
which factions, movements, flashpoints, timeline lanes, tonal modes, collision
axes, review states, and item/economy hooks are represented, and which are still
missing.

## Live Files

- Ledger: `state/corpus-coverage.json`
- Schema reference: `schemas/corpus-coverage.schema.json`
- Validator/status tool: `tools/validate_corpus_coverage.py`
- Command: `npm run coverage:status`

## Entry Contract

Each fixture entry records:

- `fixture_id`: stable fixture handle.
- `status`: `planned`, `draft`, `accepted_as_draft`, `accepted`,
  `needs_revision`, `rejected`, or `superseded`.
- `timeline_lane`: `historical_grounded`, `transition_grounded`, or
  `future_branch`.
- `canon_status`: single-history, branch-local, promoted branch, template, or
  draft status.
- `story_type`: founding-era, day-in-the-life, flashpoint, movement,
  future-branch, or trade-life story.
- `primary_subjects` and `secondary_subjects`: factions, movements,
  institutions, species/body groups, or other represented subjects.
- `collision_axes`: the pressures the fixture exercises, such as law, labor,
  care, class, logistics, species/body affordance, trade, memory, personhood,
  technology, legitimacy, or infrastructure.
- `tonal_modes`: prose modes the fixture contributes to the corpus.
- `training_targets`: organs or reference surfaces this fixture is relevant to.
- `training_usability`: explicit per-stage declaration of whether the fixture
  is `training_ready`, `reference_only`, or `not_training_data`.
- `artifacts`: paths to fixture files.
- `review`: status of schema, narrative, lore, spatial, visual, and IF review.
- `economy_hooks`: item, assembly, trade-good, supply-chain, or tech hooks.
- `open_lore_gaps`: blocking or useful gaps discovered during generation.

## Acceptance Rule

An accepted or accepted-as-draft fixture must have the core artifact refs:

- lore digest
- agent state
- coordinator artifact
- Ink file
- training sidecar

It must also carry review fields for schema, narrative, lore, spatial, visual,
and IF artifact review. A fixture may still be accepted-as-draft with review
caveats, but the caveats should be visible instead of hidden under the nice rug.

Coverage status is not training readiness. A fixture that looks good as a story
can still be unusable for a model stage if it lacks exact input/output receipts,
raw outputs, reviewer decisions, hidden-context audits, or mutation records in
the shape that stage requires. The ledger should be rude about this. If a
fixture is only a reference for story shape or grounding, mark it
`reference_only`; do not promote it by implication.

## Report Shape

`npm run coverage:status` validates the ledger and prints:

- total entries and accepted count
- progress toward the 100-150 broad target
- status, timeline lane, story type, collision-axis, tonal-mode, and subject
  counts
- training-usability counts
- major-power founding/day-in-life candidates when present
- basic gap signals, such as missing future-branch coverage or no day-in-life
  stories yet

This is deliberately a coarse instrument. It should tell us where to point the
next fixture without pretending to be a corpus scientist in a lab coat made of
spreadsheet tabs.