lidarr: reach nzbget, qbittorrent and jackett through the mesh

lidarr reached its download clients as nzbget:6789 and qbittorrent:8112 and its indexers
through jackett:9117 or indexers.zurag.be - HAL container names and a public route,
typed into its database by hand. Nothing on the mesh answers those names.

It now requires nzbget-api, qbittorrent-api and jackett-api. A run-once step
(downloads/, declared last, restart-on its bindings, credentials and settings) writes
host, port, TLS, base path, user and credential into lidarr through lidarr's own API:

- A download client is the mesh's when its name is downloads.<provision>.name and its
  kind the provider's; it is registered when missing. A jackett feed is the mesh's when
  its host is the bound one, one the step bound before, or one in
  downloads.jackett-api.adopt-hosts; the jackett indexers in
  downloads.jackett-api.indexers are registered when missing. Every other entry is left
  alone, and nothing is ever deleted.
- Only connection fields, only when they differ. The stored password is masked, so the
  app tests the entry with the credential it holds; only if that fails is the delivered
  one written. Categories, priorities and "enabled" are never touched.
- Each credential is tried against its provider first. A minted value (nothing accepted
  yet) is never written; the step exits 1 naming the exact secret accept.

The step is byte-identical in sonarr, radarr, lidarr and bookshelf (the same Servarr
API, v3 or v1): each module builds from its own directory, so each carries a copy, and
test/downloads.test.ts fails if a sibling's copy differs.

Verified: strict typecheck, the Dockerfile build, 14 unit tests; and the compiled step
against fresh pinned sonarr/radarr/lidarr/bookshelf with throwaway nzbget, qBittorrent
and jackett - minted credentials refused with nothing written, accepted ones registered
and tested by the app, a migration-shaped radarr repointed, reruns unchanged.

modules/amqp-email-forwarder/module.json

@@ -1,56 +0,0 @@
-{
-  "module": "amqp-email-forwarder",
-  "version": "1",
-  "slug": "emailfwd",
-  "capabilities": [
-    "container-runtime"
-  ],
-  "requires": [
-    "amqp"
-  ],
-  "contributes": {},
-  "binds": {
-    "amqp": "/var/lib/amqp-email-forwarder/amqp.json"
-  },
-  "secrets": {
-    "amqp": "/var/lib/amqp-email-forwarder/amqp.secret"
-  },
-  "own-secrets": {
-    "smtp-user": "/var/lib/amqp-email-forwarder/smtp-user.secret",
-    "smtp-password": "/var/lib/amqp-email-forwarder/smtp-password.secret"
-  },
-  "resources": [
-    {
-      "id": "state",
-      "type": "directory",
-      "path": "/var/lib/amqp-email-forwarder",
-      "mode": "0700"
-    },
-    {
-      "id": "app-env",
-      "type": "file",
-      "path": "/var/lib/amqp-email-forwarder/app.env",
-      "mode": "0600",
-      "content": "AMQP_HOST=${bound:amqp:at}\nAMQP_PORT=${bound:amqp:port}\nAMQP_USER=${bound:amqp:as}\nAMQP_VHOST=EMAILDELIVERY_T\nAMQP_EXCHANGE=News.TransactionalEmailing.Command\nAMQP_QUEUE=email-forwarder\nAMQP_URL=amqp://${bound:amqp:as}:${secret:amqp}@${bound:amqp:at}:${bound:amqp:port}/EMAILDELIVERY_T\nSMTP_HOST=mail.novox.be\nSMTP_PORT=587\nSMTP_USER=${secret:smtp-user}\nSMTP_PASSWORD=${secret:smtp-password}\n"
-    },
-    {
-      "id": "net",
-      "type": "network",
-      "name": "amqp-email-forwarder"
-    },
-    {
-      "id": "app",
-      "type": "container",
-      "name": "amqp-email-forwarder",
-      "image": "registry-api.novox.be/novox/amqp-email-forwarder@sha256:f76d34646d9d3b2098c72688a63f6ae656f1888ffcb2f90a9c8dd2a44ad7f8af",
-      "network": "amqp-email-forwarder",
-      "env-file": [
-        "/var/lib/amqp-email-forwarder/app.env"
-      ],
-      "restart-on": [
-        "app-env"
-      ],
-      "secrets-in-environment": "the application's own code reads AMQP_URL, SMTP_USER and SMTP_PASSWORD from the environment (amqp-email-forwarder app.js); converting is that repository's change"
-    }
-  ]
-}

modules/amqp-ping/Dockerfile

@@ -1,31 +0,0 @@
-# amqp-ping's runtime: the tool runtime, carrying this module's compiled code.
-#
-# **Built from this module's own directory and nothing else.** The sdk and the tool runtime are not
-# copied out of neighbouring checkouts — they are in the base image, which is published like any
-# other artifact. That is what makes this buildable by the mesh from a repository and a path
-# (novox/hq ADR 0069) rather than only on a workstation that happens to have the siblings.
-#
-# Two bases, named rather than pinned: the image this is COMPILED in, and the image it RUNS in.
-# They are different images on purpose — the first carries a compiler and the second must not, or
-# every running container would carry one it never invokes. The mesh answers both with the copies it
-# holds, because a fingerprint written here would name one particular copy and no other mesh has it
-# (novox/hq issue 044). Declared in module.json's `build.on`; deliberately no defaults, so a build
-# nobody told stops here and says which module to build first.
-ARG BUILD_BASE
-ARG RUNTIME_BASE
-
-FROM ${BUILD_BASE} AS build
-# Compiled under /app/modules, so resolving `@novox/mesh-sdk` walks up to the base's own
-# node_modules — the module is compiled against exactly the sdk it will run against.
-WORKDIR /app/modules/amqp-ping
-COPY . .
-# The compiler is invoked by its real path, not through node_modules/.bin. Those are symlinks to
-# a launcher that requires its library relatively, and the base image resolves them when copying —
-# leaving a launcher whose relative require no longer points at anything.
-RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts \
-      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
-
-FROM ${RUNTIME_BASE}
-COPY --from=build /app/modules/amqp-ping/dist /app/modules/amqp-ping/dist
-# Declared rather than derived from which files happen to exist: the module knows what it serves.
-ENV MESH_TOOL_MODULES=/app/modules/amqp-ping/dist/index.js

modules/amqp-ping/client.ts

@@ -1,191 +0,0 @@
-// amqp-ping's AMQP client — the demo consumer's own code (novox/hq ADR 0039). It speaks AMQP 0-9-1
-// directly over a raw TCP socket (node:net), the way redis's client speaks RESP: the module carries
-// NO npm dependency beyond @novox/mesh-sdk — no amqplib, no CLI in the image. It does exactly one
-// thing, the round-trip that proves the grant works: connect, authenticate with PLAIN to the vhost
-// the mesh named, declare a queue, publish one message and get it back.
-//
-// This is the consumer half of the `amqp` interface. It connects as the login the mesh derived
-// (`${bound:amqp:as}`) with the password the mesh minted (`${secret:amqp}`) to a vhost of that SAME
-// name — the provider named the vhost after the login, so the consumer must too. Nothing here is
-// hardcoded: user AND vhost are both the bound login, and a wrong vhost is refused by the broker.
-
-import { createConnection, type Socket } from "node:net";
-import { readFileSync } from "node:fs";
-
-const FRAME_END = 0xce;
-const PROTOCOL_HEADER = Buffer.from([0x41, 0x4d, 0x51, 0x50, 0x00, 0x00, 0x09, 0x01]); // "AMQP" 0-9-1
-
-export interface AmqpConn {
-  readonly host: string;
-  readonly port: number;
-  readonly user: string;
-  readonly password: string;
-  readonly vhost: string;
-}
-
-/** Build the connection facts from the environment the mesh's env-file set (see the module manifest). */
-export function connFromEnv(env: NodeJS.ProcessEnv = process.env): AmqpConn {
-  const host = env.MESH_AMQP_HOST ?? "";
-  const port = Number(env.MESH_AMQP_PORT ?? "5672") || 5672;
-  const user = env.MESH_AMQP_USER ?? "";
-  const vhost = env.MESH_AMQP_VHOST ?? user; // the provider names the vhost after the login
-  const password = env.MESH_AMQP_PASSWORD ?? readMaybe(env.MESH_AMQP_PASSWORD_FILE);
-  if (!host || !user || !password) {
-    throw new Error(`amqp-ping: connection is not fully set yet (host=${host} user=${user} password=${password ? "set" : "unset"})`);
-  }
-  return { host, port, user, password, vhost };
-}
-
-// --- wire helpers ---------------------------------------------------------------------------------
-
-function shortstr(s: string): Buffer {
-  const b = Buffer.from(s, "utf8");
-  const o = Buffer.alloc(1 + b.length);
-  o.writeUInt8(b.length, 0);
-  b.copy(o, 1);
-  return o;
-}
-function longstr(s: Buffer | string): Buffer {
-  const b = Buffer.isBuffer(s) ? s : Buffer.from(s, "utf8");
-  const o = Buffer.alloc(4 + b.length);
-  o.writeUInt32BE(b.length, 0);
-  b.copy(o, 4);
-  return o;
-}
-function u16(n: number): Buffer {
-  const o = Buffer.alloc(2);
-  o.writeUInt16BE(n, 0);
-  return o;
-}
-function u32(n: number): Buffer {
-  const o = Buffer.alloc(4);
-  o.writeUInt32BE(n, 0);
-  return o;
-}
-function frame(type: number, channel: number, payload: Buffer): Buffer {
-  const o = Buffer.alloc(7 + payload.length + 1);
-  o.writeUInt8(type, 0);
-  o.writeUInt16BE(channel, 1);
-  o.writeUInt32BE(payload.length, 3);
-  payload.copy(o, 7);
-  o.writeUInt8(FRAME_END, 7 + payload.length);
-  return o;
-}
-function method(channel: number, classId: number, methodId: number, ...parts: Buffer[]): Buffer {
-  return frame(1, channel, Buffer.concat([u16(classId), u16(methodId), ...parts]));
-}
-
-interface MethodWaiter {
-  classId: number;
-  methodId: number;
-  resolve: (args: Buffer) => void;
-  reject: (e: Error) => void;
-}
-
-/**
- * Connect, authenticate to the vhost, declare a queue, publish one message and get it back. Returns
- * the body that came back — the caller checks it equals what went out. Throws on any protocol error,
- * including the broker's `NOT_ALLOWED` refusal of a vhost the login has no permission on (the
- * isolation the provider builds, seen from the consumer's side).
- */
-export function roundTrip(conn: AmqpConn, queue = "amqp-ping", payload?: string): Promise<string> {
-  const body = Buffer.from(payload ?? `ping-${Date.now()}`);
-  return new Promise<string>((resolve, reject) => {
-    const sock: Socket = createConnection({ host: conn.host, port: conn.port });
-    let buf = Buffer.alloc(0);
-    const waiters: MethodWaiter[] = [];
-    let lastBody: Buffer | null = null;
-    let done = false;
-
-    const fail = (e: Error): void => {
-      if (done) return;
-      done = true;
-      sock.destroy();
-      reject(e);
-    };
-    const expect = (classId: number, methodId: number): Promise<Buffer> =>
-      new Promise((res, rej) => waiters.push({ classId, methodId, resolve: res, reject: rej }));
-
-    sock.on("error", (e) => fail(e));
-    sock.on("close", () => fail(new Error("amqp connection closed before the round-trip completed")));
-    sock.on("data", (chunk: Buffer) => {
-      buf = Buffer.concat([buf, chunk]);
-      for (;;) {
-        if (buf.length < 7) return;
-        const type = buf.readUInt8(0);
-        const size = buf.readUInt32BE(3);
-        if (buf.length < 7 + size + 1) return;
-        const framePayload = buf.subarray(7, 7 + size);
-        buf = buf.subarray(7 + size + 1);
-        if (type === 1) {
-          const classId = framePayload.readUInt16BE(0);
-          const methodId = framePayload.readUInt16BE(2);
-          const args = framePayload.subarray(4);
-          const w = waiters.shift();
-          if (!w) continue;
-          if (w.classId === classId && w.methodId === methodId) w.resolve(args);
-          else w.reject(new Error(`expected method ${w.classId}/${w.methodId}, got ${classId}/${methodId}: ${args.toString("utf8")}`));
-        } else if (type === 3) {
-          lastBody = framePayload; // a content body frame
-        }
-        // type 2 (content header) and type 8 (heartbeat) need no handling for this round-trip.
-      }
-    });
-
-    sock.on("connect", () => {
-      void (async () => {
-        try {
-          sock.write(PROTOCOL_HEADER);
-          await expect(10, 10); // Connection.Start
-          const response = Buffer.concat([
-            Buffer.from([0]), Buffer.from(conn.user, "utf8"), Buffer.from([0]), Buffer.from(conn.password, "utf8"),
-          ]);
-          // Connection.Start-Ok: empty client-properties table, PLAIN, the SASL response, locale.
-          sock.write(method(0, 10, 11, u32(0), shortstr("PLAIN"), longstr(response), shortstr("en_US")));
-          const tune = await expect(10, 30); // Connection.Tune
-          const frameMax = tune.readUInt32BE(2) || 131072;
-          sock.write(method(0, 10, 31, u16(tune.readUInt16BE(0)), u32(frameMax), u16(0))); // Tune-Ok, no heartbeat
-          sock.write(method(0, 10, 40, shortstr(conn.vhost), shortstr(""), Buffer.from([0]))); // Connection.Open
-          await expect(10, 41); // Open-Ok — authenticated and into the vhost
-
-          sock.write(method(1, 20, 10, shortstr(""))); // Channel.Open
-          await expect(20, 11);
-          // Queue.Declare: reserved, queue, bits(auto-delete=1), empty arguments table.
-          sock.write(method(1, 50, 10, u16(0), shortstr(queue), Buffer.from([0b00001000]), u32(0)));
-          await expect(50, 11);
-
-          // Basic.Publish to the default exchange, routing-key = queue; then content header + body.
-          sock.write(method(1, 60, 40, u16(0), shortstr(""), shortstr(queue), Buffer.from([0])));
-          const bodySize = Buffer.alloc(8);
-          bodySize.writeBigUInt64BE(BigInt(body.length), 0);
-          sock.write(frame(2, 1, Buffer.concat([u16(60), u16(0), bodySize, u16(0)]))); // content header, no properties
-          sock.write(frame(3, 1, body)); // content body
-
-          await new Promise((r) => setTimeout(r, 200));
-          lastBody = null;
-          sock.write(method(1, 60, 70, u16(0), shortstr(queue), Buffer.from([1]))); // Basic.Get, no-ack
-          await expect(60, 71); // Get-Ok (a Get-Empty would arrive as 60/72 and reject the expect)
-          await new Promise((r) => setTimeout(r, 200));
-          const received = lastBody ? (lastBody as Buffer).toString("utf8") : "";
-
-          sock.write(method(0, 10, 50, u16(200), shortstr("bye"), u16(0), u16(0))); // Connection.Close
-          await expect(10, 51).catch(() => undefined);
-          done = true;
-          sock.end();
-          resolve(received);
-        } catch (e) {
-          fail(e instanceof Error ? e : new Error(String(e)));
-        }
-      })();
-    });
-  });
-}
-
-function readMaybe(path: string | undefined): string {
-  if (!path) return "";
-  try {
-    return readFileSync(path, "utf8").replace(/\n$/, "");
-  } catch {
-    return "";
-  }
-}

modules/amqp-ping/index.ts

@@ -1,53 +0,0 @@
-// amqp-ping — a tiny demo consumer of the mesh `amqp` interface, run as a long-lived container by
-// `mesh-tools run` (it never returns, so the container stays up). It exists to PROVE the grant end to
-// end: the mesh gave it a scoped login and a vhost of that name on the lavinmq provider, and this
-// connects with exactly those and round-trips a message.
-//
-// The connection facts arrive the way every consumer's do — the mesh writes them into an env-file the
-// container reads (novox/hq ADR 0048): MESH_AMQP_HOST/PORT from the binding, MESH_AMQP_USER and
-// MESH_AMQP_VHOST both from `${bound:amqp:as}` (the provider named the vhost after the login, so the
-// consumer uses the login for both — the db-name lesson applied to AMQP), and MESH_AMQP_PASSWORD from
-// `${secret:amqp}`.
-//
-// It retries: on first boot the provider may not have provisioned this consumer yet (the reconcile is
-// asynchronous and cross-container), so a refused or unreachable connection is a "not yet", not a
-// failure — it waits and tries again until the round-trip succeeds, then holds the connection idle
-// and re-pings on a slow cadence so the container is a stable, running proof.
-
-import { connFromEnv, roundTrip } from "./client.js";
-
-async function sleep(ms: number): Promise<void> {
-  await new Promise((r) => setTimeout(r, ms));
-}
-
-async function pingOnce(): Promise<boolean> {
-  try {
-    const conn = connFromEnv();
-    const sent = `ping-${Date.now()}`;
-    const got = await roundTrip(conn, "amqp-ping", sent);
-    if (got === sent) {
-      console.log(`[amqp-ping] round-trip ok as ${conn.user} on vhost ${conn.vhost} (${conn.host}:${conn.port})`);
-      return true;
-    }
-    console.error(`[amqp-ping] round-trip mismatch: sent ${sent}, got ${got}`);
-    return false;
-  } catch (err) {
-    console.error(`[amqp-ping] not ready yet: ${err instanceof Error ? err.message : err}`);
-    return false;
-  }
-}
-
-// Wait for the first successful round-trip — the proof this consumer's grant works — then stay up.
-let first = false;
-for (let i = 0; !first; i++) {
-  first = await pingOnce();
-  if (!first) await sleep(3000);
-}
-console.log("[amqp-ping] connected and round-tripped; holding steady");
-for (;;) {
-  await sleep(30000);
-  await pingOnce();
-}
-// changed by the one-node test at build 66e54af151df
-// changed by the one-node test at build 4fb41636cffd
-// changed by the one-node test at build a69f083bf6a6

modules/amqp-ping/module.json

@@ -1,89 +0,0 @@
-{
-  "module": "amqp-ping",
-  "slug": "ping",
-  "version": "1",
-  "capabilities": [
-    "container-runtime"
-  ],
-  "requires": [
-    "amqp"
-  ],
-  "contributes": {},
-  "binds": {
-    "amqp": "/var/lib/amqp-ping/amqp.json"
-  },
-  "secrets": {
-    "amqp": "/var/lib/amqp-ping/amqp.secret"
-  },
-  "own-secrets": {
-    "broker": "/var/lib/mesh/amqp-ping/broker"
-  },
-  "resources": [
-    {
-      "id": "mesh-state",
-      "type": "directory",
-      "path": "/var/lib/mesh/amqp-ping",
-      "mode": "0700"
-    },
-    {
-      "id": "state",
-      "type": "directory",
-      "path": "/var/lib/amqp-ping",
-      "mode": "0700"
-    },
-    {
-      "id": "amqp-env",
-      "type": "file",
-      "path": "/var/lib/amqp-ping/amqp.env",
-      "mode": "0600",
-      "content": "MESH_AMQP_HOST=${bound:amqp:at}\nMESH_AMQP_PORT=${bound:amqp:port}\nMESH_AMQP_USER=${bound:amqp:as}\nMESH_AMQP_VHOST=${bound:amqp:as}\n"
-    },
-    {
-      "id": "net",
-      "type": "network",
-      "name": "amqp-ping"
-    },
-    {
-      "id": "runtime",
-      "type": "container",
-      "name": "amqp-ping",
-      "network": "amqp-ping",
-      "volumes": [
-        "/var/lib/mesh/amqp-ping/broker:/run/secrets/broker:ro",
-        "/var/lib/amqp-ping/amqp.secret:/run/secrets/amqp:ro"
-      ],
-      "env": {
-        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_AMQP_PASSWORD_FILE": "/run/secrets/amqp"
-      },
-      "env-file": [
-        "/var/lib/amqp-ping/amqp.env"
-      ],
-      "restart-on": [
-        "amqp-env"
-      ],
-      "artifact": "runtime"
-    }
-  ],
-  "build": {
-    "on": [
-      {
-        "arg": "BUILD_BASE",
-        "module": "mesh-tools",
-        "artifact": "build"
-      },
-      {
-        "arg": "RUNTIME_BASE",
-        "module": "mesh-tools",
-        "artifact": "runtime"
-      }
-    ],
-    "artifacts": [
-      {
-        "name": "runtime",
-        "kind": "image",
-        "from": "Dockerfile"
-      }
-    ]
-  }
-}

modules/amqp-ping/package.json

@@ -1,14 +0,0 @@
-{
-  "name": "@novox/module-amqp-ping",
-  "version": "0.1.0",
-  "description": "amqp-ping — a demo consumer of the mesh amqp interface. Connects with its scoped grant and round-trips one message to prove the broker the mesh gave it (novox/hq ADR 0039).",
-  "type": "module",
-  "private": true,
-  "dependencies": {
-    "@novox/mesh-sdk": "^0.1.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.6.0"
-  }
-}

modules/amqp-ping/tsconfig.json

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

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",
@@ -93,7 +94,7 @@
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_BAZARR_URL": "http://127.0.0.1:6767",
+        "MESH_BAZARR_URL": "http://127.0.0.1:${port:6767}",
         "MESH_BAZARR_API_KEY_FILE": "/run/secrets/api-key",
         "MESH_BAZARR_CONFIG_FILE": "/run/config/config.json",
         "MESH_BAZARR_CONFIG_DIR": "/var/lib/bazarr/config"
@@ -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",
@@ -75,7 +76,7 @@
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_BOOKSHELF_URL": "http://127.0.0.1:8787",
+        "MESH_BOOKSHELF_URL": "http://127.0.0.1:${port:8787}",
         "MESH_BOOKSHELF_CONFIG_DIR": "/var/lib/bookshelf/config"
       },
       "artifact": "runtime"
@@ -87,7 +88,7 @@
   "contributes": {
     "route": {
       "label": "books",
-      "port": 8787
+      "endpoint": "web"
     }
   },
   "binds": {

modules/ca-trust/module.json

@@ -0,0 +1,56 @@
+{
+  "module": "ca-trust",
+  "version": "1",
+  "slug": "catrust",
+  "capabilities": [
+    "service-manager"
+  ],
+  "requires": [
+    "internal-acme-ca"
+  ],
+  "seats": [
+    {
+      "name": "the-mesh-trust-anchor",
+      "scope": "node"
+    }
+  ],
+  "claims": [
+    {
+      "name": "the-mesh-trust-anchor",
+      "scope": "node"
+    }
+  ],
+  "resources": [
+    {
+      "id": "state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "."
+    },
+    {
+      "id": "anchor",
+      "type": "file",
+      "path": "${dir:state}/anchor",
+      "mode": "0755",
+      "content": "#!/bin/sh\n# The mesh's internal certificate authority, trusted by this machine.\n#\n# Written by the mesh from the ca-trust module's manifest (novox/hq ADR 0147).\n# Editing it here lasts until the next apply.\n#\n# There is no prior trust to verify the fetch against \u2014 this is the thing that\n# establishes it \u2014 so it is made over the mesh's own private network, which is\n# what authenticates it (novox/hq ADR 0098, the same reasoning that lets the\n# route proxy fetch this root for itself). What comes back is checked here: a\n# body that is not a certificate is refused now, rather than believed and then\n# failed by whatever reads the trust store next.\nset -eu\n\nROOTS='https://${bound:internal-acme-ca:at}:${bound:internal-acme-ca:port}${bound:internal-acme-ca:roots}'\nANCHORS=/etc/ca-certificates/trust-source/anchors\nANCHOR=\"$ANCHORS/mesh-internal-ca.crt\"\n\n# Arch's layout, said out loud rather than assumed: a machine that keeps its\n# anchors elsewhere fails here, visibly, instead of writing a file nothing\n# reads. That failure is the signal that this belongs in the host, where one\n# operating system's difference lives (novox/hq ADR 0147, option 2).\n[ -d \"$ANCHORS\" ] || {\n\techo \"this machine keeps no trust anchors in $ANCHORS; ca-trust is written for that layout\" >&2\n\texit 1\n}\n\ncase \"${1:-}\" in\ninstall)\n\ttmp=$(mktemp)\n\ttrap 'rm -f \"$tmp\"' EXIT\n\t# The authority may still be starting, or this machine may have come up\n\t# before it: two minutes of asking, then an honest failure.\n\tn=0\n\twhile [ \"$n\" -lt 60 ]; do\n\t\tif curl --fail --silent --show-error --insecure --max-time 10 \\\n\t\t\t--output \"$tmp\" \"$ROOTS\" &&\n\t\t\tgrep -q 'BEGIN CERTIFICATE' \"$tmp\"; then\n\t\t\tinstall -m 0644 \"$tmp\" \"$ANCHOR\"\n\t\t\tupdate-ca-trust\n\t\t\texit 0\n\t\tfi\n\t\tn=$((n + 1))\n\t\tsleep 2\n\tdone\n\techo \"the authority at $ROOTS did not serve a certificate within two minutes\" >&2\n\texit 1\n\t;;\nremove)\n\t# What stopping the unit does, and therefore what being unassigned does.\n\trm -f \"$ANCHOR\"\n\tupdate-ca-trust\n\t;;\n*)\n\techo \"usage: $(basename \"$0\") install|remove\" >&2\n\texit 2\n\t;;\nesac\n"
+    },
+    {
+      "id": "unit",
+      "type": "file",
+      "path": "/etc/systemd/system/mesh-ca-trust.service",
+      "mode": "0644",
+      "content": "[Unit]\nDescription=The mesh's internal certificate authority, trusted by this machine\n# novox/hq ADR 0147. Starting this unit places the mesh's root among this\n# machine's trust anchors; stopping it takes the root away again, which is what\n# the host does when the module is no longer assigned here.\nWants=network-online.target\nAfter=network-online.target\n\n[Service]\nType=oneshot\nRemainAfterExit=yes\nExecStart=${dir:state}/anchor install\nExecStop=${dir:state}/anchor remove\n\n[Install]\nWantedBy=multi-user.target\n"
+    },
+    {
+      "id": "trust",
+      "type": "service",
+      "unit": "mesh-ca-trust.service",
+      "state": "running",
+      "boot": "enabled",
+      "restart-on": [
+        "anchor",
+        "unit"
+      ]
+    }
+  ]
+}

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}`);
-    return (repos ?? []).map(GiteaClient.mapRepo);
+    const found = await this.request<{ data?: any[] }>(`/repos/search?page=${page}&limit=${limit}`);
+    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/lavinmq/Dockerfile

@@ -1,42 +0,0 @@
-# lavinmq's runtime: the tool runtime, carrying this module's compiled bootstrap, provisioner,
-# tools and event consumer.
-#
-# **Built from this module's own directory and nothing else.** The sdk is in the base image, so
-# nothing is copied out of a neighbouring checkout — which is what lets the mesh build this from a
-# repository and a path (novox/hq ADR 0069) rather than only on a workstation that happens to have
-# the siblings.
-#
-# Two bases, named rather than pinned: the image this is COMPILED in, and the image it RUNS in.
-# They are different images on purpose — the first carries a compiler and the second must not, or
-# every running container would carry one it never invokes. The mesh answers both with the copies it
-# holds, because a fingerprint written here would name one particular copy and no other mesh has it
-# (novox/hq issue 044). Declared in module.json's `build.on`; deliberately no defaults, so a build
-# nobody told stops here and says which module to build first.
-ARG BUILD_BASE
-ARG RUNTIME_BASE
-
-FROM ${BUILD_BASE} AS build
-# Compiled under /app/modules so `@novox/mesh-sdk` resolves upward into the base's own
-# node_modules — the module is compiled against exactly the sdk it will run against.
-WORKDIR /app/modules/lavinmq
-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.
-#
-# Four entrypoints and a client, because this module is four things: a run-once bootstrap that
-# writes the broker's configuration before it first starts, a provisioner that grants consumers
-# their own vhost and user, a set of tools, and an event consumer.
-RUN node /app/node_modules/typescript/bin/tsc \
-      client.ts index.ts bootstrap/index.ts provisioner/index.ts tools/index.ts \
-      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
-
-FROM ${RUNTIME_BASE}
-COPY --from=build /app/modules/lavinmq/dist /app/modules/lavinmq/dist
-# What the runtime loads from this module in serve mode: its event consumer, its tools, and its
-# provisioner — all three in one process, so the provisioner's reconcile loop runs with the broker
-# connected (novox/hq issues 060/061; the provisioner used to be run as a separate container `args`
-# command, which meant it served no tools and, once, ran nowhere at all). The run-once bootstrap is
-# NOT listed here — it is named in its own container's `args`, because it runs to completion before
-# the broker starts rather than serving. One image, because they are one module and share a client.
-ENV MESH_TOOL_MODULES=/app/modules/lavinmq/dist/index.js,/app/modules/lavinmq/dist/tools/index.js,/app/modules/lavinmq/dist/provisioner/index.js

modules/lavinmq/bootstrap/index.ts

@@ -1,45 +0,0 @@
-// lavinmq's run-once bootstrap — lavinmq's own code (novox/hq ADR 0039), run once before the broker
-// first starts (ADR 0052). lavinmq's default admin is set at first boot from a config file's
-// `default_password_hash`, and that value is a HASH of the mesh-minted admin password, not the
-// password itself — a form the mesh's plain-secret delivery cannot produce and no `${secret:...}`
-// placeholder can compute. So this step computes it: it reads the admin password the mesh minted and
-// the host unsealed, hashes it the way lavinmq expects (see client.rabbitHash), and writes the config
-// file the broker container reads with `--config`. The host runs it to completion and only then
-// starts the broker the manifest places after it — so the broker's first boot finds a config with an
-// admin it can authenticate, and the provisioner (which reaches the management API as that admin)
-// can do its work.
-//
-// It runs in the module's own runtime image, under the module's own account, as `mesh-tools run`
-// imports it — no broker connection, because writing a config file is an offline operation and there
-// is no broker to reach yet.
-//
-// lavinmq consults `default_user`/`default_password_hash` only on a first boot with an empty data
-// dir; a later boot uses the persisted user database and ignores them. So this seeds the admin once,
-// and a rotation of the admin secret does not re-key an already-initialised broker — the same
-// first-boot-only shape the RabbitMQ-compatible default user has always had.
-
-import { writeFileSync } from "node:fs";
-import { readFileSync } from "node:fs";
-import { rabbitHash } from "../client.js";
-
-const adminUser = process.env.MESH_PROVISION_ADMIN_USER ?? process.env.MESH_LAVINMQ_ADMIN_USER ?? "mesh-admin";
-const passwordFile = process.env.MESH_PROVISION_PASSWORD_FILE ?? process.env.MESH_LAVINMQ_ADMIN_PASSWORD_FILE ?? "/run/secrets/default";
-const configOut = process.env.MESH_LAVINMQ_CONFIG_OUT ?? "/var/lib/lavinmq-module/lavinmq.ini";
-const dataDir = process.env.MESH_LAVINMQ_DATA_DIR ?? "/var/lib/lavinmq";
-
-const password = readFileSync(passwordFile, "utf8").replace(/\n$/, "");
-if (!password) {
-  throw new Error(`[lavinmq:bootstrap] admin password file ${passwordFile} is empty — cannot seed the admin`);
-}
-
-// The broker reads only what it needs to authenticate its admin on first boot; bind/ports come from
-// the container's entrypoint (`-b 0.0.0.0`), so this file names the admin and nothing else about the
-// network.
-const ini =
-  "[main]\n" +
-  `data_dir = ${dataDir}\n` +
-  `default_user = ${adminUser}\n` +
-  `default_password_hash = ${rabbitHash(password)}\n`;
-
-writeFileSync(configOut, ini, { mode: 0o600 });
-console.log(`[lavinmq:bootstrap] wrote ${configOut} with admin '${adminUser}' (password hashed for lavinmq)`);

modules/lavinmq/client.ts

@@ -1,183 +0,0 @@
-// lavinmq's admin client — lavinmq's own code, living in the module (novox/hq ADR 0039). Both this
-// module's tools and its provisioner import it, and nothing outside lavinmq does.
-//
-// It drives lavinmq through its HTTP management API (the RabbitMQ-compatible surface lavinmq serves
-// on 15672), not a hand-rolled AMQP admin stack: the module may take NO npm dependency beyond
-// @novox/mesh-sdk, and the management API is exactly the admin surface — create/remove a vhost, a
-// user, and its permissions — reached with `fetch` (global on node 22) and HTTP Basic auth. One
-// boundary, `api()`, and every method is built on it. This is the module's one impure seam, the way
-// postgres's is `psql` and redis's is a RESP socket.
-//
-// **The login and password are the mesh's, not the provisioner's (novox/hq ADR 0048).** The mesh
-// derives the login and hands it to both ends so they agree, and mints the password and delivers a
-// copy to each. lavinmq creates exactly that user with exactly that password on a vhost of the same
-// name — a name or password the provisioner invented is one the consumer could never present.
-
-import { createHash, randomBytes } from "node:crypto";
-import { readFileSync } from "node:fs";
-
-export interface LavinmqConn {
-  /** Base URL of the management API, e.g. http://lavinmq:15672 (no trailing /api). */
-  readonly base: string;
-  readonly adminUser: string;
-  readonly adminPassword: string;
-}
-
-export class LavinmqClient {
-  constructor(private readonly conn: LavinmqConn) {}
-
-  /**
-   * Build from the module's resolved environment. Reads MESH_LAVINMQ_* first (the documented
-   * names), falling back to the MESH_PROVISION_* keys the manifest already sets on the provisioner
-   * container so the module runs unchanged there. Throws if it cannot find a management endpoint and
-   * an admin password — the right failure, because without them nothing it does can work.
-   */
-  static fromEnv(env: NodeJS.ProcessEnv = process.env): LavinmqClient {
-    const base = (env.MESH_LAVINMQ_MANAGEMENT ?? env.MESH_PROVISION_LAVINMQ ?? "").replace(/\/+$/, "");
-    const adminUser = env.MESH_LAVINMQ_ADMIN_USER ?? env.MESH_PROVISION_ADMIN_USER ?? "mesh-admin";
-    const adminPassword = env.MESH_LAVINMQ_ADMIN_PASSWORD ?? readSecretFile(env.MESH_PROVISION_PASSWORD_FILE);
-    if (!base || !adminPassword) {
-      throw new Error("lavinmq management endpoint or admin password is not set — lavinmq's own code cannot reach the server");
-    }
-    return new LavinmqClient({ base, adminUser, adminPassword });
-  }
-
-  /** One request against the management API. A non-2xx reply rejects, carrying the body for the log. */
-  async api(method: string, path: string, body?: unknown): Promise<unknown> {
-    const headers: Record<string, string> = {
-      Authorization: "Basic " + Buffer.from(`${this.conn.adminUser}:${this.conn.adminPassword}`).toString("base64"),
-    };
-    if (body !== undefined) headers["Content-Type"] = "application/json";
-    const resp = await fetch(`${this.conn.base}/api${path}`, {
-      method,
-      headers,
-      body: body !== undefined ? JSON.stringify(body) : undefined,
-    });
-    if (!resp.ok) {
-      throw new Error(`lavinmq management API ${method} ${path} -> ${resp.status}: ${await resp.text()}`);
-    }
-    const text = await resp.text();
-    return text ? JSON.parse(text) : null;
-  }
-
-  /** True once the management API answers — the server has finished starting. */
-  async ready(): Promise<boolean> {
-    try {
-      await this.api("GET", "/overview");
-      return true;
-    } catch {
-      return false;
-    }
-  }
-
-  /** Block until the management API answers, or throw once the budget is spent. */
-  async waitReady(retries = 30, delayMs = 1000): Promise<void> {
-    for (let i = 0; i < retries; i++) {
-      if (await this.ready()) return;
-      await new Promise((r) => setTimeout(r, delayMs));
-    }
-    throw new Error("lavinmq management API did not become ready");
-  }
-
-  /**
-   * Create (or reset to a known state) one consumer's broker: a vhost and a user both named for the
-   * consumer's login, with the login owning full permissions on exactly that vhost. Idempotent — a
-   * PUT of a vhost or user that exists is a no-op or a password reset, so a reconcile can call it
-   * again without harm. The consumer connects as `<login>` to vhost `<login>` and can reach nothing
-   * else (novox/hq ADR 0048).
-   */
-  async createConsumer(login: string, password: string): Promise<void> {
-    const v = encodeURIComponent(login);
-    const u = encodeURIComponent(login);
-    await this.api("PUT", `/vhosts/${v}`);
-    await this.api("PUT", `/users/${u}`, { password, tags: "" });
-    await this.api("PUT", `/permissions/${v}/${u}`, { configure: ".*", write: ".*", read: ".*" });
-  }
-
-  /**
-   * Whether a consumer's user exists with exactly this password and full permissions on its own
-   * vhost. Read-only: the stored hash is salted SHA-256, the scheme `rabbitHash` writes, so the
-   * password is checked by hashing it with the stored salt rather than by logging in. `false` when
-   * the user or its permission is gone or the password differs; an unreachable API rejects
-   * (novox/hq issue 120).
-   */
-  async holdsConsumer(login: string, password: string): Promise<boolean> {
-    const v = encodeURIComponent(login);
-    const u = encodeURIComponent(login);
-    const user = await this.getOrNull<{ password_hash?: string; hashing_algorithm?: string }>(`/users/${u}`);
-    if (!user?.password_hash) return false;
-    if (user.hashing_algorithm && !/sha256/i.test(user.hashing_algorithm)) {
-      throw new Error(`lavinmq user ${login} is hashed with ${user.hashing_algorithm}, which this check cannot verify`);
-    }
-    const stored = Buffer.from(user.password_hash, "base64");
-    if (stored.length < 5 || rabbitHash(password, stored.subarray(0, 4)) !== user.password_hash) return false;
-    const perm = await this.getOrNull<{ configure?: string; write?: string; read?: string }>(`/permissions/${v}/${u}`);
-    return perm?.configure === ".*" && perm?.write === ".*" && perm?.read === ".*";
-  }
-
-  /** A GET that answers null for a 404 and rejects on anything else that is not 2xx. */
-  private async getOrNull<T>(path: string): Promise<T | null> {
-    const resp = await fetch(`${this.conn.base}/api${path}`, {
-      headers: {
-        Authorization: "Basic " + Buffer.from(`${this.conn.adminUser}:${this.conn.adminPassword}`).toString("base64"),
-      },
-    });
-    if (resp.status === 404) return null;
-    if (!resp.ok) throw new Error(`lavinmq management API GET ${path} -> ${resp.status}: ${await resp.text()}`);
-    return (await resp.json()) as T;
-  }
-
-  /** Remove a consumer's vhost and user, idempotently. A DELETE of what is already gone is tolerated. */
-  async removeConsumer(login: string): Promise<void> {
-    const v = encodeURIComponent(login);
-    const u = encodeURIComponent(login);
-    try {
-      await this.api("DELETE", `/vhosts/${v}`);
-    } catch (err) {
-      console.error(`[lavinmq] delete vhost ${login} failed (continuing): ${err}`);
-    }
-    try {
-      await this.api("DELETE", `/users/${u}`);
-    } catch (err) {
-      console.error(`[lavinmq] delete user ${login} failed (continuing): ${err}`);
-    }
-  }
-
-  /** The vhosts, for the amqp_list_vhosts tool. */
-  async listVhosts(): Promise<{ name: string; messages: number }[]> {
-    const vhosts = (await this.api("GET", "/vhosts")) as { name: string; messages?: number }[];
-    return vhosts.map((v) => ({ name: v.name, messages: v.messages ?? 0 }));
-  }
-
-  /** The queues on one vhost (default the root vhost), for the amqp_list_queues tool. */
-  async listQueues(vhost = "/"): Promise<{ name: string; messages: number; consumers: number }[]> {
-    const queues = (await this.api("GET", `/queues/${encodeURIComponent(vhost)}`)) as
-      { name: string; messages?: number; consumers?: number }[];
-    return queues.map((q) => ({ name: q.name, messages: q.messages ?? 0, consumers: q.consumers ?? 0 }));
-  }
-}
-
-/**
- * The RabbitMQ-compatible SHA-256 password hash lavinmq's `default_password_hash` expects:
- * base64( salt[4] || sha256( salt || utf8(password) ) ). The salt is any four bytes — random here,
- * because a fixed salt buys nothing and a fresh one is free. Verified against `lavinmqctl
- * hash_password`: a hash produced here is accepted by the server unchanged.
- */
-export function rabbitHash(password: string, salt: Buffer = randomBytes(4)): string {
-  const digest = createHash("sha256").update(Buffer.concat([salt, Buffer.from(password, "utf8")])).digest();
-  return Buffer.concat([salt, digest]).toString("base64");
-}
-
-/** Generate a URL-safe password. */
-export function generatePassword(): string {
-  return randomBytes(24).toString("base64url");
-}
-
-function readSecretFile(path: string | undefined): string | undefined {
-  if (!path) return undefined;
-  try {
-    return readFileSync(path, "utf8").trim();
-  } catch {
-    return undefined;
-  }
-}

modules/lavinmq/index.ts

@@ -1,25 +0,0 @@
-// lavinmq's events entrypoint, loaded by the per-node tool host (the provisioner container runs
-// ./provisioner separately). The broker lifecycle events are EMITTED from the provisioner, where the
-// lifecycle actually happens (novox/hq ADR 0041/0042):
-//   module.lavinmq.amqp.provisioned    — a consumer's vhost + user was created
-//   module.lavinmq.amqp.deprovisioned  — that vhost + user was removed
-// Here in the tool host we react to them, keeping a lightweight audit trail of who was granted a
-// broker and who lost one — observability the provider itself is best placed to log.
-
-import { on } from "@novox/mesh-sdk/events";
-
-interface AmqpEvent {
-  consumer?: string;
-  user: string;
-  vhost?: string;
-}
-
-await on<AmqpEvent>("amqp.provisioned", async (e) => {
-  console.log(`[lavinmq] broker provisioned for ${e.body.consumer ?? "?"} (user ${e.body.user}, vhost ${e.body.vhost})`);
-});
-
-await on<AmqpEvent>("amqp.deprovisioned", async (e) => {
-  console.log(`[lavinmq] broker deprovisioned (user ${e.body.user})`);
-});
-
-console.log("[lavinmq] auditing broker lifecycle events");

modules/lavinmq/module.json

@@ -1,151 +0,0 @@
-{
-  "module": "lavinmq",
-  "version": "1",
-  "provides": [
-    {
-      "name": "amqp",
-      "scope": "mesh"
-    }
-  ],
-  "claims": [
-    {
-      "name": "mesh-broker",
-      "scope": "mesh"
-    }
-  ],
-  "capabilities": [
-    "container-runtime"
-  ],
-  "emits": [
-    "amqp.provisioned",
-    "amqp.deprovisioned"
-  ],
-  "consumes": [
-    "lavinmq.amqp.provisioned",
-    "lavinmq.amqp.deprovisioned"
-  ],
-  "serves": {
-    "amqp": {
-      "port": 5672
-    }
-  },
-  "receives": {
-    "amqp": "/var/lib/lavinmq-module/grants/mesh.json"
-  },
-  "grants": {
-    "amqp": "/var/lib/lavinmq-module/grants"
-  },
-  "own-secrets": {
-    "admin": "/var/lib/lavinmq-module/admin.secret",
-    "broker": "/var/lib/mesh/lavinmq/broker"
-  },
-  "listens": [
-    {
-      "port": 5671,
-      "protocol": "tcp",
-      "from": "mesh",
-      "why": "the mesh bus \u2014 amqps, every module's events and the control plane, reached over the overlay"
-    },
-    {
-      "port": 5672,
-      "protocol": "tcp",
-      "from": "mesh",
-      "why": "modules on any machine that were granted a queue"
-    }
-  ],
-  "guards": [
-    15672
-  ],
-  "resources": [
-    {
-      "id": "mesh-state",
-      "type": "directory",
-      "path": "/var/lib/mesh/lavinmq",
-      "mode": "0700"
-    },
-    {
-      "id": "state",
-      "type": "directory",
-      "path": "/var/lib/lavinmq-module",
-      "mode": "0700"
-    },
-    {
-      "id": "grants-dir",
-      "type": "directory",
-      "path": "/var/lib/lavinmq-module/grants",
-      "mode": "0700"
-    },
-    {
-      "id": "broker-data",
-      "type": "directory",
-      "path": "/var/lib/mesh-broker",
-      "mode": "0700"
-    },
-    {
-      "id": "server",
-      "type": "container",
-      "name": "mesh-broker",
-      "image": "cloudamqp/lavinmq@sha256:3eb54c12916d700a978c2ea86e6362cd4974b0e3189508718006d4e6d341246b",
-      "ports": [
-        "5671:5671",
-        "5672:5672",
-        "127.0.0.1:15672:15672"
-      ],
-      "volumes": [
-        "/var/lib/mesh-broker:/var/lib/lavinmq",
-        "/var/lib/mesh-broker-tls:/tls:ro"
-      ],
-      "args": [
-        "--amqps-port=5671",
-        "--cert=/tls/tls.crt",
-        "--key=/tls/tls.key"
-      ]
-    },
-    {
-      "id": "runtime",
-      "type": "container",
-      "name": "mesh-lavinmq",
-      "artifact": "runtime",
-      "network": "host",
-      "volumes": [
-        "/var/lib/mesh/lavinmq/broker:/run/secrets/broker:ro",
-        "/var/lib/lavinmq-module/grants:/var/lib/lavinmq-module/grants:ro",
-        "/var/lib/lavinmq-module/admin.secret:/run/secrets/admin:ro"
-      ],
-      "env": {
-        "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_RECEIVES": "/var/lib/lavinmq-module/grants/mesh.json",
-        "MESH_PROVISION_LAVINMQ": "http://127.0.0.1:15672",
-        "MESH_PROVISION_ADMIN_USER": "guest",
-        "MESH_PROVISION_PASSWORD_FILE": "/run/secrets/admin"
-      }
-    }
-  ],
-  "build": {
-    "on": [
-      {
-        "arg": "BUILD_BASE",
-        "module": "mesh-tools",
-        "artifact": "build"
-      },
-      {
-        "arg": "RUNTIME_BASE",
-        "module": "mesh-tools",
-        "artifact": "runtime"
-      }
-    ],
-    "artifacts": [
-      {
-        "name": "runtime",
-        "kind": "image",
-        "from": "Dockerfile"
-      }
-    ]
-  },
-  "accesses": [
-    {
-      "path": "/var/lib/mesh-broker-tls",
-      "mode": "read"
-    }
-  ]
-}

modules/lavinmq/package.json

@@ -1,14 +0,0 @@
-{
-  "name": "@novox/module-lavinmq",
-  "version": "0.1.0",
-  "description": "lavinmq — provides the mesh amqp interface (a per-consumer AMQP message broker). Its management client, provisioner, run-once bootstrap, tools and events live here (novox/hq ADR 0039).",
-  "type": "module",
-  "private": true,
-  "dependencies": {
-    "@novox/mesh-sdk": "^0.1.1"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.6.0"
-  }
-}

modules/lavinmq/provisioner/index.ts

@@ -1,56 +0,0 @@
-// lavinmq's provisioner — the adapter that makes lavinmq a provider of the mesh `amqp` interface.
-// The reconcile loop, the contributions file, and reading the mesh's minted password are the sdk
-// harness's; this writes only the per-service half: how lavinmq creates and removes a consumer's own
-// broker (novox/hq ADR 0039/0040/0048).
-//
-// The `amqp` interface: a consumer connects as `as` with the password the mesh minted, to a vhost
-// named for that same login — its own message broker, isolated from every other consumer's by the
-// vhost boundary. It is a broker of its own, not a shared account on the mesh's control-plane broker.
-//
-// **The login and password are the mesh's, not the provisioner's (novox/hq ADR 0048).** The mesh
-// derives the login and hands it to both ends so they agree, and mints the password and delivers a
-// copy to each. lavinmq creates exactly that user with exactly that password — a name or password the
-// provisioner invented is one the consumer could never present.
-//
-// Vhost-per-login is the isolation model, the exact analog of postgres's database-per-login: the
-// consumer owns one vhost, named for its login, and a user with full rights on that vhost and no
-// rights anywhere else. lavinmq enforces it — a user with no permission on `/` is refused the moment
-// it opens that vhost (`NOT_ALLOWED`), so a login is a broker the consumer alone can reach.
-
-import { runProvisioner, type Provision } from "@novox/mesh-sdk/provisioner";
-import { emit } from "@novox/mesh-sdk/events";
-import { LavinmqClient } from "../client.js";
-
-const lavinmq = LavinmqClient.fromEnv();
-
-/** Emit a lifecycle event without letting a broker hiccup fail the provisioning itself. */
-async function announce(type: string, body: Record<string, string>): Promise<void> {
-  try {
-    await emit(type, body);
-  } catch (err) {
-    console.error(`[provisioner:amqp] emit ${type} failed: ${err}`);
-  }
-}
-
-runProvisioner("amqp", {
-  async create(p: Provision): Promise<void> {
-    // The vhost and the user share the consumer's login, so one cannot reach another's broker.
-    await lavinmq.waitReady();
-    await lavinmq.createConsumer(p.as, p.password);
-    await announce("amqp.provisioned", {
-      consumer: p.consumer ?? "",
-      user: p.as,
-      vhost: p.as,
-    });
-  },
-
-  async remove(p: { as: string }): Promise<void> {
-    await lavinmq.removeConsumer(p.as);
-    await announce("amqp.deprovisioned", { user: p.as, vhost: p.as });
-  },
-  // Asked every minute by the harness: whether the backend still holds this consumer exactly as
-  // the mesh gave it, so a login lost behind the provisioner's back is made again (novox/hq issue 120).
-  async holds(p: Provision): Promise<boolean> {
-    return lavinmq.holdsConsumer(p.as, p.password);
-  },
-});

modules/lavinmq/tools/index.ts

@@ -1,32 +0,0 @@
-// lavinmq's tools — lavinmq's own code (novox/hq ADR 0039), importing lavinmq's own management
-// client. They return structured data; the mesh serves them through the sdk's tool harness.
-
-import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
-import { LavinmqClient } from "../client.js";
-
-export function getLavinmqTools(lavinmq: LavinmqClient): ToolDefinition[] {
-  return [
-    {
-      name: "amqp_list_vhosts",
-      description: "List the lavinmq virtual hosts — one per consumer that was granted a broker.",
-      input: {},
-      run: async () => ({ vhosts: await lavinmq.listVhosts() }),
-    },
-    {
-      name: "amqp_list_queues",
-      description: "List the queues on a vhost with message and consumer counts. Omit vhost for the root '/'.",
-      input: { vhost: { type: "string", description: "the vhost to list, e.g. a consumer's login; defaults to '/'" } },
-      run: async (args) => ({ queues: await lavinmq.listQueues(args.vhost ? String(args.vhost) : undefined) }),
-    },
-  ];
-}
-
-// The tools exist only when the server can be reached from the environment; without it, lavinmq
-// contributes none rather than failing the whole tool runtime.
-registerModuleTools("lavinmq", (env) => {
-  try {
-    return getLavinmqTools(LavinmqClient.fromEnv(env));
-  } catch {
-    return [];
-  }
-});

modules/lavinmq/tsconfig.json

@@ -1,12 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "noEmit": true
-  },
-  "include": ["client.ts", "index.ts", "provisioner/index.ts", "tools/index.ts", "bootstrap/index.ts"]
-}

modules/letta/module.json

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

modules/lidarr/Dockerfile

@@ -13,7 +13,7 @@ ARG RUNTIME_BASE
 FROM ${BUILD_BASE} AS build
 WORKDIR /app/modules/lidarr
 COPY . .
-RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
+RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts downloads/settings.ts downloads/index.ts \
       --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 
 FROM ${RUNTIME_BASE}
@@ -22,3 +22,6 @@ COPY --from=build /app/modules/lidarr/dist /app/modules/lidarr/dist
 # provider's provisioner runs its reconcile loop in the same process, with the broker connected —
 # the convention novox/hq issues 060/061 settled.
 ENV MESH_TOOL_MODULES=/app/modules/lidarr/dist/index.js,/app/modules/lidarr/dist/tools/index.js
+# NOT dist/downloads/index.js: that is a step the host runs to completion, named by the `downloads`
+# container's args as `mesh-tools run …` (novox/hq ADR 0052). Listed here it would run inside the
+# serving sidecar too, and exit it.

modules/lidarr/downloads/index.ts

@@ -0,0 +1,188 @@
+// The downloads step — run once by the host after the app's server starts, and again whenever a
+// binding, a pair credential or the step's settings change (the container's `restart-on`,
+// novox/hq ADR 0099). Byte-identical in sonarr, radarr, lidarr and bookshelf; see settings.ts.
+//
+// **A step, not a loop**: everything it does is a function of files the mesh writes, and the host
+// already knows when they change. It connects to no broker.
+//
+// Exits non-zero when anything could not be put right — a refused credential, an unreachable
+// provider, an entry the app would not save — so the node reports the step failed and the host
+// runs it again on the next apply. Declared last in the manifest, so its failing gates nothing
+// else of the module's (novox/hq ADR 0136).
+//
+// Reads, in MESH_DOWNLOADS_DIR, `<provision>.json` (the binding), `<provision>.secret` (the pair
+// credential) and the settings file; remembers in MESH_DOWNLOADS_MEMORY the jackett hosts it has
+// pointed feeds at, so a jackett that moves takes its feeds with it. Never prints a credential.
+
+import { mkdir, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import {
+  CLIENTS,
+  JACKETT,
+  acceptRemedy,
+  appConfig,
+  appReady,
+  listEntries,
+  providerTakes,
+  readIfThere,
+  readJson,
+  reconcileClient,
+  reconcileIndexers,
+  scrub,
+  stepSettings,
+  wanted,
+  type App,
+  type Binding,
+  type Http,
+  type Entry,
+  type Outcome,
+  type Took,
+} from "./settings.js";
+
+const module = process.env.MESH_DOWNLOADS_APP ?? "app";
+const dir = process.env.MESH_DOWNLOADS_DIR ?? "/run/downloads";
+const settingsFile = process.env.MESH_DOWNLOADS_SETTINGS ?? join(dir, "downloads.json");
+const memoryFile = process.env.MESH_DOWNLOADS_MEMORY ?? "/var/lib/downloads/memory.json";
+const waitSeconds = Number(process.env.MESH_DOWNLOADS_WAIT_SECONDS ?? "180");
+const tag = `[${module}-downloads]`;
+
+const http: Http = { fetch: (u, init) => fetch(u, init) };
+const secrets: string[] = [];
+const say = (line: string) => console.log(scrub(`${tag} ${line}`, secrets));
+const fail = (line: string) => console.error(scrub(`${tag} ${line}`, secrets));
+
+const config = appConfig((await readIfThere(process.env.MESH_DOWNLOADS_APP_CONFIG)) ?? "");
+if (!config.apiKey) {
+  fail(`no API key in ${module}'s config.xml yet — ${module} writes it on its first start; the step runs again on the next apply`);
+  process.exit(1);
+}
+secrets.push(config.apiKey);
+const app: App = {
+  module,
+  url: `${(process.env.MESH_DOWNLOADS_APP_URL ?? "http://127.0.0.1").replace(/\/$/, "")}${config.urlBase}`,
+  apiKey: config.apiKey,
+  api: process.env.MESH_DOWNLOADS_API ?? "v3",
+};
+const settings = stepSettings(await readJson(settingsFile));
+
+if (!(await appReady(http, app, waitSeconds * 1000))) {
+  fail(`${module} did not answer at ${app.url} within ${waitSeconds}s`);
+  process.exit(1);
+}
+
+const outcomes: Outcome[] = [];
+
+// The download clients.
+let clients: Entry[];
+try {
+  clients = await listEntries(http, app, "downloadclient");
+} catch (err) {
+  fail(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+}
+for (const kind of CLIENTS) {
+  const credential = await readIfThere(join(dir, `${kind.provision}.secret`));
+  if (credential) secrets.push(credential.trim());
+  const w = wanted(kind.provision, (await readJson(join(dir, `${kind.provision}.json`))) as Binding | undefined, credential, true);
+  // `in`, not `!w.ok`: the Dockerfile compiles without strict, where a boolean discriminant does not
+  // narrow.
+  if ("problem" in w) {
+    outcomes.push({ what: kind.provision, result: "refused", problem: w.problem });
+    continue;
+  }
+  const ep = w.endpoint;
+  try {
+    if (!(await providerTakes(http, kind.provision, ep)).took) {
+      outcomes.push({
+        what: kind.provision,
+        result: "refused",
+        problem: acceptRemedy(app, settings.node, kind.provision, kind.provider, kind.secretName, ep.from),
+      });
+      continue;
+    }
+  } catch (err) {
+    outcomes.push({
+      what: kind.provision,
+      result: "refused",
+      problem: `${kind.provider} could not be asked whether it takes the credential at ${ep.host}:${ep.port}: ${err instanceof Error ? err.message : String(err)}`,
+    });
+    continue;
+  }
+  outcomes.push(...(await reconcileClient(http, app, kind, settings.names[kind.provision], ep, clients)));
+}
+
+// The indexers, through jackett.
+{
+  const credential = await readIfThere(join(dir, `${JACKETT}.secret`));
+  if (credential) secrets.push(credential.trim());
+  const w = wanted(JACKETT, (await readJson(join(dir, `${JACKETT}.json`))) as Binding | undefined, credential, false);
+  if ("problem" in w) {
+    outcomes.push({ what: JACKETT, result: "refused", problem: w.problem });
+  } else {
+    const ep = w.endpoint;
+    let took: Took | undefined;
+    try {
+      took = await providerTakes(http, JACKETT, ep);
+    } catch (err) {
+      outcomes.push({
+        what: JACKETT,
+        result: "refused",
+        problem: `jackett could not be asked whether it takes the key at ${ep.host}:${ep.port}: ${err instanceof Error ? err.message : String(err)}`,
+      });
+    }
+    if (took && !took.took) {
+      outcomes.push({ what: JACKETT, result: "refused", problem: acceptRemedy(app, settings.node, JACKETT, "jackett", "API key", ep.from) });
+    } else if (took) {
+      const memory = ((await readJson(memoryFile)) ?? {}) as Record<string, { hosts?: string[] } | undefined>;
+      const remembered = Array.isArray(memory[JACKETT]?.hosts) ? (memory[JACKETT]?.hosts as string[]) : [];
+      try {
+        const indexers = await listEntries(http, app, "indexer");
+        outcomes.push(
+          ...(await reconcileIndexers(http, app, ep, took.configured ?? new Map(), settings.indexers, remembered, indexers)),
+        );
+      } catch (err) {
+        outcomes.push({ what: JACKETT, result: "refused", problem: err instanceof Error ? err.message : String(err) });
+      }
+      // Remember where the feeds now point, so they are still recognised as the mesh's if jackett
+      // moves. Written whole and renamed, so a crash leaves the old memory, never half of one.
+      const hosts = [...new Set([...remembered, ep.host.toLowerCase()])].sort();
+      if (hosts.join() !== [...remembered].sort().join()) {
+        try {
+          await mkdir(dirname(memoryFile), { recursive: true });
+          await writeFile(`${memoryFile}.tmp`, JSON.stringify({ ...memory, [JACKETT]: { hosts } }, null, 2) + "\n", { mode: 0o600 });
+          await rename(`${memoryFile}.tmp`, memoryFile);
+        } catch (err) {
+          outcomes.push({
+            what: JACKETT,
+            result: "notice",
+            note: `could not remember ${ep.host} as a jackett host (${err instanceof Error ? err.message : String(err)}); if jackett moves, list it in downloads.jackett-api.adopt-hosts`,
+          });
+        }
+      }
+    }
+  }
+}
+
+let failed = 0;
+for (const o of outcomes) {
+  switch (o.result) {
+    case "unchanged":
+      say(`${o.what}: already as the mesh says${o.untested ? "" : "; connection tested"}`);
+      break;
+    case "written":
+      say(`${o.what}: wrote ${o.fields.join(", ")}${o.untested ? "" : "; connection tested"}`);
+      break;
+    case "created":
+      say(`${o.what}: registered; connection tested`);
+      break;
+    case "notice":
+      say(`${o.what}: ${o.note}`);
+      break;
+    case "refused":
+      failed++;
+      fail(`${o.what}: ${o.problem}`);
+      break;
+  }
+}
+process.exitCode = failed > 0 ? 1 : 0;

modules/lidarr/downloads/settings.ts

@@ -0,0 +1,778 @@
+// Where a Servarr app reaches its download clients and its indexer proxy — decided by the mesh,
+// written into the app by the app's own API.
+//
+// **One file, four copies.** sonarr, radarr, lidarr and bookshelf (a Readarr fork) keep their
+// download clients and indexers behind the same API — `/api/v3/…` for the first two, `/api/v1/…`
+// for the others — so this step is the same code in each. Each module builds from its own
+// directory (novox/hq ADR 0069), so each carries a byte-identical copy under `downloads/`;
+// `test/downloads.test.ts` checks the copies agree wherever the siblings are checked out beside
+// it. Change all four together.
+//
+// **Why this exists.** The app keeps its connection to nzbget, qBittorrent and jackett in its own
+// database, not in a file, so the mesh has nowhere to write `${bound:nzbget-api:at}` for it. The
+// module requires `nzbget-api`, `qbittorrent-api` and `jackett-api`; the mesh delivers, for each,
+// a binding (where the provider is — `at` — and what it serves: `port`, `scheme`, `url-base`, and
+// for a download client the `username`) and a pair credential (nzbget's ControlPassword,
+// qBittorrent's WebUI password, jackett's API key — each the provider's one and only, accepted by
+// the operator per pair; the mesh cannot mint them). This step reads those files and makes the
+// app's entries say the same thing.
+//
+// **Which entries are the mesh's.** Never a guess from what an entry looks like:
+//   - a download client is the mesh's when its name is the one the module's settings give for
+//     that provision (`downloads.<provision>.name`) and its kind is that provider's. On a fresh
+//     machine the step registers it under that name; on a migrated one the assignment names the
+//     entry the migration adopts ("NZBGet" on ace).
+//   - a Torznab indexer is the mesh's when it reads a jackett feed
+//     (`…/api/v2.0/indexers/<id>/results/torznab`) on a host the mesh put there — the bound `at`,
+//     one it bound before (remembered by the step), or one the settings adopt
+//     (`downloads.jackett-api.adopt-hosts`, which is how a migration names the entries that pointed
+//     at the old container). `downloads.jackett-api.indexers` lists the jackett indexers the app
+//     should have; one missing is registered.
+// Everything else — every entry a person made, an nzbget elsewhere, a seedbox's jackett, a Newznab
+// indexer — is left exactly as it is. **Nothing is ever deleted.**
+//
+// **Only the connection, and only when it differs.** Host, port, TLS, base path, user name and
+// the credential. Categories, priorities, "enabled", seed criteria and every other choice made in
+// the app are left alone. The stored credential cannot be read back (the app masks it), so the
+// step asks the app to test the entry with the mesh's host and port and the credential it already
+// holds: passing, the credential is already the provider's one and only; failing, the delivered
+// credential is written.
+//
+// **A credential the provider refuses is never written.** Until the operator accepts the
+// provider's secret for this pair, the mesh delivers a value it minted itself, which no provider
+// will ever accept (novox/hq ADR 0092). Writing it would replace a working password with a dead
+// one. So it is tried against the provider first; refused, nothing of that provision is written
+// and the step fails naming the `secret accept` that fixes it.
+//
+// Pure logic and a small HTTP seam, so it is tested against fake servers (test/downloads.test.ts).
+// Never prints a credential, an API key, or a URL carrying one.
+
+import { readFile } from "node:fs/promises";
+
+/** A download-client provision and the shape of its entry in the app. */
+export interface ClientKind {
+  provision: "nzbget-api" | "qbittorrent-api";
+  /** The app's `implementation` for it. */
+  implementation: "Nzbget" | "QBittorrent";
+  /** The provider, as a person calls it. */
+  provider: string;
+  /** What the pair credential is, in the provider's words. */
+  secretName: string;
+}
+
+export const CLIENTS: readonly ClientKind[] = [
+  { provision: "nzbget-api", implementation: "Nzbget", provider: "nzbget", secretName: "ControlPassword" },
+  { provision: "qbittorrent-api", implementation: "QBittorrent", provider: "qBittorrent", secretName: "WebUI password" },
+];
+
+export const JACKETT = "jackett-api";
+
+/** What the mesh wrote at `binds.<provision>`: the binding document. */
+export interface Binding {
+  provision?: string;
+  from?: string;
+  at?: string;
+  as?: string;
+  serves?: Record<string, unknown>;
+}
+
+/** Where a provider is, as the mesh bound it, and the credential for it. */
+export interface Endpoint {
+  scheme: "http" | "https";
+  host: string;
+  port: number;
+  /** "" at the root, otherwise "/base" — one leading slash, none trailing. */
+  urlBase: string;
+  /** The user a download client logs in as; "" for jackett, which takes a key. */
+  username: string;
+  credential: string;
+  /** The provider's node, for the `secret accept` remedy. */
+  from: string;
+}
+
+export type Wanted = { ok: true; endpoint: Endpoint } | { ok: false; problem: string };
+
+/**
+ * The endpoint the mesh says to use, from a binding and its pair credential.
+ *
+ * Refused rather than guessed when the binding cannot be dialled from the app's own container: a
+ * loopback `at` — what the mesh hands a machine that is not on the private network — is the app's
+ * container itself.
+ */
+export function wanted(
+  provision: string,
+  binding: Binding | undefined,
+  credential: string | undefined,
+  needsUser: boolean,
+): Wanted {
+  if (!binding) {
+    return { ok: false, problem: `no binding for ${provision} was delivered — the mesh writes it before this step runs` };
+  }
+  const host = typeof binding.at === "string" ? binding.at.trim() : "";
+  const serves = binding.serves ?? {};
+  const port = Number(serves.port);
+  if (!host) return { ok: false, problem: `the ${provision} binding names no host (at)` };
+  if (isLoopback(host)) {
+    return {
+      ok: false,
+      problem:
+        `the ${provision} binding says the provider is at ${host}, which from the app's own container is the ` +
+        `app itself. The mesh hands loopback to a machine that is not on the private network; put it on the ` +
+        `private network so the provider has an address the app can dial`,
+    };
+  }
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    return { ok: false, problem: `the ${provision} binding serves no usable port (${String(serves.port)})` };
+  }
+  const scheme = typeof serves.scheme === "string" && serves.scheme ? serves.scheme : "http";
+  if (scheme !== "http" && scheme !== "https") {
+    return { ok: false, problem: `the ${provision} binding serves scheme ${scheme}, which the app cannot dial` };
+  }
+  const username = typeof serves.username === "string" ? serves.username.trim() : "";
+  if (needsUser && !username) {
+    return { ok: false, problem: `the ${provision} binding serves no username for the app to log in as` };
+  }
+  const key = (credential ?? "").trim();
+  if (!key) return { ok: false, problem: `the ${provision} credential is empty or was not delivered` };
+  return {
+    ok: true,
+    endpoint: {
+      scheme,
+      host,
+      port,
+      urlBase: normBase(serves["url-base"]),
+      username,
+      credential: key,
+      from: typeof binding.from === "string" ? binding.from : "",
+    },
+  };
+}
+
+/** A URL base as "" or "/x/y": slashes trimmed, one put back in front. */
+export function normBase(v: unknown): string {
+  const s = typeof v === "string" ? v.trim().replace(/^\/+|\/+$/g, "") : "";
+  return s === "" ? "" : `/${s}`;
+}
+
+function isLoopback(host: string): boolean {
+  const h = host.toLowerCase();
+  return h === "localhost" || h === "::1" || h === "[::1]" || /^127\./.test(h);
+}
+
+function hostForUrl(host: string): string {
+  return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+}
+
+/** The provider's base URL, as the step dials it and as the app is given it. */
+export function baseUrl(ep: Endpoint): string {
+  return `${ep.scheme}://${hostForUrl(ep.host)}:${ep.port}${ep.urlBase}`;
+}
+
+// ---------------------------------------------------------------------------------------------
+// HTTP
+
+/** The HTTP the step needs, so a test can stand fakes in for the app and the providers. */
+export interface Http {
+  fetch(
+    url: string,
+    init?: { method?: string; headers?: Record<string, string>; body?: string },
+  ): Promise<{ status: number; text(): Promise<string> }>;
+}
+
+/** The app, as the step reaches it from the host. */
+export interface App {
+  /** The module, for messages and the remedy: sonarr, radarr, lidarr, bookshelf. */
+  module: string;
+  /** Its own URL, base path included. */
+  url: string;
+  apiKey: string;
+  /** v3 (sonarr, radarr) or v1 (lidarr, bookshelf). */
+  api: string;
+}
+
+interface Answer {
+  status: number;
+  body: unknown;
+}
+
+async function appCall(http: Http, app: App, method: string, path: string, body?: unknown): Promise<Answer> {
+  const res = await http.fetch(`${app.url.replace(/\/$/, "")}/api/${app.api}${path}`, {
+    method,
+    headers: {
+      "X-Api-Key": app.apiKey,
+      Accept: "application/json",
+      ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+    },
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  let parsed: unknown = undefined;
+  if (text) {
+    try {
+      parsed = JSON.parse(text) as unknown;
+    } catch {
+      parsed = text;
+    }
+  }
+  return { status: res.status, body: parsed };
+}
+
+async function appGet(http: Http, app: App, path: string): Promise<unknown> {
+  const a = await appCall(http, app, "GET", path);
+  if (a.status < 200 || a.status >= 300) throw new Error(`${app.module} GET ${path} answered ${a.status}`);
+  return a.body;
+}
+
+/** One of the app's validation failures: the only parts of an answer the step ever prints. */
+interface Failure {
+  property: string;
+  message: string;
+  warning: boolean;
+}
+
+function failuresOf(body: unknown): Failure[] {
+  const list = Array.isArray(body) ? body : [];
+  return list.map((f) => {
+    const o = (f ?? {}) as Record<string, unknown>;
+    return {
+      property: String(o.propertyName ?? ""),
+      message: String(o.errorMessage ?? ""),
+      warning: o.isWarning === true,
+    };
+  });
+}
+
+/**
+ * One shape rather than a union on `ok`: the Dockerfile compiles without strict, where a boolean
+ * discriminant does not narrow.
+ */
+interface Verdict {
+  ok: boolean;
+  /** Warnings the app raised on a pass; errors (and any warnings) on a failure. */
+  failures: Failure[];
+  status: number;
+  saved?: Entry;
+}
+
+function verdict(a: Answer): Verdict {
+  if (a.status >= 200 && a.status < 300) return { ok: true, failures: [], status: a.status };
+  const failures = failuresOf(a.body);
+  if (a.status === 400 && failures.length > 0 && failures.every((f) => f.warning)) return { ok: true, failures, status: a.status };
+  return { ok: false, failures, status: a.status };
+}
+
+/** The app's own test of an entry, from the app's own container. */
+async function appTest(http: Http, app: App, resource: string, entry: Entry): Promise<Verdict> {
+  return verdict(await appCall(http, app, "POST", `/${resource}/test`, entry));
+}
+
+/**
+ * Save an entry. The app tests an enabled entry before saving it; a test that passes with only
+ * warnings ("a category is recommended") is saved with `forceSave`, the same as pressing "save
+ * anyway" in its screen. An error is never forced.
+ */
+async function appSave(http: Http, app: App, resource: string, entry: Entry, create: boolean): Promise<Verdict> {
+  const path = create ? `/${resource}` : `/${resource}/${entry.id}`;
+  const method = create ? "POST" : "PUT";
+  let a = await appCall(http, app, method, path, entry);
+  let v = verdict(a);
+  if (v.ok && (a.status < 200 || a.status >= 300)) {
+    a = await appCall(http, app, method, `${path}?forceSave=true`, entry);
+    v = verdict(a);
+    if (v.ok && (a.status < 200 || a.status >= 300)) {
+      return { ok: false, failures: failuresOf(a.body), status: a.status };
+    }
+  }
+  if (!v.ok) return v;
+  return { ...v, saved: (a.body ?? undefined) as Entry | undefined };
+}
+
+// ---------------------------------------------------------------------------------------------
+// Entries
+
+/** An entry as the app's API gives it: a download client or an indexer. */
+export interface Entry {
+  id?: number;
+  name?: string;
+  implementation?: string;
+  enable?: boolean;
+  enableRss?: boolean;
+  enableAutomaticSearch?: boolean;
+  enableInteractiveSearch?: boolean;
+  supportsRss?: boolean;
+  supportsSearch?: boolean;
+  fields?: { name: string; value?: unknown; [k: string]: unknown }[];
+  [k: string]: unknown;
+}
+
+export function field(e: Entry, name: string): unknown {
+  return e.fields?.find((f) => f.name === name)?.value;
+}
+
+/** The entry with these fields' values replaced — added when the app's shape lacks one. */
+export function withFields(e: Entry, values: Record<string, unknown>): Entry {
+  const fields = (e.fields ?? []).map((f) => (f.name in values ? { ...f, value: values[f.name] } : { ...f }));
+  for (const [name, value] of Object.entries(values)) {
+    if (!fields.some((f) => f.name === name)) fields.push({ name, value });
+  }
+  return { ...e, fields };
+}
+
+function enabled(e: Entry): boolean {
+  return e.enable === true || e.enableRss === true || e.enableAutomaticSearch === true || e.enableInteractiveSearch === true;
+}
+
+/** What one provision, or one entry of it, came to. */
+export type Outcome =
+  | { what: string; result: "unchanged"; untested?: boolean }
+  | { what: string; result: "written"; fields: string[]; untested?: boolean }
+  | { what: string; result: "created"; fields: string[] }
+  | { what: string; result: "notice"; note: string }
+  | { what: string; result: "refused"; problem: string };
+
+function said(fs: Failure[]): string {
+  return fs.length === 0 ? "no reason given" : fs.map((f) => (f.property ? `${f.property}: ${f.message}` : f.message)).join("; ");
+}
+
+/**
+ * Bring one of the mesh's entries in line: `connection` is the non-secret fields as the mesh says
+ * them, `differs` which of them the entry does not already say, `secretField` where the credential
+ * goes. Never throws: every failure is an outcome with a reason.
+ */
+export async function reconcileEntry(
+  http: Http,
+  app: App,
+  resource: "downloadclient" | "indexer",
+  what: string,
+  current: Entry,
+  connection: Record<string, unknown>,
+  differs: string[],
+  secretField: string,
+  credential: string,
+  testable = true,
+): Promise<Outcome> {
+  try {
+    const base = withFields(current, connection); // the credential as the app holds it — masked
+    if (!testable) {
+      // Nothing to test against (jackett no longer has the indexer it names): the connection is
+      // still the mesh's to state, and the key goes with it when the address changes.
+      if (differs.length === 0) return { what, result: "unchanged", untested: true };
+      const s = await appSave(http, app, resource, withFields(base, { [secretField]: credential }), false);
+      if (!s.ok) return { what, result: "refused", problem: `${app.module} would not save it: ${said(s.failures)}` };
+      return { what, result: "written", fields: [...differs, secretField], untested: true };
+    }
+    const first = await appTest(http, app, resource, base);
+    if (first.ok) {
+      // The credential the app holds already works against the provider at the mesh's address —
+      // and the provider has exactly one, so it is the delivered one.
+      if (differs.length === 0) return { what, result: "unchanged" };
+      const s = await appSave(http, app, resource, base, false);
+      if (!s.ok) return { what, result: "refused", problem: `${app.module} would not save it: ${said(s.failures)}` };
+      return { what, result: "written", fields: differs };
+    }
+    // The app's test failed with what it holds. The delivered credential was already checked
+    // against the provider, so writing it is safe; the app tests an enabled entry again on save.
+    const s = await appSave(http, app, resource, withFields(base, { [secretField]: credential }), false);
+    if (!s.ok) {
+      return {
+        what,
+        result: "refused",
+        problem: `${app.module} tested it at the mesh's address and would not save it (nothing was written): ${said(s.failures)}`,
+      };
+    }
+    const stored = (await appGet(http, app, `/${resource}/${current.id}`)) as Entry;
+    const second = await appTest(http, app, resource, stored);
+    const fields = [...differs, secretField];
+    if (second.ok) return { what, result: "written", fields };
+    const why = `written (${fields.join(", ")}), and ${app.module}'s own test still fails: ${said(second.failures)}`;
+    return enabled(stored) ? { what, result: "refused", problem: why } : { what, result: "notice", note: `${why} — it is disabled, so nothing uses it` };
+  } catch (err) {
+    return { what, result: "refused", problem: message(err) };
+  }
+}
+
+/**
+ * Register a new entry from the app's own template for that kind: its defaults, the name, the
+ * connection and the credential. A category the provider does not have (nzbget refuses one it was
+ * not told about) is left empty rather than failing the registration, and said.
+ */
+export async function createEntry(
+  http: Http,
+  app: App,
+  resource: "downloadclient" | "indexer",
+  what: string,
+  implementation: string,
+  name: string,
+  values: Record<string, unknown>,
+): Promise<Outcome> {
+  try {
+    const schema = (await appGet(http, app, `/${resource}/schema`)) as Entry[];
+    const template = (schema ?? []).find((s) => s.implementation === implementation);
+    if (!template) return { what, result: "refused", problem: `${app.module} has no ${implementation} to register` };
+    let entry: Entry = withFields({ ...template, id: undefined, name }, values);
+    if (resource === "downloadclient") entry.enable = true;
+    else {
+      entry.enableRss = template.supportsRss !== false;
+      entry.enableAutomaticSearch = template.supportsSearch !== false;
+      entry.enableInteractiveSearch = template.supportsSearch !== false;
+    }
+    let s = await appSave(http, app, resource, entry, true);
+    let note = "";
+    if (!s.ok && s.failures.length > 0 && s.failures.every((f) => /category/i.test(f.property))) {
+      const emptied: Record<string, unknown> = {};
+      for (const f of entry.fields ?? []) if (/category$/i.test(f.name) && !/imported/i.test(f.name)) emptied[f.name] = "";
+      entry = withFields(entry, emptied);
+      s = await appSave(http, app, resource, entry, true);
+      note = " with its category left empty — the provider has none by the app's default name; set one in both";
+    }
+    if (!s.ok) return { what, result: "refused", problem: `${app.module} would not register it: ${said(s.failures)}` };
+    const created = s.saved;
+    if (created?.id !== undefined) {
+      const t = await appTest(http, app, resource, (await appGet(http, app, `/${resource}/${created.id}`)) as Entry);
+      if (!t.ok) {
+        return { what, result: "refused", problem: `registered as "${name}"${note}, and ${app.module}'s own test fails: ${said(t.failures)}` };
+      }
+    }
+    return note
+      ? { what, result: "notice", note: `registered as "${name}"${note}` }
+      : { what, result: "created", fields: Object.keys(values) };
+  } catch (err) {
+    return { what, result: "refused", problem: message(err) };
+  }
+}
+
+// ---------------------------------------------------------------------------------------------
+// Providers: does it take the credential?
+
+/**
+ * Does the provider take this credential? `took` it does (for jackett, with the ids of the indexers
+ * it has configured); `refused` it said no; a thrown error when it could not be asked.
+ */
+export interface Took {
+  took: boolean;
+  configured?: Map<string, string>;
+}
+
+export async function providerTakes(http: Http, provision: string, ep: Endpoint): Promise<Took> {
+  const base = baseUrl(ep);
+  if (provision === "nzbget-api") {
+    const auth = Buffer.from(`${ep.username}:${ep.credential}`).toString("base64");
+    const res = await http.fetch(`${base}/jsonrpc/version`, { method: "GET", headers: { Authorization: `Basic ${auth}` } });
+    await res.text();
+    if (res.status === 401 || res.status === 403) return { took: false };
+    if (res.status >= 200 && res.status < 300) return { took: true };
+    throw new Error(`nzbget answered ${res.status}`);
+  }
+  if (provision === "qbittorrent-api") {
+    const form = `username=${encodeURIComponent(ep.username)}&password=${encodeURIComponent(ep.credential)}`;
+    const res = await http.fetch(`${base}/api/v2/auth/login`, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: form,
+    });
+    const text = (await res.text()).trim();
+    if (res.status === 401 || /^fails\.?$/i.test(text)) return { took: false };
+    if (res.status === 403) {
+      throw new Error(
+        "qBittorrent answered 403: it has banned this address after failed logins (WebUI\\BanDuration); it lifts by itself",
+      );
+    }
+    if (res.status >= 200 && res.status < 300) return { took: true };
+    throw new Error(`qBittorrent answered ${res.status}`);
+  }
+  if (provision === JACKETT) {
+    const url = `${base}/api/v2.0/indexers/all/results/torznab/api?t=indexers&configured=true&apikey=${encodeURIComponent(ep.credential)}`;
+    const res = await http.fetch(url, { method: "GET" });
+    const text = await res.text();
+    if (res.status === 401 || res.status === 403) return { took: false };
+    if (res.status < 200 || res.status >= 300) throw new Error(`jackett answered ${res.status}`);
+    // jackett answers a wrong key 200 with an error document: code 100, "Invalid API Key".
+    if (/<error\b[^>]*\bcode="100"/i.test(text)) return { took: false };
+    if (/<error\b/i.test(text)) throw new Error("jackett answered with an error document");
+    return { took: true, configured: configuredIndexers(text) };
+  }
+  throw new Error(`no check for ${provision}`);
+}
+
+/** jackett's configured indexers, id → title, from its `t=indexers` feed. */
+export function configuredIndexers(xml: string): Map<string, string> {
+  const out = new Map<string, string>();
+  const re = /<indexer\b[^>]*\bid="([^"]+)"[^>]*>([\s\S]*?)<\/indexer>/g;
+  for (let m = re.exec(xml); m; m = re.exec(xml)) {
+    const title = /<title>([\s\S]*?)<\/title>/.exec(m[2])?.[1]?.trim() ?? m[1];
+    out.set(m[1], decodeXml(title));
+  }
+  return out;
+}
+
+function decodeXml(s: string): string {
+  return s.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, "&");
+}
+
+/** The remedy for a refused credential, in the controller's own words (ADR 0092). */
+export function acceptRemedy(app: App, node: string, provision: string, provider: string, secretName: string, from: string): string {
+  return (
+    `${provider} refuses the ${provision} credential the mesh delivered, so nothing of ${provision} was written ` +
+    `into ${app.module}. ${provider} has one ${secretName} and the mesh cannot make it: accept it for this pair — ` +
+    `\`secret accept ${node || "<this node>"} ${app.module} ${provision} --provider ${from || "<its node>"} ` +
+    `--from <file holding ${provider}'s ${secretName}>\``
+  );
+}
+
+// ---------------------------------------------------------------------------------------------
+// Download clients
+
+/** The non-secret fields of a download client as the mesh says them. */
+export function clientConnection(ep: Endpoint): Record<string, unknown> {
+  return { host: ep.host, port: ep.port, useSsl: ep.scheme === "https", urlBase: ep.urlBase === "" ? null : ep.urlBase, username: ep.username };
+}
+
+/** Which of them the entry does not already say. Names only. */
+export function clientDiffers(e: Entry, ep: Endpoint): string[] {
+  const out: string[] = [];
+  if (String(field(e, "host") ?? "").toLowerCase() !== ep.host.toLowerCase()) out.push("host");
+  if (Number(field(e, "port") ?? 0) !== ep.port) out.push("port");
+  if (Boolean(field(e, "useSsl")) !== (ep.scheme === "https")) out.push("useSsl");
+  if (normBase(field(e, "urlBase")) !== ep.urlBase) out.push("urlBase");
+  if (String(field(e, "username") ?? "") !== ep.username) out.push("username");
+  return out;
+}
+
+/**
+ * Bring the app's download client for one provision in line: the entry by that name and kind is
+ * the mesh's and is updated; none, it is registered. An entry by that name of another kind, or by
+ * that name in another case, is somebody else's and is refused rather than touched.
+ */
+export async function reconcileClient(
+  http: Http,
+  app: App,
+  kind: ClientKind,
+  name: string,
+  ep: Endpoint,
+  entries: Entry[],
+): Promise<Outcome[]> {
+  const what = `${kind.provision} ("${name}")`;
+  const exact = entries.filter((e) => e.name === name);
+  const alike = entries.filter((e) => e.name !== name && String(e.name ?? "").toLowerCase() === name.toLowerCase());
+  if (exact.length > 0 && exact[0].implementation !== kind.implementation) {
+    return [{
+      what,
+      result: "refused",
+      problem: `the download client named "${name}" is a ${exact[0].implementation}, not ${kind.implementation}; it is not the mesh's and was left alone. Name the mesh's entry otherwise in downloads.${kind.provision}.name`,
+    }];
+  }
+  if (exact.length === 0 && alike.length > 0) {
+    return [{
+      what,
+      result: "refused",
+      problem: `${app.module} already has "${alike[0].name}", which is not the mesh's name ("${name}") and was left alone. To have the mesh manage it, set downloads.${kind.provision}.name to "${alike[0].name}"`,
+    }];
+  }
+  const outcomes: Outcome[] = [];
+  const others = entries.filter((e) => e.implementation === kind.implementation && e.name !== name);
+  if (others.length > 0) {
+    outcomes.push({
+      what,
+      result: "notice",
+      note: `also present and not the mesh's, left alone: ${others.map((o) => `"${o.name}"`).join(", ")}`,
+    });
+  }
+  if (exact.length === 0) {
+    outcomes.push(
+      await createEntry(http, app, "downloadclient", what, kind.implementation, name, {
+        ...clientConnection(ep),
+        password: ep.credential,
+      }),
+    );
+    return outcomes;
+  }
+  outcomes.push(
+    await reconcileEntry(http, app, "downloadclient", what, exact[0], clientConnection(ep), clientDiffers(exact[0], ep), "password", ep.credential),
+  );
+  return outcomes;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Indexers
+
+const FEED = /\/api\/v2\.0\/indexers\/([^/]+)\/results\/torznab\/?$/;
+
+/** A Torznab entry reading a jackett feed: the host it points at and the jackett indexer's id. */
+export function jackettFeed(e: Entry): { host: string; id: string } | undefined {
+  if (e.implementation !== "Torznab") return undefined;
+  const raw = String(field(e, "baseUrl") ?? "").trim();
+  if (!raw) return undefined;
+  let u: URL;
+  try {
+    u = new URL(raw);
+  } catch {
+    return undefined;
+  }
+  const path = `${u.pathname.replace(/\/+$/, "")}/${String(field(e, "apiPath") ?? "").replace(/^\/+/, "")}`;
+  const m = FEED.exec(path);
+  if (!m) return undefined;
+  return { host: u.hostname.replace(/^\[|\]$/g, "").toLowerCase(), id: decodeURIComponent(m[1]) };
+}
+
+/** The feed's two fields as the mesh says them. */
+export function feedConnection(ep: Endpoint, id: string): Record<string, unknown> {
+  return { baseUrl: baseUrl(ep), apiPath: `/api/v2.0/indexers/${id}/results/torznab/` };
+}
+
+function sameUrl(a: string, b: string): boolean {
+  try {
+    const x = new URL(a);
+    const y = new URL(b);
+    const port = (u: URL) => u.port || (u.protocol === "https:" ? "443" : "80");
+    return (
+      x.protocol === y.protocol &&
+      x.hostname.toLowerCase() === y.hostname.toLowerCase() &&
+      port(x) === port(y) &&
+      x.pathname.replace(/\/+$/, "") === y.pathname.replace(/\/+$/, "")
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function feedDiffers(e: Entry, ep: Endpoint, id: string): string[] {
+  const want = feedConnection(ep, id);
+  const out: string[] = [];
+  if (!sameUrl(String(field(e, "baseUrl") ?? ""), String(want.baseUrl))) out.push("baseUrl");
+  const path = (v: unknown) => `/${String(v ?? "").replace(/^\/+|\/+$/g, "")}`;
+  if (path(field(e, "apiPath")) !== path(want.apiPath)) out.push("apiPath");
+  return out;
+}
+
+export interface IndexerSettings {
+  /** Hosts whose jackett feeds the mesh takes over — a migration's old names. */
+  adoptHosts: string[];
+  /** jackett indexer ids the app should have. */
+  indexers: string[];
+}
+
+/**
+ * Bring the app's jackett feeds in line: every one the mesh manages is pointed at the bound jackett
+ * with its key, and every listed jackett indexer the app lacks is registered.
+ */
+export async function reconcileIndexers(
+  http: Http,
+  app: App,
+  ep: Endpoint,
+  configured: Map<string, string>,
+  settings: IndexerSettings,
+  remembered: string[],
+  entries: Entry[],
+): Promise<Outcome[]> {
+  const ours = new Set([ep.host, ...settings.adoptHosts, ...remembered].map((h) => h.trim().toLowerCase()).filter(Boolean));
+  const outcomes: Outcome[] = [];
+  const managed = new Set<string>();
+  for (const e of entries) {
+    const feed = jackettFeed(e);
+    if (!feed || !ours.has(feed.host)) continue;
+    managed.add(feed.id);
+    const what = `jackett-api ("${e.name}", jackett indexer ${feed.id})`;
+    const known = feed.id === "all" || configured.has(feed.id);
+    const outcome = await reconcileEntry(
+      http, app, "indexer", what, e, feedConnection(ep, feed.id), feedDiffers(e, ep, feed.id), "apiKey", ep.credential, known,
+    );
+    outcomes.push(outcome);
+    if (!known && outcome.result !== "refused") {
+      outcomes.push({ what, result: "notice", note: `jackett has no indexer "${feed.id}" configured, so it was not tested; configure it in jackett or remove the entry in ${app.module}` });
+    }
+  }
+  for (const id of settings.indexers) {
+    if (managed.has(id)) continue;
+    const what = `jackett-api (jackett indexer ${id})`;
+    if (id !== "all" && !configured.has(id)) {
+      outcomes.push({ what, result: "refused", problem: `downloads.jackett-api.indexers lists "${id}", and jackett has no indexer by that id configured` });
+      continue;
+    }
+    const name = `Jackett - ${id === "all" ? "all" : configured.get(id)}`;
+    outcomes.push(await createEntry(http, app, "indexer", what, "Torznab", name, { ...feedConnection(ep, id), apiKey: ep.credential }));
+  }
+  if (outcomes.length === 0) {
+    outcomes.push({ what: "jackett-api", result: "notice", note: `${app.module} has no jackett feed the mesh manages, and downloads.jackett-api.indexers lists none to register` });
+  }
+  return outcomes;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Files
+
+/** The module's settings for this step, from its merged `downloads.json`. */
+export interface StepSettings {
+  node: string;
+  names: Record<string, string>;
+  indexers: IndexerSettings;
+}
+
+export function stepSettings(raw: unknown): StepSettings {
+  const doc = (raw ?? {}) as Record<string, unknown>;
+  const d = (doc.downloads ?? {}) as Record<string, Record<string, unknown> | undefined>;
+  const names: Record<string, string> = {};
+  for (const k of CLIENTS) {
+    const n = d[k.provision]?.name;
+    names[k.provision] = typeof n === "string" && n.trim() ? n.trim() : k.provision.replace(/-api$/, "");
+  }
+  const j = d[JACKETT] ?? {};
+  const strings = (v: unknown) => (Array.isArray(v) ? v.filter((x): x is string => typeof x === "string" && x.trim() !== "").map((x) => x.trim()) : []);
+  return {
+    node: typeof doc.node === "string" ? doc.node : "",
+    names,
+    indexers: { adoptHosts: strings(j["adopt-hosts"]), indexers: strings(j.indexers) },
+  };
+}
+
+/** The app's own key and base path, from its config.xml. */
+export function appConfig(xml: string): { apiKey: string; urlBase: string } {
+  const tag = (t: string) => new RegExp(`<${t}>([^<]*)</${t}>`).exec(xml)?.[1]?.trim() ?? "";
+  return { apiKey: tag("ApiKey"), urlBase: normBase(tag("UrlBase")) };
+}
+
+/** A file the mesh wrote, or undefined when it is not there. */
+export async function readIfThere(path: string | undefined): Promise<string | undefined> {
+  if (!path) return undefined;
+  return readFile(path, "utf8").catch(() => undefined);
+}
+
+/** A JSON file parsed, or undefined when absent or not JSON. */
+export async function readJson(path: string | undefined): Promise<unknown> {
+  const raw = await readIfThere(path);
+  if (raw === undefined) return undefined;
+  try {
+    return JSON.parse(raw) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Wait for the app to answer, because the step runs right after its container starts. */
+export async function appReady(http: Http, app: App, waitMs: number, pauseMs = 2000): Promise<boolean> {
+  const until = Date.now() + waitMs;
+  for (;;) {
+    try {
+      const a = await appCall(http, app, "GET", "/system/status");
+      if (a.status === 200) return true;
+    } catch {
+      // not listening yet
+    }
+    if (Date.now() >= until) return false;
+    await new Promise((r) => setTimeout(r, pauseMs));
+  }
+}
+
+export async function listEntries(http: Http, app: App, resource: "downloadclient" | "indexer"): Promise<Entry[]> {
+  return ((await appGet(http, app, `/${resource}`)) as Entry[]) ?? [];
+}
+
+/** Anything printed goes through this: the credentials the step holds never reach a log. */
+export function scrub(text: string, secrets: string[]): string {
+  let out = text;
+  for (const s of secrets) if (s && s.length >= 4) out = out.split(s).join("<redacted>");
+  return out;
+}
+
+function message(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

modules/lidarr/module.json

@@ -1,6 +1,19 @@
 {
   "module": "lidarr",
   "version": "1",
+  "provides": [
+    {
+      "name": "lidarr-api",
+      "scope": "mesh"
+    }
+  ],
+  "serves": {
+    "lidarr-api": {
+      "scheme": "http",
+      "port": 8686,
+      "url-base": ""
+    }
+  },
   "capabilities": [
     "container-runtime"
   ],
@@ -14,6 +27,7 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 8686,
       "protocol": "tcp",
       "from": "mesh",
@@ -37,18 +51,33 @@
       "path": "/var/lib/mesh/lidarr",
       "mode": "0700"
     },
+    {
+      "id": "state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "."
+    },
     {
       "id": "config",
       "type": "directory",
-      "path": "/services/lidarr/config",
       "mode": "0700",
       "owner": "1000:1000"
     },
+    {
+      "id": "custom-cont-init",
+      "type": "directory",
+      "mode": "0755"
+    },
+    {
+      "id": "custom-services",
+      "type": "directory",
+      "mode": "0755"
+    },
     {
       "id": "server",
       "type": "container",
       "name": "lidarr",
-      "image": "lscr.io/linuxserver/lidarr@sha256:6b38dd330b0c653351c2e23c8b962ea51c95683dd7acace9d106c922baf85f75",
+      "image": "lscr.io/linuxserver/lidarr@sha256:8ab0fd370b604ae034d9a9c261a9d8d873bece33d9736852e7ce4f3566e4a35d",
       "env": {
         "PUID": "1000",
         "PGID": "1000",
@@ -58,7 +87,9 @@
         "8686"
       ],
       "volumes": [
-        "/services/lidarr/config:/config",
+        "${dir:config}:/config",
+        "${dir:custom-cont-init}:/custom-cont-init.d",
+        "${dir:custom-services}:/custom-services.d",
         "/services/media/music:/music",
         "/services/media/downloads:/downloads"
       ]
@@ -70,27 +101,92 @@
       "network": "host",
       "volumes": [
         "/var/lib/mesh/lidarr/broker:/run/secrets/broker:ro",
-        "/services/lidarr/config:/var/lib/lidarr/config:ro"
+        "${dir:config}:/var/lib/lidarr/config:ro"
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_LIDARR_URL": "http://127.0.0.1:8686",
+        "MESH_LIDARR_URL": "http://127.0.0.1:${port:8686}",
         "MESH_LIDARR_CONFIG_DIR": "/var/lib/lidarr/config"
       },
       "artifact": "runtime"
+    },
+    {
+      "id": "downloads-config",
+      "type": "file",
+      "path": "${dir:state}/downloads.json",
+      "mode": "0600",
+      "content": "{\n  \"node\": \"${machine:name}\",\n  \"downloads\": {\n    \"nzbget-api\": {\n      \"name\": \"nzbget\"\n    },\n    \"qbittorrent-api\": {\n      \"name\": \"qbittorrent\"\n    },\n    \"jackett-api\": {\n      \"adopt-hosts\": [],\n      \"indexers\": []\n    }\n  }\n}\n",
+      "merge": "json"
+    },
+    {
+      "id": "downloads-memory",
+      "type": "directory",
+      "mode": "0700"
+    },
+    {
+      "id": "downloads",
+      "type": "container",
+      "name": "mesh-lidarr-downloads",
+      "network": "host",
+      "run-once": true,
+      "volumes": [
+        "${dir:state}/downloads.json:/run/downloads/downloads.json:ro",
+        "${dir:state}/nzbget-api.json:/run/downloads/nzbget-api.json:ro",
+        "${dir:state}/nzbget-api.secret:/run/downloads/nzbget-api.secret:ro",
+        "${dir:state}/qbittorrent-api.json:/run/downloads/qbittorrent-api.json:ro",
+        "${dir:state}/qbittorrent-api.secret:/run/downloads/qbittorrent-api.secret:ro",
+        "${dir:state}/jackett-api.json:/run/downloads/jackett-api.json:ro",
+        "${dir:state}/jackett-api.secret:/run/downloads/jackett-api.secret:ro",
+        "${dir:config}:/var/lib/lidarr/config:ro",
+        "${dir:downloads-memory}:/var/lib/downloads"
+      ],
+      "env": {
+        "MESH_DOWNLOADS_APP": "lidarr",
+        "MESH_DOWNLOADS_API": "v1",
+        "MESH_DOWNLOADS_APP_URL": "http://127.0.0.1:${port:8686}",
+        "MESH_DOWNLOADS_APP_CONFIG": "/var/lib/lidarr/config/config.xml",
+        "MESH_DOWNLOADS_DIR": "/run/downloads",
+        "MESH_DOWNLOADS_SETTINGS": "/run/downloads/downloads.json",
+        "MESH_DOWNLOADS_MEMORY": "/var/lib/downloads/memory.json"
+      },
+      "args": [
+        "run",
+        "/app/modules/lidarr/dist/downloads/index.js"
+      ],
+      "restart-on": [
+        "downloads-config",
+        "bound-nzbget-api",
+        "secret-nzbget-api",
+        "bound-qbittorrent-api",
+        "secret-qbittorrent-api",
+        "bound-jackett-api",
+        "secret-jackett-api"
+      ],
+      "artifact": "runtime"
     }
   ],
   "requires": [
+    "jackett-api",
+    "nzbget-api",
+    "qbittorrent-api",
     "route"
   ],
   "contributes": {
     "route": {
       "label": "lidarr",
-      "port": 8686
+      "endpoint": "web"
     }
   },
   "binds": {
-    "route": "/var/lib/mesh/lidarr/route.json"
+    "route": "${dir:state}/route.json",
+    "nzbget-api": "${dir:state}/nzbget-api.json",
+    "qbittorrent-api": "${dir:state}/qbittorrent-api.json",
+    "jackett-api": "${dir:state}/jackett-api.json"
+  },
+  "secrets": {
+    "nzbget-api": "${dir:state}/nzbget-api.secret",
+    "qbittorrent-api": "${dir:state}/qbittorrent-api.secret",
+    "jackett-api": "${dir:state}/jackett-api.secret"
   },
   "build": {
     "on": [

modules/lidarr/package.json

@@ -4,6 +4,11 @@
   "description": "lidarr — music management. Its API client, tools and events live here (novox/hq ADR 0039).",
   "type": "module",
   "private": true,
+  "scripts": {
+    "build": "tsc client.ts index.ts tools/index.ts downloads/settings.ts downloads/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test --experimental-strip-types 'test/*.test.ts'"
+  },
   "dependencies": {
     "@novox/mesh-sdk": "^0.1.0"
   },

modules/lidarr/test/downloads.test.ts

@@ -0,0 +1,365 @@
+// What holds the downloads step (downloads/settings.ts): the app's download clients and jackett
+// feeds are made to say what the mesh bound — host, port, TLS, base path, user, credential — and
+// nothing else they keep is touched; only the mesh's entries are touched, and nothing is ever
+// deleted; nothing is written when nothing differs; a missing one is registered; and a credential
+// the provider refuses (the mesh's own minted value, before the operator accepts the provider's)
+// is never written, with the `secret accept` that fixes it named.
+//
+// The app and the providers are fakes: the routes the step touches, answering as the real ones do
+// (checked against the catalogue's pinned sonarr, radarr, lidarr, bookshelf, nzbget, qBittorrent
+// and jackett): the app masks a stored password as "********", tests an enabled entry before
+// saving it, refuses a warning unless forceSave, and jackett answers a wrong key 200 with an error.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  CLIENTS,
+  acceptRemedy,
+  jackettFeed,
+  providerTakes,
+  reconcileClient,
+  reconcileIndexers,
+  stepSettings,
+  wanted,
+  type App,
+  type Binding,
+  type Endpoint,
+  type Entry,
+  type Http,
+} from "../downloads/settings.ts";
+
+const NZBGET = CLIENTS.find((c) => c.provision === "nzbget-api")!;
+const QBIT = CLIENTS.find((c) => c.provision === "qbittorrent-api")!;
+const APP: App = { module: "sonarr", url: "http://127.0.0.1:8989", apiKey: "app-key", api: "v3" };
+const MASK = "********";
+
+interface Provider {
+  host: string;
+  port: number;
+  user?: string;
+  secret: string;
+  configured?: Record<string, string>;
+}
+
+const nzbget: Provider = { host: "ace.internal", port: 20201, user: "luffy", secret: "nzb-real" };
+const qbit: Provider = { host: "ace.internal", port: 8112, user: "luffy", secret: "qbt-real" };
+const jackett: Provider = { host: "ace.internal", port: 20204, secret: "jackett-real", configured: { rutracker: "RuTracker", torrent9: "Torrent9" } };
+
+function binding(p: Provider, provision: string, extra: Record<string, unknown> = {}): Binding {
+  return {
+    provision,
+    from: "ace",
+    at: p.host,
+    as: "mesh_ace_sonarr",
+    serves: { scheme: "http", port: p.port, "url-base": "", ...(p.user ? { username: p.user } : {}), ...extra },
+  };
+}
+
+function endpoint(p: Provider, provision: string, credential = p.secret): Endpoint {
+  const w = wanted(provision, binding(p, provision), credential, provision !== "jackett-api");
+  if (!w.ok) throw new Error(w.problem);
+  return w.endpoint;
+}
+
+const f = (name: string, value: unknown) => ({ name, value });
+
+function client(id: number, name: string, implementation: string, host: string, port: number, password: string, extra: Record<string, unknown> = {}): Entry {
+  return {
+    id, name, implementation, enable: true, priority: 1, tags: [],
+    fields: [f("host", host), f("port", port), f("useSsl", false), f("urlBase", null), f("username", "luffy"), f("password", password), f("tvCategory", "Series"), ...Object.entries(extra).map(([k, v]) => f(k, v))],
+  };
+}
+
+function feed(id: number, name: string, baseUrl: string, jid: string, key: string, on = true): Entry {
+  return {
+    id, name, implementation: "Torznab", enableRss: on, enableAutomaticSearch: on, enableInteractiveSearch: on, priority: 25,
+    fields: [f("baseUrl", baseUrl), f("apiPath", `/api/v2.0/indexers/${jid}/results/torznab/`), f("apiKey", key), f("categories", [5000])],
+  };
+}
+
+interface Call {
+  method: string;
+  url: string;
+  body?: unknown;
+}
+
+/** A Servarr app and the three providers behind one fetch. */
+function fakes(start: { clients?: Entry[]; indexers?: Entry[] }) {
+  const calls: Call[] = [];
+  const store: Record<string, Entry[]> = {
+    downloadclient: structuredClone(start.clients ?? []),
+    indexer: structuredClone(start.indexers ?? []),
+  };
+  let next = 100;
+  const secretOf: Record<string, string> = { downloadclient: "password", indexer: "apiKey" };
+  const masked = (e: Entry): Entry => ({ ...e, fields: e.fields!.map((x) => (x.name === "password" || x.name === "apiKey") && x.value ? { ...x, value: MASK } : { ...x }) });
+  const val = (e: Entry, n: string) => e.fields?.find((x) => x.name === n)?.value;
+
+  /** What the app's own test says: dialled from its container, with its stored secret for a mask. */
+  const appTest = (kind: string, e: Entry): { propertyName: string; errorMessage: string; isWarning: boolean }[] => {
+    let secret = val(e, secretOf[kind]);
+    if (secret === MASK) secret = val(store[kind].find((s) => s.id === e.id) ?? {}, secretOf[kind]);
+    if (kind === "downloadclient") {
+      const p = e.implementation === "Nzbget" ? nzbget : qbit;
+      if (val(e, "host") !== p.host || val(e, "port") !== p.port) return [{ propertyName: "Host", errorMessage: "Unable to connect", isWarning: false }];
+      if (secret !== p.secret || val(e, "username") !== p.user) return [{ propertyName: "Username", errorMessage: "Authentication Failure", isWarning: false }];
+      if (val(e, "tvCategory") === "") return [{ propertyName: "TvCategory", errorMessage: "A category is recommended", isWarning: true }];
+      if (e.implementation === "Nzbget" && val(e, "tvCategory") === "tv") return [{ propertyName: "TvCategory", errorMessage: "Category does not exist", isWarning: false }];
+      return [];
+    }
+    const u = new URL(String(val(e, "baseUrl")));
+    if (u.hostname !== jackett.host || Number(u.port) !== jackett.port) return [{ propertyName: "BaseUrl", errorMessage: "Unable to connect", isWarning: false }];
+    if (secret !== jackett.secret) return [{ propertyName: "ApiKey", errorMessage: "Invalid API Key", isWarning: false }];
+    const id = /indexers\/([^/]+)\//.exec(String(val(e, "apiPath")))?.[1] ?? "";
+    if (!(id in jackett.configured!)) return [{ propertyName: "", errorMessage: "Unknown indexer", isWarning: false }];
+    return [];
+  };
+
+  const http: Http = {
+    async fetch(url, init) {
+      const method = init?.method ?? "GET";
+      const body = init?.body && init.headers?.["Content-Type"] === "application/json" ? (JSON.parse(init.body) as Entry) : init?.body;
+      calls.push({ method, url, body });
+      const reply = (status: number, value?: unknown) => ({ status, text: async () => (value === undefined ? "" : typeof value === "string" ? value : JSON.stringify(value)) });
+      const u = new URL(url);
+      // Providers.
+      if (u.pathname === "/jsonrpc/version") {
+        const want = "Basic " + Buffer.from(`${nzbget.user}:${nzbget.secret}`).toString("base64");
+        return init?.headers?.Authorization === want ? reply(200, { result: "26.0" }) : reply(401);
+      }
+      if (u.pathname === "/api/v2/auth/login") {
+        const form = new URLSearchParams(String(init?.body ?? ""));
+        return form.get("username") === qbit.user && form.get("password") === qbit.secret ? reply(204) : reply(401, "Unauthorized");
+      }
+      if (u.pathname.endsWith("/torznab/api")) {
+        if (u.searchParams.get("apikey") !== jackett.secret) return reply(200, '<?xml version="1.0"?><error code="100" description="Invalid API Key" />');
+        const items = Object.entries(jackett.configured!).map(([id, t]) => `<indexer id="${id}" configured="true"><title>${t}</title></indexer>`).join("");
+        return reply(200, `<?xml version="1.0"?><indexers>${items}</indexers>`);
+      }
+      // The app.
+      if (init?.headers?.["X-Api-Key"] !== APP.apiKey) return reply(401);
+      const m = /^\/api\/v3\/(downloadclient|indexer)(?:\/(schema|test|\d+))?$/.exec(u.pathname);
+      if (!m) return reply(404);
+      const [, kind, sub] = m;
+      const force = u.searchParams.get("forceSave") === "true";
+      if (method === "GET" && !sub) return reply(200, store[kind].map(masked));
+      if (method === "GET" && sub === "schema") {
+        return reply(200, kind === "downloadclient"
+          ? [client(0, "", "Nzbget", "localhost", 6789, MASK, {}), client(0, "", "QBittorrent", "localhost", 8080, "", {})].map((e) => ({ ...e, fields: e.fields!.map((x) => x.name === "tvCategory" ? { ...x, value: e.implementation === "Nzbget" ? "tv" : "tv-sonarr" } : x.name === "username" ? { ...x, value: null } : x) }))
+          : [{ ...feed(0, "", "", "x", "", false), supportsRss: true, supportsSearch: true, fields: [f("baseUrl", null), f("apiPath", "/api"), f("apiKey", null), f("categories", [5030, 5040])] }]);
+      }
+      if (method === "GET") {
+        const e = store[kind].find((s) => s.id === Number(sub));
+        return e ? reply(200, masked(e)) : reply(404);
+      }
+      if (method === "POST" && sub === "test") {
+        const fails = appTest(kind, body as Entry);
+        return fails.length ? reply(400, fails) : reply(200);
+      }
+      // Save: tested when enabled; a mask keeps what is stored.
+      const e = body as Entry;
+      const on = e.enable === true || e.enableRss === true || e.enableAutomaticSearch === true;
+      if (on) {
+        const fails = appTest(kind, e);
+        if (fails.some((x) => !x.isWarning) || (fails.length && !force)) return reply(400, fails);
+      }
+      if (method === "POST" && !sub) {
+        if (store[kind].some((s) => String(s.name).toLowerCase() === String(e.name).toLowerCase())) {
+          return reply(400, [{ propertyName: "Name", errorMessage: "Should be unique", isWarning: false }]);
+        }
+        const created = { ...e, id: next++ };
+        store[kind].push(created);
+        return reply(201, masked(created));
+      }
+      if (method === "PUT") {
+        const i = store[kind].findIndex((s) => s.id === Number(sub));
+        if (i < 0) return reply(404);
+        const was = store[kind][i];
+        store[kind][i] = { ...e, fields: e.fields!.map((x) => x.value === MASK ? { ...x, value: val(was, x.name) } : x) };
+        return reply(202, masked(store[kind][i]));
+      }
+      return reply(405);
+    },
+  };
+  const saves = () => calls.filter((c) => (c.method === "PUT" || (c.method === "POST" && !c.url.endsWith("/test"))) && c.url.includes("/api/v3/"));
+  return { http, calls, store, saves };
+}
+
+const aceClients = () => [
+  client(1, "NZBGet", "Nzbget", "nzbget", 6789, "nzb-real"),
+  client(2, "qBitTorrent", "QBittorrent", "qbittorrent", 8112, "qbt-real"),
+];
+
+test("the migration's download client is repointed, its category and everything else kept", async () => {
+  const f = fakes({ clients: aceClients() });
+  const out = await reconcileClient(f.http, APP, NZBGET, "NZBGet", endpoint(nzbget, "nzbget-api"), f.store.downloadclient.map((e) => ({ ...e })));
+  assert.deepEqual(out, [{ what: 'nzbget-api ("NZBGet")', result: "written", fields: ["host", "port"] }]);
+  const saved = f.store.downloadclient.find((e) => e.id === 1)!;
+  const v = (n: string) => saved.fields!.find((x) => x.name === n)?.value;
+  assert.equal(v("host"), "ace.internal");
+  assert.equal(v("port"), 20201);
+  assert.equal(v("tvCategory"), "Series");
+  assert.equal(v("password"), "nzb-real", "the password it held works, so it was kept, not rewritten");
+  assert.equal(saved.priority, 1);
+});
+
+test("rerun: already as the mesh says, nothing saved", async () => {
+  const f = fakes({ clients: [client(1, "NZBGet", "Nzbget", "ace.internal", 20201, "nzb-real")] });
+  const out = await reconcileClient(f.http, APP, NZBGET, "NZBGet", endpoint(nzbget, "nzbget-api"), f.store.downloadclient);
+  assert.deepEqual(out, [{ what: 'nzbget-api ("NZBGet")', result: "unchanged" }]);
+  assert.equal(f.saves().length, 0);
+});
+
+test("a stale password is replaced by the delivered one, which the provider took first", async () => {
+  const f = fakes({ clients: [client(2, "qBitTorrent", "QBittorrent", "ace.internal", 8112, "old-pass")] });
+  const out = await reconcileClient(f.http, APP, QBIT, "qBitTorrent", endpoint(qbit, "qbittorrent-api"), f.store.downloadclient);
+  assert.deepEqual(out, [{ what: 'qbittorrent-api ("qBitTorrent")', result: "written", fields: ["password"] }]);
+  assert.equal(f.store.downloadclient[0].fields!.find((x) => x.name === "password")?.value, "qbt-real");
+});
+
+test("a minted credential is refused by the provider: nothing written, the accept named", async () => {
+  const f = fakes({ clients: aceClients() });
+  const ep = endpoint(nzbget, "nzbget-api", "a-value-the-mesh-minted");
+  assert.deepEqual(await providerTakes(f.http, "nzbget-api", ep), { took: false });
+  const remedy = acceptRemedy(APP, "ace", "nzbget-api", "nzbget", "ControlPassword", ep.from);
+  assert.match(remedy, /`secret accept ace sonarr nzbget-api --provider ace --from <file holding nzbget's ControlPassword>`/);
+  assert.doesNotMatch(remedy, /minted/);
+  assert.equal(f.calls.some((c) => c.url.includes("/api/v3/")), false, "the app was not even asked");
+  const q = endpoint(qbit, "qbittorrent-api", "minted");
+  assert.deepEqual(await providerTakes(f.http, "qbittorrent-api", q), { took: false });
+  const j = endpoint(jackett, "jackett-api", "minted");
+  assert.deepEqual(await providerTakes(f.http, "jackett-api", j), { took: false });
+  assert.equal(f.calls.find((c) => c.url.includes("apikey="))?.url.includes("jackett-real"), false);
+});
+
+test("a fresh app gets the mesh's client registered, under the mesh's name", async () => {
+  const f = fakes({});
+  const out = await reconcileClient(f.http, APP, QBIT, "qbittorrent", endpoint(qbit, "qbittorrent-api"), []);
+  assert.equal(out[0].result, "created");
+  const e = f.store.downloadclient[0];
+  assert.equal(e.name, "qbittorrent");
+  assert.equal(e.enable, true);
+  assert.equal(e.fields!.find((x) => x.name === "tvCategory")?.value, "tv-sonarr", "the app's own default category");
+});
+
+test("nzbget without the app's default category: registered with none, and said", async () => {
+  const f = fakes({});
+  const out = await reconcileClient(f.http, APP, NZBGET, "nzbget", endpoint(nzbget, "nzbget-api"), []);
+  assert.equal(out[0].result, "notice");
+  assert.match((out[0] as { note: string }).note, /category left empty/);
+  assert.equal(f.store.downloadclient[0].fields!.find((x) => x.name === "tvCategory")?.value, "");
+});
+
+test("somebody else's entries are never touched: another name of the same kind, and a clash of names", async () => {
+  const mine = client(7, "My seedbox", "QBittorrent", "seedbox.example", 443, "theirs");
+  const f = fakes({ clients: [mine] });
+  const out = await reconcileClient(f.http, APP, QBIT, "qbittorrent", endpoint(qbit, "qbittorrent-api"), f.store.downloadclient);
+  assert.equal(out[0].result, "notice");
+  assert.deepEqual(f.store.downloadclient.find((e) => e.id === 7), mine);
+  // Same name in another case: refused, and the setting that adopts it named.
+  const g = fakes({ clients: aceClients() });
+  const clash = await reconcileClient(g.http, APP, NZBGET, "nzbget", endpoint(nzbget, "nzbget-api"), g.store.downloadclient);
+  assert.equal(clash[0].result, "refused");
+  assert.match((clash[0] as { problem: string }).problem, /downloads\.nzbget-api\.name to "NZBGet"/);
+  assert.equal(g.saves().length, 0);
+});
+
+test("jackett feeds: the migration's are repointed, a person's is left, a listed one is registered", async () => {
+  const personal = feed(9, "Seedbox jackett", "https://jackett.seedbox.example", "rutracker", "their-key");
+  const f = fakes({
+    indexers: [
+      feed(5, "Torznab - RuTracker", "https://indexers.zurag.be", "rutracker-ru", "jackett-real", false),
+      feed(6, "Torznab - Torrent9", "https://indexers.zurag.be", "torrent9", "jackett-real", false),
+      feed(4, "Jackett - RARBG", "http://jackett:9117", "therarbg", "old", false),
+      personal,
+    ],
+  });
+  const configured = new Map(Object.entries(jackett.configured!));
+  const out = await reconcileIndexers(
+    f.http, APP, endpoint(jackett, "jackett-api"), configured,
+    { adoptHosts: ["indexers.zurag.be", "jackett"], indexers: ["rutracker"] }, [], f.store.indexer,
+  );
+  const byWhat = Object.fromEntries(out.map((o) => [o.what + ":" + o.result, o]));
+  // torrent9: jackett has it; repointed, key already right, tested.
+  assert.ok(byWhat['jackett-api ("Torznab - Torrent9", jackett indexer torrent9):written']);
+  // rutracker-ru and therarbg: jackett has neither — repointed with the key, untested, and said.
+  assert.ok(byWhat['jackett-api ("Jackett - RARBG", jackett indexer therarbg):written']);
+  assert.ok(byWhat['jackett-api ("Jackett - RARBG", jackett indexer therarbg):notice']);
+  // rutracker is listed and nothing of the mesh's reads it: registered.
+  assert.ok(byWhat["jackett-api (jackett indexer rutracker):created"]);
+  assert.deepEqual(f.store.indexer.find((e) => e.id === 9), personal, "a person's jackett is not the mesh's");
+  const t9 = f.store.indexer.find((e) => e.id === 6)!;
+  assert.equal(t9.fields!.find((x) => x.name === "baseUrl")?.value, "http://ace.internal:20204");
+  assert.equal(t9.enableRss, false, "disabled stays disabled");
+  const created = f.store.indexer.find((e) => e.name === "Jackett - RuTracker")!;
+  assert.equal(created.enableRss, true);
+  assert.equal(f.calls.some((c) => c.method === "DELETE"), false, "nothing is ever deleted");
+});
+
+test("jackett feeds rerun: nothing saved, and a remembered host keeps a moved jackett's feeds", async () => {
+  const f = fakes({ indexers: [feed(6, "Torznab - Torrent9", "http://ace.internal:20204", "torrent9", "jackett-real")] });
+  const configured = new Map(Object.entries(jackett.configured!));
+  const out = await reconcileIndexers(f.http, APP, endpoint(jackett, "jackett-api"), configured, { adoptHosts: [], indexers: ["torrent9"] }, [], f.store.indexer);
+  assert.deepEqual(out.map((o) => o.result), ["unchanged"]);
+  assert.equal(f.saves().length, 0);
+  // jackett moved to novox: the feed on ace.internal is still the mesh's because it was remembered.
+  const moved = { ...jackett, host: "novox.internal" };
+  const g = fakes({ indexers: [feed(6, "Torznab - Torrent9", "http://ace.internal:20204", "torrent9", "jackett-real")] });
+  const saved = jackett.host;
+  jackett.host = moved.host;
+  try {
+    const again = await reconcileIndexers(g.http, APP, endpoint(moved, "jackett-api"), configured, { adoptHosts: [], indexers: [] }, ["ace.internal"], g.store.indexer);
+    assert.equal(again[0].result, "written");
+    assert.equal(g.store.indexer[0].fields!.find((x) => x.name === "baseUrl")?.value, "http://novox.internal:20204");
+  } finally {
+    jackett.host = saved;
+  }
+});
+
+test("an enabled entry the app cannot test at the mesh's address is not saved", async () => {
+  const f = fakes({ clients: [client(1, "NZBGet", "Nzbget", "nzbget", 6789, "nzb-real")] });
+  const elsewhere = { ...nzbget, port: 1 };
+  const out = await reconcileClient(f.http, APP, NZBGET, "NZBGet", endpoint(elsewhere, "nzbget-api"), f.store.downloadclient);
+  assert.equal(out[0].result, "refused");
+  assert.equal(f.store.downloadclient[0].fields!.find((x) => x.name === "host")?.value, "nzbget", "left as it was");
+});
+
+test("bindings: loopback, no user, no credential are refused; the base path is normalised", () => {
+  assert.equal(wanted("nzbget-api", { ...binding(nzbget, "nzbget-api"), at: "127.0.0.1" }, "x", true).ok, false);
+  assert.equal(wanted("nzbget-api", binding({ ...nzbget, user: undefined }, "nzbget-api"), "x", true).ok, false);
+  assert.equal(wanted("nzbget-api", binding(nzbget, "nzbget-api"), "  \n", true).ok, false);
+  const w = wanted("jackett-api", binding(jackett, "jackett-api", { "url-base": "jackett/" }), "k", false);
+  assert.equal(w.ok && w.endpoint.urlBase, "/jackett");
+});
+
+test("a feed is read whole: base path in the base URL or in the API path", () => {
+  const e = feed(1, "x", "http://ace.internal:9117/jackett", "rutracker", "k");
+  assert.deepEqual(jackettFeed(e), { host: "ace.internal", id: "rutracker" });
+  assert.equal(jackettFeed({ ...e, implementation: "Newznab" }), undefined);
+  assert.equal(jackettFeed({ ...e, fields: [f("baseUrl", "https://api.nzbgeek.info"), f("apiPath", "/api")] }), undefined);
+});
+
+test("settings: names default to the provider's, adoption and registration read from the merged file", () => {
+  assert.deepEqual(stepSettings({ node: "ace" }), { node: "ace", names: { "nzbget-api": "nzbget", "qbittorrent-api": "qbittorrent" }, indexers: { adoptHosts: [], indexers: [] } });
+  const s = stepSettings({ node: "ace", downloads: { "nzbget-api": { name: "NZBGet" }, "jackett-api": { "adopt-hosts": ["jackett"], indexers: ["torrent9", 3] } } });
+  assert.equal(s.names["nzbget-api"], "NZBGet");
+  assert.deepEqual(s.indexers, { adoptHosts: ["jackett"], indexers: ["torrent9"] });
+});
+
+// The four copies are one step. Where the siblings are checked out beside this module, they must
+// be byte-identical — a fix made in one and not the others is a bug in three apps.
+test("the step is the same in sonarr, radarr, lidarr and bookshelf", () => {
+  const here = dirname(dirname(fileURLToPath(import.meta.url)));
+  const modules = dirname(here);
+  for (const file of ["downloads/settings.ts", "downloads/index.ts", "test/downloads.test.ts"]) {
+    const mine = readFileSync(join(here, file), "utf8");
+    for (const sibling of ["sonarr", "radarr", "lidarr", "bookshelf"]) {
+      const theirs = join(modules, sibling, file);
+      if (existsSync(theirs)) assert.equal(readFileSync(theirs, "utf8"), mine, `${sibling}/${file} differs`);
+    }
+  }
+});

modules/lidarr/tsconfig.json

@@ -8,5 +8,5 @@
     "skipLibCheck": true,
     "noEmit": true
   },
-  "include": ["client.ts", "index.ts", "tools/index.ts"]
+  "include": ["client.ts", "index.ts", "tools/index.ts", "downloads/settings.ts", "downloads/index.ts"]
 }

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
-// is the same arrangement model-usage uses: a schema step that had to reach the provider over the
-// overlay would block the very apply that brings the overlay up.
-await graph.migrate();
+// The schema is not brought up here. The mesh prepares this module's state before it starts this
+// version, and does not start it if that failed (novox/hq ADR 0135) — see prepare/index.ts. Doing it
+// at start made a schema that could not be reached a crash loop instead of a stop, with the graph
+// 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/Dockerfile

@@ -9,8 +9,11 @@
 #
 # Unlike every other module's Dockerfile, this builds no TypeScript and uses no mesh base image:
 # the module's code is the server, which upstream already built. There is no BUILD_BASE here on
-# purpose — nothing is compiled.
-FROM nats@sha256:b83efabe3e7def1e0a4a31ec6e078999bb17c80363f881df35edc70fcb6bb927
+# purpose — nothing is compiled. The upstream image is declared in the manifest under build.on and
+# arrives as NATS_BASE, like every other base the mesh copies into its own store before a build
+# (novox/hq ADR 0097); the digest above is the index one for the reason given.
+ARG NATS_BASE
+FROM ${NATS_BASE}
 
 COPY entrypoint.sh /usr/local/bin/mesh-nats-entrypoint
 RUN chmod 0755 /usr/local/bin/mesh-nats-entrypoint

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,18 +62,24 @@
       "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"
     }
   ],
   "build": {
+    "on": [
+      {
+        "arg": "NATS_BASE",
+        "image": "nats@sha256:b83efabe3e7def1e0a4a31ec6e078999bb17c80363f881df35edc70fcb6bb927"
+      }
+    ],
     "artifacts": [
       {
         "name": "server",

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",
@@ -80,7 +81,7 @@
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_NZBGET_URL": "http://127.0.0.1:6789",
+        "MESH_NZBGET_URL": "http://127.0.0.1:${port:6789}",
         "MESH_NZBGET_PASSWORD_FILE": "/run/secrets/password",
         "MESH_NZBGET_CONFIG_FILE": "/run/config/config.json",
         "MESH_NZBGET_CONFIG_DIR": "/var/lib/nzbget/config"

modules/ollama/module.json

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

modules/ombi/Dockerfile

@@ -13,7 +13,7 @@ ARG RUNTIME_BASE
 FROM ${BUILD_BASE} AS build
 WORKDIR /app/modules/ombi
 COPY . .
-RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
+RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts servarr/settings.ts servarr/index.ts \
       --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 
 FROM ${RUNTIME_BASE}
@@ -22,3 +22,6 @@ COPY --from=build /app/modules/ombi/dist /app/modules/ombi/dist
 # provider's provisioner runs its reconcile loop in the same process, with the broker connected —
 # the convention novox/hq issues 060/061 settled.
 ENV MESH_TOOL_MODULES=/app/modules/ombi/dist/index.js,/app/modules/ombi/dist/tools/index.js
+# NOT dist/servarr/index.js: that is a step the host runs to completion, named by the `servarr`
+# container's args as `mesh-tools run …` (novox/hq ADR 0052). Listed here it would run inside the
+# serving sidecar too, and exit it.

modules/ombi/module.json

@@ -14,6 +14,7 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 3579,
       "protocol": "tcp",
       "from": "mesh",
@@ -27,10 +28,15 @@
       "path": "/var/lib/mesh/ombi",
       "mode": "0700"
     },
+    {
+      "id": "state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "."
+    },
     {
       "id": "config",
       "type": "directory",
-      "path": "/services/ombi/config",
       "mode": "0700",
       "owner": "1000:1000"
     },
@@ -38,7 +44,7 @@
       "id": "server",
       "type": "container",
       "name": "ombi",
-      "image": "lscr.io/linuxserver/ombi@sha256:a6f76ac521ba01eee2e9f0c23a3fed22e56630d97a04d5eeaeaa36c1e681640d",
+      "image": "lscr.io/linuxserver/ombi@sha256:22d6ebadbaaa728571353e74dc2173719e0fb02d4eaec551a7e9d2ee99ef68ac",
       "env": {
         "PUID": "1000",
         "PGID": "1000",
@@ -48,7 +54,7 @@
         "3579"
       ],
       "volumes": [
-        "/services/ombi/config:/config"
+        "${dir:config}:/config"
       ]
     },
     {
@@ -67,33 +73,76 @@
       "volumes": [
         "/var/lib/mesh/ombi/broker:/run/secrets/broker:ro",
         "/var/lib/mesh/ombi/api-key:/run/secrets/api-key:ro",
-        "/var/lib/mesh/ombi/config.json:/run/config/config.json:ro",
-        "/services/ombi/config:/var/lib/ombi/config:ro"
+        "/var/lib/mesh/ombi/config.json:/run/config/config.json:ro"
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_OMBI_URL": "http://127.0.0.1:3579",
+        "MESH_OMBI_URL": "http://127.0.0.1:${port:3579}",
         "MESH_OMBI_API_KEY_FILE": "/run/secrets/api-key",
-        "MESH_OMBI_CONFIG_FILE": "/run/config/config.json",
-        "MESH_OMBI_CONFIG_DIR": "/var/lib/ombi/config"
+        "MESH_OMBI_CONFIG_FILE": "/run/config/config.json"
       },
       "restart-on": [
         "runtime-config"
       ],
       "artifact": "runtime"
+    },
+    {
+      "id": "servarr",
+      "type": "container",
+      "name": "mesh-ombi-servarr",
+      "network": "host",
+      "run-once": true,
+      "volumes": [
+        "/var/lib/mesh/ombi/api-key:/run/secrets/api-key:ro",
+        "${dir:state}/sonarr-api.json:/run/servarr/sonarr-api.json:ro",
+        "${dir:state}/sonarr-api.secret:/run/servarr/sonarr-api.secret:ro",
+        "${dir:state}/radarr-api.json:/run/servarr/radarr-api.json:ro",
+        "${dir:state}/radarr-api.secret:/run/servarr/radarr-api.secret:ro",
+        "${dir:state}/lidarr-api.json:/run/servarr/lidarr-api.json:ro",
+        "${dir:state}/lidarr-api.secret:/run/servarr/lidarr-api.secret:ro"
+      ],
+      "env": {
+        "MESH_OMBI_URL": "http://127.0.0.1:${port:3579}",
+        "MESH_OMBI_API_KEY_FILE": "/run/secrets/api-key",
+        "MESH_SERVARR_DIR": "/run/servarr"
+      },
+      "args": [
+        "run",
+        "/app/modules/ombi/dist/servarr/index.js"
+      ],
+      "restart-on": [
+        "bound-sonarr-api",
+        "secret-sonarr-api",
+        "bound-radarr-api",
+        "secret-radarr-api",
+        "bound-lidarr-api",
+        "secret-lidarr-api"
+      ],
+      "artifact": "runtime"
     }
   ],
   "requires": [
-    "route"
+    "lidarr-api",
+    "radarr-api",
+    "route",
+    "sonarr-api"
   ],
   "contributes": {
     "route": {
       "label": "ombi",
-      "port": 3579
+      "endpoint": "web"
     }
   },
   "binds": {
-    "route": "/var/lib/mesh/ombi/route.json"
+    "route": "${dir:state}/route.json",
+    "sonarr-api": "${dir:state}/sonarr-api.json",
+    "radarr-api": "${dir:state}/radarr-api.json",
+    "lidarr-api": "${dir:state}/lidarr-api.json"
+  },
+  "secrets": {
+    "sonarr-api": "${dir:state}/sonarr-api.secret",
+    "radarr-api": "${dir:state}/radarr-api.secret",
+    "lidarr-api": "${dir:state}/lidarr-api.secret"
   },
   "build": {
     "on": [

modules/ombi/package.json

@@ -4,6 +4,11 @@
   "description": "ombi — media requests. Its API client, tools and events live here (novox/hq ADR 0039).",
   "type": "module",
   "private": true,
+  "scripts": {
+    "build": "tsc client.ts index.ts tools/index.ts servarr/settings.ts servarr/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test --experimental-strip-types 'test/*.test.ts'"
+  },
   "dependencies": {
     "@novox/mesh-sdk": "^0.1.0"
   },

modules/ombi/servarr/index.ts

@@ -0,0 +1,59 @@
+// ombi's Servarr step — run once by the host after ombi's server starts, and run again whenever a
+// binding or pair credential it reads changes (the container's `restart-on`, novox/hq ADR 0099).
+//
+// **A step, not a loop**, for the reason route-adapter gives: everything it does is a function of
+// files the mesh writes, and the host already knows when they change. It connects to no broker.
+//
+// Exits non-zero when any app could not be put right — a refused credential, an unreachable app, an
+// ombi that cannot reach it — so the node reports the step failed and the host runs it again on the
+// next apply. It is declared last in the manifest, so its failing gates nothing else of ombi's
+// (novox/hq ADR 0136).
+//
+// Reads, per app, `<dir>/<provision>.json` (the binding) and `<dir>/<provision>.secret` (the pair
+// credential), where <dir> is MESH_SERVARR_DIR. Never prints a key.
+
+import { join } from "node:path";
+
+import { APPS, ombiReady, readBinding, readIfThere, reconcileApp, type Http } from "./settings.js";
+
+const dir = process.env.MESH_SERVARR_DIR ?? "/run/servarr";
+const url = process.env.MESH_OMBI_URL ?? "http://127.0.0.1:3579";
+const apiKey = (await readIfThere(process.env.MESH_OMBI_API_KEY_FILE))?.trim() ?? process.env.MESH_OMBI_API_KEY ?? "";
+const waitSeconds = Number(process.env.MESH_OMBI_WAIT_SECONDS ?? "180");
+
+const http: Http = { fetch: (u, init) => fetch(u, init) };
+
+if (!apiKey) {
+  console.error("[ombi-servarr] no ombi API key — ombi's own `api-key` secret has not been accepted");
+  process.exit(1);
+}
+const ombi = { url, apiKey };
+
+if (!(await ombiReady(http, ombi, waitSeconds * 1000))) {
+  console.error(`[ombi-servarr] ombi did not answer at ${url} within ${waitSeconds}s`);
+  process.exit(1);
+}
+
+let failed = 0;
+for (const spec of APPS) {
+  const outcome = await reconcileApp(
+    http,
+    ombi,
+    spec,
+    await readBinding(join(dir, `${spec.provision}.json`)),
+    await readIfThere(join(dir, `${spec.provision}.secret`)),
+  );
+  switch (outcome.result) {
+    case "unchanged":
+      console.log(`[ombi-servarr] ${outcome.app}: already as the mesh says; connection tested`);
+      break;
+    case "written":
+      console.log(`[ombi-servarr] ${outcome.app}: wrote ${outcome.fields.join(", ")}; connection tested`);
+      break;
+    case "refused":
+      failed++;
+      console.error(`[ombi-servarr] ${outcome.app}: ${outcome.problem}`);
+      break;
+  }
+}
+process.exitCode = failed > 0 ? 1 : 0;

modules/ombi/servarr/settings.ts

@@ -0,0 +1,304 @@
+// Where ombi reaches Sonarr, Radarr and Lidarr — decided by the mesh, written into ombi by ombi's
+// own API.
+//
+// **Why this exists.** ombi keeps its connection to each Servarr app in its own database
+// (OmbiSettings.db), not in a file, so the mesh has nowhere to write `${bound:sonarr-api:at}` for it.
+// ombi requires `sonarr-api`, `radarr-api` and `lidarr-api`; the mesh delivers, for each, a binding
+// (where the app is: `at`, and what it serves: `port`, `scheme`, `url-base`) and a pair credential
+// (the app's API key, accepted by the operator — a Servarr app has exactly one key and the mesh
+// cannot mint it). This step reads those files and makes ombi's settings say the same thing.
+//
+// **Only the connection, and only when it differs.** Host, port, TLS, base path and API key. The
+// quality profile, root folder, language profile, tags, "enabled" and every other choice an operator
+// made in ombi's settings screen are left exactly as they are: the mesh knows where the app is, not
+// what ombi should do with it. Radarr's 4K instance is a different Radarr and is not touched.
+//
+// **A credential the app refuses is never written.** Until the operator accepts the app's API key
+// for this pair, the mesh delivers a value it minted itself, which no Servarr app will ever accept
+// (novox/hq ADR 0092). Writing it would replace a working key in ombi with a dead one. So the key is
+// tried against the app first; refused, nothing for that app is written and the step fails naming
+// the `secret accept` that fixes it.
+//
+// Pure logic and a small HTTP seam, so it is tested against fake servers (test/servarr.test.ts).
+
+import { readFile } from "node:fs/promises";
+
+/** One Servarr app ombi connects to, and the shape of that connection in ombi's API. */
+export interface ServarrApp {
+  /** The app, as ombi's API names it: /Settings/<app>, /Tester/<app>. */
+  app: "sonarr" | "radarr" | "lidarr";
+  /** The provision it is required as — the manifest's `requires`, `binds` and `secrets` key. */
+  provision: string;
+  /** The app's own status endpoint, which answers 401 to a wrong key. */
+  statusPath: string;
+  /**
+   * Where the one connection sits in ombi's settings document. Radarr's is `{radarr, radarr4K}`
+   * (two Radarr instances); only `radarr` is this provision's.
+   */
+  within?: string;
+}
+
+export const APPS: readonly ServarrApp[] = [
+  { app: "sonarr", provision: "sonarr-api", statusPath: "/api/v3/system/status" },
+  { app: "radarr", provision: "radarr-api", statusPath: "/api/v3/system/status", within: "radarr" },
+  { app: "lidarr", provision: "lidarr-api", statusPath: "/api/v1/system/status" },
+];
+
+/** The connection fields ombi keeps for an app — the only ones this step ever writes. */
+export interface Connection {
+  ip: string;
+  port: number;
+  ssl: boolean;
+  /** ombi's name for the app's URL base; null when the app is served at the root. */
+  subDir: string | null;
+  apiKey: string;
+}
+
+/** What the mesh wrote at `binds.<provision>`: the binding document (controller's boundFile). */
+export interface Binding {
+  provision?: string;
+  from?: string;
+  at?: string;
+  as?: string;
+  serves?: Record<string, unknown>;
+}
+
+export type Wanted = { ok: true; connection: Connection; from: string } | { ok: false; problem: string };
+
+/**
+ * The connection the mesh says ombi should use, from the binding and the pair credential.
+ *
+ * Refused rather than guessed when the binding cannot be dialled from ombi's own container: a
+ * loopback `at` — what the mesh hands a machine that is not on the private network — is ombi's
+ * container itself, not the app.
+ */
+export function wanted(spec: ServarrApp, binding: Binding | undefined, credential: string | undefined): Wanted {
+  if (!binding) {
+    return { ok: false, problem: `no binding for ${spec.provision} was delivered — the mesh writes it before this step runs` };
+  }
+  const at = typeof binding.at === "string" ? binding.at.trim() : "";
+  const serves = binding.serves ?? {};
+  const port = Number(serves.port);
+  if (!at) {
+    return { ok: false, problem: `the ${spec.provision} binding names no host (at)` };
+  }
+  if (isLoopback(at)) {
+    return {
+      ok: false,
+      problem:
+        `the ${spec.provision} binding says ${spec.app} is at ${at}, which from ombi's own container is ` +
+        `ombi itself. The mesh hands loopback to a machine that is not on the private network; put it ` +
+        `on the private network so ${spec.app} has an address ombi can dial`,
+    };
+  }
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    return { ok: false, problem: `the ${spec.provision} binding serves no usable port (${String(serves.port)})` };
+  }
+  const scheme = typeof serves.scheme === "string" && serves.scheme ? serves.scheme : "http";
+  if (scheme !== "http" && scheme !== "https") {
+    return { ok: false, problem: `the ${spec.provision} binding serves scheme ${scheme}, which ombi cannot dial` };
+  }
+  const key = (credential ?? "").trim();
+  if (!key) {
+    return { ok: false, problem: `the ${spec.provision} credential is empty or was not delivered` };
+  }
+  return {
+    ok: true,
+    from: typeof binding.from === "string" ? binding.from : "",
+    connection: { ip: at, port, ssl: scheme === "https", subDir: subDirOf(serves["url-base"]), apiKey: key },
+  };
+}
+
+/** ombi's `subDir`: the URL base with its slashes trimmed, null when there is none. */
+export function subDirOf(urlBase: unknown): string | null {
+  const trimmed = typeof urlBase === "string" ? urlBase.trim().replace(/^\/+|\/+$/g, "") : "";
+  return trimmed === "" ? null : trimmed;
+}
+
+function isLoopback(host: string): boolean {
+  const h = host.toLowerCase();
+  return h === "localhost" || h === "::1" || h === "[::1]" || /^127\./.test(h);
+}
+
+/** Which connection fields differ between what ombi holds and what the mesh says. Names only. */
+export function differing(current: Record<string, unknown> | undefined, want: Connection): (keyof Connection)[] {
+  const now = current ?? {};
+  const out: (keyof Connection)[] = [];
+  if (String(now.ip ?? "") !== want.ip) out.push("ip");
+  if (Number(now.port ?? 0) !== want.port) out.push("port");
+  if (Boolean(now.ssl) !== want.ssl) out.push("ssl");
+  if (subDirOf(now.subDir) !== want.subDir) out.push("subDir");
+  if (String(now.apiKey ?? "") !== want.apiKey) out.push("apiKey");
+  return out;
+}
+
+/** ombi's settings for the app with the connection laid over them and nothing else changed. */
+export function withConnection(current: Record<string, unknown> | undefined, want: Connection): Record<string, unknown> {
+  return { ...(current ?? {}), ip: want.ip, port: want.port, ssl: want.ssl, subDir: want.subDir, apiKey: want.apiKey };
+}
+
+/** The app's base URL as the step dials it — the same host and port ombi will be given. */
+export function appUrl(want: Connection): string {
+  const scheme = want.ssl ? "https" : "http";
+  const host = want.ip.includes(":") && !want.ip.startsWith("[") ? `[${want.ip}]` : want.ip;
+  return `${scheme}://${host}:${want.port}${want.subDir ? `/${want.subDir}` : ""}`;
+}
+
+/** How one app came out. */
+export type Outcome =
+  | { app: string; result: "unchanged" }
+  | { app: string; result: "written"; fields: string[] }
+  | { app: string; result: "refused"; problem: string };
+
+/** The HTTP the step needs, so a test can stand fakes in for ombi and the apps. */
+export interface Http {
+  fetch(url: string, init?: { method?: string; headers?: Record<string, string>; body?: string }): Promise<{
+    status: number;
+    text(): Promise<string>;
+  }>;
+}
+
+export interface Ombi {
+  url: string;
+  apiKey: string;
+}
+
+async function ombiCall(http: Http, ombi: Ombi, method: string, path: string, body?: unknown): Promise<unknown> {
+  const res = await http.fetch(`${ombi.url.replace(/\/$/, "")}/api/v1${path}`, {
+    method,
+    headers: {
+      ApiKey: ombi.apiKey,
+      Accept: "application/json",
+      ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+    },
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  if (res.status < 200 || res.status >= 300) {
+    // The body is ombi's error, never a request echo, so it carries no key.
+    throw new Error(`ombi ${method} ${path} answered ${res.status}${text ? `: ${text.slice(0, 200)}` : ""}`);
+  }
+  return text ? (JSON.parse(text) as unknown) : undefined;
+}
+
+/**
+ * Does the app take this key? `true` it does, `false` it refused it (401/403), and a thrown error
+ * when it could not be asked — unreachable, or answering something that is neither.
+ */
+export async function appTakes(http: Http, spec: ServarrApp, want: Connection): Promise<boolean> {
+  const res = await http.fetch(`${appUrl(want)}${spec.statusPath}`, {
+    method: "GET",
+    headers: { "X-Api-Key": want.apiKey, Accept: "application/json" },
+  });
+  if (res.status === 401 || res.status === 403) return false;
+  if (res.status >= 200 && res.status < 300) return true;
+  throw new Error(`${spec.app} answered ${res.status} at ${spec.statusPath}`);
+}
+
+/** The remedy for a refused key, in the controller's own words (ADR 0092). */
+export function acceptRemedy(spec: ServarrApp, from: string): string {
+  return (
+    `${spec.app} refuses the ${spec.provision} credential the mesh delivered, so it was not written ` +
+    `into ombi. A Servarr app has one API key and the mesh cannot make it: accept ${spec.app}'s own ` +
+    `key for this pair — \`secret accept <this node> ombi ${spec.provision} --provider ${from || "<its node>"} ` +
+    `--from <file holding ${spec.app}'s ApiKey>\``
+  );
+}
+
+/**
+ * Bring ombi's connection to one app in line with the mesh: check the key against the app, compare,
+ * write only the connection fields when they differ, then have ombi test the connection from its own
+ * container. Never throws: every failure is an outcome with a reason.
+ */
+export async function reconcileApp(
+  http: Http,
+  ombi: Ombi,
+  spec: ServarrApp,
+  binding: Binding | undefined,
+  credential: string | undefined,
+): Promise<Outcome> {
+  const w = wanted(spec, binding, credential);
+  // `in`, not `!w.ok`: the Dockerfile compiles without strict, where a boolean discriminant does not
+  // narrow.
+  if ("problem" in w) return { app: spec.app, result: "refused", problem: w.problem };
+  const want = w.connection;
+
+  try {
+    if (!(await appTakes(http, spec, want))) {
+      return { app: spec.app, result: "refused", problem: acceptRemedy(spec, w.from) };
+    }
+  } catch (err) {
+    return {
+      app: spec.app,
+      result: "refused",
+      problem: `${spec.app} could not be asked whether it takes the key at ${want.ip}:${want.port}: ${message(err)}`,
+    };
+  }
+
+  try {
+    const document = (await ombiCall(http, ombi, "GET", `/Settings/${spec.app}`)) as Record<string, unknown> | undefined;
+    const current = spec.within ? (document?.[spec.within] as Record<string, unknown> | undefined) : document;
+    const fields = differing(current, want);
+    if (fields.length > 0) {
+      const next = withConnection(current, want);
+      const body = spec.within ? { ...(document ?? {}), [spec.within]: next } : next;
+      const saved = await ombiCall(http, ombi, "POST", `/Settings/${spec.app}`, body);
+      if (saved === false) {
+        return { app: spec.app, result: "refused", problem: `ombi declined to save its ${spec.app} settings` };
+      }
+    }
+    // ombi's own test, from ombi's own container — the path the step's check above did not take.
+    const tested = (await ombiCall(http, ombi, "POST", `/Tester/${spec.app}`, withConnection(current, want))) as
+      | { isValid?: boolean; expectedSubDir?: string | null }
+      | undefined;
+    if (!tested?.isValid) {
+      const hint = tested?.expectedSubDir ? ` (ombi expected the base path ${tested.expectedSubDir})` : "";
+      return {
+        app: spec.app,
+        result: "refused",
+        problem:
+          `ombi cannot reach ${spec.app} at ${want.ip}:${want.port} from its own container${hint}` +
+          (fields.length > 0 ? `; its settings were written (${fields.join(", ")})` : ""),
+      };
+    }
+    return fields.length > 0 ? { app: spec.app, result: "written", fields } : { app: spec.app, result: "unchanged" };
+  } catch (err) {
+    return { app: spec.app, result: "refused", problem: message(err) };
+  }
+}
+
+/** Wait for ombi to answer, because the step runs right after its container starts. */
+export async function ombiReady(http: Http, ombi: Ombi, waitMs: number, pauseMs = 2000): Promise<boolean> {
+  const until = Date.now() + waitMs;
+  for (;;) {
+    try {
+      const res = await http.fetch(`${ombi.url.replace(/\/$/, "")}/api/v1/Status`, { method: "GET" });
+      if (res.status === 200) return true;
+    } catch {
+      // not listening yet
+    }
+    if (Date.now() >= until) return false;
+    await new Promise((r) => setTimeout(r, pauseMs));
+  }
+}
+
+/** A file the mesh wrote, or undefined when it is not there. */
+export async function readIfThere(path: string | undefined): Promise<string | undefined> {
+  if (!path) return undefined;
+  return readFile(path, "utf8").catch(() => undefined);
+}
+
+/** A binding file parsed, or undefined when absent or not JSON. */
+export async function readBinding(path: string | undefined): Promise<Binding | undefined> {
+  const raw = await readIfThere(path);
+  if (raw === undefined) return undefined;
+  try {
+    return JSON.parse(raw) as Binding;
+  } catch {
+    return undefined;
+  }
+}
+
+function message(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

modules/ombi/test/servarr.test.ts

@@ -0,0 +1,147 @@
+// What holds ombi's Servarr step (servarr/settings.ts): the connection ombi keeps for each app is
+// made to say what the mesh bound — host, port, TLS, base path, key — and nothing else it keeps is
+// touched; nothing is written when nothing differs; Radarr's 4K instance is left alone; and a key the
+// app refuses (the mesh's own minted value, before the operator accepts the app's key) is never
+// written, with the `secret accept` that fixes it named.
+//
+// ombi and the apps are fakes: the routes the step touches, answering as the real ones do (checked
+// against lscr.io/linuxserver/ombi 4.53.10 and the catalogue's pinned sonarr/radarr/lidarr).
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { APPS, differing, reconcileApp, subDirOf, wanted, type Binding, type Http, type ServarrApp } from "../servarr/settings.ts";
+
+const SONARR = APPS.find((a) => a.app === "sonarr") as ServarrApp;
+const RADARR = APPS.find((a) => a.app === "radarr") as ServarrApp;
+const LIDARR = APPS.find((a) => a.app === "lidarr") as ServarrApp;
+const THE_KEY = "the-apps-own-key";
+
+function binding(provision: string, port: number, at = "ace.internal"): Binding {
+  return { binding: 1, provision, from: "ace", at, as: "mesh_ace_ombi", serves: { scheme: "http", port, "url-base": "" } } as Binding;
+}
+
+interface Call {
+  method: string;
+  url: string;
+  body?: unknown;
+}
+
+/** ombi's settings store and the apps' key check, behind one fetch. */
+function fakes(settings: Record<string, unknown>, opts: { appKey?: string; reachable?: boolean } = {}) {
+  const calls: Call[] = [];
+  const appKey = opts.appKey ?? THE_KEY;
+  const http: Http = {
+    async fetch(url, init) {
+      const method = init?.method ?? "GET";
+      const body = init?.body ? (JSON.parse(init.body) as unknown) : undefined;
+      calls.push({ method, url, body });
+      const reply = (status: number, value?: unknown) => ({
+        status,
+        text: async () => (value === undefined ? "" : JSON.stringify(value)),
+      });
+      const u = new URL(url);
+      if (u.pathname.endsWith("/system/status")) {
+        if (opts.reachable === false) throw new Error("connect ECONNREFUSED");
+        return init?.headers?.["X-Api-Key"] === appKey ? reply(200, { version: "4" }) : reply(401);
+      }
+      if (init?.headers?.ApiKey !== "ombi-key") return reply(401);
+      const m = u.pathname.match(/^\/api\/v1\/(Settings|Tester)\/(\w+)$/);
+      if (!m) return reply(404);
+      const [, kind, app] = m;
+      if (kind === "Settings" && method === "GET") return reply(200, settings[app]);
+      if (kind === "Settings" && method === "POST") {
+        settings[app] = body;
+        return reply(200, true);
+      }
+      const tried = body as { apiKey?: string };
+      return reply(200, { isValid: tried.apiKey === appKey, expectedSubDir: null });
+    },
+  };
+  return { http, calls, settings };
+}
+
+const OMBI = { url: "http://127.0.0.1:3579", apiKey: "ombi-key" };
+
+const operatorSonarr = () => ({
+  enabled: true, apiKey: "old-key", qualityProfile: "3", seasonFolders: true, rootPath: "10",
+  qualityProfileAnime: "7", rootPathAnime: "9", languageProfile: 1, ssl: false, subDir: null,
+  ip: "sonarr", port: 8989, id: 5,
+});
+
+test("it writes the connection the mesh bound, and keeps every other setting ombi had", async () => {
+  const f = fakes({ sonarr: operatorSonarr() });
+  const out = await reconcileApp(f.http, OMBI, SONARR, binding("sonarr-api", 20101), `${THE_KEY}\n`);
+  assert.deepEqual(out, { app: "sonarr", result: "written", fields: ["ip", "port", "apiKey"] });
+  assert.deepEqual(f.settings.sonarr, {
+    ...operatorSonarr(), ip: "ace.internal", port: 20101, apiKey: THE_KEY, ssl: false, subDir: null,
+  });
+  // Checked against the app itself, at the bound address, before anything was written.
+  assert.equal(f.calls[0].url, "http://ace.internal:20101/api/v3/system/status");
+});
+
+test("nothing is written when ombi already says what the mesh says", async () => {
+  const f = fakes({ sonarr: { ...operatorSonarr(), ip: "ace.internal", port: 20101, apiKey: THE_KEY } });
+  const out = await reconcileApp(f.http, OMBI, SONARR, binding("sonarr-api", 20101), THE_KEY);
+  assert.deepEqual(out, { app: "sonarr", result: "unchanged" });
+  assert.equal(f.calls.filter((c) => c.method === "POST" && c.url.includes("/Settings/")).length, 0);
+});
+
+test("a key the app refuses is never written, and the accept that fixes it is named", async () => {
+  const f = fakes({ sonarr: operatorSonarr() });
+  const out = await reconcileApp(f.http, OMBI, SONARR, binding("sonarr-api", 20101), "a-value-the-mesh-minted");
+  assert.equal(out.result, "refused");
+  assert.match((out as { problem: string }).problem, /secret accept <this node> ombi sonarr-api --provider ace/);
+  assert.doesNotMatch((out as { problem: string }).problem, /a-value-the-mesh-minted/);
+  assert.deepEqual(f.settings.sonarr, operatorSonarr(), "ombi's working settings were left alone");
+  assert.equal(f.calls.some((c) => c.url.includes("/api/v1/")), false, "ombi was not even asked");
+});
+
+test("an app it cannot reach is reported, and ombi is left alone", async () => {
+  const f = fakes({ sonarr: operatorSonarr() }, { reachable: false });
+  const out = await reconcileApp(f.http, OMBI, SONARR, binding("sonarr-api", 20101), THE_KEY);
+  assert.equal(out.result, "refused");
+  assert.match((out as { problem: string }).problem, /could not be asked.*ECONNREFUSED/);
+  assert.deepEqual(f.settings.sonarr, operatorSonarr());
+});
+
+test("radarr's connection is written inside its combined document, and the 4K instance is untouched", async () => {
+  const fourK = { enabled: true, apiKey: "4k-key", ip: "radarr4k", port: 7879, defaultQualityProfile: "9", id: 7 };
+  const f = fakes({ radarr: { radarr: { enabled: true, apiKey: "old", ip: "radarr", port: 7878, defaultRootPath: "/movies", id: 6 }, radarr4K: fourK } });
+  const out = await reconcileApp(f.http, OMBI, RADARR, binding("radarr-api", 20102), THE_KEY);
+  assert.equal(out.result, "written");
+  const doc = f.settings.radarr as { radarr: Record<string, unknown>; radarr4K: unknown };
+  assert.deepEqual(doc.radarr4K, fourK);
+  assert.equal(doc.radarr.ip, "ace.internal");
+  assert.equal(doc.radarr.port, 20102);
+  assert.equal(doc.radarr.defaultRootPath, "/movies");
+});
+
+test("lidarr is checked on its own API version", async () => {
+  const f = fakes({ lidarr: { enabled: true, apiKey: null, ip: null, port: 0, id: 0 } });
+  const out = await reconcileApp(f.http, OMBI, LIDARR, binding("lidarr-api", 20103), THE_KEY);
+  assert.equal(out.result, "written");
+  assert.equal(f.calls[0].url, "http://ace.internal:20103/api/v1/system/status");
+});
+
+test("a loopback binding is refused: from ombi's container it is ombi itself", () => {
+  const w = wanted(SONARR, binding("sonarr-api", 20101, "127.0.0.1"), THE_KEY);
+  assert.equal(w.ok, false);
+  assert.match((w as { problem: string }).problem, /private network/);
+});
+
+test("the base path is ombi's subDir, slashes trimmed; empty is none", () => {
+  assert.equal(subDirOf(""), null);
+  assert.equal(subDirOf("/sonarr/"), "sonarr");
+  assert.deepEqual(
+    differing({ ip: "h", port: 1, ssl: false, subDir: "", apiKey: "k" }, { ip: "h", port: 1, ssl: false, subDir: null, apiKey: "k" }),
+    [],
+  );
+});
+
+test("an https binding sets ombi's ssl flag", () => {
+  const b = binding("sonarr-api", 443);
+  (b.serves as Record<string, unknown>).scheme = "https";
+  const w = wanted(SONARR, b, THE_KEY);
+  assert.equal(w.ok && w.connection.ssl, true);
+});

modules/ombi/tsconfig.json

@@ -8,5 +8,5 @@
     "skipLibCheck": true,
     "noEmit": true
   },
-  "include": ["client.ts", "index.ts", "tools/index.ts"]
+  "include": ["client.ts", "index.ts", "tools/index.ts", "servarr/settings.ts", "servarr/index.ts"]
 }

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",
@@ -81,7 +82,7 @@
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_QBITTORRENT_URL": "http://127.0.0.1:8080",
+        "MESH_QBITTORRENT_URL": "http://127.0.0.1:${port:8080}",
         "MESH_QBITTORRENT_PASSWORD_FILE": "/run/secrets/password",
         "MESH_QBITTORRENT_CONFIG_FILE": "/run/config/config.json",
         "MESH_QBITTORRENT_CONFIG_DIR": "/var/lib/qbittorrent/config"

modules/radarr/module.json

@@ -1,6 +1,19 @@
 {
   "module": "radarr",
   "version": "1",
+  "provides": [
+    {
+      "name": "radarr-api",
+      "scope": "mesh"
+    }
+  ],
+  "serves": {
+    "radarr-api": {
+      "scheme": "http",
+      "port": 7878,
+      "url-base": ""
+    }
+  },
   "capabilities": [
     "container-runtime"
   ],
@@ -14,6 +27,7 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 7878,
       "protocol": "tcp",
       "from": "mesh",
@@ -74,7 +88,7 @@
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_RADARR_URL": "http://127.0.0.1:7878",
+        "MESH_RADARR_URL": "http://127.0.0.1:${port:7878}",
         "MESH_RADARR_CONFIG_DIR": "/var/lib/radarr/config"
       },
       "artifact": "runtime"
@@ -86,7 +100,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

@@ -5,11 +5,12 @@
     "container-runtime"
   ],
   "own-secrets": {
-    "secret": "/var/lib/searxng-module/secret.secret",
+    "secret": "/var/lib/mesh/searxng/secret",
     "broker": "/var/lib/mesh/searxng/broker"
   },
   "listens": [
     {
+      "name": "web",
       "port": 8080,
       "protocol": "tcp",
       "from": "mesh",
@@ -26,22 +27,14 @@
     {
       "id": "state",
       "type": "directory",
-      "path": "/var/lib/searxng-module",
-      "mode": "0700"
+      "mode": "0700",
+      "place": "."
     },
     {
       "id": "valkey-data",
       "type": "directory",
-      "path": "/var/lib/searxng-module/valkey-data",
       "mode": "0700"
     },
-    {
-      "id": "server-env",
-      "type": "file",
-      "path": "/var/lib/searxng-module/server.env",
-      "mode": "0600",
-      "content": "SEARXNG_SECRET=${secret:secret}\nSEARXNG_VALKEY_URL=valkey://valkey:6379/0\n"
-    },
     {
       "id": "net",
       "type": "network",
@@ -62,30 +55,39 @@
         "warning"
       ],
       "volumes": [
-        "/var/lib/searxng-module/valkey-data:/data"
+        "${dir:valkey-data}:/data"
       ]
     },
+    {
+      "id": "settings",
+      "type": "file",
+      "path": "${dir:state}/settings.yml",
+      "mode": "0600",
+      "merge": "json",
+      "content": "{\n  \"use_default_settings\": true,\n  \"server\": {\n    \"secret_key\": \"${secret:secret}\",\n    \"base_url\": false,\n    \"limiter\": false,\n    \"image_proxy\": false,\n    \"public_instance\": false\n  },\n  \"search\": {\n    \"formats\": [\"html\", \"json\"]\n  },\n  \"valkey\": {\n    \"url\": \"valkey://valkey:6379/0\"\n  }\n}\n"
+    },
     {
       "id": "server",
       "type": "container",
       "name": "searxng",
-      "image": "searxng/searxng@sha256:c7cc75852051bf6254afda6ed1b920dd1677d8efe4ab141bf558f02e582f4371",
+      "image": "searxng/searxng@sha256:cd8812607ab73730a0b1a0dc4990223fe1b9e383f6f35947114d0bef7f8bb441",
       "network": "searxng",
-      "env-file": [
-        "/var/lib/searxng-module/server.env"
-      ],
       "ports": [
         "8080"
       ],
-      "secrets-in-environment": "SEARXNG_SECRET is env-only, but settings.yml carries server.secret_key; convertible by mounting a generated settings.yml, not yet done"
+      "volumes": [
+        "${dir:state}/settings.yml:/etc/searxng/settings.yml:ro"
+      ],
+      "restart-on": [
+        "settings"
+      ]
     },
     {
       "id": "runtime-config",
       "type": "file",
       "path": "/var/lib/mesh/searxng/config.json",
       "mode": "0600",
-      "content": "{}\n",
-      "merge": "json"
+      "content": "{}\n"
     },
     {
       "id": "runtime",
@@ -98,7 +100,7 @@
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_SEARXNG_URL": "http://127.0.0.1:8080",
+        "MESH_SEARXNG_URL": "http://127.0.0.1:${port:8080}",
         "MESH_SEARXNG_CONFIG_FILE": "/run/config/config.json"
       },
       "restart-on": [
@@ -113,11 +115,11 @@
   "contributes": {
     "route": {
       "label": "searxng",
-      "port": 8080
+      "endpoint": "web"
     }
   },
   "binds": {
-    "route": "/var/lib/searxng-module/route.json"
+    "route": "${dir:state}/route.json"
   },
   "build": {
     "on": [

modules/showcase/module.json

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

modules/sonarr/module.json

@@ -1,6 +1,19 @@
 {
   "module": "sonarr",
   "version": "1",
+  "provides": [
+    {
+      "name": "sonarr-api",
+      "scope": "mesh"
+    }
+  ],
+  "serves": {
+    "sonarr-api": {
+      "scheme": "http",
+      "port": 8989,
+      "url-base": ""
+    }
+  },
   "capabilities": [
     "container-runtime"
   ],
@@ -14,6 +27,7 @@
   },
   "listens": [
     {
+      "name": "web",
       "port": 8989,
       "protocol": "tcp",
       "from": "mesh",
@@ -79,7 +93,7 @@
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_SONARR_URL": "http://127.0.0.1:8989",
+        "MESH_SONARR_URL": "http://127.0.0.1:${port:8989}",
         "MESH_SONARR_CONFIG_DIR": "/var/lib/sonarr/config"
       },
       "artifact": "runtime"
@@ -91,7 +105,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",
-      "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"
+      "from": "mesh",
+      "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",