@specific.dev/spectest 0.89.1 → 0.90.0

package/dist/components/android.d.ts

@@ -0,0 +1,74 @@
+import { type AndroidApp, type AndroidRecordingOptions } from "../android.js";
+export interface AndroidOptions {
+    /** Project-relative path to an APK built for the worker's native ABI. */
+    apk: string;
+    /** Android application id, for example com.example.app. */
+    package: string;
+    /** Launch activity, for example .MainActivity. */
+    activity: string;
+    /** Android image; default is the tested Android 14 arm64-only redroid image. */
+    image?: string;
+    /** Optional prebuilt image containing the same tools as ANDROID_TOOLS_DOCKERFILE. */
+    toolsImage?: string;
+    /** Display defaults to Pixel 8 dimensions: 1080 × 2400, at 420 logical dpi. */
+    width?: number;
+    height?: number;
+    dpi?: number;
+    /** Show tap markers in replay and enable native physical-touch feedback. Default true. */
+    showTouches?: boolean;
+    recording?: false | AndroidRecordingOptions;
+    dependsOn?: string[];
+}
+export declare const ANDROID_TOOLS_DOCKERFILE = "FROM node:22-bookworm-slim\nRUN apt-get update && apt-get install -y --no-install-recommends adb aapt apksigner zipalign ffmpeg default-jdk-headless ca-certificates curl gcc pkg-config meson ninja-build libsdl2-dev libavcodec-dev libavdevice-dev libavformat-dev libavutil-dev libswresample-dev libusb-1.0-0-dev && rm -rf /var/lib/apt/lists/*\nRUN curl -fL https://github.com/Genymobile/scrcpy/archive/refs/tags/v3.3.1.tar.gz | tar xz -C /tmp && curl -fL https://github.com/Genymobile/scrcpy/releases/download/v3.3.1/scrcpy-server-v3.3.1 -o /tmp/scrcpy-server && meson setup /tmp/scrcpy-build /tmp/scrcpy-3.3.1 --buildtype=release -Dprebuilt_server=/tmp/scrcpy-server && ninja -C /tmp/scrcpy-build -j4 install && rm -rf /tmp/scrcpy*\nENV ANDROID_HOME=/opt/android JAVA_HOME=/usr/lib/jvm/default-java APPIUM_HOME=/opt/appium\nRUN mkdir -p /opt/android/platform-tools && for tool in adb aapt aapt2 apksigner zipalign; do ln -s /usr/bin/$tool /opt/android/platform-tools/$tool; done && npm install -g appium@3.8.0 && appium driver install uiautomator2@8.7.0\n";
+/** Native Android, Appium and software recording, all inside the environment VM. */
+export declare function android(options: AndroidOptions): import("../index.js").ServiceGroup<{
+    device: {
+        image: {
+            type: "registry";
+            reference: string;
+        };
+        privileged: true;
+        args: string[];
+        ports: number[];
+        dependsOn: string[] | undefined;
+        readyCheck: {
+            type: "exec";
+            command: string;
+            timeoutSecs: number;
+        };
+    };
+    tools: {
+        image: {
+            type: "registry";
+            reference: string;
+            content?: undefined;
+        } | {
+            type: "dockerfile";
+            content: string;
+            reference?: undefined;
+        };
+        command: string;
+        files: {
+            path: string;
+            content: string;
+        }[];
+        volumes: {
+            source: string;
+            target: string;
+            readOnly: true;
+        }[];
+        inputs: string[];
+        env: {
+            ANDROID_SERIAL: string;
+            ANDROID_ACTIVITY: string;
+            ANDROID_SHOW_TOUCHES: string;
+        };
+        ports: number[];
+        readyCheck: {
+            type: "http";
+            port: number;
+            path: string;
+            timeoutSecs: number;
+        };
+    };
+}, AndroidApp, "tools">;

package/dist/components/android.js

@@ -0,0 +1,92 @@
+import { readFileSync } from "node:fs";
+import { posix } from "node:path";
+import { serviceGroup } from "../index.js";
+import { resolveExistingProjectPath } from "../project-files.js";
+import { androidApp } from "../android.js";
+export const ANDROID_TOOLS_DOCKERFILE = `FROM node:22-bookworm-slim
+RUN apt-get update && apt-get install -y --no-install-recommends adb aapt apksigner zipalign ffmpeg default-jdk-headless ca-certificates curl gcc pkg-config meson ninja-build libsdl2-dev libavcodec-dev libavdevice-dev libavformat-dev libavutil-dev libswresample-dev libusb-1.0-0-dev && rm -rf /var/lib/apt/lists/*
+RUN curl -fL https://github.com/Genymobile/scrcpy/archive/refs/tags/v3.3.1.tar.gz | tar xz -C /tmp && curl -fL https://github.com/Genymobile/scrcpy/releases/download/v3.3.1/scrcpy-server-v3.3.1 -o /tmp/scrcpy-server && meson setup /tmp/scrcpy-build /tmp/scrcpy-3.3.1 --buildtype=release -Dprebuilt_server=/tmp/scrcpy-server && ninja -C /tmp/scrcpy-build -j4 install && rm -rf /tmp/scrcpy*
+ENV ANDROID_HOME=/opt/android JAVA_HOME=/usr/lib/jvm/default-java APPIUM_HOME=/opt/appium
+RUN mkdir -p /opt/android/platform-tools && for tool in adb aapt aapt2 apksigner zipalign; do ln -s /usr/bin/$tool /opt/android/platform-tools/$tool; done && npm install -g appium@3.8.0 && appium driver install uiautomator2@8.7.0
+`;
+/** Native Android, Appium and software recording, all inside the environment VM. */
+export function android(options) {
+    if (!options.apk ||
+        !/^[\w]+(?:\.[\w]+)+$/.test(options.package) ||
+        !/^[\w.$]+$/.test(options.activity))
+        throw new Error("android(): apk, package and activity are required");
+    const apk = posix.normalize(options.apk);
+    if (posix.isAbsolute(apk) || apk.startsWith("../") || apk.startsWith("spectest/tests/"))
+        throw new Error("android(): apk must be project-relative and outside spectest/tests so app changes invalidate snapshots");
+    const width = options.width ?? 1080, height = options.height ?? 2400, dpi = options.dpi ?? 420;
+    for (const value of [width, height, dpi])
+        if (!Number.isInteger(value) || value < 1 || value > 4096)
+            throw new Error("android(): invalid display dimensions/density");
+    return serviceGroup({
+        primary: "tools",
+        services: (g) => ({
+            device: {
+                image: {
+                    type: "registry",
+                    reference: options.image ??
+                        "redroid/redroid:14.0.0_64only-latest@sha256:0a611199ba2e0b5d60af39b3327a517f6407231f4352114ed3bd3cbfe2be69aa",
+                },
+                privileged: true,
+                // Android's netd ignores resolv.conf. Use Docker's per-container DNS,
+                // which resolves service aliases and forwards to the in-VM resolver.
+                args: [
+                    `androidboot.redroid_width=${width}`,
+                    `androidboot.redroid_height=${height}`,
+                    `androidboot.redroid_dpi=${dpi}`,
+                    "androidboot.redroid_gpu_mode=guest",
+                    "androidboot.use_memfd=1",
+                    "androidboot.redroid_net_ndns=1",
+                    "androidboot.redroid_net_dns1=127.0.0.11",
+                ],
+                ports: [5555],
+                dependsOn: options.dependsOn,
+                readyCheck: {
+                    type: "exec",
+                    command: 'test "$(getprop sys.boot_completed)" = 1',
+                    timeoutSecs: 180,
+                },
+            },
+            tools: {
+                image: options.toolsImage
+                    ? { type: "registry", reference: options.toolsImage }
+                    : { type: "dockerfile", content: ANDROID_TOOLS_DOCKERFILE },
+                command: "node /spectest-android.mjs",
+                files: [
+                    {
+                        path: "/spectest-android.mjs",
+                        content: readFileSync(new URL("./android-runtime.mjs", import.meta.url), "utf8"),
+                    },
+                ],
+                volumes: [
+                    {
+                        source: resolveExistingProjectPath(apk, "Android APK"),
+                        target: "/spectest/app.apk",
+                        readOnly: true,
+                    },
+                ],
+                inputs: [apk],
+                env: {
+                    ANDROID_SERIAL: `${g.key("device")}.internal:5555`,
+                    ANDROID_ACTIVITY: `${options.package}/${options.activity}`,
+                    ANDROID_SHOW_TOUCHES: options.showTouches === false ? "0" : "1",
+                },
+                ports: [4723, 4725],
+                readyCheck: { type: "http", port: 4725, path: "/ready", timeoutSecs: 240 },
+            },
+        }),
+        helpers: ({ name }) => androidApp({
+            name,
+            endpoint: `http://${name}.internal:4723`,
+            recorderEndpoint: `http://${name}.internal:4725`,
+            serial: `${name}-device.internal:5555`,
+            package: options.package,
+            recording: options.recording ?? {},
+            showTouches: options.showTouches ?? true,
+        }),
+    });
+}

package/dist/components/index.d.ts

@@ -15,3 +15,4 @@ export { microsoft, type MicrosoftOptions } from "./microsoft.js";
 export { okta, type OktaOptions } from "./okta.js";
 export { replayFake, type ReplayFakeOptions, type ReplayMatch, type InjectRule, type InjectMatch, type StringMatch, type SignConfig, type AwsSigV4Sign, type ReplayHelpers, type ReplaySummary, type Cassette, type CassetteInteraction, type CassetteRequest, type CassetteResponse, type CassetteState, } from "./replayFake.js";
 export { electron, type ElectronOptions } from "./electron.js";
+export { android, type AndroidOptions } from "./android.js";

package/dist/components/index.js

@@ -24,3 +24,4 @@ export { microsoft } from "./microsoft.js";
 export { okta } from "./okta.js";
 export { replayFake, } from "./replayFake.js";
 export { electron } from "./electron.js";
+export { android } from "./android.js";

package/dist/daemon.js

@@ -1,3 +1,4 @@
+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:
 //
@@ -488,6 +489,12 @@ function ensureLocalBuildkitd() {
     return _localBuilder;
 }
 async function bringUpLocalBuildkitd() {
+    if (existsSync("/run/spectest-sticky/consumer.json")) {
+        const ready = await docker(["buildx", "inspect", "--bootstrap", LOCAL_BUILDER_NAME], 30_000);
+        if (ready.code !== 0)
+            throw new Error(`sticky BuildKit unavailable: ${ready.stderr}`);
+        return true;
+    }
     const paths = await imageCachePaths();
     if (!paths)
         return false;
@@ -4369,6 +4376,8 @@ function captureConsole(chunks) {
 }
 async function runOne(testCase) {
     const start = Date.now();
+    const nativeAndroid = androidScope(testCase.id, start);
+    let androidRecordings = [];
     const chunks = [];
     const origStdout = process.stdout.write.bind(process.stdout);
     const origStderr = process.stderr.write.bind(process.stderr);
@@ -4522,7 +4531,8 @@ async function runOne(testCase) {
         });
         return term;
     };
-    startRecording();
+    // Share the case clock with native video timestamps and other artifacts.
+    startRecording(start);
     const restoreFetch = installFetchWrapper();
     const fetchScope = createInstrumentationScope();
     // Look up the parent's stored return value (if any). The parent ran in
@@ -4633,6 +4643,7 @@ async function runOne(testCase) {
         openTerminal: recordedOpenTerminal,
         browser: trackedOpenBrowser,
         mobile: trackedOpenMobile,
+        android: nativeAndroid.open,
         desktop: desktopOpener(start, testCase.id, sessions, browserDetaches),
         mcp: openMcp,
         testName: testCase.name,
@@ -4654,10 +4665,10 @@ async function runOne(testCase) {
     });
     // Result events are gathered inside finally (after the final browser
     // drains) so we hoist these out of the try/catch.
-    let outcome;
+    let outcome = { status: "passed" };
     try {
         const value = await Promise.race([
-            Promise.resolve(runInstrumented(fetchScope, () => testCase.run(ctx))),
+            Promise.resolve(runInstrumented(fetchScope, async () => { await nativeAndroid.begin(Object.values(base.svc).filter(isAndroidApp)); return testCase.run(ctx); })),
             timedOut,
         ]);
         // Stash the return value so child cases — which fork from the snapshot
@@ -4675,6 +4686,7 @@ async function runOne(testCase) {
     finally {
         if (timer)
             clearTimeout(timer);
+        nativeAndroid.deactivate();
         RECORDING_EXEC = undefined;
         INTERCEPTORS.endScope();
         fetchScope.active = false;
@@ -4699,6 +4711,10 @@ async function runOne(testCase) {
         }
         for (const s of sessions)
             s.markClosed();
+        androidRecordings = await nativeAndroid.finish();
+        const captureErrors = androidRecordings.flatMap(r => r.error ? [r.error] : []);
+        if (captureErrors.length && outcome.status === "passed")
+            outcome = { status: "failed", error: { message: captureErrors.join("\n") } };
     }
     const durationMs = Date.now() - start;
     // Capture each service's log delta (the lines THIS case added beyond its
@@ -4757,6 +4773,7 @@ async function runOne(testCase) {
     }
     return {
         status: outcome.status,
+        androidRecordings,
         durationMs,
         log: chunks.join(""),
         events,
@@ -4987,6 +5004,7 @@ function explainEvalExportError(code, message) {
 }
 async function evalCode(code) {
     const start = Date.now();
+    const nativeAndroid = androidScope("eval", start, { record: false });
     const chunks = [];
     const origStdout = process.stdout.write.bind(process.stdout);
     const origStderr = process.stderr.write.bind(process.stderr);
@@ -5113,6 +5131,7 @@ async function evalCode(code) {
         openTerminal: evalOpenTerminal,
         browser: trackedOpenBrowser,
         mobile: trackedOpenMobile,
+        android: nativeAndroid.open,
         desktop: desktopOpener(start, "eval", sessions, browserDetaches, artifactCollector),
         mcp: openMcp,
         testName: "eval",
@@ -5173,6 +5192,7 @@ async function evalCode(code) {
         }
         for (const s of sessions)
             s.markClosed();
+        await nativeAndroid.finish();
         if (filePath) {
             fs.unlink(filePath).catch(() => {
                 /* best-effort cleanup */
@@ -5676,6 +5696,8 @@ export function harnessMethods(state) {
         },
         // One chunk of a parked replay bundle. Case ids are arbitrary user
         // strings, so they travel in params rather than a URL path.
+        androidRecordingChunk: async (params) => androidRecordingChunk(String(params.caseId ?? params.id), params.offset, params.limit),
+        releaseAndroidRecording: async (params) => releaseAndroidRecording(String(params.id)),
         replayChunk: async (params) => {
             const caseId = requireString(params, "caseId", "caseId");
             const gz = REPLAY_BUNDLES.get(caseId);

package/dist/harness/main.js

@@ -33,12 +33,13 @@
  * transports. Two tables would each enforce the rule and together break it.
  */
 import net from "node:net";
+import { initializeStickyConsumer, STICKY_CAPABILITY } from "./sticky-consumer";
 import { METHODS } from "../daemon";
 import { codeOf } from "./methods";
 import { PROTOCOL_VERSION, decodeFrame, describeThrow, encodeFrame, fail, ok, } from "./protocol";
 /** Capabilities this build announces. Empty is fine — the slot is what
  *  matters, so a later release has something to negotiate against. */
-const CAPABILITIES = [];
+const CAPABILITIES = [STICKY_CAPABILITY];
 /** Methods this build can serve. Everything else is answered with an
  *  error naming the method, which is far easier to diagnose than a
  *  request that hangs. */
@@ -46,6 +47,10 @@ export function handlers(sdkVersion, onShutdown, methods = METHODS) {
     return {
         // Everything the environment actually does.
         ...methods,
+        stickyInitialize: async (params) => {
+            await initializeStickyConsumer(params);
+            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/dist/harness/sticky-consumer.d.ts

@@ -0,0 +1,28 @@
+export declare const STICKY_CAPABILITY = "sticky-disks-v1";
+export declare const STICKY_COMPATIBILITY = "docker29-ctr21-buildkit032-overlayfs-256g-v2";
+export declare const STICKY_RUNTIME = "/run/spectest-sticky";
+export interface StickyConsumerConfig {
+    path: string;
+    capacityBytes: number;
+    headroomBytes: number;
+    cacheTargetBytes: number;
+    buildkitTargetBytes: number;
+    compatibility: string;
+}
+declare function exec(program: string, args: string[], timeout?: number): Promise<string>;
+export declare function validateStickyConfig(config: StickyConsumerConfig): void;
+export declare function initializeStickyConsumer(config: StickyConsumerConfig): Promise<void>;
+/** 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 declare function collectStickyCache(config: StickyConsumerConfig, run?: typeof exec, usage?: () => Promise<{
+    freeBytes: number;
+    totalBytes: number;
+}>): Promise<void>;
+/** Only on an isolated maintenance clone; never on the live ready environment. */
+export declare function prepareStickyConsumer(artifact?: boolean): Promise<{
+    prepared: true;
+    freeBytes: number;
+}>;
+export {};

package/dist/harness/sticky-consumer.js

@@ -0,0 +1,178 @@
+/** 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";
+function exec(program, args, timeout = 60_000) {
+    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, args) {
+    const deadline = Date.now() + 30_000;
+    let last;
+    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) {
+    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) {
+    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, program, args) => {
+        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, run = exec, usage = async () => {
+    const fs = await statfs(config.path);
+    return { freeBytes: fs.bavail * fs.bsize, totalBytes: fs.blocks * fs.bsize };
+}) {
+    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) => 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 = 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) {
+    const config = 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/dist/harness/sticky-maintenance.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/harness/sticky-maintenance.js

@@ -0,0 +1,11 @@
+// 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/dist/index.d.ts

@@ -1,3 +1,5 @@
+import type { Android, AndroidApp } from "./android.js";
+export type { Android, AndroidApp, AndroidElement, AndroidRecordingOptions } from "./android.js";
 import { strict as nodeAssert } from "node:assert";
 export type { Carrier, Wrapped, WrappedObject, WrappedArray, WrappedHeaders, WrappedBuffer, WrappedBinaryView, WrappedBytes, WrappedBlob, WrappedFile, WrappedFormData, WrappedStream, WrappedReader, WrappedBYOBReader, WrappedReadResult, WrappedResponse, Provenanced, SpectestFetch, SpectestRequestInit, Unwrap, } from "./inspect.js";
 import type { Provenanced, SpectestFetch, Wrapped } from "./inspect.js";
@@ -1315,6 +1317,8 @@ export interface TestContext<P = undefined, S extends ServicesMap = ServicesMap,
      * 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/dist/recorder.d.ts

@@ -564,7 +564,7 @@ export interface EventReservation {
 }
 export declare function pauseRecording(): void;
 export declare function resumeRecording(): void;
-export declare function startRecording(): void;
+export declare function startRecording(startedAt?: number): void;
 export declare function stopRecording(): TestEvent[];
 export declare function isRecording(): boolean;
 /** Reserve an ordering slot at the start of an op so nested events it triggers

package/dist/recorder.js

@@ -11,9 +11,12 @@ import { clearPendingNullish } from "./inspect.js";
 import { scopeAllowsRecording } from "./harness/instrumentation-scope.js";
 const OUTPUT_SNIPPET_BYTES = 256 * 1024;
 class Recorder {
+    start;
     events = [];
     seq = 0;
-    start = Date.now();
+    constructor(start = Date.now()) {
+        this.start = start;
+    }
     /** Claim a seq + start offset now; pass the result to `push` at finish. */
     reserve() {
         return { seq: this.seq++, tOffsetMs: Date.now() - this.start };
@@ -120,8 +123,8 @@ export function resumeRecording() {
 function active() {
     return current !== null && paused === 0 && scopeAllowsRecording();
 }
-export function startRecording() {
-    current = new Recorder();
+export function startRecording(startedAt = Date.now()) {
+    current = new Recorder(startedAt);
     paused = 0;
 }
 export function stopRecording() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.89.1",
+  "version": "0.90.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,7 +49,8 @@
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
-    "access": "public"
+    "access": "public",
+    "tag": "latest"
   },
   "dependencies": {
     "@kubernetes/client-node": "^1.0.0",
@@ -61,5 +62,8 @@
     "@types/dns-packet": "^5.6.5",
     "@types/bun": "^1.3.0",
     "typescript": "^5.6.3"
-  }
+  },
+  "spectestCapabilities": [
+    "sticky-disks-v1"
+  ]
 }