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

package/dist/domain/window-hierarchy.d.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import { type LayoutElement } from "./layout.js";
+export declare const AppWindowSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    packageName: z.ZodString;
+    type: z.ZodOptional<z.ZodString>;
+    layer: z.ZodOptional<z.ZodNumber>;
+    bounds: z.ZodOptional<z.ZodObject<{
+        left: z.ZodNumber;
+        top: z.ZodNumber;
+        right: z.ZodNumber;
+        bottom: z.ZodNumber;
+    }, z.core.$strict>>;
+    touchable: z.ZodBoolean;
+    focusable: z.ZodOptional<z.ZodBoolean>;
+    focused: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type AppWindow = z.infer<typeof AppWindowSchema>;
+export declare const WindowTopologySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    status: z.ZodEnum<{
+        observed: "observed";
+        unavailable: "unavailable";
+    }>;
+    windows: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        packageName: z.ZodString;
+        type: z.ZodOptional<z.ZodString>;
+        layer: z.ZodOptional<z.ZodNumber>;
+        bounds: z.ZodOptional<z.ZodObject<{
+            left: z.ZodNumber;
+            top: z.ZodNumber;
+            right: z.ZodNumber;
+            bottom: z.ZodNumber;
+        }, z.core.$strict>>;
+        touchable: z.ZodBoolean;
+        focusable: z.ZodOptional<z.ZodBoolean>;
+        focused: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    diagnostic: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type WindowTopology = z.infer<typeof WindowTopologySchema>;
+export declare const WindowHierarchySchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        unknown: "unknown";
+        complete: "complete";
+        incomplete: "incomplete";
+    }>;
+    appWindows: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        packageName: z.ZodString;
+        type: z.ZodOptional<z.ZodString>;
+        layer: z.ZodOptional<z.ZodNumber>;
+        bounds: z.ZodOptional<z.ZodObject<{
+            left: z.ZodNumber;
+            top: z.ZodNumber;
+            right: z.ZodNumber;
+            bottom: z.ZodNumber;
+        }, z.core.$strict>>;
+        touchable: z.ZodBoolean;
+        focusable: z.ZodOptional<z.ZodBoolean>;
+        focused: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    semanticWindowIds: z.ZodArray<z.ZodString>;
+    diagnostics: z.ZodArray<z.ZodObject<{
+        code: z.ZodEnum<{
+            WINDOW_TOPOLOGY_UNAVAILABLE: "WINDOW_TOPOLOGY_UNAVAILABLE";
+            SEMANTIC_WINDOW_IDS_UNAVAILABLE: "SEMANTIC_WINDOW_IDS_UNAVAILABLE";
+            APP_WINDOW_WITHOUT_SEMANTIC_ROOT: "APP_WINDOW_WITHOUT_SEMANTIC_ROOT";
+            APP_WINDOW_NOT_ACCESSIBILITY_READABLE: "APP_WINDOW_NOT_ACCESSIBILITY_READABLE";
+        }>;
+        message: z.ZodString;
+    }, z.core.$strict>>;
+    recovery: z.ZodArray<z.ZodEnum<{
+        REOBSERVE: "REOBSERVE";
+        LAYOUT_INSPECTOR: "LAYOUT_INSPECTOR";
+        DEBUG_WINDOW_INSPECTOR: "DEBUG_WINDOW_INSPECTOR";
+    }>>;
+}, z.core.$strict>;
+export type WindowHierarchy = z.infer<typeof WindowHierarchySchema>;
+export declare function assessWindowHierarchy(topology: WindowTopology, layout: readonly LayoutElement[]): WindowHierarchy;

package/dist/domain/window-hierarchy.js

@@ -0,0 +1,172 @@
+import { z } from "zod";
+import { BoundsSchema } from "./layout.js";
+export const AppWindowSchema = z.strictObject({
+    id: z.string().trim().min(1),
+    title: z.string().trim().min(1),
+    packageName: z.string().trim().min(1),
+    type: z.string().trim().min(1).optional(),
+    layer: z.number().int().nonnegative().optional(),
+    bounds: BoundsSchema.optional(),
+    touchable: z.boolean(),
+    focusable: z.boolean().optional(),
+    focused: z.boolean().optional()
+});
+export const WindowTopologySchema = z.strictObject({
+    version: z.literal(1),
+    status: z.enum(["observed", "unavailable"]),
+    windows: z.array(AppWindowSchema),
+    diagnostic: z.string().trim().min(1).optional()
+}).superRefine((topology, context) => {
+    if (topology.status === "observed"
+        && topology.diagnostic !== undefined) {
+        context.addIssue({
+            code: "custom",
+            path: ["diagnostic"],
+            message: "Observed window topology cannot include an unavailable diagnostic"
+        });
+    }
+    if (topology.status === "unavailable" && topology.windows.length > 0) {
+        context.addIssue({
+            code: "custom",
+            path: ["windows"],
+            message: "Unavailable window topology cannot include windows"
+        });
+    }
+});
+const HierarchyDiagnosticSchema = z.strictObject({
+    code: z.enum([
+        "WINDOW_TOPOLOGY_UNAVAILABLE",
+        "SEMANTIC_WINDOW_IDS_UNAVAILABLE",
+        "APP_WINDOW_WITHOUT_SEMANTIC_ROOT",
+        "APP_WINDOW_NOT_ACCESSIBILITY_READABLE"
+    ]),
+    message: z.string().trim().min(1)
+});
+export const WindowHierarchySchema = z.strictObject({
+    status: z.enum(["complete", "incomplete", "unknown"]),
+    appWindows: z.array(AppWindowSchema),
+    semanticWindowIds: z.array(z.string().trim().min(1)),
+    diagnostics: z.array(HierarchyDiagnosticSchema),
+    recovery: z.array(z.enum([
+        "REOBSERVE",
+        "LAYOUT_INSPECTOR",
+        "DEBUG_WINDOW_INSPECTOR"
+    ]))
+});
+function windowIds(elements) {
+    return [...new Set(elements.flatMap((element) => [
+            ...(element.windowId === undefined ? [] : [element.windowId]),
+            ...windowIds(element.children)
+        ]))].sort((left, right) => left.localeCompare(right));
+}
+function hasActionableElement(elements) {
+    return elements.some((element) => ((element.enabled
+        && (element.clickable === true
+            || element.longClickable === true
+            || element.focusable === true))
+        || hasActionableElement(element.children)));
+}
+/**
+ * Android accessibility serializes the active (focused) window. A visible
+ * touchable window that cannot take focus therefore never reaches the layout,
+ * no matter which acquisition backend is used. Sub panels are excluded because
+ * they carry decorations such as text-selection handles rather than controls.
+ */
+function unreadableWindows(windows) {
+    return windows.filter((window) => (window.focusable === false
+        && window.type !== "BASE_APPLICATION"
+        && window.type !== "APPLICATION_SUB_PANEL"));
+}
+export function assessWindowHierarchy(topology, layout) {
+    const parsedTopology = WindowTopologySchema.parse(topology);
+    const semanticWindowIds = windowIds(layout);
+    const unreadable = unreadableWindows(parsedTopology.windows);
+    if (unreadable.length > 0) {
+        return WindowHierarchySchema.parse({
+            status: "incomplete",
+            appWindows: parsedTopology.windows,
+            semanticWindowIds,
+            diagnostics: unreadable.map((window) => ({
+                code: "APP_WINDOW_NOT_ACCESSIBILITY_READABLE",
+                message: `Visible app window ${window.title}${window.type === undefined ? "" : ` (${window.type})`} cannot take focus, so accessibility never exposes its content`
+            })),
+            recovery: [
+                "REOBSERVE",
+                "LAYOUT_INSPECTOR",
+                "DEBUG_WINDOW_INSPECTOR"
+            ]
+        });
+    }
+    if (parsedTopology.status === "unavailable") {
+        return WindowHierarchySchema.parse({
+            status: "unknown",
+            appWindows: [],
+            semanticWindowIds,
+            diagnostics: [{
+                    code: "WINDOW_TOPOLOGY_UNAVAILABLE",
+                    message: parsedTopology.diagnostic
+                        ?? "ADB window topology is unavailable"
+                }],
+            recovery: ["REOBSERVE"]
+        });
+    }
+    if (semanticWindowIds.length === 0) {
+        return WindowHierarchySchema.parse({
+            status: "unknown",
+            appWindows: parsedTopology.windows,
+            semanticWindowIds,
+            diagnostics: [{
+                    code: "SEMANTIC_WINDOW_IDS_UNAVAILABLE",
+                    message: "Android layout did not expose semantic window identifiers"
+                }],
+            recovery: ["REOBSERVE"]
+        });
+    }
+    if (parsedTopology.windows.length === 0) {
+        return WindowHierarchySchema.parse({
+            status: "unknown",
+            appWindows: [],
+            semanticWindowIds,
+            diagnostics: [{
+                    code: "WINDOW_TOPOLOGY_UNAVAILABLE",
+                    message: "ADB window topology contained no visible touchable target-app windows"
+                }],
+            recovery: ["REOBSERVE"]
+        });
+    }
+    if (parsedTopology.windows.length > semanticWindowIds.length) {
+        const nonPanelWindows = parsedTopology.windows.filter((window) => window.type !== "APPLICATION_PANEL");
+        if (parsedTopology.windows.some((window) => window.type === "APPLICATION_PANEL")
+            && nonPanelWindows.length <= semanticWindowIds.length
+            && hasActionableElement(layout)) {
+            return WindowHierarchySchema.parse({
+                status: "complete",
+                appWindows: parsedTopology.windows,
+                semanticWindowIds,
+                diagnostics: [],
+                recovery: []
+            });
+        }
+        return WindowHierarchySchema.parse({
+            status: "incomplete",
+            appWindows: parsedTopology.windows,
+            semanticWindowIds,
+            diagnostics: [{
+                    code: "APP_WINDOW_WITHOUT_SEMANTIC_ROOT",
+                    message: `ADB observed ${String(parsedTopology.windows.length)} visible touchable app windows, but Android layout exposed ${String(semanticWindowIds.length)} semantic window roots`
+                }],
+            recovery: [
+                "REOBSERVE",
+                "LAYOUT_INSPECTOR",
+                "DEBUG_WINDOW_INSPECTOR"
+            ]
+        });
+    }
+    return WindowHierarchySchema.parse({
+        status: "complete",
+        appWindows: parsedTopology.windows,
+        semanticWindowIds,
+        diagnostics: [],
+        recovery: []
+    });
+}

package/dist/domain/workflow-manifest.d.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+export declare const WorkflowManifestSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    case: z.ZodObject<{
+        id: z.ZodString;
+        path: z.ZodEnum<{
+            accept: "accept";
+            preserve: "preserve";
+        }>;
+        requirement: z.ZodObject<{
+            sourceRef: z.ZodString;
+            summarySha256: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    diffs: z.ZodObject<{
+        implementation: z.ZodObject<{
+            path: z.ZodString;
+            sha256: z.ZodString;
+        }, z.core.$strict>;
+        verificationAssets: z.ZodObject<{
+            path: z.ZodString;
+            sha256: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    bindings: z.ZodObject<{
+        journeySha256: z.ZodString;
+        contractSha256: z.ZodOptional<z.ZodString>;
+        knowledgeHash: z.ZodOptional<z.ZodString>;
+        replayPolicy: z.ZodOptional<z.ZodObject<{
+            metaPath: z.ZodString;
+            sha256: z.ZodString;
+            strict: z.ZodBoolean;
+        }, z.core.$strict>>;
+        diffScope: z.ZodObject<{
+            used: z.ZodBoolean;
+            base: z.ZodOptional<z.ZodString>;
+            head: z.ZodOptional<z.ZodString>;
+            tiers: z.ZodArray<z.ZodEnum<{
+                p0: "p0";
+                p1: "p1";
+                p2: "p2";
+            }>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    commands: z.ZodArray<z.ZodObject<{
+        argv: z.ZodArray<z.ZodString>;
+        exitCode: z.ZodNumber;
+        jsonResultPath: z.ZodString;
+    }, z.core.$strict>>;
+    evidence: z.ZodObject<{
+        beforeReportPath: z.ZodOptional<z.ZodString>;
+        reportPath: z.ZodOptional<z.ZodString>;
+        verdictPath: z.ZodOptional<z.ZodString>;
+        baselinePath: z.ZodOptional<z.ZodString>;
+        compareResultPath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    outcome: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        path: z.ZodLiteral<"accept">;
+        verdict: z.ZodOptional<z.ZodEnum<{
+            invalid: "invalid";
+            pass: "pass";
+            fail: "fail";
+            inconclusive: "inconclusive";
+            needsReview: "needsReview";
+        }>>;
+    }, z.core.$strict>, z.ZodObject<{
+        path: z.ZodLiteral<"preserve">;
+        equivalent: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>], "path">;
+    status: z.ZodEnum<{
+        PASS: "PASS";
+        FAIL: "FAIL";
+        PAUSED: "PAUSED";
+    }>;
+    pauseReason: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type WorkflowManifest = z.infer<typeof WorkflowManifestSchema>;

package/dist/domain/workflow-manifest.js

@@ -0,0 +1,136 @@
+import { z } from "zod";
+import { posix } from "node:path";
+import { WORKFLOWS_DIR } from "./workspace.js";
+const DigestSchema = z.string().regex(/^[a-f\d]{64}$/);
+const ArtifactRefSchema = z.string().trim().min(1);
+const DiffReferenceSchema = z.strictObject({
+    path: ArtifactRefSchema,
+    sha256: DigestSchema
+});
+export const WorkflowManifestSchema = z.strictObject({
+    version: z.literal(1),
+    case: z.strictObject({
+        id: z.string().regex(/^[a-z][a-z0-9-]{0,63}$/),
+        path: z.enum(["accept", "preserve"]),
+        requirement: z.strictObject({
+            sourceRef: ArtifactRefSchema,
+            summarySha256: DigestSchema
+        })
+    }),
+    diffs: z.strictObject({
+        implementation: DiffReferenceSchema,
+        verificationAssets: DiffReferenceSchema
+    }),
+    bindings: z.strictObject({
+        journeySha256: DigestSchema,
+        contractSha256: DigestSchema.optional(),
+        knowledgeHash: DigestSchema.optional(),
+        replayPolicy: z.strictObject({
+            metaPath: ArtifactRefSchema,
+            sha256: DigestSchema,
+            strict: z.boolean()
+        }).optional(),
+        diffScope: z.strictObject({
+            used: z.boolean(),
+            base: z.string().trim().min(1).optional(),
+            head: z.string().trim().min(1).optional(),
+            tiers: z.array(z.enum(["p0", "p1", "p2"]))
+        }).superRefine((scope, context) => {
+            if (scope.used && (scope.base === undefined || scope.tiers.length === 0)) {
+                context.addIssue({
+                    code: "custom", message: "Used diff scope requires base and selected tiers"
+                });
+            }
+        })
+    }),
+    commands: z.array(z.strictObject({
+        argv: z.array(z.string().min(1)).min(1),
+        exitCode: z.number().int().nonnegative(),
+        jsonResultPath: ArtifactRefSchema
+    })),
+    evidence: z.strictObject({
+        beforeReportPath: ArtifactRefSchema.optional(),
+        reportPath: ArtifactRefSchema.optional(),
+        verdictPath: ArtifactRefSchema.optional(),
+        baselinePath: ArtifactRefSchema.optional(),
+        compareResultPath: ArtifactRefSchema.optional()
+    }),
+    outcome: z.discriminatedUnion("path", [
+        z.strictObject({
+            path: z.literal("accept"),
+            verdict: z.enum(["pass", "fail", "inconclusive", "needsReview", "invalid"])
+                .optional()
+        }),
+        z.strictObject({
+            path: z.literal("preserve"),
+            equivalent: z.boolean().optional()
+        })
+    ]),
+    status: z.enum(["PASS", "FAIL", "PAUSED"]),
+    pauseReason: z.string().trim().min(1).optional()
+}).superRefine((manifest, context) => {
+    const caseDir = `${WORKFLOWS_DIR}/${manifest.case.id}/`;
+    const insideCase = (path) => path.startsWith(caseDir)
+        && !path.includes("\\")
+        && !path.startsWith("/")
+        && posix.normalize(path) === path;
+    for (const [index, command] of manifest.commands.entries()) {
+        if (!insideCase(command.jsonResultPath)) {
+            context.addIssue({
+                code: "custom", path: ["commands", index, "jsonResultPath"],
+                message: "Command JSON must stay in the Case build directory"
+            });
+        }
+    }
+    for (const kind of ["implementation", "verificationAssets"]) {
+        if (!insideCase(manifest.diffs[kind].path)) {
+            context.addIssue({
+                code: "custom", path: ["diffs", kind, "path"],
+                message: "Diff evidence must stay in the Case build directory"
+            });
+        }
+    }
+    if (manifest.case.path !== manifest.outcome.path) {
+        context.addIssue({ code: "custom", path: ["outcome"], message: "Outcome path must match Case" });
+    }
+    if (manifest.status === "PAUSED" && manifest.pauseReason === undefined) {
+        context.addIssue({ code: "custom", path: ["pauseReason"], message: "Paused Case needs a reason" });
+    }
+    if (manifest.status !== "PASS")
+        return;
+    if (manifest.evidence.reportPath === undefined
+        || manifest.commands.length === 0
+        || manifest.commands.some((command) => command.exitCode !== 0)) {
+        context.addIssue({
+            code: "custom", path: ["status"],
+            message: "PASS needs a report and successful recorded commands"
+        });
+    }
+    if (manifest.bindings.replayPolicy?.strict !== true) {
+        context.addIssue({
+            code: "custom", path: ["bindings", "replayPolicy"],
+            message: "PASS requires a bound strict Replay policy"
+        });
+    }
+    if (manifest.case.path === "accept") {
+        if (manifest.outcome.path !== "accept"
+            || manifest.outcome.verdict !== "pass"
+            || manifest.evidence.verdictPath === undefined
+            || manifest.bindings.contractSha256 === undefined) {
+            context.addIssue({
+                code: "custom", path: ["status"],
+                message: "Accept PASS needs a bound passing Contract Verdict"
+            });
+        }
+    }
+    else if (manifest.outcome.path !== "preserve"
+        || manifest.outcome.equivalent !== true
+        || manifest.evidence.beforeReportPath === undefined
+        || manifest.evidence.baselinePath === undefined
+        || manifest.evidence.compareResultPath === undefined) {
+        context.addIssue({
+            code: "custom", path: ["status"],
+            message: "Preserve PASS needs a Baseline and equivalent comparison"
+        });
+    }
+});

package/dist/domain/workspace.d.ts

@@ -0,0 +1,28 @@
+export declare const TAPHOUND_DIR = ".taphound";
+export declare const CONFIG_PATH = ".taphound/config.json";
+export declare const CONTEXT_DIR = ".taphound/context";
+export declare const CONTEXT_INDEX_PATH = ".taphound/context/project-context.json";
+export declare const KNOWLEDGE_DIR = ".taphound/knowledge";
+export declare const KNOWLEDGE_INDEX_PATH = ".taphound/knowledge/index.json";
+export declare const KNOWLEDGE_ANCHORS_DIR = ".taphound/knowledge/anchors";
+export declare const KNOWLEDGE_SCREENS_DIR = ".taphound/knowledge/screens";
+export declare const FLOWS_DIR = ".taphound/flows";
+export declare const EXTERNAL_FLOWS_DIR = ".taphound/flows/external";
+export declare const JOURNEY_SOURCES_DIR = ".taphound/sources";
+export declare const JOURNEYS_DIR = ".taphound/journeys";
+export declare const CONTRACTS_DIR = ".taphound/contracts";
+export declare const BASELINES_DIR = ".taphound/baselines";
+export declare const BUILD_DIR = ".taphound/build";
+export declare const GENERATIONS_DIR = ".taphound/build/generations";
+export declare const JOBS_DIR = ".taphound/build/jobs";
+export declare const DEFAULT_ARTIFACTS_DIR = ".taphound/build/runs";
+export declare const WORKFLOWS_DIR = ".taphound/build/workflows";
+export declare function workflowManifestPath(caseId: string): string;
+export declare const BUILD_IGNORE_FILE = ".taphound/.gitignore";
+export declare const BUILD_IGNORE_CONTENT = "build/\n";
+export declare const GENERATION_CONTEXT_SNAPSHOT_PATH = "context/resolved.json";
+export declare function assertArtifactDirectory(projectRoot: string, artifactsDir: string, relativeAuthorityRoot?: string): void;
+export declare function isInvalidRelativeArtifactDirectory(path: string): boolean;
+export declare function assertProjectPathUnder(projectRoot: string, outputPath: string, relativeRoot: string, label: string): string;
+export declare function activeGenerationBundleName(id: string): string;
+export declare function parseSnapshotEvidenceReference(reference: string, generationId: string): string | null;

package/dist/domain/workspace.js

@@ -0,0 +1,72 @@
+import { isAbsolute, relative, resolve } from "node:path";
+import { posix } from "node:path";
+export const TAPHOUND_DIR = ".taphound";
+export const CONFIG_PATH = `${TAPHOUND_DIR}/config.json`;
+export const CONTEXT_DIR = `${TAPHOUND_DIR}/context`;
+export const CONTEXT_INDEX_PATH = `${CONTEXT_DIR}/project-context.json`;
+export const KNOWLEDGE_DIR = `${TAPHOUND_DIR}/knowledge`;
+export const KNOWLEDGE_INDEX_PATH = `${KNOWLEDGE_DIR}/index.json`;
+export const KNOWLEDGE_ANCHORS_DIR = `${KNOWLEDGE_DIR}/anchors`;
+export const KNOWLEDGE_SCREENS_DIR = `${KNOWLEDGE_DIR}/screens`;
+export const FLOWS_DIR = `${TAPHOUND_DIR}/flows`;
+export const EXTERNAL_FLOWS_DIR = `${FLOWS_DIR}/external`;
+export const JOURNEY_SOURCES_DIR = `${TAPHOUND_DIR}/sources`;
+export const JOURNEYS_DIR = `${TAPHOUND_DIR}/journeys`;
+export const CONTRACTS_DIR = `${TAPHOUND_DIR}/contracts`;
+export const BASELINES_DIR = `${TAPHOUND_DIR}/baselines`;
+export const BUILD_DIR = `${TAPHOUND_DIR}/build`;
+export const GENERATIONS_DIR = `${BUILD_DIR}/generations`;
+export const JOBS_DIR = `${BUILD_DIR}/jobs`;
+export const DEFAULT_ARTIFACTS_DIR = `${BUILD_DIR}/runs`;
+export const WORKFLOWS_DIR = `${BUILD_DIR}/workflows`;
+export function workflowManifestPath(caseId) {
+    if (!/^[a-z][a-z0-9-]{0,63}$/.test(caseId)) {
+        throw new Error("Workflow Case id must be a safe lowercase path component");
+    }
+    return `${WORKFLOWS_DIR}/${caseId}/manifest.json`;
+}
+export const BUILD_IGNORE_FILE = `${TAPHOUND_DIR}/.gitignore`;
+export const BUILD_IGNORE_CONTENT = "build/\n";
+export const GENERATION_CONTEXT_SNAPSHOT_PATH = "context/resolved.json";
+function isSameOrDescendant(parent, candidate) {
+    const fromParent = relative(parent, candidate);
+    return fromParent.length === 0
+        || (!fromParent.startsWith("..") && !isAbsolute(fromParent));
+}
+export function assertArtifactDirectory(projectRoot, artifactsDir, relativeAuthorityRoot = BUILD_DIR) {
+    const build = resolve(projectRoot, relativeAuthorityRoot);
+    const candidate = resolve(projectRoot, artifactsDir);
+    if (!isSameOrDescendant(build, candidate)) {
+        throw new Error(`Artifact output must stay under ${BUILD_DIR}/: ${artifactsDir}`);
+    }
+}
+export function isInvalidRelativeArtifactDirectory(path) {
+    const normalized = posix.normalize(path.replaceAll("\\", "/"));
+    return !posix.isAbsolute(normalized)
+        && normalized !== BUILD_DIR
+        && !normalized.startsWith(`${BUILD_DIR}/`);
+}
+export function assertProjectPathUnder(projectRoot, outputPath, relativeRoot, label) {
+    const root = resolve(projectRoot, relativeRoot);
+    const candidate = resolve(projectRoot, outputPath);
+    if (!isSameOrDescendant(root, candidate)) {
+        throw new Error(`${label} must stay under ${relativeRoot}/: ${outputPath}`);
+    }
+    return candidate;
+}
+const SNAPSHOT_EVIDENCE_REFERENCE_PATTERN = new RegExp(`^${GENERATIONS_DIR.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/([^/]+)/(evidence/snapshots/revision-\\d+/[^/]+/snapshot\\.json)$`);
+export function activeGenerationBundleName(id) {
+    return `.${id}.work`;
+}
+export function parseSnapshotEvidenceReference(reference, generationId) {
+    const match = SNAPSHOT_EVIDENCE_REFERENCE_PATTERN.exec(reference);
+    if (match === null) {
+        return null;
+    }
+    const bundleName = match[1] ?? "";
+    if (bundleName !== generationId
+        && bundleName !== activeGenerationBundleName(generationId)) {
+        return null;
+    }
+    return match[2] ?? null;
+}

package/dist/ports/adb.d.ts

@@ -1,6 +1,7 @@
-import type { Point } from "./android-cli.js";
+import type { Point } from "../domain/geometry.js";
 import type { ForegroundComponent } from "../domain/activity.js";
 import type { AppProcess } from "../domain/app-process.js";
+import type { WindowTopology } from "../domain/window-hierarchy.js";
 import type { CommandResult, RunningCommand } from "./process-runner.js";
 export interface DeviceInfo {
     serial: string;
@@ -19,24 +20,56 @@ export interface LaunchActivityOptions {
     signal?: AbortSignal | undefined;
     timeoutMs?: number | undefined;
 }
+export interface StartActivityByIntentOptions {
+    action: string;
+    deviceSerial: string;
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number | undefined;
+}
+export interface ResolveLauncherActivityOptions {
+    packageName: string;
+    deviceSerial: string;
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number | undefined;
+}
+export interface ResolvedActivity {
+    packageName: string;
+    activity: string;
+}
 export interface LogcatOptions {
     deviceSerial: string;
     onStdoutLine: (line: string) => void;
     onStderrLine?: ((line: string) => void) | undefined;
     signal?: AbortSignal | undefined;
 }
+export interface DumpLogcatOptions {
+    deviceSerial: string;
+    maxLines: number;
+    signal?: AbortSignal | undefined;
+    timeoutMs?: number | undefined;
+}
+export interface DeviceIdentity {
+    manufacturer: string;
+    model: string;
+    sdkLevel: number;
+}
 export interface AdbPort {
     devices: (signal?: AbortSignal) => Promise<readonly DeviceInfo[]>;
+    deviceIdentity?: (identity: AppIdentity) => Promise<DeviceIdentity>;
     foregroundComponent: (identity: AppIdentity) => Promise<ForegroundComponent>;
     currentActivity: (identity: AppIdentity) => Promise<string>;
     isInstalled: (identity: AppIdentity) => Promise<boolean>;
     launchActivity: (options: LaunchActivityOptions) => Promise<CommandResult>;
+    startActivityByIntent: (options: StartActivityByIntentOptions) => Promise<CommandResult>;
+    resolveLauncherActivity: (options: ResolveLauncherActivityOptions) => Promise<ResolvedActivity | undefined>;
     forceStop: (identity: AppIdentity) => Promise<CommandResult>;
     appProcesses: (identity: AppIdentity) => Promise<readonly AppProcess[]>;
+    windowTopology: (identity: AppIdentity) => Promise<WindowTopology>;
     tap: (point: Point, deviceSerial: string, signal?: AbortSignal) => Promise<CommandResult>;
     longClick: (point: Point, durationMs: number, deviceSerial: string, signal?: AbortSignal) => Promise<CommandResult>;
     swipe: (from: Point, to: Point, durationMs: number, deviceSerial: string, signal?: AbortSignal) => Promise<CommandResult>;
     back: (deviceSerial: string, signal?: AbortSignal) => Promise<CommandResult>;
     inputText: (text: string, deviceSerial: string, signal?: AbortSignal) => Promise<CommandResult>;
     startLogcat: (options: LogcatOptions) => RunningCommand;
+    dumpLogcat: (options: DumpLogcatOptions) => Promise<CommandResult>;
 }

package/dist/ports/align-prompt.d.ts

@@ -0,0 +1,11 @@
+import type { CameraProbeResult } from "./camera-probe.js";
+export declare class AlignPromptCancelledError extends Error {
+    readonly name = "AlignPromptCancelledError";
+    constructor();
+}
+export interface AlignPromptPort {
+    confirmWrite: (input: {
+        values: CameraProbeResult;
+        targetPath: string;
+    }) => Promise<boolean>;
+}

package/dist/ports/align-prompt.js

@@ -0,0 +1,6 @@
+export class AlignPromptCancelledError extends Error {
+    name = "AlignPromptCancelledError";
+    constructor() {
+        super("Align prompt was cancelled");
+    }
+}