novox/hq
3
0
Fork 0
Code Issues 4 Pull Requests 5 Releases Wiki Activity

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

Browse Source 
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:
jschoubben
2026-09-16 00:07:26 +02:00
parent a40595fa08
commit 17c2e061df
2 changed files with 22 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files
03-DESIGN/01-to-be/19-the-module-protocol.md
+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
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
implementation writes four headers; the TypeScript one declares six. This is the drift ADR 0074
exists about, and the first thing conformance will fail on.
Go emits all five required headers; the SDK requires exactly those. `x-causation-id` and `x-schema`
are **optional** — the SDK sets them when a handler has a causation or a schema, and reads them
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
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
**the module**; in Go, `Consumer` is **the node** and the module is `From`. One word, two meanings,
in two halves of one mesh. At least one is wrong and the specification above says which.
This looked like the sharpest disagreement and was not one. The live wire is the contributions file
— `as`, `secret`, `node`, `at`, `values` — and it is the same on both sides. The types that
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.
---