@specific.dev/spectest 0.92.0 → 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

@@ -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 } from "./android.js";
@@ -39,7 +40,7 @@ import { isDesktopApp } from "./desktop.js";
 // exact-then-longest-suffix rule and the one-label certificate rule are
 // each easy to restate subtly differently.
 import { buildArgFlags, buildContentKey as computeBuildContentKey, buildTargetFlags, imageTag, isGeneratedDockerignore, pickProjectIgnore, 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, } from "./harness/catalogue.js";
 import { summarizeBuildKit } from "./harness/buildkit-progress.js";
 import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta } from "./harness/log-delta.js";
@@ -1453,29 +1454,6 @@ async function withContainerPostMortem(name, err) {
         return err;
     }
 }
-/** Validate the `dependsOn` graph and return the name→service map used to
- *  walk it. Rules live in `harness/service-graph.ts`. */
-function validateServiceGraph(services) {
-    return validateGraph(services);
-}
-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 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.
 //
@@ -1625,67 +1603,6 @@ function buildIngress(project) {
         });
     }
 }
-/**
- * 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, hostnames) {
-    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. */
@@ -1719,7 +1636,10 @@ async function bridgeGatewayIp() {
  * that don't pass through as primitives.
  */
 const NATIVE_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, hostnames) {
+    return mintHostCert(label, hostnames, CA_PATH, CA_KEY_PATH);
+}
 async function startIngress() {
     const hasIngress = FAKES.size > 0 ||
         LOWERED.proxies.length > 0 ||
@@ -2038,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
@@ -2942,10 +2865,14 @@ async function bootstrap(prepared) {
     // 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();
     }
 }
@@ -3111,22 +3038,28 @@ async function bootstrapInner(prepared, identity) {
         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;
+                    }
                 }
             })()]);
         for (const task of builds)
@@ -4013,7 +3946,7 @@ async function spectestContext(scope = {}) {
         readProjectFileBytes: async (p) => new Uint8Array(await fs.readFile(resolveProjectPath(p))),
         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, init) => globalThis.fetch(input, init)),
         svc: handles,

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

@@ -0,0 +1,15 @@
+/**
+ * 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 declare function generateHostCert(label: string, hostnames: string[], caPath: string, caKeyPath: string): Promise<{
+    cert: string;
+    key: string;
+}>;