taphound 0.2.0-dev.1

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

@@ -0,0 +1,46 @@
+import { type GenerationBundleManifest, type GenerationMeta, type GenerationReport } from "../../domain/generation.js";
+import { type Journey } from "../../domain/journey.js";
+import { type TapHoundReport } from "../../domain/report.js";
+import type { ProjectBoundGenerationMetaWriterPort } from "../../ports/generation-meta-writer.js";
+import { type GenerationSessionStore } from "../../ports/generation-session-store.js";
+import type { ProjectBoundJourneyWriterPort } from "../../ports/journey-writer.js";
+export declare const GENERATION_BUNDLE_PATHS: {
+    readonly candidateJourney: "candidate/journey.json";
+    readonly verifiedJourney: "verified/journey.json";
+    readonly generationReport: "generation-report.json";
+    readonly verificationReport: "verification/report.json";
+    readonly verificationReceipt: "verification/receipt.json";
+    readonly meta: "meta.json";
+    readonly manifest: "manifest.json";
+};
+export declare function generationMetaOutputPath(journeyOutputPath: string): string;
+export interface GenerationBundleContent {
+    generationId: string;
+    journey: Journey;
+    report: GenerationReport;
+    verificationReport: TapHoundReport;
+    meta: GenerationMeta;
+}
+export interface GenerationPublisherDependencies {
+    store: Pick<GenerationSessionStore, "writeTextEvidence" | "readEvidence" | "listEvidence" | "publish">;
+    journeyWriter: ProjectBoundJourneyWriterPort;
+    metaWriter: ProjectBoundGenerationMetaWriterPort;
+}
+export declare class GenerationPublisher {
+    private readonly dependencies;
+    constructor(dependencies: GenerationPublisherDependencies);
+    readonly stage: (input: GenerationBundleContent) => Promise<GenerationBundleManifest>;
+    readonly publish: (generationId: string) => Promise<string>;
+    readonly export: (input: {
+        generationId: string;
+        projectRoot: string;
+        journeyPath: string;
+        journey: Journey;
+        meta: GenerationMeta;
+    }) => Promise<{
+        journeyPath: string;
+        metaPath: string;
+    }>;
+    private readonly verifyPublishedManifest;
+    private readonly verifyManifest;
+}

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

@@ -0,0 +1,178 @@
+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 { GenerationSessionStoreError } from "../../ports/generation-session-store.js";
+export const GENERATION_BUNDLE_PATHS = {
+    candidateJourney: "candidate/journey.json",
+    verifiedJourney: "verified/journey.json",
+    generationReport: "generation-report.json",
+    verificationReport: "verification/report.json",
+    verificationReceipt: "verification/receipt.json",
+    meta: "meta.json",
+    manifest: "manifest.json"
+};
+function serializeJson(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function manifestEntry(path, bytes) {
+    return {
+        path,
+        bytes: Buffer.byteLength(bytes),
+        sha256: sha256(bytes)
+    };
+}
+async function ensureEvidence(store, generationId, path, expected) {
+    try {
+        await store.writeTextEvidence(generationId, path, expected);
+    }
+    catch (error) {
+        if (!(error instanceof GenerationSessionStoreError)
+            || error.code !== "EVIDENCE_ALREADY_EXISTS") {
+            throw error;
+        }
+    }
+    const stored = await store.readEvidence(generationId, path);
+    if (!stored.equals(Buffer.from(expected))) {
+        throw new GenerationSessionStoreError("INVALID_EVIDENCE", `Immutable evidence does not match expected bytes: ${path}`);
+    }
+}
+export function generationMetaOutputPath(journeyOutputPath) {
+    const extension = extname(journeyOutputPath);
+    return extension.toLowerCase() === ".json"
+        ? `${journeyOutputPath.slice(0, -extension.length)}.meta.json`
+        : `${journeyOutputPath}.meta.json`;
+}
+export class GenerationPublisher {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    stage = async (input) => {
+        const journey = JourneySchema.parse(input.journey);
+        const report = GenerationReportSchema.parse(input.report);
+        const verificationReport = TapHoundReportSchema.parse(input.verificationReport);
+        const meta = GenerationMetaSchema.parse(input.meta);
+        if (input.generationId !== report.generationId
+            || input.generationId !== meta.generationId
+            || report.steps.length !== journey.steps.length) {
+            throw new Error("Generation bundle identities do not align");
+        }
+        const journeyBytes = serializeJson(journey);
+        const receiptBytes = (await this.dependencies.store.readEvidence(input.generationId, GENERATION_BUNDLE_PATHS.verificationReceipt)).toString("utf8");
+        const files = [
+            [GENERATION_BUNDLE_PATHS.candidateJourney, journeyBytes],
+            [GENERATION_BUNDLE_PATHS.verifiedJourney, journeyBytes],
+            [GENERATION_BUNDLE_PATHS.generationReport, serializeJson(report)],
+            [
+                GENERATION_BUNDLE_PATHS.verificationReport,
+                serializeJson(verificationReport)
+            ],
+            [GENERATION_BUNDLE_PATHS.verificationReceipt, receiptBytes],
+            [GENERATION_BUNDLE_PATHS.meta, serializeJson(meta)]
+        ];
+        for (const [path, bytes] of files) {
+            await ensureEvidence(this.dependencies.store, input.generationId, path, bytes);
+        }
+        const evidenceFiles = await this.dependencies.store.listEvidence(input.generationId);
+        const manifest = GenerationBundleManifestSchema.parse({
+            version: 1,
+            generationId: input.generationId,
+            files: evidenceFiles.map((file) => manifestEntry(file.path, Buffer.from(file.contentBase64, "base64")))
+        });
+        await ensureEvidence(this.dependencies.store, input.generationId, GENERATION_BUNDLE_PATHS.manifest, serializeJson(manifest));
+        await this.verifyManifest(input.generationId, manifest);
+        return manifest;
+    };
+    publish = async (generationId) => {
+        await this.verifyPublishedManifest(generationId);
+        const bundlePath = await this.dependencies.store.publish(generationId);
+        await this.verifyPublishedManifest(generationId);
+        return bundlePath;
+    };
+    export = async (input) => {
+        const journey = JourneySchema.parse(input.journey);
+        const meta = GenerationMetaSchema.parse(input.meta);
+        const journeyPath = resolve(input.projectRoot, input.journeyPath);
+        const metaPath = generationMetaOutputPath(journeyPath);
+        const authorityRoot = resolve(input.projectRoot, ".taphound");
+        try {
+            await this.dependencies.journeyWriter.writeProjectBound({
+                projectRoot: input.projectRoot,
+                authorityRoot,
+                outputPath: journeyPath,
+                journey
+            });
+            const expectedJourney = Buffer.from(serializeJson(journey));
+            const actualJourney = await this.dependencies.journeyWriter
+                .readProjectBound({
+                projectRoot: input.projectRoot,
+                authorityRoot,
+                outputPath: journeyPath
+            });
+            if (!actualJourney.equals(expectedJourney)) {
+                throw new Error("Exported Journey bytes do not match verified evidence");
+            }
+            await this.verifyPublishedManifest(input.generationId);
+        }
+        catch (error) {
+            await this.verifyPublishedManifest(input.generationId);
+            throw error;
+        }
+        try {
+            await this.dependencies.metaWriter.writeProjectBound({
+                projectRoot: input.projectRoot,
+                authorityRoot,
+                outputPath: metaPath,
+                meta
+            });
+            const expectedMeta = Buffer.from(serializeJson(meta));
+            const actualMeta = await this.dependencies.metaWriter.readProjectBound({
+                projectRoot: input.projectRoot,
+                authorityRoot,
+                outputPath: metaPath
+            });
+            if (!actualMeta.equals(expectedMeta)) {
+                throw new Error("Exported generation meta bytes do not match evidence");
+            }
+            await this.verifyPublishedManifest(input.generationId);
+        }
+        catch (error) {
+            await this.verifyPublishedManifest(input.generationId);
+            throw error;
+        }
+        return { journeyPath, metaPath };
+    };
+    verifyPublishedManifest = async (generationId) => {
+        const manifest = GenerationBundleManifestSchema.parse(JSON.parse((await this.dependencies.store.readEvidence(generationId, GENERATION_BUNDLE_PATHS.manifest)).toString("utf8")));
+        if (manifest.generationId !== generationId) {
+            throw new GenerationSessionStoreError("INVALID_EVIDENCE", "Published manifest generation id does not match");
+        }
+        await this.verifyManifest(generationId, manifest);
+    };
+    verifyManifest = async (generationId, manifest) => {
+        GenerationBundleManifestSchema.parse(manifest);
+        const evidenceFiles = await this.dependencies.store.listEvidence(generationId);
+        const manifestPaths = manifest.files.map((file) => file.path);
+        const evidencePaths = evidenceFiles.map((file) => file.path);
+        if (JSON.stringify(manifestPaths) !== JSON.stringify(evidencePaths)) {
+            throw new GenerationSessionStoreError("INVALID_EVIDENCE", "Manifest does not exactly enumerate immutable generation evidence");
+        }
+        for (const file of manifest.files) {
+            const evidence = evidenceFiles.find((candidate) => candidate.path === file.path);
+            if (evidence === undefined) {
+                throw new GenerationSessionStoreError("INVALID_EVIDENCE", `Manifest content is missing: ${file.path}`);
+            }
+            const bytes = Buffer.from(evidence.contentBase64, "base64");
+            if (bytes.byteLength !== evidence.byteLength
+                || bytes.byteLength !== file.bytes
+                || sha256(bytes) !== file.sha256) {
+                throw new GenerationSessionStoreError("INVALID_EVIDENCE", `Manifest content verification failed: ${file.path}`);
+            }
+        }
+    };
+}

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

@@ -0,0 +1,31 @@
+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 TapHoundConfig } from "../../domain/config.js";
+import type { GenerationSessionStore } from "../../ports/generation-session-store.js";
+export declare class GenerationOperationError extends Error {
+    readonly code: GenerationErrorCode;
+    readonly name = "GenerationOperationError";
+    constructor(code: GenerationErrorCode, message: string);
+}
+export interface GenerationStartInput {
+    projectRoot: string;
+    config: TapHoundConfig;
+    context: ProjectContext;
+    project: ProjectDescription;
+    deviceSerial: string;
+}
+export interface GenerationStarterDependencies {
+    contextValidator: Pick<ContextValidator, "validate">;
+    store: Pick<GenerationSessionStore, "create">;
+    now: () => Date;
+    generateId: () => string;
+    randomBytes: (size: number) => Uint8Array;
+}
+export declare function hashGenerationBinding(value: unknown): string;
+export declare class GenerationStarter {
+    private readonly dependencies;
+    constructor(dependencies: GenerationStarterDependencies);
+    readonly start: (input: GenerationStartInput) => Promise<GenerationSession>;
+}

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

@@ -0,0 +1,102 @@
+import { createHash } from "node:crypto";
+import { GenerationSessionSchema } from "../../domain/generation.js";
+import { ProjectContextSchema } from "../../domain/project-context.js";
+import { TapHoundConfigSchema } from "../../domain/config.js";
+export class GenerationOperationError extends Error {
+    code;
+    name = "GenerationOperationError";
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+function canonicalize(value) {
+    if (Array.isArray(value)) {
+        return value.map(canonicalize);
+    }
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, item]) => [key, canonicalize(item)]));
+    }
+    return value;
+}
+export function hashGenerationBinding(value) {
+    return createHash("sha256")
+        .update(JSON.stringify(canonicalize(value)))
+        .digest("hex");
+}
+function randomHex(bytes) {
+    return Buffer.from(bytes).toString("hex");
+}
+function distinctId(generationId, generateId) {
+    for (let attempt = 0; attempt < 32; attempt += 1) {
+        const candidate = generateId();
+        if (candidate !== generationId) {
+            return candidate;
+        }
+    }
+    throw new Error("Unable to generate a distinct Journey run ID");
+}
+export class GenerationStarter {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    start = async (input) => {
+        const config = TapHoundConfigSchema.parse(input.config);
+        if (input.project.projectRoot !== input.projectRoot) {
+            throw new GenerationOperationError("CONFIG_INVALID", "Project description root does not match requested project root");
+        }
+        if (input.project.packageName !== config.run.packageName) {
+            throw new GenerationOperationError("CONFIG_INVALID", "Project package does not match configured package");
+        }
+        const validation = await this.dependencies.contextValidator.validate({
+            context: input.context,
+            projectRoot: input.projectRoot,
+            config
+        });
+        if (validation.status !== "valid") {
+            throw new GenerationOperationError(validation.status === "stale" ? "CONTEXT_STALE" : "CONTEXT_INVALID", validation.reason.message);
+        }
+        const context = ProjectContextSchema.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 generationId = this.dependencies.generateId();
+        const runId = distinctId(generationId, this.dependencies.generateId);
+        const session = GenerationSessionSchema.parse({
+            version: 1,
+            id: generationId,
+            revision: 0,
+            state: "active",
+            bindings: {
+                projectHash: hashGenerationBinding(input.project),
+                configHash: hashGenerationBinding(config),
+                contextHash: hashGenerationBinding(context),
+                snapshotHash: null
+            },
+            target: {
+                packageName: config.run.packageName,
+                deviceSerial: input.deviceSerial,
+                resetStrategy: "processOnly",
+                interactionPolicy: context.interactionPolicy
+            },
+            variables: {
+                runId,
+                timestamp: this.dependencies.now().toISOString(),
+                randomHex: randomHex(this.dependencies.randomBytes(16))
+            },
+            candidateSteps: [],
+            candidateSources: [],
+            inFlight: null,
+            pendingConfirmation: null,
+            verification: { status: "notRun" },
+            publication: { status: "notRun" }
+        });
+        await this.dependencies.store.create(session);
+        return session;
+    };
+}

package/dist/application/generation/generation-step-executor.d.ts

@@ -0,0 +1,52 @@
+import { type PendingConfirmation } from "../../domain/generation.js";
+import { type JourneyStep } from "../../domain/journey.js";
+import { type ProposedStep } from "../../domain/proposed-step.js";
+import { type RuntimeSnapshot } from "../../domain/runtime-snapshot.js";
+import type { AdbPort } from "../../ports/adb.js";
+import type { AndroidCliPort } from "../../ports/android-cli.js";
+import type { Clock } from "../../ports/clock.js";
+import type { GenerationSessionStore } from "../../ports/generation-session-store.js";
+import { type IdleConfig } from "../wait/idle-waiter.js";
+import type { SnapshotReobservationGuard } from "./runtime-observer.js";
+export type GenerationCandidateSource = "planner" | "manualOverride";
+export interface GenerationStepExecutionInput {
+    generationId: string;
+    proposal: ProposedStep;
+    snapshot: RuntimeSnapshot;
+    source: GenerationCandidateSource;
+    signal?: AbortSignal | undefined;
+}
+export interface GenerationStepFailure {
+    code: string;
+    message: string;
+}
+export type GenerationStepExecutionResult = {
+    status: "succeeded";
+    step: JourneyStep;
+} | {
+    status: "failed";
+    failure: GenerationStepFailure;
+} | {
+    status: "cancelled";
+    failure: GenerationStepFailure;
+};
+export interface GenerationStepExecutorDependencies {
+    store: Pick<GenerationSessionStore, "read" | "beginStep" | "completeStep" | "update" | "writeEvidence" | "writeTextEvidence">;
+    freshnessGuard: Pick<SnapshotReobservationGuard, "assertFresh">;
+    adb: AdbPort;
+    androidCli: AndroidCliPort;
+    clock: Clock;
+    idle: IdleConfig;
+    now: () => Date;
+    generateAttemptId: () => string;
+    clearApprovedConfirmation: (generationId: string, challenge: PendingConfirmation) => Promise<void>;
+}
+export declare class GenerationStepExecutor {
+    private readonly dependencies;
+    private readonly riskEvaluator;
+    constructor(dependencies: GenerationStepExecutorDependencies);
+    readonly execute: (input: GenerationStepExecutionInput) => Promise<GenerationStepExecutionResult>;
+    private observeLive;
+    private assertForegroundIdentity;
+    private markRecovery;
+}