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

Introduce typed D&D spell artifacts

Browse Source
This commit is contained in:
Eric Rakestraw
2026-07-17 06:50:08 +00:00
parent b949e9bbc0
commit 142ba36695
27 changed files with 836 additions and 608 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
docs/internal/modules.md
View File

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

14
docs/internal/overview.md
View File

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

14
docs/internal/pipeline.md
View File

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