@specific.dev/spectest 0.69.0 → 0.71.0

package/dist/harness/hostmatch.d.ts

@@ -48,6 +48,23 @@ export declare function wildcardCoversHost(pattern: string, hostname: string): b
  * `HTTPS_CERT_BY_HOST.keys()`.
  */
 export declare function certCovers(serverNames: Iterable<string>, hostname: string): boolean;
+/**
+ * Pick the certificate server name that should serve `hostname`'s TLS
+ * handshake: the exact entry first, then the longest matching wildcard.
+ *
+ * This is the same precedence {@link matchRoute} applies to routes and the
+ * resolver applies to DNS — but over the *certificate* rule, so a wildcard
+ * covers exactly one label ({@link wildcardCoversHost}) rather than any
+ * depth.
+ *
+ * It exists because the SNI lookup is now ours to make. Until the :443
+ * listener stopped being rebuilt for every new certificate, Bun performed
+ * this match internally from the `tls` array it was served with; the
+ * terminator picks a certificate per handshake instead, so the rule has to
+ * be written down — and, being written down, it is testable, which Bun's
+ * internal version never was.
+ */
+export declare function selectCertName(serverNames: Iterable<string>, hostname: string): string | undefined;
 /**
  * Pick the route for `host`: exact match first, then the longest matching
  * wildcard suffix.

package/dist/harness/hostmatch.js

@@ -65,6 +65,39 @@ export function certCovers(serverNames, hostname) {
         return true;
     return names.some((n) => isWildcard(n) && wildcardCoversHost(n, hostname));
 }
+/**
+ * Pick the certificate server name that should serve `hostname`'s TLS
+ * handshake: the exact entry first, then the longest matching wildcard.
+ *
+ * This is the same precedence {@link matchRoute} applies to routes and the
+ * resolver applies to DNS — but over the *certificate* rule, so a wildcard
+ * covers exactly one label ({@link wildcardCoversHost}) rather than any
+ * depth.
+ *
+ * It exists because the SNI lookup is now ours to make. Until the :443
+ * listener stopped being rebuilt for every new certificate, Bun performed
+ * this match internally from the `tls` array it was served with; the
+ * terminator picks a certificate per handshake instead, so the rule has to
+ * be written down — and, being written down, it is testable, which Bun's
+ * internal version never was.
+ */
+export function selectCertName(serverNames, hostname) {
+    const names = [...serverNames];
+    if (names.includes(hostname))
+        return hostname;
+    let best;
+    let bestLen = -1;
+    for (const name of names) {
+        if (!isWildcard(name) || !wildcardCoversHost(name, hostname))
+            continue;
+        const len = wildcardSuffix(name).length;
+        if (len > bestLen) {
+            best = name;
+            bestLen = len;
+        }
+    }
+    return best;
+}
 /**
  * Pick the route for `host`: exact match first, then the longest matching
  * wildcard suffix.

package/dist/harness/ingress-table.d.ts

@@ -32,13 +32,14 @@
  * routes added afterwards go nowhere. {@link routesFor} is the only way to
  * reach a table so that this can't be done by accident.
  *
- * **A rebind is not free, so it must be earned.** Bun fixes a server's TLS
- * config at `Bun.serve` time — `reload` will not add an SNI entry — so a
- * genuinely new certificate means stopping and re-serving :443. It's cheap
- * (~1 ms) but it is a real interruption of live traffic, and a hostname
- * already covered by an existing exact or wildcard cert needs nothing but a
- * route entry. {@link planBind} is that judgement, separated from the
- * mutation so it can be tested without a network stack.
+ * **Adding a certificate no longer touches the listener.** :443 is
+ * terminated by `harness/tls-terminator.ts`, which chooses a leaf per TLS
+ * handshake, so a new certificate is a `Map` entry and nothing more. It
+ * used to mean stopping and re-serving :443, and that swap severed every
+ * idle kept-alive connection the listener was carrying — an unrelated
+ * test's request, failing with `SocketError: other side closed`. The only
+ * thing {@link planBind} still has to say is whether the listener exists
+ * yet.
  */
 /**
  * One hostname's upstream: a fake handled in-process, or a container.
@@ -89,18 +90,21 @@ export declare function routesFor<F>(tables: IngressTables<F>, port: number): Ma
 export interface BindPlan {
     /** No existing cert covers the hostname, so a leaf must be minted. */
     needsCert: boolean;
-    /** The :443 listener must be stopped and re-served. */
-    needsHttpsRebind: boolean;
+    /** The :443 listener does not exist yet and must be started. */
+    needsHttpsListener: boolean;
 }
 /**
  * Decide what binding `hostname` for TLS costs.
  *
- * A rebind is needed when a new certificate is going into the SNI table,
- * or when :443 isn't listening yet. It is deliberately *not* needed for a
- * hostname an existing wildcard already covers — the common case when a
- * component claims a whole domain up front and services appear under it
- * later, and the reason a fake can mint endpoints in a loop without
- * restarting the listener once per iteration.
+ * Minting is still earned — a hostname an existing exact or wildcard cert
+ * already covers needs nothing but a route, which is why a component can
+ * claim a whole domain up front and have services appear under it for
+ * free.
+ *
+ * Starting the listener, on the other hand, is now a once-per-process
+ * event: it is needed when :443 is not up yet, and never again. A new
+ * certificate does **not** imply it. That is the whole point of the
+ * terminator — see the module header.
  */
 export declare function planBind<F>(tables: IngressTables<F>, hostname: string, opts: {
     httpsListening: boolean;
@@ -117,11 +121,18 @@ export declare function bindRoute<F>(tables: IngressTables<F>, hostname: string,
  * Drop `hostname`'s routes, so it 404s.
  *
  * The certificate is deliberately left in the SNI table: it is harmless
- * without a route, and removing it would force an otherwise unnecessary
- * :443 rebind at exactly the moment a service is going away.
+ * without a route, and a leaf nobody asks for costs one unused `Map`
+ * entry. (Before the terminator, removing it would also have forced a
+ * :443 rebind at exactly the moment a service was going away.)
  */
 export declare function unbindRoute<F>(tables: IngressTables<F>, hostname: string): void;
-/** The SNI entries for `Bun.serve`'s TLS config. */
+/**
+ * The SNI table flattened to entries.
+ *
+ * This was `Bun.serve`'s `tls` array. The terminator selects per handshake
+ * instead ({@link import("./hostmatch").selectCertName}), so this survives
+ * as the readable projection of the table — for diagnostics and tests.
+ */
 export declare function certEntries<F>(tables: IngressTables<F>): Array<{
     cert: string;
     key: string;

package/dist/harness/ingress-table.js

@@ -32,13 +32,14 @@
  * routes added afterwards go nowhere. {@link routesFor} is the only way to
  * reach a table so that this can't be done by accident.
  *
- * **A rebind is not free, so it must be earned.** Bun fixes a server's TLS
- * config at `Bun.serve` time — `reload` will not add an SNI entry — so a
- * genuinely new certificate means stopping and re-serving :443. It's cheap
- * (~1 ms) but it is a real interruption of live traffic, and a hostname
- * already covered by an existing exact or wildcard cert needs nothing but a
- * route entry. {@link planBind} is that judgement, separated from the
- * mutation so it can be tested without a network stack.
+ * **Adding a certificate no longer touches the listener.** :443 is
+ * terminated by `harness/tls-terminator.ts`, which chooses a leaf per TLS
+ * handshake, so a new certificate is a `Map` entry and nothing more. It
+ * used to mean stopping and re-serving :443, and that swap severed every
+ * idle kept-alive connection the listener was carrying — an unrelated
+ * test's request, failing with `SocketError: other side closed`. The only
+ * thing {@link planBind} still has to say is whether the listener exists
+ * yet.
  */
 import { certCovers, isWildcard, wildcardSuffix } from "./hostmatch";
 /** Fixed HTTPS port shared by every TLS route (fakes + service `tls`). */
@@ -66,16 +67,19 @@ export function routesFor(tables, port) {
 /**
  * Decide what binding `hostname` for TLS costs.
  *
- * A rebind is needed when a new certificate is going into the SNI table,
- * or when :443 isn't listening yet. It is deliberately *not* needed for a
- * hostname an existing wildcard already covers — the common case when a
- * component claims a whole domain up front and services appear under it
- * later, and the reason a fake can mint endpoints in a loop without
- * restarting the listener once per iteration.
+ * Minting is still earned — a hostname an existing exact or wildcard cert
+ * already covers needs nothing but a route, which is why a component can
+ * claim a whole domain up front and have services appear under it for
+ * free.
+ *
+ * Starting the listener, on the other hand, is now a once-per-process
+ * event: it is needed when :443 is not up yet, and never again. A new
+ * certificate does **not** imply it. That is the whole point of the
+ * terminator — see the module header.
  */
 export function planBind(tables, hostname, opts) {
     const needsCert = !certCovers(tables.certByHost.keys(), hostname);
-    return { needsCert, needsHttpsRebind: needsCert || !opts.httpsListening };
+    return { needsCert, needsHttpsListener: !opts.httpsListening };
 }
 /**
  * Point `hostname` at `route` on both :80 and :443.
@@ -92,14 +96,21 @@ export function bindRoute(tables, hostname, route) {
  * Drop `hostname`'s routes, so it 404s.
  *
  * The certificate is deliberately left in the SNI table: it is harmless
- * without a route, and removing it would force an otherwise unnecessary
- * :443 rebind at exactly the moment a service is going away.
+ * without a route, and a leaf nobody asks for costs one unused `Map`
+ * entry. (Before the terminator, removing it would also have forced a
+ * :443 rebind at exactly the moment a service was going away.)
  */
 export function unbindRoute(tables, hostname) {
     tables.routesByPort.get(INGRESS_HTTP_PORT)?.delete(hostname);
     tables.routesByPort.get(INGRESS_HTTPS_PORT)?.delete(hostname);
 }
-/** The SNI entries for `Bun.serve`'s TLS config. */
+/**
+ * The SNI table flattened to entries.
+ *
+ * This was `Bun.serve`'s `tls` array. The terminator selects per handshake
+ * instead ({@link import("./hostmatch").selectCertName}), so this survives
+ * as the readable projection of the table — for diagnostics and tests.
+ */
 export function certEntries(tables) {
     return [...tables.certByHost].map(([serverName, leaf]) => ({
         cert: leaf.cert,

package/dist/harness/tls-terminator.d.ts

@@ -0,0 +1,32 @@
+import type { Leaf } from "./ingress-table";
+export interface TlsTerminatorOptions {
+    /** Public port to accept TLS on (443 in the harness). */
+    port: number;
+    /** Interface to accept on. */
+    hostname: string;
+    /** Loopback port of the plaintext ingress server to pipe into. */
+    upstreamPort: number;
+    /**
+     * The leaf to serve for an SNI server name, read live on every
+     * handshake — this is what lets a certificate be added with no restart.
+     * `undefined` server name means the client sent no SNI.
+     */
+    certFor(serverName: string | undefined): Leaf | undefined;
+    /** Non-fatal diagnostics (a handshake a client aborted, a pipe error). */
+    onWarning?(message: string, err: unknown): void;
+}
+export interface TlsTerminator {
+    /** The port actually bound. */
+    readonly port: number;
+    /**
+     * The real client address behind an upstream connection, keyed by the
+     * source port the plaintext server sees. `undefined` for a port this
+     * terminator did not open.
+     */
+    clientIpFor(upstreamPort: number | undefined): string | undefined;
+    /** Open TLS connections right now (diagnostics and tests). */
+    connectionCount(): number;
+    /** Stop accepting and force-close every connection. */
+    close(): void;
+}
+export declare function startTlsTerminator(opts: TlsTerminatorOptions): Promise<TlsTerminator>;

package/dist/harness/tls-terminator.js

@@ -0,0 +1,199 @@
+/**
+ * The :443 TLS terminator — one listener, for the life of the harness.
+ *
+ * ## Why this exists
+ *
+ * Ingress certificates are minted *while tests run*: a fake that
+ * provisions a database hands the app a CA-trusted `https://<new-host>/`
+ * endpoint, and that hostname did not exist a second earlier. Bun fixes a
+ * server's TLS configuration at `Bun.serve` time — `reload({ tls })` is
+ * accepted and then ignored (re-measured on Bun 1.4.0: the added
+ * `serverName` still gets the first entry's leaf) — so for as long as
+ * :443 was a `Bun.serve`, every new certificate meant swapping the
+ * listener.
+ *
+ * **No listener swap can be made safe.** Binding the replacement first
+ * under SO_REUSEPORT and draining the original with `stop(false)` saves a
+ * request that is already *in flight*, and that is all it saves: measured
+ * on Bun 1.4.0, `stop(false)` sends FIN to an **idle kept-alive
+ * connection within 1–2 ms**. A client that writes a request into that
+ * socket in the same instant gets `SocketError: other side closed`
+ * (`UND_ERR_SOCKET` under undici), and Node's `fetch` does not retry it.
+ * That is a flake in whatever unrelated test happened to be talking
+ * through the ingress — never in the one that provisioned the service —
+ * and it is why the app under test would die far from any ingress code.
+ *
+ * So the listener must stop being swapped, which means the certificate
+ * must be chosen **per handshake** rather than baked into the socket.
+ * That is what every real server does, and under Bun it is reachable
+ * through `node:tls`'s `SNICallback` (verified working on Bun 1.4.0:
+ * adding an entry to the table is served on the next handshake, with no
+ * restart and no effect on any established connection).
+ *
+ * ## The shape, and why it is a byte pipe
+ *
+ * The terminator does TLS and *nothing else*: it accepts on :443, picks a
+ * leaf by SNI, and pipes the decrypted stream to a plaintext `Bun.serve`
+ * bound on loopback. Everything downstream — routing, fakes,
+ * interceptors, reverse-proxying, and `server.upgrade()` WebSocket
+ * bridging — is the same `Bun.serve` code that already serves :80, run
+ * unchanged. Terminating HTTP here instead (`node:https`, `(req, res)`)
+ * would have meant reimplementing the WebSocket bridge against a
+ * different API, which is exactly the kind of trade this change exists to
+ * avoid: one flake removed, another introduced somewhere subtler.
+ *
+ * Measured cost of the extra hop on this host (Bun 1.4.0, undici client,
+ * 50 MB bodies): ~11 % fewer small requests per second, download
+ * throughput unchanged, upload ~500 MB/s against ~800 MB/s direct. Ingress
+ * traffic in a test VM is nowhere near either bound.
+ *
+ * ## Recovering the client's address
+ *
+ * The plaintext server's peer is the terminator, so `server.requestIP()`
+ * reports loopback and `x-forwarded-for` would lose the caller. The
+ * upstream socket's *source port* is unique among live connections, so the
+ * terminator records `source port → real client address` for the life of
+ * each connection and {@link TlsTerminator.clientIpFor} hands it back.
+ * Verified end to end: a client connecting from 127.0.0.2 is reported as
+ * 127.0.0.2 by the plaintext server behind the pipe.
+ */
+import net from "node:net";
+import tls from "node:tls";
+/**
+ * Start the terminator. Resolves once :443 is accepting, so a caller can
+ * register the hostname in DNS immediately afterwards and know the port is
+ * live.
+ */
+/**
+ * Is this the ordinary end of a connection rather than a fault? A peer
+ * that goes away mid-stream, or a half-finished handshake, is routine on a
+ * listener that fronts browsers.
+ */
+function isRoutineDisconnect(err) {
+    const code = err?.code;
+    return (code === "ECONNRESET" ||
+        code === "EPIPE" ||
+        code === "ERR_STREAM_PREMATURE_CLOSE" ||
+        code === "ECONNABORTED");
+}
+export function startTlsTerminator(opts) {
+    // Parsing a PEM into a SecureContext is the expensive half of choosing a
+    // certificate, and the table is stable — cache by the certificate's own
+    // bytes so a handshake is a Map lookup. Keyed on the PEM rather than the
+    // hostname so a re-minted leaf for the same name cannot be served stale.
+    const contexts = new Map();
+    const contextFor = (leaf) => {
+        let ctx = contexts.get(leaf.cert);
+        if (!ctx) {
+            ctx = tls.createSecureContext({ cert: leaf.cert, key: leaf.key });
+            contexts.set(leaf.cert, ctx);
+        }
+        return ctx;
+    };
+    const warn = (message, err) => {
+        // A client hanging up is not a fault, and this listener carries every
+        // browser in the VM: Chromium opens speculative connections and drops
+        // them, a fetch is abandoned when its test ends, and each of those
+        // arrives here as a reset. Logging them would bury the boot log a user
+        // reads with `spectest env logs` in noise that means nothing.
+        if (isRoutineDisconnect(err))
+            return;
+        if (opts.onWarning)
+            opts.onWarning(message, err);
+        // eslint-disable-next-line no-console
+        else
+            console.warn(`[ingress] ${message}:`, err);
+    };
+    /** upstream source port → the address the TLS client connected from. */
+    const clientIpByUpstreamPort = new Map();
+    const live = new Set();
+    // A default leaf is only ever used for a client that sends no SNI at
+    // all; `SNICallback` decides every other handshake. This mirrors what
+    // Bun did with the first entry of its `tls` array.
+    const fallback = opts.certFor(undefined);
+    const server = tls.createServer({
+        ...(fallback ? { cert: fallback.cert, key: fallback.key } : {}),
+        SNICallback: (serverName, cb) => {
+            const leaf = opts.certFor(serverName) ?? fallback;
+            // No certificate at all is a handshake we cannot complete. Answer
+            // with the fallback context rather than an error so the client
+            // gets a certificate-mismatch alert it can report, which is the
+            // same thing it saw when Bun served the first entry.
+            cb(null, leaf ? contextFor(leaf) : undefined);
+        },
+    }, (client) => {
+        // No idle timeout anywhere on the ingress path: it fronts app
+        // endpoints that legitimately take minutes (a deploy), and a
+        // timeout here would surface as a truncated response with no
+        // explanation.
+        client.setTimeout(0);
+        live.add(client);
+        // Nothing reads from `client` until `pipe` below, so a socket that
+        // is written to before the upstream is connected stays paused and
+        // its bytes are buffered rather than dropped — which is the normal
+        // case, since a client sends its first request the instant the
+        // handshake completes.
+        const upstream = net.connect(opts.upstreamPort, "127.0.0.1");
+        upstream.setTimeout(0);
+        upstream.setNoDelay(true);
+        client.setNoDelay(true);
+        let recordedPort;
+        upstream.on("connect", () => {
+            recordedPort = upstream.localPort;
+            if (recordedPort !== undefined && client.remoteAddress) {
+                clientIpByUpstreamPort.set(recordedPort, client.remoteAddress);
+            }
+            // `pipe` carries backpressure and the half-close in both
+            // directions, which is what a WebSocket bridge and a streamed
+            // upload each need.
+            client.pipe(upstream);
+            upstream.pipe(client);
+        });
+        const teardown = () => {
+            if (recordedPort !== undefined)
+                clientIpByUpstreamPort.delete(recordedPort);
+            live.delete(client);
+            client.destroy();
+            upstream.destroy();
+        };
+        client.on("error", (err) => {
+            warn("tls client connection failed", err);
+            teardown();
+        });
+        upstream.on("error", (err) => {
+            warn(`ingress upstream :${opts.upstreamPort} failed`, err);
+            teardown();
+        });
+        client.on("close", teardown);
+        upstream.on("close", teardown);
+    });
+    // A client that aborts mid-handshake, or offers a protocol version we
+    // do not speak, emits this. It must be handled: an unhandled 'error' on
+    // a net server is thrown, and taking the daemon down over one bad
+    // handshake would be a far worse failure than the one being fixed.
+    server.on("tlsClientError", (err) => warn("tls handshake failed", err));
+    server.on("error", (err) => warn(`tls listener :${opts.port} failed`, err));
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(opts.port, opts.hostname, () => {
+            server.removeListener("error", reject);
+            resolve({
+                port: opts.port,
+                clientIpFor: (upstreamPort) => upstreamPort === undefined ? undefined : clientIpByUpstreamPort.get(upstreamPort),
+                connectionCount: () => live.size,
+                close: () => {
+                    try {
+                        server.close();
+                    }
+                    catch (err) {
+                        warn("closing the tls listener failed", err);
+                    }
+                    for (const sock of [...live])
+                        sock.destroy();
+                    live.clear();
+                    clientIpByUpstreamPort.clear();
+                },
+            });
+        });
+    });
+}

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

@@ -6,22 +6,12 @@
  * 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.)
+ * semantics. Every volume lives inside it: the one cache spectest keeps
+ * across environments is the container store, which is not a volume at
+ * all (CONTAINER_STORE.md).
  */
 /** 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 {
@@ -34,8 +24,6 @@ export interface VolumeSpec {
     /** 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.
@@ -57,6 +45,13 @@ export declare function sanitizeSegment(p: string): string;
  *  3. A relative `source`, or nothing at all — under the service's own
  *     directory, derived from `target` when `source` is absent.
  *
+ * `source` honours the `{{SPECTEST_SERVICE}}` token, for the same reason
+ * `files` does: a component cannot know the map key the user will give it,
+ * and an **absolute** source gets no automatic per-service directory. A
+ * component that needs one — a nested runtime keeping its store under
+ * {@link NESTED_STORE_ROOT}, where two of them sharing one directory would
+ * be two daemons on one metadata store — writes the token into the path.
+ *
  * `workspace` is a parameter rather than a module constant so the rule is
  * testable without touching the filesystem.
  */
@@ -64,7 +59,8 @@ export declare function resolveHostPath(service: string, vol: VolumeSpec, worksp
 /**
  * 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`.
+ * True for a volume on a mounted cache disk, and for an absolute source
+ * 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

@@ -6,23 +6,14 @@
  * 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.)
+ * semantics. Every volume lives inside it: the one cache spectest keeps
+ * across environments is the container store, which is not a volume at
+ * all (CONTAINER_STORE.md).
  */
 import path from "node:path";
+import { expandServiceToken } from "./file-mounts";
 /** 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";
 /**
@@ -50,30 +41,37 @@ export function sanitizeSegment(p) {
  *  3. A relative `source`, or nothing at all — under the service's own
  *     directory, derived from `target` when `source` is absent.
  *
+ * `source` honours the `{{SPECTEST_SERVICE}}` token, for the same reason
+ * `files` does: a component cannot know the map key the user will give it,
+ * and an **absolute** source gets no automatic per-service directory. A
+ * component that needs one — a nested runtime keeping its store under
+ * {@link NESTED_STORE_ROOT}, where two of them sharing one directory would
+ * be two daemons on one metadata store — writes the token into the path.
+ *
  * `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"];
+    const source = vol.source === undefined ? undefined : expandServiceToken(vol.source, service);
     if (vol.name) {
-        const root = vol.cache ? [CACHE_ROOT, SHARED_DIR] : [...stateRoot, SHARED_DIR];
-        return path.join(...root, sanitizeSegment(vol.name));
+        return path.join(...stateRoot, SHARED_DIR, 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(/^\/+/, ""));
+    // An absolute source is the project's own path, used as is.
+    if (source && source.startsWith("/"))
+        return source;
+    const root = [...stateRoot, service];
+    if (source) {
+        return path.join(...root, 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`.
+ * True for a volume on a mounted cache disk, and for an absolute source
+ * 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);

package/dist/index.d.ts

@@ -815,15 +815,6 @@ export interface VolumeMount {
     /** Container path. */
     target: string;
     readOnly?: boolean;
-    /**
-     * Cache volume: the backing dir lives outside the per-env state tree and
-     * survives a delta-restore teardown (which recreates every container,
-     * volume, and the daemon for fresh-state semantics). Reserve this for
-     * content-addressed data whose presence is purely an accelerator — an
-     * image/layer store, a package cache — never for app state: anything in
-     * a cache volume is visible to the "fresh" environment.
-     */
-    cache?: boolean;
 }
 export interface FileMount {
     /** Absolute path inside the container where the file is mounted. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.69.0",
+  "version": "0.71.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",