@specific.dev/spectest 0.92.1 → 0.93.0

package/README.md

@@ -106,3 +106,10 @@ renderer DOM from acquisition onward, not native OS surfaces.
 
 Run `spectest docs /components/electron` for the full configuration reference,
 backend setup, session behavior, and replay scope (CLI 0.2.124 or later).
+
+`k3s({ registry: { host: "registry.test" }, images: [...] })` exposes the
+component's writable registry over verified HTTPS through the VM proxy.
+Dockerfile builds in `images` targeting `registry.test/...` are published and
+preloaded from the same cached build, preserving digests without an export/push
+step. Other images keep direct preloading. Registry writes stay isolated across
+test forks; client and containerd CA trust are configured automatically.

package/dist/components/index.d.ts

@@ -2,7 +2,7 @@ export { temporal, temporalClient, type TemporalOptions, type TemporalClient, ty
 export { postgres, type PostgresOptions, type PostgresHelpers, } from "./postgres.js";
 export { s3, type S3Options, type S3Helpers, } from "./s3.js";
 export { SQL, type SqlClient, type SqlOptions } from "../sql.js";
-export { k3s, type K3sOptions, type KubernetesImage, type K3sHelpers, type K3sClient, type TaggedObjectApi, type KubernetesObjectRef, type ApplyOptions, type RolloutTarget, type WaitOptions, type LogsOptions, type KubernetesObject, type KubernetesListObject, } from "./k3s.js";
+export { k3s, type K3sOptions, type K3sRegistryOptions, type KubernetesImage, type K3sHelpers, type K3sClient, type TaggedObjectApi, type KubernetesObjectRef, type ApplyOptions, type RolloutTarget, type WaitOptions, type LogsOptions, type KubernetesObject, type KubernetesListObject, } from "./k3s.js";
 export { expo, type ExpoOptions, type ExpoHelpers, type ExpoPackageManager, } from "./expo.js";
 export { supabase, type SupabaseOptions, type SupabaseHelpers, type SupabaseStack, } from "./supabase.js";
 export { email, type EmailOptions, type EmailHelpers, type EmailMessage, type EmailSummary, type EmailMatch, type EmailAttachment, } from "./email.js";

package/dist/components/k3s.d.ts

@@ -4,6 +4,14 @@ import { type KubernetesImage } from "../harness/component-images.js";
 export type { KubernetesImage } from "../harness/component-images.js";
 import type { Wrapped } from "../inspect.js";
 export type { KubernetesObject, KubernetesListObject, } from "@kubernetes/client-node";
+/** HTTPS exposure and publication for the component's writable registry. */
+export interface K3sRegistryOptions {
+    /** Exact DNS hostname exposed through Spectest's VM HTTPS proxy on port 443.
+     * Clients and Kubernetes's containerd trust the environment CA automatically.
+     * Builds in `images` whose reference starts with this host are also published
+     * here, using their original cached blobs and manifest digests. */
+    host: string;
+}
 /** Kubernetes pods receive read-only environment CA mounts during admission.
  * Image bytes and digests stay unchanged; explicit pod trust settings win. */
 export interface K3sOptions {
@@ -11,6 +19,9 @@ export interface K3sOptions {
      * or Dockerfile builds with a full `reference` matching your manifests. Builds
      * support path/content, context, exclude, target and buildArgs, and run in
      * parallel with service builds through the standard BuildKit pipeline.
+     * With `registry: { host }`, builds targeting that host are also published
+     * to the writable registry before setup completes. Other images remain
+     * direct preloads; no external registry receives pushes.
      * Setup waits for every pull and fails if a requested image cannot be pulled.
      * Sticky-enabled projects retain image content and unpacked layers between
      * fresh builds automatically. Digest references can reuse the cache offline;
@@ -85,10 +96,15 @@ export interface K3sOptions {
      * into your platform, e.g. `env: { REGISTRY_URL: "cluster.internal:5000" }`.
      * Plain HTTP, so configure your push client for an insecure registry.
      *
+     * Set `{ host: "registry.test" }` for verified HTTPS on port 443 through
+     * the built-in VM proxy, including containerd trust and relative upload URLs.
+     * This does not require Traefik. Builds targeting that host in `images` are
+     * published automatically; tags and test uploads remain isolated per fork.
+     *
      * On by default. Set `false` for clusters that only ever run public
      * images — that skips the extra pod.
      */
-    registry?: boolean;
+    registry?: boolean | K3sRegistryOptions;
     /**
      * Domains to route into this cluster's ingress via **wildcard DNS**. For
      * each `"example.com"`, spectest-resolver answers any `*.example.com`
@@ -336,6 +352,10 @@ export declare function k3s(opts?: K3sOptions): {
         reference: string;
     };
     imageBuilds: import("../index.js").ComponentImageBuild[];
+    tls: {
+        hostname: string;
+        port: number;
+    }[];
     command: string;
     privileged: true;
     tmpfs: string[];
@@ -348,10 +368,12 @@ export declare function k3s(opts?: K3sOptions): {
     } | {
         source: string;
         target: string;
-        readOnly: true;
-    })[] | {
+        readOnly: boolean;
+    } | {
         target: string;
-    }[];
+        source?: undefined;
+        readOnly?: undefined;
+    })[];
     files: {
         path: string;
         content: string;

package/dist/components/k3s.js

@@ -1,6 +1,7 @@
 import { isIP } from "node:net";
 import { installPodTrust } from "./k3s-trust.js";
 import { waitForAll } from "../harness/concurrency.js";
+import { CONTENT_BLOBS, REGISTRY_CONTENT, REGISTRY_DATA, REGISTRY_IMAGE, registryDirectory, seedRegistry } from "../harness/registry-seed.js";
 import { loadK3sBuildImages } from "../harness/k3s-image-loader.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { spawn as nodeSpawn } from "node:child_process";
@@ -792,7 +793,7 @@ const HUB_MIRROR = { registry: "docker.io", mirror: "https://mirror.gcr.io", ups
  *      shares the node's netns, so this needs no in-container DNS and
  *      can't be broken by a clobbered `hostnames`.
  */
-function buildRegistriesYaml(registryEnabled) {
+function buildRegistriesYaml(registryEnabled, host) {
     const lines = [
         "mirrors:",
         `  "${HUB_MIRROR.registry}":`,
@@ -807,6 +808,11 @@ function buildRegistriesYaml(registryEnabled) {
         // makes that explicit and disables any TLS attempt against it.
         `  "127.0.0.1:${K3S_REGISTRY_PORT}":`, `    tls:`, `      insecure_skip_verify: true`);
     }
+    if (host) {
+        // This names the verified HTTPS endpoint itself; do not mirror it to HTTP.
+        // container-run mounts the environment CA before k3s/containerd starts.
+        lines.push(`  "${host}":`, "    tls:", `      ca_file: ${JSON.stringify(CA_PATH)}`);
+    }
     return lines.join("\n") + "\n";
 }
 /**
@@ -814,11 +820,13 @@ function buildRegistriesYaml(registryEnabled) {
  * binds the cluster container's `:5000` directly — the same trick
  * Traefik uses — so peer services reach it at `<cluster-key>.internal:5000`
  * (the cluster service's own alias) and the node's own containerd reaches
- * it at `127.0.0.1:5000`. Storage is an `emptyDir`, so pushed images live
- * in the cluster and are captured by snapshot / isolated per test fork
- * like all other in-VM state.
+ * it at `127.0.0.1:5000`. Storage is an `emptyDir` by default. Declared
+ * publications use a rootfs directory plus a read-only content mount; both
+ * variants keep writable registry state outside persistent image caches and
+ * capture it with the VM snapshot, isolated per test fork.
  */
-const REGISTRY_MANIFEST = `apiVersion: apps/v1
+function registryManifest(seeded) {
+    return `apiVersion: apps/v1
 kind: Deployment
 metadata:
   name: spectest-registry
@@ -841,11 +849,13 @@ spec:
       - operator: Exists
       containers:
       - name: registry
-        image: registry:2
+        image: ${seeded ? REGISTRY_IMAGE : "registry:2"}
         imagePullPolicy: IfNotPresent
         env:
         - name: REGISTRY_HTTP_ADDR
           value: ":${K3S_REGISTRY_PORT}"
+        - name: REGISTRY_HTTP_RELATIVEURLS
+          value: "true"
         - name: REGISTRY_STORAGE_DELETE_ENABLED
           value: "true"
         ports:
@@ -854,10 +864,20 @@ spec:
         volumeMounts:
         - name: data
           mountPath: /var/lib/registry
-      volumes:
+${seeded ? `        - name: content
+          mountPath: ${REGISTRY_CONTENT}
+          readOnly: true
+` : ""}      volumes:
       - name: data
-        emptyDir: {}
+${seeded ? `        hostPath:
+          path: ${REGISTRY_DATA}
+          type: Directory
+      - name: content
+        hostPath:
+          path: ${REGISTRY_CONTENT}
+          type: Directory` : "        emptyDir: {}"}
 `;
+}
 // ────────────────────────────────────────────────────────────────────────
 // Apply — server-side, converging
 //
@@ -1310,7 +1330,8 @@ async function setupK3sCluster(name, helpers, opts) {
         (async () => {
             if (!opts.registry)
                 return;
-            await helpers.apply(REGISTRY_MANIFEST);
+            await opts.seed?.();
+            await helpers.apply(registryManifest(!!opts.seed));
             await wait("spectest-registry");
         })(),
     ]);
@@ -1438,6 +1459,16 @@ export function k3s(opts = {}) {
     const extra = opts.extraArgs ?? [];
     assertUsableExtraArgs(extra);
     const registryEnabled = opts.registry !== false;
+    let registryHost;
+    if (opts.registry !== undefined && typeof opts.registry !== "boolean") {
+        if (!opts.registry || typeof opts.registry.host !== "string" || opts.registry.host.startsWith("*.")) {
+            throw new Error("k3s(): registry must be a boolean or { host: an exact DNS hostname }");
+        }
+        // Reuse ingress validation (no scheme, port, path, or reserved .internal).
+        registryHost = dnsName(opts.registry.host, { ingress: true }).hostname;
+    }
+    const isPublished = (reference) => !!registryHost && reference.startsWith(`${registryHost}/`);
+    const publishBuilds = images.builds.filter(image => isPublished(image.reference));
     const traefikEnabled = opts.traefik !== false;
     const loadBalancerEnabled = opts.loadBalancer !== false;
     // Wildcard ingress domains. Drives both the `provides(... dnsName)`
@@ -1447,12 +1478,13 @@ export function k3s(opts = {}) {
     // `/etc/rancher/k3s/registries.yaml` (host-cache mirrors + trust for
     // the in-cluster registry). Seeded via `files` because k3s reads it
     // only at startup, before any setup hook could run.
-    const registriesYaml = buildRegistriesYaml(registryEnabled);
+    const registriesYaml = buildRegistriesYaml(registryEnabled, registryHost);
     // The environment's image cache, when this VM carries one: the
     // cluster's store goes on its root disk and its layers come off the
     // shared layers disk (see the store section above).
     const sticky = stickyDiskPathSync();
     const cache = sticky ? null : imageCachePathsSync();
+    const contentDirectory = `${sticky ? `${sticky}/containerd` : cache?.root ?? "/var/lib/containerd"}/${CONTENT_BLOBS}`;
     const serverArgs = [
         "k3s",
         "server",
@@ -1551,6 +1583,7 @@ export function k3s(opts = {}) {
     const def = {
         image: { type: "registry", reference: `rancher/k3s:${version}` },
         imageBuilds: images.builds,
+        tls: registryHost ? [{ hostname: registryHost, port: K3S_REGISTRY_PORT }] : [],
         command: cmd,
         privileged: true,
         tmpfs: ["/run", "/var/run"],
@@ -1572,15 +1605,20 @@ export function k3s(opts = {}) {
         // in one environment get separate roots either way (the service
         // token names the directory), because two containerd daemons cannot
         // share a store: bolt takes an exclusive lock.
-        volumes: sticky
-            ? [{ source: `${stickyKubernetesDirectory(SELF_SERVICE_TOKEN, version)}/containerd`, target: CLUSTER_STORE_TARGET }]
-            : cache ? [
-                { source: nestedStoreDir(cache, SELF_SERVICE_TOKEN), target: CLUSTER_STORE_TARGET },
-                { source: cache.layers, target: cache.layers, readOnly: true },
-                { source: MKFS_EROFS_PATH, target: MKFS_EROFS_PATH, readOnly: true },
-                { source: STORE_ADOPT_PATH, target: STORE_ADOPT_PATH, readOnly: true },
-            ]
-                : [{ target: CLUSTER_STORE_TARGET }],
+        volumes: [...(sticky
+                ? [{ source: `${stickyKubernetesDirectory(SELF_SERVICE_TOKEN, version)}/containerd`, target: CLUSTER_STORE_TARGET }]
+                : cache ? [
+                    { source: nestedStoreDir(cache, SELF_SERVICE_TOKEN), target: CLUSTER_STORE_TARGET },
+                    { source: cache.layers, target: cache.layers, readOnly: true },
+                    { source: MKFS_EROFS_PATH, target: MKFS_EROFS_PATH, readOnly: true },
+                    { source: STORE_ADOPT_PATH, target: STORE_ADOPT_PATH, readOnly: true },
+                ]
+                    : [{ target: CLUSTER_STORE_TARGET }]),
+            ...(publishBuilds.length ? [
+                { source: registryDirectory(SELF_SERVICE_TOKEN), target: REGISTRY_DATA },
+                { source: contentDirectory, target: REGISTRY_CONTENT, readOnly: true },
+            ] : []),
+        ],
         files: [
             ...(registriesYaml ? [{ path: "/etc/rancher/k3s/registries.yaml", content: registriesYaml }] : []),
             ...(cache
@@ -1600,55 +1638,61 @@ export function k3s(opts = {}) {
             const runtime = componentRuntime(ctx);
             if (images.builds.length && !runtime)
                 throw new Error(`k3s(${name}): prepared image inputs are missing`);
-            await waitForAll([
-                runtime ? loadK3sBuildImages(name, runtime.images, runtime.gateway, exec) : Promise.resolve(),
-                prePullK3sImages(name, images.pulls, exec),
-                (async () => {
-                    if (runtime?.caBundle && caPresent()) {
-                        const { cert, key } = await issueIngressCert([runtime.gateway]);
-                        await installPodTrust({ name, gateway: runtime.gateway, cert, key,
-                            ca: await readFile(CA_PATH, "utf8"), bundle: await readFile(runtime.caBundle, "utf8"),
-                        }, {
-                            apply: async (configuration) => { await helpers.apply(JSON.stringify(configuration)); },
-                            ensureBundle: async (namespace, configMap, bundle) => {
-                                try {
-                                    await helpers.client.core.createNamespacedConfigMap({ namespace, body: {
-                                            metadata: { name: configMap, namespace }, immutable: true, data: { "ca-bundle.crt": bundle },
-                                        } });
-                                }
-                                catch (err) {
-                                    // A simultaneous Pod may have created the same namespace's bundle.
-                                    const existing = (await helpers.client.core.readNamespacedConfigMap({ namespace, name: configMap })).unwrap();
-                                    if (existing.data?.["ca-bundle.crt"] !== bundle || existing.immutable !== true)
-                                        throw err;
-                                }
-                            },
-                        });
-                        // The API server observes webhook registration asynchronously. A dry-run
-                        // Pod proves TLS reachability and admission before any project workload.
-                        const deadline = Date.now() + 30_000;
-                        for (;;) {
+            const infrastructure = (async () => {
+                if (runtime?.caBundle && caPresent()) {
+                    const { cert, key } = await issueIngressCert([runtime.gateway]);
+                    await installPodTrust({ name, gateway: runtime.gateway, cert, key,
+                        ca: await readFile(CA_PATH, "utf8"), bundle: await readFile(runtime.caBundle, "utf8"),
+                    }, {
+                        apply: async (configuration) => { await helpers.apply(JSON.stringify(configuration)); },
+                        ensureBundle: async (namespace, configMap, bundle) => {
                             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" }] },
-                                    } })).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`);
+                                await helpers.client.core.createNamespacedConfigMap({ namespace, body: {
+                                        metadata: { name: configMap, namespace }, immutable: true, data: { "ca-bundle.crt": bundle },
+                                    } });
                             }
                             catch (err) {
-                                if (Date.now() >= deadline)
+                                // A simultaneous Pod may have created the same namespace's bundle.
+                                const existing = (await helpers.client.core.readNamespacedConfigMap({ namespace, name: configMap })).unwrap();
+                                if (existing.data?.["ca-bundle.crt"] !== bundle || existing.immutable !== true)
                                     throw err;
                             }
-                            await new Promise(resolve => setTimeout(resolve, 100));
+                        },
+                    });
+                    // The API server observes webhook registration asynchronously. A dry-run
+                    // Pod proves TLS reachability and admission before any project workload.
+                    const deadline = Date.now() + 30_000;
+                    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" }] },
+                                } })).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`);
+                        }
+                        catch (err) {
+                            if (Date.now() >= deadline)
+                                throw err;
                         }
+                        await new Promise(resolve => setTimeout(resolve, 100));
                     }
-                    await setupK3sCluster(name, helpers, {
-                        registry: registryEnabled,
-                        ingressDomains,
-                        traefik: traefikEnabled,
-                    });
+                }
+                await setupK3sCluster(name, helpers, {
+                    registry: registryEnabled,
+                    seed: publishBuilds.length ? () => seedRegistry(name, contentDirectory, runtime.images.filter(image => isPublished(image.reference))) : undefined,
+                    ingressDomains,
+                    traefik: traefikEnabled,
+                });
+            })();
+            await waitForAll([
+                runtime ? loadK3sBuildImages(name, runtime.images, runtime.gateway, exec) : Promise.resolve(),
+                prePullK3sImages(name, images.pulls.filter(ref => !isPublished(ref)), exec),
+                (async () => {
+                    // Registry-local references must not race registry startup/publication.
+                    await infrastructure;
+                    await prePullK3sImages(name, images.pulls.filter(isPublished), exec);
                 })(),
             ]);
             if (sticky)

package/dist/daemon.js

@@ -1958,6 +1958,9 @@ serve = { proto: "http" }) {
         // {@link stopIngressServers} depends on: a half-alive listener shares
         // the port silently instead of colliding loudly.
         reusePort: true,
+        // OCI layer uploads can exceed Bun's default 128 MiB request limit.
+        // Large proxy bodies stream through; this limit does not allocate a buffer.
+        maxRequestBodySize: 1024 ** 4,
         // Bun.serve defaults to a 10s idleTimeout, which kills any proxied
         // request whose upstream takes >10s to produce bytes — under parallel
         // test load that surfaced as "fetch failed"/"other side closed" on

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

@@ -0,0 +1,16 @@
+export interface Descriptor {
+    digest: string;
+    size: number;
+    mediaType: string;
+    platform?: {
+        os: string;
+        architecture: string;
+    };
+}
+/** Preserve the original index/manifest bytes and all application descriptors. */
+export declare function hostImage(source: string): Promise<{
+    target: Descriptor;
+    metadata: Map<string, Buffer<ArrayBufferLike>>;
+    allowed: Map<string, Descriptor>;
+    configDigest: string;
+}>;

package/dist/harness/built-image.js

@@ -0,0 +1,57 @@
+/** Read build results without reserializing manifests or exporting layers. */
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { promisify } from "node:util";
+import { canonicalImageReference } from "./component-images.js";
+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);
+const HOST_CTR = ["--address", "/run/containerd/containerd.sock", "--namespace", "moby"];
+async function hostContent(id) {
+    if (!/^sha256:[a-f0-9]{64}$/.test(id))
+        throw new Error(`invalid content digest ${id}`);
+    const result = await run("ctr", [...HOST_CTR, "content", "get", id], { encoding: "buffer", maxBuffer: 16 * 1024 * 1024, timeout: 30_000 });
+    if (digest(result.stdout) !== id)
+        throw new Error(`corrupt image metadata ${id}`);
+    return result.stdout;
+}
+/** Preserve the original index/manifest bytes and all application descriptors. */
+export async function hostImage(source) {
+    const name = canonicalImageReference(source);
+    const { stdout } = await run("ctr", [...HOST_CTR, "images", "ls", `name==${name}`], { timeout: 30_000 });
+    const found = stdout.split("\n").map(line => line.trim().split(/\s+/)).find(row => row[0] === name)?.[2];
+    if (!found)
+        throw new Error(`built image ${name} is missing from the VM container store`);
+    const metadata = new Map();
+    const allowed = new Map();
+    let configDigest;
+    async function visit(id, selected, depth = 0) {
+        if (depth > 4)
+            throw new Error(`built image ${name} has a recursive manifest index`);
+        const bytes = await hostContent(id);
+        const obj = JSON.parse(bytes.toString());
+        const desc = descriptor(bytes, obj.mediaType);
+        metadata.set(id, bytes);
+        allowed.set(id, desc);
+        if (obj.config && Array.isArray(obj.layers)) {
+            const manifest = obj;
+            for (const blob of [manifest.config, ...manifest.layers])
+                allowed.set(blob.digest, blob);
+            if (selected)
+                configDigest = manifest.config.digest;
+        }
+        else if (Array.isArray(obj.manifests)) {
+            for (const entry of obj.manifests) {
+                const matches = !entry.platform || (entry.platform.os === "linux" && entry.platform.architecture === (process.arch === "arm64" ? "arm64" : "amd64"));
+                await visit(entry.digest, selected && matches, depth + 1);
+            }
+        }
+        else
+            throw new Error(`built image ${name} has invalid image metadata`);
+        return desc;
+    }
+    const target = await visit(found, true);
+    if (!configDigest)
+        throw new Error(`built image ${name} has no image for this VM's platform`);
+    return { target, metadata, allowed, configDigest };
+}

package/dist/harness/k3s-image-loader.js

@@ -1,65 +1,14 @@
 /** A short-lived, read-only OCI endpoint over the host containerd content store.
  * k3s fetches only missing blobs and unpacks only missing snapshots. No Docker
  * archive, staging registry, or second persistent copy of application blobs. */
-import { execFile, spawn } from "node:child_process";
+import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { createServer } from "node:http";
-import { promisify } from "node:util";
 import { canonicalImageReference } from "./component-images.js";
 import { waitForK3sRuntime } from "./k3s-prepull.js";
+import { hostImage } from "./built-image.js";
 import { waitForAll } from "./concurrency.js";
-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);
 const HOST_CTR = ["--address", "/run/containerd/containerd.sock", "--namespace", "moby"];
-async function hostContent(id) {
-    if (!/^sha256:[a-f0-9]{64}$/.test(id))
-        throw new Error(`invalid content digest ${id}`);
-    const result = await run("ctr", [...HOST_CTR, "content", "get", id], { encoding: "buffer", maxBuffer: 16 * 1024 * 1024, timeout: 30_000 });
-    if (digest(result.stdout) !== id)
-        throw new Error(`corrupt image metadata ${id}`);
-    return result.stdout;
-}
-/** Preserve the original index/manifest bytes and all application descriptors. */
-async function hostImage(source) {
-    const name = canonicalImageReference(source);
-    const { stdout } = await run("ctr", [...HOST_CTR, "images", "ls", `name==${name}`], { timeout: 30_000 });
-    const found = stdout.split("\n").map(line => line.trim().split(/\s+/)).find(row => row[0] === name)?.[2];
-    if (!found)
-        throw new Error(`built image ${name} is missing from the VM container store`);
-    const metadata = new Map();
-    const allowed = new Map();
-    let configDigest;
-    async function visit(id, selected, depth = 0) {
-        if (depth > 4)
-            throw new Error(`built image ${name} has a recursive manifest index`);
-        const bytes = await hostContent(id);
-        const obj = JSON.parse(bytes.toString());
-        const desc = descriptor(bytes, obj.mediaType);
-        metadata.set(id, bytes);
-        allowed.set(id, desc);
-        if (obj.config && Array.isArray(obj.layers)) {
-            const manifest = obj;
-            for (const blob of [manifest.config, ...manifest.layers])
-                allowed.set(blob.digest, blob);
-            if (selected)
-                configDigest = manifest.config.digest;
-        }
-        else if (Array.isArray(obj.manifests)) {
-            for (const entry of obj.manifests) {
-                const matches = !entry.platform || (entry.platform.os === "linux" && entry.platform.architecture === (process.arch === "arm64" ? "arm64" : "amd64"));
-                await visit(entry.digest, selected && matches, depth + 1);
-            }
-        }
-        else
-            throw new Error(`built image ${name} has invalid image metadata`);
-        return desc;
-    }
-    const target = await visit(found, true);
-    if (!configDigest)
-        throw new Error(`built image ${name} has no image for this VM's platform`);
-    return { target, metadata, allowed, configDigest };
-}
 export async function loadK3sBuildImages(service, images, gateway, exec) {
     if (!images.length)
         return;

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

@@ -0,0 +1,12 @@
+import { hostImage } from "./built-image.js";
+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 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.
+ * The prepared build's containerd image record retains the referenced blobs. */
+export declare function seedRegistryImage(directory: string, contentDirectory: string, reference: string, image: Awaited<ReturnType<typeof hostImage>>, mountedContent?: string): Promise<void>;
+export declare function seedRegistry(service: string, contentDirectory: string, images: readonly PreparedComponentImage[]): Promise<void>;

package/dist/harness/registry-seed.js

@@ -0,0 +1,61 @@
+/** 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. */
+import { mkdir, stat, symlink, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { hostImage } from "./built-image.js";
+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 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.
+ * The prepared build's containerd image record retains the referenced blobs. */
+export async function seedRegistryImage(directory, contentDirectory, reference, image, mountedContent = REGISTRY_CONTENT) {
+    const canonical = canonicalImageReference(reference);
+    if (canonical.includes("@"))
+        throw new Error("registry publication must name a tag");
+    const repository = canonical.slice(canonical.indexOf("/") + 1, canonical.lastIndexOf(":"));
+    const tag = canonical.slice(canonical.lastIndexOf(":") + 1);
+    const root = `${directory}/docker/registry/v2`;
+    const repo = `${root}/repositories/${repository}`;
+    const link = async (path, value) => {
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, value);
+    };
+    for (const [id, descriptor] of image.allowed) {
+        if (!/^sha256:[a-f0-9]{64}$/.test(id))
+            throw new Error(`invalid registry seed digest ${id}`);
+        const hex = id.slice(7);
+        const info = await stat(`${contentDirectory}/${hex}`);
+        if (!info.isFile() || info.size !== descriptor.size)
+            throw new Error(`missing or incomplete registry seed blob ${id}`);
+        const destination = `${root}/blobs/sha256/${hex.slice(0, 2)}/${hex}/data`;
+        await mkdir(dirname(destination), { recursive: true });
+        try {
+            await symlink(`${mountedContent}/${hex}`, destination);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        await link(`${repo}/_layers/sha256/${hex}/link`, id);
+        if (image.metadata.has(id))
+            await link(`${repo}/_manifests/revisions/sha256/${hex}/link`, id);
+    }
+    const id = image.target.digest;
+    await link(`${repo}/_manifests/tags/${tag}/index/sha256/${id.slice(7)}/link`, id);
+    await link(`${repo}/_manifests/tags/${tag}/current/link`, id);
+}
+export async function seedRegistry(service, contentDirectory, images) {
+    // Sequential metadata updates avoid races when several tags share blobs.
+    // Builds themselves still run concurrently with all environment preparation.
+    for (const image of images) {
+        await image.ready;
+        const built = await hostImage(image.source);
+        await seedRegistryImage(registryDirectory(service), contentDirectory, image.reference, built);
+        console.log(`[k3s-registry] ${service}: ${image.reference} @ ${built.target.digest} (cached blobs, no export)`);
+    }
+}

package/dist/index.d.ts

@@ -831,7 +831,8 @@ export type BuildImage = (Omit<Extract<NormalizedServiceImage, {
 }>, "type">) & {
     /** Full image reference, e.g. "k8s.internal:5000/runtime:spectest".
      * Optional for a service; required for a Kubernetes build. This names a
-     * local image and does not publish it to a registry. */
+     * local image. In k3s, builds targeting `registry.host` are also published
+     * to that component's registry; other references are only preloaded. */
     reference?: string;
 };
 /** A registry reference or Dockerfile build. Tagged objects from older SDKs

package/package.json

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

package/src/components/index.ts

@@ -26,6 +26,7 @@ export { SQL, type SqlClient, type SqlOptions } from "../sql.js";
 export {
   k3s,
   type K3sOptions,
+  type K3sRegistryOptions,
   type KubernetesImage,
   type K3sHelpers,
   type K3sClient,

package/src/components/k3s-registry.test.ts

@@ -0,0 +1,50 @@
+import { expect, test } from "bun:test";
+import { k3s } from "./k3s";
+import { REGISTRY_CONTENT, REGISTRY_DATA } from "../harness/registry-seed";
+
+test("HTTPS registry is component-owned, with explicit containerd trust and no Traefik dependency", () => {
+  const cluster = k3s({ registry: { host: "Registry.Test" }, traefik: false });
+  expect(cluster.tls).toEqual([{ hostname: "registry.test", port: 5000 }]);
+  const registries = cluster.files.find(file => file.path.endsWith("registries.yaml"))!.content;
+  expect(registries).toContain('"registry.test":\n    tls:\n      ca_file:');
+  expect(registries).not.toContain('"https://127.0.0.1');
+  expect(registries).toContain('"http://127.0.0.1:5000"');
+});
+
+test("only builds targeting the configured registry require publication storage", () => {
+  const image = { content: "FROM scratch", reference: "registry.test/codenode:latest" };
+  const cluster = k3s({ registry: { host: "registry.test" }, images: [image] });
+  expect(cluster.imageBuilds).toHaveLength(1);
+  expect(cluster.volumes.find(v => v.target === REGISTRY_DATA)?.source).toBe(
+    "/var/lib/spectest-registries/{{SPECTEST_SERVICE}}",
+  );
+  expect(cluster.volumes.find(v => v.target === REGISTRY_CONTENT)?.readOnly).toBe(true);
+  for (const registry of [undefined, false, true, { host: "other.test" }]) {
+    expect(k3s({ registry, images: [image] }).volumes.some(v => v.target === REGISTRY_DATA)).toBe(false);
+  }
+  expect(k3s({ registry: { host: "registry.test" }, images: [image.reference] }).volumes.some(v => v.target === REGISTRY_DATA)).toBe(false);
+});
+
+test("registry host rejects ports, URLs, wildcard and reserved hostnames", () => {
+  for (const host of ["", "https://registry.test", "registry.test:443", "*.registry.test", "k8s.internal", "registry.test/path"]) {
+    expect(() => k3s({ registry: { host } })).toThrow();
+  }
+  for (const registry of [null, "registry.test", {}, { host: 123 }]) {
+    expect(() => k3s({ registry } as never)).toThrow();
+  }
+});
+
+test("registry upload URLs are relative and local pre-pulls wait for the registry", async () => {
+  const cluster = k3s({ registry: { host: "registry.test" }, traefik: false, images: ["registry.test/app:latest"] });
+  let ready = false;
+  await cluster.setup({ name: "cluster", helpers: {
+    apply: async (manifest: string) => {
+      expect(manifest).toContain('REGISTRY_HTTP_RELATIVEURLS\n          value: "true"');
+      expect(manifest).toContain("emptyDir: {}");
+    },
+    waitForRollout: async () => { ready = true; },
+  }, exec: async (_name: string, args: string[]) => {
+    if (args[3] === "pull") expect(ready).toBe(true);
+    return { exitCode: 0, stdout: "", stderr: "" };
+  } } as never);
+});

package/src/components/k3s.ts

@@ -1,6 +1,7 @@
 import { isIP } from "node:net";
 import { installPodTrust } from "./k3s-trust.js";
 import { waitForAll } from "../harness/concurrency.js";
+import { CONTENT_BLOBS, REGISTRY_CONTENT, REGISTRY_DATA, REGISTRY_IMAGE, registryDirectory, seedRegistry } from "../harness/registry-seed.js";
 import { loadK3sBuildImages } from "../harness/k3s-image-loader.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { spawn as nodeSpawn } from "node:child_process";
@@ -60,6 +61,15 @@ export type {
   KubernetesListObject,
 } from "@kubernetes/client-node";
 
+/** HTTPS exposure and publication for the component's writable registry. */
+export interface K3sRegistryOptions {
+  /** Exact DNS hostname exposed through Spectest's VM HTTPS proxy on port 443.
+   * Clients and Kubernetes's containerd trust the environment CA automatically.
+   * Builds in `images` whose reference starts with this host are also published
+   * here, using their original cached blobs and manifest digests. */
+  host: string;
+}
+
 /** Kubernetes pods receive read-only environment CA mounts during admission.
  * Image bytes and digests stay unchanged; explicit pod trust settings win. */
 export interface K3sOptions {
@@ -67,6 +77,9 @@ export interface K3sOptions {
    * or Dockerfile builds with a full `reference` matching your manifests. Builds
    * support path/content, context, exclude, target and buildArgs, and run in
    * parallel with service builds through the standard BuildKit pipeline.
+   * With `registry: { host }`, builds targeting that host are also published
+   * to the writable registry before setup completes. Other images remain
+   * direct preloads; no external registry receives pushes.
    * Setup waits for every pull and fails if a requested image cannot be pulled.
    * Sticky-enabled projects retain image content and unpacked layers between
    * fresh builds automatically. Digest references can reuse the cache offline;
@@ -141,10 +154,15 @@ export interface K3sOptions {
    * into your platform, e.g. `env: { REGISTRY_URL: "cluster.internal:5000" }`.
    * Plain HTTP, so configure your push client for an insecure registry.
    *
+   * Set `{ host: "registry.test" }` for verified HTTPS on port 443 through
+   * the built-in VM proxy, including containerd trust and relative upload URLs.
+   * This does not require Traefik. Builds targeting that host in `images` are
+   * published automatically; tags and test uploads remain isolated per fork.
+   *
    * On by default. Set `false` for clusters that only ever run public
    * images — that skips the extra pod.
    */
-  registry?: boolean;
+  registry?: boolean | K3sRegistryOptions;
   /**
    * Domains to route into this cluster's ingress via **wildcard DNS**. For
    * each `"example.com"`, spectest-resolver answers any `*.example.com`
@@ -1290,7 +1308,7 @@ const HUB_MIRROR = { registry: "docker.io", mirror: "https://mirror.gcr.io", ups
  *      shares the node's netns, so this needs no in-container DNS and
  *      can't be broken by a clobbered `hostnames`.
  */
-function buildRegistriesYaml(registryEnabled: boolean): string | null {
+function buildRegistriesYaml(registryEnabled: boolean, host?: string): string | null {
   const lines: string[] = [
     "mirrors:",
     `  "${HUB_MIRROR.registry}":`,
@@ -1312,6 +1330,11 @@ function buildRegistriesYaml(registryEnabled: boolean): string | null {
       `      insecure_skip_verify: true`,
     );
   }
+  if (host) {
+    // This names the verified HTTPS endpoint itself; do not mirror it to HTTP.
+    // container-run mounts the environment CA before k3s/containerd starts.
+    lines.push(`  "${host}":`, "    tls:", `      ca_file: ${JSON.stringify(CA_PATH)}`);
+  }
   return lines.join("\n") + "\n";
 }
 
@@ -1320,11 +1343,13 @@ function buildRegistriesYaml(registryEnabled: boolean): string | null {
  * binds the cluster container's `:5000` directly — the same trick
  * Traefik uses — so peer services reach it at `<cluster-key>.internal:5000`
  * (the cluster service's own alias) and the node's own containerd reaches
- * it at `127.0.0.1:5000`. Storage is an `emptyDir`, so pushed images live
- * in the cluster and are captured by snapshot / isolated per test fork
- * like all other in-VM state.
+ * it at `127.0.0.1:5000`. Storage is an `emptyDir` by default. Declared
+ * publications use a rootfs directory plus a read-only content mount; both
+ * variants keep writable registry state outside persistent image caches and
+ * capture it with the VM snapshot, isolated per test fork.
  */
-const REGISTRY_MANIFEST = `apiVersion: apps/v1
+function registryManifest(seeded: boolean): string {
+  return `apiVersion: apps/v1
 kind: Deployment
 metadata:
   name: spectest-registry
@@ -1347,11 +1372,13 @@ spec:
       - operator: Exists
       containers:
       - name: registry
-        image: registry:2
+        image: ${seeded ? REGISTRY_IMAGE : "registry:2"}
         imagePullPolicy: IfNotPresent
         env:
         - name: REGISTRY_HTTP_ADDR
           value: ":${K3S_REGISTRY_PORT}"
+        - name: REGISTRY_HTTP_RELATIVEURLS
+          value: "true"
         - name: REGISTRY_STORAGE_DELETE_ENABLED
           value: "true"
         ports:
@@ -1360,10 +1387,20 @@ spec:
         volumeMounts:
         - name: data
           mountPath: /var/lib/registry
-      volumes:
+${seeded ? `        - name: content
+          mountPath: ${REGISTRY_CONTENT}
+          readOnly: true
+` : ""}      volumes:
       - name: data
-        emptyDir: {}
+${seeded ? `        hostPath:
+          path: ${REGISTRY_DATA}
+          type: Directory
+      - name: content
+        hostPath:
+          path: ${REGISTRY_CONTENT}
+          type: Directory` : "        emptyDir: {}"}
 `;
+}
 
 // ────────────────────────────────────────────────────────────────────────
 // Apply — server-side, converging
@@ -1883,7 +1920,7 @@ async function waitForJob(
 async function setupK3sCluster(
   name: string,
   helpers: K3sHelpers,
-  opts: { registry: boolean; ingressDomains: string[]; traefik: boolean },
+  opts: { registry: boolean; ingressDomains: string[]; traefik: boolean; seed?: () => Promise<void> },
 ): Promise<void> {
   // The registry can start while Traefik's certificates are being prepared.
   const wait = (deployment: string): Promise<void> =>
@@ -1927,7 +1964,8 @@ async function setupK3sCluster(
     })(),
     (async () => {
       if (!opts.registry) return;
-      await helpers.apply(REGISTRY_MANIFEST);
+      await opts.seed?.();
+      await helpers.apply(registryManifest(!!opts.seed));
       await wait("spectest-registry");
     })(),
   ]);
@@ -2061,6 +2099,16 @@ export function k3s(opts: K3sOptions = {}) {
   const extra = opts.extraArgs ?? [];
   assertUsableExtraArgs(extra);
   const registryEnabled = opts.registry !== false;
+  let registryHost: string | undefined;
+  if (opts.registry !== undefined && typeof opts.registry !== "boolean") {
+    if (!opts.registry || typeof opts.registry.host !== "string" || opts.registry.host.startsWith("*.")) {
+      throw new Error("k3s(): registry must be a boolean or { host: an exact DNS hostname }");
+    }
+    // Reuse ingress validation (no scheme, port, path, or reserved .internal).
+    registryHost = dnsName(opts.registry.host, { ingress: true }).hostname;
+  }
+  const isPublished = (reference: string) => !!registryHost && reference.startsWith(`${registryHost}/`);
+  const publishBuilds = images.builds.filter(image => isPublished(image.reference));
   const traefikEnabled = opts.traefik !== false;
   const loadBalancerEnabled = opts.loadBalancer !== false;
   // Wildcard ingress domains. Drives both the `provides(... dnsName)`
@@ -2070,12 +2118,13 @@ export function k3s(opts: K3sOptions = {}) {
   // `/etc/rancher/k3s/registries.yaml` (host-cache mirrors + trust for
   // the in-cluster registry). Seeded via `files` because k3s reads it
   // only at startup, before any setup hook could run.
-  const registriesYaml = buildRegistriesYaml(registryEnabled);
+  const registriesYaml = buildRegistriesYaml(registryEnabled, registryHost);
   // The environment's image cache, when this VM carries one: the
   // cluster's store goes on its root disk and its layers come off the
   // shared layers disk (see the store section above).
   const sticky = stickyDiskPathSync();
   const cache = sticky ? null : imageCachePathsSync();
+  const contentDirectory = `${sticky ? `${sticky}/containerd` : cache?.root ?? "/var/lib/containerd"}/${CONTENT_BLOBS}`;
   const serverArgs = [
     "k3s",
     "server",
@@ -2175,6 +2224,7 @@ export function k3s(opts: K3sOptions = {}) {
   const def = {
     image: { type: "registry", reference: `rancher/k3s:${version}` },
     imageBuilds: images.builds,
+    tls: registryHost ? [{ hostname: registryHost, port: K3S_REGISTRY_PORT }] : [],
     command: cmd,
     privileged: true,
     tmpfs: ["/run", "/var/run"],
@@ -2196,7 +2246,7 @@ export function k3s(opts: K3sOptions = {}) {
     // in one environment get separate roots either way (the service
     // token names the directory), because two containerd daemons cannot
     // share a store: bolt takes an exclusive lock.
-    volumes: sticky
+    volumes: [...(sticky
       ? [{ source: `${stickyKubernetesDirectory(SELF_SERVICE_TOKEN, version)}/containerd`, target: CLUSTER_STORE_TARGET }]
       : cache ? [
           { source: nestedStoreDir(cache, SELF_SERVICE_TOKEN), target: CLUSTER_STORE_TARGET },
@@ -2204,7 +2254,12 @@ export function k3s(opts: K3sOptions = {}) {
           { source: MKFS_EROFS_PATH, target: MKFS_EROFS_PATH, readOnly: true },
           { source: STORE_ADOPT_PATH, target: STORE_ADOPT_PATH, readOnly: true },
         ]
-      : [{ target: CLUSTER_STORE_TARGET }],
+      : [{ target: CLUSTER_STORE_TARGET }]),
+      ...(publishBuilds.length ? [
+        { source: registryDirectory(SELF_SERVICE_TOKEN), target: REGISTRY_DATA },
+        { source: contentDirectory, target: REGISTRY_CONTENT, readOnly: true },
+      ] : []),
+    ],
     files: [
       ...(registriesYaml ? [{ path: "/etc/rancher/k3s/registries.yaml", content: registriesYaml }] : []),
       ...(cache
@@ -2223,49 +2278,56 @@ export function k3s(opts: K3sOptions = {}) {
       const { name, helpers, exec } = ctx;
       const runtime = componentRuntime(ctx);
       if (images.builds.length && !runtime) throw new Error(`k3s(${name}): prepared image inputs are missing`);
-      await waitForAll([
-        runtime ? loadK3sBuildImages(name, runtime.images, runtime.gateway, exec) : Promise.resolve(),
-        prePullK3sImages(name, images.pulls, exec),
-        (async () => {
-          if (runtime?.caBundle && caPresent()) {
-            const { cert, key } = await issueIngressCert([runtime.gateway]);
-            await installPodTrust({ name, gateway: runtime.gateway, cert, key,
-              ca: await readFile(CA_PATH, "utf8"), bundle: await readFile(runtime.caBundle, "utf8"),
-            }, {
-              apply: async configuration => { await helpers.apply(JSON.stringify(configuration)); },
-              ensureBundle: async (namespace, configMap, bundle) => {
-                try {
-                  await helpers.client.core.createNamespacedConfigMap({ namespace, body: {
-                    metadata: { name: configMap, namespace }, immutable: true, data: { "ca-bundle.crt": bundle },
-                  } });
-                } catch (err) {
-                  // A simultaneous Pod may have created the same namespace's bundle.
-                  const existing = (await helpers.client.core.readNamespacedConfigMap({ namespace, name: configMap })).unwrap();
-                  if (existing.data?.["ca-bundle.crt"] !== bundle || existing.immutable !== true) throw err;
-                }
-              },
-            });
-            // The API server observes webhook registration asynchronously. A dry-run
-            // Pod proves TLS reachability and admission before any project workload.
-            const deadline = Date.now() + 30_000;
-            for (;;) {
+      const infrastructure = (async () => {
+        if (runtime?.caBundle && caPresent()) {
+          const { cert, key } = await issueIngressCert([runtime.gateway]);
+          await installPodTrust({ name, gateway: runtime.gateway, cert, key,
+            ca: await readFile(CA_PATH, "utf8"), bundle: await readFile(runtime.caBundle, "utf8"),
+          }, {
+            apply: async configuration => { await helpers.apply(JSON.stringify(configuration)); },
+            ensureBundle: async (namespace, configMap, bundle) => {
               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" }] },
-                } })).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`);
+                await helpers.client.core.createNamespacedConfigMap({ namespace, body: {
+                  metadata: { name: configMap, namespace }, immutable: true, data: { "ca-bundle.crt": bundle },
+                } });
               } catch (err) {
-                if (Date.now() >= deadline) throw err;
+                // A simultaneous Pod may have created the same namespace's bundle.
+                const existing = (await helpers.client.core.readNamespacedConfigMap({ namespace, name: configMap })).unwrap();
+                if (existing.data?.["ca-bundle.crt"] !== bundle || existing.immutable !== true) throw err;
               }
-              await new Promise(resolve => setTimeout(resolve, 100));
+            },
+          });
+          // The API server observes webhook registration asynchronously. A dry-run
+          // Pod proves TLS reachability and admission before any project workload.
+          const deadline = Date.now() + 30_000;
+          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" }] },
+              } })).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`);
+            } catch (err) {
+              if (Date.now() >= deadline) throw err;
             }
+            await new Promise(resolve => setTimeout(resolve, 100));
           }
-          await setupK3sCluster(name, helpers, {
-            registry: registryEnabled,
-            ingressDomains,
-            traefik: traefikEnabled,
-          });
+        }
+        await setupK3sCluster(name, helpers, {
+          registry: registryEnabled,
+          seed: publishBuilds.length ? () => seedRegistry(name, contentDirectory,
+            runtime!.images.filter(image => isPublished(image.reference))) : undefined,
+          ingressDomains,
+          traefik: traefikEnabled,
+        });
+      })();
+      await waitForAll([
+        runtime ? loadK3sBuildImages(name, runtime.images, runtime.gateway, exec) : Promise.resolve(),
+        prePullK3sImages(name, images.pulls.filter(ref => !isPublished(ref)), exec),
+        (async () => {
+          // Registry-local references must not race registry startup/publication.
+          await infrastructure;
+          await prePullK3sImages(name, images.pulls.filter(isPublished), exec);
         })(),
       ]);
       if (sticky) await registerStickyKubernetesStore(name, version);

package/src/daemon.ts

@@ -2417,6 +2417,9 @@ function bindIngressServer(
     // {@link stopIngressServers} depends on: a half-alive listener shares
     // the port silently instead of colliding loudly.
     reusePort: true,
+    // OCI layer uploads can exceed Bun's default 128 MiB request limit.
+    // Large proxy bodies stream through; this limit does not allocate a buffer.
+    maxRequestBodySize: 1024 ** 4,
     // Bun.serve defaults to a 10s idleTimeout, which kills any proxied
     // request whose upstream takes >10s to produce bytes — under parallel
     // test load that surfaced as "fetch failed"/"other side closed" on

package/src/harness/built-image.ts

@@ -0,0 +1,53 @@
+/** Read build results without reserializing manifests or exporting layers. */
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { promisify } from "node:util";
+import { canonicalImageReference } from "./component-images.js";
+
+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")}`;
+const descriptor = (bytes: Uint8Array, mediaType: string): Descriptor => ({ digest: digest(bytes), size: bytes.length, mediaType });
+const run = promisify(execFile);
+const HOST_CTR = ["--address", "/run/containerd/containerd.sock", "--namespace", "moby"];
+
+async function hostContent(id: string): Promise<Buffer> {
+  if (!/^sha256:[a-f0-9]{64}$/.test(id)) throw new Error(`invalid content digest ${id}`);
+  const result = await run("ctr", [...HOST_CTR, "content", "get", id], { encoding: "buffer", maxBuffer: 16 * 1024 * 1024, timeout: 30_000 });
+  if (digest(result.stdout) !== id) throw new Error(`corrupt image metadata ${id}`);
+  return result.stdout;
+}
+
+/** Preserve the original index/manifest bytes and all application descriptors. */
+export async function hostImage(source: string) {
+  const name = canonicalImageReference(source);
+  const { stdout } = await run("ctr", [...HOST_CTR, "images", "ls", `name==${name}`], { timeout: 30_000 });
+  const found = stdout.split("\n").map(line => line.trim().split(/\s+/)).find(row => row[0] === name)?.[2];
+  if (!found) throw new Error(`built image ${name} is missing from the VM container store`);
+  const metadata = new Map<string, Buffer>();
+  const allowed = new Map<string, Descriptor>();
+  let configDigest: string | undefined;
+  async function visit(id: string, selected: boolean, depth = 0): Promise<Descriptor> {
+    if (depth > 4) throw new Error(`built image ${name} has a recursive manifest index`);
+    const bytes = await hostContent(id);
+    const obj = JSON.parse(bytes.toString());
+    const desc = descriptor(bytes, obj.mediaType);
+    metadata.set(id, bytes);
+    allowed.set(id, desc);
+    if (obj.config && Array.isArray(obj.layers)) {
+      const manifest = obj as Manifest;
+      for (const blob of [manifest.config, ...manifest.layers]) allowed.set(blob.digest, blob);
+      if (selected) configDigest = manifest.config.digest;
+    } else if (Array.isArray(obj.manifests)) {
+      for (const entry of obj.manifests as Descriptor[]) {
+        const matches = !entry.platform || (entry.platform.os === "linux" && entry.platform.architecture === (process.arch === "arm64" ? "arm64" : "amd64"));
+        await visit(entry.digest, selected && matches, depth + 1);
+      }
+    } else throw new Error(`built image ${name} has invalid image metadata`);
+    return desc;
+  }
+  const target = await visit(found, true);
+  if (!configDigest) throw new Error(`built image ${name} has no image for this VM's platform`);
+  return { target, metadata, allowed, configDigest };
+}
+

package/src/harness/k3s-image-loader.ts

@@ -1,62 +1,17 @@
 /** A short-lived, read-only OCI endpoint over the host containerd content store.
  * k3s fetches only missing blobs and unpacks only missing snapshots. No Docker
  * archive, staging registry, or second persistent copy of application blobs. */
-import { execFile, spawn } from "node:child_process";
+import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import { createServer } from "node:http";
-import { promisify } from "node:util";
 import type { SpectestContext } from "../index.js";
 import { canonicalImageReference, type PreparedComponentImage } from "./component-images.js";
 import { waitForK3sRuntime } from "./k3s-prepull.js";
+import { hostImage } from "./built-image.js";
 import { waitForAll } from "./concurrency.js";
 
-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")}`;
-const descriptor = (bytes: Uint8Array, mediaType: string): Descriptor => ({ digest: digest(bytes), size: bytes.length, mediaType });
-const run = promisify(execFile);
 const HOST_CTR = ["--address", "/run/containerd/containerd.sock", "--namespace", "moby"];
 
-async function hostContent(id: string): Promise<Buffer> {
-  if (!/^sha256:[a-f0-9]{64}$/.test(id)) throw new Error(`invalid content digest ${id}`);
-  const result = await run("ctr", [...HOST_CTR, "content", "get", id], { encoding: "buffer", maxBuffer: 16 * 1024 * 1024, timeout: 30_000 });
-  if (digest(result.stdout) !== id) throw new Error(`corrupt image metadata ${id}`);
-  return result.stdout;
-}
-
-/** Preserve the original index/manifest bytes and all application descriptors. */
-async function hostImage(source: string) {
-  const name = canonicalImageReference(source);
-  const { stdout } = await run("ctr", [...HOST_CTR, "images", "ls", `name==${name}`], { timeout: 30_000 });
-  const found = stdout.split("\n").map(line => line.trim().split(/\s+/)).find(row => row[0] === name)?.[2];
-  if (!found) throw new Error(`built image ${name} is missing from the VM container store`);
-  const metadata = new Map<string, Buffer>();
-  const allowed = new Map<string, Descriptor>();
-  let configDigest: string | undefined;
-  async function visit(id: string, selected: boolean, depth = 0): Promise<Descriptor> {
-    if (depth > 4) throw new Error(`built image ${name} has a recursive manifest index`);
-    const bytes = await hostContent(id);
-    const obj = JSON.parse(bytes.toString());
-    const desc = descriptor(bytes, obj.mediaType);
-    metadata.set(id, bytes);
-    allowed.set(id, desc);
-    if (obj.config && Array.isArray(obj.layers)) {
-      const manifest = obj as Manifest;
-      for (const blob of [manifest.config, ...manifest.layers]) allowed.set(blob.digest, blob);
-      if (selected) configDigest = manifest.config.digest;
-    } else if (Array.isArray(obj.manifests)) {
-      for (const entry of obj.manifests as Descriptor[]) {
-        const matches = !entry.platform || (entry.platform.os === "linux" && entry.platform.architecture === (process.arch === "arm64" ? "arm64" : "amd64"));
-        await visit(entry.digest, selected && matches, depth + 1);
-      }
-    } else throw new Error(`built image ${name} has invalid image metadata`);
-    return desc;
-  }
-  const target = await visit(found, true);
-  if (!configDigest) throw new Error(`built image ${name} has no image for this VM's platform`);
-  return { target, metadata, allowed, configDigest };
-}
-
 export async function loadK3sBuildImages(
   service: string, images: readonly PreparedComponentImage[],
   gateway: string, exec: SpectestContext["exec"],

package/src/harness/registry-seed.test.ts

@@ -0,0 +1,60 @@
+import { afterEach, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import { mkdtemp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { seedRegistryImage } from "./registry-seed";
+import type { Descriptor } from "./built-image";
+
+const roots: string[] = [];
+afterEach(async () => { await Promise.all(roots.splice(0).map(root => rm(root, { recursive: true, force: true }))); });
+
+async function fixture() {
+  const root = await mkdtemp(join(tmpdir(), "registry-seed-")); roots.push(root);
+  const content = `${root}/content`; await mkdir(content);
+  const metadata = new Map<string, Buffer>(), allowed = new Map<string, Descriptor>();
+  async function blob(value: string, mediaType: string, manifest = false) {
+    const bytes = Buffer.from(value);
+    const digest = `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+    const descriptor = { digest, size: bytes.length, mediaType };
+    await writeFile(`${content}/${digest.slice(7)}`, bytes);
+    allowed.set(digest, descriptor);
+    if (manifest) metadata.set(digest, bytes);
+    return descriptor;
+  }
+  const config = await blob('{"rootfs":{"type":"layers","diff_ids":[]}}', "application/vnd.oci.image.config.v1+json");
+  const layer = await blob("layer bytes", "application/vnd.oci.image.layer.v1.tar");
+  const manifestType = "application/vnd.oci.image.manifest.v1+json";
+  const manifest = await blob(JSON.stringify({ schemaVersion: 2, mediaType: manifestType, config, layers: [layer] }), manifestType, true);
+  const indexType = "application/vnd.oci.image.index.v1+json";
+  const target = await blob(JSON.stringify({ schemaVersion: 2, mediaType: indexType, manifests: [manifest] }), indexType, true);
+  return { root, content, layer, image: { target, metadata, allowed, configDigest: config.digest } };
+}
+
+test("seeding preserves index/manifest bytes and shares blobs while repository state stays separate", async () => {
+  const { root, content, image } = await fixture();
+  for (const name of ["a", "b"]) {
+    await seedRegistryImage(`${root}/${name}`, content, "registry.test/team/code:latest", image, content);
+  }
+  const base = "/docker/registry/v2";
+  for (const id of image.allowed.keys()) {
+    const hex = id.slice(7), path = `${base}/blobs/sha256/${hex.slice(0, 2)}/${hex}/data`;
+    expect(await readFile(`${root}/a${path}`)).toEqual(await readFile(`${content}/${hex}`));
+    expect((await stat(`${root}/a${path}`)).ino).toBe((await stat(`${root}/b${path}`)).ino);
+  }
+  const tag = `${base}/repositories/team/code/_manifests/tags/latest/current/link`;
+  expect(await readFile(`${root}/a${tag}`, "utf8")).toBe(image.target.digest);
+  await writeFile(`${root}/a${tag}`, `sha256:${"f".repeat(64)}`);
+  expect(await readFile(`${root}/b${tag}`, "utf8")).toBe(image.target.digest);
+  // A new environment seeded against the same cached blobs has only its declaration.
+  await seedRegistryImage(`${root}/fresh`, content, "registry.test/team/code:latest", image, content);
+  expect(await readdir(`${root}/fresh${base}/repositories/team/code/_manifests/tags`)).toEqual(["latest"]);
+  expect(await readFile(`${root}/fresh${tag}`, "utf8")).toBe(image.target.digest);
+});
+
+test("an incomplete cached build cannot publish a usable tag", async () => {
+  const { root, content, image, layer } = await fixture();
+  await writeFile(`${content}/${layer.digest.slice(7)}`, "truncated");
+  await expect(seedRegistryImage(`${root}/data`, content, "registry.test/code:latest", image, content)).rejects.toThrow("incomplete");
+  expect(await Bun.file(`${root}/data/docker/registry/v2/repositories/code/_manifests/tags/latest/current/link`).exists()).toBe(false);
+});

package/src/harness/registry-seed.ts

@@ -0,0 +1,61 @@
+/** 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. */
+import { mkdir, stat, symlink, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { hostImage } from "./built-image.js";
+import { canonicalImageReference, type PreparedComponentImage } 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 registryDirectory = (service: string) => `/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.
+ * The prepared build's containerd image record retains the referenced blobs. */
+export async function seedRegistryImage(
+  directory: string, contentDirectory: string, reference: string,
+  image: Awaited<ReturnType<typeof hostImage>>,
+  mountedContent = REGISTRY_CONTENT,
+): Promise<void> {
+  const canonical = canonicalImageReference(reference);
+  if (canonical.includes("@")) throw new Error("registry publication must name a tag");
+  const repository = canonical.slice(canonical.indexOf("/") + 1, canonical.lastIndexOf(":"));
+  const tag = canonical.slice(canonical.lastIndexOf(":") + 1);
+  const root = `${directory}/docker/registry/v2`;
+  const repo = `${root}/repositories/${repository}`;
+  const link = async (path: string, value: string) => {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, value);
+  };
+  for (const [id, descriptor] of image.allowed) {
+    if (!/^sha256:[a-f0-9]{64}$/.test(id)) throw new Error(`invalid registry seed digest ${id}`);
+    const hex = id.slice(7);
+    const info = await stat(`${contentDirectory}/${hex}`);
+    if (!info.isFile() || info.size !== descriptor.size) throw new Error(`missing or incomplete registry seed blob ${id}`);
+    const destination = `${root}/blobs/sha256/${hex.slice(0, 2)}/${hex}/data`;
+    await mkdir(dirname(destination), { recursive: true });
+    try { await symlink(`${mountedContent}/${hex}`, destination); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+    await link(`${repo}/_layers/sha256/${hex}/link`, id);
+    if (image.metadata.has(id)) await link(`${repo}/_manifests/revisions/sha256/${hex}/link`, id);
+  }
+  const id = image.target.digest;
+  await link(`${repo}/_manifests/tags/${tag}/index/sha256/${id.slice(7)}/link`, id);
+  await link(`${repo}/_manifests/tags/${tag}/current/link`, id);
+}
+
+export async function seedRegistry(
+  service: string, contentDirectory: string, images: readonly PreparedComponentImage[],
+): Promise<void> {
+  // Sequential metadata updates avoid races when several tags share blobs.
+  // Builds themselves still run concurrently with all environment preparation.
+  for (const image of images) {
+    await image.ready;
+    const built = await hostImage(image.source);
+    await seedRegistryImage(registryDirectory(service), contentDirectory, image.reference, built);
+    console.log(`[k3s-registry] ${service}: ${image.reference} @ ${built.target.digest} (cached blobs, no export)`);
+  }
+}

package/src/index.ts

@@ -1250,7 +1250,8 @@ export type BuildImage = (
 ) & {
   /** Full image reference, e.g. "k8s.internal:5000/runtime:spectest".
    * Optional for a service; required for a Kubernetes build. This names a
-   * local image and does not publish it to a registry. */
+   * local image. In k3s, builds targeting `registry.host` are also published
+   * to that component's registry; other references are only preloaded. */
   reference?: string;
 };