@intentic/sandbox-contract 1.311.0 → 1.312.0

package/src/front/generated/wire.ts

@@ -1,6 +1,10 @@
 // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
 
-export type Answer = { "answer": "preview", route: PreviewRoute, };
+export type Answer = { "answer": "preview", route: PreviewRoute, } | { "answer": "terminal", plan: TerminalPlan, 
+/**
+ * The member whose ticket opened it, lowercased; absent when the daemon runs without auth.
+ */
+member?: string, };
 
 /**
  * A PEM certificate chain and its PEM private key.
@@ -12,7 +16,7 @@ export type Endpoint = { host: string, port: number, };
 /**
  * Everything Node sends the front.
  */
-export type FromNode = { "kind": "hello", build: string, pid: number, } | { "kind": "listen", config: ListenConfig, } | { "kind": "certificate", certificate?: Certificate, } | { "kind": "tunnel", tunnel?: TunnelConfig, } | { "kind": "answer", id: number, answer: Answer, } | { "kind": "refused", id: number, message: string, };
+export type FromNode = { "kind": "hello", build: string, pid: number, } | { "kind": "listen", config: ListenConfig, } | { "kind": "certificate", certificate?: Certificate, } | { "kind": "tunnel", tunnel?: TunnelConfig, } | { "kind": "answer", id: number, answer: Answer, } | { "kind": "refused", id: number, message: string, } | { "kind": "revoke", member?: string, } | { "kind": "watch", checkout: WatchedCheckout, } | { "kind": "unwatch", dir: string, } | { "kind": "sync", id: number, dirs: Array<string>, };
 
 /**
  * Request headers only the front sets on what it forwards to Node; it strips them from everything arriving outside.
@@ -45,14 +49,35 @@ export type PreviewRoute = { "to": "upstream", upstream: Upstream, } | { "to": "
 /**
  * A question the front asks Node; the answer carries the same id.
  */
-export type Question = { "question": "preview", host: string, };
+export type Question = { "question": "preview", host: string, } | { "question": "terminal", query: string, };
 
 export type Scheme = "http" | "https";
 
+/**
+ * What the browser sends on a terminal socket, each a JSON text frame.
+ */
+export type TerminalClientMessage = { "type": "input", data: string, } | { "type": "resize", cols: number, rows: number, } | { "type": "ping" };
+
+/**
+ * What a terminal socket opens onto, as Node decided from its ticket, session name and working directory.
+ */
+export type TerminalPlan = { "plan": "tmux", session: string, argv: Array<string>, } | { "plan": "tail", path: string, } | { "plan": "exit", code: number, reason: string, } | { "plan": "refused", code: number, reason: string, };
+
+/**
+ * What a terminal socket sends as JSON text; the pane's own bytes travel as binary frames.
+ */
+export type TerminalServerMessage = { "type": "exit", code: number, reason?: string, } | { "type": "pong" };
+
+/**
+ * The Upgrade a terminal opens with where no WebSocket rides the stream, a WebTransport one: its messages then travel
+ * as frames (`FrameKind`). Exported as a literal type, as `FrontHeader` is.
+ */
+export type TerminalUpgrade = "intentic-terminal";
+
 /**
  * Everything the front sends Node.
  */
-export type ToNode = { "kind": "ask", id: number, question: Question, } | { "kind": "tunnel", connected: boolean, };
+export type ToNode = { "kind": "ask", id: number, question: Question, } | { "kind": "tunnel", connected: boolean, } | { "kind": "synced", id: number, generations: Array<number | null>, };
 
 /**
  * The ingress tunnel's door and the reachability grant it presents there.
@@ -71,3 +96,9 @@ localhost: boolean,
  * Framed by the editor: `frame-ancestors` is set and `x-frame-options` dropped.
  */
 frameable: boolean, };
+
+/**
+ * A checkout whose changes the front counts: its working tree, the git dir holding its index and HEAD, and the common
+ * dir holding refs and excludes (the git dir itself for a repository's main checkout).
+ */
+export type WatchedCheckout = { dir: string, gitDir: string, commonDir: string, };

package/src/front/terminal-frames.fixture.json

@@ -0,0 +1,55 @@
+{
+    "session": "/system/transport",
+    "upgrade": "intentic-terminal",
+    "frames": [
+        {
+            "encoded": "00000000081b5b33316d68c3a9",
+            "frame": {
+                "kind": "pane",
+                "bytes": "1b5b33316d68c3a9"
+            }
+        },
+        {
+            "encoded": "010000001c7b2274797065223a22696e707574222c2264617461223a22c582227d",
+            "frame": {
+                "kind": "message",
+                "text": "{\"type\":\"input\",\"data\":\"ł\"}"
+            }
+        },
+        {
+            "encoded": "020000001703f0617574686f72697a6174696f6e207265766f6b6564",
+            "frame": {
+                "kind": "close",
+                "code": 1008,
+                "reason": "authorization revoked"
+            }
+        },
+        {
+            "encoded": "0200000000",
+            "frame": {
+                "kind": "close",
+                "reason": ""
+            }
+        },
+        {
+            "encoded": "0300000000",
+            "frame": {
+                "kind": "ping",
+                "bytes": ""
+            }
+        },
+        {
+            "encoded": "040000000101",
+            "frame": {
+                "kind": "pong",
+                "bytes": "01"
+            }
+        }
+    ],
+    "unreadable": [
+        "0500000000",
+        "01ffffffff",
+        "020000000103",
+        "0100000002c328"
+    ]
+}

package/src/front/terminal-frames.test.ts

@@ -0,0 +1,63 @@
+import { readFileSync } from "node:fs";
+import { TERMINAL_UPGRADE, type TerminalFrame, WEBTRANSPORT_PATH, encodeTerminalFrame, terminalFrameReader } from "./terminal-frames.js";
+
+interface FixtureFrame {
+    readonly kind: TerminalFrame["kind"];
+    readonly bytes?: string;
+    readonly text?: string;
+    readonly code?: number;
+    readonly reason?: string;
+}
+
+const FIXTURE = JSON.parse(readFileSync(new URL("./terminal-frames.fixture.json", import.meta.url), "utf8")) as {
+    session: string;
+    upgrade: string;
+    frames: { encoded: string; frame: FixtureFrame }[];
+    unreadable: string[];
+};
+
+const hex = (value: string): Uint8Array => Uint8Array.from(value.match(/../g) ?? [], (pair) => Number.parseInt(pair, 16));
+
+const frameOf = ({ kind, bytes, text, code, reason }: FixtureFrame): TerminalFrame => {
+    if (kind === "message") {
+        return { kind, text: text ?? "" };
+    }
+    if (kind === "close") {
+        return code === undefined ? { kind, reason: reason ?? "" } : { kind, code, reason: reason ?? "" };
+    }
+    return { kind, bytes: hex(bytes ?? "") };
+};
+
+const MAX = 16 * 1024 * 1024;
+
+test("the session's path and the upgrade are the ones the edge and the front answer", () => {
+    expect(FIXTURE.session).toBe(WEBTRANSPORT_PATH);
+    expect(FIXTURE.upgrade).toBe(TERMINAL_UPGRADE);
+});
+
+test("every frame the shared fixture names encodes to its bytes and reads back", () => {
+    expect(FIXTURE.frames.length).toBeGreaterThan(5);
+    for (const { encoded, frame } of FIXTURE.frames) {
+        expect(encodeTerminalFrame(frameOf(frame))).toEqual(hex(encoded));
+        expect(terminalFrameReader(MAX)(hex(encoded))).toEqual([frameOf(frame)]);
+    }
+});
+
+test("frames read the same however the stream's chunks cut them", () => {
+    const whole = hex(FIXTURE.frames.map(({ encoded }) => encoded).join(""));
+    const expected = FIXTURE.frames.map(({ frame }) => frameOf(frame));
+    for (const size of [1, 2, 3, 7, whole.length]) {
+        const read = terminalFrameReader(MAX);
+        const frames: TerminalFrame[] = [];
+        for (let at = 0; at < whole.length; at += size) {
+            frames.push(...read(whole.slice(at, at + size)));
+        }
+        expect(frames).toEqual(expected);
+    }
+});
+
+test("a frame no front sends ends the stream", () => {
+    for (const encoded of FIXTURE.unreadable) {
+        expect(() => terminalFrameReader(MAX)(hex(encoded))).toThrow();
+    }
+});

package/src/front/terminal-frames.ts

@@ -0,0 +1,102 @@
+// A terminal's messages on a stream no WebSocket rides (a WebTransport one): a kind byte, a big-endian u32 length, then
+// that many bytes, one WebSocket message's worth each. The front's Rust codec reads the fixture this file's test reads.
+
+import type { TerminalUpgrade } from "./generated/wire.js";
+
+export const TERMINAL_UPGRADE: TerminalUpgrade = "intentic-terminal";
+
+// Where a browser opens its WebTransport session, on the address of the sandbox the session's streams reach; the edge
+// answers it, never the sandbox.
+export const WEBTRANSPORT_PATH = "/system/transport";
+
+const HEADER_BYTES = 5;
+
+// Indexed by the kind byte.
+const KINDS = ["pane", "message", "close", "ping", "pong"] as const;
+
+export type TerminalFrame =
+    | { readonly kind: "pane" | "ping" | "pong"; readonly bytes: Uint8Array }
+    | { readonly kind: "message"; readonly text: string }
+    // No code is a close that names none, as a WebSocket's may.
+    | { readonly kind: "close"; readonly code?: number; readonly reason: string };
+
+const utf8 = new TextEncoder();
+const strictUtf8 = new TextDecoder("utf-8", { fatal: true });
+
+const payloadOf = (frame: TerminalFrame): Uint8Array => {
+    switch (frame.kind) {
+        case "message":
+            return utf8.encode(frame.text);
+        case "close": {
+            if (frame.code === undefined) {
+                return new Uint8Array(0);
+            }
+            const reason = utf8.encode(frame.reason);
+            const payload = new Uint8Array(2 + reason.length);
+            new DataView(payload.buffer).setUint16(0, frame.code);
+            payload.set(reason, 2);
+            return payload;
+        }
+        default:
+            return frame.bytes;
+    }
+};
+
+export const encodeTerminalFrame = (frame: TerminalFrame): Uint8Array => {
+    const payload = payloadOf(frame);
+    const encoded = new Uint8Array(HEADER_BYTES + payload.length);
+    encoded[0] = KINDS.indexOf(frame.kind);
+    new DataView(encoded.buffer).setUint32(1, payload.length);
+    encoded.set(payload, HEADER_BYTES);
+    return encoded;
+};
+
+const frameOf = (kind: (typeof KINDS)[number], payload: Uint8Array): TerminalFrame => {
+    switch (kind) {
+        case "message":
+            return { kind, text: strictUtf8.decode(payload) };
+        case "close": {
+            if (payload.length === 0) {
+                return { kind, reason: "" };
+            }
+            if (payload.length < 2) {
+                throw new Error("a close frame's code is two bytes");
+            }
+            const code = new DataView(payload.buffer, payload.byteOffset, 2).getUint16(0);
+            return { kind, code, reason: strictUtf8.decode(payload.subarray(2)) };
+        }
+        default:
+            return { kind, bytes: payload };
+    }
+};
+
+// Whole frames out of a stream's chunks however the chunks cut them. Throws on a kind, a length past `maxBytes` or a
+// payload no front sends, since nothing after it on the stream can be framed.
+export const terminalFrameReader = (maxBytes: number): ((chunk: Uint8Array) => TerminalFrame[]) => {
+    let pending = new Uint8Array(0);
+    return (chunk) => {
+        const joined = new Uint8Array(pending.length + chunk.length);
+        joined.set(pending);
+        joined.set(chunk, pending.length);
+        const view = new DataView(joined.buffer);
+        const frames: TerminalFrame[] = [];
+        let at = 0;
+        while (joined.length - at >= HEADER_BYTES) {
+            const kind = KINDS[joined[at] ?? KINDS.length];
+            if (kind === undefined) {
+                throw new Error(`no terminal frame is of kind ${joined[at]}`);
+            }
+            const length = view.getUint32(at + 1);
+            if (length > maxBytes) {
+                throw new Error(`a terminal frame of ${length} bytes is past ${maxBytes}`);
+            }
+            if (joined.length - at - HEADER_BYTES < length) {
+                break;
+            }
+            frames.push(frameOf(kind, joined.subarray(at + HEADER_BYTES, at + HEADER_BYTES + length)));
+            at += HEADER_BYTES + length;
+        }
+        pending = joined.slice(at);
+        return frames;
+    };
+};

package/src/ids/conversation-ids.ts

@@ -178,6 +178,13 @@ const digest = (text: string): string => {
 
 export const pushFixConversationId = (scope: string, signature: string): string => `${PUSH_FIX_PREFIX}${repoSlug(scope)}-${digest(signature)}`;
 
+// A red main-line check that no conversation still holding the work could take: keyed by the project and the moment its
+// red streak began, so every attempt at one streak shares a base and a later streak in the same project starts over.
+// Seconds in base36 keep it short; the workspace root is spelled `workspace`, since its project folder is empty.
+export const LAND_FIX_PREFIX = "land-fix-";
+export const landFixConversationId = (project: string, redSince: number): string =>
+    `${LAND_FIX_PREFIX}${repoSlug(project === "" ? "workspace" : project)}-${Math.floor(redSince / 1000).toString(36)}`;
+
 // ONE FAILURE, MANY ATTEMPTS, ONE LIVE ANSWER. The derived id above names the FAILURE; an attempt at it is a
 // conversation of its own, so starting over (another model, a clean worktree) never rewrites a record some other window
 // is showing, and every attempt keeps its own transcript, cost and URL. Attempt 1 wears the bare id, so every id minted

package/src/index.ts

@@ -40,6 +40,7 @@ import { skillsContract } from "./contracts/skills.contract.js";
 import { systemContract } from "./contracts/system.contract.js";
 import { translatorContract } from "./contracts/translator.contract.js";
 import { usageContract } from "./contracts/usage.contract.js";
+import { offloadContract } from "./contracts/offload.contract.js";
 import { vpnContract } from "./contracts/vpn.contract.js";
 import { workflowsContract } from "./contracts/workflows.contract.js";
 import { workspaceContract } from "./contracts/workspace.contract.js";
@@ -100,6 +101,7 @@ export { systemContract } from "./contracts/system.contract.js";
 export { translatorContract } from "./contracts/translator.contract.js";
 export { type PlanLimitsHeld, type PlanLimitsRefreshed, PlanLimitsRefreshedSchema, usageContract } from "./contracts/usage.contract.js";
 export { netdiskContract } from "./contracts/netdisk.contract.js";
+export { offloadContract } from "./contracts/offload.contract.js";
 export { vpnContract } from "./contracts/vpn.contract.js";
 export { workflowsContract } from "./contracts/workflows.contract.js";
 export { workspaceContract } from "./contracts/workspace.contract.js";
@@ -110,6 +112,7 @@ export * from "./events/resume.js";
 export * from "./events/system-events.js";
 export * from "./events/transcript.js";
 export * from "./events/land-breakage.js";
+export * from "./events/land-conflict.js";
 export * from "./events/verify-nudge.js";
 export * from "./events/watch-wake.js";
 export * from "./policy/request-status.js";
@@ -210,6 +213,7 @@ export * from "./schemas/secrets.js";
 export * from "./schemas/netdisk.js";
 export * from "./schemas/sessions.js";
 export * from "./schemas/settings.js";
+export * from "./schemas/settings-history.js";
 export * from "./schemas/share.js";
 export * from "./schemas/shared.js";
 export * from "./schemas/system-prompt.js";
@@ -219,17 +223,18 @@ export * from "./schemas/turn-break.js";
 export * from "./schemas/keep-warm.js";
 export * from "./schemas/providers/usage.js";
 export * from "./schemas/vpn.js";
+export * from "./schemas/offload.js";
 export * from "./schemas/webext.js";
 export * from "./schemas/workflows.js";
 export * from "./schemas/workspace/workspace-repos.js";
 export * from "./schemas/workspace/workspace-search.js";
+export * from "./schemas/workspace/mainline.js";
 export * from "./schemas/workspace/workspace-setup.js";
 export * from "./schemas/workspace/workspace-tree.js";
 export * from "./state/arrival.js";
 export * from "./state/definition.js";
 export * from "./policy/search-globs.js";
 export * from "./state/starter.js";
-export * from "./protocol/terminal-protocol.js";
 export * from "./text/title.js";
 export * from "./state/versions.js";
 export * from "./text/model-answer.js";
@@ -278,6 +283,7 @@ export const sandboxContract = {
     translator: translatorContract,
     usage: usageContract,
     vpn: vpnContract,
+    offload: offloadContract,
     exit: exitContract,
     netdisk: netdiskContract,
     workflows: workflowsContract,

package/src/protocol/container-requirements.test.ts

@@ -38,9 +38,8 @@ describe(`containerDrift`, () => {
         expect(containerDrift({ SANDBOX_PUBLIC_URL: `` })).toEqual([]);
     });
 
-    // A hosted Fly microVM has no grant by design, so this reports nothing on it.
-    it(`stays quiet on a hosted machine, which serves its address without dialling out`, () => {
-        expect(containerDrift({ SANDBOX_PUBLIC_URL: CURRENT.SANDBOX_PUBLIC_URL, SANDBOX_VM: `1` })).toEqual([]);
+    it(`holds a hosted machine to the same grant, since it dials the edge like any sandbox`, () => {
+        expect(containerDrift({ SANDBOX_PUBLIC_URL: CURRENT.SANDBOX_PUBLIC_URL, SANDBOX_VM: `1` }).map((gap) => gap.key)).toEqual([`reachability`]);
     });
 });
 

package/src/protocol/container-requirements.ts

@@ -7,8 +7,6 @@ export interface ContainerRequirement {
     readonly requires: readonly string[];
     // Absent `given` evidence means this sandbox never had the capability: not a fault, just unconfigured.
     readonly given: readonly string[];
-    // Row stays silent if any `unless` key is present: an alternate mechanism already satisfies the evidence.
-    readonly unless?: readonly string[];
     readonly enables: string;
     readonly lost: string;
     readonly repair: string;
@@ -25,8 +23,6 @@ export const CONTAINER_REQUIREMENTS: readonly ContainerRequirement[] = [
         key: "reachability",
         requires: ["SANDBOX_GRANT", "INGRESS_URL"],
         given: ["SANDBOX_PUBLIC_URL"],
-        // A Fly microVM's edge replays directly to it, so it holds no grant by design.
-        unless: ["SANDBOX_VM"],
         enables: "reaching this sandbox at its public address, from anywhere",
         lost:
             "Its public address answers 502 to everyone, including this browser when it is not on the same machine as the sandbox. " +
@@ -45,9 +41,7 @@ export interface ContainerGap {
 
 /** Empty means every requirement is met or not applicable; non-empty always means a setup rerun is needed. */
 export const containerDrift = (env: ContainerEnv): readonly ContainerGap[] =>
-    CONTAINER_REQUIREMENTS.filter(
-        (requirement) => requirement.given.every((name) => present(env, name)) && !(requirement.unless ?? []).some((name) => present(env, name)),
-    )
+    CONTAINER_REQUIREMENTS.filter((requirement) => requirement.given.every((name) => present(env, name)))
         .map((requirement) => ({
             key: requirement.key,
             missing: requirement.requires.filter((name) => !present(env, name)),

package/src/protocol/ingress-contract.fixture.json

@@ -0,0 +1,77 @@
+{
+    "publicKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAfiMlxPB/8tnjh6TYS3rVde63OXB/wY77KWWtJ39XjBg=\n-----END PUBLIC KEY-----\n",
+    "grants": [
+        { "token": "ig1.eyJzdWIiOiJhYmNkZWYwMTIzNDUiLCJpYXQiOjE3MDAwMDAwMDB9.wdpBpqmMl21mqAZvRSYi4WfDejreTKDxHfOQp_sBKOTQB0_N2trL6iFcRxFUDrGBnGHmYnv-x66FgU_j57ZECA", "claim": {"sandboxId": "abcdef012345", "issuedAt": 1700000000} },
+        { "token": "ig1.eyJzdWIiOiIwMTIzNDU2Nzg5YWIiLCJpYXQiOjE3NTcwMDAwMDAsImV4dHJhIjoiaWdub3JlZCJ9.NK2BR2L_ycCACdmnbZgkg7sovw-Nhlt5vIL6ldArAx_jN9XOh-k1wisviROAgU40YGBgUASIgA6Wdn5SyYHHCA", "claim": {"sandboxId": "0123456789ab", "issuedAt": 1757000000} },
+        { "token": "ig1.eyJpYXQiOjE3MDAwMDAwMDAsInN1YiI6ImFiY2RlZjAxMjM0NSJ9.AenzYQn3Opfc-Sg_vkBrMEIOnCFZ3a46oSzjABAWyoVe3GP0vXlIM8MFgddHDQc7yow4kdfn1kHcUcsOoKkLCg", "claim": {"sandboxId": "abcdef012345", "issuedAt": 1700000000} },
+        { "token": "ig1.eyJzdWIiOiJhYmNkZWYwMTIzNDUiLCJpYXQiOjE3MDAwMDAwMDB9.wNpBpqmMl21mqAZvRSYi4WfDejreTKDxHfOQp_sBKOTQB0_N2trL6iFcRxFUDrGBnGHmYnv-x66FgU_j57ZECA", "claim": null },
+        { "token": "ig1.eiJzdWIiOiJhYmNkZWYwMTIzNDUiLCJpYXQiOjE3MDAwMDAwMDB9.wdpBpqmMl21mqAZvRSYi4WfDejreTKDxHfOQp_sBKOTQB0_N2trL6iFcRxFUDrGBnGHmYnv-x66FgU_j57ZECA", "claim": null },
+        { "token": "ig1.eyJzdWIiOiJhYmNkZWYwMTIzNDUiLCJpYXQiOjE3MDAwMDAwMDB9.Ac2ofn7IxD3M51pchXEycOPg4TP_kiTzu-aTVowDLTirjVzYrvfJ-ntrzPbQg-3RpBhmc53yP7s7iWyOgGWuAw", "claim": null },
+        { "token": "ig2.eyJzdWIiOiJhYmNkZWYwMTIzNDUiLCJpYXQiOjE3MDAwMDAwMDB9.wdpBpqmMl21mqAZvRSYi4WfDejreTKDxHfOQp_sBKOTQB0_N2trL6iFcRxFUDrGBnGHmYnv-x66FgU_j57ZECA", "claim": null },
+        { "token": "eyJzdWIiOiJhYmNkZWYwMTIzNDUiLCJpYXQiOjE3MDAwMDAwMDB9.wdpBpqmMl21mqAZvRSYi4WfDejreTKDxHfOQp_sBKOTQB0_N2trL6iFcRxFUDrGBnGHmYnv-x66FgU_j57ZECA", "claim": null },
+        { "token": "ig1.eyJzdWIiOiJhYmNkZWYwMTIzNDUiLCJpYXQiOjE3MDAwMDAwMDB9.wdpBpqmMl21mqAZvRSYi4WfDejreTKDxHfOQp_sBKOTQB0_N2trL6iFcRxFUDrGBnGHmYnv-x66FgU_j57ZECA.wdpBpqmMl21mqAZvRSYi4WfDejreTKDxHfOQp_sBKOTQB0_N2trL6iFcRxFUDrGBnGHmYnv-x66FgU_j57ZECA", "claim": null },
+        { "token": "ig1.eyJzdWIiOiJhYmNkZWYwMTIzNDUiLCJpYXQiOjE3MDAwMDAwMDB9.", "claim": null },
+        { "token": "", "claim": null },
+        { "token": "ig1", "claim": null },
+        { "token": "ig1..", "claim": null },
+        { "token": "ig1.%%%.%%%", "claim": null },
+        { "token": "ig1.eyJzdWIiOiJBQkNERUYwMTIzNDUiLCJpYXQiOjE3MDAwMDAwMDB9.CbPEciFki-GXJnUcS5F9_9uXUOw5tWhv3iS69BjuQpSmsA72_xnvYUIjhAMiBPI98XBQ9-zKc9GSPJIFGQqaDA", "claim": null },
+        { "token": "ig1.eyJzdWIiOiJhYmNkZWYwMTIzNCIsImlhdCI6MTcwMDAwMDAwMH0.qfJbxpVtbcymaweaCu9fUounkldkMy4HSdllEDlHs5Yq8b11XxiHLguDyvqubXcMGCuVVygCeg2MjU3i0vEuDA", "claim": null },
+        { "token": "ig1.eyJzdWIiOiJhYmNkZWYwMTIzNDUiLCJpYXQiOiIxNzAwMDAwMDAwIn0.BI6UT1aTaN01bGZyI9SHc_qIf9S-JlpmNtiBd8by_giZCq8pQIJCBKIutYZW0mmqCF0YHf0NHc9icq1h9Wr7BA", "claim": null },
+        { "token": "ig1.eyJzdWIiOiJhYmNkZWYwMTIzNDUifQ.Aa5FeLKazhsr2IvYZ2p5BJmLL1qvQWReXeCKt5gxCq9PqSaAnn8Pa6PJp0jiaXY5FIbc_S9MFrUCeEfQ6vnkBQ", "claim": null },
+        { "token": "ig1.eyJzdWIiOjEyMzQ1Njc4OTAxMiwiaWF0IjoxNzAwMDAwMDAwfQ.kb_lMTBvFS4nzTmqLf-T7l9IF8PHaPPkP5HB1T0yd0IRWqYJnIZH2eoKexv7e6aA2PkqCpe-B1FL8Nbu4qPvDg", "claim": null },
+        { "token": "ig1.bm90IGpzb24.Ffec27cYSbvKvjlxtSUIFFX7sGo3Zp4BxotW02rFwcJHfJikM51Zfzn3_0Rg8coR4y43iOUA2u-ZOcBJg4mmDA", "claim": null },
+        { "token": "ig1.bnVsbA.lFa3FNSkMcf3WCyjdb87YRVdt8h3aSzt4cignx9Rkwq6drwl12m0rlrmzdPkLjsdrQdL1oWZ2E2MGuo2CMeSBw", "claim": null },
+        { "token": "ig1.WyJhYmNkZWYwMTIzNDUiLDE3MDAwMDAwMDBd.BWFTD0bHKDBAEWwhYq6F-cWo_HXEC8UvDWkrTmafOycvTZUHvVOjWy_97OYl_pF-svCO1vbeumhF89ybhqv4Dw", "claim": null }
+    ],
+    "owners": [
+        { "host": "sandbox-abcdef012345.sbx.example.test", "owner": "abcdef012345" },
+        { "host": "sandbox-abcdef012345.sbx.example.test:443", "owner": "abcdef012345" },
+        { "host": "preview-web-app-abcdef012345.sbx.example.test:443", "owner": "abcdef012345" },
+        { "host": "port-0f0f0f0f0f0f-abcdef012345.sbx.example.dev", "owner": "abcdef012345" },
+        { "host": "public-1a2b3c4d5e6f-abcdef012345.sbx.example.dev", "owner": "abcdef012345" },
+        { "host": "SANDBOX-abcdef012345.sbx.example.test", "owner": "abcdef012345" },
+        { "host": "-abcdef012345.example.com", "owner": "abcdef012345" },
+        { "host": "sandbox-abcdef012345", "owner": "abcdef012345" },
+        { "host": "ingress.sbx.example.test", "owner": null },
+        { "host": "sbx.example.test", "owner": null },
+        { "host": "abcdef012345.local.sbx.example.dev", "owner": null },
+        { "host": "sandbox-ABCDEF012345.sbx.example.test", "owner": null },
+        { "host": "sandbox-abcdef01234.sbx.example.test", "owner": null },
+        { "host": "sandbox-abcdef012345x.sbx.example.test", "owner": null },
+        { "host": "sandbox-abcdef012345-.sbx.example.test", "owner": null },
+        { "host": "[::1]:8788", "owner": null },
+        { "host": "127.0.0.1:8788", "owner": null },
+        { "host": "", "owner": null }
+    ],
+    "lanes": [
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/workspace/media?path=a.mp4", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "POST", "path": "/workspace/upload?path=a", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test:443", "method": "GET", "path": "/system/runners/git/app/info/refs?service=git-upload-pack", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "POST", "path": "/system/runners/git/app/git-receive-pack", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/system/sync/ssh", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/extensions/abc/bundle", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/diff/raw?a=1?b=2", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/bundles/download?ticket=x", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "POST", "path": "/workspace/upload-archive", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "HEAD", "path": "/workspace/raw?path=a", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "OPTIONS", "path": "/workspace/raw", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "OPTIONS", "path": "/system/runners/git/app/git-upload-pack", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "get", "path": "/workspace/raw?path=a", "lane": "bulk" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/workspace/thumb?path=a.png", "lane": "interactive" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "POST", "path": "/workspace/upload-diff", "lane": "interactive" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/agents", "lane": "interactive" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/system/terminal?ticket=t", "lane": "interactive" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "POST", "path": "/workspace/raw", "lane": "interactive" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/workspace/raw/", "lane": "interactive" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/system/runners/git//info/refs", "lane": "interactive" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/x/anything/at/all", "lane": "interactive" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/", "lane": "interactive" },
+        { "host": "sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "", "lane": "interactive" },
+        { "host": "preview-web-abcdef012345.sbx.example.test", "method": "GET", "path": "/agents", "lane": "bulk" },
+        { "host": "port-1a2b3c4d5e6f-abcdef012345.sbx.example.test", "method": "GET", "path": "/", "lane": "bulk" },
+        { "host": "Sandbox-abcdef012345.sbx.example.test", "method": "GET", "path": "/agents", "lane": "bulk" },
+        { "host": "sbx.example.test", "method": "GET", "path": "/agents", "lane": "bulk" },
+        { "host": "", "method": "GET", "path": "/agents", "lane": "bulk" }
+    ]
+}

package/src/protocol/ingress-contract.test.ts

@@ -1,5 +1,14 @@
 import { generateKeyPairSync } from "node:crypto";
-import { hostOwnerId, mintReachabilityGrant, verifyReachabilityGrant } from "./ingress-contract.js";
+import { readFileSync } from "node:fs";
+import { hostOwnerId, type ReachabilityGrant, mintReachabilityGrant, verifyReachabilityGrant } from "./ingress-contract.js";
+
+// The edge's rules as both implementations must answer them; the Rust edge reads the same file. Its grants were minted
+// by a throwaway pair whose private half was never kept, so a new grant case takes a new pair and every token again.
+const FIXTURE = JSON.parse(readFileSync(new URL("./ingress-contract.fixture.json", import.meta.url), "utf8")) as {
+    readonly publicKey: string;
+    readonly grants: readonly { readonly token: string; readonly claim: ReachabilityGrant | null }[];
+    readonly owners: readonly { readonly host: string; readonly owner: string | null }[];
+};
 
 const pemPair = (): { privateKey: string; publicKey: string } => {
     const { privateKey, publicKey } = generateKeyPairSync("ed25519");
@@ -31,10 +40,11 @@ describe("reachability grant", () => {
         expect(verifyReachabilityGrant(keys.publicKey, `${prefix}.${forged}.${signature}`)).toBeUndefined();
     });
 
-    it("answers undefined for garbage rather than throwing", () => {
-        const keys = pemPair();
-        for (const junk of ["", "ig1", "ig1..", "nonsense.a.b", "ig2.a.b", "ig1.%%%.%%%"]) {
-            expect(verifyReachabilityGrant(keys.publicKey, junk)).toBeUndefined();
+    it("answers every grant in the shared fixture as it states, and garbage with undefined rather than a throw", () => {
+        // Both verdicts, so the loop below can never pass by holding only one kind of case.
+        expect(new Set(FIXTURE.grants.map(({ claim }) => (claim === null ? "refused" : "accepted")))).toEqual(new Set(["accepted", "refused"]));
+        for (const { token, claim } of FIXTURE.grants) {
+            expect({ token, claim: verifyReachabilityGrant(FIXTURE.publicKey, token) ?? null }).toEqual({ token, claim });
         }
     });
 
@@ -44,27 +54,9 @@ describe("reachability grant", () => {
 });
 
 describe("hostOwnerId", () => {
-    it("owns the daemon's own name and every labelled name", () => {
-        expect(hostOwnerId(`sandbox-${SANDBOX_ID}.sbx.example.dev`)).toBe(SANDBOX_ID);
-        expect(hostOwnerId(`preview-operator-${SANDBOX_ID}.sbx.example.dev`)).toBe(SANDBOX_ID);
-        expect(hostOwnerId(`port-0f0f0f0f0f0f-${SANDBOX_ID}.sbx.example.dev`)).toBe(SANDBOX_ID);
-        expect(hostOwnerId(`public-1a2b3c4d5e6f-${SANDBOX_ID}.sbx.example.dev`)).toBe(SANDBOX_ID);
-    });
-
-    it("ignores a port suffix", () => {
-        expect(hostOwnerId(`sandbox-${SANDBOX_ID}.sbx.example.dev:443`)).toBe(SANDBOX_ID);
-    });
-
-    it("owns nothing that does not end in a 12-hex tail", () => {
-        // The ingress's own door, the zone apex, the loopback name's bare-id label, and a near-miss tail.
-        for (const host of [
-            "ingress.sbx.example.dev",
-            "sbx.example.dev",
-            `${SANDBOX_ID}.local.sbx.example.dev`,
-            "sandbox-abc123def45.sbx.example.dev",
-            "",
-        ]) {
-            expect(hostOwnerId(host)).toBeUndefined();
+    it("owns every host in the shared fixture as it states, port or not", () => {
+        for (const { host, owner } of FIXTURE.owners) {
+            expect({ host, owner: hostOwnerId(host) ?? null }).toEqual({ host, owner });
         }
     });
 });

package/src/protocol/ingress-contract.ts

@@ -73,31 +73,12 @@ export const INGRESS_GRANT_HEADER = "x-intentic-grant";
 export const ENV_INGRESS_URL = "INGRESS_URL";
 export const ENV_SANDBOX_GRANT = "SANDBOX_GRANT";
 
-// The daemon-side surface
-
-// Daemon-side tunnel behavior this contract requires: dial, register, forward to the loopback listener, and reconnect
-// forever with backoff, never giving up. `close()` is for shutdown and tests.
-export interface IngressTunnelOptions {
-    // e.g. https://ingress.<zone>; the daemon derives the wss:// door itself via INGRESS_TUNNEL_PATH.
-    readonly url: string;
-    readonly grant: string;
-    // The daemon's own loopback listener; every h2 stream lands there as a plain HTTP/1.1 request or upgrade.
-    readonly targetPort: number;
-    readonly log: (message: string, error?: unknown) => void;
-}
-
-export interface IngressTunnelHandle {
-    readonly close: () => Promise<void>;
-    // For /health and the boot log: whether the tunnel currently holds a registered session.
-    readonly connected: () => boolean;
-}
-
-export type StartIngressTunnel = (options: IngressTunnelOptions) => IngressTunnelHandle;
-
-// What the ingress side must also honor, enforced by ingress-protocol tests:
+// What the edge (_platform/ingress, Rust) must also honor, held by its suites and by ingress-contract.fixture.json:
 // - Register: verify the grant offline; if PLATFORM_URL is set, check the sandbox exists (GET /api/reachability/<id>)
 //   and cache the answer, failing open if the platform doesn't respond. A 404 refuses the tunnel.
 // - Displacement: a new tunnel for an id closes the old session (code 4001) and takes the registration.
+// - Lanes: a tunnel naming the bulk lane (tunnel-lanes.ts) is held beside the interactive one and displaces only its
+//   own kind; only the interactive lane is the sandbox's home in the cluster.
 // - Liveness: WebSocket ping every 15s; a peer silent for 45s is unregistered.
 // - Routing: host maps via hostOwnerId to a registered tunnel; no tunnel answers 502 naming the sandbox label, with
 //   the verdict header and CORS of edge-verdict.ts, and admits the preflight of the request it is about to refuse.