anthropic-consumer: its usage runs in the node's runtime, and its apply is a scheduled process (hq ADR 0198)

Both containers go with the Dockerfile, build bases, bus credential and state directory. apply needs no bus and runs every five minutes as a process on the machine at the host paths the container mounted. usage emitted by spawning the runtime image's own emit command with the module's credential, which exists nowhere now, so it is loaded by the node's runtime instead: it emits through the SDK as this module and reads on the cadence the schedule gave it, once at start and every five minutes. That is the one code change.

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

@@ -15,7 +15,7 @@ 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)); // the pattern index.ts subscribes
+  await on("**", async (event) => record(event, path));
 
   process.env.MESH_MODULE = "umami";
   process.env.MESH_NODE = "anchor";
@@ -24,9 +24,7 @@ test("audit-logger records every event to the trail as one line each", async ()
 
   const lines = (await readFile(path, "utf8")).trim().split("\n").map((l) => JSON.parse(l));
   assert.equal(lines.length, 2);
-  // A module names its events locally (design 29); the module is the `source`, which together with
-  // the type says whose event it was. This broker does no namespacing, so the type is as emitted.
-  assert.deepEqual(lines.map((l) => l.type), ["site.created", "node.anchor.joined"]);
+  assert.deepEqual(lines.map((l) => l.type), ["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/mesh-catalog/Dockerfile

@@ -0,0 +1,55 @@
+# mesh-catalog's runtime: the tool runtime, carrying the catalogue's compiled graph, its consumer
+# of what the builder announces, and its tools.
+#
+# **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 with 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/mesh-catalog
+COPY . .
+# The compiler is invoked by its real path rather than through node_modules/.bin, whose entries are
+# symlinks to a launcher that requires its library relatively — resolved away when the base image
+# was assembled.
+RUN node /app/node_modules/typescript/bin/tsc pg.d.ts store.ts index.ts tools/index.ts prepare/index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+# **A module may need something the base image does not carry.** The base holds what every module
+# needs — the sdk, the broker client — and a postgres driver is not that: the one other module that
+# reaches a database shells out to psql instead. So the catalogue brings its own.
+#
+# Installed into an empty directory rather than into the module's, because the module's package.json
+# also names `@novox/mesh-sdk`, which is not on any registry — it is in the base image. Asking npm to
+# resolve this module's dependencies would therefore fail on the one it already has.
+RUN mkdir -p /deps && cd /deps && \
+      npm install --omit=dev --no-audit --no-fund --no-package-lock pg@8
+
+FROM ${RUNTIME_BASE}
+COPY --from=build /app/modules/mesh-catalog/dist /app/modules/mesh-catalog/dist
+# Beside the compiled code, so `pg` resolves from it while `@novox/mesh-sdk` keeps walking up to the
+# base image's own node_modules — the module gets its extra dependency without shadowing the sdk it
+# was compiled against.
+COPY --from=build /deps/node_modules /app/modules/mesh-catalog/node_modules
+# Both entrypoints, loaded in serve mode.
+#
+# **A consumer cannot be started with `run`.** That mode imports an entrypoint without binding a
+# broker — it is for a step that does its work offline and exits — and the catalogue's whole job is
+# to listen for what the builder announces. Serve binds the broker first, then imports these, so
+# `on()` has something to subscribe to.
+ENV MESH_TOOL_MODULES=/app/modules/mesh-catalog/dist/index.js,/app/modules/mesh-catalog/dist/tools/index.js
+
+# And what prepares this module's state, for the runtime's `prepare` mode (novox/hq ADR 0135). Named
+# here, beside the entrypoints above, because the module knows which of its files prepares its state
+# and nothing else could: the mesh asks one word and this says what answers it.
+ENV MESH_PREPARE=/app/modules/mesh-catalog/dist/prepare/index.js

modules/mesh-catalog/module.json

@@ -25,6 +25,9 @@
   "secrets": {
     "postgres-database": "${dir:state}/database.secret"
   },
+  "own-secrets": {
+    "broker": "${dir:mesh-state}/broker"
+  },
   "consumes": [
     "mesh-build-machine.built",
     "mesh-controller.built-before"
@@ -35,7 +38,14 @@
     "rebuild-needed",
     "catching-up"
   ],
+  "prepares": true,
   "resources": [
+    {
+      "id": "mesh-state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "mesh"
+    },
     {
       "id": "state",
       "type": "directory",
@@ -50,41 +60,43 @@
       "content": "postgresql://${bound:postgres-database:as}:${secret:postgres-database}@${bound:postgres-database:at}:${bound:postgres-database:port}/${bound:postgres-database:as}\n"
     },
     {
-      "id": "prepare",
-      "type": "process",
-      "name": "mesh-catalog-prepare",
-      "artifact": "code",
-      "run": [
-        "node",
-        "prepare/index.js"
+      "id": "runtime",
+      "type": "container",
+      "name": "mesh-catalog",
+      "network": "host",
+      "volumes": [
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "${dir:state}:/run/state",
+        "${dir:state}/database.url:/run/secrets/database-url:ro"
       ],
-      "run-once": true,
       "env": {
-        "DATABASE_URL_FILE": "${dir:state}/database.url"
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "DATABASE_URL_FILE": "/run/secrets/database-url"
       },
+      "artifact": "runtime",
       "restart-on": [
         "database-url"
       ]
     }
   ],
   "build": {
+    "on": [
+      {
+        "arg": "BUILD_BASE",
+        "module": "mesh-tools",
+        "artifact": "build"
+      },
+      {
+        "arg": "RUNTIME_BASE",
+        "module": "mesh-tools",
+        "artifact": "runtime"
+      }
+    ],
     "artifacts": [
       {
-        "name": "code",
-        "kind": "bundle",
-        "language": "typescript",
-        "entrypoints": [
-          "index.js",
-          "tools/index.js",
-          "prepare/index.js"
-        ],
-        "loads": [
-          "index.js",
-          "tools/index.js"
-        ],
-        "env": {
-          "DATABASE_URL_FILE": "${dir:state}/database.url"
-        }
+        "name": "runtime",
+        "kind": "image",
+        "from": "Dockerfile"
       }
     ]
   }

modules/mesh-catalog/pg.d.ts

@@ -1,9 +1,9 @@
 // Ambient types for `pg` (node-postgres), which ships its types only via the separate `@types/pg`
 // package. Rather than pull that in at tsc time, this declares the exact slice model-usage uses —
 // the same precedent anthropic-manager sets for `tweetnacl-sealedbox-js` (a local ambient .d.ts,
-// listed in tsconfig `include`, default-imported). The real `pg` is the package.json dependency the
-// builder installs and inlines into the module's bundle (novox/hq ADR 0198 §4), so this types the
-// code without deciding what runs.
+// listed in tsconfig `include`, default-imported). The real `pg` is installed into the module's
+// runtime image (package.json `dependencies`; novox/hq ADR 0052), so this types the code without
+// deciding what runs.
 declare module "pg" {
   /** One checked-out connection. Needed because registering a module-version and its edges is one
    *  act: a half-written registration is a graph that lies about what something was built against. */

modules/mesh-catalog/prepare/index.ts

@@ -7,9 +7,8 @@
 // nothing anywhere said so.
 //
 // Nothing here connects to the broker. Preparation runs before the version that would use it, so
-// there is nothing yet to talk to: the host runs this file as a run-once process, with the module's
-// words and no bus (novox/hq ADR 0198 §3), before the node's runtime is started with the version
-// that needs it, and this process exiting non-zero is how the host knows the step did not complete.
+// there is nothing yet to talk to; the runtime's `prepare` mode imports this and awaits it, and this
+// process exiting non-zero is how the host knows not to start the runtime.
 import { Graph } from "../store.js";
 
 const graph = Graph.fromEnv();

modules/mongodb/Dockerfile

@@ -0,0 +1,37 @@
+# mongodb'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
+# 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. The compiler
+# is invoked by its real path: node_modules/.bin entries are launcher symlinks the base image
+# resolved away.
+WORKDIR /app/modules/mongodb
+COPY . .
+RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts provisioner/index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+FROM ${RUNTIME_BASE}
+# mongodb's client shells out to `mongosh`, installed from MongoDB's own apt repo so its shared
+# libraries come with it — copying the bare binary out of the mongo image leaves it unable to load.
+RUN apt-get update && apt-get install -y --no-install-recommends gnupg curl ca-certificates \
+ && curl -fsSL https://pgp.mongodb.com/server-7.0.asc | gpg --dearmor -o /usr/share/keyrings/mongodb.gpg \
+ && echo "deb [signed-by=/usr/share/keyrings/mongodb.gpg] https://repo.mongodb.org/apt/debian bookworm/mongodb-org/7.0 main" > /etc/apt/sources.list.d/mongodb.list \
+ && apt-get update && apt-get install -y --no-install-recommends mongodb-mongosh \
+ && rm -rf /var/lib/apt/lists/*
+COPY --from=build /app/modules/mongodb/dist /app/modules/mongodb/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. 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/mongodb/dist/index.js,/app/modules/mongodb/dist/tools/index.js,/app/modules/mongodb/dist/provisioner/index.js

modules/mongodb/client.ts

@@ -1,16 +1,19 @@
 // mongodb's admin client — mongodb's own code, living in the module (novox/hq ADR 0039). Both this
 // module's tools and its provisioner import it, and nothing outside mongodb does.
 //
-// **The backend's own driver, inside the bundle** (novox/hq ADR 0198 §4). This used to shell out to
-// `mongosh`, which the module's container installed from MongoDB's apt repository; the module's code
-// now runs in the node's runtime, on machines whose system carries no mongosh, so it speaks to the
-// server through the official `mongodb` driver its package.json names — installed and inlined into
-// the bundle by the builder. One connection per call, as one mongosh invocation was: the module is
-// called rarely, and a pool held open across calls would hold a credential the mesh may rotate.
+// Commands run through `mongosh`, not a wire-protocol driver: the module may take NO npm dependency
+// beyond @novox/mesh-sdk, and hand-rolling the MongoDB wire protocol + SCRAM auth is more surface
+// than this should carry — so it shells out to the shell the mongodb image ships, the same way
+// postgres drives itself through `psql`, minio through `mc` and mailu through doveadm. One boundary,
+// `evalJs()`, and every method is built on it: a snippet of JavaScript is evaluated server-side and
+// its result comes back as EJSON on stdout.
 
 import { randomBytes } from "node:crypto";
 import { readFileSync } from "node:fs";
-import { MongoClient as Driver, MongoServerError, BSON, type Document } from "mongodb";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
 
 export interface DatabaseInfo {
   readonly name: string;
@@ -56,26 +59,32 @@ export class MongoClient {
     return this.conn.port;
   }
 
-  /** The admin connection URI, credentials percent-encoded. */
+  /** The admin connection URI mongosh authenticates with, credentials percent-encoded. */
   private uri(): string {
     const u = encodeURIComponent(this.conn.user);
     const p = encodeURIComponent(this.conn.password);
     const a = encodeURIComponent(this.conn.authSource);
-    return `mongodb://${u}:${p}@${this.conn.host}:${this.conn.port}/?authSource=${a}&directConnection=true`;
+    return `mongodb://${u}:${p}@${this.conn.host}:${this.conn.port}/?authSource=${a}`;
   }
 
   /**
-   * The one execution boundary: connect as the administrator, do `work`, and close — a failure to
-   * connect or to authenticate rejects here rather than returning a partial success.
+   * Evaluate a JavaScript snippet server-side through `mongosh` and parse the JSON it prints (see
+   * header). The snippet MUST `print()` exactly one JSON document as its only stdout — every method
+   * below ends in `print(EJSON.stringify(...))`. `--quiet` suppresses the shell banner so stdout is
+   * the JSON alone; a non-zero exit (auth failure, bad command) rejects here rather than returning
+   * a partial success.
    */
-  private async admin<T>(work: (client: Driver) => Promise<T>): Promise<T> {
-    const client = new Driver(this.uri(), { serverSelectionTimeoutMS: 10_000 });
-    try {
-      await client.connect();
-      return await work(client);
-    } finally {
-      await client.close();
+  async evalJs<T>(js: string): Promise<T> {
+    const { stdout } = await run(
+      "mongosh",
+      [this.uri(), "--quiet", "--eval", js],
+      { maxBuffer: 16 << 20 },
+    );
+    const text = stdout.trim();
+    if (text.length === 0) {
+      throw new Error("mongosh returned no output — the eval printed nothing");
     }
+    return JSON.parse(text) as T;
   }
 
   /**
@@ -85,16 +94,19 @@ export class MongoClient {
    * password and roles, so a rotated credential converges.
    */
   async createDatabaseAndUser(database: string, user: string, password: string): Promise<void> {
-    await this.admin(async (client) => {
-      const target = client.db(database);
-      const roles = [{ role: "dbOwner", db: database }];
-      const found = await target.command({ usersInfo: user });
-      if (Array.isArray(found.users) && found.users.length > 0) {
-        await target.command({ updateUser: user, pwd: password, roles });
+    const js = `
+const target = db.getSiblingDB(${lit(database)});
+let existing = null;
+try { existing = target.getUser(${lit(user)}); } catch (e) { existing = null; }
+const roles = [{ role: "dbOwner", db: ${lit(database)} }];
+if (existing) {
+  target.updateUser(${lit(user)}, { pwd: ${lit(password)}, roles: roles });
 } else {
-        await target.command({ createUser: user, pwd: password, roles });
+  target.createUser({ user: ${lit(user)}, pwd: ${lit(password)}, roles: roles });
 }
-    });
+print(EJSON.stringify({ ok: 1 }));
+`;
+    await this.evalJs<{ ok: number }>(js);
   }
 
   /**
@@ -103,43 +115,45 @@ export class MongoClient {
    * authentication failure or a missing role; an unreachable server rejects (novox/hq issue 120).
    */
   async canAuthenticateAs(database: string, user: string, password: string): Promise<boolean> {
-    // Credentials as options, never in a URI, so the consumer's password is in no message a failed
-    // connection prints.
-    const client = new Driver(`mongodb://${this.conn.host}:${this.conn.port}/?directConnection=true`, {
-      auth: { username: user, password },
-      authSource: database,
-      serverSelectionTimeoutMS: 10_000,
-    });
+    // Connected without credentials, then authenticated inside the eval from the environment, so
+    // the consumer's password is neither on argv nor in the message of a failed command.
+    const uri = `mongodb://${this.conn.host}:${this.conn.port}/?serverSelectionTimeoutMS=10000`;
+    const js =
+      "const t = db.getSiblingDB(process.env.MESH_HOLDS_DB);" +
+      "t.auth(process.env.MESH_HOLDS_USER, process.env.MESH_HOLDS_PW);" +
+      "print(EJSON.stringify(t.runCommand({ connectionStatus: 1 }).authInfo.authenticatedUserRoles))";
+    let stdout: string;
     try {
-      await client.connect();
-      const status = await client.db(database).command({ connectionStatus: 1 });
-      const roles = (status.authInfo?.authenticatedUserRoles ?? []) as { role: string; db: string }[];
-      return roles.some((r) => r.role === "dbOwner" && r.db === database);
+      ({ stdout } = await run("mongosh", [uri, "--quiet", "--eval", js], {
+        env: { ...process.env, MESH_HOLDS_DB: database, MESH_HOLDS_USER: user, MESH_HOLDS_PW: password },
+        timeout: 30_000,
+      }));
     } catch (err) {
-      if (isAuthFailure(err)) return false;
-      throw new Error(`mongodb could not check ${user}: ${String((err as Error).message).split("\n")[0]}`);
-    } finally {
-      await client.close();
+      const text = `${(err as { stderr?: string }).stderr ?? ""}${(err as { stdout?: string }).stdout ?? ""}`;
+      if (/Authentication failed|AuthenticationFailed/i.test(text)) return false;
+      throw new Error(`mongosh could not check ${user}: ${text.trim().slice(0, 500) || String((err as Error).message).split("\n")[0]}`);
     }
+    const roles = JSON.parse(stdout.trim()) as { role: string; db: string }[];
+    return roles.some((r) => r.role === "dbOwner" && r.db === database);
   }
 
   /** Drop a database and its owning user, idempotently. Dropping the database evicts its data; the
    *  user is removed first so a re-grant of the same login starts clean. */
   async dropDatabaseAndUser(database: string, user: string): Promise<void> {
-    await this.admin(async (client) => {
-      const target = client.db(database);
-      try {
-        await target.command({ dropUser: user });
-      } catch (err) {
-        if (!(err instanceof MongoServerError && err.code === 11)) throw err; // 11: UserNotFound
-      }
-      await target.dropDatabase();
-    });
+    const js = `
+const target = db.getSiblingDB(${lit(database)});
+try { target.dropUser(${lit(user)}); } catch (e) {}
+target.dropDatabase();
+print(EJSON.stringify({ ok: 1 }));
+`;
+    await this.evalJs<{ ok: number }>(js);
   }
 
   /** List the databases on the server, with on-disk size, for the mongodb_list_databases tool. */
   async listDatabases(): Promise<DatabaseInfo[]> {
-    const res = await this.admin((client) => client.db("admin").admin().listDatabases());
+    const res = await this.evalJs<{ databases: { name: string; sizeOnDisk?: number }[] }>(
+      `print(EJSON.stringify(db.adminCommand({ listDatabases: 1 })));`,
+    );
     return (res.databases ?? [])
       .map((d) => ({ name: String(d.name), sizeBytes: Number(d.sizeOnDisk ?? 0) }))
       .sort((a, b) => a.name.localeCompare(b.name));
@@ -148,8 +162,6 @@ export class MongoClient {
   /**
    * Run a read-only `find` against a collection in a named database, for the mongodb_query tool.
    * `find` mutates nothing; the limit is capped so a tool call cannot stream an unbounded result.
-   * Documents come back as relaxed Extended JSON — an ObjectId as `{"$oid": …}` — exactly as the
-   * shell's `EJSON.stringify` rendered them before.
    */
   async find(
     database: string,
@@ -158,29 +170,26 @@ export class MongoClient {
     limit: number,
   ): Promise<Record<string, unknown>[]> {
     const capped = Math.max(1, Math.min(limit, 1000));
-    const docs = await this.admin((client) =>
-      client
-        .db(database)
-        .collection(collection)
-        .find(BSON.EJSON.deserialize(filter as Document, { relaxed: true }) as Document)
-        .limit(capped)
-        .toArray(),
-    );
-    return BSON.EJSON.serialize(docs, { relaxed: true }) as Record<string, unknown>[];
+    const js =
+      `print(EJSON.stringify(` +
+      `db.getSiblingDB(${lit(database)}).getCollection(${lit(collection)})` +
+      `.find(${JSON.stringify(filter)}).limit(${capped}).toArray()` +
+      `));`;
+    return this.evalJs<Record<string, unknown>[]>(js);
   }
 }
 
-/** An authentication failure, as the server or the driver reports it. */
-function isAuthFailure(err: unknown): boolean {
-  if (err instanceof MongoServerError && err.code === 18) return true; // 18: AuthenticationFailed
-  return /Authentication failed|AuthenticationFailed/i.test(String((err as Error)?.message ?? ""));
-}
-
 /** Generate a URL-safe password. */
 export function generatePassword(): string {
   return randomBytes(24).toString("base64url");
 }
 
+/** Embed a value as a JavaScript literal inside a mongosh snippet — JSON.stringify escapes quotes,
+ *  backslashes and control characters, so a string cannot break out of the snippet. */
+function lit(val: unknown): string {
+  return JSON.stringify(val);
+}
+
 function readSecretFile(path: string | undefined): string | undefined {
   if (!path) return undefined;
   try {

modules/mongodb/index.ts

@@ -1,9 +1,9 @@
-// mongodb's events entrypoint, launched by the node's runtime beside its tools and provisioner
-// (novox/hq ADR 0198). The database lifecycle events are EMITTED from the provisioner, where
+// mongodb's events entrypoint, loaded by the per-node tool host (the provisioner container runs
+// ./provisioner separately). The database lifecycle events are EMITTED from the provisioner, where
 // the lifecycle actually happens (novox/hq ADR 0041/0042):
 //   module.mongodb.database.provisioned    — a consumer's database + owning user was created
 //   module.mongodb.database.deprovisioned  — that database was removed
-// Here in the runtime we react to them, keeping a lightweight audit trail of who was granted a
+// Here in the tool host we react to them, keeping a lightweight audit trail of who was granted a
 // database and who lost one — observability the provider itself is best placed to log.
 
 import { on } from "@novox/mesh-sdk/events";

modules/mongodb/module.json

@@ -39,9 +39,17 @@
     "mongodb-database": "${dir:grants}"
   },
   "own-secrets": {
-    "root": "${dir:state}/root.secret"
+    "root": "${dir:state}/root.secret",
+    "broker": "${dir:mesh-state}/broker"
   },
+  "secrets-owner": "999:999",
   "resources": [
+    {
+      "id": "mesh-state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "mesh"
+    },
     {
       "id": "state",
       "type": "directory",
@@ -63,14 +71,6 @@
       "type": "network",
       "name": "mongodb"
     },
-    {
-      "id": "server-root",
-      "type": "file",
-      "path": "${dir:state}/server-root.secret",
-      "mode": "0400",
-      "owner": "999:999",
-      "content": "${secret:root}"
-    },
     {
       "id": "server",
       "type": "container",
@@ -86,31 +86,46 @@
       ],
       "volumes": [
         "${dir:data}:/data/db",
-        "${dir:state}/server-root.secret:/run/secrets/root:ro"
+        "${dir:state}/root.secret:/run/secrets/root:ro"
       ]
+    },
+    {
+      "id": "runtime",
+      "type": "container",
+      "name": "mesh-mongodb",
+      "network": "mongodb",
+      "volumes": [
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "${dir:grants}:${dir:grants}:ro",
+        "${dir:state}/root.secret:/run/secrets/root:ro"
+      ],
+      "env": {
+        "MESH_PROVISION_MONGODB": "mongodb://root@mongodb-server:27017/admin?authSource=admin",
+        "MESH_PROVISION_PASSWORD_FILE": "/run/secrets/root",
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_RECEIVES": "${dir:grants}/mesh.json"
+      },
+      "artifact": "runtime"
     }
   ],
   "build": {
+    "on": [
+      {
+        "arg": "BUILD_BASE",
+        "module": "mesh-tools",
+        "artifact": "build"
+      },
+      {
+        "arg": "RUNTIME_BASE",
+        "module": "mesh-tools",
+        "artifact": "runtime"
+      }
+    ],
     "artifacts": [
       {
-        "name": "code",
-        "kind": "bundle",
-        "language": "typescript",
-        "entrypoints": [
-          "index.js",
-          "tools/index.js",
-          "provisioner/index.js"
-        ],
-        "loads": [
-          "index.js",
-          "tools/index.js",
-          "provisioner/index.js"
-        ],
-        "env": {
-          "MESH_PROVISION_MONGODB": "mongodb://root@127.0.0.1:${port:27017}/admin?authSource=admin",
-          "MESH_PROVISION_PASSWORD_FILE": "${dir:state}/root.secret",
-          "MESH_RECEIVES": "${dir:grants}/mesh.json"
-        }
+        "name": "runtime",
+        "kind": "image",
+        "from": "Dockerfile"
       }
     ]
   }

modules/mongodb/package.json

@@ -5,8 +5,7 @@
   "type": "module",
   "private": true,
   "dependencies": {
-    "@novox/mesh-sdk": "^0.1.1",
-    "mongodb": "^6.21.0"
+    "@novox/mesh-sdk": "^0.1.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

modules/mongodb/provisioner/index.ts

@@ -11,7 +11,8 @@
 // same-named database under exactly that login — a name the consumer cannot learn is a database it
 // cannot reach.
 //
-// The commands run through MongoClient, the official driver inside this bundle (see client.ts).
+// The commands run through MongoClient.evalJs(), which is the module's one execution boundary (see
+// client.ts).
 
 import { runProvisioner, type Provision } from "@novox/mesh-sdk/provisioner";
 import { emit } from "@novox/mesh-sdk/events";

modules/mongodb/tools/index.ts

@@ -1,6 +1,6 @@
 // mongodb's tools — mongodb's own code (novox/hq ADR 0039), importing mongodb's own client. They
-// return structured data; the mesh serves them through the sdk's tool harness. Both call the server
-// through MongoClient, the driver inside this bundle (see client.ts).
+// return structured data; the mesh serves them through the sdk's tool harness. Both call through
+// MongoClient.evalJs(), the module's one execution boundary (see client.ts).
 
 import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
 import { MongoClient } from "../client.js";

modules/mosquitto/client.ts

@@ -18,7 +18,6 @@ import { randomBytes } from "node:crypto";
 import { connect as tcpConnect } from "node:net";
 import { readFileSync } from "node:fs";
 import { execFile } from "node:child_process";
-import { basename, dirname } from "node:path";
 import { promisify } from "node:util";
 
 import { missingAcls, parseRoleAcls, staleAcls, wantedAcls } from "./topics.js";
@@ -31,14 +30,6 @@ export interface MqttConn {
   /** The Dynamic Security admin client the runtime authenticates as. */
   readonly adminUser: string;
   readonly adminPassword: string;
-  /**
-   * The broker's own container, when `mosquitto_ctrl` is run inside it rather than from this
-   * machine's packages. The broker's image carries the tool at the broker's version, and inside it
-   * the broker listens on 127.0.0.1:1883 whatever port the machine publishes.
-   */
-  readonly container?: string;
-  /** The broker's image, to seed the security file before the broker has ever started. */
-  readonly image?: string;
 }
 
 export class MosquittoClient {
@@ -62,11 +53,7 @@ export class MosquittoClient {
         "mosquitto host or admin password is not set — mosquitto's own code cannot reach the broker",
       );
     }
-    return new MosquittoClient({
-      host, port, adminUser, adminPassword: adminPassword ?? "",
-      container: env.MESH_MQTT_CTRL_CONTAINER || undefined,
-      image: env.MESH_MQTT_CTRL_IMAGE || undefined,
-    });
+    return new MosquittoClient({ host, port, adminUser, adminPassword: adminPassword ?? "" });
   }
 
   get host(): string {
@@ -97,18 +84,16 @@ export class MosquittoClient {
    * to this single-purpose runtime container; see the module README.
    */
   async ctl(...args: string[]): Promise<string> {
-    const inside = this.conn.container !== undefined;
     const base = [
-      "-h", inside ? "127.0.0.1" : this.conn.host,
-      "-p", inside ? "1883" : String(this.conn.port),
+      "-h", this.conn.host,
+      "-p", String(this.conn.port),
       "-u", this.conn.adminUser,
       "-P", this.conn.adminPassword,
     ];
     let stdout: string;
     let stderr: string;
     try {
-      const [command, argv] = this.ctrl([...base, "dynsec", ...args]);
-      ({ stdout, stderr } = await run(command, argv, {
+      ({ stdout, stderr } = await run("mosquitto_ctrl", [...base, "dynsec", ...args], {
         maxBuffer: 16 << 20,
         timeout: 30_000,
       }));
@@ -255,27 +240,10 @@ export class MosquittoClient {
   async initBootstrapFile(configFile: string): Promise<void> {
     // `dynsec init <file> <admin-username> [admin-password]` is an offline file operation — it does
     // not connect to the broker. The password is a positional argument (omitting it prompts).
-    if (this.conn.image) {
-      // Before the broker has ever started there is no container to enter: a throwaway one from the
-      // broker's own image writes the file into the directory the broker will mount.
-      await run("docker", [
-        "run", "--rm", "--entrypoint", "mosquitto_ctrl",
-        "-v", `${dirname(configFile)}:/mosquitto/data`,
-        this.conn.image,
-        "dynsec", "init", `/mosquitto/data/${basename(configFile)}`, this.conn.adminUser, this.conn.adminPassword,
-      ], { maxBuffer: 16 << 20 });
-      return;
-    }
     await run("mosquitto_ctrl", ["dynsec", "init", configFile, this.conn.adminUser, this.conn.adminPassword], {
       maxBuffer: 16 << 20,
     });
   }
-
-  /** How `mosquitto_ctrl` is run here: inside the broker's container when one is named. */
-  ctrl(argv: string[]): [string, string[]] {
-    if (this.conn.container) return ["docker", ["exec", this.conn.container, "mosquitto_ctrl", ...argv]];
-    return ["mosquitto_ctrl", argv];
-  }
 }
 
 /** Generate a URL-safe password with no argv- or MQTT-hostile characters. */

modules/mosquitto/module.json

@@ -92,7 +92,7 @@
       "type": "file",
       "path": "${dir:state}/bootstrap.env",
       "mode": "0600",
-      "content": "MESH_PROVISION_MQTT=127.0.0.1:${port:1883}\nMESH_PROVISION_ADMIN_USER=mesh-admin\nMESH_PROVISION_PASSWORD_FILE=${dir:mesh-state}/admin\nMESH_DYNSEC_FILE=${dir:data}/dynamic-security.json\nMESH_MQTT_CTRL_IMAGE=eclipse-mosquitto@sha256:38c0da4f2ef84284d47b3b3eeea1cb3bdeabe81ee10caf0cd5c5ff61ee3ea408\n"
+      "content": "MESH_PROVISION_MQTT=127.0.0.1:${port:1883}\nMESH_PROVISION_ADMIN_USER=mesh-admin\nMESH_PROVISION_PASSWORD_FILE=${dir:mesh-state}/admin\nMESH_DYNSEC_FILE=${dir:data}/dynamic-security.json\n"
     },
     {
       "id": "bootstrap",
@@ -125,6 +125,11 @@
         "${dir:data}:/mosquitto/data",
         "${dir:state}/mosquitto.conf:/mosquitto/config/mosquitto.conf:ro"
       ]
+    },
+    {
+      "id": "client",
+      "type": "package",
+      "package": "mosquitto"
     }
   ],
   "build": {
@@ -148,8 +153,7 @@
           "MESH_RECEIVES": "${dir:grants}/mesh.json",
           "MESH_PROVISION_MQTT": "127.0.0.1:${port:1883}",
           "MESH_PROVISION_ADMIN_USER": "mesh-admin",
-          "MESH_PROVISION_PASSWORD_FILE": "${dir:mesh-state}/admin",
-          "MESH_MQTT_CTRL_CONTAINER": "mosquitto"
+          "MESH_PROVISION_PASSWORD_FILE": "${dir:mesh-state}/admin"
         }
       }
     ]

modules/mosquitto/test/ctrl.test.ts

@@ -1,19 +0,0 @@
-// Run after `npm run build`.
-// mosquitto_ctrl runs inside the broker's own container when the manifest names it, so a machine
-// needs no mosquitto package (whose index may be too stale to install from) and the tool always
-// matches the broker's version.
-import assert from "node:assert/strict";
-import { test } from "node:test";
-import { MosquittoClient } from "../dist/client.js"; // compiled: client.ts uses parameter properties, which type stripping cannot run
-
-const env = { MESH_PROVISION_MQTT: "127.0.0.1:21883", MESH_MQTT_PASSWORD: "pw" };
-
-test("named, the broker's container runs mosquitto_ctrl", () => {
-  const c = MosquittoClient.fromEnv({ ...env, MESH_MQTT_CTRL_CONTAINER: "mosquitto" });
-  assert.deepEqual(c.ctrl(["dynsec", "listClients"]), ["docker", ["exec", "mosquitto", "mosquitto_ctrl", "dynsec", "listClients"]]);
-});
-
-test("unnamed, this machine's mosquitto_ctrl runs", () => {
-  const c = MosquittoClient.fromEnv(env);
-  assert.deepEqual(c.ctrl(["dynsec", "listClients"]), ["mosquitto_ctrl", ["dynsec", "listClients"]]);
-});

modules/mssql/Dockerfile

@@ -0,0 +1,43 @@
+# mssql'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
+# 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. The compiler
+# is invoked by its real path: node_modules/.bin entries are launcher symlinks the base image
+# resolved away.
+WORKDIR /app/modules/mssql
+COPY . .
+RUN node /app/node_modules/typescript/bin/tsc client.ts index.ts tools/index.ts provisioner/index.ts \
+      --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist
+
+# **sqlcmd, which this module's client drives, has to be here** — it never was, so every tool failed
+# with `spawn sqlcmd ENOENT`. go-sqlcmd is one static binary; fetched at a pinned release and checked
+# against its digest, so a build that receives anything else stops here.
+FROM ${BUILD_BASE} AS sqlcmd
+ARG SQLCMD_VERSION=v1.10.0
+ARG SQLCMD_SHA256=92516d98c63d99b0994de5b61350c91f6915f9b76f139a59039fbcb225c2e987
+RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates bzip2 \
+      && curl -fsSL -o /tmp/sqlcmd.tar.bz2 \
+           "https://github.com/microsoft/go-sqlcmd/releases/download/${SQLCMD_VERSION}/sqlcmd-linux-amd64.tar.bz2" \
+      && echo "${SQLCMD_SHA256}  /tmp/sqlcmd.tar.bz2" | sha256sum -c - \
+      && tar -xjf /tmp/sqlcmd.tar.bz2 -C /usr/local/bin sqlcmd
+
+FROM ${RUNTIME_BASE}
+COPY --from=sqlcmd /usr/local/bin/sqlcmd /usr/local/bin/sqlcmd
+COPY --from=build /app/modules/mssql/dist /app/modules/mssql/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. 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/mssql/dist/index.js,/app/modules/mssql/dist/tools/index.js,/app/modules/mssql/dist/provisioner/index.js

modules/mssql/client.ts

@@ -1,74 +1,22 @@
 // mssql's admin client — mssql's own code, living in the module (novox/hq ADR 0039). Both this
 // module's tools and its provisioner import it, and nothing outside mssql does.
 //
-// **The backend's own driver, inside the bundle** (novox/hq ADR 0198 §4). This used to shell out to
-// `sqlcmd`, a binary the module's container fetched; the module's code now runs in the node's
-// runtime, on machines whose system carries no SQL Server client, so it speaks TDS through the
-// `mssql` driver its package.json names — installed and inlined into the bundle by the builder. One
-// boundary, `session()`, and every method is built on it: a connection as one login to one database,
-// opened for one call and closed after, as one sqlcmd invocation was.
+// SQL is executed through `sqlcmd`, not a wire-protocol driver: the module may take NO npm
+// dependency beyond @novox/mesh-sdk, and hand-rolling the TDS handshake, pre-login and query
+// protocol is more surface than this should carry — so it shells out to the client the mssql
+// tools ship, the same way postgres drives itself through `psql`, minio through `mc`, and mailu
+// through doveadm. One boundary, `run()`, and every method is built on it.
 //
-// Structured rows still come back as JSON rendered by SQL Server itself (`FOR JSON`), so a tool's
-// answer is shaped exactly as it was: SQL Server owns the quoting and typing.
+// Structured rows come back as JSON: SQL Server itself renders the result with `FOR JSON`, and
+// this parses the single JSON document sqlcmd prints — far more robust than parsing sqlcmd's
+// column-aligned text, since SQL Server owns the quoting and typing.
 
-import { isIP } from "node:net";
 import { randomBytes } from "node:crypto";
 import { readFileSync } from "node:fs";
-import sql from "mssql";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
 
-/** Where a session connects, and as whom. */
-export interface Target {
-  readonly host: string;
-  readonly port: number;
-  readonly user: string;
-  readonly password: string;
-  readonly database: string;
-}
-
-/** One login's connection to one database: run a batch, answer the rows of its last result set. */
-export interface Session {
-  /** `params` are bound as NVARCHAR parameters (`@name`), never written into the text. */
-  run(text: string, params?: Record<string, string>): Promise<Record<string, unknown>[]>;
-  close(): Promise<void>;
-}
-
-/** How a session is opened — the driver, or a test's fake. */
-export type Connect = (to: Target) => Promise<Session>;
-
-/**
- * The driver's session: TLS, trusting the self-signed certificate the mssql image ships with (what
- * sqlcmd's `-C` did), one connection, closed with the session.
- */
-export const connectWithDriver: Connect = async (to) => {
-  const pool = new sql.ConnectionPool({
-    server: to.host,
-    port: to.port,
-    user: to.user,
-    password: to.password,
-    database: to.database,
-    // TLS names a host, never an address: Node refuses an IP as the server name (DEP0123, an error
-    // since Node 25), and the module reaches its server on loopback. The certificate is trusted
-    // either way, so the name only has to be one TLS accepts.
-    options: { encrypt: true, trustServerCertificate: true, ...(isIP(to.host) ? { serverName: "localhost" } : {}) },
-    pool: { min: 0, max: 1 },
-    connectionTimeout: 15_000,
-    requestTimeout: 60_000,
-  });
-  await pool.connect();
-  return {
-    async run(text, params = {}) {
-      const request = pool.request();
-      const names = Object.keys(params);
-      for (const name of names) request.input(name, sql.NVarChar, params[name]);
-      // A batch when nothing is bound — CREATE DATABASE must stand alone in its batch, which a
-      // parameterised query (sp_executesql) is not.
-      const result = names.length > 0 ? await request.query(text) : await request.batch(text);
-      const sets = (result.recordsets ?? []) as Record<string, unknown>[][];
-      return sets.length > 0 ? sets[sets.length - 1] : [];
-    },
-    close: () => pool.close(),
-  };
-};
+const run = promisify(execFile);
 
 export interface QueryResult {
   /** The leading keyword of the statement, e.g. "SELECT", "CREATE". */
@@ -97,17 +45,20 @@ export interface MssqlConn {
  */
 export const READER = "mesh_mssql_reader";
 
-/** Who a session logs in as. */
+/** Who a sqlcmd invocation logs in as, and whether the text is a caller's rather than the module's. */
 interface Invocation {
   readonly user: string;
   readonly password: string;
+  /**
+   * A caller's text: sqlcmd substitutes no `$(NAME)` in it, which would read this process's
+   * environment — the administrator's password among it. (Its own commands are kept out by the
+   * caller's text never beginning a line; see readOnlyQuery.)
+   */
+  readonly caller: boolean;
 }
 
 export class MssqlClient {
-  constructor(
-    private readonly conn: MssqlConn,
-    private readonly connect: Connect = connectWithDriver,
-  ) {}
+  constructor(private readonly conn: MssqlConn) {}
 
   /** The reader is made once per process: idempotent, and repeating it re-sets a rotated password. */
   private readerReady?: Promise<void>;
@@ -139,41 +90,63 @@ export class MssqlClient {
     return this.conn.port;
   }
 
-  /** Execute a batch that returns no rows (DDL and the like). A failed statement rejects. */
-  async exec(text: string, database = "master"): Promise<void> {
-    await this.session(text, database);
+  /**
+   * Execute a batch that returns no rows (DDL and the like), through `sqlcmd`. The password is
+   * passed by SQLCMDPASSWORD, never on argv, the way postgres passes PGPASSWORD; `-b` makes a
+   * failed statement an error here rather than a success with a warning, and `-C` trusts the
+   * server's self-signed certificate the mssql image ships with.
+   */
+  async exec(sql: string, database = "master"): Promise<void> {
+    await this.sqlcmd(sql, database);
   }
 
   /**
    * Run a SELECT and return its rows as objects. The caller's SQL must be a single SELECT; it is
-   * wrapped so SQL Server renders the result with `FOR JSON PATH`, and the JSON document it answers
-   * (split across rows for a large result, and reassembled here) is parsed. An empty result yields
-   * no rows — an empty array. `params` are bound as `@name`, never written into the text.
+   * wrapped so SQL Server renders the result with `FOR JSON PATH`, and the JSON document sqlcmd
+   * prints (split across output lines for a large result, and reassembled here) is parsed. An
+   * empty result yields no output at all — an empty array.
    */
   async query(
     select: string,
     database = "master",
-    params: Record<string, string> = {},
+    variables: Record<string, string> = {},
   ): Promise<Record<string, unknown>[]> {
     const wrapped = `SET NOCOUNT ON;\n${stripTrailingSemis(select)}\nFOR JSON PATH, INCLUDE_NULL_VALUES;`;
-    return parseJsonRows(await this.session(wrapped, database, params));
+    const stdout = await this.sqlcmd(wrapped, database, variables);
+    return parseJsonRows(stdout);
   }
 
-  /** The one execution boundary: open a session as `as`, run `text`, close it. */
-  private async session(
-    text: string,
+  /** The one execution boundary: invoke `sqlcmd` and return its concatenated stdout. */
+  private async sqlcmd(
+    sql: string,
     database: string,
-    params: Record<string, string> = {},
-    as: Invocation = { user: this.conn.user, password: this.conn.password },
-  ): Promise<Record<string, unknown>[]> {
-    const session = await this.connect({
-      host: this.conn.host, port: this.conn.port, user: as.user, password: as.password, database,
-    });
-    try {
-      return await session.run(text, params);
-    } finally {
-      await session.close();
-    }
+    variables: Record<string, string> = {},
+    as: Invocation = { user: this.conn.user, password: this.conn.password, caller: false },
+  ): Promise<string> {
+    // `-h -1` drops the column-header rule; `-y 0`/`-Y 0` lift the display-width cap so a long
+    // JSON document is not truncated; `-W` trims trailing whitespace so the JSON chunks rejoin
+    // cleanly. sqlcmd from the mssql-tools ships in the runtime container, the way `psql` ships
+    // with postgres's — the module owns its own code (ADR 0039) and shells out to it.
+    const { stdout } = await run(
+      "sqlcmd",
+      [
+        "-S", `${this.conn.host},${this.conn.port}`,
+        "-U", as.user,
+        "-d", database,
+        ...(as.caller ? ["-x"] : []),
+        "-C",
+        "-b",
+        "-h", "-1",
+        "-y", "0",
+        "-Y", "0",
+        "-W",
+        "-Q", sql,
+      ],
+      // `variables` reach sqlcmd as environment variables, which it substitutes as `$(NAME)` scripting
+      // variables: a value that must not appear on argv, or in the message of a failed command.
+      { env: { ...process.env, ...variables, SQLCMDPASSWORD: as.password }, maxBuffer: 16 << 20 },
+    );
+    return stdout;
   }
 
   /**
@@ -200,7 +173,7 @@ export class MssqlClient {
       `SELECT 1 AS ok FROM sys.databases WHERE name = ${literal(database)}`,
     );
     if (dbs.length === 0) {
-      // CREATE DATABASE must stand alone in its batch; it runs as its own session.
+      // CREATE DATABASE must stand alone in its batch; it runs as its own sqlcmd invocation.
       await this.exec(`CREATE DATABASE ${ident(database)}`);
     }
 
@@ -233,14 +206,15 @@ export class MssqlClient {
    * nothing logs in and no failed-login is recorded (novox/hq issue 120).
    */
   async holdsLogin(database: string, login: string, password: string): Promise<boolean> {
-    // The password is a bound parameter, never inside the query text, so it is in no message of a
-    // failed statement.
+    // The password reaches sqlcmd as a scripting variable from the environment, never inside the
+    // query text, so it is neither on argv nor in the message of a failed command. It is the mesh's
+    // minted value, which carries no quote.
     const server = await this.query(
       `SELECT CAST(CASE WHEN EXISTS (SELECT 1 FROM sys.sql_logins WHERE name = ${literal(login)} ` +
-        `AND is_disabled = 0 AND PWDCOMPARE(@meshholdspw, password_hash) = 1) ` +
+        `AND is_disabled = 0 AND PWDCOMPARE(N'$(MESHHOLDSPW)', password_hash) = 1) ` +
         `AND DB_ID(${literal(database)}) IS NOT NULL THEN 1 ELSE 0 END AS int) AS ok`,
       "master",
-      { meshholdspw: password },
+      { MESHHOLDSPW: password },
     );
     if (Number(server[0]?.ok) !== 1) return false;
     // The user must be this login's, by SID, and a db_owner. A user orphaned by a restore has the
@@ -320,27 +294,35 @@ export class MssqlClient {
    * (novox/hq issue 193). Read-only by the login, not by a transaction wrapped around the text; the
    * rows are rendered by FOR JSON. Never as the administrator: without the reader's password the call
    * is refused.
-   *
-   * The text goes to the server as it is, over the driver: there is no client between that reads a
-   * line of its own (sqlcmd's `:!!`, which could start a program) or substitutes `$(NAME)` from this
-   * process's environment, so neither the one-line rule nor `-x` has anything left to guard.
    */
-  async readOnlyQuery(database: string, text: string): Promise<QueryResult> {
+  async readOnlyQuery(database: string, sql: string): Promise<QueryResult> {
     const password = this.conn.readerPassword;
     if (!password) throw readerMissing();
+    // **One line, refused otherwise.** sqlcmd reads a line that BEGINS with `:` or `!!` as its own
+    // command rather than SQL, and `:!!` starts a program in this container, which holds the
+    // administrator's password. Its switch for refusing those (-X) makes it ignore -Q in the
+    // version shipped here, so instead no line of a caller's text can begin one: the text follows
+    // this module's own on the first line, and a line break in it is refused. Proven on a throwaway
+    // server: the same text at the start of a line ran a program; mid-line it is a syntax error.
+    if (/[\r\n]/.test(sql)) {
+      throw new Error(
+        "mssql_query: the statement must be one line — sqlcmd takes a line beginning with ':' or " +
+          "'!!' as a command of its own, which can start a program (novox/hq issue 193)",
+      );
+    }
     this.readerReady ??= this.ensureReader().catch((err) => {
       this.readerReady = undefined; // asked again next call, not failed for the process's life
       throw err;
     });
     await this.readerReady;
-    const rows = await this.session(
-      `SET NOCOUNT ON; ${stripTrailingSemis(text)}\nFOR JSON PATH, INCLUDE_NULL_VALUES;`,
+    const stdout = await this.sqlcmd(
+      `SET NOCOUNT ON; ${stripTrailingSemis(sql)}\nFOR JSON PATH, INCLUDE_NULL_VALUES;`,
       database,
       {},
-      { user: READER, password },
+      { user: READER, password, caller: true },
     );
-    const command = /^\s*([A-Za-z]+)/.exec(text)?.[1]?.toUpperCase() ?? "";
-    return { command, rows: parseJsonRows(rows) };
+    const command = /^\s*([A-Za-z]+)/.exec(sql)?.[1]?.toUpperCase() ?? "";
+    return { command, rows: parseJsonRows(stdout) };
   }
 }
 
@@ -390,13 +372,18 @@ function safeUrl(raw: string): URL | undefined {
 }
 
 /**
- * Parse the JSON a FOR JSON query answers. SQL Server splits a large FOR JSON result into
- * ~2033-character chunks, one per row of a single column, so the document is reassembled by
- * concatenating that column in order. No rows (an empty result, or a pure DDL batch) means none.
+ * Parse the JSON a FOR JSON query prints through sqlcmd. SQL Server splits a large FOR JSON result
+ * into ~2033-character chunks, one per output row; with `-h -1 -W` each lands on its own line, so
+ * the document is reassembled by concatenating the non-empty lines. No output (an empty result, or
+ * a pure DDL batch) means no rows.
  */
-function parseJsonRows(rows: Record<string, unknown>[]): Record<string, unknown>[] {
-  const joined = rows.map((row) => String(Object.values(row)[0] ?? "")).join("");
-  if (joined.trim().length === 0) return [];
+function parseJsonRows(stdout: string): Record<string, unknown>[] {
+  const joined = stdout
+    .split(/\r?\n/)
+    .map((l) => l.trimEnd())
+    .filter((l) => l.length > 0)
+    .join("");
+  if (joined.length === 0) return [];
   const parsed = JSON.parse(joined);
   return Array.isArray(parsed) ? (parsed as Record<string, unknown>[]) : [parsed as Record<string, unknown>];
 }

modules/mssql/index.ts

@@ -1,9 +1,9 @@
-// mssql's events entrypoint, launched by the node's runtime beside its tools and provisioner
-// (novox/hq ADR 0198). The database lifecycle events are EMITTED from the provisioner, where
+// mssql's events entrypoint, loaded by the per-node tool host (the provisioner container runs
+// ./provisioner separately). The database lifecycle events are EMITTED from the provisioner, where
 // the lifecycle actually happens (novox/hq ADR 0041/0042):
 //   module.mssql.database.provisioned    — a consumer's database + login/user was created
 //   module.mssql.database.deprovisioned  — that database was removed
-// Here in the runtime we react to them, keeping a lightweight audit trail of who was granted a
+// Here in the tool host we react to them, keeping a lightweight audit trail of who was granted a
 // database and who lost one — observability the provider itself is best placed to log.
 
 import { on } from "@novox/mesh-sdk/events";

modules/mssql/module.json

@@ -38,9 +38,16 @@
   },
   "own-secrets": {
     "sa": "${dir:state}/sa.secret",
+    "broker": "${dir:mesh-state}/broker",
     "reader": "${dir:state}/reader.secret"
   },
   "resources": [
+    {
+      "id": "mesh-state",
+      "type": "directory",
+      "mode": "0700",
+      "place": "mesh"
+    },
     {
       "id": "state",
       "type": "directory",
@@ -86,30 +93,46 @@
         "${dir:data}:/var/opt/mssql"
       ],
       "secrets-in-environment": "the image documents only MSSQL_SA_PASSWORD, no _FILE and no configuration field; not convertible without a wrapper entrypoint"
+    },
+    {
+      "id": "runtime",
+      "type": "container",
+      "name": "mesh-mssql",
+      "network": "mssql",
+      "volumes": [
+        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
+        "${dir:grants}:/var/lib/mssql/grants:ro",
+        "${dir:state}/sa.secret:/run/secrets/sa:ro",
+        "${dir:state}/reader.secret:/run/secrets/reader:ro"
+      ],
+      "env": {
+        "MESH_PROVISION_MSSQL": "mssql://sa@mssql:1433/master",
+        "MESH_PROVISION_PASSWORD_FILE": "/run/secrets/sa",
+        "MESH_BROKER_FILE": "/run/secrets/broker",
+        "MESH_RECEIVES": "/var/lib/mssql/grants/mesh.json",
+        "MESH_MSSQL_READER_PASSWORD_FILE": "/run/secrets/reader"
+      },
+      "artifact": "runtime"
     }
   ],
   "build": {
+    "on": [
+      {
+        "arg": "BUILD_BASE",
+        "module": "mesh-tools",
+        "artifact": "build"
+      },
+      {
+        "arg": "RUNTIME_BASE",
+        "module": "mesh-tools",
+        "artifact": "runtime"
+      }
+    ],
     "artifacts": [
       {
-        "name": "code",
-        "kind": "bundle",
-        "language": "typescript",
-        "entrypoints": [
-          "index.js",
-          "tools/index.js",
-          "provisioner/index.js"
-        ],
-        "loads": [
-          "index.js",
-          "tools/index.js",
-          "provisioner/index.js"
-        ],
-        "env": {
-          "MESH_PROVISION_MSSQL": "mssql://sa@127.0.0.1:${port:1433}/master",
-          "MESH_PROVISION_PASSWORD_FILE": "${dir:state}/sa.secret",
-          "MESH_RECEIVES": "${dir:grants}/mesh.json",
-          "MESH_MSSQL_READER_PASSWORD_FILE": "${dir:state}/reader.secret"
-        }
+        "name": "runtime",
+        "kind": "image",
+        "from": "Dockerfile"
       }
     ]
   }

modules/mssql/mssql.d.ts

@@ -1,32 +0,0 @@
-// Ambient types for `mssql`, which ships its types only in the separate `@types/mssql` package. This
-// declares the slice client.ts uses — the precedent mesh-catalog's pg.d.ts sets — so the module
-// type-checks without deciding what runs: the real `mssql` is the package.json dependency the
-// builder installs and inlines into the bundle (novox/hq ADR 0198 §4).
-declare module "mssql" {
-  interface Result {
-    recordsets: unknown;
-  }
-  interface Request {
-    input(name: string, type: unknown, value: unknown): Request;
-    query(text: string): Promise<Result>;
-    batch(text: string): Promise<Result>;
-  }
-  class ConnectionPool {
-    constructor(config: {
-      server: string;
-      port?: number;
-      user?: string;
-      password?: string;
-      database?: string;
-      options?: { encrypt?: boolean; trustServerCertificate?: boolean; serverName?: string };
-      pool?: { min?: number; max?: number };
-      connectionTimeout?: number;
-      requestTimeout?: number;
-    });
-    connect(): Promise<ConnectionPool>;
-    request(): Request;
-    close(): Promise<void>;
-  }
-  const sql: { ConnectionPool: typeof ConnectionPool; NVarChar: unknown };
-  export default sql;
-}

modules/mssql/package.json

@@ -5,12 +5,11 @@
   "type": "module",
   "private": true,
   "scripts": {
-    "build": "tsc mssql.d.ts client.ts index.ts tools/index.ts provisioner/index.ts --module NodeNext --moduleResolution NodeNext --target ES2022 --outDir dist",
+    "build": "tsc client.ts index.ts tools/index.ts provisioner/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",
-    "mssql": "^11.0.2"
+    "@novox/mesh-sdk": "^0.1.1"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

modules/mssql/test/reader.test.ts

@@ -1,83 +1,96 @@
 // What holds mssql_query to being read-only (novox/hq issue 193): a caller's statement runs as the
-// reader login and never as the administrator, with no transaction wrapped around it as text, and
-// without the reader's password the statement is refused.
+// reader login and never as the administrator, with sqlcmd's variable substitution off, on one line
+// that follows the module's own — a line break is refused before sqlcmd starts — and with no
+// transaction wrapped around it as text. Without the reader's password the statement is refused.
 //
-// The driver is a fake session that records each call's login, database, text and bound
-// parameters. That the reader cannot write is the server's to enforce and was proven against a real
-// server; this holds the module to asking for it. Run against the compiled module (npm test builds
-// first), the way the runtime loads it.
+// sqlcmd is a fake on PATH that records each call's login, flags and text. That the reader cannot
+// write is the server's to enforce and was proven against a real server; this holds the module to
+// asking for it. Run against the compiled module (npm test builds first), the way the runtime loads it.
 
-import { test } from "node:test";
+import { test, before, after } from "node:test";
 import assert from "node:assert/strict";
+import { chmod, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 
-import { MssqlClient, READER, type Connect, type Target } from "../dist/client.js";
+import { MssqlClient, READER } from "../dist/client.js";
 
-interface Call extends Target {
-  text: string;
-  params: Record<string, string>;
-}
+let dir: string;
+let log: string;
+const originalPath = process.env.PATH;
 
-function recording(): { connect: Connect; calls: Call[] } {
-  const calls: Call[] = [];
-  const connect: Connect = async (to) => ({
-    async run(text, params = {}) {
-      calls.push({ ...to, text, params });
-      if (/FROM sys.server_principals/.test(text)) return [];
-      // FOR JSON answers its document split across rows of one column.
-      if (/FOR JSON/.test(text)) return [{ JSON_F52E: '[{"name":"al' }, { JSON_F52E: 'pha","n":1}]' }];
-      return [];
-    },
-    async close() {},
+before(async () => {
+  dir = await mkdtemp(join(tmpdir(), "mssql-reader-"));
+  log = join(dir, "calls.jsonl");
+  await writeFile(join(dir, "sqlcmd"), `#!/usr/bin/env node
+const fs = require("node:fs");
+const args = process.argv.slice(2);
+const at = (flag) => args[args.indexOf(flag) + 1];
+fs.appendFileSync(${JSON.stringify(log)}, JSON.stringify({
+  user: at("-U"), database: at("-d"), sql: at("-Q"), noVariables: args.includes("-x"),
+  password: process.env.SQLCMDPASSWORD,
+}) + "\\n");
+const sql = at("-Q");
+if (/FROM sys.server_principals/.test(sql)) process.stdout.write("");
+else if (/FOR JSON/.test(sql)) process.stdout.write('[{"name":"alpha","n":1}]\\n');
+`);
+  await chmod(join(dir, "sqlcmd"), 0o755);
+  process.env.PATH = `${dir}:${originalPath}`;
 });
-  return { connect, calls };
+
+after(async () => {
+  process.env.PATH = originalPath;
+  await rm(dir, { recursive: true, force: true });
+});
+
+async function calls(): Promise<Record<string, unknown>[]> {
+  const text = await readFile(log, "utf8").catch(() => "");
+  await writeFile(log, "");
+  return text.split("\n").filter(Boolean).map((line) => JSON.parse(line));
 }
 
 const conn = { host: "127.0.0.1", port: 1433, user: "sa", password: "admin-secret" };
 
-test("a caller's statement runs as the reader, as it was written, on the database it names", async () => {
-  const { connect, calls } = recording();
-  const client = new MssqlClient({ ...conn, readerPassword: "reader-secret" }, connect);
+test("a caller's statement runs as the reader, without variables, on the module's first line", async () => {
+  const client = new MssqlClient({ ...conn, readerPassword: "reader-secret" });
   const result = await client.readOnlyQuery("inventory", "SELECT '$(SQLCMDPASSWORD)' AS p");
 
-  const asked = calls.at(-1)!;
+  const asked = (await calls()).at(-1)!;
   assert.equal(asked.user, READER, "the statement never runs as the administrator");
   assert.equal(asked.password, "reader-secret");
-  assert.equal(asked.database, "inventory");
-  assert.ok(asked.text.startsWith("SET NOCOUNT ON; SELECT '$(SQLCMDPASSWORD)' AS p\nFOR JSON PATH"),
-    "the caller's text reaches the server unaltered");
-  assert.doesNotMatch(asked.text, /BEGIN TRANSACTION|ROLLBACK/, "no transaction wrapped around it as text");
-  assert.deepEqual(result.rows, [{ name: "alpha", n: 1 }], "a FOR JSON document split across rows is reassembled");
+  assert.equal(asked.noVariables, true, "no $(NAME) is substituted in a caller's text");
+  const [first] = String(asked.sql).split("\n");
+  assert.ok(first.startsWith("SET NOCOUNT ON; SELECT '$(SQLCMDPASSWORD)'"), "the caller's text never begins a line");
+  assert.doesNotMatch(String(asked.sql), /BEGIN TRANSACTION|ROLLBACK/, "no transaction wrapped around it as text");
+  assert.deepEqual(result.rows, [{ name: "alpha", n: 1 }]);
   assert.equal(result.command, "SELECT");
 });
 
+test("a line break in a caller's statement is refused before sqlcmd starts", async () => {
+  const client = new MssqlClient({ ...conn, readerPassword: "reader-secret" });
+  for (const sql of ["SELECT 1\n:!! id", "SELECT 1\r\n:!! id", "SELECT 1\r:!! id"]) {
+    await assert.rejects(client.readOnlyQuery("inventory", sql), /must be one line/);
+  }
+  assert.deepEqual(await calls(), []);
+});
+
 test("the reader is made as the administrator, kept out of sysadmin, and granted only reading", async () => {
-  const { connect, calls } = recording();
-  const client = new MssqlClient({ ...conn, readerPassword: "reader-secret" }, connect);
+  const client = new MssqlClient({ ...conn, readerPassword: "reader-secret" });
   await client.readOnlyQuery("inventory", "SELECT 1 AS x");
   await client.readOnlyQuery("inventory", "SELECT 2 AS x");
 
-  const asAdmin = calls.filter((c) => c.user === "sa").map((c) => c.text);
+  const made = await calls();
+  const asAdmin = made.filter((c) => c.user === "sa").map((c) => String(c.sql));
   assert.ok(asAdmin.some((s) => s.startsWith(`CREATE LOGIN [${READER}]`)));
   assert.ok(asAdmin.some((s) => /ALTER SERVER ROLE sysadmin DROP MEMBER/.test(s)));
   assert.ok(asAdmin.includes(`GRANT CONNECT ANY DATABASE TO [${READER}]`));
   assert.ok(asAdmin.includes(`GRANT SELECT ALL USER SECURABLES TO [${READER}]`));
   assert.equal(asAdmin.filter((s) => s.startsWith("CREATE LOGIN")).length, 1, "made once, not per call");
-  assert.equal(calls.filter((c) => c.user === READER).length, 2);
+  assert.equal(made.filter((c) => c.user === READER).length, 2);
 });
 
 test("without the reader's password the statement is refused, and nothing runs as the administrator", async () => {
-  const { connect, calls } = recording();
-  const client = new MssqlClient(conn, connect);
+  const client = new MssqlClient(conn);
   await assert.rejects(client.readOnlyQuery("inventory", "SELECT 1"), /refused rather than run as the administrator/);
-  assert.deepEqual(calls, []);
-});
-
-test("a consumer's password is checked as a bound parameter, never in the text", async () => {
-  const { connect, calls } = recording();
-  const client = new MssqlClient(conn, connect);
-  await client.holdsLogin("shop", "shop_login", "minted-secret");
-  const asked = calls[0];
-  assert.equal(asked.params.meshholdspw, "minted-secret");
-  assert.doesNotMatch(asked.text, /minted-secret/);
-  assert.match(asked.text, /PWDCOMPARE\(@meshholdspw, password_hash\)/);
+  assert.deepEqual(await calls(), []);
 });

modules/mssql/tsconfig.json

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

modules/netcheck/cmd/netcheck/checks.go

@@ -1,173 +0,0 @@
-package main
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"math"
-	"net"
-	"sort"
-	"strconv"
-	"strings"
-	"time"
-)
-
-// Bounds on what a caller may ask: a check is a probe, never a wait anyone can make long.
-const (
-	DefaultTimeout = 3 * time.Second
-	MostTimeout    = 30 * time.Second
-)
-
-// TCPResult is what netcheck_tcp answers.
-type TCPResult struct {
-	Host      string `json:"host"`
-	Port      int    `json:"port"`
-	Address   string `json:"address,omitempty"`
-	Reachable bool   `json:"reachable"`
-	ElapsedMS int64  `json:"elapsed_ms"`
-	Error     string `json:"error,omitempty"`
-}
-
-// CheckTCP opens one TCP connection and closes it, sending nothing. A port that refuses or a host
-// that does not answer is a result, not a failure of the tool; only a malformed question is.
-func CheckTCP(host string, port int, timeout time.Duration) (TCPResult, error) {
-	if port < 1 || port > 65535 {
-		return TCPResult{}, fmt.Errorf("port %d is not a TCP port (1-65535)", port)
-	}
-	out := TCPResult{Host: host, Port: port}
-	start := time.Now()
-	conn, err := net.DialTimeout("tcp", net.JoinHostPort(host, strconv.Itoa(port)), timeout)
-	out.ElapsedMS = time.Since(start).Milliseconds()
-	if err != nil {
-		out.Error = err.Error()
-		return out, nil
-	}
-	out.Address = conn.RemoteAddr().String()
-	out.Reachable = true
-	_ = conn.Close()
-	return out, nil
-}
-
-// DNSResult is what netcheck_dns answers.
-type DNSResult struct {
-	Name      string   `json:"name"`
-	Type      string   `json:"type"`
-	Answers   []string `json:"answers"`
-	ElapsedMS int64    `json:"elapsed_ms"`
-	Error     string   `json:"error,omitempty"`
-}
-
-// DNSTypes are the record types netcheck_dns looks up.
-var DNSTypes = []string{"A", "AAAA", "CNAME", "TXT", "MX"}
-
-// CheckDNS looks a name up with the machine's resolver. Built without cgo, Go's own resolver reads
-// the machine's /etc/resolv.conf and /etc/hosts, which is the resolver this machine's programs use.
-// A name that does not resolve is a result with its error; an unknown type is refused.
-func CheckDNS(name, kind string, timeout time.Duration) (DNSResult, error) {
-	kind = strings.ToUpper(strings.TrimSpace(kind))
-	if kind == "" {
-		kind = "A"
-	}
-	known := false
-	for _, t := range DNSTypes {
-		known = known || t == kind
-	}
-	if !known {
-		return DNSResult{}, fmt.Errorf("type %q is not one netcheck_dns looks up (%s)", kind, strings.Join(DNSTypes, ", "))
-	}
-	out := DNSResult{Name: name, Type: kind, Answers: []string{}}
-	ctx, cancel := context.WithTimeout(context.Background(), timeout)
-	defer cancel()
-	r := net.DefaultResolver
-	start := time.Now()
-	var err error
-	switch kind {
-	case "A", "AAAA":
-		network := "ip4"
-		if kind == "AAAA" {
-			network = "ip6"
-		}
-		var ips []net.IP
-		if ips, err = r.LookupIP(ctx, network, name); err == nil {
-			for _, ip := range ips {
-				out.Answers = append(out.Answers, ip.String())
-			}
-		}
-	case "CNAME":
-		var cname string
-		if cname, err = r.LookupCNAME(ctx, name); err == nil {
-			out.Answers = append(out.Answers, cname)
-		}
-	case "TXT":
-		var txts []string
-		if txts, err = r.LookupTXT(ctx, name); err == nil {
-			out.Answers = append(out.Answers, txts...)
-		}
-	case "MX":
-		var mxs []*net.MX
-		if mxs, err = r.LookupMX(ctx, name); err == nil {
-			for _, mx := range mxs {
-				out.Answers = append(out.Answers, fmt.Sprintf("%d %s", mx.Pref, mx.Host))
-			}
-		}
-	}
-	out.ElapsedMS = time.Since(start).Milliseconds()
-	if err != nil {
-		out.Error = err.Error()
-	}
-	if kind != "MX" {
-		sort.Strings(out.Answers)
-	}
-	return out, nil
-}
-
-// text is a required string argument.
-func text(args map[string]any, key string) (string, error) {
-	s, _ := args[key].(string)
-	s = strings.TrimSpace(s)
-	if s == "" {
-		return "", fmt.Errorf("%s is required", key)
-	}
-	return s, nil
-}
-
-// whole is an integer argument, given as a JSON number or a numeric string; fallback when absent.
-func whole(args map[string]any, key string, fallback int) (int, error) {
-	v, given := args[key]
-	if !given || v == nil {
-		if fallback == 0 {
-			return 0, fmt.Errorf("%s is required", key)
-		}
-		return fallback, nil
-	}
-	switch n := v.(type) {
-	case float64:
-		if n != math.Trunc(n) {
-			return 0, fmt.Errorf("%s must be a whole number, not %v", key, n)
-		}
-		return int(n), nil
-	case string:
-		i, err := strconv.Atoi(strings.TrimSpace(n))
-		if err != nil {
-			return 0, fmt.Errorf("%s must be a whole number, not %q", key, n)
-		}
-		return i, nil
-	}
-	return 0, errors.New(key + " must be a whole number")
-}
-
-// timeoutOf is timeout_ms, defaulted and bounded.
-func timeoutOf(args map[string]any) (time.Duration, error) {
-	ms, err := whole(args, "timeout_ms", int(DefaultTimeout/time.Millisecond))
-	if err != nil {
-		return 0, err
-	}
-	if ms < 1 {
-		return 0, fmt.Errorf("timeout_ms must be at least 1, not %d", ms)
-	}
-	d := time.Duration(ms) * time.Millisecond
-	if d > MostTimeout {
-		d = MostTimeout
-	}
-	return d, nil
-}

modules/netcheck/cmd/netcheck/checks_test.go

@@ -1,68 +0,0 @@
-package main
-
-import (
-	"net"
-	"testing"
-	"time"
-)
-
-func TestATCPPortThatListensIsReachableAndOneThatDoesNotIsNot(t *testing.T) {
-	l, err := net.Listen("tcp", "127.0.0.1:0")
-	if err != nil {
-		t.Fatal(err)
-	}
-	port := l.Addr().(*net.TCPAddr).Port
-	got, err := CheckTCP("127.0.0.1", port, time.Second)
-	if err != nil || !got.Reachable || got.Error != "" {
-		t.Fatalf("a listening port: %+v, %v", got, err)
-	}
-	l.Close()
-	got, err = CheckTCP("127.0.0.1", port, time.Second)
-	if err != nil || got.Reachable || got.Error == "" {
-		t.Fatalf("a closed port is reported as a result with its error, not a failure: %+v, %v", got, err)
-	}
-}
-
-func TestAPortOutsideTheRangeIsRefused(t *testing.T) {
-	for _, p := range []int{0, -1, 65536} {
-		if _, err := CheckTCP("127.0.0.1", p, time.Second); err == nil {
-			t.Errorf("port %d was accepted", p)
-		}
-	}
-}
-
-func TestDNSAnswersFromTheMachinesResolverAndRefusesAnUnknownType(t *testing.T) {
-	got, err := CheckDNS("localhost", "a", time.Second)
-	if err != nil || got.Type != "A" || len(got.Answers) == 0 {
-		t.Fatalf("localhost A: %+v, %v", got, err)
-	}
-	if _, err := CheckDNS("localhost", "SRV", time.Second); err == nil {
-		t.Fatal("an unknown record type was accepted")
-	}
-	got, err = CheckDNS("no-such-name.invalid", "A", time.Second)
-	if err != nil || got.Error == "" || len(got.Answers) != 0 {
-		t.Fatalf("a name that does not resolve is a result with its error: %+v, %v", got, err)
-	}
-}
-
-func TestTimeoutIsDefaultedAndBounded(t *testing.T) {
-	if d, _ := timeoutOf(map[string]any{}); d != DefaultTimeout {
-		t.Errorf("default: %v", d)
-	}
-	if d, _ := timeoutOf(map[string]any{"timeout_ms": float64(10 * 60 * 1000)}); d != MostTimeout {
-		t.Errorf("bounded: %v", d)
-	}
-	if _, err := timeoutOf(map[string]any{"timeout_ms": float64(0)}); err == nil {
-		t.Error("a zero timeout was accepted")
-	}
-}
-
-func TestBothToolsAreListedUnprefixed(t *testing.T) {
-	names := map[string]bool{}
-	for _, tool := range tools() {
-		names[tool.Name] = true
-	}
-	if !names["netcheck_tcp"] || !names["netcheck_dns"] || len(names) != 2 {
-		t.Fatalf("tools: %v", names)
-	}
-}

modules/netcheck/cmd/netcheck/main.go

@@ -1,72 +0,0 @@
-// netcheck's Go tools bundle (novox/hq ADR 0188, ADR 0193): a process the node's runtime launches
-// and speaks MCP over stdio to, through the Go SDK. It serves the two checks that are the machine's
-// own sockets and resolver — a TCP connect and a DNS lookup — and nothing that changes anything.
-// The module's HTTP check is its TypeScript bundle; the runtime serves both under one module.
-package main
-
-import (
-	"fmt"
-	"os"
-
-	stdio "git.novox.be/novox/mesh-sdk/go"
-)
-
-func main() {
-	// An empty name serves as the module the runtime names (MESH_SERVED_MODULE): netcheck.
-	if err := stdio.Serve("", tools()); err != nil {
-		fmt.Fprintln(os.Stderr, err)
-		os.Exit(1)
-	}
-}
-
-func tools() []stdio.Tool {
-	return []stdio.Tool{
-		{
-			Name: "netcheck_tcp",
-			Description: "Check whether a TCP port is reachable from this machine: opens one connection " +
-				"and closes it at once, sending nothing. Answers reachable, elapsed_ms and the error when not.",
-			Input: map[string]any{
-				"host":       map[string]any{"type": "string", "description": "host name or IP address"},
-				"port":       map[string]any{"type": "integer", "description": "TCP port, 1-65535"},
-				"timeout_ms": map[string]any{"type": "integer", "description": "give up after this long (default 3000, at most 30000)"},
-			},
-			Run: func(args map[string]any) (any, error) {
-				host, err := text(args, "host")
-				if err != nil {
-					return nil, err
-				}
-				port, err := whole(args, "port", 0)
-				if err != nil {
-					return nil, err
-				}
-				timeout, err := timeoutOf(args)
-				if err != nil {
-					return nil, err
-				}
-				return CheckTCP(host, port, timeout)
-			},
-		},
-		{
-			Name: "netcheck_dns",
-			Description: "Look a name up with this machine's resolver (its /etc/resolv.conf and /etc/hosts). " +
-				"type is A, AAAA, CNAME, TXT or MX; answers the records found, or the error.",
-			Input: map[string]any{
-				"name":       map[string]any{"type": "string", "description": "the name to look up"},
-				"type":       map[string]any{"type": "string", "enum": []string{"A", "AAAA", "CNAME", "TXT", "MX"}, "description": "record type (default A)"},
-				"timeout_ms": map[string]any{"type": "integer", "description": "give up after this long (default 3000, at most 30000)"},
-			},
-			Run: func(args map[string]any) (any, error) {
-				name, err := text(args, "name")
-				if err != nil {
-					return nil, err
-				}
-				kind, _ := args["type"].(string)
-				timeout, err := timeoutOf(args)
-				if err != nil {
-					return nil, err
-				}
-				return CheckDNS(name, kind, timeout)
-			},
-		},
-	}
-}

modules/netcheck/go.mod

@@ -1,5 +0,0 @@
-module netcheck
-
-go 1.22
-
-require git.novox.be/novox/mesh-sdk/go v0.1.6

modules/netcheck/go.sum

@@ -1,2 +0,0 @@
-git.novox.be/novox/mesh-sdk/go v0.1.6 h1:9qzdYONYbJdWcu6sxQcq9v1LI0JxcfkiKYkMUzJSkVQ=
-git.novox.be/novox/mesh-sdk/go v0.1.6/go.mod h1:GFuZUElBZ9A++mxgIKo97aXXo+kV0uJ/UkbhQPPIbrY=

modules/netcheck/http.ts

@@ -1,84 +0,0 @@
-// netcheck's HTTP check — the module's own code, in TypeScript (novox/hq ADR 0039, ADR 0188). One
-// request, HEAD or GET, never a body sent and never a body read: the status, how long it took and
-// a few headers that say what answered. Redirects are reported, not followed, so a check reaches
-// exactly the address it was given.
-
-export const METHODS = ["HEAD", "GET"] as const;
-export type Method = (typeof METHODS)[number];
-
-/** The headers worth reporting: what answered and what it says it is, nothing it set for a client. */
-export const REPORTED_HEADERS = [
-  "content-type", "content-length", "server", "location", "date",
-  "cache-control", "last-modified", "etag",
-] as const;
-
-export const DEFAULT_TIMEOUT_MS = 5000;
-export const MOST_TIMEOUT_MS = 30000;
-
-export interface HttpResult {
-  url: string;
-  method: Method;
-  status?: number;
-  statusText?: string;
-  elapsed_ms: number;
-  headers: Record<string, string>;
-  error?: string;
-}
-
-/** Only http and https are checked; anything else — file:, data:, ftp: — is refused by name. */
-export function checkedUrl(raw: unknown): URL {
-  const text = typeof raw === "string" ? raw.trim() : "";
-  if (!text) throw new Error("url is required");
-  let url: URL;
-  try {
-    url = new URL(text);
-  } catch {
-    throw new Error(`${JSON.stringify(text)} is not a URL`);
-  }
-  if (url.protocol !== "http:" && url.protocol !== "https:") {
-    throw new Error(`netcheck_http checks http and https URLs only, not ${url.protocol}`);
-  }
-  return url;
-}
-
-export function checkedMethod(raw: unknown): Method {
-  const m = (typeof raw === "string" && raw.trim() ? raw.trim() : "HEAD").toUpperCase();
-  if (!(METHODS as readonly string[]).includes(m)) {
-    throw new Error(`method ${m} is not one netcheck_http uses (${METHODS.join(", ")}): a check never changes anything`);
-  }
-  return m as Method;
-}
-
-export function checkedTimeout(raw: unknown): number {
-  if (raw === undefined || raw === null || raw === "") return DEFAULT_TIMEOUT_MS;
-  const n = Number(raw);
-  if (!Number.isInteger(n) || n < 1) throw new Error(`timeout_ms must be a whole number of at least 1, not ${String(raw)}`);
-  return Math.min(n, MOST_TIMEOUT_MS);
-}
-
-/** Make one request and report how it went. A refused connection or a timeout is a result with its
- *  error; only a malformed question throws. */
-export async function checkHttp(args: Readonly<Record<string, unknown>>, fetcher: typeof fetch = fetch): Promise<HttpResult> {
-  const url = checkedUrl(args.url);
-  const method = checkedMethod(args.method);
-  const timeout = checkedTimeout(args.timeout_ms);
-  const started = performance.now();
-  const out: HttpResult = { url: url.toString(), method, elapsed_ms: 0, headers: {} };
-  try {
-    const res = await fetcher(url, { method, redirect: "manual", signal: AbortSignal.timeout(timeout) });
-    out.elapsed_ms = Math.round(performance.now() - started);
-    out.status = res.status;
-    out.statusText = res.statusText;
-    for (const h of REPORTED_HEADERS) {
-      const v = res.headers.get(h);
-      if (v !== null) out.headers[h] = v;
-    }
-    // The body is not read: a check asks whether something answers, not what it says.
-    await res.body?.cancel().catch(() => {});
-  } catch (err) {
-    out.elapsed_ms = Math.round(performance.now() - started);
-    const e = err as Error & { cause?: { message?: string; code?: string } };
-    out.error = e.name === "TimeoutError" ? `no answer within ${timeout} ms` : (e.cause?.code ?? e.cause?.message ?? e.message);
-  }
-  return out;
-}

modules/netcheck/module.json

@@ -1,35 +0,0 @@
-{
-  "module": "netcheck",
-  "version": "1",
-  "tools": [
-    "netcheck_tcp",
-    "netcheck_dns",
-    "netcheck_http"
-  ],
-  "build": {
-    "artifacts": [
-      {
-        "name": "tools-go",
-        "kind": "bundle",
-        "language": "go",
-        "system": "arch",
-        "from": "cmd/netcheck",
-        "binary": "netcheck",
-        "loads": [
-          "netcheck"
-        ]
-      },
-      {
-        "name": "tools-typescript",
-        "kind": "bundle",
-        "language": "typescript",
-        "entrypoints": [
-          "tools/index.js"
-        ],
-        "loads": [
-          "tools/index.js"
-        ]
-      }
-    ]
-  }
-}

modules/netcheck/package.json

@@ -1,17 +0,0 @@
-{
-  "name": "@novox/module-netcheck",
-  "version": "0.1.0",
-  "description": "netcheck — read-only network checks from a machine, as one module carrying a Go tools bundle (TCP, DNS) and a TypeScript one (HTTP) (novox/hq ADR 0188, ADR 0193).",
-  "type": "module",
-  "private": true,
-  "scripts": {
-    "test": "node --test --experimental-strip-types 'test/*.test.ts'"
-  },
-  "dependencies": {
-    "@novox/mesh-sdk": "^0.1.6"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.6.0"
-  }
-}

modules/netcheck/test/http.test.ts

@@ -1,52 +0,0 @@
-// The HTTP check refuses what is not http(s) and what would change something, and reports a status,
-// a refusal and a timeout as results (novox/hq ADR 0188: a tools bundle is read-only and harmless).
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { createServer } from "node:http";
-import type { AddressInfo } from "node:net";
-import { checkHttp, checkedMethod, checkedUrl } from "../http.ts";
-
-test("only http and https URLs are checked", () => {
-  for (const bad of ["file:///etc/passwd", "ftp://example.org/", "data:text/plain,hi", "javascript:1", "", "not a url"]) {
-    assert.throws(() => checkedUrl(bad), `${bad} was accepted`);
-  }
-  assert.equal(checkedUrl("https://example.org/x").protocol, "https:");
-});
-
-test("only HEAD and GET are used", () => {
-  assert.equal(checkedMethod(undefined), "HEAD");
-  assert.equal(checkedMethod("get"), "GET");
-  for (const bad of ["POST", "PUT", "DELETE", "PATCH"]) assert.throws(() => checkedMethod(bad));
-});
-
-test("a status, its headers and a redirect not followed", async () => {
-  const server = createServer((req, res) => {
-    if (req.url === "/moved") { res.writeHead(302, { location: "/elsewhere" }); res.end(); return; }
-    res.writeHead(200, { "content-type": "text/plain", "x-secret": "not reported" });
-    res.end(req.method === "GET" ? "body" : undefined);
-  });
-  await new Promise<void>((ok) => server.listen(0, "127.0.0.1", ok));
-  const base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
-  try {
-    const head = await checkHttp({ url: base + "/" });
-    assert.equal(head.status, 200);
-    assert.equal(head.method, "HEAD");
-    assert.equal(head.headers["content-type"], "text/plain");
-    assert.equal(head.headers["x-secret"], undefined);
-    const moved = await checkHttp({ url: base + "/moved", method: "GET" });
-    assert.equal(moved.status, 302);
-    assert.equal(moved.headers.location, "/elsewhere");
-  } finally {
-    server.close();
-  }
-});
-
-test("a refused connection is a result with its error", async () => {
-  const server = createServer();
-  await new Promise<void>((ok) => server.listen(0, "127.0.0.1", ok));
-  const port = (server.address() as AddressInfo).port;
-  await new Promise<void>((ok) => server.close(() => ok()));
-  const got = await checkHttp({ url: `http://127.0.0.1:${port}/`, timeout_ms: 2000 });
-  assert.equal(got.status, undefined);
-  assert.ok(got.error, "no error reported");
-});

modules/netcheck/tools/index.ts

@@ -1,28 +0,0 @@
-// netcheck's TypeScript tools bundle (novox/hq ADR 0188, ADR 0193): what the builder's launcher
-// imports and serves over MCP on stdio. Its Go bundle serves the TCP and DNS checks; this one the
-// HTTP check — one module, two languages, one runtime that knows neither.
-
-import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
-import { checkHttp, DEFAULT_TIMEOUT_MS, METHODS, MOST_TIMEOUT_MS } from "../http.js";
-
-export function getNetcheckHttpTools(): ToolDefinition[] {
-  return [
-    {
-      name: "netcheck_http",
-      description:
-        "Check whether an http(s) URL answers from this machine: one HEAD or GET, no body sent or read, " +
-        "redirects reported and not followed. Answers status, elapsed_ms and a few headers.",
-      input: {
-        url: { type: "string", description: "an http:// or https:// URL" },
-        method: { type: "string", enum: [...METHODS], description: "HEAD (default) or GET" },
-        timeout_ms: {
-          type: "integer",
-          description: `give up after this long (default ${DEFAULT_TIMEOUT_MS}, at most ${MOST_TIMEOUT_MS})`,
-        },
-      },
-      run: async (args) => checkHttp(args),
-    },
-  ];
-}
-
-registerModuleTools("netcheck", () => getNetcheckHttpTools());

modules/netcheck/tsconfig.json

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

modules/systemd/client.ts

@@ -1,93 +0,0 @@
-// systemctl and journalctl, asked in one scope or the other (novox/hq ADR 0177).
-//
-// The system manager is the machine's. The user manager is the operator account's own: reached as
-// `systemctl --user --machine=<account>@` when this process is not that account (the node tools
-// runtime runs as the node's account, root when the host started it), and as plain `--user` when
-// it is. It answers only while the account's manager runs — a login, or lingering enabled.
-
-import { execFile } from "node:child_process";
-import { userInfo } from "node:os";
-
-export type Scope = "system" | "user";
-
-export interface Unit {
-  unit: string;
-  load: string;
-  active: string;
-  sub: string;
-  description: string;
-}
-
-function run(cmd: string, args: string[]): Promise<{ stdout: string; stderr: string; status: number }> {
-  return new Promise((resolve) => {
-    execFile(cmd, args, { maxBuffer: 8 * 1024 * 1024 }, (err, stdout, stderr) => {
-      const status = err && typeof (err as { code?: unknown }).code === "number" ? ((err as { code: number }).code) : err ? 1 : 0;
-      resolve({ stdout: String(stdout ?? ""), stderr: String(stderr ?? "") + (err && !(err as { code?: unknown }).code ? err.message : ""), status });
-    });
-  });
-}
-
-export class ServiceManager {
-  constructor(private readonly account: string) {}
-
-  static fromEnv(env: NodeJS.ProcessEnv): ServiceManager {
-    return new ServiceManager(env.MESH_OPERATOR_ACCOUNT?.trim() || userInfo().username);
-  }
-
-  /** The leading arguments that pick a manager. */
-  scopeArgs(scope: Scope): string[] {
-    if (scope !== "user") return [];
-    return userInfo().username === this.account ? ["--user"] : ["--user", `--machine=${this.account}@`];
-  }
-
-  async systemctl(scope: Scope, ...args: string[]): Promise<{ stdout: string; stderr: string; status: number }> {
-    return run("systemctl", [...this.scopeArgs(scope), ...args]);
-  }
-
-  async units(scope: Scope, pattern?: string): Promise<Unit[]> {
-    const args = ["list-units", "--all", "--no-legend", "--plain", "--no-pager"];
-    if (pattern) args.push(pattern);
-    const { stdout } = await this.systemctl(scope, ...args);
-    return stdout
-      .split("\n")
-      .map((l) => l.trim())
-      .filter(Boolean)
-      .map((l) => {
-        const [unit, load, active, sub, ...rest] = l.split(/\s+/);
-        return { unit, load, active, sub, description: rest.join(" ") };
-      });
-  }
-
-  async status(scope: Scope, unit: string): Promise<Record<string, string>> {
-    const props = ["LoadState", "ActiveState", "SubState", "UnitFileState", "MainPID", "ExecMainStatus", "Description", "FragmentPath"];
-    const { stdout } = await this.systemctl(scope, "show", unit, ...props.map((p) => `--property=${p}`));
-    const out: Record<string, string> = { unit, scope };
-    for (const line of stdout.split("\n")) {
-      const i = line.indexOf("=");
-      if (i > 0) out[line.slice(0, i)] = line.slice(i + 1);
-    }
-    return out;
-  }
-
-  async act(scope: Scope, verb: "start" | "stop" | "restart" | "enable" | "disable", unit: string): Promise<Record<string, unknown>> {
-    const { stderr, status } = await this.systemctl(scope, verb, unit);
-    const after = await this.status(scope, unit);
-    return { unit, scope, verb, ok: status === 0, stderr: stderr.trim(), active: after.ActiveState, boot: after.UnitFileState,
-      note: "a unit the mesh declares is restored to its declared state at the host's next apply" };
-  }
-
-  async journal(scope: Scope, unit: string, lines: number): Promise<{ unit: string; scope: Scope; lines: string[] }> {
-    const args = ["--no-pager", "-n", String(lines), "-u", unit, "-o", "short-iso"];
-    if (scope === "user") {
-      args.unshift(userInfo().username === this.account ? "--user" : `--machine=${this.account}@`, ...(userInfo().username === this.account ? [] : ["--user"]));
-    }
-    const { stdout } = await run("journalctl", args);
-    return { unit, scope, lines: stdout.split("\n").filter(Boolean) };
-  }
-
-  async failed(): Promise<{ system: Unit[]; user: Unit[] }> {
-    const system = (await this.units("system")).filter((u) => u.active === "failed");
-    const user = (await this.units("user").catch(() => [] as Unit[])).filter((u) => u.active === "failed");
-    return { system, user };
-  }
-}

modules/systemd/module.json

@@ -1,46 +0,0 @@
-{
-  "module": "systemd",
-  "version": "1",
-  "capabilities": [
-    "service-manager",
-    "package-manager"
-  ],
-  "claims": [
-    {
-      "name": "node-service-manager",
-      "scope": "node",
-      "serves": [
-        "units",
-        "status",
-        "start",
-        "stop",
-        "restart",
-        "enable",
-        "disable",
-        "journal"
-      ]
-    }
-  ],
-  "tools": [
-    "systemd_failed"
-  ],
-  "resources": [
-    {
-      "id": "package",
-      "type": "package",
-      "package": "systemd"
-    }
-  ],
-  "build": {
-    "artifacts": [
-      {
-        "name": "tools",
-        "kind": "bundle",
-        "language": "typescript",
-        "entrypoints": [
-          "tools/index.js"
-        ]
-      }
-    ]
-  }
-}

modules/systemd/package.json

@@ -1,14 +0,0 @@
-{
-  "name": "@novox/module-systemd",
-  "version": "0.1.0",
-  "description": "systemd \u2014 the machine's service manager as a module: holds node-service-manager and answers for the units in both scopes (novox/hq ADR 0177). The host applies units; this answers about them.",
-  "type": "module",
-  "private": true,
-  "dependencies": {
-    "@novox/mesh-sdk": "^0.1.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.6.0"
-  }
-}

modules/systemd/tools/index.ts

@@ -1,71 +0,0 @@
-// systemd's tools: the node-service-manager seat's eight verbs — the units on this machine in
-// both scopes, read and acted on by name — and the module's own reading of what has failed
-// (novox/hq ADR 0177). Served by the node tools runtime (ADR 0175); the host applies units, this
-// answers about them.
-import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
-import { ServiceManager, type Scope } from "../client.js";
-
-const scope = { type: "string", description: "\"system\" (the default) or \"user\": the operator account's own manager" };
-const unit = { type: "string", description: "the unit's name, as the service manager knows it" };
-
-function scopeOf(args: Readonly<Record<string, unknown>>): Scope {
-  const s = String(args.scope ?? "system");
-  if (s !== "system" && s !== "user") throw new Error(`scope ${JSON.stringify(s)}: "system" or "user"`);
-  return s;
-}
-function unitOf(args: Readonly<Record<string, unknown>>): string {
-  const u = String(args.unit ?? "").trim();
-  if (!u) throw new Error("a unit is required");
-  return u;
-}
-
-export function getSeatVerbs(manager: ServiceManager): ToolDefinition[] {
-  const act = (verb: "start" | "stop" | "restart" | "enable" | "disable", description: string): ToolDefinition => ({
-    name: verb,
-    description,
-    input: { type: "object", properties: { scope, unit }, required: ["unit"] },
-    run: async (args) => manager.act(scopeOf(args), verb, unitOf(args)),
-  });
-  return [
-    {
-      name: "units",
-      description: "The units the service manager knows in a scope, each with its load, active and sub state; narrowed to a pattern when asked.",
-      input: { type: "object", properties: { scope, pattern: { type: "string", description: "a glob the unit's name must match (optional)" } } },
-      run: async (args) => ({ scope: scopeOf(args), units: await manager.units(scopeOf(args), args.pattern ? String(args.pattern) : undefined) }),
-    },
-    {
-      name: "status",
-      description: "One unit as the service manager sees it now: its states, whether it starts at boot, its main process, and whether the mesh declares it.",
-      input: { type: "object", properties: { scope, unit }, required: ["unit"] },
-      run: async (args) => manager.status(scopeOf(args), unitOf(args)),
-    },
-    act("start", "Start one unit. For a unit the mesh declares, the answer says the host will restore what its declaration says at the next apply."),
-    act("stop", "Stop one unit; for a mesh-declared unit the answer says the host will restore its declared state."),
-    act("restart", "Restart one unit."),
-    act("enable", "Make one unit start at boot (or at the account's login, in user scope)."),
-    act("disable", "Stop one unit starting at boot (or at login, in user scope)."),
-    {
-      name: "journal",
-      description: "The last lines of one unit's journal.",
-      input: { type: "object", properties: { scope, unit, lines: { type: "number", description: "how many lines from the end (default 100)" } }, required: ["unit"] },
-      run: async (args) => {
-        const n = Number(args.lines ?? 100);
-        return manager.journal(scopeOf(args), unitOf(args), Number.isFinite(n) && n > 0 ? Math.min(n, 5000) : 100);
-      },
-    },
-  ];
-}
-
-export function getOwnTools(manager: ServiceManager): ToolDefinition[] {
-  return [
-    {
-      name: "systemd_failed",
-      description: "Every failed unit on this machine, in the system manager and in the operator account's.",
-      input: { type: "object", properties: {} },
-      run: async () => manager.failed(),
-    },
-  ];
-}
-
-registerModuleTools("node-service-manager", (env) => getSeatVerbs(ServiceManager.fromEnv(env)));
-registerModuleTools("systemd", (env) => getOwnTools(ServiceManager.fromEnv(env)));

modules/systemd/tsconfig.json

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

modules/zsh/module.json

@@ -1,81 +0,0 @@
-{
-  "module": "zsh",
-  "version": "1",
-  "capabilities": [
-    "package-manager"
-  ],
-  "seats": [
-    {
-      "name": "login-shell",
-      "scope": "node",
-      "serves": [
-        {
-          "name": "execute",
-          "description": "Run one command on this machine as the operator account, in a login shell; answers with what it printed and how it exited (novox/hq ADR 0176).",
-          "input": {
-            "type": "object",
-            "properties": {
-              "command": {
-                "type": "string",
-                "description": "the command line, as you would type it"
-              },
-              "timeout_seconds": {
-                "type": "number",
-                "description": "give up after this long (default 60)"
-              }
-            },
-            "required": [
-              "command"
-            ]
-          }
-        }
-      ]
-    }
-  ],
-  "claims": [
-    {
-      "name": "login-shell",
-      "scope": "node",
-      "serves": [
-        "execute"
-      ]
-    }
-  ],
-  "tools": [
-    "zsh_config"
-  ],
-  "resources": [
-    {
-      "id": "package",
-      "type": "package",
-      "package": "zsh"
-    },
-    {
-      "id": "rc",
-      "type": "file",
-      "path": "${machine:account-home}/.zshrc",
-      "owner": "${machine:account}",
-      "mode": "0644",
-      "into": "block",
-      "content": "# The mesh's default zsh configuration (module zsh). Everything OUTSIDE this block is yours and\n# survives every push; everything inside it is replaced on the next one (novox/hq ADR 0174).\n# Machine-specific lines go in ~/.zshrc.local, which this sources last.\n\nexport EDITOR=vim\nexport VISUAL=vim\nexport XDG_CONFIG_HOME=\"$HOME/.config\"\nexport PATH=\"$HOME/.local/bin:$HOME/scripts:$HOME/scripts/bin:$PATH\"\n\n# Terminal title: host, directory, git branch\nfunction set_terminal_title() {\n  local git_branch=\"\"\n  if git rev-parse --is-inside-work-tree &>/dev/null; then\n    git_branch=\" ($(git branch --show-current 2>/dev/null))\"\n  fi\n  print -Pn \"\\e]2;%m: %~${git_branch}\\a\"\n}\nprecmd_functions+=(set_terminal_title)\n\n# A prompt theme and plugins, when a module placed them (the prompt module owns ~/.p10k.zsh and\n# ~/.zsh/themes; this only loads what is there).\n[[ ! -f ~/.zsh/themes/powerlevel10k/powerlevel10k.zsh-theme ]] || source ~/.zsh/themes/powerlevel10k/powerlevel10k.zsh-theme\n[[ ! -f ~/.p10k.zsh ]] || source ~/.p10k.zsh\n[[ ! -f ~/.zsh/plugins/zsh-autosuggestions/zsh-autosuggestions.zsh ]] || source ~/.zsh/plugins/zsh-autosuggestions/zsh-autosuggestions.zsh\n[[ ! -f ~/.zsh/plugins/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh ]] || source ~/.zsh/plugins/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh\n\n# Keybindings: Home, End, Ctrl-A, Ctrl-E, Del\nbindkey \"^[[H\"  beginning-of-line\nbindkey \"^[OH\"  beginning-of-line\nbindkey \"^A\"    beginning-of-line\nbindkey \"^[[F\"  end-of-line\nbindkey \"^[OF\"  end-of-line\nbindkey \"^E\"    end-of-line\nbindkey \"^[[3~\" delete-char\n\n# Colour and the usual ls aliases\nif [ -x /usr/bin/dircolors ]; then\n  test -r \"$HOME/.dircolors\" && eval \"$(dircolors -b \"$HOME/.dircolors\")\" || eval \"$(dircolors -b)\"\n  alias ls='ls --color=auto'\n  alias grep='grep --color=auto'\nfi\nalias ll='ls -alhF'\nalias la='ls -Ah'\nalias l='ls -CFh'\nalias drun='docker run -it --rm'\ndisksize() { du -h --max-depth=1 \"${1:-.}\" | sort -h; }\n\n# Machine-specific configuration, kept by you\n[[ ! -f ~/.zshrc.local ]] || source ~/.zshrc.local\n"
-    },
-    {
-      "id": "login",
-      "type": "user",
-      "name": "${machine:account}",
-      "shell": "/usr/bin/zsh"
-    }
-  ],
-  "build": {
-    "artifacts": [
-      {
-        "name": "tools",
-        "kind": "bundle",
-        "language": "typescript",
-        "entrypoints": [
-          "tools/index.js"
-        ]
-      }
-    ]
-  }
-}

modules/zsh/package.json

@@ -1,14 +0,0 @@
-{
-  "name": "@novox/module-zsh",
-  "version": "0.1.0",
-  "description": "zsh \u2014 the shell as a module: the package, the mesh's default ~/.zshrc as a block the operator's own lines survive around, the login-shell seat and its execute verb (novox/hq ADR 0176).",
-  "type": "module",
-  "private": true,
-  "dependencies": {
-    "@novox/mesh-sdk": "^0.1.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.6.0"
-  }
-}

modules/zsh/tools/index.ts

@@ -1,98 +0,0 @@
-// zsh's tools — the module's own, and its implementation of the login-shell seat's one verb
-// (novox/hq ADR 0176). Served by the node tools runtime (ADR 0175); nothing here runs a process.
-//
-// `execute` runs as the operator account. The runtime runs as the node's account — root when the
-// host started it — so the command is handed to the account through `runuser` when we are not
-// already that account. Root is the module's concern (ADR 0175 §4): a command that needs it uses
-// sudo inside the shell like a person would.
-
-import { spawn } from "node:child_process";
-import { readFile } from "node:fs/promises";
-import { homedir, userInfo } from "node:os";
-import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
-
-/** The operator account on this machine, as the mesh told the runtime; the current user otherwise. */
-function account(env: NodeJS.ProcessEnv): string {
-  return env.MESH_OPERATOR_ACCOUNT?.trim() || userInfo().username;
-}
-
-interface Executed {
-  command: string;
-  account: string;
-  status: number | null;
-  signal: string | null;
-  stdout: string;
-  stderr: string;
-  timed_out: boolean;
-}
-
-/** Run one command line in a zsh login shell as the account, capturing everything. */
-export async function execute(command: string, who: string, timeoutSeconds: number): Promise<Executed> {
-  const self = userInfo().username;
-  const argv = who === self
-    ? ["zsh", "-lc", command]
-    : ["runuser", "-u", who, "--", "zsh", "-lc", command];
-  return new Promise((resolve) => {
-    const child = spawn(argv[0], argv.slice(1), { stdio: ["ignore", "pipe", "pipe"] });
-    let stdout = "";
-    let stderr = "";
-    let timedOut = false;
-    child.stdout.on("data", (d: Buffer) => { stdout += d.toString(); });
-    child.stderr.on("data", (d: Buffer) => { stderr += d.toString(); });
-    const timer = setTimeout(() => { timedOut = true; child.kill("SIGKILL"); }, timeoutSeconds * 1000);
-    child.on("error", (err) => {
-      clearTimeout(timer);
-      resolve({ command, account: who, status: null, signal: null, stdout, stderr: stderr + err.message, timed_out: false });
-    });
-    child.on("close", (status, signal) => {
-      clearTimeout(timer);
-      resolve({ command, account: who, status, signal, stdout, stderr, timed_out: timedOut });
-    });
-  });
-}
-
-function seatVerbs(env: NodeJS.ProcessEnv): ToolDefinition[] {
-  return [
-    {
-      name: "execute",
-      description: "Run one command on this machine as the operator account, in a login shell; answers with what it printed and how it exited.",
-      input: {
-        type: "object",
-        properties: {
-          command: { type: "string", description: "the command line, as you would type it" },
-          timeout_seconds: { type: "number", description: "give up after this long (default 60)" },
-        },
-        required: ["command"],
-      },
-      run: async (args) => {
-        const command = String(args.command ?? "").trim();
-        if (!command) throw new Error("execute: a command is required");
-        const timeout = Number(args.timeout_seconds ?? 60);
-        return execute(command, account(env), Number.isFinite(timeout) && timeout > 0 ? timeout : 60);
-      },
-    },
-  ];
-}
-
-function ownTools(env: NodeJS.ProcessEnv): ToolDefinition[] {
-  return [
-    {
-      name: "zsh_config",
-      description: "The operator account's ~/.zshrc on this machine as it is now: the mesh's block and the lines around it.",
-      input: { type: "object", properties: {} },
-      run: async () => {
-        const who = account(env);
-        const home = env.MESH_OPERATOR_HOME?.trim() || (who === userInfo().username ? homedir() : `/home/${who}`);
-        const path = `${home}/.zshrc`;
-        const text = await readFile(path, "utf8").catch(() => "");
-        const inBlock = /# BEGIN mesh [^\n]*\n([\s\S]*?)# END mesh/.exec(text);
-        return { account: who, path, lines: text.split("\n").length, mesh_block_lines: inBlock ? inBlock[1].split("\n").length - 1 : 0, content: text };
-      },
-    },
-  ];
-}
-
-// The seat's verb is registered under the seat's name (what the runtime serves on the seat's
-// subject when this module holds it) and the module's own tools under the module's.
-registerModuleTools("login-shell", seatVerbs);
-registerModuleTools("zsh", ownTools);

modules/zsh/tsconfig.json

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