Skip to content

Columna 0.13.1 - the reconciliation delta reports at the resolution its tolerance warrants

Choose a tag to compare

@datumwise datumwise released this 27 Jul 01:49

A recorded exhibit was changing by itself. This fixes it at the true cause and adds the structural guard so the class cannot recur silently.

The defect

The /case alloc reconciliation badge rendered delta 0.0000 on most runs and -0.0000 on ~20% — same package, same input, same machine. It reached a byte-preserved artifact, so an exhibit that may change only by re-recording was in fact changing on a coin flip, every deploy. The committed value was not correct; it was merely the side the coin had landed on in CI.

Misdiagnosed twice, then measured

Both first diagnoses said "signed zero." Both were wrong, and the fix derived from them provably does not work:

raw_delta= 4.656612873077393e-10   is_exactly_zero=False   formats=0.0000
raw_delta=-4.656612873077393e-10   is_exactly_zero=False   formats=-0.0000
raw_delta= 0.0                     is_exactly_zero=True    formats=0.0000

The value alternates between exactly 0.0 and ±2⁻³¹ — a sub-epsilon residue that flips sign. x if x != 0 else 0.0 therefore passes it through untouched. Implemented and measured: the flap survived at an unchanged rate (5 × -0.0000 of 20).

The epistemic failure is the point, and it ran in both directions: the builder reported a symptom name rather than a measured value, and the desk ruled on the report. Neither had looked at the number. Readings do not verify each other — and a symptom named in a report is still a reading.

The fix — at the cause, at the point of computation

def canonical_delta(delta: float, tol: float) -> float:
    return 0.0 if abs(delta) <= tol else delta

abs(delta) <= tol is exactly the condition under which the engine has already ruled status: "reconciles".

The doctrine: a value below the system's declared tolerance is noise, not a finding — reporting it as a finding is false precision. Below its own declared resolution of meaning, the residual bits are non-reproducible summation noise (~2e-16 relative to a $2.2M total). Serving them as data is false precision, which is a species of confident wrong number — small, but the masthead does not say "no large wrong numbers."

Canonicalized where the delta is computed, not at the formatting boundary: the structured reconciliation.delta must be canonical too, or a consumer reading the number gets the artifact even when the prose does not.

No laundering — the load-bearing half: a delta OUTSIDE tolerance keeps its exact value and its sign, asserted by test. The guard must never quietly absorb a real shortfall.

Root cause, and what was rejected as a fix

Float summation order. Pinning threads was tried and rejected: it did not remove the flap and in fact inverted its distribution (9 × -0.0000 of 15). That is evidence of the cause — and its own argument against suppressing a symptom while leaving the class alive. We do not pin threading to hide a coin flip.

The structural guard

apps/website/scripts/check_generator_determinism.py — every committed-output generator runs twice and must be byte-identical. Non-determinism in a recorded artifact becomes a loud, named build failure instead of a 20%-of-deploys surprise. Wired into the deploy workflow. It fails closed and names its reason (proverb 5; AW-6's lesson) — never a sentinel, never a bare traceback.

Verified: STABLE gen_case.py (26312 bytes, 4 runs byte-identical).

Wire change, named not silent

Within-tolerance reconciliation deltas now canonicalize to 0.0, in both the prose and the structured field. In-tree consumers only. No contract_version bump — the envelope and the four moods are untouched. Named here per the standing rule: removal-and-change is always named, never silent.

Release

core 0.13.1 / 0.13.1-core · umbrella 0.13.1 pinning columna-core>=0.13.1 · columna-server 0.8.0 unchanged (its >=0.13.0 floor already admits the patch) · deploy pin moved to the 0.13.1 triad, publish-first-as-installable on the verbatim-pin gate.

Provenance — the honest history of a defect

Flagged at the #85 preview → ordered for the 0.12.1 cargonever landed → resurfaced as a flap during the 0.13.0 confirmation re-record → misdiagnosed twice, once by the builder and once by the desk → measured → fixed at the true cause.

Verified: 20/20 runs now 0.0000; suite green.