@specific.dev/spectest 0.92.0 → 0.93.0

package/dist/harness/certificate.js

@@ -0,0 +1,67 @@
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/**
+ * Generate a leaf cert + key for one ingress route (fake or service
+ * proxy), signed by the in-VM root CA. SANs cover every
+ * hostname the route answers to, so a client connecting with TLS
+ * verifies cleanly regardless of which hostname it used. Shells out
+ * to `openssl req -x509 -CA ... -CAkey ...` (OpenSSL 3.0+; Debian
+ * bookworm ships 3.0.x).
+ *
+ * `label` is a diagnostic tag baked into the cert Subject CN and the temp
+ * file names — only used for diagnostics, not for TLS verification.
+ */
+export async function generateHostCert(label, hostnames, caPath, caKeyPath) {
+    // CN is diagnostic only; SANs retain the full hostnames. Bound the label
+    // for both OpenSSL's 64-byte CN limit and filesystem component limits.
+    const commonName = `spectest-${label.replace(/[^a-zA-Z0-9.-]/g, "_").slice(0, 55)}`;
+    const id = `${commonName}-${randomUUID()}`;
+    const keyPath = path.join("/tmp", `${id}.key`);
+    const crtPath = path.join("/tmp", `${id}.crt`);
+    const sans = hostnames.map((h) => `DNS:${h}`).join(",");
+    const args = [
+        "req",
+        "-newkey",
+        "rsa:2048",
+        "-nodes",
+        "-keyout",
+        keyPath,
+        "-out",
+        crtPath,
+        "-x509",
+        "-CA",
+        caPath,
+        "-CAkey",
+        caKeyPath,
+        "-days",
+        "3650",
+        "-subj",
+        `/CN=${commonName}`,
+        "-addext",
+        `subjectAltName=${sans}`,
+        "-addext",
+        "basicConstraints=CA:FALSE",
+        "-addext",
+        "extendedKeyUsage=serverAuth",
+        "-addext",
+        "keyUsage=digitalSignature,keyEncipherment",
+    ];
+    try {
+        await execFileAsync("openssl", args, { timeout: 30_000 });
+        const [cert, key] = await Promise.all([
+            fs.readFile(crtPath, "utf8"),
+            fs.readFile(keyPath, "utf8"),
+        ]);
+        return { cert, key };
+    }
+    finally {
+        await Promise.all([
+            fs.unlink(keyPath).catch(() => { }),
+            fs.unlink(crtPath).catch(() => { }),
+        ]);
+    }
+}

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/harness/service-graph.d.ts

@@ -27,3 +27,6 @@ export declare function validateServiceGraph<T extends GraphNode>(services: read
  * graph is walkable at all.
  */
 export declare function topologicalOrder<T extends GraphNode>(services: readonly T[]): T[];
+/** Start each service after its dependencies finish setup. Drain all branches
+ * before reporting failure so teardown cannot race containers or hooks. */
+export declare function startServices<T extends GraphNode>(services: readonly T[], startOne: (svc: T) => Promise<void>): Promise<void>;

package/dist/harness/service-graph.js

@@ -1,12 +1,4 @@
-/**
- * The `dependsOn` graph: validation, and the traversal order bring-up
- * uses.
- *
- * Ported out of `daemon.ts`. Validation runs before anything starts, so
- * the DAG runner can assume a clean graph — an unknown dependency or a
- * cycle must be a clear error at load, not a container that never becomes
- * ready and eventually times out with no explanation.
- */
+import { waitForAll } from "./concurrency.js";
 /**
  * Check the graph and return the name→node map used to walk it.
  *
@@ -90,3 +82,21 @@ export function topologicalOrder(services) {
         visit(s.name);
     return out;
 }
+/** Start each service after its dependencies finish setup. Drain all branches
+ * before reporting failure so teardown cannot race containers or hooks. */
+export async function startServices(services, startOne) {
+    const byName = validateServiceGraph(services);
+    const started = new Map();
+    const start = (svc) => {
+        const existing = started.get(svc.name);
+        if (existing)
+            return existing;
+        const pending = (async () => {
+            await Promise.all((svc.dependsOn ?? []).map(name => start(byName.get(name))));
+            await startOne(svc);
+        })();
+        started.set(svc.name, pending);
+        return pending;
+    };
+    await waitForAll(services.map(start));
+}

package/dist/index.d.ts

@@ -590,11 +590,10 @@ export interface ServiceDefinition<H extends Record<string, any> = Record<string
  * the typecheck on any service declaring a hook, while the same literal
  * written inline passed. */
 export type ServicesMap = Record<string, ServiceDefinition<any>>;
-/** Awaited return type of a service's `helpers` factory, or `never` if
- * the service doesn't ship one. */
-type HelpersOf<D> = D extends {
-    helpers: (...args: any) => infer R;
-} ? Awaited<R> : never;
+/** Awaited return type of a service's helpers factory. Check key presence
+ * before removing optionality: annotations keep `helpers?`, while plain
+ * service literals with no factory must stay out of ctx.svc. */
+type HelpersOf<D> = "helpers" extends keyof D ? [NonNullable<D["helpers"]>] extends [never] ? never : NonNullable<D["helpers"]> extends (...args: any[]) => infer R ? Awaited<R> : never : never;
 /**
  * Per-service handles derived from a concrete services map. Only
  * services that ship a `helpers` factory appear here; `ctx.svc.<name>`
@@ -832,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.0",
+  "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);