A module answers the word the mesh asks: prepare

The runtime gains `prepare`, which brings this module's state to the shape this version needs and
exits (novox/hq ADR 0135). The entrypoints come from MESH_PREPARE, which a module's own image names
beside the entrypoints it already lists there — the module knows which of its files prepares its
state and nothing else could. No broker is connected: preparation runs before the version that would
use it. An empty list fails rather than passing quietly, because the mesh asks this only of a module
whose manifest says it prepares something, and exiting 0 would let that version serve against a
state nobody shaped.

src/broker-nats.ts

@@ -19,7 +19,7 @@
 import { createHash } from "node:crypto";
 import net from "node:net";
 import tls from "node:tls";
-import { connect as natsConnect, headers as natsHeaders, StringCodec, type JsMsg, type Subscription } from "nats";
+import { connect as natsConnect, headers as natsHeaders, StringCodec, type JsMsg, type Subscription, type TlsOptions } from "nats";
 import type { Broker, Envelope, EventHeaders } from "@novox/mesh-sdk/messaging";
 
 const sc = StringCodec();
@@ -85,6 +85,10 @@ export async function connectNats(
     pass: cred.password,
     name: `${cred.node ?? "?"}.${self}`,
     tls: cred.fingerprint ? await pinnedTls(cred.url, cred.fingerprint) : undefined,
+    // Its own inbox, not a random one: every user's inbox is private to it (design 25 §4), and the
+    // grant names `_INBOX.<user>.>` — a reply space the client invented would be refused, and with
+    // it every pull for the next message and every answer to a tool call.
+    inboxPrefix: cred.user ? `_INBOX.${cred.user}` : undefined,
     // Reconnect forever: the bus being restarted is an upgrade, not a reason for every module on
     // the mesh to exit. `close()` stays the only thing that ends the connection.
     maxReconnectAttempts: -1,
@@ -298,14 +302,15 @@ function normalizeFingerprint(fingerprint: string): string {
  * A certificate authority is not consulted: the mesh issued this and knows its fingerprint,
  * which is stronger than trusting whoever a machine's trust store happens to contain.
  *
- * **A constraint on the mesh, not a detail of this file.** Pinning the exact certificate makes
- * hostname verification redundant in principle, but the NATS client exposes no hook to replace
- * it — its TLS options are file paths and PEM strings, with no verify callback. So the
- * certificate the mesh issues the bus **must carry a subject-alternative name matching the
- * address nodes dial it by**. The fingerprint check below still happens and is still the real
- * guarantee; what cannot be switched off is the check *beside* it.
+ * **The pin is the only check.** What comes back is handed to the client as its TLS options, and
+ * the client's transport spreads them into Node's own `tls.connect` — so the pinned certificate
+ * is the one authority the handshake accepts, and the hostname check beside it is replaced with
+ * one that always passes. Pinning the exact certificate makes verifying its name redundant, and
+ * the bus's certificate names the seat (`mesh-broker`), not the address a machine happens to
+ * dial it by: every module on the mesh met "does not match certificate's altnames" the first time
+ * it reached the handshake (2026-09-28).
  */
-async function pinnedTls(rawUrl: string, fingerprint: string): Promise<{ ca: string }> {
+async function pinnedTls(rawUrl: string, fingerprint: string): Promise<TlsOptions> {
   const url = new URL(rawUrl.includes("://") ? rawUrl : `nats://${rawUrl}`);
   const port = url.port ? Number(url.port) : 4222;
   // **The bus speaks first, in the clear.** A NATS server sends its INFO line before TLS begins,
@@ -342,7 +347,9 @@ async function pinnedTls(rawUrl: string, fingerprint: string): Promise<{ ca: str
     );
   }
   const pem = `-----BEGIN CERTIFICATE-----\n${certificate.raw.toString("base64").replace(/(.{64})/g, "$1\n")}\n-----END CERTIFICATE-----\n`;
-  return { ca: pem };
+  // Node's option, not the client's: the transport passes the whole object on. `undefined` from
+  // checkServerIdentity is "the name is fine"; the pin above already decided the rest.
+  return { ca: pem, checkServerIdentity: () => undefined } as TlsOptions;
 }
 
 /** The mesh's topic matching: `*` is one token, `#` the rest. This is the module's vocabulary —

src/main.ts

@@ -5,6 +5,10 @@
 //                                 starts consuming as it is imported, so this also runs consumers.
 //   mesh-tools emit TYPE [JSON]   emit one event onto the mesh and exit — an operable primitive,
 //                                 and what an events test uses to put a message on the wire.
+//   mesh-tools prepare            bring this module's state to the shape this version needs and exit
+//                                 — the runtime's answer to the word the mesh asks every module
+//                                 (novox/hq ADR 0135). The entrypoints come from MESH_PREPARE, which
+//                                 the module's own image names beside MESH_TOOL_MODULES.
 //   mesh-tools run ENTRYPOINT     run one compiled module entrypoint to completion and exit — the
 //                                 runtime side of a run-once step (novox/hq ADR 0052). It imports
 //                                 the given entrypoint, whose top-level code does its work — seed a
@@ -18,6 +22,7 @@
 //                      amqps account scoped to this module. Preferred: a module holds its own.
 //   MESH_BROKER_URL    a plain URL, for the bootstrap/admin case before a module has an account.
 //   MESH_TOOL_MODULES  /path/a,/path/b,…   compiled module entrypoints (serve mode)
+//   MESH_PREPARE       /path/a,/path/b,…   compiled entrypoints that prepare this module's state
 //   MESH_MODULE / MESH_NODE                the identity stamped onto emitted events (ADR 0042)
 
 import { readFileSync } from "node:fs";
@@ -177,12 +182,49 @@ async function runEntry(entrypoint: string): Promise<void> {
   await import(pathToFileURL(entrypoint).href);
 }
 
+/**
+ * Bring this module's state to the shape this version needs, and exit — the runtime's answer to the
+ * one word the mesh asks every module (novox/hq ADR 0135).
+ *
+ * The entrypoints come from `MESH_PREPARE`, which a module's own image sets beside the entrypoints it
+ * already lists there: the module knows which of its files prepares its state, and nothing else could.
+ * Each is imported in the order given, to completion, with no broker — preparation runs before the
+ * version that would use it, so there is nothing yet to talk to.
+ *
+ * **An empty list is a failure, not a no-op.** The mesh only asks this of a module whose manifest says
+ * it prepares something; a module that says so and names nothing has been built wrong, and exiting 0
+ * would let that version serve against a state nobody shaped.
+ */
+async function prepareState(): Promise<void> {
+  const named = (process.env.MESH_PREPARE ?? "")
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry !== "");
+  if (named.length === 0) {
+    console.error(
+      "mesh-tools prepare: this module was asked to prepare its state and its image names nothing " +
+        "to do it with — set MESH_PREPARE to the compiled entrypoint(s) that prepare it, the way " +
+        "MESH_TOOL_MODULES names the ones it serves",
+    );
+    process.exit(1);
+  }
+  for (const entrypoint of named) {
+    console.log(`[mesh-tools] preparing with ${entrypoint}`);
+    await runEntry(entrypoint);
+  }
+  console.log(`[mesh-tools] prepared: ${named.length} entrypoint(s) ran to completion`);
+}
+
 async function main(): Promise<void> {
   const [command, ...rest] = process.argv.slice(2);
   if (command === "run") {
     await runEntry(rest[0] ?? "");
     return;
   }
+  if (command === "prepare") {
+    await prepareState();
+    return;
+  }
   if (command === "invoke") {
     const [module, tool] = rest;
     if (!module || !tool) {

test/patient-connect.test.ts

@@ -1,3 +1,4 @@
+import { spawn } from "node:child_process";
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { fatalBrokerReason, PinMismatchError } from "../src/broker-nats.ts";
@@ -41,3 +42,21 @@ test("a non-Error value does not crash the classifier", () => {
   assert.equal(fatalBrokerReason("just a string"), null);
   assert.equal(fatalBrokerReason(undefined), null);
 });
+
+// **A module asked to prepare its state and naming nothing is a failure, not a no-op** (novox/hq
+// ADR 0135). The mesh asks this only of a module whose manifest says it prepares something, so an
+// image that names nothing was built wrong, and exiting 0 would let that version serve against a
+// state nobody shaped.
+test("preparing with nothing named fails rather than passing quietly", async () => {
+  const runtime = new URL("../dist/main.js", import.meta.url).pathname;
+  const ran = await new Promise<{ code: number | null; said: string }>((resolve) => {
+    const child = spawn(process.execPath, [runtime, "prepare"], {
+      env: { ...process.env, MESH_PREPARE: "" },
+    });
+    let said = "";
+    child.stderr.on("data", (chunk) => (said += String(chunk)));
+    child.on("close", (code) => resolve({ code, said }));
+  });
+  assert.notEqual(ran.code, 0, "a module that prepares nothing exited 0, so its version would serve");
+  assert.match(ran.said, /MESH_PREPARE/);
+});