Glossary

The project's terms of art, each with a stable anchor. Docstrings and guides link here; each entry links onward to the page that treats its subject in depth.

Workdir

The per-module working directory (<module>.forge/ by default) that convert creates and every stage reads and writes — source copy, page renders, stage caches, and the four consumer artifacts. The layout is a contract; see the workdir and artifacts.

Pipeline stage

One step of preprocess → survey → content → monsters → assemble, each tracked with its own status and token usage in the workdir's run.json. geometry is tracked as a stage but has no independent run — it is recomputed inside every assembly. See architecture.

Stage cache

An extraction stage's validated output, written under stages/ in the workdir (survey.json, areas.<dungeon>.<level>.json, monsters.json, statblocks.json). Caches are what make assembly pure: the model is consulted once per extraction stage, and everything downstream is a deterministic function of these files. Their models live in osrforge.contracts.stages.

Frozen stage-cache schema

The stage caches' wire formats are pinned (each cache carries a schema_version), and downstream code must tolerate everything a pinned schema does not forbid — an empty monster name or an empty treasure string is handled and flagged, never crashed on, because regenerating a cache costs model spend the consumer already paid.

Assembly purity

The core guarantee: adventure.json, report.json, and the previews are a deterministic function of the cached stage outputs plus overrides.yaml. Correcting a draft never re-rolls the model. Stated for consumers on the home page; its implementation consequences run through architecture.

The correction loop

The read-report → edit-overrides.yaml → re-assemble → check cycle that takes a draft to publishable, entirely model-free. See the correction loop.

Override

One entry in overrides.yaml, the human correction channel: monster remaps, stat-block patches, per-area field replacement, geometry, and town/module metadata, each carrying a reason. Every entry must take effect or assembly fails — no silent no-ops in a correction file. See the correction loop.

Flag

One entry in report.json's enumerated per-area vocabulary recording what extraction or assembly was unsure about (low_confidence, connection_ambiguous, monster_unresolved, …). Flags describe the built draft: an override that replaces an input suppresses the flags that input would have raised, while extraction facts persist. See badge vocabularies.

Finding

One entry in the playability lint's vocabulary, produced by check and merged into report.json — errors break the correction loop's exit code, warnings record accepted decisions. See badge vocabularies and the correction loop.

Tolerate-and-flag

The pipeline's posture toward imperfect input it cannot reject: accept it, build the best draft the input supports, and record the doubt as a flag a human can act on. Crashing is reserved for programmer misuse and corrupted workdirs; module weirdness is data, not an error.

Best-effort fallback

The unresolved_fallback: best-effort setting's behavior where extraction came up empty: flagged level-band monster stand-ins and unguarded-treasure rolls keep the draft playable, while omit leaves the gap. See settings and rerun.

Knob

One field of ConversionSettings — the deterministic pipeline configuration, echoed into run.json. See settings and rerun.

The settings echo

The copy of the run's settings stored in run.json. It is the single source of truth every stage reads, so a workdir always knows exactly how its artifacts were produced. See settings and rerun.

The drift guard

The rule that rerun --set rejects a settings update whose owning stage is upstream of the rerun stage — the settings echo is never allowed to lie about how upstream artifacts were produced. See settings and rerun.

Canonical slug

The id and key grammar shared by dungeon ids, area keys, and override addresses: lowercase [a-z0-9]+ groups joined by single hyphens. The alphabet is restrictive on purpose — no / (the address grammar uses it), no . (cache filenames and request tags parse unambiguously), no uppercase (a hand-edited override can't alias 4a against 4A). Enforced at the source by CANONICAL_SLUG_PATTERN.

Request fingerprint

A model request's identity hash: ModelRequest.fingerprint, the sha256 of the request's tag, system text, content parts (images as their own sha256 + size), and JSON Schema. Fixtures are stored and replayed by fingerprint, which is why a prompt, schema, or page-render change strands recorded fixtures. See testing.

Fixture

One recorded model exchange — request digest plus response — written by RecordingProvider and replayed by FixtureProvider at zero network and zero cost. Named <tag>.<fingerprint[:12]>.json. See testing.

Replay-grade vs evidence-grade

A replay-grade fixture set is closed over committed assets — every byte of its requests can be rebuilt from the repository, so tests replay it forever. An evidence-grade set embeds content the repository does not commit (page images of a licensed module); it documents that a run happened and what it answered, with no replay promise. See testing.

Goldens

Committed expected outputs (stage caches, adventure.json, report.json, previews) that pipeline tests compare byte-for-byte. Goldens are regenerated deliberately by re-running the documented fabrication commands — never hand-edited. See testing.

Byte-stability

The determinism discipline that makes goldens possible: sorted JSON keys, pinned iteration and placement orders, and version stamps kept out of the stage caches, so byte-identical inputs produce byte-identical artifacts on every platform.

Resolution tiers

The monsters stage's four-tier cascade over extracted encounter names, each tier consulted only when the previous one misses: normalized exact match, the curated alias table, stdlib fuzzy matching, and one LLM pass over the remainder. A fully deterministic resolution makes no model call. See osrforge.monsters.

The stat-block pass

The monsters-stage pass (under custom_monsters: emit) that transcribes the printed stat block for each name the tiers left unresolved, caching the raw block for assembly to map into a bundled custom MonsterTemplate. Transcription is the pass's whole job — every rules judgment lives in assembly, where it is deterministic and correctable.

Truth independence

The eval discipline that ground truth is authored from the printed module, never from pipeline output — the measuring instrument must be independent of the system under test. See evals.

Asserted-empty

The truth convention that distinguishes encounters: [] — an asserted, verified-empty area — from an omitted key, which asserts nothing. Only inside an asserted universe is an extracted name that matches nothing provably a hallucination, which is what the encounter-precision metric counts. See evals.

Map reading

The mapread stage's output for one level: the adjacency pairs, doors, and entrance the model proposed from the printed map pages alone — an independent second opinion on the prose, cached as answered in stages/mapread.json. A level whose map could not be read records itself unread with the reason, and an unread level asserts nothing downstream.

Reconciliation

The deterministic merge of a level's prose edge facts with its map reading, in osrforge.reconcile — shared by geometry synthesis and the eval scorer so the two can never merge or pick differently. The precedence rule: a stated prose fact survives any map conflict, flagged; a prose absence fills from the map, flagged as adopted; agreement is silent. Every adoption, disagreement, and dropped proposal is a map_disputed flag.

Edge-fact seam

The single scorer function through which every extracted edge fact — connection presence, door kind, locked state — flows from the level caches into the connection and door families. Phase 11 rerouted the seam through reconciliation, swapping the fact source without touching the metric semantics. See evals.

Dungeon-scoped matching

The transition and entrance families' matching scope: extracted claims resolve through the dungeon's level pairings to truth (level, key) addresses, because levels are peers — a printed inter-level stair survives an extraction that collapsed the printed levels into one. See evals.

Offline re-score

The rescore tooling: a scoreboard entry's metrics regenerated from its retained workdir against the current truth, with the run block carried verbatim — no live spend. The regression rule's counterpart for PRs that change the scorer's matching or metric semantics rather than extraction. See evals.

BYOM

Bring-your-own-module measurement: private eval corpora over locally owned, non-redistributable modules, with only aggregate numbers ever committed. See evals.