@specific.dev/spectest 0.92.0 → 0.93.0

package/src/daemon.ts

@@ -1,3 +1,4 @@
+import { generateHostCert as mintHostCert } from "./harness/certificate.js";
 import { componentBuildTasks, COMPONENT_RUNTIME } from "./harness/component-images.js";
 import { waitForAll } from "./harness/concurrency.js";
 import { androidScope, androidRecordingChunk, releaseAndroidRecording, isAndroidApp, type AndroidRecording } from "./android.js";
@@ -89,7 +90,7 @@ import {
   serviceDockerignore as composeServiceDockerignore,
   unionDockerignore,
 } from "./harness/build-context.js";
-import { validateServiceGraph as validateGraph } from "./harness/service-graph.js";
+import { startServices } from "./harness/service-graph.js";
 import {
   casesMetadata as catalogueCases,
   groupsMetadata as catalogueGroups,
@@ -1859,35 +1860,6 @@ async function withContainerPostMortem(name: string, err: unknown): Promise<unkn
   }
 }
 
-/** Validate the `dependsOn` graph and return the name→service map used to
- *  walk it. Rules live in `harness/service-graph.ts`. */
-function validateServiceGraph(services: NamedService[]): Map<string, NamedService> {
-  return validateGraph(services);
-}
-
-async function startServices(
-  services: NamedService[],
-  startOne: (svc: NamedService) => Promise<void>,
-): Promise<void> {
-  const byName = validateServiceGraph(services);
-  const started = new Map<string, Promise<void>>();
-  const start = (svc: NamedService): Promise<void> => {
-    const existing = started.get(svc.name);
-    if (existing) return existing;
-    const p = (async () => {
-      await Promise.all(
-        (svc.dependsOn ?? [])
-          .filter((d) => byName.has(d))
-          .map((d) => start(byName.get(d)!)),
-      );
-      await startOne(svc);
-    })();
-    started.set(svc.name, p);
-    return p;
-  };
-  await Promise.all(services.map(start));
-}
-
 // ────────────────────────────────────────────────────────────────────────
 // Ingress — in-daemon HTTP/HTTPS listeners that route by Host header.
 //
@@ -2057,72 +2029,6 @@ function buildIngress(project: Project): void {
   }
 }
 
-/**
- * Generate a leaf cert + key for one ingress route (fake or service
- * proxy), signed by the in-VM root CA at {CA_PATH}. 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 short tag baked into the cert Subject CN and the temp
- * file names — only used for diagnostics, not for TLS verification.
- */
-async function generateHostCert(
-  label: string,
-  hostnames: string[],
-): Promise<{ cert: string; key: string }> {
-  const id = `spectest-host-${sanitizeSegment(label)}-${randomUUID().slice(0, 8)}`;
-  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",
-    CA_PATH,
-    "-CAkey",
-    CA_KEY_PATH,
-    "-days",
-    "3650",
-    "-subj",
-    `/CN=spectest-${label}`,
-    "-addext",
-    `subjectAltName=${sans}`,
-    "-addext",
-    "basicConstraints=CA:FALSE",
-    "-addext",
-    "extendedKeyUsage=serverAuth",
-    "-addext",
-    "keyUsage=digitalSignature,keyEncipherment",
-  ];
-  const r = await shx("openssl", args, 30_000);
-  if (r.code !== 0) {
-    throw new Error(
-      `openssl req for ${label} failed (rc=${r.code}): ${r.stderr.trim() || r.stdout.trim()}`,
-    );
-  }
-  try {
-    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(() => {}),
-    ]);
-  }
-}
-
 /** Resolve the spectest-net bridge gateway IP — the address containers
  * use to reach the VM host. Asks dockerd via the docker CLI; cached for
  * the daemon's life because the network is recreated only on reload. */
@@ -2165,7 +2071,11 @@ type Route = IngressRoute<FakeRuntime>;
  */
 const NATIVE_FETCH: typeof fetch = globalThis.fetch.bind(globalThis);
 
-/** Hop-by-hop headers per RFC 7230 §6.1 — never forwarded by a proxy. */
+/** Mint ingress and container certificates with the environment CA. */
+function generateHostCert(label: string, hostnames: string[]): Promise<{ cert: string; key: string }> {
+  return mintHostCert(label, hostnames, CA_PATH, CA_KEY_PATH);
+}
+
 async function startIngress(): Promise<void> {
   const hasIngress =
     FAKES.size > 0 ||
@@ -2507,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
@@ -3519,9 +3432,13 @@ async function bootstrap(prepared?: PreparedImages): Promise<BootstrapTimings> {
   // hook's — into the boot log, so GET /boot-log can explain a slow or
   // finished boot. Restored in the finally at the end.
   const restoreBootLog = captureConsole(BOOT_LOG_SINK);
+  // One dispatcher for the whole bootstrap: service hooks run concurrently.
+  // Only each hook's async scope opts into wrapped fetch responses.
+  const restoreFetch = installFetchWrapper();
   try {
     return await bootstrapInner(prepared);
   } finally {
+    restoreFetch();
     restoreBootLog();
   }
 }
@@ -3695,20 +3612,25 @@ async function bootstrapInner(prepared?: PreparedImages, identity?: string): Pro
     await waitForAll([...builds.map(task => prep.get(task.name)!), (async () => {
       if (svc.setup) {
         progressService(svc.name, { status: "probing", detail: "running setup" });
-        const helpers = await ensureHelpers(svc.name, svc);
+        const fetchScope = createInstrumentationScope(false);
         try {
-          await svc.setup({
-            name: svc.name,
-            helpers,
-            ...(await spectestContext({ service: svc.name, includeSelf: true })),
-            ...{ [COMPONENT_RUNTIME]: {
-              images: builds.map(task => ({ source: imageTag(task.name), reference: task.reference, ready: prep.get(task.name)! })),
-              gateway: await bridgeGatewayIp(),
-              caBundle: await ensureCaBundle(),
-            } },
+          await runInstrumented(fetchScope, async () => {
+            const helpers = await ensureHelpers(svc.name, svc);
+            await svc.setup!({
+              name: svc.name,
+              helpers,
+              ...(await spectestContext({ service: svc.name, includeSelf: true })),
+              ...{ [COMPONENT_RUNTIME]: {
+                images: builds.map(task => ({ source: imageTag(task.name), reference: task.reference, ready: prep.get(task.name)! })),
+                gateway: await bridgeGatewayIp(),
+                caBundle: await ensureCaBundle(),
+              } },
+            });
           });
         } catch (err) {
           throw await withContainerPostMortem(svc.name, err);
+        } finally {
+          fetchScope.active = false;
         }
       }
     })()]);
@@ -4857,7 +4779,7 @@ async function spectestContext(scope: ContextScope = {}): Promise<SpectestContex
     exec: (service, command, opts) =>
       componentExec(service, command, opts, execTimeoutMs),
     // Read `globalThis.fetch` at call time: the wrapper is installed for
-    // the duration of a test / eval / project setup, so a context built
+    // the duration of bootstrap / a test / eval / project setup, so a context built
     // before it lands still gets the wrapped one.
     fetch: ((input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) =>
       globalThis.fetch(input, init)) as unknown as SpectestContext["fetch"],

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/certificate.test.ts

@@ -0,0 +1,31 @@
+import { expect, test } from "bun:test";
+import { X509Certificate } from "node:crypto";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { generateHostCert } from "./certificate.js";
+
+test("long ingress names retain their full SAN while the diagnostic CN stays bounded", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "spectest-leaf-"));
+  const ca = join(dir, "ca.crt");
+  const key = join(dir, "ca.key");
+  try {
+    const root = Bun.spawnSync(["openssl", "req", "-x509", "-newkey", "rsa:2048",
+      "-nodes", "-days", "1", "-subj", "/CN=test-ca", "-keyout", key, "-out", ca]);
+    expect(root.exitCode, root.stderr.toString()).toBe(0);
+    // Long enough to exceed both the former CN and temporary filename limits.
+    const host = `${"a".repeat(63)}.${"b".repeat(63)}.${"c".repeat(63)}.${"d".repeat(61)}`;
+    const { cert, key: leafKey } = await generateHostCert(host, [host, "*.example.test"], ca, key);
+    const leaf = new X509Certificate(cert);
+    expect(leaf.subject.length).toBeLessThanOrEqual(67); // "CN=" + 64 bytes
+    expect(leaf.checkHost(host)).toBe(host);
+    expect(leaf.checkHost("api.example.test")).toBe("*.example.test");
+    expect(leafKey).toContain("PRIVATE KEY");
+    const file = join(dir, "leaf.crt");
+    await writeFile(file, cert);
+    const verified = Bun.spawnSync(["openssl", "verify", "-CAfile", ca, "-verify_hostname", host, file]);
+    expect(verified.exitCode, verified.stderr.toString()).toBe(0);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}, 10_000);

package/src/harness/certificate.ts

@@ -0,0 +1,73 @@
+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: string,
+  hostnames: string[],
+  caPath: string,
+  caKeyPath: string,
+): Promise<{ cert: string; key: string }> {
+  // 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/src/harness/eval-typecheck.test.ts

@@ -50,6 +50,34 @@ function run(command: string, args: string[], timeout: number): Promise<{ code:
 const opts = () => ({ appDir, file, projectEntry, typecheckDir, run });
 const query = 'const rows = await ctx.svc.supabase.sql<{ analyzed: boolean }>`SELECT true AS analyzed`;';
 
+test("annotated services keep helper types while literals without helpers stay absent", async () => {
+  await fs.writeFile(projectEntry, `
+import { defineEnvironment, type ServiceDefinition } from "@specific.dev/spectest";
+interface Helpers { value(): number }
+const annotated: ServiceDefinition<Helpers> = {
+  image: "example:latest", helpers: async () => ({ value: () => 42 }),
+};
+const checked = { image: "example:latest", helpers: () => ({ value: () => 42 }) } satisfies ServiceDefinition<Helpers>;
+const env = defineEnvironment({ name: "helpers", services: {
+  annotated, checked, plain: { image: "example:latest" },
+  absent: { image: "example:latest", helpers: undefined },
+} });
+export default env.project([]);
+`);
+  await fs.writeFile(file, `
+const a: number = ctx.svc.annotated.value();
+const b: number = ctx.svc.checked.value();
+// @ts-expect-error plain services have no handle
+ctx.svc.plain;
+// @ts-expect-error explicitly absent helpers have no handle either
+ctx.svc.absent;
+// @ts-expect-error helper return type must not widen to any
+const wrong: string = ctx.svc.annotated.value();
+export default a + b;
+`);
+  expect(await checkEval(opts())).toMatchObject({ status: "ok", errors: [], totalErrors: 0 });
+}, 30_000);
+
 test("eval receives the default-exported project's service/fake types and globals", async () => {
   await fs.writeFile(file, `${query}
 const ready: boolean = rows[0].analyzed.unwrap();

package/src/harness/fetch.test.ts

@@ -3,6 +3,7 @@ import { expect as assertValue } from "../index.js";
 import { readRaw, readTag, type SpectestFetch, type WrappedResponse } from "../inspect.js";
 import { recordFake, startRecording, stopRecording, type HttpEvent } from "../recorder.js";
 import { installFetchWrapper, isTransportError } from "./fetch.js";
+import { startServices } from "./service-graph.js";
 import {
   bindInstrumentationScope,
   createInstrumentationScope,
@@ -356,4 +357,31 @@ describe("fetch execution scopes", () => {
       setup.active = false;
     }
   });
+
+  test("parallel service setup scopes keep wrapping after a sibling fails", async () => {
+    const gate = deferred();
+    const slowStarted = deferred();
+    const setup = startServices([{ name: "bad" }, { name: "slow" }], async ({ name }) => {
+      const hookScope = createInstrumentationScope(false);
+      try {
+        await runInstrumented(hookScope, async () => {
+          if (name === "bad") { await slowStarted.promise; throw new Error("failed hook"); }
+          slowStarted.resolve();
+          await gate.promise;
+          const res = await fetch(url("/service-setup")) as unknown as WrappedResponse;
+          expect(res.status.unwrap()).toBe(200);
+          expect((await res.json<{ value: number }>()).value.unwrap()).toBe(42);
+          await runUninstrumented(async () => {
+            expect((await fetch(url("/fake"))).status).toBe(200);
+          });
+        });
+      } finally { hookScope.active = false; }
+    });
+    const outcome = setup.catch(error => error);
+    await slowStarted.promise;
+    expect((await fetch(url("/background"))).status).toBe(200);
+    gate.resolve();
+    expect((await outcome).message).toBe("failed hook");
+    expect(stopRecording()).toEqual([]);
+  });
 });

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)`);
+  }
+}