Introduce typed D&D spell artifacts

docs/integrations/dnd-spell-artifacts.md

@@ -6,6 +6,7 @@ extractor. Selectable extractor keys are cataloged in
 
 ## Identity
 
+- Artifact kind: `dnd/spell-list`
 - Prompt ID: `dnd.spells`
 - Response schema key: `dnd_spells`
 - Response schema ID: `notarius.dnd.spells`
@@ -13,6 +14,12 @@ extractor. Selectable extractor keys are cataloged in
 - Response schema version: `v1`
 - Media type: `application/json`
 
+The durable JSON Schema is owned by the D&D spell artifact codec. The
+extractor's private LLM response schema is a separate transport contract: its
+source-reference objects omit `source_id`, which the extractor assigns while
+mapping the response to the canonical artifact. The LLM DTO and transport
+schema are not part of this durable contract.
+
 The output contains canonical spell casts derived from transcript evidence.
 Source IDs are assigned from the input identity; source-unit ranges identify
 the evidence location.

docs/internal/modules.md

@@ -17,15 +17,14 @@ validator registry. Package-family registrars compose those leaf registrations
 into the production catalog and own family-level policy such as default
 validator chains and prompt asset collection.
 
-Production input, chunk, and output packages register strict option decoders and
-run-local builders. Preparation decodes their options into implementation-owned
-values and injects dependencies; their operation requests contain run context,
-not raw option maps or LLM clients. Production extract, merge, normalize, and
-validator packages still use the explicit legacy raw registration APIs and
-temporary adapters around zero-argument constructors. Their raw option maps and
-LLM clients remain operation inputs while that part of the catalog migrates.
-Typed registration is framework-ready, but no production artifact kind or
-codec is registered yet.
+Production input, chunk, output, and D&D spell-extract packages register strict
+option decoders and run-local builders. Preparation decodes their options into
+implementation-owned values and injects dependencies. The spell extractor is
+typed over the canonical D&D model; a temporary raw adapter preserves the
+current downstream production path. Production merge, normalize, and validator
+packages still use the explicit legacy raw registration APIs and temporary
+adapters around zero-argument constructors. Their raw option maps and LLM
+clients remain operation inputs while that part of the catalog migrates.
 
 Specs expose capability and execution metadata without constructing an
 implementation. Registry entries separately expose option validation and
@@ -106,12 +105,16 @@ The spell extractor prepares a structured request from one chunk, the
 chunk-scoped source input, the session, and optional D&D reference inputs. It
 decodes the model response, assigns the generic source identity to every source
 reference, canonicalizes duplicate references, orders spell casts by their
-earliest cited unit, and returns raw JSON plus response-schema provenance.
+earliest cited unit, and returns `dnd.SpellList`.
 
-The package owns its embedded prompt, response schemas, and prompt/schema
-manifest metadata. Shared D&D helpers keep prompt input names and source-unit
-reference conversion consistent with the scene chunker. The extractor produces
-raw output; production validators own approval policy.
+The extractor owns its private model-response DTO, embedded prompt, LLM response
+schema, strict option decoder, injected shared LLM client, and prompt/schema
+manifest metadata. The separate `internal/modules/dnd/codec/spells` package
+owns the durable schema and stable JSON representation for artifact kind
+`dnd/spell-list`. Production composition currently wraps the typed extractor
+with a raw adapter that encodes through this codec, so existing validators and
+later stages remain unchanged. Shared D&D helpers keep prompt input names and
+source-unit reference conversion consistent with the scene chunker.
 
 The durable payload and manifest metadata shapes are defined in the
 [D&D spell artifact contract](../integrations/dnd-spell-artifacts.md).

docs/internal/overview.md

@@ -62,10 +62,12 @@ run-local construction closures. Preparation injects shared dependencies and
 constructs input, chunk, validators, ordered lanes, and output before source
 parsing. Production input, chunk, and output modules use strict construction-time
 option decoding, and the LLM-backed scene chunker retains the injected shared
-client. Production artifact-lane modules and validators do not register typed
-variants yet and continue through explicitly named legacy raw registrations and
-temporary zero-argument constructor adapters. The current runner rejects a
-typed prepared lane instead of routing it through raw execution.
+client. The D&D family registers the canonical `dnd/spell-list` codec and a
+typed spell extractor. A temporary raw adapter serializes that typed result for
+the still-raw production validators, merger, normalizer, and runner. Other
+artifact-lane modules and validators continue through explicitly named legacy
+raw registrations and temporary zero-argument constructor adapters. The current
+runner rejects a typed prepared lane instead of routing it through raw execution.
 
 ## Production Extensions
 
@@ -79,7 +81,9 @@ Configuration. The implemented module packages are:
 | `internal/modules/seriatim/input/transcript` | Parses the supported Seriatim transcript format into the generic source model. |
 | `internal/modules/generic/chunk/units` | Splits ordered source units by unit count and overlap. |
 | `internal/modules/dnd/chunk/scenes` | Produces contiguous D&D scene chunks from structured model output. |
-| `internal/modules/dnd/extract/spells` | Produces source-grounded D&D spell-cast raw output. |
+| `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/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. |

docs/internal/pipeline.md

@@ -73,9 +73,11 @@ separate target namespaces; serialized registrations declare whether they
 support chunks, artifacts, or both. Duplicate variants and exact Go-type
 mismatches are rejected deterministically.
 
-Production composition initializes the artifact codec registry without adding
-codec entries, and production artifact-lane modules use the explicitly named
-legacy raw registration APIs. A raw registration cannot satisfy a typed lane.
+Production composition registers the D&D spell-list codec. The typed spell
+extractor also registers a temporary raw adapter, which resolution selects
+until its downstream production lane is typed. Other production artifact-lane
+modules use the explicitly named legacy raw registration APIs. A standalone raw
+registration cannot satisfy a typed lane.
 
 A `ModuleSpec` declares its stage plus required and provided capabilities.
 Chunk, extract, merge, and normalize specs may also declare reference slots.
@@ -84,8 +86,10 @@ and verify that a constructed implementation reports the registered key.
 Builder registrations accept `ModuleDependencies` and cloned raw options through
 one `BuildRequest`. Production input, chunk, and output builders decode those
 options and retain typed values or injected dependencies in the constructed
-implementation. Remaining production raw-stage registrations are adapted from
-their zero-argument constructors during migration.
+implementation. A typed extractor registration may explicitly supply a raw
+adapter builder for a still-raw downstream lane; the adapter is selected as one
+unit and does not expose the typed value to raw consumers. Remaining production
+raw-stage registrations are adapted from their zero-argument constructors.
 
 A `ValidatorSpec` declares a validator key and execution class. Resolution uses
 the execution class to reject incompatible profile bindings before execution.