@specific.dev/spectest 0.119.5 → 0.120.0

package/dist/components/k3s.d.ts

@@ -30,10 +30,7 @@ export interface K3sOptions {
     images?: readonly KubernetesImage[];
     /**
      * Image tag for the official `rancher/k3s` image. Default
-     * `"v1.33.5-k3s1"`. Any tag works; a k3s older than 1.33 embeds a
-     * containerd (1.7) without the EROFS snapshotter, so its cluster keeps
-     * its images on overlayfs and shares the environment's image cache only
-     * as a directory that survives — see `k3s()`'s store section.
+     * `"v1.33.5-k3s1"`. The cluster keeps its image store on overlayfs.
      */
     version?: string;
     /**
@@ -365,14 +362,14 @@ export declare function k3s(opts?: K3sOptions): {
         source: string;
         target: string;
         readOnly?: undefined;
-    } | {
-        source: string;
-        target: string;
-        readOnly: boolean;
     } | {
         target: string;
         source?: undefined;
         readOnly?: undefined;
+    } | {
+        source: string;
+        target: string;
+        readOnly: boolean;
     })[];
     files: {
         path: string;

package/dist/components/k3s.js

@@ -11,7 +11,6 @@ import { readFile, unlink } from "node:fs/promises";
 import { AppsV1Api, BatchV1Api, CoreV1Api, KubeConfig, KubernetesObjectApi, PatchStrategy, ResponseContext, ServerConfiguration, createConfiguration, loadAllYaml, } from "@kubernetes/client-node";
 import { Observable } from "@kubernetes/client-node/dist/gen/rxjsStub.js";
 import { dnsName, provides, SELF_SERVICE_TOKEN } from "../index.js";
-import { MKFS_EROFS_PATH, STORE_ADOPT_PATH, imageCachePathsSync, nestedStoreDir, } from "../harness/image-cache.js";
 import { stickyDiskPathSync } from "../harness/sticky-paths.js";
 import { registerStickyKubernetesStore, stickyKubernetesDirectory } from "../harness/sticky-kubernetes.js";
 import { prePullK3sImages } from "../harness/k3s-prepull.js";
@@ -22,15 +21,8 @@ import { recorderAnnotate, recorderRemove } from "../recorder.js";
 const K3S_REGISTRY_PORT = 5000;
 /** The cluster's own containerd root, inside the k3s container. */
 const CLUSTER_STORE_TARGET = "/var/lib/rancher/k3s/agent/containerd";
-/** Where k3s (containerd 2.x layout) reads a containerd config template. */
-const CONTAINERD_TEMPLATE_PATH = "/var/lib/rancher/k3s/agent/etc/containerd/config-v3.toml.tmpl";
-/** The EROFS settings that template imports; the store's prepare daemon
- *  imports the same file, so both daemons agree on the snapshotter. */
-const CONTAINERD_EROFS_CONFIG_PATH = "/etc/spectest/containerd-erofs.toml";
 /** The socket of the throwaway daemon that prepares the store. */
 const PREPARE_SOCKET = "/run/spectest-prepare.sock";
-/** containerd's CRI plugin lists only images carrying this label. */
-const CRI_MANAGED_LABEL = "io.cri-containerd.image=managed";
 /**
  * Written before the server starts and removed by the ready probe.
  *
@@ -46,78 +38,6 @@ const BOOT_MARKER = ".spectest-boot-incomplete";
  * sticky-kubernetes adapter removes runtime state and retains images and
  * unpacked layers under the shared filesystem budget. Test forks do not
  * write back. The preparation wrapper below also handles delta rebuilds.
- *
- * Legacy image-cache integration (`CONTAINER_STORE.md` §12):
- *
- * The cluster's embedded containerd keeps its root on the **root disk**
- * of the environment's image cache, in a directory of its own
- * (`<root>/spectest-nested/<service>`, bind-mounted at
- * `CLUSTER_STORE_TARGET`), and runs the **EROFS snapshotter** over the
- * same read-only **layers disk** the guest's own containerd uses,
- * mounted into the container at the same path. So a layer is one file
- * on the host whichever runtime holds it, the cluster's pulls land in
- * the lineage's root clone like a `docker pull` does, and the merge
- * reads the cluster's indexes exactly as it reads dockerd's — at every
- * VM teardown, whether the pull happened at env boot or in the middle
- * of a test. Nothing distinguishes the two: a fork's root clone grew,
- * so it is harvested. The next cold build's cluster **adopts** what the
- * merge put on the layers disk under its own namespace (`k8s.io`) with
- * the same helper dockerd's store uses, before the cluster starts.
- *
- * Extraction is 48x the I/O of the download (`STICKY_DISKS.md` §7.2),
- * which is why a mirror never helped here and an extracted, shared
- * store is the whole prize. Measured on the one project on the old
- * per-environment store: 20.6 s of cluster bring-up per build.
- *
- * Three things the container needs for it, all mounted by `k3s()`:
- * golden's static `mkfs.erofs` (the EROFS differ needs it and no k3s
- * image ships one); the adopt helper (POSIX sh, run by busybox); and a
- * containerd config template that imports the EROFS settings — k3s
- * generates its config from `config-v3.toml.tmpl` when present, and an
- * `imports` line on top of the stock template is the one way to add
- * plugin sections without colliding with the ones it writes. The
- * EROFS snapshotter mounts every layer through a loop device, and a
- * privileged container's `/dev` is a static copy that never sees the
- * nodes the kernel allocates later, so the wrapper pre-creates 1024 of
- * them (measured: 0 s).
- *
- * What the store inherits with the cache is one build's crash state:
- * the root was captured from a running guest, and the teardown's
- * `docker rm -f` killed that cluster where it stood. **Deleting the dead
- * files is not enough, and the failure is not subtle.** containerd's
- * index still lists the previous build's containers, so the CRI plugin
- * offers them to a kubelet whose API server has never heard of them; the
- * kubelet spends its startup reconciling containers whose tasks are gone
- * (`Failed to create existing container … task not found`) and does not
- * register its own Node in time, and the CSI plugin — which waits on that
- * Node with a fixed budget — calls `Fatalf`. The kubelet dies, k3s exits
- * 2, and what the author sees is a rollout that timed out against a
- * hostname that no longer resolves. Measured: 2 of 2 delta restores,
- * against 2 of 2 clean without the store.
- *
- * So a **throwaway daemon** on the store, with the CRI plugin disabled,
- * does both jobs before k3s starts: it deletes the previous build's
- * containers and their tasks through containerd itself (the only thing
- * that can edit its index), and it adopts the inbox. Images, content
- * blobs and extracted snapshots — the whole cache — stay. It is the same
- * discipline `spectest-image-cache-up` applies to the guest's own store
- * one level up.
- *
- * Two failures cost a cache and never a build:
- *
- *  1. **A sweep that cannot run wipes the store.** A daemon that will not
- *     start leaves behind exactly the containers this cluster fatals on,
- *     so carrying on is the one option that is known bad.
- *  2. **A store that did not work is never inherited twice.** The marker
- *     is written before the server starts and removed by the ready probe,
- *     so it survives only when a boot never reached a live API server.
- *     That is the backstop for the sweep being incomplete in some way we
- *     have not seen: the cost is one cold build's pulls, and it repairs
- *     itself.
- *
- * Without an image cache (the fake backend, a server that predates it)
- * the store is a per-environment volume as before, on overlayfs, with
- * the same sweep.
  */
 /** Plugins the prepare daemon does not need. Every plugin is startup
  *  time, and the daemon sits on the critical path of the cluster's boot.
@@ -135,37 +55,9 @@ const SWEEP_DISABLED_PLUGINS = [
     "io.containerd.snapshotter.v1.fuse-overlayfs",
 ];
 const DISABLED_PLUGINS_TOML = `disabled_plugins = [${SWEEP_DISABLED_PLUGINS.map((p) => `"${p}"`).join(", ")}]`;
-/** The containerd config template: the stock one, importing our EROFS
- *  settings. `imports` is a top-level key and has to come first. */
-const CONTAINERD_TEMPLATE = `imports = ["${CONTAINERD_EROFS_CONFIG_PATH}"]\n{{ template "base" . }}\n`;
-/**
- * containerd's EROFS settings, the same golden bakes for the guest's
- * own daemon (`local-vms-rootfs.Dockerfile`): the differ first, the
- * transfer service unpacking onto EROFS, and `set_immutable` off because
- * a committed layer's file is a symlink into a read-only disk, on which
- * the immutable ioctl would fail the commit.
- */
-function erofsConfigToml() {
-    const arch = process.arch === "arm64" ? "arm64" : process.arch === "x64" ? "amd64" : process.arch;
-    return [
-        "version = 3",
-        '[plugins."io.containerd.snapshotter.v1.erofs"]',
-        "  set_immutable = false",
-        '[plugins."io.containerd.differ.v1.erofs"]',
-        '  mkfs_options = ["-T0", "--mkfs-time", "--sort=none"]',
-        '[plugins."io.containerd.service.v1.diff-service"]',
-        '  default = ["erofs","walking"]',
-        '[plugins."io.containerd.transfer.v1.local"]',
-        '  [[plugins."io.containerd.transfer.v1.local".unpack_config]]',
-        `    platform = "linux/${arch}"`,
-        '    snapshotter = "erofs"',
-        '    differ = "erofs"',
-        "",
-    ].join("\n");
-}
 /**
  * The store-preparation half of the command wrapper: sweep the crash
- * state, adopt the cache's inbox (image-cache mode), leave `SNAP` set to
+ * state and leave `SNAP` set to
  * the snapshotter the cluster starts on.
  *
  * Runs under busybox `sh`. Every `ctr` call is one invocation for the
@@ -174,25 +66,10 @@ function erofsConfigToml() {
  * per-container form spent seconds of the cluster's boot on process
  * starts alone (measured: ready 3.6 s -> 7.0 s).
  */
-function storePrepareSh(cache) {
-    const daemonConfig = cache
-        ? // containerd 2.x (v3 config, EROFS) when the image's containerd has
-            // the snapshotter; a 1.7 image (k3s < 1.33) gets the v2 shape it
-            // understands and stays on overlayfs.
-            `if [ "$EROFS" = 1 ]; then printf '%s\\n' 'version = 3' 'imports = ["${CONTAINERD_EROFS_CONFIG_PATH}"]' '${DISABLED_PLUGINS_TOML}' > /run/spectest-prepare.toml; ` +
-                `else printf '%s\\n' 'version = 2' '${DISABLED_PLUGINS_TOML}' > /run/spectest-prepare.toml; fi; `
-        : `printf '%s\\n' 'version = 2' '${DISABLED_PLUGINS_TOML}' > /run/spectest-prepare.toml; `;
-    const detect = cache
-        ? `EROFS=0; if containerd config default 2>/dev/null | grep -q 'snapshotter.v1.erofs'; then EROFS=1; fi; ` +
-            `if [ "$EROFS" = 1 ]; then SNAP=erofs; i=0; while [ $i -lt 1024 ]; do [ -e /dev/loop$i ] || mknod /dev/loop$i b 7 $i 2>/dev/null; i=$((i+1)); done; ` +
-            `else SNAP=overlayfs; echo 'spectest: this k3s image has no EROFS snapshotter; the cluster keeps its images on overlayfs and shares the image cache as a directory only' >&2; fi; `
-        : `EROFS=0; SNAP=overlayfs; `;
-    const adopt = cache
-        ? `adopt_store() { [ "$EROFS" = 1 ] && [ -f "$L/spectest-inbox/layers.txt" ] || return 0; ` +
-            `${STORE_ADOPT_PATH} "$S" "$L" -n k8s.io -a "$A" -l ${CRI_MANAGED_LABEL} 2>&1 | tail -1; }; `
-        : `adopt_store() { :; }; `;
-    return (`S=${CLUSTER_STORE_TARGET}; M="$S/${BOOT_MARKER}"; A=${PREPARE_SOCKET}; L=${cache ? cache.layers : "/nonexistent"}; ` +
-        detect +
+function storePrepareSh() {
+    const daemonConfig = `printf '%s\\n' 'version = 2' '${DISABLED_PLUGINS_TOML}' > /run/spectest-prepare.toml; `;
+    return (`S=${CLUSTER_STORE_TARGET}; M="$S/${BOOT_MARKER}"; A=${PREPARE_SOCKET}; ` +
+        `SNAP=overlayfs; ` +
         `start_daemon() { ` +
         daemonConfig +
         `containerd -c /run/spectest-prepare.toml --root "$S" --state /run/spectest-prepare ` +
@@ -211,16 +88,15 @@ function storePrepareSh(cache) {
         // k3s ships they are ordinary containers and this is a no-op.
         `sb=$(timeout 30 ctr -a "$A" -n k8s.io sandboxes ls 2>/dev/null | awk 'NR > 1 {print $1}'); ` +
         `[ -n "$sb" ] && timeout 60 ctr -a "$A" -n k8s.io sandboxes rm --force $sb >/dev/null 2>&1; return 0; }; ` +
-        adopt +
         `if [ -e "$M" ]; then ` +
         `echo 'spectest: the previous cluster on this image store never became ready; starting from an empty one' >&2; ` +
         `rm -rf "$S"/* "$S"/.[!.]* 2>/dev/null || true; fi; ` +
         `mkdir -p "$S"; ` +
         `had_state=0; [ -d "$S/io.containerd.metadata.v1.bolt" ] && had_state=1; ` +
         `T0=$(date +%s); ` +
-        `if [ "$had_state" = 1 ] || [ "$EROFS" = 1 ]; then ` +
+        `if [ "$had_state" = 1 ]; then ` +
         `if start_daemon; then ` +
-        `[ "$had_state" = 1 ] && sweep_store; adopt_store; stop_daemon; ` +
+        `[ "$had_state" = 1 ] && sweep_store; stop_daemon; ` +
         // Timed and printed always: this is inside the cluster's ready time,
         // so it is the first thing to suspect if that time moves.
         `echo "spectest: cluster image store at $S ready on $SNAP (prepared in $(($(date +%s)-T0))s)"; ` +
@@ -1445,12 +1321,6 @@ async function collectDiagnostics(client, namespace) {
  * so neither cold-cache nor warm starts re-pull. Any `opts.version`
  * works — there's no base-snapshot release to keep in sync with.
  *
- * **Why v1.33.x:** k3s 1.33.5 is the first line embedding containerd
- * 2.1 (2.1.4-k3s1), whose in-tree EROFS snapshotter is what lets the
- * cluster share the environment's image cache (see the store section
- * above); 1.32 ships containerd 1.7. kube-proxy's `nftables` proxy mode
- * is GA since k8s 1.32 (beta in 1.31, alpha-gated in 1.30); dropping
- * below 1.31 falls back to the iptables path.
  */
 const DEFAULT_K3S_VERSION = "v1.33.5-k3s1";
 export function k3s(opts = {}) {
@@ -1479,12 +1349,9 @@ export function k3s(opts = {}) {
     // the in-cluster registry). Seeded via `files` because k3s reads it
     // only at startup, before any setup hook could run.
     const registriesYaml = buildRegistriesYaml(registryEnabled, registryHost);
-    // The environment's image cache, when this VM carries one: the
-    // cluster's store goes on its root disk and its layers come off the
-    // shared layers disk (see the store section above).
+    // Pre-pulls read content from the environment's containerd store.
     const sticky = stickyDiskPathSync();
-    const cache = sticky ? null : imageCachePathsSync();
-    const contentDirectory = `${sticky ? `${sticky}/containerd` : cache?.root ?? "/var/lib/containerd"}/${CONTENT_BLOBS}`;
+    const contentDirectory = `${sticky ? `${sticky}/containerd` : "/var/lib/containerd"}/${CONTENT_BLOBS}`;
     const serverArgs = [
         "k3s",
         "server",
@@ -1566,9 +1433,8 @@ export function k3s(opts = {}) {
         // is affected.
         "mount --make-rshared / 2>/dev/null || " +
         "echo 'spectest: could not make / rshared; CSI node plugins may fail to publish volumes' >&2; " +
-        storePrepareSh(cache) +
-        // The snapshotter is decided by the wrapper: EROFS on the image cache
-        // when the image's containerd has it, overlayfs otherwise.
+        storePrepareSh() +
+        // Sticky and environment-local stores use overlayfs.
         `exec ${serverArgs} --snapshotter=$SNAP`;
     // Plain /readyz probe. On a warm zot cache the cluster's images are
     // already local, so the first boot completes in seconds; the
@@ -1598,22 +1464,9 @@ export function k3s(opts = {}) {
         // in this list (it's documentation, not a firewall).
         ports: registryEnabled ? [80, 443, 6443, K3S_REGISTRY_PORT] : [80, 443, 6443],
         // Sticky disks retain an independent overlayfs store per service/version.
-        // The legacy image cache (see the store section above) keeps its
-        // containerd root on the image cache's root disk, the shared layers
-        // disk read-only at its guest path, golden's mkfs.erofs and the adopt
-        // helper — or, with no cache, a per-environment volume. Two clusters
-        // in one environment get separate roots either way (the service
-        // token names the directory), because two containerd daemons cannot
-        // share a store: bolt takes an exclusive lock.
         volumes: [...(sticky
                 ? [{ source: `${stickyKubernetesDirectory(SELF_SERVICE_TOKEN, version)}/containerd`, target: CLUSTER_STORE_TARGET }]
-                : cache ? [
-                    { source: nestedStoreDir(cache, SELF_SERVICE_TOKEN), target: CLUSTER_STORE_TARGET },
-                    { source: cache.layers, target: cache.layers, readOnly: true },
-                    { source: MKFS_EROFS_PATH, target: MKFS_EROFS_PATH, readOnly: true },
-                    { source: STORE_ADOPT_PATH, target: STORE_ADOPT_PATH, readOnly: true },
-                ]
-                    : [{ target: CLUSTER_STORE_TARGET }]),
+                : [{ target: CLUSTER_STORE_TARGET }]),
             ...(publishBuilds.length ? [
                 { source: registryDirectory(SELF_SERVICE_TOKEN), target: REGISTRY_DATA },
                 { source: contentDirectory, target: REGISTRY_CONTENT, readOnly: true },
@@ -1621,12 +1474,6 @@ export function k3s(opts = {}) {
         ],
         files: [
             ...(registriesYaml ? [{ path: "/etc/rancher/k3s/registries.yaml", content: registriesYaml }] : []),
-            ...(cache
-                ? [
-                    { path: CONTAINERD_TEMPLATE_PATH, content: CONTAINERD_TEMPLATE },
-                    { path: CONTAINERD_EROFS_CONFIG_PATH, content: erofsConfigToml() },
-                ]
-                : []),
         ],
         readyCheck: {
             type: "exec",

package/dist/coverage-next.d.ts

@@ -16,5 +16,6 @@ export interface NextBuildMetadata {
     browserMaps: number;
 }
 /** Server + browser coverage for a built Next app. Build-time maps are required;
- * use withCoverage from @specific.dev/spectest/next in the Next configuration. */
+ * enable native Next source maps and retain them in the runtime image.
+ * Configure this adapter only in Spectest; the application needs no SDK dependency. */
 export declare function next(options?: NextCoverageOptions): CoverageAdapter;

package/dist/coverage-next.js

@@ -40,7 +40,7 @@ if (require.main === module) {
     }
     walk(path.join(dist, "server"), true);
     walk(path.join(dist, "static"), false);
-    if (!serverMaps || !browserMaps) throw new Error("Next coverage needs server and browser .js.map files in the runtime image. Enable withCoverage from @specific.dev/spectest/next in the test build and retain .next/server and .next/static maps when copying standalone output.");
+    if (!serverMaps || !browserMaps) throw new Error("Next coverage needs server and browser .js.map files in the runtime image. Enable productionBrowserSourceMaps and experimental.serverSourceMaps in Next config, and copy .next/server and .next/static maps into the runtime image, including Edge maps.");
     process.stdout.write(JSON.stringify({generated:launcher(m), serverMaps, browserMaps}));
   } catch (e) { console.error("Next coverage: " + e.message); process.exitCode = 1; }
 }
@@ -55,7 +55,8 @@ const GENERATED_SOURCES = [
     "*/app/*.mjs (structured image object)",
 ];
 /** Server + browser coverage for a built Next app. Build-time maps are required;
- * use withCoverage from @specific.dev/spectest/next in the Next configuration. */
+ * enable native Next source maps and retain them in the runtime image.
+ * Configure this adapter only in Spectest; the application needs no SDK dependency. */
 export function next(options = {}) {
     const sourceRoot = options.sourceRoot === undefined ? "." : options.sourceRoot;
     if (typeof sourceRoot !== "string" || !sourceRoot || /[\\:\0\r\n]/.test(sourceRoot) || (sourceRoot !== "." && sourceRoot.split("/").some(p => !p || p === "." || p === "..")))

package/dist/daemon.js

@@ -71,7 +71,6 @@ import { startHttp2Proxy } from "./harness/http2-proxy.js";
 import { startTlsTerminator } from "./harness/tls-terminator.js";
 import { runContainerArgs } from "./harness/container-run.js";
 import { isOnStickyDisk } from "./harness/sticky-paths.js";
-import { BUILDKIT_CACHE_DIR, BUILDKIT_CACHE_UNION, IMAGE_CACHE_MANIFEST, imageCachePathsSync, isOnImageCache, mergeCacheIndex, } from "./harness/image-cache.js";
 import { assertAbsolute, certificateHostnames, defaultKeyMode, expandServiceToken, isNoopChown, mountFlag, needsIdTables, numericId, resolveChownIds, } from "./harness/file-mounts.js";
 import { badRequest, conflict, notFound, requireString, } from "./harness/methods.js";
 import { openTerminal } from "./terminal.js";
@@ -475,158 +474,19 @@ async function hasBuildx() {
     }
     return _buildxAvailable;
 }
-// Every VM carries its project's container store (CONTAINER_STORE.md):
-// the disk every pull and every build lands on, mounted by the control
-// plane before this harness starts. The manifest below says where; the
-// in-VM buildkitd keeps its exported cache there too, so a fresh VM finds
-// every layer it built before. Detected once; if the daemon will not
-// start, dockerd's own BuildKit builds instead.
 const LOCAL_BUILDER_NAME = "spectest-local";
-const LOCAL_BUILDKIT_ADDR = "tcp://127.0.0.1:1234";
-/** The bring-up script the cache base bakes (`base.rs::BUILDKITD_UP_SH`). */
-const BUILDKITD_UP_PATH = "/usr/local/bin/spectest-buildkitd-up";
-/** Where the control plane mounted this VM's image cache: containerd's
- *  root (read-write, this VM's own) and the layers disk (read-only, shared
- *  by every VM of a generation). `null` when the VM carries no cache. */
-async function imageCachePaths() {
-    return imageCachePathsSync(IMAGE_CACHE_MANIFEST);
-}
-/**
- * The bring-up, once. A promise and not a flag: every build of a
- * bootstrap calls this at the same time now that builds go in together,
- * and a flag set to "not yet" while the first caller waits for buildkitd
- * sent every other build to dockerd's own builder — which cannot build
- * on the erofs store at all (`lease does not exist`), so Specific's
- * first three cold builds on SDK 0.76.0 failed inside ten seconds
- * (2026-09-07). Sharing the promise makes every caller wait for the one
- * bring-up and read its one answer.
- */
+// Every concurrent image build waits for the same consumer readiness check.
 let _localBuilder;
-/**
- * Start buildkitd inside this VM with its state on the cache disk, and
- * register it as a buildx `remote` builder.
- *
- * Lazy on purpose: it runs on the first build a project actually does,
- * so a project with no dockerfile service never pays for a builder. And
- * best-effort: a daemon that will not start falls back to the shared host
- * one, which is a slower build and not a failed one.
- */
 function ensureLocalBuildkitd() {
-    _localBuilder ??= bringUpLocalBuildkitd();
-    return _localBuilder;
-}
-async function bringUpLocalBuildkitd() {
-    if (existsSync("/run/spectest-sticky/consumer.json")) {
+    _localBuilder ??= (async () => {
+        if (!existsSync("/run/spectest-sticky/consumer.json"))
+            return false;
         const ready = await docker(["buildx", "inspect", "--bootstrap", LOCAL_BUILDER_NAME], 30_000);
         if (ready.code !== 0)
             throw new Error(`sticky BuildKit unavailable: ${ready.stderr}`);
         return true;
-    }
-    const paths = await imageCachePaths();
-    if (!paths)
-        return false;
-    const state = paths.root;
-    if (!(await hasBuildx()))
-        return false;
-    // The bring-up itself is a script baked into the image cache's base
-    // snapshot (`base.rs::BUILDKITD_UP_SH`), so production and the real-VM
-    // test drive exactly the same daemon with exactly the same config. All
-    // it takes from us is where the state lives — the registry routing is
-    // its own (Docker Hub via `mirror.gcr.io`, deliberately not the host
-    // zot instance).
-    const started = await shx("/bin/bash", [BUILDKITD_UP_PATH, state], 900_000);
-    if (started.code !== 0) {
-        // eslint-disable-next-line no-console
-        console.warn(`[build] in-VM buildkitd would not start; building with dockerd's own BuildKit:\n${(started.stderr || started.stdout).trim()}`);
-        return false;
-    }
-    const create = await docker(["buildx", "create", "--name", LOCAL_BUILDER_NAME, "--driver", "remote", LOCAL_BUILDKIT_ADDR], 30_000);
-    if (create.code !== 0 && !/existing instance|already exists/i.test(create.stderr)) {
-        // eslint-disable-next-line no-console
-        console.warn(`[build] could not register the in-VM builder:\n${create.stderr.trim()}`);
-        return false;
-    }
-    // `inspect --bootstrap` dials the daemon, so it is both the readiness
-    // wait and the proof it is really answering.
-    const boot = await docker(["buildx", "inspect", "--bootstrap", LOCAL_BUILDER_NAME], 120_000);
-    if (boot.code !== 0) {
-        // eslint-disable-next-line no-console
-        console.warn(`[build] in-VM buildkitd never answered; building with dockerd's own BuildKit:\n${boot.stderr.trim()}`);
-        return false;
-    }
-    // eslint-disable-next-line no-console
-    console.log(`[build] building in this VM against the image cache (root ${paths.root}, layers ${paths.layers})`);
-    // The cache directory union is for the project's OWN BuildKit (the
-    // `/services` docs page tells it to mount `BUILDKIT_CACHE_UNION`).
-    // The harness's builds no longer touch it: their cache is the
-    // daemon's own state, which lives on the root disk and rides the
-    // base root into the next cold build (CONTAINER_STORE.md §20), so a
-    // hit is a snapshot that already exists — no tar blob to unpack
-    // before the first uncached step, no export pass after a miss.
-    await ensureBuildkitCacheUnion(paths);
-    return true;
-}
-/**
- * Mount the BuildKit cache union (`BUILDKIT_CACHE_UNION`): overlayfs with
- * the layers disk's cache directory as the lower and the root disk's as
- * the upper, so one path serves `--cache-from` and `--cache-to`.
- *
- * Idempotent — a delta restore restarts the harness on a guest that
- * still has the mount. Returns null, and the caller keeps the two-directory
- * scheme, when the lower does not exist yet (a volume that has never
- * been merged has no cache directory on its layers disk) or the mount is
- * refused; the build is then slower, never failed. The work directory
- * has to share a filesystem with the upper, so it lives on the root disk
- * beside it; the merge reads neither it nor anything but the upper.
- */
-async function ensureBuildkitCacheUnion(paths) {
-    const lower = `${paths.layers}/${BUILDKIT_CACHE_DIR}`;
-    const upper = `${paths.root}/${BUILDKIT_CACHE_DIR}`;
-    const work = `${paths.root}/spectest-buildkit-work`;
-    if (!existsSync(lower)) {
-        // eslint-disable-next-line no-console
-        console.log(`[build] no merged BuildKit cache on the layers disk yet; exporting to the root directly`);
-        return null;
-    }
-    // overlayfs shows the upper's `index.json` INSTEAD of the lower's, so
-    // an index on the root (a lineage's exports, or one left behind with
-    // its blobs gone) would hide every merged tag and, naming manifests
-    // that are not there, make BuildKit skip the import altogether. Write
-    // the union of the two into the upper first (`mergeCacheIndex`), and
-    // say what each side held so a miss can be read off the boot log.
-    try {
-        const readIndex = (dir) => existsSync(`${dir}/index.json`) ? JSON.parse(readFileSync(`${dir}/index.json`, "utf8")) : null;
-        const lowerIdx = readIndex(lower);
-        const upperIdx = readIndex(upper);
-        if (upperIdx && lowerIdx) {
-            const merged = mergeCacheIndex(lowerIdx, upperIdx, (hex) => existsSync(`${upper}/blobs/sha256/${hex}`));
-            await fs.mkdir(upper, { recursive: true });
-            await fs.writeFile(`${upper}/index.json`, JSON.stringify(merged));
-            await fs.writeFile(`${upper}/oci-layout`, JSON.stringify({ imageLayoutVersion: "1.0.0" }));
-            // eslint-disable-next-line no-console
-            console.log(`[build] BuildKit cache union: ${lowerIdx.manifests.length} tag(s) from the merged cache, ${upperIdx.manifests.length} on this root, ${merged.manifests.length} after the merge`);
-        }
-        else {
-            // eslint-disable-next-line no-console
-            console.log(`[build] BuildKit cache union: ${lowerIdx?.manifests.length ?? 0} tag(s) from the merged cache, none on this root`);
-        }
-    }
-    catch (err) {
-        // eslint-disable-next-line no-console
-        console.warn(`[build] could not reconcile the BuildKit cache indexes (${err}); the union shows the root's`);
-    }
-    const r = await shx("/bin/sh", [
-        "-c",
-        `mkdir -p "${BUILDKIT_CACHE_UNION}" "${upper}" "${work}" && ` +
-            `{ mountpoint -q "${BUILDKIT_CACHE_UNION}" || ` +
-            `mount -t overlay overlay -o "lowerdir=${lower},upperdir=${upper},workdir=${work}" "${BUILDKIT_CACHE_UNION}"; }`,
-    ], 60_000);
-    if (r.code !== 0) {
-        // eslint-disable-next-line no-console
-        console.warn(`[build] could not mount the BuildKit cache union; exporting to the root directly:\n${(r.stderr || r.stdout).trim()}`);
-        return null;
-    }
-    return BUILDKIT_CACHE_UNION;
+    })();
+    return _localBuilder;
 }
 /**
  * A reference as containerd names it. buildx's `-t` on a remote builder
@@ -704,7 +564,7 @@ async function ensureVolumes(svc) {
             // A directory on a cache disk is the same kind of thing: a nested
             // runtime's containerd root (`k3s()`), kept as a cache by the
             // lineage exactly as the container store one level up is.
-            const durable = host.startsWith("/var/cache/spectest/") || isOnStickyDisk(host) || isOnImageCache(host, imageCachePathsSync(IMAGE_CACHE_MANIFEST));
+            const durable = host.startsWith("/var/cache/spectest/") || isOnStickyDisk(host);
             if (vol.source?.startsWith("/") && !durable) {
                 await recordAbsoluteVolumeDir(host);
             }
@@ -2755,7 +2615,7 @@ async function bootstrapInner(prepared, identity) {
     // Prep concurrency: everything at once. Registry pulls are
     // network-bound and cheap in RAM. Dockerfile builds all go to the one
     // in-VM buildkitd, whose `max-parallelism` (all but one vCPU,
-    // `base.rs::BUILDKITD_UP_SH`) caps the steps in flight across every
+    // the sticky consumer) caps the steps in flight across every
     // build it holds, and whose steps run under a cgroup with a memory
     // ceiling — so a fully cached build finishes at once while a miss is
     // still running, and two installs that fan out together kill a step,

package/dist/harness/buildkit-progress.d.ts

@@ -42,7 +42,7 @@ export declare function summarizeBuildKit(out: string): BuildStep[];
  * Between SDK 0.75.0 and 0.76.0 this gated the harness's cache export
  * (a `mode=max` export cost ~3 s per service with nothing to write,
  * measured 2026-09-06). The harness exports nothing since its cache is
- * the daemon's own state (CONTAINER_STORE.md §20); the reading stays,
+ * the daemon's own state (CONTAINER_STORE.md); the reading stays,
  * since it is the one machine-readable answer to "did this build run
  * anything".
  *

package/dist/harness/buildkit-progress.js

@@ -71,7 +71,7 @@ export function summarizeBuildKit(out) {
  * Between SDK 0.75.0 and 0.76.0 this gated the harness's cache export
  * (a `mode=max` export cost ~3 s per service with nothing to write,
  * measured 2026-09-06). The harness exports nothing since its cache is
- * the daemon's own state (CONTAINER_STORE.md §20); the reading stays,
+ * the daemon's own state (CONTAINER_STORE.md); the reading stays,
  * since it is the one machine-readable answer to "did this build run
  * anything".
  *

package/dist/harness/container-run.d.ts

@@ -80,7 +80,7 @@ export interface ContainerRunInput {
     /** The bridge gateway, where the ingress listeners are. Null when it
      *  isn't known yet, in which case no `--add-host` is emitted. */
     gatewayIp?: string | null;
-    /** The host image-cache gateway, reachable as `spectest-host`. */
+    /** The host registry-cache gateway, reachable as `spectest-host`. */
     hostCacheGateway?: string | null;
     hostCacheName: string;
     /** The in-VM root CA, bind-mounted and appended to Node's roots. */

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

@@ -49,7 +49,7 @@ export declare function sanitizeSegment(p: string): string;
  * `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
- * the image cache's `spectest-nested/<service>` (`image-cache.ts::nestedStoreDir`),
+ * the sticky disk's per-service Kubernetes directory,
  * where two of them sharing one directory would be two daemons on one
  * metadata store — writes the token into the path.
  *

package/dist/harness/volume-paths.js

@@ -45,7 +45,7 @@ export function sanitizeSegment(p) {
  * `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
- * the image cache's `spectest-nested/<service>` (`image-cache.ts::nestedStoreDir`),
+ * the sticky disk's per-service Kubernetes directory,
  * where two of them sharing one directory would be two daemons on one
  * metadata store — writes the token into the path.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.119.5",
+  "version": "0.120.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,11 +21,6 @@
       "bun": "./src/coverage.ts",
       "default": "./dist/coverage.js"
     },
-    "./next": {
-      "types": "./dist/next.d.ts",
-      "bun": "./src/next.ts",
-      "default": "./dist/next.js"
-    },
     "./browser": {
       "types": "./dist/browser.d.ts",
       "bun": "./src/browser.ts",