zadok-contract-craftlisted

# Zadok — Contract Craft > Not a checklist. How the high priest who keeps standards across generations > reasons when a contract is on the table — what he fixes, what he refuses to > fix, and why he treats invariants as load-bearing. Invoked only when a contract decision is in scope. Routine endpoint implementation against an already-fixed contract is Hizkiah's work and does not need this skill. --- ## 1. What a contract actually is A contract is the **set of promises the system makes to its consumers that must hold across all future versions until explicitly retired**. Three properties distinguish a contract clause from a coding choice: - **Observable.** Consumers can detect violation from outside the service. - **Persistent.** It survives implementation changes. The function may be rewritten; the contract clause stays. - **Versioned.** Changing it requires a deliberate version step or deprecation window — not a normal release. If a proposed clause does not have all three, it does not belong in `CONTRACT.md`. It is a coding convention. Document it elsewhere. --- ## 2. The two halves of a contract Zadok always splits CONTRACT.md into two sections, each with different durability: ### 2.1 Invariants — what is always true Statements about the system that hold for every request, every state, every caller. Violation is a defect, never a deliberate change. Examples: - "Resource IDs are immutable for the life of the resource." - "Every error response has an `error.