@specific.dev/spectest 0.131.12 → 0.131.14

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,7 +4,8 @@ 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 { 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 } from "./harness/service-progress.js";
 import { androidScope, androidRecordingChunk, releaseAndroidRecording, isAndroidApp } from "./android.js";
@@ -491,21 +492,17 @@ 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;
+/** `true` when a digest-pinned reference is already complete in the store. */
+async function imagePresentByDigest(ref) {
+    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`. */
@@ -913,6 +910,19 @@ async function prepareServiceImageInner(svc, opts) {
         // 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) => {
@@ -1053,11 +1063,34 @@ 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).
+            //
+            // `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/dist/harness/built-image.d.ts

@@ -1,3 +1,15 @@
+/** 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 declare function containerdImageOutput(reference: string, options?: {
+    unpack?: boolean;
+}): string;
 export interface Descriptor {
     digest: string;
     size: number;

package/dist/harness/built-image.js

@@ -3,6 +3,19 @@ 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.
+ *
+ * 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, options = {}) {
+    const unpack = options.unpack ?? true;
+    return `type=image,name=${canonicalImageReference(reference)},name-canonical=true,unpack=${unpack},compression=uncompressed`;
+}
 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/component-images.d.ts

@@ -5,10 +5,17 @@ export type KubernetesImage = string | (BuildImage & {
 });
 /** containerd/CRI use fully qualified names, including the default tag. */
 export declare function canonicalImageReference(reference: string): string;
+/** A `name@sha256:…` reference names one immutable image; a tag can move. */
+export declare function isDigestReference(reference: string): boolean;
 export declare function kubernetesImages(images: readonly KubernetesImage[]): {
     pulls: string[];
     builds: ComponentImageBuild[];
 };
+/** Prefix of every component image task name; `isComponentImageTask` is the test. */
+export declare 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 declare function isComponentImageTask(name: string): boolean;
 /** Stable internal task names, separate from the service graph. */
 export declare function componentBuildTasks<T extends ServiceConfig & {
     name: string;

package/dist/harness/component-images.js

@@ -24,6 +24,10 @@ export function canonicalImageReference(reference) {
         result += ":latest";
     return result;
 }
+/** A `name@sha256:…` reference names one immutable image; a tag can move. */
+export function isDigestReference(reference) {
+    return /@sha256:[a-f0-9]{64}$/.test(reference);
+}
 export function kubernetesImages(images) {
     if (!Array.isArray(images))
         throw new Error("k3s(): images must be an array of registry references or Dockerfile builds");
@@ -54,10 +58,17 @@ export function kubernetesImages(images) {
     }
     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) {
+    return name.startsWith(COMPONENT_IMAGE_TASK_PREFIX);
+}
 /** Stable internal task names, separate from the service graph. */
 export function componentBuildTasks(services) {
     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/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-consumer.js

@@ -101,6 +101,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, program, args) => {

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.14",
   "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');