taphound 0.2.0-dev.1 → 0.2.0-dev.12

package/dist/application/generation/generation-finalizer.js

@@ -2,10 +2,12 @@ import { createHash } from "node:crypto";
 import { realpath } from "node:fs/promises";
 import { basename, extname } from "node:path";
 import { z } from "zod";
+import { UiBackendDescriptorSchema } from "../../domain/ui-backend.js";
 import { normalizeActivity } from "../../domain/activity.js";
 import { GenerationMetaSchema, GenerationReportSchema, GenerationSessionSchema } from "../../domain/generation.js";
-import { JourneySchema } from "../../domain/journey.js";
-import { ProjectContextSchema, ProjectRelativePathSchema } from "../../domain/project-context.js";
+import { DEFAULT_DEVICE_ROLE, JourneySchema } from "../../domain/journey.js";
+import { ResolvedProjectContextSchema } from "../../domain/project-context.js";
+import { JourneyOutputPathSchema } from "../../domain/journey-composition.js";
 import { hashJourney, TapHoundReportSchema } from "../../domain/report.js";
 import { TapHoundConfigSchema } from "../../domain/config.js";
 import { GenerationSessionStoreError } from "../../ports/generation-session-store.js";
@@ -35,7 +37,8 @@ const VerificationReceiptSchema = z.strictObject({
         projectHash: Sha256Schema,
         configHash: Sha256Schema,
         contextHash: Sha256Schema,
-        snapshotHash: Sha256Schema.nullable()
+        snapshotHash: Sha256Schema.nullable(),
+        uiBackend: UiBackendDescriptorSchema
     }),
     tools: z.record(z.string(), z.string()),
     report: z.strictObject({
@@ -44,18 +47,19 @@ const VerificationReceiptSchema = z.strictObject({
         runId: z.string().min(1)
     })
 });
-export const GenerationOutputPathSchema = ProjectRelativePathSchema.refine((path) => path.split("/").every((segment) => segment.length > 0 && segment !== "."), "Generation output path must be normalized").refine((path) => (path !== ".taphound/generations"
-    && !path.startsWith(".taphound/generations/")), "Generation output cannot overlap the authoritative bundle");
+export const GenerationOutputPathSchema = JourneyOutputPathSchema;
 export class GenerationFinalizationError extends Error {
     code;
     stage;
     recoverable;
+    details;
     name = "GenerationFinalizationError";
-    constructor(code, stage, recoverable, message, options) {
+    constructor(code, stage, recoverable, message, options, details) {
         super(message, options);
         this.code = code;
         this.stage = stage;
         this.recoverable = recoverable;
+        this.details = details;
     }
 }
 function serializeJson(value) {
@@ -64,12 +68,6 @@ function serializeJson(value) {
 function sha256(value) {
     return createHash("sha256").update(value).digest("hex");
 }
-function commandFailed(result) {
-    return result.exitCode !== 0
-        || result.timedOut
-        || result.cancelled
-        || result.spawnError !== undefined;
-}
 function derivedJourneyName(outputPath) {
     const file = basename(outputPath);
     const extension = extname(file);
@@ -89,13 +87,23 @@ function sameJson(left, right) {
 function locatorMatchIsEligible(matchedBy, step) {
     if (step.action !== "click"
         && step.action !== "longClick"
-        && step.action !== "swipe") {
+        && step.action !== "swipe"
+        && step.action !== "bridge") {
         return matchedBy === undefined;
     }
-    return matchedBy !== undefined && step.locator[matchedBy] !== undefined;
+    if (matchedBy === undefined) {
+        return false;
+    }
+    const locator = step.action === "bridge"
+        ? step.triggerLocator
+        : step.locator;
+    if (locator === undefined || matchedBy === "anchor") {
+        return false;
+    }
+    return locator[matchedBy] !== undefined;
 }
-function failure(code, stage, message, recoverable = false, cause) {
-    return new GenerationFinalizationError(code, stage, recoverable, message, cause === undefined ? undefined : { cause });
+function failure(code, stage, message, recoverable = false, cause, details) {
+    return new GenerationFinalizationError(code, stage, recoverable, message, cause === undefined ? undefined : { cause }, details);
 }
 export class GenerationFinalizer {
     dependencies;
@@ -104,7 +112,7 @@ export class GenerationFinalizer {
     }
     finalize = async (input) => {
         const config = TapHoundConfigSchema.parse(input.config);
-        const context = ProjectContextSchema.parse(input.context);
+        const context = ResolvedProjectContextSchema.parse(input.context);
         const project = ProjectDescriptionSchema.parse(input.project);
         const canonicalProjectRoot = await realpath(input.projectRoot);
         const outputPath = GenerationOutputPathSchema.parse(input.outputPath);
@@ -114,13 +122,20 @@ export class GenerationFinalizer {
         let session = GenerationSessionSchema.parse(await this.dependencies.store.read(input.generationId));
         this.assertBindings(session, input, config, context, project);
         const journey = JourneySchema.parse({
-            version: 1,
+            version: 2,
             name,
+            devices: [{ role: DEFAULT_DEVICE_ROLE }],
             steps: session.candidateSteps
         });
+        if (input.manualReplay === false
+            && journey.steps.some((step) => step.replayMode === "manual")) {
+            throw failure("VERIFICATION_FAILED", "verification", "Journey contains manual steps; cannot finalize in non-interactive mode. Re-run finalize from an interactive terminal so manual steps can be replayed with human operation of the external application", false);
+        }
         let replayed = false;
         let verificationReport;
         if (session.verification.status === "notRun") {
+            this.revalidate(input, config, context, project, session);
+            this.dependencies.progress?.("verification");
             const begun = await this.beginVerification(session);
             session = begun.session;
             if (!begun.owned
@@ -136,7 +151,9 @@ export class GenerationFinalizer {
                     let reconciled;
                     try {
                         reconciled = session.verification.status === "running"
-                            ? await this.reconcilePassedVerification(session, expected, () => this.revalidate(input, config, context, project, session))
+                            ? await this.reconcilePassedVerification(session, expected, () => {
+                                this.revalidate(input, config, context, project, session);
+                            })
                             : undefined;
                     }
                     catch (error) {
@@ -154,33 +171,33 @@ export class GenerationFinalizer {
             }
             if (begun.owned) {
                 try {
-                    await this.revalidate(input, config, context, project, session);
                     if (input.signal?.aborted === true) {
                         throw failure("VERIFICATION_FAILED", "verification", "Generation finalization was cancelled");
                     }
-                    const stopped = await this.dependencies.adb.forceStop({
-                        packageName: session.target.packageName,
-                        deviceSerial: session.target.deviceSerial,
-                        ...(input.signal === undefined ? {} : { signal: input.signal }),
-                        timeoutMs: config.idle.timeoutMs
-                    });
-                    if (commandFailed(stopped)) {
-                        throw failure("VERIFICATION_FAILED", "verification", stopped.stderr.trim()
-                            || stopped.spawnError
-                            || "Unable to reset the generated Journey process");
-                    }
+                    const replayProgress = this.bridgeReplayProgress(session.id, expected.attemptId);
+                    const replayConfig = session.idlePolicy === undefined
+                        ? config
+                        : { ...config, idle: session.idlePolicy };
                     const result = await this.dependencies.verifyRuntime.verify({
-                        config,
+                        config: replayConfig,
                         journey,
                         projectRoot: canonicalProjectRoot,
-                        deviceSerial: input.deviceSerial,
+                        devices: [{
+                                role: journey.devices[0]?.role ?? DEFAULT_DEVICE_ROLE,
+                                deviceSerial: input.deviceSerial
+                            }],
                         toolVersions: input.toolVersions,
                         requireFocusedInput: true,
                         generatedReplayPolicy: true,
-                        ...(input.signal === undefined ? {} : { signal: input.signal })
+                        ...(input.manualReplay === undefined
+                            ? {}
+                            : { manualReplay: input.manualReplay }),
+                        ...(input.signal === undefined ? {} : { signal: input.signal }),
+                        progress: replayProgress.onEvent
                     });
+                    await replayProgress.settled();
                     replayed = true;
-                    await this.revalidate(input, config, context, project, session);
+                    this.revalidate(input, config, context, project, session);
                     this.assertEligible(result, journey, expected);
                     verificationReport = TapHoundReportSchema.parse(result.report);
                     session = await this.persistPassedVerification(session, verificationReport, expected);
@@ -189,7 +206,12 @@ export class GenerationFinalizer {
                     if (session.verification.status === "running"
                         && !(error instanceof GenerationFinalizationError
                             && error.code === "FINALIZATION_IN_PROGRESS")) {
-                        await this.persistFailedVerification(session, error);
+                        const aborted = error instanceof GenerationFinalizationError
+                            && error.stage === "precondition"
+                            && await this.tryAbortVerification(session);
+                        if (!aborted) {
+                            await this.persistFailedVerification(session, error);
+                        }
                     }
                     throw error instanceof GenerationFinalizationError
                         ? error
@@ -203,7 +225,9 @@ export class GenerationFinalizer {
             const expected = this.expectedVerification(session, journey, config, canonicalProjectRoot, input.toolVersions);
             let reconciled;
             try {
-                reconciled = await this.reconcilePassedVerification(session, expected, () => this.revalidate(input, config, context, project, session));
+                reconciled = await this.reconcilePassedVerification(session, expected, () => {
+                    this.revalidate(input, config, context, project, session);
+                });
             }
             catch (error) {
                 await this.persistFailedVerification(session, error);
@@ -228,7 +252,7 @@ export class GenerationFinalizer {
         }
         this.assertReport(verificationReport, journey, this.expectedVerification(session, journey, config, canonicalProjectRoot, input.toolVersions), "RECOVERY_REQUIRED");
         this.assertBindings(session, input, config, context, project);
-        const meta = this.buildMeta(session, outputPath, verificationReport);
+        const meta = this.buildMeta(session, outputPath, verificationReport, config);
         const generationReport = GenerationReportSchema.parse({
             version: 1,
             generationId: session.id,
@@ -239,6 +263,7 @@ export class GenerationFinalizer {
             }))
         });
         if (session.publication.status === "notRun") {
+            this.dependencies.progress?.("publication");
             try {
                 await this.dependencies.publisher.stage({
                     generationId: session.id,
@@ -287,6 +312,7 @@ export class GenerationFinalizer {
             }
         }
         try {
+            this.dependencies.progress?.("export");
             const exported = await this.dependencies.publisher.export({
                 generationId: session.id,
                 projectRoot: input.projectRoot,
@@ -308,44 +334,75 @@ export class GenerationFinalizer {
             throw failure("EXPORT_FAILED", "export", "Authoritative bundle was published but Journey export failed", true, error);
         }
     };
+    bridgeReplayProgress(generationId, attemptId) {
+        let pending = Promise.resolve();
+        const onEvent = (event) => {
+            const phase = event;
+            pending = pending
+                .then(async () => {
+                await this.dependencies.store.updateVerificationPhase(generationId, attemptId, phase);
+                this.dependencies.replayProgress?.(phase);
+            })
+                .catch(() => undefined);
+        };
+        return {
+            onEvent,
+            settled: () => pending
+        };
+    }
     assertBindings(session, input, config, context, project) {
-        if (input.projectRoot !== project.projectRoot
-            || input.deviceSerial !== session.target.deviceSerial
-            || project.packageName !== session.target.packageName
-            || session.target.packageName !== config.run.packageName
-            || normalizeActivity(project.packageName, project.launchActivity) !== normalizeActivity(config.run.packageName, config.run.activity)
-            || session.inFlight !== null
-            || session.pendingConfirmation !== null
-            || session.state !== "active"
-            || session.bindings.projectHash !== hashGenerationBinding(project)
-            || session.bindings.configHash !== hashGenerationBinding(config)
-            || session.bindings.contextHash !== hashGenerationBinding(context)
-            || JSON.stringify(session.target.interactionPolicy)
-                !== JSON.stringify(context.interactionPolicy)) {
-            throw failure("CONTEXT_STALE", "precondition", "Generation identity, context, configuration, or process-only binding changed");
+        const hashSummary = (value) => value.slice(0, 8);
+        const mismatches = [];
+        const compare = (binding, expected, actual) => {
+            if (expected !== actual) {
+                mismatches.push({ binding, expected, actual });
+            }
+        };
+        compare("projectRoot", input.projectRoot, project.projectRoot);
+        compare("deviceSerial", session.target.deviceSerial, input.deviceSerial);
+        compare("project.packageName", session.target.packageName, project.packageName);
+        compare("config.packageName", session.target.packageName, config.run.packageName);
+        compare("launchActivity", normalizeActivity(config.run.packageName, config.run.activity), normalizeActivity(project.packageName, project.launchActivity));
+        compare("inFlight", "none", session.inFlight === null ? "none" : "present");
+        compare("pendingConfirmation", "none", session.pendingConfirmation === null ? "none" : "present");
+        compare("session.state", "active", session.state);
+        compare("projectHash", hashSummary(session.bindings.projectHash), hashSummary(hashGenerationBinding(project)));
+        compare("configHash", hashSummary(session.bindings.configHash), hashSummary(hashGenerationBinding(config)));
+        compare("contextHash", hashSummary(session.bindings.contextHash), hashSummary(hashGenerationBinding(context)));
+        compare("contextSelection", hashSummary(hashGenerationBinding(session.contextSelection)), hashSummary(hashGenerationBinding(context.selection)));
+        compare("interactionPolicy", hashSummary(hashGenerationBinding(session.target.interactionPolicy)), hashSummary(hashGenerationBinding(context.interactionPolicy)));
+        if (mismatches.length > 0) {
+            const summary = mismatches.map((entry) => `${entry.binding} expected=${entry.expected} actual=${entry.actual}`).join("; ");
+            throw failure("CONTEXT_STALE", "precondition", `Generation binding changed: ${summary}`, false, undefined, { mismatches });
         }
     }
-    async revalidate(input, config, context, project, session) {
+    revalidate(input, config, context, project, session) {
+        // The session's stored context snapshot is authoritative; the CLI only
+        // warns when the live project context has drifted from it.
         this.assertBindings(session, input, config, context, project);
-        const result = await this.dependencies.contextValidator.validate({
-            context,
-            projectRoot: input.projectRoot,
-            config
-        });
-        if (result.status !== "valid") {
-            throw failure(result.status === "stale" ? "CONTEXT_STALE" : "CONTEXT_INVALID", "precondition", result.reason.message);
-        }
     }
     async beginVerification(session) {
         const attemptId = this.dependencies.generateAttemptId();
+        const owner = this.dependencies.owner === undefined
+            ? undefined
+            : {
+                pid: this.dependencies.owner.pid,
+                startedAt: this.dependencies.owner.now().toISOString()
+            };
         const expected = GenerationSessionSchema.parse({
             ...session,
             revision: session.revision + 1,
-            verification: { status: "running", attemptId }
+            verification: {
+                status: "running",
+                attemptId,
+                ...(owner === undefined
+                    ? {}
+                    : { ownerPid: owner.pid, startedAt: owner.startedAt })
+            }
         });
         try {
             return {
-                session: await this.dependencies.store.beginVerification(session.id, session.revision, attemptId),
+                session: await this.dependencies.store.beginVerification(session.id, session.revision, attemptId, owner),
                 owned: true
             };
         }
@@ -390,6 +447,11 @@ export class GenerationFinalizer {
         this.assertReport(result.report, journey, expected, "VERIFICATION_FAILED");
     }
     assertReport(report, journey, expected, code) {
+        const reportDevice = report.environment.devices[0];
+        const singleDefaultDevice = report.environment.devices.length === 1
+            && reportDevice?.role === DEFAULT_DEVICE_ROLE
+            && reportDevice.deviceSerial === expected.deviceSerial;
+        const reportUiBackend = reportDevice?.uiBackend;
         if (report.status !== "passed"
             || report.fallbackUsed
             || report.primaryFailure !== undefined
@@ -400,7 +462,8 @@ export class GenerationFinalizer {
             || report.project.root !== expected.project.root
             || report.project.packageName !== expected.project.packageName
             || report.project.launchActivity !== expected.project.launchActivity
-            || report.environment.deviceSerial !== expected.deviceSerial
+            || !singleDefaultDevice
+            || !sameJson(reportUiBackend, expected.bindings.uiBackend)
             || !sameJson(canonicalTools(report.environment.tools), expected.tools)
             || report.steps.length !== journey.steps.length) {
             throw failure(code, "verification", "Verification report does not match the exact generated replay");
@@ -410,7 +473,8 @@ export class GenerationFinalizer {
             const expectationType = candidate.expect?.type;
             const hasLocator = candidate.action === "click"
                 || candidate.action === "longClick"
-                || candidate.action === "swipe";
+                || candidate.action === "swipe"
+                || candidate.action === "bridge";
             const isScrollTo = candidate.action === "scrollTo";
             if (step === undefined
                 || step.index !== index
@@ -529,8 +593,9 @@ export class GenerationFinalizer {
                 throw new Error("Verification Report run ID does not match receipt");
             }
             this.assertReport(report, {
-                version: 1,
+                version: 2,
                 name: expected.journey.name,
+                devices: [{ role: DEFAULT_DEVICE_ROLE }],
                 steps: running.candidateSteps
             }, expected, "VERIFICATION_FAILED");
         }
@@ -539,12 +604,28 @@ export class GenerationFinalizer {
                 ? error
                 : failure("VERIFICATION_FAILED", "verification", "Immutable verification Report does not match the receipt", false, error);
         }
-        await revalidateCurrent();
+        revalidateCurrent();
         return {
             session: await this.persistPassedVerification(running, report, expected),
             report
         };
     }
+    async tryAbortVerification(running) {
+        const latest = GenerationSessionSchema.parse(await this.dependencies.store.read(running.id));
+        if (running.verification.status !== "running"
+            || latest.verification.status !== "running"
+            || latest.revision !== running.revision
+            || latest.verification.attemptId !== running.verification.attemptId) {
+            return false;
+        }
+        try {
+            await this.dependencies.store.abortVerification(latest.id, latest.revision);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     async persistFailedVerification(running, error) {
         const latest = GenerationSessionSchema.parse(await this.dependencies.store.read(running.id));
         if (running.verification.status !== "running"
@@ -603,13 +684,14 @@ export class GenerationFinalizer {
             throw failure("RECOVERY_REQUIRED", "verification", "Immutable verification report is not a clean passed replay");
         }
         this.assertReport(report, {
-            version: 1,
+            version: 2,
             name: expected.journey.name,
+            devices: [{ role: DEFAULT_DEVICE_ROLE }],
             steps: session.candidateSteps
         }, expected, "RECOVERY_REQUIRED");
         return report;
     }
-    buildMeta(session, outputPath, report) {
+    buildMeta(session, outputPath, report, config) {
         if (session.verification.status !== "passed") {
             throw failure("RECOVERY_REQUIRED", "verification", "Generation verification is not durably passed");
         }
@@ -618,17 +700,32 @@ export class GenerationFinalizer {
             status: "verified",
             generationId: session.id,
             journeyPath: outputPath,
+            journeySha256: report.journey.sha256,
             bindings: {
                 projectHash: session.bindings.projectHash,
                 configHash: session.bindings.configHash,
-                contextHash: session.bindings.contextHash
+                contextHash: session.bindings.contextHash,
+                uiBackend: session.bindings.uiBackend
+            },
+            replayPolicy: {
+                generatedReplayPolicy: true,
+                requireFocusedInput: true,
+                idle: session.idlePolicy ?? config.idle
             },
+            contextSelection: session.contextSelection,
             verification: {
                 reportPath: GENERATION_BUNDLE_PATHS.verificationReport,
                 reportSha256: session.verification.reportSha256,
                 runId: report.runId,
                 runs: 1
             },
+            ...(session.baseFlow === undefined
+                ? {}
+                : { baseFlow: session.baseFlow }),
+            ...(session.sourceBrief === undefined
+                ? {}
+                : { sourceBrief: session.sourceBrief }),
+            externalFlows: session.externalFlows,
             manualOverrideStepIndexes: session.candidateSources.flatMap((source, index) => source === "manualOverride" ? [index] : [])
         });
     }

package/dist/application/generation/generation-publisher.js

@@ -2,7 +2,8 @@ import { createHash } from "node:crypto";
 import { extname, resolve } from "node:path";
 import { GenerationBundleManifestSchema, GenerationMetaSchema, GenerationReportSchema } from "../../domain/generation.js";
 import { JourneySchema } from "../../domain/journey.js";
-import { TapHoundReportSchema } from "../../domain/report.js";
+import { hashJourney, TapHoundReportSchema } from "../../domain/report.js";
+import { BUILD_DIR } from "../../domain/workspace.js";
 import { GenerationSessionStoreError } from "../../ports/generation-session-store.js";
 export const GENERATION_BUNDLE_PATHS = {
     candidateJourney: "candidate/journey.json",
@@ -59,7 +60,9 @@ export class GenerationPublisher {
         const meta = GenerationMetaSchema.parse(input.meta);
         if (input.generationId !== report.generationId
             || input.generationId !== meta.generationId
-            || report.steps.length !== journey.steps.length) {
+            || report.steps.length !== journey.steps.length
+            || meta.journeySha256 !== verificationReport.journey.sha256
+            || meta.journeySha256 !== hashJourney(journey)) {
             throw new Error("Generation bundle identities do not align");
         }
         const journeyBytes = serializeJson(journey);
@@ -97,12 +100,13 @@ export class GenerationPublisher {
     export = async (input) => {
         const journey = JourneySchema.parse(input.journey);
         const meta = GenerationMetaSchema.parse(input.meta);
-        const journeyPath = resolve(input.projectRoot, input.journeyPath);
+        const exportRoot = input.projectRoot;
+        const journeyPath = resolve(exportRoot, input.journeyPath);
         const metaPath = generationMetaOutputPath(journeyPath);
-        const authorityRoot = resolve(input.projectRoot, ".taphound");
+        const authorityRoot = resolve(exportRoot, BUILD_DIR);
         try {
             await this.dependencies.journeyWriter.writeProjectBound({
-                projectRoot: input.projectRoot,
+                projectRoot: exportRoot,
                 authorityRoot,
                 outputPath: journeyPath,
                 journey
@@ -110,7 +114,7 @@ export class GenerationPublisher {
             const expectedJourney = Buffer.from(serializeJson(journey));
             const actualJourney = await this.dependencies.journeyWriter
                 .readProjectBound({
-                projectRoot: input.projectRoot,
+                projectRoot: exportRoot,
                 authorityRoot,
                 outputPath: journeyPath
             });
@@ -125,14 +129,14 @@ export class GenerationPublisher {
         }
         try {
             await this.dependencies.metaWriter.writeProjectBound({
-                projectRoot: input.projectRoot,
+                projectRoot: exportRoot,
                 authorityRoot,
                 outputPath: metaPath,
                 meta
             });
             const expectedMeta = Buffer.from(serializeJson(meta));
             const actualMeta = await this.dependencies.metaWriter.readProjectBound({
-                projectRoot: input.projectRoot,
+                projectRoot: exportRoot,
                 authorityRoot,
                 outputPath: metaPath
             });

package/dist/application/generation/generation-recovery-service.d.ts

@@ -0,0 +1,35 @@
+import { type GenerationSession } from "../../domain/generation.js";
+import { type GenerationSessionStore } from "../../ports/generation-session-store.js";
+export interface GenerationRecoveryStatus {
+    generationId: string;
+    revision: number;
+    state: GenerationSession["state"];
+    candidateStepCount: number;
+    idlePolicy?: GenerationSession["idlePolicy"];
+    inFlight: GenerationSession["inFlight"];
+    pendingConfirmation: (NonNullable<GenerationSession["pendingConfirmation"]> & {
+        expired: boolean;
+    }) | null;
+    verification: GenerationSession["verification"];
+    publication: GenerationSession["publication"];
+    recovery: {
+        available: boolean;
+        kind: "step" | "verification" | null;
+        actionMayHaveExecuted: boolean;
+        attemptOutcome: "succeeded" | "failed" | "cancelled" | "unknown" | null;
+        requiredDecision: "retry" | null;
+        ownerAlive: boolean | null;
+    };
+}
+export interface GenerationRecoveryDependencies {
+    store: Pick<GenerationSessionStore, "read" | "readEvidence" | "recover" | "recoverVerification">;
+    ownerAlive?: ((pid: number) => boolean) | undefined;
+    now: () => Date;
+}
+export declare class GenerationRecoveryService {
+    private readonly dependencies;
+    constructor(dependencies: GenerationRecoveryDependencies);
+    readonly status: (generationId: string) => Promise<GenerationRecoveryStatus>;
+    readonly retry: (generationId: string) => Promise<GenerationSession>;
+    private evidenceExists;
+}