Phase 1 was mostly a phantom: correct doc 19 and the WBS

The protocol spec claimed the envelope and grant drifted across implementations.
Inspection showed the wire agrees — envelope required headers match, the two
optional ones are legitimately optional, and the grant wire (the contributions
file) is identical on both sides. The disagreement was in dead types, now removed.

So phase 1's 'make them agree' work is done by deletion and correction. What
remains is a conformance fixture as prevention — pinning the envelope and the
contributions file so a future change that breaks agreement fails a test — and a
full per-capability suite is deferred until a third language actually needs it.

Claude-Session: https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx
This commit is contained in:
2026-09-16 00:07:26 +02:00
parent a40595fa08
commit 17c2e061df
2 changed files with 22 additions and 16 deletions
+13 -8
View File
@@ -115,11 +115,13 @@ breaking change for everybody.
At-least-once. **Deduplication is on `x-event-id`**, which only the emitter can produce — a At-least-once. **Deduplication is on `x-event-id`**, which only the emitter can produce — a
consumer cannot tell a redelivery from a second event any other way. consumer cannot tell a redelivery from a second event any other way.
### Not yet true ### What is true, checked (2026-09-16)
`x-causation-id` and `x-schema` are specified above and **emitted by nothing**. The Go Go emits all five required headers; the SDK requires exactly those. `x-causation-id` and `x-schema`
implementation writes four headers; the TypeScript one declares six. This is the drift ADR 0074 are **optional** — the SDK sets them when a handler has a causation or a schema, and reads them
exists about, and the first thing conformance will fail on. back; a bare event carrying neither is correct. So the envelope agrees across the two
implementations. `x-schema` is available for versioning a body's shape and is set by whoever has a
version to declare.
--- ---
@@ -158,11 +160,14 @@ A provider ships the provisioner that creates instances of what it offers
same provision, so a grant addressed to a node alone does not name a consumer, and withdrawing one same provision, so a grant addressed to a node alone does not name a consumer, and withdrawing one
would take another's away. would take another's away.
### Not yet true, and it is the sharpest disagreement ### Checked, and it agrees (2026-09-16)
The two existing implementations do not agree on this shape. In TypeScript a grant's `consumer` is This looked like the sharpest disagreement and was not one. The live wire is the contributions file
**the module**; in Go, `Consumer` is **the node** and the module is `From`. One word, two meanings, — `as`, `secret`, `node`, `at`, `values` — and it is the same on both sides. The types that
in two halves of one mesh. At least one is wrong and the specification above says which. disagreed (`Grant`, `Interface` in the SDK's `contracts`) were dead: exported, imported by nothing,
describing fields the wire does not carry. They have been removed. The lesson kept: a type beside
the wire that has drifted from it is worse than none, which is why the wire is specified and
implementations are checked against it rather than trusted to still match a hand-kept shape.
--- ---
+9 -8
View File
@@ -32,20 +32,21 @@ The installer's own regressions (stale carried builder, a diagnostic on the pars
fixed and committed. Whether it reaches a full green run is answered by the final lab run below, fixed and committed. Whether it reaches a full green run is answered by the final lab run below,
after the phases that change its build path are in — not before. after the phases that change its build path are in — not before.
## Phase 1 — the protocol is one thing, and correct ## Phase 1 — the protocol is one thing, and correct *(mostly done: the drift was dead types)*
**Why here.** The Go control plane and the TypeScript SDK disagree about what a grant carries **Why here.** The Go control plane and the TypeScript SDK disagree about what a grant carries
(`consumer` is the module in one, the node in the other). That is exercised by the installer's own (`consumer` is the module in one, the node in the other). That is exercised by the installer's own
provisioning — the catalogue's database — so it belongs before more is built on it. provisioning — the catalogue's database — so it belongs before more is built on it.
- [ ] 1.1 extract the wire contracts to one specification the two implementations both conform to - [x] 1.1 the drift was not live — inspection showed the wire agrees (contributions file; envelope
- [ ] 1.2 make Go and TypeScript agree — one meaning for `consumer`, the envelope's six headers required headers). The dead types that disagreed are removed, ADR 0074 and doc 19 corrected
emitted by both - [ ] 1.2 a conformance fixture for the two live cross-language contracts — the event envelope and
- [ ] 1.3 an executable conformance suite, per capability, both existing SDKs made to pass it the contributions file — checked in both suites, as **prevention** rather than repair
- [ ] 1.4 the `x-schema` header written, so a body's shape can version (ADR 0074) - [ ] 1.3 (deferred) a full per-capability suite when a third language is actually added; not
needed to keep two honest
**Done when.** A fixture emitted by one implementation is read identically by the other, checked in **Done when.** A fixture pins the envelope and the contributions file, and a change to either side
both test suites. that breaks agreement fails a test rather than a mesh.
## Phase 2 — the private package registry, and the SDK in it ## Phase 2 — the private package registry, and the SDK in it