Suede Parity Contract

Suede Parity Contract

Iron Law: generate the contract from the reference surface's live constants.
A contract you transcribe is a second copy, and second copies drift.
A contract you generate cannot disagree with the code it came from.

Silent drift is the failure this prevents. Nothing crashes when a threshold is copied wrong into a second language. The two surfaces simply start answering the same question differently, and a user finds out before you do.

Step 1: Name one reference surface

Exactly one surface is the reference. Every other surface is a follower that asserts against it. Two references is two sources of truth with extra steps.

Pick the surface where the domain is most complete and most exercised, and write that choice into the contract's reference field so nobody re-litigates it.

Step 2: Build the contract by importing, never retyping

The builder imports the constants from the modules the application actually runs on and serializes them. Retyping a value into the builder reintroduces exactly the copy this skill exists to delete.

When a needed value is private, export it rather than duplicating it. That is a one-line change and it keeps the count of definitions at one.

Serialize with stable key order and a trailing newline, because followers vendor the file verbatim and a reformat shows up as a spurious diff.

Step 3: Make staleness fail on the reference side

One test rebuilds the contract in memory and compares it to the committed file. Without it the JSON is a snapshot someone took once.

Give it a write mode so regeneration is one command, and put that command in the contract's README and in the file's own note field:

CONTRACT_WRITE=1 <test runner> <contract test>

Compare parsed objects first so the failure names the key that moved, then compare raw bytes so a reformat is caught too.

Step 4: Vendor byte-identical to each follower

Followers keep a copy at the same relative path. Prove it matches rather than assuming:

shasum -a 256 <reference>/contracts/<name>.json <follower>/contracts/<name>.json

Two identical hashes, or the copy is stale. Record the re-sync command in the follower's README so the next person does not invent one.

Step 5: Assert through public behavior, not private internals

A follower test that reimplements the reference formula proves only that you can write the same bug twice.

Assert what a user experiences. For a ladder, feed the contract's rung values to the public accessor and check the level it returns. For a threshold, check the boundary and one step below it: a threshold asserted only from above still passes after it moves down.

Start the follower suite with a test that the contract loaded and is non-empty. A file that fails to load makes every assertion after it vacuously true.

Step 6: Pin the divergences you already have

You will find existing differences. The contract's job on day one is to make them visible and hold them still, not to erase them.

Record each under knownDivergences with the value on each surface and a reason that survives you leaving. Then add a guard asserting the divergence list is exactly the expected set, so an entry added elsewhere is a failure rather than a silence.

Each pinned divergence gets two assertions on the follower: that it still differs by the recorded amount, and that it does not equal the reference. The second one fires when someone closes the divergence and forgets the contract.

Halt format: a divergence found mid-build

Changing a shipped constant changes behavior for real users, and which surface is right is a product decision. At the moment you find one, stop and report:

Divergence: <key>. <reference surface> says <a>, <follower> says <b>.
Both shipped. <one line on what a user feels>.
  1. Move <follower> to <a>
  2. Move <reference> to <b>
  3. Record it and decide later

Then wait. Do not pick for the user, and do not change either side as a side effect of writing a contract.

Step 7: Prove non-vacuity on both sides, in this run

A parity test that cannot fail is worse than none, because it reads as evidence.

Reference side: change one constant, watch the staleness test fail naming that key, restore it, watch it pass. Follower side: edit one value in the vendored copy, watch exactly the matching assertion fail, restore.

Paste both the failing and the passing output. "The tests pass" is not proof that they can fail.