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

package/dist/application/context/context-rehasher.js

@@ -0,0 +1,110 @@
+import { ProjectContextModuleSchema, ProjectContextSchema } from "../../domain/project-context.js";
+import { projectRelativePath } from "../../shared/paths.js";
+import { MAX_CONTEXT_SHARD_BYTES } from "./context-loader.js";
+import { assertShardIdentity } from "./shard-identity.js";
+import { assertProjectPathUnder, CONTEXT_DIR } from "../../domain/workspace.js";
+export class ContextRehashError extends Error {
+    code;
+    name = "ContextRehashError";
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export class ContextRehasher {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    rehash = async (input) => {
+        const contextRelativePath = projectRelativePath(input.projectRoot, input.contextPath, (message) => new ContextRehashError("CONTEXT_INVALID", message));
+        try {
+            assertProjectPathUnder(input.projectRoot, contextRelativePath, CONTEXT_DIR, "Project Context output");
+        }
+        catch (error) {
+            throw new ContextRehashError("CONTEXT_INVALID", error instanceof Error ? error.message : String(error));
+        }
+        const { bundle, indexHash } = await this.dependencies.loader.readIndex({
+            projectRoot: input.projectRoot,
+            contextPath: input.contextPath
+        });
+        const requestedIds = input.moduleIds === undefined || input.moduleIds.length === 0
+            ? undefined
+            : new Set(input.moduleIds);
+        const moduleResults = [];
+        let anyChanged = false;
+        for (const reference of bundle.modules) {
+            if (requestedIds !== undefined && !requestedIds.has(reference.id)) {
+                continue;
+            }
+            const inspection = await this.dependencies.files.inspectProjectFile({
+                projectRoot: input.projectRoot,
+                relativePath: reference.contextPath,
+                maximumBytes: MAX_CONTEXT_SHARD_BYTES
+            });
+            if (inspection.status !== "inspected") {
+                throw new ContextRehashError("CONTEXT_INVALID", `Context shard cannot be read: ${reference.contextPath}`);
+            }
+            let parsedJson;
+            try {
+                parsedJson = JSON.parse(inspection.bytes?.toString("utf8") ?? "");
+            }
+            catch {
+                throw new ContextRehashError("CONTEXT_INVALID", `Context shard is not valid JSON: ${reference.contextPath}`);
+            }
+            const document = ProjectContextModuleSchema.safeParse(parsedJson);
+            if (!document.success) {
+                throw new ContextRehashError("CONTEXT_INVALID", `Context shard does not match the module schema: ${reference.contextPath}`);
+            }
+            assertShardIdentity(reference, document.data, (message) => new ContextRehashError("CONTEXT_INVALID", message));
+            const changed = inspection.sha256 !== reference.sha256;
+            if (changed) {
+                anyChanged = true;
+            }
+            moduleResults.push({
+                id: reference.id,
+                previousSha256: reference.sha256,
+                currentSha256: inspection.sha256,
+                changed
+            });
+        }
+        if (!anyChanged) {
+            return {
+                status: "unchanged",
+                modules: moduleResults,
+                previousIndexHash: indexHash,
+                indexHash
+            };
+        }
+        const nextModules = bundle.modules.map((reference) => {
+            const result = moduleResults.find((r) => r.id === reference.id);
+            return result !== undefined && result.changed
+                ? { ...reference, sha256: result.currentSha256 }
+                : reference;
+        });
+        const nextBundle = {
+            ...bundle,
+            modules: nextModules
+        };
+        const parsedBundle = ProjectContextSchema.safeParse(nextBundle);
+        if (!parsedBundle.success) {
+            throw new ContextRehashError("CONTEXT_INVALID", "Rehashed Project Context index does not match the version 2 schema");
+        }
+        const written = await this.dependencies.writer.writeContextDocument({
+            projectRoot: input.projectRoot,
+            relativePath: contextRelativePath,
+            document: parsedBundle.data
+        });
+        if (written.status !== "written") {
+            throw new ContextRehashError("CONTEXT_WRITE_FAILED", written.status === "escape"
+                ? `Context document resolves outside the project: ${contextRelativePath}`
+                : `Context document cannot be written: ${contextRelativePath}${"message" in written ? `: ${written.message}` : ""}`);
+        }
+        return {
+            status: "rehashed",
+            modules: moduleResults,
+            previousIndexHash: indexHash,
+            indexHash: written.sha256
+        };
+    };
+}

package/dist/application/context/context-validator.d.ts

@@ -1,27 +1,49 @@
 import type { TapHoundConfig } from "../../domain/config.js";
+import { type ProjectContextModule } from "../../domain/project-context.js";
 import { type ProjectFileInspector } from "../../ports/project-file-inspector.js";
+import type { ProjectInventoryInspector } from "../../ports/project-inventory-inspector.js";
 export declare const MAX_CONTEXT_EVIDENCE_BYTES: number;
 export type ContextValidationReasonCode = "CONTEXT_SCHEMA_INVALID" | "CONTEXT_IDENTITY_MISMATCH" | "PROJECT_ROOT_UNREADABLE" | "PROJECT_ROOT_NOT_DIRECTORY" | "EVIDENCE_SECRET_PATH" | "EVIDENCE_NOT_FOUND" | "EVIDENCE_UNREADABLE" | "EVIDENCE_NOT_FILE" | "EVIDENCE_PATH_ESCAPE" | "EVIDENCE_CHANGED_IDENTITY" | "EVIDENCE_TOO_LARGE" | "EVIDENCE_HASH_MISMATCH";
 export interface ContextValidationReason {
     code: ContextValidationReasonCode;
     message: string;
 }
+export interface ContextValidationScope {
+    id: string;
+    inventoryChanged: boolean;
+    missingPaths: string[];
+    changedPaths: string[];
+}
+export interface ContextIdentityDivergence {
+    evidencePackageName: string;
+    configuredPackageName: string;
+    launchActivity: string;
+}
 export type ContextValidationResult = {
     status: "valid";
+    scopes?: ContextValidationScope[] | undefined;
+    divergence?: ContextIdentityDivergence | undefined;
 } | {
     status: "stale";
     reason: ContextValidationReason;
+    scopes?: ContextValidationScope[];
 } | {
     status: "invalid";
     reason: ContextValidationReason;
+    scopes?: ContextValidationScope[];
 };
 export interface ContextValidationInput {
     context: unknown;
     projectRoot: string;
     config: TapHoundConfig;
+    modules?: ProjectContextModule[] | undefined;
+    reportScopes?: boolean | undefined;
+    identityPolicy?: "strict" | "configured" | undefined;
 }
 export declare class ContextValidator {
     private readonly files;
-    constructor(files: ProjectFileInspector);
+    private readonly inventory?;
+    constructor(files: ProjectFileInspector, inventory?: ProjectInventoryInspector | undefined);
     readonly validate: (input: ContextValidationInput) => Promise<ContextValidationResult>;
+    private readonly inspectScopes;
 }

package/dist/application/context/context-validator.js

@@ -1,5 +1,6 @@
 import { normalizeActivity } from "../../domain/activity.js";
-import { ProjectContextSchema } from "../../domain/project-context.js";
+import { evidenceMatches } from "./evidence-match.js";
+import { ResolvedProjectContextSchema } from "../../domain/project-context.js";
 export const MAX_CONTEXT_EVIDENCE_BYTES = 1024 * 1024;
 const SECRET_FILE_NAMES = new Set([
     ".git-credentials",
@@ -70,13 +71,15 @@ function invalidInspection(path, inspection) {
 }
 export class ContextValidator {
     files;
-    constructor(files) {
+    inventory;
+    constructor(files, inventory) {
         this.files = files;
+        this.inventory = inventory;
     }
     validate = async (input) => {
-        const parsed = ProjectContextSchema.safeParse(input.context);
+        const parsed = ResolvedProjectContextSchema.safeParse(input.context);
         if (!parsed.success) {
-            return invalid("CONTEXT_SCHEMA_INVALID", "Project Context does not match the version 1 schema");
+            return invalid("CONTEXT_SCHEMA_INVALID", "Resolved Project Context does not match the version 2 schema");
         }
         let configuredActivity;
         try {
@@ -85,11 +88,55 @@ export class ContextValidator {
         catch {
             return invalid("CONTEXT_IDENTITY_MISMATCH", "Project Context identity does not match the configured project");
         }
-        if (parsed.data.packageName !== input.config.run.packageName
+        let divergence;
+        if (input.identityPolicy === "configured") {
+            const evidenceActivity = parsed.data.launchActivity;
+            const activityIsRelative = input.config.run.activity.startsWith(".");
+            const suffixMatch = (activityIsRelative
+                && evidenceActivity.endsWith(input.config.run.activity));
+            if (evidenceActivity === configuredActivity
+                || suffixMatch) {
+                if (parsed.data.packageName !== input.config.run.packageName) {
+                    const evidencePackageName = suffixMatch
+                        ? evidenceActivity.slice(0, evidenceActivity.length - input.config.run.activity.length)
+                        : parsed.data.packageName;
+                    divergence = {
+                        evidencePackageName,
+                        configuredPackageName: input.config.run.packageName,
+                        launchActivity: evidenceActivity
+                    };
+                }
+            }
+            else {
+                return invalid("CONTEXT_IDENTITY_MISMATCH", `Project Context identity does not match the configured project (evidence launchActivity ${evidenceActivity}, configured ${configuredActivity}; declare the activity with: taphound local add <id> --path <path> --package <pkg> --activity <relative-or-fq>)`);
+            }
+        }
+        else if (parsed.data.packageName !== input.config.run.packageName
             || parsed.data.launchActivity !== configuredActivity) {
             return invalid("CONTEXT_IDENTITY_MISMATCH", "Project Context identity does not match the configured project");
         }
         let staleReason;
+        const inventoryCache = new Map();
+        if (this.inventory !== undefined) {
+            for (const module of parsed.data.selection.modules) {
+                const inspection = await this.inventory.inspectProjectInventory({
+                    projectRoot: input.projectRoot,
+                    projectDir: module.projectDir,
+                    categories: module.inventory.categories
+                });
+                inventoryCache.set(module.projectDir, inspection);
+                if (inspection.status !== "inspected") {
+                    return invalid("CONTEXT_SCHEMA_INVALID", `Unable to inspect module inventory: ${module.id}`);
+                }
+                if (inspection.pathSetSha256 !== module.inventory.pathSetSha256
+                    && staleReason === undefined) {
+                    staleReason = {
+                        code: "EVIDENCE_HASH_MISMATCH",
+                        message: `Module file inventory changed: ${module.id}`
+                    };
+                }
+            }
+        }
         for (const evidence of parsed.data.manifest.files) {
             if (isSecretEvidencePath(evidence.path)) {
                 return invalid("EVIDENCE_SECRET_PATH", `Secret files cannot be context evidence: ${evidence.path}`);
@@ -106,15 +153,75 @@ export class ContextValidator {
             if (inspection.status !== "inspected") {
                 return invalidInspection(evidence.path, inspection);
             }
-            if (inspection.sha256 !== evidence.sha256) {
+            const inspected = inspection;
+            if (!evidenceMatches(evidence, inspected)) {
                 staleReason ??= {
                     code: "EVIDENCE_HASH_MISMATCH",
-                    message: `Evidence file changed: ${evidence.path}`
+                    message: evidence.semanticSha256 !== undefined
+                        ? `Semantic evidence changed: ${evidence.path}`
+                        : `Evidence file changed: ${evidence.path}`
                 };
             }
         }
+        const scopes = input.reportScopes === true && input.modules !== undefined
+            ? await this.inspectScopes(input.projectRoot, input.modules, inventoryCache)
+            : undefined;
         return staleReason === undefined
-            ? { status: "valid" }
-            : { status: "stale", reason: staleReason };
+            ? {
+                status: "valid",
+                ...(scopes === undefined ? {} : { scopes }),
+                ...(divergence === undefined ? {} : { divergence })
+            }
+            : {
+                status: "stale",
+                reason: staleReason,
+                ...(scopes === undefined ? {} : { scopes })
+            };
+    };
+    inspectScopes = async (projectRoot, modules, inventoryCache) => {
+        const scopes = [];
+        for (const module of modules) {
+            const cached = inventoryCache?.get(module.projectDir);
+            const inventory = cached !== undefined
+                ? cached
+                : this.inventory === undefined
+                    ? undefined
+                    : await this.inventory.inspectProjectInventory({
+                        projectRoot,
+                        projectDir: module.projectDir,
+                        categories: module.inventory.categories
+                    });
+            const inventoryChanged = inventory !== undefined
+                && inventory.status === "inspected"
+                && inventory.pathSetSha256 !== module.inventory.pathSetSha256;
+            const missingPaths = [];
+            const changedPaths = [];
+            for (const evidence of module.manifest.files) {
+                const inspection = await this.files.inspectProjectFile({
+                    projectRoot,
+                    relativePath: evidence.path,
+                    maximumBytes: MAX_CONTEXT_EVIDENCE_BYTES
+                });
+                if (inspection.status !== "inspected") {
+                    if (inspection.status === "notFound") {
+                        missingPaths.push(evidence.path);
+                    }
+                    continue;
+                }
+                if (inspection.bytes === undefined) {
+                    continue;
+                }
+                if (!evidenceMatches(evidence, inspection)) {
+                    changedPaths.push(evidence.path);
+                }
+            }
+            scopes.push({
+                id: module.moduleId,
+                inventoryChanged,
+                missingPaths,
+                changedPaths
+            });
+        }
+        return scopes;
     };
 }

package/dist/application/context/evidence-hash.d.ts

@@ -0,0 +1 @@
+export declare function semanticSha256(value: string | Uint8Array): string;

package/dist/application/context/evidence-hash.js

@@ -0,0 +1,125 @@
+import { createHash } from "node:crypto";
+// Produces a conservative semantic hash for source and resource evidence.
+//
+// Comments and formatting whitespace are ignored, while string contents and
+// all other tokens remain significant. This intentionally prefers false
+// positives over allowing a potentially meaningful UI change to pass
+// unnoticed.
+//
+// Supported comment forms: double-slash and hash line comments, C-style and
+// XML block comments. Hash is retained because Gradle .properties provenance
+// files use it.
+//
+// String literals (single quote, double quote, backtick) preserve their
+// contents verbatim, with backslash escapes honored so a quote inside a
+// string does not close it.
+//
+// Kotlin raw strings (triple double-quote) and XML CDATA sections are
+// treated as opaque literals: their full content is preserved (including
+// internal whitespace, which is semantically significant in both) and no
+// comment or quote sequence inside them is interpreted.
+export function semanticSha256(value) {
+    const source = typeof value === "string"
+        ? value
+        : Buffer.from(value).toString("utf8");
+    let normalized = "";
+    let quote;
+    let rawString = false;
+    let cdata = false;
+    let escaped = false;
+    let lineComment = false;
+    let blockComment = false;
+    for (let index = 0; index < source.length; index += 1) {
+        const current = source.charAt(index);
+        const next = source.charAt(index + 1);
+        const after = source.charAt(index + 2);
+        if (lineComment) {
+            if (current === "\n") {
+                lineComment = false;
+            }
+            continue;
+        }
+        if (blockComment) {
+            if ((current === "*" && next === "/")
+                || (current === "-"
+                    && next === "-"
+                    && after === ">")) {
+                blockComment = false;
+                index += current === "*" ? 1 : 2;
+            }
+            continue;
+        }
+        if (cdata) {
+            if (current === "]" && next === "]" && after === ">") {
+                cdata = false;
+                index += 2;
+                continue;
+            }
+            normalized += current;
+            continue;
+        }
+        if (rawString) {
+            if (current === "\"" && next === "\"" && after === "\"") {
+                rawString = false;
+                normalized += "\"\"\"";
+                index += 2;
+                continue;
+            }
+            normalized += current;
+            continue;
+        }
+        if (quote !== undefined) {
+            normalized += current;
+            if (escaped) {
+                escaped = false;
+            }
+            else if (current === "\\") {
+                escaped = true;
+            }
+            else if (current === quote) {
+                quote = undefined;
+            }
+            continue;
+        }
+        if (current === "\"" && next === "\"" && after === "\"") {
+            rawString = true;
+            normalized += "\"\"\"";
+            index += 2;
+            continue;
+        }
+        if (current === "<"
+            && next === "!"
+            && after === "["
+            && source.startsWith("[CDATA[", index + 2)) {
+            cdata = true;
+            normalized += source.slice(index, index + 9);
+            index += 8;
+            continue;
+        }
+        if ((current === "/" && next === "/") || current === "#") {
+            lineComment = true;
+            if (current === "/") {
+                index += 1;
+            }
+            continue;
+        }
+        if ((current === "/" && next === "*")
+            || (current === "<"
+                && next === "!"
+                && after === "-"
+                && source.charAt(index + 3) === "-")) {
+            blockComment = true;
+            index += current === "/" ? 1 : 3;
+            continue;
+        }
+        if (current === "'" || current === "\"" || current === "`") {
+            quote = current;
+            normalized += current;
+            continue;
+        }
+        if (!/\s/.test(current)) {
+            normalized += current;
+        }
+    }
+    return createHash("sha256").update(normalized).digest("hex");
+}

package/dist/application/context/evidence-match.d.ts

@@ -0,0 +1,9 @@
+export interface EvidenceRecord {
+    readonly sha256: string;
+    readonly semanticSha256?: string | undefined;
+}
+export interface InspectedFile {
+    readonly sha256: string;
+    readonly bytes?: Buffer | undefined;
+}
+export declare function evidenceMatches(evidence: EvidenceRecord, inspected: InspectedFile): boolean;

package/dist/application/context/evidence-match.js

@@ -0,0 +1,8 @@
+import { semanticSha256 } from "./evidence-hash.js";
+export function evidenceMatches(evidence, inspected) {
+    if (evidence.semanticSha256 !== undefined) {
+        return inspected.bytes !== undefined
+            && semanticSha256(inspected.bytes) === evidence.semanticSha256;
+    }
+    return inspected.sha256 === evidence.sha256;
+}

package/dist/application/context/shard-identity.d.ts

@@ -0,0 +1,2 @@
+import type { ContextModuleReference, ProjectContextModule } from "../../domain/project-context.js";
+export declare function assertShardIdentity(reference: ContextModuleReference, document: ProjectContextModule, createError: (message: string) => Error): void;

package/dist/application/context/shard-identity.js

@@ -0,0 +1,7 @@
+export function assertShardIdentity(reference, document, createError) {
+    if (document.moduleId !== reference.id
+        || document.projectDir !== reference.projectDir
+        || document.status !== reference.status) {
+        throw createError(`Context shard identity does not match its index: ${reference.id}`);
+    }
+}

package/dist/application/contract/contract-loader.d.ts

@@ -0,0 +1,25 @@
+import { type AcceptanceContract } from "../../domain/contract.js";
+import type { FailureCode } from "../../domain/failure.js";
+import { type Journey } from "../../domain/journey.js";
+export declare class ContractError extends Error {
+    readonly code: FailureCode;
+    constructor(code: FailureCode, message: string);
+}
+export interface LoadedContract {
+    contract: AcceptanceContract;
+    contractSha256: string;
+    journey: Journey;
+    journeyPath: string;
+}
+export interface ContractLoaderDependencies {
+    readText: (path: string) => Promise<string>;
+}
+export declare function hashContractText(text: string): string;
+export declare class ContractLoader {
+    private readonly dependencies;
+    constructor(dependencies: ContractLoaderDependencies);
+    readonly load: (input: {
+        projectRoot: string;
+        contractPath: string;
+    }) => Promise<LoadedContract>;
+}

package/dist/application/contract/contract-loader.js

@@ -0,0 +1,68 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { AcceptanceContractSchema } from "../../domain/contract.js";
+import { JourneySchema } from "../../domain/journey.js";
+import { hashJourney } from "../../domain/report.js";
+export class ContractError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ContractError";
+    }
+}
+export function hashContractText(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+export class ContractLoader {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    load = async (input) => {
+        let contractText;
+        try {
+            contractText = await this.dependencies.readText(input.contractPath);
+        }
+        catch (error) {
+            throw new ContractError("CONTRACT_INVALID", `Cannot read Acceptance Contract at ${input.contractPath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        let contract;
+        try {
+            contract = AcceptanceContractSchema.parse(JSON.parse(contractText));
+        }
+        catch (error) {
+            throw new ContractError("CONTRACT_INVALID", `Acceptance Contract at ${input.contractPath} is invalid: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const journeyPath = join(input.projectRoot, contract.journey.path);
+        let journeyText;
+        try {
+            journeyText = await this.dependencies.readText(journeyPath);
+        }
+        catch (error) {
+            throw new ContractError("CONTRACT_JOURNEY_MISSING", `Bound Journey ${contract.journey.path} is missing: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        let journey;
+        try {
+            journey = JourneySchema.parse(JSON.parse(journeyText));
+        }
+        catch (error) {
+            throw new ContractError("CONTRACT_JOURNEY_MISSING", `Bound Journey ${contract.journey.path} is invalid: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const journeySha256 = hashJourney(journey);
+        if (journeySha256 !== contract.journey.sha256) {
+            throw new ContractError("CONTRACT_JOURNEY_DRIFT", `Bound Journey ${contract.journey.path} drifted: binding ${contract.journey.sha256}, found ${journeySha256}. Re-bind the contract to the current Journey or restore the bound content.`);
+        }
+        for (const id of contract.requiredCheckpoints) {
+            if (!journey.checkpoints?.some((checkpoint) => checkpoint.id === id)) {
+                throw new ContractError("CONTRACT_INVALID", `Required Checkpoint ${id} is not defined by the bound Journey`);
+            }
+        }
+        return {
+            contract,
+            contractSha256: hashContractText(contractText),
+            journey,
+            journeyPath
+        };
+    };
+}

package/dist/application/contract/contract-review.d.ts

@@ -0,0 +1,25 @@
+import { type ContractReviewInput, type ContractVerdictView } from "../../domain/contract.js";
+export interface ContractReviewMergeDependencies {
+    now: () => Date;
+}
+export interface ContractReviewMergeResult {
+    view: ContractVerdictView;
+    applied: boolean;
+}
+/**
+ * Applies reviewer findings on top of a deterministic Verdict view.
+ *
+ * Source-of-Truth enforcement (docs/source-of-truth.md):
+ * - a lower-trust layer (semantic / multimodal reviewer) may escalate a
+ *   successful or uncertain result into `needsReview`;
+ * - it must never rewrite a deterministic `fail` or `invalid` back to
+ *   success; those stay immutable and the review is recorded as not applied.
+ */
+export declare class ContractReviewMerger {
+    private readonly dependencies;
+    constructor(dependencies: ContractReviewMergeDependencies);
+    readonly merge: (input: {
+        view: ContractVerdictView;
+        review: ContractReviewInput;
+    }) => Promise<ContractReviewMergeResult>;
+}

package/dist/application/contract/contract-review.js

@@ -0,0 +1,51 @@
+import { ContractReviewSchema, ContractVerdictViewSchema } from "../../domain/contract.js";
+const IMMUTABLE_VERDICTS = new Set([
+    "fail",
+    "invalid"
+]);
+/**
+ * Applies reviewer findings on top of a deterministic Verdict view.
+ *
+ * Source-of-Truth enforcement (docs/source-of-truth.md):
+ * - a lower-trust layer (semantic / multimodal reviewer) may escalate a
+ *   successful or uncertain result into `needsReview`;
+ * - it must never rewrite a deterministic `fail` or `invalid` back to
+ *   success; those stay immutable and the review is recorded as not applied.
+ */
+export class ContractReviewMerger {
+    dependencies;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    merge = (input) => {
+        const { view, review } = input;
+        const immutable = IMMUTABLE_VERDICTS.has(view.verdict);
+        const applied = !immutable;
+        const previousFindings = view.review?.findings ?? [];
+        const record = ContractReviewSchema.parse({
+            version: 1,
+            source: review.source,
+            ...(review.model === undefined ? {} : { model: review.model }),
+            ...(review.promptVersion === undefined
+                ? {}
+                : { promptVersion: review.promptVersion }),
+            findings: [...previousFindings, ...review.findings],
+            appliedAt: new Date(this.dependencies.now()).toISOString(),
+            applied,
+            baseVerdict: view.verdict,
+            baseReason: view.reason
+        });
+        const merged = ContractVerdictViewSchema.parse({
+            ...view,
+            ...(applied
+                ? {
+                    verdict: "needsReview",
+                    reason: "REVIEW_FINDINGS",
+                    message: `Reviewer ${review.source} found ${String(record.findings.length)} finding(s) requiring human review`
+                }
+                : {}),
+            review: record
+        });
+        return Promise.resolve({ view: merged, applied });
+    };
+}