@specific.dev/spectest 0.131.17 → 0.131.18

package/dist/browser-surface.d.ts

@@ -0,0 +1,9 @@
+import type { BrowserContext, CDPSession, Page } from "playwright-core";
+export declare function reduceBrowserSurfaces(context: BrowserContext, options: {
+    mobile: boolean;
+    deviceScaleFactor: number;
+}): void;
+export declare function awaitBrowserSurface(page: Page): Promise<void>;
+export declare function captureBrowserScreenshot(page: Page, cdp: CDPSession): Promise<{
+    data: string;
+}>;

package/dist/browser-surface.js

@@ -0,0 +1,71 @@
+// Layout, input coordinates and the visual viewport retain their real size.
+// Only the compositor's output is clipped. Native frame scheduling (including
+// rAF on otherwise quiet pages) remains Chromium's responsibility.
+const SURFACES = new WeakMap();
+class Surface {
+    page;
+    cdp;
+    options;
+    tail = Promise.resolve();
+    constructor(page, cdp, options) {
+        this.page = page;
+        this.cdp = cdp;
+        this.options = options;
+    }
+    async apply(reduced) {
+        const viewport = this.page.viewportSize();
+        if (!viewport)
+            throw new Error("Browser surface requires a fixed viewport");
+        const landscape = viewport.width > viewport.height;
+        await this.cdp.send("Emulation.setDeviceMetricsOverride", {
+            ...viewport,
+            ...this.options,
+            screenWidth: viewport.width,
+            screenHeight: viewport.height,
+            screenOrientation: this.options.mobile
+                ? { angle: landscape ? 90 : 0, type: landscape ? "landscapePrimary" : "portraitPrimary" }
+                : { angle: 0, type: "landscapePrimary" },
+            ...(reduced ? { viewport: { x: 0, y: 0, width: 1, height: 1, scale: 1 } } : {}),
+        });
+    }
+    screenshot() {
+        // Concurrent screenshots must not shrink another capture's surface.
+        const result = this.tail.then(async () => {
+            try {
+                await this.apply(false);
+                // Capture through the same emulation agent: a different CDP session
+                // can read back mobile screenshots at the wrong device scale.
+                return await this.cdp.send("Page.captureScreenshot", { format: "png" });
+            }
+            finally {
+                if (!this.page.isClosed())
+                    await this.apply(true);
+            }
+        });
+        this.tail = result.catch(() => { });
+        return result;
+    }
+}
+export function reduceBrowserSurfaces(context, options) {
+    context.on("page", page => {
+        const pending = (async () => {
+            const surface = new Surface(page, await context.newCDPSession(page), options);
+            await surface.apply(true);
+            return surface;
+        })();
+        SURFACES.set(page, pending);
+        // spawnPage awaits this for SDK views. Popups have no spawnPage caller.
+        void pending.catch(error => {
+            if (!page.isClosed())
+                console.warn("[spectest] failed to reduce browser surface:", error);
+        });
+    });
+}
+export async function awaitBrowserSurface(page) {
+    await SURFACES.get(page);
+}
+export async function captureBrowserScreenshot(page, cdp) {
+    const surface = await SURFACES.get(page);
+    // Externally attached browsers (e.g. Electron) retain their own viewport.
+    return surface ? surface.screenshot() : cdp.send("Page.captureScreenshot", { format: "png" });
+}

package/dist/browser.js

@@ -43,6 +43,7 @@ import { describeUrlPattern, matchesUrl } from "./url-match.js";
 import { attachBrowserCoverage, browserCoverageActive, harvestBrowserCoverage, } from "./browser-coverage.js";
 import { attachBrowserProbe, DEFAULT_ACTION_TIMEOUT_MS, desktopStrategy, makeLocator, mobileStrategy, } from "./locator.js";
 import { chromium } from "playwright-core";
+import { reduceBrowserSurfaces, awaitBrowserSurface, captureBrowserScreenshot } from "./browser-surface.js";
 /** Decoded byte count of a base64 string, without decoding it. */
 function base64ByteLength(b64) {
     let padding = 0;
@@ -179,6 +180,7 @@ async function newViewContext(width, height, device, opts = {}) {
             timezoneId: opts.timezone,
             locale: opts.locale,
         });
+        reduceBrowserSurfaces(context, { mobile: !!device, deviceScaleFactor: device?.deviceScaleFactor ?? 1 });
         context.setDefaultTimeout(DEFAULT_ACTION_TIMEOUT_MS);
         context.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
         if (fixture) {
@@ -847,6 +849,7 @@ const VIEW_POOL = [];
  *  slow part (renderer process spawn). */
 async function spawnPage(context) {
     const page = await context.newPage();
+    await awaitBrowserSurface(page);
     const cdp = await context.newCDPSession(page);
     // Without Page.enable the addScriptToEvaluateOnNewDocument registration
     // silently never fires on this session (verified in the fork spike).
@@ -1651,9 +1654,7 @@ function buildBackend(holder, recorder, buildOpts) {
                 }
                 // Raw CDP rather than page.screenshot(): captures the viewport
                 // exactly like the pre-Playwright backend.
-                const res = (await holder.cdp.send("Page.captureScreenshot", {
-                    format: "png",
-                }));
+                const res = await captureBrowserScreenshot(holder.page, holder.cdp);
                 const id = generateId("art");
                 register({
                     id,

package/dist/daemon.js

@@ -52,6 +52,7 @@ import { ensureStickyBuildHeadroom } from "./harness/sticky-consumer.js";
 import { fakeFunctions, fakeFunctionParameters, callFakeFunction } from "./harness/fake-functions.js";
 import { dispatchFake } from "./harness/fake-websocket.js";
 import { casesMetadata as catalogueCases, groupsMetadata as catalogueGroups, } from "./harness/catalogue.js";
+import { shadowBuilder, shadowImage, shadowOutput, imageDigest, shadowTiming } from "./harness/shadow-builder.js";
 import { summarizeBuildKit } from "./harness/buildkit-progress.js";
 import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta, mergeServiceLogDeltas } from "./harness/log-delta.js";
 import { resolveHostPath as resolveVolumeHostPath, sanitizeSegment, } from "./harness/volume-paths.js";
@@ -1039,18 +1040,28 @@ async function runServiceBuild(name, image, tag) {
         // own layer cache, and the finished image is already in the store
         // dockerd reads. dockerd's built-in BuildKit is the fallback (a guest
         // with no store, or a daemon that would not start).
-        const useLocal = await ensureLocalBuildkitd();
+        const remote = await shadowBuilder();
+        const useLocal = !remote && await ensureLocalBuildkitd();
         // Both the in-VM daemon and dockerd's buildx are BuildKit, so both
         // emit per-step timing on stderr under `--progress=plain` (parsed
         // below). Only the legacy builder takes no progress flag.
-        const useBuildKit = useLocal || (await hasBuildx());
+        const useBuildKit = !!remote || useLocal || (await hasBuildx());
         const buildEnv = {};
         let buildArgs;
         // The user's `buildArgs`, as `--build-arg` flags; a plain client flag,
         // so every builder — in-VM BuildKit, dockerd's own, legacy — takes it.
         const argFlags = [...buildTargetFlags(image.target), ...buildArgFlags(image.buildArgs)];
         const contextDir = image.contextDir;
-        if (useLocal) {
+        const remoteReference = remote ? shadowImage(remote, name) : undefined;
+        const metadataPath = path.join(dfDir, "shadow-result.json");
+        const buildStarted = Date.now();
+        if (remote) {
+            buildArgs = ["buildx", "build", "--builder", remote.builder,
+                "--progress=plain", "--metadata-file", metadataPath,
+                "--output", shadowOutput(remoteReference), ...argFlags,
+                "-f", dfPath, contextDir];
+        }
+        else if (useLocal) {
             // The in-VM builder is BuildKit's containerd worker on this VM's
             // own image store (CONTAINER_STORE.md): the output is an image
             // record in dockerd's namespace, unpacked, so there is no `--load`
@@ -1129,9 +1140,23 @@ async function runServiceBuild(name, image, tag) {
             }
         });
         const log = `${build.stderr.trim()}\n${build.stdout.trim()}`;
+        if (remote)
+            await shadowTiming(name, "solve-export-push", buildStarted, { ok: build.code === 0 });
         if (build.code !== 0) {
             return { ok: false, log };
         }
+        if (remote) {
+            const digest = imageDigest(JSON.parse(await fs.readFile(metadataPath, "utf8")));
+            const immutable = `${remoteReference.split(":result")[0]}@${digest}`;
+            const pullStarted = Date.now();
+            const pulled = await shxStream("docker", ["pull", immutable], undefined, undefined, () => { });
+            await shadowTiming(name, "pull-unpack", pullStarted, { digest, ok: pulled.code === 0, lazy: false });
+            if (pulled.code !== 0)
+                return { ok: false, log: pulled.stderr };
+            const tagged = await docker(["tag", immutable, tag]);
+            if (tagged.code !== 0)
+                return { ok: false, log: tagged.stderr };
+        }
         if (useBuildKit) {
             // Keep only the slowest dozen steps ≥1s — enough to profile, small
             // enough to ride back in the /bootstrap response and the journal.
@@ -5133,7 +5158,7 @@ export function harnessMethods(state) {
     return {
         health: async () => ({
             ok: true,
-            capabilities: ["prepared-images-v1"],
+            capabilities: ["prepared-images-v1", "shadow-builder-v1"],
             // Optional discovery: old SDKs omit this field and are never sent the
             // new method. Check the loaded project, including after warm restore.
             setupInteractive: typeof loaded?.project.interactive?.seed === "function",

package/dist/harness/shadow-builder.d.ts

@@ -0,0 +1,12 @@
+export interface ShadowBuilder {
+    version: 1;
+    builder: string;
+    registry: string;
+    experiment: string;
+}
+export declare function validateShadowBuilder(value: unknown): ShadowBuilder;
+export declare function shadowBuilder(): Promise<ShadowBuilder | undefined>;
+export declare function shadowImage(c: ShadowBuilder, service: string): string;
+export declare function shadowOutput(reference: string): string;
+export declare function imageDigest(metadata: unknown): string;
+export declare function shadowTiming(service: string, phase: string, started: number, extra?: {}): Promise<void>;

package/dist/harness/shadow-builder.js

@@ -0,0 +1,36 @@
+/** Internal experiment configuration. Never selected by project configuration. */
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+export function validateShadowBuilder(value) {
+    const c = value;
+    if (!c || c.version !== 1 || !/^shadow-[a-z0-9-]+$/.test(c.builder)
+        || !/^[a-z0-9.-]+(?::[0-9]+)?$/.test(c.registry)
+        || !/^[a-z0-9-]{1,80}$/.test(c.experiment))
+        throw new Error("invalid shadow builder configuration");
+    return c;
+}
+export async function shadowBuilder() {
+    if (process.env.SPECTEST_SHADOW_BUILD !== "1")
+        return undefined;
+    // A missing configuration is an experiment failure, never a local build.
+    return validateShadowBuilder(JSON.parse(await fs.readFile("/run/spectest/shadow-builder.json", "utf8")));
+}
+export function shadowImage(c, service) {
+    const id = createHash("sha256").update(service).digest("hex").slice(0, 32);
+    return `${c.registry}/shadow/${c.experiment}/${id}:result`;
+}
+export function shadowOutput(reference) {
+    return `type=image,name=${reference},push=true,oci-mediatypes=true,compression=zstd`;
+}
+export function imageDigest(metadata) {
+    const digest = metadata?.["containerimage.digest"];
+    if (typeof digest !== "string" || !/^sha256:[0-9a-f]{64}$/.test(digest)) {
+        throw new Error("remote builder did not return an image digest");
+    }
+    return digest;
+}
+export async function shadowTiming(service, phase, started, extra = {}) {
+    await fs.appendFile("/run/spectest/shadow-timings.jsonl", JSON.stringify({
+        service, phase, startedMs: started, durationMs: Date.now() - started, ...extra,
+    }) + "\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.131.17",
+  "version": "0.131.18",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/browser-surface.test.ts

@@ -0,0 +1,68 @@
+import { expect, test } from "bun:test";
+import { chromium } from "playwright-core";
+import { awaitBrowserSurface, captureBrowserScreenshot, reduceBrowserSurfaces } from "./browser-surface.js";
+
+const executablePath = Bun.which("chromium") ?? Bun.which("chromium-browser") ?? undefined;
+for (const mobile of [false, true]) {
+  test.skipIf(!executablePath)(`reduced surface preserves ${mobile ? "mobile" : "desktop"} behavior and screenshot pixels`, async () => {
+    const browser = await chromium.launch({ executablePath, headless: true, args: ["--no-sandbox"] });
+    const width = mobile ? 393 : 1280, height = mobile ? 852 : 720, dpr = mobile ? 3 : 1;
+    try {
+      const context = await browser.newContext({ viewport: { width, height }, isMobile: mobile, hasTouch: mobile, deviceScaleFactor: dpr });
+      reduceBrowserSurfaces(context, { mobile, deviceScaleFactor: dpr });
+      const page = await context.newPage();
+      await awaitBrowserSurface(page);
+      const cdp = await context.newCDPSession(page);
+      const html = `<meta name="viewport" content="width=device-width,initial-scale=1">
+        <style>body{margin:0;background:white}button{position:absolute;right:10px;top:600px;width:100px;height:50px;background:red;border:0;color:red}#below{position:absolute;top:1600px}iframe{width:200px;height:60px}</style>
+        <button onclick="window.clicks++">Click</button><div id="below">Below</div>
+        <iframe srcdoc="<button onclick='this.textContent=123'>Frame</button>"></iframe>
+        <script>window.clicks=0;window.raf=0;window.resizes=0;window.visible=false;
+        onresize=()=>window.resizes++;new IntersectionObserver(e=>window.visible=e[0].isIntersecting).observe(document.querySelector('button'));
+        function tick(){window.raf++;requestAnimationFrame(tick)}requestAnimationFrame(tick)</script>`;
+      await page.goto(`data:text/html,${encodeURIComponent(html)}`);
+      await page.waitForFunction(() => (window as any).visible && (window as any).raf > 2);
+      await page.getByRole("button", {name:"Click",exact:true}).click();
+      await page.frameLocator("iframe").getByRole("button").click();
+      expect(await page.frameLocator("iframe").getByRole("button").textContent()).toBe("123");
+      const state = () => page.evaluate(() => ({ inner:[innerWidth,innerHeight], visual:[visualViewport!.width,visualViewport!.height], screen:[screen.width,screen.height], dpr:devicePixelRatio, resizes:(window as any).resizes }));
+      // Script-visible rendering APIs and animation completion still progress.
+      expect(await page.evaluate(async () => {
+        const canvas = document.createElement("canvas");
+        canvas.width = canvas.height = 2;
+        const ctx = canvas.getContext("2d")!;
+        ctx.fillStyle = "#00ff00";ctx.fillRect(0,0,2,2);
+        const button = document.querySelector("button")!;
+        await button.animate([{transform:"translateX(0px)"},{transform:"translateX(-1px)"}],{duration:40}).finished;
+        return [...ctx.getImageData(0,0,1,1).data];
+      })).toEqual([0,255,0,255]);
+      const before = await state();
+      expect(before).toMatchObject({inner:[width,height],visual:[width,height],screen:[width,height],dpr});
+      const captures = await Promise.all([captureBrowserScreenshot(page, cdp), captureBrowserScreenshot(page, cdp)]);
+      for (const capture of captures) {
+        const png = Buffer.from(capture.data, "base64");
+        expect([png.readUInt32BE(16),png.readUInt32BE(20)]).toEqual([width*dpr,height*dpr]);
+        const pixel = await page.evaluate(async ({data,x,y}) => {
+          const img = new Image();img.src=`data:image/png;base64,${data}`;await img.decode();
+          const canvas=document.createElement('canvas');canvas.width=img.width;canvas.height=img.height;
+          const ctx=canvas.getContext('2d')!;ctx.drawImage(img,0,0);return [...ctx.getImageData(x,y,1,1).data];
+        },{data:capture.data,x:(width-60)*dpr,y:620*dpr});
+        expect(pixel).toEqual([255,0,0,255]);
+      }
+      expect(await state()).toEqual(before);
+      await page.locator("#below").scrollIntoViewIfNeeded();
+      await page.getByRole("button",{name:"Click",exact:true}).click();
+      expect(await page.evaluate(() => (window as any).clicks)).toBe(2);
+      if (mobile) {
+        const box = await page.getByRole("button",{name:"Click",exact:true}).boundingBox();
+        await page.touchscreen.tap(box!.x+box!.width/2,box!.y+box!.height/2);
+        expect(await page.evaluate(() => (window as any).clicks)).toBe(3);
+      }
+      // A newly opened tab is configured too, without changing its layout.
+      const popup = await context.newPage();await awaitBrowserSurface(popup);
+      await popup.goto(`data:text/html,${encodeURIComponent(html)}`);
+      await popup.getByRole("button",{name:"Click",exact:true}).click();
+      expect(await popup.evaluate(() => [innerWidth,innerHeight,(window as any).clicks])).toEqual([width,height,1]);
+    } finally { await browser.close(); }
+  },30000);
+}

package/src/browser-surface.ts

@@ -0,0 +1,70 @@
+import type { BrowserContext, CDPSession, Page } from "playwright-core";
+
+// Layout, input coordinates and the visual viewport retain their real size.
+// Only the compositor's output is clipped. Native frame scheduling (including
+// rAF on otherwise quiet pages) remains Chromium's responsibility.
+const SURFACES = new WeakMap<Page, Promise<Surface>>();
+
+class Surface {
+  private tail: Promise<unknown> = Promise.resolve();
+  constructor(private page: Page, private cdp: CDPSession,
+    private options: { mobile: boolean; deviceScaleFactor: number }) {}
+
+  async apply(reduced: boolean) {
+    const viewport = this.page.viewportSize();
+    if (!viewport) throw new Error("Browser surface requires a fixed viewport");
+    const landscape = viewport.width > viewport.height;
+    await this.cdp.send("Emulation.setDeviceMetricsOverride", {
+      ...viewport,
+      ...this.options,
+      screenWidth: viewport.width,
+      screenHeight: viewport.height,
+      screenOrientation: this.options.mobile
+        ? { angle: landscape ? 90 : 0, type: landscape ? "landscapePrimary" : "portraitPrimary" }
+        : { angle: 0, type: "landscapePrimary" },
+      ...(reduced ? { viewport: { x: 0, y: 0, width: 1, height: 1, scale: 1 } } : {}),
+    });
+  }
+
+  screenshot(): Promise<{ data: string }> {
+    // Concurrent screenshots must not shrink another capture's surface.
+    const result = this.tail.then(async () => {
+      try {
+        await this.apply(false);
+        // Capture through the same emulation agent: a different CDP session
+        // can read back mobile screenshots at the wrong device scale.
+        return await this.cdp.send("Page.captureScreenshot", { format: "png" });
+      } finally {
+        if (!this.page.isClosed()) await this.apply(true);
+      }
+    });
+    this.tail = result.catch(() => {});
+    return result;
+  }
+}
+
+export function reduceBrowserSurfaces(context: BrowserContext,
+  options: { mobile: boolean; deviceScaleFactor: number }) {
+  context.on("page", page => {
+    const pending = (async () => {
+      const surface = new Surface(page, await context.newCDPSession(page), options);
+      await surface.apply(true);
+      return surface;
+    })();
+    SURFACES.set(page, pending);
+    // spawnPage awaits this for SDK views. Popups have no spawnPage caller.
+    void pending.catch(error => {
+      if (!page.isClosed()) console.warn("[spectest] failed to reduce browser surface:", error);
+    });
+  });
+}
+
+export async function awaitBrowserSurface(page: Page): Promise<void> {
+  await SURFACES.get(page);
+}
+
+export async function captureBrowserScreenshot(page: Page, cdp: CDPSession): Promise<{ data: string }> {
+  const surface = await SURFACES.get(page);
+  // Externally attached browsers (e.g. Electron) retain their own viewport.
+  return surface ? surface.screenshot() : cdp.send("Page.captureScreenshot", { format: "png" });
+}

package/src/browser.ts

@@ -67,6 +67,7 @@ import type {
 } from "./locator.js";
 
 import { chromium } from "playwright-core";
+import { reduceBrowserSurfaces, awaitBrowserSurface, captureBrowserScreenshot } from "./browser-surface.js";
 import type {
   Browser as PlaywrightBrowser,
   BrowserContext,
@@ -543,6 +544,7 @@ async function newViewContext(
       timezoneId: opts.timezone,
       locale: opts.locale,
     });
+    reduceBrowserSurfaces(context, { mobile: !!device, deviceScaleFactor: device?.deviceScaleFactor ?? 1 });
     context.setDefaultTimeout(DEFAULT_ACTION_TIMEOUT_MS);
     context.setDefaultNavigationTimeout(NAVIGATION_TIMEOUT_MS);
     if (fixture) {
@@ -1288,6 +1290,7 @@ const VIEW_POOL: PooledView[] = [];
  *  slow part (renderer process spawn). */
 async function spawnPage(context: BrowserContext): Promise<SpawnedPage> {
   const page = await context.newPage();
+  await awaitBrowserSurface(page);
   const cdp = await context.newCDPSession(page);
   // Without Page.enable the addScriptToEvaluateOnNewDocument registration
   // silently never fires on this session (verified in the fork spike).
@@ -2199,9 +2202,7 @@ function buildBackend(
         }
         // Raw CDP rather than page.screenshot(): captures the viewport
         // exactly like the pre-Playwright backend.
-        const res = (await holder.cdp.send("Page.captureScreenshot", {
-          format: "png",
-        } as never)) as { data: string };
+        const res = await captureBrowserScreenshot(holder.page, holder.cdp);
         const id = generateId("art");
         register({
           id,

package/src/daemon.ts

@@ -109,6 +109,7 @@ import {
   type CaseMeta,
   type GroupMeta,
 } from "./harness/catalogue.js";
+import { shadowBuilder, shadowImage, shadowOutput, imageDigest, shadowTiming } from "./harness/shadow-builder.js";
 import { summarizeBuildKit, type BuildStep } from "./harness/buildkit-progress.js";
 import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta, mergeServiceLogDeltas } from "./harness/log-delta.js";
 import {
@@ -1364,18 +1365,27 @@ async function runServiceBuild(
     // own layer cache, and the finished image is already in the store
     // dockerd reads. dockerd's built-in BuildKit is the fallback (a guest
     // with no store, or a daemon that would not start).
-    const useLocal = await ensureLocalBuildkitd();
+    const remote = await shadowBuilder();
+    const useLocal = !remote && await ensureLocalBuildkitd();
     // Both the in-VM daemon and dockerd's buildx are BuildKit, so both
     // emit per-step timing on stderr under `--progress=plain` (parsed
     // below). Only the legacy builder takes no progress flag.
-    const useBuildKit = useLocal || (await hasBuildx());
+    const useBuildKit = !!remote || useLocal || (await hasBuildx());
     const buildEnv: Record<string, string> = {};
     let buildArgs: string[];
     // The user's `buildArgs`, as `--build-arg` flags; a plain client flag,
     // so every builder — in-VM BuildKit, dockerd's own, legacy — takes it.
     const argFlags = [...buildTargetFlags(image.target), ...buildArgFlags(image.buildArgs)];
     const contextDir = image.contextDir;
-    if (useLocal) {
+    const remoteReference = remote ? shadowImage(remote, name) : undefined;
+    const metadataPath = path.join(dfDir, "shadow-result.json");
+    const buildStarted = Date.now();
+    if (remote) {
+      buildArgs = ["buildx", "build", "--builder", remote.builder,
+        "--progress=plain", "--metadata-file", metadataPath,
+        "--output", shadowOutput(remoteReference!), ...argFlags,
+        "-f", dfPath, contextDir];
+    } else if (useLocal) {
       // The in-VM builder is BuildKit's containerd worker on this VM's
       // own image store (CONTAINER_STORE.md): the output is an image
       // record in dockerd's namespace, unpacked, so there is no `--load`
@@ -1452,9 +1462,20 @@ async function runServiceBuild(
         }
     });
     const log = `${build.stderr.trim()}\n${build.stdout.trim()}`;
+    if (remote) await shadowTiming(name, "solve-export-push", buildStarted, { ok: build.code === 0 });
     if (build.code !== 0) {
       return { ok: false, log };
     }
+    if (remote) {
+      const digest = imageDigest(JSON.parse(await fs.readFile(metadataPath, "utf8")));
+      const immutable = `${remoteReference!.split(":result")[0]}@${digest}`;
+      const pullStarted = Date.now();
+      const pulled = await shxStream("docker", ["pull", immutable], undefined, undefined, () => {});
+      await shadowTiming(name, "pull-unpack", pullStarted, { digest, ok: pulled.code === 0, lazy: false });
+      if (pulled.code !== 0) return { ok: false, log: pulled.stderr };
+      const tagged = await docker(["tag", immutable, tag]);
+      if (tagged.code !== 0) return { ok: false, log: tagged.stderr };
+    }
     if (useBuildKit) {
       // Keep only the slowest dozen steps ≥1s — enough to profile, small
       // enough to ride back in the /bootstrap response and the journal.
@@ -6101,7 +6122,7 @@ export function harnessMethods(state: RouteState): MethodTable {
   return {
     health: async () => ({
       ok: true,
-      capabilities: ["prepared-images-v1"],
+      capabilities: ["prepared-images-v1", "shadow-builder-v1"],
       // Optional discovery: old SDKs omit this field and are never sent the
       // new method. Check the loaded project, including after warm restore.
       setupInteractive: typeof loaded?.project.interactive?.seed === "function",

package/src/harness/shadow-builder.test.ts

@@ -0,0 +1,29 @@
+import { expect, test } from "bun:test";
+import { imageDigest, shadowBuilder, shadowImage, shadowOutput, validateShadowBuilder } from "./shadow-builder";
+const config = { version: 1, builder: "shadow-test", registry: "registry.example.com", experiment: "experiment-1" } as const;
+test("shadow image namespaces isolate experiments and hash untrusted service names", () => {
+  const a = shadowImage(config, "../../other,compression=gzip");
+  expect(a).toMatch(/^registry.example.com\/shadow\/experiment-1\/[a-f0-9]{32}:result$/);
+  expect(shadowImage({ ...config, experiment: "experiment-2" }, "api")).not.toBe(shadowImage(config, "api"));
+  expect(shadowOutput(a)).toContain("compression=zstd");
+});
+test("configuration rejects exporter and endpoint injection", () => {
+  expect(validateShadowBuilder(config)).toEqual(config);
+  for (const registry of ["https://example.com", "example.com,push=false", "user:secret@example.com", "example.com/path"]) {
+    expect(() => validateShadowBuilder({ ...config, registry })).toThrow();
+  }
+});
+test("delivery requires a content digest, never a mutable tag", () => {
+  expect(imageDigest({ "containerimage.digest": `sha256:${"a".repeat(64)}` })).toBe(`sha256:${"a".repeat(64)}`);
+  for (const value of [null, {}, { "containerimage.digest": "latest" }]) expect(() => imageDigest(value)).toThrow();
+});
+
+test("ordinary SDK execution never needs remote builder configuration", async () => {
+  const previous = process.env.SPECTEST_SHADOW_BUILD;
+  delete process.env.SPECTEST_SHADOW_BUILD;
+  try { expect(await shadowBuilder()).toBeUndefined(); }
+  finally {
+    if (previous === undefined) delete process.env.SPECTEST_SHADOW_BUILD;
+    else process.env.SPECTEST_SHADOW_BUILD = previous;
+  }
+});

package/src/harness/shadow-builder.ts

@@ -0,0 +1,41 @@
+/** Internal experiment configuration. Never selected by project configuration. */
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+
+export interface ShadowBuilder {
+  version: 1;
+  builder: string;
+  registry: string;
+  experiment: string;
+}
+export function validateShadowBuilder(value: unknown): ShadowBuilder {
+  const c = value as ShadowBuilder;
+  if (!c || c.version !== 1 || !/^shadow-[a-z0-9-]+$/.test(c.builder)
+    || !/^[a-z0-9.-]+(?::[0-9]+)?$/.test(c.registry)
+    || !/^[a-z0-9-]{1,80}$/.test(c.experiment)) throw new Error("invalid shadow builder configuration");
+  return c;
+}
+export async function shadowBuilder(): Promise<ShadowBuilder | undefined> {
+  if (process.env.SPECTEST_SHADOW_BUILD !== "1") return undefined;
+  // A missing configuration is an experiment failure, never a local build.
+  return validateShadowBuilder(JSON.parse(await fs.readFile("/run/spectest/shadow-builder.json", "utf8")));
+}
+export function shadowImage(c: ShadowBuilder, service: string): string {
+  const id = createHash("sha256").update(service).digest("hex").slice(0, 32);
+  return `${c.registry}/shadow/${c.experiment}/${id}:result`;
+}
+export function shadowOutput(reference: string): string {
+  return `type=image,name=${reference},push=true,oci-mediatypes=true,compression=zstd`;
+}
+export function imageDigest(metadata: unknown): string {
+  const digest = (metadata as Record<string, unknown>)?.["containerimage.digest"];
+  if (typeof digest !== "string" || !/^sha256:[0-9a-f]{64}$/.test(digest)) {
+    throw new Error("remote builder did not return an image digest");
+  }
+  return digest;
+}
+export async function shadowTiming(service: string, phase: string, started: number, extra = {}) {
+  await fs.appendFile("/run/spectest/shadow-timings.jsonl", JSON.stringify({
+    service, phase, startedMs: started, durationMs: Date.now() - started, ...extra,
+  }) + "\n");
+}