@specific.dev/spectest 0.131.12 → 0.131.14

package/src/components/electron.ts

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 import { existsSync, readFileSync } from "node:fs";
 import { posix } from "node:path";
 import type { ServiceDefinition } from "../index.js";
@@ -131,7 +132,7 @@ export function electron(options: ElectronOptions = {}) {
       type: "dockerfile",
       context,
       exclude: ["node_modules", "**/node_modules", "out", "test-results", ".data"],
-      content: `FROM node:${node}
+      content: `FROM ${options.nodeVersion === undefined ? BUILTIN_IMAGES["node:24-bookworm-slim"] : `node:${node}`}
 RUN apt-get update && apt-get install -y --no-install-recommends xvfb xauth libgtk-3-0 libnss3 libgbm1 libasound2 fonts-liberation ca-certificates && rm -rf /var/lib/apt/lists/*
 WORKDIR /app
 COPY . .

package/src/components/email.ts

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 import { rawFetch } from "../harness/raw-fetch.js";
 // `email()` — a real SMTP server as a spectest service. The app under test
 // points its SMTP transport at `<key>:1025` and sends mail exactly as it
@@ -29,7 +30,7 @@ import {
 import { wrap } from "../inspect.js";
 import type { Wrapped } from "../inspect.js";
 
-const DEFAULT_IMAGE = "axllent/mailpit:v1.30";
+const DEFAULT_IMAGE = BUILTIN_IMAGES["axllent/mailpit:v1.30"];
 const SMTP_PORT = 1025;
 const API_PORT = 8025;
 

package/src/components/emulate/service.ts

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../../harness/builtin-images.js";
 // Shared runtime behind the third-party provider components — `google()`,
 // `github()`, `apple()`, `microsoft()`, `okta()`.
 //
@@ -53,7 +54,7 @@ import type { ServiceDefinition } from "../../index.js";
 import { certificate, provides, proxy, SELF_SERVICE_TOKEN } from "../../index.js";
 
 /** Base image, pinned. Bun runs the emulators' ESM directly. */
-const IMAGE_BASE = "oven/bun:1.3.14-alpine";
+const IMAGE_BASE = BUILTIN_IMAGES["oven/bun:1.3.14-alpine"];
 /** Emulator package version, pinned rather than floated. */
 const EMULATE_VERSION = "0.9.0";
 /** The port the provider is served on. Callers reach it through the

package/src/components/expo.test.ts

@@ -175,9 +175,9 @@ describe("expo() Node version", () => {
     expect(dockerfile(expo())).toContain("FROM node:20-bookworm-slim");
   });
 
-  test("builds on 22 when the app declares nothing readable", () => {
+  test("pins the default Node image when the app declares nothing readable", () => {
     app({ "package.json": pkg(), ".nvmrc": "lts/iron\n" });
-    expect(dockerfile(expo())).toContain("FROM node:22-bookworm-slim");
+    expect(dockerfile(expo()).split("\n")[0]).toMatch(/^FROM node:22-bookworm-slim@sha256:[a-f0-9]{64}$/);
   });
 
   test("the option wins", () => {

package/src/components/expo.ts

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 // `expo()` — a ready-to-use service for an Expo / React Native app rendered
 // to the web, built for `ctx.mobile(...)`.
 //
@@ -420,13 +421,13 @@ function publicEnvLines(env: Record<string, string>): string[] {
  * BuildKit, which every builder in a VM is.
  */
 function generateDockerfile(input: {
-  nodeVersion: string;
+  nodeImage: string;
   plan: InstallPlan;
   publicEnv: string[];
   outputDir: string;
 }): string {
-  const { nodeVersion, plan, publicEnv, outputDir } = input;
-  const lines = [`FROM node:${nodeVersion}`, "WORKDIR /app", "ENV CI=1", ...plan.env];
+  const { nodeImage, plan, publicEnv, outputDir } = input;
+  const lines = [`FROM ${nodeImage}`, "WORKDIR /app", "ENV CI=1", ...plan.env];
   for (const step of plan.bootstrap) lines.push(`RUN ${step}`);
   lines.push(`COPY ${plan.manifests.join(" ")} ./`);
   lines.push(`RUN --mount=type=cache,target=${plan.cacheDir},sharing=locked ${plan.install}`);
@@ -522,7 +523,7 @@ export function expo(opts: ExpoOptions = {}) {
     image = {
       type: "dockerfile",
       content: generateDockerfile({
-        nodeVersion: node.tag,
+        nodeImage: node.source === "the default" ? BUILTIN_IMAGES["node:22-bookworm-slim"] : `node:${node.tag}`,
         plan,
         publicEnv: publicEnvLines(opts.env ?? {}),
         outputDir,

package/src/components/image-pins.test.ts

@@ -0,0 +1,44 @@
+import { expect, test } from "bun:test";
+import { defineEnvironment } from "../index.js";
+import { postgres, email, aws, k3s, supabase, temporal, google } from "./index.js";
+import { ANDROID_TOOLS_DOCKERFILE } from "./android.js";
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
+import { REGISTRY_IMAGE } from "../harness/registry-seed.js";
+
+const credentials = { database: "app", user: "app", password: "app" };
+const digest = /@sha256:[a-f0-9]{64}$/;
+
+test("SDK-owned component images and generated base images are immutable", () => {
+  const environment = defineEnvironment({ name: "pins", services: {
+    db: postgres(credentials), mail: email(), cloud: aws(), cluster: k3s({ nodes: 3 }),
+    supabase: supabase().group, temporal: temporal({ tls: { hostname: "temporal.test" } }).group,
+    identity: google(),
+  } });
+  for (const [name, service] of Object.entries(environment.config.services)) {
+    const image = service.image;
+    if (image.type === "registry") expect(image.reference, name).toMatch(digest);
+    else if ("content" in image) {
+      for (const line of image.content!.split("\n").filter(line => /^FROM /i.test(line))) {
+        expect(line.split(/\s+/)[1], name).toMatch(digest);
+      }
+    }
+  }
+  expect(ANDROID_TOOLS_DOCKERFILE.split("\n")[0]!.slice(5)).toMatch(digest);
+  expect(REGISTRY_IMAGE).toMatch(digest);
+  for (const [tag, reference] of Object.entries(BUILTIN_IMAGES)) {
+    expect(reference.startsWith(`${tag}@`)).toBe(true);
+    expect(reference).toMatch(digest);
+  }
+});
+
+test("explicit user image and version overrides remain unchanged", () => {
+  expect(postgres({ ...credentials, version: "17-alpine" }).image).toMatchObject({ reference: "postgres:17-alpine" });
+  expect(postgres({ ...credentials, version: "17", image: "custom/db:latest" }).image).toMatchObject({ reference: "custom/db:latest" });
+  expect(email({ image: "custom/mail:latest" }).image).toMatchObject({ reference: "custom/mail:latest" });
+  const env = defineEnvironment({ name: "overrides", services: {
+    cluster: k3s({ version: "v1.33.6-k3s1" }),
+    temporal: temporal({ image: "custom/temporal:latest" }).group,
+  } });
+  expect(env.config.services.cluster.image).toMatchObject({ reference: "rancher/k3s:v1.33.6-k3s1" });
+  expect(env.config.services.temporal.image).toMatchObject({ reference: "custom/temporal:latest" });
+});

package/src/components/k3s.ts

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 import { isIP } from "node:net";
 import { waitForK3sNodes } from "./k3s-nodes.js";
 import { JOIN_DIRECTORY, prepareK3sJoin } from "./k3s-join.js";
@@ -996,7 +997,7 @@ function withTagging<T extends object>(api: T): Tagged<T> {
  * `registries.yaml`, then captured into the warm-template snapshot so
  * warm starts never pull.
  */
-const TRAEFIK_IMAGE = "rancher/mirrored-library-traefik:3.3.2";
+const TRAEFIK_IMAGE = BUILTIN_IMAGES["rancher/mirrored-library-traefik:3.3.2"];
 
 /**
  * Names of the in-cluster resources that carry the CA-signed default
@@ -1247,7 +1248,7 @@ spec:
       - operator: Exists
       containers:
       - name: registry
-        image: ${seeded ? REGISTRY_IMAGE : "registry:2"}
+        image: ${REGISTRY_IMAGE}
         imagePullPolicy: IfNotPresent
         env:
         - name: REGISTRY_HTTP_ADDR
@@ -2111,7 +2112,7 @@ function createK3sCluster(opts: K3sOptions, count: number) {
     // checked all Nodes and finished loading images, not at API readiness.
     const readyCmd = "kubectl get --raw=/readyz >/dev/null 2>&1";
     const def = {
-      image: { type: "registry", reference: `rancher/k3s:${version}` },
+      image: { type: "registry", reference: opts.version === undefined ? BUILTIN_IMAGES["rancher/k3s:v1.33.5-k3s1"] : `rancher/k3s:${version}` },
       imageBuilds: server ? images.builds : [],
       tls: server && registryHost ? [{ hostname: registryHost, port: K3S_REGISTRY_PORT }] : [],
       command: cmd,
@@ -2215,7 +2216,7 @@ function createK3sCluster(opts: K3sOptions, count: number) {
           for (;;) {
             try {
               const pod = (await helpers.client.core.createNamespacedPod({ namespace: "default", dryRun: "All", body: {
-                metadata: { generateName: "spectest-trust-probe-" }, spec: { containers: [{ name: "probe", image: "registry.k8s.io/pause:3.10" }] },
+                metadata: { generateName: "spectest-trust-probe-" }, spec: { containers: [{ name: "probe", image: BUILTIN_IMAGES["registry.k8s.io/pause:3.10"] }] },
               } })).unwrap();
               if (pod.spec?.containers[0].env?.some(e => e.name === "SSL_CERT_FILE" && e.value === "/spectest/ca-bundle.crt")) break;
               if (Date.now() >= deadline) throw new Error(`k3s(${name}): Pod CA mounts did not become ready`);

package/src/components/postgres.ts

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 import type { ServiceDefinition, ServiceSetupContext } from "../index.js";
 import { SQL, type SqlClient } from "../sql.js";
 import { postgresTls } from "./postgres-tls.js";
@@ -97,8 +98,8 @@ export interface PostgresHelpers {
  * ```
  */
 export function postgres(opts: PostgresOptions) {
-  const version = opts.version ?? "18-alpine";
-  const reference = opts.image ?? `postgres:${version}`;
+  const reference = opts.image ?? (opts.version === undefined
+    ? BUILTIN_IMAGES["postgres:18-alpine"] : `postgres:${opts.version}`);
   const port = opts.port ?? 5432;
   const persistent = opts.persistent ?? true;
   const tls = opts.tls !== false ? postgresTls() : undefined;

package/src/components/supabase-pooler.ts

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 import type { ServiceDefinition } from "../index.js";
 
 /** Supabase CLI's [db.pooler] settings. Ports are local to the pooler container. */
@@ -83,7 +84,7 @@ export function supabasePoolerService(opts: {
   const { config, dbHost, tenantId, password, jwtSecret, tls, url } = opts;
   const quotedUrl = `'${url.replace(/'/g, "'\\''")}'`;
   return {
-    image: { type: "registry", reference: "supabase/supavisor:2.9.12" },
+    image: { type: "registry", reference: BUILTIN_IMAGES["supabase/supavisor:2.9.12"] },
     // eval starts the OTP application too. Give that temporary instance
     // ephemeral SQL ports so readiness only sees the final server process.
     command: '/app/bin/migrate && PROXY_PORT_SESSION=0 PROXY_PORT_TRANSACTION=0 /app/bin/supavisor eval "$(cat /etc/pooler/pooler.exs)" && exec /app/bin/server',

package/src/components/supabase.ts

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 import { rawFetch } from "../harness/raw-fetch.js";
 // A ready-to-use, self-hosted **Supabase** stack, expressed as a set of
 // spectest services (one container each) wired together on spectest-net.
@@ -88,22 +89,22 @@ import {
 export type { MailTemplateId, MailTemplateSpec } from "./supabase-config.js";
 
 // ──────────────────────────────────────────────────────────────────────────
-// Pinned upstream image tags (github.com/supabase/supabase docker-compose.yml,
-// current master). Bump together; each is pulled through the host Hub mirror on
+// Digest-pinned upstream images. Update BUILTIN_IMAGES together for compatible
+// Supabase releases; each is pulled through the host Hub mirror on
 // first cold boot and captured into the warm-template snapshot thereafter.
 // ──────────────────────────────────────────────────────────────────────────
 const IMAGES = {
-  db: "supabase/postgres:17.6.1.136",
-  kong: "kong/kong:3.9.1",
-  auth: "supabase/gotrue:v2.189.0",
-  rest: "postgrest/postgrest:v14.12",
-  realtime: "supabase/realtime:v2.102.3",
-  storage: "supabase/storage-api:v1.60.4",
-  imgproxy: "darthsim/imgproxy:v3.30.1",
-  functions: "supabase/edge-runtime:v1.74.0",
+  db: BUILTIN_IMAGES["supabase/postgres:17.6.1.136"],
+  kong: BUILTIN_IMAGES["kong/kong:3.9.1"],
+  auth: BUILTIN_IMAGES["supabase/gotrue:v2.189.0"],
+  rest: BUILTIN_IMAGES["postgrest/postgrest:v14.12"],
+  realtime: BUILTIN_IMAGES["supabase/realtime:v2.102.3"],
+  storage: BUILTIN_IMAGES["supabase/storage-api:v1.60.4"],
+  imgproxy: BUILTIN_IMAGES["darthsim/imgproxy:v3.30.1"],
+  functions: BUILTIN_IMAGES["supabase/edge-runtime:v1.74.0"],
   // Serves custom mail templates to GoTrue over HTTP (see the `templates`
   // part). Tiny, and only pulled by a stack that configures a template.
-  templates: "busybox:1.37",
+  templates: BUILTIN_IMAGES["busybox:1.37"],
 } as const;
 
 /** Override tables without mutating the parsed project config. */

package/src/components/temporal.ts

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 import { serviceGroup, type ServiceDefinition, type ServicesMap } from "../index.js";
 import { rawFetch } from "../harness/raw-fetch.js";
 import { readRaw } from "../inspect.js";
@@ -167,13 +168,13 @@ export function temporal(opts: TemporalOptions = {}) {
     primary, expectKey: name,
     services: (): ServicesMap => {
       const server: ServiceDefinition = {
-        image: { type: "registry", reference: opts.image ?? "temporalio/temporal:1.9.1" }, args,
+        image: { type: "registry", reference: opts.image ?? BUILTIN_IMAGES["temporalio/temporal:1.9.1"] }, args,
         ports: [port, httpPort, ...(opts.ui ? [8233] : [])],
         readyCheck: { type: "http", port: httpPort, path: `/api/v1/namespaces/${encodeURIComponent(namespace)}`, timeoutSecs: 30 },
       };
       if (!opts.tls) return { server };
       return { server, tls: {
-        image: { type: "registry", reference: "nginx:1.29.6-alpine" },
+        image: { type: "registry", reference: BUILTIN_IMAGES["nginx:1.29.6-alpine"] },
         ports: [port], hostnames: [opts.tls.hostname], dependsOn: [serverName],
         certificates: [{ hostnames: [opts.tls.hostname], certPath: "/tls/server.crt", keyPath: "/tls/server.key" }],
         files: [{ path: "/etc/nginx/nginx.conf", content: `worker_processes 1;\nevents { worker_connections 1024; }\nstream { server { listen ${port} ssl; ssl_certificate /tls/server.crt; ssl_certificate_key /tls/server.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_alpn h2; proxy_pass ${serverName}:${port}; } }\n` }],

package/src/daemon.ts

@@ -4,7 +4,8 @@ import { collectSecretRefs } from "./fake-upstream.js";
 import { phoneScope, phoneRecordingChunk, releasePhoneRecording, type PhoneRecording } from "./phone.js";
 import { runWithBackgroundFailures } from "./harness/background-failures.js";
 import { generateHostCert as mintHostCert } from "./harness/certificate.js";
-import { componentBuildTasks, COMPONENT_RUNTIME } from "./harness/component-images.js";
+import { containerdImageOutput } from "./harness/built-image.js";
+import { componentBuildTasks, COMPONENT_RUNTIME, isComponentImageTask, isDigestReference } from "./harness/component-images.js";
 import { waitForAll } from "./harness/concurrency.js";
 import { updateServiceProgress, serviceProgressSnapshot, type ServiceProgress } from "./harness/service-progress.js";
 import { androidScope, androidRecordingChunk, releaseAndroidRecording, isAndroidApp, type AndroidRecording } from "./android.js";
@@ -748,22 +749,18 @@ function ensureLocalBuildkitd(): Promise<boolean> {
   return _localBuilder;
 }
 
-/**
- * A reference as containerd names it. buildx's `-t` on a remote builder
- * stores an unqualified name (`probe:bx`) that dockerd then cannot
- * resolve (measured, CONTAINER_STORE.md), so the in-VM build names its
- * output in full.
- */
-function qualifyImageRef(ref: string): string {
-  const slash = ref.indexOf("/");
-  const first = slash < 0 ? "" : ref.slice(0, slash);
-  const isRegistry = first.includes(".") || first.includes(":") || first === "localhost";
-  if (slash < 0) return `docker.io/library/${ref}`;
-  if (!isRegistry) return `docker.io/${ref}`;
-  return ref;
+/** `true` when a digest-pinned reference is already complete in the store. */
+async function imagePresentByDigest(ref: string): Promise<boolean> {
+  if (!isDigestReference(ref)) return false;
+  // `inspect` succeeds only when every layer of the image for this
+  // platform is in the store; a partial or missing image falls through to
+  // the ordinary pull, which fetches what is absent. dockerd's containerd
+  // store also unpacks on demand at container creation, so a record whose
+  // snapshots were reclaimed is repaired there rather than failing.
+  const present = await docker(["image", "inspect", "--format", "{{.Id}}", ref], 30_000);
+  return present.code === 0;
 }
 
-
 /** Host directory backing one volume mount. Rules (notably which volumes
  *  survive the delta-restore teardown) live in `harness/volume-paths.ts`. */
 function resolveHostPath(service: string, vol: VolumeMount): string {
@@ -1229,6 +1226,18 @@ async function prepareServiceImageInner(
     // tags (`foo:latest`) at whatever the previous generation pulled, for
     // as long as the delta chain lives — a silent semantic divergence
     // from the cold build a delta restore must be equivalent to.
+    //
+    // The one reference that cannot float is a digest. `name@sha256:…`
+    // names exactly one image for as long as it exists, so a copy already
+    // in the store is the image the registry would return, and the
+    // round-trip buys nothing: skip it. Component images pinned by digest
+    // and user references pinned by digest take this path; a tag never does.
+    if (await imagePresentByDigest(ref)) {
+      progressService(svc.name, { status: "pulling", detail: `present by digest` });
+      const tagged = await docker(["tag", ref, tag], 30_000);
+      if (tagged.code !== 0) throw new Error(`docker tag ${ref} ${tag} failed: ${tagged.stderr.trim()}`);
+      return { tag };
+    }
     progressService(svc.name, { status: "pulling", detail: `pulling ${ref}` });
     let layers = 0;
     const pull = await shxStream("docker", ["pull", ref], 900_000, undefined, (line) => {
@@ -1379,11 +1388,34 @@ async function runServiceBuild(
       // every cached parent before the first uncached step (11–79 s for
       // one `COPY` on Specific's dashboard) and a second full pass to
       // export after every miss.
+      // Keep an immutable image reference as well as the service tag. The
+      // containerd exporter replaces the tag directly, bypassing Docker's
+      // dangling-image retention. Old versions must remain usable until our
+      // image GC decides they are no longer needed (including by nested stores).
+      //
+      // `compression=uncompressed` (`containerdImageOutput`): the image never leaves this store, so
+      // gzip on export only to gunzip on unpack is pure cost — on Listen,
+      // 64 s compressing a 2.7 GB layer and 56 s decompressing it again,
+      // single-threaded, in the same guest that already held the layer as
+      // a build snapshot (CONTAINER_STORE.md, "Image delivery inside the
+      // guest"). With the default `force-compression=false` this applies
+      // to layers this build creates; a pulled base image's gzip blobs are
+      // reused as they are, so no existing layer is re-encoded or
+      // re-unpacked. The uncompressed blob is a second on-disk copy of the
+      // layer; the sticky headroom logic already budgets for blobs.
+      //
+      // `unpack`: dockerd needs the snapshot chain to start a container,
+      // so a service image is unpacked here rather than at `docker run`.
+      // A component image task (a `k3s()` build) is consumed only through
+      // the content store — `k3s-image-loader.ts` serves its blobs and the
+      // cluster's containerd unpacks them into its own store — so unpacking
+      // it in dockerd's store would be a third copy nobody reads.
+      const unpack = !isComponentImageTask(name);
       buildArgs = [
         "buildx", "build",
         "--builder", LOCAL_BUILDER_NAME,
         "--progress=plain",
-        "--output", `type=image,name=${qualifyImageRef(tag)},unpack=true`,
+        "--output", containerdImageOutput(tag, { unpack }),
         ...argFlags,
         "-f", dfPath, contextDir,
       ];

package/src/harness/built-image-docker.test.ts

@@ -0,0 +1,62 @@
+// SPECTEST_TEST_STICKY_DOCKER=1 bun test sdk/src/harness/built-image-docker.test.ts
+// Requires local Docker's containerd store at /run/containerd/containerd.sock.
+import { expect, test } from "bun:test";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { containerdImageOutput } from "./built-image";
+
+async function run(args: string[]) {
+  const process = Bun.spawn(args, { stdout: "pipe", stderr: "pipe" });
+  const [code, stdout, stderr] = await Promise.all([process.exited,
+    new Response(process.stdout).text(), new Response(process.stderr).text()]);
+  if (code) throw new Error(`${args.slice(0, 4).join(" ")}: ${stderr}`);
+  return stdout.trim();
+}
+
+test.skipIf(!process.env.SPECTEST_TEST_STICKY_DOCKER)("containerd rebuild retains old images until explicit image GC", async () => {
+  const root = await mkdtemp(join(tmpdir(), "sticky-export-"));
+  const builder = `sticky-export-${crypto.randomUUID()}`;
+  const consumer = `${builder}-consumer`;
+  const tag = `docker.io/spectest/${builder}:latest`;
+  const images = new Set<string>();
+  try {
+    await writeFile(`${root}/Dockerfile`, 'FROM scratch\nCOPY payload /payload\nCMD ["/payload"]\n');
+    await run(["docker", "run", "-d", "--privileged", "--name", builder,
+      "-v", "/run/containerd/containerd.sock:/run/containerd/containerd.sock",
+      "-v", "/var/lib/containerd:/var/lib/containerd", "-v", `${root}:/context:ro`,
+      "moby/buildkit:v0.32.2", "--oci-worker=false", "--containerd-worker=true",
+      "--containerd-worker-namespace=moby", "--containerd-worker-gc=false"]);
+    for (let attempt = 0; ; attempt++) {
+      try { await run(["docker", "exec", builder, "buildctl", "debug", "workers"]); break; }
+      catch (error) { if (attempt === 40) throw error; await Bun.sleep(250); }
+    }
+    async function build(payload: string, output = containerdImageOutput(tag)) {
+      await writeFile(`${root}/payload`, `${builder}-${payload}`);
+      await run(["docker", "exec", builder, "buildctl", "build", "--frontend", "dockerfile.v0",
+        "--local", "context=/context", "--local", "dockerfile=/context", "--output", output]);
+      const id = await run(["docker", "image", "inspect", "--format", "{{.Id}}", tag]);
+      images.add(id);
+      return id;
+    }
+    const first = await build("first");
+    const second = await build("second");
+    expect(second).not.toBe(first);
+    expect(await run(["docker", "image", "inspect", "--format", "{{.Id}}", first])).toBe(first);
+    await run(["docker", "create", "--name", consumer, first]);
+    await run(["docker", "rm", consumer]);
+    // The normal retention collector removes by image ID, including aliases.
+    await run(["docker", "image", "rm", "-f", first]);
+    await expect(run(["docker", "image", "inspect", first])).rejects.toThrow("No such image");
+    expect(await run(["docker", "image", "inspect", "--format", "{{.Id}}", tag])).toBe(second);
+    // Negative control: the old export mode reproduces Tangent's failure.
+    const unpinned = await build("unpinned", `type=image,name=${tag},unpack=true`);
+    await build("replacement");
+    await expect(run(["docker", "image", "inspect", unpinned])).rejects.toThrow("No such image");
+  } finally {
+    await run(["docker", "rm", "-f", consumer]).catch(() => {});
+    await run(["docker", "rm", "-fv", builder]).catch(() => {});
+    for (const id of images) await run(["docker", "image", "rm", "-f", id]).catch(() => {});
+    await rm(root, { recursive: true, force: true });
+  }
+}, 120_000);

package/src/harness/built-image.ts

@@ -4,6 +4,20 @@ import { createHash } from "node:crypto";
 import { promisify } from "node:util";
 import { canonicalImageReference } from "./component-images.js";
 
+/** Containerd exports replace mutable tags without Docker's dangling-image
+ * retention. Keep each result addressable until the SDK's image GC evicts it.
+ *
+ * Layers this build creates are stored uncompressed: the image never leaves
+ * the VM's store, so compressing on export only to decompress on unpack was
+ * pure cost (64 s + 56 s on Listen's 2.7 GB layer). `force-compression` stays
+ * off, so a pulled base image's blobs are reused as they are. `unpack` is
+ * false for images only a nested store reads (CONTAINER_STORE.md, "Image
+ * delivery inside the guest"). */
+export function containerdImageOutput(reference: string, options: { unpack?: boolean } = {}): string {
+  const unpack = options.unpack ?? true;
+  return `type=image,name=${canonicalImageReference(reference)},name-canonical=true,unpack=${unpack},compression=uncompressed`;
+}
+
 export interface Descriptor { digest: string; size: number; mediaType: string; platform?: { os: string; architecture: string } }
 interface Manifest { schemaVersion: number; mediaType: string; config: Descriptor; layers: Descriptor[]; annotations?: Record<string, string> }
 const digest = (bytes: Uint8Array) => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;

package/src/harness/builtin-images.ts

@@ -0,0 +1,29 @@
+/** SDK-owned upstream inputs, resolved from registry manifests on 2026-11-02.
+ * Pin the multi-platform index, never the workstation's platform manifest.
+ * Update deliberately with an SDK release; user image/version overrides bypass
+ * these defaults. Keep generated Dockerfiles and helper pods here as well.
+ */
+export const BUILTIN_IMAGES = {
+  "postgres:18-alpine": "postgres:18-alpine@sha256:10a5c69a83035ab5239f5620d708520e8b28f5aa1f2b20143e6024532edadfb5",
+  "rancher/k3s:v1.33.5-k3s1": "rancher/k3s:v1.33.5-k3s1@sha256:fd4740667b7033055c27d424d0d2d660bf66cedbdb225d68e0eab6dd48aa0fd2",
+  "rancher/mirrored-library-traefik:3.3.2": "rancher/mirrored-library-traefik:3.3.2@sha256:a03ee2f858f77975fa943f6797da5446b7ac9a83beef6bbdae2afd8feaf67b76",
+  "registry:2.8.3": "registry:2.8.3@sha256:a3d8aaa63ed8681a604f1dea0aa03f100d5895b6a58ace528858a7b332415373",
+  "registry.k8s.io/pause:3.10": "registry.k8s.io/pause:3.10@sha256:ee6521f290b2168b6e0935a181d4cff9be1ac3f505666ef0e3c98fae8199917a",
+  "node:22-bookworm-slim": "node:22-bookworm-slim@sha256:4b150b48b4116e2a22f2c39cc27025fbf4f153e2078fd3b14d159fdb5c7279da",
+  "node:24-bookworm-slim": "node:24-bookworm-slim@sha256:c86ecead9e55a5210ac1727de38a4ca840bf03dcaf34dc9749addbf383b1920c",
+  "oven/bun:1.3.14-alpine": "oven/bun:1.3.14-alpine@sha256:5acc90a93e91ff07bf72aa90a7c9f0fa189765aec90b47bdbf2152d2196383c0",
+  "axllent/mailpit:v1.30": "axllent/mailpit:v1.30@sha256:d5ecbb067db3705fa953d79e1b7f81ef84038df67aba6c52825d8c02a1ea748a",
+  "ministackorg/ministack:1.4.8": "ministackorg/ministack:1.4.8@sha256:eb0a00c897ec91589eb78a77f0afaf13a6d7be99abfeca2d1d719a7ec76d3141",
+  "temporalio/temporal:1.9.1": "temporalio/temporal:1.9.1@sha256:ad4c82c97bd12b417d1ea942610dbcd511afb250c4d5ed26c694009533df447e",
+  "nginx:1.29.6-alpine": "nginx:1.29.6-alpine@sha256:f46cb72c7df02710e693e863a983ac42f6a9579058a59a35f1ae36c9958e4ce0",
+  "supabase/supavisor:2.9.12": "supabase/supavisor:2.9.12@sha256:464b93a60ba8c96bc06dad7f241562d6613b2a994922307717b05f432ae415c2",
+  "supabase/postgres:17.6.1.136": "supabase/postgres:17.6.1.136@sha256:f371b5f3f2ac0a05703f33d6e6134515fb2498cab708fb948a0aeb7481467c00",
+  "kong/kong:3.9.1": "kong/kong:3.9.1@sha256:6addf50e6bd8d578314cb9ce4f2d2d1e3781d2edecef59f707e00c6e05d384f5",
+  "supabase/gotrue:v2.189.0": "supabase/gotrue:v2.189.0@sha256:385184459f57569c54c25209f51f3b2be99ddd7c4ce9e3555b5d3eea8447b7cf",
+  "postgrest/postgrest:v14.12": "postgrest/postgrest:v14.12@sha256:54000f24847d01a2c2302e0041cf0618b875c57fb48507d743cfa9aaa50bf43c",
+  "supabase/realtime:v2.102.3": "supabase/realtime:v2.102.3@sha256:aa1c92c0cf326007563641730ec9da9c60478caa6853887775365fa2c097a471",
+  "supabase/storage-api:v1.60.4": "supabase/storage-api:v1.60.4@sha256:c8eb9858eafec891a97c27125470aaad54703c3f4eb4d55ca7f1bf6c6411febf",
+  "darthsim/imgproxy:v3.30.1": "darthsim/imgproxy:v3.30.1@sha256:3b709e4a0e5e8e0e959b556b7031229202b4b8e7e7d955c517ea7abed68ee34d",
+  "supabase/edge-runtime:v1.74.0": "supabase/edge-runtime:v1.74.0@sha256:2781daf92394db91f7e94129cc3d04ec474ad16a8fe64b3fbeef6e7d557ab120",
+  "busybox:1.37": "busybox:1.37@sha256:a7dbc319b1438115a207e11930dc4bb3e643dcb3ec0bdd694bb36cd8fad289ec",
+} as const;

package/src/harness/component-images.test.ts

@@ -1,5 +1,5 @@
 import { expect, test } from "bun:test";
-import { canonicalImageReference, componentBuildTasks, kubernetesImages } from "./component-images";
+import { canonicalImageReference, componentBuildTasks, isComponentImageTask, isDigestReference, kubernetesImages } from "./component-images";
 import { validateServiceImage, type BuildImage } from "../index";
 
 test("services and Kubernetes share all Dockerfile build options without a type discriminator", () => {
@@ -42,3 +42,21 @@ test("build task identity survives list reordering but is scoped to the owning c
   expect(() => validateServiceImage("app", { content: "FROM scratch", buildArgs: { "bad-key": "x" } })).toThrow("ARG");
   expect(() => validateServiceImage("app", { content: "FROM scratch", exclude: [1] as never })).toThrow("exclude");
 });
+
+test("component image tasks are recognised by name and services are not", () => {
+  const [task] = componentBuildTasks([{ name: "cluster", image: { type: "registry", reference: "rancher/k3s:v1.33.1-k3s1" },
+    imageBuilds: [{ reference: "registry.internal/app:dev", image: { type: "dockerfile", content: "FROM scratch" } }] } as any]);
+  expect(isComponentImageTask(task!.name)).toBe(true);
+  expect(isComponentImageTask("cluster")).toBe(false);
+  expect(isComponentImageTask("spectest-image")).toBe(false);
+});
+
+test("only a full sha256 digest reference is immutable", () => {
+  const digest = "a".repeat(64);
+  expect(isDigestReference(`postgres@sha256:${digest}`)).toBe(true);
+  expect(isDigestReference(`ghcr.io/org/app:1.2@sha256:${digest}`)).toBe(true);
+  expect(isDigestReference("postgres:16.4")).toBe(false);
+  expect(isDigestReference("postgres:latest")).toBe(false);
+  expect(isDigestReference(`postgres@sha256:${digest.slice(1)}`)).toBe(false);
+  expect(isDigestReference(`postgres@sha512:${digest}`)).toBe(false);
+});

package/src/harness/component-images.ts

@@ -26,6 +26,11 @@ export function canonicalImageReference(reference: string): string {
   return result;
 }
 
+/** A `name@sha256:…` reference names one immutable image; a tag can move. */
+export function isDigestReference(reference: string): boolean {
+  return /@sha256:[a-f0-9]{64}$/.test(reference);
+}
+
 export function kubernetesImages(images: readonly KubernetesImage[]): { pulls: string[]; builds: ComponentImageBuild[] } {
   if (!Array.isArray(images)) throw new Error("k3s(): images must be an array of registry references or Dockerfile builds");
   const pulls: string[] = [];
@@ -53,10 +58,19 @@ export function kubernetesImages(images: readonly KubernetesImage[]): { pulls: s
   return { pulls, builds };
 }
 
+/** Prefix of every component image task name; `isComponentImageTask` is the test. */
+export const COMPONENT_IMAGE_TASK_PREFIX = "spectest-image-";
+
+/** A component image task builds for a component's own runtime (today: a
+ * `k3s()` cluster's containerd), never for a container dockerd starts. */
+export function isComponentImageTask(name: string): boolean {
+  return name.startsWith(COMPONENT_IMAGE_TASK_PREFIX);
+}
+
 /** Stable internal task names, separate from the service graph. */
 export function componentBuildTasks<T extends ServiceConfig & { name: string }>(services: readonly T[]) {
   return services.flatMap(svc => (svc.imageBuilds ?? []).map(build => ({
-    name: `spectest-image-${createHash("sha256").update(`${svc.name}\0${build.reference}`).digest("hex")}`,
+    name: `${COMPONENT_IMAGE_TASK_PREFIX}${createHash("sha256").update(`${svc.name}\0${build.reference}`).digest("hex")}`,
     owner: svc.name,
     reference: build.reference,
     image: build.image,

package/src/harness/registry-seed.ts

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "./builtin-images.js";
 /** Distribution v2 publication. Blob data stays in containerd, mounted
  * read-only in the registry. Repository metadata and uploads MUST live on
  * the environment rootfs, outside persistent image/build caches. */
@@ -9,7 +10,7 @@ import { canonicalImageReference, type PreparedComponentImage } from "./componen
 export const REGISTRY_DATA = "/var/lib/spectest-registry";
 export const REGISTRY_CONTENT = "/spectest-registry-content";
 export const CONTENT_BLOBS = "io.containerd.content.v1.content/blobs/sha256";
-export const REGISTRY_IMAGE = "registry:2.8.3";
+export const REGISTRY_IMAGE = BUILTIN_IMAGES["registry:2.8.3"];
 export const registryDirectory = (service: string) => `/var/lib/spectest-registries/${service}`;
 
 /** Distribution 2.8 registry/storage/paths.go defines this layout. Seed

package/src/harness/sticky-consumer.ts

@@ -104,6 +104,12 @@ disabled_plugins = ["io.containerd.grpc.v1.cri"]
   dockerConfig["data-root"] = `${config.path}/docker`;
   dockerConfig.features = { "containerd-snapshotter": true };
   dockerConfig["storage-driver"] = "overlayfs";
+  // Pull up to ten layers at once instead of dockerd's default three. The
+  // containerd image store honours this since Docker 29.7.0; extraction is
+  // still one layer at a time, so this only moves the download side off
+  // the critical path of many-layer images. Set here as well as in the
+  // golden's daemon.json so an SDK release carries it without a rebuild.
+  dockerConfig["max-concurrent-downloads"] = 10;
   await writeFile(`${STICKY_RUNTIME}/docker.json`, JSON.stringify(dockerConfig));
   await writeFile(`${STICKY_RUNTIME}/buildkit.toml`, stickyBuildkitConfig(config, (await diskUsage(config.path)).reservedBytes));
   const start = async (unit: string, program: string, args: string[]) => {

package/src/harness/sticky-kubernetes.test.ts

@@ -18,6 +18,7 @@ async function store(root: string, service: string, age = 0) {
 function runner(calls: string[][]): CacheCommand {
   return async (program, args) => {
     calls.push([program, ...args]);
+    if (program === "docker" && args.join(" ") === "image ls -aq --no-trunc") return image;
     if (program === "docker" && args[0] === "inspect") return JSON.stringify({ ExitCode: 0, OOMKilled: false });
     return "";
   };
@@ -86,3 +87,25 @@ test("unclean nested containerd shutdown rejects sealing instead of publishing i
   await expect(cache.close()).rejects.toThrow("Kubernetes cache shutdown failed");
   expect(calls.some(c => c[0] === "rm")).toBe(false);
 });
+
+test("orphaned legacy stores are discarded while healthy stores are maintained", async () => {
+  const root = await temporary();
+  const orphan = await store(root, "old");
+  await writeFile(`${orphan}/store.json`, JSON.stringify({ schema: 1, image: `sha256:${"b".repeat(64)}`, updatedAt: Date.now() }));
+  await store(root, "healthy");
+  const calls: string[][] = [];
+  const cache = await openKubernetesCacheMaintenance(runner(calls), root);
+  expect(calls).toContainEqual(["rm", "-rf", orphan]);
+  expect(calls.filter(c => c[1] === "run")).toHaveLength(1);
+  await cache.close();
+});
+
+test("inventory failure never discards stores", async () => {
+  const root = await temporary(); await store(root, "cluster");
+  const calls: string[][] = [];
+  await expect(openKubernetesCacheMaintenance(async (program, args) => {
+    calls.push([program, ...args]);
+    throw new Error("Docker unavailable");
+  }, root)).rejects.toThrow("Docker unavailable");
+  expect(calls.some(c => c[0] === "rm")).toBe(false);
+});