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

package/dist/domain/checkpoint.js

@@ -0,0 +1,297 @@
+import { z } from "zod";
+import { KnowledgeIdSchema, KnowledgeSha256Schema, KnowledgeStatusSchema } from "./knowledge.js";
+import { QualifiedNameSchema } from "./knowledge.js";
+import { LocatorSchema } from "./layout.js";
+import { LogcatEventExpectSchema } from "./logcat-event.js";
+import { checkBindingReferences } from "./binding-reference.js";
+/**
+ * Checkpoint: a named behavioral expectation at a point in a Journey.
+ *
+ * A Checkpoint is not a screenshot. It is a verifiable contract over
+ * observable behavior: which Activity is in the foreground, which elements
+ * are present/absent, and (optionally) a Knowledge Screen. The expectation is
+ * deterministic and machine-checkable; a checkpoint never triggers an AI
+ * layer by itself (see docs/source-of-truth.md).
+ */
+export const CheckpointAllOfConditionSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        kind: z.literal("activity"),
+        expected: z.string().trim().min(1)
+    }),
+    z.strictObject({
+        kind: z.literal("screen"),
+        expected: KnowledgeIdSchema
+    }),
+    z.strictObject({
+        kind: z.literal("visibleElement"),
+        locator: LocatorSchema
+    }),
+    z.strictObject({
+        kind: z.literal("absentElement"),
+        locator: LocatorSchema
+    }),
+    z.strictObject({
+        kind: z.literal("logcatEvent"),
+        expect: LogcatEventExpectSchema.omit({ timeoutMs: true })
+    })
+]);
+export const CheckpointExpectSchema = z.strictObject({
+    allOf: z.array(CheckpointAllOfConditionSchema).min(1),
+    timeoutMs: z.number().int().positive().max(60000)
+}).superRefine((expect, context) => {
+    checkBindingReferences(expect, context, []);
+    const keys = new Set();
+    const kinds = new Set();
+    for (const [index, condition] of expect.allOf.entries()) {
+        if (condition.kind === "logcatEvent" && condition.expect.capture !== undefined) {
+            context.addIssue({
+                code: "custom", path: ["allOf", index, "expect", "capture"],
+                message: "Checkpoint cannot capture Replay bindings"
+            });
+        }
+        if ((condition.kind === "activity" || condition.kind === "screen")
+            && kinds.has(condition.kind)) {
+            context.addIssue({
+                code: "custom",
+                path: ["allOf", index],
+                message: "allOf supports only one activity and one screen condition"
+            });
+        }
+        kinds.add(condition.kind);
+        const key = JSON.stringify([
+            condition.kind,
+            condition.kind === "logcatEvent"
+                ? condition.expect
+                : "locator" in condition ? condition.locator : condition.expected
+        ]);
+        if (keys.has(key)) {
+            context.addIssue({
+                code: "custom",
+                path: ["allOf", index],
+                message: "allOf conditions must have unique identities"
+            });
+        }
+        keys.add(key);
+    }
+});
+export const CheckpointDefinitionSchema = z.strictObject({
+    version: z.literal(1),
+    id: KnowledgeIdSchema,
+    name: z.string().trim().min(1),
+    /** Zero-based step index evaluated after that step; absent means after the Journey. */
+    stepIndex: z.number().int().nonnegative().optional(),
+    expect: CheckpointExpectSchema,
+    status: KnowledgeStatusSchema.default("inferred")
+});
+export const BaselineElementFactSchema = z.strictObject({
+    locator: LocatorSchema.optional(),
+    anchorId: KnowledgeIdSchema.optional(),
+    stepIndex: z.number().int().nonnegative(),
+    kind: z.literal("present"),
+    matchedBy: z.enum([
+        "resourceId",
+        "text",
+        "contentDescription",
+        "anchor"
+    ]).optional(),
+    fallbackUsed: z.boolean().optional(),
+    evidenceSha256: KnowledgeSha256Schema.optional()
+}).refine((fact) => (fact.locator === undefined) !== (fact.anchorId === undefined), "Element facts need exactly one locator or anchor identity");
+export const BaselineActivityFactSchema = z.strictObject({
+    stepIndex: z.number().int().nonnegative(),
+    before: z.string().trim().min(1),
+    after: z.string().trim().min(1)
+});
+export const BaselineScreenFactSchema = z.strictObject({
+    screen: KnowledgeIdSchema,
+    status: z.enum(["matched", "ambiguous", "unresolved"])
+});
+const CheckpointFactIdentity = {
+    checkpointId: KnowledgeIdSchema,
+    stepIndex: z.number().int().nonnegative().optional()
+};
+export const BaselineCheckpointFactSchema = z.discriminatedUnion("kind", [
+    z.strictObject({
+        ...CheckpointFactIdentity,
+        kind: z.literal("activity"),
+        expected: z.string().trim().min(1)
+    }),
+    z.strictObject({
+        ...CheckpointFactIdentity,
+        kind: z.literal("screen"),
+        expected: KnowledgeIdSchema
+    }),
+    z.strictObject({
+        ...CheckpointFactIdentity,
+        kind: z.literal("visibleElement"),
+        locator: LocatorSchema
+    }),
+    z.strictObject({
+        ...CheckpointFactIdentity,
+        kind: z.literal("absentElement"),
+        locator: LocatorSchema
+    }),
+    z.strictObject({
+        ...CheckpointFactIdentity,
+        kind: z.literal("logcatEvent"),
+        expect: LogcatEventExpectSchema.omit({ timeoutMs: true })
+    })
+]);
+/**
+ * Baseline: frozen, hash-bound evidence of one known-good run.
+ *
+ * The Baseline is behavior evidence, not a screenshot (architecture doc
+ * §15): activity sequence, element presence facts, optional Knowledge screen
+ * detection, and the failing evidence summary fields. Every fact is
+ * deterministic and comparable.
+ */
+export const BaselineSchema = z.strictObject({
+    version: z.literal(1),
+    id: KnowledgeIdSchema,
+    journeySha256: KnowledgeSha256Schema,
+    contractSha256: KnowledgeSha256Schema.optional(),
+    capturedAt: z.iso.datetime(),
+    packageName: QualifiedNameSchema,
+    runId: z.string().trim().min(1),
+    activities: z.array(BaselineActivityFactSchema),
+    elements: z.array(BaselineElementFactSchema),
+    screens: z.array(BaselineScreenFactSchema),
+    checkpoints: z.array(BaselineCheckpointFactSchema).optional(),
+    requiredEvidence: z.strictObject({
+        screens: z.boolean()
+    }),
+    sourceReportPath: z.string().trim().min(1)
+}).superRefine((baseline, context) => {
+    if (baseline.activities.length === 0
+        && baseline.elements.length === 0
+        && baseline.screens.length === 0
+        && (baseline.checkpoints?.length ?? 0) === 0) {
+        context.addIssue({
+            code: "custom",
+            path: ["activities"],
+            message: "A Baseline needs at least one comparable fact"
+        });
+    }
+    if (!baseline.requiredEvidence.screens
+        && baseline.screens.length > 0) {
+        context.addIssue({
+            code: "custom",
+            path: ["requiredEvidence", "screens"],
+            message: "Screen facts require Screen evidence"
+        });
+    }
+    const steps = new Set();
+    for (const [index, fact] of baseline.activities.entries()) {
+        if (steps.has(fact.stepIndex)) {
+            context.addIssue({
+                code: "custom",
+                path: ["activities", index, "stepIndex"],
+                message: `Activity facts must be unique per step; duplicate step ${String(fact.stepIndex)}`
+            });
+        }
+        steps.add(fact.stepIndex);
+    }
+    const elementKeys = new Set();
+    for (const [index, fact] of baseline.elements.entries()) {
+        const key = JSON.stringify([
+            fact.stepIndex,
+            fact.anchorId ?? null,
+            fact.locator ?? null
+        ]);
+        if (elementKeys.has(key)) {
+            context.addIssue({
+                code: "custom",
+                path: ["elements", index],
+                message: "Element facts must be unique per step and identity"
+            });
+        }
+        elementKeys.add(key);
+    }
+    const screenIds = new Set();
+    for (const [index, fact] of baseline.screens.entries()) {
+        if (screenIds.has(fact.screen)) {
+            context.addIssue({
+                code: "custom",
+                path: ["screens", index, "screen"],
+                message: "Screen facts must be unique per Screen"
+            });
+        }
+        screenIds.add(fact.screen);
+    }
+    const checkpointKeys = new Set();
+    const checkpointPoints = new Map();
+    for (const [index, fact] of (baseline.checkpoints ?? []).entries()) {
+        const priorPoint = checkpointPoints.get(fact.checkpointId);
+        if (checkpointPoints.has(fact.checkpointId)
+            && priorPoint !== fact.stepIndex) {
+            context.addIssue({
+                code: "custom",
+                path: ["checkpoints", index],
+                message: "Checkpoint facts must share one evaluation point per ID"
+            });
+        }
+        checkpointPoints.set(fact.checkpointId, fact.stepIndex);
+        const key = JSON.stringify([
+            fact.checkpointId,
+            fact.stepIndex ?? null,
+            fact.kind,
+            "locator" in fact ? fact.locator
+                : "expect" in fact ? fact.expect : fact.expected
+        ]);
+        if (checkpointKeys.has(key)) {
+            context.addIssue({
+                code: "custom",
+                path: ["checkpoints", index],
+                message: "Checkpoint facts must have unique condition identities"
+            });
+        }
+        checkpointKeys.add(key);
+    }
+});
+export function baselineEvidence(baseline) {
+    return {
+        activities: baseline.activities,
+        elements: baseline.elements,
+        screens: baseline.screens,
+        ...(baseline.checkpoints === undefined ? {} : { checkpoints: baseline.checkpoints })
+    };
+}
+/**
+ * Regression compare result. `regressions` is empty when current evidence is
+ * equivalent to the baseline; each entry names one drifted fact.
+ */
+export const RegressionDiffSchema = z.strictObject({
+    kind: z.enum(["activity", "element", "screen", "logcatEvent"]),
+    stepIndex: z.number().int().nonnegative().optional(),
+    locator: LocatorSchema.optional(),
+    screen: KnowledgeIdSchema.optional(),
+    checkpointId: KnowledgeIdSchema.optional(),
+    expected: z.string().trim().min(1),
+    actual: z.string().trim().min(1)
+});
+export const RegressionCompareResultSchema = z.strictObject({
+    version: z.literal(1),
+    baselineId: KnowledgeIdSchema,
+    journeySha256: KnowledgeSha256Schema,
+    comparedAt: z.iso.datetime(),
+    equivalent: z.boolean(),
+    coverage: z.strictObject({
+        activities: z.number().int().nonnegative(),
+        elements: z.number().int().nonnegative(),
+        screens: z.number().int().nonnegative(),
+        checkpoints: z.number().int().nonnegative().optional()
+    }),
+    regressions: z.array(RegressionDiffSchema)
+}).superRefine((result, context) => {
+    if (result.equivalent
+        && (result.regressions.length > 0
+            || (result.coverage.activities
+                + result.coverage.elements
+                + result.coverage.screens === 0
+                && (result.coverage.checkpoints ?? 0) === 0))) {
+        context.addIssue({
+            code: "custom",
+            message: "Equivalence requires nonempty coverage and no regressions"
+        });
+    }
+});

package/dist/domain/config.d.ts

@@ -1,4 +1,58 @@
 import { z } from "zod";
+export declare const DeviceIdleProfileMatchSchema: z.ZodObject<{
+    manufacturer: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    sdkLevel: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const DeviceIdleProfileSchema: z.ZodObject<{
+    match: z.ZodObject<{
+        manufacturer: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        sdkLevel: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    strategy: z.ZodOptional<z.ZodEnum<{
+        frameStats: "frameStats";
+        hybrid: "hybrid";
+        layoutDiff: "layoutDiff";
+        structural: "structural";
+    }>>;
+    pollIntervalMs: z.ZodOptional<z.ZodNumber>;
+    stablePolls: z.ZodOptional<z.ZodNumber>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    ignoreCursorBlink: z.ZodOptional<z.ZodBoolean>;
+    ignoreLayoutDrift: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const IdlePolicySchema: z.ZodObject<{
+    strategy: z.ZodDefault<z.ZodEnum<{
+        frameStats: "frameStats";
+        hybrid: "hybrid";
+        layoutDiff: "layoutDiff";
+        structural: "structural";
+    }>>;
+    pollIntervalMs: z.ZodNumber;
+    stablePolls: z.ZodNumber;
+    timeoutMs: z.ZodNumber;
+    ignoreCursorBlink: z.ZodOptional<z.ZodBoolean>;
+    ignoreLayoutDrift: z.ZodOptional<z.ZodBoolean>;
+    deviceProfiles: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        match: z.ZodObject<{
+            manufacturer: z.ZodOptional<z.ZodString>;
+            model: z.ZodOptional<z.ZodString>;
+            sdkLevel: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+        strategy: z.ZodOptional<z.ZodEnum<{
+            frameStats: "frameStats";
+            hybrid: "hybrid";
+            layoutDiff: "layoutDiff";
+            structural: "structural";
+        }>>;
+        pollIntervalMs: z.ZodOptional<z.ZodNumber>;
+        stablePolls: z.ZodOptional<z.ZodNumber>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+        ignoreCursorBlink: z.ZodOptional<z.ZodBoolean>;
+        ignoreLayoutDrift: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
 export declare const TapHoundConfigSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
     run: z.ZodObject<{
@@ -6,10 +60,62 @@ export declare const TapHoundConfigSchema: z.ZodObject<{
         activity: z.ZodString;
     }, z.core.$strict>;
     idle: z.ZodObject<{
+        strategy: z.ZodDefault<z.ZodEnum<{
+            frameStats: "frameStats";
+            hybrid: "hybrid";
+            layoutDiff: "layoutDiff";
+            structural: "structural";
+        }>>;
         pollIntervalMs: z.ZodNumber;
         stablePolls: z.ZodNumber;
         timeoutMs: z.ZodNumber;
+        ignoreCursorBlink: z.ZodOptional<z.ZodBoolean>;
+        ignoreLayoutDrift: z.ZodOptional<z.ZodBoolean>;
+        deviceProfiles: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            match: z.ZodObject<{
+                manufacturer: z.ZodOptional<z.ZodString>;
+                model: z.ZodOptional<z.ZodString>;
+                sdkLevel: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>;
+            strategy: z.ZodOptional<z.ZodEnum<{
+                frameStats: "frameStats";
+                hybrid: "hybrid";
+                layoutDiff: "layoutDiff";
+                structural: "structural";
+            }>>;
+            pollIntervalMs: z.ZodOptional<z.ZodNumber>;
+            stablePolls: z.ZodOptional<z.ZodNumber>;
+            timeoutMs: z.ZodOptional<z.ZodNumber>;
+            ignoreCursorBlink: z.ZodOptional<z.ZodBoolean>;
+            ignoreLayoutDrift: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>>;
     }, z.core.$strict>;
-    artifactsDir: z.ZodString;
+    ui: z.ZodOptional<z.ZodObject<{
+        backend: z.ZodEnum<{
+            "system-uiautomator": "system-uiautomator";
+            "android-cli": "android-cli";
+            "appium-uiautomator2": "appium-uiautomator2";
+            auto: "auto";
+        }>;
+        snapshotTimeoutMs: z.ZodOptional<z.ZodNumber>;
+        cacheEnabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    runtime: z.ZodOptional<z.ZodObject<{
+        backend: z.ZodEnum<{
+            adb: "adb";
+            "mobile-mcp": "mobile-mcp";
+            auto: "auto";
+        }>;
+    }, z.core.$strict>>;
+    artifactsDir: z.ZodDefault<z.ZodString>;
 }, z.core.$strict>;
+export type IdlePolicy = z.infer<typeof IdlePolicySchema>;
+export type DeviceIdleProfileMatch = z.infer<typeof DeviceIdleProfileMatchSchema>;
+export type DeviceIdleProfile = z.infer<typeof DeviceIdleProfileSchema>;
 export type TapHoundConfig = z.infer<typeof TapHoundConfigSchema>;
+export declare const DEFAULT_UI_CONFIG: {
+    backend: "auto";
+};
+export declare const DEFAULT_RUNTIME_CONFIG: {
+    backend: "auto";
+};

package/dist/domain/config.js

@@ -1,17 +1,63 @@
 import { z } from "zod";
+import { DEFAULT_ARTIFACTS_DIR, isInvalidRelativeArtifactDirectory } from "./workspace.js";
+import { RuntimeBackendChoiceSchema } from "./runtime.js";
+import { UiBackendSelectionSchema } from "./ui-backend.js";
 const PackageNameSchema = z.string().regex(/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)+$/, "packageName must be a qualified Java package");
 const ActivityNameSchema = z.string().refine((value) => (/^\.[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/.test(value)
     || /^(?:[A-Za-z_$][\w$]*\.)+[A-Za-z_$][\w$]*$/.test(value)), "activity must be relative with a leading dot or fully qualified");
+export const DeviceIdleProfileMatchSchema = z.strictObject({
+    manufacturer: z.string().trim().min(1).optional(),
+    model: z.string().trim().min(1).optional(),
+    sdkLevel: z.number().int().positive().optional()
+});
+export const DeviceIdleProfileSchema = z.strictObject({
+    match: DeviceIdleProfileMatchSchema,
+    strategy: z.enum(["hybrid", "layoutDiff", "frameStats", "structural"]).optional(),
+    pollIntervalMs: z.number().int().positive().optional(),
+    stablePolls: z.number().int().positive().optional(),
+    timeoutMs: z.number().int().positive().optional(),
+    ignoreCursorBlink: z.boolean().optional(),
+    ignoreLayoutDrift: z.boolean().optional()
+}).superRefine((profile, context) => {
+    if (profile.match.manufacturer === undefined
+        && profile.match.model === undefined
+        && profile.match.sdkLevel === undefined) {
+        context.addIssue({
+            code: "custom",
+            path: ["match"],
+            message: "A device idle profile must match at least one device attribute"
+        });
+    }
+});
+export const IdlePolicySchema = z.strictObject({
+    strategy: z.enum(["hybrid", "layoutDiff", "frameStats", "structural"]).default("hybrid"),
+    pollIntervalMs: z.number().int().positive(),
+    stablePolls: z.number().int().positive(),
+    timeoutMs: z.number().int().positive(),
+    ignoreCursorBlink: z.boolean().optional(),
+    ignoreLayoutDrift: z.boolean().optional(),
+    deviceProfiles: z.array(DeviceIdleProfileSchema).optional()
+});
 export const TapHoundConfigSchema = z.strictObject({
     version: z.literal(1),
     run: z.strictObject({
         packageName: PackageNameSchema,
         activity: ActivityNameSchema
     }),
-    idle: z.strictObject({
-        pollIntervalMs: z.number().int().positive(),
-        stablePolls: z.number().int().positive(),
-        timeoutMs: z.number().int().positive()
-    }),
-    artifactsDir: z.string().trim().min(1)
+    idle: IdlePolicySchema,
+    ui: z.strictObject({
+        backend: UiBackendSelectionSchema,
+        snapshotTimeoutMs: z.number().int().positive().optional(),
+        cacheEnabled: z.boolean().optional()
+    }).optional(),
+    runtime: z.strictObject({
+        backend: RuntimeBackendChoiceSchema
+    }).optional(),
+    artifactsDir: z.string().trim().min(1).refine((path) => !isInvalidRelativeArtifactDirectory(path), "artifactsDir inside .taphound/ must stay under .taphound/build/").default(DEFAULT_ARTIFACTS_DIR)
 });
+export const DEFAULT_UI_CONFIG = {
+    backend: "auto"
+};
+export const DEFAULT_RUNTIME_CONFIG = {
+    backend: "auto"
+};