2026-09-23 23:38:40 +00:00
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?