2026-09-16 21:25:51 +00:00
3 changed files with 62 additions and 2 deletions
@@ -1,6 +1,6 @@
 ---
 topic: the tiers
-status: proposed
+status: accepted
 date: 2026-09-15
 deciders: jochen
 reconstructed: false
@@ -106,7 +106,7 @@ python3 00-META/checks/index.py            fail if stale
 - **0071** — [Genesis clones from a mesh, and checks what it got](0071-where-genesis-gets-its-source.md)
 - **0072** — [Two graphs, and a build chain that orders itself](0072-two-graphs-and-the-build-chain.md)
 - **0073** — [The installer carries a builder, and the registry stays where it is](0073-the-installer-carries-a-builder.md)
- **0074** — [The mesh defines a module protocol; an SDK is an implementation of it](0074-the-wire-is-specified-not-the-types.md)  *(proposed)*
+- **0074** — [The mesh defines a module protocol; an SDK is an implementation of it](0074-the-wire-is-specified-not-the-types.md)

 ### What runs on them, and how it gets there

@@ -0,0 +1,60 @@
+---
+status: open
+opened: 2026-09-15
+located-in: []
+fixed-by:
+amended-design:
+---
+
+# 053 — The SDK is pinned twice, and the two disagree
+
+## Symptom
+
+The module that carries the tool runtime names the SDK two ways, and they are not the same thing:
+
+```
+package.json       @novox/mesh-sdk  ->  git+https://<the forge>/mesh-sdk.git#<a commit>
+package-lock.json  @novox/mesh-sdk  ->  ../mesh-sdk
+```
+
+The manifest names a commit in a repository any machine can reach. The lock names a **sibling
+directory**, which exists on the workstation the lock was generated on and nowhere else.
+
+It builds anyway, because the recipe runs `npm install` — which tolerates a lock that disagrees
+with its manifest and re-resolves from the manifest. It is the one command that hides this.
+
+## Why this matters
+
+**A lock file exists to make a build reproducible, and this one describes one machine.** `npm ci` —
+the command for exactly the case a lock is for — fails here, or worse, succeeds against whatever
+happens to be at that path.
+
+**It is the first thing a fresh mesh builds.** The toolchain image carries the SDK, and everything
+with code of its own is compiled inside it. A dependency resolved differently on the build machine
+than on a workstation is a difference in every module the mesh will ever build, arriving as a
+compile error or a runtime mismatch far from here.
+
+**And it is about to be copied.** Each language's toolchain will carry that language's SDK the same
+way ([ADR 0074](../../02-DECISIONS/0074-the-wire-is-specified-not-the-types.md)). Whatever this
+repository does, the Rust and Python ones will do, so the shape is worth getting right before there
+are four of them.
+
+## Open questions
+
+- **Is a git dependency at a pinned commit the intended mechanism?** It works, needs no package
+  registry, and reuses the forge a mesh already depends on to exist at all
+  ([ADR 0071](../../02-DECISIONS/0071-where-genesis-gets-its-source.md)). If so, the lock should say
+  so and the sibling path should never have been committed.
+- **Or should the SDK be a published package?** The catalogue holds a private registry module, and a
+  published package is how the rest of the world does this — at the cost of a mesh needing that
+  registry up before it can build anything, which is a bootstrap problem where there is currently
+  none.
+- **What generates the lock, and on what?** A lock produced on a workstation with sibling checkouts
+  will keep saying this. A lock produced the way the image builds would not.
+
+## How this would be checked
+
+| Rule | Checked by |
+|---|---|
+| A build does not depend on the machine it runs on | The toolchain image builds with `npm ci` rather than `npm install`, which refuses a lock that disagrees with its manifest. |
+| The SDK a module compiles against is the one named | The commit baked into the toolchain image is compared with the one the manifest pins. |