Convert the resolver from the module it replaces: forward, answer at 127.0.0.1, point the runtime at it

Read against hal/modules/dnsmasq-app (hal dnsmasq-app conversion, hq 08-connectivity).
On the machines it runs, the predecessor's dnsmasq answers every name: the mesh's own
itself, the rest forwarded to 1.1.1.1 and 8.8.8.8, its module's defaults; resolv.conf
names it alone at 127.0.0.1, and the container runtime's dns is the machine's tunnel
address, so the host and every container resolve the world through it. The nox module
forwarded nothing, listened on 127.0.0.55 — a convention of its own beside the one every
machine already followed — and read a machines file that the module's `facts` already
asks the mesh for, so taking it would have left an adopted machine with a resolv.conf
pointing at an address nothing answered on, and no upstream for anything else.

Now the resolver keeps `no-resolv` (the documented loop — finding its own address in
resolv.conf and becoming its own upstream — stays impossible) and forwards to the same
two explicit upstreams; listens on mesh0 and 127.0.0.1, which systemd-resolved does not
hold; requires `mesh-addressing`, since its data is the mesh's addresses; and writes the
runtime's `dns` into daemon.json beside whatever the machine had (ADR 0102), at this
machine's own address — `${machine:address}`, new in the controller. The runtime is not
restarted for it: it reads the key at start, not on reload, and a restart stops every
container; on the machine this replaces the value is already there.

resolv-conf names the resolver alone, as the predecessor's file did; its placeholder second
line was a fallback nothing ever reached. resolved-split-dns follows the address. The
mesh's suffix as a local domain comes with the machines file, so a mesh name the resolver
does not know is refused here rather than asked upstream. mDNS is not carried: no module
does it and the design says mesh names are not multicast names.

modules/amqp-email-forwarder/module.json

@@ -0,0 +1,56 @@
+{
+  "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

@@ -0,0 +1,31 @@
+# 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

@@ -0,0 +1,191 @@
+// 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

@@ -0,0 +1,53 @@
+// 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

@@ -0,0 +1,89 @@
+{
+  "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

@@ -0,0 +1,14 @@
+{
+  "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

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

modules/anthropic-consumer/module.json

@@ -9,29 +9,29 @@
     "model-access"
   ],
   "binds": {
-    "model-access": "${dir:state}/model.json"
+    "model-access": "/var/lib/anthropic-consumer/model.json"
   },
   "secrets": {
-    "model-access": "${dir:state}/access-token"
+    "model-access": "/var/lib/anthropic-consumer/access-token"
   },
   "own-secrets": {
-    "broker": "${dir:mesh-state}/broker"
+    "broker": "/var/lib/mesh/anthropic-consumer/broker"
   },
   "emits": [
-    "usage.session"
+    "module.anthropic-consumer.usage.session"
   ],
   "resources": [
     {
       "id": "mesh-state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/mesh/anthropic-consumer",
-      "place": "mesh"
+      "mode": "0700"
     },
     {
       "id": "state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/anthropic-consumer",
-      "place": "."
+      "mode": "0700"
     },
     {
       "id": "claude-home",
@@ -42,6 +42,7 @@
     {
       "id": "out",
       "type": "directory",
+      "path": "/var/lib/anthropic-consumer/out",
       "mode": "0700"
     },
     {
@@ -55,7 +56,7 @@
         "/app/modules/anthropic-consumer/dist/apply/index.js"
       ],
       "volumes": [
-        "${dir:state}:/run/state"
+        "/var/lib/anthropic-consumer:/run/state"
       ],
       "env": {
         "MESH_MODEL_ACCESS_SECRET_FILE": "/run/state/access-token",
@@ -76,8 +77,8 @@
         "/app/modules/anthropic-consumer/dist/usage/index.js"
       ],
       "volumes": [
-        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "/var/lib/mesh/anthropic-consumer/broker:/run/secrets/broker:ro",
-        "${dir:state}:/run/state"
+        "/var/lib/anthropic-consumer:/run/state"
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",

modules/anthropic-consumer/usage/index.ts

@@ -123,7 +123,7 @@ async function emitUsage(body: Record<string, unknown>): Promise<void> {
   await new Promise<void>((resolve) => {
     const child = spawn(
       process.execPath,
-      [main, "emit", "usage.session", JSON.stringify(body)],
+      [main, "emit", "module.anthropic-consumer.usage.session", JSON.stringify(body)],
       { stdio: "inherit" },
     );
     child.on("exit", () => resolve());

modules/anthropic-manager/module.json

@@ -9,28 +9,28 @@
     "model-access"
   ],
   "binds": {
-    "model-access": "${dir:mesh-state}/model.json"
+    "model-access": "/var/lib/mesh/anthropic-manager/model.json"
   },
   "secrets": {
-    "model-access": "${dir:mesh-state}/refresh-token"
+    "model-access": "/var/lib/mesh/anthropic-manager/refresh-token"
   },
   "own-secrets": {
-    "broker": "${dir:mesh-state}/broker"
+    "broker": "/var/lib/mesh/anthropic-manager/broker"
   },
   "emits": [
-    "usage.read"
+    "module.anthropic-manager.usage.read"
   ],
   "resources": [
     {
       "id": "mesh-state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/mesh/anthropic-manager",
-      "place": "mesh"
+      "mode": "0700"
     },
     {
       "id": "out",
       "type": "directory",
-      "path": "${dir:mesh-state}/out",
+      "path": "/var/lib/mesh/anthropic-manager/out",
       "mode": "0700"
     },
     {
@@ -45,8 +45,8 @@
         "/app/modules/anthropic-manager/dist/refresh/index.js"
       ],
       "volumes": [
-        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "/var/lib/mesh/anthropic-manager/broker:/run/secrets/broker:ro",
-        "${dir:mesh-state}:/run/state"
+        "/var/lib/mesh/anthropic-manager:/run/state"
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",

modules/anthropic-manager/refresh/index.ts

@@ -143,7 +143,7 @@ async function emitUsage(body: Record<string, unknown>): Promise<void> {
   const main = process.env.MESH_TOOLS_MAIN ?? "/app/dist/main.js";
   const { spawn } = await import("node:child_process");
   await new Promise<void>((resolve) => {
-    const child = spawn(process.execPath, [main, "emit", "usage.read", JSON.stringify(body)], {
+    const child = spawn(process.execPath, [main, "emit", "module.anthropic-manager.usage.read", JSON.stringify(body)], {
       stdio: "inherit",
     });
     child.on("exit", () => resolve());

modules/audit-logger/module.json

@@ -3,10 +3,10 @@
   "version": "1",
   "slug": "audit",
   "consumes": [
-    "**"
+    "#"
   ],
   "own-secrets": {
-    "broker": "${dir:state}/broker"
+    "broker": "/var/lib/audit-logger/broker"
   },
   "build": {
     "on": [
@@ -33,12 +33,13 @@
     {
       "id": "state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/audit-logger",
-      "place": "."
+      "mode": "0700"
     },
     {
       "id": "trail",
       "type": "directory",
+      "path": "/var/lib/audit-logger/trail",
       "mode": "0700"
     },
     {
@@ -47,8 +48,8 @@
       "name": "mesh-audit-logger",
       "network": "host",
       "volumes": [
-        "${dir:state}/broker:/run/secrets/broker:ro",
+        "/var/lib/audit-logger/broker:/run/secrets/broker:ro",
-        "${dir:trail}:/trail"
+        "/var/lib/audit-logger/trail:/trail"
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",

modules/audit-logger/test/audit.test.ts

@@ -15,16 +15,16 @@ test("audit-logger records every event to the trail as one line each", async ()
   const path = join(dir, "audit.log");
 
   // The audit-logger's whole behaviour: consume everything, record it.
-  await on("**", async (event) => record(event, path));
+  await on("#", async (event) => record(event, path));
 
   process.env.MESH_MODULE = "umami";
   process.env.MESH_NODE = "anchor";
-  await emit("site.created", { domain: "my-app" });
+  await emit("module.umami.site.created", { domain: "my-app" });
   await emit("node.anchor.joined", { role: "worker" }); // a node event, not a module one
 
   const lines = (await readFile(path, "utf8")).trim().split("\n").map((l) => JSON.parse(l));
   assert.equal(lines.length, 2);
-  assert.deepEqual(lines.map((l) => l.type), ["umami.site.created", "node.anchor.joined"]);
+  assert.deepEqual(lines.map((l) => l.type), ["module.umami.site.created", "node.anchor.joined"]);
   assert.equal(lines[0].source, "umami");
   assert.equal(lines[0].node, "anchor");
   assert.equal(lines[0].body.domain, "my-app");

modules/baserow/client.ts

@@ -2,15 +2,12 @@
 // module's tools and anything else baserow-specific import it; nothing outside baserow does.
 //
 // Baserow authenticates a person with email + password, exchanged for a JWT at /api/user/token-auth/.
-// The standard image creates no admin from env, so the account is one a person made in Baserow: its
+// Those credentials are the mesh's own: a person signs up in Baserow (the standard image creates no
-// password is the module's `admin` secret, accepted from the operator, and its email and the public
+// admin from env), and the credential is placed in the runtime config file the mesh mounts. Until
-// host Baserow answers to reach the runtime config file the mesh mounts (the email from the
+// that happens fromEnv throws and the module simply exposes no tools — the same dormant-until-
-// assignment's settings). Until both are there fromEnv throws and the module exposes no tools — the
+// configured shape gitea uses for its token.
-// same dormant-until-configured shape gitea uses for its token.
 
 import { readFileSync } from "node:fs";
-import { request as httpRequest } from "node:http";
-import { request as httpsRequest } from "node:https";
 
 export interface BaserowApplication {
   id: number;
@@ -71,63 +68,35 @@ export class BaserowClient {
     return h;
   }
 
-  /**
+  /** Exchange email + password for a JWT, caching it for the client's lifetime. Handles both the
-   * One HTTP exchange. Not `fetch`: Node's fetch drops a caller's Host header and sends the URL's
-   * own, and Baserow answers only the host of its BASEROW_PUBLIC_URL — any other Host is looked up
-   * as a published builder site and gets 404, `/api/_health/` included. A co-located caller reaching
-   * it by container name must present the public host, so the request is made with node:http, which
-   * sends the Host it is given.
-   */
-  private send(path: string, method: string, headers: Record<string, string>, body?: string): Promise<{ status: number; text: string }> {
-    const url = new URL(`${this.baseUrl}${path}`);
-    const request = url.protocol === "https:" ? httpsRequest : httpRequest;
-    // A length, never chunked: Baserow's server reads a chunked body as empty.
-    const sent = body === undefined ? headers : { ...headers, "Content-Length": String(Buffer.byteLength(body)) };
-    return new Promise((resolve, reject) => {
-      const req = request(url, { method, headers: sent }, (res) => {
-        let text = "";
-        res.setEncoding("utf8");
-        res.on("data", (chunk: string) => (text += chunk));
-        res.on("end", () => resolve({ status: res.statusCode ?? 0, text }));
-        res.on("error", reject);
-      });
-      req.on("error", reject);
-      if (body !== undefined) req.write(body);
-      req.end();
-    });
-  }
-
-  /** Exchange email + password for a JWT, caching it until Baserow refuses it. Handles both the
    *  older `{ token }` and the newer `{ access_token }` response shapes. */
   async authenticate(): Promise<string> {
     if (this.token) return this.token;
-    const res = await this.send(
+    const res = await fetch(`${this.baseUrl}/api/user/token-auth/`, {
-      "/api/user/token-auth/",
+      method: "POST",
-      "POST",
+      headers: this.headers(),
-      this.headers(),
+      body: JSON.stringify({ email: this.email, password: this.password }),
-      JSON.stringify({ email: this.email, password: this.password }),
+    });
-    );
+    if (!res.ok) throw new Error(`baserow auth failed: ${res.status} ${await res.text()}`);
-    if (res.status < 200 || res.status >= 300) throw new Error(`baserow auth failed: ${res.status} ${res.text}`);
+    const data = (await res.json()) as { token?: string; access_token?: string };
-    const data = JSON.parse(res.text) as { token?: string; access_token?: string };
     const token = data.access_token ?? data.token;
     if (!token) throw new Error("baserow auth returned no token");
     this.token = token;
     return token;
   }
 
-  /** An authenticated GET. A refused token is dropped and the call made once more with a fresh one:
+  private async authed<T>(path: string, options: RequestInit = {}): Promise<T> {
-   *  Baserow's access tokens expire after minutes, and the runtime lives for weeks. */
-  private async authed<T>(path: string): Promise<T> {
-    for (let attempt = 0; ; attempt++) {
     const token = await this.authenticate();
-      const res = await this.send(path, "GET", this.headers({ Authorization: `JWT ${token}` }));
+    const res = await fetch(`${this.baseUrl}${path}`, {
-      if (res.status === 401 && attempt === 0) {
+      ...options,
-        this.token = null;
+      headers: this.headers({
-        continue;
+        Authorization: `JWT ${token}`,
-      }
+        ...(options.headers as Record<string, string> | undefined),
-      if (res.status < 200 || res.status >= 300) throw new Error(`baserow ${path}: ${res.status} ${res.text}`);
+      }),
-      return (res.text ? JSON.parse(res.text) : null) as T;
+    });
-    }
+    if (!res.ok) throw new Error(`baserow ${path}: ${res.status} ${await res.text()}`);
+    const text = await res.text();
+    return (text ? JSON.parse(text) : null) as T;
   }
 
   /** The applications (databases) the account can see, across all its workspaces. */

modules/baserow/module.json

@@ -14,54 +14,54 @@
     },
     "route": {
       "label": "baserow",
-      "endpoint": "web"
+      "port": 80
     }
   },
   "binds": {
-    "postgres-database": "${dir:state}/database.json",
+    "postgres-database": "/var/lib/baserow/database.json",
-    "route": "${dir:state}/route.json"
+    "route": "/var/lib/baserow/route.json"
   },
   "secrets": {
-    "postgres-database": "${dir:state}/database.secret"
+    "postgres-database": "/var/lib/baserow/database.secret"
   },
   "own-secrets": {
-    "admin": "${dir:state}/admin.secret",
+    "secret-key": "/var/lib/baserow/secret-key.secret",
-    "broker": "${dir:mesh-state}/broker"
+    "broker": "/var/lib/mesh/baserow/broker"
   },
   "listens": [
     {
-      "name": "web",
       "port": 80,
       "protocol": "tcp",
       "from": "mesh",
-      "why": "the Baserow web UI and REST API, served by the image's own Caddy; a public name is the route's"
+      "why": "the Baserow web UI and REST API; a public name is a route grant later"
     }
   ],
   "resources": [
     {
       "id": "mesh-state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/mesh/baserow",
-      "place": "mesh"
+      "mode": "0700"
     },
     {
       "id": "state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/baserow",
-      "place": "."
+      "mode": "0700"
     },
     {
       "id": "data",
       "type": "directory",
+      "path": "/services/baserow/data",
       "mode": "0755",
       "owner": "9999:9999"
     },
     {
       "id": "server-env",
       "type": "file",
-      "path": "${dir:state}/server.env",
+      "path": "/var/lib/baserow/server.env",
       "mode": "0600",
-      "content": "DATABASE_HOST=${bound:postgres-database:at}\nDATABASE_PORT=${bound:postgres-database:port}\nDATABASE_NAME=${bound:postgres-database:as}\nDATABASE_USER=${bound:postgres-database:as}\nDATABASE_PASSWORD_FILE=/run/secrets/database\nDISABLE_EMBEDDED_PSQL=true\nBASEROW_PUBLIC_URL=https://${bound:route:name}\n"
+      "content": "DATABASE_HOST=${bound:postgres-database:at}\nDATABASE_PORT=${bound:postgres-database:port}\nDATABASE_NAME=${bound:postgres-database:as}\nDATABASE_USER=${bound:postgres-database:as}\nDATABASE_PASSWORD=${secret:postgres-database}\nSECRET_KEY=${secret:secret-key}\nBASEROW_PUBLIC_URL=http://localhost\n"
     },
     {
       "id": "net",
@@ -72,25 +72,25 @@
       "id": "server",
       "type": "container",
       "name": "baserow",
-      "image": "baserow/baserow@sha256:263ea6c4b72c9eccabcd975ffe9fdebf23913a293a514bec6a3897a5e0a5a080",
+      "image": "baserow/baserow@sha256:834424a10413798567f76428f255dc259445b7f8dcec56598c05b4073bb2a124",
       "network": "baserow",
       "env-file": [
-        "${dir:state}/server.env"
+        "/var/lib/baserow/server.env"
       ],
       "ports": [
         "80"
       ],
       "volumes": [
-        "${dir:data}:/baserow/data",
+        "/services/baserow/data:/baserow/data"
-        "${dir:state}/database.secret:/run/secrets/database:ro"
+      ],
-      ]
+      "secrets-in-environment": "baserow reads DATABASE_PASSWORD and SECRET_KEY with os.getenv and has no _FILE twin (settings/base.py); not convertible"
     },
     {
       "id": "runtime-config",
       "type": "file",
-      "path": "${dir:mesh-state}/config.json",
+      "path": "/var/lib/mesh/baserow/config.json",
       "mode": "0600",
-      "content": "{\n  \"password\": \"${secret:admin}\",\n  \"host\": \"${bound:route:name}\"\n}\n",
+      "content": "{}\n",
       "merge": "json"
     },
     {
@@ -99,8 +99,8 @@
       "name": "mesh-baserow",
       "network": "baserow",
       "volumes": [
-        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "/var/lib/mesh/baserow/broker:/run/secrets/broker:ro",
-        "${dir:mesh-state}/config.json:/run/config/config.json:ro"
+        "/var/lib/mesh/baserow/config.json:/run/config/config.json:ro"
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",

modules/bazarr/Dockerfile

@@ -0,0 +1,24 @@
+# bazarr'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 in
+# the base images, published like any other artifact — which 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 (novox/hq issue 044): the image this is COMPILED in and the
+# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
+ARG BUILD_BASE
+ARG RUNTIME_BASE
+
+FROM ${BUILD_BASE} AS build
+WORKDIR /app/modules/bazarr
+COPY . .
+RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+COPY --from=build /app/modules/bazarr/dist /app/modules/bazarr/dist
+# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
+# 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/bazarr/dist/index.js,/app/modules/bazarr/dist/tools/index.js

modules/bazarr/client.ts

@@ -0,0 +1,173 @@
+// The Bazarr API client — bazarr's own code, living in the module (novox/hq ADR 0039). Bazarr
+// manages subtitles for a Sonarr/Radarr library: it tracks which episodes and movies are still
+// missing subtitles, searches providers for them, and records what it downloaded. This client
+// talks its /api surface (keyed by an X-API-KEY header); bazarr's tools and events import it.
+
+import { readFileSync } from "node:fs";
+
+export interface WantedSubtitle {
+  kind: "episode" | "movie";
+  title: string; // series + episode, or movie title
+  path?: string;
+  seriesId?: number; // sonarr series id (episodes)
+  episodeId?: number; // sonarr episode id (episodes)
+  radarrId?: number; // radarr movie id (movies)
+  missing: string[]; // language names still missing
+}
+
+export interface ProviderSubtitle {
+  provider: string;
+  language: string;
+  hearingImpaired: boolean;
+  forced: boolean;
+  score?: number;
+  release?: string;
+  subtitle: string; // the opaque token Bazarr uses to download this exact result
+}
+
+export interface HistoryEntry {
+  kind: "episode" | "movie";
+  id: string; // stable dedup key across polls
+  title: string;
+  language?: string;
+  provider?: string;
+  path?: string;
+  timestamp?: string;
+  description?: string;
+}
+
+/** The settings-merged config the mesh delivers (novox/hq ADR 0046): { url, apiKey, token, password, user, ... }. */
+function meshConfig(file?: string): Record<string, string> {
+  if (!file) return {};
+  try { return JSON.parse(readFileSync(file, "utf8")) as Record<string, string>; }
+  catch { return {}; }
+}
+
+/** Read a secret the mesh mounted at a file path (an own-secret delivered by `secret accept`);
+ *  absent or unreadable yields undefined so callers fall back rather than crash. */
+function readSecret(file?: string): string | undefined {
+  if (!file) return undefined;
+  try { return readFileSync(file, "utf8").trim(); }
+  catch { return undefined; }
+}
+
+export class BazarrClient {
+  readonly baseUrl: string;
+
+  constructor(
+    url: string,
+    private readonly apiKey: string,
+  ) {
+    this.baseUrl = url.replace(/\/$/, "");
+  }
+
+  /** Build from the module's resolved environment. Bazarr's API is keyed; without URL and key
+   *  there is nothing to talk to, so this throws rather than run half-configured. */
+  static fromEnv(env: NodeJS.ProcessEnv = process.env): BazarrClient {
+    const cfg = meshConfig(env.MESH_BAZARR_CONFIG_FILE);
+    const url = cfg.url ?? env.MESH_BAZARR_URL;
+    const apiKey = cfg.apiKey ?? readSecret(env.MESH_BAZARR_API_KEY_FILE) ?? env.MESH_BAZARR_API_KEY;
+    if (!url) throw new Error("no Bazarr URL — set MESH_BAZARR_URL");
+    if (!apiKey) throw new Error("no Bazarr API key — set MESH_BAZARR_API_KEY");
+    return new BazarrClient(url, apiKey);
+  }
+
+  private async request(method: string, path: string, params: Record<string, string> = {}): Promise<any> {
+    const url = new URL(`${this.baseUrl}/api${path}`);
+    for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
+    const res = await fetch(url.toString(), { method, headers: { "X-API-KEY": this.apiKey, Accept: "application/json" } });
+    if (!res.ok) throw new Error(`Bazarr API ${method} ${path}: ${res.status} ${await res.text()}`);
+    // Downloads/patches return an empty body; only GETs carry JSON.
+    const text = await res.text();
+    return text ? JSON.parse(text) : {};
+  }
+
+  private get(path: string, params?: Record<string, string>): Promise<any> {
+    return this.request("GET", path, params);
+  }
+
+  private languageNames(missing: any[]): string[] {
+    return (missing ?? []).map((m: any) => m?.name ?? m?.code2 ?? m?.code3).filter(Boolean);
+  }
+
+  /** Episodes and movies still missing subtitles — Bazarr's core "what's left to do" list. */
+  async getWanted(limit = 50): Promise<WantedSubtitle[]> {
+    const [eps, movies] = await Promise.all([
+      this.get("/episodes/wanted", { start: "0", length: String(limit) }),
+      this.get("/movies/wanted", { start: "0", length: String(limit) }),
+    ]);
+    const episodes: WantedSubtitle[] = (eps?.data ?? []).map((e: any) => ({
+      kind: "episode" as const,
+      title: `${e.seriesTitle ?? e.series ?? "Unknown"} — ${e.episodeTitle ?? e.episode_title ?? ""}`.trim(),
+      path: e.path,
+      seriesId: e.sonarrSeriesId,
+      episodeId: e.sonarrEpisodeId,
+      missing: this.languageNames(e.missing_subtitles),
+    }));
+    const films: WantedSubtitle[] = (movies?.data ?? []).map((m: any) => ({
+      kind: "movie" as const,
+      title: m.title ?? "Unknown",
+      path: m.path,
+      radarrId: m.radarrId,
+      missing: this.languageNames(m.missing_subtitles),
+    }));
+    return [...episodes, ...films];
+  }
+
+  /** Ask providers what subtitles are available for one wanted episode — a manual search. */
+  async searchEpisode(episodeId: number): Promise<ProviderSubtitle[]> {
+    const raw = await this.get("/providers/episodes", { episodeid: String(episodeId) });
+    return this.mapProviderResults(raw);
+  }
+
+  /** Ask providers what subtitles are available for one movie — a manual search. */
+  async searchMovie(radarrId: number): Promise<ProviderSubtitle[]> {
+    const raw = await this.get("/providers/movies", { radarrid: String(radarrId) });
+    return this.mapProviderResults(raw);
+  }
+
+  private mapProviderResults(raw: any): ProviderSubtitle[] {
+    const list = Array.isArray(raw) ? raw : (raw?.data ?? []);
+    return list.map((r: any) => ({
+      provider: r.provider,
+      language: r.language?.name ?? r.language ?? "unknown",
+      hearingImpaired: Boolean(r.hearing_impaired ?? r.hi),
+      forced: Boolean(r.forced),
+      score: r.score,
+      release: r.release_info?.[0] ?? r.release_info,
+      subtitle: r.subtitle,
+    }));
+  }
+
+  /** Recent subtitle-download history, episodes and movies together, newest first. Each entry
+   *  carries a stable id so the events poller can tell a fresh download from one already seen. */
+  async getHistory(limit = 40): Promise<HistoryEntry[]> {
+    const [eps, movies] = await Promise.all([
+      this.get("/episodes/history", { start: "0", length: String(limit) }),
+      this.get("/movies/history", { start: "0", length: String(limit) }),
+    ]);
+    const key = (kind: string, r: any): string =>
+      `${kind}:${r.timestamp ?? r.parsed_timestamp ?? ""}:${r.subtitles_path ?? r.path ?? ""}:${r.language?.code3 ?? r.language ?? ""}`;
+    const episodes: HistoryEntry[] = (eps?.data ?? []).map((r: any) => ({
+      kind: "episode" as const,
+      id: key("episode", r),
+      title: `${r.seriesTitle ?? "Unknown"} — ${r.episodeTitle ?? ""}`.trim(),
+      language: r.language?.name ?? r.language,
+      provider: r.provider,
+      path: r.subtitles_path,
+      timestamp: r.timestamp,
+      description: r.description,
+    }));
+    const films: HistoryEntry[] = (movies?.data ?? []).map((r: any) => ({
+      kind: "movie" as const,
+      id: key("movie", r),
+      title: r.title ?? "Unknown",
+      language: r.language?.name ?? r.language,
+      provider: r.provider,
+      path: r.subtitles_path,
+      timestamp: r.timestamp,
+      description: r.description,
+    }));
+    return [...episodes, ...films];
+  }
+}

modules/bazarr/index.ts

@@ -0,0 +1,47 @@
+// bazarr's events. The tool runtime imports this once the broker is bound. Bazarr's one genuinely
+// observable thing is a subtitle arriving: it works away in the background, searching providers for
+// the missing-subtitle list, and when it succeeds a subtitle appears in its history. That is worth
+// announcing to the mesh.
+//
+// Emits (novox/hq ADR 0041/0042):
+//   module.bazarr.subtitle.downloaded   — a subtitle was fetched for an episode or movie
+//
+// Bazarr has nothing on the mesh it usefully reacts to (a download completing is Sonarr/Radarr's
+// business, and they trigger Bazarr directly), so it consumes nothing — a pure emitter.
+//
+// The event is observation-based: poll history and diff. Primed silently on the first look, or a
+// restart would re-announce the whole recent history as freshly downloaded.
+
+import { emit } from "@novox/mesh-sdk/events";
+import { BazarrClient } from "./client.js";
+
+const bazarr = BazarrClient.fromEnv();
+
+const seen = new Set<string>();
+let primed = false;
+async function pollHistory(): Promise<void> {
+  const entries = await bazarr.getHistory(40);
+  for (const entry of entries) {
+    if (seen.has(entry.id)) continue;
+    if (primed) {
+      await emit("module.bazarr.subtitle.downloaded", {
+        kind: entry.kind,
+        title: entry.title,
+        language: entry.language,
+        provider: entry.provider,
+        path: entry.path,
+      });
+    }
+    seen.add(entry.id);
+  }
+  primed = true;
+}
+
+const tick = (fn: () => Promise<void>, everyMs: number): void => {
+  const run = (): void => void fn().catch((err) => console.error(`[bazarr] ${err}`));
+  setInterval(run, everyMs);
+  run();
+};
+tick(pollHistory, 60_000);
+
+console.log("[bazarr] watching subtitle-download history");

modules/bazarr/module.json

@@ -0,0 +1,140 @@
+{
+  "module": "bazarr",
+  "version": "1",
+  "capabilities": [
+    "container-runtime"
+  ],
+  "emits": [
+    "module.bazarr.subtitle.downloaded"
+  ],
+  "own-secrets": {
+    "broker": "/var/lib/mesh/bazarr/broker",
+    "api-key": "/var/lib/mesh/bazarr/api-key"
+  },
+  "listens": [
+    {
+      "port": 6767,
+      "protocol": "tcp",
+      "from": "mesh",
+      "why": "managing subtitles"
+    }
+  ],
+  "accesses": [
+    {
+      "path": "/services/media/movies",
+      "mode": "read-write"
+    },
+    {
+      "path": "/services/media/series",
+      "mode": "read-write"
+    },
+    {
+      "path": "/services/media/anime",
+      "mode": "read-write"
+    },
+    {
+      "path": "/services/media/downloads",
+      "mode": "read"
+    }
+  ],
+  "resources": [
+    {
+      "id": "mesh-state",
+      "type": "directory",
+      "path": "/var/lib/mesh/bazarr",
+      "mode": "0700"
+    },
+    {
+      "id": "config",
+      "type": "directory",
+      "path": "/services/bazarr/config",
+      "mode": "0700",
+      "owner": "1000:1000"
+    },
+    {
+      "id": "server",
+      "type": "container",
+      "name": "bazarr",
+      "image": "lscr.io/linuxserver/bazarr@sha256:3a820372f19fcb2981ea19fe4b5382934d67414afaba974bce831ddda0a64a02",
+      "env": {
+        "PUID": "1000",
+        "PGID": "1000",
+        "TZ": "Etc/UTC"
+      },
+      "ports": [
+        "6767"
+      ],
+      "volumes": [
+        "/services/bazarr/config:/config",
+        "/services/media/movies:/movies",
+        "/services/media/series:/series",
+        "/services/media/anime:/anime",
+        "/services/media/downloads:/downloads"
+      ]
+    },
+    {
+      "id": "runtime-config",
+      "type": "file",
+      "path": "/var/lib/mesh/bazarr/config.json",
+      "mode": "0600",
+      "content": "{}\n",
+      "merge": "json"
+    },
+    {
+      "id": "runtime",
+      "type": "container",
+      "name": "mesh-bazarr",
+      "network": "host",
+      "volumes": [
+        "/var/lib/mesh/bazarr/broker:/run/secrets/broker:ro",
+        "/var/lib/mesh/bazarr/api-key:/run/secrets/api-key:ro",
+        "/var/lib/mesh/bazarr/config.json:/run/config/config.json:ro",
+        "/services/bazarr/config:/var/lib/bazarr/config:ro"
+      ],
+      "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_BAZARR_URL": "http://127.0.0.1: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"
+      },
+      "restart-on": [
+        "runtime-config"
+      ],
+      "artifact": "runtime"
+    }
+  ],
+  "requires": [
+    "route"
+  ],
+  "contributes": {
+    "route": {
+      "label": "subs",
+      "port": 6767
+    }
+  },
+  "binds": {
+    "route": "/var/lib/mesh/bazarr/route.json"
+  },
+  "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/bazarr/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@novox/module-bazarr",
+  "version": "0.1.0",
+  "description": "bazarr — subtitle management. Its API client, tools and events live here (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/bazarr/tools/index.ts

@@ -0,0 +1,57 @@
+// bazarr's tools — its own code (novox/hq ADR 0039), importing bazarr's 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 { BazarrClient } from "../client.js";
+
+export function getBazarrTools(bazarr: BazarrClient): ToolDefinition[] {
+  return [
+    {
+      name: "bazarr_wanted",
+      description: "Episodes and movies still missing subtitles, with the languages each still needs.",
+      input: { limit: { type: "number", description: "max items per kind (default 50)" } },
+      run: async (args) => {
+        const wanted = await bazarr.getWanted(args.limit ? Number(args.limit) : 50);
+        return { count: wanted.length, wanted };
+      },
+    },
+    {
+      name: "bazarr_search_subtitles",
+      description: "Manually search subtitle providers for one wanted item — pass an episodeId or a radarrId.",
+      input: {
+        episodeId: { type: "number", description: "a Sonarr episode id (from bazarr_wanted)" },
+        radarrId: { type: "number", description: "a Radarr movie id (from bazarr_wanted)" },
+      },
+      run: async (args) => {
+        if (args.episodeId !== undefined) {
+          const results = await bazarr.searchEpisode(Number(args.episodeId));
+          return { kind: "episode", episodeId: Number(args.episodeId), count: results.length, results };
+        }
+        if (args.radarrId !== undefined) {
+          const results = await bazarr.searchMovie(Number(args.radarrId));
+          return { kind: "movie", radarrId: Number(args.radarrId), count: results.length, results };
+        }
+        throw new Error("pass either episodeId or radarrId");
+      },
+    },
+    {
+      name: "bazarr_history",
+      description: "Recent subtitle-download history — what was downloaded, for which title, from which provider.",
+      input: { limit: { type: "number", description: "max entries per kind (default 40)" } },
+      run: async (args) => {
+        const history = await bazarr.getHistory(args.limit ? Number(args.limit) : 40);
+        return { count: history.length, history };
+      },
+    },
+  ];
+}
+
+// Exposed only when Bazarr is configured; otherwise bazarr contributes no tools rather than
+// failing the whole runtime.
+registerModuleTools("bazarr", (env) => {
+  try {
+    return getBazarrTools(BazarrClient.fromEnv(env));
+  } catch {
+    return [];
+  }
+});

modules/bazarr/tsconfig.json

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

modules/bookshelf/Dockerfile

@@ -0,0 +1,24 @@
+# bookshelf'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 in
+# the base images, published like any other artifact — which 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 (novox/hq issue 044): the image this is COMPILED in and the
+# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
+ARG BUILD_BASE
+ARG RUNTIME_BASE
+
+FROM ${BUILD_BASE} AS build
+WORKDIR /app/modules/bookshelf
+COPY . .
+RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+COPY --from=build /app/modules/bookshelf/dist /app/modules/bookshelf/dist
+# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
+# 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/bookshelf/dist/index.js,/app/modules/bookshelf/dist/tools/index.js

modules/bookshelf/client.ts

@@ -0,0 +1,136 @@
+// The Bookshelf API client — bookshelf's own code, living in the module (novox/hq ADR 0039).
+// Ported from the shared hal `arr` client, but self-contained: in nox each Servarr app owns its own
+// copy, so a change to Bookshelf's API rebuilds only bookshelf and nothing else. Both this module's
+// tools and its events entrypoint import it, and nothing outside bookshelf does.
+//
+// Bookshelf is a Readarr fork (ghcr.io/pennydreadful/bookshelf). It speaks the Servarr v1 API; its
+// content is "book". Unlike Sonarr/Radarr it exposes no calendar endpoint, so there is no calendar
+// tool here — matching hal, which excluded bookshelf from its calendar-capable apps.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// Bookshelf speaks the v1 API; its content is "book".
+const API_VERSION = "v1";
+const CONTENT_ENDPOINT = "book";
+const APP_NAME = "Bookshelf";
+
+export interface BookshelfQueueItem {
+  /** The queue record id — stable while the item is in the queue, so events can diff on it. */
+  id: number;
+  title: string;
+  status: string;
+  size: string;
+  sizeleft: string;
+  timeleft?: string;
+}
+
+export interface BookshelfContentItem {
+  title: string;
+  author?: string;
+  year?: number;
+  status?: string;
+  monitored: boolean;
+}
+
+export class BookshelfClient {
+  readonly baseUrl: string;
+
+  constructor(
+    url: string,
+    private readonly apiKey: string,
+  ) {
+    this.baseUrl = url.replace(/\/$/, "");
+  }
+
+  /**
+   * Build from the module's resolved environment. The URL defaults to the server on this node (the
+   * runtime shares its network), and the API key is read from MESH_BOOKSHELF_API_KEY or, failing
+   * that, discovered from the server's own config.xml under MESH_BOOKSHELF_CONFIG_DIR — the same
+   * file Bookshelf writes it to, so a running server needs nothing configured by hand. Throws when
+   * no key can be found, so the tools/events simply do not load (the harness treats the throw as
+   * "exposes nothing").
+   */
+  static fromEnv(env: NodeJS.ProcessEnv = process.env): BookshelfClient {
+    const url = env.MESH_BOOKSHELF_URL ?? `http://127.0.0.1:${env.MESH_BOOKSHELF_PORT ?? "8787"}`;
+    const configDir = env.MESH_BOOKSHELF_CONFIG_DIR ?? "/config";
+    const apiKey = env.MESH_BOOKSHELF_API_KEY ?? BookshelfClient.detectApiKey(configDir);
+    if (!apiKey) {
+      throw new Error("Bookshelf not configured — set MESH_BOOKSHELF_API_KEY or make the config dir readable");
+    }
+    return new BookshelfClient(url, apiKey);
+  }
+
+  /** Discover the API key from the server's config.xml, falling back to null. Every Servarr app
+   *  writes <ApiKey> into config.xml at the root of its config directory. */
+  static detectApiKey(configDir: string): string | null {
+    const config = join(configDir, "config.xml");
+    if (existsSync(config)) {
+      const match = readFileSync(config, "utf8").match(/<ApiKey>([^<]+)<\/ApiKey>/);
+      if (match) return match[1];
+    }
+    return null;
+  }
+
+  private async get(endpoint: string, params?: Record<string, string>): Promise<unknown> {
+    const url = new URL(`${this.baseUrl}/api/${API_VERSION}/${endpoint}`);
+    if (params) {
+      for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
+    }
+    const res = await fetch(url.toString(), { headers: { "X-Api-Key": this.apiKey } });
+    if (!res.ok) throw new Error(`${APP_NAME} API /${endpoint}: ${res.status} ${await res.text()}`);
+    return res.json();
+  }
+
+  async getStatus(): Promise<{ appName: string; version: string }> {
+    const data = (await this.get("system/status")) as { appName?: string; version?: string };
+    return { appName: data.appName || APP_NAME, version: data.version ?? "unknown" };
+  }
+
+  async getContent(limit?: number): Promise<BookshelfContentItem[]> {
+    const data = await this.get(CONTENT_ENDPOINT);
+    const items: any[] = Array.isArray(data) ? data : ((data as any)?.records ?? []);
+    const mapped = items.map((item) => ({
+      title: item.title ?? "Unknown",
+      author: item.author?.authorName ?? item.authorName,
+      year: item.releaseDate ? new Date(item.releaseDate).getFullYear() : item.year,
+      status: item.status,
+      monitored: item.monitored ?? true,
+    }));
+    return limit ? mapped.slice(0, limit) : mapped;
+  }
+
+  /** Library search is a filter over existing content, not an indexer lookup — same as hal's. */
+  async searchContent(term: string): Promise<BookshelfContentItem[]> {
+    const all = await this.getContent();
+    const lower = term.toLowerCase();
+    return all.filter(
+      (item) =>
+        item.title.toLowerCase().includes(lower) ||
+        (item.author?.toLowerCase().includes(lower) ?? false),
+    );
+  }
+
+  async getQueue(): Promise<{ totalRecords: number; items: BookshelfQueueItem[] }> {
+    const data = (await this.get("queue", { pageSize: "50" })) as { totalRecords?: number; records?: any[] };
+    const records = data.records ?? [];
+    return {
+      totalRecords: data.totalRecords ?? records.length,
+      items: records.map((r) => ({
+        id: r.id,
+        title: r.title ?? r.book?.title ?? r.author?.authorName ?? "Unknown",
+        status: r.status ?? "unknown",
+        size: formatBytes(r.size ?? 0),
+        sizeleft: formatBytes(r.sizeleft ?? 0),
+        timeleft: r.timeleft,
+      })),
+    };
+  }
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes === 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  return `${(bytes / Math.pow(1024, i)).toFixed(1)} ${units[i]}`;
+}

modules/bookshelf/index.ts

@@ -0,0 +1,74 @@
+// bookshelf's events. The tool runtime imports this once the broker is bound. It watches the
+// download queue and turns its comings and goings into mesh events — the same mechanism radarr uses,
+// applied to a Servarr book manager.
+//
+// Emits (novox/hq ADR 0041/0042):
+//   module.bookshelf.book.grabbed        — a release entered the queue (Bookshelf grabbed it)
+//   module.bookshelf.download.completed  — a release left the queue, imported. This routing key is
+//                                          what the plex module consumes (module.*.download.completed)
+//                                          to rescan, so a new audiobook becomes a visible item.
+// Consumes: none.
+//
+// NOTE: the hal bookshelf module emitted no events (its hooks only did install-time provisioning).
+// This queue watcher is new in nox, modelled exactly on radarr's — bookshelf is a Servarr app with
+// the same queue semantics, so the diff-and-emit pattern carries over unchanged.
+//
+// The queue is polled and diffed, primed silently on the first look (like plex's index.ts) so a
+// restart mid-download does not re-announce everything already in flight as freshly grabbed.
+
+import { emit } from "@novox/mesh-sdk/events";
+import { BookshelfClient, type BookshelfQueueItem } from "./client.js";
+
+// Building the client throws when Bookshelf has no URL/key yet. Like the tools (see tools/index.ts),
+// the events entrypoint must not crash the runtime for that — it stays idle until configured.
+function buildClient(): BookshelfClient | null {
+  try {
+    return BookshelfClient.fromEnv();
+  } catch {
+    return null;
+  }
+}
+
+const bookshelf = buildClient();
+
+// Bookshelf removes an item from the queue once it has been imported; a "warning"/"failed" status is
+// how a stuck or broken grab shows itself, so we do not call those a completion when they vanish.
+const FAILED_STATUSES = new Set(["failed", "warning"]);
+
+const inQueue = new Map<number, BookshelfQueueItem>();
+let primed = false;
+
+async function pollQueue(bookshelf: BookshelfClient): Promise<void> {
+  const { items } = await bookshelf.getQueue();
+  const now = new Map(items.map((i) => [i.id, i]));
+
+  if (primed) {
+    // Entered the queue since last look — Bookshelf grabbed a release.
+    for (const [id, item] of now) {
+      if (!inQueue.has(id)) await emit("module.bookshelf.book.grabbed", { title: item.title, status: item.status });
+    }
+    // Left the queue — imported and done, unless it was last seen failing.
+    for (const [id, item] of inQueue) {
+      if (!now.has(id) && !FAILED_STATUSES.has(item.status)) {
+        await emit("module.bookshelf.download.completed", { title: item.title });
+      }
+    }
+  }
+
+  inQueue.clear();
+  for (const [id, item] of now) inQueue.set(id, item);
+  primed = true;
+}
+
+const tick = (fn: () => Promise<void>, everyMs: number): void => {
+  const run = (): void => void fn().catch((err) => console.error(`[bookshelf] ${err}`));
+  setInterval(run, everyMs);
+  run();
+};
+
+if (bookshelf) {
+  tick(() => pollQueue(bookshelf), 30_000);
+  console.log("[bookshelf] watching the download queue, emitting grabs and completions");
+} else {
+  console.log("[bookshelf] not configured — events idle until an API key is available");
+}

modules/bookshelf/module.json

@@ -0,0 +1,117 @@
+{
+  "module": "bookshelf",
+  "version": "1",
+  "slug": "books",
+  "capabilities": [
+    "container-runtime"
+  ],
+  "emits": [
+    "module.bookshelf.book.grabbed",
+    "module.bookshelf.download.completed"
+  ],
+  "consumes": [],
+  "own-secrets": {
+    "broker": "/var/lib/mesh/bookshelf/broker"
+  },
+  "listens": [
+    {
+      "port": 8787,
+      "protocol": "tcp",
+      "from": "mesh",
+      "why": "managing the ebook/audiobook library"
+    }
+  ],
+  "accesses": [
+    {
+      "path": "/services/media/books",
+      "mode": "read-write"
+    },
+    {
+      "path": "/services/media/downloads",
+      "mode": "read-write"
+    }
+  ],
+  "resources": [
+    {
+      "id": "mesh-state",
+      "type": "directory",
+      "path": "/var/lib/mesh/bookshelf",
+      "mode": "0700"
+    },
+    {
+      "id": "config",
+      "type": "directory",
+      "path": "/services/bookshelf/config",
+      "mode": "0700",
+      "owner": "1000:1000"
+    },
+    {
+      "id": "server",
+      "type": "container",
+      "name": "bookshelf",
+      "image": "ghcr.io/pennydreadful/bookshelf@sha256:388eecc94362580eae31ee0a454be6af516f8a311f8432a521c202fb475f4359",
+      "env": {
+        "PUID": "1000",
+        "PGID": "1000",
+        "TZ": "Etc/UTC"
+      },
+      "ports": [
+        "8787"
+      ],
+      "volumes": [
+        "/services/bookshelf/config:/config",
+        "/services/media/books:/books",
+        "/services/media/downloads:/downloads"
+      ]
+    },
+    {
+      "id": "runtime",
+      "type": "container",
+      "name": "mesh-bookshelf",
+      "network": "host",
+      "volumes": [
+        "/var/lib/mesh/bookshelf/broker:/run/secrets/broker:ro",
+        "/services/bookshelf/config:/var/lib/bookshelf/config:ro"
+      ],
+      "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_BOOKSHELF_URL": "http://127.0.0.1:8787",
+        "MESH_BOOKSHELF_CONFIG_DIR": "/var/lib/bookshelf/config"
+      },
+      "artifact": "runtime"
+    }
+  ],
+  "requires": [
+    "route"
+  ],
+  "contributes": {
+    "route": {
+      "label": "books",
+      "port": 8787
+    }
+  },
+  "binds": {
+    "route": "/var/lib/mesh/bookshelf/route.json"
+  },
+  "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/bookshelf/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@novox/module-bookshelf",
+  "version": "0.1.0",
+  "description": "bookshelf — ebook/audiobook management (Readarr fork). Its API client, tools and events live here (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/bookshelf/tools/index.ts

@@ -0,0 +1,69 @@
+// bookshelf's tools — ported from the shared hal `arr` sdk (novox/hq ADR 0039), importing
+// bookshelf's own client. They return structured data (not the pre-formatted text hal returned); the
+// mesh serves them through the sdk's tool harness. Bookshelf has no calendar endpoint, so there is
+// no calendar tool — matching hal, which excluded it from its calendar-capable apps.
+
+import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
+import { BookshelfClient } from "../client.js";
+
+export function getBookshelfTools(bookshelf: BookshelfClient): ToolDefinition[] {
+  return [
+    {
+      name: "bookshelf_status",
+      description: "Bookshelf status overview: version, book count, monitored count, queue size.",
+      input: {},
+      run: async () => {
+        const [status, content, queue] = await Promise.all([
+          bookshelf.getStatus(),
+          bookshelf.getContent(),
+          bookshelf.getQueue(),
+        ]);
+        return {
+          app: status.appName,
+          version: status.version,
+          books: content.length,
+          monitored: content.filter((c) => c.monitored).length,
+          queue: queue.totalRecords,
+        };
+      },
+    },
+    {
+      name: "bookshelf_library",
+      description: "List books from the Bookshelf library.",
+      input: { limit: { type: "number", description: "max items to return (default 50)" } },
+      run: async (args) => {
+        const items = await bookshelf.getContent(args.limit ? Number(args.limit) : 50);
+        return { count: items.length, books: items };
+      },
+    },
+    {
+      name: "bookshelf_search",
+      description:
+        "Search the Bookshelf library for books by title or author (filters existing content, not indexers).",
+      input: { query: { type: "string", description: "the search term" } },
+      run: async (args) => {
+        const query = String(args.query);
+        return { query, results: await bookshelf.searchContent(query) };
+      },
+    },
+    {
+      name: "bookshelf_queue",
+      description: "Show the Bookshelf download queue — what is downloading and how far along.",
+      input: {},
+      run: async () => {
+        const queue = await bookshelf.getQueue();
+        return { count: queue.totalRecords, items: queue.items };
+      },
+    },
+  ];
+}
+
+// The tools exist only when Bookshelf is configured; without a URL and key, bookshelf contributes
+// none rather than failing the whole runtime.
+registerModuleTools("bookshelf", (env) => {
+  try {
+    return getBookshelfTools(BookshelfClient.fromEnv(env));
+  } catch {
+    return [];
+  }
+});

modules/bookshelf/tsconfig.json

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

modules/builder/Dockerfile

@@ -1,25 +0,0 @@
-ARG GO_BASE
-ARG ALPINE_BASE
-# builder's own image: the build machine itself, compiled into a container.
-#
-# **The source is not vendored here.** builder's actual code — cmd/mesh-builder, internal/builder,
-# internal/catalogue — lives in the mesh-controller repository, the same control plane it is one
-# half of. This module ships the packaging, not a second copy of the source, so the build context
-# is the mesh-controller repository root (declared under build.artifacts[].context), and this
-# Dockerfile compiles ./cmd/mesh-builder from it — the same shape route-proxy already uses for the
-# same reason.
-FROM ${GO_BASE} AS build
-WORKDIR /src
-COPY go.mod go.sum ./
-RUN go mod download
-COPY . .
-RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -o /mesh-builder ./cmd/mesh-builder
-
-# Unlike mesh-controller's own FROM scratch (ADR 0006: nothing to audit but one binary), the build
-# machine's whole job is shelling out to git and docker — it needs a real userland to do that in,
-# not a second copy of either tool vendored into this image. apk installs both from the base's own
-# packages, not fetched on its own at build time.
-FROM ${ALPINE_BASE}
-RUN apk add --no-cache docker-cli git
-COPY --from=build /mesh-builder /usr/local/bin/mesh-builder
-ENTRYPOINT ["/usr/local/bin/mesh-builder"]

modules/builder/module.json

@@ -6,83 +6,73 @@
   ],
   "claims": [
     {
-      "name": "mesh-build-machine",
+      "name": "the-build-machine",
-      "scope": "mesh"
+      "scope": "node"
     }
   ],
   "requires": [
-    "artifact-store",
+    "artifact-store"
-    "npm-package-registry"
+  ],
+  "emits": [
+    "module.builder.built"
   ],
-  "binds": {
-    "npm-package-registry": "${dir:mesh-state}/package-registry.json"
-  },
-  "secrets": {
-    "npm-package-registry": "${dir:mesh-state}/package-registry.secret"
-  },
   "own-secrets": {
-    "broker": "${dir:mesh-state}/broker"
+    "broker": "/var/lib/mesh/builder/broker",
+    "npm-password": "/var/lib/mesh/builder/npm-password"
   },
   "resources": [
     {
       "id": "mesh-state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/mesh/builder",
-      "place": "mesh"
+      "mode": "0700"
     },
     {
       "id": "workspace",
       "type": "directory",
+      "path": "/var/lib/builder/workspace",
       "mode": "0700"
     },
     {
       "id": "builder-env",
       "type": "file",
-      "path": "${dir:mesh-state}/builder.env",
+      "path": "/var/lib/mesh/builder/builder.env",
       "mode": "0600",
-      "content": "MESH_BROKER_FILE=/run/mesh/broker\nMESH_NODE=${machine:name}\nMESH_REGISTRY=${bound:artifact-store:at}:${bound:artifact-store:port}\nMESH_PACKAGE_BINDING=/run/mesh/package-registry.json\nMESH_NPM_TOKEN_FILE=/run/mesh/package-registry.secret\nMESH_WORKSPACE=${dir:workspace}\n"
+      "content": "MESH_BROKER_FILE=/run/mesh/broker\nMESH_NODE=${machine:name}\nMESH_REGISTRY=${bound:artifact-store:at}:${bound:artifact-store:port}\nMESH_PACKAGE_BINDING=/run/mesh/package-registry.json\nMESH_NPM_TOKEN_FILE=/run/mesh/npm-password\nMESH_WORKSPACE=/var/lib/builder/workspace\n"
+    },
+    {
+      "id": "package-binding",
+      "type": "file",
+      "path": "/var/lib/mesh/builder/package-registry.json",
+      "mode": "0600",
+      "merge": "json",
+      "protected": [
+        "provision",
+        "from",
+        "at",
+        "as"
+      ],
+      "content": "{\"provision\": \"package-registry\", \"from\": \"gitea\", \"at\": \"127.0.0.1\", \"as\": \"mesh-builder\", \"serves\": {\"scheme\": \"http\", \"port\": 3000, \"npm-path\": \"/api/packages/novox/npm/\"}}\n"
     },
     {
       "id": "server",
       "type": "container",
       "name": "mesh-builder",
-      "artifact": "server",
+      "image": "mesh-builder@sha256:0000000000000000000000000000000000000000000000000000000000000000",
       "env-file": [
-        "${dir:mesh-state}/builder.env"
+        "/var/lib/mesh/builder/builder.env"
       ],
       "volumes": [
-        "${dir:mesh-state}:/run/mesh:ro",
+        "/var/lib/mesh/builder:/run/mesh:ro",
-        "${dir:workspace}:${dir:workspace}",
+        "/var/lib/builder/workspace:/var/lib/builder/workspace",
         "/var/run/docker.sock:/var/run/docker.sock"
       ],
       "restart-on": [
-        "builder-env"
+        "builder-env",
+        "package-binding",
+        "needs-npm-password"
       ],
       "network": "host"
     }
-  ],
-  "build": {
-    "artifacts": [
-      {
-        "name": "server",
-        "kind": "image",
-        "from": "Dockerfile",
-        "context": {
-          "seat": "git",
-          "repository": "novox/mesh-controller",
-          "ref": "main"
-        }
-      }
-    ],
-    "on": [
-      {
-        "arg": "GO_BASE",
-        "image": "golang@sha256:8ac98ca534ac3f51e1f420a1dd2c15e74c75cfa0f23f3ad27eb5d7236c349a0c"
-      },
-      {
-        "arg": "ALPINE_BASE",
-        "image": "alpine@sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc"
-      }
   ]
-  }
 }

modules/ca-trust/module.json

@@ -1,56 +0,0 @@
-{
-  "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/cloudflare-dns/module.json

@@ -12,41 +12,42 @@
     "public-dns": {}
   },
   "grants": {
-    "public-dns": "${dir:grants}"
+    "public-dns": "/var/lib/cloudflare-dns/grants"
   },
   "receives": {
-    "public-dns": "${dir:grants}/mesh.json"
+    "public-dns": "/var/lib/cloudflare-dns/grants/mesh.json"
   },
   "own-secrets": {
-    "token": "${dir:state}/token",
+    "token": "/var/lib/cloudflare-dns/token",
-    "broker": "${dir:mesh-state}/broker"
+    "broker": "/var/lib/mesh/cloudflare-dns/broker"
   },
   "emits": [
-    "record.created",
+    "module.cloudflare-dns.record.created",
-    "record.removed"
+    "module.cloudflare-dns.record.removed"
   ],
   "resources": [
     {
       "id": "mesh-state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/mesh/cloudflare-dns",
-      "place": "mesh"
+      "mode": "0700"
     },
     {
       "id": "state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/cloudflare-dns",
-      "place": "."
+      "mode": "0700"
     },
     {
       "id": "grants",
       "type": "directory",
+      "path": "/var/lib/cloudflare-dns/grants",
       "mode": "0700"
     },
     {
       "id": "config",
       "type": "file",
-      "path": "${dir:state}/config.json",
+      "path": "/var/lib/cloudflare-dns/config.json",
       "merge": "json",
       "content": "{}",
       "mode": "0600"
@@ -57,10 +58,10 @@
       "name": "mesh-cloudflare-dns",
       "network": "host",
       "volumes": [
-        "${dir:state}/config.json:/run/config/config.json:ro",
+        "/var/lib/cloudflare-dns/config.json:/run/config/config.json:ro",
-        "${dir:grants}:/grants",
+        "/var/lib/cloudflare-dns/grants:/grants",
-        "${dir:state}/token:/run/secrets/token:ro",
+        "/var/lib/cloudflare-dns/token:/run/secrets/token:ro",
-        "${dir:mesh-state}/broker:/run/secrets/broker:ro"
+        "/var/lib/mesh/cloudflare-dns/broker:/run/secrets/broker:ro"
       ],
       "env": {
         "MESH_CLOUDFLARE_TOKEN_FILE": "/run/secrets/token",

modules/cloudflare-dns/provisioner/index.ts

@@ -20,7 +20,7 @@ runProvisioner("public-dns", {
   async create(p: Provision): Promise<void> {
     const fqdn = cloudflare.nameFor(p.as);
     await cloudflare.upsert(fqdn);
-    await announce("record.created", {
+    await announce("module.cloudflare-dns.record.created", {
       name: fqdn,
       target: cloudflare.ingress,
       consumer: p.consumer ?? "",
@@ -30,7 +30,7 @@ runProvisioner("public-dns", {
   async remove(p: { as: string }): Promise<void> {
     const fqdn = cloudflare.nameFor(p.as);
     await cloudflare.remove(fqdn);
-    await announce("record.removed", { name: fqdn, consumer: p.as });
+    await announce("module.cloudflare-dns.record.removed", { name: fqdn, consumer: p.as });
   },
 });
 

modules/confluence/module.json

@@ -3,26 +3,26 @@
   "version": "1",
   "slug": "confl",
   "own-secrets": {
-    "token": "${dir:state}/token",
+    "token": "/var/lib/confluence/token",
-    "broker": "${dir:mesh-state}/broker"
+    "broker": "/var/lib/mesh/confluence/broker"
   },
   "resources": [
     {
       "id": "mesh-state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/mesh/confluence",
-      "place": "mesh"
+      "mode": "0700"
     },
     {
       "id": "state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/confluence",
-      "place": "."
+      "mode": "0700"
     },
     {
       "id": "config",
       "type": "file",
-      "path": "${dir:state}/config.json",
+      "path": "/var/lib/confluence/config.json",
       "merge": "json",
       "content": "{}",
       "mode": "0600"
@@ -33,9 +33,9 @@
       "name": "mesh-runtime-confluence",
       "network": "host",
       "volumes": [
-        "${dir:state}/config.json:/run/config/config.json:ro",
+        "/var/lib/confluence/config.json:/run/config/config.json:ro",
-        "${dir:state}/token:/run/secrets/token:ro",
+        "/var/lib/confluence/token:/run/secrets/token:ro",
-        "${dir:mesh-state}/broker:/run/secrets/broker:ro"
+        "/var/lib/mesh/confluence/broker:/run/secrets/broker:ro"
       ],
       "env": {
         "MESH_CONFLUENCE_TOKEN_FILE": "/run/secrets/token",

modules/de-spiegel/module.json

@@ -11,36 +11,35 @@
   "contributes": {
     "route": {
       "label": "de-spiegel",
-      "endpoint": "web"
+      "port": 35621
     }
   },
   "binds": {
-    "route": "${dir:state}/route.json"
+    "route": "/var/lib/de-spiegel/route.json"
   },
   "own-secrets": {
-    "smtp-user": "${dir:state}/smtp-user.secret",
+    "smtp-user": "/var/lib/de-spiegel/smtp-user.secret",
-    "smtp-pass": "${dir:state}/smtp-pass.secret"
+    "smtp-pass": "/var/lib/de-spiegel/smtp-pass.secret"
   },
   "listens": [
     {
-      "name": "web",
       "port": 35621,
       "protocol": "tcp",
       "from": "mesh",
-      "why": "the de-spiegel site and its /contact endpoint over http; its public name is a route grant, and route-proxy reaches it on this published port"
+      "why": "the de-spiegel site and its /contact endpoint over http; the public name de-spiegel.novox.be is a route grant, and route-proxy reaches it on this published port"
     }
   ],
   "resources": [
     {
       "id": "state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/de-spiegel",
-      "place": "."
+      "mode": "0700"
     },
     {
       "id": "server-env",
       "type": "file",
-      "path": "${dir:state}/server.env",
+      "path": "/var/lib/de-spiegel/server.env",
       "mode": "0600",
       "content": "SMTP_AUTH_USER=${secret:smtp-user}\nSMTP_AUTH_PASS=${secret:smtp-pass}\n"
     },
@@ -56,15 +55,12 @@
       "image": "registry-api.novox.be/novox/de-spiegel@sha256:e144b72ce9c145870470d765343549f2c60211728cd118b9ff0e4029f36342ba",
       "network": "de-spiegel",
       "env-file": [
-        "${dir:state}/server.env"
+        "/var/lib/de-spiegel/server.env"
       ],
       "ports": [
-        "35621"
+        "35621:35621"
       ],
-      "secrets-in-environment": "the application's own code reads SMTP_AUTH_USER/PASS from the environment (de-spiegel server/index.js); converting is that repository's change",
+      "secrets-in-environment": "the application's own code reads SMTP_AUTH_USER/PASS from the environment (de-spiegel server/index.js); converting is that repository's change"
-      "names-on-purpose": {
-        "registry-api.novox.be": "built outside the mesh, from the application's own repository, and pulled from the registry that built it; moves when that repository is a build source on the git seat (novox/hq ADR 0155, issue 122)"
-      }
     }
   ]
 }

modules/dhcpcd/README.md

@@ -1,43 +0,0 @@
-# dhcpcd
-
-The uplink seat's module for a machine whose own network is dhcpcd's (novox/hq ADR 0117). It
-asks two things of dhcpcd, and nothing else: leave the resolver file to the mesh, and leave the
-private network's interface alone. It never declares an interface, an address, a route, a
-wireless network or its credentials — the link dhcpcd keeps is the only channel the mesh reaches
-the machine over.
-
-## What it writes
-
-Two lines into `/etc/dhcpcd.conf`, as the mesh's marked region (`into: block`) — dhcpcd reads no
-drop-in directory, so the mesh writes into its one file rather than over it (ADR 0102):
-
-- `nohook resolv.conf` — dhcpcd's resolv.conf hook rewrites `/etc/resolv.conf` on every lease it
-  takes or renews, which would silently replace the resolver `resolv-conf` names.
-- `denyinterfaces mesh0` — dhcpcd never asks for a lease on the private network's interface, and
-  never takes it down. dhcpcd leaves a point-to-point interface alone by default; this says so
-  rather than relying on it.
-
-**At the start of the file** (`at: start`). Both are global options, and dhcpcd reads every line
-after an `interface` or `ssid` line as that interface's own. A configured machine's file ends in
-exactly such a block (the interface, its static address), so appended at the end these two would
-quietly apply to one interface only.
-
-## Why it declares no service
-
-dhcpcd is the machine's, not the mesh's. The mesh never starts, stops or enables it: stopping it
-drops the address the machine is reached at, and a module unassigned by mistake must not be able
-to do that. And there is nothing to reload it with — `dhcpcd.service` reports `CanReload=no`, and
-a restart drops the lease. So the two lines take effect at **dhcpcd's next start**.
-
-On an adopted machine that is normally no gap: the predecessor wrote the same `nohook` line, and
-it is already in force. **On a machine that was not adopted, it is one:** until dhcpcd next
-starts (a reboot, or the operator restarting it in a window of their choosing), a lease renewal
-still rewrites `/etc/resolv.conf`, and `resolv-conf` puts it back at the next push. Assign this
-module before `resolv-conf` on such a machine, and restart dhcpcd once, by hand, when losing the
-link for a moment is acceptable.
-
-## One manager per machine
-
-It claims `the-uplink`: a machine runs one network manager, and assigning a second module that
-claims the seat is refused. Assigning this one to a machine whose network is NetworkManager's
-installs the package and writes the two lines, and starts nothing.

modules/dhcpcd/module.json

@@ -1,31 +0,0 @@
-{
-  "module": "dhcpcd",
-  "version": "1",
-  "capabilities": [
-    "package-manager",
-    "service-manager",
-    "uplink-dhcpcd"
-  ],
-  "claims": [
-    {
-      "name": "node-uplink",
-      "scope": "node"
-    }
-  ],
-  "resources": [
-    {
-      "id": "package",
-      "type": "package",
-      "package": "dhcpcd"
-    },
-    {
-      "id": "config",
-      "type": "file",
-      "path": "/etc/dhcpcd.conf",
-      "mode": "0644",
-      "into": "block",
-      "at": "start",
-      "content": "# The mesh's two lines (module dhcpcd, novox/hq ADR 0117). Global options, so\n# kept above any interface line; read at dhcpcd's next start.\nnohook resolv.conf\ndenyinterfaces mesh0\n"
-    }
-  ]
-}

modules/distribution/index.ts

@@ -33,7 +33,7 @@ async function pollCatalog(): Promise<void> {
     for (const tag of tags) {
       const id = `${repo}:${tag}`;
       if (!seen.has(id)) {
-        if (primed) await emit("image.pushed", { repo, tag });
+        if (primed) await emit("module.registry.image.pushed", { repo, tag });
         seen.add(id);
       }
     }

modules/distribution/module.json

@@ -9,15 +9,15 @@
   ],
   "claims": [
     {
-      "name": "mesh-artifact-store",
+      "name": "the-artifact-store",
-      "scope": "mesh"
+      "scope": "node"
     }
   ],
   "capabilities": [
     "container-runtime"
   ],
   "emits": [
-    "image.pushed"
+    "module.registry.image.pushed"
   ],
   "own-secrets": {
     "broker": "/var/lib/mesh/registry/broker"
@@ -29,7 +29,6 @@
   },
   "listens": [
     {
-      "name": "registry",
       "port": 5000,
       "protocol": "tcp",
       "from": "mesh",
@@ -43,12 +42,6 @@
       "path": "/var/lib/mesh/registry",
       "mode": "0700"
     },
-    {
-      "id": "registry-data",
-      "type": "directory",
-      "path": "/var/lib/mesh-registry",
-      "mode": "0700"
-    },
     {
       "id": "store",
       "type": "container",
@@ -58,7 +51,7 @@
         "5000:5000"
       ],
       "volumes": [
-        "/var/lib/mesh-registry:/var/lib/registry"
+        "mesh-registry-data:/var/lib/registry"
       ]
     }
   ]

modules/dnsmasq/index.ts

@@ -20,10 +20,10 @@ async function poll(): Promise<void> {
   const now = new Map((await dnsmasq.answeredNames()).map((a) => [a.name, a.address]));
   if (primed) {
     for (const [name, address] of now) {
-      if (!known.has(name)) await emit("name.added", { name, address });
+      if (!known.has(name)) await emit("module.dnsmasq.name.added", { name, address });
     }
     for (const [name] of known) {
-      if (!now.has(name)) await emit("name.removed", { name });
+      if (!now.has(name)) await emit("module.dnsmasq.name.removed", { name });
     }
   }
   known.clear();

modules/fail2ban/module.json

@@ -6,7 +6,7 @@
   ],
   "claims": [
     {
-      "name": "node-intrusion-prevention",
+      "name": "the-intrusion-prevention",
       "scope": "node"
     }
   ],
@@ -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\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"
+      "content": "[INCLUDES]\n\nbefore = paths-arch.conf\n\n[DEFAULT]\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"
     },
     {
       "id": "jail-sshd",
@@ -42,14 +42,6 @@
       "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/Dockerfile

@@ -23,7 +23,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 client.ts token.ts index.ts provisioner/index.ts tools/index.ts \
+RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts provisioner/index.ts tools/index.ts \
       --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 
 FROM ${RUNTIME_BASE}

modules/gitea/client.ts

@@ -4,13 +4,10 @@
 // does.
 
 import { readFileSync } from "node:fs";
-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;
@@ -36,23 +33,12 @@ 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;
   html_url: string;
 }
 
-export interface GiteaComment {
-  id: number;
-  user?: string;
-  body: string;
-  created_at?: string;
-  html_url: string;
-}
-
 export interface GiteaLabel {
   id: number;
   name: string;
@@ -67,67 +53,44 @@ function meshConfig(file?: string): Record<string, string> {
 
 export class GiteaClient {
   readonly baseUrl: string;
-  private readonly tokens: TokenSource;
+  private cachedUsername: string | null = null;
 
-  /** A token given as a string is one somebody configured; a source decides for itself (token.ts). */
+  constructor(
-  constructor(url: string, token: string | TokenSource) {
+    url: string,
+    private readonly token: string,
+  ) {
     this.baseUrl = url.replace(/\/+$/, "");
-    this.tokens = typeof token === "string" ? new ConfiguredToken(token) : token;
   }
 
   /**
-   * Build from the module's resolved environment. The URL comes from MESH_GITEA_URL (the mesh's own
+   * Build from the module's resolved environment. URL and token come from MESH_GITEA_URL /
-   * name), falling back to the bare GITEA_URL and to the forge's loopback port. The token, in order:
+   * MESH_GITEA_TOKEN (the mesh's own names), falling back to the bare GITEA_* names and, for the
-   * one configured in settings or the environment (MESH_GITEA_TOKEN / GITEA_TOKEN), which wins; else
+   * URL, to the forge's loopback port. A token is required — without one there is no authenticated
-   * one the module mints for itself with the admin account the vault delivered and keeps in its own
+   * call to make, so this throws rather than hand back a client that fails on first use.
-   * state (token.ts; hq issue 100). Throws only when neither is possible, naming what is missing,
-   * rather than hand back a client that fails on first use.
    */
   static fromEnv(env: NodeJS.ProcessEnv = process.env): GiteaClient {
     const cfg = meshConfig(env.MESH_GITEA_CONFIG_FILE);
     const url = cfg.url ?? env.MESH_GITEA_URL ?? env.GITEA_URL ?? `http://127.0.0.1:${env.GITEA_PORT ?? "3000"}`;
-    const configured = cfg.token ?? env.MESH_GITEA_TOKEN ?? env.GITEA_TOKEN;
+    const token = cfg.token ?? env.MESH_GITEA_TOKEN ?? env.GITEA_TOKEN;
-    if (configured) return new GiteaClient(url, new ConfiguredToken(configured));
+    if (!token) throw new Error("no Gitea token — set MESH_GITEA_TOKEN");
-    return new GiteaClient(url, MintedToken.fromEnv(url, env));
+    return new GiteaClient(url, token);
   }
 
-  /**
-   * One authenticated call. A 401 is the forge saying the token is not one it knows — the case
-   * after the forge's data was restored, or after somebody revoked it — so the source is asked to
-   * renew once and the call is repeated with the new token. A configured token has nothing to renew
-   * with, and its source says so.
-   */
   private async request<T = unknown>(path: string, options: RequestInit = {}): Promise<T> {
-    let token = await this.tokens.current();
+    const res = await fetch(`${this.baseUrl}/api/v1${path}`, {
-    let res = await this.send(path, options, token);
+      ...options,
-    if (res.status === 401) {
+      headers: {
-      token = await this.tokens.renew(token);
+        "Content-Type": "application/json",
-      res = await this.send(path, options, token);
+        Authorization: `token ${this.token}`,
-    } else if (res.status === 403) {
+        ...(options.headers as Record<string, string> | undefined),
-      // A kept token minted before a scope was added lacks it. The forge says so; the source
+      },
-      // re-mints with the whole list and the call is retried once. Any other 403 stays a 403.
+    });
-      const text = await res.text();
-      if (!MintedToken.lacksScope(res.status, text)) throw new Error(`Gitea API ${path}: 403 ${text}`);
-      token = await this.tokens.renew(token);
-      res = await this.send(path, options, token);
-    }
     if (!res.ok) throw new Error(`Gitea API ${path}: ${res.status} ${await res.text()}`);
     if (res.status === 204) return null as T;
     const text = await res.text();
     return (text ? JSON.parse(text) : null) as T;
   }
 
-  private send(path: string, options: RequestInit, token: string): Promise<Response> {
-    return fetch(`${this.baseUrl}/api/v1${path}`, {
-      ...options,
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `token ${token}`,
-        ...(options.headers as Record<string, string> | undefined),
-      },
-    });
-  }
-
   /** Generic authenticated API call — the escape hatch for endpoints without a dedicated method.
    *  Path is relative to /api/v1. */
   async api<T = unknown>(path: string, options: RequestInit = {}): Promise<T> {
@@ -136,23 +99,9 @@ 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 found = await this.request<{ data?: any[] }>(`/repos/search?page=${page}&limit=${limit}`);
+    const repos = await this.request<any[]>(`/user/repos?page=${page}&limit=${limit}`);
-    return (found?.data ?? []).map(GiteaClient.mapRepo);
+    return (repos ?? []).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: {
@@ -244,17 +193,6 @@ 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,
@@ -265,64 +203,6 @@ export class GiteaClient {
     );
   }
 
-  /** Close or reopen a pull request without merging it. A pull request is an issue to the forge's
-   *  state machine, and the pulls endpoint takes the same `state`. */
-  async setPullState(owner: string, repo: string, index: number, state: "open" | "closed"): Promise<GiteaPull> {
-    return GiteaClient.mapPull(
-      await this.request<any>(`/repos/${owner}/${repo}/pulls/${index}`, { method: "PATCH", body: JSON.stringify({ state }) }),
-    );
-  }
-
-  /** Change a pull request's title or body; a field left undefined is left alone. */
-  async updatePullRequest(owner: string, repo: string, index: number, data: { title?: string; body?: string }): Promise<GiteaPull> {
-    return GiteaClient.mapPull(
-      await this.request<any>(`/repos/${owner}/${repo}/pulls/${index}`, { method: "PATCH", body: JSON.stringify(data) }),
-    );
-  }
-
-  /** The unified diff of a pull request, as text. */
-  async pullDiff(owner: string, repo: string, index: number): Promise<string> {
-    return this.requestText(`/repos/${owner}/${repo}/pulls/${index}.diff`);
-  }
-
-  /** Every comment on an issue or pull request, oldest first. */
-  async listComments(owner: string, repo: string, index: number): Promise<GiteaComment[]> {
-    const raw = await this.request<any[]>(`/repos/${owner}/${repo}/issues/${index}/comments`);
-    return (raw ?? []).map((c) => ({
-      id: Number(c?.id ?? 0),
-      user: c?.user?.login,
-      body: String(c?.body ?? ""),
-      created_at: c?.created_at,
-      html_url: String(c?.html_url ?? ""),
-    }));
-  }
-
-  /** One file's contents at a ref (default the repository's default branch), decoded. */
-  async getFile(owner: string, repo: string, path: string, ref?: string): Promise<{ path: string; ref?: string; sha: string; size: number; content: string }> {
-    const qs = ref ? `?ref=${encodeURIComponent(ref)}` : "";
-    const f = await this.request<any>(`/repos/${owner}/${repo}/contents/${path.split("/").map(encodeURIComponent).join("/")}${qs}`);
-    if (!f || f.type !== "file") throw new Error(`Gitea API: ${path} is not a file`);
-    const content = f.encoding === "base64" ? Buffer.from(String(f.content ?? ""), "base64").toString("utf8") : String(f.content ?? "");
-    return { path, ref, sha: String(f.sha ?? ""), size: Number(f.size ?? content.length), content };
-  }
-
-  async listBranches(owner: string, repo: string): Promise<{ name: string; commit: string; protected: boolean }[]> {
-    const raw = await this.request<any[]>(`/repos/${owner}/${repo}/branches?limit=100`);
-    return (raw ?? []).map((b) => ({ name: String(b?.name ?? ""), commit: String(b?.commit?.id ?? ""), protected: Boolean(b?.protected) }));
-  }
-
-  async deleteBranch(owner: string, repo: string, branch: string): Promise<void> {
-    await this.request(`/repos/${owner}/${repo}/branches/${encodeURIComponent(branch)}`, { method: "DELETE" });
-  }
-
-  /** A request whose answer is text, not JSON — a diff. Same token handling as request(). */
-  private async requestText(path: string): Promise<string> {
-    const token = await this.tokens.current();
-    const res = await this.send(path, { headers: { Accept: "text/plain" } }, token);
-    if (!res.ok) throw new Error(`Gitea API ${path}: ${res.status} ${await res.text()}`);
-    return res.text();
-  }
-
   async mergePullRequest(owner: string, repo: string, index: number, method = "merge", deleteBranch = false): Promise<void> {
     await this.request(`/repos/${owner}/${repo}/pulls/${index}/merge`, {
       method: "POST",
@@ -335,7 +215,6 @@ 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),
@@ -363,8 +242,6 @@ 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,
@@ -458,34 +335,24 @@ export class GiteaAdmin {
     GiteaAdmin.fail("/orgs", res);
   }
 
-  /** Ensure the org's package team exists with exactly these units, and return its id. Found or
+  /** Ensure the org's package team exists, granting read+write on packages, and return its id. The
-   *  created, the units are applied either way — a team is configuration the reconcile loop owns,
+   *  team is found by name if it is already there, created otherwise; a lost create race is resolved
-   *  the same as a user's password, so a unit this code gains reaches a team that already exists
+   *  by re-listing. */
-   *  rather than only the next mesh raised from scratch. A lost create race is resolved by
-   *  re-listing. */
   async ensureTeam(org: string, team: string, packageWrite: boolean): Promise<number> {
-    // The units a consumer needs, and no more. `units_map` is exhaustive — a unit not named is a
-    // unit the team does not have — so code read must be said here: without it gitea answers a
-    // member's clone of a private repository with "not found", which is how the builder's first
-    // credentialed clone failed against a team that named only packages.
-    const units = {
-      permission: "read",
-      units_map: { "repo.code": "read", "repo.packages": packageWrite ? "write" : "read" },
-      includes_all_repositories: true,
-      can_create_org_repo: false,
-    };
     const found = await this.findTeam(org, team);
-    if (found !== null) {
+    if (found !== null) return found;
-      const patch = await this.request(`/teams/${found}`, {
-        method: "PATCH",
-        body: JSON.stringify({ name: team, ...units }),
-      });
-      if (patch.status === 200) return found;
-      GiteaAdmin.fail(`/teams/${found}`, patch);
-    }
     const res = await this.request(`/orgs/${encodeURIComponent(org)}/teams`, {
       method: "POST",
-      body: JSON.stringify({ name: team, ...units }),
+      body: JSON.stringify({
+        name: team,
+        permission: "read",
+        // Package access is a per-unit grant; the team needs write on the packages unit and nothing
+        // else. includes_all_repositories keeps the team's repo view whole without widening its
+        // repo permission beyond read.
+        units_map: { "repo.packages": packageWrite ? "write" : "read" },
+        includes_all_repositories: true,
+        can_create_org_repo: false,
+      }),
     });
     if (res.status === 201) return Number(res.body?.id);
     if (res.status === 422 || res.status === 409) {
@@ -496,18 +363,14 @@ export class GiteaAdmin {
   }
 
   private async findTeam(org: string, team: string): Promise<number | null> {
-    const res = await this.request(`/orgs/${encodeURIComponent(org)}/teams?limit=50`);
+    const res = await this.request(`/orgs/${encodeURIComponent(org)}/teams`);
     if (res.status !== 200) return null;
     const match = (res.body as any[] | null)?.find((t) => t?.name === team);
     return match ? Number(match.id) : null;
   }
 
   /** Ensure a user exists with exactly this password. Created if absent; if already there, its
-   *  password is patched — so the mesh minting a new secret takes on the next reconcile.
+   *  password is patched — so the mesh minting a new secret takes on the next reconcile. */
-   *
-   *  The edit path is taken only when the user actually exists. A 422 from the create is also what
-   *  a plain validation failure returns, and reading it as "already there" made the follow-up edit
-   *  404 — burying the create's own message, which is the one that says what is actually wrong. */
   async ensureUser(username: string, password: string, email: string): Promise<void> {
     const res = await this.request("/admin/users", {
       method: "POST",
@@ -515,19 +378,14 @@ export class GiteaAdmin {
     });
     if (res.status === 201) return;
     if (res.status === 422 || res.status === 409) {
-      const seen = await this.request(`/users/${encodeURIComponent(username)}`);
-      if (seen.status === 200) {
       const patch = await this.request(`/admin/users/${encodeURIComponent(username)}`, {
         method: "PATCH",
         // login_name is required by the admin edit endpoint; for a local user it is the username.
-          // active and prohibit_login: a deactivated or login-prohibited user is refused like a wrong
+        body: JSON.stringify({ login_name: username, password, must_change_password: false }),
-          // password, so the provisioner's check reports it lost; applying again must undo both.
-          body: JSON.stringify({ login_name: username, password, must_change_password: false, active: true, prohibit_login: false }),
       });
       if (patch.status === 200) return;
       GiteaAdmin.fail(`/admin/users/${username}`, patch);
     }
-    }
     GiteaAdmin.fail("/admin/users", res);
   }
 
@@ -541,29 +399,6 @@ export class GiteaAdmin {
     GiteaAdmin.fail(`/teams/${teamId}/members/${username}`, res);
   }
 
-  /**
-   * Whether a consumer's user logs in with exactly this password and is still a member of the
-   * package team. Read-only: the password is checked as the consumer presents it, basic auth on the
-   * API, and membership through the admin API. `false` for a refused login or a missing member; any
-   * other answer rejects (novox/hq issue 120).
-   */
-  async holdsTeamMember(org: string, team: string, username: string, password: string): Promise<boolean> {
-    const me = await fetch(`${this.baseUrl}/api/v1/user`, {
-      headers: { Authorization: "Basic " + Buffer.from(`${username}:${password}`).toString("base64") },
-    });
-    if (me.status === 401 || me.status === 403) return false;
-    if (me.status !== 200) throw new Error(`Gitea GET /user as ${username}: ${me.status}`);
-    const teams = await this.request(`/orgs/${encodeURIComponent(org)}/teams?limit=50`);
-    if (teams.status === 404) return false;
-    if (teams.status !== 200) GiteaAdmin.fail(`/orgs/${org}/teams`, teams);
-    const found = (teams.body as { id: number; name: string }[]).find((t) => t.name === team);
-    if (!found) return false;
-    const member = await this.request(`/teams/${found.id}/members/${encodeURIComponent(username)}`);
-    if (member.status === 200 || member.status === 204) return true;
-    if (member.status === 404) return false;
-    GiteaAdmin.fail(`/teams/${found.id}/members/${username}`, member);
-  }
-
   /** Delete a user, purging what they own. A 404 means the mesh already withdrew them — success, not
    *  an error, so a re-run of remove is safe. */
   async deleteUser(username: string): Promise<void> {

modules/gitea/index.ts

@@ -16,9 +16,7 @@
 import { emit } from "@novox/mesh-sdk/events";
 import { GiteaClient } from "./client.js";
 
-// Without a way to a token — configured, or mintable with the admin account (token.ts) — there is
+// Without a token there is nothing to watch; log and stay quiet rather than crash the runtime.
-// nothing to watch; log and stay quiet rather than crash the runtime. With one, the first poll mints
-// or reuses the token, so the runtime's start also shows what it did about it.
 let gitea: GiteaClient | null = null;
 try {
   gitea = GiteaClient.fromEnv();
@@ -31,11 +29,11 @@ try {
 const seen = new Set<string>();
 let primed = false;
 async function pollRepos(client: GiteaClient): Promise<void> {
-  const repos = await client.listAllRepos();
+  const repos = await client.listRepos(1, 50);
   for (const repo of repos) {
     if (!seen.has(repo.full_name)) {
       if (primed) {
-        await emit("repo.created", {
+        await emit("module.gitea.repo.created", {
           full_name: repo.full_name,
           owner: repo.owner,
           name: repo.name,
@@ -49,104 +47,13 @@ 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
-  // yet, the admin account refused on a restored forge) is one fact, and a recovery is worth a line.
-  let failing: string | null = null;
   const tick = (fn: () => Promise<void>, everyMs: number): void => {
-    const run = (): void =>
+    const run = (): void => void fn().catch((err) => console.error(`[gitea] ${err}`));
-      void fn()
-        .then(() => {
-          if (failing !== null) console.log("[gitea] watching again");
-          failing = null;
-        })
-        .catch((err) => {
-          const why = err instanceof Error ? err.message : String(err);
-          if (why !== failing) console.error(`[gitea] not watching until this clears — ${why}`);
-          failing = why;
-        });
     setInterval(run, everyMs);
     run();
   };
   tick(() => pollRepos(client), 60_000);
-  tick(() => pollMerged(client), 30_000);
+  console.log("[gitea] watching for new repositories");
-  console.log("[gitea] watching for new repositories and merged pull requests");
 }

modules/gitea/module.json

@@ -11,117 +11,89 @@
       "name": "gitea"
     },
     "route": {
-      "web": {
       "label": "git",
-        "endpoint": "web"
+      "port": 3000
-      },
-      "internal-api-refused": {
-        "label": "git",
-        "path": "/api/internal",
-        "deny": true,
-        "priority": 100000
-      }
     }
   },
   "binds": {
-    "postgres-database": "${dir:state}/database.json",
+    "postgres-database": "/var/lib/gitea/database.json",
-    "route": "${dir:state}/route.json"
+    "route": "/var/lib/gitea/route.json"
   },
   "secrets": {
-    "postgres-database": "${dir:state}/database.secret",
+    "postgres-database": "/var/lib/gitea/database.secret",
     "secret": {
-      "internal-token": "${dir:state}/internal-token.secret",
+      "internal-token": "/var/lib/gitea/internal-token.secret",
-      "admin": "${dir:state}/admin.secret"
+      "admin": "/var/lib/gitea/admin.secret"
     }
   },
   "capabilities": [
     "container-runtime"
   ],
   "emits": [
-    "repo.created",
+    "module.gitea.repo.created",
-    "issue.opened",
+    "module.gitea.issue.opened",
-    "pull.merged"
+    "module.gitea.pull.merged"
   ],
   "listens": [
     {
-      "name": "web",
       "port": 3000,
       "protocol": "tcp",
       "from": "mesh",
       "why": "the forge, over http"
     },
     {
-      "name": "ssh",
+      "port": 2222,
-      "port": 22,
       "protocol": "tcp",
       "from": "mesh",
-      "why": "git over ssh, gitea's own unmodified sshd. Published on the machine's own side at 222, the mesh's fixed public convention \u2014 not 22, which the machine's own daemon holds and a module does not take"
+      "why": "git over ssh. Not 22: the machine's own daemon holds that, and a module does not take it"
     }
   ],
   "serves": {
-    "npm-package-registry": {
+    "package-registry": {
       "scheme": "http",
       "port": 3000,
       "npm-path": "/api/packages/novox/npm/"
-    },
-    "git": {
-      "scheme": "http",
-      "port": 3000
     }
   },
   "receives": {
-    "npm-package-registry": "${dir:grants}/npm.json"
+    "package-registry": "/var/lib/gitea/grants/mesh.json"
   },
   "grants": {
-    "npm-package-registry": "${dir:grants}"
+    "package-registry": "/var/lib/gitea/grants"
   },
-  "claims": [
-    {
-      "name": "npm-package-registry",
-      "scope": "mesh"
-    },
-    {
-      "name": "git",
-      "scope": "mesh"
-    }
-  ],
   "own-secrets": {
-    "broker": "${dir:mesh-state}/broker"
+    "broker": "/var/lib/mesh/gitea/broker"
   },
   "resources": [
     {
       "id": "mesh-state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/mesh/gitea",
-      "place": "mesh"
-    },
-    {
-      "id": "runtime-state",
-      "type": "directory",
-      "path": "${dir:mesh-state}/state",
       "mode": "0700"
     },
     {
       "id": "state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/gitea",
-      "place": "."
+      "mode": "0700"
     },
     {
       "id": "grants",
       "type": "directory",
+      "path": "/var/lib/gitea/grants",
       "mode": "0700"
     },
     {
       "id": "server-env",
       "type": "file",
-      "path": "${dir:state}/server.env",
+      "path": "/var/lib/gitea/server.env",
       "mode": "0600",
       "content": "GITEA__security__INTERNAL_TOKEN=${secret:internal-token}\nGITEA__database__DB_TYPE=postgres\nGITEA__database__HOST=${bound:postgres-database:at}:${bound:postgres-database:port}\nGITEA__database__NAME=${bound:postgres-database:as}\nGITEA__database__USER=${bound:postgres-database:as}\nGITEA__database__PASSWD=${secret:postgres-database}\n"
     },
     {
       "id": "data",
       "type": "directory",
+      "path": "/services/gitea/gitea",
       "mode": "0700",
       "owner": "1000:1000"
     },
@@ -136,14 +108,14 @@
         "USER_GID": "1000"
       },
       "env-file": [
-        "${dir:state}/server.env"
+        "/var/lib/gitea/server.env"
       ],
       "ports": [
         "3000",
-        "222:22"
+        "2222:22"
       ],
       "volumes": [
-        "${dir:data}:/data"
+        "/services/gitea/gitea:/data"
       ],
       "secrets-in-environment": "gitea honours GITEA__database__PASSWD__FILE and GITEA__security__INTERNAL_TOKEN__FILE; convertible, awaiting a bed that proves it"
     },
@@ -159,11 +131,11 @@
         "MESH_GITEA_ADMIN_USER": "mesh-admin"
       },
       "env-file": [
-        "${dir:state}/server.env"
+        "/var/lib/gitea/server.env"
       ],
       "volumes": [
-        "${dir:data}:/data",
+        "/services/gitea/gitea:/data",
-        "${dir:state}/admin.secret:/run/secrets/admin:ro"
+        "/var/lib/gitea/admin.secret:/run/secrets/admin:ro"
       ],
       "args": [
         "/bin/sh",
@@ -175,7 +147,7 @@
     {
       "id": "runtime-config",
       "type": "file",
-      "path": "${dir:mesh-state}/config.json",
+      "path": "/var/lib/mesh/gitea/config.json",
       "mode": "0600",
       "content": "{}\n",
       "merge": "json"
@@ -186,11 +158,10 @@
       "name": "mesh-gitea",
       "network": "host",
       "volumes": [
-        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "/var/lib/mesh/gitea/broker:/run/secrets/broker:ro",
-        "${dir:mesh-state}/config.json:/run/config/config.json:ro",
+        "/var/lib/mesh/gitea/config.json:/run/config/config.json:ro",
-        "${dir:grants}:${dir:grants}:ro",
+        "/var/lib/gitea/grants:/var/lib/gitea/grants:ro",
-        "${dir:state}/admin.secret:/run/secrets/admin:ro",
+        "/var/lib/gitea/admin.secret:/run/secrets/admin:ro"
-        "${dir:runtime-state}:/run/state"
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",
@@ -198,8 +169,7 @@
         "MESH_GITEA_CONFIG_FILE": "/run/config/config.json",
         "MESH_GITEA_ADMIN_USER": "mesh-admin",
         "MESH_GITEA_ADMIN_PASSWORD_FILE": "/run/secrets/admin",
-        "MESH_GITEA_STATE_DIR": "/run/state",
+        "MESH_RECEIVES": "/var/lib/gitea/grants/mesh.json"
-        "MESH_RECEIVES": "${dir:grants}/npm.json"
       },
       "artifact": "runtime",
       "restart-on": [
@@ -209,11 +179,7 @@
   ],
   "provides": [
     {
-      "name": "npm-package-registry",
+      "name": "package-registry",
-      "scope": "mesh"
-    },
-    {
-      "name": "git",
       "scope": "mesh"
     }
   ],

modules/gitea/package.json

@@ -4,12 +4,8 @@
   "description": "gitea — git hosting. Its API client, tools and events live here (novox/hq ADR 0039).",
   "type": "module",
   "private": true,
-  "scripts": {
-    "build": "tsc client.ts token.ts index.ts provisioner/index.ts tools/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist",
-    "test": "npm run build && node --test --experimental-strip-types 'test/*.test.ts'"
-  },
   "dependencies": {
-    "@novox/mesh-sdk": "^0.1.1"
+    "@novox/mesh-sdk": "^0.1.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

modules/gitea/provisioner/index.ts

@@ -1,15 +1,9 @@
-// gitea's provisioner — the adapter that makes gitea a provider of the mesh
+// gitea's provisioner — the adapter that makes gitea a provider of the mesh `package-registry`
-// `npm-package-registry` interface. The reconcile loop, the contributions file, and reading the
+// interface. The reconcile loop, the contributions file, and reading the mesh's minted password are
-// mesh's minted password are the sdk harness's; this writes only the per-service half: how gitea
+// the sdk harness's; this writes only the per-service half: how gitea creates and removes a
-// creates and removes a consumer's npm credential (novox/hq ADR 0048/0076).
+// consumer's npm credential (novox/hq ADR 0048/0076).
 //
-// **A package registry seat is one per ecosystem (novox/hq ADR 0109).** gitea holds the npm seat
+// The `package-registry` interface: a consumer authenticates to the npm registry at
-// (ADR 0110). Adding cargo or PyPI is adding a provision — another `provides` entry, another
-// `receives` path and another registration below — not widening this one. `git`, which gitea also
-// provides, mints nothing and so registers nothing here: the mesh's own repositories are public,
-// and a clone credential is not yet decided (ADR 0111).
-//
-// The `npm-package-registry` interface: a consumer authenticates to the npm registry at
 // `/api/packages/novox/npm/` with basic auth, as `as` with the password the mesh minted, and can
 // read and write packages under the `@novox` scope. The registry's npm owner is the gitea org
 // `novox`; a consumer is a gitea *user* placed on that org's package team.
@@ -32,11 +26,7 @@ const PACKAGE_TEAM = "packages";
 
 const gitea = GiteaAdmin.fromEnv();
 
-// Where this registration's contributions land comes from $MESH_RECEIVES, never a path written
+runProvisioner("package-registry", {
-// here: the mesh writes the file where the manifest's `receives` says, and a second copy of that
-// path in code would drift from it. One variable carries one path, so a second registration in this
-// module needs the mesh to say where each provision's file is — not yet possible, and not faked.
-runProvisioner("npm-package-registry", {
   async create(p: Provision): Promise<void> {
     // The org and its package team are the same for every consumer; ensuring them per-create is
     // idempotent and needs no separate bootstrap step.
@@ -44,21 +34,11 @@ runProvisioner("npm-package-registry", {
     const teamId = await gitea.ensureTeam(ORG, PACKAGE_TEAM, true);
     // The user carries the consumer's login and the mesh's minted password, set every run so a
     // rotation takes. Membership of the package team is what grants read+write on packages.
-    //
+    await gitea.ensureUser(p.as, p.password, `${p.as}@localhost`);
-    // The address is gitea's own convention for one that is not real: its email validation
-    // requires a dotted domain, so `@localhost` was refused at create — the fault that had this
-    // grant retrying for a day — while `@noreply.localhost` is the shape gitea itself gives
-    // hidden addresses.
-    await gitea.ensureUser(p.as, p.password, `${p.as}@noreply.localhost`);
     await gitea.addUserToTeam(teamId, p.as);
   },
 
   async remove(p: { as: string }): Promise<void> {
     await gitea.deleteUser(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 gitea.holdsTeamMember(ORG, PACKAGE_TEAM, p.as, p.password);
-  },
 });

modules/gitea/test/token.test.ts

@@ -1,451 +0,0 @@
-// What holds the module to its own token (token.ts; hq issue 100, the forge's tools): minted with
-// the delivered admin account on the first call and kept at 0600, reused on the next start, minted
-// afresh when the forge rejects it or the kept file is gone, and a refused admin account reported in
-// plain words rather than crash-looped. A configured token still wins. And the tools register once
-// there is a way to a token at all — before one exists.
-//
-// The forge is a fake: the four routes the module touches, with the same status codes gitea gives.
-// Run against the compiled module (npm test builds first), the way the runtime loads it.
-
-import { test, after } from "node:test";
-import assert from "node:assert/strict";
-import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
-import { mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import { collectTools } from "@novox/mesh-sdk/tools";
-import { AdminRefused, MintedToken, TOKEN_SCOPES } from "../dist/token.js";
-import { GiteaClient } from "../dist/client.js";
-import "../dist/tools/index.js";
-
-const ADMIN = "mesh-admin";
-const PASSWORD = "the-vault-minted-this";
-
-// ---- A fake forge: what the module sends, and what gitea would answer. ----
-
-interface Forge {
-  url: string;
-  mints: number;
-  lastScopes: string[] | null;
-  tokens: Map<string, string>;
-  scopesOf: Map<string, string[]>;
-  admins: Map<string, string>;
-  pullState: string;
-  pullTitle: string;
-  branchDeleted: boolean;
-  close(): Promise<void>;
-}
-
-function fakeForge(): Promise<Forge> {
-  const forge = {
-    mints: 0,
-    lastScopes: null as string[] | null,
-    tokens: new Map<string, string>(), // name -> value
-    scopesOf: new Map<string, string[]>(), // value -> scopes, so a route can enforce them like gitea does
-    admins: new Map([[ADMIN, PASSWORD]]),
-    pullState: "open",
-    pullTitle: "The console shipped",
-    branchDeleted: false,
-  };
-  // write:X implies read:X — gitea's own rule (models/auth/access_token_scope.go).
-  const covers = (scopes: string[], required: string): boolean =>
-    scopes.includes(required) || scopes.includes(`write:${required.split(":")[1]}`);
-  const json = (res: ServerResponse, status: number, body: unknown): void => {
-    res.writeHead(status, { "Content-Type": "application/json" });
-    res.end(body === null ? "" : JSON.stringify(body));
-  };
-  const body = (req: IncomingMessage): Promise<any> =>
-    new Promise((resolve) => {
-      let text = "";
-      req.on("data", (c) => (text += c));
-      req.on("end", () => resolve(text ? JSON.parse(text) : null));
-    });
-  const basic = (req: IncomingMessage): string | null => {
-    const h = req.headers.authorization ?? "";
-    if (!h.startsWith("Basic ")) return null;
-    const [user, pass] = Buffer.from(h.slice(6), "base64").toString().split(":");
-    return forge.admins.get(user) === pass ? user : null;
-  };
-
-  const server = createServer(async (req, res) => {
-    const url = new URL(req.url ?? "/", "http://fake");
-    const tokens = url.pathname.match(/^\/api\/v1\/users\/([^/]+)\/tokens(?:\/([^/]+))?$/);
-    if (tokens) {
-      const user = basic(req);
-      if (user === null || user !== decodeURIComponent(tokens[1])) return json(res, 401, { message: "auth required" });
-      if (req.method === "POST") {
-        const { name, scopes } = await body(req);
-        if (forge.tokens.has(name)) return json(res, 400, { message: "token name has already been used" });
-        forge.mints++;
-        forge.lastScopes = scopes;
-        const sha1 = `minted-${forge.mints}-${Math.random().toString(36).slice(2)}`;
-        forge.tokens.set(name, sha1);
-        forge.scopesOf.set(sha1, scopes);
-        return json(res, 201, { id: forge.mints, name, sha1, scopes, token_last_eight: sha1.slice(-8) });
-      }
-      if (req.method === "DELETE" && tokens[2]) {
-        const name = decodeURIComponent(tokens[2]);
-        if (!forge.tokens.has(name)) return json(res, 404, { message: "token not found" });
-        forge.tokens.delete(name);
-        return json(res, 204, null);
-      }
-      return json(res, 405, { message: "method not allowed" });
-    }
-    const tokenOf = (): string => {
-      const h = req.headers.authorization ?? "";
-      return h.startsWith("token ") ? h.slice(6) : "";
-    };
-    const pull = url.pathname.match(/^\/api\/v1\/repos\/novox\/hq\/pulls\/(\d+)(\.diff)?$/);
-    if (pull) {
-      if (![...forge.tokens.values()].includes(tokenOf())) return json(res, 401, { message: "token is required" });
-      if (pull[2]) {
-        res.writeHead(200, { "Content-Type": "text/plain" });
-        return res.end("diff --git a/x b/x\n--- a/x\n+++ b/x\n@@ -1 +1 @@\n-old\n+new\n");
-      }
-      if (req.method === "PATCH") {
-        const patch = await body(req);
-        forge.pullState = patch?.state ?? forge.pullState;
-        forge.pullTitle = patch?.title ?? forge.pullTitle;
-      }
-      return json(res, 200, { number: Number(pull[1]), title: forge.pullTitle, state: forge.pullState, merged: false,
-        user: { login: "mesh-admin" }, head: { ref: "feat/x" }, base: { ref: "main" }, html_url: "http://fake/novox/hq/pulls/" + pull[1] });
-    }
-    if (url.pathname === "/api/v1/repos/novox/hq/issues/223/comments") {
-      return json(res, 200, [{ id: 1, user: { login: "jochen" }, body: "landed elsewhere", created_at: "2026-10-01T00:00:00Z", html_url: "http://fake/c/1" }]);
-    }
-    if (url.pathname === "/api/v1/repos/novox/hq/contents/README.md") {
-      return json(res, 200, { type: "file", encoding: "base64", sha: "abc", size: 5, content: Buffer.from("hello").toString("base64") });
-    }
-    if (url.pathname === "/api/v1/repos/novox/hq/branches") {
-      return json(res, 200, [{ name: "main", protected: true, commit: { id: "aaaa" } }, { name: "feat/x", protected: false, commit: { id: "bbbb" } }]);
-    }
-    if (url.pathname === "/api/v1/repos/novox/hq/branches/feat%2Fx" || url.pathname === "/api/v1/repos/novox/hq/branches/feat/x") {
-      if (req.method === "DELETE") { forge.branchDeleted = true; return json(res, 204, null); }
-    }
-    if (url.pathname === "/api/v1/repos/search") {
-      // The client lists through the search endpoint since 2026-09-28 (the forge's whole view);
-      // it sits under `repository`, which write:repository covers.
-      const h = req.headers.authorization ?? "";
-      const value = h.startsWith("token ") ? h.slice(6) : "";
-      if (![...forge.tokens.values()].includes(value)) return json(res, 401, { message: "token is required" });
-      if (!covers(forge.scopesOf.get(value) ?? [], "read:repository")) {
-        return json(res, 403, { message: `token does not have at least one of required scope(s), required=[read:repository]` });
-      }
-      return json(res, 200, {
-        ok: true,
-        data: [{ full_name: "novox/hq", name: "hq", owner: { login: "novox" }, private: true, html_url: "http://fake/novox/hq" }],
-      });
-    }
-    if (url.pathname === "/api/v1/user/repos") {
-      const h = req.headers.authorization ?? "";
-      const value = h.startsWith("token ") ? h.slice(6) : "";
-      if (![...forge.tokens.values()].includes(value)) return json(res, 401, { message: "token is required" });
-      // gitea 1.27.3: GET /user/repos sits under the `user` scope category, not `repository` —
-      // confirmed against the live forge. A token without read:user (or write:user) is refused here.
-      const scopes = forge.scopesOf.get(value) ?? [];
-      if (!covers(scopes, "read:user")) {
-        return json(res, 403, {
-          message: `token does not have at least one of required scope(s), required=[read:user]`,
-        });
-      }
-      return json(res, 200, [
-        { full_name: "novox/hq", name: "hq", owner: { login: "novox" }, private: true, html_url: "http://fake/novox/hq" },
-      ]);
-    }
-    const adminUser = url.pathname.match(/^\/api\/v1\/admin\/users\/([^/]+)$/);
-    if (adminUser && req.method === "PATCH") {
-      const h = req.headers.authorization ?? "";
-      const value = h.startsWith("token ") ? h.slice(6) : "";
-      if (![...forge.tokens.values()].includes(value)) return json(res, 401, { message: "token is required" });
-      if (!covers(forge.scopesOf.get(value) ?? [], "write:admin")) {
-        return json(res, 403, {
-          message: `token does not have at least one of required scope(s), required=[write:admin]`,
-        });
-      }
-      const login = decodeURIComponent(adminUser[1]);
-      if (login === "untouchable") return json(res, 403, { message: "user untouchable may not be edited" });
-      const patch = await body(req);
-      return json(res, 200, { login, is_admin: patch?.admin === true });
-    }
-    return json(res, 404, { message: "no such route in the fake" });
-  });
-  return new Promise((resolve) => {
-    server.listen(0, "127.0.0.1", () => {
-      const { port } = server.address() as { port: number };
-      resolve({
-        url: `http://127.0.0.1:${port}`,
-        get mints() { return forge.mints; },
-        get lastScopes() { return forge.lastScopes; },
-        get pullState() { return forge.pullState; },
-        get pullTitle() { return forge.pullTitle; },
-        get branchDeleted() { return forge.branchDeleted; },
-        tokens: forge.tokens,
-        scopesOf: forge.scopesOf,
-        admins: forge.admins,
-        close: () => new Promise((r) => server.close(() => r())),
-      });
-    });
-  });
-}
-
-// ---- What the runtime's environment gives the module. ----
-
-async function delivered(forge: Forge): Promise<{ env: NodeJS.ProcessEnv; file: string; logs: string[] }> {
-  const dir = await mkdtemp(join(tmpdir(), "gitea-"));
-  const passwordFile = join(dir, "admin.secret");
-  await writeFile(passwordFile, PASSWORD + "\n", { mode: 0o600 });
-  const state = join(dir, "state");
-  return {
-    env: {
-      MESH_GITEA_URL: forge.url,
-      MESH_GITEA_ADMIN_USER: ADMIN,
-      MESH_GITEA_ADMIN_PASSWORD_FILE: passwordFile,
-      MESH_GITEA_STATE_DIR: state,
-    },
-    file: join(state, "token"),
-    logs: [],
-  };
-}
-
-/** A client as a fresh process would build it: a new source over the kept file, its log captured. */
-function minted(env: NodeJS.ProcessEnv, logs: string[]): GiteaClient {
-  const source = new MintedToken({
-    url: env.MESH_GITEA_URL!,
-    admin: env.MESH_GITEA_ADMIN_USER!,
-    passwordFile: env.MESH_GITEA_ADMIN_PASSWORD_FILE!,
-    file: join(env.MESH_GITEA_STATE_DIR!, "token"),
-    log: (l) => logs.push(l),
-  });
-  return new GiteaClient(env.MESH_GITEA_URL!, source);
-}
-
-const forge = await fakeForge();
-after(() => forge.close());
-
-test("first start: mints with the admin account, keeps the token at 0600, asks for the tools' scopes only", async () => {
-  const { env, file, logs } = await delivered(forge);
-
-  const repos = await minted(env, logs).listRepos();
-
-  assert.equal(repos[0]?.full_name, "novox/hq");
-  assert.equal(forge.mints, 1);
-  assert.deepEqual(forge.lastScopes, ["write:repository", "write:issue", "read:user", "write:admin"]);
-  assert.deepEqual(forge.lastScopes, [...TOKEN_SCOPES]);
-  const token = forge.tokens.get("mesh-tools")!;
-  assert.equal(await readFile(file, "utf8"), token + "\n");
-  assert.equal((await stat(file)).mode & 0o777, 0o600);
-  // Said that it minted, and where it keeps it — never what it is.
-  assert.ok(logs.some((l) => l.startsWith("minted a token")), logs.join("\n"));
-  assert.ok(logs.every((l) => !l.includes(token) && !l.includes(PASSWORD)), logs.join("\n"));
-});
-
-test("second start: reuses the kept token, mints nothing", async () => {
-  const { env, logs } = await delivered(forge);
-  await minted(env, logs).listRepos();
-  const before = forge.mints;
-
-  const again: string[] = [];
-  await minted(env, again).listRepos();
-
-  assert.equal(forge.mints, before);
-  assert.ok(again.some((l) => l.startsWith("reusing the token kept at")), again.join("\n"));
-  assert.ok(again.every((l) => !l.includes(forge.tokens.get("mesh-tools")!)), again.join("\n"));
-});
-
-test("the forge rejects the kept token (its data was restored): minted afresh, once, and the call goes through", async () => {
-  const { env, file, logs } = await delivered(forge);
-  const client = minted(env, logs);
-  await client.listRepos();
-  const before = forge.mints;
-
-  forge.tokens.clear(); // the forge no longer knows any token — a restore from the predecessor
-  const repos = await client.listRepos();
-
-  assert.equal(repos.length, 1);
-  assert.equal(forge.mints, before + 1);
-  assert.equal(await readFile(file, "utf8"), forge.tokens.get("mesh-tools") + "\n");
-  assert.ok(logs.some((l) => l.startsWith("the forge rejected the kept token")), logs.join("\n"));
-});
-
-test("a kept token from before write:admin: the forge refuses the admin route for the scope, the token is re-minted with the whole list, and the call goes through", async () => {
-  const { env, file, logs } = await delivered(forge);
-  const client = minted(env, logs);
-  await client.listRepos();
-  const before = forge.mints;
-  const old = forge.tokens.get("mesh-tools")!;
-  forge.scopesOf.set(old, ["write:repository", "write:issue", "read:user"]); // minted by the previous build
-
-  const user = await client.api<{ login: string; is_admin: boolean }>("/admin/users/mesh_novox_builder", {
-    method: "PATCH",
-    body: JSON.stringify({ admin: true }),
-  });
-
-  assert.equal(user.is_admin, true);
-  assert.equal(forge.mints, before + 1);
-  assert.deepEqual(forge.lastScopes, [...TOKEN_SCOPES]);
-  assert.notEqual(forge.tokens.get("mesh-tools"), old);
-  assert.equal(await readFile(file, "utf8"), forge.tokens.get("mesh-tools") + "\n");
-  assert.ok(logs.some((l) => l.startsWith("the forge rejected the kept token")), logs.join("\n"));
-  // A 403 that is not about scopes is the forge's answer, not a reason to mint.
-  const again = forge.mints;
-  await assert.rejects(
-    client.api("/admin/users/untouchable", { method: "PATCH", body: JSON.stringify({ admin: true }) }),
-    /403 .*untouchable/,
-  );
-  assert.equal(forge.mints, again);
-});
-
-test("the kept file is gone but the forge still holds a token by that name: replaced, not refused", async () => {
-  const { env, file, logs } = await delivered(forge);
-  await minted(env, logs).listRepos();
-  const before = forge.mints;
-  await rm(file);
-
-  const repos = await minted(env, logs).listRepos();
-
-  assert.equal(repos.length, 1);
-  assert.equal(forge.mints, before + 1);
-  assert.equal([...forge.tokens.keys()].filter((n) => n === "mesh-tools").length, 1);
-  assert.ok(logs.some((l) => l.includes('already holds a token named "mesh-tools"')), logs.join("\n"));
-});
-
-test("concurrent first calls share one mint", async () => {
-  const { env, logs } = await delivered(forge);
-  const client = minted(env, logs);
-  const before = forge.mints;
-
-  await Promise.all([client.listRepos(), client.listRepos(), client.listRepos()]);
-
-  assert.equal(forge.mints, before + 1);
-});
-
-test("the admin account is refused: said plainly, nothing kept, and the next call fails the same way rather than crashing", async () => {
-  const { env, file, logs } = await delivered(forge);
-  forge.admins.delete(ADMIN); // the forge's data came from a predecessor; mesh-admin was never created there
-  try {
-    const client = minted(env, logs);
-    const before = forge.mints;
-
-    await assert.rejects(client.listRepos(), (err: unknown) => {
-      assert.ok(err instanceof AdminRefused, String(err));
-      assert.match(err.message, /refused the admin account "mesh-admin" \(401\)/);
-      assert.match(err.message, /admin-bootstrap step creates it/);
-      assert.match(err.message, /came from a predecessor/);
-      assert.ok(!err.message.includes(PASSWORD));
-      return true;
-    });
-    await assert.rejects(client.listRepos(), AdminRefused);
-    assert.equal(forge.mints, before);
-    await assert.rejects(stat(file), /ENOENT/);
-
-    // The account appears (the operator created it): the very next call mints and works.
-    forge.admins.set(ADMIN, PASSWORD);
-    assert.equal((await client.listRepos()).length, 1);
-    assert.equal(forge.mints, before + 1);
-  } finally {
-    forge.admins.set(ADMIN, PASSWORD);
-  }
-});
-
-test("one process shares one source per kept file — the watcher and the tools never renew against each other", async () => {
-  const { env } = await delivered(forge);
-  assert.equal(MintedToken.fromEnv(env.MESH_GITEA_URL!, env), MintedToken.fromEnv(env.MESH_GITEA_URL!, env));
-});
-
-test("a second process finds the token the first renewed, and reuses it instead of minting over it", async () => {
-  const { env, logs } = await delivered(forge);
-  const first = minted(env, logs);
-  const second = minted(env, logs);
-  await first.listRepos();
-  await second.listRepos(); // both hold the same kept token
-  const before = forge.mints;
-
-  forge.tokens.clear();
-  await first.listRepos(); // renews: one mint
-  await second.listRepos(); // rejected too — but the kept file already carries the renewed one
-
-  assert.equal(forge.mints, before + 1);
-  assert.ok(logs.some((l) => l.includes("is newer — reusing it")), logs.join("\n"));
-});
-
-test("a configured token wins, and is reported rather than minted over when the forge rejects it", async () => {
-  const { env } = await delivered(forge);
-  const before = forge.mints;
-
-  const client = GiteaClient.fromEnv({ ...env, MESH_GITEA_TOKEN: "one-somebody-pasted-in" });
-
-  await assert.rejects(client.listRepos(), /rejected the configured Gitea token \(401\)/);
-  assert.equal(forge.mints, before);
-});
-
-test("nothing to mint with and no token: the client says what is missing", async () => {
-  assert.throws(
-    () => GiteaClient.fromEnv({ MESH_GITEA_URL: forge.url, MESH_GITEA_ADMIN_USER: ADMIN }),
-    /set MESH_GITEA_TOKEN, or MESH_GITEA_ADMIN_PASSWORD_FILE, MESH_GITEA_STATE_DIR/,
-  );
-});
-
-test("the tools register once there is a way to a token, and the first call mints it", async () => {
-  const { env } = await delivered(forge);
-  const before = forge.mints;
-
-  const withAdmin = collectTools(env).find((c) => c.module === "gitea")!;
-  const withNothing = collectTools({}).find((c) => c.module === "gitea")!;
-
-  assert.equal(withNothing.tools.length, 0);
-  assert.deepEqual(
-    withAdmin.tools.map((t) => t.name),
-    [
-      "gitea_list_repos", "gitea_create_repo", "gitea_delete_repo",
-      "gitea_list_issues", "gitea_get_issue", "gitea_create_issue", "gitea_close_issue", "gitea_add_comment",
-      "gitea_list_pull_requests", "gitea_get_pull_request", "gitea_create_pull_request", "gitea_merge_pull_request",
-      "gitea_close_pull_request",
-      "gitea_reopen_pull_request",
-      "gitea_update_pull_request",
-      "gitea_pull_request_files",
-      "gitea_pull_request_diff",
-      "gitea_list_comments",
-      "gitea_reopen_issue",
-      "gitea_get_file",
-      "gitea_list_branches",
-      "gitea_delete_branch",
-      "gitea_list_labels", "gitea_create_label",
-      "gitea_api",
-    ],
-  );
-  assert.equal(forge.mints, before, "registering must not mint — the forge may not be up yet");
-
-  const result = (await withAdmin.tools.find((t) => t.name === "gitea_list_repos")!.run({})) as { repos: unknown[] };
-  assert.equal(result.repos.length, 1);
-  assert.equal(forge.mints, before + 1);
-});
-
-// The forge's tools reach every action a review needs without a checkout and without the API
-// escape hatch: close a pull request whose work landed elsewhere, read its diff, its comments, a
-// file, the branches, and delete the branch left behind. Against the fake forge, through the
-// compiled tools, the way the console calls them.
-test("a pull request can be closed, read and cleaned up through the tools", async () => {
-  const { env } = await delivered(forge);
-  const tools = collectTools(env).find((c) => c.module === "gitea")!.tools;
-  const tool = (name: string) => tools.find((t) => t.name === name)!;
-  for (const name of ["gitea_close_pull_request", "gitea_reopen_pull_request", "gitea_update_pull_request", "gitea_pull_request_files",
-    "gitea_pull_request_diff", "gitea_list_comments", "gitea_reopen_issue", "gitea_get_file", "gitea_list_branches", "gitea_delete_branch"]) {
-    assert.ok(tool(name), `${name} is not a tool`);
-  }
-  const closed = (await tool("gitea_close_pull_request").run({ owner: "novox", repo: "hq", number: 223 })) as { pull: { state: string } };
-  assert.equal(closed.pull.state, "closed");
-  assert.equal(forge.pullState, "closed");
-  const renamed = (await tool("gitea_update_pull_request").run({ owner: "novox", repo: "hq", number: 223, title: "Superseded" })) as { pull: { title: string } };
-  assert.equal(renamed.pull.title, "Superseded");
-  const diff = (await tool("gitea_pull_request_diff").run({ owner: "novox", repo: "hq", number: 223 })) as { diff: string };
-  assert.match(diff.diff, /^diff --git/);
-  const comments = (await tool("gitea_list_comments").run({ owner: "novox", repo: "hq", number: 223 })) as { comments: { body: string }[] };
-  assert.equal(comments.comments[0].body, "landed elsewhere");
-  const file = (await tool("gitea_get_file").run({ owner: "novox", repo: "hq", path: "README.md" })) as { file: { content: string } };
-  assert.equal(file.file.content, "hello");
-  const branches = (await tool("gitea_list_branches").run({ owner: "novox", repo: "hq" })) as { branches: { name: string }[] };
-  assert.deepEqual(branches.branches.map((b) => b.name), ["main", "feat/x"]);
-  await tool("gitea_delete_branch").run({ owner: "novox", repo: "hq", branch: "feat/x" });
-  assert.equal(forge.branchDeleted, true);
-});

modules/gitea/token.ts

@@ -1,264 +0,0 @@
-// The token the forge's tools and watcher authenticate with — and where it comes from.
-//
-// Nobody configures it. The forge is raised by the mesh, so there is no operator holding a token to
-// paste in, and pasting one into settings would put a secret in the inventory in plaintext. What
-// the mesh does deliver is the admin account: a login the manifest names and a password the vault
-// minted and the host unsealed into a file (novox/hq ADR 0086). That account is enough to mint a
-// token, so the module mints its own (hq issue 100, the forge's tools):
-//
-//   - at first use, when none is kept: POST /users/{admin}/tokens over basic auth, with the two
-//     scopes the tools and the watcher need, and no more;
-//   - kept in the module's own state, a 0600 file, and read back on the next start — the forge
-//     hands a token's value out exactly once, so a token not kept is a token lost;
-//   - re-minted when the forge rejects it (401) or the kept file is gone. The one case that is not
-//     a fault: the forge's data was restored from a predecessor and the token the file names never
-//     existed there.
-//
-// An explicitly configured token still wins, and is never minted over: if it is rejected, that is
-// reported, not repaired — somebody chose it.
-//
-// The token is never logged. Lines say that one was minted, reused or renewed, and where it is
-// kept; never what it is.
-
-import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-
-/** The name the token carries in the forge's own list — one per mesh runtime, found by name. */
-export const TOKEN_NAME = "mesh-tools";
-
-/**
- * The least the fifteen tools and the watcher need (gitea's route groups, 1.20+ scoped tokens):
- *   write:repository — create/delete repositories, pull requests (list/get/open/merge);
- *   write:issue      — issues, comments, labels;
- *   read:user        — GET /user/repos, which the watcher's poll and gitea_list_repos both call.
- *                      It sits under the `user` category despite listing repositories, not `repository`
- *                      — confirmed against the running forge (1.27.3), which answered
- *                      `required=[read:user]` to a token carrying only the other two.
- *   write:admin      — /admin/users: the forge's own users are the mesh's to settle, such as making
- *                      the builder's login a site admin so every repository the mesh may build is
- *                      clonable (novox/hq 229). Nothing under /orgs or write:user.
- *
- * A token kept from before a scope was added lacks it: the forge answers such a call with
- * `403 token does not have at least one of required scope(s)`, and the client treats that like a
- * 401 — the source re-mints by name, with the whole list, and the call is retried once.
- */
-export const TOKEN_SCOPES: readonly string[] = ["write:repository", "write:issue", "read:user", "write:admin"];
-
-/** Where a client's token comes from, and what to do when the forge says it is wrong. */
-export interface TokenSource {
-  /** The token to authenticate with now; minted, read or configured. */
-  current(): Promise<string>;
-  /** The forge answered 401 to `rejected`, or 403 for a scope it lacks. A fresh token, or a plain error when there is nothing to renew with. */
-  renew(rejected: string): Promise<string>;
-}
-
-/** A token somebody set — in settings or the environment. Never minted over. */
-export class ConfiguredToken implements TokenSource {
-  constructor(private readonly token: string) {}
-
-  async current(): Promise<string> {
-    return this.token;
-  }
-
-  async renew(): Promise<string> {
-    throw new Error(
-      "the forge rejected the configured Gitea token (401). It was set explicitly (settings or MESH_GITEA_TOKEN), " +
-        "so the module does not mint over it — fix it, or unset it and the module mints its own",
-    );
-  }
-}
-
-/** The forge would not take the admin account: it is missing, or its password is not the one the mesh holds. */
-export class AdminRefused extends Error {
-  constructor(admin: string, status: number) {
-    super(
-      `the forge refused the admin account "${admin}" (${status}) — it does not exist there, or its password is not ` +
-        `the one the vault delivered. The admin-bootstrap step creates it on a forge the mesh raised; a forge whose data ` +
-        `came from a predecessor does not have it. Create "${admin}" on the forge with the delivered password and the ` +
-        `token is minted on the next call — the tools stay registered and the watcher keeps trying`,
-    );
-    this.name = "AdminRefused";
-  }
-}
-
-export interface MintedTokenOptions {
-  /** The forge, e.g. http://127.0.0.1:3000. */
-  readonly url: string;
-  /** The admin login the manifest names. */
-  readonly admin: string;
-  /** The file the host unsealed the admin password into (ADR 0086). Read at mint time, so a rotation takes. */
-  readonly passwordFile: string;
-  /** Where the token is kept: a 0600 file in the module's own state. */
-  readonly file: string;
-  readonly name?: string;
-  readonly scopes?: readonly string[];
-  readonly log?: (line: string) => void;
-  readonly fetch?: typeof fetch;
-}
-
-/** The token the module mints for itself, kept in its state and renewed when the forge rejects it. */
-export class MintedToken implements TokenSource {
-  private held: string | null = null;
-  private readFile = false;
-  private inflight: Promise<string> | null = null;
-  private readonly name: string;
-  private readonly scopes: readonly string[];
-  private readonly log: (line: string) => void;
-  private readonly fetchImpl: typeof fetch;
-
-  constructor(private readonly opts: MintedTokenOptions) {
-    this.name = opts.name ?? TOKEN_NAME;
-    this.scopes = opts.scopes ?? TOKEN_SCOPES;
-    this.log = opts.log ?? ((line) => console.log(`[gitea] ${line}`));
-    this.fetchImpl = opts.fetch ?? fetch;
-  }
-
-  /**
-   * Build from the runtime's environment: the forge's URL, the admin login and password file the
-   * manifest hands the runtime, and the module's state directory (MESH_GITEA_STATE_DIR, a directory
-   * the runtime mounts writable). Throws, naming what is missing, rather than hand back a source
-   * that cannot mint.
-   */
-  static fromEnv(url: string, env: NodeJS.ProcessEnv = process.env): MintedToken {
-    const opts = MintedToken.optionsFromEnv(url, env);
-    // One source per kept file in a process. The watcher and the tools entrypoint both build a
-    // client in the same runtime; two sources over one file would each renew on a 401 and drop the
-    // other's token by name, forever. Shared, a renewal is one renewal.
-    const shared = MintedToken.shared.get(opts.file);
-    if (shared) return shared;
-    const source = new MintedToken(opts);
-    MintedToken.shared.set(opts.file, source);
-    return source;
-  }
-
-  private static readonly shared = new Map<string, MintedToken>();
-
-  private static optionsFromEnv(url: string, env: NodeJS.ProcessEnv): MintedTokenOptions {
-    const admin = env.MESH_GITEA_ADMIN_USER;
-    const passwordFile = env.MESH_GITEA_ADMIN_PASSWORD_FILE;
-    const stateDir = env.MESH_GITEA_STATE_DIR;
-    const missing = [
-      admin ? null : "MESH_GITEA_ADMIN_USER",
-      passwordFile ? null : "MESH_GITEA_ADMIN_PASSWORD_FILE",
-      stateDir ? null : "MESH_GITEA_STATE_DIR",
-    ].filter((v): v is string => v !== null);
-    if (missing.length) {
-      throw new Error(`no Gitea token, and nothing to mint one with — set MESH_GITEA_TOKEN, or ${missing.join(", ")}`);
-    }
-    return { url, admin: admin!, passwordFile: passwordFile!, file: join(stateDir!, "token") };
-  }
-
-  async current(): Promise<string> {
-    if (this.held !== null) return this.held;
-    if (!this.readFile) {
-      this.readFile = true;
-      const kept = this.read();
-      if (kept !== null) {
-        this.held = kept;
-        this.log(`reusing the token kept at ${this.opts.file}`);
-        return kept;
-      }
-    }
-    return this.mint("no token kept — minting one");
-  }
-
-  async renew(rejected: string): Promise<string> {
-    // Another caller already renewed while this one was in flight with the old token.
-    if (this.held !== null && this.held !== rejected) return this.held;
-    // Or another process did, and kept it: use what is kept before minting over it.
-    const kept = this.read();
-    if (kept !== null && kept !== rejected) {
-      this.held = kept;
-      this.log(`the forge rejected the token held; the kept one at ${this.opts.file} is newer — reusing it`);
-      return kept;
-    }
-    this.held = null;
-    return this.mint("the forge rejected the kept token — minting a fresh one");
-  }
-
-  /** What the forge's scoped tokens say when a kept token predates a scope the tools now need. */
-  static lacksScope(status: number, body: string): boolean {
-    return status === 403 && /required scope/i.test(body);
-  }
-
-  /** One mint at a time: concurrent first calls share it, rather than each minting its own. */
-  private mint(why: string): Promise<string> {
-    if (this.inflight === null) {
-      this.log(why);
-      this.inflight = this.doMint().finally(() => {
-        this.inflight = null;
-      });
-    }
-    return this.inflight;
-  }
-
-  private read(): string | null {
-    try {
-      const token = readFileSync(this.opts.file, "utf8").replace(/\n$/, "");
-      return token.length ? token : null;
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
-      throw new Error(`cannot read the kept Gitea token at ${this.opts.file}: ${(err as Error).message}`);
-    }
-  }
-
-  /** Write the token at 0600, whole or not at all: a temp file beside it, then a rename. */
-  private keep(token: string): void {
-    mkdirSync(dirname(this.opts.file), { recursive: true, mode: 0o700 });
-    const tmp = `${this.opts.file}.tmp`;
-    writeFileSync(tmp, token + "\n", { mode: 0o600 });
-    chmodSync(tmp, 0o600);
-    renameSync(tmp, this.opts.file);
-  }
-
-  private async doMint(): Promise<string> {
-    let password: string;
-    try {
-      password = readFileSync(this.opts.passwordFile, "utf8").replace(/\n$/, "");
-    } catch (err) {
-      throw new Error(`cannot read the admin password at ${this.opts.passwordFile}: ${(err as Error).message}`);
-    }
-    const authorization = "Basic " + Buffer.from(`${this.opts.admin}:${password}`).toString("base64");
-    const tokens = `${this.opts.url.replace(/\/+$/, "")}/api/v1/users/${encodeURIComponent(this.opts.admin)}/tokens`;
-    const call = async (method: string, path = "", body?: unknown): Promise<{ status: number; body: any }> => {
-      const res = await this.fetchImpl(tokens + path, {
-        method,
-        headers: { "Content-Type": "application/json", Authorization: authorization },
-        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
-      });
-      const text = await res.text();
-      let parsed: any = null;
-      if (text) {
-        try { parsed = JSON.parse(text); } catch { parsed = text; }
-      }
-      return { status: res.status, body: parsed };
-    };
-
-    let res = await call("POST", "", { name: this.name, scopes: this.scopes });
-    if (res.status === 401 || res.status === 403) throw new AdminRefused(this.opts.admin, res.status);
-    if (res.status === 400 || res.status === 422) {
-      // The forge still holds a token by this name whose value we no longer have — the kept file
-      // went while the forge's data stayed. It is ours to replace: drop it by name and mint again.
-      this.log(`the forge already holds a token named "${this.name}" — replacing it`);
-      const dropped = await call("DELETE", `/${encodeURIComponent(this.name)}`);
-      if (dropped.status !== 204 && dropped.status !== 404) {
-        throw new Error(`Gitea DELETE /users/${this.opts.admin}/tokens/${this.name}: ${dropped.status} ${detail(dropped.body)}`);
-      }
-      res = await call("POST", "", { name: this.name, scopes: this.scopes });
-    }
-    if (res.status !== 201 && res.status !== 200) {
-      throw new Error(`Gitea POST /users/${this.opts.admin}/tokens: ${res.status} ${detail(res.body)}`);
-    }
-    const token = typeof res.body?.sha1 === "string" ? res.body.sha1 : null;
-    if (!token) throw new Error(`Gitea POST /users/${this.opts.admin}/tokens: ${res.status} but no token in the reply`);
-
-    this.keep(token);
-    this.held = token;
-    this.log(`minted a token for "${this.opts.admin}" (${this.scopes.join(", ")}), kept at ${this.opts.file}`);
-    return token;
-  }
-}
-
-function detail(body: unknown): string {
-  return typeof body === "string" ? body : JSON.stringify(body);
-}

modules/gitea/tools/index.ts

@@ -124,7 +124,7 @@ export function getGiteaTools(gitea: GiteaClient): ToolDefinition[] {
           labels: labelIds,
         });
         // The mesh just opened an issue — announce it the moment it exists.
-        await emit("issue.opened", {
+        await emit("module.gitea.issue.opened", {
           owner,
           repo,
           number: issue.number,
@@ -231,154 +231,20 @@ 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.
+        await emit("module.gitea.pull.merged", {
-        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,
           number,
           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 };
       },
     },
 
-    {
-      name: "gitea_close_pull_request",
-      description: "Close a pull request without merging it — one whose work landed elsewhere, or was abandoned.",
-      input: {
-        owner: { type: "string", description: "the repository owner" },
-        repo: { type: "string", description: "the repository name" },
-        number: { type: "number", description: "the PR number" },
-      },
-      run: async (args) => ({
-        pull: await gitea.setPullState(String(args.owner), String(args.repo), Number(args.number), "closed"),
-      }),
-    },
-    {
-      name: "gitea_reopen_pull_request",
-      description: "Reopen a closed, unmerged pull request.",
-      input: {
-        owner: { type: "string", description: "the repository owner" },
-        repo: { type: "string", description: "the repository name" },
-        number: { type: "number", description: "the PR number" },
-      },
-      run: async (args) => ({
-        pull: await gitea.setPullState(String(args.owner), String(args.repo), Number(args.number), "open"),
-      }),
-    },
-    {
-      name: "gitea_update_pull_request",
-      description: "Change a pull request's title or body; a field not given is left as it is.",
-      input: {
-        owner: { type: "string", description: "the repository owner" },
-        repo: { type: "string", description: "the repository name" },
-        number: { type: "number", description: "the PR number" },
-        title: { type: "string", description: "the new title (optional)" },
-        body: { type: "string", description: "the new body, markdown (optional)" },
-      },
-      run: async (args) => ({
-        pull: await gitea.updatePullRequest(String(args.owner), String(args.repo), Number(args.number), {
-          title: args.title === undefined ? undefined : String(args.title),
-          body: args.body === undefined ? undefined : String(args.body),
-        }),
-      }),
-    },
-    {
-      name: "gitea_pull_request_files",
-      description: "The files a pull request changes, as paths from the repository's root (up to 100; says when there are more).",
-      input: {
-        owner: { type: "string", description: "the repository owner" },
-        repo: { type: "string", description: "the repository name" },
-        number: { type: "number", description: "the PR number" },
-      },
-      run: async (args) => gitea.listPullFiles(String(args.owner), String(args.repo), Number(args.number)),
-    },
-    {
-      name: "gitea_pull_request_diff",
-      description: "A pull request's unified diff, as text — for reviewing it without a checkout.",
-      input: {
-        owner: { type: "string", description: "the repository owner" },
-        repo: { type: "string", description: "the repository name" },
-        number: { type: "number", description: "the PR number" },
-      },
-      run: async (args) => ({
-        diff: await gitea.pullDiff(String(args.owner), String(args.repo), Number(args.number)),
-      }),
-    },
-    {
-      name: "gitea_list_comments",
-      description: "Every comment on an issue or pull request, oldest first.",
-      input: {
-        owner: { type: "string", description: "the repository owner" },
-        repo: { type: "string", description: "the repository name" },
-        number: { type: "number", description: "the issue or PR number" },
-      },
-      run: async (args) => ({
-        comments: await gitea.listComments(String(args.owner), String(args.repo), Number(args.number)),
-      }),
-    },
-    {
-      name: "gitea_reopen_issue",
-      description: "Reopen a closed issue.",
-      input: {
-        owner: { type: "string", description: "the repository owner" },
-        repo: { type: "string", description: "the repository name" },
-        number: { type: "number", description: "the issue number" },
-      },
-      run: async (args) => ({
-        issue: await gitea.setIssueState(String(args.owner), String(args.repo), Number(args.number), "open"),
-      }),
-    },
-
-    // ---- Contents and branches ----
-    {
-      name: "gitea_get_file",
-      description: "One file's contents from a repository, decoded, at a branch, tag or commit (default the repository's default branch).",
-      input: {
-        owner: { type: "string", description: "the repository owner" },
-        repo: { type: "string", description: "the repository name" },
-        path: { type: "string", description: "the file's path from the repository's root" },
-        ref: { type: "string", description: "branch, tag or commit (optional)" },
-      },
-      run: async (args) => ({
-        file: await gitea.getFile(String(args.owner), String(args.repo), String(args.path), args.ref ? String(args.ref) : undefined),
-      }),
-    },
-    {
-      name: "gitea_list_branches",
-      description: "Every branch of a repository with the commit it points at.",
-      input: {
-        owner: { type: "string", description: "the repository owner" },
-        repo: { type: "string", description: "the repository name" },
-      },
-      run: async (args) => ({ branches: await gitea.listBranches(String(args.owner), String(args.repo)) }),
-    },
-    {
-      name: "gitea_delete_branch",
-      description: "Delete a branch — a feature branch whose pull request was closed rather than merged. Refused by the forge for a protected branch.",
-      input: {
-        owner: { type: "string", description: "the repository owner" },
-        repo: { type: "string", description: "the repository name" },
-        branch: { type: "string", description: "the branch name" },
-      },
-      run: async (args) => {
-        await gitea.deleteBranch(String(args.owner), String(args.repo), String(args.branch));
-        return { deleted: true, branch: String(args.branch) };
-      },
-    },
-
     // ---- Labels ----
     {
       name: "gitea_list_labels",
@@ -429,15 +295,12 @@ export function getGiteaTools(gitea: GiteaClient): ToolDefinition[] {
   ];
 }
 
-// The tools exist when the client has a way to a token: one configured, or the admin account to mint
+// The tools exist only when a token can be found; without one, gitea contributes none rather than
-// one with (token.ts). The mint itself happens on the first call, not here — a contributor is
+// failing the whole runtime.
-// synchronous, and a forge not yet answering must not keep the runtime from serving. Without either
-// way, gitea contributes none rather than failing the whole runtime, and says why.
 registerModuleTools("gitea", (env) => {
   try {
     return getGiteaTools(GiteaClient.fromEnv(env));
-  } catch (err) {
+  } catch {
-    console.log(`[gitea] no tools — ${err instanceof Error ? err.message : String(err)}`);
     return [];
   }
 });

modules/gitea/tsconfig.json

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

modules/gitlab/module.json

@@ -2,26 +2,26 @@
   "module": "gitlab",
   "version": "1",
   "own-secrets": {
-    "token": "${dir:state}/token",
+    "token": "/var/lib/gitlab/token",
-    "broker": "${dir:mesh-state}/broker"
+    "broker": "/var/lib/mesh/gitlab/broker"
   },
   "resources": [
     {
       "id": "mesh-state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/mesh/gitlab",
-      "place": "mesh"
+      "mode": "0700"
     },
     {
       "id": "state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/gitlab",
-      "place": "."
+      "mode": "0700"
     },
     {
       "id": "config",
       "type": "file",
-      "path": "${dir:state}/config.json",
+      "path": "/var/lib/gitlab/config.json",
       "merge": "json",
       "content": "{}",
       "mode": "0600"
@@ -32,9 +32,9 @@
       "name": "mesh-runtime-gitlab",
       "network": "host",
       "volumes": [
-        "${dir:state}/config.json:/run/config/config.json:ro",
+        "/var/lib/gitlab/config.json:/run/config/config.json:ro",
-        "${dir:state}/token:/run/secrets/token:ro",
+        "/var/lib/gitlab/token:/run/secrets/token:ro",
-        "${dir:mesh-state}/broker:/run/secrets/broker:ro"
+        "/var/lib/mesh/gitlab/broker:/run/secrets/broker:ro"
       ],
       "env": {
         "MESH_GITLAB_TOKEN_FILE": "/run/secrets/token",

modules/grafana/index.ts

@@ -40,7 +40,7 @@ async function pollAlerts(client: GrafanaClient): Promise<void> {
     for (const key of now) {
       if (!firing.has(key)) {
         const a = byKey.get(key)!;
-        await emit("alert.firing", { name: a.name, labels: a.labels, activeAt: a.activeAt });
+        await emit("module.grafana.alert.firing", { name: a.name, labels: a.labels, activeAt: a.activeAt });
       }
     }
   }

modules/grafana/module.json

@@ -2,18 +2,17 @@
   "module": "grafana",
   "version": "1",
   "emits": [
-    "alert.firing"
+    "module.grafana.alert.firing"
   ],
   "own-secrets": {
-    "admin": "${dir:mesh-state}/admin",
+    "admin": "/var/lib/grafana-module/admin.secret",
-    "broker": "${dir:mesh-state}/broker"
+    "broker": "/var/lib/mesh/grafana/broker"
   },
   "capabilities": [
     "container-runtime"
   ],
   "listens": [
     {
-      "name": "web",
       "port": 3000,
       "protocol": "tcp",
       "from": "mesh",
@@ -24,93 +23,51 @@
     {
       "id": "mesh-state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/mesh/grafana",
-      "place": "mesh"
+      "mode": "0700"
     },
     {
       "id": "state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/grafana-module",
-      "place": "."
+      "mode": "0700"
     },
     {
       "id": "data",
       "type": "directory",
+      "path": "/services/grafana/data",
       "mode": "0700",
       "owner": "472:472"
     },
     {
-      "id": "admin-secret",
+      "id": "server-env",
       "type": "file",
-      "path": "${dir:state}/admin.secret",
+      "path": "/var/lib/grafana-module/server.env",
-      "mode": "0400",
+      "mode": "0600",
-      "owner": "472:472",
+      "content": "GF_SECURITY_ADMIN_PASSWORD=${secret:admin}\n"
-      "content": "${secret:admin}"
-    },
-    {
-      "id": "oidc-secret",
-      "type": "file",
-      "path": "${dir:state}/oidc-client.secret",
-      "mode": "0400",
-      "owner": "472:472",
-      "content": "${secret:oidc-client}"
-    },
-    {
-      "id": "oidc-env",
-      "type": "file",
-      "path": "${dir:state}/oidc.env",
-      "mode": "0644",
-      "content": "GF_SERVER_ROOT_URL=https://${bound:route:name}\nGF_AUTH_GENERIC_OAUTH_ENABLED=true\nGF_AUTH_GENERIC_OAUTH_NAME=Keycloak\nGF_AUTH_GENERIC_OAUTH_CLIENT_ID=${bound:oidc-client:as}\nGF_AUTH_GENERIC_OAUTH_CLIENT_SECRET__FILE=/run/secrets/oidc-client\nGF_AUTH_GENERIC_OAUTH_SCOPES=openid email profile roles\nGF_AUTH_GENERIC_OAUTH_AUTH_URL=${bound:oidc-client:issuer}${bound:oidc-client:authorization-path}\nGF_AUTH_GENERIC_OAUTH_TOKEN_URL=${bound:oidc-client:issuer}${bound:oidc-client:token-path}\nGF_AUTH_GENERIC_OAUTH_API_URL=${bound:oidc-client:issuer}${bound:oidc-client:userinfo-path}\nGF_AUTH_GENERIC_OAUTH_ROLE_ATTRIBUTE_PATH=contains(roles[*], 'admin') && 'Admin' || contains(realm_access.roles[*], 'admin') && 'Admin' || 'Viewer'\nGF_AUTH_GENERIC_OAUTH_USE_PKCE=true\nGF_AUTH_GENERIC_OAUTH_ALLOW_SIGN_UP=true\nGF_AUTH_GENERIC_OAUTH_ALLOW_ASSIGN_GRAFANA_ADMIN=true\n"
-    },
-    {
-      "id": "influxdb-secret",
-      "type": "file",
-      "path": "${dir:state}/influxdb-api.secret",
-      "mode": "0400",
-      "owner": "472:472",
-      "content": "${secret:influxdb-api}"
-    },
-    {
-      "id": "influxdb-datasource",
-      "type": "file",
-      "path": "${dir:state}/datasource-influxdb.yaml",
-      "mode": "0644",
-      "content": "apiVersion: 1\n# Written by the mesh from grafana's influxdb-api binding; grafana reads it at start. Its own name and\n# uid, so a data source somebody made in the UI is never overwritten, and read-only in the UI because\n# the mesh resets it. The password is read from the file the mesh delivers, never written here.\ndatasources:\n  - name: InfluxDB (mesh)\n    uid: mesh-influxdb-api\n    type: influxdb\n    access: proxy\n    url: ${bound:influxdb-api:scheme}://${bound:influxdb-api:at}:${bound:influxdb-api:port}\n    user: ${bound:influxdb-api:as}\n    isDefault: false\n    editable: false\n    jsonData:\n      dbName: ${bound:influxdb-api:bucket}\n      httpMode: POST\n    secureJsonData:\n      password: $__file{/run/secrets/influxdb-api}\n"
     },
     {
       "id": "server",
       "type": "container",
       "name": "grafana",
-      "image": "grafana/grafana@sha256:ac461fb352abc50da10a51c7d02462e9c05488f11f53f14b3ad79a8145f638a0",
+      "image": "grafana/grafana@sha256:f772d434e8fab0049deb2b1b30abd43342bcfca1537614aa8d36080232cf4283",
       "ports": [
         "3000"
       ],
       "volumes": [
-        "${dir:data}:/var/lib/grafana",
+        "/services/grafana/data:/var/lib/grafana"
-        "${dir:state}/admin.secret:/run/secrets/admin:ro",
-        "${dir:state}/oidc-client.secret:/run/secrets/oidc-client:ro",
-        "${dir:state}/influxdb-api.secret:/run/secrets/influxdb-api:ro",
-        "${dir:state}/datasource-influxdb.yaml:/etc/grafana/provisioning/datasources/mesh-influxdb.yaml:ro"
       ],
-      "env": {
-        "GF_SECURITY_ADMIN_PASSWORD__FILE": "/run/secrets/admin"
-      },
       "env-file": [
-        "${dir:state}/oidc.env"
+        "/var/lib/grafana-module/server.env"
       ],
-      "restart-on": [
+      "secrets-in-environment": "grafana honours GF_SECURITY_ADMIN_PASSWORD__FILE; convertible, awaiting a bed that exercises the admin password (assigned-grafana serves tools only)"
-        "oidc-env",
-        "oidc-secret",
-        "influxdb-datasource",
-        "influxdb-secret"
-      ]
     },
     {
       "id": "runtime-config",
       "type": "file",
-      "path": "${dir:mesh-state}/config.json",
+      "path": "/var/lib/mesh/grafana/config.json",
       "mode": "0600",
-      "content": "{\n  \"user\": \"admin\",\n  \"password\": \"${secret:admin}\"\n}\n",
+      "content": "{}\n",
       "merge": "json"
     },
     {
@@ -119,12 +76,12 @@
       "name": "mesh-grafana",
       "network": "host",
       "volumes": [
-        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "/var/lib/mesh/grafana/broker:/run/secrets/broker:ro",
-        "${dir:mesh-state}/config.json:/run/config/config.json:ro"
+        "/var/lib/mesh/grafana/config.json:/run/config/config.json:ro"
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_GRAFANA_URL": "http://127.0.0.1:${port:3000}",
+        "MESH_GRAFANA_URL": "http://127.0.0.1:3000",
         "MESH_GRAFANA_CONFIG_FILE": "/run/config/config.json"
       },
       "restart-on": [
@@ -134,32 +91,16 @@
     }
   ],
   "requires": [
-    "route",
+    "route"
-    "oidc-client",
-    "influxdb-api"
   ],
   "contributes": {
     "route": {
       "label": "grafana",
-      "endpoint": "web"
+      "port": 3000
-    },
-    "oidc-client": {
-      "label": "grafana",
-      "endpoint": "web",
-      "callback": "/login/generic_oauth"
-    },
-    "influxdb-api": {
-      "access": "read"
     }
   },
   "binds": {
-    "route": "${dir:state}/route.json",
+    "route": "/var/lib/mesh/grafana/route.json"
-    "oidc-client": "${dir:state}/oidc.json",
-    "influxdb-api": "${dir:state}/influxdb.json"
-  },
-  "secrets": {
-    "oidc-client": "${dir:mesh-state}/oidc-client",
-    "influxdb-api": "${dir:mesh-state}/influxdb-api"
   },
   "build": {
     "on": [

modules/hello-web/module.json

@@ -11,15 +11,14 @@
   "contributes": {
     "route": {
       "label": "hello",
-      "endpoint": "web"
+      "port": 8080
     }
   },
   "binds": {
-    "route": "${dir:state}/route.json"
+    "route": "/var/lib/hello-web/route.json"
   },
   "listens": [
     {
-      "name": "web",
       "port": 8080,
       "protocol": "tcp",
       "from": "mesh",
@@ -30,13 +29,13 @@
     {
       "id": "state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/hello-web",
-      "place": "."
+      "mode": "0700"
     },
     {
       "id": "page",
       "type": "file",
-      "path": "${dir:state}/index.html",
+      "path": "/var/lib/hello-web/index.html",
       "mode": "0644",
       "content": "hello from hello-web, routed by the mesh\n"
     },
@@ -51,10 +50,10 @@
       "name": "hello-web",
       "network": "hello-web",
       "ports": [
-        "8080"
+        "8080:8080"
       ],
       "volumes": [
-        "${dir:state}/index.html:/www/index.html:ro"
+        "/var/lib/hello-web/index.html:/www/index.html:ro"
       ],
       "args": [
         "sh",

modules/home-assistant/Dockerfile

@@ -13,7 +13,7 @@ ARG RUNTIME_BASE
 FROM ${BUILD_BASE} AS build
 WORKDIR /app/modules/home-assistant
 COPY . .
-RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts provisions/hass.ts provisions/probe.ts provisions/connections.ts provisions/mesh.ts provisions/index.ts \
+RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
       --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 
 FROM ${RUNTIME_BASE}
@@ -22,6 +22,3 @@ COPY --from=build /app/modules/home-assistant/dist /app/modules/home-assistant/d
 # 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/home-assistant/dist/index.js,/app/modules/home-assistant/dist/tools/index.js
-# NOT dist/provisions/index.js: that is a step the host runs to completion, named by the
-# `provisions` 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/home-assistant/index.ts

@@ -44,7 +44,7 @@ async function pollStates(): Promise<void> {
   for (const s of states) {
     const prev = lastState.get(s.entity_id);
     if (primed && prev !== undefined && prev !== s.state) {
-      await emit("state.changed", {
+      await emit("module.home-assistant.state.changed", {
         entity: s.entity_id,
         name: nameOf(s),
         from: prev,

modules/home-assistant/module.json

@@ -6,75 +6,51 @@
     "container-runtime"
   ],
   "emits": [
-    "state.changed"
+    "module.home-assistant.state.changed"
   ],
   "own-secrets": {
-    "broker": "${dir:mesh-state}/broker",
+    "broker": "/var/lib/mesh/home-assistant/broker",
-    "token": "${dir:mesh-state}/token"
+    "token": "/var/lib/mesh/home-assistant/token"
   },
   "listens": [
     {
-      "name": "web",
       "port": 8123,
       "protocol": "tcp",
       "from": "mesh",
-      "why": "the dashboard, the API and the companion apps"
+      "why": "the dashboard and the API"
-    },
-    {
-      "name": "sonos-events",
-      "port": 1400,
-      "protocol": "tcp",
-      "from": "mesh",
-      "why": "the Sonos integration's event callback: speakers push their state changes here"
-    },
-    {
-      "name": "webrtc",
-      "port": 18555,
-      "protocol": "tcp",
-      "from": "mesh",
-      "why": "the bundled go2rtc's WebRTC port, which camera streams to a browser use"
     }
   ],
   "resources": [
     {
       "id": "mesh-state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/mesh/home-assistant",
-      "place": "mesh"
+      "mode": "0700"
-    },
-    {
-      "id": "state",
-      "type": "directory",
-      "mode": "0700",
-      "place": "."
     },
     {
       "id": "config",
       "type": "directory",
-      "mode": "0700"
+      "path": "/services/home-assistant/config",
-    },
+      "mode": "0700",
-    {
+      "owner": "1000:1000"
-      "id": "written",
-      "type": "directory",
-      "mode": "0700"
     },
     {
       "id": "server",
       "type": "container",
       "name": "home-assistant",
-      "image": "ghcr.io/home-assistant/home-assistant@sha256:d8922685169707fd91e8b9729902d975f06157d005e422874d201e0261dda196",
+      "image": "ghcr.io/home-assistant/home-assistant@sha256:14931c6b13756317849f46da1d01b45937a1150db66c081cfe529d48215943fe",
       "network": "host",
       "env": {
         "TZ": "Etc/UTC"
       },
       "volumes": [
-        "${dir:config}:/config"
+        "/services/home-assistant/config:/config"
       ]
     },
     {
       "id": "runtime-config",
       "type": "file",
-      "path": "${dir:mesh-state}/config.json",
+      "path": "/var/lib/mesh/home-assistant/config.json",
       "mode": "0600",
       "content": "{}\n",
       "merge": "json"
@@ -85,92 +61,35 @@
       "name": "mesh-home-assistant",
       "network": "host",
       "volumes": [
-        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "/var/lib/mesh/home-assistant/broker:/run/secrets/broker:ro",
-        "${dir:mesh-state}/token:/run/secrets/token:ro",
+        "/var/lib/mesh/home-assistant/token:/run/secrets/token:ro",
-        "${dir:mesh-state}/config.json:/run/config/config.json:ro"
+        "/var/lib/mesh/home-assistant/config.json:/run/config/config.json:ro",
+        "/services/home-assistant/config:/var/lib/home-assistant/config:ro"
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_HOMEASSISTANT_URL": "http://127.0.0.1:${port:8123}",
+        "MESH_HOMEASSISTANT_URL": "http://127.0.0.1:8123",
         "MESH_HOMEASSISTANT_TOKEN_FILE": "/run/secrets/token",
-        "MESH_HOMEASSISTANT_CONFIG_FILE": "/run/config/config.json"
+        "MESH_HOMEASSISTANT_CONFIG_FILE": "/run/config/config.json",
+        "MESH_HOMEASSISTANT_CONFIG_DIR": "/var/lib/home-assistant/config"
       },
       "restart-on": [
         "runtime-config"
       ],
       "artifact": "runtime"
-    },
-    {
-      "id": "provisions",
-      "type": "container",
-      "name": "mesh-home-assistant-provisions",
-      "network": "host",
-      "run-once": true,
-      "volumes": [
-        "${dir:mesh-state}/token:/run/secrets/token:ro",
-        "${dir:written}:/var/lib/home-assistant-provisions",
-        "${dir:state}/mqtt-topic.json:/run/provisions/mqtt-topic.json:ro",
-        "${dir:state}/mqtt-topic.secret:/run/provisions/mqtt-topic.secret:ro",
-        "${dir:state}/sonarr-api.json:/run/provisions/sonarr-api.json:ro",
-        "${dir:state}/sonarr-api.secret:/run/provisions/sonarr-api.secret:ro",
-        "${dir:state}/radarr-api.json:/run/provisions/radarr-api.json:ro",
-        "${dir:state}/radarr-api.secret:/run/provisions/radarr-api.secret:ro",
-        "${dir:state}/lidarr-api.json:/run/provisions/lidarr-api.json:ro",
-        "${dir:state}/lidarr-api.secret:/run/provisions/lidarr-api.secret:ro"
-      ],
-      "env": {
-        "MESH_HOMEASSISTANT_URL": "http://127.0.0.1:${port:8123}",
-        "MESH_HOMEASSISTANT_TOKEN_FILE": "/run/secrets/token",
-        "MESH_PROVISIONS_DIR": "/run/provisions",
-        "MESH_WRITTEN_DIR": "/var/lib/home-assistant-provisions"
-      },
-      "args": [
-        "run",
-        "/app/modules/home-assistant/dist/provisions/index.js"
-      ],
-      "restart-on": [
-        "bound-mqtt-topic",
-        "secret-mqtt-topic",
-        "bound-sonarr-api",
-        "secret-sonarr-api",
-        "bound-radarr-api",
-        "secret-radarr-api",
-        "bound-lidarr-api",
-        "secret-lidarr-api"
-      ],
-      "artifact": "runtime"
     }
   ],
   "requires": [
-    "lidarr-api",
+    "route"
-    "mqtt-topic",
-    "radarr-api",
-    "route",
-    "sonarr-api"
   ],
   "contributes": {
-    "mqtt-topic": {
-      "topics": [
-        "#"
-      ]
-    },
     "route": {
       "label": "home-assistant",
-      "endpoint": "web"
+      "port": 8123
     }
   },
   "binds": {
-    "route": "${dir:state}/route.json",
+    "route": "/var/lib/mesh/home-assistant/route.json"
-    "mqtt-topic": "${dir:state}/mqtt-topic.json",
-    "sonarr-api": "${dir:state}/sonarr-api.json",
-    "radarr-api": "${dir:state}/radarr-api.json",
-    "lidarr-api": "${dir:state}/lidarr-api.json"
-  },
-  "secrets": {
-    "mqtt-topic": "${dir:state}/mqtt-topic.secret",
-    "sonarr-api": "${dir:state}/sonarr-api.secret",
-    "radarr-api": "${dir:state}/radarr-api.secret",
-    "lidarr-api": "${dir:state}/lidarr-api.secret"
   },
   "build": {
     "on": [

modules/home-assistant/package.json

@@ -1,14 +1,9 @@
 {
   "name": "@novox/module-home-assistant",
   "version": "0.1.0",
-  "description": "home-assistant \u2014 home automation platform. Its API client, tools and events live here (novox/hq ADR 0039).",
+  "description": "home-assistant — home automation platform. 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 provisions/hass.ts provisions/probe.ts provisions/connections.ts provisions/mesh.ts provisions/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/home-assistant/provisions/connections.ts

@@ -1,486 +0,0 @@
-// How home-assistant's provisions step brings Home Assistant's integrations in line with what the
-// mesh bound: the MQTT integration to `mqtt-topic`, the Sonarr, Radarr and Lidarr integrations to
-// `sonarr-api`, `radarr-api` and `lidarr-api`. Pure logic over two seams — Home Assistant's config
-// flows (hass.ts) and the broker/apps — so it is tested against fakes (test/provisions.test.ts).
-//
-// The half that reads files and talks HTTP lives beside it (mesh.ts, hass.ts, probe.ts, index.ts).
-
-import { createHash } from "node:crypto";
-
-import type { Hass, SchemaField } from "./hass.js";
-import type { Probe } from "./probe.js";
-
-/** What the mesh wrote at `binds.<provision>` (the controller's binding document). */
-export interface Binding {
-  provision?: string;
-  from?: string;
-  at?: string;
-  as?: string;
-  serves?: Record<string, unknown>;
-}
-
-/** How one provision came out. Never carries a credential. */
-export type Outcome =
-  | { what: string; result: "unchanged"; note?: string }
-  | { what: string; result: "written"; fields: string[]; note?: string }
-  | { what: string; result: "equivalent"; note: string }
-  | { what: string; result: "refused"; problem: string };
-
-/** A port the binding serves, or undefined when it names none usable. */
-export function portOf(serves: Record<string, unknown> | undefined): number | undefined {
-  const port = Number(serves?.port);
-  return Number.isInteger(port) && port > 0 && port <= 65535 ? port : undefined;
-}
-
-/** A host as it goes into a URL: an IPv6 literal bracketed. */
-export function urlHost(host: string): string {
-  return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
-}
-
-/**
- * What this step last wrote, per target, as a digest: the only way to know "already as the mesh
- * says" for a credential Home Assistant will not show back. A sha256 over the target and the values,
- * never the values; kept in the module's own placed directory.
- */
-export interface Marks {
-  get(name: string): Promise<string | undefined>;
-  set(name: string, digest: string): Promise<void>;
-}
-
-export function digest(...parts: (string | number)[]): string {
-  return createHash("sha256").update(parts.map(String).join("\u0000")).digest("hex");
-}
-
-/** An error as text with the credential taken out, raw and URL-encoded. */
-export function scrub(err: unknown, ...secrets: (string | undefined)[]): string {
-  let text = err instanceof Error ? err.message : String(err);
-  for (const s of secrets) {
-    if (!s) continue;
-    for (const form of new Set([s, encodeURIComponent(s)])) text = text.split(form).join("***");
-  }
-  return text;
-}
-
-/**
- * What a form would submit if a person pressed "submit" without touching it: each field's
- * suggested value (what Home Assistant pre-fills from the entry), else its default; a section's
- * fields nested under its name. The step lays only the connection fields over this, so every other
- * choice the entry carries is sent back exactly as Home Assistant showed it.
- */
-export function formValues(schema: readonly SchemaField[] | null | undefined): Record<string, unknown> {
-  const out: Record<string, unknown> = {};
-  for (const field of schema ?? []) {
-    if (Array.isArray(field.schema)) {
-      out[field.name] = formValues(field.schema);
-      continue;
-    }
-    const suggested = field.description?.suggested_value;
-    if (suggested !== undefined && suggested !== null) out[field.name] = suggested;
-    else if (field.default !== undefined) out[field.name] = field.default;
-  }
-  return out;
-}
-
-/** Whether a form has a field of this name at its top level. */
-export function hasField(schema: readonly SchemaField[] | null | undefined, name: string): boolean {
-  return (schema ?? []).some((f) => f.name === name);
-}
-
-// ---- MQTT ----
-
-// Home Assistant's MQTT integration, pointed at the broker the mesh bound — `mqtt-topic`.
-//
-// **Why a step.** Home Assistant keeps its broker, login and password in its MQTT config entry
-// (`.storage/core.config_entries`), not in a file the mesh could fill with `${bound:mqtt-topic:at}`.
-// So this reads the binding and the pair credential and makes the entry say the same thing, through
-// the MQTT integration's own reconfigure flow — the flow its "Reconfigure" button runs, which tests
-// the connection itself and saves nothing it could not connect with.
-//
-// **Only the connection, and only when it differs.** Broker, port, username, password. The protocol
-// version, client id, keepalive, TLS choices and discovery options the entry holds are sent back
-// exactly as Home Assistant pre-filled them. Whether the password already matches cannot be read
-// back (Home Assistant never shows a stored password), so the step keeps a digest of what it last
-// wrote: equal broker/port/username and an equal digest is "already as the mesh says".
-//
-// **Nothing loses its connection without someone seeing it.** Before Home Assistant is touched the
-// broker itself is asked whether it takes the delivered login (the provisioner creates it within
-// seconds of the grant): if not, nothing is written and the step fails saying why, and Home
-// Assistant keeps the login it has — the carried `luffy` on ace, which mosquitto keeps. If Home
-// Assistant's own connection test refuses the new settings, the flow saves nothing, and the step
-// fails with Home Assistant's reason. A login that may not subscribe to the discovery topics is said
-// as a warning: discovery would find nothing.
-
-export const MQTT_PROVISION = "mqtt-topic";
-/** Home Assistant's discovery prefix, subscribed to whenever discovery is on (the default). */
-export const DISCOVERY_FILTER = "homeassistant/#";
-
-export interface MqttWanted {
-  host: string;
-  port: number;
-  username: string;
-  password: string;
-}
-
-export type Wanted = { ok: true; want: MqttWanted } | { ok: false; problem: string };
-
-/** The broker, port and login the mesh says Home Assistant uses. */
-export function wantedMqtt(binding: Binding | undefined, credential: string | undefined): Wanted {
-  if (!binding) return { ok: false, problem: `no binding for ${MQTT_PROVISION} was delivered — the mesh writes it before this step runs` };
-  const host = typeof binding.at === "string" ? binding.at.trim() : "";
-  if (!host) return { ok: false, problem: `the ${MQTT_PROVISION} binding names no host (at)` };
-  const port = portOf(binding.serves);
-  if (port === undefined) return { ok: false, problem: `the ${MQTT_PROVISION} binding serves no usable port (${String(binding.serves?.port)})` };
-  const scheme = binding.serves?.scheme;
-  if (scheme !== undefined && scheme !== "mqtt") {
-    return { ok: false, problem: `the ${MQTT_PROVISION} binding serves scheme ${String(scheme)}; this step writes plain MQTT` };
-  }
-  const username = typeof binding.as === "string" ? binding.as.trim() : "";
-  if (!username) return { ok: false, problem: `the ${MQTT_PROVISION} binding names no login (as)` };
-  const password = (credential ?? "").replace(/\n$/, "");
-  if (!password) return { ok: false, problem: `the ${MQTT_PROVISION} credential is empty or was not delivered` };
-  return { ok: true, want: { host, port, username, password } };
-}
-
-export interface MqttDeps {
-  hass: Hass;
-  probe: Probe;
-  marks: Marks;
-}
-
-const markFor = (entryId: string, w: MqttWanted): string => digest("mqtt", entryId, w.host, w.port, w.username, w.password);
-
-/** Bring Home Assistant's MQTT entry in line with the mesh. Never throws: every failure is an outcome. */
-export async function reconcileMqtt(deps: MqttDeps, binding: Binding | undefined, credential: string | undefined): Promise<Outcome> {
-  const what = "mqtt";
-  const w = wantedMqtt(binding, credential);
-  if ("problem" in w) return { what, result: "refused", problem: w.problem };
-  const want = w.want;
-
-  // The broker first: a login it does not take is never written into Home Assistant.
-  let note: string | undefined;
-  try {
-    const probe = await deps.probe(want.host, want.port, want.username, want.password, DISCOVERY_FILTER);
-    if (probe.connack === 4 || probe.connack === 5) {
-      return {
-        what,
-        result: "refused",
-        problem:
-          `the broker at ${want.host}:${want.port} does not (yet) take the login ${want.username} with the delivered ` +
-          `password (CONNACK ${probe.connack}); mosquitto's provisioner creates it from the grant — nothing was ` +
-          `written, and Home Assistant keeps the broker login it has`,
-      };
-    }
-    if (probe.connack !== 0) {
-      return { what, result: "refused", problem: `the broker at ${want.host}:${want.port} answered CONNACK ${probe.connack}; nothing was written` };
-    }
-    if (probe.suback === 0x80) {
-      note =
-        `warning: ${want.username} may not subscribe to ${DISCOVERY_FILTER} — MQTT discovery will find nothing; ` +
-        `grant it with the mqtt-topic contribution's \`topics\``;
-    }
-  } catch (err) {
-    return {
-      what,
-      result: "refused",
-      problem: `the broker at ${want.host}:${want.port} could not be asked: ${scrub(err, want.password)}; nothing was written`,
-    };
-  }
-
-  try {
-    const entries = (await deps.hass.entries("mqtt")).filter((e) => e.domain === "mqtt");
-    if (entries.length > 1) {
-      return { what, result: "refused", problem: `Home Assistant has ${entries.length} MQTT entries; which one the mesh owns is not guessed` };
-    }
-    if (entries.length === 0) return await createEntry(deps, want, note);
-
-    const entry = entries[0];
-    const flow = await deps.hass.startFlow("mqtt", entry.entry_id);
-    if (flow.type !== "form" || !flow.flow_id || !flow.data_schema) {
-      if (flow.flow_id) await deps.hass.abortFlow(flow.flow_id);
-      return { what, result: "refused", problem: `Home Assistant's MQTT reconfigure flow answered ${flow.type}${flow.reason ? ` (${flow.reason})` : ""}` };
-    }
-    const current = formValues(flow.data_schema);
-    const fields: string[] = [];
-    if (String(current.broker ?? "") !== want.host) fields.push("broker");
-    if (Number(current.port ?? 0) !== want.port) fields.push("port");
-    if (String(current.username ?? "") !== want.username) fields.push("username");
-    if ((await deps.marks.get("mqtt")) !== markFor(entry.entry_id, want)) fields.push("password");
-    if (fields.length === 0) {
-      await deps.hass.abortFlow(flow.flow_id);
-      return note ? { what, result: "unchanged", note } : { what, result: "unchanged" };
-    }
-
-    const saved = await deps.hass.stepFlow(flow.flow_id, {
-      ...current,
-      broker: want.host,
-      port: want.port,
-      username: want.username,
-      password: want.password,
-    });
-    if (saved.type === "abort" && saved.reason === "reconfigure_successful") {
-      await deps.marks.set("mqtt", markFor(entry.entry_id, want));
-      return { what, result: "written", fields, ...(note ? { note } : {}) };
-    }
-    if (saved.flow_id) await deps.hass.abortFlow(saved.flow_id);
-    return {
-      what,
-      result: "refused",
-      problem:
-        `Home Assistant's own connection test refused ${want.username}@${want.host}:${want.port} ` +
-        `(${describe(saved)}); its MQTT entry is unchanged`,
-    };
-  } catch (err) {
-    return { what, result: "refused", problem: scrub(err, want.password) };
-  }
-}
-
-/** A fresh Home Assistant has no MQTT entry: made through the integration's user flow. */
-async function createEntry(deps: MqttDeps, want: MqttWanted, note?: string): Promise<Outcome> {
-  const what = "mqtt";
-  let flow = await deps.hass.startFlow("mqtt");
-  if (flow.type === "form" && flow.step_id !== "broker" && flow.flow_id) {
-    // Anything before the broker form (none outside the Supervisor) is not this step's to answer.
-    await deps.hass.abortFlow(flow.flow_id);
-    return { what, result: "refused", problem: `Home Assistant's MQTT user flow asked ${flow.step_id} before the broker` };
-  }
-  if (flow.type !== "form" || !flow.flow_id) {
-    return { what, result: "refused", problem: `Home Assistant's MQTT user flow answered ${describe(flow)}` };
-  }
-  const shown = formValues(flow.data_schema);
-  // A new entry's form has no value for its two certificate choices (a reconfigure pre-fills them
-  // from the entry): plain MQTT, so neither a CA nor a client certificate.
-  const other = (shown.other_settings ?? {}) as Record<string, unknown>;
-  if (flow.data_schema?.some((f) => f.name === "other_settings")) {
-    shown.other_settings = { set_ca_cert: "off", set_client_cert: false, ...other };
-  }
-  flow = await deps.hass.stepFlow(flow.flow_id, {
-    ...shown,
-    broker: want.host,
-    port: want.port,
-    username: want.username,
-    password: want.password,
-  });
-  if (flow.type === "create_entry") {
-    const id = (flow.result as { entry_id?: string } | undefined)?.entry_id;
-    if (id) await deps.marks.set("mqtt", markFor(id, want));
-    return { what, result: "written", fields: ["entry"], ...(note ? { note } : {}) };
-  }
-  if (flow.flow_id) await deps.hass.abortFlow(flow.flow_id);
-  return { what, result: "refused", problem: `Home Assistant refused a new MQTT entry for ${want.host}:${want.port} (${describe(flow)})` };
-}
-
-export function describe(r: { type: string; reason?: string; errors?: Record<string, string> | null }): string {
-  const errors = r.errors ? Object.entries(r.errors).map(([k, v]) => `${k}: ${v}`).join(", ") : "";
-  return [r.type, r.reason, errors].filter(Boolean).join(" — ");
-}
-
-// ---- Sonarr, Radarr, Lidarr ----
-
-// Home Assistant's Sonarr, Radarr and Lidarr integrations, pointed at the apps the mesh bound —
-// `sonarr-api`, `radarr-api`, `lidarr-api` (their providers: mesh-catalog #156).
-//
-// **What Home Assistant lets anyone change, and what it does not.** Each integration keeps a URL and
-// an API key in its config entry. None of the three has a reconfigure flow: Home Assistant changes
-// them only through the flow its UI runs —
-//   - a **user flow** makes a new entry (validated against the app);
-//   - a **reauth flow**, which Home Assistant starts by itself when the app refuses the key it holds,
-//     takes a new key (Sonarr) or a new URL and key (Radarr, Lidarr);
-//   - anything else — the URL of a working entry — only by removing the integration and adding it
-//     again, which throws away its entities' names, areas and history links. **This step never
-//     removes an entry.**
-// So, per app:
-//   1. The bound key is tried against the bound app first. Refused, nothing is written: until the
-//      operator accepts the app's own key for this pair, the mesh delivers a value it minted, which
-//      no Servarr app takes (novox/hq ADR 0092) — the failure names the `secret accept` that fixes it.
-//   2. No entry: one is made through the user flow.
-//   3. A reauth flow Home Assistant started for the entry: finished with the bound key (and URL,
-//      where the integration's reauth asks for one).
-//   4. An entry whose URL (read from the device the integration registered, `configuration_url`)
-//      is the bound one and which is loaded: already as the mesh says. The key needs no digest here:
-//      a Servarr app has one key, so an entry loaded against the app holds the key the app took.
-//   5. A working entry at a different URL that reaches **the same app** — the same process, by the
-//      app's own status (start time, data folder, version) — is left as it is and said: ace's entries
-//      say `127.0.0.1:<port>` and the binding says `ace.internal:<port>`, one Sonarr either way.
-//   6. Anything else is refused, loudly, with what the operator can do; nothing is removed.
-
-
-export interface ServarrApp {
-  /** The integration's domain, also the app. */
-  domain: "sonarr" | "radarr" | "lidarr";
-  /** The provision it is required as: the `requires`, `binds` and `secrets` key. */
-  provision: string;
-  /** The app's status endpoint: answers 401 to a wrong key, and says which process answered. */
-  statusPath: string;
-}
-
-export const APPS: readonly ServarrApp[] = [
-  { domain: "sonarr", provision: "sonarr-api", statusPath: "/api/v3/system/status" },
-  { domain: "radarr", provision: "radarr-api", statusPath: "/api/v3/system/status" },
-  { domain: "lidarr", provision: "lidarr-api", statusPath: "/api/v1/system/status" },
-];
-
-/** The HTTP the step needs toward the apps, so a test can stand fakes in. */
-export interface Http {
-  fetch(url: string, init?: { method?: string; headers?: Record<string, string> }): Promise<{ status: number; text(): Promise<string> }>;
-}
-
-export type AppWanted = { ok: true; url: string; key: string; from: string } | { ok: false; problem: string };
-
-/** The URL and key the mesh says Home Assistant uses for this app. */
-export function wantedApp(spec: ServarrApp, binding: Binding | undefined, credential: string | undefined): AppWanted {
-  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() : "";
-  if (!at) return { ok: false, problem: `the ${spec.provision} binding names no host (at)` };
-  const port = portOf(binding.serves);
-  if (port === undefined) return { ok: false, problem: `the ${spec.provision} binding serves no usable port (${String(binding.serves?.port)})` };
-  const scheme = typeof binding.serves?.scheme === "string" && binding.serves.scheme ? binding.serves.scheme : "http";
-  if (scheme !== "http" && scheme !== "https") return { ok: false, problem: `the ${spec.provision} binding serves scheme ${scheme}` };
-  const base = typeof binding.serves?.["url-base"] === "string" ? String(binding.serves["url-base"]).trim().replace(/^\/+|\/+$/g, "") : "";
-  const key = (credential ?? "").trim();
-  if (!key) return { ok: false, problem: `the ${spec.provision} credential is empty or was not delivered` };
-  return {
-    ok: true,
-    url: `${scheme}://${urlHost(at)}:${port}${base ? `/${base}` : ""}`,
-    key,
-    from: typeof binding.from === "string" ? binding.from : "",
-  };
-}
-
-/** Two URLs naming the same place: scheme, host, port (explicit or default) and base path. */
-export function sameUrl(a: string | null | undefined, b: string): boolean {
-  if (!a) return false;
-  try {
-    const x = new URL(a);
-    const y = new URL(b);
-    const port = (u: URL) => u.port || (u.protocol === "https:" ? "443" : "80");
-    const path = (u: URL) => u.pathname.replace(/\/+$/, "");
-    return x.protocol === y.protocol && x.hostname.toLowerCase() === y.hostname.toLowerCase() && port(x) === port(y) && path(x) === path(y);
-  } catch {
-    return false;
-  }
-}
-
-type Status = { taken: true; status: Record<string, unknown> } | { taken: false };
-
-/** The app's status with this key: `taken: false` when it refuses the key; throws when it cannot be asked. */
-export async function appStatus(http: Http, spec: ServarrApp, url: string, key: string): Promise<Status> {
-  const res = await http.fetch(`${url.replace(/\/+$/, "")}${spec.statusPath}`, {
-    method: "GET",
-    headers: { "X-Api-Key": key, Accept: "application/json" },
-  });
-  if (res.status === 401 || res.status === 403) return { taken: false };
-  if (res.status < 200 || res.status >= 300) throw new Error(`${spec.domain} answered ${res.status} at ${spec.statusPath}`);
-  return { taken: true, status: JSON.parse(await res.text()) as Record<string, unknown> };
-}
-
-/** Whether two status answers came from one running app. */
-export function sameInstance(a: Record<string, unknown>, b: Record<string, unknown>): boolean {
-  const facts = ["startTime", "appData", "version"];
-  return facts.every((k) => a[k] !== undefined && a[k] !== null && a[k] === b[k]);
-}
-
-/** The remedy for a refused key, in the controller's words (ADR 0092). */
-export function acceptRemedy(spec: ServarrApp, from: string): string {
-  return (
-    `${spec.domain} refuses the ${spec.provision} credential the mesh delivered, so nothing was written into ` +
-    `Home Assistant. A Servarr app has one API key and the mesh cannot make it: accept ${spec.domain}'s own key ` +
-    `for this pair — \`secret accept <this node> home-assistant ${spec.provision} --provider ${from || "<its node>"} ` +
-    `--from <file holding ${spec.domain}'s ApiKey>\``
-  );
-}
-
-export interface ServarrDeps {
-  hass: Hass;
-  http: Http;
-}
-
-/** The input a Servarr form takes: what it shows, with the URL (where asked) and the key laid over. */
-function servarrInput(schema: readonly SchemaField[] | null | undefined, url: string, key: string): Record<string, unknown> {
-  const input = formValues(schema);
-  if (hasField(schema, "url")) input.url = url;
-  if (hasField(schema, "api_key")) input.api_key = key;
-  return input;
-}
-
-/** Bring Home Assistant's entry for one app in line with the mesh. Never throws. */
-export async function reconcileApp(deps: ServarrDeps, spec: ServarrApp, binding: Binding | undefined, credential: string | undefined): Promise<Outcome> {
-  const what = spec.domain;
-  const w = wantedApp(spec, binding, credential);
-  if ("problem" in w) return { what, result: "refused", problem: w.problem };
-
-  let bound: Status;
-  try {
-    bound = await appStatus(deps.http, spec, w.url, w.key);
-  } catch (err) {
-    return { what, result: "refused", problem: `${spec.domain} could not be asked at ${w.url}: ${scrub(err, w.key)}` };
-  }
-  if (!bound.taken) return { what, result: "refused", problem: acceptRemedy(spec, w.from) };
-
-  try {
-    const entries = (await deps.hass.entries(spec.domain)).filter((e) => e.domain === spec.domain);
-    if (entries.length > 1) {
-      return { what, result: "refused", problem: `Home Assistant has ${entries.length} ${spec.domain} entries; which one the mesh owns is not guessed` };
-    }
-
-    // No entry: made, through the integration's own user flow, which validates the key itself.
-    if (entries.length === 0) {
-      const flow = await deps.hass.startFlow(spec.domain);
-      if (flow.type !== "form" || !flow.flow_id) return { what, result: "refused", problem: `Home Assistant's ${spec.domain} user flow answered ${describe(flow)}` };
-      const made = await deps.hass.stepFlow(flow.flow_id, servarrInput(flow.data_schema, w.url, w.key));
-      if (made.type === "create_entry") return { what, result: "written", fields: ["entry"] };
-      if (made.flow_id) await deps.hass.abortFlow(made.flow_id);
-      return { what, result: "refused", problem: `Home Assistant refused a new ${spec.domain} entry at ${w.url} (${describe(made)})` };
-    }
-
-    const entry = entries[0];
-    if (entry.disabled_by) return { what, result: "unchanged", note: `the ${spec.domain} entry is disabled (by ${entry.disabled_by}); left alone` };
-
-    // A reauth Home Assistant started because the app refused its key: finished with the bound one.
-    const reauth = (await deps.hass.flowsInProgress()).find(
-      (f) => f.handler === spec.domain && f.context?.source === "reauth" && f.context?.entry_id === entry.entry_id,
-    );
-    if (reauth) {
-      let step = await deps.hass.stepFlow(reauth.flow_id, {}); // reauth_confirm: a confirmation, no fields
-      if (step.type === "form" && step.flow_id && step.step_id !== "reauth_confirm") {
-        const input = servarrInput(step.data_schema, w.url, w.key);
-        const fields = ["api_key", ...(hasField(step.data_schema, "url") ? ["url"] : [])];
-        step = await deps.hass.stepFlow(step.flow_id, input);
-        if (step.type === "abort" && step.reason === "reauth_successful") return { what, result: "written", fields };
-      }
-      return { what, result: "refused", problem: `Home Assistant's ${spec.domain} reauth did not take the bound key and URL (${describe(step)})` };
-    }
-
-    const device = (await deps.hass.devices()).find((d) => d.config_entries?.includes(entry.entry_id) && d.configuration_url);
-    const current = device?.configuration_url ?? undefined;
-    if (entry.state === "loaded" && sameUrl(current, w.url)) return { what, result: "unchanged" };
-
-    if (entry.state === "loaded" && current) {
-      let there: Status | undefined;
-      try {
-        there = await appStatus(deps.http, spec, current, w.key);
-      } catch {
-        there = undefined;
-      }
-      if (there?.taken && sameInstance(there.status, bound.status)) {
-        return {
-          what,
-          result: "equivalent",
-          note:
-            `Home Assistant reaches ${spec.domain} at ${current}, the same running app the mesh bound at ${w.url}; ` +
-            `Home Assistant has no way to change a working ${spec.domain} entry's URL short of removing it, so it is left as it is`,
-        };
-      }
-    }
-    return {
-      what,
-      result: "refused",
-      problem:
-        `Home Assistant's ${spec.domain} entry (${entry.state ?? "unknown state"}) points at ${current ?? "an unknown URL"}, ` +
-        `not the ${spec.domain} the mesh bound at ${w.url}. Home Assistant only lets a working entry's URL change by ` +
-        `removing and re-adding the integration, which this step never does: remove it in Home Assistant ` +
-        `(Settings → Devices & services → ${spec.domain}) and the next run adds it at the bound URL`,
-    };
-  } catch (err) {
-    return { what, result: "refused", problem: scrub(err, w.key) };
-  }
-}

modules/home-assistant/provisions/hass.ts

@@ -1,160 +0,0 @@
-// Home Assistant's own configuration API, as the provisions step uses it — the supported way to
-// change an integration's connection. Home Assistant keeps every integration in
-// `.storage/core.config_entries`, a file it owns and rewrites; the mesh may not write it, and it is
-// not a file the mesh could merge into. What Home Assistant offers instead is the same thing its UI
-// uses: **config flows** over REST (`/api/config/config_entries/flow`) — a user flow creates an
-// entry, a reconfigure flow changes one, a reauth flow (which Home Assistant starts itself when a
-// credential stops working) replaces its credential — each validated by the integration's own
-// connection test before anything is saved. The two things REST does not answer (which flows Home
-// Assistant has started, which device an entry made) come over its WebSocket API.
-//
-// Nothing here reads `.storage`. Authenticated with the module's accepted long-lived access token.
-
-/** A config entry as `GET /api/config/config_entries/entry` lists it — no data, no credentials. */
-export interface ConfigEntry {
-  entry_id: string;
-  domain: string;
-  title?: string;
-  source?: string;
-  state?: string;
-  disabled_by?: string | null;
-}
-
-/** One field of a flow's form, as Home Assistant serializes a voluptuous schema. */
-export interface SchemaField {
-  name: string;
-  type?: string;
-  required?: boolean;
-  optional?: boolean;
-  default?: unknown;
-  description?: { suggested_value?: unknown } | null;
-  /** A section (`type: "expandable"`) carries its own fields. */
-  schema?: SchemaField[];
-}
-
-/** What a flow answered: another form, an entry made, or the flow ended (abort). */
-export interface FlowResult {
-  type: string;
-  flow_id?: string;
-  handler?: string;
-  step_id?: string;
-  data_schema?: SchemaField[] | null;
-  errors?: Record<string, string> | null;
-  reason?: string;
-  result?: { entry_id?: string } | unknown;
-}
-
-/** A flow in progress that Home Assistant started itself (a reauth, a discovery). */
-export interface FlowProgress {
-  flow_id: string;
-  handler: string;
-  step_id?: string;
-  context?: { source?: string; entry_id?: string };
-}
-
-/** A device from the device registry; an integration names where its app is as configuration_url. */
-export interface DeviceEntry {
-  id: string;
-  config_entries?: string[];
-  configuration_url?: string | null;
-}
-
-export interface Hass {
-  entries(domain: string): Promise<ConfigEntry[]>;
-  /** A user flow for `handler`, or — given an entry — a reconfigure flow for it. */
-  startFlow(handler: string, entryId?: string): Promise<FlowResult>;
-  stepFlow(flowId: string, input: Record<string, unknown>): Promise<FlowResult>;
-  abortFlow(flowId: string): Promise<void>;
-  flowsInProgress(): Promise<FlowProgress[]>;
-  devices(): Promise<DeviceEntry[]>;
-}
-
-/** Home Assistant over HTTP: REST for entries and flows, one short WebSocket session per question. */
-export class HassApi implements Hass {
-  private readonly base: string;
-
-  constructor(url: string, private readonly token: string) {
-    this.base = url.replace(/\/$/, "");
-  }
-
-  private async rest(method: string, path: string, body?: unknown): Promise<unknown> {
-    const res = await fetch(`${this.base}${path}`, {
-      method,
-      headers: {
-        Authorization: `Bearer ${this.token}`,
-        Accept: "application/json",
-        ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
-      },
-      body: body !== undefined ? JSON.stringify(body) : undefined,
-    });
-    const text = await res.text();
-    if (!res.ok) {
-      // Home Assistant's error text names fields, never echoes their values.
-      throw new Error(`Home Assistant ${method} ${path} answered ${res.status}${text ? `: ${text.slice(0, 200)}` : ""}`);
-    }
-    return text ? (JSON.parse(text) as unknown) : undefined;
-  }
-
-  async entries(domain: string): Promise<ConfigEntry[]> {
-    return ((await this.rest("GET", `/api/config/config_entries/entry?domain=${encodeURIComponent(domain)}`)) ??
-      []) as ConfigEntry[];
-  }
-
-  async startFlow(handler: string, entryId?: string): Promise<FlowResult> {
-    return (await this.rest("POST", "/api/config/config_entries/flow", {
-      handler,
-      show_advanced_options: true,
-      ...(entryId ? { entry_id: entryId } : {}),
-    })) as FlowResult;
-  }
-
-  async stepFlow(flowId: string, input: Record<string, unknown>): Promise<FlowResult> {
-    return (await this.rest("POST", `/api/config/config_entries/flow/${encodeURIComponent(flowId)}`, input)) as FlowResult;
-  }
-
-  async abortFlow(flowId: string): Promise<void> {
-    await this.rest("DELETE", `/api/config/config_entries/flow/${encodeURIComponent(flowId)}`).catch(() => undefined);
-  }
-
-  async flowsInProgress(): Promise<FlowProgress[]> {
-    return (await this.ws("config_entries/flow/progress")) as FlowProgress[];
-  }
-
-  async devices(): Promise<DeviceEntry[]> {
-    return (await this.ws("config/device_registry/list")) as DeviceEntry[];
-  }
-
-  /** One WebSocket command: connect, authenticate, ask, close. */
-  private ws(type: string): Promise<unknown> {
-    const url = `${this.base.replace(/^http/, "ws")}/api/websocket`;
-    return new Promise((resolve, reject) => {
-      const socket = new WebSocket(url);
-      const timer = setTimeout(() => {
-        socket.close();
-        reject(new Error(`Home Assistant's WebSocket did not answer ${type} within 30s`));
-      }, 30_000);
-      const done = (fn: () => void): void => {
-        clearTimeout(timer);
-        socket.close();
-        fn();
-      };
-      socket.onerror = () => done(() => reject(new Error(`Home Assistant's WebSocket at ${url} failed`)));
-      socket.onmessage = (event: { data: unknown }) => {
-        const msg = JSON.parse(String(event.data)) as {
-          type: string;
-          id?: number;
-          success?: boolean;
-          result?: unknown;
-          error?: { message?: string };
-        };
-        if (msg.type === "auth_required") socket.send(JSON.stringify({ type: "auth", access_token: this.token }));
-        else if (msg.type === "auth_invalid") done(() => reject(new Error("Home Assistant refused the token")));
-        else if (msg.type === "auth_ok") socket.send(JSON.stringify({ id: 1, type }));
-        else if (msg.type === "result" && msg.id === 1) {
-          if (msg.success) done(() => resolve(msg.result));
-          else done(() => reject(new Error(`Home Assistant ${type}: ${msg.error?.message ?? "failed"}`)));
-        }
-      };
-    });
-  }
-}

modules/home-assistant/provisions/index.ts

@@ -1,84 +0,0 @@
-// home-assistant's provisions step — run once by the host after Home Assistant starts, and again
-// whenever a binding or pair credential it reads changes (the container's `restart-on`, novox/hq
-// ADR 0099). It points Home Assistant's MQTT integration at the `mqtt-topic` broker and its Sonarr,
-// Radarr and Lidarr integrations at the `sonarr-api`, `radarr-api` and `lidarr-api` apps, through
-// Home Assistant's own config flows (connections.ts). It connects to no mesh broker.
-//
-// Exits non-zero when anything could not be put right, 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 home-assistant's (novox/hq ADR 0136). Never prints a key or password.
-
-import { join } from "node:path";
-
-import { APPS, MQTT_PROVISION, reconcileApp, reconcileMqtt, type Outcome } from "./connections.js";
-import { HassApi } from "./hass.js";
-import { marksIn, readBinding, readIfThere } from "./mesh.js";
-import { probeBroker } from "./probe.js";
-
-const dir = process.env.MESH_PROVISIONS_DIR ?? "/run/provisions";
-const url = process.env.MESH_HOMEASSISTANT_URL ?? "http://127.0.0.1:8123";
-const token = (await readIfThere(process.env.MESH_HOMEASSISTANT_TOKEN_FILE))?.trim() ?? "";
-const marks = marksIn(process.env.MESH_WRITTEN_DIR ?? "/var/lib/home-assistant-provisions");
-const waitSeconds = Number(process.env.MESH_HOMEASSISTANT_WAIT_SECONDS ?? "300");
-
-if (!token) {
-  console.error("[hass-provisions] no Home Assistant token — home-assistant's own `token` secret has not been accepted");
-  process.exit(1);
-}
-
-/** Home Assistant answers /api/ with 200 once it is up and the token is good. */
-async function ready(): Promise<boolean> {
-  const until = Date.now() + waitSeconds * 1000;
-  for (;;) {
-    try {
-      const res = await fetch(`${url.replace(/\/$/, "")}/api/`, { headers: { Authorization: `Bearer ${token}` } });
-      if (res.status === 200) return true;
-      if (res.status === 401 || res.status === 403) {
-        console.error("[hass-provisions] Home Assistant refuses the token — accept a long-lived access token it issued");
-        return false;
-      }
-    } catch {
-      // not listening yet
-    }
-    if (Date.now() >= until) return false;
-    await new Promise((r) => setTimeout(r, 3000));
-  }
-}
-
-if (!(await ready())) {
-  console.error(`[hass-provisions] Home Assistant did not answer at ${url} within ${waitSeconds}s`);
-  process.exit(1);
-}
-
-const hass = new HassApi(url, token);
-const read = async (p: string) => [await readBinding(join(dir, `${p}.json`)), await readIfThere(join(dir, `${p}.secret`))] as const;
-
-const outcomes: Outcome[] = [];
-{
-  const [binding, secret] = await read(MQTT_PROVISION);
-  outcomes.push(await reconcileMqtt({ hass, probe: probeBroker, marks }, binding, secret));
-}
-for (const spec of APPS) {
-  const [binding, secret] = await read(spec.provision);
-  outcomes.push(await reconcileApp({ hass, http: { fetch: (u, init) => fetch(u, init) } }, spec, binding, secret));
-}
-
-let failed = 0;
-for (const o of outcomes) {
-  switch (o.result) {
-    case "unchanged":
-      console.log(`[hass-provisions] ${o.what}: already as the mesh says${o.note ? ` — ${o.note}` : ""}`);
-      break;
-    case "written":
-      console.log(`[hass-provisions] ${o.what}: wrote ${o.fields.join(", ")}; Home Assistant's own test passed${o.note ? ` — ${o.note}` : ""}`);
-      break;
-    case "equivalent":
-      console.log(`[hass-provisions] ${o.what}: ${o.note}`);
-      break;
-    case "refused":
-      failed++;
-      console.error(`[hass-provisions] ${o.what}: ${o.problem}`);
-      break;
-  }
-}
-process.exitCode = failed > 0 ? 1 : 0;

modules/home-assistant/provisions/mesh.ts

@@ -1,42 +0,0 @@
-// What the mesh delivered to home-assistant's provisions step, and the step's own small memory.
-//
-// Per provision it requires, the mesh writes two files beside each other (the manifest's `binds` and
-// `secrets`): `<provision>.json`, the binding — where the provider is (`at`), what it serves (`port`,
-// `scheme`, …) and the login this module presents (`as`) — and `<provision>.secret`, the pair
-// credential. Nothing here guesses a host, a port or a key.
-
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-
-import type { Binding, Marks } from "./connections.js";
-
-/** 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): Promise<Binding | undefined> {
-  const raw = await readIfThere(path);
-  if (raw === undefined) return undefined;
-  try {
-    return JSON.parse(raw) as Binding;
-  } catch {
-    return undefined;
-  }
-}
-
-export function marksIn(dir: string): Marks {
-  return {
-    async get(name) {
-      return (await readIfThere(join(dir, `${name}.digest`)))?.trim() || undefined;
-    },
-    async set(name, value) {
-      await mkdir(dir, { recursive: true, mode: 0o700 });
-      const path = join(dir, `${name}.digest`);
-      await writeFile(`${path}.tmp`, `${value}\n`, { mode: 0o600 });
-      await rename(`${path}.tmp`, path);
-    },
-  };
-}

modules/home-assistant/provisions/probe.ts

@@ -1,117 +0,0 @@
-// Ask the broker, before Home Assistant is told anything, whether it takes the login and password
-// the mesh delivered — and whether that login may subscribe to Home Assistant's discovery topics.
-//
-// One MQTT 3.1.1 session: CONNECT (clean, a throwaway client id, so Home Assistant's own session is
-// never taken over), read the CONNACK, optionally SUBSCRIBE once and read the SUBACK, DISCONNECT.
-// No dependency: the handful of bytes MQTT needs for this are written here.
-
-import { randomBytes } from "node:crypto";
-import { connect } from "node:net";
-
-export interface ProbeResult {
-  /** 0 accepted; 4 bad username or password; 5 not authorised. */
-  connack: number;
-  /** The SUBACK return code for the filter asked about: 0–2 granted, 0x80 refused. */
-  suback?: number;
-}
-
-export type Probe = (host: string, port: number, username: string, password: string, subscribe?: string) => Promise<ProbeResult>;
-
-function str(v: string): Buffer {
-  const b = Buffer.from(v, "utf8");
-  const len = Buffer.alloc(2);
-  len.writeUInt16BE(b.length);
-  return Buffer.concat([len, b]);
-}
-
-function packet(type: number, body: Buffer): Buffer {
-  let remaining = body.length;
-  const lenBytes: number[] = [];
-  do {
-    let byte = remaining % 128;
-    remaining = Math.floor(remaining / 128);
-    if (remaining > 0) byte |= 0x80;
-    lenBytes.push(byte);
-  } while (remaining > 0);
-  return Buffer.concat([Buffer.from([type, ...lenBytes]), body]);
-}
-
-/** The first complete packet in `buf`: its type byte, its body, and how many bytes it took. */
-export function firstPacket(buf: Buffer): { type: number; body: Buffer; used: number } | undefined {
-  if (buf.length < 2) return undefined;
-  let length = 0;
-  let multiplier = 1;
-  let i = 1;
-  for (;;) {
-    if (i >= buf.length) return undefined;
-    const byte = buf[i++];
-    length += (byte & 0x7f) * multiplier;
-    if ((byte & 0x80) === 0) break;
-    multiplier *= 128;
-    if (i > 4) throw new Error("malformed MQTT remaining length");
-  }
-  if (buf.length < i + length) return undefined;
-  return { type: buf[0], body: buf.subarray(i, i + length), used: i + length };
-}
-
-export const probeBroker: Probe = (host, port, username, password, subscribe) => {
-  const connectBody = Buffer.concat([
-    str("MQTT"),
-    Buffer.from([4, 0xc2, 0, 10]), // level 4 (3.1.1); username + password + clean session; keepalive 10s
-    str(`mesh-probe-${randomBytes(6).toString("hex")}`),
-    str(username),
-    str(password),
-  ]);
-  return new Promise((resolve, reject) => {
-    const socket = connect({ host, port });
-    let buf = Buffer.alloc(0);
-    const result: ProbeResult = { connack: -1 };
-    const timer = setTimeout(() => {
-      socket.destroy();
-      reject(new Error(`no answer from the broker at ${host}:${port} within 10s`));
-    }, 10_000);
-    const finish = (): void => {
-      clearTimeout(timer);
-      if (result.connack === 0) socket.end(Buffer.from([0xe0, 0]));
-      else socket.destroy();
-      resolve(result);
-    };
-    socket.on("connect", () => socket.write(packet(0x10, connectBody)));
-    socket.on("data", (chunk) => {
-      buf = Buffer.concat([buf, chunk]);
-      for (;;) {
-        let p;
-        try {
-          p = firstPacket(buf);
-        } catch (err) {
-          clearTimeout(timer);
-          socket.destroy();
-          reject(err);
-          return;
-        }
-        if (!p) return;
-        buf = buf.subarray(p.used);
-        const kind = p.type >> 4;
-        if (kind === 2) {
-          result.connack = p.body[1] ?? -1;
-          if (result.connack !== 0 || !subscribe) return finish();
-          // SUBSCRIBE, packet id 1, one filter at QoS 0.
-          socket.write(packet(0x82, Buffer.concat([Buffer.from([0, 1]), str(subscribe), Buffer.from([0])])));
-        } else if (kind === 9) {
-          result.suback = p.body[2];
-          return finish();
-        }
-      }
-    });
-    socket.on("error", (err) => {
-      clearTimeout(timer);
-      reject(err);
-    });
-    socket.on("close", () => {
-      if (result.connack === -1) {
-        clearTimeout(timer);
-        reject(new Error(`the broker at ${host}:${port} closed the connection without answering`));
-      }
-    });
-  });
-};

modules/home-assistant/test/provisions.test.ts

@@ -1,293 +0,0 @@
-// What holds home-assistant's provisions step (provisions/*.ts): Home Assistant's MQTT entry is
-// made to use the broker, port and login the mesh bound — only after the broker takes that login,
-// through the reconfigure flow, keeping every other setting as Home Assistant pre-filled it, and not
-// again once it already says so; its Sonarr/Radarr/Lidarr entries are made, finished (reauth), left
-// alone when they already reach the bound app, and never removed; a key the app refuses (the mesh's
-// minted value before the operator accepts the app's) is never written.
-//
-// Home Assistant and the apps are fakes answering as the real ones do (flow shapes checked against
-// ghcr.io/home-assistant/home-assistant 2026.9.3, the build ace runs).
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-
-import type { ConfigEntry, DeviceEntry, FlowProgress, FlowResult, Hass, SchemaField } from "../provisions/hass.ts";
-
-import type { Binding, Marks } from "../provisions/connections.ts";
-import { APPS, formValues, reconcileApp, reconcileMqtt, sameUrl, type Http, type ServarrApp } from "../provisions/connections.ts";
-import type { Probe } from "../provisions/probe.ts";
-
-const PWD_NOT_CHANGED = "__**password_not_changed**__";
-const MINTED = "mesh-minted-password";
-
-function mqttBinding(): Binding {
-  return { provision: "mqtt-topic", from: "ace", at: "ace.internal", as: "mesh_ace_hass", serves: { scheme: "mqtt", port: 1883 } };
-}
-
-/** The MQTT reconfigure form as Home Assistant serializes it, pre-filled from an entry. */
-function brokerForm(data: Record<string, unknown>): SchemaField[] {
-  return [
-    { name: "broker", type: "string", required: true, description: { suggested_value: data.broker } },
-    { name: "port", type: "integer", required: true, default: 1883, description: { suggested_value: data.port } },
-    { name: "protocol", type: "select", required: true, default: "3.1.1", description: { suggested_value: data.protocol } },
-    { name: "username", type: "string", optional: true, description: { suggested_value: data.username } },
-    { name: "password", type: "string", optional: true, description: { suggested_value: data.password ? PWD_NOT_CHANGED : undefined } },
-    {
-      name: "other_settings",
-      type: "expandable",
-      required: true,
-      schema: [
-        { name: "keepalive", type: "integer", optional: true, description: { suggested_value: 60 } },
-        { name: "transport", type: "select", required: true, default: "tcp", description: { suggested_value: "tcp" } },
-        { name: "set_ca_cert", type: "select", required: true, description: { suggested_value: "off" } },
-        { name: "set_client_cert", type: "boolean", required: true, description: { suggested_value: false } },
-      ],
-    },
-  ];
-}
-
-interface FakeOpts {
-  entries?: Record<string, (ConfigEntry & { data: Record<string, unknown> })[]>;
-  /** What Home Assistant's own connection test accepts. */
-  accepts?: (data: Record<string, unknown>) => boolean;
-  reauth?: FlowProgress[];
-  devices?: DeviceEntry[];
-}
-
-function fakeHass(opts: FakeOpts = {}) {
-  const entries = opts.entries ?? {};
-  const calls: string[] = [];
-  const submitted: Record<string, unknown>[] = [];
-  const flows = new Map<string, { handler: string; entryId?: string; step: string; reauth?: boolean }>();
-  let n = 0;
-  const accepts = opts.accepts ?? (() => true);
-  const form = (id: string, step: string, schema: SchemaField[], errors?: Record<string, string>): FlowResult => ({
-    type: "form", flow_id: id, step_id: step, data_schema: schema, errors: errors ?? null,
-  });
-  const servarrUser: SchemaField[] = [
-    { name: "url", type: "string", required: true },
-    { name: "api_key", type: "string", required: true },
-    { name: "more_options", type: "expandable", required: true, schema: [{ name: "verify_ssl", type: "boolean", optional: true, default: false }] },
-  ];
-  const hass: Hass = {
-    async entries(domain) {
-      calls.push(`entries ${domain}`);
-      return (entries[domain] ?? []).map(({ data: _d, ...e }) => e);
-    },
-    async startFlow(handler, entryId) {
-      calls.push(`start ${handler}${entryId ? ` ${entryId}` : ""}`);
-      const id = `f${++n}`;
-      if (handler === "mqtt") {
-        const entry = entryId ? entries.mqtt.find((e) => e.entry_id === entryId) : undefined;
-        if (entryId && !entry) return { type: "abort", reason: "not_found" };
-        flows.set(id, { handler, entryId, step: "broker" });
-        return form(id, "broker", brokerForm(entry?.data ?? {}));
-      }
-      if (entryId) return { type: "abort", reason: "not_implemented" }; // no reconfigure for Servarr
-      flows.set(id, { handler, step: "user" });
-      return form(id, "user", servarrUser);
-    },
-    async stepFlow(flowId, input) {
-      calls.push(`step ${flowId}`);
-      const flow = flows.get(flowId);
-      if (!flow) throw new Error(`Home Assistant POST flow/${flowId} answered 404`);
-      if (flow.step === "reauth_confirm") {
-        flow.step = "user";
-        return form(flowId, "user", [
-          { name: "url", type: "string", required: true, default: "http://old:1" },
-          { name: "api_key", type: "string", optional: true },
-          { name: "verify_ssl", type: "boolean", optional: true, default: false },
-        ]);
-      }
-      submitted.push(input);
-      if (flow.handler === "mqtt") {
-        const entry = entries.mqtt?.find((e) => e.entry_id === flow.entryId);
-        const data = { ...input, ...(input.password === PWD_NOT_CHANGED ? { password: entry?.data.password } : {}) };
-        if (!accepts(data)) return form(flowId, "broker", brokerForm(data), { base: "cannot_connect" });
-        flows.delete(flowId);
-        if (entry) {
-          entry.data = data;
-          return { type: "abort", reason: "reconfigure_successful" };
-        }
-        (entries.mqtt ??= []).push({ entry_id: "new-mqtt", domain: "mqtt", state: "loaded", data });
-        return { type: "create_entry", result: { entry_id: "new-mqtt" } };
-      }
-      if (!accepts(input)) return form(flowId, "user", servarrUser, { base: "invalid_auth" });
-      flows.delete(flowId);
-      if (flow.reauth) return { type: "abort", reason: "reauth_successful" };
-      (entries[flow.handler] ??= []).push({ entry_id: `new-${flow.handler}`, domain: flow.handler, state: "loaded", data: input });
-      return { type: "create_entry", result: { entry_id: `new-${flow.handler}` } };
-    },
-    async abortFlow(flowId) {
-      calls.push(`abort ${flowId}`);
-      flows.delete(flowId);
-    },
-    async flowsInProgress() {
-      for (const f of opts.reauth ?? []) flows.set(f.flow_id, { handler: f.handler, entryId: f.context?.entry_id, step: "reauth_confirm", reauth: true });
-      return opts.reauth ?? [];
-    },
-    async devices() {
-      return opts.devices ?? [];
-    },
-  };
-  return { hass, calls, submitted, entries };
-}
-
-function memoryMarks(): Marks & { store: Map<string, string> } {
-  const store = new Map<string, string>();
-  return { store, get: async (k) => store.get(k), set: async (k, v) => void store.set(k, v) };
-}
-
-const takes = (suback = 0): Probe => async (_h, _p, user, pass) => ({ connack: user === "mesh_ace_hass" && pass === MINTED ? 0 : 5, suback });
-
-const aceMqttEntry = () => ({
-  entry_id: "7d1e", domain: "mqtt", state: "loaded",
-  data: { broker: "127.0.0.1", port: 1883, protocol: "5", username: "luffy", password: "luffys-password" },
-});
-
-test("mqtt: the broker is asked first; a login it does not take is never written", async () => {
-  const f = fakeHass({ entries: { mqtt: [aceMqttEntry()] } });
-  const out = await reconcileMqtt({ hass: f.hass, probe: async () => ({ connack: 5 }), marks: memoryMarks() }, mqttBinding(), MINTED);
-  assert.equal(out.result, "refused");
-  assert.match((out as { problem: string }).problem, /does not \(yet\) take the login mesh_ace_hass/);
-  assert.deepEqual(f.calls, []); // Home Assistant not even asked
-  assert.equal(f.entries.mqtt[0].data.username, "luffy");
-});
-
-test("mqtt: ace's entry (127.0.0.1, luffy) is moved to the bound broker and login, every other setting kept", async () => {
-  const f = fakeHass({ entries: { mqtt: [aceMqttEntry()] } });
-  const marks = memoryMarks();
-  const out = await reconcileMqtt({ hass: f.hass, probe: takes(), marks }, mqttBinding(), `${MINTED}\n`);
-  assert.deepEqual(out, { what: "mqtt", result: "written", fields: ["broker", "username", "password"] });
-  assert.deepEqual(f.entries.mqtt[0].data, {
-    broker: "ace.internal", port: 1883, protocol: "5", username: "mesh_ace_hass", password: MINTED,
-    other_settings: { keepalive: 60, transport: "tcp", set_ca_cert: "off", set_client_cert: false },
-  });
-  assert.ok(marks.store.get("mqtt"));
-  assert.ok(![...marks.store.values()].some((v) => v.includes(MINTED)));
-
-  // Run again: nothing differs, the flow is opened to read and closed without submitting.
-  const before = f.submitted.length;
-  const again = await reconcileMqtt({ hass: f.hass, probe: takes(), marks }, mqttBinding(), MINTED);
-  assert.deepEqual(again, { what: "mqtt", result: "unchanged" });
-  assert.equal(f.submitted.length, before);
-  assert.match(f.calls.at(-1) ?? "", /^abort /);
-});
-
-test("mqtt: a new password alone is written (the digest tells)", async () => {
-  const f = fakeHass({ entries: { mqtt: [aceMqttEntry()] } });
-  const marks = memoryMarks();
-  await reconcileMqtt({ hass: f.hass, probe: takes(), marks }, mqttBinding(), MINTED);
-  const rotated: Probe = async () => ({ connack: 0, suback: 0 });
-  const out = await reconcileMqtt({ hass: f.hass, probe: rotated, marks }, mqttBinding(), "rotated");
-  assert.deepEqual(out, { what: "mqtt", result: "written", fields: ["password"] });
-  assert.equal(f.entries.mqtt[0].data.password, "rotated");
-});
-
-test("mqtt: Home Assistant's own connection test refusing saves nothing and fails loudly", async () => {
-  const f = fakeHass({ entries: { mqtt: [aceMqttEntry()] }, accepts: () => false });
-  const marks = memoryMarks();
-  const out = await reconcileMqtt({ hass: f.hass, probe: takes(), marks }, mqttBinding(), MINTED);
-  assert.equal(out.result, "refused");
-  assert.match((out as { problem: string }).problem, /cannot_connect.*unchanged/);
-  assert.equal(f.entries.mqtt[0].data.username, "luffy");
-  assert.equal(marks.store.size, 0);
-});
-
-test("mqtt: a fresh Home Assistant gets an entry; a grant without the discovery topics is warned about", async () => {
-  const f = fakeHass();
-  const out = await reconcileMqtt({ hass: f.hass, probe: takes(0x80), marks: memoryMarks() }, mqttBinding(), MINTED);
-  assert.equal(out.result, "written");
-  assert.match((out as { note?: string }).note ?? "", /may not subscribe to homeassistant\/#/);
-  assert.equal(f.entries.mqtt[0].data.broker, "ace.internal");
-});
-
-test("mqtt: two entries, or a binding without a port, are refused rather than guessed", async () => {
-  const f = fakeHass({ entries: { mqtt: [aceMqttEntry(), { ...aceMqttEntry(), entry_id: "other" }] } });
-  assert.equal((await reconcileMqtt({ hass: f.hass, probe: takes(), marks: memoryMarks() }, mqttBinding(), MINTED)).result, "refused");
-  const noPort = { ...mqttBinding(), serves: {} };
-  assert.match(((await reconcileMqtt({ hass: f.hass, probe: takes(), marks: memoryMarks() }, noPort, MINTED)) as { problem: string }).problem, /no usable port/);
-});
-
-// ---- Servarr ----
-
-const SONARR = APPS.find((a) => a.domain === "sonarr") as ServarrApp;
-const RADARR = APPS.find((a) => a.domain === "radarr") as ServarrApp;
-const KEY = "the-apps-own-key";
-const servarrBinding = (port: number, at = "ace.internal"): Binding => ({ provision: "sonarr-api", from: "ace", at, as: "mesh_ace_hass", serves: { scheme: "http", port, "url-base": "" } });
-
-/** One running Sonarr, answering on several addresses (127.0.0.1 and ace.internal are one host). */
-function apps(instances: Record<string, { startTime: string }>): Http & { asked: string[] } {
-  const asked: string[] = [];
-  return {
-    asked,
-    async fetch(url, init) {
-      asked.push(url);
-      const u = new URL(url);
-      const inst = instances[`${u.hostname}:${u.port}`];
-      if (!inst) throw new Error("connect ECONNREFUSED");
-      if (init?.headers?.["X-Api-Key"] !== KEY) return { status: 401, text: async () => "" };
-      return { status: 200, text: async () => JSON.stringify({ version: "4.0.15", appData: "/config", startTime: inst.startTime }) };
-    },
-  };
-}
-const oneSonarr = () => apps({ "ace.internal:8989": { startTime: "t1" }, "127.0.0.1:8989": { startTime: "t1" } });
-const sonarrEntry = (state = "loaded") => ({ entry_id: "5a1d", domain: "sonarr", state, data: { url: "http://127.0.0.1:8989", api_key: KEY } });
-
-test("servarr: the mesh's minted key is never written; the remedy names the accept", async () => {
-  const f = fakeHass({ entries: { sonarr: [sonarrEntry()] } });
-  const out = await reconcileApp({ hass: f.hass, http: oneSonarr() }, SONARR, servarrBinding(8989), "minted-by-the-mesh");
-  assert.equal(out.result, "refused");
-  assert.match((out as { problem: string }).problem, /secret accept <this node> home-assistant sonarr-api --provider ace/);
-  assert.deepEqual(f.calls, []);
-});
-
-test("servarr: ace's entry at 127.0.0.1 reaches the same Sonarr the mesh bound at ace.internal — left, and said", async () => {
-  const f = fakeHass({ entries: { sonarr: [sonarrEntry()] }, devices: [{ id: "d", config_entries: ["5a1d"], configuration_url: "http://127.0.0.1:8989" }] });
-  const out = await reconcileApp({ hass: f.hass, http: oneSonarr() }, SONARR, servarrBinding(8989), KEY);
-  assert.equal(out.result, "equivalent");
-  assert.equal(f.submitted.length, 0);
-});
-
-test("servarr: an entry already at the bound URL is unchanged", async () => {
-  const f = fakeHass({ entries: { sonarr: [sonarrEntry()] }, devices: [{ id: "d", config_entries: ["5a1d"], configuration_url: "http://ace.internal:8989" }] });
-  assert.deepEqual(await reconcileApp({ hass: f.hass, http: oneSonarr() }, SONARR, servarrBinding(8989), KEY), { what: "sonarr", result: "unchanged" });
-});
-
-test("servarr: a working entry that reaches a different app is refused, and nothing is removed", async () => {
-  const f = fakeHass({ entries: { sonarr: [sonarrEntry()] }, devices: [{ id: "d", config_entries: ["5a1d"], configuration_url: "http://127.0.0.1:8989" }] });
-  const two = apps({ "ace.internal:8989": { startTime: "t1" }, "127.0.0.1:8989": { startTime: "another" } });
-  const out = await reconcileApp({ hass: f.hass, http: two }, SONARR, servarrBinding(8989), KEY);
-  assert.equal(out.result, "refused");
-  assert.match((out as { problem: string }).problem, /never does/);
-  assert.equal(f.entries.sonarr.length, 1);
-});
-
-test("servarr: no entry — one is made at the bound URL through the user flow", async () => {
-  const f = fakeHass({ entries: {} });
-  const out = await reconcileApp({ hass: f.hass, http: oneSonarr() }, SONARR, servarrBinding(8989), KEY);
-  assert.deepEqual(out, { what: "sonarr", result: "written", fields: ["entry"] });
-  assert.deepEqual(f.submitted[0], { url: "http://ace.internal:8989", api_key: KEY, more_options: { verify_ssl: false } });
-});
-
-test("servarr: a reauth Home Assistant started is finished with the bound URL and key", async () => {
-  const entry = { ...sonarrEntry("setup_error"), domain: "radarr", entry_id: "1955" };
-  const f = fakeHass({
-    entries: { radarr: [entry] },
-    reauth: [{ flow_id: "r1", handler: "radarr", step_id: "reauth_confirm", context: { source: "reauth", entry_id: "1955" } }],
-  });
-  const radarr = apps({ "ace.internal:7878": { startTime: "t" } });
-  const out = await reconcileApp({ hass: f.hass, http: radarr }, RADARR, { ...servarrBinding(7878), provision: "radarr-api" }, KEY);
-  assert.deepEqual(out, { what: "radarr", result: "written", fields: ["api_key", "url"] });
-  assert.deepEqual(f.submitted[0], { url: "http://ace.internal:7878", api_key: KEY, verify_ssl: false });
-});
-
-test("form values: suggested first, then default, sections nested", () => {
-  assert.deepEqual(formValues(brokerForm({ broker: "b", port: 1, protocol: "5", username: "u", password: "p" })), {
-    broker: "b", port: 1, protocol: "5", username: "u", password: PWD_NOT_CHANGED,
-    other_settings: { keepalive: 60, transport: "tcp", set_ca_cert: "off", set_client_cert: false },
-  });
-  assert.ok(sameUrl("http://ace.internal:8989/", "http://ace.internal:8989"));
-  assert.ok(sameUrl("http://ACE.internal", "http://ace.internal:80"));
-  assert.ok(!sameUrl("http://127.0.0.1:8989", "http://ace.internal:8989"));
-});

modules/home-assistant/tsconfig.json

@@ -8,14 +8,5 @@
     "skipLibCheck": true,
     "noEmit": true
   },
-  "include": [
+  "include": ["client.ts", "index.ts", "tools/index.ts"]
-    "client.ts",
-    "index.ts",
-    "tools/index.ts",
-    "provisions/hass.ts",
-    "provisions/probe.ts",
-    "provisions/connections.ts",
-    "provisions/mesh.ts",
-    "provisions/index.ts"
-  ]
 }

modules/icecast/index.ts

@@ -23,7 +23,7 @@ async function pollMounts(): Promise<void> {
   if (primed) {
     for (const [mount, m] of now) {
       if (!live.has(mount)) {
-        await emit("stream.started", {
+        await emit("module.icecast.stream.started", {
           mount,
           name: m.name,
           description: m.description,
@@ -33,7 +33,7 @@ async function pollMounts(): Promise<void> {
     }
     for (const [mount, m] of live) {
       if (!now.has(mount)) {
-        await emit("stream.stopped", { mount, name: m.name });
+        await emit("module.icecast.stream.stopped", { mount, name: m.name });
       }
     }
   }

modules/icecast/module.json

@@ -1,97 +1,61 @@
 {
   "module": "icecast",
   "version": "1",
-  "requires": [
-    "route",
-    "secret"
-  ],
-  "contributes": {
-    "route": {
-      "label": "icecast",
-      "endpoint": "stream"
-    }
-  },
-  "binds": {
-    "route": "${dir:state}/route.json"
-  },
-  "secrets": {
-    "secret": {
-      "source": "${dir:state}/source.secret",
-      "admin": "${dir:state}/admin.secret",
-      "relay": "${dir:state}/relay.secret"
-    }
-  },
   "capabilities": [
     "container-runtime"
   ],
   "emits": [
-    "stream.started",
+    "module.icecast.stream.started",
-    "stream.stopped"
+    "module.icecast.stream.stopped"
   ],
   "own-secrets": {
-    "broker": "${dir:mesh-state}/broker"
+    "broker": "/var/lib/mesh/icecast/broker"
   },
   "listens": [
     {
-      "name": "stream",
       "port": 8000,
       "protocol": "tcp",
       "from": "mesh",
-      "why": "streams in from sources (HTTP PUT) and out to listeners, plus the status and admin pages; a public name is its route"
+      "why": "streams in from sources and out to listeners"
     }
   ],
   "resources": [
     {
       "id": "mesh-state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/mesh/icecast",
-      "place": "mesh"
+      "mode": "0700"
     },
     {
       "id": "state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/icecast-module",
-      "place": "."
+      "mode": "0700"
     },
     {
-      "id": "logs",
+      "id": "server-env",
-      "type": "directory",
-      "mode": "0700",
-      "owner": "100:101"
-    },
-    {
-      "id": "server-conf",
       "type": "file",
-      "path": "${dir:state}/icecast.xml",
+      "path": "/var/lib/icecast-module/server.env",
       "mode": "0600",
-      "content": "<icecast>\n    <!-- Written by the mesh (modules/icecast). Passwords arrive as secrets rendered into this file,\n         never as environment: the image's entrypoint seds ICECAST_* variables into the file only\n         when they are set, and none are. -->\n    <location>Earth</location>\n    <admin>icemaster@localhost</admin>\n    <limits>\n        <clients>100</clients>\n        <sources>2</sources>\n        <queue-size>524288</queue-size>\n        <client-timeout>30</client-timeout>\n        <header-timeout>15</header-timeout>\n        <source-timeout>10</source-timeout>\n        <burst-on-connect>1</burst-on-connect>\n        <burst-size>65535</burst-size>\n    </limits>\n    <authentication>\n        <source-password>${secret:source}</source-password>\n        <relay-password>${secret:relay}</relay-password>\n        <admin-user>admin</admin-user>\n        <admin-password>${secret:admin}</admin-password>\n    </authentication>\n    <!-- The name icecast writes into playlists (.m3u/.xspf: http://<hostname>:<port>/<mount>) and\n         would announce to YP (none configured). A machine's own name belongs to its assignment, and\n         an assignment merges only into JSON; this XML cannot take it, so the neutral default stays. -->\n    <hostname>localhost</hostname>\n    <listen-socket>\n        <port>8000</port>\n    </listen-socket>\n    <http-headers>\n        <header name=\"Access-Control-Allow-Origin\" value=\"*\" />\n    </http-headers>\n    <fileserve>1</fileserve>\n    <paths>\n        <basedir>/usr/share/icecast</basedir>\n        <logdir>/var/log/icecast</logdir>\n        <webroot>/usr/share/icecast/web</webroot>\n        <adminroot>/usr/share/icecast/admin</adminroot>\n        <alias source=\"/\" destination=\"/status.xsl\"/>\n    </paths>\n    <logging>\n        <accesslog>access.log</accesslog>\n        <errorlog>error.log</errorlog>\n        <loglevel>3</loglevel>\n        <logsize>10000</logsize>\n    </logging>\n    <security>\n        <chroot>0</chroot>\n        <!-- Starts as root, reads this 0600 root-owned file, then drops to the image's icecast user\n             (uid 100, group icecast 101) before serving. -->\n        <changeowner>\n            <user>icecast</user>\n            <group>icecast</group>\n        </changeowner>\n    </security>\n</icecast>\n"
+      "content": "ICECAST_SOURCE_PASSWORD=${secret:source}\nICECAST_ADMIN_PASSWORD=${secret:admin}\nICECAST_RELAY_PASSWORD=${secret:relay}\nICECAST_ADMIN_USERNAME=admin\n"
-    },
-    {
-      "id": "net",
-      "type": "network",
-      "name": "icecast"
     },
     {
       "id": "server",
       "type": "container",
       "name": "icecast",
       "image": "infiniteproject/icecast@sha256:cd506cf3dfe31ce05fd37d7e672dbd1213e7255cc93d28ecf5a3b547af4e162c",
-      "network": "icecast",
+      "env-file": [
+        "/var/lib/icecast-module/server.env"
+      ],
       "ports": [
         "8000"
       ],
-      "volumes": [
+      "secrets-in-environment": "the image seds ICECAST_*_PASSWORD into icecast.xml and has no _FILE; convertible by mounting a generated icecast.xml, not yet done"
-        "${dir:state}/icecast.xml:/etc/icecast.xml:ro",
-        "${dir:logs}:/var/log/icecast"
-      ],
-      "restart-on": [
-        "server-conf"
-      ]
     },
     {
       "id": "runtime-config",
       "type": "file",
-      "path": "${dir:mesh-state}/config.json",
+      "path": "/var/lib/mesh/icecast/config.json",
       "mode": "0600",
       "content": "{}\n",
       "merge": "json"
@@ -100,14 +64,14 @@
       "id": "runtime",
       "type": "container",
       "name": "mesh-icecast",
-      "network": "icecast",
+      "network": "host",
       "volumes": [
-        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "/var/lib/mesh/icecast/broker:/run/secrets/broker:ro",
-        "${dir:mesh-state}/config.json:/run/config/config.json:ro"
+        "/var/lib/mesh/icecast/config.json:/run/config/config.json:ro"
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_ICECAST_URL": "http://icecast:8000",
+        "MESH_ICECAST_URL": "http://127.0.0.1:8000",
         "MESH_ICECAST_CONFIG_FILE": "/run/config/config.json"
       },
       "restart-on": [
@@ -136,5 +100,15 @@
         "from": "Dockerfile"
       }
     ]
+  },
+  "requires": [
+    "secret"
+  ],
+  "secrets": {
+    "secret": {
+      "source": "/var/lib/icecast-module/source.secret",
+      "admin": "/var/lib/icecast-module/admin.secret",
+      "relay": "/var/lib/icecast-module/relay.secret"
+    }
   }
 }

modules/influxdb/Dockerfile

@@ -13,7 +13,7 @@ ARG RUNTIME_BASE
 FROM ${BUILD_BASE} AS build
 WORKDIR /app/modules/influxdb
 COPY . .
-RUN node /app/node_modules/typescript/bin/tsc client.ts grants.ts provisioner/index.ts tools/index.ts \
+RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
       --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 
 FROM ${RUNTIME_BASE}
@@ -21,4 +21,4 @@ COPY --from=build /app/modules/influxdb/dist /app/modules/influxdb/dist
 # Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
 # 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/influxdb/dist/tools/index.js,/app/modules/influxdb/dist/provisioner/index.js
+ENV MESH_TOOL_MODULES=/app/modules/influxdb/dist/tools/index.js

modules/influxdb/client.ts

@@ -17,25 +17,6 @@ export interface InfluxBucket {
   retentionSeconds?: number;
 }
 
-/** One permission of an authorization, as InfluxDB represents it: an action on a resource type,
- *  in one org, optionally narrowed to one resource by id (no id = every resource of that type). */
-export interface InfluxPermission {
-  action: "read" | "write";
-  resource: { type: string; orgID?: string; id?: string; name?: string; org?: string };
-}
-
-/** A v1-compatibility ("legacy") authorization: a username (InfluxDB calls it `token`) and a
- *  password the caller chooses, scoped by permissions. The one credential InfluxDB 2.x lets a
- *  caller set to a value it did not generate — which is what a mesh-minted password needs. */
-export interface LegacyAuthorization {
-  id: string;
-  token: string;
-  orgID: string;
-  status?: "active" | "inactive";
-  description?: string;
-  permissions: InfluxPermission[];
-}
-
 /** The settings-merged config the mesh delivers (novox/hq ADR 0046): { url, apiKey, token, password, user, ... }. */
 function meshConfig(file?: string): Record<string, string> {
   if (!file) return {};
@@ -43,20 +24,13 @@ function meshConfig(file?: string): Record<string, string> {
   catch { return {}; }
 }
 
-/** A secret delivered as a file, trimmed; undefined when there is none, so the caller can fall back. */
-function tokenFromFile(file?: string): string | undefined {
-  if (!file) return undefined;
-  try { return readFileSync(file, "utf8").trim() || undefined; }
-  catch { return undefined; }
-}
-
 export class InfluxDBClient {
   readonly baseUrl: string;
 
   constructor(
     url: string,
     private readonly token: string,
-    readonly org: string,
+    private readonly org: string,
   ) {
     this.baseUrl = url.replace(/\/$/, "");
   }
@@ -69,10 +43,8 @@ export class InfluxDBClient {
   static fromEnv(env: NodeJS.ProcessEnv = process.env): InfluxDBClient {
     const cfg = meshConfig(env.MESH_INFLUXDB_CONFIG_FILE);
     const url = cfg.url ?? env.MESH_INFLUXDB_URL ?? `http://127.0.0.1:${env.INFLUXDB_PORT ?? "8086"}`;
-    // The token reaches the process as a file (novox/hq ADR 0086); the environment variable stays
+    const token = cfg.token ?? env.MESH_INFLUXDB_TOKEN;
-    // only for a workstation running the tools by hand.
+    if (!token) throw new Error("no InfluxDB token — set MESH_INFLUXDB_TOKEN");
-    const token = cfg.token ?? tokenFromFile(env.MESH_INFLUXDB_TOKEN_FILE) ?? env.MESH_INFLUXDB_TOKEN;
-    if (!token) throw new Error("no InfluxDB token — set MESH_INFLUXDB_TOKEN_FILE");
     const org = cfg.org ?? env.MESH_INFLUXDB_ORG ?? "mesh";
     return new InfluxDBClient(url, token, org);
   }
@@ -89,93 +61,6 @@ export class InfluxDBClient {
     return res;
   }
 
-  /** Like request, but the answer is returned whatever its status, for the caller to read. */
-  private async raw(path: string, init?: RequestInit): Promise<Response> {
-    return fetch(`${this.baseUrl}${path}`, {
-      ...init,
-      headers: { Authorization: `Token ${this.token}`, ...(init?.headers ?? {}) },
-    });
-  }
-
-  private async send(path: string, method: string, body?: unknown): Promise<Response> {
-    return this.request(path, {
-      method,
-      headers: { "Content-Type": "application/json" },
-      body: body === undefined ? undefined : JSON.stringify(body),
-    });
-  }
-
-  /** The id of the org of this name, or undefined when there is none. */
-  async orgID(name: string): Promise<string | undefined> {
-    const res = await this.raw(`/api/v2/orgs?org=${encodeURIComponent(name)}`);
-    if (res.status === 404) return undefined;
-    if (!res.ok) throw new Error(`InfluxDB API /api/v2/orgs: ${res.status} ${await res.text()}`);
-    const body = (await res.json()) as { orgs?: { id: string; name: string }[] };
-    return body.orgs?.find((o) => o.name === name)?.id;
-  }
-
-  /** The bucket of exactly this name in the org, or undefined. */
-  async findBucket(orgID: string, name: string): Promise<InfluxBucket | undefined> {
-    const res = await this.raw(`/api/v2/buckets?orgID=${encodeURIComponent(orgID)}&name=${encodeURIComponent(name)}`);
-    if (res.status === 404) return undefined;
-    if (!res.ok) throw new Error(`InfluxDB API /api/v2/buckets: ${res.status} ${await res.text()}`);
-    const body = (await res.json()) as { buckets?: { id: string; name: string; orgID?: string }[] };
-    const b = body.buckets?.find((x) => x.name === name);
-    return b ? { id: b.id, name: b.name, orgID: b.orgID } : undefined;
-  }
-
-  /** Create a bucket that keeps its data for ever — retention is the operator's choice, never the mesh's. */
-  async createBucket(orgID: string, name: string, description: string): Promise<InfluxBucket> {
-    const b = (await (await this.send("/api/v2/buckets", "POST", {
-      orgID, name, description, retentionRules: [],
-    })).json()) as { id: string; name: string; orgID?: string };
-    return { id: b.id, name: b.name, orgID: b.orgID };
-  }
-
-  /** The v1 authorization whose username is exactly this, or undefined. */
-  async findLegacy(username: string): Promise<LegacyAuthorization | undefined> {
-    const path = `/private/legacy/authorizations?token=${encodeURIComponent(username)}`;
-    const res = await this.raw(path);
-    // InfluxDB answers a filter matching nothing with 404, not an empty list.
-    if (res.status === 404) return undefined;
-    if (!res.ok) throw new Error(`InfluxDB API ${path}: ${res.status} ${await res.text()}`);
-    const body = (await res.json()) as { authorizations?: LegacyAuthorization[] };
-    return body.authorizations?.find((a) => a.token === username);
-  }
-
-  async createLegacy(a: Omit<LegacyAuthorization, "id">): Promise<LegacyAuthorization> {
-    return (await (await this.send("/private/legacy/authorizations", "POST", a)).json()) as LegacyAuthorization;
-  }
-
-  /** Set a v1 authorization's password. InfluxDB keeps only a hash of it, so it can be set, never read. */
-  async setLegacyPassword(id: string, password: string): Promise<void> {
-    await this.send(`/private/legacy/authorizations/${encodeURIComponent(id)}/password`, "POST", { password });
-  }
-
-  async updateLegacy(id: string, patch: { status?: "active" | "inactive"; description?: string }): Promise<void> {
-    await this.send(`/private/legacy/authorizations/${encodeURIComponent(id)}`, "PATCH", patch);
-  }
-
-  async deleteLegacy(id: string): Promise<void> {
-    await this.send(`/private/legacy/authorizations/${encodeURIComponent(id)}`, "DELETE");
-  }
-
-  /**
-   * Whether this username and password sign in on the v1 API — the consumer's own view. Asked with
-   * a statement that reads nothing (`SHOW DATABASES` lists only what the credential may read), sent
-   * with Basic auth so the password is never in a URL. 401 is a wrong password or no such user;
-   * anything else that is not a server error means InfluxDB knew who was asking.
-   */
-  async legacySignsIn(username: string, password: string): Promise<boolean> {
-    const res = await fetch(`${this.baseUrl}/query?q=${encodeURIComponent("SHOW DATABASES")}`, {
-      headers: { Authorization: `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}` },
-    });
-    await res.arrayBuffer();
-    if (res.status === 401) return false;
-    if (res.status >= 500) throw new Error(`InfluxDB v1 /query: ${res.status}`);
-    return true;
-  }
-
   /** Server health — the one endpoint that needs no token, but we send it anyway. */
   async health(): Promise<InfluxHealth> {
     return (await (await this.request("/health")).json()) as InfluxHealth;

modules/influxdb/grants.ts

@@ -1,186 +0,0 @@
-// What the `influxdb-api` provision means in InfluxDB: one v1-compatibility authorization per
-// consumer, in the org this module serves, under the username and password the mesh gave both ends,
-// allowed exactly the access the consumer contributed. The provisioner (provisioner/index.ts) is the
-// sdk harness calling these; they are here, apart from it, so they can be exercised against a fake
-// InfluxDB without a broker or a contributions file.
-//
-// **Why a v1 authorization and not a v2 API token.** The mesh mints the consumer's password and
-// hands it to both ends (novox/hq ADR 0048); the provider sets it, and never hands one back. An
-// InfluxDB 2.x API token is generated by the server — `POST /api/v2/authorizations` ignores a token
-// the caller sends — so a token could only ever be the operator's to accept, one per pair, by hand.
-// A v1 authorization is a username and a password the caller chooses (8–72 characters; the mesh
-// mints 40), stored hashed, and it reads and writes through InfluxQL (`/query`) and line protocol
-// (`/write`), which every bucket answers under its own name as a database (InfluxDB maps each
-// bucket to a database of the same name by itself). That is what grafana's InfluxDB data source
-// speaks, and what Node-RED's influxdb nodes speak in their 1.x mode — so the mesh can make every
-// consumer's credential, rotate it and withdraw it, with no person in the loop.
-//
-// **What a consumer contributes.** `access`: "read" (the default), "write" or "read-write".
-// `buckets`: the buckets it may use, by name. A reader that names none may read every bucket of the
-// org — a dashboard is pointed at data, it does not own it. A writer must name its buckets: writing
-// everywhere, the org's system buckets included, is never what a consumer means. A named bucket
-// that does not exist is created, keeping its data for ever; the mesh never deletes a bucket.
-//
-// **Only what the mesh made is touched.** An authorization this module creates is named with the
-// mesh's identity prefix and its description starts with MARK. One with the same username that
-// lacks the mark is somebody else's: it is refused, never adopted, never updated, never deleted.
-// Every other authorization, token, user and bucket in the instance is left exactly as it was.
-
-import type { InfluxDBClient, InfluxPermission, LegacyAuthorization } from "./client.js";
-
-/** How a description marks an authorization as the mesh's own work. */
-export const MARK = "[mesh]";
-
-/** The prefix the mesh gives every consumer identity (novox/hq ADR 0049). */
-const IDENTITY_PREFIX = "mesh_";
-
-/** One consumer, as the harness hands it over. */
-export interface ApiGrant {
-  readonly as: string;
-  readonly password: string;
-  readonly values: Readonly<Record<string, unknown>>;
-  readonly consumer?: string;
-}
-
-export type Access = "read" | "write" | "read-write";
-
-/** What a contribution asks for, checked. Refused when it cannot be served as asked. */
-export function askedFor(values: Readonly<Record<string, unknown>>): { access: Access; buckets: string[] } {
-  const access = values.access ?? "read";
-  if (access !== "read" && access !== "write" && access !== "read-write") {
-    throw new Error(`contributes an access of ${JSON.stringify(access)} — it is "read", "write" or "read-write"`);
-  }
-  const raw = values.buckets ?? [];
-  if (!Array.isArray(raw) || raw.some((b) => typeof b !== "string" || b.trim() === "")) {
-    throw new Error(`contributes buckets of ${JSON.stringify(raw)} — a list of bucket names`);
-  }
-  const buckets = [...new Set((raw as string[]).map((b) => b.trim()))].sort();
-  if (access !== "read" && buckets.length === 0) {
-    throw new Error(`asks to write and names no bucket (\`buckets\`) — a writer names what it writes to`);
-  }
-  if (buckets.some((b) => b.startsWith("_"))) {
-    throw new Error(`names a system bucket (${buckets.filter((b) => b.startsWith("_")).join(", ")}) — those are InfluxDB's own`);
-  }
-  return { access: access as Access, buckets };
-}
-
-/** The permissions a grant resolves to, given each named bucket's id. */
-export function permissionsFor(orgID: string, access: Access, bucketIDs: string[]): InfluxPermission[] {
-  const actions: ("read" | "write")[] = access === "read-write" ? ["read", "write"] : [access];
-  const out: InfluxPermission[] = [];
-  for (const action of actions) {
-    if (bucketIDs.length === 0) {
-      out.push({ action, resource: { type: "buckets", orgID } });
-      continue;
-    }
-    for (const id of bucketIDs) out.push({ action, resource: { type: "buckets", orgID, id } });
-  }
-  return out;
-}
-
-/** A permission as a comparable string: what InfluxDB answers carries names and links besides. */
-function key(p: InfluxPermission): string {
-  return `${p.action}:${p.resource.type}:${p.resource.orgID ?? ""}:${p.resource.id ?? "*"}`;
-}
-
-function samePermissions(a: readonly InfluxPermission[], b: readonly InfluxPermission[]): boolean {
-  const x = a.map(key).sort();
-  const y = b.map(key).sort();
-  return x.length === y.length && x.every((v, i) => v === y[i]);
-}
-
-export function marked(a: Pick<LegacyAuthorization, "token" | "description">): boolean {
-  return a.token.startsWith(IDENTITY_PREFIX) && (a.description ?? "").startsWith(MARK);
-}
-
-function describe(g: ApiGrant): string {
-  return `${MARK} made by the mesh for ${g.consumer ? `a module on ${g.consumer}` : "a consumer"} — do not edit; it is reset`;
-}
-
-export class ApiGrants {
-  constructor(private readonly influx: InfluxDBClient, readonly org: string) {}
-
-  private async orgID(): Promise<string> {
-    const id = await this.influx.orgID(this.org);
-    if (!id) throw new Error(`InfluxDB has no org ${JSON.stringify(this.org)} — the org this module serves must exist`);
-    return id;
-  }
-
-  /** The ids of the named buckets, creating any that are missing when `create` says so. Undefined
-   *  when one is missing and may not be created (a read-only question). */
-  private async bucketIDs(orgID: string, names: string[], create: ApiGrant | undefined): Promise<string[] | undefined> {
-    const ids: string[] = [];
-    for (const name of names) {
-      let b = await this.influx.findBucket(orgID, name);
-      if (!b) {
-        if (!create) return undefined;
-        b = await this.influx.createBucket(orgID, name, `${MARK} made by the mesh for ${create.as}; the mesh never deletes it`);
-      }
-      ids.push(b.id);
-    }
-    return ids.sort();
-  }
-
-  /** Create the consumer's authorization, or bring the mesh's existing one back to what the grant
-   *  says. Idempotent: a second apply of the same grant changes nothing beyond re-asserting the
-   *  password, which InfluxDB can be told but never asked. */
-  async ensure(g: ApiGrant): Promise<"created" | "updated" | "unchanged"> {
-    if (!g.as.startsWith(IDENTITY_PREFIX)) {
-      throw new Error(`${g.as} is not a mesh identity — the mesh names every consumer ${IDENTITY_PREFIX}<node>_<module>`);
-    }
-    const { access, buckets } = askedFor(g.values);
-    const orgID = await this.orgID();
-    const found = await this.influx.findLegacy(g.as);
-    if (found && !marked(found)) {
-      throw new Error(
-        `InfluxDB already has a v1 authorization ${g.as} the mesh did not make — left alone; ` +
-          `delete it if the mesh should own that name`);
-    }
-    const want = permissionsFor(orgID, access, (await this.bucketIDs(orgID, buckets, g))!);
-
-    if (found && found.orgID === orgID && samePermissions(found.permissions, want)) {
-      // Only what differs is written. The password cannot be read back, so it is tried instead.
-      let changed = false;
-      if (found.status === "inactive") {
-        await this.influx.updateLegacy(found.id, { status: "active" });
-        changed = true;
-      }
-      if (!(await this.influx.legacySignsIn(g.as, g.password))) {
-        await this.influx.setLegacyPassword(found.id, g.password);
-        changed = true;
-      }
-      return changed ? "updated" : "unchanged";
-    }
-    // InfluxDB cannot change an authorization's permissions in place, so the mesh's own is made
-    // again. Only ever one the mesh made: a foreign one was refused above.
-    if (found) await this.influx.deleteLegacy(found.id);
-    const made = await this.influx.createLegacy({
-      token: g.as, orgID, status: "active", description: describe(g), permissions: want,
-    });
-    await this.influx.setLegacyPassword(made.id, g.password);
-    return found ? "updated" : "created";
-  }
-
-  /** Whether InfluxDB still holds this consumer's authorization exactly as the grant says: present,
-   *  the mesh's, active, allowed what was asked and nothing more, and signing in with the mesh's
-   *  password. Reads only — a missing bucket is "not held", never created here. */
-  async holds(g: ApiGrant): Promise<boolean> {
-    const { access, buckets } = askedFor(g.values);
-    const orgID = await this.influx.orgID(this.org);
-    if (!orgID) return false;
-    const found = await this.influx.findLegacy(g.as);
-    if (!found || !marked(found) || found.status === "inactive" || found.orgID !== orgID) return false;
-    const ids = await this.bucketIDs(orgID, buckets, undefined);
-    if (!ids || !samePermissions(found.permissions, permissionsFor(orgID, access, ids))) return false;
-    return this.influx.legacySignsIn(g.as, g.password);
-  }
-
-  /** Withdraw a consumer's authorization — only one the mesh made. Its buckets and their data stay. */
-  async remove(as: string): Promise<"removed" | "absent" | "not ours"> {
-    const found = await this.influx.findLegacy(as);
-    if (!found) return "absent";
-    if (!marked(found)) return "not ours";
-    await this.influx.deleteLegacy(found.id);
-    return "removed";
-  }
-}

modules/influxdb/module.json

@@ -1,102 +1,75 @@
 {
   "module": "influxdb",
   "version": "1",
-  "provides": [
-    {
-      "name": "influxdb-api",
-      "scope": "mesh"
-    }
-  ],
   "capabilities": [
     "container-runtime"
   ],
   "own-secrets": {
-    "broker": "${dir:mesh-state}/broker",
+    "broker": "/var/lib/mesh/influxdb/broker"
-    "admin": "${dir:state}/admin.secret",
-    "admin-token": "${dir:state}/admin-token.secret"
   },
   "listens": [
     {
-      "name": "api",
       "port": 8086,
       "protocol": "tcp",
       "from": "mesh",
-      "why": "queries, writes and the web UI, over http; consumers granted influxdb-api sign in with the mesh's credential, and a name is a route grant"
+      "why": "queries and writes, over http"
     }
   ],
-  "serves": {
-    "influxdb-api": {
-      "scheme": "http",
-      "port": 8086,
-      "org": "mesh",
-      "bucket": "default"
-    }
-  },
-  "receives": {
-    "influxdb-api": "${dir:grants}/mesh.json"
-  },
-  "grants": {
-    "influxdb-api": "${dir:grants}"
-  },
   "resources": [
     {
       "id": "mesh-state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/mesh/influxdb",
-      "place": "mesh"
+      "mode": "0700"
     },
     {
       "id": "state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/influxdb-module",
-      "place": "."
+      "mode": "0700"
+    },
+    {
+      "id": "server-env",
+      "type": "file",
+      "path": "/var/lib/influxdb-module/server.env",
+      "mode": "0600",
+      "content": "DOCKER_INFLUXDB_INIT_MODE=setup\nDOCKER_INFLUXDB_INIT_USERNAME=admin\nDOCKER_INFLUXDB_INIT_PASSWORD=${secret:admin}\nDOCKER_INFLUXDB_INIT_ADMIN_TOKEN=${secret:admin-token}\nDOCKER_INFLUXDB_INIT_ORG=mesh\nDOCKER_INFLUXDB_INIT_BUCKET=default\n"
     },
     {
       "id": "data",
       "type": "directory",
+      "path": "/services/influxdb/data",
       "mode": "0700",
       "owner": "1000:1000"
     },
     {
       "id": "config",
       "type": "directory",
+      "path": "/services/influxdb/config",
       "mode": "0700",
       "owner": "1000:1000"
     },
-    {
-      "id": "grants",
-      "type": "directory",
-      "mode": "0700"
-    },
-    {
-      "id": "server-env",
-      "type": "file",
-      "path": "${dir:state}/server.env",
-      "mode": "0600",
-      "content": "DOCKER_INFLUXDB_INIT_MODE=setup\nDOCKER_INFLUXDB_INIT_USERNAME=admin\nDOCKER_INFLUXDB_INIT_PASSWORD_FILE=/run/secrets/admin\nDOCKER_INFLUXDB_INIT_ADMIN_TOKEN_FILE=/run/secrets/admin-token\nDOCKER_INFLUXDB_INIT_ORG=mesh\nDOCKER_INFLUXDB_INIT_BUCKET=default\n"
-    },
     {
       "id": "server",
       "type": "container",
       "name": "influxdb",
       "image": "influxdb@sha256:f75e48af0598e8aec7986e991a848d19a119101a7d563a2e5db1dfaac9c45daa",
       "env-file": [
-        "${dir:state}/server.env"
+        "/var/lib/influxdb-module/server.env"
       ],
       "ports": [
         "8086"
       ],
       "volumes": [
-        "${dir:data}:/var/lib/influxdb2",
+        "/services/influxdb/data:/var/lib/influxdb2",
-        "${dir:config}:/etc/influxdb2",
+        "/services/influxdb/config:/etc/influxdb2"
-        "${dir:state}/admin.secret:/run/secrets/admin:ro",
+      ],
-        "${dir:state}/admin-token.secret:/run/secrets/admin-token:ro"
+      "secrets-in-environment": "the image honours DOCKER_INFLUXDB_INIT_PASSWORD_FILE and _ADMIN_TOKEN_FILE; convertible, awaiting a bed that proves it"
-      ]
     },
     {
       "id": "runtime-config",
       "type": "file",
-      "path": "${dir:mesh-state}/config.json",
+      "path": "/var/lib/mesh/influxdb/config.json",
       "mode": "0600",
       "content": "{}\n",
       "merge": "json"
@@ -107,17 +80,15 @@
       "name": "mesh-influxdb",
       "network": "host",
       "volumes": [
-        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "/var/lib/mesh/influxdb/broker:/run/secrets/broker:ro",
-        "${dir:mesh-state}/config.json:/run/config/config.json:ro",
+        "/var/lib/mesh/influxdb/config.json:/run/config/config.json:ro",
-        "${dir:state}/admin-token.secret:/run/secrets/admin-token:ro",
+        "/services/influxdb/config:/var/lib/influxdb/config:ro"
-        "${dir:grants}:${dir:grants}:ro"
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_INFLUXDB_URL": "http://127.0.0.1:${port:8086}",
+        "MESH_INFLUXDB_URL": "http://127.0.0.1:8086",
         "MESH_INFLUXDB_CONFIG_FILE": "/run/config/config.json",
-        "MESH_INFLUXDB_TOKEN_FILE": "/run/secrets/admin-token",
+        "MESH_INFLUXDB_CONFIG_DIR": "/var/lib/influxdb/config"
-        "MESH_RECEIVES": "${dir:grants}/mesh.json"
       },
       "restart-on": [
         "runtime-config"
@@ -125,15 +96,6 @@
       "artifact": "runtime"
     }
   ],
-  "requires": [
-    "route"
-  ],
-  "contributes": {
-    "route": {
-      "label": "influxdb",
-      "endpoint": "api"
-    }
-  },
   "build": {
     "on": [
       {
@@ -154,5 +116,14 @@
         "from": "Dockerfile"
       }
     ]
+  },
+  "requires": [
+    "secret"
+  ],
+  "secrets": {
+    "secret": {
+      "admin": "/var/lib/influxdb-module/admin.secret",
+      "admin-token": "/var/lib/influxdb-module/admin-token.secret"
+    }
   }
 }

modules/influxdb/package.json

@@ -1,14 +1,9 @@
 {
   "name": "@novox/module-influxdb",
   "version": "0.1.0",
-  "description": "influxdb — time-series database; provides the mesh influxdb-api interface. Its API client, provisioner and tools live here (novox/hq ADR 0039).",
+  "description": "influxdb — time-series database. Its API client and tools live here (novox/hq ADR 0039).",
   "type": "module",
   "private": true,
-  "scripts": {
-    "build": "tsc client.ts grants.ts provisioner/index.ts tools/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist",
-    "typecheck": "tsc -p tsconfig.json",
-    "test": "npm run build && node --test --experimental-strip-types 'test/*.test.ts'"
-  },
   "dependencies": {
     "@novox/mesh-sdk": "^0.1.0"
   },

modules/influxdb/provisioner/index.ts

@@ -1,54 +0,0 @@
-// influxdb's provisioner — the adapter that makes influxdb a provider of the mesh `influxdb-api`
-// interface. The reconcile loop, the contributions file and reading the mesh's minted secret are the
-// sdk harness's; this writes only the per-service half: how InfluxDB creates, checks and removes a
-// consumer's credential (novox/hq ADR 0039/0040/0048). What that credential is, and why it is a v1
-// authorization, is in ../grants.ts.
-//
-// The `influxdb-api` interface: a consumer reaches `${bound:influxdb-api:scheme}://…:at:…:port`,
-// signs in as `${bound:influxdb-api:as}` with the password the mesh minted for the pair, and reads
-// or writes the org's buckets as databases of the same name — `${bound:influxdb-api:bucket}` being
-// the one this instance serves by default. The org and the default bucket are the assignment's
-// settings, which reach both what is served and this module's config.json, so the org a consumer is
-// told and the org its credential is made in cannot disagree.
-
-import { runProvisioner, type Provision } from "@novox/mesh-sdk/provisioner";
-import { InfluxDBClient } from "../client.js";
-import { ApiGrants } from "../grants.js";
-
-let grants: ApiGrants | undefined;
-try {
-  const influx = InfluxDBClient.fromEnv();
-  grants = new ApiGrants(influx, influx.org);
-} catch (err) {
-  // No admin token: nothing can be provisioned, and the tools loaded beside this must still serve.
-  console.error(`[provisioner:influxdb-api] not started: ${err instanceof Error ? err.message : err}`);
-}
-
-if (grants) serve(grants);
-
-function serve(grants: ApiGrants): void {
-  runProvisioner("influxdb-api", {
-    async create(p: Provision): Promise<void> {
-      const done = await grants.ensure(p);
-      if (done !== "unchanged") {
-        console.log(`[provisioner:influxdb-api] ${done} v1 authorization ${p.as} in org ${grants.org}`);
-      }
-    },
-
-    async remove(p: { as: string }): Promise<void> {
-      const done = await grants.remove(p.as);
-      if (done === "not ours") {
-        console.error(`[provisioner:influxdb-api] ${p.as}: an authorization of that name exists that the mesh did not make — left alone`);
-      } else if (done === "removed") {
-        console.log(`[provisioner:influxdb-api] removed v1 authorization ${p.as}; its buckets and their data stay`);
-      }
-    },
-
-    // Asked every minute by the harness: whether InfluxDB still holds this consumer's authorization
-    // exactly as the mesh gave it, so one deleted, disabled or re-passworded behind the mesh's back is
-    // made whole again (hq issue 120).
-    async holds(p: Provision): Promise<boolean> {
-      return grants.holds(p);
-    },
-  });
-}

modules/influxdb/test/grants.test.ts

@@ -1,246 +0,0 @@
-// What holds influxdb to the `influxdb-api` provision (grants.ts): one v1 authorization per consumer,
-// under the username and password the mesh gave, allowed only what the consumer contributed; made
-// once and brought back on every apply; buckets created when missing and never deleted; and an
-// authorization the mesh did not make — same name or not — never adopted, changed or deleted.
-//
-// InfluxDB is a fake: the routes the module touches, answering with the status codes and shapes
-// InfluxDB 2.9 gives (a filter matching nothing is a 404, a password outside 8–72 characters a 400,
-// an inactive authorization or a wrong password a 401 on /query). Run against the compiled module
-// (npm test builds first), the way the runtime loads it.
-
-import { test, after, beforeEach } from "node:test";
-import assert from "node:assert/strict";
-import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
-
-import { InfluxDBClient } from "../dist/client.js";
-import { ApiGrants, MARK, askedFor, marked } from "../dist/grants.js";
-
-type Rec = Record<string, any>;
-
-const ADMIN = "operator-token";
-const orgs = new Map<string, string>([["zurag", "org1"]]);
-let buckets: Rec[] = [];
-let auths: Rec[] = [];
-let calls: string[] = [];
-let seq = 0;
-
-function body(req: IncomingMessage): Promise<any> {
-  return new Promise((resolve) => {
-    let raw = "";
-    req.on("data", (c) => (raw += c));
-    req.on("end", () => resolve(raw ? JSON.parse(raw) : undefined));
-  });
-}
-
-function send(res: ServerResponse, status: number, value?: unknown): void {
-  res.writeHead(status, { "Content-Type": "application/json" });
-  res.end(value === undefined ? "" : JSON.stringify(value));
-}
-
-const server = createServer(async (req, res) => {
-  const url = new URL(req.url!, "http://fake");
-  const p = url.pathname;
-  calls.push(`${req.method} ${p}`);
-  if (p === "/query") {
-    const basic = (req.headers.authorization ?? "").replace(/^Basic /, "");
-    const [u, pw] = Buffer.from(basic, "base64").toString().split(":");
-    const a = auths.find((x) => x.token === u);
-    if (!a || a.status !== "active" || a.password === undefined || a.password !== pw) {
-      return send(res, 401, { code: "unauthorized", message: "Unauthorized" });
-    }
-    return send(res, 200, { results: [{ statement_id: 0 }] });
-  }
-  if (req.headers.authorization !== `Token ${ADMIN}`) return send(res, 401, { code: "unauthorized" });
-  if (p === "/api/v2/orgs") {
-    const id = orgs.get(url.searchParams.get("org") ?? "");
-    if (!id) return send(res, 404, { code: "not found", message: "organization name not found" });
-    return send(res, 200, { orgs: [{ id, name: url.searchParams.get("org") }] });
-  }
-  if (p === "/api/v2/buckets" && req.method === "GET") {
-    const found = buckets.filter((b) => b.orgID === url.searchParams.get("orgID") && b.name === url.searchParams.get("name"));
-    if (found.length === 0) return send(res, 404, { code: "not found", message: "bucket not found" });
-    return send(res, 200, { buckets: found });
-  }
-  if (p === "/api/v2/buckets" && req.method === "POST") {
-    const b = { ...(await body(req)), id: `b${++seq}` };
-    buckets.push(b);
-    return send(res, 201, b);
-  }
-  if (p === "/private/legacy/authorizations" && req.method === "GET") {
-    const found = auths.filter((a) => a.token === url.searchParams.get("token"));
-    if (found.length === 0) return send(res, 404, { code: "not found", message: "authorization not found" });
-    // Never answers with the password: InfluxDB keeps only its hash.
-    return send(res, 200, { authorizations: found.map(({ password, ...a }) => ({ ...a, links: {} })) });
-  }
-  if (p === "/private/legacy/authorizations" && req.method === "POST") {
-    const a = await body(req);
-    if (auths.some((x) => x.token === a.token)) return send(res, 409, { code: "conflict", message: "token already exists" });
-    const made = { ...a, id: `a${++seq}`, status: a.status ?? "active" };
-    auths.push(made);
-    return send(res, 201, made);
-  }
-  const m = /^\/private\/legacy\/authorizations\/([^/]+)(\/password)?$/.exec(p);
-  const a = m && auths.find((x) => x.id === m[1]);
-  if (!a) return send(res, 404, { code: "not found" });
-  if (m![2] && req.method === "POST") {
-    const { password } = await body(req);
-    if (typeof password !== "string" || password.length < 8 || password.length > 72) {
-      return send(res, 400, { code: "invalid", message: "passwords must be between 8 and 72 characters long" });
-    }
-    a.password = password;
-    return send(res, 204);
-  }
-  if (req.method === "PATCH") {
-    Object.assign(a, await body(req));
-    return send(res, 200, a);
-  }
-  if (req.method === "DELETE") {
-    auths = auths.filter((x) => x !== a);
-    return send(res, 204);
-  }
-  send(res, 405);
-});
-await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
-after(() => server.close());
-const port = (server.address() as { port: number }).port;
-
-const grants = new ApiGrants(new InfluxDBClient(`http://127.0.0.1:${port}`, ADMIN, "zurag"), "zurag");
-
-const PW = "mesh-minted-password-of-forty-characters";
-
-/** Grafana on ace, as the mesh hands it to the provisioner. */
-function grafana(password = PW, values: Record<string, unknown> = { access: "read" }) {
-  return { as: "mesh_ace_grafana", password, consumer: "ace", values };
-}
-/** Node-RED on ace: writes one bucket. */
-function nodered(password = PW, values: Record<string, unknown> = { access: "write", buckets: ["zurag"] }) {
-  return { as: "mesh_ace_nodered", password, consumer: "ace", values };
-}
-
-function only(token: string): Rec {
-  const found = auths.filter((a) => a.token === token);
-  assert.equal(found.length, 1, `exactly one authorization ${token}, found ${found.length}`);
-  return found[0];
-}
-
-function perms(a: Rec): string[] {
-  return a.permissions.map((p: Rec) => `${p.action}:${p.resource.type}:${p.resource.id ?? "*"}`).sort();
-}
-
-beforeEach(() => {
-  buckets = [{ id: "zb", orgID: "org1", name: "zurag" }];
-  auths = [];
-  calls = [];
-});
-
-test("what a contribution may ask for, and what is refused", () => {
-  assert.deepEqual(askedFor({}), { access: "read", buckets: [] });
-  assert.deepEqual(askedFor({ access: "read-write", buckets: ["b", "a", "a"] }), { access: "read-write", buckets: ["a", "b"] });
-  assert.throws(() => askedFor({ access: "admin" }), /access/);
-  assert.throws(() => askedFor({ access: "write" }), /names no bucket/);
-  assert.throws(() => askedFor({ buckets: "zurag" }), /list of bucket names/);
-  assert.throws(() => askedFor({ access: "write", buckets: ["_monitoring"] }), /system bucket/);
-});
-
-test("a reader is given one authorization, reading every bucket of the org, under the mesh's password", async () => {
-  assert.equal(await grants.ensure(grafana()), "created");
-  const a = only("mesh_ace_grafana");
-  assert.equal(a.orgID, "org1");
-  assert.equal(a.status, "active");
-  assert.ok(a.description.startsWith(MARK));
-  assert.deepEqual(perms(a), ["read:buckets:*"]);
-  assert.equal(a.password, PW);
-  assert.equal(await grants.holds(grafana()), true);
-});
-
-test("a writer is allowed its own buckets only, and a missing one is made — never deleted", async () => {
-  assert.equal(await grants.ensure(nodered(PW, { access: "write", buckets: ["zurag", "printer"] })), "created");
-  const made = buckets.find((b) => b.name === "printer");
-  assert.ok(made, "the missing bucket was created");
-  assert.deepEqual(made!.retentionRules, [], "kept for ever: retention is the operator's choice");
-  assert.deepEqual(perms(only("mesh_ace_nodered")), [`write:buckets:${made!.id}`, "write:buckets:zb"]);
-  assert.equal(await grants.remove("mesh_ace_nodered"), "removed");
-  assert.equal(buckets.length, 2, "withdrawing the consumer leaves every bucket and its data");
-});
-
-test("applying the same grant again writes nothing", async () => {
-  await grants.ensure(grafana());
-  calls = [];
-  assert.equal(await grants.ensure(grafana()), "unchanged");
-  assert.ok(calls.every((c) => c.startsWith("GET")), `only reads: ${calls.join(", ")}`);
-  only("mesh_ace_grafana");
-});
-
-test("a rotated password is set in place; a changed access remakes only the mesh's own", async () => {
-  await grants.ensure(nodered());
-  const id = only("mesh_ace_nodered").id;
-  assert.equal(await grants.holds(nodered("rotated-password-0123456789")), false);
-  assert.equal(await grants.ensure(nodered("rotated-password-0123456789")), "updated");
-  assert.equal(only("mesh_ace_nodered").id, id, "updated, not replaced");
-  assert.equal(await grants.holds(nodered("rotated-password-0123456789")), true);
-
-  await grants.ensure(nodered(PW, { access: "read-write", buckets: ["zurag"] }));
-  assert.deepEqual(perms(only("mesh_ace_nodered")), ["read:buckets:zb", "write:buckets:zb"]);
-  assert.equal(await grants.holds(nodered(PW, { access: "read-write", buckets: ["zurag"] })), true);
-});
-
-test("an authorization disabled, re-passworded or deleted behind the mesh's back is not held, and is made whole", async () => {
-  await grants.ensure(grafana());
-  only("mesh_ace_grafana").status = "inactive";
-  assert.equal(await grants.holds(grafana()), false);
-  assert.equal(await grants.ensure(grafana()), "updated");
-  assert.equal(await grants.holds(grafana()), true);
-
-  only("mesh_ace_grafana").password = "somebody-else-set-this";
-  assert.equal(await grants.holds(grafana()), false);
-  await grants.ensure(grafana());
-  assert.equal(await grants.holds(grafana()), true);
-
-  auths = [];
-  assert.equal(await grants.holds(grafana()), false);
-  assert.equal(await grants.ensure(grafana()), "created");
-});
-
-test("holds only reads, and a bucket gone missing is not held rather than made", async () => {
-  await grants.ensure(nodered());
-  buckets = [];
-  calls = [];
-  assert.equal(await grants.holds(nodered()), false);
-  assert.ok(calls.every((c) => c.startsWith("GET")), `only reads: ${calls.join(", ")}`);
-  assert.equal(buckets.length, 0);
-});
-
-test("an authorization of the same name the mesh did not make is refused, and left exactly as it was", async () => {
-  auths = [{ id: "theirs", token: "mesh_ace_grafana", orgID: "org1", status: "active", description: "hand-made",
-    permissions: [{ action: "write", resource: { type: "buckets", orgID: "org1" } }], password: "their-password" }];
-  const before = JSON.stringify(auths);
-  await assert.rejects(grants.ensure(grafana()), /did not make/);
-  assert.equal(JSON.stringify(auths), before);
-  assert.ok(calls.every((c) => c.startsWith("GET")), `only reads: ${calls.join(", ")}`);
-  assert.equal(await grants.holds(grafana()), false);
-  assert.equal(await grants.remove("mesh_ace_grafana"), "not ours");
-  assert.equal(auths.length, 1, "never deleted");
-});
-
-test("the predecessor's own v1 users and tokens are never touched", async () => {
-  auths = [{ id: "hal", token: "grafana", orgID: "org1", status: "active", description: "",
-    permissions: [{ action: "read", resource: { type: "buckets", orgID: "org1" } }], password: "old-password" }];
-  await grants.ensure(grafana());
-  assert.equal(auths.find((a) => a.id === "hal")!.password, "old-password");
-  assert.equal(await grants.remove("grafana"), "not ours");
-  assert.equal(marked({ token: "grafana", description: `${MARK} x` }), false, "the mark needs the mesh's name too");
-});
-
-test("an org the instance does not have, or a non-mesh name, makes nothing", async () => {
-  const elsewhere = new ApiGrants(new InfluxDBClient(`http://127.0.0.1:${port}`, ADMIN, "nope"), "nope");
-  await assert.rejects(elsewhere.ensure(grafana()), /no org "nope"/);
-  await assert.rejects(grants.ensure({ ...grafana(), as: "grafana" }), /not a mesh identity/);
-  assert.equal(auths.length, 0);
-});
-
-test("a withdrawn consumer's authorization is removed, and an absent one is not an error", async () => {
-  await grants.ensure(grafana());
-  assert.equal(await grants.remove("mesh_ace_grafana"), "removed");
-  assert.equal(auths.length, 0);
-  assert.equal(await grants.remove("mesh_ace_grafana"), "absent");
-});

modules/influxdb/tsconfig.json

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

modules/invoicing/module.json

@@ -14,36 +14,31 @@
     "mongodb-database": {
       "name": "invoicing"
     },
-    "route": {
+    "s3-bucket": {
-      "site": {
+      "bucket": "invoicing"
-        "label": "invoicing",
-        "endpoint": "web"
     },
-      "api": {
+    "route": {
-        "label": "invoicing-api",
+      "label": "invoicing",
-        "endpoint": "api"
+      "port": 80
-      }
     }
   },
   "binds": {
-    "mongodb-database": "${dir:state}/database.json",
+    "mongodb-database": "/var/lib/invoicing/database.json",
-    "s3-bucket": "${dir:state}/store.json",
+    "s3-bucket": "/var/lib/invoicing/store.json",
-    "route": "${dir:state}/route.json"
+    "route": "/var/lib/invoicing/route.json"
   },
   "secrets": {
-    "mongodb-database": "${dir:state}/database.secret",
+    "mongodb-database": "/var/lib/invoicing/database.secret",
-    "s3-bucket": "${dir:state}/store.secret"
+    "s3-bucket": "/var/lib/invoicing/store.secret"
   },
   "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",
@@ -54,21 +49,21 @@
     {
       "id": "mesh-state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/mesh/invoicing",
-      "place": "mesh"
+      "mode": "0700"
     },
     {
       "id": "state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/invoicing",
-      "place": "."
+      "mode": "0700"
     },
     {
       "id": "api-env",
       "type": "file",
-      "path": "${dir:state}/api.env",
+      "path": "/var/lib/invoicing/api.env",
       "mode": "0600",
-      "content": "NODE_ENV=production\nPORT=9000\nMONGO_URL=mongodb://${bound:mongodb-database:as}:${secret:mongodb-database}@${bound:mongodb-database:at}:${bound:mongodb-database:port}/${bound:mongodb-database:as}?authSource=${bound:mongodb-database:as}\nMONGO_DB=${bound:mongodb-database:as}\nMINIO_BUCKET=mesh-novox-invoice\nMINIO_ENDPOINT=${bound:s3-bucket:at}\nMINIO_PORT=${bound:s3-bucket:port}\nMINIO_ACCESSKEY=${bound:s3-bucket:as}\nMINIO_SECRET=${secret:s3-bucket}\n"
+      "content": "NODE_ENV=production\nPORT=9000\nMONGO_URL=mongodb://${bound:mongodb-database:as}:${secret:mongodb-database}@${bound:mongodb-database:at}:${bound:mongodb-database:port}/invoicing?authSource=admin\nMINIO_BUCKET=invoicing\nMINIO_ENDPOINT=${bound:s3-bucket:at}\nMINIO_PORT=${bound:s3-bucket:port}\nMINIO_ACCESSKEY=${bound:s3-bucket:as}\nMINIO_SECRET=${secret:s3-bucket}\n"
     },
     {
       "id": "net",
@@ -87,10 +82,7 @@
       },
       "ports": [
         "80"
-      ],
+      ]
-      "names-on-purpose": {
-        "registry-api.novox.be": "built outside the mesh, from the application's own repository, and pulled from the registry that built it; moves when that repository is a build source on the git seat (novox/hq ADR 0155, issue 122)"
-      }
     },
     {
       "id": "api",
@@ -103,15 +95,12 @@
         "GID": "2201"
       },
       "env-file": [
-        "${dir:state}/api.env"
+        "/var/lib/invoicing/api.env"
       ],
       "ports": [
         "9000"
       ],
-      "secrets-in-environment": "the application's own code reads MONGO_URL and MINIO_SECRET from the environment (invoicing-app server/src/config.js); converting is that repository's change",
+      "secrets-in-environment": "the application's own code reads MONGO_URL and MINIO_SECRET from the environment (invoicing-app server/src/config.js); converting is that repository's change"
-      "names-on-purpose": {
-        "registry-api.novox.be": "built outside the mesh, from the application's own repository, and pulled from the registry that built it; moves when that repository is a build source on the git seat (novox/hq ADR 0155, issue 122)"
-      }
     }
   ]
 }

modules/jackett/Dockerfile

@@ -0,0 +1,24 @@
+# jackett'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 in
+# the base images, published like any other artifact — which 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 (novox/hq issue 044): the image this is COMPILED in and the
+# image it RUNS in — the second must not carry a compiler. Declared in module.json's `build.on`.
+ARG BUILD_BASE
+ARG RUNTIME_BASE
+
+FROM ${BUILD_BASE} AS build
+WORKDIR /app/modules/jackett
+COPY . .
+RUN node /app/node_modules/typescript/bin/tsc client.ts tools/index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+COPY --from=build /app/modules/jackett/dist /app/modules/jackett/dist
+# Every serve-time entrypoint, loaded by the runtime in serve mode: tools and events serve, and a
+# 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/jackett/dist/tools/index.js

modules/jackett/client.ts

@@ -0,0 +1,99 @@
+// The Jackett API client — jackett's own code, living in the module (novox/hq ADR 0039). Jackett is
+// an indexer proxy: it normalises many torrent trackers behind one Torznab surface. This client
+// talks its /api/v2.0 REST API, and only jackett's tools import it.
+
+import { readFileSync } from "node:fs";
+
+export interface JackettIndexer {
+  id: string;
+  name: string;
+  type: string; // "public" | "private" | "semi-public"
+  configured: boolean;
+  siteLink?: string;
+  lastError?: string;
+}
+
+export interface JackettResult {
+  title: string;
+  tracker: string;
+  category?: string;
+  size: number;
+  seeders?: number;
+  peers?: number;
+  publishDate?: string;
+  link?: string;
+}
+
+/** The settings-merged config the mesh delivers (novox/hq ADR 0046): { url, apiKey, token, password, user, ... }. */
+function meshConfig(file?: string): Record<string, string> {
+  if (!file) return {};
+  try { return JSON.parse(readFileSync(file, "utf8")) as Record<string, string>; }
+  catch { return {}; }
+}
+
+export class JackettClient {
+  readonly baseUrl: string;
+
+  constructor(
+    url: string,
+    private readonly apiKey: string,
+  ) {
+    this.baseUrl = url.replace(/\/$/, "");
+  }
+
+  /**
+   * Build from the module's resolved environment. Jackett's REST API is keyed, so both the URL and
+   * the key must be present — without them there is nothing to talk to, so this throws and the
+   * module contributes no tools rather than failing half-configured.
+   */
+  static fromEnv(env: NodeJS.ProcessEnv = process.env): JackettClient {
+    const cfg = meshConfig(env.MESH_JACKETT_CONFIG_FILE);
+    const url = cfg.url ?? env.MESH_JACKETT_URL;
+    const apiKey = cfg.apiKey ?? env.MESH_JACKETT_API_KEY;
+    if (!url) throw new Error("no Jackett URL — set MESH_JACKETT_URL");
+    if (!apiKey) throw new Error("no Jackett API key — set MESH_JACKETT_API_KEY");
+    return new JackettClient(url, apiKey);
+  }
+
+  private async get(path: string, params: Record<string, string> = {}): Promise<any> {
+    const url = new URL(`${this.baseUrl}${path}`);
+    url.searchParams.set("apikey", this.apiKey);
+    for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
+    const res = await fetch(url.toString(), { headers: { Accept: "application/json" } });
+    if (!res.ok) throw new Error(`Jackett API ${path}: ${res.status} ${await res.text()}`);
+    return res.json();
+  }
+
+  /** The configured indexers Jackett proxies. `configured=false` also lists the ones not set up. */
+  async getIndexers(configuredOnly = true): Promise<JackettIndexer[]> {
+    const raw = await this.get("/api/v2.0/indexers", { configured: configuredOnly ? "true" : "false" });
+    const list = Array.isArray(raw) ? raw : [];
+    return list.map((i: any) => ({
+      id: i.id,
+      name: i.name,
+      type: i.type,
+      configured: i.configured ?? false,
+      siteLink: i.site_link,
+      lastError: i.last_error || undefined,
+    }));
+  }
+
+  /**
+   * A Torznab search across one indexer, or the "all" aggregate. Jackett returns a normalised JSON
+   * result set regardless of the underlying tracker, which is the whole point of the proxy.
+   */
+  async search(query: string, indexer = "all", limit = 25): Promise<JackettResult[]> {
+    const raw = await this.get(`/api/v2.0/indexers/${encodeURIComponent(indexer)}/results`, { Query: query });
+    const results = Array.isArray(raw?.Results) ? raw.Results : [];
+    return results.slice(0, limit).map((r: any) => ({
+      title: r.Title,
+      tracker: r.Tracker ?? r.TrackerId ?? "unknown",
+      category: Array.isArray(r.CategoryDesc) ? r.CategoryDesc.join(", ") : r.CategoryDesc,
+      size: r.Size ?? 0,
+      seeders: r.Seeders,
+      peers: r.Peers,
+      publishDate: r.PublishDate,
+      link: r.Link ?? r.Details,
+    }));
+  }
+}

modules/jackett/module.json

@@ -0,0 +1,112 @@
+{
+  "module": "jackett",
+  "version": "1",
+  "capabilities": [
+    "container-runtime"
+  ],
+  "listens": [
+    {
+      "port": 9117,
+      "protocol": "tcp",
+      "from": "mesh",
+      "why": "the indexer proxy"
+    }
+  ],
+  "resources": [
+    {
+      "id": "mesh-state",
+      "type": "directory",
+      "path": "/var/lib/mesh/jackett",
+      "mode": "0700"
+    },
+    {
+      "id": "config",
+      "type": "directory",
+      "path": "/services/jackett/config",
+      "mode": "0700",
+      "owner": "1000:1000"
+    },
+    {
+      "id": "server",
+      "type": "container",
+      "name": "jackett",
+      "image": "lscr.io/linuxserver/jackett@sha256:fd72d42b731ebf750b5de9711127251cf3b3f609419c32083ea8b3b3ee840b77",
+      "env": {
+        "PUID": "1000",
+        "PGID": "1000",
+        "TZ": "Etc/UTC"
+      },
+      "ports": [
+        "9117"
+      ],
+      "volumes": [
+        "/services/jackett/config:/config"
+      ]
+    },
+    {
+      "id": "runtime-config",
+      "type": "file",
+      "path": "/var/lib/mesh/jackett/config.json",
+      "mode": "0600",
+      "content": "{}\n",
+      "merge": "json"
+    },
+    {
+      "id": "runtime",
+      "type": "container",
+      "name": "mesh-jackett",
+      "network": "host",
+      "volumes": [
+        "/var/lib/mesh/jackett/broker:/run/secrets/broker:ro",
+        "/var/lib/mesh/jackett/config.json:/run/config/config.json:ro",
+        "/services/jackett/config:/var/lib/jackett/config:ro"
+      ],
+      "env": {
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_JACKETT_URL": "http://127.0.0.1:9117",
+        "MESH_JACKETT_CONFIG_FILE": "/run/config/config.json",
+        "MESH_JACKETT_CONFIG_DIR": "/var/lib/jackett/config"
+      },
+      "restart-on": [
+        "runtime-config"
+      ],
+      "artifact": "runtime"
+    }
+  ],
+  "own-secrets": {
+    "broker": "/var/lib/mesh/jackett/broker"
+  },
+  "requires": [
+    "route"
+  ],
+  "contributes": {
+    "route": {
+      "label": "indexers",
+      "port": 9117
+    }
+  },
+  "binds": {
+    "route": "/var/lib/mesh/jackett/route.json"
+  },
+  "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/jackett/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@novox/module-jackett",
+  "version": "0.1.0",
+  "description": "jackett — indexer proxy. Its API client and tools live here (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/jackett/tools/index.ts

@@ -0,0 +1,48 @@
+// jackett's tools — its own code (novox/hq ADR 0039), importing jackett's client. Jackett has
+// nothing worth watching (an indexer proxy answers queries; it has no timeline of its own), so it
+// is a tools-only module: no events entrypoint, no broker. What is useful is asking it things.
+
+import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
+import { JackettClient } from "../client.js";
+
+export function getJackettTools(jackett: JackettClient): ToolDefinition[] {
+  return [
+    {
+      name: "jackett_indexers",
+      description: "List the indexers Jackett proxies, with their type and any last error.",
+      input: { all: { type: "boolean", description: "include indexers not yet configured (default false)" } },
+      run: async (args) => {
+        const indexers = await jackett.getIndexers(!args.all);
+        return { count: indexers.length, indexers };
+      },
+    },
+    {
+      name: "jackett_search",
+      description: "Torznab search across Jackett's indexers, returning normalised torrent results.",
+      input: {
+        query: { type: "string", description: "the search query" },
+        indexer: { type: "string", description: 'an indexer id, or "all" to aggregate (default "all")' },
+        limit: { type: "number", description: "max results (default 25)" },
+      },
+      run: async (args) => {
+        const query = String(args.query);
+        const results = await jackett.search(
+          query,
+          args.indexer ? String(args.indexer) : "all",
+          args.limit ? Number(args.limit) : 25,
+        );
+        return { query, count: results.length, results };
+      },
+    },
+  ];
+}
+
+// Only exposed when Jackett is configured; otherwise jackett contributes no tools rather than
+// failing the whole runtime.
+registerModuleTools("jackett", (env) => {
+  try {
+    return getJackettTools(JackettClient.fromEnv(env));
+  } catch {
+    return [];
+  }
+});

modules/jackett/tsconfig.json

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

modules/jira/module.json

@@ -2,26 +2,26 @@
   "module": "jira",
   "version": "1",
   "own-secrets": {
-    "token": "${dir:state}/token",
+    "token": "/var/lib/jira/token",
-    "broker": "${dir:mesh-state}/broker"
+    "broker": "/var/lib/mesh/jira/broker"
   },
   "resources": [
     {
       "id": "mesh-state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/mesh/jira",
-      "place": "mesh"
+      "mode": "0700"
     },
     {
       "id": "state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/jira",
-      "place": "."
+      "mode": "0700"
     },
     {
       "id": "config",
       "type": "file",
-      "path": "${dir:state}/config.json",
+      "path": "/var/lib/jira/config.json",
       "merge": "json",
       "content": "{}",
       "mode": "0600"
@@ -32,9 +32,9 @@
       "name": "mesh-runtime-jira",
       "network": "host",
       "volumes": [
-        "${dir:state}/config.json:/run/config/config.json:ro",
+        "/var/lib/jira/config.json:/run/config/config.json:ro",
-        "${dir:state}/token:/run/secrets/token:ro",
+        "/var/lib/jira/token:/run/secrets/token:ro",
-        "${dir:mesh-state}/broker:/run/secrets/broker:ro"
+        "/var/lib/mesh/jira/broker:/run/secrets/broker:ro"
       ],
       "env": {
         "MESH_JIRA_TOKEN_FILE": "/run/secrets/token",

modules/keycloak/Dockerfile

@@ -17,7 +17,7 @@ FROM ${BUILD_BASE} AS build
 # resolved away.
 WORKDIR /app/modules/keycloak
 COPY . .
-RUN node /app/node_modules/typescript/bin/tsc client.ts oidc.ts index.ts provisioner/index.ts tools/index.ts \
+RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts \
       --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
 
 FROM ${RUNTIME_BASE}
@@ -27,4 +27,4 @@ COPY --from=build /app/modules/keycloak/dist /app/modules/keycloak/dist
 # the convention novox/hq issues 060/061 settled. A container that instead ran only its
 # provisioner (`run`) served no tools and emitted no events; a container that named no command
 # ran no provisioner at all.
-ENV MESH_TOOL_MODULES=/app/modules/keycloak/dist/index.js,/app/modules/keycloak/dist/tools/index.js,/app/modules/keycloak/dist/provisioner/index.js
+ENV MESH_TOOL_MODULES=/app/modules/keycloak/dist/index.js,/app/modules/keycloak/dist/tools/index.js

modules/keycloak/client.ts

@@ -12,45 +12,6 @@ function meshConfig(file?: string): Record<string, string> {
   catch { return {}; }
 }
 
-/** A secret file's value, trailing newline trimmed; undefined when unset or unreadable. */
-function secretFile(file?: string): string | undefined {
-  if (!file) return undefined;
-  try { return readFileSync(file, "utf8").replace(/\n$/, "") || undefined; }
-  catch { return undefined; }
-}
-
-/** A client as the admin API represents it — only the fields this module reads or writes are typed;
- *  the rest travel through untouched, so an update never drops what somebody else set. */
-export interface ClientRepresentation {
-  id?: string;
-  clientId: string;
-  name?: string;
-  enabled?: boolean;
-  protocol?: string;
-  publicClient?: boolean;
-  clientAuthenticatorType?: string;
-  secret?: string;
-  rootUrl?: string;
-  baseUrl?: string;
-  redirectUris?: string[];
-  webOrigins?: string[];
-  standardFlowEnabled?: boolean;
-  implicitFlowEnabled?: boolean;
-  directAccessGrantsEnabled?: boolean;
-  serviceAccountsEnabled?: boolean;
-  attributes?: Record<string, string>;
-  protocolMappers?: ProtocolMapperRepresentation[];
-  [other: string]: unknown;
-}
-
-export interface ProtocolMapperRepresentation {
-  id?: string;
-  name: string;
-  protocol: string;
-  protocolMapper: string;
-  config: Record<string, string>;
-}
-
 export class KeycloakClient {
   readonly baseUrl: string;
   readonly defaultRealm: string;
@@ -79,13 +40,8 @@ export class KeycloakClient {
     const cfg = meshConfig(env.MESH_KEYCLOAK_CONFIG_FILE);
     const url = cfg.url ?? env.MESH_KEYCLOAK_URL ?? `http://127.0.0.1:${env.KEYCLOAK_PORT ?? "8080"}`;
     const adminUser = cfg.user ?? env.MESH_KEYCLOAK_ADMIN ?? env.KEYCLOAK_ADMIN ?? "admin";
-    // The admin password reaches the runtime as a file (novox/hq ADR 0086): the module's own `admin`
+    const adminPass = cfg.password ?? env.MESH_KEYCLOAK_PASSWORD ?? env.KEYCLOAK_ADMIN_PASSWORD;
-    // secret, mounted read-only. The environment forms stay for a co-located server that has them.
+    if (!adminPass) throw new Error("no Keycloak admin password — set MESH_KEYCLOAK_PASSWORD");
-    const adminPass = cfg.password ?? secretFile(env.MESH_KEYCLOAK_PASSWORD_FILE)
-      ?? env.MESH_KEYCLOAK_PASSWORD ?? env.KEYCLOAK_ADMIN_PASSWORD;
-    if (!adminPass) {
-      throw new Error("no Keycloak admin password — set MESH_KEYCLOAK_PASSWORD_FILE (or MESH_KEYCLOAK_PASSWORD)");
-    }
     const realm = cfg.realm ?? env.MESH_KEYCLOAK_REALM ?? "master";
     return new KeycloakClient(url, adminUser, adminPass, realm);
   }
@@ -203,50 +159,6 @@ export class KeycloakClient {
     return client.id as string;
   }
 
-  /** The one client with exactly this clientId, or undefined. The admin API's `clientId` filter is an
-   *  exact match unless `search=true` is asked for. */
-  async findClient(realm: string, clientId: string): Promise<ClientRepresentation | undefined> {
-    const found = await this.request<ClientRepresentation[]>(
-      `/${realm}/clients?clientId=${encodeURIComponent(clientId)}`);
-    return found.find((c) => c.clientId === clientId);
-  }
-
-  async createClientFrom(realm: string, rep: ClientRepresentation): Promise<void> {
-    await this.request(`/${realm}/clients`, { method: "POST", body: JSON.stringify(rep) });
-  }
-
-  /** Replace a client's representation, addressed by its internal id. */
-  async updateClient(realm: string, id: string, rep: ClientRepresentation): Promise<void> {
-    await this.request(`/${realm}/clients/${id}`, { method: "PUT", body: JSON.stringify(rep) });
-  }
-
-  async deleteClientById(realm: string, id: string): Promise<void> {
-    await this.request(`/${realm}/clients/${id}`, { method: "DELETE" });
-  }
-
-  async clientSecretById(realm: string, id: string): Promise<string | undefined> {
-    const result = await this.request<{ value?: string }>(`/${realm}/clients/${id}/client-secret`);
-    return result.value;
-  }
-
-  async listClientMappers(realm: string, id: string): Promise<ProtocolMapperRepresentation[]> {
-    return this.request(`/${realm}/clients/${id}/protocol-mappers/models`);
-  }
-
-  async addClientMapper(realm: string, id: string, mapper: ProtocolMapperRepresentation): Promise<void> {
-    await this.request(`/${realm}/clients/${id}/protocol-mappers/models`, {
-      method: "POST",
-      body: JSON.stringify(mapper),
-    });
-  }
-
-  async updateClientMapper(realm: string, id: string, mapper: ProtocolMapperRepresentation): Promise<void> {
-    await this.request(`/${realm}/clients/${id}/protocol-mappers/models/${mapper.id}`, {
-      method: "PUT",
-      body: JSON.stringify(mapper),
-    });
-  }
-
   async deleteClient(realm: string, clientId: string): Promise<void> {
     await this.request(`/${realm}/clients/${await this.resolveClientId(realm, clientId)}`, { method: "DELETE" });
   }

modules/keycloak/index.ts

@@ -28,17 +28,17 @@ async function announce(type: string, body: Record<string, unknown>): Promise<vo
 
 export const events = {
   userCreated: (realm: string, username: string, email?: string) =>
-    announce("user.created", { realm, username, ...(email ? { email } : {}) }),
+    announce("module.keycloak.user.created", { realm, username, ...(email ? { email } : {}) }),
   userDeleted: (realm: string, userId: string) =>
-    announce("user.deleted", { realm, userId }),
+    announce("module.keycloak.user.deleted", { realm, userId }),
   passwordReset: (realm: string, userId: string) =>
-    announce("password.reset", { realm, userId }),
+    announce("module.keycloak.password.reset", { realm, userId }),
   clientCreated: (realm: string, clientId: string, name?: string) =>
-    announce("client.created", { realm, clientId, ...(name ? { name } : {}) }),
+    announce("module.keycloak.client.created", { realm, clientId, ...(name ? { name } : {}) }),
   groupCreated: (realm: string, name: string) =>
-    announce("group.created", { realm, name }),
+    announce("module.keycloak.group.created", { realm, name }),
   roleCreated: (realm: string, name: string) =>
-    announce("role.created", { realm, name }),
+    announce("module.keycloak.role.created", { realm, name }),
 };
 
 console.log("[keycloak] event surface ready — identity, client, group and role changes are announced");

modules/keycloak/module.json

@@ -1,12 +1,6 @@
 {
   "module": "keycloak",
   "version": "1",
-  "provides": [
-    {
-      "name": "oidc-client",
-      "scope": "mesh"
-    }
-  ],
   "requires": [
     "postgres-database",
     "route"
@@ -17,83 +11,63 @@
     },
     "route": {
       "label": "keycloak",
-      "endpoint": "web"
+      "port": 8080
     }
   },
   "binds": {
-    "postgres-database": "${dir:state}/database.json",
+    "postgres-database": "/var/lib/keycloak/database.json",
-    "route": "${dir:state}/route.json"
+    "route": "/var/lib/keycloak/route.json"
   },
   "secrets": {
-    "postgres-database": "${dir:state}/database.secret"
+    "postgres-database": "/var/lib/keycloak/database.secret"
   },
   "capabilities": [
     "container-runtime"
   ],
   "emits": [
-    "user.created",
+    "module.keycloak.user.created",
-    "user.deleted",
+    "module.keycloak.user.deleted",
-    "password.reset",
+    "module.keycloak.password.reset",
-    "client.created",
+    "module.keycloak.client.created",
-    "group.created",
+    "module.keycloak.group.created",
-    "role.created"
+    "module.keycloak.role.created"
   ],
   "listens": [
     {
-      "name": "web",
       "port": 8080,
       "protocol": "tcp",
       "from": "mesh",
       "why": "anything the mesh runs that authenticates a person"
     }
   ],
-  "serves": {
-    "oidc-client": {
-      "authorization-path": "/protocol/openid-connect/auth",
-      "token-path": "/protocol/openid-connect/token",
-      "userinfo-path": "/protocol/openid-connect/userinfo",
-      "issuer": "${setting:issuer}"
-    }
-  },
-  "receives": {
-    "oidc-client": "${dir:grants}/mesh.json"
-  },
-  "grants": {
-    "oidc-client": "${dir:grants}"
-  },
   "own-secrets": {
-    "admin": "${dir:state}/admin.secret",
+    "admin": "/var/lib/keycloak/admin.secret",
-    "broker": "${dir:mesh-state}/broker"
+    "broker": "/var/lib/mesh/keycloak/broker"
   },
   "resources": [
     {
       "id": "mesh-state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/mesh/keycloak",
-      "place": "mesh"
+      "mode": "0700"
     },
     {
       "id": "state",
       "type": "directory",
-      "mode": "0700",
+      "path": "/var/lib/keycloak",
-      "place": "."
-    },
-    {
-      "id": "grants",
-      "type": "directory",
       "mode": "0700"
     },
     {
       "id": "admin-env",
       "type": "file",
-      "path": "${dir:state}/admin.env",
+      "path": "/var/lib/keycloak/admin.env",
       "mode": "0600",
       "content": "KEYCLOAK_ADMIN=admin\nKEYCLOAK_ADMIN_PASSWORD=${secret:admin}\n"
     },
     {
       "id": "database-env",
       "type": "file",
-      "path": "${dir:state}/database.env",
+      "path": "/var/lib/keycloak/database.env",
       "mode": "0600",
       "content": "KC_DB_URL=jdbc:postgresql://${bound:postgres-database:at}:${bound:postgres-database:port}/${bound:postgres-database:as}\nKC_DB_USERNAME=${bound:postgres-database:as}\nKC_DB_PASSWORD=${secret:postgres-database}\n"
     },
@@ -102,13 +76,6 @@
       "type": "network",
       "name": "keycloak"
     },
-    {
-      "id": "hostname",
-      "type": "file",
-      "path": "${dir:state}/hostname.env",
-      "mode": "0644",
-      "content": "KC_HOSTNAME=https://${bound:route:name}\n"
-    },
     {
       "id": "server",
       "type": "container",
@@ -121,26 +88,21 @@
       "env": {
         "KC_DB": "postgres",
         "KC_HTTP_ENABLED": "true",
-        "KC_HEALTH_ENABLED": "true",
+        "KC_HEALTH_ENABLED": "true"
-        "KC_PROXY_HEADERS": "xforwarded"
       },
       "env-file": [
-        "${dir:state}/admin.env",
+        "/var/lib/keycloak/admin.env",
-        "${dir:state}/database.env",
+        "/var/lib/keycloak/database.env"
-        "${dir:state}/hostname.env"
       ],
       "ports": [
         "8080"
       ],
-      "secrets-in-environment": "KC_DB_PASSWORD is convertible through a generated keycloak.conf (db-password=); KEYCLOAK_ADMIN_PASSWORD is env-only before Keycloak 26; not yet converted",
+      "secrets-in-environment": "KC_DB_PASSWORD is convertible through a generated keycloak.conf (db-password=); KEYCLOAK_ADMIN_PASSWORD is env-only before Keycloak 26; not yet converted"
-      "restart-on": [
-        "hostname"
-      ]
     },
     {
       "id": "runtime-config",
       "type": "file",
-      "path": "${dir:mesh-state}/config.json",
+      "path": "/var/lib/mesh/keycloak/config.json",
       "mode": "0600",
       "content": "{}\n",
       "merge": "json"
@@ -151,17 +113,13 @@
       "name": "mesh-keycloak",
       "network": "host",
       "volumes": [
-        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "/var/lib/mesh/keycloak/broker:/run/secrets/broker:ro",
-        "${dir:mesh-state}/config.json:/run/config/config.json:ro",
+        "/var/lib/mesh/keycloak/config.json:/run/config/config.json:ro"
-        "${dir:state}/admin.secret:/run/secrets/admin:ro",
-        "${dir:grants}:${dir:grants}:ro"
       ],
       "env": {
         "MESH_BROKER_FILE": "/run/secrets/broker",
-        "MESH_KEYCLOAK_URL": "http://127.0.0.1:${port:8080}",
+        "MESH_KEYCLOAK_URL": "http://127.0.0.1:8080",
-        "MESH_KEYCLOAK_CONFIG_FILE": "/run/config/config.json",
+        "MESH_KEYCLOAK_CONFIG_FILE": "/run/config/config.json"
-        "MESH_KEYCLOAK_PASSWORD_FILE": "/run/secrets/admin",
-        "MESH_RECEIVES": "${dir:grants}/mesh.json"
       },
       "restart-on": [
         "runtime-config"

modules/keycloak/oidc.ts

@@ -1,185 +0,0 @@
-// What the `oidc-client` provision means in Keycloak: one confidential OpenID Connect client per
-// consumer, in the realm this module serves, under the name and secret the mesh gave both ends.
-// The provisioner (provisioner/index.ts) is the sdk harness calling these; they are here, apart from
-// it, so they can be exercised against a fake admin API without a broker or a contributions file.
-//
-// **The client id and the secret are the mesh's, not Keycloak's (novox/hq ADR 0048).** The mesh
-// derives the consumer's identity (`as`, e.g. `mesh_ace_grafana`) and hands it to both ends — the
-// consumer names it as its client id through `${bound:oidc-client:as}` — and mints the secret, which
-// this sets as the client's secret. Keycloak generates neither.
-//
-// **Where the consumer's browser comes back to is the consumer's to say.** Its contribution carries
-// `callback` (a path, e.g. `/login/generic_oauth`) and the `label`/`endpoint` of the endpoint it is
-// reached on; the mesh composes that endpoint's names into `name` (public) and `internal-name`
-// (private network) exactly as it does for a route (novox/hq ADR 0056, 0138), so the redirect URI
-// registered here is built from the same names the proxy serves the consumer under.
-//
-// **Only what the mesh made is touched.** A client this module creates carries the attribute
-// `mesh.provisioned=true`, and its id starts with the mesh's own prefix. A client with the same id
-// that lacks the mark is somebody else's: it is refused, never adopted, never updated, never deleted.
-
-import type { ClientRepresentation, KeycloakClient, ProtocolMapperRepresentation } from "./client.js";
-
-/** The attribute marking a client as the mesh's own work. */
-export const MARK = "mesh.provisioned";
-
-/** The mapper every mesh client carries: realm roles as a flat `roles` claim in the id token, the
- *  access token and userinfo — what a consumer maps its own roles from (grafana's role path reads
- *  `roles[*]`), and what the predecessor added to its hand-made clients by hand. */
-export const ROLES_MAPPER: ProtocolMapperRepresentation = {
-  name: "realm roles",
-  protocol: "openid-connect",
-  protocolMapper: "oidc-usermodel-realm-role-mapper",
-  config: {
-    "claim.name": "roles",
-    "jsonType.label": "String",
-    multivalued: "true",
-    "id.token.claim": "true",
-    "access.token.claim": "true",
-    "userinfo.token.claim": "true",
-  },
-};
-
-/** One consumer, as the harness hands it over. */
-export interface OidcGrant {
-  readonly as: string;
-  readonly password: string;
-  readonly values: Readonly<Record<string, unknown>>;
-  readonly consumer?: string;
-}
-
-/** The realm named by an issuer URL — `https://id.example/realms/Novox` is realm `Novox`. The issuer is
- *  the one value an assignment sets (it is also what consumers are served), so the realm is read
- *  out of it rather than set a second time where the two could disagree. */
-export function realmOf(issuer: string): string {
-  let path: string;
-  try {
-    path = new URL(issuer).pathname;
-  } catch {
-    throw new Error(`the issuer ${JSON.stringify(issuer)} is not a URL`);
-  }
-  const m = /\/realms\/([^/]+)\/?$/.exec(path);
-  if (!m) throw new Error(`the issuer ${JSON.stringify(issuer)} does not end in /realms/<realm>`);
-  return decodeURIComponent(m[1]);
-}
-
-/** The redirect URIs a consumer's contribution asks for: its callback under each name the mesh
- *  composed for its endpoint. Refused when there is nothing to register — a client that accepts no
- *  redirect is a client nobody can log in through, and one that accepts any is worse. */
-export function redirectsOf(values: Readonly<Record<string, unknown>>): { root: string; redirects: string[] } {
-  const callback = values.callback;
-  if (typeof callback !== "string" || !callback.startsWith("/")) {
-    throw new Error(`contributes no callback path (\`callback\`, starting with "/"): ${JSON.stringify(callback)}`);
-  }
-  const names: string[] = [];
-  for (const key of ["name", "internal-name"]) {
-    const n = values[key];
-    if (typeof n === "string" && n.trim() !== "" && !names.includes(n.trim())) names.push(n.trim());
-  }
-  if (names.length === 0) {
-    throw new Error("has no name the mesh composed (`name` / `internal-name`) — contribute a `label` and the `endpoint` it is reached on");
-  }
-  return { root: `https://${names[0]}`, redirects: names.map((n) => `https://${n}${callback}`) };
-}
-
-/** The fields the mesh owns on a client it made. Everything else on the client is left as found. */
-function wanted(g: OidcGrant): ClientRepresentation {
-  const { root, redirects } = redirectsOf(g.values);
-  return {
-    clientId: g.as,
-    name: g.as,
-    description: `made by the mesh for ${g.consumer ? `a module on ${g.consumer}` : "a consumer"} — do not edit; it is reset`,
-    enabled: true,
-    protocol: "openid-connect",
-    publicClient: false,
-    clientAuthenticatorType: "client-secret",
-    secret: g.password,
-    rootUrl: root,
-    baseUrl: root,
-    redirectUris: redirects,
-    standardFlowEnabled: true,
-    implicitFlowEnabled: false,
-    directAccessGrantsEnabled: false,
-    serviceAccountsEnabled: false,
-  };
-}
-
-function sameSet(a: readonly string[] | undefined, b: readonly string[]): boolean {
-  const x = [...(a ?? [])].sort();
-  const y = [...b].sort();
-  return x.length === y.length && x.every((v, i) => v === y[i]);
-}
-
-function marked(c: ClientRepresentation): boolean {
-  return c.attributes?.[MARK] === "true";
-}
-
-export class OidcClients {
-  constructor(private readonly kc: KeycloakClient, readonly realm: string) {}
-
-  /** Create the consumer's client, or bring the mesh's existing one back to what the grant says.
-   *  Returns whether it was newly created. Idempotent: applying the same grant twice changes nothing
-   *  the second time beyond re-asserting it. */
-  async ensure(g: OidcGrant): Promise<"created" | "updated"> {
-    const want = wanted(g);
-    const found = await this.kc.findClient(this.realm, g.as);
-    if (found && !marked(found)) {
-      throw new Error(
-        `realm ${this.realm} already has a client ${g.as} the mesh did not make — left alone; ` +
-          `delete or rename it if the mesh should own that id`);
-    }
-    if (!found) {
-      await this.kc.createClientFrom(this.realm, {
-        ...want,
-        attributes: { [MARK]: "true" },
-        protocolMappers: [ROLES_MAPPER],
-      });
-      return "created";
-    }
-    // Overlay what the mesh owns on what is there, so a field Keycloak added or an operator set on a
-    // field the mesh does not own survives the update.
-    await this.kc.updateClient(this.realm, found.id!, {
-      ...found,
-      ...want,
-      attributes: { ...(found.attributes ?? {}), [MARK]: "true" },
-    });
-    await this.ensureMapper(found.id!);
-    return "updated";
-  }
-
-  private async ensureMapper(id: string): Promise<void> {
-    const mappers = await this.kc.listClientMappers(this.realm, id);
-    const have = mappers.find((m) => m.name === ROLES_MAPPER.name);
-    if (!have) {
-      await this.kc.addClientMapper(this.realm, id, ROLES_MAPPER);
-      return;
-    }
-    const drifted =
-      have.protocolMapper !== ROLES_MAPPER.protocolMapper ||
-      Object.entries(ROLES_MAPPER.config).some(([k, v]) => have.config?.[k] !== v);
-    if (drifted) {
-      await this.kc.updateClientMapper(this.realm, id, { ...ROLES_MAPPER, id: have.id });
-    }
-  }
-
-  /** Whether Keycloak still holds this consumer's client exactly as the grant says: present, the
-   *  mesh's, enabled, confidential, with the mesh's secret and the redirects asked for. Reads only. */
-  async holds(g: OidcGrant): Promise<boolean> {
-    const want = wanted(g);
-    const found = await this.kc.findClient(this.realm, g.as);
-    if (!found || !marked(found) || found.enabled === false || found.publicClient) return false;
-    if (!sameSet(found.redirectUris, want.redirectUris!)) return false;
-    const mappers = await this.kc.listClientMappers(this.realm, found.id!);
-    if (!mappers.some((m) => m.name === ROLES_MAPPER.name)) return false;
-    return (await this.kc.clientSecretById(this.realm, found.id!)) === g.password;
-  }
-
-  /** Withdraw a consumer's client — only one the mesh made. Returns what happened, for the log. */
-  async remove(as: string): Promise<"removed" | "absent" | "not ours"> {
-    const found = await this.kc.findClient(this.realm, as);
-    if (!found) return "absent";
-    if (!marked(found)) return "not ours";
-    await this.kc.deleteClientById(this.realm, found.id!);
-    return "removed";
-  }
-}

modules/keycloak/package.json

@@ -1,15 +1,11 @@
 {
   "name": "@novox/module-keycloak",
   "version": "0.1.0",
-  "description": "keycloak — identity and access; provides the mesh oidc-client interface. Its admin API client, provisioner, tools and events live here (novox/hq ADR 0039).",
+  "description": "keycloak — identity and access. Its admin API client, tools and events live here (novox/hq ADR 0039).",
   "type": "module",
   "private": true,
-  "scripts": {
-    "build": "tsc client.ts oidc.ts index.ts provisioner/index.ts tools/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist",
-    "test": "npm run build && node --test --experimental-strip-types 'test/*.test.ts'"
-  },
   "dependencies": {
-    "@novox/mesh-sdk": "^0.1.1"
+    "@novox/mesh-sdk": "^0.1.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

modules/keycloak/provisioner/index.ts

@@ -1,73 +0,0 @@
-// keycloak's provisioner — the adapter that makes keycloak a provider of the mesh `oidc-client`
-// interface. The reconcile loop, the contributions file and reading the mesh's minted secret are the
-// sdk harness's; this writes only the per-service half: how Keycloak creates, checks and removes a
-// consumer's client (novox/hq ADR 0039/0040/0048). What a client is, and which ones are the mesh's,
-// is in ../oidc.ts.
-//
-// The `oidc-client` interface: a consumer logs people in through the realm this module serves, as
-// the confidential client `as` with the secret the mesh minted, and is redirected back to the
-// callback it contributed under the names the mesh composed for its endpoint. What it is served —
-// the issuer and the endpoint paths under it — is in the manifest's `serves`, settled with the
-// assignment's settings.
-//
-// **The realm is read out of the issuer**, the one value an assignment sets (settings reach both the
-// served facts and this module's config.json): a realm set in one place and an issuer in another
-// would let the consumer be told one realm while its client is made in another.
-
-import { runProvisioner, type Provision } from "@novox/mesh-sdk/provisioner";
-import { emit } from "@novox/mesh-sdk/events";
-import { readFileSync } from "node:fs";
-import { KeycloakClient } from "../client.js";
-import { OidcClients, realmOf } from "../oidc.js";
-
-/** The issuer this assignment serves, from the settings-merged config the mesh delivers. */
-function issuer(): string {
-  const file = process.env.MESH_KEYCLOAK_CONFIG_FILE;
-  let cfg: Record<string, unknown> = {};
-  if (file) {
-    try {
-      cfg = JSON.parse(readFileSync(file, "utf8")) as Record<string, unknown>;
-    } catch {
-      // Absent or unreadable: fall through to the environment, and refuse below if that is empty too.
-    }
-  }
-  const said = typeof cfg.issuer === "string" ? cfg.issuer : process.env.MESH_KEYCLOAK_ISSUER;
-  if (!said) throw new Error("no issuer — the module's config.json carries none and MESH_KEYCLOAK_ISSUER is unset");
-  return said;
-}
-
-const clients = new OidcClients(KeycloakClient.fromEnv(), realmOf(issuer()));
-
-/** 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:oidc-client] emit ${type} failed: ${err}`);
-  }
-}
-
-runProvisioner("oidc-client", {
-  async create(p: Provision): Promise<void> {
-    const done = await clients.ensure(p);
-    if (done === "created") {
-      console.log(`[provisioner:oidc-client] created client ${p.as} in realm ${clients.realm}`);
-      await announce("client.created", { realm: clients.realm, clientId: p.as, consumer: p.consumer ?? "" });
-    }
-  },
-
-  async remove(p: { as: string }): Promise<void> {
-    const done = await clients.remove(p.as);
-    if (done === "not ours") {
-      console.error(`[provisioner:oidc-client] ${p.as}: a client of that id exists that the mesh did not make — left alone`);
-    } else if (done === "removed") {
-      console.log(`[provisioner:oidc-client] removed client ${p.as} from realm ${clients.realm}`);
-    }
-  },
-
-  // Asked every minute by the harness: whether Keycloak still holds this consumer's client exactly as
-  // the mesh gave it, so a client deleted or edited behind the mesh's back is made again (hq issue 120).
-  async holds(p: Provision): Promise<boolean> {
-    return clients.holds(p);
-  },
-});

modules/keycloak/test/oidc.test.ts

@@ -1,239 +0,0 @@
-// What holds keycloak to the `oidc-client` provision (oidc.ts): one confidential client per consumer,
-// under the id and secret the mesh gave, redirecting only to the consumer's own callback under the
-// names the mesh composed; made once and brought back on every apply; and a client the mesh did not
-// make — same id or not — never adopted, changed or deleted.
-//
-// Keycloak is a fake: the admin routes the module touches, answering with the status codes and the
-// shapes Keycloak gives. Run against the compiled module (npm test builds first), the way the runtime
-// loads it.
-
-import { test, after } from "node:test";
-import assert from "node:assert/strict";
-import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
-import { randomUUID } from "node:crypto";
-
-import { KeycloakClient } from "../dist/client.js";
-import { MARK, OidcClients, ROLES_MAPPER, realmOf, redirectsOf } from "../dist/oidc.js";
-
-type Client = Record<string, any>;
-
-/** The realm's clients, by internal id, and what the fake was asked. */
-const realm = "Novox";
-const clients = new Map<string, Client>();
-const calls: string[] = [];
-
-function body(req: IncomingMessage): Promise<any> {
-  return new Promise((resolve) => {
-    let raw = "";
-    req.on("data", (c) => (raw += c));
-    req.on("end", () => resolve(raw ? JSON.parse(raw) : undefined));
-  });
-}
-
-function send(res: ServerResponse, status: number, value?: unknown): void {
-  res.writeHead(status, { "Content-Type": "application/json" });
-  res.end(value === undefined ? "" : JSON.stringify(value));
-}
-
-const server = createServer(async (req, res) => {
-  const url = new URL(req.url!, "http://fake");
-  calls.push(`${req.method} ${url.pathname}`);
-  if (url.pathname === "/realms/master/protocol/openid-connect/token") {
-    return send(res, 200, { access_token: "t", expires_in: 300 });
-  }
-  const base = `/admin/realms/${realm}/clients`;
-  if (!url.pathname.startsWith(base)) return send(res, 404, { error: "Realm not found." });
-  const rest = url.pathname.slice(base.length).split("/").filter(Boolean);
-  if (rest.length === 0 && req.method === "GET") {
-    const want = url.searchParams.get("clientId");
-    return send(res, 200, [...clients.values()].filter((c) => !want || c.clientId === want));
-  }
-  if (rest.length === 0 && req.method === "POST") {
-    const rep = await body(req);
-    if ([...clients.values()].some((c) => c.clientId === rep.clientId)) {
-      return send(res, 409, { errorMessage: `Client ${rep.clientId} already exists` });
-    }
-    const id = randomUUID();
-    const mappers = (rep.protocolMappers ?? []).map((m: Client) => ({ ...m, id: randomUUID() }));
-    clients.set(id, { ...rep, id, protocolMappers: mappers });
-    return send(res, 201);
-  }
-  const c = clients.get(rest[0]);
-  if (!c) return send(res, 404, { error: "Could not find client" });
-  if (rest.length === 1 && req.method === "PUT") {
-    // Keycloak ignores protocolMappers on a client update: they have their own endpoints.
-    const rep = await body(req);
-    clients.set(c.id, { ...rep, id: c.id, protocolMappers: c.protocolMappers });
-    return send(res, 204);
-  }
-  if (rest.length === 1 && req.method === "DELETE") {
-    clients.delete(c.id);
-    return send(res, 204);
-  }
-  if (rest[1] === "client-secret" && req.method === "GET") {
-    return send(res, 200, { type: "secret", value: c.secret });
-  }
-  if (rest[1] === "protocol-mappers") {
-    if (req.method === "GET") return send(res, 200, c.protocolMappers ?? []);
-    if (req.method === "POST") {
-      c.protocolMappers = [...(c.protocolMappers ?? []), { ...(await body(req)), id: randomUUID() }];
-      return send(res, 201);
-    }
-    if (req.method === "PUT") {
-      const m = await body(req);
-      c.protocolMappers = c.protocolMappers.map((x: Client) => (x.id === rest[4] ? m : x));
-      return send(res, 204);
-    }
-  }
-  send(res, 405);
-});
-await new Promise<void>((r) => server.listen(0, "127.0.0.1", r));
-after(() => server.close());
-const port = (server.address() as { port: number }).port;
-
-const oidc = new OidcClients(new KeycloakClient(`http://127.0.0.1:${port}`, "admin", "pw"), realm);
-
-/** Grafana on ace, as the mesh hands it to the provisioner. */
-function grafana(secret = "s3cret", values: Record<string, unknown> = {}) {
-  return {
-    as: "mesh_ace_grafana",
-    password: secret,
-    consumer: "ace",
-    values: {
-      label: "grafana", endpoint: "web", port: 20010, callback: "/login/generic_oauth",
-      name: "grafana.zurag.be", "internal-name": "grafana.ace.internal", ...values,
-    },
-  };
-}
-
-function only(clientId: string): Client {
-  const found = [...clients.values()].filter((c) => c.clientId === clientId);
-  assert.equal(found.length, 1, `exactly one client ${clientId}, found ${found.length}`);
-  return found[0];
-}
-
-test("the realm is read out of the issuer, and an issuer that names none is refused", () => {
-  assert.equal(realmOf("https://keycloak.novox.be/realms/Novox"), "Novox");
-  assert.equal(realmOf("https://keycloak.novox.be/realms/Novox/"), "Novox");
-  assert.equal(realmOf("http://127.0.0.1:18500/realms/master"), "master");
-  assert.throws(() => realmOf("https://keycloak.novox.be"), /realms/);
-  assert.throws(() => realmOf("keycloak"), /not a URL/);
-});
-
-test("the redirect is the consumer's callback under every name the mesh composed for it", () => {
-  assert.deepEqual(redirectsOf(grafana().values), {
-    root: "https://grafana.zurag.be",
-    redirects: ["https://grafana.zurag.be/login/generic_oauth", "https://grafana.ace.internal/login/generic_oauth"],
-  });
-  // A route reaching only the private network has only the internal name, and that is enough.
-  assert.deepEqual(redirectsOf({ callback: "/cb", "internal-name": "x.ace.internal" }).redirects,
-    ["https://x.ace.internal/cb"]);
-  assert.throws(() => redirectsOf({ name: "grafana.zurag.be" }), /callback/);
-  assert.throws(() => redirectsOf({ name: "grafana.zurag.be", callback: "login" }), /callback/);
-  assert.throws(() => redirectsOf({ callback: "/cb" }), /label/);
-});
-
-test("a consumer is given one confidential client, under its id and the mesh's secret", async () => {
-  clients.clear();
-  assert.equal(await oidc.ensure(grafana()), "created");
-  const c = only("mesh_ace_grafana");
-  assert.equal(c.publicClient, false);
-  assert.equal(c.clientAuthenticatorType, "client-secret");
-  assert.equal(c.secret, "s3cret");
-  assert.equal(c.enabled, true);
-  assert.equal(c.standardFlowEnabled, true);
-  assert.equal(c.directAccessGrantsEnabled, false);
-  assert.equal(c.implicitFlowEnabled, false);
-  assert.deepEqual(c.redirectUris, [
-    "https://grafana.zurag.be/login/generic_oauth", "https://grafana.ace.internal/login/generic_oauth"]);
-  assert.equal(c.attributes[MARK], "true");
-  assert.deepEqual(c.protocolMappers.map((m: Client) => m.name), [ROLES_MAPPER.name]);
-  assert.equal(await oidc.holds(grafana()), true);
-});
-
-test("applying the same grant again makes no second client", async () => {
-  clients.clear();
-  await oidc.ensure(grafana());
-  assert.equal(await oidc.ensure(grafana()), "updated");
-  assert.equal(await oidc.ensure(grafana()), "updated");
-  only("mesh_ace_grafana");
-  assert.equal(only("mesh_ace_grafana").protocolMappers.length, 1, "the roles mapper is not added twice");
-});
-
-test("a new secret or a moved name is applied in place, and what the mesh does not own survives", async () => {
-  clients.clear();
-  await oidc.ensure(grafana());
-  const id = only("mesh_ace_grafana").id;
-  // Something the mesh does not own, set on the client after it was made.
-  clients.get(id)!.consentRequired = true;
-  clients.get(id)!.attributes["post.logout.redirect.uris"] = "+";
-
-  assert.equal(await oidc.holds(grafana("rotated")), false, "a rotated secret is not held until applied");
-  await oidc.ensure(grafana("rotated", { name: "dash.zurag.be" }));
-  const c = only("mesh_ace_grafana");
-  assert.equal(c.id, id, "updated, not replaced");
-  assert.equal(c.secret, "rotated");
-  assert.deepEqual(c.redirectUris, [
-    "https://dash.zurag.be/login/generic_oauth", "https://grafana.ace.internal/login/generic_oauth"]);
-  assert.equal(c.rootUrl, "https://dash.zurag.be");
-  assert.equal(c.consentRequired, true);
-  assert.equal(c.attributes["post.logout.redirect.uris"], "+");
-  assert.equal(c.attributes[MARK], "true");
-  assert.equal(await oidc.holds(grafana("rotated", { name: "dash.zurag.be" })), true);
-});
-
-test("a client lost or edited behind the mesh's back is not held, and is made whole again", async () => {
-  clients.clear();
-  await oidc.ensure(grafana());
-  const c = only("mesh_ace_grafana");
-  c.redirectUris = ["*"];
-  assert.equal(await oidc.holds(grafana()), false, "a widened redirect is not what the mesh gave");
-  await oidc.ensure(grafana());
-  assert.equal(await oidc.holds(grafana()), true);
-
-  only("mesh_ace_grafana").protocolMappers = [];
-  assert.equal(await oidc.holds(grafana()), false, "a client without its roles mapper is not held");
-  await oidc.ensure(grafana());
-  assert.equal(await oidc.holds(grafana()), true);
-
-  clients.clear();
-  assert.equal(await oidc.holds(grafana()), false);
-});
-
-test("a client of the same id the mesh did not make is refused, and left exactly as it was", async () => {
-  clients.clear();
-  clients.set("theirs", { id: "theirs", clientId: "mesh_ace_grafana", secret: "their-secret", redirectUris: ["*"] });
-  const before = JSON.stringify(clients.get("theirs"));
-  const writes = calls.length;
-  await assert.rejects(oidc.ensure(grafana()), /did not make/);
-  assert.equal(JSON.stringify(clients.get("theirs")), before);
-  assert.ok(calls.slice(writes).every((c) => c.startsWith("GET") || c.startsWith("POST /realms/master")),
-    `only reads were made: ${calls.slice(writes).join(", ")}`);
-  assert.equal(await oidc.holds(grafana()), false);
-  assert.equal(await oidc.remove("mesh_ace_grafana"), "not ours");
-  assert.ok(clients.has("theirs"), "a client the mesh did not make is never deleted");
-});
-
-test("the predecessor's hand-made client is never touched: the mesh's has its own id", async () => {
-  clients.clear();
-  clients.set("hal", { id: "hal", clientId: "grafana", secret: "old", redirectUris: ["https://grafana.zurag.be/*"] });
-  await oidc.ensure(grafana());
-  assert.equal(clients.get("hal")!.secret, "old");
-  only("mesh_ace_grafana");
-  assert.equal(await oidc.remove("grafana"), "not ours");
-  assert.ok(clients.has("hal"));
-});
-
-test("a withdrawn consumer's client is removed, and an absent one is not an error", async () => {
-  clients.clear();
-  await oidc.ensure(grafana());
-  assert.equal(await oidc.remove("mesh_ace_grafana"), "removed");
-  assert.equal([...clients.values()].length, 0);
-  assert.equal(await oidc.remove("mesh_ace_grafana"), "absent");
-});
-
-test("a contribution with no callback makes no client at all", async () => {
-  clients.clear();
-  await assert.rejects(oidc.ensure({ ...grafana(), values: { name: "grafana.zurag.be" } }), /callback/);
-  assert.equal(clients.size, 0);
-});

modules/keycloak/tsconfig.json

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

modules/lavinmq/Dockerfile

@@ -0,0 +1,42 @@
+# 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

@@ -0,0 +1,45 @@
+// 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

@@ -0,0 +1,150 @@
+// 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: ".*" });
+  }
+
+  /** 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

@@ -0,0 +1,25 @@
+// 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>("module.lavinmq.amqp.provisioned", async (e) => {
+  console.log(`[lavinmq] broker provisioned for ${e.body.consumer ?? "?"} (user ${e.body.user}, vhost ${e.body.vhost})`);
+});
+
+await on<AmqpEvent>("module.lavinmq.amqp.deprovisioned", async (e) => {
+  console.log(`[lavinmq] broker deprovisioned (user ${e.body.user})`);
+});
+
+console.log("[lavinmq] auditing broker lifecycle events");

modules/lavinmq/module.json

@@ -0,0 +1,139 @@
+{
+  "module": "lavinmq",
+  "version": "1",
+  "provides": [
+    {
+      "name": "amqp",
+      "scope": "mesh"
+    }
+  ],
+  "claims": [
+    {
+      "name": "mesh-broker",
+      "scope": "mesh"
+    }
+  ],
+  "capabilities": [
+    "container-runtime"
+  ],
+  "emits": [
+    "module.lavinmq.amqp.provisioned",
+    "module.lavinmq.amqp.deprovisioned"
+  ],
+  "consumes": [
+    "module.lavinmq.amqp.provisioned",
+    "module.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": "server",
+      "type": "container",
+      "name": "mesh-broker",
+      "image": "cloudamqp/lavinmq@sha256:3eb54c12916d700a978c2ea86e6362cd4974b0e3189508718006d4e6d341246b",
+      "ports": [
+        "5671:5671",
+        "5672:5672",
+        "127.0.0.1:15672:15672"
+      ],
+      "volumes": [
+        "mesh-broker-data:/var/lib/lavinmq",
+        "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"
+      }
+    ]
+  }
+}