taphound 0.2.0-dev.1

package/dist/application/generation/generation-confirmation-service.js

@@ -0,0 +1,383 @@
+import { GenerationConfirmationEvidenceSchema, GenerationSessionIdSchema, GenerationSessionSchema, hashGenerationConfirmationEvidence } from "../../domain/generation.js";
+import { ProposedStepSchema, hashProposedStep } from "../../domain/proposed-step.js";
+import { RuntimeSnapshotSchema, hashRuntimeSnapshot } from "../../domain/runtime-snapshot.js";
+import { GenerationPromptCancelledError } from "../../ports/generation-prompt.js";
+import { GenerationOperationError } from "./generation-starter.js";
+import { ProposedStepValidator } from "./proposed-step-validator.js";
+import { RiskEvaluator } from "./risk-evaluator.js";
+function locatorSummary(step) {
+    if (step.action === "inputText"
+        || step.action === "back"
+        || step.action === "wait") {
+        return "";
+    }
+    return JSON.stringify(step.locator);
+}
+export function summarizeProposedStep(step) {
+    const before = step.activity.before;
+    if (step.action === "back") {
+        return `Back from ${before}`;
+    }
+    if (step.action === "wait") {
+        return `Wait on ${before}`;
+    }
+    if (step.action === "inputText") {
+        return `Input text on focused element in ${before}`;
+    }
+    if (step.action === "scrollTo") {
+        return `Scroll ${step.direction} in ${JSON.stringify(step.container)} to ${locatorSummary(step)} on ${before}`;
+    }
+    return `${step.action} ${locatorSummary(step)} on ${before}`;
+}
+function bindingFailure(message) {
+    return new GenerationOperationError("RISK_CONFIRMATION_REQUIRED", message);
+}
+export function confirmationEvidencePath(challengeId) {
+    return `evidence/confirmations/${GenerationSessionIdSchema.parse(challengeId)}.json`;
+}
+export class GenerationConfirmationService {
+    dependencies;
+    validator = new ProposedStepValidator();
+    riskEvaluator = new RiskEvaluator();
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+        if (!Number.isSafeInteger(dependencies.confirmationTtlMs)
+            || dependencies.confirmationTtlMs <= 0) {
+            throw new Error("Confirmation TTL must be a positive safe integer");
+        }
+    }
+    request = async (input) => {
+        const session = GenerationSessionSchema.parse(await this.dependencies.store.read(input.generationId));
+        const submittedEvidence = GenerationConfirmationEvidenceSchema.parse({
+            version: 1,
+            proposal: input.proposal,
+            snapshot: input.snapshot,
+            source: input.source ?? "planner"
+        });
+        if (session.pendingConfirmation !== null
+            && session.pendingConfirmation.status === "pending") {
+            const storedEvidence = await this.readStoredEvidence({
+                generationId: session.id,
+                challengeId: session.pendingConfirmation.challengeId
+            });
+            if (JSON.stringify(storedEvidence) !== JSON.stringify(submittedEvidence)) {
+                throw bindingFailure("Pending generation confirmation does not match submitted evidence");
+            }
+            const challenge = this.requireExactPendingChallenge(session, storedEvidence);
+            return { status: "confirmationRequired", challenge };
+        }
+        const proposal = this.validator.validate({
+            session,
+            snapshot: submittedEvidence.snapshot,
+            proposal: submittedEvidence.proposal
+        });
+        const risk = this.riskEvaluator.evaluate(proposal.action, session.target.interactionPolicy);
+        if (risk.effectiveRisk === "forbidden") {
+            throw new GenerationOperationError("ACTION_FORBIDDEN", `${proposal.action} is forbidden by the Core interaction policy`);
+        }
+        if (risk.effectiveRisk === "safe") {
+            return { status: "approved", proposal };
+        }
+        if (session.revision === Number.MAX_SAFE_INTEGER) {
+            throw bindingFailure("Generation revision cannot create a challenge");
+        }
+        const evidence = GenerationConfirmationEvidenceSchema.parse({
+            version: 1,
+            proposal,
+            snapshot: submittedEvidence.snapshot,
+            source: submittedEvidence.source
+        });
+        const challenge = {
+            challengeId: this.dependencies.generateChallengeId(),
+            stepIndex: session.candidateSteps.length,
+            proposalHash: hashProposedStep(proposal),
+            snapshotHash: proposal.binding.snapshotHash,
+            evidenceHash: hashGenerationConfirmationEvidence(evidence),
+            actionSummary: summarizeProposedStep(proposal),
+            expiresAt: new Date(this.dependencies.now().getTime()
+                + this.dependencies.confirmationTtlMs).toISOString(),
+            status: "pending"
+        };
+        const next = GenerationSessionSchema.parse({
+            ...session,
+            revision: session.revision + 1,
+            pendingConfirmation: challenge
+        });
+        await this.dependencies.store.writeEvidence(session.id, confirmationEvidencePath(challenge.challengeId), evidence);
+        await this.updateConfirmationReconciled(session.id, session.revision, next);
+        return { status: "confirmationRequired", challenge };
+    };
+    requestManual = async (input) => {
+        const proposal = await this.dependencies.prompt.buildManualProposal(input.manual, input.signal);
+        if (input.signal?.aborted === true) {
+            throw new GenerationPromptCancelledError();
+        }
+        return this.request({
+            generationId: input.generationId,
+            proposal,
+            snapshot: input.snapshot,
+            source: "manualOverride"
+        });
+    };
+    findPendingManual = async (input) => {
+        const session = GenerationSessionSchema.parse(await this.dependencies.store.read(input.generationId));
+        const pending = session.pendingConfirmation;
+        if (pending === null || pending.status !== "pending") {
+            return null;
+        }
+        const evidence = await this.readStoredEvidence({
+            generationId: session.id,
+            challengeId: pending.challengeId
+        });
+        if (evidence.source !== "manualOverride"
+            || evidence.proposal.action !== input.action) {
+            throw bindingFailure("Pending manual confirmation does not match the requested action");
+        }
+        const challenge = this.requireExactPendingChallenge(session, evidence);
+        return { status: "confirmationRequired", challenge };
+    };
+    confirmStored = async (input) => {
+        const evidence = await this.readStoredEvidence(input);
+        await this.confirm({
+            generationId: input.generationId,
+            challengeId: input.challengeId,
+            proposal: evidence.proposal,
+            snapshot: evidence.snapshot,
+            source: evidence.source,
+            signal: input.signal
+        });
+        return {
+            status: "approved",
+            proposal: evidence.proposal,
+            snapshot: evidence.snapshot,
+            source: evidence.source
+        };
+    };
+    confirm = async (input) => {
+        const session = GenerationSessionSchema.parse(await this.dependencies.store.read(input.generationId));
+        const proposal = ProposedStepSchema.parse(input.proposal);
+        const snapshot = RuntimeSnapshotSchema.parse(input.snapshot);
+        const evidence = GenerationConfirmationEvidenceSchema.parse({
+            version: 1,
+            proposal,
+            snapshot,
+            source: input.source ?? "planner"
+        });
+        const evidenceHash = hashGenerationConfirmationEvidence(evidence);
+        const challenge = session.pendingConfirmation;
+        if (challenge === null) {
+            throw bindingFailure("No pending generation confirmation exists");
+        }
+        const expectedRevision = proposal.binding.baseRevision
+            + (challenge.status === "pending" ? 1 : 2);
+        const cleanupToken = {
+            expectedRevision,
+            expectedChallenge: challenge
+        };
+        const expired = this.dependencies.now().getTime()
+            >= new Date(challenge.expiresAt).getTime();
+        const challengeMatches = challenge.challengeId === input.challengeId;
+        const proposalMatches = challenge.proposalHash
+            === hashProposedStep(proposal);
+        const evidenceMatches = challenge.evidenceHash === evidenceHash;
+        const snapshotMatches = challenge.snapshotHash
+            === hashRuntimeSnapshot(snapshot)
+            && challenge.snapshotHash === proposal.binding.snapshotHash
+            && challenge.snapshotHash === session.bindings.snapshotHash;
+        const stateMatches = session.state === "active"
+            && session.inFlight === null
+            && session.verification.status === "notRun"
+            && session.publication.status === "notRun"
+            && session.revision === expectedRevision
+            && challenge.stepIndex === session.candidateSteps.length
+            && challenge.actionSummary === summarizeProposedStep(proposal);
+        if (expired
+            || !challengeMatches
+            || !proposalMatches
+            || !evidenceMatches
+            || !snapshotMatches
+            || !stateMatches) {
+            if (challengeMatches) {
+                await this.clearExactChallenge(session.id, cleanupToken);
+            }
+            if (expired) {
+                throw bindingFailure("Generation confirmation challenge expired");
+            }
+            if (!evidenceMatches) {
+                throw bindingFailure("Generation confirmation evidence hash is not authoritative");
+            }
+            throw bindingFailure("Generation confirmation binding is no longer authoritative");
+        }
+        try {
+            const validationSession = GenerationSessionSchema.parse({
+                ...session,
+                revision: proposal.binding.baseRevision,
+                pendingConfirmation: null
+            });
+            this.validator.validate({
+                session: validationSession,
+                snapshot,
+                proposal
+            });
+        }
+        catch {
+            await this.clearExactChallenge(session.id, cleanupToken);
+            throw bindingFailure("Generation proposal or runtime state changed before confirmation");
+        }
+        if (challenge.status === "approved") {
+            return { status: "approved", proposal };
+        }
+        let confirmed;
+        try {
+            confirmed = await this.dependencies.prompt.confirm(challenge, input.signal);
+        }
+        catch (error) {
+            await this.clearExactChallenge(session.id, cleanupToken);
+            throw error;
+        }
+        if (input.signal?.aborted === true) {
+            await this.cancelPrompt(session.id, cleanupToken);
+        }
+        if (!confirmed) {
+            await this.clearExactChallenge(session.id, cleanupToken);
+            throw bindingFailure("Generation action confirmation was declined");
+        }
+        const latest = GenerationSessionSchema.parse(await this.dependencies.store.read(input.generationId));
+        if (input.signal?.aborted === true) {
+            await this.cancelPrompt(session.id, cleanupToken);
+        }
+        const stillAuthoritative = latest.revision === session.revision
+            && JSON.stringify(latest.pendingConfirmation)
+                === JSON.stringify(challenge)
+            && this.dependencies.now().getTime()
+                < new Date(challenge.expiresAt).getTime();
+        if (!stillAuthoritative) {
+            await this.clearExactChallenge(session.id, cleanupToken);
+            throw bindingFailure("Generation confirmation state changed while prompting");
+        }
+        if (latest.revision === Number.MAX_SAFE_INTEGER) {
+            await this.clearExactChallenge(session.id, cleanupToken);
+            throw bindingFailure("Generation revision cannot approve challenge");
+        }
+        if (input.signal?.aborted === true) {
+            await this.cancelPrompt(session.id, cleanupToken);
+        }
+        const approved = GenerationSessionSchema.parse({
+            ...latest,
+            revision: latest.revision + 1,
+            pendingConfirmation: {
+                ...challenge,
+                status: "approved"
+            }
+        });
+        await this.dependencies.store.updateConfirmation(latest.id, latest.revision, approved);
+        return { status: "approved", proposal };
+    };
+    clearApproved = async (input) => {
+        const session = GenerationSessionSchema.parse(await this.dependencies.store.read(input.generationId));
+        const challenge = session.pendingConfirmation;
+        if (challenge === null
+            || JSON.stringify(challenge) !== JSON.stringify(input.challenge)
+            || challenge.status !== "approved") {
+            return;
+        }
+        await this.clearExactChallenge(session.id, {
+            expectedRevision: session.revision,
+            expectedChallenge: challenge
+        });
+    };
+    async clearExactChallenge(generationId, token) {
+        const latest = GenerationSessionSchema.parse(await this.dependencies.store.read(generationId));
+        const pending = latest.pendingConfirmation;
+        if (latest.revision !== token.expectedRevision
+            || pending === null
+            || JSON.stringify(pending) !== JSON.stringify(token.expectedChallenge)) {
+            return;
+        }
+        if (latest.revision === Number.MAX_SAFE_INTEGER) {
+            throw bindingFailure("Generation revision cannot clear challenge");
+        }
+        const cleared = GenerationSessionSchema.parse({
+            ...latest,
+            revision: latest.revision + 1,
+            pendingConfirmation: null
+        });
+        await this.updateConfirmationReconciled(latest.id, latest.revision, cleared);
+    }
+    async cancelPrompt(generationId, token) {
+        await this.clearExactChallenge(generationId, token);
+        throw new GenerationPromptCancelledError();
+    }
+    requireExactPendingChallenge(session, evidence) {
+        const challenge = session.pendingConfirmation;
+        const proposal = evidence.proposal;
+        const snapshot = evidence.snapshot;
+        if (challenge === null
+            || challenge.status !== "pending"
+            || session.revision !== proposal.binding.baseRevision + 1) {
+            throw bindingFailure("Pending generation confirmation is no longer authoritative");
+        }
+        try {
+            const baseSession = GenerationSessionSchema.parse({
+                ...session,
+                revision: proposal.binding.baseRevision,
+                pendingConfirmation: null
+            });
+            this.validator.validate({
+                session: baseSession,
+                snapshot,
+                proposal
+            });
+        }
+        catch {
+            throw bindingFailure("Pending generation confirmation is no longer authoritative");
+        }
+        const risk = this.riskEvaluator.evaluate(proposal.action, session.target.interactionPolicy);
+        if (risk.effectiveRisk !== "confirmationRequired"
+            || challenge.stepIndex !== session.candidateSteps.length
+            || challenge.proposalHash !== hashProposedStep(proposal)
+            || challenge.snapshotHash !== hashRuntimeSnapshot(snapshot)
+            || challenge.snapshotHash !== proposal.binding.snapshotHash
+            || challenge.evidenceHash !== hashGenerationConfirmationEvidence(evidence)
+            || challenge.actionSummary !== summarizeProposedStep(proposal)
+            || this.dependencies.now().getTime()
+                >= new Date(challenge.expiresAt).getTime()) {
+            throw bindingFailure("Pending generation confirmation does not match stored evidence");
+        }
+        return challenge;
+    }
+    async updateConfirmationReconciled(generationId, expectedRevision, intended) {
+        try {
+            await this.dependencies.store.updateConfirmation(generationId, expectedRevision, intended);
+        }
+        catch (error) {
+            let authoritative;
+            try {
+                authoritative = GenerationSessionSchema.parse(await this.dependencies.store.read(generationId));
+            }
+            catch {
+                throw error;
+            }
+            if (JSON.stringify(authoritative) === JSON.stringify(intended)) {
+                return;
+            }
+            throw error;
+        }
+    }
+    async readStoredEvidence(input) {
+        try {
+            const parsed = JSON.parse((await this.dependencies.store.readEvidence(input.generationId, confirmationEvidencePath(input.challengeId))).toString("utf8"));
+            const evidence = GenerationConfirmationEvidenceSchema.parse(parsed);
+            if (evidence.proposal.binding.generationId !== input.generationId
+                || evidence.snapshot.generationId !== input.generationId) {
+                throw new Error("Generation confirmation evidence belongs to another session");
+            }
+            return evidence;
+        }
+        catch (error) {
+            throw bindingFailure(error instanceof Error
+                ? `Generation confirmation evidence is unavailable: ${error.message}`
+                : "Generation confirmation evidence is unavailable");
+        }
+    }
+}

package/dist/application/generation/generation-finalizer.d.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import { type GenerationErrorCode, type GenerationMeta } from "../../domain/generation.js";
+import { type Journey } from "../../domain/journey.js";
+import { type ProjectContext } from "../../domain/project-context.js";
+import { type TapHoundConfig } from "../../domain/config.js";
+import type { AdbPort } from "../../ports/adb.js";
+import { type GenerationSessionStore } from "../../ports/generation-session-store.js";
+import type { ContextValidator } from "../context/context-validator.js";
+import type { ProjectDescription } from "../project/project-describer.js";
+import type { VerifyRuntime } from "../runtime/verify-runtime.js";
+import { GenerationPublisher } from "./generation-publisher.js";
+export declare const GenerationOutputPathSchema: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+export type GenerationFinalizationStage = "precondition" | "verification" | "publication" | "export";
+export declare class GenerationFinalizationError extends Error {
+    readonly code: GenerationErrorCode;
+    readonly stage: GenerationFinalizationStage;
+    readonly recoverable: boolean;
+    readonly name = "GenerationFinalizationError";
+    constructor(code: GenerationErrorCode, stage: GenerationFinalizationStage, recoverable: boolean, message: string, options?: ErrorOptions);
+}
+export interface GenerationFinalizeInput {
+    generationId: string;
+    projectRoot: string;
+    config: TapHoundConfig;
+    context: ProjectContext;
+    project: ProjectDescription;
+    outputPath: string;
+    name?: string | undefined;
+    deviceSerial: string;
+    toolVersions: Record<string, string>;
+    signal?: AbortSignal | undefined;
+}
+export interface GenerationFinalizerDependencies {
+    store: Pick<GenerationSessionStore, "read" | "beginVerification" | "completeVerification" | "failVerification" | "markBundlePublishable" | "writeTextEvidence" | "readEvidence">;
+    contextValidator: Pick<ContextValidator, "validate">;
+    adb: Pick<AdbPort, "forceStop">;
+    verifyRuntime: Pick<VerifyRuntime, "verify">;
+    publisher: GenerationPublisher;
+    generateAttemptId: () => string;
+}
+export interface GenerationFinalizeResult {
+    status: "verified";
+    journey: Journey;
+    meta: GenerationMeta;
+    bundlePath: string;
+    journeyPath: string;
+    metaPath: string;
+    replayed: boolean;
+}
+export declare class GenerationFinalizer {
+    private readonly dependencies;
+    constructor(dependencies: GenerationFinalizerDependencies);
+    readonly finalize: (input: GenerationFinalizeInput) => Promise<GenerationFinalizeResult>;
+    private assertBindings;
+    private revalidate;
+    private beginVerification;
+    private expectedVerification;
+    private assertEligible;
+    private assertReport;
+    private receiptMatches;
+    private persistPassedVerification;
+    private reconcilePassedVerification;
+    private persistFailedVerification;
+    private readVerifiedReport;
+    private buildMeta;
+    private ensureVerificationEvidence;
+}