From 87c57681f6600389dde8589e935241306c7e11c5 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 20 Jul 2026 19:44:31 +0000 Subject: [PATCH] Document completed spell catalog baseline --- docs/integrations/dnd-spell-artifacts.md | 17 +++++++++++--- docs/internal/modules.md | 18 +++++++-------- docs/internal/overview.md | 4 ++-- docs/roadmap/dnd-spell-extraction.md | 28 +++++++++++++++++++++--- docs/roadmap/future.md | 11 +++------- docs/roadmap/implementation.md | 7 +++--- 6 files changed, 57 insertions(+), 28 deletions(-) diff --git a/docs/integrations/dnd-spell-artifacts.md b/docs/integrations/dnd-spell-artifacts.md index 775d14e..adece4b 100644 --- a/docs/integrations/dnd-spell-artifacts.md +++ b/docs/integrations/dnd-spell-artifacts.md @@ -51,7 +51,10 @@ Each spell cast contains exactly these required fields: IDs and evidence unit ranges. It must contain at least one entry. All four string fields must be non-empty. `caster` is the in-world caster, not -the transcript speaker. Unknown fields are rejected. +the transcript speaker. The `spell` value must resolve through the effective +SRD-plus-overlay catalog as either a canonical name or alias. Catalog +validation accepts aliases but does not rewrite them; unknown fields are +rejected. ## Source References @@ -81,10 +84,18 @@ manifest metadata: "response_schema_id": "notarius.dnd.spells", "response_schema_name": "notarius_dnd_spells_v1", "response_schema_version": "v1", - "response_schema_sha256": "sha256:..." + "response_schema_sha256": "sha256:...", + "catalog_base_id": "dnd-5e-2014-srd-spells", + "catalog_digest": "sha256:...", + "catalog_overlay_ids": ["campaign.example"] } } } ``` -Raw prompt and schema content are not included in manifest metadata. +`catalog_digest` identifies the effective semantic catalog, while +`catalog_overlay_ids` is sorted and empty for a base-only configuration. Raw +prompt, schema, catalog, alias, and local overlay-file content are not +included in manifest metadata. Overlay origin, media type, byte size, and raw +digest are recorded separately in the manifest's reference provenance; see +the [JSON output contract](json-output.md#manifestjson). diff --git a/docs/internal/modules.md b/docs/internal/modules.md index b6525d3..eee303e 100644 --- a/docs/internal/modules.md +++ b/docs/internal/modules.md @@ -70,15 +70,15 @@ license details live beside the asset in `SOURCES.md`. This domain-owned data is separate from `internal/modules/dnd/shared`, which is reserved for reusable prompt and source-reference machinery. -`ResolveEffectiveCatalog` builds the immutable recognition view used by later -D&D consumers. It starts with the embedded SRD catalog and optionally applies -one strict JSON overlay from the `spell_catalog` item in a materialized -reference set. Overlay catalogs are ordered by ID, may add names and aliases, -and may augment an existing canonical spell without replacing its display -name. Cross-spell lookup collisions are errors. The effective view exposes -sorted canonical names, normalized lookup, overlay identities, and a semantic -digest; overlay content remains contextual reference material rather than -source evidence. Its external JSON contract is defined in the +`ResolveEffectiveCatalog` builds the immutable recognition view used by the +spell extractor and catalog validator. It starts with the embedded SRD catalog +and optionally applies one strict JSON overlay from the `spell_catalog` item in +a materialized reference set. Overlay catalogs are ordered by ID, may add names +and aliases, and may augment an existing canonical spell without replacing its +display name. Cross-spell lookup collisions are errors. The effective view +exposes sorted canonical names, normalized lookup, overlay identities, and a +semantic digest; overlay content remains contextual reference material rather +than source evidence. Its external JSON contract is defined in the [spell-catalog overlay contract](../integrations/dnd-spell-catalog-overlays.md). ## Input Adapter diff --git a/docs/internal/overview.md b/docs/internal/overview.md index 94bc8da..c22b38e 100644 --- a/docs/internal/overview.md +++ b/docs/internal/overview.md @@ -87,7 +87,7 @@ Configuration. The implemented module packages are: | `internal/modules/dnd` | Owns the canonical D&D spell-list and spell-cast artifact types. | | `internal/modules/dnd/codec/spells` | Strictly decodes and stably encodes the durable D&D spell-list representation. | | `internal/modules/dnd/extract/spells` | Maps private structured model output to canonical source-grounded D&D spell lists. | -| `internal/modules/dnd/spells/catalog` | Embeds and validates the versioned D&D 5e 2014 SRD spell catalog and provides immutable lookup. | +| `internal/modules/dnd/spells/catalog` | Embeds and validates the versioned D&D 5e 2014 SRD catalog, composes optional overlays, and provides immutable effective lookup. | | `internal/modules/generic/merge/appendorder` | Combines accepted extraction results in chunk order. | | `internal/modules/generic/normalize/noop` | Preserves accepted merged output. | | `internal/modules/generic/output/json` | Encodes manifests, lane payloads, warnings, and rejections as logical JSON files. | @@ -101,7 +101,7 @@ Generic validators under `internal/modules/generic/validate` provide unconditional test decisions, JSON syntax validation, and JSON Schema validation. D&D spell validators under `internal/modules/dnd/validate/spells` consume the canonical spell-list type directly to provide shape, -source-reference, and source-relatedness decisions. +effective-catalog, source-reference, and source-relatedness decisions. Production composition is grouped behind package-family registrars, and every implemented production extension uses its domain-first tree: diff --git a/docs/roadmap/dnd-spell-extraction.md b/docs/roadmap/dnd-spell-extraction.md index 094004a..8df0656 100644 --- a/docs/roadmap/dnd-spell-extraction.md +++ b/docs/roadmap/dnd-spell-extraction.md @@ -2,9 +2,31 @@ ## Status -The immediate baseline feature is accepted and pending implementation. -Feedback-aware repair and semantic LLM validation are deferred until the -baseline has been evaluated. +The accepted baseline implementation is complete. It provides effective +SRD-plus-overlay catalog composition, canonical-name prompt grounding, +deterministic catalog validation, the maintained `retries: 2` policy, and +provenance and checkpoint identity coverage through the assembled offline +workflow. + +External quality evaluation is pending. This repository contains the +maintained example and offline fake-LLM coverage, but no approved +human-reviewed transcript corpus or authorized live-model evaluation was +available for this implementation run. The maintained example can be run +from the repository root with: + +```sh +go run ./cmd/notarius run dnd-session \ + --config examples/dnd-spells-production.config.yml \ + --input examples/seriatim-minimal-transcript.json \ + --chunk_cache bypass +``` + +That command requires the configured Scriptorium profile credential. When an +approved profile and reviewed corpus are available, record anonymized +aggregate false positives, false negatives, unknown-name rejections, +acceptance by attempt, and model-call cost here without committing transcripts +or raw prompts. Feedback-aware repair and semantic LLM validation remain +deferred until that baseline evaluation is available. ## Objective diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index 78e9e9a..1088ae5 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -9,14 +9,9 @@ not as committed release dates. ### Solidify Spell Extraction -- Implement the immediate overlay-capable catalog-grounding and - deterministic-validation baseline in - [D&D Spell Extraction Quality](dnd-spell-extraction.md), using ordinary - `retries: 2` behavior as the comparison point. -- After evaluating that baseline, reconsider the roadmap's deferred structured - diagnostics, retryability classification, repair-capable extractor contract, - hybrid repair/fresh retry policy, and narrowly scoped semantic LLM - validation. +- Evaluate the implemented baseline in + [D&D Spell Extraction Quality](dnd-spell-extraction.md), then reconsider its + [deferred retry and validation work](dnd-spell-extraction.md#deferred-retry-and-validation-work). - Replace the no-op spell normalizer with a D&D-specific implementation that canonicalizes recognized spell names, performs only high-confidence repairs, retains uncertain values for review, and emits scoped warnings. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 56c178a..c4b5561 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -2,9 +2,10 @@ ## Status -Ready for implementation. Follow the stages in order. This plan covers the -accepted baseline in [D&D Spell Extraction Quality](dnd-spell-extraction.md), -not its deferred repair-aware retry or semantic LLM-validation work. +The accepted baseline implementation is complete through the assembled +offline workflow. External quality evaluation remains pending as recorded in +[D&D Spell Extraction Quality](dnd-spell-extraction.md). This plan covers that +baseline, not its deferred repair-aware retry or semantic LLM-validation work. This active plan replaces the completed test-suite implementation record that previously occupied this filename. That review remains documented in