@nicia-ai/typegraph 0.55.0 → 0.56.0

package/dist/graph-merge/index.d.cts

@@ -1,7 +1,7 @@
-import { fV as NodeId, z as NodeType, cE as JsonValue, eV as EdgeId, d as GraphDef, fY as NodeKinds, fi as GetNodeType, aD as TypeGraphError, gs as TypeGraphErrorOptions, e as GraphBackend, fk as GraphAnnotations, cF as KindAnnotations, fO as MetaEdge, y as AnyEdgeType, bk as DeleteBehavior, T as TemporalMode, I as IndexDeclaration, ch as GraphExtensionVersion, bP as ExtensionNodeDef, bJ as ExtensionEdgeDef, bU as ExtensionOntologyRelation, bN as ExtensionIndex } from '../types-vg7PwMjm.cjs';
+import { fV as NodeId, z as NodeType, cE as JsonValue, eV as EdgeId, d as GraphDef, fY as NodeKinds, fi as GetNodeType, G as GraphIdentityConfig, aD as TypeGraphError, gs as TypeGraphErrorOptions, e as GraphBackend, fk as GraphAnnotations, cF as KindAnnotations, fO as MetaEdge, y as AnyEdgeType, bk as DeleteBehavior, T as TemporalMode, I as IndexDeclaration, ch as GraphExtensionVersion, bP as ExtensionNodeDef, bJ as ExtensionEdgeDef, bU as ExtensionOntologyRelation, bN as ExtensionIndex } from '../types-vg7PwMjm.cjs';
 export { C as ContributionDiagnostic, a as ContributionDiagnosticState, b as ContributionRepairEntry, c as ContributionRepairResult } from '../types-vg7PwMjm.cjs';
+import { b as Store, b0 as IdentityAssertionWriteFacade, bi as Node, cU as TransactionContext, dt as EDGE_TEMPORAL_READ_NAMES, g as IdentityFacade, du as IDENTITY_READ_NAMES, d0 as UniqueIntrospection } from '../store-DbHAgVMH.cjs';
 import { I as IngestionImportTarget } from '../ingestion-import-target-C6Z1ugDW.cjs';
-import { b as Store, a$ as IdentityAssertionWriteFacade, bh as Node, c$ as UniqueIntrospection } from '../store-DTEkUQ0k.cjs';
 import { R as Result } from '../result-DWo6mUVz.cjs';
 export { i as isErr, a as isOk, u as unwrap } from '../result-DWo6mUVz.cjs';
 import { z } from 'zod';
@@ -744,6 +744,35 @@ type MergeReport<G extends GraphDef = GraphDef> = Readonly<{
     }>;
 }>;
 
+declare const NODE_READ_NAMES: readonly ["getById", "getByIds", "find", "count", "findByConstraint", "bulkFindByConstraint", "bulkFindByIndex"];
+/** Transaction-bound reads available before applying a fenced merge plan. */
+type MergePlanReadContext<G extends GraphDef> = Readonly<{
+    nodes: Readonly<{
+        [K in keyof TransactionContext<G>["nodes"]]: Pick<TransactionContext<G>["nodes"][K], (typeof NODE_READ_NAMES)[number]>;
+    }>;
+    edges: Readonly<{
+        [K in keyof TransactionContext<G>["edges"]]: Pick<TransactionContext<G>["edges"][K], (typeof EDGE_TEMPORAL_READ_NAMES)[number]>;
+    }>;
+}> & (G["identity"] extends GraphIdentityConfig ? Readonly<{
+    identity: Pick<IdentityFacade<G>, (typeof IDENTITY_READ_NAMES)[number]>;
+}> : Readonly<Record<never, never>>);
+/** Plan effects inside an uncommitted transaction; excludes callback writes. */
+type MergePlanApplied = Readonly<{
+    merged: MergedCounts;
+}>;
+/**
+ * Work composed with merge application in its own protected transaction.
+ * Both callbacks may be replayed (up to three attempts) on transaction conflicts.
+ * Await all work, use only the supplied context, and perform no external effects.
+ * Throw/reject to abort; returning a value (including a Result) is refused.
+ */
+type MergePlanApplyOptions<G extends GraphDef> = Readonly<{
+    /** Runs after the target fence is checked, before plan writes. Reads only. */
+    beforeApply?: (reads: MergePlanReadContext<G>) => Promise<void>;
+    /** Runs after plan writes, before capture flush and commit. */
+    afterApply?: (tx: TransactionContext<G>, applied: MergePlanApplied) => Promise<void>;
+}>;
+
 /**
  * `base@V` stamping.
  *
@@ -829,6 +858,7 @@ declare const MERGE_ERROR_CODES: {
     readonly candidateSource: "GRAPH_MERGE_CANDIDATE_SOURCE";
     readonly evidence: "GRAPH_MERGE_EVIDENCE";
     readonly candidateWriteSet: "GRAPH_MERGE_CANDIDATE_WRITE_SET";
+    readonly review: "GRAPH_MERGE_REVIEW";
 };
 /**
  * Options shared by every merge error. Mirrors the relevant subset of
@@ -854,6 +884,12 @@ declare class InvalidMergeOptionsError extends MergeError {
     readonly code: "GRAPH_MERGE_INVALID_OPTIONS";
     constructor(message: string, options?: MergeErrorOptions);
 }
+/** Invalid, unsupported, or unavailable evidence for durable merge review. */
+declare class MergeReviewError extends MergeError {
+    protected static readonly errorCategory = "user";
+    readonly code: "GRAPH_MERGE_REVIEW";
+    constructor(message: string, options?: MergeErrorOptions);
+}
 /**
  * Failure raised while creating a working-copy branch of a base store
  * (clone/export/import failures, backend construction failures).
@@ -1446,6 +1482,74 @@ declare function captureCandidateWriteSetTarget<G extends GraphDef>(target: Stor
  */
 declare function planCandidateWriteSet<G extends GraphDef>(args: PlanCandidateWriteSetArgs<G>): Promise<Result<MergePlanArtifact, MergeError>>;
 
+declare const MERGE_REVIEW_FORMAT_VERSION: 1;
+/** Application-owned identity of policy code and all opaque/external dependencies. */
+type MergeReviewPolicy = Readonly<{
+    id: string;
+    /** Explicit evidence; use an empty object only when there are no such dependencies. */
+    context: JsonValue;
+}>;
+/** A fingerprint of an observed row, or an expected absence. */
+type MergeReviewRow = MergePlanEntityRef & Readonly<{
+    role: "node" | "edge";
+    /** Absent means this reference did not exist at review time. */
+    digest?: string | undefined;
+}>;
+/** Conservative baseline: all original rows and the complete identity ledger. */
+type MergeReviewBaseline = Readonly<{
+    rows: readonly MergeReviewRow[];
+    identityDigest: string;
+}>;
+/**
+ * Immutable review evidence, distinct from its single-use execution plan.
+ * V1 supports candidate write sets only. Authenticate stored artifacts separately.
+ */
+type MergeReviewArtifact = Readonly<{
+    formatVersion: typeof MERGE_REVIEW_FORMAT_VERSION;
+    kind: "candidate-write-set";
+    digest: MergePlanDigest;
+    writeSet: CandidateWriteSet;
+    policy: MergeReviewPolicy;
+    options: JsonValue;
+    plan: MergePlanArtifact;
+    baseline: MergeReviewBaseline;
+}>;
+/** Structured reason to refuse approval reuse; paths name fields in the review. */
+type MergeReviewDifference = Readonly<{
+    category: "target" | "policy" | "baseline" | "plan";
+    path: string;
+    entity?: MergePlanEntityRef & Readonly<{
+        role: "node" | "edge";
+    }>;
+}>;
+/** Compatibility is evidence for application policy, never an authorization decision. */
+type MergeReviewRevalidation = Readonly<{
+    status: "compatible";
+    reviewDigest: MergePlanDigest;
+    plan: MergePlanArtifact;
+}> | Readonly<{
+    status: "changed" | "incompatible";
+    reviewDigest: MergePlanDigest;
+    differences: readonly MergeReviewDifference[];
+    /** Present when a fresh plan was computed; it requires a new review. */
+    plan?: MergePlanArtifact;
+}>;
+
+type PlanCandidateWriteSetReviewArgs<G extends GraphDef> = PlanCandidateWriteSetArgs<G> & Readonly<{
+    policy: MergeReviewPolicy;
+}>;
+type RevalidateCandidateWriteSetReviewArgs<G extends GraphDef> = Omit<PlanCandidateWriteSetReviewArgs<G>, "writeSet"> & Readonly<{
+    review: unknown;
+}>;
+/** Capture a durable review, with planning and baseline reads under one fence. */
+declare function planCandidateWriteSetReview<G extends GraphDef>(args: PlanCandidateWriteSetReviewArgs<G>): Promise<Result<MergeReviewArtifact, MergeError>>;
+/**
+ * Replan the retained input and relate it to its original review. Never writes
+ * the target, edits an old plan, or authorizes execution. Apply a compatible
+ * result with applyMergePlan(), retaining its final transactional revision fence.
+ */
+declare function revalidateCandidateWriteSetReview<G extends GraphDef>(args: RevalidateCandidateWriteSetReviewArgs<G>): Promise<Result<MergeReviewRevalidation, MergeError>>;
+
 /**
  * Constraint-aware working copies for untrusted ingestion.
  *
@@ -1539,7 +1643,7 @@ declare function planMerge<G extends GraphDef>(store: Store<G>, branchInputs: re
 /** Builds a durable, reviewable incremental merge plan without mutating the target. */
 declare function planMergeIncremental<G extends GraphDef>(args: MergeIncrementalArgs<G>): Promise<Result<MergePlanArtifact, MergeError>>;
 /** Validates and atomically applies an approved serialized merge plan. */
-declare function applyMergePlan<G extends GraphDef>(target: Store<G>, input: MergePlanArtifact): Promise<Result<MergeReport<G>, MergeError>>;
+declare function applyMergePlan<G extends GraphDef>(target: Store<G>, input: MergePlanArtifact, options?: MergePlanApplyOptions<NoInfer<G>>): Promise<Result<MergeReport<G>, MergeError>>;
 /**
  * Merges a set of branches back into a target store (design §7.2).
  *
@@ -1880,4 +1984,4 @@ type KeylessConfig = Readonly<{
     sortFields: readonly string[];
 }>;
 
-export { type BaseAmbiguity, type BaseNodeLookup, type BaseVersion, BaseVersionMismatchError, BranchError, type BranchId, type BranchOptions, type BranchProvenance, CANDIDATE_WRITE_SET_FORMAT_VERSION, type CandidateDiagnostic, type CandidateDiagnostics, type CandidateDiagnosticsOptions, type CandidateSource, CandidateSourceError, type CandidateWriteSet, CandidateWriteSetError, CandidateWriteSetSchema, type CandidateWriteSetTarget, CandidateWriteSetTargetSchema, type ComparisonCeilingPolicy, type ConflictingValue, type DeleteModifyConflict, type DeleteModifyPolicy, type DroppedItem, type Embedder, type EntityRef, type EntityResolution, type GraphBranch, IdentityAssertionWriteFacade, IdentityMergeConflictError, type IngestionBranch, IngestionImportTarget, type IngestionNodeCollections, InvalidMergeOptionsError, InvalidMergePlanError, type KeylessConfig, MERGE_ERROR_CODES, MERGE_OPTION_DEFAULTS, MERGE_PLAN_DIGEST_ALGORITHM, MERGE_PLAN_FORMAT_VERSION, type MakeBackend, type MatchEvidence, MatchEvidenceError, type MatchSource, type MatchStrategy, type MergeBranch, MergeConflictError, MergeConstraintConflictError, type MergeConstraintConflictErrorDetails, MergeError, type MergeIncrementalArgs, type MergeOptions, type MergePlanAnchors, type MergePlanArtifact, type MergePlanArtifactV1, type MergePlanArtifactV1Input, type MergePlanBranchAnchor, type MergePlanCandidateDiagnostic, type MergePlanCanonicalMapping, MergePlanCapabilityError, type MergePlanDiagnostics, type MergePlanDigest, MergePlanDigestMismatchError, type MergePlanEdgeDelete, type MergePlanEdgeUpsert, type MergePlanEntityRef, type MergePlanEntityResolution, type MergePlanGuards, type MergePlanIdentityAssertion, type MergePlanMatchEvidence, type MergePlanMatchSource, type MergePlanNodeDelete, type MergePlanNodeUpsert, MergePlanOriginMismatchError, type MergePlanProposedSummary, type MergePlanProvenanceOptions, type MergePlanRetype, type MergePlanReview, type MergePlanRevisionFence, type MergePlanSchemaFence, MergePlanSchemaMismatchError, type MergePlanSimilarityStrategy, type MergePlanTargetFence, MergePlanTargetMismatchError, type MergePlanTypeReconciliation, type MergePlanWrites, MergePlanningStaleError, type MergeReport, type MergedCounts, type NormalizedMergeOptions, type PlanCandidateWriteSetArgs, type PropertyConflict, type PropertyConflictPolicy, type ProvenanceGraph, type ProvenanceIndex, type ProvenanceNode, type ProvenanceQuery, type ProvenanceRecord, type ReconcileTypesMode, type ResolveConfig, type ResolveMap, type ResolvedCluster, Result, type SimilarityStrategy, SimilarityUnavailableError, type SourceScope, StaleMergePlanError, type TypeReconciliation, UnsupportedMergePlanVersionError, VALIDITY_END_TARGET_PRECEDENCE, type ValidityEndResolution, type WorkingCopyStrategy, applyMergePlan, asBaseVersion, asBranchId, branch, captureCandidateWriteSetTarget, cloneWorkingCopyStrategy, computeBaseVersion, ingestionBranch, merge, mergeIncremental, normalizeMergeOptions, openProvenanceStore, persistProvenanceRecords, planCandidateWriteSet, planMerge, planMergeIncremental, provenanceGraphId, readProvenance };
+export { type BaseAmbiguity, type BaseNodeLookup, type BaseVersion, BaseVersionMismatchError, BranchError, type BranchId, type BranchOptions, type BranchProvenance, CANDIDATE_WRITE_SET_FORMAT_VERSION, type CandidateDiagnostic, type CandidateDiagnostics, type CandidateDiagnosticsOptions, type CandidateSource, CandidateSourceError, type CandidateWriteSet, CandidateWriteSetError, CandidateWriteSetSchema, type CandidateWriteSetTarget, CandidateWriteSetTargetSchema, type ComparisonCeilingPolicy, type ConflictingValue, type DeleteModifyConflict, type DeleteModifyPolicy, type DroppedItem, type Embedder, type EntityRef, type EntityResolution, type GraphBranch, IdentityAssertionWriteFacade, IdentityMergeConflictError, type IngestionBranch, IngestionImportTarget, type IngestionNodeCollections, InvalidMergeOptionsError, InvalidMergePlanError, type KeylessConfig, MERGE_ERROR_CODES, MERGE_OPTION_DEFAULTS, MERGE_PLAN_DIGEST_ALGORITHM, MERGE_PLAN_FORMAT_VERSION, MERGE_REVIEW_FORMAT_VERSION, type MakeBackend, type MatchEvidence, MatchEvidenceError, type MatchSource, type MatchStrategy, type MergeBranch, MergeConflictError, MergeConstraintConflictError, type MergeConstraintConflictErrorDetails, MergeError, type MergeIncrementalArgs, type MergeOptions, type MergePlanAnchors, type MergePlanApplied, type MergePlanApplyOptions, type MergePlanArtifact, type MergePlanArtifactV1, type MergePlanArtifactV1Input, type MergePlanBranchAnchor, type MergePlanCandidateDiagnostic, type MergePlanCanonicalMapping, MergePlanCapabilityError, type MergePlanDiagnostics, type MergePlanDigest, MergePlanDigestMismatchError, type MergePlanEdgeDelete, type MergePlanEdgeUpsert, type MergePlanEntityRef, type MergePlanEntityResolution, type MergePlanGuards, type MergePlanIdentityAssertion, type MergePlanMatchEvidence, type MergePlanMatchSource, type MergePlanNodeDelete, type MergePlanNodeUpsert, MergePlanOriginMismatchError, type MergePlanProposedSummary, type MergePlanProvenanceOptions, type MergePlanReadContext, type MergePlanRetype, type MergePlanReview, type MergePlanRevisionFence, type MergePlanSchemaFence, MergePlanSchemaMismatchError, type MergePlanSimilarityStrategy, type MergePlanTargetFence, MergePlanTargetMismatchError, type MergePlanTypeReconciliation, type MergePlanWrites, MergePlanningStaleError, type MergeReport, type MergeReviewArtifact, type MergeReviewBaseline, type MergeReviewDifference, MergeReviewError, type MergeReviewPolicy, type MergeReviewRevalidation, type MergeReviewRow, type MergedCounts, type NormalizedMergeOptions, type PlanCandidateWriteSetArgs, type PlanCandidateWriteSetReviewArgs, type PropertyConflict, type PropertyConflictPolicy, type ProvenanceGraph, type ProvenanceIndex, type ProvenanceNode, type ProvenanceQuery, type ProvenanceRecord, type ReconcileTypesMode, type ResolveConfig, type ResolveMap, type ResolvedCluster, Result, type RevalidateCandidateWriteSetReviewArgs, type SimilarityStrategy, SimilarityUnavailableError, type SourceScope, StaleMergePlanError, type TypeReconciliation, UnsupportedMergePlanVersionError, VALIDITY_END_TARGET_PRECEDENCE, type ValidityEndResolution, type WorkingCopyStrategy, applyMergePlan, asBaseVersion, asBranchId, branch, captureCandidateWriteSetTarget, cloneWorkingCopyStrategy, computeBaseVersion, ingestionBranch, merge, mergeIncremental, normalizeMergeOptions, openProvenanceStore, persistProvenanceRecords, planCandidateWriteSet, planCandidateWriteSetReview, planMerge, planMergeIncremental, provenanceGraphId, readProvenance, revalidateCandidateWriteSetReview };

package/dist/graph-merge/index.d.ts

@@ -1,7 +1,7 @@
-import { fV as NodeId, z as NodeType, cE as JsonValue, eV as EdgeId, d as GraphDef, fY as NodeKinds, fi as GetNodeType, aD as TypeGraphError, gs as TypeGraphErrorOptions, e as GraphBackend, fk as GraphAnnotations, cF as KindAnnotations, fO as MetaEdge, y as AnyEdgeType, bk as DeleteBehavior, T as TemporalMode, I as IndexDeclaration, ch as GraphExtensionVersion, bP as ExtensionNodeDef, bJ as ExtensionEdgeDef, bU as ExtensionOntologyRelation, bN as ExtensionIndex } from '../types-vg7PwMjm.js';
+import { fV as NodeId, z as NodeType, cE as JsonValue, eV as EdgeId, d as GraphDef, fY as NodeKinds, fi as GetNodeType, G as GraphIdentityConfig, aD as TypeGraphError, gs as TypeGraphErrorOptions, e as GraphBackend, fk as GraphAnnotations, cF as KindAnnotations, fO as MetaEdge, y as AnyEdgeType, bk as DeleteBehavior, T as TemporalMode, I as IndexDeclaration, ch as GraphExtensionVersion, bP as ExtensionNodeDef, bJ as ExtensionEdgeDef, bU as ExtensionOntologyRelation, bN as ExtensionIndex } from '../types-vg7PwMjm.js';
 export { C as ContributionDiagnostic, a as ContributionDiagnosticState, b as ContributionRepairEntry, c as ContributionRepairResult } from '../types-vg7PwMjm.js';
+import { b as Store, b0 as IdentityAssertionWriteFacade, bi as Node, cU as TransactionContext, dt as EDGE_TEMPORAL_READ_NAMES, g as IdentityFacade, du as IDENTITY_READ_NAMES, d0 as UniqueIntrospection } from '../store-CQ3uzXla.js';
 import { I as IngestionImportTarget } from '../ingestion-import-target-Dt7cC-Et.js';
-import { b as Store, a$ as IdentityAssertionWriteFacade, bh as Node, c$ as UniqueIntrospection } from '../store-stw2AEB4.js';
 import { R as Result } from '../result-DWo6mUVz.js';
 export { i as isErr, a as isOk, u as unwrap } from '../result-DWo6mUVz.js';
 import { z } from 'zod';
@@ -744,6 +744,35 @@ type MergeReport<G extends GraphDef = GraphDef> = Readonly<{
     }>;
 }>;
 
+declare const NODE_READ_NAMES: readonly ["getById", "getByIds", "find", "count", "findByConstraint", "bulkFindByConstraint", "bulkFindByIndex"];
+/** Transaction-bound reads available before applying a fenced merge plan. */
+type MergePlanReadContext<G extends GraphDef> = Readonly<{
+    nodes: Readonly<{
+        [K in keyof TransactionContext<G>["nodes"]]: Pick<TransactionContext<G>["nodes"][K], (typeof NODE_READ_NAMES)[number]>;
+    }>;
+    edges: Readonly<{
+        [K in keyof TransactionContext<G>["edges"]]: Pick<TransactionContext<G>["edges"][K], (typeof EDGE_TEMPORAL_READ_NAMES)[number]>;
+    }>;
+}> & (G["identity"] extends GraphIdentityConfig ? Readonly<{
+    identity: Pick<IdentityFacade<G>, (typeof IDENTITY_READ_NAMES)[number]>;
+}> : Readonly<Record<never, never>>);
+/** Plan effects inside an uncommitted transaction; excludes callback writes. */
+type MergePlanApplied = Readonly<{
+    merged: MergedCounts;
+}>;
+/**
+ * Work composed with merge application in its own protected transaction.
+ * Both callbacks may be replayed (up to three attempts) on transaction conflicts.
+ * Await all work, use only the supplied context, and perform no external effects.
+ * Throw/reject to abort; returning a value (including a Result) is refused.
+ */
+type MergePlanApplyOptions<G extends GraphDef> = Readonly<{
+    /** Runs after the target fence is checked, before plan writes. Reads only. */
+    beforeApply?: (reads: MergePlanReadContext<G>) => Promise<void>;
+    /** Runs after plan writes, before capture flush and commit. */
+    afterApply?: (tx: TransactionContext<G>, applied: MergePlanApplied) => Promise<void>;
+}>;
+
 /**
  * `base@V` stamping.
  *
@@ -829,6 +858,7 @@ declare const MERGE_ERROR_CODES: {
     readonly candidateSource: "GRAPH_MERGE_CANDIDATE_SOURCE";
     readonly evidence: "GRAPH_MERGE_EVIDENCE";
     readonly candidateWriteSet: "GRAPH_MERGE_CANDIDATE_WRITE_SET";
+    readonly review: "GRAPH_MERGE_REVIEW";
 };
 /**
  * Options shared by every merge error. Mirrors the relevant subset of
@@ -854,6 +884,12 @@ declare class InvalidMergeOptionsError extends MergeError {
     readonly code: "GRAPH_MERGE_INVALID_OPTIONS";
     constructor(message: string, options?: MergeErrorOptions);
 }
+/** Invalid, unsupported, or unavailable evidence for durable merge review. */
+declare class MergeReviewError extends MergeError {
+    protected static readonly errorCategory = "user";
+    readonly code: "GRAPH_MERGE_REVIEW";
+    constructor(message: string, options?: MergeErrorOptions);
+}
 /**
  * Failure raised while creating a working-copy branch of a base store
  * (clone/export/import failures, backend construction failures).
@@ -1446,6 +1482,74 @@ declare function captureCandidateWriteSetTarget<G extends GraphDef>(target: Stor
  */
 declare function planCandidateWriteSet<G extends GraphDef>(args: PlanCandidateWriteSetArgs<G>): Promise<Result<MergePlanArtifact, MergeError>>;
 
+declare const MERGE_REVIEW_FORMAT_VERSION: 1;
+/** Application-owned identity of policy code and all opaque/external dependencies. */
+type MergeReviewPolicy = Readonly<{
+    id: string;
+    /** Explicit evidence; use an empty object only when there are no such dependencies. */
+    context: JsonValue;
+}>;
+/** A fingerprint of an observed row, or an expected absence. */
+type MergeReviewRow = MergePlanEntityRef & Readonly<{
+    role: "node" | "edge";
+    /** Absent means this reference did not exist at review time. */
+    digest?: string | undefined;
+}>;
+/** Conservative baseline: all original rows and the complete identity ledger. */
+type MergeReviewBaseline = Readonly<{
+    rows: readonly MergeReviewRow[];
+    identityDigest: string;
+}>;
+/**
+ * Immutable review evidence, distinct from its single-use execution plan.
+ * V1 supports candidate write sets only. Authenticate stored artifacts separately.
+ */
+type MergeReviewArtifact = Readonly<{
+    formatVersion: typeof MERGE_REVIEW_FORMAT_VERSION;
+    kind: "candidate-write-set";
+    digest: MergePlanDigest;
+    writeSet: CandidateWriteSet;
+    policy: MergeReviewPolicy;
+    options: JsonValue;
+    plan: MergePlanArtifact;
+    baseline: MergeReviewBaseline;
+}>;
+/** Structured reason to refuse approval reuse; paths name fields in the review. */
+type MergeReviewDifference = Readonly<{
+    category: "target" | "policy" | "baseline" | "plan";
+    path: string;
+    entity?: MergePlanEntityRef & Readonly<{
+        role: "node" | "edge";
+    }>;
+}>;
+/** Compatibility is evidence for application policy, never an authorization decision. */
+type MergeReviewRevalidation = Readonly<{
+    status: "compatible";
+    reviewDigest: MergePlanDigest;
+    plan: MergePlanArtifact;
+}> | Readonly<{
+    status: "changed" | "incompatible";
+    reviewDigest: MergePlanDigest;
+    differences: readonly MergeReviewDifference[];
+    /** Present when a fresh plan was computed; it requires a new review. */
+    plan?: MergePlanArtifact;
+}>;
+
+type PlanCandidateWriteSetReviewArgs<G extends GraphDef> = PlanCandidateWriteSetArgs<G> & Readonly<{
+    policy: MergeReviewPolicy;
+}>;
+type RevalidateCandidateWriteSetReviewArgs<G extends GraphDef> = Omit<PlanCandidateWriteSetReviewArgs<G>, "writeSet"> & Readonly<{
+    review: unknown;
+}>;
+/** Capture a durable review, with planning and baseline reads under one fence. */
+declare function planCandidateWriteSetReview<G extends GraphDef>(args: PlanCandidateWriteSetReviewArgs<G>): Promise<Result<MergeReviewArtifact, MergeError>>;
+/**
+ * Replan the retained input and relate it to its original review. Never writes
+ * the target, edits an old plan, or authorizes execution. Apply a compatible
+ * result with applyMergePlan(), retaining its final transactional revision fence.
+ */
+declare function revalidateCandidateWriteSetReview<G extends GraphDef>(args: RevalidateCandidateWriteSetReviewArgs<G>): Promise<Result<MergeReviewRevalidation, MergeError>>;
+
 /**
  * Constraint-aware working copies for untrusted ingestion.
  *
@@ -1539,7 +1643,7 @@ declare function planMerge<G extends GraphDef>(store: Store<G>, branchInputs: re
 /** Builds a durable, reviewable incremental merge plan without mutating the target. */
 declare function planMergeIncremental<G extends GraphDef>(args: MergeIncrementalArgs<G>): Promise<Result<MergePlanArtifact, MergeError>>;
 /** Validates and atomically applies an approved serialized merge plan. */
-declare function applyMergePlan<G extends GraphDef>(target: Store<G>, input: MergePlanArtifact): Promise<Result<MergeReport<G>, MergeError>>;
+declare function applyMergePlan<G extends GraphDef>(target: Store<G>, input: MergePlanArtifact, options?: MergePlanApplyOptions<NoInfer<G>>): Promise<Result<MergeReport<G>, MergeError>>;
 /**
  * Merges a set of branches back into a target store (design §7.2).
  *
@@ -1880,4 +1984,4 @@ type KeylessConfig = Readonly<{
     sortFields: readonly string[];
 }>;
 
-export { type BaseAmbiguity, type BaseNodeLookup, type BaseVersion, BaseVersionMismatchError, BranchError, type BranchId, type BranchOptions, type BranchProvenance, CANDIDATE_WRITE_SET_FORMAT_VERSION, type CandidateDiagnostic, type CandidateDiagnostics, type CandidateDiagnosticsOptions, type CandidateSource, CandidateSourceError, type CandidateWriteSet, CandidateWriteSetError, CandidateWriteSetSchema, type CandidateWriteSetTarget, CandidateWriteSetTargetSchema, type ComparisonCeilingPolicy, type ConflictingValue, type DeleteModifyConflict, type DeleteModifyPolicy, type DroppedItem, type Embedder, type EntityRef, type EntityResolution, type GraphBranch, IdentityAssertionWriteFacade, IdentityMergeConflictError, type IngestionBranch, IngestionImportTarget, type IngestionNodeCollections, InvalidMergeOptionsError, InvalidMergePlanError, type KeylessConfig, MERGE_ERROR_CODES, MERGE_OPTION_DEFAULTS, MERGE_PLAN_DIGEST_ALGORITHM, MERGE_PLAN_FORMAT_VERSION, type MakeBackend, type MatchEvidence, MatchEvidenceError, type MatchSource, type MatchStrategy, type MergeBranch, MergeConflictError, MergeConstraintConflictError, type MergeConstraintConflictErrorDetails, MergeError, type MergeIncrementalArgs, type MergeOptions, type MergePlanAnchors, type MergePlanArtifact, type MergePlanArtifactV1, type MergePlanArtifactV1Input, type MergePlanBranchAnchor, type MergePlanCandidateDiagnostic, type MergePlanCanonicalMapping, MergePlanCapabilityError, type MergePlanDiagnostics, type MergePlanDigest, MergePlanDigestMismatchError, type MergePlanEdgeDelete, type MergePlanEdgeUpsert, type MergePlanEntityRef, type MergePlanEntityResolution, type MergePlanGuards, type MergePlanIdentityAssertion, type MergePlanMatchEvidence, type MergePlanMatchSource, type MergePlanNodeDelete, type MergePlanNodeUpsert, MergePlanOriginMismatchError, type MergePlanProposedSummary, type MergePlanProvenanceOptions, type MergePlanRetype, type MergePlanReview, type MergePlanRevisionFence, type MergePlanSchemaFence, MergePlanSchemaMismatchError, type MergePlanSimilarityStrategy, type MergePlanTargetFence, MergePlanTargetMismatchError, type MergePlanTypeReconciliation, type MergePlanWrites, MergePlanningStaleError, type MergeReport, type MergedCounts, type NormalizedMergeOptions, type PlanCandidateWriteSetArgs, type PropertyConflict, type PropertyConflictPolicy, type ProvenanceGraph, type ProvenanceIndex, type ProvenanceNode, type ProvenanceQuery, type ProvenanceRecord, type ReconcileTypesMode, type ResolveConfig, type ResolveMap, type ResolvedCluster, Result, type SimilarityStrategy, SimilarityUnavailableError, type SourceScope, StaleMergePlanError, type TypeReconciliation, UnsupportedMergePlanVersionError, VALIDITY_END_TARGET_PRECEDENCE, type ValidityEndResolution, type WorkingCopyStrategy, applyMergePlan, asBaseVersion, asBranchId, branch, captureCandidateWriteSetTarget, cloneWorkingCopyStrategy, computeBaseVersion, ingestionBranch, merge, mergeIncremental, normalizeMergeOptions, openProvenanceStore, persistProvenanceRecords, planCandidateWriteSet, planMerge, planMergeIncremental, provenanceGraphId, readProvenance };
+export { type BaseAmbiguity, type BaseNodeLookup, type BaseVersion, BaseVersionMismatchError, BranchError, type BranchId, type BranchOptions, type BranchProvenance, CANDIDATE_WRITE_SET_FORMAT_VERSION, type CandidateDiagnostic, type CandidateDiagnostics, type CandidateDiagnosticsOptions, type CandidateSource, CandidateSourceError, type CandidateWriteSet, CandidateWriteSetError, CandidateWriteSetSchema, type CandidateWriteSetTarget, CandidateWriteSetTargetSchema, type ComparisonCeilingPolicy, type ConflictingValue, type DeleteModifyConflict, type DeleteModifyPolicy, type DroppedItem, type Embedder, type EntityRef, type EntityResolution, type GraphBranch, IdentityAssertionWriteFacade, IdentityMergeConflictError, type IngestionBranch, IngestionImportTarget, type IngestionNodeCollections, InvalidMergeOptionsError, InvalidMergePlanError, type KeylessConfig, MERGE_ERROR_CODES, MERGE_OPTION_DEFAULTS, MERGE_PLAN_DIGEST_ALGORITHM, MERGE_PLAN_FORMAT_VERSION, MERGE_REVIEW_FORMAT_VERSION, type MakeBackend, type MatchEvidence, MatchEvidenceError, type MatchSource, type MatchStrategy, type MergeBranch, MergeConflictError, MergeConstraintConflictError, type MergeConstraintConflictErrorDetails, MergeError, type MergeIncrementalArgs, type MergeOptions, type MergePlanAnchors, type MergePlanApplied, type MergePlanApplyOptions, type MergePlanArtifact, type MergePlanArtifactV1, type MergePlanArtifactV1Input, type MergePlanBranchAnchor, type MergePlanCandidateDiagnostic, type MergePlanCanonicalMapping, MergePlanCapabilityError, type MergePlanDiagnostics, type MergePlanDigest, MergePlanDigestMismatchError, type MergePlanEdgeDelete, type MergePlanEdgeUpsert, type MergePlanEntityRef, type MergePlanEntityResolution, type MergePlanGuards, type MergePlanIdentityAssertion, type MergePlanMatchEvidence, type MergePlanMatchSource, type MergePlanNodeDelete, type MergePlanNodeUpsert, MergePlanOriginMismatchError, type MergePlanProposedSummary, type MergePlanProvenanceOptions, type MergePlanReadContext, type MergePlanRetype, type MergePlanReview, type MergePlanRevisionFence, type MergePlanSchemaFence, MergePlanSchemaMismatchError, type MergePlanSimilarityStrategy, type MergePlanTargetFence, MergePlanTargetMismatchError, type MergePlanTypeReconciliation, type MergePlanWrites, MergePlanningStaleError, type MergeReport, type MergeReviewArtifact, type MergeReviewBaseline, type MergeReviewDifference, MergeReviewError, type MergeReviewPolicy, type MergeReviewRevalidation, type MergeReviewRow, type MergedCounts, type NormalizedMergeOptions, type PlanCandidateWriteSetArgs, type PlanCandidateWriteSetReviewArgs, type PropertyConflict, type PropertyConflictPolicy, type ProvenanceGraph, type ProvenanceIndex, type ProvenanceNode, type ProvenanceQuery, type ProvenanceRecord, type ReconcileTypesMode, type ResolveConfig, type ResolveMap, type ResolvedCluster, Result, type RevalidateCandidateWriteSetReviewArgs, type SimilarityStrategy, SimilarityUnavailableError, type SourceScope, StaleMergePlanError, type TypeReconciliation, UnsupportedMergePlanVersionError, VALIDITY_END_TARGET_PRECEDENCE, type ValidityEndResolution, type WorkingCopyStrategy, applyMergePlan, asBaseVersion, asBranchId, branch, captureCandidateWriteSetTarget, cloneWorkingCopyStrategy, computeBaseVersion, ingestionBranch, merge, mergeIncremental, normalizeMergeOptions, openProvenanceStore, persistProvenanceRecords, planCandidateWriteSet, planCandidateWriteSetReview, planMerge, planMergeIncremental, provenanceGraphId, readProvenance, revalidateCandidateWriteSetReview };