@specific.dev/spectest 0.119.5 → 0.120.0

package/src/components/k3s.ts

@@ -40,13 +40,6 @@ import type {
   SpectestContext,
 } from "../index.js";
 import { dnsName, provides, SELF_SERVICE_TOKEN } from "../index.js";
-import {
-  MKFS_EROFS_PATH,
-  STORE_ADOPT_PATH,
-  imageCachePathsSync,
-  nestedStoreDir,
-  type ImageCachePaths,
-} 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";
@@ -88,10 +81,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;
   /**
@@ -197,15 +187,8 @@ 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.
@@ -223,78 +206,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.
@@ -314,39 +225,9 @@ const SWEEP_DISABLED_PLUGINS = [
 
 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(): string {
-  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
@@ -355,26 +236,11 @@ function erofsConfigToml(): string {
  * 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: ImageCachePaths | null): string {
-  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() { :; }; `;
+function storePrepareSh(): string {
+  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}; L=${cache ? cache.layers : "/nonexistent"}; ` +
-    detect +
+    `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 ` +
@@ -393,16 +259,15 @@ function storePrepareSh(cache: ImageCachePaths | null): string {
     // 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)"; ` +
@@ -2084,12 +1949,6 @@ async function collectDiagnostics(
  * 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";
 
@@ -2119,12 +1978,9 @@ export function k3s(opts: K3sOptions = {}) {
   // 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",
@@ -2207,9 +2063,8 @@ export function k3s(opts: K3sOptions = {}) {
     // 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
@@ -2239,21 +2094,8 @@ export function k3s(opts: K3sOptions = {}) {
     // 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 }]),
       ...(publishBuilds.length ? [
         { source: registryDirectory(SELF_SERVICE_TOKEN), target: REGISTRY_DATA },
@@ -2262,12 +2104,6 @@ export function k3s(opts: K3sOptions = {}) {
     ],
     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" as const,

package/src/coverage-next.test.ts

@@ -1,7 +1,6 @@
 import { describe, test, expect } from "bun:test";
 import { next, NEXT_COVERAGE_HELPER, NEXT_COVERAGE_HELPER_PATH, type NextBuildMetadata } from "./coverage-next.js";
 import { applyCoverageAdapters, resolveCoverageSourceOptions, attachCoverageSourceOptions, node, browser, type CoverageSourceContext } from "./coverage.js";
-import { withCoverage } from "./next.js";
 import { applyCoverageDelta, encodeCoverageBundle } from "./harness/coverage.js";
 import { gunzipSync } from "node:zlib";
 import { promises as fs } from "node:fs";
@@ -64,49 +63,6 @@ describe("Next adapter", () => {
     expect(()=>attachCoverageSourceOptions({reports:[{name:"browser.lcov"}]},duplicate)).toThrow(/multiple adapters/);
     expect(JSON.parse(JSON.stringify(applyCoverageAdapters("web",{image,coverage:{adapters}}))).coverage.adapters[1].sourceOptions.sourceRoot).toBe("client");
   });
-  test("build helper preserves user settings and includes standalone maps", () => {
-    const c=withCoverage({output:"standalone",distDir:"build",experimental:{cpus:2},outputFileTracingIncludes:{"/*":["./assets/*"],"/api/*":["./data/*"]}}) as any;
-    expect(c.experimental).toEqual({cpus:2,serverSourceMaps:true});
-    expect(c.productionBrowserSourceMaps).toBe(true);
-    expect(c.outputFileTracingIncludes).toEqual({"/*":["./assets/*"],"/api/*":["./data/*"],"/**":["./build/server/**/*.map"]});
-  });
-  test("Webpack helper preserves hooks and disables dependency maps only", () => {
-    let called = false;
-    const config = withCoverage({ webpack(c: any) { called = true; return {...c, marker: true}; } });
-    const compiled = config.webpack({plugins: []});
-    expect(called).toBe(true);
-    expect(compiled.marker).toBe(true);
-    let loaderHook: (loader: any, module: any) => void;
-    compiled.plugins[0].apply({
-      hooks: {compilation: {tap(_name: string, f: Function) { f({}); }}},
-      webpack: {NormalModule: {getCompilationHooks() { return {
-        loader: {tap(_name: string, f: typeof loaderHook) { loaderHook = f; }},
-      }; }}},
-    });
-    for (const resource of ["/app/app/page.tsx", "/workspace/shared/index.ts", ""]) {
-      const loader = {sourceMap: true};
-      loaderHook!(loader, {resource});
-      expect(loader.sourceMap).toBe(true);
-    }
-    const dependency = {sourceMap: true};
-    loaderHook!(dependency, {resource: "/app/node_modules/next/dist/client/router.js"});
-    expect(dependency.sourceMap).toBe(false);
-  });
-  test("build hook retains traced maps and composes an existing compiler hook", async () => {
-    const dir=await fs.mkdtemp(path.join(os.tmpdir(),"next-trace-"));
-    try {
-      let called=false;
-      const config=withCoverage({compiler:{runAfterProductionCompile:async()=>{
-        called=true;
-        await fs.writeFile(path.join(dir,"page.js.map"),"{}");
-        await fs.writeFile(path.join(dir,"chunk.js.map"),"{}");
-        await fs.writeFile(path.join(dir,"page.js.nft.json"),JSON.stringify({version:1,files:["chunk.js","missing.js"]}));
-      }}});
-      await (config.compiler.runAfterProductionCompile as any)({projectDir:dir,distDir:dir});
-      expect(called).toBe(true);
-      expect(JSON.parse(await fs.readFile(path.join(dir,"page.js.nft.json"),"utf8")).files).toEqual(["chunk.js","missing.js","page.js.map","chunk.js.map"]);
-    } finally {await fs.rm(dir,{recursive:true,force:true});}
-  });
   test("runtime probe distinguishes generated launcher from authored custom server and checks maps", async () => {
     const dir=await fs.mkdtemp(path.join(os.tmpdir(),"next-cov-"));
     const helper=path.join(dir,"helper.cjs");

package/src/coverage-next.ts

@@ -52,7 +52,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; }
 }
@@ -75,7 +75,8 @@ const GENERATED_SOURCES = [
 ];
 
 /** 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: NextCoverageOptions = {}): CoverageAdapter {
   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 === ".."))) throw new Error("coverage.next sourceRoot must be repository-relative (use \".\" for the repository root)");

package/src/daemon.ts

@@ -169,16 +169,6 @@ import { startHttp2Proxy } from "./harness/http2-proxy.js";
 import { startTlsTerminator, type TlsTerminator } 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,
-  type ImageCachePaths,
-  type OciIndex,
-} from "./harness/image-cache.js";
 import {
   assertAbsolute,
   certificateHostnames,
@@ -741,171 +731,20 @@ async function hasBuildx(): Promise<boolean> {
   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(): Promise<ImageCachePaths | null> {
-  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: Promise<boolean> | undefined;
-/**
- * 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(): Promise<boolean> {
-  _localBuilder ??= bringUpLocalBuildkitd();
-  return _localBuilder;
-}
-
-async function bringUpLocalBuildkitd(): Promise<boolean> {
-  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;
+  })();
+  return _localBuilder;
 }
 
-/**
- * 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: ImageCachePaths): Promise<string | null> {
-  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: string): OciIndex | null =>
-      existsSync(`${dir}/index.json`) ? (JSON.parse(readFileSync(`${dir}/index.json`, "utf8")) as OciIndex) : 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;
-}
 /**
  * A reference as containerd names it. buildx's `-t` on a remote builder
  * stores an unqualified name (`probe:bx`) that dockerd then cannot
@@ -986,7 +825,7 @@ async function ensureVolumes(svc: NamedService): Promise<string[]> {
       // 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);
       }
@@ -3278,7 +3117,7 @@ async function bootstrapInner(prepared?: PreparedImages, identity?: string): Pro
   // 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/src/harness/buildkit-progress.ts

@@ -80,7 +80,7 @@ export 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/src/harness/container-run.ts

@@ -82,7 +82,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/src/harness/volume-paths.ts

@@ -63,7 +63,7 @@ export 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.
  *