Mind · Reasoning
SpecBinding
Bind an implementation to an external specification by a pinned version, a two-way map and a ledger of deviations
Definition
Mechanism
An implementation, such as code, a procedure or a set of controls, is bound to an external Spec, such as a paper, a standard, a regulation or a design document, in four ways. One document is named authoritative and its exact version pinned, such as a commit, an edition or a dated consolidated text. Every restatement, summary, comment or test is marked as derived, never as a second source. A two-way map links each rule of the specification to the part of the implementation that carries it out, and links each consequential part to the rule it serves or to a recorded implementation choice; the binding states its criterion for what is consequential. A deviation ledger records rules not implemented, choices the specification leaves open (precision, rounding, ordering, or how a vague clause is read) and places where the implementation knowingly differs. When the pin or a mapped part changes, the map is checked again before the change is accepted, and a value whose meaning changes is swept as in MeaningChangeSweep. Verification against the binding establishes conformance to the pinned version only, not that the specification is right.
Invariants
- Exactly one source is authoritative for each rule, and its version is pinned.
- Every specification rule maps to part of the implementation, to a test, or to a ledger entry stating why it does not.
- Every part of the implementation that the binding's stated criterion marks as consequential maps to a rule or to a recorded implementation choice.
- A change to the pin or to a mapped part of the implementation triggers the map check before the change is accepted.
Risks
Failure modes
Floating pin
the implementation cites the specification without a version, so a later edit silently changes what it claims to implement.
Second source
a summary, a lighter edition or a test suite drifts and is treated as authoritative.
One-way map
rules map to the implementation, but consequential parts of it map to nothing, so unspecified behaviour stays hidden.
Ledger rot
a recorded deviation, comment or test keeps describing an implementation or meaning that has since changed.
Relationships
Builds on
References
When a value's meaning changes, find and recheck every reader of the old meaning
Infrastructure
Rigorous requirement definition
Confirming alignment with truth or spec
Nothing in this library builds on this pattern yet.
Reference