124 lines
3.0 KiB
Markdown
124 lines
3.0 KiB
Markdown
# Checkpoint 1: Core Contracts And Skeleton
|
|
|
|
## Status
|
|
|
|
This document describes planned work, not implemented behavior.
|
|
|
|
## Goal
|
|
|
|
Define the stable vocabulary and core interfaces that adapters, extractors,
|
|
validators, and runners will build against.
|
|
|
|
This checkpoint should produce a compileable Go repository with a minimal CLI
|
|
shell and contract-level tests. It does not need to process real input or
|
|
produce useful artifacts.
|
|
|
|
## Scope
|
|
|
|
In scope:
|
|
|
|
- Go module bootstrap;
|
|
- executable entrypoint;
|
|
- minimal CLI package;
|
|
- core source, artifact, manifest, and contract types;
|
|
- fake implementation tests proving the interfaces are usable.
|
|
|
|
Out of scope:
|
|
|
|
- real input adapters;
|
|
- real extractors;
|
|
- LLM provider calls;
|
|
- prompt or response-schema assets;
|
|
- diagnostics run directory;
|
|
- production config loading.
|
|
|
|
## Proposed Stages
|
|
|
|
### Stage 1: Bootstrap Go Project
|
|
|
|
Create:
|
|
|
|
- `go.mod`;
|
|
- `cmd/notarius/main.go`;
|
|
- `internal/cli`;
|
|
- a minimal CLI command surface that compiles.
|
|
|
|
Expected validation:
|
|
|
|
```sh
|
|
go test ./...
|
|
go build ./cmd/notarius
|
|
```
|
|
|
|
### Stage 2: Source Core Types
|
|
|
|
Create `internal/core/source`.
|
|
|
|
Initial types:
|
|
|
|
- `SourceDocument`;
|
|
- `SourceUnit`;
|
|
- `SourceRef`;
|
|
- source validation helpers for document ID, ordered units, unique unit IDs, and
|
|
non-empty text.
|
|
|
|
Keep the model generic. Do not introduce transcript-specific field names into
|
|
core source types.
|
|
|
|
### Stage 3: Artifact Core Types
|
|
|
|
Create `internal/core/artifacts`.
|
|
|
|
Initial types:
|
|
|
|
- artifact candidate;
|
|
- approved artifact envelope;
|
|
- rejected artifact record;
|
|
- run manifest;
|
|
- source-reference-bearing helper interfaces or conventions if useful.
|
|
|
|
Keep the artifact model extractor-neutral. D&D-specific fields should wait until
|
|
the D&D spells extractor checkpoint.
|
|
|
|
### Stage 4: Framework Contract Types
|
|
|
|
Create `internal/framework/contracts`.
|
|
|
|
Initial contracts:
|
|
|
|
- `InputAdapter`;
|
|
- `Extractor`;
|
|
- `Validator`;
|
|
- structured LLM client interface placeholder;
|
|
- parse, extraction, and validation request/response types.
|
|
|
|
Interfaces should be small and should depend on core source/artifact types, not
|
|
on concrete adapter or extractor packages.
|
|
|
|
### Stage 5: Contract Tests With Fakes
|
|
|
|
Add tests using fake adapter, extractor, and validator implementations.
|
|
|
|
These tests should prove:
|
|
|
|
- fake components can satisfy the interfaces;
|
|
- source documents can flow into extraction requests;
|
|
- artifact candidates can flow into validation requests;
|
|
- the contracts are not forcing transcript or D&D assumptions.
|
|
|
|
## Done Criteria
|
|
|
|
- `go test ./...` passes.
|
|
- `go build ./cmd/notarius` passes.
|
|
- Core types and contracts exist in stable package locations.
|
|
- Tests prove fake implementations can compose at the type-contract level.
|
|
- No real Seriatim, D&D, LLM, or Audita-specific behavior has been added yet.
|
|
|
|
## Review Questions
|
|
|
|
- Are the interfaces small enough?
|
|
- Are source-format details absent from core packages?
|
|
- Are D&D concepts absent from framework and core packages?
|
|
- Is the shell compileable without placeholder behavior that will be hard to
|
|
unwind?
|