notarius/docs/roadmap/2-framework-composition.md

Checkpoint 2: Framework Composition

Status

This document describes planned work, not implemented behavior.

Goal

Prove the core contracts compose before adding real adapters, real extractors, or portable Audita infrastructure.

This checkpoint should produce a minimal runner that can execute fake registered components from source input to artifact output in tests.

Scope

In scope:

• input adapter registry;
• extractor registry;
• validator decision model;
• decision-cardinality checks;
• minimal runner;
• fake-component runner tests.

Out of scope:

• real input parsing;
• real LLM calls;
• prompt assets;
• response schema assets;
• diagnostics run directory;
• real D&D artifact schemas.

Proposed Stages

Stage 1: Input Adapter Registry

Add a registry for InputAdapter constructors or instances.

The registry should:

• reject empty keys;
• reject duplicate registrations;
• return clear errors for unknown keys;
• avoid importing concrete adapter packages from core contracts.

Stage 2: Extractor Registry

Add a registry for extractor constructors or instances.

The registry should:

• support stable extractor keys;
• support repeated extractor instances if needed later;
• return clear errors for unknown keys;
• avoid domain-specific logic.

Stage 3: Validator Decisions

Add validator decision types and cardinality checks.

Each validator should return exactly one decision for each candidate artifact it receives.

Decision fields should include:

• candidate index;
• approved flag;
• reason code;
• message;
• optional diagnostics path.

Stage 4: Minimal Runner

Add a runner that can:

1. receive a SourceDocument;
2. execute configured extractors;
3. validate candidate artifacts;
4. return approved and rejected artifacts.

Keep source chunking optional or stubbed at this checkpoint. The runner may operate on whole documents only until source-unit chunking is added later.

Stage 5: Runner Tests With Fakes

Add tests with fake components that prove:

• registered fake extractors run in configured order;
• validators filter candidates deterministically;
• decision cardinality failures are surfaced;
• approved and rejected artifacts are returned in stable order.

Done Criteria

• go test ./... passes.
• Fake adapter/extractor/validator registrations work in tests.
• The runner operates on SourceDocument, not transcript-specific structures.
• The runner does not import concrete D&D extractor packages.

Review Questions

• Does the runner know only about sources, extractors, validators, and artifacts?
• Are registries simple enough to evolve?
• Are validation decisions expressive enough for deterministic and LLM-backed validators?
• Is any domain-specific behavior creeping into framework packages?