@specific.dev/spectest 0.90.2 → 0.91.0

package/src/components/k3s.ts

@@ -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";
@@ -31,6 +34,7 @@ import { Observable } from "@kubernetes/client-node/dist/gen/rxjsStub.js";
 import type {
   ServiceDefinition,
   ServiceHelpersContext,
+  ServiceSetupContext,
   SpectestContext,
 } from "../index.js";
 import { dnsName, provides, SELF_SERVICE_TOKEN } from "../index.js";
@@ -41,6 +45,11 @@ import {
   nestedStoreDir,
   type ImageCachePaths,
 } 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, type KubernetesImage } from "../harness/component-images.js";
+export type { KubernetesImage } from "../harness/component-images.js";
 import { deepUnwrap, readTag, wrap } from "../inspect.js";
 import type { Wrapped } from "../inspect.js";
 import { recorderAnnotate, recorderRemove } from "../recorder.js";
@@ -50,7 +59,19 @@ export type {
   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
@@ -178,8 +199,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
@@ -346,8 +372,8 @@ function storePrepareSh(cache: ImageCachePaths | null): string {
     `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; ` +
@@ -724,7 +750,7 @@ async function issueIngressCert(
   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",
     [
@@ -2007,6 +2033,7 @@ const DEFAULT_K3S_VERSION = "v1.33.5-k3s1";
 
 export function k3s(opts: K3sOptions = {}) {
   const version = opts.version ?? DEFAULT_K3S_VERSION;
+  const images = kubernetesImages(opts.images ?? []);
   const extra = opts.extraArgs ?? [];
   assertUsableExtraArgs(extra);
   const registryEnabled = opts.registry !== false;
@@ -2023,7 +2050,8 @@ export function k3s(opts: K3sOptions = {}) {
   // 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",
@@ -2122,6 +2150,7 @@ export function k3s(opts: K3sOptions = {}) {
   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"],
@@ -2135,15 +2164,17 @@ export function k3s(opts: K3sOptions = {}) {
     // 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 },
@@ -2164,12 +2195,52 @@ export function k3s(opts: K3sOptions = {}) {
       command: readyCmd,
       timeoutSecs: opts.readyTimeoutSecs ?? 120,
     },
-    setup: async ({ name, helpers }: { name: string; helpers: K3sHelpers }) => {
+    setup: async (ctx: ServiceSetupContext<K3sHelpers>) => {
+      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 }: ServiceHelpersContext): Promise<K3sHelpers> => {
       // Read the cluster's kubeconfig and address the API server by its

package/src/coverage.test.ts

@@ -135,6 +135,56 @@ describe("units", () => {
 });
 
 describe("browserCoverage", () => {
+  for (const order of ["dashboard first", "admin first", "concurrent"] as const) {
+    test(`services retain their own coverage and deltas: ${order}`, async () => {
+      const reports = new Map<string, string>();
+      const contexts = ["dashboard", "admin"].map((service): CoverageCaptureContext => ({
+        ...fakeCtx("unused"),
+        service,
+        async writeReport(name, content) {
+          expect(name).toBe("browser.lcov");
+          reports.set(service, content);
+        },
+      }));
+      if (order === "admin first") contexts.reverse();
+      const capture = async () => {
+        if (order === "concurrent") {
+          await Promise.all(contexts.map((ctx) => browser().capture!(ctx)));
+        } else {
+          for (const ctx of contexts) await browser().capture!(ctx);
+        }
+      };
+      foldBrowserCoverage("dashboard", new Map([["src/dashboard.ts", new Map([[1, 2]])]]));
+      foldBrowserCoverage("admin", new Map([["src/admin.ts", new Map([[3, 4]])]]));
+      await capture();
+      expect(reports.get("dashboard")).toBe("TN:\nSF:src/dashboard.ts\nDA:1,2\nLF:1\nLH:1\nend_of_record\n");
+      expect(reports.get("admin")).toBe("TN:\nSF:src/admin.ts\nDA:3,4\nLF:1\nLH:1\nend_of_record\n");
+
+      await capture();
+      expect(reports.get("dashboard")).toBe("TN:\n");
+      expect(reports.get("admin")).toBe("TN:\n");
+
+      foldBrowserCoverage("admin", new Map([["src/admin.ts", new Map([[3, 1]])]]));
+      await capture();
+      expect(reports.get("dashboard")).toBe("TN:\n");
+      expect(reports.get("admin")).toBe("TN:\nSF:src/admin.ts\nDA:3,1\nLF:1\nLH:1\nend_of_record\n");
+    });
+  }
+
+  test("capturing a service with no coverage preserves other services' totals", async () => {
+    const reports = new Map<string, string>();
+    foldBrowserCoverage("dashboard", new Map([["src/dashboard.ts", new Map([[1, 2]])]]));
+    for (const service of ["admin", "dashboard"]) {
+      await browser().capture!({
+        ...fakeCtx("unused"),
+        service,
+        async writeReport(_name, content) { reports.set(service, content); },
+      });
+    }
+    expect(reports.get("admin")).toBe("TN:\n");
+    expect(reports.get("dashboard")).toBe("TN:\nSF:src/dashboard.ts\nDA:1,2\nLF:1\nLH:1\nend_of_record\n");
+  });
+
   test("writes an empty lcov when nothing ran for the service", async () => {
     const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-cov-"));
     await browser().capture!(fakeCtx(dir));

package/src/coverage.ts

@@ -30,7 +30,7 @@
 import { createHash } from "node:crypto";
 
 import type { ServiceConfig } from "./index.js";
-import { harvestAllBrowserCoverage, takeBrowserCoverageReports } from "./browser-coverage.js";
+import { harvestAllBrowserCoverage, takeBrowserCoverageReport } from "./browser-coverage.js";
 
 import { COVERAGE_CONTAINER_DIR, type CoverageReportsMode } from "./harness/coverage.js";
 export { COVERAGE_CONTAINER_DIR, type CoverageReportsMode };
@@ -969,7 +969,7 @@ export async function collectNodeReports(dir: string): Promise<NodeReportStats>
  * loads from this service's origins, maps it back to source through the
  * served source map, and writes one lcov per capture (`browser.lcov`)
  * holding what ran since the previous capture: every live session is
- * harvested first, and the totals are taken and cleared. Nothing ran ⇒
+ * harvested first, and only this service's totals are taken and cleared. Nothing ran ⇒
  * an lcov with no records, which is a report saying so.
  */
 export function browser(): CoverageAdapter {
@@ -981,7 +981,7 @@ export function browser(): CoverageAdapter {
     },
     async capture(ctx) {
       await harvestAllBrowserCoverage();
-      const lcov = takeBrowserCoverageReports().get(ctx.service) ?? "TN:\n";
+      const lcov = takeBrowserCoverageReport(ctx.service);
       await ctx.writeReport("browser.lcov", lcov);
     },
   };

package/src/daemon.ts

@@ -1,3 +1,4 @@
+import { componentBuildTasks, COMPONENT_RUNTIME } from "./harness/component-images.js";
 import { androidScope, androidRecordingChunk, releaseAndroidRecording, isAndroidApp, type AndroidRecording } from "./android.js";
 // Long-running HTTP daemon. Runs as a systemd unit on the VM host (not in
 // a container). Owns:
@@ -35,6 +36,7 @@ import {
   dnsName as makeDnsDecl,
   isWildcard,
   validateServiceImage,
+  normalizeServiceImage,
   proxy as makeProxyDecl,
 } from "./index.js";
 import type { DnsTarget, LoweredIngress } from "./index.js";
@@ -154,6 +156,7 @@ import {
 } from "./harness/ingress-table.js";
 import { startTlsTerminator, type TlsTerminator } 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,
@@ -239,7 +242,7 @@ import type {
   ServiceConfig,
   ServiceDefinition,
   ServiceHandles,
-  ServiceImage,
+  NormalizedServiceImage,
   SpectestContext,
   Terminal,
   TerminalOpts,
@@ -256,10 +259,21 @@ import type { InternalTerminal, TerminalFrameSink } from "./terminal.js";
  * name (container name, image tag, ready-probe host). Widened to
  * accept any helpers shape so a typed `setup({ helpers })` call from
  * a component (e.g. K3sHelpers) lines up at the call site. */
-type NamedService = ServiceDefinition<Record<string, unknown>> & { name: string };
+type NamedService = Omit<ServiceDefinition<Record<string, unknown>>, "image"> & { name: string; image: NormalizedServiceImage };
 
 function namedServices(cfg: EnvironmentConfig): NamedService[] {
-  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: NamedService[]): NamedService[] {
+  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;
@@ -977,7 +991,7 @@ async function ensureVolumes(svc: NamedService): Promise<string[]> {
       // 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);
       }
@@ -1365,6 +1379,18 @@ async function resolveDockerfileBuild(svc: NamedService): Promise<DockerfileBuil
 async function prepareServiceImage(
   svc: NamedService,
   opts?: { dedup?: boolean },
+): Promise<{ tag: string; buildSteps?: BuildStep[] }> {
+  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: NamedService,
+  opts?: { dedup?: boolean },
 ): Promise<{ tag: string; buildSteps?: BuildStep[] }> {
   const tag = imageTag(svc.name);
   if (svc.image.type === "registry") {
@@ -1414,7 +1440,7 @@ async function prepareServiceImage(
         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()}`);
@@ -3175,7 +3201,8 @@ function specToNamedService(spec: RuntimeServiceSpec): NamedService {
   // run here: the image is checked (a `path` Dockerfile and a `context`
   // must exist), and coverage adapters get their configure step.
   const svc = { ...(rest as ServiceConfig), 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`.
@@ -3507,12 +3534,14 @@ async function bootstrapInner(prepared?: PreparedImages, identity?: string): Pro
   const bootStart = Date.now();
   const cfg: EnvironmentConfig = requireLoaded().project.environment;
   const services = namedServices(cfg);
+  const tasks = imageTasks(services);
+  const componentTasks = componentBuildTasks(services);
   const timings = new Map<string, ServiceTiming>();
   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.
@@ -3535,7 +3564,7 @@ async function bootstrapInner(prepared?: PreparedImages, identity?: string): Pro
       if ((await readIgnoreFile(path.join(WORKSPACE, ".dockerignore"))) !== null) return;
       await fs.writeFile(
         path.join(WORKSPACE, ".dockerignore"),
-        unionDockerignore(services),
+        unionDockerignore(tasks),
       );
     })(),
   ]);
@@ -3572,11 +3601,14 @@ async function bootstrapInner(prepared?: PreparedImages, identity?: string): Pro
     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<string, Promise<void>>();
   const prepOffsets = new Map<string, number>();
-  for (const svc of services) {
+  for (const svc of tasks) {
     const p = (async () => {
       const t0 = Date.now();
       prepOffsets.set(svc.name, Date.now() - bootStart);
@@ -3602,7 +3634,7 @@ async function bootstrapInner(prepared?: PreparedImages, identity?: string): Pro
     // No application services, setup hooks, ingress, or runtime state in the builder.
     await Promise.all(prep.values());
     const images: PreparedImages["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)) {
@@ -3654,6 +3686,8 @@ async function bootstrapInner(prepared?: PreparedImages, identity?: string): Pro
     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);
@@ -3662,11 +3696,17 @@ async function bootstrapInner(prepared?: PreparedImages, identity?: string): Pro
           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) {
@@ -4223,9 +4263,10 @@ async function computeProjectReach(all: NamedService[]): Promise<ReachRules> {
 async function computeProjectReachInner(all: NamedService[]): Promise<ReachRules> {
   const files = await walkProjectFiles(WORKSPACE, [".git"]);
   const sources: ReachSource[] = [];
-  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: ReachSource = {
-      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] } : {}),
     };
@@ -6720,7 +6761,7 @@ export function harnessMethods(state: RouteState): MethodTable {
     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),
+          params.prepared, params.identity, imageTasks(namedServices(requireLoaded().project.environment)).map(s => s.name),
         );
         return { ok: true, timings: await bootstrap(prepared) };
       }),

package/src/harness/component-images.test.ts

@@ -0,0 +1,44 @@
+import { expect, test } from "bun:test";
+import { canonicalImageReference, componentBuildTasks, kubernetesImages } from "./component-images";
+import { validateServiceImage, type BuildImage } from "../index";
+
+test("services and Kubernetes share all Dockerfile build options without a type discriminator", () => {
+  const image: BuildImage & { reference: string } = {
+    reference: "k8s.internal:5000/runtime:spectest", content: "FROM scratch AS test",
+    target: "test", context: ".", exclude: ["fixtures"], buildArgs: { MODE: "test" },
+  };
+  expect(validateServiceImage("app", { ...image, context: undefined })).toEqual({ ...image, context: undefined, type: "dockerfile" });
+  expect(validateServiceImage("redis", "redis:7.4")).toEqual({ type: "registry", reference: "redis:7.4" });
+  const parsed = kubernetesImages(["redis:7.4", image]);
+  expect(parsed.pulls).toEqual(["redis:7.4"]);
+  expect(parsed.builds).toEqual([{ reference: image.reference, image }]);
+  const tasks = componentBuildTasks([{ name: "cluster", image: "k3s:latest", imageBuilds: parsed.builds }]);
+  expect(tasks[0].image).toBe(image);
+  expect(tasks[0].owner).toBe("cluster");
+  expect(tasks[0].name).toMatch(/^spectest-image-[a-f0-9]+$/);
+});
+
+test("image identity validates references and rejects conflicting definitions", () => {
+  expect(canonicalImageReference("redis:7.4")).toBe("docker.io/library/redis:7.4");
+  expect(canonicalImageReference("docker.io/redis:7.4")).toBe("docker.io/library/redis:7.4");
+  expect(canonicalImageReference("company/api")).toBe("docker.io/company/api:latest");
+  expect(canonicalImageReference("localhost:5000/api")).toBe("localhost:5000/api:latest");
+  expect(kubernetesImages(["redis:7.4", "redis:7.4"]).pulls).toHaveLength(1);
+  for (const value of ["", "--help", "https://example.com/api", "has space", "bad:tag:extra"]) {
+    expect(() => kubernetesImages([value])).toThrow();
+  }
+  expect(() => kubernetesImages([{ content: "FROM scratch" } as never])).toThrow("reference");
+  expect(() => kubernetesImages([{ type: "registry", reference: "redis:7" } as never])).toThrow();
+  expect(() => kubernetesImages([{ reference: `api@sha256:${"a".repeat(64)}`, content: "FROM scratch" }])).toThrow("digest");
+  expect(() => kubernetesImages(["api:1", { reference: "docker.io/library/api:1", content: "FROM scratch" }])).toThrow("conflicting");
+});
+
+test("build task identity survives list reordering but is scoped to the owning cluster", () => {
+  const a = { reference: "app:1", image: { content: "FROM scratch" } };
+  const b = { reference: "app:2", image: { content: "FROM scratch" } };
+  const tasks = (name: string, imageBuilds: typeof a[]) => componentBuildTasks([{ name, image: "k3s:1", imageBuilds }]);
+  expect(tasks("cluster", [a, b])[0].name).toBe(tasks("cluster", [b, a])[1].name);
+  expect(tasks("cluster", [a])[0].name).not.toBe(tasks("other", [a])[0].name);
+  expect(() => validateServiceImage("app", { content: "FROM scratch", buildArgs: { "bad-key": "x" } })).toThrow("ARG");
+  expect(() => validateServiceImage("app", { content: "FROM scratch", exclude: [1] as never })).toThrow("exclude");
+});

package/src/harness/component-images.ts

@@ -0,0 +1,73 @@
+import { createHash } from "node:crypto";
+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 function canonicalImageReference(reference: string): string {
+  if (typeof reference !== "string" || !reference || reference.startsWith("-") || /[\s\x00]/.test(reference)) {
+    throw new Error("image reference must be a non-empty image name without whitespace");
+  }
+  const slash = reference.indexOf("/");
+  const first = slash < 0 ? "" : reference.slice(0, slash);
+  let result = slash < 0 ? `docker.io/library/${reference}`
+    : first.includes(".") || first.includes(":") || first === "localhost" ? reference : `docker.io/${reference}`;
+  if (result.startsWith("index.docker.io/")) result = result.replace("index.docker.io/", "docker.io/");
+  if (result.startsWith("docker.io/") && !result.slice(10).includes("/")) result = `docker.io/library/${result.slice(10)}`;
+  const [name, digest] = result.split("@");
+  const tagAt = name.lastIndexOf(":") > name.lastIndexOf("/") ? name.lastIndexOf(":") : -1;
+  const repository = tagAt < 0 ? name : name.slice(0, tagAt);
+  if (!/^[a-z0-9.-]+(?::[0-9]+)?\/[a-z0-9]+(?:(?:[._]|__|[-]+)[a-z0-9]+)*(?:\/[a-z0-9]+(?:(?:[._]|__|[-]+)[a-z0-9]+)*)*$/.test(repository)
+      || (tagAt >= 0 && !/^[\w][\w.-]{0,127}$/.test(name.slice(tagAt + 1)))
+      || (result.includes("@") && (!digest || !/^sha256:[a-f0-9]{64}$/.test(digest) || result.split("@").length !== 2))) {
+    throw new Error(`invalid image reference: ${reference}`);
+  }
+  if (tagAt < 0 && !digest) result += ":latest";
+  return result;
+}
+
+export function kubernetesImages(images: readonly KubernetesImage[]): { pulls: string[]; builds: ComponentImageBuild[] } {
+  if (!Array.isArray(images)) throw new Error("k3s(): images must be an array of registry references or Dockerfile builds");
+  const pulls: string[] = [];
+  const builds: ComponentImageBuild[] = [];
+  const seen = new Map<string, string>();
+  for (const image of images) {
+    if (typeof image !== "string" && (!image || typeof image !== "object" || "type" in image || !image.reference)) {
+      throw new Error("k3s(): images expects registry strings or Dockerfile builds with a reference");
+    }
+    const reference = canonicalImageReference(typeof image === "string" ? image : image.reference);
+    if (typeof image !== "string" && reference.includes("@")) throw new Error("k3s(): a build reference must be an image name/tag, not a digest");
+    const identity = JSON.stringify(image);
+    const previous = seen.get(reference);
+    if (previous !== undefined) {
+      if (previous !== identity) throw new Error(`k3s(): conflicting images for ${reference}`);
+      continue;
+    }
+    seen.set(reference, identity);
+    if (typeof image === "string") pulls.push(image);
+    else builds.push({ reference, image });
+  }
+  return { pulls, builds };
+}
+
+/** Stable internal task names, separate from the service graph. */
+export function componentBuildTasks<T extends ServiceConfig & { name: string }>(services: readonly T[]) {
+  return services.flatMap(svc => (svc.imageBuilds ?? []).map(build => ({
+    name: `spectest-image-${createHash("sha256").update(`${svc.name}\0${build.reference}`).digest("hex")}`,
+    owner: svc.name,
+    reference: build.reference,
+    image: build.image,
+  })));
+}
+
+/** Private handoff to a component's setup hook. Builds stay generic; the
+ * component decides how its runtime consumes them and establishes trust. */
+export const COMPONENT_RUNTIME = Symbol.for("spectest.component-runtime");
+export interface ComponentRuntime {
+  images: readonly { source: string; reference: string }[];
+  gateway: string;
+  caBundle: string | null;
+}
+export function componentRuntime(context: object): ComponentRuntime | undefined {
+  return (context as { [COMPONENT_RUNTIME]?: ComponentRuntime })[COMPONENT_RUNTIME];
+}