The conformance suite · dive 03

A minor appends, a major rewrites

The set grows by adding clauses, never by changing one — that single rule is the line between a safe minor and a wire break.

A conformance set is only useful if it can grow as the bus gains surface. The growth has a law: a new clause is added additively. Prior scenarios stay byte-frozen and git-verified; the new one is probe-registered in run order; the count is re-pinned. Adding a clause is a protocol minor — a prior port still conforms, because it satisfies a subset. Changing an existing clause's verdict is a major — the wire said something different, and every port that passed the old set now fails. The set is that line.

The three rules Minor vs major A minor, illustrated The polyglot contract Pattern & implementation References

A change · minor or major

The three rules

The growth has a law, and the law is three rules — every one holds each time the set grows:

1. Prior scenarios stay byte-frozen. An existing clause's contract and its apply_scenario body do not change — git verifies it byte-for-byte against HEAD. A passing port stays passing.

2. The new scenario is probe-registered. It is appended to scenarios/0 in run order with its own apply_scenario clause, and asserts one new externally visible verdict on a live server.

3. The count is re-pinned. The live total n is re-pinned in both pinning tests — the {:ok, n} run test and the @run_order scenarios test — so the set's size is asserted, not assumed.

Because the page never prints a hard count, none of this dates the course: the shape is fixed (names + contracts in run order → run on sub-queues → {:ok, n}), and the size is the bus's live total.

Minor vs major — the version meaning

Additive registration is a protocol minor: a new clause adds a promise without changing an existing one, so a prior port still conforms — it satisfies a subset. Changing an existing clause's verdict — the wire saying something different than it said before — is a major: it breaks every port that passed the old set. The conformance set is exactly the line between the two. A minor appends; a major rewrites. Pick the two changes in the figure above to see which a prior port survives.

This is the same rule the bus's wire version follows: additive registration is a wire minor; a wire break is a major. The conformance set encodes the rule as runnable scenarios — you cannot ship a major by accident, because every prior clause is byte-frozen and a changed verdict fails the set loudly.

A minor, illustrated

Appending a clause leaves the prior set untouched and re-pins the count. The shape of an additive minor — the new clause is the last entry, every prior clause byte-identical to HEAD:

# echo_mq — EchoMQ.Conformance
# An additive MINOR: the new clause is APPENDED in run order; every prior clause
# is byte-identical to HEAD (git-verified). The run total n grows by one and is
# re-pinned in both pinning tests. A prior port still conforms — it satisfies a subset.
def scenarios do
  [
    fence:            "the version fence is claimed before any work …",
    # … every prior clause unchanged, byte-for-byte …
    stream_retention: "retention as policy: trim/4 bounds a stream to a DECLARED window …",
    # ── the new clause, appended last, probe-registered ──
    stream_time_travel: "time-travel as a mint-time window read: a CLOSED [t0,t1] read EQUALS the id-filtered truth"
  ]
end

A wire-break major, by contrast, would change an existing line's verdict — e.g. claim mints token 0 instead of 1. Every port that passed the old claim now fails. That is the diff the additive-minor law forbids on the same wire version:

# A MAJOR (forbidden as an in-place change) — an EXISTING clause's verdict moves.
# Every port that passed the old `claim` now fails; this is a wire break, not a minor.
    claim: "claim mints token 0, returns the payload, and moves the row to active"   # was: token 1

The count grows by minor · a major flagged

Each append raises the live count by one and the set stays green; a changed verdict turns it red. The set's size is allowed to grow, and its prior verdicts are not allowed to move.

The polyglot contract

The protocol lives below the language line — the keyspace plus the verbs, not the Elixir. A new runtime is conformant precisely when it drives the same server to the same verdicts. The set is therefore the contract that lets the bus be polyglot: the harness ports by translation, because each clause is wire-level. Add a runtime, and you have not added trust — you have added a thing that must pass the same set. The course teaches one canonical implementation, in Elixir; a port in any language is conformant by exactly this measure.

Pattern & implementation

the pattern (Redis Patterns Applied)

A production protocol evolves by adding capability without breaking the clients already running against it — backward-compatible change. Production Operations teaches running a tier as it grows.

the implementation (echo_mq)

The conformance set encodes that rule — append a clause (a minor, prior set byte-frozen), never rewrite one (a major, the wire broke) — with the count re-pinned each time, so a major cannot ship by accident.

The pattern is backward-compatible growth; the set makes it mechanical: a minor adds a clause, a major fails the set, and the line between them is the contract itself.

Recap — grow the set, hold the wire

The set grows by additive minor: prior scenarios byte-frozen and git-verified, each new one probe-registered in run order, the count re-pinned in both pinning tests. A minor appends a clause and a prior port still conforms; a major changes an existing verdict and breaks every passing port. The conformance set is that line, and the contract that lets the protocol live below the language line — a new runtime is conformant iff it passes the same set. That closes the module: the contract is run, the run answers one verdict, and the set grows without ever breaking the wire.

Back to the module: The conformance suite — and on through the Proof pillar to telemetry and the read plane.

References

Where the additive-minor law and the polyglot contract are grounded.

Sources

Beck — Test-Driven Development — the scenario set as the executable contract that grows.
Valkey — ZCARD — a read whose verdict a clause pins.
Valkey — Cluster specification — the wire the conformance set is the contract for.
The llms.txt convention — a wire-level convention any runtime can read, the polyglot idea applied to docs.

Related in this course

The conformance suite — the module this dive belongs to.
Run & the verdict — where the count n is returned.
The Protocol — the wire the set is the contract for.
Production Operations — running the tier as it grows.