@specific.dev/spectest 0.126.0 → 0.128.0

package/dist/android-step.d.ts

@@ -8,6 +8,13 @@ export interface AndroidTarget {
 export interface AndroidStepDetails {
     device: string;
     action: "tap" | "fill" | "text" | "visible" | "wait" | "swipe" | "back" | "source" | "screenshot" | "execute";
+    /** Normalized screen bounds observed by this operation. */
+    bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
     target?: AndroidTarget;
     point?: {
         x: number;

package/dist/android.d.ts

@@ -24,10 +24,24 @@ export declare class AppiumError extends Error {
     readonly code: string;
     constructor(code: string, message: string);
 }
+export declare const ANDROID_ASSERT: unique symbol;
+export type AndroidMatcher = "toBeVisible" | "toBeHidden" | "toHaveText" | "toContainText";
+export interface AndroidAssertionResult {
+    sourceSeq?: number;
+    actual?: unknown;
+    error?: unknown;
+}
 export interface AndroidElement {
-    tap(): Promise<void>;
-    fill(text: string): Promise<void>;
-    text(): Promise<Wrapped<string>>;
+    [ANDROID_ASSERT](matcher: AndroidMatcher, negated: boolean, expected: string | RegExp | undefined, timeoutMs?: number): Promise<AndroidAssertionResult>;
+    tap(options?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    fill(text: string, options?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    text(options?: {
+        timeoutMs?: number;
+    }): Promise<Wrapped<string>>;
     isDisplayed(): Promise<Wrapped<boolean>>;
     waitFor(options?: {
         state?: "visible" | "hidden";

package/dist/android.js

@@ -42,6 +42,10 @@ async function session(app) {
             capabilities: {
                 alwaysMatch: {
                     platformName: "Android",
+                    // Conditions are explicit waits. Do not stack a session-wide lookup
+                    // wait or UiSelector's own 10s wait underneath their deadline.
+                    timeouts: { implicit: 0 },
+                    "appium:settings[waitForSelectorTimeout]": 0,
                     "appium:automationName": "UiAutomator2",
                     "appium:udid": app.serial,
                     "appium:appPackage": app.package,
@@ -65,6 +69,7 @@ async function session(app) {
     }
     return pending;
 }
+export const ANDROID_ASSERT = Symbol.for("spectest.androidAssert");
 const parked = new Map();
 let epoch = 0;
 /** A case owns capture and handle lifetime; the Android/Appium processes outlive it. */
@@ -155,13 +160,13 @@ export function androidScope(caseId, testStartedAt, options = {}) {
                     list.push(marker);
                 taps.set(app.name, list);
             }
-            async function op(operation, fn) {
+            async function op(operation, fn, settled) {
                 assertActive();
                 const android = { device: app.name, ...operation };
                 const title = androidStepTitle(android);
                 const reservation = reserveEvent(), started = Date.now();
                 try {
-                    const result = await fn();
+                    const result = await fn(android);
                     const seq = recordStep({
                         kind: "android",
                         title,
@@ -169,10 +174,11 @@ export function androidScope(caseId, testStartedAt, options = {}) {
                         durationMs: Date.now() - started,
                         status: "passed",
                     }, reservation);
+                    settled?.(seq);
                     return wrap(result, seq);
                 }
                 catch (error) {
-                    recordStep({
+                    const seq = recordStep({
                         kind: "android",
                         title,
                         android,
@@ -180,9 +186,46 @@ export function androidScope(caseId, testStartedAt, options = {}) {
                         status: "failed",
                         error: String(error),
                     }, reservation);
+                    settled?.(seq);
                     throw error;
                 }
             }
+            async function bounds(path, details) {
+                delete details.bounds;
+                if (!captures.has(app.name))
+                    return;
+                try {
+                    if (!await command("GET", `${path}/displayed`))
+                        return;
+                    const screen = await command("GET", "/window/rect");
+                    const rect = await command("GET", `${path}/rect`);
+                    const box = { x: rect.x / screen.width, y: rect.y / screen.height, width: rect.width / screen.width, height: rect.height / screen.height };
+                    if (Object.values(box).every(Number.isFinite) && box.width > 0 && box.height > 0)
+                        details.bounds = box;
+                }
+                catch { /* Replay decoration must not change the operation's result. */ }
+            }
+            const transient = (error) => error instanceof AppiumError && ["no such element", "stale element reference"].includes(error.code);
+            async function until(probe, label, timeoutMs = 10000) {
+                if (!Number.isFinite(timeoutMs) || timeoutMs < 0)
+                    throw new Error("Invalid wait timeout");
+                const deadline = Date.now() + timeoutMs;
+                while (true) {
+                    assertActive();
+                    try {
+                        const value = await probe();
+                        if (value !== undefined)
+                            return value;
+                    }
+                    catch (error) {
+                        if (!transient(error))
+                            throw error;
+                    }
+                    if (Date.now() >= deadline)
+                        throw new Error(`Timed out waiting for ${label}`);
+                    await new Promise(resolve => setTimeout(resolve, Math.min(100, deadline - Date.now())));
+                }
+            }
             const element = (using, value, target = androidTarget(using, value)) => {
                 const label = androidTargetLabel(target);
                 const find = async () => {
@@ -195,49 +238,102 @@ export function androidScope(caseId, testStartedAt, options = {}) {
                         throw new Error("Appium returned no element id");
                     return `/element/${encodeURIComponent(id)}`;
                 };
-                const displayed = async () => {
+                const visiblePath = async () => {
                     try {
-                        return await command("GET", `${await find()}/displayed`);
+                        const path = await find();
+                        return await command("GET", `${path}/displayed`) ? path : undefined;
                     }
                     catch (error) {
-                        if (error instanceof AppiumError &&
-                            ["no such element", "stale element reference"].includes(error.code))
-                            return false;
+                        if (transient(error))
+                            return undefined;
                         throw error;
                     }
                 };
+                const ready = (timeoutMs) => until(async () => {
+                    const path = await visiblePath();
+                    return path && await command("GET", `${path}/enabled`) ? path : undefined;
+                }, `${label} to be visible and enabled`, timeoutMs);
                 return {
-                    async tap() {
+                    async tap(options = {}) {
                         await op({ action: "tap", target }, async () => {
-                            const path = await find();
+                            const path = await ready(options.timeoutMs);
                             const marker = await tapMarker(path);
+                            // Never retry an input dispatch: a transport failure may occur
+                            // after the app has received it.
                             await command("POST", `${path}/click`, {});
                             saveTap(marker);
                         });
                     },
-                    async fill(text) {
-                        await op({ action: "fill", target }, async () => {
-                            const path = await find();
+                    async fill(text, options = {}) {
+                        await op({ action: "fill", target }, async (details) => {
+                            const path = await ready(options.timeoutMs);
                             await command("POST", `${path}/clear`, {});
                             await command("POST", `${path}/value`, { text });
+                            await bounds(path, details);
                         });
                     },
-                    text: () => op({ action: "text", target }, async () => command("GET", `${await find()}/text`)),
-                    isDisplayed: () => op({ action: "visible", target }, displayed),
+                    text: (options = {}) => op({ action: "text", target }, async (details) => {
+                        return until(async () => {
+                            const path = await find();
+                            const value = await command("GET", `${path}/text`);
+                            await bounds(path, details);
+                            return value;
+                        }, label, options.timeoutMs);
+                    }),
+                    isDisplayed: () => op({ action: "visible", target }, async (details) => {
+                        const path = await visiblePath();
+                        if (path)
+                            await bounds(path, details);
+                        return !!path;
+                    }),
                     async waitFor(options = {}) {
-                        const timeout = options.timeoutMs ?? 10000;
-                        if (!Number.isFinite(timeout) || timeout < 0)
-                            throw new Error("Invalid wait timeout");
-                        await op({ action: "wait", target, state: options.state ?? "visible" }, async () => {
-                            const end = Date.now() + timeout;
-                            do {
-                                if ((await displayed()) === (options.state !== "hidden"))
-                                    return;
-                                await new Promise((resolve) => setTimeout(resolve, 100));
-                            } while (Date.now() < end);
-                            throw new Error(`Timed out waiting for ${label}`);
+                        await op({ action: "wait", target, state: options.state ?? "visible" }, async (details) => {
+                            await until(async () => {
+                                const path = await visiblePath();
+                                if (path)
+                                    await bounds(path, details);
+                                else
+                                    delete details.bounds;
+                                return (!!path === (options.state !== "hidden")) ? true : undefined;
+                            }, `${label} to be ${options.state ?? "visible"}`, options.timeoutMs);
                         });
                     },
+                    async [ANDROID_ASSERT](matcher, negated, expected, timeoutMs) {
+                        let sourceSeq, actual, error;
+                        const visibility = matcher === "toBeVisible" || matcher === "toBeHidden";
+                        try {
+                            await op({ action: visibility ? "wait" : "text", target,
+                                ...(visibility ? { state: ((matcher === "toBeVisible") !== negated ? "visible" : "hidden") } : {}) }, async (details) => {
+                                await until(async () => {
+                                    let path;
+                                    let matches;
+                                    if (visibility) {
+                                        path = await visiblePath();
+                                        actual = !!path;
+                                        matches = matcher === "toBeVisible" ? !!path : !path;
+                                    }
+                                    else {
+                                        path = await find();
+                                        const text = await command("GET", `${path}/text`);
+                                        actual = text;
+                                        const normalize = (value) => value.replace(/\s+/g, " ").trim();
+                                        matches = expected instanceof RegExp
+                                            ? new RegExp(expected.source, expected.flags).test(text)
+                                            : matcher === "toContainText" ? normalize(text).includes(normalize(expected)) : normalize(text) === normalize(expected);
+                                    }
+                                    if (path)
+                                        await bounds(path, details);
+                                    else
+                                        delete details.bounds;
+                                    return matches !== negated ? true : undefined;
+                                }, `${label} ${negated ? "not " : ""}${matcher}${expected === undefined ? "" : ` ${expected}`}`, timeoutMs);
+                            }, seq => { sourceSeq = seq; });
+                        }
+                        catch (cause) {
+                            error = cause;
+                        }
+                        return { sourceSeq, actual, error };
+                    },
                 };
             };
             return {

package/dist/components/android.d.ts

@@ -6,7 +6,7 @@ export interface AndroidOptions {
     package: string;
     /** Launch activity, for example .MainActivity. */
     activity: string;
-    /** Android image; default is the tested Android 14 arm64-only redroid image. */
+    /** Android image; default is the pinned Android 16 64-bit-only redroid image. */
     image?: string;
     /** Optional prebuilt image containing the same tools as ANDROID_TOOLS_DOCKERFILE. */
     toolsImage?: string;

package/dist/components/android.js

@@ -47,7 +47,7 @@ export function android(options) {
                 image: {
                     type: "registry",
                     reference: options.image ??
-                        "redroid/redroid:14.0.0_64only-latest@sha256:0a611199ba2e0b5d60af39b3327a517f6407231f4352114ed3bd3cbfe2be69aa",
+                        "redroid/redroid:16.0.0_64only-latest@sha256:7b1e389bd15f37af3bcd06138f5b2ffa7cfba4332bd5ef54c53e99c2f160a15b",
                 },
                 privileged: true,
                 // Android's netd ignores resolv.conf. Use Docker's per-container DNS,

package/dist/components/k3s-coverage.d.ts

@@ -0,0 +1,24 @@
+import { type CoverageAdapter } from "../coverage.js";
+import { type KubernetesImage } from "../harness/component-images.js";
+import type { Patch, Pod } from "./k3s-trust.js";
+interface ImageInfo {
+    aliases: string[];
+    root: string;
+    env: Record<string, string>;
+}
+export interface K3sCoverageDependencies {
+    image(reference: string): Promise<ImageInfo>;
+    files(namespace: string, name: string, data: Record<string, string>): Promise<void>;
+}
+/** One component-owned bridge; runtime adapters remain unaware of Kubernetes. */
+export declare function k3sCoverage(images: readonly KubernetesImage[]): {
+    enabled: boolean;
+    volume(cluster: string): {
+        source: string;
+        target: string;
+        reachExempt: boolean;
+    };
+    mutate(cluster: string, podInput: Pod, namespace: string, dryRun: boolean, ephemeral: boolean, uid: string, deps: K3sCoverageDependencies): Promise<Patch[]>;
+    adapter(): CoverageAdapter;
+};
+export {};

package/dist/components/k3s-coverage.js

@@ -0,0 +1,259 @@
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { applyCoverageAdapters, coverageAdapters } from "../coverage.js";
+import { coverageHostDir, COVERAGE_MAX_BYTES_PER_SERVICE } from "../harness/coverage.js";
+import { captureCoverageTarget } from "../harness/coverage-target.js";
+import { canonicalImageReference } from "../harness/component-images.js";
+import { WORKSPACE } from "../project-files.js";
+const MOUNT = "/spectest/pod-coverage";
+const ANNOTATION = "spectest.dev/coverage";
+const hash = (value) => createHash("sha256").update(value).digest("hex").slice(0, 16);
+const quote = (value) => "'" + value.replaceAll("'", "'\\''") + "'";
+/** One component-owned bridge; runtime adapters remain unaware of Kubernetes. */
+export function k3sCoverage(images) {
+    const declarations = images.flatMap(image => typeof image === "string" || image.coverage === undefined ? [] : [{
+            reference: canonicalImageReference(image.reference), coverage: image.coverage,
+        }]);
+    for (const image of declarations) {
+        const adapters = coverageAdapters(image.coverage);
+        if (adapters.some(adapter => adapter.load || adapter.collect))
+            throw new Error("k3s image coverage accepts container adapters; put browser coverage on the cluster service");
+        applyCoverageAdapters(image.reference, { image: { type: "registry", reference: image.reference }, coverage: image.coverage });
+    }
+    const metadata = new Map();
+    const service = (cluster, reference) => `${cluster}/image-${hash(reference)}`;
+    return {
+        enabled: declarations.length > 0,
+        volume(cluster) {
+            return { source: coverageHostDir(WORKSPACE, cluster), target: MOUNT, reachExempt: true };
+        },
+        async mutate(cluster, podInput, namespace, dryRun, ephemeral, uid, deps) {
+            if (!declarations.length || ephemeral)
+                return [];
+            const pod = podInput;
+            if (!pod.spec)
+                return [];
+            const existing = pod.metadata?.annotations?.[ANNOTATION];
+            if (existing) {
+                if (JSON.parse(existing).admission === uid)
+                    return [];
+                throw new Error("remove inherited spectest.dev/coverage annotations before creating another Pod");
+            }
+            const patch = [];
+            const volumes = [...(pod.spec.volumes ?? [])];
+            const instances = [];
+            const namedVolume = (stem, volume) => {
+                let name = stem;
+                for (let i = 1; volumes.some(v => v.name === name); i++)
+                    name = `${stem}-${i}`;
+                volumes.push({ name, ...volume });
+                return name;
+            };
+            for (const group of ["initContainers", "containers"]) {
+                for (const [index, container] of (pod.spec[group] ?? []).entries()) {
+                    const requested = canonicalImageReference(container.image);
+                    let declaration = declarations.find(image => image.reference === requested);
+                    // Tangent deploys the prepared image by digest. Resolve aliases from
+                    // CRI's actual image record, never by stripping a repository tag.
+                    if (!declaration && requested.includes("@")) {
+                        for (const candidate of declarations) {
+                            let info = metadata.get(candidate.reference);
+                            if (!info)
+                                metadata.set(candidate.reference, info = await deps.image(candidate.reference));
+                            if (info.aliases.includes(requested)) {
+                                declaration = candidate;
+                                break;
+                            }
+                        }
+                    }
+                    if (!declaration)
+                        continue;
+                    let info = metadata.get(declaration.reference);
+                    if (!info)
+                        metadata.set(declaration.reference, info = await deps.image(declaration.reference));
+                    const id = hash(`${uid}/${group}/${container.name}`);
+                    const name = service(cluster, declaration.reference);
+                    const env = { ...info.env };
+                    for (const entry of container.env ?? [])
+                        if (entry.value !== undefined)
+                            env[entry.name] = entry.value;
+                    const configured = applyCoverageAdapters(name, { image: { type: "registry", reference: container.image }, env, coverage: declaration.coverage });
+                    if (Object.keys(configured).some(key => !["image", "env", "coverage", "files"].includes(key))) {
+                        throw new Error("Kubernetes coverage adapters may inject env and files only; configure the workload's command and mounts in its manifest");
+                    }
+                    const changed = Object.entries(configured.env ?? {}).filter(([key, value]) => env[key] !== value);
+                    for (const [key] of changed)
+                        if (container.env?.some(e => e.name === key && e.valueFrom))
+                            throw new Error(`cannot inject coverage into dynamic ${key}`);
+                    const mounts = [...(container.volumeMounts ?? [])];
+                    const addMount = (mountPath, mount) => {
+                        if (mounts.some(m => mountPath === m.mountPath || mountPath.startsWith(m.mountPath.replace(/\/$/, "") + "/")))
+                            throw new Error(`coverage mount conflicts with ${mountPath}`);
+                        mounts.push({ mountPath, ...mount });
+                    };
+                    const volume = namedVolume(`spectest-cov-${id}`, { hostPath: { path: `${MOUNT}/.pods/${id}`, type: "Directory" } });
+                    addMount("/spectest/coverage", { name: volume });
+                    const files = configured.files ?? [];
+                    if (files.some(file => file.user !== undefined || file.group !== undefined || (file.mode !== undefined && !["444", "0444", "644", "0644"].includes(file.mode)))) {
+                        throw new Error("Kubernetes coverage hook files must be world-readable and need no custom ownership");
+                    }
+                    if (files.length) {
+                        const data = Object.fromEntries(files.map((file, index) => [`file${index}`, file.content]));
+                        const configMap = `spectest-coverage-${hash(JSON.stringify(data))}`;
+                        if (!dryRun)
+                            await deps.files(namespace, configMap, data);
+                        const fileVolume = namedVolume(`spectest-hooks-${id}`, { configMap: { name: configMap, defaultMode: 0o444 } });
+                        files.forEach((file, index) => addMount(file.path, { name: fileVolume, subPath: `file${index}`, readOnly: true }));
+                    }
+                    const instance = { id, image: declaration.reference, namespace, container: container.name, root: container.workingDir || info.root || "/" };
+                    if (!dryRun) {
+                        const dir = path.join(coverageHostDir(WORKSPACE, cluster), ".pods", id);
+                        await fs.mkdir(dir, { recursive: true, mode: 0o777 });
+                        await fs.chmod(dir, 0o777);
+                        await fs.writeFile(path.join(dir, ".instance.json"), JSON.stringify(instance));
+                    }
+                    instances.push(instance);
+                    patch.push({ op: "add", path: `/spec/${group}/${index}/env`, value: [
+                            ...(container.env ?? []).filter(e => !changed.some(([key]) => key === e.name)),
+                            ...changed.map(([name, value]) => ({ name, value })),
+                        ] }, { op: "add", path: `/spec/${group}/${index}/volumeMounts`, value: mounts });
+                }
+            }
+            if (!instances.length)
+                return [];
+            patch.push({ op: "add", path: "/spec/volumes", value: volumes });
+            patch.push({ op: "add", path: "/metadata/annotations", value: { ...pod.metadata?.annotations,
+                    [ANNOTATION]: JSON.stringify({ admission: uid, instances: instances.map(i => i.id) }),
+                } });
+            return patch;
+        },
+        adapter() {
+            return {
+                name: "k3s-containers",
+                // Include nested policy AND injected hooks in the warm identity. An
+                // adapter's functions would otherwise disappear from JSON.stringify.
+                toJSON() {
+                    return { adapter: "k3s-containers", images: declarations.map(image => ({
+                            reference: image.reference,
+                            config: applyCoverageAdapters(image.reference, { image: { type: "registry", reference: image.reference }, coverage: image.coverage }),
+                        })) };
+                },
+                async collect(ctx, baseline) {
+                    const root = path.join(ctx.reportDir, ".pods");
+                    let entries;
+                    try {
+                        entries = await fs.readdir(root);
+                    }
+                    catch (error) {
+                        if (error.code !== "ENOENT")
+                            throw error;
+                        entries = [];
+                    }
+                    // Native adapters flush through the shared Unix sockets, including
+                    // after Pod deletion. Only inventory or command adapters need the API.
+                    let pods;
+                    const findPod = async (id) => {
+                        pods ??= ctx.exec("kubectl get pods -A -o json --request-timeout=10s")
+                            .then(result => JSON.parse(result.stdout).items);
+                        return (await pods).find(p => {
+                            const ids = p.metadata?.annotations?.[ANNOTATION];
+                            return ids && JSON.parse(ids).instances.includes(id);
+                        });
+                    };
+                    const captures = new Map();
+                    const inventories = new Map();
+                    for (const declaration of declarations)
+                        captures.set(declaration.reference, { service: service(ctx.service, declaration.reference), reports: [] });
+                    const collectInstance = async (id) => {
+                        ctx.signal.throwIfAborted();
+                        if (!/^[a-f0-9]{16}$/.test(id))
+                            throw new Error("invalid coverage instance directory");
+                        const dir = path.join(root, id);
+                        const instance = JSON.parse(await fs.readFile(path.join(dir, ".instance.json"), "utf8"));
+                        const declaration = declarations.find(d => d.reference === instance.image);
+                        if (!declaration)
+                            throw new Error(`coverage image no longer declared: ${instance.image}`);
+                        const adapters = coverageAdapters(declaration.coverage);
+                        const livePod = async () => {
+                            const pod = await findPod(id);
+                            const statuses = [...(pod?.status?.containerStatuses ?? []), ...(pod?.status?.initContainerStatuses ?? [])];
+                            return statuses.some(status => status.name === instance.container && status.state?.running) ? pod : undefined;
+                        };
+                        for (const adapter of adapters) {
+                            if (adapter.name === "node") {
+                                try {
+                                    await fs.access(path.join(dir, `.attached-${adapter.name}`));
+                                }
+                                catch {
+                                    throw new Error(`coverage hook never attached to ${instance.namespace}/${instance.container} (${adapter.name})`);
+                                }
+                            }
+                        }
+                        const captured = await captureCoverageTarget({
+                            coverage: declaration.coverage, root: instance.root, baseline,
+                            inventoryAvailable: baseline && adapters.some(a => a.inventory) ? !!await livePod() : false,
+                            counterKey: `${service(ctx.service, instance.image)}/${id}`,
+                            context: { ...ctx, service: service(ctx.service, instance.image), reportDir: dir,
+                                exec: async (command) => {
+                                    const pod = await livePod();
+                                    if (!pod?.metadata?.name)
+                                        throw new Error(`coverage command requires live container ${instance.container}`);
+                                    return ctx.exec(`kubectl exec -n ${quote(instance.namespace)} ${quote(pod.metadata.name)} -c ${quote(instance.container)} -- sh -c ${quote(command)}`);
+                                },
+                            },
+                        });
+                        return { id, instance, captured };
+                    };
+                    // Bound simultaneous LLVM exports and API execs. Drain all workers
+                    // even on error so no collector can race the following VM snapshot.
+                    const pending = entries.sort();
+                    const results = new Map();
+                    let cursor = 0;
+                    const workers = await Promise.allSettled(Array.from({ length: Math.min(8, pending.length) }, async () => {
+                        while (cursor < pending.length) {
+                            const id = pending[cursor++];
+                            results.set(id, await collectInstance(id));
+                        }
+                    }));
+                    const failure = workers.find(worker => worker.status === "rejected");
+                    if (failure?.status === "rejected")
+                        throw failure.reason;
+                    for (const id of pending) {
+                        const { instance, captured } = results.get(id);
+                        const aggregate = captures.get(instance.image);
+                        if (captured.error)
+                            aggregate.error = [aggregate.error, `${instance.namespace}/${instance.container}: ${captured.error}`].filter(Boolean).join("; ");
+                        if (aggregate.root && aggregate.root !== instance.root) {
+                            aggregate.error = "coverage containers from one image have different working directories; use a common workingDir for this image's covered containers";
+                        }
+                        aggregate.root = instance.root;
+                        for (const report of captured.reports) {
+                            if (report.name === "inventory.units") {
+                                let units = inventories.get(instance.image);
+                                if (!units)
+                                    inventories.set(instance.image, units = new Set());
+                                for (const unit of report.content.split("\n"))
+                                    if (unit)
+                                        units.add(unit);
+                            }
+                            else
+                                aggregate.reports.push({ ...report, name: `${id}/${report.name}` });
+                        }
+                    }
+                    for (const [image, units] of inventories)
+                        captures.get(image).reports.push({ name: "inventory.units", content: [...units].sort().join("\n") });
+                    for (const capture of captures.values()) {
+                        if (!capture.reports.length && !capture.error)
+                            capture.reports.push({ name: "empty.lcov", content: "TN:\n" });
+                        if (capture.reports.reduce((bytes, report) => bytes + Buffer.byteLength(report.content), 0) > COVERAGE_MAX_BYTES_PER_SERVICE) {
+                            capture.reports = [];
+                            capture.error = "Kubernetes image coverage exceeds the per-service report size limit";
+                        }
+                    }
+                    return [...captures.values()];
+                },
+            };
+        },
+    };
+}

package/dist/components/k3s-trust.d.ts

@@ -12,7 +12,7 @@ interface Container {
         readOnly?: boolean;
     }[];
 }
-interface Pod {
+export interface Pod {
     metadata?: {
         annotations?: Record<string, string>;
     };
@@ -32,7 +32,7 @@ interface Pod {
         ephemeralContainers?: Container[];
     };
 }
-interface Patch {
+export interface Patch {
     op: "add";
     path: string;
     value: unknown;
@@ -43,6 +43,8 @@ export interface TrustDependencies {
     /** Ensure this immutable ConfigMap exists in the requesting namespace. */
     ensureBundle(namespace: string, name: string, bundle: string): Promise<void>;
     apply(configuration: unknown): Promise<void>;
+    /** Component-owned pod instrumentation runs after trust patching. */
+    mutatePod?(pod: Pod, namespace: string, dryRun: boolean, ephemeral: boolean, uid: string): Promise<Patch[]>;
 }
 export declare function installPodTrust(options: {
     name: string;

package/dist/components/k3s-trust.js

@@ -75,6 +75,19 @@ export async function installPodTrust(options, deps) {
                 return;
             }
             const patch = podTrustPatch(request.object, configMap, request.subResource === "ephemeralcontainers");
+            if (deps.mutatePod) {
+                const pod = structuredClone(request.object);
+                for (const operation of patch) {
+                    const keys = operation.path.slice(1).split("/");
+                    const key = keys.pop();
+                    const parent = keys.reduce((value, key) => value[key], pod);
+                    if (key === "-")
+                        parent.push(operation.value);
+                    else
+                        parent[key] = operation.value;
+                }
+                patch.push(...await deps.mutatePod(pod, request.namespace, !!request.dryRun, request.subResource === "ephemeralcontainers", request.uid));
+            }
             // Dry runs return the same patch but perform no API writes.
             if (patch.length && !request.dryRun)
                 await deps.ensureBundle(request.namespace, configMap, options.bundle);