Documentation menu
On this page

ADR 0001 — The contract owns itself (Q2-A)

Date: 2026-06-11 · Status: accepted

Context

The supervisor and worker implementations evolve independently and meet only at a schema: JSON task in, NDJSON events out, verified result at the end. Independent processes connected by an unversioned schema are the classic way such systems die. Candidate owners: the supervisor, the worker, or neither.

Decision

Neither side owns the boundary; the boundary owns itself. A third, tiny, dependency-light package — agent-task-contract (pydantic only) — holds the Pydantic v2 models, the JSON Schema exports, the golden NDJSON fixtures, and the version-skew helper. The supervisor and worker packages depend on it and run its fixtures in CI. contract_version rides in every envelope and every event from message one. Schema changes: additive optional fields are a minor bump; removal/rename/ semantic change is a major bump; fixtures are regenerated on every bump.

Consequences

  • Envelope models are never redefined locally in either repo (standing guard rail); a drift is a CI failure, not a runtime surprise.
  • The supervisor rejects dispatch on version skew with a doctor-style error (G5), and the worker self-rejects unsupported envelopes via task.rejected.
  • The package must stay small: anything not needed by v1–v2 is reserved in spec §9, not specified.