@intentic/sandbox-contract 1.248.0 → 1.249.0

package/src/protocol/peer-dial.ts

@@ -0,0 +1,207 @@
+// The one outbound socket a peer (machine agent, webext, runner) holds to its sandbox: hello carries the enrollment
+// token in the frame, then the link is pure oRPC. Reconnects on backoff after any drop except a revoked enrollment
+// (code 1008), which never retries.
+
+// Reconnect backoff: fast floor for a restart, low cap so a reopened laptop is back within a minute.
+export const PEER_LINK_BACKOFF = { floorMs: 1_000, capMs: 30_000, stableMs: 60_000 } as const;
+
+/* HOW LONG A SOCKET MAY SAY NOTHING before this side calls the link dead, as a multiple of the door's own
+ * heartbeat: the hub pings every live peer on an interval (peer-hub.ts), so a socket with nothing on it for
+ * three heartbeats is not quiet, it is gone.
+ *
+ * WHY A PEER NEEDS THIS AT ALL — a close event is not guaranteed, and the loop below has nothing else to react
+ * to. The socket that taught us is a loopback one: a machine agent dialling a sandbox container on its own
+ * machine through Docker Desktop's port relay. The container was recreated; the relay was not, so it held the
+ * agent's TCP connection open with nothing behind it. No FIN, no error, no close event — the agent held an open
+ * socket to a daemon that had never heard of it for 25 hours, its Devices card offline the whole time, every
+ * control on that card dead, and the only cure anyone found was re-running setup by hand. Any path with a
+ * middlebox in it (a NAT, a tunnel, a userland proxy, a laptop's suspended wifi) can do this to a socket with
+ * nothing to say, and the middlebox is never the side that notices. The peer is. */
+export const PEER_LINK_SILENCE_HEARTBEATS = 3;
+export const peerLinkSilenceMs = (heartbeatMs: number): number => heartbeatMs * PEER_LINK_SILENCE_HEARTBEATS;
+
+// The sandbox closes with this when the token is not enrolled: a decision, not a fault, and one that never heals.
+const UNAUTHORIZED = 1008;
+
+// WebSocket spec's readyState value for open, named so a fake socket need not import the real class.
+const OPEN = 1;
+
+// Structural interface a browser's WebSocket, node's global one, and a test's fake all satisfy without a cast.
+export interface SocketLike {
+    readonly readyState: number;
+    /* `message` is here for the watchdog alone, which needs no more than the fact that one arrived: what is IN
+     * the frames belongs to the oRPC handler `attach` hands the socket to, and a listener added here does not
+     * take it from that one (both runtimes' sockets fan an event out to every listener). */
+    addEventListener(type: "open" | "close" | "error" | "message", listener: (event: { readonly code?: number }) => void): void;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+}
+
+export interface PeerDialSpec<S extends SocketLike> {
+    // Resolves the address for this attempt, not once at startup; undefined ends the loop (pairing forgotten). `said`
+    // logs once open; a resolution outliving `signal`'s abort opens nothing.
+    readonly open: (signal: AbortSignal) => Promise<{ readonly socket: S; readonly said?: string } | undefined>;
+    // First frame sent on open: the enrollment token plus whatever the door's hello schema asks for.
+    readonly hello: () => Promise<Record<string, unknown>> | Record<string, unknown>;
+    // Hand the open socket to the oRPC handler serving the door's contract.
+    readonly attach: (socket: S) => void;
+    // The retry ladder: how long to wait after a drop, given how long the socket had held.
+    readonly backoff: { readonly next: (heldMs: number) => number };
+    /* How long this socket may hear nothing before the link is presumed dead: `peerLinkSilenceMs` of the
+     * heartbeat the door's own hub pings on. Required rather than defaulted, because the number belongs to the
+     * door and a peer that quietly inherited someone else's would be guessing about the one deadline that
+     * decides whether it ever notices a dead link. */
+    readonly silenceMs: number;
+    readonly log: (message: string) => void;
+    // Sandbox refused the enrollment (1008); the loop has already stopped, this is where the peer says so.
+    readonly revoked: () => void;
+}
+
+export interface PeerLink {
+    // Resolves when the loop is asked to stop or refused for good; never rejects, a connection error is a retry.
+    readonly done: Promise<void>;
+    readonly stop: (reason?: string) => void;
+    // "connecting" covers a dial in flight and a retry waiting on the ladder: nobody should start another.
+    readonly state: () => "open" | "connecting" | "closed";
+}
+
+export const dialPeer = <S extends SocketLike>(spec: PeerDialSpec<S>): PeerLink => {
+    const stopping = new AbortController();
+    let socket: S | undefined;
+    let waiting = false;
+    let openedAt: number | undefined;
+    // The live attempt's watchdog, reachable from `stop`: a stopped link that left a timer armed is a process
+    // the runtime keeps alive for a socket nobody holds any more.
+    let disarmWatchdog: () => void = () => undefined;
+    let resolveDone: () => void = () => undefined;
+    const done = new Promise<void>((resolve) => {
+        resolveDone = resolve;
+    });
+
+    const open = async (): Promise<void> => {
+        waiting = true;
+        const attempt = await spec.open(stopping.signal);
+        waiting = false;
+        // Aborted while resolving: nothing to open, `done` settled; a socket handed over late is closed, not dialled.
+        if (stopping.signal.aborted) {
+            attempt?.socket.close(1000, "stopping");
+            return;
+        }
+        if (attempt === undefined) {
+            stopping.abort();
+            resolveDone();
+            return;
+        }
+        const ws = attempt.socket;
+        socket = ws;
+
+        let watchdog: ReturnType<typeof setTimeout> | undefined;
+        const disarm = (): void => {
+            if (watchdog !== undefined) {
+                clearTimeout(watchdog);
+                watchdog = undefined;
+            }
+        };
+        disarmWatchdog = disarm;
+
+        /* THIS ATTEMPT'S DROP, taken by whichever side notices first: the far end's close frame, or the
+         * watchdog. Latched, because a socket the watchdog abandoned may still emit its close minutes later,
+         * and two redials on one link is two loops racing to hold the same door. */
+        let dropped = false;
+        const drop = (said: string): void => {
+            if (dropped) {
+                return;
+            }
+            dropped = true;
+            disarm();
+            if (socket === ws) {
+                socket = undefined;
+            }
+            if (stopping.signal.aborted) {
+                resolveDone();
+                return;
+            }
+            const delay = spec.backoff.next(openedAt === undefined ? 0 : Date.now() - openedAt);
+            openedAt = undefined;
+            spec.log(`${said}; reconnecting in ${Math.round(delay / 1000)}s`);
+            waiting = true;
+            setTimeout(() => void open(), delay);
+        };
+
+        const arm = (): void => {
+            disarm();
+            watchdog = setTimeout(() => {
+                /* ABANDONED, not closed politely. A close frame sent to an end that is gone waits on a reply
+                 * that never comes — CLOSING is the state this watchdog exists to escape — so `close` is called
+                 * for the runtime's sake and the redial does not wait on an event that may never fire. */
+                ws.close(1000, "no heartbeat");
+                drop(`nothing heard for ${Math.round(spec.silenceMs / 1000)}s`);
+            }, spec.silenceMs);
+        };
+        // Armed from the DIAL rather than the open, because a socket that never finishes connecting hangs the
+        // same way and reads the same from outside: "connecting", forever, with nothing coming.
+        arm();
+        // Every frame is proof the far end is there, and the hub's heartbeat is what guarantees there are some.
+        ws.addEventListener("message", arm);
+
+        ws.addEventListener("open", () => {
+            if (dropped) {
+                return; // abandoned mid-connect: this socket is already closed and its replacement is on the ladder
+            }
+            openedAt = Date.now();
+            arm();
+            spec.attach(ws);
+            const send = (hello: Record<string, unknown>): void => {
+                ws.send(JSON.stringify(hello));
+                if (attempt.said !== undefined) {
+                    spec.log(attempt.said);
+                }
+            };
+            // Sent synchronously when possible so a test can read it the same tick; an async hello still follows.
+            const hello = spec.hello();
+            if (hello instanceof Promise) {
+                void hello.then(send);
+            } else {
+                send(hello);
+            }
+        });
+
+        ws.addEventListener("close", (event) => {
+            /* A revocation is answered here rather than through `drop`: it is the one close that ends the loop
+             * instead of feeding the ladder, and it must still land on a socket the watchdog abandoned first —
+             * an owner who revoked a peer has said so, whether or not this side had already given up on it. */
+            if (event.code === UNAUTHORIZED) {
+                dropped = true;
+                disarm();
+                if (socket === ws) {
+                    socket = undefined;
+                }
+                stopping.abort();
+                resolveDone();
+                spec.revoked();
+                return;
+            }
+            drop(`disconnected (${event.code ?? "no code"})`);
+        });
+
+        // Always followed by a close event that owns the retry; this only records a cause the close code can't carry.
+        ws.addEventListener("error", () => spec.log("connection error"));
+    };
+
+    void open();
+
+    return {
+        done,
+        stop: (reason = "stopping") => {
+            stopping.abort();
+            waiting = false;
+            disarmWatchdog();
+            // Forgotten before the close frame arrives, so `state` reads closed the moment the peer asked.
+            const held = socket;
+            socket = undefined;
+            held?.close(1000, reason);
+            resolveDone();
+        },
+        state: () => (socket?.readyState === OPEN ? "open" : socket !== undefined || waiting ? "connecting" : "closed"),
+    };
+};

package/src/{peer-mcp-server.ts → protocol/peer-mcp-server.ts}

@@ -1,45 +1,22 @@
 import { z } from "zod";
 import { MCP_PROTOCOL_VERSION } from "./host-protocol.js";
 
-/* THE MCP SERVER A PEER RUNS, on the peer, not in the sandbox.
- *
- * The sandbox's daemon forwards JSON-RPC verbatim and interprets none of it, so the tool table handed to this is
- * the entire tool surface: what a device or a browser can do is decided by the build installed on it, and a
- * peer that upgrades learns new tools without anything changing in the sandbox. That is the reason for the
- * split; the alternative (schemas in the daemon, execution on the peer) makes every new tool a coordinated
- * release of two products.
- *
- * The protocol implemented is the subset a Streamable HTTP client actually uses against a stateless server:
- * initialize, tools/list, tools/call, ping, and notifications (which get no reply). Anything else answers
- * "method not found", which is the correct JSON-RPC response and not an error worth logging.
- *
- * A FAILED TOOL IS NOT A FAILED CALL. Every error, a refused scope, a missing file, a command that exited 1, an
- * argument that does not typecheck, comes back as a normal result with isError, because that is what a model can
- * read and act on; a JSON-RPC error surfaces as a transport fault and invites a retry loop against a peer that
- * will refuse it exactly the same way the second time.
- *
- * EACH TOOL'S ARGUMENTS ARE DESCRIBED ONCE. The zod schema a tool is built with is what the model is shown
- * (`tools/list` publishes it as JSON Schema) AND what an arriving call is checked against, so the advertised
- * shape and the accepted one cannot drift, the failure mode of writing both by hand, where a renamed field
- * keeps validating and the model keeps being told about the old name. A handler receives its arguments typed. */
+// The MCP server a peer (device, browser) runs; the daemon forwards JSON-RPC verbatim, so the tool table here is the
+// whole surface. A failed tool returns isError, never a JSON-RPC error. Each tool's zod schema is both what tools/list
+// advertises and what a call is checked against.
 
 export interface McpTool<Ctx> {
     readonly name: string;
     readonly description: string;
-    // JSON Schema for `tools/list`, derived from the zod schema once at module load rather than per request.
+    // JSON Schema for `tools/list`, derived from the zod schema once at module load, not per request.
     readonly inputSchema: Record<string, unknown>;
     readonly call: (args: unknown, ctx: Ctx) => Promise<Record<string, unknown>>;
 }
 
 export const textResult = (text: string, isError = false): Record<string, unknown> => ({ content: [{ type: "text", text }], isError });
 
-/* One tool, from the only description of its arguments there is. The generic is what carries the schema's type
- * through to the handler's parameter; `McpTool` erases it again, because the dispatch table holds them all and
- * the parse is what re-establishes the type at the boundary. `Ctx` is what the peer hands every call beside
- * its arguments: a device's live grant, nothing for a browser.
- *
- * `$schema` is dropped: the enclosing tool entry already says what this document is, and MCP clients read the
- * keywords rather than the dialect declaration. */
+// Builds one tool from a single zod schema; the generic carries its type to the handler, and `McpTool` erases it again
+// since the dispatch table holds every tool. `$schema` is dropped from the JSON Schema output as redundant.
 export const tool = <Schema extends z.ZodType, Ctx>(spec: {
     readonly name: string;
     readonly description: string;
@@ -53,15 +30,14 @@ export const tool = <Schema extends z.ZodType, Ctx>(spec: {
         inputSchema,
         call: async (args, ctx) => {
             const parsed = spec.input.safeParse(args);
-            // Readable enough for a model to fix its own call: which field, and what was expected there.
+            // Readable enough for a model to fix its own call: which field, and what was expected.
             return parsed.success ? await spec.run(parsed.data, ctx) : textResult(z.prettifyError(parsed.error), true);
         },
     };
 };
 
-// What the peer's audit log is told about one call: the arguments verbatim (redaction is the peer's, it knows
-// which of its tools carry typed secrets), and how it ended. A tool that answered with isError is `ok: false`
-// with no message; one that threw carries what it said, and whether it was the peer's own refusal.
+// What the peer's audit log is told about one call: arguments verbatim (redaction is the peer's job) and how it ended.
+// isError is `ok: false` with no message; a throw carries its message and whether it was a refusal.
 export interface McpAuditEntry {
     readonly tool: string;
     readonly args: Record<string, unknown>;
@@ -72,21 +48,20 @@ export interface McpAuditEntry {
 export interface McpServerSpec<Ctx> {
     readonly serverInfo: () => { readonly name: string; readonly version: string };
     readonly tools: readonly McpTool<Ctx>[];
-    // The sentence for a tool this peer does not have, in the peer's own noun.
+    // Message for an unknown tool, phrased in the peer's own vocabulary.
     readonly noSuchTool: (name: string) => string;
-    // Whether a thrown error is this peer's own refusal (a switch that is off, a site that is not granted) as
-    // opposed to a tool that failed: the audit line says which.
+    // Whether a thrown error is the peer's own refusal (a disabled switch, an ungranted site) rather than a tool
+    // failure.
     readonly refused: (error: unknown) => boolean;
     readonly errorMessage: (error: unknown) => string;
-    // Every call, accepted or refused, once it has an outcome. Best-effort: a log that cannot be written must
-    // never fail the answer, so a rejection here is swallowed.
+    // Called with every outcome; best-effort, a logging failure here must never fail the answer.
     readonly audit: (entry: McpAuditEntry) => Promise<void> | void;
 }
 
 const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
 
-// Handle one JSON-RPC message. Returns the response, or undefined for a notification (nothing to answer). `ctx`
-// is read per call by the tool that runs, so a grant pushed mid-session takes effect on the very next call.
+// Handles one JSON-RPC message; returns undefined for a notification. `ctx` is read per call, so a grant pushed
+// mid-session takes effect on the next call.
 export const createMcpServer = <Ctx>(spec: McpServerSpec<Ctx>): ((message: unknown, ctx: Ctx) => Promise<Record<string, unknown> | undefined>) => {
     const byName = new Map(spec.tools.map((entry) => [entry.name, entry]));
     const listing = spec.tools.map(({ name, description, inputSchema }) => ({ name, description, inputSchema }));
@@ -94,7 +69,7 @@ export const createMcpServer = <Ctx>(spec: McpServerSpec<Ctx>): ((message: unkno
         try {
             await spec.audit(entry);
         } catch {
-            // Deliberately silent: a record for a human, never a control.
+            // Silent: this log is for a human, never a control.
         }
     };
 

package/src/protocol/request-id.ts

@@ -0,0 +1,5 @@
+// Correlates a browser call to the daemon request that served it; a token only, never a security boundary.
+export const REQUEST_ID_HEADER = "x-intentic-request-id";
+
+// Confirms daemon CORS accepts this header before sending; no evidence here means don't send, unlike supportsRoute.
+export const REQUEST_ID_EVIDENCE_ROUTE = "logs.report";

package/src/{routes.test.ts → protocol/routes.test.ts}

@@ -1,7 +1,7 @@
 import { eventIterator, oc } from "@orpc/contract";
 import { describe, expect, it } from "vitest";
 import { z } from "zod";
-import { SANDBOX_ROUTE_NAMES, SANDBOX_ROUTE_SHAPES, SANDBOX_ROUTES, sandboxRouteName } from "./index.js";
+import { SANDBOX_ROUTE_NAMES, SANDBOX_ROUTE_SHAPES, SANDBOX_ROUTES, sandboxRouteName } from "../index.js";
 import { contractRoutes, routeNameForRequest, routeShapes } from "./routes.js";
 
 const fixture = {
@@ -14,7 +14,7 @@ const fixture = {
     },
 };
 
-// A contract whose one route carries real schemas, so a shape can actually change between "builds".
+// A contract whose one route carries real schemas, so its shape can change between builds.
 const shaped = (output: z.ZodType) => ({ vpn: { list: oc.route({ method: "GET", path: "/vpn" }).output(output) } });
 
 describe(`contractRoutes`, () => {
@@ -77,8 +77,6 @@ describe(`routeShapes`, () => {
     it(`changes the fingerprint when a field is added`, () => {
         const before = routeShapes(shaped(z.object({ a: z.string() })))[`vpn.list`];
         const after = routeShapes(shaped(z.object({ a: z.string(), b: z.number() })))[`vpn.list`];
-        // A fingerprint is a string, and saying so is what makes the line below mean something: with `before`
-        // undefined and `after` a real shape, "they differ" is true for the wrong reason.
         expect(before).toEqual(expect.any(String));
         expect(after).not.toBe(before);
     });
@@ -96,8 +94,7 @@ describe(`routeShapes`, () => {
     });
 
     it(`reads a defaulted field differently on the way in than on the way out`, () => {
-        // `.default()` makes a field optional going in and required coming out: the same declaration, two
-        // wire shapes. Reading both directions the same way would call them identical.
+        // `.default()` makes a field optional on input, required on output: same declaration, two shapes.
         const one = z.object({ a: z.string().default(`x`) });
         const asOutput = routeShapes(shaped(one))[`vpn.list`];
         const asInput = routeShapes({ vpn: { list: oc.route({ method: "GET", path: "/vpn" }).input(one) } })[`vpn.list`];
@@ -106,8 +103,8 @@ describe(`routeShapes`, () => {
     });
 
     it(`treats a route declaring no schemas as a shape of its own`, () => {
-        // Not a special case: "this route carries nothing" is a real shape, and a build that later gives it an
-        // output has genuinely changed it. All three fixture routes declare nothing, so all three agree.
+        // All three fixture routes declare nothing, so all three share one shape; giving one an output later is a real
+        // change.
         const shapes = routeShapes(fixture);
         expect(Object.keys(shapes).toSorted()).toEqual([`system.killTerminal`, `vpn.connect`, `vpn.list`]);
         expect(new Set(Object.values(shapes)).size).toBe(1);
@@ -115,10 +112,8 @@ describe(`routeShapes`, () => {
     });
 
     it(`omits a route whose shape cannot be expressed rather than failing the walk`, () => {
-        // An oRPC event iterator wraps its output in an opaque type with no schema underneath. The route keeps
-        // its NAME (it is still advertised as existing) and simply carries no shape, which reads downstream as
-        // "assume compatible". The two neighbours still get fingerprinted, which is the part that matters: one
-        // unexpressable route must not cost the whole walk.
+        // An oRPC event iterator wraps its output in an opaque type with no schema, so `watch` here keeps its name but
+        // no shape.
         const withStream = {
             vpn: {
                 list: fixture.vpn.list,
@@ -137,15 +132,13 @@ describe(`routeShapes`, () => {
 describe(`the real sandbox contract`, () => {
     it(`fingerprints all but the streaming routes`, () => {
         const unshaped = SANDBOX_ROUTE_NAMES.filter((name) => !(name in SANDBOX_ROUTE_SHAPES));
-        // oRPC wraps an event iterator's output in an opaque type with no schema under it, so these eleven
-        // cannot be fingerprinted and are assumed compatible. Named rather than counted: a NEW entry here is
-        // a route that quietly lost its shape check, which is worth failing a test over.
+        // oRPC gives an event iterator's output no schema, so these can't be fingerprinted; named rather than counted
+        // so a new one added here fails the test.
         expect(unshaped.toSorted()).toEqual([
             `agent.attach`,
             `capabilities.add`,
-            // The three geo-exit moves, streaming for the same reason vpn.connect does: bringing an exit up
-            // pulls a catalog, dials, and then verifies the address it landed on, which is tens of seconds on
-            // the free providers and can fail with something the user has to read at each step.
+            // The three exit moves stream since bringing an exit up dials and verifies over tens of seconds, failing at
+            // any step.
             `exit.rotate`,
             `exit.start`,
             `exit.use`,
@@ -153,8 +146,8 @@ describe(`the real sandbox contract`, () => {
             `intentic.run`,
             `system.events`,
             `system.manageDeviceSandbox`,
-            // The device's own agent updating or restarting itself: minutes of download and swap, and the
-            // stream dies with the process it is reporting on, so the lines have to arrive as they happen.
+            // The device agent updates or restarts itself; the stream dies with the process, so lines arrive as they
+            // happen.
             `system.runDeviceAgentFlow`,
             `vpn.connect`,
         ]);
@@ -171,8 +164,7 @@ describe(`the real sandbox contract`, () => {
     });
 
     it(`covers every oc.route in the contract`, () => {
-        // Guards the walk against a future contract nesting deeper than group → procedure, which would
-        // silently advertise fewer routes than the daemon serves.
+        // Guards against a contract nesting deeper than group → procedure, which would silently under-report routes.
         expect(SANDBOX_ROUTES.length).toBeGreaterThan(100);
     });
 

package/src/protocol/routes.ts

@@ -0,0 +1,159 @@
+import { z } from "zod";
+
+// Named route surface of the daemon's contract (`<group>.<route>`), derived automatically so nothing here is
+// hand-maintained. The daemon advertises which routes it implements (the /events hello frame); the browser diffs that
+// against its own contract so an old daemon's gap is a named feature check, not a silent 404.
+
+// Structural shape of `~orpc.route`, the metadata oRPC attaches to every `oc.route(...)` procedure; read this way since
+// oRPC's internal types aren't public.
+interface ContractProcedureLike {
+    readonly "~orpc": { readonly route?: { readonly method?: string; readonly path?: string } };
+}
+
+const procedureRoute = (value: unknown): { method: string; path: string } | undefined => {
+    if (typeof value !== "object" || value === null || !("~orpc" in value)) {
+        return undefined;
+    }
+    const { route } = (value as ContractProcedureLike)["~orpc"];
+    if (route?.method === undefined || route.path === undefined) {
+        return undefined;
+    }
+    return { method: route.method, path: route.path };
+};
+
+// One advertised route: contract name plus wire shape, matched back to a concrete request path by routeNameForRequest.
+export interface ContractRoute {
+    readonly name: string;
+    readonly method: string;
+    // oRPC path template with `{param}` placeholders, e.g. `/system/terminals/{name}`.
+    readonly path: string;
+}
+
+// Walks a contract object (group → procedure) into a flat route list, sorted by name for a stable diff.
+export const contractRoutes = (contract: Record<string, unknown>): ContractRoute[] => {
+    const routes: ContractRoute[] = [];
+    for (const [group, procedures] of Object.entries(contract)) {
+        if (typeof procedures !== "object" || procedures === null) {
+            continue;
+        }
+        for (const [name, procedure] of Object.entries(procedures as Record<string, unknown>)) {
+            const route = procedureRoute(procedure);
+            if (route !== undefined) {
+                routes.push({ name: `${group}.${name}`, method: route.method, path: route.path });
+            }
+        }
+    }
+    return routes.toSorted((a, b) => a.name.localeCompare(b.name));
+};
+
+// Route names alone miss payload drift: a route present on both sides can still have a different schema between builds.
+// Each route also carries a fingerprint of its input/output schema, computed automatically so nothing here is a
+// hand-bumped version number.
+
+// Schemas oRPC hangs off a procedure, read structurally like `route` above since they're internal metadata, not public.
+interface ContractSchemasLike {
+    readonly "~orpc": { readonly inputSchema?: unknown; readonly outputSchema?: unknown };
+}
+
+// JSON Schema keywords whose array value is a set; reordering a z.object's fields must not read as drift.
+const UNORDERED = new Set(["required", "enum", "anyOf", "oneOf", "allOf"]);
+
+// Canonicalizes JSON: object keys and set-valued arrays (UNORDERED) sorted, everything else left as written, so a
+// cosmetic edit doesn't fingerprint as a payload change. Positional arrays like a tuple's `prefixItems` stay ordered,
+// or distinct shapes would collide.
+const canonical = (value: unknown, key?: string): unknown => {
+    if (Array.isArray(value)) {
+        const items = value.map((item) => canonical(item));
+        return key !== undefined && UNORDERED.has(key) ? items.toSorted((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))) : items;
+    }
+    if (typeof value !== "object" || value === null) {
+        return value;
+    }
+    const entries = Object.entries(value as Record<string, unknown>).toSorted(([a], [b]) => a.localeCompare(b));
+    return entries.map(([name, nested]) => [name, canonical(nested, name)]);
+};
+
+// FNV-1a over the canonical JSON, base36; not cryptographic, since this is only a drift signal and a collision costs
+// one missed warning, nothing more.
+const fingerprint = (value: unknown): string => {
+    const text = JSON.stringify(canonical(value));
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(36);
+};
+
+// One route's wire shape, or undefined if it can't be expressed (a streaming route with no underlying schema). `io`
+// matters: a `.default()` field is optional in and required out, so both directions must be read separately.
+const procedureShape = (value: unknown): string | undefined => {
+    if (typeof value !== "object" || value === null || !("~orpc" in value)) {
+        return undefined;
+    }
+    const { inputSchema, outputSchema } = (value as ContractSchemasLike)["~orpc"];
+    try {
+        return fingerprint({
+            in: inputSchema === undefined ? undefined : z.toJSONSchema(inputSchema as z.ZodType, { io: "input" }),
+            out: outputSchema === undefined ? undefined : z.toJSONSchema(outputSchema as z.ZodType, { io: "output" }),
+        });
+    } catch {
+        return undefined;
+    }
+};
+
+// Every route whose shape this build can express, as name → fingerprint. A separate map from ContractRoute since
+// existence and shape are advertised, and checked, independently.
+export const routeShapes = (contract: Record<string, unknown>): Record<string, string> => {
+    const shapes: Record<string, string> = {};
+    for (const [group, procedures] of Object.entries(contract)) {
+        if (typeof procedures !== "object" || procedures === null) {
+            continue;
+        }
+        for (const [name, procedure] of Object.entries(procedures as Record<string, unknown>)) {
+            if (procedureRoute(procedure) === undefined) {
+                continue;
+            }
+            const shape = procedureShape(procedure);
+            if (shape !== undefined) {
+                shapes[`${group}.${name}`] = shape;
+            }
+        }
+    }
+    return shapes;
+};
+
+// Matches a concrete path against a route template segment-wise; `{param}` matches exactly one segment, so length must
+// match too.
+const pathMatches = (template: string, path: string): boolean => {
+    const wanted = template.split("/");
+    const actual = path.split("/");
+    if (wanted.length !== actual.length) {
+        return false;
+    }
+    return wanted.every((segment, index) => (segment.startsWith("{") && segment.endsWith("}") ? actual[index] !== "" : segment === actual[index]));
+};
+
+// The contract route a request belongs to, or undefined for a hand-written daemon route (/health, /workspace/raw) never
+// gated by the contract. Query string stripped first.
+export const routeNameForRequest = (routes: readonly ContractRoute[], method: string, pathWithQuery: string): string | undefined => {
+    const path = pathWithQuery.split("?")[0] ?? pathWithQuery;
+    const upper = method.toUpperCase();
+    return routes.find((route) => route.method.toUpperCase() === upper && pathMatches(route.path, path))?.name;
+};
+
+// The route a typed client call belongs to; oRPC addresses a procedure by contract position (`['git','stashApply']`),
+// so this is a lookup, not a match.
+export const routeForProcedure = (routes: readonly ContractRoute[], procedure: readonly string[]): ContractRoute | undefined =>
+    routes.find((route) => route.name === procedure.join("."));
+
+// Fills each `{param}` in the route template from the matching input field, so a permission gate checks the real path,
+// not a template a glob would still match unfilled. An unmatched param keeps its placeholder, the safe failure since a
+// literal grant won't match braces.
+export const requestPathFor = (route: ContractRoute, input: unknown): string => {
+    const fields = typeof input === "object" && input !== null ? (input as Record<string, unknown>) : {};
+    return route.path.replace(/\{([^}]+)\}/g, (placeholder, name: string) => {
+        const value = fields[name];
+        return value === undefined ? placeholder : encodeURIComponent(String(value));
+    });
+};