Issue 091: a module definition carries a machine port, measured across the catalogue

2026-09-22 22:26:14 +02:00
parent dd81523eab
commit fb9d3035d4
1 changed files with 51 additions and 0 deletions
@@ -0,0 +1,51 @@
+---
+status: open
+opened: 2026-09-22
+located-in: []
+fixed-by:
+amended-design:
+---
+
+# 091 — A module definition carries a machine port
+
+## What was observed
+
+Measured across the catalogue, 2026-09-22, while planning the migration of a control-node:
+**14 of 46 modules with containers fix the machine side of a published port in the module
+definition**; 32 leave it to the node.
+
+Four kinds turned up, and only two of them are defensible:
+
+- **The foundation's own** — the store, the bus, the broker's management port, the registry. These
+  are rewritten at genesis and are now per-node settings
+  ([ADR 0100](../../02-DECISIONS/0100-a-node-in-use-is-adopted-before-it-is-converged.md)), so the
+  number in the manifest is a default, not a claim.
+- **Ports a protocol fixes** — device discovery and relay ports that clients find by number. The
+  machine has no freedom here, and the manifest is the right place to say so.
+- **A predecessor's host ports, copied in during conversion** — a site on one number, a document
+  editor on another, an object browser on a third. These are facts about one machine that were
+  written into a definition meant for any machine.
+- **A demonstration module** serving on a memorable number.
+
+## Why it matters beyond this instance
+
+The mesh's rule is that a module says what it *listens* on and the node decides what the machine
+publishes; that is what lets the same module run on two machines, and what lets a node adopted
+beside a predecessor move a port out of the way. A machine port in a definition is that rule
+broken quietly: it works until two nodes want the module, or until one node already has something
+on that number.
+
+It is not fatal today — a node's `ports` setting overrides the mapping's machine side — but the
+default is in the wrong place, and nothing says so when a module is written or converted.
+
+The conversion backlog is the moment this gets decided for the rest of the modules, so it is worth
+answering before the remaining ones are written.
+
+## Open questions
+
+- Should a module be refused when it fixes a machine port without saying why — with an explicit
+  "this protocol needs this number" — so the two defensible cases stay and the copied ones do not?
+- Is the right default that *every* published port is machine-assigned unless the module declares
+  the number is part of the protocol?
+- What should a converted module do with the predecessor's host port: drop it, or record it as the
+  node's setting on the machine being migrated, which is where it is actually true?