Decision record For everyone

0001 · The contract is the source of truth; SQL is derived

Status: Accepted
Date: 2026-08-04

Context

A data product's audit question is "what produced this table, and who asked for each column?". If SQL is written by hand — or by a model — beside a contract, the two drift, and the question has no checkable answer.

Decision

The data agreement (contract) is the only authored artefact. domain/generate.py derives the SQL, the tests and the documentation from it, byte-identically, with no model involved. Every column declares the requirement it satisfies and every expectation the criterion it verifies, inside the hashed contract body.

Consequences

An auditor can regenerate any release from its contract and compare. A hand-edit to a generated model is allowed but recorded (patched), and read as a gap in what the contract can express. Anything the contract cannot express needs the contract to grow, which is slower than writing SQL and is the point.