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

Update the architecture plan to standardize on input -> chunk -> extract -> merge -> normalize -> output naming conventions

Browse Source
This commit is contained in:
Eric Rakestraw
2026-07-03 09:03:45 -05:00
parent 88042174b3
commit 5a6e82f599
18 changed files with 121 additions and 113 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
docs/roadmap/implementation.md
View File

@@ -7,7 +7,7 @@ This is a staged implementation plan for
an LLM coding agent to follow stage by stage.
This plan implements only checkpoint 2. Do not implement real input modules,
real process modules, source chunking, LLM provider clients, prompt assets,
real extract modules, source chunking, LLM provider clients, prompt assets,
response schema registries, diagnostics run directories, production config
loading, or D&D artifact schemas in this pass.
@@ -22,7 +22,7 @@ Required boundaries:
- framework packages must stay source-agnostic and domain-agnostic;
- input adapter registry code must not import concrete input module packages;
- extractor registry and runner code must not import concrete process module
- extractor registry and runner code must not import concrete extract module
packages;
- runner code should operate on `SourceDocument`, not transcript-specific
structures;
@@ -196,7 +196,7 @@ Cover the same cases as the input adapter registry:
- sorted `RegisteredKeys`;
- nil registry behavior.
Use fake extractors only. Do not add concrete process module packages.
Use fake extractors only. Do not add concrete extract module packages.
### Validation
@@ -236,7 +236,7 @@ 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
func EnforceDecisionCardinality(candidates []artifacts.ArtifactCandidate, decisions []contracts.ValidationDecision) error
```
### Required Behavior
@@ -264,8 +264,8 @@ func EnforceDecisionCardinality(candidates []artifacts.Candidate, decisions []co
- 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.
Artifact 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
@@ -396,7 +396,7 @@ func (r *Runner) Run(ctx context.Context, input RunInput) (RunOutput, error)
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;
4. iterate 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`;
@@ -406,9 +406,9 @@ func (r *Runner) Run(ctx context.Context, input RunInput) (RunOutput, error)
11. reject candidates denied by validators;
12. return approved/rejected artifacts in deterministic order.
Candidate normalization must:
Artifact candidate normalization must:
- assign `Candidate.Index` using a global monotonically increasing counter;
- assign `ArtifactCandidate.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
@@ -502,7 +502,7 @@ Assertions:
- extractor execution follows configured key order;
- approved artifacts are in deterministic order;
- rejected artifacts are in deterministic order;
- no concrete input module or process module packages are imported.
- no concrete input module or extract module packages are imported.
### Validation
@@ -528,7 +528,7 @@ Check:
- no package names mention transcripts, Seriatim, D&D, spells, NPCs, items, or
combat;
- no concrete input module or process module package exists;
- no concrete input module or extract module package exists;
- no LLM provider code exists;
- no prompt, response schema, diagnostics, config, or source chunking package
was added;