@specific.dev/spectest 0.38.0 → 0.41.0

package/dist/harness/names-registry.js

@@ -0,0 +1,90 @@
+/**
+ * The DNS names registry: the file the harness writes and
+ * `spectest-resolver` reads.
+ *
+ * Ported out of `daemon.ts`. The point of a shared module is that this
+ * format had **two independent implementations** — the writer here and
+ * the reader in `resolver.ts` — with nothing keeping them in step. That
+ * is the same shape as the `config.rs` ↔ SDK drift the harness split
+ * exists to remove, just inside one language.
+ *
+ * The registry answers names that Docker's own DNS cannot:
+ *  - fake hostnames (`api.stripe.com` → the bridge gateway),
+ *  - names bound at runtime by `ctx.dnsName`,
+ *  - **wildcards** (`*.us-east-1.amazonaws.com`), which have no
+ *    `--add-host` or `--network-alias` equivalent and therefore *only*
+ *    exist here.
+ *
+ * Lookup is exact-first, then longest matching suffix — the same
+ * precedence the ingress routes and the SNI cert table use.
+ */
+export const EMPTY_REGISTRY = { hosts: {}, wildcards: [] };
+/** Serialise for the resolver. */
+export function encodeRegistry(doc, now) {
+    return JSON.stringify({
+        hosts: doc.hosts,
+        wildcards: doc.wildcards,
+        updatedAt: now,
+    });
+}
+/**
+ * Parse a registry file.
+ *
+ * Deliberately total: a truncated or malformed file yields an **empty**
+ * registry rather than throwing. The resolver reads this on a hot path
+ * while the harness may be rewriting it, and a parse error there would
+ * take out DNS for the whole environment — every name, not just the one
+ * being added. Degrading to "no custom names" is recoverable; the next
+ * successful read restores everything.
+ */
+export function decodeRegistry(text) {
+    try {
+        const raw = JSON.parse(text);
+        const hosts = raw.hosts && typeof raw.hosts === "object" ? raw.hosts : {};
+        const wildcards = Array.isArray(raw.wildcards)
+            ? raw.wildcards.filter((w) => !!w && typeof w.suffix === "string" && typeof w.ip === "string")
+            : [];
+        return { hosts, wildcards, updatedAt: raw.updatedAt };
+    }
+    catch {
+        return { hosts: {}, wildcards: [] };
+    }
+}
+/** `"*.example.com"` → `".example.com"`, the form stored in `wildcards`. */
+export function suffixOf(pattern) {
+    return pattern.startsWith("*.") ? pattern.slice(1) : pattern;
+}
+/**
+ * Resolve a name: exact entry first, then the longest matching wildcard
+ * suffix. Returns `null` when nothing matches, which is the resolver's
+ * signal to fall through to Docker's DNS and then upstream.
+ */
+export function lookup(doc, name) {
+    const exact = doc.hosts[name];
+    if (exact)
+        return exact;
+    let best = null;
+    for (const w of doc.wildcards) {
+        if (name.endsWith(w.suffix) && (!best || w.suffix.length > best.suffix.length)) {
+            best = w;
+        }
+    }
+    return best?.ip ?? null;
+}
+/**
+ * Add or replace a name.
+ *
+ * A wildcard replaces any existing entry for the same suffix rather than
+ * appending, so re-registering a name (which `ctx.dnsName` allows, and
+ * which a re-run of a `setup` hook does) cannot grow the list without
+ * bound or leave two entries racing on equal suffix length.
+ */
+export function upsert(doc, hostname, ip) {
+    if (hostname.startsWith("*.")) {
+        const suffix = suffixOf(hostname);
+        const wildcards = doc.wildcards.filter((w) => w.suffix !== suffix);
+        wildcards.push({ suffix, ip });
+        return { ...doc, wildcards };
+    }
+    return { ...doc, hosts: { ...doc.hosts, [hostname]: ip } };
+}

package/dist/harness/protocol.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The supervisor↔harness protocol — TypeScript half.
+ *
+ * Mirrors `crates/spectest-vm-agent/src/protocol.rs`. Read that file's
+ * header for the design; the rules that matter when editing this one:
+ *
+ *  - `hello` carries a protocol version AND a capability list in both
+ *    directions, from the first release. A release that announces nothing
+ *    can only ever be treated as "oldest".
+ *  - **Unknown fields are ignored in both directions.** Nothing here
+ *    validates against a closed field set, deliberately — that is the
+ *    mistake `config.rs` made, where a newer SDK's config was rejected
+ *    outright by an older server.
+ *  - A message never changes meaning. It only gains optional fields.
+ *  - An unrecognised *method* must still parse, so the receiver can answer
+ *    with an error instead of dropping the frame and hanging the sender.
+ *
+ * Anti-drift: the messages are defined once in
+ * `protocols/supervisor-harness/frames.json`, and both this module's test suite and
+ * the Rust one parse that file. A field added on one side and forgotten on
+ * the other fails there rather than in a VM.
+ */
+/** Protocol version this build speaks. Must match `PROTOCOL_VERSION` in protocol.rs. */
+export declare const PROTOCOL_VERSION = 1;
+/** Methods either side can send. */
+export type Method = "hello" | "load" | "loadTests" | "fingerprint" | "bootstrap" | "run" | "eval" | "teardown" | "shutdown" | "createArtifact" | "completeArtifact" | "progress" | "step";
+/** Methods this build knows how to dispatch. A method outside this set still
+ *  *parses* — it is answered with an error, never dropped. */
+export declare const KNOWN_METHODS: ReadonlySet<string>;
+export interface ProtocolError {
+    message: string;
+    code?: string;
+}
+export interface RequestFrame {
+    kind: "request";
+    /** Correlates the response. */
+    id: string;
+    /** Typed as `string`, not `Method`: a newer peer's method must parse. */
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface ResponseFrame {
+    kind: "response";
+    id: string;
+    ok: boolean;
+    result?: Record<string, unknown>;
+    error?: ProtocolError;
+}
+/** Fire-and-forget. No id, no reply — progress that blocked on an ack would
+ *  make the UI a correctness dependency. */
+export interface EventFrame {
+    kind: "event";
+    method: string;
+    params?: Record<string, unknown>;
+}
+export type Frame = RequestFrame | ResponseFrame | EventFrame;
+/** `hello` payload, sent in both directions. `sdkVersion` is on the
+ *  harness's reply only. */
+export interface Hello {
+    protocolVersion: number;
+    capabilities?: string[];
+    sdkVersion?: string;
+}
+/** One contribution to the L2 declared cache key. The supervisor hashes
+ *  these without interpreting them — a fingerprint it could interpret
+ *  would just be the schema coupling again. */
+export interface Contribution {
+    id: string;
+    kind: string;
+    key: string;
+}
+/**
+ * Parse one NDJSON line.
+ *
+ * Throws only on frames that cannot be *routed* — malformed JSON, or a
+ * missing `kind`/`id`/`method`. An unknown method is not such a case: it
+ * parses, and the dispatcher answers with an error. Unknown *fields* are
+ * left untouched on the returned object rather than stripped, so a value
+ * this build ignores still round-trips if forwarded.
+ */
+export declare function decodeFrame(line: string): Frame;
+/** Encode one frame as a single NDJSON line, newline included. */
+export declare function encodeFrame(frame: Frame): string;
+/** A successful reply to `id`. */
+export declare function ok(id: string, result?: Record<string, unknown>): ResponseFrame;
+/** A failed reply to `id`. Always carries the id: a request that failed must
+ *  never leave its caller waiting. */
+export declare function fail(id: string, message: string, code?: string): ResponseFrame;

package/dist/harness/protocol.js

@@ -0,0 +1,96 @@
+/**
+ * The supervisor↔harness protocol — TypeScript half.
+ *
+ * Mirrors `crates/spectest-vm-agent/src/protocol.rs`. Read that file's
+ * header for the design; the rules that matter when editing this one:
+ *
+ *  - `hello` carries a protocol version AND a capability list in both
+ *    directions, from the first release. A release that announces nothing
+ *    can only ever be treated as "oldest".
+ *  - **Unknown fields are ignored in both directions.** Nothing here
+ *    validates against a closed field set, deliberately — that is the
+ *    mistake `config.rs` made, where a newer SDK's config was rejected
+ *    outright by an older server.
+ *  - A message never changes meaning. It only gains optional fields.
+ *  - An unrecognised *method* must still parse, so the receiver can answer
+ *    with an error instead of dropping the frame and hanging the sender.
+ *
+ * Anti-drift: the messages are defined once in
+ * `protocols/supervisor-harness/frames.json`, and both this module's test suite and
+ * the Rust one parse that file. A field added on one side and forgotten on
+ * the other fails there rather than in a VM.
+ */
+/** Protocol version this build speaks. Must match `PROTOCOL_VERSION` in protocol.rs. */
+export const PROTOCOL_VERSION = 1;
+/** Methods this build knows how to dispatch. A method outside this set still
+ *  *parses* — it is answered with an error, never dropped. */
+export const KNOWN_METHODS = new Set([
+    "hello",
+    "load",
+    "loadTests",
+    "fingerprint",
+    "bootstrap",
+    "run",
+    "eval",
+    "teardown",
+    "shutdown",
+    "createArtifact",
+    "completeArtifact",
+    "progress",
+    "step",
+]);
+/**
+ * Parse one NDJSON line.
+ *
+ * Throws only on frames that cannot be *routed* — malformed JSON, or a
+ * missing `kind`/`id`/`method`. An unknown method is not such a case: it
+ * parses, and the dispatcher answers with an error. Unknown *fields* are
+ * left untouched on the returned object rather than stripped, so a value
+ * this build ignores still round-trips if forwarded.
+ */
+export function decodeFrame(line) {
+    let raw;
+    try {
+        raw = JSON.parse(line);
+    }
+    catch (e) {
+        throw new Error(`harness protocol: malformed JSON frame: ${e.message}`);
+    }
+    if (typeof raw !== "object" || raw === null) {
+        throw new Error("harness protocol: frame is not an object");
+    }
+    const f = raw;
+    switch (f.kind) {
+        case "request":
+            if (typeof f.id !== "string")
+                throw new Error("harness protocol: request has no id");
+            if (typeof f.method !== "string")
+                throw new Error("harness protocol: request has no method");
+            return f;
+        case "response":
+            if (typeof f.id !== "string")
+                throw new Error("harness protocol: response has no id");
+            if (typeof f.ok !== "boolean")
+                throw new Error("harness protocol: response has no ok");
+            return f;
+        case "event":
+            if (typeof f.method !== "string")
+                throw new Error("harness protocol: event has no method");
+            return f;
+        default:
+            throw new Error(`harness protocol: unknown frame kind ${JSON.stringify(f.kind)}`);
+    }
+}
+/** Encode one frame as a single NDJSON line, newline included. */
+export function encodeFrame(frame) {
+    return `${JSON.stringify(frame)}\n`;
+}
+/** A successful reply to `id`. */
+export function ok(id, result = {}) {
+    return { kind: "response", id, ok: true, result };
+}
+/** A failed reply to `id`. Always carries the id: a request that failed must
+ *  never leave its caller waiting. */
+export function fail(id, message, code) {
+    return { kind: "response", id, ok: false, error: code ? { message, code } : { message } };
+}

package/dist/harness/ready-poll.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The polling schedule behind a readiness probe.
+ *
+ * Ported out of `daemon.ts`, separated from the probes themselves so the
+ * timing rules can be tested without opening a socket or spawning a
+ * `docker exec`.
+ *
+ * Why a ramp rather than a fixed interval: a flat 500 ms delay quantises
+ * *every* service's measured ready latency to a multiple of 500 ms, and
+ * that error compounds down a `dependsOn` chain — a four-deep chain of
+ * services that are each genuinely ready in 60 ms reports two seconds.
+ * Probing fast at first catches quick services honestly; ramping up caps
+ * the polling load on genuinely slow ones.
+ *
+ * Exec probes keep a higher floor because each attempt spawns a
+ * `docker exec`, which costs far more than a TCP connect.
+ */
+export type ProbeKind = "tcp" | "http" | "exec";
+/** Delays between attempts, in ms. The last entry repeats forever. */
+export declare const RAMP_DEFAULT: readonly number[];
+export declare const RAMP_EXEC: readonly number[];
+export declare const DEFAULT_TIMEOUT_SECS = 60;
+export declare function rampFor(kind: ProbeKind): readonly number[];
+/** Delay before attempt number `attempt` (0-based), clamped to the ramp's tail. */
+export declare function delayForAttempt(ramp: readonly number[], attempt: number): number;
+export interface PollOptions {
+    kind: ProbeKind;
+    timeoutSecs?: number;
+    /** Injectable for tests; defaults to the wall clock. */
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface PollResult {
+    ready: boolean;
+    attempts: number;
+    elapsedMs: number;
+}
+/**
+ * Poll `probe` until it returns true or the deadline passes.
+ *
+ * The probe is **always attempted at least once**, even with a zero or
+ * negative timeout. A deadline check placed before the first attempt
+ * would make `timeoutSecs: 0` mean "never check", which reads as "no
+ * timeout" to anyone writing it — and would fail a service that was
+ * ready all along.
+ */
+export declare function pollUntilReady(probe: () => Promise<boolean>, opts: PollOptions): Promise<PollResult>;

package/dist/harness/ready-poll.js

@@ -0,0 +1,67 @@
+/**
+ * The polling schedule behind a readiness probe.
+ *
+ * Ported out of `daemon.ts`, separated from the probes themselves so the
+ * timing rules can be tested without opening a socket or spawning a
+ * `docker exec`.
+ *
+ * Why a ramp rather than a fixed interval: a flat 500 ms delay quantises
+ * *every* service's measured ready latency to a multiple of 500 ms, and
+ * that error compounds down a `dependsOn` chain — a four-deep chain of
+ * services that are each genuinely ready in 60 ms reports two seconds.
+ * Probing fast at first catches quick services honestly; ramping up caps
+ * the polling load on genuinely slow ones.
+ *
+ * Exec probes keep a higher floor because each attempt spawns a
+ * `docker exec`, which costs far more than a TCP connect.
+ */
+/** Delays between attempts, in ms. The last entry repeats forever. */
+export const RAMP_DEFAULT = [50, 100, 150, 250, 400, 500];
+export const RAMP_EXEC = [250, 250, 400, 400, 500];
+export const DEFAULT_TIMEOUT_SECS = 60;
+export function rampFor(kind) {
+    return kind === "exec" ? RAMP_EXEC : RAMP_DEFAULT;
+}
+/** Delay before attempt number `attempt` (0-based), clamped to the ramp's tail. */
+export function delayForAttempt(ramp, attempt) {
+    return ramp[Math.min(attempt, ramp.length - 1)];
+}
+/**
+ * Poll `probe` until it returns true or the deadline passes.
+ *
+ * The probe is **always attempted at least once**, even with a zero or
+ * negative timeout. A deadline check placed before the first attempt
+ * would make `timeoutSecs: 0` mean "never check", which reads as "no
+ * timeout" to anyone writing it — and would fail a service that was
+ * ready all along.
+ */
+export async function pollUntilReady(probe, opts) {
+    const now = opts.now ?? Date.now;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const timeoutSecs = opts.timeoutSecs ?? DEFAULT_TIMEOUT_SECS;
+    const ramp = rampFor(opts.kind);
+    const started = now();
+    const deadline = started + timeoutSecs * 1000;
+    let attempts = 0;
+    for (;;) {
+        attempts++;
+        if (await probe()) {
+            return { ready: true, attempts, elapsedMs: now() - started };
+        }
+        const remaining = deadline - now();
+        if (remaining <= 0) {
+            return { ready: false, attempts, elapsedMs: now() - started };
+        }
+        // Clamp rather than give up early. An earlier version returned as soon
+        // as `now + delay` passed the deadline, which stopped probing up to a
+        // full ramp step (500 ms) BEFORE the timeout the user asked for — so a
+        // service that became ready in that final window was reported as
+        // failed. Harmless when everything is fast, and exactly wrong under
+        // load, which is when readiness is marginal in the first place.
+        //
+        // Clamping keeps the original "probe until the deadline" behaviour and
+        // still never sleeps past it.
+        const delay = Math.min(delayForAttempt(ramp, attempts - 1), remaining);
+        await sleep(delay);
+    }
+}

package/dist/harness/service-graph.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The `dependsOn` graph: validation, and the traversal order bring-up
+ * uses.
+ *
+ * Ported out of `daemon.ts`. Validation runs before anything starts, so
+ * the DAG runner can assume a clean graph — an unknown dependency or a
+ * cycle must be a clear error at load, not a container that never becomes
+ * ready and eventually times out with no explanation.
+ */
+export interface GraphNode {
+    name: string;
+    dependsOn?: readonly string[];
+}
+/**
+ * Check the graph and return the name→node map used to walk it.
+ *
+ * Rejects a dependency on a service that doesn't exist, and any cycle.
+ */
+export declare function validateServiceGraph<T extends GraphNode>(services: readonly T[]): Map<string, T>;
+/**
+ * Services in an order where every node follows its dependencies.
+ *
+ * Bring-up itself does **not** walk levels — each service starts the
+ * moment its own dependencies are ready, so an unrelated slow probe never
+ * holds back a branch that is ready. This ordering is for the places that
+ * genuinely need a sequence (teardown, reporting), and for asserting the
+ * graph is walkable at all.
+ */
+export declare function topologicalOrder<T extends GraphNode>(services: readonly T[]): T[];

package/dist/harness/service-graph.js

@@ -0,0 +1,92 @@
+/**
+ * The `dependsOn` graph: validation, and the traversal order bring-up
+ * uses.
+ *
+ * Ported out of `daemon.ts`. Validation runs before anything starts, so
+ * the DAG runner can assume a clean graph — an unknown dependency or a
+ * cycle must be a clear error at load, not a container that never becomes
+ * ready and eventually times out with no explanation.
+ */
+/**
+ * Check the graph and return the name→node map used to walk it.
+ *
+ * Rejects a dependency on a service that doesn't exist, and any cycle.
+ */
+export function validateServiceGraph(services) {
+    const byName = new Map(services.map((s) => [s.name, s]));
+    // A duplicate name would silently shadow one definition and make the
+    // graph lie about what is running. The old code built the map without
+    // checking, so the second service simply replaced the first.
+    if (byName.size !== services.length) {
+        const seen = new Set();
+        const dupe = services.find((s) => !seen.add(s.name))?.name;
+        throw new Error(`duplicate service name ${JSON.stringify(dupe)}`);
+    }
+    for (const s of services) {
+        for (const d of s.dependsOn ?? []) {
+            if (!byName.has(d)) {
+                throw new Error(`service ${s.name} depends on unknown service ${d}`);
+            }
+            if (d === s.name) {
+                throw new Error(`service ${s.name} depends on itself`);
+            }
+        }
+    }
+    // Cycle detection by DFS colouring: white = unseen, gray = on the
+    // current stack (so meeting gray again is a cycle), black = finished.
+    const WHITE = 0;
+    const GRAY = 1;
+    const BLACK = 2;
+    const color = new Map(services.map((s) => [s.name, WHITE]));
+    const stack = [];
+    const visit = (name) => {
+        color.set(name, GRAY);
+        stack.push(name);
+        for (const d of byName.get(name).dependsOn ?? []) {
+            const c = color.get(d);
+            if (c === GRAY) {
+                // Naming the cycle matters: "service dependency cycle" alone
+                // leaves the user to find it by eye in a large services map.
+                const from = stack.indexOf(d);
+                const loop = [...stack.slice(from), d].join(" → ");
+                throw new Error(`service dependency cycle: ${loop}`);
+            }
+            if (c === WHITE)
+                visit(d);
+        }
+        stack.pop();
+        color.set(name, BLACK);
+    };
+    for (const s of services)
+        if (color.get(s.name) === WHITE)
+            visit(s.name);
+    return byName;
+}
+/**
+ * Services in an order where every node follows its dependencies.
+ *
+ * Bring-up itself does **not** walk levels — each service starts the
+ * moment its own dependencies are ready, so an unrelated slow probe never
+ * holds back a branch that is ready. This ordering is for the places that
+ * genuinely need a sequence (teardown, reporting), and for asserting the
+ * graph is walkable at all.
+ */
+export function topologicalOrder(services) {
+    const byName = validateServiceGraph(services);
+    const out = [];
+    const done = new Set();
+    const visit = (name) => {
+        if (done.has(name))
+            return;
+        const node = byName.get(name);
+        for (const d of node.dependsOn ?? [])
+            visit(d);
+        done.add(name);
+        out.push(node);
+    };
+    // Declaration order among independent services, so the result is stable
+    // rather than dependent on Map iteration incidentals.
+    for (const s of services)
+        visit(s.name);
+    return out;
+}

package/dist/harness/volume-paths.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Where a service's volume is backed on the VM's filesystem.
+ *
+ * Ported out of `daemon.ts`. Pure path arithmetic, but it decides
+ * something with real consequences: **which volumes survive a
+ * delta-restore teardown**.
+ *
+ * Teardown wipes `/workspace` to give a restored environment fresh-state
+ * semantics. Anything that must survive it therefore has to live outside
+ * `/workspace` — and that is exactly what `cache: true` selects, by
+ * rooting the directory under `/var/cache/spectest/volumes` instead.
+ *
+ * The flag is only ever correct for **content-addressed accelerator
+ * data**: package stores, layer caches — data whose presence can change
+ * how *fast* something runs but never *what* it does. It is wrong for any
+ * real state, because a restored environment would then start with a
+ * previous run's data and stop being reproducible. (Counter-example worth
+ * remembering: `k3s()` deliberately does not cache its containerd store —
+ * a fresh cluster over an un-cleanly-killed store wedged the apiserver.)
+ */
+/** Root of the per-environment state tree. Wiped by delta teardown. */
+export declare const DEFAULT_WORKSPACE = "/workspace";
+/** Root of the cache tree. Deliberately outside the workspace. */
+export declare const CACHE_ROOT = "/var/cache/spectest/volumes";
+/** Directory holding named shared volumes, under whichever root applies. */
+export declare const SHARED_DIR = "_shared";
+export interface VolumeSpec {
+    /** Named shared volume — every service mounting this name gets the same
+     *  directory. Mutually exclusive with `source`. */
+    name?: string;
+    /** Host path. Absolute paths are used as-is; relative ones resolve under
+     *  the service's own directory. */
+    source?: string;
+    /** Path inside the container. Used to derive a directory when neither
+     *  `name` nor `source` is given. */
+    target: string;
+    /** Survive the delta-restore teardown. Content-addressed data only. */
+    cache?: boolean;
+}
+/**
+ * Make an arbitrary string safe as a single path segment.
+ *
+ * Strips leading slashes, replaces anything outside `[A-Za-z0-9_-]`, and
+ * trims the dashes that leaves at the edges. The character filter also
+ * removes `.`, so `..` cannot survive — a volume name or target can't
+ * escape its root.
+ */
+export declare function sanitizeSegment(p: string): string;
+/**
+ * The host directory backing one volume mount.
+ *
+ * Resolution order:
+ *  1. `name` — a shared directory under `_shared`, so two services
+ *     mounting the same name genuinely share one directory.
+ *  2. An **absolute** `source` — used verbatim. The project asked for a
+ *     specific path, so it gets it.
+ *  3. A relative `source`, or nothing at all — under the service's own
+ *     directory, derived from `target` when `source` is absent.
+ *
+ * `workspace` is a parameter rather than a module constant so the rule is
+ * testable without touching the filesystem.
+ */
+export declare function resolveHostPath(service: string, vol: VolumeSpec, workspace?: string): string;
+/**
+ * Does this volume survive a delta-restore teardown?
+ *
+ * True for cache-flagged volumes and for absolute sources outside the
+ * workspace — the two ways a directory ends up beyond `rm -rf /workspace`.
+ */
+export declare function survivesTeardown(vol: VolumeSpec, service: string, workspace?: string): boolean;

package/dist/harness/volume-paths.js

@@ -0,0 +1,81 @@
+/**
+ * Where a service's volume is backed on the VM's filesystem.
+ *
+ * Ported out of `daemon.ts`. Pure path arithmetic, but it decides
+ * something with real consequences: **which volumes survive a
+ * delta-restore teardown**.
+ *
+ * Teardown wipes `/workspace` to give a restored environment fresh-state
+ * semantics. Anything that must survive it therefore has to live outside
+ * `/workspace` — and that is exactly what `cache: true` selects, by
+ * rooting the directory under `/var/cache/spectest/volumes` instead.
+ *
+ * The flag is only ever correct for **content-addressed accelerator
+ * data**: package stores, layer caches — data whose presence can change
+ * how *fast* something runs but never *what* it does. It is wrong for any
+ * real state, because a restored environment would then start with a
+ * previous run's data and stop being reproducible. (Counter-example worth
+ * remembering: `k3s()` deliberately does not cache its containerd store —
+ * a fresh cluster over an un-cleanly-killed store wedged the apiserver.)
+ */
+import path from "node:path";
+/** Root of the per-environment state tree. Wiped by delta teardown. */
+export const DEFAULT_WORKSPACE = "/workspace";
+/** Root of the cache tree. Deliberately outside the workspace. */
+export const CACHE_ROOT = "/var/cache/spectest/volumes";
+/** Directory holding named shared volumes, under whichever root applies. */
+export const SHARED_DIR = "_shared";
+/**
+ * Make an arbitrary string safe as a single path segment.
+ *
+ * Strips leading slashes, replaces anything outside `[A-Za-z0-9_-]`, and
+ * trims the dashes that leaves at the edges. The character filter also
+ * removes `.`, so `..` cannot survive — a volume name or target can't
+ * escape its root.
+ */
+export function sanitizeSegment(p) {
+    return p
+        .replace(/^\/+/, "")
+        .replace(/[^A-Za-z0-9_-]/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * The host directory backing one volume mount.
+ *
+ * Resolution order:
+ *  1. `name` — a shared directory under `_shared`, so two services
+ *     mounting the same name genuinely share one directory.
+ *  2. An **absolute** `source` — used verbatim. The project asked for a
+ *     specific path, so it gets it.
+ *  3. A relative `source`, or nothing at all — under the service's own
+ *     directory, derived from `target` when `source` is absent.
+ *
+ * `workspace` is a parameter rather than a module constant so the rule is
+ * testable without touching the filesystem.
+ */
+export function resolveHostPath(service, vol, workspace = DEFAULT_WORKSPACE) {
+    const stateRoot = [workspace, ".spectest", "volumes"];
+    if (vol.name) {
+        const root = vol.cache ? [CACHE_ROOT, SHARED_DIR] : [...stateRoot, SHARED_DIR];
+        return path.join(...root, sanitizeSegment(vol.name));
+    }
+    // An absolute source is the project's own path; `cache` doesn't apply
+    // because the location was already chosen explicitly.
+    if (vol.source && vol.source.startsWith("/"))
+        return vol.source;
+    const root = vol.cache ? [CACHE_ROOT, service] : [...stateRoot, service];
+    if (vol.source) {
+        return path.join(...root, vol.source.replace(/^\/+/, ""));
+    }
+    return path.join(...root, sanitizeSegment(vol.target));
+}
+/**
+ * Does this volume survive a delta-restore teardown?
+ *
+ * True for cache-flagged volumes and for absolute sources outside the
+ * workspace — the two ways a directory ends up beyond `rm -rf /workspace`.
+ */
+export function survivesTeardown(vol, service, workspace = DEFAULT_WORKSPACE) {
+    const host = resolveHostPath(service, vol, workspace);
+    return !host.startsWith(`${workspace}/`) && host !== workspace;
+}