Conformance contract example for stored Todo data

Article 2 companion · Illustrative example · Published October 9, 2026

The existing Todo package contains eleven obligations. These three adjacent obligations show how it distinguishes absent data, failed reads and failed writes. The obligation text below is copied from the source contract. This is an explanatory excerpt, not a replacement contract or a new executable package.

ID	Obligation
TD-07	Absent stored data yields an empty list, not an error.
TD-08	Stored data is version-checked and shape-validated before use; invalid, unreadable, or unsupported data yields a distinguishable read-failure result and the original stored bytes are not overwritten or cleared by the failed read.
TD-09	A failed write leaves the last successfully persisted state authoritative and the failure distinguishable to the caller; no previously persisted data is lost.

For TD-08, the contract's required evidence is:

Exactly four representative failures: unsupported version: 2; a non-object envelope; a version-1 envelope whose todos value is not an array; and an adapter read error. Each case asserts a read-failure result and unchanged original bytes. No additional malformed-shape variants are baseline requirements.

The integration interface supplies further detail. storage.load() returns null for absent data or a parsed envelope for stored data. The model constructor returns either a model or a distinguishable failure result. The check can inject storage and a clock, which makes the selected behavior directly observable.

An author translating intent into this contract must decide what happens when data cannot be read. Silently replacing it, preserving it for recovery and attempting a migration are different product policies. This package selects preservation and an error result for the named conditions. Evaluation can test that choice; a passing test cannot establish that it was the right product decision.

The required-evidence cell makes the selected coverage explicit. It also exposes the distance between broad language such as “shape-validated” and a finite set of representative inputs. A reviewer can inspect that boundary and request more coverage when warranted. New requirements or authoritative checks should enter through an approved revision rather than changing silently during a run.

Continue to the mapping from TD-08 to executable observations.