Engineering guide
Write an interface contract both sides can use
An interface control document is useful when it makes the agreement between participants explicit. A list of endpoints or function signatures is only the beginning of that agreement.
Describe the boundary and its participants
Take an order service publishing work to a fulfillment consumer. Identify which team or component owns each side, which participants are external, and which system promise the interaction serves. The contract should remain understandable without reading both implementations.
Illustrative contract. The producer publishes an order ID and payload revision. Delivery may repeat. The consumer records at most one accepted fulfillment for an order ID. A repeated ID with a different payload revision is rejected and surfaced for investigation.
This makes a crucial distinction: transport delivery can repeat while the business effect must not. A signature such as ProcessOrder(message) does not express that distinction.
Write the decisions that usually drift
| Surface | Question to resolve |
|---|---|
| Data | Which fields are required, bounded, versioned, or optional? |
| Timing | Which deadlines and ordering guarantees can callers rely on? |
| Failure | How are rejection, timeout, partial completion, and retries distinguished? |
| State | What happens after duplicate delivery, restart, or a stale message? |
| Authority | Who may change the contract and how do participants migrate? |
Keep assumptions separate from guarantees. “The queue never duplicates a message” is an environmental claim that needs justification; it cannot be added merely to simplify the consumer model.
Connect the contract to each side
In Proof, an integration requirement can describe the boundary while software requirements allocate participant responsibilities. Declare the internal components and any external parties accurately. Use direct integration evidence that exercises the real boundary, not only unrelated unit tests that happen to pass.
proof audit --check interface_coverage --verbose
proof audit --check cross_component_clean --verboseThese checks inspect declared interface structure and component allocation. They do not discover every production interaction or establish that both sides agree on the semantics.
Review the contract when implementation changes
A producer might start emitting a new payload revision while an old consumer remains deployed. Review compatibility and migration behavior as part of the change. Retain the relevant environment, versions, and results with the evidence.
proof audit --check interface_staleness_clean --format markdownContent drift can reopen an interface review. Refreshing its record should follow substantive assessment; a new fingerprint alone does not verify protocol compatibility. A generated document is a view of the recorded contract, not proof that the distributed system obeys it.
Continue from here
Exercise the real boundary. Review overlapping interface records.
Bring one producer-consumer interaction whose failure behavior is unclear. Bring a change to Proof.