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

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

@@ -0,0 +1,144 @@
+import { z } from "zod";
+import { GenerationSessionSchema, isGenerationConfirmationExpired } from "../../domain/generation.js";
+import { GenerationSessionStoreError } from "../../ports/generation-session-store.js";
+import { GenerationOperationError } from "./generation-starter.js";
+const AttemptOutcomeSchema = z.looseObject({
+    status: z.enum(["succeeded", "failed", "cancelled"])
+});
+function resultPath(session) {
+    const inFlight = session.inFlight;
+    return inFlight === null
+        ? undefined
+        : `evidence/steps/${String(inFlight.stepIndex)}-${inFlight.attemptId}/result.json`;
+}
+export class GenerationRecoveryService {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    status = async (generationId) => {
+        const session = GenerationSessionSchema.parse(await this.dependencies.store.read(generationId));
+        const path = resultPath(session);
+        let attemptOutcome = null;
+        if (path !== undefined) {
+            try {
+                const bytes = await this.dependencies.store.readEvidence(session.id, path);
+                const parsed = z.looseObject({
+                    outcome: AttemptOutcomeSchema
+                }).parse(JSON.parse(bytes.toString("utf8")));
+                attemptOutcome = parsed.outcome.status;
+            }
+            catch (error) {
+                if (error instanceof GenerationSessionStoreError
+                    && error.code === "EVIDENCE_NOT_FOUND") {
+                    attemptOutcome = "unknown";
+                }
+                else if (error instanceof SyntaxError || error instanceof z.ZodError) {
+                    attemptOutcome = "unknown";
+                }
+                else {
+                    throw error;
+                }
+            }
+        }
+        const stepAvailable = session.state === "recoveryRequired"
+            && session.inFlight !== null
+            && session.verification.status === "notRun"
+            && session.publication.status === "notRun";
+        const verificationMayRecover = session.state === "active"
+            && session.inFlight === null
+            && session.verification.status === "running"
+            && session.publication.status === "notRun";
+        const [hasReceipt, hasReport] = verificationMayRecover
+            ? await Promise.all([
+                this.evidenceExists(session.id, "verification/receipt.json"),
+                this.evidenceExists(session.id, "verification/report.json")
+            ])
+            : [false, false];
+        const verificationOwnerAlive = session.verification.status === "running"
+            && session.verification.ownerPid !== undefined
+            ? (this.dependencies.ownerAlive?.(session.verification.ownerPid) ?? null)
+            : null;
+        const verificationAvailable = verificationMayRecover
+            && verificationOwnerAlive !== true
+            && !hasReceipt
+            && !hasReport;
+        const available = stepAvailable || verificationAvailable;
+        return {
+            generationId: session.id,
+            revision: session.revision,
+            state: session.state,
+            candidateStepCount: session.candidateSteps.length,
+            ...(session.idlePolicy === undefined
+                ? {}
+                : { idlePolicy: session.idlePolicy }),
+            inFlight: session.inFlight,
+            pendingConfirmation: session.pendingConfirmation === null
+                ? null
+                : {
+                    ...session.pendingConfirmation,
+                    expired: isGenerationConfirmationExpired(session.pendingConfirmation, this.dependencies.now())
+                },
+            verification: session.verification,
+            publication: session.publication,
+            recovery: {
+                available,
+                kind: stepAvailable
+                    ? "step"
+                    : verificationAvailable ? "verification" : null,
+                actionMayHaveExecuted: session.inFlight !== null
+                    || session.verification.status === "running",
+                attemptOutcome,
+                requiredDecision: available ? "retry" : null,
+                ownerAlive: verificationOwnerAlive
+            }
+        };
+    };
+    retry = async (generationId) => {
+        const session = GenerationSessionSchema.parse(await this.dependencies.store.read(generationId));
+        if (session.state === "recoveryRequired"
+            && session.inFlight !== null
+            && session.verification.status === "notRun"
+            && session.publication.status === "notRun") {
+            const next = GenerationSessionSchema.parse({
+                ...session,
+                revision: session.revision + 1,
+                state: "active",
+                inFlight: null
+            });
+            await this.dependencies.store.recover(session.id, session.revision, next);
+            return next;
+        }
+        if (session.state === "active"
+            && session.inFlight === null
+            && session.verification.status === "running"
+            && session.publication.status === "notRun"
+            && (session.verification.ownerPid === undefined
+                || this.dependencies.ownerAlive?.(session.verification.ownerPid)
+                    !== true)
+            && !await this.evidenceExists(session.id, "verification/receipt.json")
+            && !await this.evidenceExists(session.id, "verification/report.json")) {
+            const next = GenerationSessionSchema.parse({
+                ...session,
+                revision: session.revision + 1,
+                verification: { status: "notRun" }
+            });
+            await this.dependencies.store.recoverVerification(session.id, session.revision, next);
+            return next;
+        }
+        throw new GenerationOperationError("RECOVERY_REQUIRED", "Session recovery is unavailable or immutable verification evidence already exists");
+    };
+    async evidenceExists(generationId, path) {
+        try {
+            await this.dependencies.store.readEvidence(generationId, path);
+            return true;
+        }
+        catch (error) {
+            if (error instanceof GenerationSessionStoreError
+                && error.code === "EVIDENCE_NOT_FOUND") {
+                return false;
+            }
+            throw error;
+        }
+    }
+}

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

@@ -0,0 +1,15 @@
+import { type GenerationSession } from "../../domain/generation.js";
+import type { GenerationSessionStore } from "../../ports/generation-session-store.js";
+export interface GenerationReopenInput {
+    generationId: string;
+    reason: string;
+}
+export interface GenerationReopenDependencies {
+    store: Pick<GenerationSessionStore, "read" | "reopenVerification">;
+    now: () => Date;
+}
+export declare class GenerationReopenService {
+    private readonly dependencies;
+    constructor(dependencies: GenerationReopenDependencies);
+    readonly reopen: (input: GenerationReopenInput) => Promise<GenerationSession>;
+}

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

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { GenerationSessionSchema } from "../../domain/generation.js";
+import { GenerationOperationError } from "./generation-starter.js";
+const ReopenReasonSchema = z.string().trim().min(1).max(500);
+export class GenerationReopenService {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    reopen = async (input) => {
+        const reason = ReopenReasonSchema.parse(input.reason);
+        const current = GenerationSessionSchema.parse(await this.dependencies.store.read(input.generationId));
+        if (current.state !== "active"
+            || current.inFlight !== null
+            || current.pendingConfirmation !== null
+            || current.verification.status !== "failed"
+            || current.publication.status !== "notRun") {
+            throw new GenerationOperationError("CONFIG_INVALID", "Only an idle active session with failed verification and no publication can be reopened");
+        }
+        const next = GenerationSessionSchema.parse({
+            ...current,
+            revision: current.revision + 1,
+            verification: { status: "notRun" },
+            verificationHistory: [
+                ...current.verificationHistory,
+                {
+                    failedRevision: current.revision,
+                    reopenedAt: this.dependencies.now().toISOString(),
+                    reason,
+                    failure: current.verification.failure
+                }
+            ]
+        });
+        await this.dependencies.store.reopenVerification(current.id, current.revision, next);
+        return next;
+    };
+}

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

@@ -0,0 +1,32 @@
+import type { TapHoundConfig } from "../../domain/config.js";
+import type { GenerationSessionStore } from "../../ports/generation-session-store.js";
+import type { RuntimeObservation, RuntimeObserver } from "./runtime-observer.js";
+import type { VerifyRuntime } from "../runtime/verify-runtime.js";
+import type { GenerationAppPreparer } from "./generation-app-preparer.js";
+export interface GenerationReplaceInput {
+    generationId: string;
+    stepIndex: number;
+    projectRoot: string;
+    config: TapHoundConfig;
+    toolVersions: Record<string, string>;
+    manualReplay?: boolean | undefined;
+    signal?: AbortSignal | undefined;
+}
+export interface GenerationReplaceResult {
+    status: "replaced";
+    stepIndex: number;
+    remainingStepCount: number;
+    truncatedStepCount: number;
+    observation: RuntimeObservation;
+}
+export interface GenerationReplaceDependencies {
+    store: Pick<GenerationSessionStore, "read" | "update">;
+    observer: Pick<RuntimeObserver, "observe">;
+    verifyRuntime: Pick<VerifyRuntime, "verify">;
+    appPreparer: Pick<GenerationAppPreparer, "prepare">;
+}
+export declare class GenerationReplaceService {
+    private readonly dependencies;
+    constructor(dependencies: GenerationReplaceDependencies);
+    readonly replace: (input: GenerationReplaceInput) => Promise<GenerationReplaceResult>;
+}

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

@@ -0,0 +1,116 @@
+import { realpath } from "node:fs/promises";
+import { GenerationSessionSchema } from "../../domain/generation.js";
+import { DEFAULT_DEVICE_ROLE, JourneySchema } from "../../domain/journey.js";
+import { GenerationOperationError } from "./generation-starter.js";
+function assertReplaceable(session) {
+    if (session.state === "recoveryRequired") {
+        throw new GenerationOperationError("RECOVERY_REQUIRED", "Generation session must be recovered before replacing steps");
+    }
+    if (session.state !== "active") {
+        throw new GenerationOperationError("CONFIG_INVALID", `Generation steps can only be replaced on an active session (state: ${session.state})`);
+    }
+    if (session.inFlight !== null) {
+        throw new GenerationOperationError("RECOVERY_REQUIRED", "Generation steps cannot be replaced while a step is in flight");
+    }
+    if (session.pendingConfirmation !== null) {
+        throw new GenerationOperationError("RISK_CONFIRMATION_REQUIRED", `Generation confirmation ${session.pendingConfirmation.challengeId} must be resolved before replacing steps`);
+    }
+    if (session.verification.status !== "notRun") {
+        throw new GenerationOperationError("CONFIG_INVALID", "Generation steps cannot be replaced once verification has started");
+    }
+    if (session.publication.status !== "notRun") {
+        throw new GenerationOperationError("CONFIG_INVALID", "Generation steps cannot be replaced after publication");
+    }
+}
+function assertReplaceIndex(session, stepIndex) {
+    if (!Number.isInteger(stepIndex)
+        || stepIndex < 0
+        || stepIndex > session.candidateSteps.length) {
+        throw new GenerationOperationError("CONFIG_INVALID", `Replace step index must be between 0 and the candidate step count (${String(session.candidateSteps.length)})`);
+    }
+    const flowStepCount = session.candidateSources.filter((source) => source === "flow").length;
+    if (stepIndex < flowStepCount) {
+        throw new GenerationOperationError("FLOW_INVALID", "Replace step index cannot target the bound Base Flow prefix; start a new session with a different Flow");
+    }
+}
+export class GenerationReplaceService {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    replace = async (input) => {
+        const session = GenerationSessionSchema.parse(await this.dependencies.store.read(input.generationId));
+        assertReplaceable(session);
+        assertReplaceIndex(session, input.stepIndex);
+        const replayConfig = session.idlePolicy === undefined
+            ? input.config
+            : { ...input.config, idle: session.idlePolicy };
+        const prefixSteps = session.candidateSteps.slice(0, input.stepIndex);
+        if (prefixSteps.length === 0) {
+            try {
+                await this.dependencies.appPreparer.prepare({
+                    config: replayConfig,
+                    deviceSerial: session.target.deviceSerial,
+                    ...(input.signal === undefined ? {} : { signal: input.signal })
+                });
+            }
+            catch (error) {
+                throw new GenerationOperationError("APP_LAUNCH_FAILED", error instanceof Error ? error.message : String(error));
+            }
+        }
+        else {
+            const canonicalProjectRoot = await realpath(input.projectRoot);
+            const journey = JourneySchema.parse({
+                version: 2,
+                name: `generation-${session.id}-prefix-${String(input.stepIndex)}`,
+                devices: [{ role: DEFAULT_DEVICE_ROLE }],
+                steps: prefixSteps
+            });
+            const result = await this.dependencies.verifyRuntime.verify({
+                config: replayConfig,
+                journey,
+                projectRoot: canonicalProjectRoot,
+                devices: [{
+                        role: DEFAULT_DEVICE_ROLE,
+                        deviceSerial: session.target.deviceSerial
+                    }],
+                toolVersions: input.toolVersions,
+                requireFocusedInput: true,
+                generatedReplayPolicy: true,
+                ...(input.manualReplay === undefined
+                    ? {}
+                    : { manualReplay: input.manualReplay }),
+                ...(input.signal === undefined ? {} : { signal: input.signal })
+            });
+            if (result.status !== "passed" || result.exitCode !== 0) {
+                const failure = result.report.primaryFailure;
+                throw new GenerationOperationError("VERIFICATION_FAILED", `Prefix replay failed before step replacement${failure === undefined
+                    ? ""
+                    : ` (${failure.stepIndex === undefined
+                        ? ""
+                        : `step ${String(failure.stepIndex)}: `}${failure.code} - ${failure.message})`}; see ${result.reportPath}`);
+            }
+        }
+        if (input.stepIndex < session.candidateSteps.length) {
+            const truncated = GenerationSessionSchema.parse({
+                ...session,
+                revision: session.revision + 1,
+                candidateSteps: prefixSteps,
+                candidateSources: session.candidateSources.slice(0, input.stepIndex)
+            });
+            await this.dependencies.store.update(session.id, session.revision, truncated);
+        }
+        const observation = await this.dependencies.observer.observe({
+            generationId: session.id,
+            idle: input.config.idle,
+            ...(input.signal === undefined ? {} : { signal: input.signal })
+        });
+        return {
+            status: "replaced",
+            stepIndex: input.stepIndex,
+            remainingStepCount: prefixSteps.length,
+            truncatedStepCount: session.candidateSteps.length - input.stepIndex,
+            observation
+        };
+    };
+}

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

@@ -1,29 +1,69 @@
 import type { ContextValidator } from "../context/context-validator.js";
 import type { ProjectDescription } from "../project/project-describer.js";
 import { type GenerationErrorCode, type GenerationSession } from "../../domain/generation.js";
-import { type ProjectContext } from "../../domain/project-context.js";
+import { type ResolvedProjectContext } from "../../domain/project-context.js";
 import { type TapHoundConfig } from "../../domain/config.js";
 import type { GenerationSessionStore } from "../../ports/generation-session-store.js";
+import { type Journey } from "../../domain/journey.js";
+import { type TapHoundReport } from "../../domain/report.js";
+import type { GenerationAppPreparer } from "./generation-app-preparer.js";
+import type { UiSnapshotProviderFactory } from "../../ports/ui-snapshot.js";
+export interface GenerationRecoveryDetails {
+    diagnostics: readonly {
+        code: string;
+        message: string;
+    }[];
+    recovery: readonly string[];
+}
 export declare class GenerationOperationError extends Error {
     readonly code: GenerationErrorCode;
+    readonly details?: unknown | undefined;
     readonly name = "GenerationOperationError";
-    constructor(code: GenerationErrorCode, message: string);
+    constructor(code: GenerationErrorCode, message: string, details?: unknown | undefined);
+}
+export interface GenerationExternalFlowInput {
+    name: string;
+    flowSha256: string;
+    escapedPackageName: string;
+    stepCount: number;
 }
 export interface GenerationStartInput {
     projectRoot: string;
     config: TapHoundConfig;
-    context: ProjectContext;
+    context: ResolvedProjectContext;
     project: ProjectDescription;
     deviceSerial: string;
+    signal?: AbortSignal | undefined;
+    allowEvidenceDrift?: boolean | undefined;
+    baseFlow?: {
+        name: string;
+        resolutionSha256: string;
+        journey: Journey;
+        verificationReport: TapHoundReport;
+        verificationReportPath: string;
+    } | undefined;
+    externalFlows?: readonly GenerationExternalFlowInput[] | undefined;
+    sourceBrief?: {
+        path: string;
+        sha256: string;
+    } | undefined;
 }
 export interface GenerationStarterDependencies {
     contextValidator: Pick<ContextValidator, "validate">;
-    store: Pick<GenerationSessionStore, "create">;
+    appPreparer: Pick<GenerationAppPreparer, "prepare">;
+    uiSnapshots: UiSnapshotProviderFactory;
+    store: Pick<GenerationSessionStore, "create" | "writeEvidence">;
     now: () => Date;
     generateId: () => string;
     randomBytes: (size: number) => Uint8Array;
 }
 export declare function hashGenerationBinding(value: unknown): string;
+export declare function flowReplayFailureDetails(input: {
+    flowName: string;
+    reportPath: string;
+    journey: Journey;
+    report: TapHoundReport;
+}): unknown;
 export declare class GenerationStarter {
     private readonly dependencies;
     constructor(dependencies: GenerationStarterDependencies);

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

@@ -1,13 +1,22 @@
 import { createHash } from "node:crypto";
-import { GenerationSessionSchema } from "../../domain/generation.js";
-import { ProjectContextSchema } from "../../domain/project-context.js";
+import { GenerationSessionSchema, GenerationExternalFlowBindingSchema, GenerationSourceBriefSchema } from "../../domain/generation.js";
+import { ResolvedProjectContextSchema } from "../../domain/project-context.js";
 import { TapHoundConfigSchema } from "../../domain/config.js";
+import { JourneySchema } from "../../domain/journey.js";
+import { normalizeActivity } from "../../domain/activity.js";
+import { GENERATION_CONTEXT_SNAPSHOT_PATH } from "../../domain/workspace.js";
+import { FlowNameSchema } from "../../domain/journey-composition.js";
+import { TapHoundReportSchema, hashJourney } from "../../domain/report.js";
+import { isRuntimeCapabilityError } from "../../ports/runtime-capability.js";
+import { closeUiSnapshotProvider } from "../ui/ui-snapshot-lifecycle.js";
 export class GenerationOperationError extends Error {
     code;
+    details;
     name = "GenerationOperationError";
-    constructor(code, message) {
+    constructor(code, message, details) {
         super(message);
         this.code = code;
+        this.details = details;
     }
 }
 function canonicalize(value) {
@@ -30,6 +39,57 @@ export function hashGenerationBinding(value) {
 function randomHex(bytes) {
     return Buffer.from(bytes).toString("hex");
 }
+function failedFlowStepSummary(step, stepIndex) {
+    if (step === undefined || stepIndex === undefined) {
+        return null;
+    }
+    return {
+        stepIndex,
+        action: step.action,
+        activity: step.activity,
+        ...("locator" in step ? { locator: step.locator } : {}),
+        ...(step.expect === undefined ? {} : { expectation: step.expect })
+    };
+}
+export function flowReplayFailureDetails(input) {
+    const primaryFailure = input.report.primaryFailure;
+    const stepIndex = primaryFailure?.stepIndex;
+    const relatedStepIndex = stepIndex
+        ?? (primaryFailure?.phase === "readiness" ? 0 : undefined);
+    const stepReport = relatedStepIndex === undefined
+        ? undefined
+        : input.report.steps[relatedStepIndex];
+    return {
+        flowName: input.flowName,
+        reportPath: input.reportPath,
+        primaryFailure: primaryFailure === undefined
+            ? null
+            : {
+                code: primaryFailure.code,
+                phase: primaryFailure.phase,
+                stepIndex: stepIndex ?? null,
+                message: primaryFailure.message
+            },
+        failedStep: failedFlowStepSummary(relatedStepIndex === undefined
+            ? undefined
+            : input.journey.steps[relatedStepIndex], relatedStepIndex),
+        // The device state at the moment of failure, so an environment blocker
+        // (lock screen, permission dialog) is distinguishable from a genuine
+        // regression without re-dumping the UI hierarchy.
+        actualActivity: stepReport?.activity === undefined
+            ? null
+            : {
+                before: stepReport.activity.before.actual ?? null,
+                after: stepReport.activity.after.actual ?? null
+            },
+        recovery: [
+            "Check that the first Flow step starts from a stable Activity deterministically reached after cold launch.",
+            "Replace a transient Splash transition with a Home readiness anchor such as wait: Home -> Home plus an expectation for a unique Home element.",
+            "Repair or re-record the Flow, then retry generation start.",
+            "Omit --base-flow only when the user explicitly chooses to bypass reuse."
+        ]
+    };
+}
 function distinctId(generationId, generateId) {
     for (let attempt = 0; attempt < 32; attempt += 1) {
         const candidate = generateId();
@@ -57,14 +117,114 @@ export class GenerationStarter {
             projectRoot: input.projectRoot,
             config
         });
-        if (validation.status !== "valid") {
+        if (validation.status !== "valid"
+            && !(validation.status === "stale" && input.allowEvidenceDrift === true)) {
             throw new GenerationOperationError(validation.status === "stale" ? "CONTEXT_STALE" : "CONTEXT_INVALID", validation.reason.message);
         }
-        const context = ProjectContextSchema.parse(input.context);
+        const context = ResolvedProjectContextSchema.parse(input.context);
         if (context.packageName !== input.project.packageName
             || context.launchActivity !== input.project.launchActivity) {
             throw new GenerationOperationError("CONTEXT_INVALID", "Context package and launch identity do not match the project");
         }
+        const baseFlow = input.baseFlow === undefined
+            ? undefined
+            : (() => {
+                const journey = JourneySchema.parse(input.baseFlow.journey);
+                const report = TapHoundReportSchema.parse(input.baseFlow.verificationReport);
+                const journeySha256 = hashJourney(journey);
+                if (report.status !== "passed"
+                    || report.primaryFailure !== undefined
+                    || report.secondaryErrors.length !== 0
+                    || report.fallbackUsed
+                    || Object.values(report.layers).some((status) => status !== "passed")
+                    || report.journey.name !== journey.name
+                    || report.journey.sha256 !== journeySha256
+                    || report.steps.length !== journey.steps.length
+                    || report.project.root !== input.projectRoot
+                    || report.project.packageName !== config.run.packageName
+                    || report.project.launchActivity !== normalizeActivity(config.run.packageName, config.run.activity)
+                    || report.environment.devices.length !== 1
+                    || report.environment.devices[0]?.deviceSerial !== input.deviceSerial
+                    || journey.steps.some((step, index) => {
+                        const result = report.steps[index];
+                        const expectationType = step.expect?.type;
+                        const requiresLocator = step.action === "click"
+                            || step.action === "longClick"
+                            || step.action === "swipe";
+                        return result === undefined
+                            || result.index !== index
+                            || result.action !== step.action
+                            || result.status !== "passed"
+                            || result.activity?.before.status !== "passed"
+                            || result.activity.before.expected !== step.activity.before
+                            || result.activity.before.actual !== step.activity.before
+                            || result.activity.after.status !== "passed"
+                            || result.activity.after.expected !== step.activity.after
+                            || result.activity.after.actual !== step.activity.after
+                            || (expectationType === undefined
+                                ? result.expectation !== undefined
+                                : (result.expectation?.type !== expectationType
+                                    || result.expectation.status !== "passed"))
+                            || (requiresLocator
+                                ? (result.locator?.status !== "found"
+                                    || result.locator.fallbackUsed)
+                                : result.locator !== undefined)
+                            || result.locator?.fallbackUsed === true;
+                    })) {
+                    throw new GenerationOperationError("FLOW_REPLAY_FAILED", "Base Flow requires a clean exact replay before generation", flowReplayFailureDetails({
+                        flowName: input.baseFlow.name,
+                        reportPath: input.baseFlow.verificationReportPath,
+                        journey,
+                        report
+                    }));
+                }
+                return {
+                    journey,
+                    binding: {
+                        name: FlowNameSchema.parse(input.baseFlow.name),
+                        resolutionSha256: input.baseFlow.resolutionSha256,
+                        journeySha256,
+                        verificationReportSha256: hashGenerationBinding(report),
+                        verificationRunId: report.runId,
+                        stepCount: journey.steps.length
+                    }
+                };
+            })();
+        if (baseFlow === undefined) {
+            try {
+                await this.dependencies.appPreparer.prepare({
+                    config,
+                    deviceSerial: input.deviceSerial,
+                    ...(input.signal === undefined ? {} : { signal: input.signal })
+                });
+            }
+            catch (error) {
+                if (isRuntimeCapabilityError(error)) {
+                    throw error;
+                }
+                throw new GenerationOperationError("APP_LAUNCH_FAILED", error instanceof Error ? error.message : String(error));
+            }
+        }
+        const externalFlowBindings = input.externalFlows === undefined
+            ? []
+            : input.externalFlows.map((entry) => GenerationExternalFlowBindingSchema.parse({
+                name: FlowNameSchema.parse(entry.name),
+                flowSha256: entry.flowSha256,
+                escapedPackageName: entry.escapedPackageName,
+                stepCount: entry.stepCount
+            }));
+        const sourceBrief = input.sourceBrief === undefined
+            ? undefined
+            : GenerationSourceBriefSchema.parse(input.sourceBrief);
+        const uiSnapshotProvider = await this.dependencies.uiSnapshots.open({
+            deviceSerial: input.deviceSerial,
+            timeoutMs: config.ui?.snapshotTimeoutMs ?? config.idle.timeoutMs,
+            backend: config.ui?.backend ?? "auto",
+            cacheEnabled: config.ui?.cacheEnabled ?? true,
+            ...(input.signal === undefined ? {} : { signal: input.signal })
+        });
+        const uiBackend = uiSnapshotProvider.descriptor;
+        await closeUiSnapshotProvider(uiSnapshotProvider);
         const generationId = this.dependencies.generateId();
         const runId = distinctId(generationId, this.dependencies.generateId);
         const session = GenerationSessionSchema.parse({
@@ -76,7 +236,8 @@ export class GenerationStarter {
                 projectHash: hashGenerationBinding(input.project),
                 configHash: hashGenerationBinding(config),
                 contextHash: hashGenerationBinding(context),
-                snapshotHash: null
+                snapshotHash: null,
+                uiBackend
             },
             target: {
                 packageName: config.run.packageName,
@@ -84,19 +245,25 @@ export class GenerationStarter {
                 resetStrategy: "processOnly",
                 interactionPolicy: context.interactionPolicy
             },
+            contextSelection: context.selection,
             variables: {
                 runId,
                 timestamp: this.dependencies.now().toISOString(),
                 randomHex: randomHex(this.dependencies.randomBytes(16))
             },
-            candidateSteps: [],
-            candidateSources: [],
+            ...(baseFlow === undefined ? {} : { baseFlow: baseFlow.binding }),
+            ...(sourceBrief === undefined ? {} : { sourceBrief }),
+            externalFlows: externalFlowBindings,
+            candidateSteps: baseFlow?.journey.steps ?? [],
+            candidateSources: baseFlow?.journey.steps.map(() => "flow") ?? [],
             inFlight: null,
             pendingConfirmation: null,
             verification: { status: "notRun" },
+            verificationHistory: [],
             publication: { status: "notRun" }
         });
         await this.dependencies.store.create(session);
+        await this.dependencies.store.writeEvidence(session.id, GENERATION_CONTEXT_SNAPSHOT_PATH, context);
         return session;
     };
 }