diff --git a/README.md b/README.md index f967d61..88c7246 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ Notarius is a Go CLI for turning source material into structured artifacts with configured extraction pipelines. The implemented D&D workflow reads Seriatim -transcript JSON and can produce location registries and occurrences, scene -descriptions, item and currency events, NPC identities, combat turns, NPC -occurrences, enemy events, and spell casts. +transcript JSON and can produce NPC, location, and item registries; their +source-grounded occurrences; scene descriptions, combat turns, enemy events, +and spell casts. ## Quickstart diff --git a/docs/config.md b/docs/config.md index 03f4c68..fb2789c 100644 --- a/docs/config.md +++ b/docs/config.md @@ -298,7 +298,7 @@ output: enabled: true window_units: 3 lanes: - - npc_registry + - npc-registry - spells ~~~ @@ -332,7 +332,7 @@ step: steps: - id: describe-session artifacts: - npc_registry: + npc-registry: extract: dnd/npc-registry normalize: dnd/npc-registry - id: extract-events @@ -340,7 +340,7 @@ steps: npc_registry: artifact: step: describe-session - lane: npc_registry + lane: npc-registry artifacts: spells: extract: dnd/spells @@ -371,14 +371,17 @@ selected target declares them: | **glossary** | Optional text campaign glossary. | | **spell_catalog** | Optional JSON spell-catalog overlay for spell extraction and normalization. See [spell-catalog overlays](integrations/dnd-spell-catalog-overlays.md). | | **location_registry** | Required normalized location registry for location-occurrence extraction and normalization. | +| **item_registry** | Required normalized item registry for item-occurrence extraction and normalization. | | **npc_registry** | Normalized NPC registry. Optional for spells and combat turns; required for NPC occurrences and enemy-event extraction and normalization. | | **scene_descriptions** | Required normalized scene-description artifact for combat-turn and enemy-event extraction. | | **combat_turns** | Required normalized combat-turn artifact for enemy-event extraction. | | **npc_occurrences** | Required normalized NPC-occurrence artifact for enemy-event extraction. | -Location-occurrence and enemy-event artifact slots have the following exact -binding contracts. Durable semantics and wire shapes remain in their -[location-occurrence](integrations/dnd-location-occurrence-artifacts.md) and +Registry-backed occurrence and enemy-event artifact slots have the following +exact binding contracts. Durable semantics and wire shapes remain in their +[NPC occurrence](integrations/dnd-npc-occurrence-artifacts.md), +[location occurrence](integrations/dnd-location-occurrence-artifacts.md), +[item occurrence](integrations/dnd-item-occurrence-artifacts.md), and [enemy-event](integrations/dnd-enemy-event-artifacts.md) contracts. | Slot | Accepted artifact kind | Media type | Maximum size | Required stage | @@ -388,13 +391,15 @@ binding contracts. Durable semantics and wire shapes remain in their | `combat_turns` | `dnd/combat-turn-list` | `application/json` | 1,048,576 bytes | extract only | | `npc_occurrences` | `dnd/npc-occurrence-list` | `application/json` | 1,048,576 bytes | extract only | | `location_registry` | `dnd/location-registry` | `application/json` | 1,048,576 bytes | location-occurrence extract and normalize | +| `item_registry` | `dnd/item-registry` | `application/json` | 1,048,576 bytes | item-occurrence extract and normalize | Scene descriptions accept **party**, **players**, and **glossary**, but not **roster**. NPC occurrences require **npc_registry** for both extraction and normalization. Combat turns require **scene_descriptions** for extraction; the normalized combat-turn module may use optional **npc_registry**. Location occurrences -require **location_registry** for extraction and normalization. Enemy-event extraction -requires all four of its JSON artifact slots; its normalizer requires **npc_registry**. +require **location_registry** for extraction and normalization. Item occurrences require +**item_registry** for extraction and normalization. Enemy-event extraction requires all +four of its JSON artifact slots; its normalizer requires **npc_registry**. The [complete example](../examples/dnd-complete.config.yml) shows the ordered generated bindings. @@ -409,21 +414,21 @@ generated bindings. | Normalize | **noop**, **dnd/spells**, **dnd/npc-registry**, **dnd/combat-turns**, **dnd/item-occurrences**, **dnd/item-registry**, **dnd/npc-occurrences**, **dnd/scene-descriptions**, **dnd/enemy-events**, **dnd/location-registry**, **dnd/location-occurrences** | | Output | **json** | -`dnd/location-registry` and `dnd/item-registry` extraction and normalization -are `llm_backed`; their normalizers may use the pipeline's selected LLM profile -for bounded duplicate proposals. `dnd/location-occurrences` and -`dnd/item-occurrences` extraction are `llm_backed`, while their normalizers are -`deterministic`. The complete example binds each registry in an earlier step -before its occurrence consumer. +`dnd/scenes` and every D&D extractor are `llm_backed`. The +`dnd/npc-registry`, `dnd/location-registry`, and `dnd/item-registry` +normalizers are also `llm_backed` for bounded duplicate proposals; every other +D&D normalizer is `deterministic`. LLM-backed bindings use the effective +[PromptKit profile](#promptkit-profiles). The complete example binds each +registry in an earlier step before its occurrence consumer. The D&D artifact contracts define each emitted schema: [spells](integrations/dnd-spell-artifacts.md), [NPC registry](integrations/dnd-npc-registry-artifacts.md), [NPC occurrences](integrations/dnd-npc-occurrence-artifacts.md), [combat turns](integrations/dnd-combat-turn-artifacts.md), -[item occurrences](integrations/dnd-item-occurrence-artifacts.md), [item registry](integrations/dnd-item-registry-artifacts.md), -[scene descriptions](integrations/dnd-scene-description-artifacts.md), and +[item occurrences](integrations/dnd-item-occurrence-artifacts.md), +[scene descriptions](integrations/dnd-scene-description-artifacts.md), [enemy events](integrations/dnd-enemy-event-artifacts.md), [location registry](integrations/dnd-location-registry-artifacts.md), and [location occurrences](integrations/dnd-location-occurrence-artifacts.md). diff --git a/docs/integrations/dnd-item-occurrence-artifacts.md b/docs/integrations/dnd-item-occurrence-artifacts.md index d538a15..b7325c1 100644 --- a/docs/integrations/dnd-item-occurrence-artifacts.md +++ b/docs/integrations/dnd-item-occurrence-artifacts.md @@ -14,9 +14,11 @@ inventory, balance, or ledger. | Schema version | `v1` | | Media type | `application/json` | -The strict root has required `occurrences`. Records require `item_id`, `name`, -`kind`, and `source_refs`; unknown fields are rejected. `quantity`, `from`, and -`to` appear only when their kind permits them. +`v1` accepts one strict JSON object with required `occurrences`; the array may +be empty. Each occurrence has required `item_id`, `name`, `kind`, and +`source_refs`, and occurrence and source-reference objects reject unknown +fields. `quantity`, `from`, and `to` appear only when their kind permits them. +An incompatible shape change requires a new schema version. ## Registry grounding @@ -33,6 +35,10 @@ pairs. ## Wire shape +Each source reference has exactly `source_id`, `start_unit_id`, and +`end_unit_id`. It identifies an inclusive range in the current transcript; +unit IDs are positive and the start may not follow the end. + ```json { "occurrences": [ @@ -54,7 +60,10 @@ The five kinds remain `discovered`, `acquired`, `lost`, `consumed`, and `transferred`. Holder, quantity, currency, ordering, and exact-duplicate rules are unchanged: discovered has no holder; acquired requires `to`; lost and consumed require `from`; transferred requires distinct non-`party` holders. -Each source reference is an inclusive current-transcript range. +The only current downstream compatibility requirement is its registry handoff; +the normalized occurrence list is otherwise published for callers. See +[Configuration](../config.md#d-d-reference-slots) for the binding and +[JSON output](json-output.md) for publication. See [item registry](dnd-item-registry-artifacts.md) for the grounding artifact and [D&D module internals](../internal/dnd.md) for implementation details. diff --git a/docs/integrations/dnd-item-registry-artifacts.md b/docs/integrations/dnd-item-registry-artifacts.md index 46bf641..6420117 100644 --- a/docs/integrations/dnd-item-registry-artifacts.md +++ b/docs/integrations/dnd-item-registry-artifacts.md @@ -78,9 +78,14 @@ result with retry or fallback diagnostics. Currency denominations, materially different item types, and merely nearby objects remain distinct. Source references establish registry provenance, not evidence for later artifacts. -## Publication +## Consumers and publication -The registry is a selectable D&D artifact. See -[Configuration](../config.md#production-module-keys) for module keys and -validator chains, and the [JSON output contract](json-output.md) for -publication. It does not yet define a consumer handoff contract. +`dnd/item-occurrences` requires one approved item registry through its +`item_registry` reference slot for both extraction and normalization. Its +consumer receives only an ordered, source-free `{id,name}` projection; the +registry’s source references are never occurrence evidence. Unknown IDs and +mismatched pairs are rejected by the occurrence contract. See the +[item-occurrence artifact](dnd-item-occurrence-artifacts.md) for that strict +wire contract, [Configuration](../config.md#d-d-reference-slots) for binding +rules and validator selection, and the [JSON output contract](json-output.md) +for publication. diff --git a/docs/integrations/dnd-npc-registry-artifacts.md b/docs/integrations/dnd-npc-registry-artifacts.md index a923707..b3c585e 100644 --- a/docs/integrations/dnd-npc-registry-artifacts.md +++ b/docs/integrations/dnd-npc-registry-artifacts.md @@ -76,7 +76,10 @@ occurrence. This registry can ground actor or caster names in the [spell](dnd-spell-artifacts.md) and [combat-turn](dnd-combat-turn-artifacts.md) artifacts. It is required to resolve the canonical `name` in an [NPC occurrence](dnd-npc-occurrence-artifacts.md). -The [enemy-event artifact](dnd-enemy-event-artifacts.md) also uses it only for -subject grounding and canonical display names. +Occurrence consumers receive an ordered source-free `{id,name}` projection; +spells, combat turns, and the [enemy-event artifact](dnd-enemy-event-artifacts.md) +receive names-only grounding for actor or subject display. None of these +projections supply later-artifact evidence. [Configuration](../config.md#d-d-reference-slots) +owns the `npc_registry` binding rules. The [JSON output contract](json-output.md) defines publication, and [D&D module internals](../internal/dnd.md) owns pipeline mechanics. diff --git a/docs/integrations/json-output.md b/docs/integrations/json-output.md index 899dfa9..7c31931 100644 --- a/docs/integrations/json-output.md +++ b/docs/integrations/json-output.md @@ -74,8 +74,9 @@ than infer a lane schema from its name. The current D&D payload contracts are [spells](dnd-spell-artifacts.md), [NPC registry](dnd-npc-registry-artifacts.md), [NPC occurrences](dnd-npc-occurrence-artifacts.md), [combat turns](dnd-combat-turn-artifacts.md), +[item registry](dnd-item-registry-artifacts.md), [item occurrences](dnd-item-occurrence-artifacts.md), -[scene descriptions](dnd-scene-description-artifacts.md), and +[scene descriptions](dnd-scene-description-artifacts.md), [enemy events](dnd-enemy-event-artifacts.md), [location registry](dnd-location-registry-artifacts.md), and [location occurrences](dnd-location-occurrence-artifacts.md). diff --git a/docs/internal/dnd.md b/docs/internal/dnd.md index 62f8f99..796f0f5 100644 --- a/docs/internal/dnd.md +++ b/docs/internal/dnd.md @@ -50,7 +50,10 @@ such as a catalog, registry, grounding projection, or candidate collection are local only when that module needs them. New extractor content uses its feature subtree, while families with both extraction and normalization content use their `extract` and `normalize` subtrees. Shared visual-provenance fragments use -the `common-dnd-` prefix. +the `common-dnd-` prefix. Production lane code belongs with its D&D codec, +extractor, normalizer, and validator packages; registry projections and +identity helpers remain in their owning entity packages rather than in a +consumer lane. The owning module’s manifest is the source of truth for which local and shared assets are selected, their mount paths, their message order, cache controls, @@ -83,7 +86,7 @@ source. Deployment profile selection is documented in The transcript assets have distinct consumers. Scene chunking consumes the complete-session `common-dnd-transcript-full.md`; extraction prompts consume -the current-chunk `common-dnd-transcript-chunk.md`; and NPC and location +the current-chunk `common-dnd-transcript-chunk.md`; and NPC, location, and item normalization consume `common-dnd-transcript-windows.md` alongside their candidate collections. Player, party, glossary, and compatible campaign references provide disambiguating context, not evidence. Reference material is @@ -141,17 +144,16 @@ producer provenance; consumers resolve the handed-off artifact into an immutable, validated projection for each operation. External files are checked during preparation, while generated artifacts are resolved at the handoff. -NPC registries are names-only grounding projections: they may canonicalize -actors for spells and combat turns and are required for NPC occurrences, but -they do not supply evidence. Scene-description registries are eligibility-only -projections: they retain the current chunk’s classification data, not scene -prose or evidence, and exist to route combat extraction. Enemy-event extraction -also projects combat turns to `actor` and `turn_kind` and filters NPC -occurrences to `combat_opponent` names and kinds. Location registries project -ordered `{id, name}` pairs to location-occurrence extraction and normalization; -exact ID/name matching keeps same-name locations distinguishable. These compact -projections, like NPC grounding, are source-free guidance and never event -evidence. +NPC, location, and item registries project ordered, source-free `{id, name}` +pairs to their respective occurrence extractors and normalizers. Exact ID/name +matching preserves every identity the registry recognizes, including same-name +locations with distinct source anchors. The NPC registry additionally supplies +names-only actor grounding to spells, combat turns, and enemy events. +Scene descriptions are eligibility-only projections: they retain current-chunk +classification data, not scene prose or evidence, and exist to route combat +extraction. Enemy-event extraction also projects combat turns to `actor` and +`turn_kind` and filters NPC occurrences to `combat_opponent` names and kinds. +These projections are guidance only and never event evidence. ## Lane-Specific Rules @@ -161,9 +163,9 @@ shared helper changes. | Lane | Intentional behavior | | --- | --- | | Spells | May use a spell-catalog overlay and optional NPC grounding; the catalog validator supplies domain-specific semantic checks. | -| NPCs | Does not consume an NPC registry. Its normalizer is the LLM-assisted reconciliation exception described above. | +| NPC registry | Does not consume an NPC registry. Its normalizer is the LLM-assisted reconciliation exception described above. | | Combat turns | Requires a scene-description artifact. It calls the LLM only for an exact `combat` classification; exact non-combat classifications return an accepted empty result, while missing or mismatched classifications return an empty result with a bounded warning. Optional NPC grounding never becomes evidence. | -| Item occurrences | Uses campaign context for disambiguation but has no NPC-registry or scene-description dependency. | +| Item occurrences | Requires the normalized item registry for exact ID/name grounding at extraction and normalization. Campaign context may disambiguate, but the registry never becomes occurrence evidence. | | Item registry | Produces source-grounded item types and unique designations. Its LLM-assisted reconciliation is proposal-only, preserves distinct currency denominations and item types, and does not create per-instance identities. | | NPC occurrences | Requires the normalized NPC registry at extraction and normalization, using it for canonical actor grounding only. | | Scene descriptions | Produces the classifications consumed by combat routing; it does not consume an NPC registry or provide evidence for combat artifacts. |