@namzu/sandbox 13.0.0 → 14.0.0

package/dist/testing/sandbox-conformance.d.ts

@@ -0,0 +1,193 @@
+/**
+ * The {@link Sandbox} contract, as a suite a backend author runs against
+ * their own implementation.
+ *
+ * ## Why this exists
+ *
+ * `@namzu/sdk`'s `Sandbox` interface is the one thing every backend in this
+ * package promises to implement the same way — `exec`'s exit codes, the
+ * `AbortSignal` contract, a `writeFile`/`readFile` round trip, terminal
+ * ownership on `destroy()` — and until now nothing PROVED that two backends
+ * agreed on any of it. Each backend carried its own bespoke test file
+ * (`sandbox-surface.test.ts`, `backend.test.ts`, …), written by whoever
+ * built that backend, checking whatever that author thought to check. A
+ * shared contract can be silently narrower than either file: this suite is
+ * the thing that would have caught it.
+ *
+ * ## Why it takes its runner as an argument
+ *
+ * The same shape as `@namzu/sdk/testing`'s checkpoint-store and provider
+ * driver suites, and for the same two reasons: `@namzu/sandbox` gains no
+ * test dependency from publishing it, and a caller can pass a RECORDING
+ * `describe`/`it` and run the whole contract as ordinary code — which is
+ * how `testing/__tests__/conformance-fails-a-broken-sandbox.test.ts`
+ * proves a deliberately wrong `Sandbox` fails it.
+ *
+ * ## What is asserted, and what deliberately is not
+ *
+ * Contract behaviour only — never a backend-specific object, field or
+ * error string. A case never inspects `sandbox.constructor.name`, never
+ * matches an error message, and never assumes a particular
+ * {@link SandboxEnvironment}. `openTerminal` and `openTcpConnection` are
+ * OPTIONAL on {@link Sandbox} by the SDK's own contract — a backend that
+ * cannot honour one must omit it rather than accept and ignore it — so a
+ * factory whose sandbox omits either capability skips that section rather
+ * than failing it. Every other section runs against every sandbox.
+ *
+ * ## Where it runs today
+ *
+ * Both `backends/kubernetes/__tests__/conformance.test.ts` and
+ * `backends/firecracker/__tests__/conformance.test.ts` call this against a
+ * real `agent/agent.cjs` on a loopback socket — proving the suite is
+ * backend-agnostic rather than one backend's tests wearing a new name.
+ * `packages/sandbox/k8s/scripts/contract-suite.mjs` runs it a third time,
+ * against a live cluster.
+ *
+ * ## Not published from `@namzu/sandbox`'s entry point
+ *
+ * The package has no `testing` subpath today (unlike `@namzu/sdk`), and
+ * this batch does not add one — promoting this to a public import path is
+ * a deliberate, separate decision. Within the monorepo a caller imports it
+ * by relative path, exactly as the two files above do:
+ *
+ * ```ts sketch
+ * import { defineSandboxConformance } from '../../../testing/sandbox-conformance.js'
+ *
+ * defineSandboxConformance({
+ *   describe, it, expect,
+ *   label: 'my-backend',
+ *   makeSandbox: async () => ({ sandbox: await myBackend.create(), dispose: async () => {} }),
+ * })
+ * ```
+ */
+import type { OpenTerminalOptions, Sandbox, TerminalSession } from '@namzu/sdk';
+import type { ConformanceAssertion, ConformanceDescribe, ConformanceExpect, ConformanceIt } from '@namzu/sdk/testing';
+/**
+ * The contract revision these assertions express. Carried on the describe
+ * label so a failure is legible on sight as "the sandbox contract", the
+ * same convention `PROVIDER_DRIVER_CONTRACT_VERSION` uses — raised only
+ * when a case is ADDED or TIGHTENED, never on a rewording.
+ */
+export declare const SANDBOX_CONTRACT_VERSION = 1;
+/** A sandbox to test, plus whatever teardown building it required. */
+export interface SandboxConformanceHandle {
+    readonly sandbox: Sandbox;
+    /**
+     * Called after each case, pass or fail — closes fixture servers, restores
+     * environment variables, removes temp directories. Distinct from
+     * `sandbox.destroy()`, which the suite calls itself (idempotently) as
+     * part of every case's teardown; `dispose` is for what `makeSandbox`
+     * itself stood up, not for the sandbox's own lifecycle.
+     */
+    dispose?(): void | Promise<void>;
+}
+/**
+ * Build one fresh {@link Sandbox}. Called once per case, so no case can be
+ * affected by another's writes, aborts or destroys — the suite never
+ * assumes a shared instance and never reuses one across cases.
+ */
+export type MakeSandbox = () => SandboxConformanceHandle | Promise<SandboxConformanceHandle>;
+export interface SandboxConformanceOptions {
+    readonly describe: ConformanceDescribe;
+    readonly it: ConformanceIt;
+    readonly expect: ConformanceExpect;
+    readonly makeSandbox: MakeSandbox;
+    /** Names the backend in test output. Defaults to `sandbox`. */
+    readonly label?: string;
+    /**
+     * Whether this backend's guest can run the `openTcpConnection` positive
+     * case's listener at all — by default {@link nodeGuestListener}, `node
+     * -e`. Defaults to `true`: every backend this suite ships against runs
+     * `agent/agent.cjs` in the guest, and that agent IS node, so node on the
+     * guest's own `PATH` is a precondition of the agent existing rather than
+     * an extra capability this suite demands.
+     *
+     * Set `false` for a guest that cannot run a listener this way at all
+     * (no `openTerminal`, or an image with neither node nor a substitute) —
+     * the case then SKIPS, its own title stating why, rather than failing a
+     * backend for a capability its contract never promised. A backend that
+     * can run *some* listener, just not node, keeps this `true` (or omits
+     * it) and supplies {@link SandboxConformanceOptions.guestListenerCommand}
+     * instead.
+     */
+    readonly guestCanRunNode?: boolean;
+    /**
+     * Overrides the program the `openTcpConnection` positive case starts
+     * inside the guest. Defaults to {@link nodeGuestListener}. A guest
+     * without node but with, say, busybox `nc` can supply its own command as
+     * long as it reports the bound port the way
+     * {@link GuestListenerCommand.parsePort} expects.
+     */
+    readonly guestListenerCommand?: () => GuestListenerCommand;
+}
+/**
+ * A program the `openTcpConnection` positive case can start INSIDE a guest
+ * through {@link Sandbox.openTerminal}, and dial back into over
+ * `openTcpConnection` itself.
+ *
+ * Starting the listener in the guest — rather than in the orchestrator/test
+ * process, which is what this case used to do — is the whole point: a
+ * listener on the HOST'S loopback only ever proves anything for a backend
+ * whose "guest" happens to share that loopback (a Firecracker fixture over a
+ * local socket, a fake-agent-in-this-process kubernetes test). It never
+ * proves anything for a real remote guest, which cannot dial the
+ * orchestrator's loopback at all — that gap is exactly what let the case
+ * pass in every colocated fixture and fail the one time it ran against a
+ * live cluster.
+ */
+export interface GuestListenerCommand {
+    /** The program `openTerminal` runs as the session's top-level process. */
+    readonly command: string;
+    readonly args: readonly string[];
+    /**
+     * Reads the port the listener bound out of everything it has printed to
+     * its terminal so far. Returns `undefined` until the listener has
+     * reported one — the suite polls this as output arrives rather than
+     * parsing a single chunk, because a pty may deliver the report split
+     * across reads.
+     */
+    parsePort(output: string): number | undefined;
+}
+/**
+ * The default {@link GuestListenerCommand}: `node -e` binding an ephemeral
+ * port on the GUEST's own loopback, echoing `conformance-reply:<payload>`
+ * back for the first chunk of the one connection it accepts, then reporting
+ * the bound port on its own stdout — the only way the host, which cannot
+ * inspect a real remote guest's open ports any other way, learns which port
+ * to dial.
+ *
+ * Every backend this suite ships against runs `agent/agent.cjs` in the
+ * guest, which is itself node — so node on the guest's `PATH` is not an
+ * extra requirement this suite invents, it is a precondition of the agent
+ * existing at all. A backend whose guest genuinely cannot run node (or
+ * cannot run `openTerminal`) declares that through
+ * {@link SandboxConformanceOptions.guestCanRunNode} or supplies its own
+ * command via {@link SandboxConformanceOptions.guestListenerCommand}.
+ */
+export declare function nodeGuestListener(): GuestListenerCommand;
+/**
+ * Start `listener` through `openTerminal`, and resolve once it has reported
+ * the port it bound.
+ *
+ * The returned `stop()` kills the terminal's owned process tree — the exact
+ * ownership guarantee the `openTerminal` section above already proves
+ * `destroy()` gets for free, used here to tear the listener down without
+ * waiting for the whole sandbox to go away.
+ *
+ * Takes `openTerminal` as a plain function rather than a `Sandbox`, so a
+ * unit test can exercise the port-parsing and exit-races above without a
+ * `Sandbox` fixture — see `__tests__/guest-listener.test.ts`.
+ */
+export declare function startGuestListener(openTerminal: (options: OpenTerminalOptions) => Promise<TerminalSession>, listener: GuestListenerCommand): Promise<{
+    readonly port: number;
+    stop(): Promise<void>;
+}>;
+/**
+ * Register the {@link Sandbox} contract against one backend.
+ *
+ * Call it once per backend. It registers cases through the supplied
+ * `describe`/`it`; it does not run them.
+ */
+export declare function defineSandboxConformance(options: SandboxConformanceOptions): void;
+export type { ConformanceAssertion, ConformanceDescribe, ConformanceExpect, ConformanceIt };
+//# sourceMappingURL=sandbox-conformance.d.ts.map

package/dist/testing/sandbox-conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-conformance.d.ts","sourceRoot":"","sources":["../../src/testing/sandbox-conformance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH,OAAO,KAAK,EACX,mBAAmB,EACnB,OAAO,EAEP,eAAe,EACf,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EACX,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,MAAM,oBAAoB,CAAA;AAE3B;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAA;AAEzC,sEAAsE;AACtE,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAChC;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,wBAAwB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAA;AAE5F,MAAM,WAAW,yBAAyB;IACzC,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAA;IACtC,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;IAClC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAA;IACjC,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAA;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,oBAAoB,CAAA;CAC1D;AAkCD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,oBAAoB;IACpC,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC;;;;;;OAMG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;CAC7C;AAKD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,IAAI,oBAAoB,CAsBxD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CACvC,YAAY,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,eAAe,CAAC,EACxE,QAAQ,EAAE,oBAAoB,GAC5B,OAAO,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CA0C3D;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,IAAI,CAiWjF;AAKD,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,aAAa,EAAE,CAAA"}

package/dist/testing/sandbox-conformance.js

@@ -0,0 +1,465 @@
+/**
+ * The {@link Sandbox} contract, as a suite a backend author runs against
+ * their own implementation.
+ *
+ * ## Why this exists
+ *
+ * `@namzu/sdk`'s `Sandbox` interface is the one thing every backend in this
+ * package promises to implement the same way — `exec`'s exit codes, the
+ * `AbortSignal` contract, a `writeFile`/`readFile` round trip, terminal
+ * ownership on `destroy()` — and until now nothing PROVED that two backends
+ * agreed on any of it. Each backend carried its own bespoke test file
+ * (`sandbox-surface.test.ts`, `backend.test.ts`, …), written by whoever
+ * built that backend, checking whatever that author thought to check. A
+ * shared contract can be silently narrower than either file: this suite is
+ * the thing that would have caught it.
+ *
+ * ## Why it takes its runner as an argument
+ *
+ * The same shape as `@namzu/sdk/testing`'s checkpoint-store and provider
+ * driver suites, and for the same two reasons: `@namzu/sandbox` gains no
+ * test dependency from publishing it, and a caller can pass a RECORDING
+ * `describe`/`it` and run the whole contract as ordinary code — which is
+ * how `testing/__tests__/conformance-fails-a-broken-sandbox.test.ts`
+ * proves a deliberately wrong `Sandbox` fails it.
+ *
+ * ## What is asserted, and what deliberately is not
+ *
+ * Contract behaviour only — never a backend-specific object, field or
+ * error string. A case never inspects `sandbox.constructor.name`, never
+ * matches an error message, and never assumes a particular
+ * {@link SandboxEnvironment}. `openTerminal` and `openTcpConnection` are
+ * OPTIONAL on {@link Sandbox} by the SDK's own contract — a backend that
+ * cannot honour one must omit it rather than accept and ignore it — so a
+ * factory whose sandbox omits either capability skips that section rather
+ * than failing it. Every other section runs against every sandbox.
+ *
+ * ## Where it runs today
+ *
+ * Both `backends/kubernetes/__tests__/conformance.test.ts` and
+ * `backends/firecracker/__tests__/conformance.test.ts` call this against a
+ * real `agent/agent.cjs` on a loopback socket — proving the suite is
+ * backend-agnostic rather than one backend's tests wearing a new name.
+ * `packages/sandbox/k8s/scripts/contract-suite.mjs` runs it a third time,
+ * against a live cluster.
+ *
+ * ## Not published from `@namzu/sandbox`'s entry point
+ *
+ * The package has no `testing` subpath today (unlike `@namzu/sdk`), and
+ * this batch does not add one — promoting this to a public import path is
+ * a deliberate, separate decision. Within the monorepo a caller imports it
+ * by relative path, exactly as the two files above do:
+ *
+ * ```ts sketch
+ * import { defineSandboxConformance } from '../../../testing/sandbox-conformance.js'
+ *
+ * defineSandboxConformance({
+ *   describe, it, expect,
+ *   label: 'my-backend',
+ *   makeSandbox: async () => ({ sandbox: await myBackend.create(), dispose: async () => {} }),
+ * })
+ * ```
+ */
+/**
+ * The contract revision these assertions express. Carried on the describe
+ * label so a failure is legible on sight as "the sandbox contract", the
+ * same convention `PROVIDER_DRIVER_CONTRACT_VERSION` uses — raised only
+ * when a case is ADDED or TIGHTENED, never on a rewording.
+ */
+export const SANDBOX_CONTRACT_VERSION = 1;
+/** Assert `call()` rejects. The contract cares that admission was refused, never the message. */
+async function expectRejects(expect, call) {
+    let rejected = false;
+    try {
+        await call();
+    }
+    catch {
+        rejected = true;
+    }
+    expect(rejected).toBe(true);
+}
+/** Assert `call()` resolves — the inverse check, for the rare case a rejection is the defect. */
+async function expectResolves(expect, call) {
+    let threw;
+    try {
+        await call();
+    }
+    catch (error) {
+        threw = error;
+    }
+    expect(threw === undefined).toBe(true);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** What {@link nodeGuestListener} has its script print once it is bound. */
+const NODE_LISTENER_MARKER = 'namzu-conformance-listening:';
+/**
+ * The default {@link GuestListenerCommand}: `node -e` binding an ephemeral
+ * port on the GUEST's own loopback, echoing `conformance-reply:<payload>`
+ * back for the first chunk of the one connection it accepts, then reporting
+ * the bound port on its own stdout — the only way the host, which cannot
+ * inspect a real remote guest's open ports any other way, learns which port
+ * to dial.
+ *
+ * Every backend this suite ships against runs `agent/agent.cjs` in the
+ * guest, which is itself node — so node on the guest's `PATH` is not an
+ * extra requirement this suite invents, it is a precondition of the agent
+ * existing at all. A backend whose guest genuinely cannot run node (or
+ * cannot run `openTerminal`) declares that through
+ * {@link SandboxConformanceOptions.guestCanRunNode} or supplies its own
+ * command via {@link SandboxConformanceOptions.guestListenerCommand}.
+ */
+export function nodeGuestListener() {
+    const script = [
+        "const net = require('node:net');",
+        'const server = net.createServer((socket) => {',
+        "  socket.once('data', (chunk) => {",
+        "    socket.end(Buffer.concat([Buffer.from('conformance-reply:'), chunk]));",
+        '  });',
+        '});',
+        "server.listen(0, '127.0.0.1', () => {",
+        `  process.stdout.write(${JSON.stringify(NODE_LISTENER_MARKER)} + server.address().port + '\\n');`,
+        '});',
+    ].join('\n');
+    return {
+        command: 'node',
+        args: ['-e', script],
+        parsePort(output) {
+            const marker = output.indexOf(NODE_LISTENER_MARKER);
+            if (marker === -1)
+                return undefined;
+            const match = /\d+/.exec(output.slice(marker + NODE_LISTENER_MARKER.length));
+            return match ? Number(match[0]) : undefined;
+        },
+    };
+}
+/**
+ * Start `listener` through `openTerminal`, and resolve once it has reported
+ * the port it bound.
+ *
+ * The returned `stop()` kills the terminal's owned process tree — the exact
+ * ownership guarantee the `openTerminal` section above already proves
+ * `destroy()` gets for free, used here to tear the listener down without
+ * waiting for the whole sandbox to go away.
+ *
+ * Takes `openTerminal` as a plain function rather than a `Sandbox`, so a
+ * unit test can exercise the port-parsing and exit-races above without a
+ * `Sandbox` fixture — see `__tests__/guest-listener.test.ts`.
+ */
+export async function startGuestListener(openTerminal, listener) {
+    const terminal = await openTerminal({
+        command: listener.command,
+        args: listener.args,
+        size: { cols: 80, rows: 24 },
+    });
+    let output = '';
+    const port = await new Promise((resolve, reject) => {
+        const unsubscribe = terminal.onData((chunk) => {
+            output += chunk;
+            const found = listener.parsePort(output);
+            if (found !== undefined) {
+                unsubscribe();
+                resolve(found);
+            }
+        });
+        void terminal.exited.then((result) => {
+            // A settled promise ignores a later resolve/reject, so this is a
+            // no-op on the path where the port was already found and `stop()`
+            // is what causes this exit — it only fires the rejection when the
+            // listener died before ever reporting a port.
+            if (listener.parsePort(output) === undefined) {
+                unsubscribe();
+                reject(new Error(`guest listener exited before reporting a port (exit code ${result.exitCode}): ${output || '<no output>'}`));
+            }
+        });
+    });
+    return {
+        port,
+        async stop() {
+            terminal.kill();
+            await terminal.exited.catch(() => { });
+        },
+    };
+}
+/**
+ * Register the {@link Sandbox} contract against one backend.
+ *
+ * Call it once per backend. It registers cases through the supplied
+ * `describe`/`it`; it does not run them.
+ */
+export function defineSandboxConformance(options) {
+    const { describe, it, expect, makeSandbox } = options;
+    const label = options.label ?? 'sandbox';
+    const guestCanRunNode = options.guestCanRunNode ?? true;
+    const guestListenerCommand = options.guestListenerCommand ?? nodeGuestListener;
+    /**
+     * Run `body` against a sandbox built for this case alone.
+     *
+     * Destroys the sandbox itself (idempotent, so a body that already
+     * destroyed it costs nothing extra) before calling `dispose`, so a
+     * case that forgets to release a pod/microVM does not leak one — the
+     * same reasoning `withStore`'s `finally` states for a leaked temp
+     * directory: a suite that is expensive to run red is a suite people
+     * stop running.
+     */
+    const withSandbox = (body) => async () => {
+        const handle = await makeSandbox();
+        try {
+            await body(handle.sandbox);
+        }
+        finally {
+            await handle.sandbox.destroy().catch(() => { });
+            await handle.dispose?.();
+        }
+    };
+    describe(`${label} — sandbox contract v${SANDBOX_CONTRACT_VERSION}`, () => {
+        describe('exec', () => {
+            it('reports the exit code and streams stdout/stderr as the command runs', withSandbox(async (sandbox) => {
+                const chunks = [];
+                const result = await sandbox.exec('/bin/sh', ['-c', 'echo conformance-out; echo conformance-err 1>&2; exit 7'], { onOutput: (chunk) => chunks.push({ ...chunk }) });
+                expect(result.exitCode).toBe(7);
+                expect(result.timedOut).toBe(false);
+                expect(result.stdout).toMatch(/conformance-out/);
+                expect(result.stderr).toMatch(/conformance-err/);
+                // Streamed, not just present in the final string: a backend
+                // that buffers everything until exit and calls `onOutput`
+                // once at the end would satisfy the two checks above and
+                // fail this one.
+                expect(chunks.some((c) => c.stream === 'stdout' && c.data.includes('conformance-out'))).toBe(true);
+                expect(chunks.some((c) => c.stream === 'stderr' && c.data.includes('conformance-err'))).toBe(true);
+            }));
+            it('reports busy while a command is in flight and ready once it settles', withSandbox(async (sandbox) => {
+                let observedBusy = false;
+                await sandbox.exec('/bin/sh', ['-c', 'echo started; sleep 0.2'], {
+                    onOutput: (chunk) => {
+                        if (chunk.data.includes('started'))
+                            observedBusy = sandbox.status === 'busy';
+                    },
+                });
+                expect(observedBusy).toBe(true);
+                expect(sandbox.status).toBe('ready');
+            }));
+            it('honours an AbortSignal: the process is really terminated, never a partial success', withSandbox(async (sandbox) => {
+                // The contract (`SandboxExecOptions.signal`'s own doc comment):
+                // a backend that accepts the signal must terminate the process
+                // it owns, or prove admission never happened; it must never
+                // silently ignore the signal and let the command run to
+                // completion while reporting as though it had been cancelled.
+                // The command below writes a marker file a moment after
+                // printing "ready" — if the process is genuinely killed on
+                // abort, that write never happens. That is the decisive
+                // check; whatever the settled promise looks like is a second,
+                // weaker one.
+                const marker = 'conformance-abort-marker.txt';
+                const caller = new AbortController();
+                let signalReady;
+                const ready = new Promise((resolve) => {
+                    signalReady = resolve;
+                });
+                const running = sandbox.exec('/bin/sh', [
+                    '-c',
+                    `trap '' TERM; (trap '' TERM; sleep 0.4; printf late > ${marker}) & echo ready; wait`,
+                ], {
+                    signal: caller.signal,
+                    onOutput: (chunk) => {
+                        if (chunk.stream === 'stdout' && chunk.data.includes('ready'))
+                            signalReady?.();
+                    },
+                });
+                await ready;
+                caller.abort(new Error('conformance suite cancelled this command'));
+                // Resolve OR reject are both compliant — a backend that cannot
+                // confirm the kill may refuse instead of reporting a result it
+                // is not sure of. What is never compliant is reporting a clean,
+                // unaborted-looking success.
+                let settled;
+                try {
+                    settled = await running;
+                }
+                catch {
+                    settled = undefined;
+                }
+                if (settled !== undefined) {
+                    expect(settled.exitCode === 0 && settled.signal === undefined).toBe(false);
+                }
+                // Long enough that an un-killed process would have finished its
+                // sleep and written the file.
+                await sleep(900);
+                await expectRejects(expect, () => sandbox.readFile(marker));
+            }));
+        });
+        describe('file IO', () => {
+            it('round-trips a UTF-8 string through writeFile/readFile', withSandbox(async (sandbox) => {
+                await sandbox.writeFile('conformance-notes.txt', 'héllo wörld');
+                const read = await sandbox.readFile('conformance-notes.txt');
+                expect(read.toString('utf8')).toBe('héllo wörld');
+            }));
+            it('round-trips arbitrary binary content byte for byte', withSandbox(async (sandbox) => {
+                const payload = Buffer.from([0x00, 0xff, 0x10, 0x00, 0x42, 0xfe, 0x7f, 0x80, 0x01]);
+                await sandbox.writeFile('nested/conformance/blob.bin', payload);
+                const read = await sandbox.readFile('nested/conformance/blob.bin');
+                // Compared as base64 rather than through a deep-equality
+                // matcher: the four matchers this suite is allowed to assume
+                // (`toBe`/`toEqual`/`toBeGreaterThan`/`toMatch`) do not
+                // guarantee byte-exact `Buffer` comparison across every
+                // runner a caller might wire in, and a corrupted byte belongs
+                // in the string this failure prints.
+                expect(read.toString('base64')).toBe(payload.toString('base64'));
+            }));
+        });
+        describe('listFiles', () => {
+            it('lists written files as absolute paths with their sizes', withSandbox(async (sandbox) => {
+                const contentA = '123456789';
+                const contentB = '42 bytes worth of fixed content!!';
+                await sandbox.writeFile('conformance-list/a.txt', contentA);
+                await sandbox.writeFile('conformance-list/b.txt', contentB);
+                const dir = `${sandbox.rootDir}/conformance-list`;
+                const files = await sandbox.listFiles(dir);
+                const byPath = new Map(files.map((f) => [f.path, f.size]));
+                expect(byPath.get(`${dir}/a.txt`)).toBe(Buffer.byteLength(contentA));
+                expect(byPath.get(`${dir}/b.txt`)).toBe(Buffer.byteLength(contentB));
+            }));
+            it('reports a root that does not exist as empty rather than failing', withSandbox(async (sandbox) => {
+                const files = await sandbox.listFiles(`${sandbox.rootDir}/conformance-never-created`);
+                expect(files.length).toBe(0);
+            }));
+        });
+        /**
+         * Optional on {@link Sandbox} by the SDK's own contract: a backend that
+         * cannot provide a real pseudo-terminal must OMIT the method rather
+         * than hand back a pipe masquerading as one. So a factory whose
+         * sandbox has no `openTerminal` is not in violation of anything — the
+         * case below passes vacuously for it, which is the documented
+         * skip-if-unavailable this suite promises rather than a silent hole:
+         * both shipped backends (kubernetes, firecracker) DO implement it, so
+         * in CI this case only ever runs vacuously against a fixture that
+         * deliberately declines the capability.
+         */
+        describe('openTerminal', () => {
+            it('is owned by the sandbox: destroy() kills and awaits every terminal it returned', withSandbox(async (sandbox) => {
+                if (!sandbox.openTerminal)
+                    return;
+                const terminal = await sandbox.openTerminal({
+                    command: '/bin/sh',
+                    args: ['-c', 'sleep 30'],
+                    size: { cols: 80, rows: 24 },
+                });
+                let exited = false;
+                void terminal.exited.then(() => {
+                    exited = true;
+                });
+                await sandbox.destroy();
+                // Nothing awaited in between: awaiting `terminal.exited` here
+                // would rescue a `destroy()` that only fired the kill and
+                // returned without waiting for it, which is exactly the
+                // defect this case exists to catch.
+                expect(exited).toBe(true);
+                await terminal.exited;
+            }));
+        });
+        /**
+         * Same optionality and the same documented skip as `openTerminal`,
+         * above: a factory whose sandbox has no `openTcpConnection` passes
+         * vacuously. The positive case below adds a second, independent skip
+         * axis on top of that — see `guestCanRunNode` and
+         * `guestListenerCommand` on {@link SandboxConformanceOptions} — because
+         * proving the forward really crosses into a REMOTE guest needs a
+         * listener running there, and not every guest can start one the same
+         * way.
+         */
+        describe('openTcpConnection', () => {
+            // The reason for a title, rather than a console message, printing
+            // the skip: `ConformanceIt` promises only `(name, body) => unknown`
+            // (`contract-suite.mjs`'s own flat recorder has no skip concept
+            // either), so the one channel a skip can travel through every
+            // runner this suite is ever handed is the case's own name — decided
+            // once, here, from options given synchronously to
+            // `defineSandboxConformance`, not from anything discovered at run
+            // time.
+            const positiveCaseTitle = guestCanRunNode
+                ? 'forwards a bidirectional stream to a service started inside the guest'
+                : 'forwards a bidirectional stream to a service started inside the guest (skipped: guestCanRunNode is false)';
+            it(positiveCaseTitle, withSandbox(async (sandbox) => {
+                if (!sandbox.openTcpConnection)
+                    return;
+                if (!guestCanRunNode)
+                    return;
+                const openTerminal = sandbox.openTerminal;
+                if (!openTerminal) {
+                    // A backend offering `openTcpConnection` without
+                    // `openTerminal` has no portable way for this suite to
+                    // start a guest-side listener — declare the skip
+                    // explicitly (`guestCanRunNode: false`) rather than
+                    // leaving the default to discover it here as a failure.
+                    throw new Error('openTcpConnection conformance: starting a guest-side listener needs openTerminal, ' +
+                        'which this sandbox does not implement. Pass guestCanRunNode: false to ' +
+                        'defineSandboxConformance to skip this case with a stated reason, or supply ' +
+                        'guestListenerCommand for a guest that can run a listener some other way.');
+                }
+                // Called through `.call(sandbox, …)` rather than passed as
+                // a bare reference: `openTerminal` may be an ordinary
+                // method relying on `this` (a class-based fixture, for
+                // instance), and detaching it from `sandbox` would drop
+                // that binding.
+                const listener = await startGuestListener((terminalOptions) => openTerminal.call(sandbox, terminalOptions), guestListenerCommand());
+                try {
+                    const connection = await sandbox.openTcpConnection({ port: listener.port });
+                    let received = '';
+                    const unsubscribe = connection.onData((chunk) => {
+                        received += Buffer.from(chunk).toString('utf8');
+                    });
+                    connection.write('conformance-hello');
+                    await connection.closed;
+                    expect(received).toBe('conformance-reply:conformance-hello');
+                    unsubscribe();
+                }
+                finally {
+                    await listener.stop();
+                }
+            }));
+            it('refuses a non-loopback host', withSandbox(async (sandbox) => {
+                if (!sandbox.openTcpConnection)
+                    return;
+                // `SandboxTcpConnectOptions.host` types as loopback-only; the
+                // cast is deliberate — this proves the refusal is enforced at
+                // RUNTIME, not merely by the type checker a compliant caller
+                // could route around with the same cast.
+                const nonLoopback = {
+                    port: 9,
+                    host: '203.0.113.10',
+                };
+                await expectRejects(expect, () => sandbox.openTcpConnection?.(nonLoopback) ?? Promise.reject(new Error('unreachable')));
+            }));
+        });
+        describe('destroy', () => {
+            it('is idempotent, however many times or however concurrently it is called', withSandbox(async (sandbox) => {
+                await Promise.all([sandbox.destroy(), sandbox.destroy()]);
+                expect(sandbox.status).toBe('destroyed');
+                await expectResolves(expect, () => sandbox.destroy());
+                expect(sandbox.status).toBe('destroyed');
+            }));
+            it('refuses every call once destroyed, rather than admitting one', withSandbox(async (sandbox) => {
+                await sandbox.destroy();
+                await expectRejects(expect, () => sandbox.exec('/bin/sh', ['-c', 'true']));
+                await expectRejects(expect, () => sandbox.writeFile('x.txt', 'x'));
+                await expectRejects(expect, () => sandbox.readFile('x.txt'));
+                await expectRejects(expect, () => sandbox.listFiles(sandbox.rootDir));
+                // `?.()` rather than an `if` guard around the assertion: it is
+                // type-correct whether or not the capability exists, and when
+                // it does not exist there is nothing to refuse — the
+                // documented skip-if-unavailable this suite promises for
+                // every optional capability.
+                if (sandbox.openTerminal) {
+                    await expectRejects(expect, () => sandbox.openTerminal?.({ size: { cols: 80, rows: 24 } }) ??
+                        Promise.reject(new Error('unreachable')));
+                }
+                if (sandbox.openTcpConnection) {
+                    await expectRejects(expect, () => sandbox.openTcpConnection?.({ port: 9 }) ??
+                        Promise.reject(new Error('unreachable')));
+                }
+            }));
+        });
+    });
+}
+//# sourceMappingURL=sandbox-conformance.js.map