Add a staged implementation plan for the initial framework and module composition architecture

This commit is contained in:
2026-07-03 07:38:23 -05:00
parent 2690cdd959
commit 281f236e27
2 changed files with 425 additions and 432 deletions

View File

@@ -32,65 +32,26 @@ Out of scope:
- diagnostics run directory;
- real D&D artifact schemas.
## Proposed Stages
## Target End State
### Stage 1: Input Adapter Registry
The repository should contain a minimal framework composition layer:
Add a registry for `InputAdapter` constructors or instances.
- `internal/framework/inputregistry` registers and builds input adapter
constructors by stable key.
- `internal/framework/extractorregistry` registers and builds extractor
constructors by stable key.
- `internal/framework/validators` provides shared validator decision helpers and
cardinality checks.
- `internal/framework/runner` executes configured extractors against a
`SourceDocument`, applies validator chains, and returns approved and rejected
artifacts.
The registry should:
The runner should operate on already parsed source documents in this checkpoint.
Raw input parsing and concrete input adapter behavior remain deferred to the
Seriatim adapter checkpoint.
- 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.
Implementation staging belongs in
[`implementation.md`](implementation.md).
## Done Criteria