<!-- informative -->

# First milestone implementation brief

The agent-independent brief for the first roadmap milestone. It records how the
milestone was scoped and delivered, and is kept as a historical record:
[the milestone itself is COMPLETE](roadmap.md#first-milestone-schema-and-replay-slice),
and the forward plan is the [self-hosting roadmap](self-host.md).

This file is plain Markdown on purpose, so any coding agent can be pointed at
it without depending on a particular agent's command format. It is informative:
the normative contracts it references remain in
[control-plane.md](control-plane.md), [event-catalogue.md](event-catalogue.md),
[experiment.md](experiment.md) and the extracted tables, and where this brief
and those documents disagree, they do.

Implement the first milestone defined in [roadmap.md](roadmap.md) under
`## Milestones` → `First milestone: schema-and-replay slice`, exactly as scoped
there.

Read before coding: [AGENTS.md](../AGENTS.md),
[roadmap.md](roadmap.md), [control-plane.md](control-plane.md) (Reducer contract,
State Machines, MVP ordering, concurrency, and transactions, Replay and external
inputs, Schema and policy evolution baseline, Run termination and outcomes, Crash
recovery), [event-catalogue.md](event-catalogue.md), `docs/tables/*.yaml`,
[glossary.md](glossary.md), and the conformance sections of
[experiment.md](experiment.md).

Build a single-process, single-admission-thread, replayable run against a frozen
repository, using an in-process scripted executor over trusted fixtures. No
untrusted code executes in this milestone.

## Scope

1. Harness contract schemas, driven by one concrete workflow (submit a run
   specification, inspect status, cancel, retrieve candidate reference, outcome,
   evidence, costs, and event history): run configuration, project kernel
   reference, experiment manifest reference, progress/audit record, run result,
   and evidence retrieval. Versioned, uppercase enums, with valid and invalid
   fixture examples.
2. Event-catalogue completion per the [AGENTS.md](../AGENTS.md) change rules:
   `RESULT_REVALIDATED` gains `replacement_result_id`; the replacement's
   `ACCEPTANCE_AUTHORISED` carries `supersedes_result_id`. Results and acceptance
   records are immutable and superseded, never edited; nodes are mutable entities
   with versions.
3. In-process store: single-writer transactional append with atomic
   event-plus-state persistence. SQLite in WAL mode is acceptable; nothing
   normative may depend on SQLite-specific behaviour. Full-log replay from
   genesis; no snapshots.
4. Reducer over the generated tables per
   [Reducer contract](control-plane.md#reducer-contract): unknown event types and
   enum values rejected at admission, explicit-over-wildcard resolution,
   `guarded_alternatives` honoured, one admitted event yields ordered effects,
   and [outcome precedence](control-plane.md#run-termination-and-outcomes) tested
   separately from quiescence.
5. One scripted executor with single-use attempt tokens, dispatch recorded before
   send, duplicate-delivery idempotency, and cancellation and timeout handling.
6. Crash injection at persistence and dispatch boundaries showing the recovery
   behaviour declared in [Crash recovery](control-plane.md#crash-recovery).

## Completion and boundaries

The milestone is complete when the six acceptance demonstrations listed in the
roadmap milestone section pass as automated tests.

Do not build: model adapters, decomposition or recursive planning, parallel
workers, runtime approvals, sandbox enforcement, snapshots, or any external
dispatch substrate; do not freeze the full schema catalogue. Those boundaries
were scoped for this milestone only — the
[self-hosting roadmap](self-host.md) is where the later work, including sandbox
enforcement and the project-owned oracle, was subsequently delivered. If you
believe a deviation from the acceptance list is required, stop and record the
proposed deviation for review before implementing it.

## Repository rules

Follow [AGENTS.md](../AGENTS.md): run `.venv/bin/python scripts/tables.py` (use
`--write` only after editing `docs/tables/*.yaml`), `scripts/check-docs`, and
`pytest -q` after every documentation or schema change; new events require a
catalogue entry, a transition entry, and a conformance test entry; never
hand-edit content between `gen:` markers; keep changes to normative documents
minimal and summarize them for review.
