Two Teams Own Opposite Ends of an Interface: Freeze One Reviewable Contract Before Integration

ByLIU, ZHUOHUI

Resolve each disputed interface behavior in one controlled decision record, then give both teams the same versioned examples and acceptance observations. Two implementations can pass their own tests while disagreeing about timeout origins, invalid values or command completion. Integration should expose those disagreements before they become undocumented compatibility patches.

This article proposes an engineering coordination method for firmware, host software and supplier boundaries. It does not amend commercial agreements, assign legal responsibility or promise a delivery outcome. The example is fictional and no interface implementation or test was executed.

1. Identify who may decide each boundary

Name the producing implementation owner, consuming implementation owner, system requirement owner and authorized change decision-maker. One person may hold several roles, but the authority must be explicit.

NASA’s interface-management guidance, section 6.3, calls for defined responsibilities, controlled interface documentation and retained decisions and assumptions. Use that as engineering guidance; the project’s own approved process determines who can commit each party.

A coordinator can maintain the record without having authority to choose a new product behavior. If the teams disagree about who owns a requirement, escalate that question before either side treats a convenient implementation as the specification.

Two teams supply interpretations to one evidence-backed decision record, which produces an approved clause and shared fixtures before implementation and integration receipts.
Original cross-team interface review workflow. All team roles, timing values and fixtures are hypothetical; no interface tests or approvals occurred.

2. Capture disagreement as competing interpretations

For every disputed field or event, write both interpretations without immediately choosing a winner. Attach the document, version, example or observed behavior supporting each one.

Boundary Producer interpretation Consumer interpretation Decision required
Response deadline Starts at physical transmission Starts at client submission Reference event and queue-time treatment
Unavailable measurement Last value remains in the field Every value is current Validity and freshness representation
Command acknowledgement Request accepted Action complete Exact completion boundary
Unknown optional field Consumer may ignore it Unknown content is rejected Version and extensibility rule

These are hypothetical disagreements, not protocol defaults. Do not infer the correct answer from which team’s implementation already shipped. Identify the controlling requirement and the consequences of each proposed resolution.

3. Turn the decision into observable terms

A usable interface clause names stimulus, preconditions, state transition, output, timing reference, limits and error behavior. Add units, ownership and version applicability where they affect the result.

Replace “respond quickly” with a specified event pair and an approved limit. Replace “acknowledged” with the exact state reached. Replace “compatible” with the accepted producer/consumer revisions and the behavior for an unsupported combination.

Where the current requirement is genuinely incomplete, record the question as unresolved. A temporary test assumption may unblock a prototype, but it must remain labeled provisional and cannot silently become a delivered promise.

4. Build one small shared fixture packet

Include a baseline statement, an example input, the expected semantic result, invalid/boundary cases and a list of deliberately untested properties. Use artificial identifiers and nonsecret values.

For the fictional deadline dispute, suppose submission occurs at 0 ms, transmission starts at 120 ms and the response completes at 200 ms. A 150 ms submission-based limit fails; a 150 ms transmission-based limit passes. The trace exposes the interpretation difference without requiring a complex device simulation.

{
  "case": "IC-17-queued-response",
  "contract_revision": "example-2",
  "submitted_ms": 0,
  "transmitted_ms": 120,
  "response_complete_ms": 200,
  "deadline_origin": "submission",
  "limit_ms": 150,
  "expected": "deadline_exceeded"
}

This JSON is an illustrative fixture, not executed code or a measured trace. Both teams should adapt the agreed case to their test seam and report their own actual results. The expected outcome becomes authoritative only through the project’s approved decision.

5. Require independent interpretation before joint integration

Ask each team to explain the expected result from the shared record before running a combined system. This catches semantic disagreement that a test harness could hide by sharing the same mistaken helper.

Then obtain implementation receipts naming the exact build, fixture revision, observed result and remaining deviations. A passing producer-side serializer test and a passing consumer-side parser test still leave queueing, transport and timing integration to be checked.

NASA’s product-integration guidance, section 5.2, links integration to interface requirements and a prepared environment. Do not substitute separate component demonstrations for the specific integrated observation the contract requires.

6. Freeze the contract without freezing discovery

Assign an immutable baseline identifier and retain the disputed alternatives, chosen interpretation, rationale and approvals. Store examples alongside the clause they illustrate so later edits cannot change one without review of the other.

A new incompatibility should create a change proposal against that baseline. Classify whether the proposal corrects an implementation, clarifies genuinely equivalent wording or changes externally visible behavior. These categories require different evidence and may require different authority.

NASA’s configuration-management discussion in section 6.5 emphasizes evaluated, approved and verified changes. The practical adaptation here is to obtain impact statements from both endpoints before activating a revised interface.

7. Close disagreements with a reviewable outcome

Status Required record
Resolved, implementation pending Approved meaning and named changes on each side
Implemented, integration pending Build identities and component evidence
Integrated for the agreed scope Shared fixture results and unresolved exclusions
Unresolved Decision owner, blocking assumption and next evidence needed

Do not close a disagreement merely because one side stopped raising it. Nor should a successful happy-path demo erase an unresolved timeout or invalid-data rule.

The final packet should let a new engineer identify the controlling clause, understand why it was chosen, run the corresponding approved examples and see which implementation versions support it. That is a practical interface handover, without inventing commitments for either team or promising that every future extension will remain compatible.

Similar Posts