eric/notarius
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document completed spell catalog baseline

Browse Source
This commit is contained in:
Eric Rakestraw
2026-07-20 19:44:31 +00:00
parent 3d0d79360e
commit 87c57681f6
6 changed files with 57 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docs/integrations/dnd-spell-artifacts.md
View File

@@ -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).

18
docs/internal/modules.md
View File

@@ -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

4
docs/internal/overview.md
View File

@@ -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:

28
docs/roadmap/dnd-spell-extraction.md
View File

@@ -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

11
docs/roadmap/future.md
View File

@@ -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.

7
docs/roadmap/implementation.md
View File

@@ -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