Storing the SHA-256 Envelope: A Data-Model Pattern

The response envelope is only an audit trail if you keep it. This is the boring, load-bearing part: what to store, in which columns, and when to re-verify.

Every Worthune response arrives with its own provenance: the spec version that produced it, the inputs echoed back, the constants consumed, and a SHA-256 record over the answer. Products that show users a number they may act on — a payoff date, a break-even, a contribution amount — should store that provenance next to wherever they store the number. The pattern is five columns and two decisions, and it is the difference between "our tool said something like that" and producing the exact answer, proven, years later.

The columns

Store the JSON exactly as returned — the hash is computed over canonical key-sorted serialization of those fields, and the response states the recipe, so preserving bytes (or at least values and types) is what keeps the seal checkable. The sentinels, assumptions, and facts arrays are worth storing too, in one auxiliary JSON column: they cost little and answer the questions auditors actually ask, like which constant vintage the answer used.

When to write it

Write the envelope at the moment the answer crosses the trust boundary — when it is shown to a user, written into a document, or consumed by a downstream decision. Ephemeral interactions do not need envelopes: a user dragging a slider through thirty scenarios generates thirty answers and zero commitments; storing all thirty is noise. Store the one they acted on. The rule that holds up: if the answer would matter in a dispute, it gets a row.

Re-verification: when and why

The stored hash earns its keep at three moments. On write, verify once — recompute the SHA-256 from the four fields and compare to the stored value — to catch serialization bugs on your side while they are cheap. On dispute, verify and replay: recompute the hash to prove the stored answer is untampered, then re-POST the stored inputs. If the current spec version matches the stored one, the outputs will match byte-for-byte; if the version has moved on, the changelog explains the delta between what the user saw then and what the model says now — which is itself the answer to most disputes. On migration, verify the whole table after any ETL that touched the JSON columns, because a hash that stops matching after a database migration is telling you your migration changed evidence.

• ✓Write on trust-boundary events, not on every keystroke.
• ✓Verify once at write time — serialization bugs die young.
• ✓Keep user identity outside the envelope.
• ✓After any migration touching these columns, re-verify the table.
• ✓Retention follows your records schedule — the envelope is a business record about a computation, not user PII.

Retention and the records conversation

How long to keep envelopes is a records-retention question, not a technical one, and the envelope makes the conversation easy: it is small (a few kilobytes), it contains no user identity by construction, and it is precisely the artifact a books-and-records regime wants — what was shown, when, computed how. Firms subject to communication-retention rules should slot envelope rows into the same schedule as the customer communication they supported. Everyone else can default to keeping them as long as the related account or document lives, plus their dispute window.

The pattern's quiet payoff

Six months after launch, someone — support, compliance, a partner, occasionally a regulator — asks what the tool told a specific user on a specific day and why. Products without envelopes reconstruct from logs, release history, and guesswork, and the reconstruction is an estimate. Products with envelopes run one SELECT and one hash check, and hand over the answer with its proof attached. The five columns cost an afternoon. The reconstruction they replace costs a week, arrives uncertain, and lands at the worst possible time.