From fb9d3035d4601cfb0c1cd0b734ca360a519b834e Mon Sep 17 00:00:00 2001 From: jochen Date: Tue, 22 Sep 2026 22:26:14 +0200 Subject: [PATCH] Issue 091: a module definition carries a machine port, measured across the catalogue --- .../00-report.md | 51 +++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 04-ISSUES/091-a-module-definition-carries-a-machine-port/00-report.md diff --git a/04-ISSUES/091-a-module-definition-carries-a-machine-port/00-report.md b/04-ISSUES/091-a-module-definition-carries-a-machine-port/00-report.md new file mode 100644 index 0000000..6cb2830 --- /dev/null +++ b/04-ISSUES/091-a-module-definition-carries-a-machine-port/00-report.md @@ -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?