taphound 0.2.0-dev.1 → 0.2.0-dev.11

package/dist/application/checkpoint/checkpoint-evaluator.js

@@ -0,0 +1,415 @@
+import { createHash } from "node:crypto";
+import { matchesLogcatEvent } from "../collector/logcat-event.js";
+import { resolveLocatorIdentity } from "../locator/locator-resolver.js";
+import { ScreenDetector } from "../recognition/screen-detector.js";
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function unresolvedConditions(expect, message) {
+    return [
+        ...(expect.activity === undefined ? [] : [{
+                kind: "activity",
+                status: "unresolved",
+                expected: expect.activity,
+                message
+            }]),
+        ...(expect.screen === undefined ? [] : [{
+                kind: "screen",
+                status: "unresolved",
+                expected: expect.screen,
+                message
+            }]),
+        ...expect.visibleElements.map((locator) => ({
+            kind: "visibleElement",
+            status: "unresolved",
+            locator,
+            message
+        })),
+        ...expect.absentElements.map((locator) => ({
+            kind: "absentElement",
+            status: "unresolved",
+            locator,
+            message
+        }))
+    ];
+}
+function checkpointResult(checkpoint, conditions, matchedScreen) {
+    const status = conditions.some((condition) => condition.status === "failed")
+        ? "failed"
+        : conditions.some((condition) => condition.status === "unresolved")
+            ? "unresolved"
+            : "passed";
+    return {
+        report: {
+            id: checkpoint.id,
+            ...(checkpoint.stepIndex === undefined ? {} : { stepIndex: checkpoint.stepIndex }),
+            status,
+            conditions
+        },
+        ...(matchedScreen === undefined ? {} : { matchedScreen })
+    };
+}
+export class CheckpointEvaluator {
+    detector = new ScreenDetector();
+    observeUi = async (input, expect) => {
+        let snapshot;
+        try {
+            snapshot = await input.provider.capture({
+                reason: "evidence",
+                freshness: "forceFresh",
+                timeoutMs: input.timeoutMs,
+                ...(input.signal === undefined ? {} : { signal: input.signal })
+            });
+        }
+        catch (error) {
+            return {
+                conditions: unresolvedConditions(expect, `Checkpoint layout unavailable: ${errorMessage(error)}`)
+            };
+        }
+        let foreground;
+        try {
+            foreground = await input.adb.foregroundComponent({
+                packageName: input.packageName,
+                deviceSerial: input.deviceSerial,
+                timeoutMs: input.timeoutMs,
+                ...(input.signal === undefined ? {} : { signal: input.signal })
+            });
+        }
+        catch (error) {
+            return {
+                conditions: unresolvedConditions(expect, `Checkpoint foreground unavailable: ${errorMessage(error)}`)
+            };
+        }
+        if (foreground.packageName !== input.packageName) {
+            return {
+                conditions: unresolvedConditions(expect, `Checkpoint foreground package ${foreground.packageName} is not ${input.packageName}`)
+            };
+        }
+        const activity = foreground.activity;
+        const conditions = [];
+        if (expect.activity !== undefined) {
+            const expected = expect.activity;
+            conditions.push({
+                kind: "activity",
+                status: activity === expected ? "passed" : "failed",
+                expected,
+                actual: activity
+            });
+        }
+        let matchedScreen;
+        if (expect.screen !== undefined) {
+            const expected = expect.screen;
+            if (input.knowledge === undefined
+                || input.knowledge.index.packageName !== input.packageName) {
+                conditions.push({
+                    kind: "screen",
+                    status: "unresolved",
+                    expected,
+                    message: input.knowledgeError ?? (input.knowledge === undefined
+                        ? "Project Knowledge is unavailable"
+                        : "Project Knowledge belongs to another package")
+                });
+            }
+            else if (!input.knowledge.screens.some((screen) => screen.id === expected)) {
+                conditions.push({
+                    kind: "screen",
+                    status: "unresolved",
+                    expected,
+                    message: `Screen ${expected} is not defined in Project Knowledge`
+                });
+            }
+            else {
+                const runtimeSnapshot = {
+                    activity,
+                    layout: [...snapshot.roots]
+                };
+                try {
+                    const detection = this.detector.detect({
+                        snapshot: runtimeSnapshot,
+                        anchors: input.knowledge.anchors,
+                        screens: input.knowledge.screens
+                    });
+                    if (detection.status === "matched") {
+                        matchedScreen = detection.screenId;
+                        conditions.push({
+                            kind: "screen",
+                            status: matchedScreen === expected ? "passed" : "failed",
+                            expected,
+                            actual: matchedScreen
+                        });
+                    }
+                    else {
+                        conditions.push({
+                            kind: "screen",
+                            status: "unresolved",
+                            expected,
+                            message: detection.status === "ambiguous"
+                                ? `Screen detection is ambiguous: ${detection.screenIds.join(", ")}`
+                                : "Screen detection could not identify a screen"
+                        });
+                    }
+                }
+                catch (error) {
+                    conditions.push({
+                        kind: "screen",
+                        status: "unresolved",
+                        expected,
+                        message: `Screen detection failed: ${errorMessage(error)}`
+                    });
+                }
+            }
+        }
+        for (const [kind, locators] of [
+            ["visibleElement", expect.visibleElements],
+            ["absentElement", expect.absentElements]
+        ]) {
+            for (const locator of locators) {
+                const resolution = resolveLocatorIdentity(snapshot.roots, locator);
+                if (resolution.status === "found") {
+                    conditions.push({
+                        kind,
+                        locator,
+                        status: kind === "visibleElement" ? "passed" : "failed"
+                    });
+                }
+                else if (resolution.code === "LOCATOR_AMBIGUOUS"
+                    || resolution.evidenceMismatch === true
+                    || (resolution.code !== "LOCATOR_NOT_FOUND")) {
+                    conditions.push({
+                        kind,
+                        locator,
+                        status: "unresolved",
+                        message: resolution.message
+                    });
+                }
+                else {
+                    conditions.push({
+                        kind,
+                        locator,
+                        status: kind === "absentElement" ? "passed" : "failed",
+                        ...(kind === "visibleElement" ? { message: resolution.message } : {})
+                    });
+                }
+            }
+        }
+        return { conditions, matchedScreen, snapshot };
+    };
+    evaluate = async (input) => {
+        const { checkpoint, clock, logcat } = input;
+        const allOf = checkpoint.expect.allOf;
+        const startedAtMs = clock?.now() ?? 0;
+        const timeoutMs = checkpoint.expect.timeoutMs;
+        const deadline = startedAtMs + timeoutMs;
+        const uiConditions = allOf.filter((condition) => condition.kind !== "logcatEvent");
+        const activityCondition = uiConditions.find((condition) => condition.kind === "activity");
+        const screenCondition = uiConditions.find((condition) => condition.kind === "screen");
+        const uiExpect = {
+            ...(activityCondition?.kind === "activity" ? { activity: activityCondition.expected } : {}),
+            ...(screenCondition?.kind === "screen" ? { screen: screenCondition.expected } : {}),
+            visibleElements: uiConditions.flatMap((condition) => (condition.kind === "visibleElement" ? [condition.locator] : [])),
+            absentElements: uiConditions.flatMap((condition) => (condition.kind === "absentElement" ? [condition.locator] : []))
+        };
+        const observed = new Map();
+        let matchedScreen;
+        const identity = (condition) => JSON.stringify([
+            condition.kind,
+            condition.kind === "activity" || condition.kind === "screen"
+                ? condition.expected
+                : condition.kind === "logcatEvent" ? condition.expect : condition.locator
+        ]);
+        const buildReport = () => {
+            const conditions = allOf.map((condition, index) => (observed.get(index) ?? (condition.kind === "logcatEvent"
+                ? {
+                    kind: "logcatEvent",
+                    expect: condition.expect,
+                    status: "failed",
+                    matchedCount: 0,
+                    startedAtMs,
+                    message: "Logcat event did not appear before the shared timeout"
+                }
+                : {
+                    ...condition,
+                    status: "failed",
+                    startedAtMs,
+                    message: "Condition did not match before the shared timeout"
+                })));
+            return checkpointResult(checkpoint, conditions, matchedScreen);
+        };
+        const unresolved = (message) => checkpointResult(checkpoint, allOf.map((condition) => condition.kind === "logcatEvent"
+            ? {
+                kind: "logcatEvent", expect: condition.expect,
+                status: "unresolved", matchedCount: 0, startedAtMs, message
+            }
+            : { ...condition, status: "unresolved", startedAtMs, message }));
+        if (clock === undefined || timeoutMs <= 0) {
+            const conditions = allOf.map((condition) => (condition.kind === "logcatEvent"
+                ? {
+                    kind: "logcatEvent", expect: condition.expect,
+                    status: "unresolved", matchedCount: 0, startedAtMs,
+                    message: "Checkpoint event clock is unavailable"
+                }
+                : { ...condition, status: "unresolved", startedAtMs,
+                    message: "Checkpoint observation clock is unavailable" }));
+            return checkpointResult(checkpoint, conditions);
+        }
+        // Even a Logcat-only Checkpoint requires one fresh layout and a valid
+        // foreground package before it can assert application evidence.
+        if (uiConditions.length === 0) {
+            try {
+                await input.provider.capture({
+                    reason: "evidence",
+                    freshness: "forceFresh",
+                    timeoutMs: Math.min(input.timeoutMs, timeoutMs),
+                    ...(input.signal === undefined ? {} : { signal: input.signal })
+                });
+                const foreground = await input.adb.foregroundComponent({
+                    packageName: input.packageName,
+                    deviceSerial: input.deviceSerial,
+                    timeoutMs: Math.max(1, Math.min(input.timeoutMs, deadline - clock.now())),
+                    ...(input.signal === undefined ? {} : { signal: input.signal })
+                });
+                if (foreground.packageName !== input.packageName) {
+                    return unresolved(`Checkpoint target app is not foreground: ${foreground.packageName}`);
+                }
+            }
+            catch (error) {
+                return unresolved(`Checkpoint UI or foreground unavailable: ${errorMessage(error)}`);
+            }
+        }
+        for (;;) {
+            if (input.signal?.aborted === true) {
+                return unresolved("Checkpoint was cancelled");
+            }
+            const now = clock.now();
+            const remaining = Math.max(1, deadline - now);
+            if (uiConditions.length === 0) {
+                try {
+                    const foreground = await input.adb.foregroundComponent({
+                        packageName: input.packageName,
+                        deviceSerial: input.deviceSerial,
+                        timeoutMs: Math.min(input.timeoutMs, remaining),
+                        ...(input.signal === undefined ? {} : { signal: input.signal })
+                    });
+                    if (foreground.packageName !== input.packageName) {
+                        return unresolved(`Checkpoint target app is not foreground: ${foreground.packageName}`);
+                    }
+                }
+                catch (error) {
+                    return unresolved(`Checkpoint foreground unavailable: ${errorMessage(error)}`);
+                }
+            }
+            if (uiConditions.some((condition) => observed.get(allOf.indexOf(condition))?.status !== "passed")) {
+                const ui = await this.observeUi({
+                    ...input,
+                    timeoutMs: Math.min(input.timeoutMs, remaining)
+                }, uiExpect);
+                const uiObservedAtMs = clock.now();
+                if (ui.matchedScreen !== undefined) {
+                    matchedScreen = ui.matchedScreen;
+                }
+                for (const [index, condition] of allOf.entries()) {
+                    if (condition.kind === "logcatEvent"
+                        || observed.get(index)?.status === "passed") {
+                        continue;
+                    }
+                    const matching = ui.conditions.find((entry) => (identity(entry) === identity({
+                        ...condition,
+                        status: "passed"
+                    })));
+                    if (matching === undefined) {
+                        return unresolved("Checkpoint UI observation did not cover every condition");
+                    }
+                    if (matching.status === "unresolved") {
+                        return unresolved(matching.message ?? "Checkpoint UI evidence is unresolved");
+                    }
+                    if (uiObservedAtMs > deadline && matching.status === "passed") {
+                        observed.set(index, {
+                            ...matching,
+                            status: "failed",
+                            startedAtMs,
+                            message: "UI condition matched after the shared timeout"
+                        });
+                        continue;
+                    }
+                    let evidenceRef;
+                    if (input.writeSnapshot !== undefined && ui.snapshot !== undefined
+                        && (matching.status === "passed" || clock.now() >= deadline)) {
+                        evidenceRef = `checkpoints/${checkpoint.id}-${String(index)}-ui.json`;
+                        try {
+                            await input.writeSnapshot(evidenceRef, ui.snapshot);
+                        }
+                        catch (error) {
+                            return unresolved(`Checkpoint UI artifact unavailable: ${errorMessage(error)}`);
+                        }
+                    }
+                    observed.set(index, {
+                        ...matching,
+                        startedAtMs,
+                        ...(matching.status === "passed" ? { matchedAtMs: uiObservedAtMs } : {}),
+                        ...(evidenceRef === undefined ? {} : { evidenceRef })
+                    });
+                }
+            }
+            for (const [index, condition] of allOf.entries()) {
+                if (condition.kind !== "logcatEvent") {
+                    continue;
+                }
+                const window = condition.expect.window;
+                const windowStart = window.from === "stepStart"
+                    ? input.stepStartedAt
+                    : window.from === "runStart" ? input.runStartedAt
+                        : input.markers?.get(window.markerId);
+                if (windowStart === undefined || logcat === undefined
+                    || !logcat.completeSince(windowStart)) {
+                    observed.set(index, {
+                        kind: "logcatEvent", expect: condition.expect, status: "unresolved",
+                        matchedCount: 0, startedAtMs,
+                        message: "Checkpoint Logcat window is unavailable or incomplete"
+                    });
+                    continue;
+                }
+                const matches = logcat.linesBetween(windowStart, Math.min(clock.now(), deadline))
+                    .filter((line) => matchesLogcatEvent(line, {
+                    ...condition.expect,
+                    timeoutMs
+                }));
+                const first = matches[0];
+                observed.set(index, {
+                    kind: "logcatEvent",
+                    expect: condition.expect,
+                    status: matches.length > 1 ? "failed"
+                        : matches.length === 1 ? "passed" : "failed",
+                    matchedCount: matches.length,
+                    startedAtMs: windowStart,
+                    ...(first === undefined || matches.length !== 1 ? {} : {
+                        matchedLineSha256: createHash("sha256")
+                            .update(first.raw).digest("hex"),
+                        matchedAtMs: first.receivedAt
+                    }),
+                    ...(input.logcatEvidenceRef === undefined ? {} : {
+                        evidenceRef: input.logcatEvidenceRef
+                    }),
+                    ...(matches.length > 1 ? { message: "Logcat event is not unique" } : {})
+                });
+            }
+            if ([...observed.values()].some((condition) => (condition.status === "unresolved"
+                || (condition.kind === "logcatEvent" && condition.matchedCount > 1)))) {
+                return buildReport();
+            }
+            const allPassed = observed.size === allOf.length
+                && [...observed.values()].every((condition) => condition.status === "passed");
+            if (allPassed && !allOf.some((condition) => condition.kind === "logcatEvent")) {
+                return buildReport();
+            }
+            if (clock.now() >= deadline) {
+                return buildReport();
+            }
+            try {
+                await clock.sleep(Math.min(100, deadline - clock.now()), input.signal);
+            }
+            catch (error) {
+                return unresolved(`Checkpoint polling was interrupted: ${errorMessage(error)}`);
+            }
+        }
+    };
+}

package/dist/application/checkpoint/regression-comparator.d.ts

@@ -0,0 +1,18 @@
+import type { Baseline, RegressionCompareResult } from "../../domain/checkpoint.js";
+import type { TapHoundReport } from "../../domain/report.js";
+export interface RegressionCompareInput {
+    baseline: Baseline;
+    current: Pick<TapHoundReport, "steps" | "screens" | "checkpoints" | "logcatEvidence">;
+    journeySha256: string;
+    comparedAt: string;
+}
+/**
+ * Deterministic Regression Comparator (architecture doc §16.1): is current
+ * behavior still equivalent to the known-good Baseline?
+ *
+ * `equivalent: true` only when every baseline activity fact and element fact
+ * is reproduced. A drift yields one `RegressionDiff` entry per fact with
+ * `expected` (baseline) vs `actual` (current). This comparator is pure and
+ * never calls a model; ambiguity is the job of the escalation policy.
+ */
+export declare const compareRegression: (input: RegressionCompareInput) => RegressionCompareResult;

package/dist/application/checkpoint/regression-comparator.js

@@ -0,0 +1,192 @@
+import { BaselineSchema, RegressionCompareResultSchema } from "../../domain/checkpoint.js";
+import { BaselineError } from "./baseline-error.js";
+function currentActivities(steps) {
+    const map = new Map();
+    for (const step of steps) {
+        map.set(step.index, {
+            before: step.activity?.before.actual,
+            after: step.activity?.after.actual
+        });
+    }
+    return map;
+}
+function elementIdentity(fact) {
+    return fact.anchorId === undefined
+        ? JSON.stringify(["locator", fact.locator])
+        : JSON.stringify(["anchor", fact.anchorId]);
+}
+function conditionIdentity(fact) {
+    return JSON.stringify([
+        fact.kind,
+        "locator" in fact ? fact.locator
+            : "expect" in fact ? fact.expect : fact.expected
+    ]);
+}
+function reportConditionIdentity(condition) {
+    return JSON.stringify([
+        condition.kind,
+        "locator" in condition ? condition.locator
+            : "expect" in condition ? condition.expect : condition.expected
+    ]);
+}
+/**
+ * Deterministic Regression Comparator (architecture doc §16.1): is current
+ * behavior still equivalent to the known-good Baseline?
+ *
+ * `equivalent: true` only when every baseline activity fact and element fact
+ * is reproduced. A drift yields one `RegressionDiff` entry per fact with
+ * `expected` (baseline) vs `actual` (current). This comparator is pure and
+ * never calls a model; ambiguity is the job of the escalation policy.
+ */
+export const compareRegression = (input) => {
+    BaselineSchema.parse(input.baseline);
+    if (input.baseline.screens.some((fact) => fact.status !== "matched")) {
+        throw new BaselineError("BASELINE_INCOMPARABLE", "An unresolved Screen fact cannot establish equivalence");
+    }
+    const regressions = [];
+    const currentActs = currentActivities(input.current.steps);
+    for (const fact of input.baseline.activities) {
+        const actual = currentActs.get(fact.stepIndex);
+        if (actual === undefined) {
+            regressions.push({
+                kind: "activity",
+                stepIndex: fact.stepIndex,
+                expected: `before ${fact.before}`,
+                actual: "missing"
+            });
+            continue;
+        }
+        if (actual.before !== fact.before) {
+            regressions.push({
+                kind: "activity",
+                stepIndex: fact.stepIndex,
+                expected: `before ${fact.before}`,
+                actual: `before ${actual.before ?? "missing"}`
+            });
+        }
+        if (actual.after !== fact.after) {
+            regressions.push({
+                kind: "activity",
+                stepIndex: fact.stepIndex,
+                expected: `after ${fact.after}`,
+                actual: `after ${actual.after ?? "missing"}`
+            });
+        }
+    }
+    for (const fact of input.baseline.elements) {
+        const stepIndex = fact.stepIndex;
+        const current = input.current.steps.find((step) => step.index === stepIndex)?.locator;
+        if (current?.status === "found" && (current.anchorId === undefined
+            && current.requested === undefined)) {
+            throw new BaselineError("BASELINE_INCOMPARABLE", `Current locator at step ${String(stepIndex)} has no stable identity`);
+        }
+        if (current?.status !== "found"
+            || elementIdentity({
+                anchorId: current.anchorId,
+                locator: current.requested
+            }) !== elementIdentity(fact)) {
+            regressions.push({
+                kind: "element",
+                ...(fact.locator === undefined ? {} : { locator: fact.locator }),
+                stepIndex,
+                expected: `${fact.kind} element`,
+                actual: current?.status === "found"
+                    ? "different element"
+                    : "missing"
+            });
+            continue;
+        }
+        if (fact.matchedBy !== undefined && current.matchedBy !== fact.matchedBy) {
+            regressions.push({
+                kind: "element",
+                ...(fact.locator === undefined ? {} : { locator: fact.locator }),
+                stepIndex,
+                expected: `matched by ${fact.matchedBy}`,
+                actual: `matched by ${current.matchedBy ?? "none"}`
+            });
+        }
+        if (fact.fallbackUsed !== undefined
+            && fact.fallbackUsed !== current.fallbackUsed) {
+            regressions.push({
+                kind: "element",
+                ...(fact.locator === undefined ? {} : { locator: fact.locator }),
+                stepIndex,
+                expected: `annotated fallback ${String(fact.fallbackUsed)}`,
+                actual: `annotated fallback ${String(current.fallbackUsed)}`
+            });
+        }
+    }
+    const currentScreens = new Map((input.current.screens ?? []).map((screen) => [
+        screen.screen, screen.status
+    ]));
+    for (const fact of input.baseline.screens) {
+        const currentStatus = currentScreens.get(fact.screen);
+        if (currentStatus !== fact.status) {
+            regressions.push({
+                kind: "screen",
+                screen: fact.screen,
+                expected: fact.status,
+                actual: currentStatus ?? "missing"
+            });
+        }
+    }
+    const checkpointFacts = input.baseline.checkpoints ?? [];
+    const checkpointIds = new Set(checkpointFacts.map((fact) => fact.checkpointId));
+    for (const id of checkpointIds) {
+        const baselineConditions = checkpointFacts.filter((fact) => fact.checkpointId === id);
+        const matches = (input.current.checkpoints ?? []).filter((entry) => entry.id === id);
+        const checkpoint = matches[0];
+        if (matches.length !== 1 || checkpoint === undefined) {
+            throw new BaselineError("BASELINE_INCOMPARABLE", `Checkpoint ${id} has no unique current evaluation`);
+        }
+        if (checkpoint.stepIndex !== baselineConditions[0]?.stepIndex
+            || checkpoint.conditions.length !== baselineConditions.length
+            || checkpoint.conditions.some((condition) => !baselineConditions.some((fact) => conditionIdentity(fact) === reportConditionIdentity(condition)))) {
+            throw new BaselineError("BASELINE_INCOMPARABLE", `Checkpoint ${id} does not have the same condition identities`);
+        }
+        for (const fact of baselineConditions) {
+            const condition = checkpoint.conditions.find((entry) => (conditionIdentity(fact) === reportConditionIdentity(entry)));
+            if (condition?.status === "unresolved"
+                || (condition?.kind === "logcatEvent" && condition.status === "passed"
+                    && (condition.matchedCount !== 1
+                        || condition.matchedLineSha256 === undefined
+                        || condition.matchedAtMs === undefined
+                        || condition.evidenceRef === undefined))
+                || (fact.kind === "logcatEvent"
+                    && input.current.logcatEvidence?.some((entry) => (entry.lastDroppedAtMs === undefined
+                        || (condition?.kind === "logcatEvent"
+                            && entry.lastDroppedAtMs >= condition.startedAtMs))) === true)) {
+                throw new BaselineError("BASELINE_INCOMPARABLE", `Checkpoint ${id} has unresolved current evidence`);
+            }
+            if (condition?.status !== "passed") {
+                regressions.push({
+                    kind: fact.kind === "activity"
+                        ? "activity"
+                        : fact.kind === "screen" ? "screen"
+                            : fact.kind === "logcatEvent" ? "logcatEvent" : "element",
+                    checkpointId: id,
+                    ...(fact.stepIndex === undefined ? {} : { stepIndex: fact.stepIndex }),
+                    ...("locator" in fact ? { locator: fact.locator } : {}),
+                    ...(fact.kind === "screen" ? { screen: fact.expected } : {}),
+                    expected: `passed ${fact.kind}`,
+                    actual: condition?.status ?? "missing"
+                });
+            }
+        }
+    }
+    const result = RegressionCompareResultSchema.parse({
+        version: 1,
+        baselineId: input.baseline.id,
+        journeySha256: input.journeySha256,
+        comparedAt: input.comparedAt,
+        coverage: {
+            activities: input.baseline.activities.length,
+            elements: input.baseline.elements.length,
+            screens: input.baseline.screens.length,
+            ...(checkpointFacts.length === 0 ? {} : { checkpoints: checkpointFacts.length })
+        },
+        equivalent: regressions.length === 0,
+        regressions
+    });
+    return result;
+};

package/dist/application/collector/logcat-collector.d.ts

@@ -4,6 +4,8 @@ import type { CommandResult } from "../../ports/process-runner.js";
 export type LogLevel = "V" | "D" | "I" | "W" | "E" | "F" | "A";
 export interface LogcatLine {
     receivedAt: number;
+    /** Device threadtime timestamp without a year; receivedAt remains the monotonic window clock. */
+    deviceTimestamp?: string | undefined;
     raw: string;
     pid?: number | undefined;
     tid?: number | undefined;
@@ -14,25 +16,44 @@ export interface LogcatLine {
 export interface LogcatMetadata {
     deviceSerial: string;
     pids: readonly number[];
+    droppedLines?: number | undefined;
+    droppedBytes?: number | undefined;
+    lastDroppedAtMs?: number | undefined;
 }
 export interface StartLogcatOptions {
     deviceSerial: string;
+    pids?: readonly number[] | undefined;
     signal?: AbortSignal | undefined;
 }
 export declare class LogcatCollector {
     private readonly adb;
     private readonly clock;
+    private readonly limits;
+    /** Live lines are `collected[head..]`; dropped lines are compacted lazily. */
     private readonly collected;
+    private head;
+    private bufferedBytes;
+    private readonly droppedByPid;
     private readonly stderr;
     private readonly scopedPids;
     private running?;
     private streamMetadata?;
     private stopPromise?;
-    constructor(adb: AdbPort, clock: Clock);
+    constructor(adb: AdbPort, clock: Clock, limits?: {
+        maxLines: number;
+        maxBytes: number;
+    });
+    private append;
+    private retained;
+    private addScopedPids;
+    private droppedEvidence;
     start(options: StartLogcatOptions): Promise<void>;
     scopeToPids(pids: readonly number[]): void;
     metadata(): LogcatMetadata;
     lines(): readonly LogcatLine[];
+    /** Includes unparsed lines as raw artifacts, within the declared buffer limit. */
+    rawLines(): readonly LogcatLine[];
+    completeSince(startedAt: number): boolean;
     diagnosticLines(): readonly string[];
     linesBetween(startedAt: number, finishedAt: number): LogcatLine[];
     stop(): Promise<CommandResult>;