notarius/docs/roadmap/1-core-contracts-and-skeleton.md

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:

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?