notarius/docs/internal/modules.md

Modules

Production modules live under internal/modules. Each module implements one contract from internal/framework/contracts, exposes a ModuleSpec, and registers itself with the matching pipeline registry.

The CLI production catalog currently registers only the modules listed here.

Contract Pattern

A production module package should provide:

• a stable module key;
• a constructor such as New;
• the relevant contract implementation;
• ModuleSpec;
• Register;
• focused tests for registration, options, contract behavior, and errors.

Module specs should describe capabilities accurately. Resolution uses specs to reject incompatible pipelines before execution.

seriatim Input

Package: internal/modules/input/seriatim

The seriatim adapter parses Seriatim transcript JSON into a generic source document. It owns transcript JSON details, source ID selection, source digest creation, transcript segment validation, and segment metadata mapping.

Provides:

• source.transcript
• transcript.speaker
• transcript.timestamps

External JSON shape belongs in the Seriatim integration doc.

generic Chunker

Package: internal/modules/chunk/generic

The generic chunker splits source units into ordered chunks. It validates the source document, clones source units, assigns chunk IDs such as chunk-000001, and records chunk metadata for start unit, end unit, and unit count.

Options:

• max_units: positive integer, default 50;
• overlap_units: non-negative integer, default 0, and less than max_units.

Provides:

• chunks

dnd/spells Extractor

Package: internal/modules/extract/dnd/spells

The dnd/spells extractor owns D&D spell-cast artifact semantics. It renders embedded prompts, loads the embedded structured response schema, calls the structured LLM client, converts spell-cast responses into artifact candidates, and supplies deterministic validators.

Requires:

• chunks
• source.transcript

Provides:

• dnd.spell_casts

Artifact type and schema version:

• artifact type: dnd.spell_cast
• schema version: v1

The extractor adds prompt and response-schema provenance to lane manifest metadata. Durable artifact payload details belong in the D&D spell artifact contract.

D&D Spell Validators

The spell extractor returns two built-in validators:

• dnd/spells/shape: rejects malformed payloads and missing required fields.
• dnd/spells/source_refs: rejects candidates without valid source references.

Reason codes include:

• invalid_payload
• missing_required_field
• missing_source_ref
• invalid_source_ref

These validators are supplied by the extractor when no validators are configured for the lane.

appendorder Merger

Package: internal/modules/merge/appendorder

The appendorder merger clones and appends candidates in chunk order. It does not deduplicate or reconcile candidates.

Provides:

• merged

noop Normalizer

Package: internal/modules/normalize/noop

The noop normalizer clones merged candidates and returns them unchanged.

Requires:

• merged

Provides:

• normalized

json Output

Package: internal/modules/output/json

The json output encoder converts approved artifacts, rejected artifacts, warnings, and the run manifest into logical JSON output files. It groups approved artifacts by artifact type and sanitizes artifact-type file names.

Requires:

• normalized

Provides:

• encoded

Durable output file shapes belong in the JSON output contract. Operator behavior belongs in Operations.

Production Registration

Production registration is centralized in internal/cli/catalog.go.

Do not make framework code import production modules. The CLI wires production modules at the application boundary; tests may provide fake registries or fake catalogs directly.

Adding A Module

When adding a module, keep source-format and extraction-domain boundaries clear:

• input modules may know external source formats;
• extract modules may know artifact semantics and prompt/schema assets;
• merge and normalize modules own candidate combination and reconciliation;
• output modules own serialization, not diagnostics or CLI reporting.

Update Development, Configuration, internal docs, integration docs, and examples when the new module becomes implemented production behavior.