# 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?