# Implementation Plan: Checkpoint 2 Framework Composition ## Status This is a staged implementation plan for [`2-framework-composition.md`](2-framework-composition.md). It is intended for an LLM coding agent to follow stage by stage. This plan implements only checkpoint 2. Do not implement real input adapters, real extractors, source chunking, LLM provider clients, prompt assets, response schema registries, diagnostics run directories, production config loading, or D&D artifact schemas in this pass. ## Policy Context Follow: - [`docs/policy/architecture.md`](../policy/architecture.md) - [`docs/policy/documentation.md`](../policy/documentation.md) Required boundaries: - framework packages must stay source-agnostic and domain-agnostic; - input adapter registry code must not import concrete adapter packages; - extractor registry and runner code must not import concrete extractor packages; - runner code should operate on `SourceDocument`, not transcript-specific structures; - validators should be independently testable and composable; - planned behavior outside this checkpoint must remain in roadmap docs. ## Global Implementation Decisions - Add no third-party dependencies in checkpoint 2. - Do not change public core source/artifact/contract types unless a stage cannot compile without a small compatibility adjustment. - Use constructor-based registries. Constructors can close over future dependencies without changing registry APIs. - Registries normalize keys with `strings.TrimSpace`. - Registries reject empty keys, duplicate keys, nil constructors, nil built instances, and key/name mismatches. - The minimal runner receives an already parsed `*source.SourceDocument`. - The minimal runner does not use input adapters yet; input adapter registry is tested directly. - The runner assigns global candidate indices in extractor execution order. - If a candidate supplies non-empty extractor metadata that conflicts with its owning extractor, the runner returns an error. - If a candidate leaves extractor metadata empty, the runner fills `ExtractorKey`, `ArtifactType`, and `SchemaVersion` from the owning extractor. - Validator chains run in the order returned by `Extractor.Validators()`. - A validator result must use the same `ValidatorName` as `Validator.Name()`. - Each validator must return exactly one decision for each currently eligible candidate. - If an extractor has no validators, its candidates are approved. - On setup, extraction, or validation errors, return the current partial `RunOutput` with a wrapped error. - Run `gofmt` on all touched Go files before validation. ## Stage 1: Input Adapter Registry ### Goal Add a constructor-based registry for `contracts.InputAdapter`. ### Files To Add - `internal/framework/inputregistry/registry.go` - `internal/framework/inputregistry/registry_test.go` ### Required API Create package `inputregistry`. Define: ```go type Constructor func() (contracts.InputAdapter, error) type Registry struct { // unexported fields } func New() *Registry func (r *Registry) Register(key string, constructor Constructor) error func (r *Registry) Build(key string) (contracts.InputAdapter, error) func (r *Registry) RegisteredKeys() []string ``` ### Required Behavior `Register` must: - return an error if the registry is nil; - trim `key`; - reject empty keys; - reject nil constructors; - reject duplicate keys; - store constructors by normalized key. `Build` must: - return an error if the registry is nil; - trim `key`; - reject empty keys; - return a clear unknown-key error for unregistered keys; - call the constructor; - wrap constructor errors with key context; - reject nil adapters; - reject adapters whose `Key()` does not match the normalized key. `RegisteredKeys` must: - return nil for a nil registry; - return registered keys in sorted order; - return a copy that callers cannot mutate to affect registry state. ### Required Tests Cover: - successful registration and build; - key trimming; - empty key rejection; - duplicate key rejection; - nil constructor rejection; - unknown key build error; - constructor error wrapping; - nil adapter rejection; - adapter key mismatch rejection; - sorted `RegisteredKeys`; - nil registry behavior. Use fake adapters only. Do not add concrete adapter packages. ### Validation Run: ```sh gofmt -w internal/framework/inputregistry go test ./internal/framework/inputregistry go test ./... ``` ## Stage 2: Extractor Registry ### Goal Add a constructor-based registry for `contracts.Extractor`. ### Files To Add - `internal/framework/extractorregistry/registry.go` - `internal/framework/extractorregistry/registry_test.go` ### Required API Create package `extractorregistry`. Define: ```go type Constructor func() (contracts.Extractor, error) type Registry struct { // unexported fields } func New() *Registry func (r *Registry) Register(key string, constructor Constructor) error func (r *Registry) Build(key string) (contracts.Extractor, error) func (r *Registry) RegisteredKeys() []string ``` ### Required Behavior Mirror `inputregistry` behavior, but for `contracts.Extractor`. `Build` must reject extractors whose `Key()` does not match the normalized key. It should not validate artifact type, schema version, or validator chain. Those are extractor/runtime concerns. ### Required Tests Cover the same cases as the input adapter registry: - successful registration and build; - key trimming; - empty key rejection; - duplicate key rejection; - nil constructor rejection; - unknown key build error; - constructor error wrapping; - nil extractor rejection; - extractor key mismatch rejection; - sorted `RegisteredKeys`; - nil registry behavior. Use fake extractors only. Do not add concrete extractor packages. ### Validation Run: ```sh gofmt -w internal/framework/extractorregistry go test ./internal/framework/extractorregistry go test ./... ``` ## Stage 3: Validator Runtime Helpers ### Goal Add shared validator decision helpers and decision-cardinality enforcement. ### Files To Add - `internal/framework/validators/validators.go` - `internal/framework/validators/validators_test.go` ### Required API Create package `validators`. Define reason constants: ```go const ( ReasonApproved = "approved" ) ``` Define helpers: ```go func Approved(candidateIndex int) contracts.ValidationDecision func Rejected(candidateIndex int, reasonCode string, message string) contracts.ValidationDecision func EnforceDecisionCardinality(candidates []artifacts.Candidate, decisions []contracts.ValidationDecision) error ``` ### Required Behavior `Approved` returns an approved decision with: - `CandidateIndex` set to the input; - `Approved` set to true; - `ReasonCode` set to `ReasonApproved`; - `Message` set to `approved`. `Rejected` returns a rejected decision with: - `CandidateIndex` set to the input; - `Approved` set to false; - `ReasonCode` set to the trimmed reason code; - `Message` set to the trimmed message. `EnforceDecisionCardinality` must: - require exactly one decision per candidate index; - reject decisions for unknown candidate indices; - reject duplicate decisions for the same candidate index; - reject missing decisions; - work with candidate indices, not slice positions; - allow an empty candidate slice only when decisions are also empty. Candidate indices are expected to be unique by the time validators run. If the candidate slice itself contains duplicate indices, return an error. ### Required Tests Cover: - approved helper shape; - rejected helper trims reason/message; - cardinality success with non-zero candidate indices; - empty candidates and empty decisions success; - unknown decision index error; - duplicate decision index error; - missing decision index error; - duplicate candidate index error. ### Validation Run: ```sh gofmt -w internal/framework/validators go test ./internal/framework/validators go test ./... ``` ## Stage 4: Minimal Runner Types And Constructor ### Goal Add runner package types and constructor without implementing the full run loop yet. ### Files To Add - `internal/framework/runner/runner.go` - `internal/framework/runner/runner_test.go` ### Required API Create package `runner`. Define: ```go type ExtractorFactory interface { Build(key string) (contracts.Extractor, error) } type Runner struct { // unexported fields } func New(extractors ExtractorFactory) *Runner ``` Define input/output structs: ```go type RunInput struct { Source *source.SourceDocument ExtractorKeys []string LLMClient contracts.StructuredLLMClient Metadata map[string]any } type RunOutput struct { Approved []artifacts.Artifact `json:"approved,omitempty"` Rejected []artifacts.RejectedArtifact `json:"rejected,omitempty"` Warnings []contracts.Warning `json:"warnings,omitempty"` } ``` Define package errors as ordinary returned errors. Do not introduce custom error types in this checkpoint unless tests require behavior that ordinary errors cannot express. ### Required Behavior At this stage, `New` should only store the extractor factory. If you add `Run` in this stage as a stub, it must return an explicit `runner is not implemented` error and must be completed in stage 5. Prefer adding the real `Run` method only in stage 5. ### Required Tests Cover: - `New` accepts a fake extractor factory and returns a non-nil runner; - `RunInput` and `RunOutput` can be constructed with the expected fields. Do not add registry imports to runner tests unless needed for interface assertions. Runner should depend only on framework contracts and core packages. ### Validation Run: ```sh gofmt -w internal/framework/runner go test ./internal/framework/runner go test ./... ``` ## Stage 5: Minimal Runner Execution ### Goal Implement the minimal runner flow from `SourceDocument` to approved/rejected artifacts. ### Files To Update - `internal/framework/runner/runner.go` - `internal/framework/runner/runner_test.go` ### Required API Add: ```go func (r *Runner) Run(ctx context.Context, input RunInput) (RunOutput, error) ``` ### Required Behavior `Run` must: 1. reject nil runner or nil extractor factory; 2. validate `input.Source` with `source.ValidateDocument`; 3. reject an empty `ExtractorKeys` list; 4. process extractor keys in input order; 5. build each extractor through the factory; 6. call `Extractor.Extract` with the source, LLM client, and metadata; 7. append extractor warnings to `RunOutput.Warnings`; 8. normalize candidate metadata for each returned candidate; 9. run validators in `Extractor.Validators()` order; 10. approve candidates that survive all validators; 11. reject candidates denied by validators; 12. return approved/rejected artifacts in deterministic order. Candidate normalization must: - assign `Candidate.Index` using a global monotonically increasing counter; - fill empty `ExtractorKey`, `ArtifactType`, and `SchemaVersion` from the owning extractor; - return an error if a candidate's non-empty `ExtractorKey` differs from `Extractor.Key()`; - return an error if a candidate's non-empty `ArtifactType` differs from `Extractor.ArtifactType()`; - return an error if a candidate's non-empty `SchemaVersion` differs from `Extractor.SchemaVersion()`. Validation behavior: - if an extractor has no validators, all normalized candidates are approved; - each validator receives only currently eligible candidates; - each validator result must have `ValidatorName == Validator.Name()`; - call `validators.EnforceDecisionCardinality` for every validator result; - approved decisions keep candidates eligible for the next validator; - rejected decisions create `artifacts.RejectedArtifact` records using the candidate, validator name, reason code, and message; - candidates rejected by one validator are not passed to later validators; - append validator warnings to `RunOutput.Warnings`. Error behavior: - return current partial `RunOutput` plus an error for setup, extraction, validation, cardinality, or metadata mismatch failures; - wrap errors with enough context to identify the extractor key or validator name. Do not validate source references inside the runner in checkpoint 2. Source reference validation will be a deterministic validator in a later checkpoint. ### Required Tests Cover: - nil runner/factory error; - invalid source document error; - empty extractor list error; - extractor keys run in configured order; - runner assigns global candidate indices across extractors; - runner fills empty candidate extractor metadata; - candidate extractor-key mismatch errors; - candidate artifact-type mismatch errors; - candidate schema-version mismatch errors; - no validators approves all candidates; - validator approval produces approved artifacts; - validator rejection produces rejected artifacts and removes candidate from later validators; - validator name mismatch errors; - validator cardinality error is surfaced; - extractor warnings and validator warnings are collected; - partial output is returned when a later extractor or validator fails. Use fake extractors, validators, and factories only. ### Validation Run: ```sh gofmt -w internal/framework/runner go test ./internal/framework/runner go test ./... ``` ## Stage 6: Registry And Runner Integration Tests ### Goal Prove the extractor registry and runner compose without adding real extractors. ### Files To Add - `internal/framework/runner/registry_integration_test.go` ### Required Test Scenario Use `extractorregistry.New()` to register two fake extractor constructors. Run the runner with: - a valid `SourceDocument`; - extractor keys in a deliberate order; - fake extractors that each return one candidate; - fake validators that approve or reject candidates. Assertions: - registered fake extractors are built by key; - extractor execution follows configured key order; - approved artifacts are in deterministic order; - rejected artifacts are in deterministic order; - no concrete adapter or extractor packages are imported. ### Validation Run: ```sh gofmt -w internal/framework/runner go test ./internal/framework/runner go test ./... go build ./cmd/notarius ``` ## Stage 7: Final Checkpoint 2 Review Pass ### Goal Clean up naming, formatting, and accidental scope creep before checkpoint 2 is considered complete. ### Required Review Check: - no package names mention transcripts, Seriatim, D&D, spells, NPCs, items, or combat; - no concrete adapter or extractor package exists; - no LLM provider code exists; - no prompt, response schema, diagnostics, config, or source chunking package was added; - no third-party dependency was added; - runner operates on `SourceDocument`; - input adapter registry is not wired into runner yet; - roadmap docs remain the only place describing future behavior. ### Required Validation Run: ```sh gofmt -w internal/framework go test ./... go build ./cmd/notarius git status --short ``` Remove the root `./notarius` binary produced by `go build ./cmd/notarius` before finishing the implementation turn. The implementation response for this checkpoint should summarize: - files added; - tests run; - any deviations from this plan and why. ## Open Questions No blocking open questions remain for checkpoint 2. The plan intentionally keeps raw input parsing outside the runner. The input adapter registry is added and tested now because it is part of framework composition, but concrete parsing and adapter-runner wiring remain deferred until the Seriatim adapter checkpoint.