@specific.dev/spectest 0.89.1 → 0.90.1

package/src/eval-fetch.test.ts

@@ -0,0 +1,111 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+test("interactive ctx.fetch keeps its wrapped contract across module evaluation", async () => {
+  // Exercise the real eval import boundary in a separate process: the daemon
+  // changes globals and captures stdout, and APP_DIR is fixed at import time.
+  const root = await mkdtemp(join(tmpdir(), "spectest-eval-fetch-"));
+  try {
+    const daemon = new URL("./daemon.ts", import.meta.url).href;
+    const scopes = new URL("./harness/instrumentation-scope.ts", import.meta.url).href;
+    const recorder = new URL("./recorder.ts", import.meta.url).href;
+    const url = "data:application/json,%7B%22id%22%3A%22example%22%7D";
+    await writeFile(join(root, "helper.ts"), `
+      export async function read(fetcher) {
+        await new Promise(resolve => setTimeout(resolve, 0));
+        const response = await fetcher(${JSON.stringify(url)});
+        return (await response.json()).id.unwrap();
+      }
+    `);
+    const reproducer = `
+      const r = await ctx.fetch(${JSON.stringify(url)});
+      const j = await r.json();
+      export default {
+        statusType: typeof r.status, statusUnwrap: typeof r.status.unwrap,
+        idType: typeof j.id, idUnwrap: typeof j.id.unwrap,
+      };
+    `;
+    const readers = `
+      import { read } from "../helper.ts";
+      const r = await ctx.fetch(${JSON.stringify(url)});
+      const clone = r.clone();
+      await Promise.resolve();
+      const body = await r.json();
+      const { fetch: fetcher } = ctx;
+      export default {
+        status: r.status.unwrap(), ok: r.ok.unwrap(),
+        contentType: r.headers.get("content-type").unwrap(),
+        id: body.id.unwrap(), text: (await clone.text()).unwrap(),
+        rawStatus: r.unwrap().status, helperId: await read(fetcher),
+      };
+    `;
+    const script = `
+      import { strict as assert } from "node:assert";
+      import { METHODS } from ${JSON.stringify(daemon)};
+      import { currentInstrumentationScope, runUninstrumented } from ${JSON.stringify(scopes)};
+      import { startRecording, stopRecording } from ${JSON.stringify(recorder)};
+      const originalFetch = globalThis.fetch;
+      const url = ${JSON.stringify(url)};
+      const contentType = (await originalFetch(url)).headers.get("content-type");
+      startRecording();
+      const result = await METHODS.eval({ code: ${JSON.stringify(reproducer)} });
+      assert.equal(result.ok, true, JSON.stringify(result));
+      assert.deepEqual(result.result, {
+        statusType: "object", statusUnwrap: "function",
+        idType: "object", idUnwrap: "function",
+      });
+      const values = await METHODS.eval({ code: ${JSON.stringify(readers)} });
+      assert.equal(values.ok, true, JSON.stringify(values));
+      assert.deepEqual(values.result, {
+        status: 200, ok: true, contentType,
+        id: "example", text: '{"id":"example"}', rawStatus: 200,
+        helperId: "example",
+      });
+      // Fake/background work outside the eval's call must still see native fetch.
+      let releaseBackground;
+      const released = new Promise(resolve => { releaseBackground = resolve; });
+      const background = released.then(async () => {
+        const r = await fetch(url);
+        assert.equal(r.status, 200);
+        assert.equal((await r.json()).id, "example");
+      });
+      globalThis.nativeProbe = async () => {
+        releaseBackground();
+        await background;
+        await runUninstrumented(async () => {
+          await Promise.resolve();
+          const fakeResponse = await fetch(url);
+          assert.equal(fakeResponse.status, 200);
+          assert.equal((await fakeResponse.json()).id, "example");
+        });
+      };
+      const isolated = await METHODS.eval({ code: "await nativeProbe();" });
+      assert.equal(isolated.ok, true, JSON.stringify(isolated));
+      const failed = await METHODS.eval({ code: 'await ctx.fetch(' + JSON.stringify(url) + '); throw new Error("expected");' });
+      assert.equal(failed.ok, false);
+      assert.equal(failed.error.message, "expected");
+      assert.equal(globalThis.fetch, originalFetch);
+      assert.equal(currentInstrumentationScope(), undefined);
+      assert.equal((await fetch(url)).status, 200);
+      const next = await METHODS.eval({ code: ${JSON.stringify(reproducer)} });
+      assert.equal(next.ok, true, JSON.stringify(next));
+      assert.deepEqual(next.result, result.result);
+      assert.deepEqual(stopRecording(), []);
+    `;
+    const child = Bun.spawn([process.execPath, "--eval", script], {
+      env: { ...process.env, SPECTEST_APP_DIR: root },
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [code, stdout, stderr] = await Promise.all([
+      child.exited,
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+    ]);
+    expect(code, stdout + stderr).toBe(0);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+}, 20_000);

package/src/harness/main.ts

@@ -34,6 +34,7 @@
  */
 
 import net from "node:net";
+import { initializeStickyConsumer, STICKY_CAPABILITY, type StickyConsumerConfig } from "./sticky-consumer";
 
 import { METHODS } from "../daemon";
 import { codeOf } from "./methods";
@@ -50,7 +51,7 @@ import {
 
 /** Capabilities this build announces. Empty is fine — the slot is what
  *  matters, so a later release has something to negotiate against. */
-const CAPABILITIES: string[] = [];
+const CAPABILITIES: string[] = [STICKY_CAPABILITY];
 
 type Handler = (params: Record<string, unknown>) => Promise<unknown>;
 
@@ -65,6 +66,10 @@ export function handlers(
   return {
     // Everything the environment actually does.
     ...methods,
+    stickyInitialize: async (params) => {
+      await initializeStickyConsumer(params as unknown as StickyConsumerConfig);
+      return { initialized: true };
+    },
     // Transport-level methods, which the method table has no business
     // knowing about: they concern this connection, not this environment.
     // Declared after the spread so the table can never shadow them — a

package/src/harness/sticky-consumer.test.ts

@@ -0,0 +1,45 @@
+import { expect, test } from "bun:test";
+import { STICKY_COMPATIBILITY, validateStickyConfig, collectStickyCache } from "./sticky-consumer";
+
+const GiB = 1024 ** 3;
+const config = { path: "/var/lib/spectest-sticky", capacityBytes: 256 * GiB,
+  headroomBytes: 32 * GiB, cacheTargetBytes: 64 * GiB, buildkitTargetBytes: 32 * GiB,
+  compatibility: STICKY_COMPATIBILITY };
+
+test("sticky consumer validates independent retention and working budgets", () => {
+  expect(() => validateStickyConfig(config)).not.toThrow();
+  // Changing capacity does not require increasing either retention target.
+  expect(() => validateStickyConfig({ ...config, capacityBytes: 512 * GiB })).not.toThrow();
+  for (const override of [{ path: "/" }, { compatibility: "legacy" }, { headroomBytes: 0 },
+    { headroomBytes: config.capacityBytes }, { capacityBytes: Number.NaN },
+    { cacheTargetBytes: 240 * GiB }, { buildkitTargetBytes: 65 * GiB }, { cacheTargetBytes: Number.NaN }]) {
+    expect(() => validateStickyConfig({ ...config, ...override })).toThrow();
+  }
+});
+
+test("filesystem pressure removes oldest Docker images when BuildKit pruning frees nothing", async () => {
+  let used = 100 * GiB;
+  const calls: string[][] = [];
+  const run = async (command: string, args: string[]) => {
+    calls.push([command, ...args]);
+    if (command === "docker" && args[1] === "ls") return "new\nold\n";
+    if (command === "docker" && args[1] === "inspect") return JSON.stringify([
+      { Id: "new", Created: "2026-09-29T10:00:00Z" }, { Id: "old", Created: "2026-09-28T10:00:00Z" }]);
+    if (command === "docker" && args[1] === "rm") used -= 40 * GiB;
+    return ""; // Model Harmony: BuildKit's own GC reports no reclaimable data.
+  };
+  await collectStickyCache(config, run, async () => ({ totalBytes: 256 * GiB, freeBytes: 256 * GiB - used }));
+  expect(calls.filter(c => c[2] === "rm")).toEqual([["docker", "image", "rm", "-f", "old"]]);
+  const prune = calls.find(c => c.includes("--free-storage"))!;
+  expect(prune[prune.indexOf("--keep-storage") + 1]).toBe(String(Math.floor(32 * GiB / 1e6)));
+  expect(prune[prune.indexOf("--free-storage") + 1]).toBe(String(Math.ceil(192 * GiB / 1e6)));
+});
+
+test("healthy cache keeps recent images and a cache that cannot shrink is not published", async () => {
+  const calls: string[][] = [];
+  const run = async (command: string, args: string[]) => { calls.push([command, ...args]); return ""; };
+  await collectStickyCache(config, run, async () => ({ totalBytes: 256 * GiB, freeBytes: 220 * GiB }));
+  expect(calls.some(c => c[2] === "rm" || c[2] === "inspect")).toBe(false);
+  await expect(collectStickyCache(config, run, async () => ({ totalBytes: 256 * GiB, freeBytes: 5 * GiB })))
+    .rejects.toThrow("cannot meet filesystem retention target");
+});

package/src/harness/sticky-consumer.ts

@@ -0,0 +1,176 @@
+/** Docker/BuildKit policy for the generic sticky disk. No host publication API. */
+import { execFile } from "node:child_process";
+import { mkdir, readFile, statfs, writeFile } from "node:fs/promises";
+
+export const STICKY_CAPABILITY = "sticky-disks-v1";
+export const STICKY_COMPATIBILITY = "docker29-ctr21-buildkit032-overlayfs-256g-v2";
+export const STICKY_RUNTIME = "/run/spectest-sticky";
+export interface StickyConsumerConfig {
+  path: string;
+  capacityBytes: number;
+  headroomBytes: number;
+  cacheTargetBytes: number;
+  buildkitTargetBytes: number;
+  compatibility: string;
+}
+
+function exec(program: string, args: string[], timeout = 60_000): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile(program, args, { timeout, maxBuffer: 8 * 1024 * 1024 }, (error, stdout, stderr) => {
+      if (error) reject(new Error(`${program} failed: ${stderr || stdout || error.message}`));
+      else resolve(stdout.trim());
+    });
+  });
+}
+async function ready(program: string, args: string[]): Promise<void> {
+  const deadline = Date.now() + 30_000;
+  let last: unknown;
+  do {
+    try { await exec(program, args, 2000); return; } catch (error) { last = error; }
+    await Bun.sleep(100);
+  } while (Date.now() < deadline);
+  throw last;
+}
+export function validateStickyConfig(config: StickyConsumerConfig): void {
+  if (config.path !== "/var/lib/spectest-sticky" || config.compatibility !== STICKY_COMPATIBILITY ||
+      !Number.isSafeInteger(config.capacityBytes) || config.capacityBytes <= 0 ||
+      !Number.isSafeInteger(config.headroomBytes) || config.headroomBytes < 16 * 1024 * 1024 ||
+      !Number.isSafeInteger(config.cacheTargetBytes) || config.cacheTargetBytes <= 0 ||
+      !Number.isSafeInteger(config.buildkitTargetBytes) || config.buildkitTargetBytes <= 0 ||
+      config.buildkitTargetBytes > config.cacheTargetBytes ||
+      config.cacheTargetBytes + config.headroomBytes >= config.capacityBytes) {
+    throw new Error("unsupported sticky consumer profile or budget");
+  }
+}
+
+export async function initializeStickyConsumer(config: StickyConsumerConfig): Promise<void> {
+  validateStickyConfig(config);
+  await exec("mountpoint", ["-q", config.path]);
+  // The base must have stopped these before its RAM was captured. Refuse an
+  // unexpected writer rather than racing it for the standard daemon sockets.
+  for (const unit of ["docker.service", "docker.socket", "containerd.service"]) {
+    const state = await exec("systemctl", ["show", unit, "-p", "ActiveState", "--value"]);
+    if (!["inactive", "failed"].includes(state)) throw new Error(`sticky base has active legacy consumer: ${unit}: ${state}`);
+  }
+  for (const [program, version] of [["dockerd", "29.7.2"], ["containerd", "v2.1.5"], ["buildkitd", "v0.32.2"]]) {
+    if (!(await exec(program!, ["--version"])).includes(version!)) throw new Error(`unsupported ${program} version for sticky profile`);
+  }
+  await mkdir(STICKY_RUNTIME, { recursive: true });
+  for (const child of ["docker", "containerd", "buildkit"]) await mkdir(`${config.path}/${child}`, { recursive: true });
+  await writeFile(`${STICKY_RUNTIME}/consumer.json`, JSON.stringify(config));
+  await writeFile(`${STICKY_RUNTIME}/containerd.toml`, `version = 2
+root = "${config.path}/containerd"
+state = "/run/containerd"
+disabled_plugins = ["io.containerd.grpc.v1.cri"]
+[grpc]
+  address = "/run/containerd/containerd.sock"
+`);
+  const dockerConfig = JSON.parse(await readFile("/etc/docker/daemon.json", "utf8"));
+  dockerConfig["data-root"] = `${config.path}/docker`;
+  dockerConfig.features = { "containerd-snapshotter": true };
+  dockerConfig["storage-driver"] = "overlayfs";
+  await writeFile(`${STICKY_RUNTIME}/docker.json`, JSON.stringify(dockerConfig));
+  await writeFile(`${STICKY_RUNTIME}/buildkit.toml`, `root = "${config.path}/buildkit"
+[grpc]
+  address = ["tcp://127.0.0.1:1234"]
+[worker.oci]
+  enabled = false
+[worker.containerd]
+  enabled = true
+  address = "/run/containerd/containerd.sock"
+  namespace = "moby"
+  snapshotter = "overlayfs"
+  gc = true
+  reservedSpace = "1GB"
+  maxUsedSpace = ${config.buildkitTargetBytes}
+  minFreeSpace = ${config.headroomBytes}
+`);
+  const start = async (unit: string, program: string, args: string[]) => {
+    await exec("systemd-run", ["--quiet", "--unit", unit, "-p", "TimeoutStopSec=30",
+      // Pinned BuildKit 0.32.2 returns 1 after its normal first-SIGTERM
+      // shutdown (util/appcontext). A timeout/signal still fails the unit.
+      ...(unit === "spectest-sticky-buildkit" ? ["-p", "SuccessExitStatus=1"] : []),
+      program, ...args]);
+  };
+  await start("spectest-sticky-containerd", "containerd", ["--config", `${STICKY_RUNTIME}/containerd.toml`]);
+  await ready("ctr", ["version"]);
+  await start("spectest-sticky-docker", "dockerd", ["--config-file", `${STICKY_RUNTIME}/docker.json`,
+    "--host", "unix:///run/docker.sock", "--exec-root", "/run/docker", "--pidfile", "/run/docker.pid",
+    "--containerd", "/run/containerd/containerd.sock", "--containerd-namespace", "moby"]);
+  await ready("docker", ["info"]);
+  await start("spectest-sticky-buildkit", "buildkitd", ["--config", `${STICKY_RUNTIME}/buildkit.toml`]);
+  await ready("buildctl", ["--addr", "tcp://127.0.0.1:1234", "debug", "workers"]);
+  await exec("docker", ["buildx", "create", "--name", "spectest-local", "--driver", "remote", "tcp://127.0.0.1:1234"]);
+  await exec("docker", ["buildx", "inspect", "--bootstrap", "spectest-local"]);
+}
+
+/** Filesystem pressure takes precedence over cache age/BuildKit record sizes.
+ * Only called after runtime containers/volumes have been removed on the
+ * isolated publication clone. Never removes files behind the daemons' backs.
+ */
+export async function collectStickyCache(
+  config: StickyConsumerConfig,
+  run: typeof exec = exec,
+  usage = async (): Promise<{ freeBytes: number; totalBytes: number }> => {
+    const fs = await statfs(config.path);
+    return { freeBytes: fs.bavail * fs.bsize, totalBytes: fs.blocks * fs.bsize };
+  },
+): Promise<void> {
+  validateStickyConfig(config);
+  const buildctl = ["--addr", "tcp://127.0.0.1:1234", "prune"];
+  await run("buildctl", [...buildctl, "--keep-duration", "168h"], 120_000);
+  await run("docker", ["image", "prune", "-af", "--filter", "until=168h"], 120_000);
+  const withinTarget = (fs: { freeBytes: number; totalBytes: number }) =>
+    fs.freeBytes >= config.headroomBytes && fs.totalBytes - fs.freeBytes <= config.cacheTargetBytes;
+  let fs = await usage();
+  // Always enforce the independent BuildKit target. Its accounting alone
+  // cannot bound shared images/content, so also request real filesystem space.
+  const pruneBuildkit = async () => {
+    await run("buildctl", [...buildctl, "--all", "--keep-storage",
+      String(Math.floor(config.buildkitTargetBytes / 1e6)), "--free-storage",
+      String(Math.ceil(Math.max(config.headroomBytes, fs.totalBytes - config.cacheTargetBytes) / 1e6))], 120_000);
+    fs = await usage();
+  };
+  await pruneBuildkit();
+  if (withinTarget(fs)) return;
+  // Pressure can be entirely in recent Docker images. Drop oldest images
+  // first, even within the age window, until the whole filesystem fits.
+  const ids = [...new Set((await run("docker", ["image", "ls", "-aq", "--no-trunc"])).split(/\s+/).filter(Boolean))];
+  const images: { Id: string; Created: string }[] = ids.length
+    ? JSON.parse(await run("docker", ["image", "inspect", ...ids])) : [];
+  images.sort((a, b) => a.Created.localeCompare(b.Created) || a.Id.localeCompare(b.Id));
+  for (const image of images) {
+    await run("docker", ["image", "rm", "-f", image.Id], 120_000);
+    await pruneBuildkit();
+    if (withinTarget(fs)) return;
+  }
+  // Containerd GC may lag reference removal; allow bounded additional passes.
+  for (let pass = 0; pass < 3 && !withinTarget(fs); pass++) await pruneBuildkit();
+  if (!withinTarget(fs)) throw new Error("sticky cache cannot meet filesystem retention target and write headroom");
+}
+
+/** Only on an isolated maintenance clone; never on the live ready environment. */
+export async function prepareStickyConsumer(artifact = false): Promise<{ prepared: true; freeBytes: number }> {
+  const config: StickyConsumerConfig = JSON.parse(await readFile(`${STICKY_RUNTIME}/consumer.json`, "utf8"));
+  validateStickyConfig(config);
+  if (!artifact) {
+    const containers = (await exec("docker", ["ps", "-aq"])).split(/\s+/).filter(Boolean);
+    if (containers.length) await exec("docker", ["rm", "-f", ...containers]);
+    const volumes = (await exec("docker", ["volume", "ls", "-q"])).split(/\s+/).filter(Boolean);
+    if (volumes.length) await exec("docker", ["volume", "rm", ...volumes]);
+    await collectStickyCache(config);
+  }
+  const units = ["spectest-sticky-buildkit", "spectest-sticky-docker", "spectest-sticky-containerd"];
+  for (const unit of units) {
+    const active = await exec("systemctl", ["show", unit, "-p", "ActiveState", "--value"]);
+    if (active !== "active") throw new Error(`consumer exited before sealing: ${unit}: ${active}`);
+    await exec("systemctl", ["stop", unit], 45_000);
+    const result = await exec("systemctl", ["show", unit, "-p", "Result", "--value"]);
+    if (result !== "success") throw new Error(`unclean consumer shutdown: ${unit}: ${result}`);
+  }
+  const fs = await statfs(config.path);
+  const freeBytes = fs.bavail * fs.bsize;
+  if (freeBytes < config.headroomBytes) throw new Error("sticky publication has insufficient write headroom");
+  // The supervisor verifies and unmounts; only the worker seals/publishes.
+  return { prepared: true, freeBytes };
+}

package/src/harness/sticky-maintenance.ts

@@ -0,0 +1,7 @@
+// Dedicated entry point: no daemon.ts, project modules, bootstrap or tests.
+import { prepareStickyConsumer } from "./sticky-consumer";
+
+if (import.meta.main) {
+  try { console.log(JSON.stringify(await prepareStickyConsumer(process.argv.includes("--artifact")))); }
+  catch (error) { console.error(error); process.exitCode = 1; }
+}

package/src/index.ts

@@ -1,3 +1,5 @@
+import type { Android, AndroidApp } from "./android.js";
+export type { Android, AndroidApp, AndroidElement, AndroidRecordingOptions } from "./android.js";
 // Spectest SDK. The user's single `spectest/index.ts` calls
 // `defineEnvironment({ name, services })` once, defines test cases via
 // the returned `env.test(...)`, and default-exports `env.project([...])`.
@@ -1967,6 +1969,8 @@ export interface TestContext<
    * like named desktop browsers.
    */
   mobile(app: MobileApp, name?: string): Promise<Mobile>;
+  /** Native Android via Appium. Recording is automatic for test cases; the app and session survive forks. */
+  android(app: AndroidApp): Promise<Android>;
   /** Drive a real Electron renderer window through locators and user input.
    * Acquires the app started by electron(); keeps its live state across forks.
    * Each test gets a self-contained graphical replay. Selecting another window

package/src/recorder.ts

@@ -8,6 +8,7 @@
 // current recorder is `null` and the `record*` helpers are no-ops, so
 // callers can invoke them unconditionally.
 
+import type { AndroidStepDetails } from "./android-step.js";
 import { clearPendingNullish } from "./inspect.js";
 import { scopeAllowsRecording } from "./harness/instrumentation-scope.js";
 
@@ -632,7 +633,7 @@ export interface EventReservation {
 class Recorder {
   private events: TestEvent[] = [];
   private seq = 0;
-  private readonly start = Date.now();
+  constructor(private readonly start = Date.now()) {}
 
   /** Claim a seq + start offset now; pass the result to `push` at finish. */
   reserve(): EventReservation {
@@ -753,8 +754,8 @@ function active(): boolean {
   return current !== null && paused === 0 && scopeAllowsRecording();
 }
 
-export function startRecording(): void {
-  current = new Recorder();
+export function startRecording(startedAt = Date.now()): void {
+  current = new Recorder(startedAt);
   paused = 0;
 }
 
@@ -911,6 +912,8 @@ export interface StepEvent extends BaseEvent {
   kind: string;
   /** The step's one-line summary in the timeline. */
   title: string;
+  /** Native action semantics; titles are presentation only. */
+  android?: AndroidStepDetails;
   blocks?: StepBlock[];
   status?: "passed" | "failed" | "error";
   durationMs?: number;