@specific.dev/spectest 0.131.12 → 0.131.13

package/dist/components/android.js

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 import { readFileSync } from "node:fs";
 import { posix } from "node:path";
 import { serviceGroup } from "../index.js";
@@ -21,7 +22,7 @@ a = 'scrcpy_print_version(void) {'
 assert s.count(a) == 1
 p.write_text(s.replace(a, a + '\n    puts("spectest-first-frame-v1");'))`;
 const shellQuote = (value) => "'" + value.replaceAll("'", "'\\''") + "'";
-export const ANDROID_TOOLS_DOCKERFILE = `FROM node:22-bookworm-slim
+export const ANDROID_TOOLS_DOCKERFILE = `FROM ${BUILTIN_IMAGES["node:22-bookworm-slim"]}
 RUN apt-get update && apt-get install -y --no-install-recommends adb aapt apksigner zipalign ffmpeg default-jdk-headless ca-certificates openssl curl gcc python3 pkg-config meson ninja-build libsdl2-dev libavcodec-dev libavdevice-dev libavformat-dev libavutil-dev libswresample-dev libusb-1.0-0-dev && rm -rf /var/lib/apt/lists/*
 RUN curl -fL https://github.com/Genymobile/scrcpy/archive/refs/tags/v3.3.1.tar.gz | tar xz -C /tmp && curl -fL https://github.com/Genymobile/scrcpy/releases/download/v3.3.1/scrcpy-server-v3.3.1 -o /tmp/scrcpy-server && python3 -c ${shellQuote(recorderPatch.replaceAll("\n", ";"))} && meson setup /tmp/scrcpy-build /tmp/scrcpy-3.3.1 --buildtype=release -Dprebuilt_server=/tmp/scrcpy-server && ninja -C /tmp/scrcpy-build -j4 install && rm -rf /tmp/scrcpy*
 ENV ANDROID_HOME=/opt/android JAVA_HOME=/usr/lib/jvm/default-java APPIUM_HOME=/opt/appium

package/dist/components/aws.d.ts

@@ -105,7 +105,7 @@ export declare function aws(opts?: AwsOptions): {
     inputs?: string[] | undefined;
     image: {
         type: "registry";
-        reference: string;
+        reference: "ministackorg/ministack:1.4.8@sha256:eb0a00c897ec91589eb78a77f0afaf13a6d7be99abfeca2d1d719a7ec76d3141";
     };
     env: {
         AWS_DEFAULT_REGION: string;

package/dist/components/aws.js

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 // `aws()` — the AWS cloud APIs, emulated inside the environment, answering
 // at their **real** endpoints.
 //
@@ -64,7 +65,7 @@ import { deflateRawSync } from "node:zlib";
 import { certificate, provides, proxy, SELF_SERVICE_TOKEN } from "../index.js";
 import { pauseRecording, resumeRecording } from "../recorder.js";
 /** Backing image, pinned internally (not part of the documented surface). */
-const AWS_IMAGE = "ministackorg/ministack:1.4.8";
+const AWS_IMAGE = BUILTIN_IMAGES["ministackorg/ministack:1.4.8"];
 /** Port the emulator serves every AWS API on. Internal: callers reach the
  *  emulator through the AWS hostnames, never through this port. */
 const AWS_PORT = 4566;

package/dist/components/electron.js

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 import { existsSync, readFileSync } from "node:fs";
 import { posix } from "node:path";
 import { resolveProjectPath } from "../project-files.js";
@@ -104,7 +105,7 @@ export function electron(options = {}) {
             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/dist/components/email.js

@@ -1,7 +1,8 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 import { rawFetch } from "../harness/raw-fetch.js";
 import { recordEmail, reserveEvent, truncateUtf8, } from "../recorder.js";
 import { wrap } 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/dist/components/emulate/service.js

@@ -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()`.
 //
@@ -49,7 +50,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 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/dist/components/expo.js

@@ -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(...)`.
 //
@@ -299,8 +300,8 @@ function publicEnvLines(env) {
  * BuildKit, which every builder in a VM is.
  */
 function generateDockerfile(input) {
-    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(" ")} ./`);
@@ -389,7 +390,7 @@ export function expo(opts = {}) {
         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/dist/components/k3s.js

@@ -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";
@@ -492,7 +493,7 @@ function withTagging(api) {
  * `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
  * ingress certificate (created in `setupK3sCluster` when TLS is enabled).
@@ -730,7 +731,7 @@ spec:
       - operator: Exists
       containers:
       - name: registry
-        image: ${seeded ? REGISTRY_IMAGE : "registry:2"}
+        image: ${REGISTRY_IMAGE}
         imagePullPolicy: IfNotPresent
         env:
         - name: REGISTRY_HTTP_ADDR
@@ -1476,7 +1477,7 @@ function createK3sCluster(opts, count) {
         // 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,
@@ -1588,7 +1589,7 @@ function createK3sCluster(opts, count) {
                     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;

package/dist/components/postgres.js

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 import { SQL } from "../sql.js";
 import { postgresTls } from "./postgres-tls.js";
 /**
@@ -26,8 +27,8 @@ import { postgresTls } from "./postgres-tls.js";
  * ```
  */
 export function postgres(opts) {
-    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/dist/components/supabase-pooler.js

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 export const DEFAULT_POOLER_CONFIG = {
     enabled: false,
     port: 54329,
@@ -64,7 +65,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/dist/components/supabase.js

@@ -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.
@@ -68,22 +69,22 @@ import { supabasePoolerService } from "./supabase-pooler.js";
 import { SUPABASE_COVERAGE_COLLECTOR, supabaseFunctionsCoverage } from "./supabase-coverage.js";
 import { mapSupabaseConfig, parseSupabaseConfigFile, } 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"],
 };
 /** Override tables without mutating the parsed project config. */
 function mergeConfig(base, overrides) {

package/dist/components/temporal.js

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 import { serviceGroup } from "../index.js";
 import { rawFetch } from "../harness/raw-fetch.js";
 import { readRaw } from "../inspect.js";
@@ -164,14 +165,14 @@ export function temporal(opts = {}) {
         primary, expectKey: name,
         services: () => {
             const server = {
-                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/dist/daemon.js

@@ -4,6 +4,7 @@ import { collectSecretRefs } from "./fake-upstream.js";
 import { phoneScope, phoneRecordingChunk, releasePhoneRecording } from "./phone.js";
 import { runWithBackgroundFailures } from "./harness/background-failures.js";
 import { generateHostCert as mintHostCert } from "./harness/certificate.js";
+import { containerdImageOutput } from "./harness/built-image.js";
 import { componentBuildTasks, COMPONENT_RUNTIME } from "./harness/component-images.js";
 import { waitForAll } from "./harness/concurrency.js";
 import { updateServiceProgress, serviceProgressSnapshot } from "./harness/service-progress.js";
@@ -491,22 +492,6 @@ function ensureLocalBuildkitd() {
     })();
     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) {
-    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;
-}
 /** Host directory backing one volume mount. Rules (notably which volumes
  *  survive the delta-restore teardown) live in `harness/volume-paths.ts`. */
 function resolveHostPath(service, vol) {
@@ -1053,11 +1038,15 @@ async function runServiceBuild(name, image, tag) {
             // 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).
             buildArgs = [
                 "buildx", "build",
                 "--builder", LOCAL_BUILDER_NAME,
                 "--progress=plain",
-                "--output", `type=image,name=${qualifyImageRef(tag)},unpack=true`,
+                "--output", containerdImageOutput(tag),
                 ...argFlags,
                 "-f", dfPath, contextDir,
             ];

package/dist/harness/built-image.d.ts

@@ -1,3 +1,6 @@
+/** Containerd exports replace mutable tags without Docker's dangling-image
+ * retention. Keep each result addressable until the SDK's image GC evicts it. */
+export declare function containerdImageOutput(reference: string): string;
 export interface Descriptor {
     digest: string;
     size: number;

package/dist/harness/built-image.js

@@ -3,6 +3,11 @@ import { execFile } from "node:child_process";
 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. */
+export function containerdImageOutput(reference) {
+    return `type=image,name=${canonicalImageReference(reference)},name-canonical=true,unpack=true`;
+}
 const digest = (bytes) => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
 const descriptor = (bytes, mediaType) => ({ digest: digest(bytes), size: bytes.length, mediaType });
 const run = promisify(execFile);

package/dist/harness/builtin-images.d.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 declare const BUILTIN_IMAGES: {
+    readonly "postgres:18-alpine": "postgres:18-alpine@sha256:10a5c69a83035ab5239f5620d708520e8b28f5aa1f2b20143e6024532edadfb5";
+    readonly "rancher/k3s:v1.33.5-k3s1": "rancher/k3s:v1.33.5-k3s1@sha256:fd4740667b7033055c27d424d0d2d660bf66cedbdb225d68e0eab6dd48aa0fd2";
+    readonly "rancher/mirrored-library-traefik:3.3.2": "rancher/mirrored-library-traefik:3.3.2@sha256:a03ee2f858f77975fa943f6797da5446b7ac9a83beef6bbdae2afd8feaf67b76";
+    readonly "registry:2.8.3": "registry:2.8.3@sha256:a3d8aaa63ed8681a604f1dea0aa03f100d5895b6a58ace528858a7b332415373";
+    readonly "registry.k8s.io/pause:3.10": "registry.k8s.io/pause:3.10@sha256:ee6521f290b2168b6e0935a181d4cff9be1ac3f505666ef0e3c98fae8199917a";
+    readonly "node:22-bookworm-slim": "node:22-bookworm-slim@sha256:4b150b48b4116e2a22f2c39cc27025fbf4f153e2078fd3b14d159fdb5c7279da";
+    readonly "node:24-bookworm-slim": "node:24-bookworm-slim@sha256:c86ecead9e55a5210ac1727de38a4ca840bf03dcaf34dc9749addbf383b1920c";
+    readonly "oven/bun:1.3.14-alpine": "oven/bun:1.3.14-alpine@sha256:5acc90a93e91ff07bf72aa90a7c9f0fa189765aec90b47bdbf2152d2196383c0";
+    readonly "axllent/mailpit:v1.30": "axllent/mailpit:v1.30@sha256:d5ecbb067db3705fa953d79e1b7f81ef84038df67aba6c52825d8c02a1ea748a";
+    readonly "ministackorg/ministack:1.4.8": "ministackorg/ministack:1.4.8@sha256:eb0a00c897ec91589eb78a77f0afaf13a6d7be99abfeca2d1d719a7ec76d3141";
+    readonly "temporalio/temporal:1.9.1": "temporalio/temporal:1.9.1@sha256:ad4c82c97bd12b417d1ea942610dbcd511afb250c4d5ed26c694009533df447e";
+    readonly "nginx:1.29.6-alpine": "nginx:1.29.6-alpine@sha256:f46cb72c7df02710e693e863a983ac42f6a9579058a59a35f1ae36c9958e4ce0";
+    readonly "supabase/supavisor:2.9.12": "supabase/supavisor:2.9.12@sha256:464b93a60ba8c96bc06dad7f241562d6613b2a994922307717b05f432ae415c2";
+    readonly "supabase/postgres:17.6.1.136": "supabase/postgres:17.6.1.136@sha256:f371b5f3f2ac0a05703f33d6e6134515fb2498cab708fb948a0aeb7481467c00";
+    readonly "kong/kong:3.9.1": "kong/kong:3.9.1@sha256:6addf50e6bd8d578314cb9ce4f2d2d1e3781d2edecef59f707e00c6e05d384f5";
+    readonly "supabase/gotrue:v2.189.0": "supabase/gotrue:v2.189.0@sha256:385184459f57569c54c25209f51f3b2be99ddd7c4ce9e3555b5d3eea8447b7cf";
+    readonly "postgrest/postgrest:v14.12": "postgrest/postgrest:v14.12@sha256:54000f24847d01a2c2302e0041cf0618b875c57fb48507d743cfa9aaa50bf43c";
+    readonly "supabase/realtime:v2.102.3": "supabase/realtime:v2.102.3@sha256:aa1c92c0cf326007563641730ec9da9c60478caa6853887775365fa2c097a471";
+    readonly "supabase/storage-api:v1.60.4": "supabase/storage-api:v1.60.4@sha256:c8eb9858eafec891a97c27125470aaad54703c3f4eb4d55ca7f1bf6c6411febf";
+    readonly "darthsim/imgproxy:v3.30.1": "darthsim/imgproxy:v3.30.1@sha256:3b709e4a0e5e8e0e959b556b7031229202b4b8e7e7d955c517ea7abed68ee34d";
+    readonly "supabase/edge-runtime:v1.74.0": "supabase/edge-runtime:v1.74.0@sha256:2781daf92394db91f7e94129cc3d04ec474ad16a8fe64b3fbeef6e7d557ab120";
+    readonly "busybox:1.37": "busybox:1.37@sha256:a7dbc319b1438115a207e11930dc4bb3e643dcb3ec0bdd694bb36cd8fad289ec";
+};

package/dist/harness/builtin-images.js

@@ -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",
+};

package/dist/harness/registry-seed.d.ts

@@ -3,7 +3,7 @@ import { type PreparedComponentImage } from "./component-images.js";
 export declare const REGISTRY_DATA = "/var/lib/spectest-registry";
 export declare const REGISTRY_CONTENT = "/spectest-registry-content";
 export declare const CONTENT_BLOBS = "io.containerd.content.v1.content/blobs/sha256";
-export declare const REGISTRY_IMAGE = "registry:2.8.3";
+export declare const REGISTRY_IMAGE: "registry:2.8.3@sha256:a3d8aaa63ed8681a604f1dea0aa03f100d5895b6a58ace528858a7b332415373";
 export declare const registryDirectory: (service: string) => string;
 /** Distribution 2.8 registry/storage/paths.go defines this layout. Seed
  * before starting the registry so it cannot cache partial publication.

package/dist/harness/registry-seed.js

@@ -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. */
@@ -8,7 +9,7 @@ import { canonicalImageReference } from "./component-images.js";
 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) => `/var/lib/spectest-registries/${service}`;
 /** Distribution 2.8 registry/storage/paths.go defines this layout. Seed
  * before starting the registry so it cannot cache partial publication.

package/dist/harness/sticky-kubernetes.js

@@ -111,6 +111,10 @@ export async function openKubernetesCacheMaintenance(run, root = ROOT) {
         throw error;
     });
     try {
+        // A successful inventory distinguishes orphaned legacy stores from Docker
+        // outages. Only this isolated maintenance copy may discard a store.
+        const available = new Set((await run("docker", ["image", "ls", "-aq", "--no-trunc"]))
+            .split(/\s+/).filter(Boolean));
         for (const service of entries) {
             if (!service.isDirectory() || !SERVICE_NAME.test(service.name))
                 continue;
@@ -122,6 +126,14 @@ export async function openKubernetesCacheMaintenance(run, root = ROOT) {
                 if (descriptor.schema !== 1 || !IMAGE_ID.test(descriptor.image) || !Number.isSafeInteger(descriptor.updatedAt)) {
                     throw new Error(`invalid Kubernetes cache descriptor: ${directory}`);
                 }
+                if (!available.has(descriptor.image)) {
+                    // Older exporters replaced their sole image reference on rebuild.
+                    // An obsolete version's store can outlive that image. It is disposable
+                    // cache, and must not prevent publishing the healthy stores.
+                    console.warn(`Discarding orphaned Kubernetes cache ${directory}: missing runtime image ${descriptor.image}`);
+                    await run("rm", ["-rf", directory]);
+                    continue;
+                }
                 const container = `spectest-k8s-cache-${randomUUID()}`;
                 await run("docker", ["run", "-d", "--name", container, "--network", "none", "--privileged", "--stop-signal", "SIGTERM", "--tmpfs", "/run", "--tmpfs", "/var/run",
                     "--mount", `type=bind,source=${directory}/containerd,target=${STORE_TARGET}`,

package/package.json

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

package/src/components/android.ts

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 import { readFileSync } from "node:fs";
 import { posix } from "node:path";
 import { serviceGroup } from "../index.js";
@@ -44,7 +45,7 @@ assert s.count(a) == 1
 p.write_text(s.replace(a, a + '\n    puts("spectest-first-frame-v1");'))`;
 const shellQuote = (value: string) => "'" + value.replaceAll("'", "'\\''") + "'";
 
-export const ANDROID_TOOLS_DOCKERFILE = `FROM node:22-bookworm-slim
+export const ANDROID_TOOLS_DOCKERFILE = `FROM ${BUILTIN_IMAGES["node:22-bookworm-slim"]}
 RUN apt-get update && apt-get install -y --no-install-recommends adb aapt apksigner zipalign ffmpeg default-jdk-headless ca-certificates openssl curl gcc python3 pkg-config meson ninja-build libsdl2-dev libavcodec-dev libavdevice-dev libavformat-dev libavutil-dev libswresample-dev libusb-1.0-0-dev && rm -rf /var/lib/apt/lists/*
 RUN curl -fL https://github.com/Genymobile/scrcpy/archive/refs/tags/v3.3.1.tar.gz | tar xz -C /tmp && curl -fL https://github.com/Genymobile/scrcpy/releases/download/v3.3.1/scrcpy-server-v3.3.1 -o /tmp/scrcpy-server && python3 -c ${shellQuote(recorderPatch.replaceAll("\n", ";"))} && meson setup /tmp/scrcpy-build /tmp/scrcpy-3.3.1 --buildtype=release -Dprebuilt_server=/tmp/scrcpy-server && ninja -C /tmp/scrcpy-build -j4 install && rm -rf /tmp/scrcpy*
 ENV ANDROID_HOME=/opt/android JAVA_HOME=/usr/lib/jvm/default-java APPIUM_HOME=/opt/appium

package/src/components/aws.ts

@@ -1,3 +1,4 @@
+import { BUILTIN_IMAGES } from "../harness/builtin-images.js";
 // `aws()` — the AWS cloud APIs, emulated inside the environment, answering
 // at their **real** endpoints.
 //
@@ -68,7 +69,7 @@ import { certificate, provides, proxy, SELF_SERVICE_TOKEN } from "../index.js";
 import { pauseRecording, resumeRecording } from "../recorder.js";
 
 /** Backing image, pinned internally (not part of the documented surface). */
-const AWS_IMAGE = "ministackorg/ministack:1.4.8";
+const AWS_IMAGE = BUILTIN_IMAGES["ministackorg/ministack:1.4.8"];
 /** Port the emulator serves every AWS API on. Internal: callers reach the
  *  emulator through the AWS hostnames, never through this port. */
 const AWS_PORT = 4566;

package/src/components/electron.test.ts

@@ -24,6 +24,8 @@ describe('Electron component contract', () => {
     writeFileSync(join(appDir, 'package-lock.json'), '{}');
     const service = electron({ appDir, buildCommand: 'npm run compile', env: { API_URL: 'http://backend:4320' } });
     expect(service.image).toMatchObject({ context: appDir });
+    expect(service.image.content.split('\n')[0]).toMatch(/^FROM node:24-bookworm-slim@sha256:[a-f0-9]{64}$/);
+    expect(electron({ appDir, nodeVersion: '22-alpine' }).image.content.split('\n')[0]).toBe('FROM node:22-alpine');
     expect((service.image as { content: string }).content).toContain('RUN npm ci\n');
     expect((service.image as { content: string }).content).toContain('RUN npm run compile\n');
     expect(service.env?.API_URL).toBe('http://backend:4320');

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,6 +4,7 @@ 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 { containerdImageOutput } from "./harness/built-image.js";
 import { componentBuildTasks, COMPONENT_RUNTIME } from "./harness/component-images.js";
 import { waitForAll } from "./harness/concurrency.js";
 import { updateServiceProgress, serviceProgressSnapshot, type ServiceProgress } from "./harness/service-progress.js";
@@ -748,22 +749,6 @@ 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;
-}
-
-
 /** 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 {
@@ -1379,11 +1364,15 @@ 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).
       buildArgs = [
         "buildx", "build",
         "--builder", LOCAL_BUILDER_NAME,
         "--progress=plain",
-        "--output", `type=image,name=${qualifyImageRef(tag)},unpack=true`,
+        "--output", containerdImageOutput(tag),
         ...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,12 @@ 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. */
+export function containerdImageOutput(reference: string): string {
+  return `type=image,name=${canonicalImageReference(reference)},name-canonical=true,unpack=true`;
+}
+
 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/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-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);
+});

package/src/harness/sticky-kubernetes.ts

@@ -119,6 +119,10 @@ export async function openKubernetesCacheMaintenance(run: CacheCommand, root = R
     throw error;
   });
   try {
+    // A successful inventory distinguishes orphaned legacy stores from Docker
+    // outages. Only this isolated maintenance copy may discard a store.
+    const available = new Set((await run("docker", ["image", "ls", "-aq", "--no-trunc"]))
+      .split(/\s+/).filter(Boolean));
     for (const service of entries) {
       if (!service.isDirectory() || !SERVICE_NAME.test(service.name)) continue;
       for (const layout of await readdir(`${root}/${service.name}`, { withFileTypes: true })) {
@@ -128,6 +132,14 @@ export async function openKubernetesCacheMaintenance(run: CacheCommand, root = R
         if (descriptor.schema !== 1 || !IMAGE_ID.test(descriptor.image) || !Number.isSafeInteger(descriptor.updatedAt)) {
           throw new Error(`invalid Kubernetes cache descriptor: ${directory}`);
         }
+        if (!available.has(descriptor.image)) {
+          // Older exporters replaced their sole image reference on rebuild.
+          // An obsolete version's store can outlive that image. It is disposable
+          // cache, and must not prevent publishing the healthy stores.
+          console.warn(`Discarding orphaned Kubernetes cache ${directory}: missing runtime image ${descriptor.image}`);
+          await run("rm", ["-rf", directory]);
+          continue;
+        }
         const container = `spectest-k8s-cache-${randomUUID()}`;
         await run("docker", ["run", "-d", "--name", container, "--network", "none", "--privileged", "--stop-signal", "SIGTERM", "--tmpfs", "/run", "--tmpfs", "/var/run",
           "--mount", `type=bind,source=${directory}/containerd,target=${STORE_TARGET}`,