A network-checker module: dial what the mesh claims, from where the callers are

The mesh asserts three things are callable (ADR 0144) — what runs on the same
machine, another machine's service exposed to the private network, and another
machine's service exposed publicly — and has never checked any of them. The first
was broken for eleven hours while the mesh reported every machine healthy.

This runs on every machine, on the cadence the mesh already has, in its own
container: the same position every other module calls from. Not the host and not
the control plane, both of which reach these addresses by paths no ordinary caller
uses and would have passed throughout that outage.

**Its probe is its own endpoint, and that is the point.** Declared reachable over
the private network like any other service, so it is admitted by exactly the rule
that governs every internally-exposed service and fails when that rule is wrong.
The tempting target is a service every machine has, and those are the ones never
closed — ssh above all — which would have passed while the thing that actually
broke was a service exposed to the private network.

It resolves before it dials and says which failed, because a name that does not
resolve and a port that does not answer have different owners. One failure is not
a fault: a machine rebooting is ordinary, so a path is broken after consecutive
runs and the count travels with the result. It reports and repairs nothing.

novox/hq ADR 0145. Eight tests; the consecutive-failure logic proved by reverting
it once. Not yet registered or assigned.

modules/baserow/module.json

@@ -14,7 +14,7 @@
     },
     "route": {
       "label": "baserow",
-      "port": 80
+      "endpoint": "web"
     }
   },
   "binds": {
@@ -30,6 +30,7 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 80,
       "protocol": "tcp",
       "from": "mesh",

modules/bazarr/module.json

@@ -13,6 +13,7 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 6767,
       "protocol": "tcp",
       "from": "mesh",
@@ -110,7 +111,7 @@
   "contributes": {
     "route": {
       "label": "subs",
-      "port": 6767
+      "endpoint": "web"
     }
   },
   "binds": {

modules/bookshelf/module.json

@@ -15,6 +15,7 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 8787,
       "protocol": "tcp",
       "from": "mesh",
@@ -87,7 +88,7 @@
   "contributes": {
     "route": {
       "label": "books",
-      "port": 8787
+      "endpoint": "web"
     }
   },
   "binds": {

modules/de-spiegel/module.json

@@ -11,7 +11,7 @@
   "contributes": {
     "route": {
       "label": "de-spiegel",
-      "port": 35621
+      "endpoint": "web"
     }
   },
   "binds": {
@@ -23,6 +23,7 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 35621,
       "protocol": "tcp",
       "from": "mesh",

modules/distribution/module.json

@@ -29,6 +29,7 @@
   },
   "listens": [
     {
+      "name": "registry",
       "port": 5000,
       "protocol": "tcp",
       "from": "mesh",

modules/dnsmasq/module.json

@@ -22,11 +22,20 @@
   ],
   "listens": [
     {
+      "name": "dns-udp",
       "port": 53,
       "protocol": "udp",
       "from": "mesh",
       "why": "every name for this machine and what it runs \u2014 the mesh's own answered here, the rest forwarded",
       "fixed": true
+    },
+    {
+      "name": "dns-tcp",
+      "port": 53,
+      "protocol": "tcp",
+      "from": "mesh",
+      "why": "the same names over tcp, which a resolver answers on as well and is asked for whenever an answer will not fit in a datagram. Declared because the daemon serves it: a declaration that covers one of the two protocols its own service listens on leaves the other closed while everything reports success",
+      "fixed": true
     }
   ],
   "resources": [

modules/fail2ban/module.json

@@ -33,7 +33,7 @@
       "type": "file",
       "path": "/etc/fail2ban/jail.local",
       "mode": "0644",
-      "content": "[INCLUDES]\n\nbefore = paths-arch.conf\n\n[DEFAULT]\n\n# Never act on the machine itself or on a tunnel peer: the mesh's private range is\n# ${machine:mesh-range}, named here rather than written as a value the module cannot\n# know (novox/hq ADR 0112). Without this, fail2ban could ban the mesh's own nodes.\nignoreip = 127.0.0.1/8 ::1 ${machine:mesh-range}\n\nbantime  = 10m\nfindtime = 10m\nmaxretry = 5\n\nbanaction = ufw\nbanaction_allports = iptables-allports\n\n[sshd]\nenabled = true\nport    = ssh\nlogpath = %(sshd_log)s\nbackend = %(sshd_backend)s\n"
+      "content": "[INCLUDES]\n\nbefore = paths-arch.conf\n\n[DEFAULT]\n\n# Never act on the machine itself or on a tunnel peer: the mesh's private range is\n# ${machine:mesh-range}, named here rather than written as a value the module cannot\n# know (novox/hq ADR 0112). Without this, fail2ban could ban the mesh's own nodes.\nignoreip = 127.0.0.1/8 ::1 ${machine:mesh-range}\n\nbantime  = 10m\nfindtime = 10m\nmaxretry = 5\n\n# Ban through iptables, not through a firewall front-end the machine may not have. ufw is\n# installed on two of this mesh's machines and absent on the other two, and fail2ban finds out\n# only at ban time: the service reports healthy, the jail counts the attempt, the ban command\n# exits 127, and nothing is blocked. Proven on 2026-09-28 -- 'ufw: command not found' on a\n# machine the mesh reported as protected.\n#\n# The action below is this module's own, already used by the recidive jail on every machine\n# here, and it bans in DOCKER-USER as well as INPUT, so a container's published port is\n# covered too.\nbanaction = iptables-allports-dualchain\nbanaction_allports = iptables-allports-dualchain\n\n[sshd]\nenabled = true\nport    = ssh\nlogpath = %(sshd_log)s\nbackend = %(sshd_backend)s\n"
     },
     {
       "id": "jail-sshd",
@@ -42,6 +42,14 @@
       "mode": "0644",
       "content": "[sshd]\nenabled = true\nport    = ssh\nlogpath = %(sshd_log)s\nbackend = %(sshd_backend)s\nmaxretry = 5\n"
     },
+    {
+      "id": "log",
+      "type": "file",
+      "path": "/var/log/fail2ban.log",
+      "mode": "0640",
+      "create-once": true,
+      "content": ""
+    },
     {
       "id": "jail-recidive",
       "type": "file",

modules/gitea/client.ts

@@ -9,6 +9,8 @@ import { ConfiguredToken, MintedToken, type TokenSource } from "./token.js";
 /** A repository, trimmed to what the mesh cares about. */
 export interface GiteaRepo {
   full_name: string;
+  /** The URL a build clones — what a module records as its source. */
+  clone_url?: string;
   name: string;
   owner: string;
   private: boolean;
@@ -34,6 +36,9 @@ export interface GiteaPull {
   title: string;
   state: string;
   merged: boolean;
+  /** The commit the merge produced — what a build of the base branch is made from. */
+  merge_commit_sha?: string;
+  merged_at?: string;
   user?: string;
   head?: string;
   base?: string;
@@ -116,9 +121,23 @@ export class GiteaClient {
 
   // ---- Repositories ----
 
+  /** Every repository this token can see, one page. `/user/repos` is only what the token's own
+   *  user owns — for the mesh's administrator that is nothing, which is how the forge watched an
+   *  empty list and announced no merge (2026-09-28). The search endpoint is the forge's whole view. */
   async listRepos(page = 1, limit = 20): Promise<GiteaRepo[]> {
-    const repos = await this.request<any[]>(`/user/repos?page=${page}&limit=${limit}`);
+    const found = await this.request<{ data?: any[] }>(`/repos/search?page=${page}&limit=${limit}`);
-    return (repos ?? []).map(GiteaClient.mapRepo);
+    return (found?.data ?? []).map(GiteaClient.mapRepo);
+  }
+
+  /** Every repository, all pages. */
+  async listAllRepos(): Promise<GiteaRepo[]> {
+    const all: GiteaRepo[] = [];
+    for (let page = 1; page < 100; page++) {
+      const batch = await this.listRepos(page, 50);
+      all.push(...batch);
+      if (batch.length < 50) break;
+    }
+    return all;
   }
 
   async createRepo(data: {
@@ -210,6 +229,17 @@ export class GiteaClient {
     return GiteaClient.mapPull(await this.request<any>(`/repos/${owner}/${repo}/pulls/${index}`));
   }
 
+  /** The files a merged pull request changed, as paths from the repository's root.
+   *
+   *  `limit` is what is asked for, and a merge that changed more says so rather than being read
+   *  page by page: what the mesh does with a partial list is treat the whole repository as changed,
+   *  so more pages would buy nothing. */
+  async listPullFiles(owner: string, repo: string, index: number, limit = 100): Promise<{ paths: string[]; truncated: boolean }> {
+    const files = await this.request<any[]>(`/repos/${owner}/${repo}/pulls/${index}/files?limit=${limit}`);
+    const paths = (files ?? []).map((f) => String(f?.filename ?? "")).filter((p) => p !== "");
+    return { paths, truncated: paths.length >= limit };
+  }
+
   async createPullRequest(
     owner: string,
     repo: string,
@@ -232,6 +262,7 @@ export class GiteaClient {
   private static mapRepo(r: any): GiteaRepo {
     return {
       full_name: r.full_name,
+      clone_url: r.clone_url ?? undefined,
       name: r.name,
       owner: r.owner?.login ?? r.full_name?.split("/")[0] ?? "unknown",
       private: Boolean(r.private),
@@ -259,6 +290,8 @@ export class GiteaClient {
       title: p.title,
       state: p.state,
       merged: Boolean(p.merged),
+      merge_commit_sha: p.merge_commit_sha ?? undefined,
+      merged_at: p.merged_at ?? undefined,
       user: p.user?.login,
       head: p.head?.ref,
       base: p.base?.ref,

modules/gitea/index.ts

@@ -31,7 +31,7 @@ try {
 const seen = new Set<string>();
 let primed = false;
 async function pollRepos(client: GiteaClient): Promise<void> {
-  const repos = await client.listRepos(1, 50);
+  const repos = await client.listAllRepos();
   for (const repo of repos) {
     if (!seen.has(repo.full_name)) {
       if (primed) {
@@ -49,6 +49,83 @@ async function pollRepos(client: GiteaClient): Promise<void> {
   primed = true;
 }
 
+// **A merge is announced whoever made it.** The merge tool below emits at the instant it acts; a
+// merge made in the forge's own pages or over its API would emit nothing, and the mesh would go on
+// believing every module current with its source (novox/hq 04-ISSUES/131). So merged pull requests
+// are watched the way repositories are: what the forge holds, asked for on a tick, announced once.
+// What has been announced is kept beside the module's state, so a restart does not announce the
+// whole history again — and the first tick on a machine with no record announces nothing, because
+// everything it sees then predates the watching.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const mergedRecord = process.env.MESH_GITEA_STATE_DIR ? join(process.env.MESH_GITEA_STATE_DIR, "merged-announced.json") : null;
+const announced = new Set<string>();
+let primedMerges = false;
+// since is the moment the watching began: a merge made before it is history, whatever page of the
+// forge's listing it surfaces on. Without it, an old merge past the first page — pushed into view
+// as newer pull requests were updated — was announced as if it had just happened, and the mesh
+// rebuilt everything built from that repository, once per old merge (2026-09-28).
+let since = "";
+if (mergedRecord && existsSync(mergedRecord)) {
+  try {
+    const kept = JSON.parse(readFileSync(mergedRecord, "utf8")) as string[] | { announced: string[]; since: string };
+    const list = Array.isArray(kept) ? kept : kept.announced;
+    for (const sha of list) announced.add(sha);
+    since = Array.isArray(kept) ? new Date().toISOString() : kept.since;
+    primedMerges = true;
+  } catch {
+    // An unreadable record is treated as no record: prime again rather than re-announce history.
+  }
+}
+function keepAnnounced(): void {
+  if (!mergedRecord) return;
+  mkdirSync(join(mergedRecord, ".."), { recursive: true });
+  const tmp = mergedRecord + ".tmp";
+  writeFileSync(tmp, JSON.stringify({ announced: [...announced].slice(-2000), since }));
+  renameSync(tmp, mergedRecord);
+}
+async function pollMerged(client: GiteaClient): Promise<void> {
+  const repos = await client.listAllRepos();
+  let changed = false;
+  for (const repo of repos) {
+    const pulls = await client.listPullRequests(repo.owner, repo.name, { state: "closed", sort: "recentupdate", limit: "20" });
+    for (const pull of pulls) {
+      if (!pull.merged || !pull.merge_commit_sha || announced.has(pull.merge_commit_sha)) continue;
+      // Announced only if merged since the watching began; recorded either way, so it is looked
+      // at once.
+      const fresh = !!pull.merged_at && !!since && pull.merged_at > since;
+      if (primedMerges && fresh) {
+        // What it changed, asked for only now: a module is rebuilt because a file inside its own
+        // directory moved, and without this every module built from a repository is rebuilt for a
+        // change to any of them (novox/hq 04-ISSUES/131).
+        const changed = await client.listPullFiles(repo.owner, repo.name, pull.number);
+        await emit("pull.merged", {
+          owner: repo.owner,
+          repo: repo.name,
+          number: pull.number,
+          title: pull.title,
+          head: pull.head,
+          base: pull.base,
+          merge_commit_sha: pull.merge_commit_sha,
+          merged_at: pull.merged_at,
+          clone_url: repo.clone_url,
+          html_url: pull.html_url,
+          paths: changed.paths,
+          paths_truncated: changed.truncated,
+        });
+        // Said, because a trigger that fires silently is indistinguishable from one that did not
+        // fire (novox/hq 04-ISSUES/131) — this line is how an operator knows the mesh was told.
+        console.log(`[gitea] announced merge ${repo.full_name}#${pull.number} (${pull.merge_commit_sha.slice(0, 8)}) into ${pull.base}`);
+      }
+      announced.add(pull.merge_commit_sha);
+      changed = true;
+    }
+  }
+  if (!primedMerges) since = new Date().toISOString();
+  if (!primedMerges || changed) keepAnnounced();
+  primedMerges = true;
+}
+
 if (gitea) {
   const client = gitea;
   // A poll that fails says so once, not once a minute: the same reason repeating (the forge not up
@@ -70,5 +147,6 @@ if (gitea) {
     run();
   };
   tick(() => pollRepos(client), 60_000);
-  console.log("[gitea] watching for new repositories");
+  tick(() => pollMerged(client), 30_000);
+  console.log("[gitea] watching for new repositories and merged pull requests");
 }

modules/gitea/module.json

@@ -13,7 +13,7 @@
     "route": {
       "web": {
         "label": "git",
-        "port": 3000
+        "endpoint": "web"
       },
       "internal-api-refused": {
         "label": "git",
@@ -44,12 +44,14 @@
   ],
   "listens": [
     {
+      "name": "web",
       "port": 3000,
       "protocol": "tcp",
       "from": "mesh",
       "why": "the forge, over http"
     },
     {
+      "name": "ssh",
       "port": 22,
       "protocol": "tcp",
       "from": "mesh",

modules/gitea/tools/index.ts

@@ -231,6 +231,11 @@ export function getGiteaTools(gitea: GiteaClient): ToolDefinition[] {
         // Read the PR first, so the merged event carries a title and branches, not just a number.
         const pull = await gitea.getPullRequest(owner, repo, number);
         await gitea.mergePullRequest(owner, repo, number, method, deleteBranch);
+        // Read it again: the merge commit only exists now, and it is what a build is made from.
+        const merged = await gitea.getPullRequest(owner, repo, number);
+        // And what it changed, so the mesh rebuilds the modules whose own files moved rather than
+        // every module built from the repository (novox/hq 04-ISSUES/131).
+        const changed = await gitea.listPullFiles(owner, repo, number);
         await emit("pull.merged", {
           owner,
           repo,
@@ -238,8 +243,12 @@ export function getGiteaTools(gitea: GiteaClient): ToolDefinition[] {
           title: pull.title,
           head: pull.head,
           base: pull.base,
+          merge_commit_sha: merged.merge_commit_sha,
+          merged_at: merged.merged_at,
           method,
           html_url: pull.html_url,
+          paths: changed.paths,
+          paths_truncated: changed.truncated,
         });
         return { merged: true, number, method, deleted_branch: deleteBranch };
       },

modules/grafana/module.json

@@ -13,6 +13,7 @@
   ],
   "listens": [
     {
+      "name": "web",
       "port": 3000,
       "protocol": "tcp",
       "from": "mesh",
@@ -96,7 +97,7 @@
   "contributes": {
     "route": {
       "label": "grafana",
-      "port": 3000
+      "endpoint": "web"
     }
   },
   "binds": {

modules/hello-web/module.json

@@ -11,7 +11,7 @@
   "contributes": {
     "route": {
       "label": "hello",
-      "port": 8080
+      "endpoint": "web"
     }
   },
   "binds": {
@@ -19,6 +19,7 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 8080,
       "protocol": "tcp",
       "from": "mesh",

modules/home-assistant/module.json

@@ -14,6 +14,7 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 8123,
       "protocol": "tcp",
       "from": "mesh",
@@ -85,7 +86,7 @@
   "contributes": {
     "route": {
       "label": "home-assistant",
-      "port": 8123
+      "endpoint": "web"
     }
   },
   "binds": {

modules/icecast/module.json

@@ -13,6 +13,7 @@
   },
   "listens": [
     {
+      "name": "stream",
       "port": 8000,
       "protocol": "tcp",
       "from": "mesh",

modules/influxdb/module.json

@@ -9,6 +9,7 @@
   },
   "listens": [
     {
+      "name": "api",
       "port": 8086,
       "protocol": "tcp",
       "from": "mesh",

modules/invoicing/module.json

@@ -17,11 +17,11 @@
     "route": {
       "site": {
         "label": "invoicing",
-        "port": 80
+        "endpoint": "web"
       },
       "api": {
         "label": "invoicing-api",
-        "port": 9000
+        "endpoint": "api"
       }
     }
   },
@@ -36,12 +36,14 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 80,
       "protocol": "tcp",
       "from": "mesh",
       "why": "the invoicing web frontend; a public name is a route grant later"
     },
     {
+      "name": "api",
       "port": 9000,
       "protocol": "tcp",
       "from": "mesh",

modules/jackett/module.json

@@ -6,6 +6,7 @@
   ],
   "listens": [
     {
+      "name": "web",
       "port": 9117,
       "protocol": "tcp",
       "from": "mesh",
@@ -82,7 +83,7 @@
   "contributes": {
     "route": {
       "label": "indexers",
-      "port": 9117
+      "endpoint": "web"
     }
   },
   "binds": {

modules/keycloak/module.json

@@ -11,7 +11,7 @@
     },
     "route": {
       "label": "keycloak",
-      "port": 8080
+      "endpoint": "web"
     }
   },
   "binds": {
@@ -34,6 +34,7 @@
   ],
   "listens": [
     {
+      "name": "web",
       "port": 8080,
       "protocol": "tcp",
       "from": "mesh",

modules/letta/module.json

@@ -24,6 +24,7 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 8283,
       "protocol": "tcp",
       "from": "mesh",

modules/lidarr/module.json

@@ -14,6 +14,7 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 8686,
       "protocol": "tcp",
       "from": "mesh",
@@ -86,7 +87,7 @@
   "contributes": {
     "route": {
       "label": "lidarr",
-      "port": 8686
+      "endpoint": "web"
     }
   },
   "binds": {

modules/mailu/module.json

@@ -16,27 +16,27 @@
     "route": {
       "web": {
         "label": "mail",
-        "port": 7443,
+        "endpoint": "web-tls",
         "scheme": "https",
         "insecure": true
       },
       "acme": {
         "label": "mail",
         "path": "/.well-known/acme-challenge",
-        "port": 7080,
+        "endpoint": "web",
         "priority": 100
       },
       "autoconfig": {
         "label": "autoconfig",
-        "port": 4243
+        "endpoint": "autoconfig"
       },
       "autodiscover": {
         "label": "autodiscover",
-        "port": 4243
+        "endpoint": "autoconfig"
       },
       "automx": {
         "label": "automx",
-        "port": 4243
+        "endpoint": "autoconfig"
       }
     }
   },
@@ -60,6 +60,7 @@
   ],
   "listens": [
     {
+      "name": "smtp",
       "port": 25,
       "protocol": "tcp",
       "from": "anywhere",
@@ -67,6 +68,7 @@
       "fixed": true
     },
     {
+      "name": "pop3",
       "port": 110,
       "protocol": "tcp",
       "from": "anywhere",
@@ -74,6 +76,7 @@
       "fixed": true
     },
     {
+      "name": "imap",
       "port": 143,
       "protocol": "tcp",
       "from": "anywhere",
@@ -81,6 +84,7 @@
       "fixed": true
     },
     {
+      "name": "smtps",
       "port": 465,
       "protocol": "tcp",
       "from": "anywhere",
@@ -88,6 +92,7 @@
       "fixed": true
     },
     {
+      "name": "submission",
       "port": 587,
       "protocol": "tcp",
       "from": "anywhere",
@@ -95,6 +100,7 @@
       "fixed": true
     },
     {
+      "name": "imaps",
       "port": 993,
       "protocol": "tcp",
       "from": "anywhere",
@@ -102,6 +108,7 @@
       "fixed": true
     },
     {
+      "name": "pop3s",
       "port": 995,
       "protocol": "tcp",
       "from": "anywhere",
@@ -109,18 +116,21 @@
       "fixed": true
     },
     {
+      "name": "web",
       "port": 7080,
       "protocol": "tcp",
       "from": "mesh",
       "why": "the web front over http; only the ACME HTTP-01 passthrough is routed here \u2014 everything else 301s to https and would loop a proxy"
     },
     {
+      "name": "web-tls",
       "port": 7443,
       "protocol": "tcp",
       "from": "mesh",
       "why": "the web front over its own TLS (admin, webmail, API); the public name mail.novox.be is a route grant reaching it here"
     },
     {
+      "name": "autoconfig",
       "port": 4243,
       "protocol": "tcp",
       "from": "mesh",

modules/marrytts/module.json

@@ -6,6 +6,7 @@
   ],
   "listens": [
     {
+      "name": "api",
       "port": 59125,
       "protocol": "tcp",
       "from": "mesh",

modules/mesh-catalog/Dockerfile

@@ -22,7 +22,7 @@ COPY . .
 # The compiler is invoked by its real path rather than through node_modules/.bin, whose entries are
 # symlinks to a launcher that requires its library relatively — resolved away when the base image
 # was assembled.
-RUN node /app/node_modules/typescript/bin/tsc pg.d.ts store.ts index.ts tools/index.ts \
+RUN node /app/node_modules/typescript/bin/tsc pg.d.ts store.ts index.ts tools/index.ts prepare/index.ts \
       --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 
 # **A module may need something the base image does not carry.** The base holds what every module
@@ -48,3 +48,8 @@ COPY --from=build /deps/node_modules /app/modules/mesh-catalog/node_modules
 # to listen for what the builder announces. Serve binds the broker first, then imports these, so
 # `on()` has something to subscribe to.
 ENV MESH_TOOL_MODULES=/app/modules/mesh-catalog/dist/index.js,/app/modules/mesh-catalog/dist/tools/index.js
+
+# And what prepares this module's state, for the runtime's `prepare` mode (novox/hq ADR 0135). Named
+# here, beside the entrypoints above, because the module knows which of its files prepares its state
+# and nothing else could: the mesh asks one word and this says what answers it.
+ENV MESH_PREPARE=/app/modules/mesh-catalog/dist/prepare/index.js

modules/mesh-catalog/index.ts

@@ -14,10 +14,12 @@ import { Graph, type Made } from "./store.js";
 
 const graph = Graph.fromEnv();
 
-// Before subscribing, and idempotent. The runtime is restarted until its store is reachable, which
+// The schema is not brought up here. The mesh prepares this module's state before it starts this
-// is the same arrangement model-usage uses: a schema step that had to reach the provider over the
+// version, and does not start it if that failed (novox/hq ADR 0135) — see prepare/index.ts. Doing it
-// overlay would block the very apply that brings the overlay up.
+// at start made a schema that could not be reached a crash loop instead of a stop, with the graph
-await graph.migrate();
+// keeping a gap and nothing saying so. The reason it used to be here — that a step blocking the apply
+// would block the very apply that brings the overlay up — stopped being true when a step's failure
+// became this module's business and not the machine's (ADR 0136).
 
 /** What the builder says when it has built something. */
 interface Built {
@@ -47,7 +49,15 @@ interface Built {
   replay?: boolean;
 }
 
-await on("mesh-build-machine.built", async (event) => {
+/**
+ * What a build means for the graph, wherever it came from.
+ *
+ * Two emitters say the same thing and neither is a mistake: the build machine says it as it happens,
+ * and the control plane says what it already held when this module asks what it missed
+ * (novox/hq ADR 0134). A replay is marked as one in its body, so nothing acts on a module that moved
+ * months ago — see `replay` above.
+ */
+const placeTheBuild = async (event: { body: unknown }): Promise<void> => {
   const body = event.body as Built;
   if (!body.module || !body.commit) {
     // Said rather than dropped: a build that announced itself without saying what it built is a
@@ -89,7 +99,11 @@ await on("mesh-build-machine.built", async (event) => {
       because: next.because,
     });
   }
-});
+};
+
+// As it happens, and what the mesh already held when this module asked what it missed.
+await on("mesh-build-machine.built", placeTheBuild);
+await on("mesh-controller.built-before", placeTheBuild);
 
 // **And ask for what was built before this catalogue existed** (novox/hq 04-ISSUES/050).
 //

modules/mesh-catalog/module.json

@@ -29,13 +29,16 @@
     "broker": "/var/lib/mesh/mesh-catalog/broker"
   },
   "consumes": [
-    "mesh-build-machine.built"
+    "mesh-build-machine.built",
+    "mesh-controller.built-before"
   ],
   "emits": [
     "registered",
     "upgraded",
-    "rebuild-needed"
+    "rebuild-needed",
+    "catching-up"
   ],
+  "prepares": true,
   "resources": [
     {
       "id": "mesh-state",

modules/mesh-catalog/prepare/index.ts

@@ -0,0 +1,17 @@
+// The catalogue's state, brought to the shape this version needs (novox/hq ADR 0135).
+//
+// **The mesh runs this before the version that needs it, and does not start that version if it
+// fails** — and the refusal reaches this module and nothing else on the machine
+// (novox/hq ADR 0136). That is the whole difference from where this used to happen: at start, inside
+// the runtime, a schema that could not be brought up was a crash loop, the graph kept a gap, and
+// nothing anywhere said so.
+//
+// Nothing here connects to the broker. Preparation runs before the version that would use it, so
+// there is nothing yet to talk to; the runtime's `prepare` mode imports this and awaits it, and this
+// process exiting non-zero is how the host knows not to start the runtime.
+import { Graph } from "../store.js";
+
+const graph = Graph.fromEnv();
+await graph.migrate();
+console.log("[mesh-catalog] the module graph's schema is what this version needs");
+await graph.close();

modules/mesh-catalog/tsconfig.json

@@ -12,6 +12,7 @@
     "pg.d.ts",
     "store.ts",
     "index.ts",
-    "tools/index.ts"
+    "tools/index.ts",
+    "prepare/index.ts"
   ]
 }

modules/minio/module.json

@@ -14,11 +14,11 @@
     "route": {
       "api": {
         "label": "files-api",
-        "port": 9000
+        "endpoint": "s3"
       },
       "console": {
         "label": "files",
-        "port": 9001
+        "endpoint": "console"
       }
     }
   },
@@ -31,12 +31,14 @@
   ],
   "listens": [
     {
+      "name": "s3",
       "port": 9000,
       "protocol": "tcp",
       "from": "mesh",
       "why": "the S3 endpoint"
     },
     {
+      "name": "console",
       "port": 9001,
       "protocol": "tcp",
       "from": "mesh",

modules/mongodb/module.json

@@ -20,6 +20,7 @@
   ],
   "listens": [
     {
+      "name": "database",
       "port": 27017,
       "protocol": "tcp",
       "from": "mesh",

modules/mosquitto/module.json

@@ -34,12 +34,14 @@
   },
   "listens": [
     {
+      "name": "mqtt",
       "port": 1883,
       "protocol": "tcp",
       "from": "mesh",
       "why": "modules on any machine that were granted a topic namespace"
     },
     {
+      "name": "mqtt-websockets",
       "port": 8081,
       "protocol": "tcp",
       "from": "mesh",

modules/mssql/module.json

@@ -20,6 +20,7 @@
   ],
   "listens": [
     {
+      "name": "database",
       "port": 4848,
       "protocol": "tcp",
       "from": "mesh",

modules/n8n/module.json

@@ -14,7 +14,7 @@
     },
     "route": {
       "label": "n8n",
-      "port": 5682
+      "endpoint": "web"
     }
   },
   "binds": {
@@ -29,6 +29,7 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 5682,
       "protocol": "tcp",
       "from": "mesh",

modules/nats/module.json

@@ -21,6 +21,7 @@
   "consumes": [],
   "listens": [
     {
+      "name": "bus",
       "port": 4222,
       "protocol": "tcp",
       "from": "mesh",
@@ -47,7 +48,7 @@
       "id": "server-conf",
       "type": "file",
       "path": "/var/lib/nats-module/conf/nats.conf",
-      "content": "# The nats module's own server settings. Declared by the module, because a port, a TLS path\n# and a store directory are properties of the container this module raises: they live in its\n# image and its mounts and change when it does.\n#\n# The mesh writes accounts.conf beside this one and nothing else. A controller that wrote the\n# whole file would have to be kept in step with a Dockerfile it never sees.\n\nport: 4222\nhttp: 127.0.0.1:8222\n\ntls {\n  cert_file: \"/tls/tls.crt\"\n  key_file: \"/tls/tls.key\"\n  ca_file: \"/tls/ca.crt\"\n}\n\n# **No `verify`, deliberately, and it was `verify: true` until a probe ran this image.** That\n# setting makes the server demand a *client* certificate, and nothing in the mesh presents one: a\n# host pins this server's exact certificate and authenticates with the password the mesh minted\n# (novox/hq ADR 0004, design 25 \u00a74), and so does a module's runtime. With it on, every connection\n# in the mesh is refused at the TLS handshake, before any password is looked at \u2014 and the error is\n# \"client didn't provide a certificate\", which reads as a client fault.\n#\n# TLS is still required: a tls block is what makes it required, and verify only decides whether\n# client certificates are checked. What is given up is a second factor the mesh has no machinery\n# to issue or rotate \u2014 a certificate per module per node \u2014 and what is kept is stronger than a\n# name check in both directions: an exact pin outward, a per-user password inward.\n\njetstream {\n  store_dir: \"/data\"\n}\n\n# Every user of the mesh, composed by the controller and rewritten whenever a module is\n# assigned, a node enrols or a person's access changes.\n#\n# **Relative, and in this same directory, because it has to be.** An absolute include path is\n# resolved relative to the including file's directory, not from the root: nats-server given\n# `include /etc/nats/accounts.conf` from /etc/nats-server/nats.conf looks for\n# /etc/nats-server/etc/nats/accounts.conf and refuses to start. Verified against the server.\ninclude accounts.conf\n",
+      "content": "# The nats module's own server settings. Declared by the module, because a port, a TLS path\n# and a store directory are properties of the container this module raises: they live in its\n# image and its mounts and change when it does.\n#\n# The mesh writes accounts.conf beside this one and nothing else. A controller that wrote the\n# whole file would have to be kept in step with a Dockerfile it never sees.\n\nport: 4222\nhttp: 127.0.0.1:8222\n\n# The mesh's own broker certificate \u2014 the one every machine already pins by fingerprint and the\n# controller already trusts (MESH_BROKER_CERTIFICATE). Serving the new bus with it means no\n# machine's pin changes when it moves, and no second certificate exists to be wrong about.\ntls {\n  cert_file: \"/tls/tls.crt\"\n  key_file: \"/tls/tls.key\"\n}\n\n# **No `verify`, deliberately, and it was `verify: true` until a probe ran this image.** That\n# setting makes the server demand a *client* certificate, and nothing in the mesh presents one: a\n# host pins this server's exact certificate and authenticates with the password the mesh minted\n# (novox/hq ADR 0004, design 25 \u00a74), and so does a module's runtime. With it on, every connection\n# in the mesh is refused at the TLS handshake, before any password is looked at \u2014 and the error is\n# \"client didn't provide a certificate\", which reads as a client fault.\n#\n# TLS is still required: a tls block is what makes it required, and verify only decides whether\n# client certificates are checked. What is given up is a second factor the mesh has no machinery\n# to issue or rotate \u2014 a certificate per module per node \u2014 and what is kept is stronger than a\n# name check in both directions: an exact pin outward, a per-user password inward.\n\njetstream {\n  store_dir: \"/data\"\n}\n\n# Every user of the mesh, composed by the controller and rewritten whenever a module is\n# assigned, a node enrols or a person's access changes.\n#\n# **Relative, and in this same directory, because it has to be.** An absolute include path is\n# resolved relative to the including file's directory, not from the root: nats-server given\n# `include /etc/nats/accounts.conf` from /etc/nats-server/nats.conf looks for\n# /etc/nats-server/etc/nats/accounts.conf and refuses to start. Verified against the server.\ninclude accounts.conf\n",
       "mode": "0644"
     },
     {
@@ -61,14 +62,14 @@
       "volumes": [
         "/var/lib/mesh-broker-nats:/data",
         "/var/lib/nats-module/conf:/etc/nats:ro",
-        "/var/lib/mesh-broker-nats-tls:/tls:ro"
+        "/var/lib/mesh-broker-tls:/tls:ro"
       ],
       "artifact": "server"
     }
   ],
   "accesses": [
     {
-      "path": "/var/lib/mesh-broker-nats-tls",
+      "path": "/var/lib/mesh-broker-tls",
       "mode": "read"
     }
   ],

modules/network-checker/check/index.ts

@@ -0,0 +1,84 @@
+// Dial everything the mesh claims is reachable, and say what was found (novox/hq ADR 0145).
+//
+// Runs on a cadence, from this machine, in this module's own container — the same position every other
+// module on the machine calls from. That is the whole point: a check run by the host or by the control
+// plane reaches these addresses by a path no ordinary caller uses, and would have passed throughout the
+// outage that produced this module (novox/hq 04-ISSUES/145).
+//
+// It reports and does nothing else. A checker that repaired things would be a second control plane.
+
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { dial, tally, targetsFor, type Counts, type Result, type Roster } from "../reach.js";
+
+/** Where the mesh renders this machine's view of the others, and where the counts are kept between runs. */
+const rosterFile = process.env.MESH_NETWORK_CHECKER_ROSTER ?? "/run/config/roster.json";
+const stateDir = process.env.MESH_NETWORK_CHECKER_STATE ?? "/run/state";
+const probePort = Number(process.env.MESH_NETWORK_CHECKER_PORT ?? "9876");
+const publicPort = process.env.MESH_NETWORK_CHECKER_PUBLIC_PORT
+  ? Number(process.env.MESH_NETWORK_CHECKER_PUBLIC_PORT)
+  : undefined;
+const timeoutMs = Number(process.env.MESH_NETWORK_CHECKER_TIMEOUT_MS ?? "4000");
+const threshold = Number(process.env.MESH_NETWORK_CHECKER_THRESHOLD ?? "2");
+
+/** read is a JSON file or a stated failure — never a silent default, which is how a checker comes to
+ *  report that everything is fine because it read nothing. */
+function read<T>(path: string, whenMissing: T | null): T {
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as T;
+  } catch (err) {
+    if (whenMissing !== null) return whenMissing;
+    console.error(`network-checker: cannot read ${path}: ${(err as Error).message}`);
+    process.exit(1);
+  }
+}
+
+function writeAtomically(path: string, body: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const temp = `${path}.writing`;
+  writeFileSync(temp, body);
+  renameSync(temp, path);
+}
+
+async function main(): Promise<void> {
+  const roster = read<Roster>(rosterFile, null);
+  if (!roster.machines?.length) {
+    console.error("network-checker: the roster names no machines; nothing to check");
+    process.exit(1);
+  }
+
+  const targets = targetsFor(roster, probePort, publicPort);
+  // In parallel, because a machine that is away should not delay the rest: a run that takes
+  // machines × timeout would outlast its own cadence on a mesh of any size.
+  const results: Result[] = await Promise.all(targets.map((t) => dial(t, timeoutMs)));
+
+  const countsFile = join(stateDir, "consecutive.json");
+  const { counts, broken } = tally(results, read<Counts>(countsFile, {}), threshold);
+  writeAtomically(countsFile, JSON.stringify(counts, null, 1));
+
+  // Written whole, every run: a reader asking "what does this machine reach" gets an answer about now
+  // rather than the last time something changed.
+  writeAtomically(join(stateDir, "reach.json"), JSON.stringify({
+    node: roster.node,
+    at: new Date().toISOString(),
+    checked: results.length,
+    broken: broken.length,
+    results,
+  }, null, 1));
+
+  for (const b of broken) {
+    console.error(
+      `network-checker: ${roster.node} cannot reach ${b.machine} (${b.claim}) at ${b.at}:${b.port} — ` +
+      `${b.failed} failed${b.detail ? `: ${b.detail}` : ""}, ${b.consecutive} run(s) running`);
+  }
+  if (broken.length === 0) {
+    console.log(`network-checker: ${roster.node} reaches all ${results.length} checked path(s)`);
+  }
+
+  // A broken path is not this process failing. It did its job; exiting non-zero would make the mesh
+  // read the checker as the fault, and a scheduled step that fails is retried rather than believed.
+  process.exit(0);
+}
+
+void main();

modules/network-checker/module.json

@@ -0,0 +1,61 @@
+{
+  "module": "network-checker",
+  "version": "1",
+  "slug": "netcheck",
+  "listens": [
+    {
+      "name": "probe",
+      "port": 9876,
+      "protocol": "tcp",
+      "from": "mesh",
+      "why": "what the other machines' checkers dial. Deliberately this module's own endpoint and nothing else's: it is admitted by exactly the rule that governs every internally-exposed service, so it fails when that rule is wrong. A probe on a port that is never closed — ssh, say — would have passed throughout the outage this module exists to catch (novox/hq ADR 0145)"
+    }
+  ],
+  "facts": {
+    "roster": {
+      "path": "/var/lib/network-checker/roster.json",
+      "template": "{\n \"generated\": \"by the mesh — do not edit; replaced whenever a machine joins or leaves\",\n \"node\": \"{{.Node}}\",\n \"machines\": [{{range $i, $m := .Machines}}{{if $i}},{{end}}\n  { \"name\": \"{{$m.Name}}\", \"fqdn\": \"{{$m.FQDN}}\", \"address\": \"{{$m.Address}}\" }{{end}}\n ]\n}\n"
+    }
+  },
+  "build": {
+    "artifacts": [
+      {
+        "name": "code",
+        "kind": "bundle",
+        "language": "typescript",
+        "entrypoints": ["probe/index.js", "check/index.js"]
+      }
+    ]
+  },
+  "resources": [
+    {
+      "id": "state",
+      "type": "directory",
+      "path": "/var/lib/network-checker",
+      "mode": "0700"
+    },
+    {
+      "id": "probe",
+      "type": "container",
+      "name": "mesh-network-checker-probe",
+      "args": ["run", "/app/modules/network-checker/dist/probe/index.js"],
+      "ports": ["9876"],
+      "state": "running",
+      "env": { "MESH_NETWORK_CHECKER_PORT": "9876" }
+    },
+    {
+      "id": "check",
+      "type": "container",
+      "name": "mesh-network-checker-check",
+      "network": "host",
+      "schedule": "*/5 * * * *",
+      "args": ["run", "/app/modules/network-checker/dist/check/index.js"],
+      "volumes": ["/var/lib/network-checker:/run/state"],
+      "env": {
+        "MESH_NETWORK_CHECKER_ROSTER": "/run/state/roster.json",
+        "MESH_NETWORK_CHECKER_STATE": "/run/state",
+        "MESH_NETWORK_CHECKER_PORT": "${port:9876}"
+      }
+    }
+  ]
+}

modules/network-checker/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@novox/module-network-checker",
+  "version": "0.1.0",
+  "description": "network-checker — dials what the mesh claims is reachable, from where the callers are, and says what it found.",
+  "type": "module",
+  "private": true,
+  "devDependencies": { "@types/node": "^22.0.0", "typescript": "^5.6.0" }
+}

modules/network-checker/probe/index.ts

@@ -0,0 +1,31 @@
+// The endpoint the other machines' checkers dial (novox/hq ADR 0145).
+//
+// **This module's own endpoint is the instrument.** It is declared reachable over the private network
+// like any other service, so it is admitted by exactly the rule that governs every internally-exposed
+// service and it fails when that rule is wrong. A probe on a port that is never closed — ssh, say —
+// would have passed throughout the outage this module exists to catch.
+//
+// It accepts a connection and closes it. Answering anything would make this a protocol, and then the
+// question would be whether the protocol worked rather than whether the path did.
+
+import { createServer } from "node:net";
+
+const port = Number(process.env.MESH_NETWORK_CHECKER_PORT ?? "9876");
+
+const server = createServer((socket) => {
+  // Written before closing so a person dialling it by hand sees something, and so a half-open
+  // connection is not mistaken for a working path by a client that only checks the handshake.
+  socket.end("mesh network-checker\n");
+});
+
+server.on("error", (err: Error) => {
+  // Said and fatal: a probe that cannot listen must not look like a probe that nothing dialled.
+  console.error(`network-checker: cannot serve the probe on ${port}: ${err.message}`);
+  process.exit(1);
+});
+
+server.listen(port, () => console.log(`network-checker: probe listening on ${port}`));
+
+for (const signal of ["SIGTERM", "SIGINT"] as const) {
+  process.on(signal, () => server.close(() => process.exit(0)));
+}

modules/network-checker/reach.ts

@@ -0,0 +1,155 @@
+// What the mesh claims is reachable, and how to find out (novox/hq ADR 0145).
+//
+// The mesh asserts three things are callable (ADR 0144): what runs on the same machine, another
+// machine's service exposed to the private network, and another machine's service exposed publicly.
+// This decides what to dial for each and reads the answers. It opens connections and nothing more —
+// the module that owns a service is the one that knows whether it is working.
+//
+// **The target is this module's own endpoint, and that is deliberate.** The obvious thing to dial is a
+// service every machine has, and the services every machine has are the ones never closed — ssh above
+// all. Dialling one of those would have passed throughout the outage this exists to catch, because what
+// broke was a service exposed to the private network and ssh is admitted unconditionally. A probe on a
+// port that cannot fail measures nothing.
+
+import { connect } from "node:net";
+import { lookup } from "node:dns";
+
+/** One machine as the mesh's roster describes it. */
+export interface Machine {
+  name: string;
+  fqdn: string;
+  address: string;
+  /** The name this machine is reached by from outside, where it has one. Absent for most machines, and
+   *  a machine with no public face has no public claim to check. */
+  public?: string;
+}
+
+/** The roster the mesh renders for this module: who this machine is, and who the others are. */
+export interface Roster {
+  node: string;
+  machines: Machine[];
+}
+
+/** Which of the mesh's three claims a check is about, so a failure says which one broke. */
+export type Claim = "this machine" | "the private network" | "the public network";
+
+/** One thing to dial. */
+export interface Target {
+  claim: Claim;
+  machine: string;
+  /** What to dial — a name where the point is that names resolve, an address where it is not. */
+  at: string;
+  port: number;
+  /** Whether `at` is a name that must resolve first, so a resolution failure is reported as one. */
+  byName: boolean;
+}
+
+/** What one dial found. */
+export interface Result extends Target {
+  ok: boolean;
+  /** Which step failed, so a reader is sent to the right place: the resolver, or the filter. */
+  failed?: "resolution" | "connection";
+  detail?: string;
+  ms: number;
+}
+
+/**
+ * targetsFor is everything this machine should be able to reach, from the roster it was given.
+ *
+ * Its own machine first, because that is the case that distinguishes a caller on the machine from a
+ * caller in one of its containers — the one that broke. Then every other machine over the private
+ * network. The public claim is only checked where a public address is known for a machine, because a
+ * machine with no public face has nothing to fail.
+ */
+export function targetsFor(roster: Roster, probePort: number, publicPort?: number): Target[] {
+  const out: Target[] = [];
+  for (const m of roster.machines) {
+    const own = m.name === roster.node;
+    out.push({
+      claim: own ? "this machine" : "the private network",
+      machine: m.name,
+      at: m.address,
+      port: probePort,
+      byName: false,
+    });
+    // And by name, because a name that does not resolve and a port that does not answer are different
+    // faults with different owners.
+    out.push({
+      claim: own ? "this machine" : "the private network",
+      machine: m.name,
+      at: m.fqdn,
+      port: probePort,
+      byName: true,
+    });
+  }
+  if (publicPort !== undefined) {
+    for (const m of roster.machines) {
+      if (!m.public) continue;
+      out.push({
+        claim: "the public network",
+        machine: m.name,
+        at: m.public,
+        port: publicPort,
+        byName: true,
+      });
+    }
+  }
+  return out;
+}
+
+/** dial opens a connection and closes it. Whether the port accepts is the whole of what is asked. */
+export function dial(target: Target, timeoutMs: number): Promise<Result> {
+  const began = Date.now();
+  const done = (ok: boolean, failed?: Result["failed"], detail?: string): Result => ({
+    ...target, ok, failed, detail, ms: Date.now() - began,
+  });
+
+  return new Promise<Result>((resolve) => {
+    const open = () => {
+      const socket = connect({ host: target.at, port: target.port });
+      const finish = (r: Result) => { socket.destroy(); resolve(r); };
+      socket.setTimeout(timeoutMs);
+      socket.once("connect", () => finish(done(true)));
+      socket.once("timeout", () => finish(done(false, "connection", "timed out")));
+      socket.once("error", (err: Error) => finish(done(false, "connection", err.message)));
+    };
+
+    if (!target.byName) { open(); return; }
+    // Resolved first and reported separately: a checker that says "unreachable" for a name the
+    // resolver never answered sends a reader to the filter, which is not where the fault is.
+    lookup(target.at, (err) => {
+      if (err) { resolve(done(false, "resolution", err.message)); return; }
+      open();
+    });
+  });
+}
+
+/** A path's running count of consecutive failures, keyed so it survives between runs. */
+export type Counts = Record<string, number>;
+
+/** keyOf names one path, stably, so a count follows it across runs. */
+export function keyOf(t: Target): string {
+  return `${t.claim}|${t.machine}|${t.at}|${t.port}`;
+}
+
+/**
+ * tally folds this run's results into the counts carried from the last one.
+ *
+ * **One failure is not a fault.** A machine rebooting is ordinary, and a checker that cries at the
+ * first missed dial trains a reader to ignore it — which is worse than not checking (ADR 0145). A path
+ * is broken once it has failed on consecutive runs, and the count travels with the result so a reader
+ * can tell "briefly away" from "never worked".
+ */
+export function tally(results: Result[], before: Counts, threshold: number): {
+  counts: Counts; broken: Array<Result & { consecutive: number }>;
+} {
+  const counts: Counts = {};
+  const broken: Array<Result & { consecutive: number }> = [];
+  for (const r of results) {
+    const key = keyOf(r);
+    const n = r.ok ? 0 : (before[key] ?? 0) + 1;
+    if (n > 0) counts[key] = n;
+    if (n >= threshold) broken.push({ ...r, consecutive: n });
+  }
+  return { counts, broken };
+}

modules/network-checker/test/reach.test.ts

@@ -0,0 +1,72 @@
+import { strict as assert } from "node:assert";
+import test from "node:test";
+
+import { keyOf, tally, targetsFor, type Result, type Roster } from "../reach.js";
+
+const roster: Roster = {
+  node: "here",
+  machines: [
+    { name: "here", fqdn: "here.internal", address: "10.0.0.1" },
+    { name: "there", fqdn: "there.internal", address: "10.0.0.2", public: "there.example.test" },
+  ],
+};
+
+test("its own machine is checked, which is the case that distinguishes a caller on it from one in a container", () => {
+  const own = targetsFor(roster, 9876).filter((t) => t.claim === "this machine");
+  assert.equal(own.length, 2, "its own machine by address and by name");
+  assert.ok(own.some((t) => t.at === "10.0.0.1" && !t.byName));
+  assert.ok(own.some((t) => t.at === "here.internal" && t.byName));
+});
+
+test("every other machine is checked over the private network", () => {
+  const other = targetsFor(roster, 9876).filter((t) => t.claim === "the private network");
+  assert.deepEqual(other.map((t) => t.machine), ["there", "there"]);
+});
+
+test("the public claim is only checked where a machine has a public name", () => {
+  const pub = targetsFor(roster, 9876, 443).filter((t) => t.claim === "the public network");
+  assert.equal(pub.length, 1, "only the machine with a public name");
+  assert.equal(pub[0]!.at, "there.example.test");
+  assert.equal(pub[0]!.port, 443);
+});
+
+test("no public claim is made when no public port was given", () => {
+  assert.equal(targetsFor(roster, 9876).filter((t) => t.claim === "the public network").length, 0);
+});
+
+const failed = (at: string): Result => ({
+  claim: "this machine", machine: "here", at, port: 9876, byName: false,
+  ok: false, failed: "connection", ms: 1,
+});
+const passed = (at: string): Result => ({
+  claim: "this machine", machine: "here", at, port: 9876, byName: false, ok: true, ms: 1,
+});
+
+test("one failure is not a fault — a machine rebooting is ordinary", () => {
+  const { counts, broken } = tally([failed("10.0.0.1")], {}, 2);
+  assert.equal(broken.length, 0, "one missed dial says nothing");
+  assert.equal(counts[keyOf(failed("10.0.0.1"))], 1, "and is remembered");
+});
+
+test("a path that keeps failing is broken, and the count travels with it", () => {
+  const first = tally([failed("10.0.0.1")], {}, 2);
+  const second = tally([failed("10.0.0.1")], first.counts, 2);
+  assert.equal(second.broken.length, 1);
+  assert.equal(second.broken[0]!.consecutive, 2, "so a reader can tell briefly away from never worked");
+});
+
+test("a path that recovers stops being counted", () => {
+  const first = tally([failed("10.0.0.1")], {}, 2);
+  const second = tally([passed("10.0.0.1")], first.counts, 2);
+  assert.equal(second.broken.length, 0);
+  assert.deepEqual(second.counts, {}, "nothing carried forward for a path that works");
+});
+
+test("a count follows one path and not another", () => {
+  const a = failed("10.0.0.1");
+  const b = failed("10.0.0.2");
+  const first = tally([a, b], {}, 2);
+  const second = tally([a], first.counts, 2);
+  assert.equal(second.broken.length, 1, "only the path dialled this run is judged");
+  assert.equal(second.broken[0]!.at, "10.0.0.1");
+});

modules/network-checker/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["reach.ts", "probe/index.ts", "check/index.ts", "test/*.ts"]
+}

modules/nextcloud/module.json

@@ -13,7 +13,7 @@
     },
     "route": {
       "label": "drive",
-      "port": 80
+      "endpoint": "web"
     }
   },
   "binds": {
@@ -38,6 +38,7 @@
   ],
   "listens": [
     {
+      "name": "web",
       "port": 80,
       "protocol": "tcp",
       "from": "mesh",

modules/nodered/module.json

@@ -12,6 +12,7 @@
   ],
   "listens": [
     {
+      "name": "web",
       "port": 1880,
       "protocol": "tcp",
       "from": "mesh",
@@ -81,7 +82,7 @@
   "contributes": {
     "route": {
       "label": "nodered",
-      "port": 1880
+      "endpoint": "web"
     }
   },
   "binds": {

modules/novox.be/module.json

@@ -10,7 +10,7 @@
   "contributes": {
     "route": {
       "label": "@",
-      "port": 4000
+      "endpoint": "web"
     }
   },
   "binds": {
@@ -18,6 +18,7 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 4000,
       "protocol": "tcp",
       "from": "mesh",

modules/nzbget/module.json

@@ -15,6 +15,7 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 6789,
       "protocol": "tcp",
       "from": "mesh",

modules/ollama/module.json

@@ -12,6 +12,7 @@
   ],
   "listens": [
     {
+      "name": "api",
       "port": 11434,
       "protocol": "tcp",
       "from": "machine",

modules/ombi/module.json

@@ -14,6 +14,7 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 3579,
       "protocol": "tcp",
       "from": "mesh",
@@ -89,7 +90,7 @@
   "contributes": {
     "route": {
       "label": "ombi",
-      "port": 3579
+      "endpoint": "web"
     }
   },
   "binds": {

modules/only-office/module.json

@@ -11,7 +11,7 @@
   "contributes": {
     "route": {
       "label": "office",
-      "port": 9070
+      "endpoint": "web"
     }
   },
   "binds": {
@@ -22,6 +22,7 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 9070,
       "protocol": "tcp",
       "from": "mesh",

modules/photos-eef/module.json

@@ -11,7 +11,7 @@
   "contributes": {
     "route": {
       "label": "eef",
-      "port": 4012
+      "endpoint": "web"
     }
   },
   "binds": {
@@ -19,6 +19,7 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 4012,
       "protocol": "tcp",
       "from": "mesh",

modules/photos-filip/module.json

@@ -11,7 +11,7 @@
   "contributes": {
     "route": {
       "label": "filip",
-      "port": 4013
+      "endpoint": "web"
     }
   },
   "binds": {
@@ -19,6 +19,7 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 4013,
       "protocol": "tcp",
       "from": "mesh",

modules/photos/module.json

@@ -18,7 +18,7 @@
     },
     "route": {
       "label": "photos",
-      "port": 4001
+      "endpoint": "web"
     }
   },
   "binds": {
@@ -32,12 +32,14 @@
   },
   "listens": [
     {
+      "name": "api",
       "port": 9000,
       "protocol": "tcp",
       "from": "mesh",
       "why": "the photos backend API; the client sites on the module network call it"
     },
     {
+      "name": "web",
       "port": 4001,
       "protocol": "tcp",
       "from": "mesh",

modules/plex/module.json

@@ -18,6 +18,7 @@
   },
   "listens": [
     {
+      "name": "stream",
       "port": 32400,
       "protocol": "tcp",
       "from": "mesh",

modules/portainer/module.json

@@ -7,12 +7,14 @@
   ],
   "listens": [
     {
+      "name": "web",
       "port": 9090,
       "protocol": "tcp",
       "from": "mesh",
       "why": "the dashboard over http; portainer.novox.be is a route grant and the proxy reaches it here \u2014 the machine side of 9090:9000, the predecessor's number"
     },
     {
+      "name": "web-tls",
       "port": 9443,
       "protocol": "tcp",
       "from": "mesh",
@@ -103,7 +105,7 @@
   "contributes": {
     "route": {
       "label": "portainer",
-      "port": 9090
+      "endpoint": "web"
     }
   },
   "binds": {

modules/postgres/module.json

@@ -26,6 +26,7 @@
   ],
   "listens": [
     {
+      "name": "database",
       "port": 5432,
       "protocol": "tcp",
       "from": "mesh",

modules/qbittorrent/module.json

@@ -16,6 +16,7 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 8080,
       "protocol": "tcp",
       "from": "mesh",

modules/radarr/module.json

@@ -14,6 +14,7 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 7878,
       "protocol": "tcp",
       "from": "mesh",
@@ -86,7 +87,7 @@
   "contributes": {
     "route": {
       "label": "movies",
-      "port": 7878
+      "endpoint": "web"
     }
   },
   "binds": {

modules/redis/module.json

@@ -40,6 +40,7 @@
   },
   "listens": [
     {
+      "name": "cache",
       "port": 6379,
       "protocol": "tcp",
       "from": "mesh",

modules/route-proxy/module.json

@@ -27,12 +27,14 @@
   },
   "listens": [
     {
+      "name": "http",
       "port": 80,
       "protocol": "tcp",
       "from": "anywhere",
       "why": "public HTTP, and the ACME HTTP-01 challenge answered at the name being certified"
     },
     {
+      "name": "https",
       "port": 443,
       "protocol": "tcp",
       "from": "anywhere",

modules/searxng/module.json

@@ -10,6 +10,7 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 8080,
       "protocol": "tcp",
       "from": "mesh",
@@ -113,7 +114,7 @@
   "contributes": {
     "route": {
       "label": "searxng",
-      "port": 8080
+      "endpoint": "web"
     }
   },
   "binds": {

modules/showcase/module.json

@@ -43,6 +43,7 @@
   ],
   "listens": [
     {
+      "name": "web",
       "port": 8080,
       "protocol": "tcp",
       "from": "mesh",

modules/sonarr/module.json

@@ -14,6 +14,7 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 8989,
       "protocol": "tcp",
       "from": "mesh",
@@ -91,7 +92,7 @@
   "contributes": {
     "route": {
       "label": "series",
-      "port": 8989
+      "endpoint": "web"
     }
   },
   "binds": {

modules/sshd/module.json

@@ -7,6 +7,7 @@
   ],
   "listens": [
     {
+      "name": "ssh",
       "port": 22,
       "protocol": "tcp",
       "from": "anywhere",
@@ -31,6 +32,7 @@
       "type": "service",
       "unit": "sshd.service",
       "state": "running",
+      "boot": "enabled",
       "restart-on": [
         "config"
       ]

modules/step-ca/module.json

@@ -26,6 +26,7 @@
   },
   "listens": [
     {
+      "name": "acme",
       "port": 9000,
       "protocol": "tcp",
       "from": "mesh",

modules/tautulli/module.json

@@ -12,6 +12,7 @@
   ],
   "listens": [
     {
+      "name": "web",
       "port": 8181,
       "protocol": "tcp",
       "from": "mesh",
@@ -85,7 +86,7 @@
   "contributes": {
     "route": {
       "label": "tautulli",
-      "port": 8181
+      "endpoint": "web"
     }
   },
   "binds": {

modules/umami/module.json

@@ -15,7 +15,7 @@
     },
     "route": {
       "label": "umami",
-      "port": 3000
+      "endpoint": "web"
     }
   },
   "binds": {
@@ -49,10 +49,11 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 3000,
       "protocol": "tcp",
-      "from": "anywhere",
+      "from": "mesh",
-      "why": "one port serves two surfaces: the dashboard (the proxy gates it to the mesh) and the public collection endpoint that the browsers of every tracked site POST to \u2014 so the port itself must be reachable from anywhere"
+      "why": "one port serves two surfaces \u2014 the dashboard and the collection endpoint that the browsers of every tracked site POST to. Both are reached through the proxy, by name, so the port is how the proxy reaches this module and nothing else (novox/hq ADR 0045). It said \"anywhere\" and gave the reason that the collection endpoint must be public, which is true of the name and not of the port: opened, the machine-side port served the dashboard over plain HTTP to the internet, bypassing every rule the proxy applies by path"
     }
   ],
   "resources": [

modules/unifi/module.json

@@ -6,54 +6,63 @@
   ],
   "listens": [
     {
+      "name": "web",
       "port": 8443,
       "protocol": "tcp",
       "from": "mesh",
       "why": "the controller web UI, over its own self-signed tls; reaching it from outside is a route grant later"
     },
     {
+      "name": "inform",
       "port": 8080,
       "protocol": "tcp",
       "from": "mesh",
       "why": "device inform \u2014 how APs and switches check in and are adopted"
     },
     {
+      "name": "stun",
       "port": 3478,
       "protocol": "udp",
       "from": "mesh",
       "why": "STUN, so managed devices can find the controller through NAT"
     },
     {
+      "name": "discovery",
       "port": 10001,
       "protocol": "udp",
       "from": "mesh",
       "why": "device discovery \u2014 the controller finds unadopted devices on the network"
     },
     {
+      "name": "discovery-l2",
       "port": 1902,
       "protocol": "udp",
       "from": "mesh",
       "why": "layer-2 (UBNT) discovery broadcasts; published on 1902, the container listens on 1900"
     },
     {
+      "name": "portal-tls",
       "port": 8843,
       "protocol": "tcp",
       "from": "mesh",
       "why": "the guest captive portal over https"
     },
     {
+      "name": "portal",
       "port": 8880,
       "protocol": "tcp",
       "from": "mesh",
       "why": "the guest captive portal over http"
     },
     {
+      "name": "speedtest",
       "port": 6789,
       "protocol": "tcp",
       "from": "mesh",
       "why": "mobile-app speed-test throughput measurement"
     },
     {
+      "name": "syslog",
       "port": 5514,
       "protocol": "udp",
       "from": "mesh",