# ADR-0002: zod as schema source of truth

**Status**: accepted · 2026-09

**Context**: Business objects cross TS runtime ↔ Python skills; schema drift
between languages is the classic failure. Someone must own the truth.

**Decision**: Hand-written zod schemas in `packages/domain` are the only
source. Build exports JSON Schema to `contracts/` (committed, versioned);
pydantic models are generated from those (never hand-edited). Golden fixtures
validated by both CIs. Data representation rules in docs/11 §3.3 are part of
the contract (decimal strings for money, units in field names, etc.).

**Alternatives**: Hand-written JSON Schema as neutral source (revisit if
Python-side partners need co-ownership — the contracts/ layer stays identical);
protobuf/gRPC (rejected: call volume doesn't need it, lineage snapshots should
be human-readable, partner onboarding cost).

**Consequences**: Python teams depend only on `contracts/`, never on TS
internals — org boundary = code boundary.