ADR-0032 — SQA contract doc ≠ consumer-driven contract

ADRsUpdated 2026-05-11 00:00 EDT5 min readEdit on GitHub ↗

ADR-0032 — SQA contract doc ≠ consumer-driven contract #

Status: Proposed
Date: 2026-05-11
Deciders: Natan
Source: PRD-14 ratification (Convergence E of the

2026-05-09 master synthesis ↗ §2.5). Disambiguates ADR-0026's Newman citation. The dossier on Newman's Building Microservices (2nd ed.) §3.1 surfaces that ADR-0026 cites Newman for two distinct ideas — the drive→observe→verify phrasing (which is test-pyramid lineage, not Newman) and CDCs (which Newman owns, but which SQA contract docs are not).

Context #

ADR-0026 ends with a See-Also pointer to Building Microservices Ch 10. A reader who knows Newman well will read that pointer and infer SQA contract documents (e.g. docs/contracts/snappy/domain-activation.md) are consumer- driven contracts (CDCs) in Newman's sense. They are not, and the difference matters for who writes them, who owns them, when they run, and what they fail on.

Newman, Building Microservices (2nd ed., 2021) Ch 9 lines 7100–7160 defines a CDC as a contract the consumer publishes that the producer is bound to honour — the canonical implementation is Pact (Pact Broker, multi-consumer model). The producer runs all its consumers' CDCs in its own CI; a CDC fail means "you broke a downstream consumer." The contract artifact encodes call-response shapes: a request and the expected response.

SQA contract docs are different on every one of those axes:

Axis	Newman CDC	SQA contract doc
Owner	Consumer (each consumer writes its own)	External observer (SQA, one per workflow)
Cardinality	N consumers → N CDCs per producer	One contract per workflow
Encodes	Call-response shapes	Side-effects of running the workflow
Runs where	Producer CI	SQA runner (cron + on-demand)
Lives where	Pact Broker (shared registry)	The SUT's repo (alongside the workflow it describes)
What "fail" means	Producer broke a downstream consumer	The workflow's documented side-effect did not land
Cycle	Pre-merge gate	Post-deploy observation

Newman also gives SQA the drive → observe → verify phrasing ADR-0026 cites, but Newman's Building Microservices doesn't coin it — the phrase belongs to the test-pyramid lineage (Cohn, Succeeding with Agile 2009; Vocke, The Practical Test Pyramid). Newman uses it as received vocabulary. ADR-0026's phrasing-citation should be softened, and the CDC ambiguity disambiguated.

Decision #

SQA contract documents are observer-owned semantic contracts. They are explicitly not Newman-style consumer-driven contracts. Three rules follow:

Vocabulary. When SQA prose mentions "contract," it means

the doc-anchored side-effect spec in docs/contracts/. When it means a Pact-style CDC, it must say "consumer-driven contract" or "CDC" in full. The bare word "contract" never means CDC inside this codebase.

Ownership. SQA contract docs are written by the observer

(SQA), reviewed by the SUT team, and committed alongside the workflow's source. They do not live in a multi-consumer registry. There is no Pact Broker.

Citation hygiene. ADRs and PRDs that lean on Newman cite

the specific chapter (e.g. "Newman Ch 10, in-production testing"), not Newman-the-book as proxy for the drive→observe→verify phrasing. The phrasing predates Newman.

A small carve-out: ADR-0026's See-Also pointer to Newman Ch 10 stays — Newman's "in-production testing" + "synthetic transactions" sections (Ch 10 lines 7220–7237) are the closest prior art SQA inherits from, and the pointer remains useful. But ADR-0026 gains a See-Also pointer to this ADR (per PRD-14 §14.1.3) so the reader who chases the Newman citation lands on the disambiguation.

Consequences #

Architectural #

The glossary's contract / scenario / segment

vocabulary stays unchanged; this ADR pins the prose convention around it, not the words themselves.

The contract-doc template (docs/contracts/snappy/*.md)

inherits a one-sentence opening disambiguation: "This is an observer-owned semantic contract, not a consumer-driven contract — see ADR-0032." The disambiguation can live in the template header rather than being repeated per-claim.

Behavioural #

A reader who picks up the codebase fresh from a Pact background

no longer infers the wrong cycle (pre-merge gate) from the word "contract." This was a real source of confusion in the dossier-review pass that produced PRD-14.

ADRs and PRDs gain a small citation-hygiene burden: Newman gets

cited by chapter, not as wallpaper.

Falsifiability #

If a future ADR proposes adding a Pact Broker or multi-consumer

CDC registry to SQA, this ADR has failed — that's a different surface that requires its own ADR superseding this one.

If a contract doc in docs/contracts/ is written by the SUT

team without observer review, this ADR has failed — the observer-owned property is the load-bearing distinction.

If an SQA scenario file starts asserting call-response shapes

(e.g., "this endpoint returns this exact JSON" without any side-effect claim), this ADR has failed — that's a CDC, not an SQA contract claim.