@specific.dev/spectest 0.90.3 → 0.91.0

package/dist/components/expo.d.ts

@@ -103,6 +103,7 @@ export declare function nodeMajorFromRange(range: string): number | null;
 export declare function expo(opts?: ExpoOptions): {
     image: {
         type: "dockerfile";
+        reference?: string;
         path: string;
         content?: never;
         context?: string;
@@ -111,6 +112,7 @@ export declare function expo(opts?: ExpoOptions): {
         buildArgs?: Readonly<Record<string, string>>;
     } | {
         type: "dockerfile";
+        reference?: string;
         content: string;
         path?: never;
         context?: string;

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 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 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-trust.d.ts

@@ -0,0 +1,57 @@
+export declare const POD_CA_PATH = "/spectest/ca-bundle.crt";
+interface Container {
+    env?: {
+        name: string;
+        value?: string;
+        valueFrom?: unknown;
+    }[];
+    volumeMounts?: {
+        name: string;
+        mountPath: string;
+        subPath?: string;
+        readOnly?: boolean;
+    }[];
+}
+interface Pod {
+    metadata?: {
+        annotations?: Record<string, string>;
+    };
+    spec?: {
+        os?: {
+            name: string;
+        };
+        volumes?: {
+            name: string;
+            configMap?: {
+                name: string;
+            };
+            [key: string]: unknown;
+        }[];
+        containers?: Container[];
+        initContainers?: Container[];
+        ephemeralContainers?: Container[];
+    };
+}
+interface Patch {
+    op: "add";
+    path: string;
+    value: unknown;
+}
+export declare const TRUST_OPT_OUT = "spectest.dev/inject-ca";
+export declare function podTrustPatch(pod: Pod, configMap: string, ephemeral?: boolean): Patch[];
+export interface TrustDependencies {
+    /** Ensure this immutable ConfigMap exists in the requesting namespace. */
+    ensureBundle(namespace: string, name: string, bundle: string): Promise<void>;
+    apply(configuration: unknown): Promise<void>;
+}
+export declare function installPodTrust(options: {
+    name: string;
+    gateway: string;
+    bundle: string;
+    cert: string;
+    key: string;
+    ca: string;
+}, deps: TrustDependencies): Promise<void>;
+/** Release a component listener on replacement or in standalone tests. */
+export declare function stopPodTrust(name: string): void;
+export {};

package/dist/components/k3s-trust.js

@@ -0,0 +1,125 @@
+/** Pod trust belongs to the cluster. Admission adds read-only ConfigMap
+ * mounts and environment defaults, without changing any image bytes. */
+import { createHash, randomUUID } from "node:crypto";
+import { createServer } from "node:https";
+export const POD_CA_PATH = "/spectest/ca-bundle.crt";
+const TRUST_ENV = {
+    NODE_EXTRA_CA_CERTS: POD_CA_PATH, SSL_CERT_FILE: POD_CA_PATH,
+    REQUESTS_CA_BUNDLE: POD_CA_PATH, AWS_CA_BUNDLE: POD_CA_PATH,
+    PGSSLROOTCERT: POD_CA_PATH, DENO_TLS_CA_STORE: "mozilla,system",
+};
+const MOUNT_PATHS = [POD_CA_PATH, "/etc/ssl/certs/ca-certificates.crt", "/etc/pki/tls/certs/ca-bundle.crt"];
+export const TRUST_OPT_OUT = "spectest.dev/inject-ca";
+export function podTrustPatch(pod, configMap, ephemeral = false) {
+    if (!pod.spec || pod.spec.os?.name === "windows" || pod.metadata?.annotations?.[TRUST_OPT_OUT] === "false")
+        return [];
+    const patches = [];
+    const volumes = pod.spec.volumes ?? [];
+    // Reuse our immutable ConfigMap, but never overwrite a user's volume.
+    let volume = volumes.find(v => v.configMap?.name === configMap)?.name;
+    if (!volume && ephemeral)
+        return []; // Pod volumes cannot change on this subresource.
+    if (!volume) {
+        const names = new Set(volumes.map(v => v.name));
+        volume = "spectest-ca";
+        for (let n = 1; names.has(volume); n++)
+            volume = `spectest-ca-${n}`;
+        const value = { name: volume, configMap: { name: configMap, defaultMode: 0o444, items: [{ key: "ca-bundle.crt", path: "ca-bundle.crt" }] } };
+        patches.push(pod.spec.volumes
+            ? { op: "add", path: "/spec/volumes/-", value }
+            : { op: "add", path: "/spec/volumes", value: [value] });
+    }
+    const groups = ephemeral ? ["ephemeralContainers"] : ["containers", "initContainers"];
+    for (const group of groups) {
+        for (const [index, container] of (pod.spec[group] ?? []).entries()) {
+            const prefix = `/spec/${group}/${index}`;
+            const env = container.env ?? [];
+            const names = new Set(env.map(e => e.name));
+            const extraEnv = Object.entries(TRUST_ENV).filter(([name]) => !names.has(name)).map(([name, value]) => ({ name, value }));
+            const mounts = container.volumeMounts ?? [];
+            // A user mount at a path (or a parent directory) owns that path.
+            const extraMounts = MOUNT_PATHS.filter(path => !mounts.some(m => path === m.mountPath || path.startsWith(m.mountPath.replace(/\/$/, "") + "/")))
+                .map(mountPath => ({ name: volume, mountPath, subPath: "ca-bundle.crt", readOnly: true }));
+            if (extraEnv.length)
+                patches.push({ op: "add", path: `${prefix}/env`, value: [...env, ...extraEnv] });
+            if (extraMounts.length)
+                patches.push({ op: "add", path: `${prefix}/volumeMounts`, value: [...mounts, ...extraMounts] });
+        }
+    }
+    return patches;
+}
+const servers = new Map();
+export async function installPodTrust(options, deps) {
+    const configMap = `spectest-ca-${createHash("sha256").update(options.bundle).digest("hex").slice(0, 20)}`;
+    const endpoint = `/admit/${randomUUID()}`;
+    const server = createServer({ cert: options.cert, key: options.key }, async (req, res) => {
+        if (req.method !== "POST" || new URL(req.url ?? "/", "https://local").pathname !== endpoint) {
+            res.writeHead(404).end();
+            return;
+        }
+        const chunks = [];
+        let size = 0;
+        try {
+            for await (const chunk of req) {
+                size += chunk.length;
+                if (size > 2 * 1024 * 1024) {
+                    res.writeHead(413).end();
+                    return;
+                }
+                chunks.push(Buffer.from(chunk));
+            }
+            const review = JSON.parse(Buffer.concat(chunks).toString());
+            const request = review.request;
+            if (!request?.uid || request.resource?.resource !== "pods" || !request.object || !request.namespace) {
+                res.writeHead(400).end("invalid Pod admission request");
+                return;
+            }
+            const patch = podTrustPatch(request.object, configMap, request.subResource === "ephemeralcontainers");
+            // Dry runs return the same patch but perform no API writes.
+            if (patch.length && !request.dryRun)
+                await deps.ensureBundle(request.namespace, configMap, options.bundle);
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify({ apiVersion: "admission.k8s.io/v1", kind: "AdmissionReview", response: {
+                    uid: request.uid, allowed: true,
+                    ...(patch.length ? { patchType: "JSONPatch", patch: Buffer.from(JSON.stringify(patch)).toString("base64") } : {}),
+                } }));
+        }
+        catch (err) {
+            console.error(`[k3s-trust] ${options.name}: ${err instanceof Error ? err.message : err}`);
+            res.writeHead(500).end("could not mount the environment CA");
+        }
+    });
+    server.requestTimeout = 15_000;
+    try {
+        await new Promise((resolve, reject) => { server.once("error", reject); server.listen(0, options.gateway, resolve); });
+        const port = server.address().port;
+        await deps.apply({
+            apiVersion: "admissionregistration.k8s.io/v1", kind: "MutatingWebhookConfiguration",
+            metadata: { name: "spectest-pod-trust" },
+            webhooks: [{
+                    name: "pod-trust.spectest.dev", admissionReviewVersions: ["v1"],
+                    sideEffects: "NoneOnDryRun", failurePolicy: "Fail", timeoutSeconds: 10,
+                    reinvocationPolicy: "IfNeeded", matchPolicy: "Equivalent",
+                    clientConfig: { url: `https://${options.gateway}:${port}${endpoint}`, caBundle: Buffer.from(options.ca).toString("base64") },
+                    rules: [{ operations: ["CREATE"], apiGroups: [""], apiVersions: ["v1"], resources: ["pods"], scope: "Namespaced" },
+                        { operations: ["UPDATE"], apiGroups: [""], apiVersions: ["v1"], resources: ["pods/ephemeralcontainers"], scope: "Namespaced" }],
+                }],
+        });
+    }
+    catch (err) {
+        server.closeAllConnections();
+        server.close();
+        throw err;
+    }
+    const previous = servers.get(options.name);
+    servers.set(options.name, server);
+    previous?.closeAllConnections();
+    previous?.close();
+}
+/** Release a component listener on replacement or in standalone tests. */
+export function stopPodTrust(name) {
+    const server = servers.get(name);
+    servers.delete(name);
+    server?.closeAllConnections();
+    server?.close();
+}

package/dist/components/k3s.d.ts

@@ -1,8 +1,22 @@
 import { AppsV1Api, BatchV1Api, CoreV1Api, KubeConfig, PatchStrategy, type KubernetesListObject, type KubernetesObject, type V1DeleteOptions, type V1Job, type V1Status } from "@kubernetes/client-node";
-import type { ServiceHelpersContext } from "../index.js";
+import type { ServiceHelpersContext, ServiceSetupContext } from "../index.js";
+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";
+/** Kubernetes pods receive read-only environment CA mounts during admission.
+ * Image bytes and digests stay unchanged; explicit pod trust settings win. */
 export interface K3sOptions {
+    /** Images available to kubelet before project setup. Use registry strings,
+     * 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.
+     * 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;
+     * tags are resolved again on each fresh setup. Pod imagePullPolicy still applies.
+     */
+    images?: readonly KubernetesImage[];
     /**
      * Image tag for the official `rancher/k3s` image. Default
      * `"v1.33.5-k3s1"`. Any tag works; a k3s older than 1.33 embeds a
@@ -319,6 +333,7 @@ export declare function k3s(opts?: K3sOptions): {
         type: "registry";
         reference: string;
     };
+    imageBuilds: import("../index.js").ComponentImageBuild[];
     command: string;
     privileged: true;
     tmpfs: string[];
@@ -344,9 +359,6 @@ export declare function k3s(opts?: K3sOptions): {
         command: string;
         timeoutSecs: number;
     };
-    setup: ({ name, helpers }: {
-        name: string;
-        helpers: K3sHelpers;
-    }) => Promise<void>;
+    setup: (ctx: ServiceSetupContext<K3sHelpers>) => Promise<void>;
     helpers: ({ name, exec, poll }: ServiceHelpersContext) => Promise<K3sHelpers>;
 };

package/dist/components/k3s.js

@@ -1,3 +1,6 @@
+import { isIP } from "node:net";
+import { installPodTrust } from "./k3s-trust.js";
+import { loadK3sBuildImages } from "../harness/k3s-image-loader.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { spawn as nodeSpawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
@@ -7,6 +10,10 @@ import { AppsV1Api, BatchV1Api, CoreV1Api, KubeConfig, KubernetesObjectApi, Patc
 import { Observable } from "@kubernetes/client-node/dist/gen/rxjsStub.js";
 import { dnsName, provides, SELF_SERVICE_TOKEN } from "../index.js";
 import { MKFS_EROFS_PATH, STORE_ADOPT_PATH, imageCachePathsSync, nestedStoreDir, } from "../harness/image-cache.js";
+import { stickyDiskPathSync } from "../harness/sticky-paths.js";
+import { registerStickyKubernetesStore, stickyKubernetesDirectory } from "../harness/sticky-kubernetes.js";
+import { prePullK3sImages } from "../harness/k3s-prepull.js";
+import { componentRuntime, kubernetesImages } from "../harness/component-images.js";
 import { deepUnwrap, readTag, wrap } from "../inspect.js";
 import { recorderAnnotate, recorderRemove } from "../recorder.js";
 /** Port the in-cluster registry listens on (plain HTTP). */
@@ -32,8 +39,13 @@ const CRI_MANAGED_LABEL = "io.cri-containerd.image=managed";
  */
 const BOOT_MARKER = ".spectest-boot-incomplete";
 /**
- * The cluster's image store, and how it shares the environment's image
- * cache (`CONTAINER_STORE.md` §12).
+ * Sticky-enabled projects bind a per-service/version directory on the
+ * sticky disk at CLUSTER_STORE_TARGET and use overlayfs. Publication's
+ * sticky-kubernetes adapter removes runtime state and retains images and
+ * unpacked layers under the shared filesystem budget. Test forks do not
+ * write back. The preparation wrapper below also handles delta rebuilds.
+ *
+ * Legacy image-cache integration (`CONTAINER_STORE.md` §12):
  *
  * The cluster's embedded containerd keeps its root on the **root disk**
  * of the environment's image cache, in a directory of its own
@@ -195,8 +207,8 @@ function storePrepareSh(cache) {
         `timeout 60 ctr -a "$A" -n k8s.io containers rm $ids >/dev/null 2>&1 || true; fi; ` +
         // containerd 2.x keeps sandboxes in a store of their own; on the 1.7
         // k3s ships they are ordinary containers and this is a no-op.
-        `sb=$(timeout 30 ctr -a "$A" -n k8s.io sandboxes ls -q 2>/dev/null); ` +
-        `[ -n "$sb" ] && timeout 60 ctr -a "$A" -n k8s.io sandboxes rm $sb >/dev/null 2>&1; return 0; }; ` +
+        `sb=$(timeout 30 ctr -a "$A" -n k8s.io sandboxes ls 2>/dev/null | awk 'NR > 1 {print $1}'); ` +
+        `[ -n "$sb" ] && timeout 60 ctr -a "$A" -n k8s.io sandboxes rm --force $sb >/dev/null 2>&1; return 0; }; ` +
         adopt +
         `if [ -e "$M" ]; then ` +
         `echo 'spectest: the previous cluster on this image store never became ready; starting from an empty one' >&2; ` +
@@ -287,7 +299,7 @@ async function issueIngressCert(hostnames) {
     const id = `spectest-k3s-ingress-${randomUUID().slice(0, 8)}`;
     const keyPath = `/tmp/${id}.key`;
     const crtPath = `/tmp/${id}.crt`;
-    const sans = hostnames.map((h) => `DNS:${h}`).join(",");
+    const sans = hostnames.map((h) => `${isIP(h) ? "IP" : "DNS"}:${h}`).join(",");
     const r = await runProcess("openssl", [
         "req",
         "-newkey",
@@ -1393,6 +1405,7 @@ async function collectDiagnostics(client, namespace) {
 const DEFAULT_K3S_VERSION = "v1.33.5-k3s1";
 export function k3s(opts = {}) {
     const version = opts.version ?? DEFAULT_K3S_VERSION;
+    const images = kubernetesImages(opts.images ?? []);
     const extra = opts.extraArgs ?? [];
     assertUsableExtraArgs(extra);
     const registryEnabled = opts.registry !== false;
@@ -1409,7 +1422,8 @@ export function k3s(opts = {}) {
     // 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 cache = imageCachePathsSync();
+    const sticky = stickyDiskPathSync();
+    const cache = sticky ? null : imageCachePathsSync();
     const serverArgs = [
         "k3s",
         "server",
@@ -1507,6 +1521,7 @@ export function k3s(opts = {}) {
     const readyCmd = `kubectl get --raw=/readyz >/dev/null 2>&1 && rm -f ${CLUSTER_STORE_TARGET}/${BOOT_MARKER}`;
     const def = {
         image: { type: "registry", reference: `rancher/k3s:${version}` },
+        imageBuilds: images.builds,
         command: cmd,
         privileged: true,
         tmpfs: ["/run", "/var/run"],
@@ -1520,21 +1535,23 @@ export function k3s(opts = {}) {
         // the same netns and are reachable the same way, without appearing
         // in this list (it's documentation, not a firewall).
         ports: registryEnabled ? [80, 443, 6443, K3S_REGISTRY_PORT] : [80, 443, 6443],
-        // The cluster's image store (see the store section above): its
+        // Sticky disks retain an independent overlayfs store per service/version.
+        // The legacy image cache (see the store section above) keeps its
         // containerd root on the image cache's root disk, the shared layers
         // disk read-only at its guest path, golden's mkfs.erofs and the adopt
         // helper — or, with no cache, a per-environment volume. Two clusters
         // 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: cache
-            ? [
+        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 }],
+                : [{ target: CLUSTER_STORE_TARGET }],
         files: [
             ...(registriesYaml ? [{ path: "/etc/rancher/k3s/registries.yaml", content: registriesYaml }] : []),
             ...(cache
@@ -1549,12 +1566,61 @@ export function k3s(opts = {}) {
             command: readyCmd,
             timeoutSecs: opts.readyTimeoutSecs ?? 120,
         },
-        setup: async ({ name, helpers }) => {
+        setup: async (ctx) => {
+            const { name, helpers, exec } = ctx;
+            const runtime = componentRuntime(ctx);
+            if (images.builds.length && !runtime)
+                throw new Error(`k3s(${name}): prepared image inputs are missing`);
+            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 (;;) {
+                    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));
+                }
+            }
+            if (runtime)
+                await loadK3sBuildImages(name, runtime.images, runtime.gateway, exec);
             await setupK3sCluster(name, helpers, {
                 registry: registryEnabled,
                 ingressDomains,
                 traefik: traefikEnabled,
             });
+            await prePullK3sImages(name, images.pulls, exec);
+            if (sticky)
+                await registerStickyKubernetesStore(name, version);
         },
         helpers: async ({ name, exec, poll }) => {
             // Read the cluster's kubeconfig and address the API server by its

package/dist/daemon.js

@@ -1,3 +1,4 @@
+import { componentBuildTasks, COMPONENT_RUNTIME } from "./harness/component-images.js";
 import { androidScope, androidRecordingChunk, releaseAndroidRecording, isAndroidApp } from "./android.js";
 // Long-running HTTP daemon. Runs as a systemd unit on the VM host (not in
 // a container). Owns:
@@ -24,7 +25,7 @@ import net from "node:net";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { ENVIRONMENT_CA_PATH as CA_PATH } from "./environment-ca.js";
-import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, validateServiceImage, proxy as makeProxyDecl, } from "./index.js";
+import { assert, expect, expectRaw, lowerIngress, dnsName as makeDnsDecl, isWildcard, validateServiceImage, normalizeServiceImage, proxy as makeProxyDecl, } from "./index.js";
 import { COVERAGE_CONTAINER_DIR, coverageBundleRef, coverageHostDir, encodeCoverageBundle, isEmptyReport, readCoverageDir, applyCoverageDelta, walkProjectFiles, ENVIRONMENT_SERVICE, REACH_REPORT, READS_REPORT, } from "./harness/coverage.js";
 import { configureBrowserCoverage } from "./browser-coverage.js";
 import { INVENTORY_REPORT, NODE_COVERAGE_MARKERS_SUBDIR, NODE_COVERAGE_SCRIPTS_SUBDIR, applyCoverageAdapters, coverageAdapters, coverageReportsMode, validateCoverage, } from "./coverage.js";
@@ -57,6 +58,7 @@ import { certCovers as hostmatchCertCovers, hostWithoutPort, matchRoute, selectC
 import { INGRESS_HTTPS_PORT, INGRESS_HTTP_PORT, bindRoute, clearTables, emptyTables, planBind, registryTarget, routesFor, unbindRoute, } from "./harness/ingress-table.js";
 import { startTlsTerminator } from "./harness/tls-terminator.js";
 import { runContainerArgs } from "./harness/container-run.js";
+import { isOnStickyDisk } from "./harness/sticky-paths.js";
 import { BUILDKIT_CACHE_DIR, BUILDKIT_CACHE_UNION, IMAGE_CACHE_MANIFEST, imageCachePathsSync, isOnImageCache, mergeCacheIndex, } from "./harness/image-cache.js";
 import { assertAbsolute, certificateHostnames, defaultKeyMode, expandServiceToken, isNoopChown, mountFlag, needsIdTables, numericId, resolveChownIds, } from "./harness/file-mounts.js";
 import { badRequest, conflict, notFound, requireString, } from "./harness/methods.js";
@@ -70,7 +72,18 @@ import { deepUnwrap, readRaw, wrap } from "./inspect.js";
 import { setRecordSecrets } from "./record-secrets.js";
 import { encodeReplayBundle, replayChunk } from "./replay-bundle.js";
 function namedServices(cfg) {
-    return Object.entries(cfg.services).map(([name, def]) => ({ name, ...def }));
+    return Object.entries(cfg.services).map(([name, def]) => ({ name, ...def, image: normalizeServiceImage(def.image) }));
+}
+/** Build tasks participate in image preparation, never container startup. */
+function imageTasks(services) {
+    const tasks = componentBuildTasks(services).map(task => ({ ...task, image: validateServiceImage(task.name, task.image) }));
+    const names = new Set(services.map(s => s.name));
+    for (const task of tasks) {
+        if (names.has(task.name))
+            throw new Error(`image task name conflicts with service: ${task.name}`);
+        names.add(task.name);
+    }
+    return [...services, ...tasks];
 }
 const DEFAULT_TEST_TIMEOUT_MS = 60_000;
 const NETWORK_NAME = process.env.SPECTEST_NETWORK ?? "spectest-net";
@@ -677,7 +690,7 @@ async function ensureVolumes(svc) {
             // A directory on a cache disk is the same kind of thing: a nested
             // runtime's containerd root (`k3s()`), kept as a cache by the
             // lineage exactly as the container store one level up is.
-            const durable = host.startsWith("/var/cache/spectest/") || isOnImageCache(host, imageCachePathsSync(IMAGE_CACHE_MANIFEST));
+            const durable = host.startsWith("/var/cache/spectest/") || isOnStickyDisk(host) || isOnImageCache(host, imageCachePathsSync(IMAGE_CACHE_MANIFEST));
             if (vol.source?.startsWith("/") && !durable) {
                 await recordAbsoluteVolumeDir(host);
             }
@@ -1013,6 +1026,15 @@ async function resolveDockerfileBuild(svc) {
     };
 }
 async function prepareServiceImage(svc, opts) {
+    const result = await prepareServiceImageInner(svc, opts);
+    if (svc.image.type === "dockerfile" && svc.image.reference) {
+        const tagged = await docker(["tag", result.tag, svc.image.reference], 30_000);
+        if (tagged.code !== 0)
+            throw new Error(`cannot name built image ${svc.image.reference}: ${tagged.stderr}`);
+    }
+    return result;
+}
+async function prepareServiceImageInner(svc, opts) {
     const tag = imageTag(svc.name);
     if (svc.image.type === "registry") {
         const ref = svc.image.reference;
@@ -1062,7 +1084,7 @@ async function prepareServiceImage(svc, opts) {
                 progressService(svc.name, { status: "failed" });
                 throw err;
             }
-            // first.tag is already CA-layered; tagging it covers this service too.
+            // Reuse the same application image; runtime trust is added separately.
             const tagr = await docker(["tag", first.tag, tag], 30_000);
             if (tagr.code !== 0) {
                 throw new Error(`docker tag ${first.tag} ${tag} failed: ${tagr.stderr.trim()}`);
@@ -2640,7 +2662,8 @@ function specToNamedService(spec) {
     // run here: the image is checked (a `path` Dockerfile and a `context`
     // must exist), and coverage adapters get their configure step.
     const svc = { ...rest, image: validateServiceImage(name, rest.image) };
-    return { name, ...applyCoverageAdapters(name, svc) };
+    const configured = applyCoverageAdapters(name, svc);
+    return { name, ...configured, image: normalizeServiceImage(configured.image) };
 }
 /** Implementation behind `ctx.startService` / a fake's `ctx.startService`.
  *  Prepares the image (pulling on first use through the host cache), runs
@@ -2931,12 +2954,14 @@ async function bootstrapInner(prepared, identity) {
     const bootStart = Date.now();
     const cfg = requireLoaded().project.environment;
     const services = namedServices(cfg);
+    const tasks = imageTasks(services);
+    const componentTasks = componentBuildTasks(services);
     const timings = new Map();
     if (prepared && (prepared.version !== 1 || !prepared.images ||
-        Object.keys(prepared.images).sort().join("\n") !== services.map(s => s.name).sort().join("\n"))) {
+        Object.keys(prepared.images).sort().join("\n") !== tasks.map(s => s.name).sort().join("\n"))) {
         throw new Error("prepared image manifest does not match the environment's services");
     }
-    progressInit(services);
+    progressInit(tasks);
     // Build dedup is only valid within one workspace generation — a fresh
     // bootstrap may follow a workspace re-upload with the same dockerfile
     // text but different build-context content.
@@ -2957,7 +2982,7 @@ async function bootstrapInner(prepared, identity) {
             // that reads it.
             if ((await readIgnoreFile(path.join(WORKSPACE, ".dockerignore"))) !== null)
                 return;
-            await fs.writeFile(path.join(WORKSPACE, ".dockerignore"), unionDockerignore(services));
+            await fs.writeFile(path.join(WORKSPACE, ".dockerignore"), unionDockerignore(tasks));
         })(),
     ]);
     // Image prep is DECOUPLED from container start: every service's image
@@ -2993,11 +3018,15 @@ async function bootstrapInner(prepared, identity) {
         if (found.code !== 0 || found.stdout.trim() !== entry.image) {
             throw new Error(`prepared image missing for ${svc.name}: ${entry.image}`);
         }
-        return { tag: entry.image, buildSteps: entry.buildSteps };
+        const tag = imageTag(svc.name);
+        const tagged = await docker(["tag", entry.image, tag], 30_000);
+        if (tagged.code !== 0)
+            throw new Error(`cannot restore prepared image name for ${svc.name}: ${tagged.stderr}`);
+        return { tag, buildSteps: entry.buildSteps };
     };
     const prep = new Map();
     const prepOffsets = new Map();
-    for (const svc of services) {
+    for (const svc of tasks) {
         const p = (async () => {
             const t0 = Date.now();
             prepOffsets.set(svc.name, Date.now() - bootStart);
@@ -3022,7 +3051,7 @@ async function bootstrapInner(prepared, identity) {
         // No application services, setup hooks, ingress, or runtime state in the builder.
         await Promise.all(prep.values());
         const images = Object.create(null);
-        for (const svc of services) {
+        for (const svc of tasks) {
             const out = await docker(["image", "inspect", "--format", "{{.Id}}", tags.get(svc.name)], 30_000);
             const image = out.stdout.trim();
             if (out.code !== 0 || !/^sha256:[a-f0-9]{64}$/.test(image)) {
@@ -3073,6 +3102,8 @@ async function bootstrapInner(prepared, identity) {
         progressService(svc.name, { status: "probing", detail: "ready check" });
         await waitForReady(svc);
         const tSetup = Date.now();
+        const builds = componentTasks.filter(task => task.owner === svc.name);
+        await Promise.all(builds.map(task => prep.get(task.name)));
         if (svc.setup) {
             progressService(svc.name, { status: "probing", detail: "running setup" });
             const helpers = await ensureHelpers(svc.name, svc);
@@ -3081,12 +3112,19 @@ async function bootstrapInner(prepared, identity) {
                     name: svc.name,
                     helpers,
                     ...(await spectestContext({ service: svc.name, includeSelf: true })),
+                    ...{ [COMPONENT_RUNTIME]: {
+                            images: builds.map(task => ({ source: tags.get(task.name), reference: task.reference })),
+                            gateway: await bridgeGatewayIp(),
+                            caBundle: await ensureCaBundle(),
+                        } },
                 });
             }
             catch (err) {
                 throw await withContainerPostMortem(svc.name, err);
             }
         }
+        for (const task of builds)
+            progressService(task.name, { status: "ready", detail: `loaded ${task.reference}` });
         progressService(svc.name, { status: "ready", detail: undefined });
         const ti = timings.get(svc.name);
         if (ti) {
@@ -3545,9 +3583,10 @@ async function computeProjectReach(all) {
 async function computeProjectReachInner(all) {
     const files = await walkProjectFiles(WORKSPACE, [".git"]);
     const sources = [];
-    for (const svc of all) {
+    const owners = new Map(componentBuildTasks(all).map(t => [t.name, t.owner]));
+    for (const svc of imageTasks(all)) {
         const src = {
-            service: svc.name,
+            service: owners.get(svc.name) ?? svc.name,
             volumeSources: (svc.volumes ?? []).flatMap((v) => (v.source && !v.reachExempt ? [v.source] : [])),
             ...(svc.inputs && svc.inputs.length > 0 ? { inputs: [...svc.inputs] } : {}),
         };
@@ -5611,7 +5650,7 @@ export function harnessMethods(state) {
             }
         }),
         bootstrap: async (params) => exclusive(state, "inFlightBootstrap", "bootstrap already in progress", async () => {
-            const prepared = params.prepared === undefined ? undefined : preparedImages(params.prepared, params.identity, namedServices(requireLoaded().project.environment).map(s => s.name));
+            const prepared = params.prepared === undefined ? undefined : preparedImages(params.prepared, params.identity, imageTasks(namedServices(requireLoaded().project.environment)).map(s => s.name));
             return { ok: true, timings: await bootstrap(prepared) };
         }),
         projectSetup: async () => exclusive(state, "inFlightProjectSetup", "project-setup already in progress", () => runProjectSetup()),

package/dist/harness/component-images.d.ts

@@ -0,0 +1,31 @@
+import type { BuildImage, ComponentImageBuild, ServiceConfig } from "../index.js";
+export type KubernetesImage = string | (BuildImage & {
+    reference: string;
+});
+/** containerd/CRI use fully qualified names, including the default tag. */
+export declare function canonicalImageReference(reference: string): string;
+export declare function kubernetesImages(images: readonly KubernetesImage[]): {
+    pulls: string[];
+    builds: ComponentImageBuild[];
+};
+/** Stable internal task names, separate from the service graph. */
+export declare function componentBuildTasks<T extends ServiceConfig & {
+    name: string;
+}>(services: readonly T[]): {
+    name: string;
+    owner: string;
+    reference: string;
+    image: BuildImage;
+}[];
+/** Private handoff to a component's setup hook. Builds stay generic; the
+ * component decides how its runtime consumes them and establishes trust. */
+export declare const COMPONENT_RUNTIME: unique symbol;
+export interface ComponentRuntime {
+    images: readonly {
+        source: string;
+        reference: string;
+    }[];
+    gateway: string;
+    caBundle: string | null;
+}
+export declare function componentRuntime(context: object): ComponentRuntime | undefined;