@nicia-ai/typegraph 0.45.0 → 0.46.1

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

@@ -1,15 +1,14 @@
-import { b0 as NodeId, d as NodeType, ar as EdgeId, aT as JsonValue, z as GraphBackend, aU as KindAnnotations, aY as MetaEdge, a2 as EdgeType, D as DeleteBehavior, T as TemporalMode, I as IndexDeclaration, aI as GraphExtensionVersion, c7 as ExtensionNodeDef, c8 as ExtensionEdgeDef, c9 as ExtensionOntologyRelation, ca as ExtensionIndex } from '../types-Ch9a0Dx6.js';
-export { C as ContributionDiagnostic, a as ContributionDiagnosticState, b as ContributionRepairEntry, c as ContributionRepairResult } from '../types-Ch9a0Dx6.js';
-import { G as GraphDef, N as NodeKinds, c as GetNodeType } from '../define-graph-BGrJahvp.js';
-import { a as Store, az as Node, bZ as UniqueIntrospection } from '../store-view-66p92IPi.js';
-import { a1 as TypeGraphError } from '../index-BBxZCUdu.js';
+import { _ as NodeId, u as NodeType, $ as EdgeId, a0 as JsonValue, d as GraphDef, a1 as NodeKinds, a2 as GetNodeType, y as GraphBackend, a3 as KindAnnotations, a4 as MetaEdge, a5 as EdgeType, a6 as DeleteBehavior, T as TemporalMode, I as IndexDeclaration, a7 as GraphExtensionVersion, a8 as ExtensionNodeDef, a9 as ExtensionEdgeDef, aa as ExtensionOntologyRelation, ab as ExtensionIndex } from '../types-HkveCCx0.js';
+export { C as ContributionDiagnostic, a as ContributionDiagnosticState, b as ContributionRepairEntry, c as ContributionRepairResult } from '../types-HkveCCx0.js';
+import { a as Store, N as Node, m as UniqueIntrospection } from '../store-ClQ-MZQS.js';
+import { T as TypeGraphError, b as TypeGraphErrorOptions } from '../index-BSHvKfok.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';
-import '../temporal-Bob6Nfbp.js';
-import '../manager-YoLEfcc1.js';
-import '../materialize-indexes-Bhhyb1B3.js';
-import '../searchable-DLWEfC4a.js';
+import '../temporal-BtM4UALv.js';
+import '../searchable-9OQoPuRs.js';
+import '../manager-CfZAimti.js';
+import '../materialize-indexes-BMJP6Tms.js';
 
 /**
  * Core type model for the graph-merge primitive.
@@ -60,6 +59,21 @@ type GraphBranch<G extends GraphDef> = Readonly<{
     id: BranchId;
     base: BaseVersion;
     store: Store<G>;
+    /**
+     * The branch store's committed schema row `(version, hash)` captured AT
+     * FORK. The merge requires the branch's CURRENT committed schema to still
+     * equal this anchor: any schema operation on the branch after forking —
+     * including a round-trip that restores the original document hash —
+     * advances the version and is refused, so its row side effects can never
+     * be projected into a merge as bare data changes. `undefined` inside the
+     * tuple-less field means the clone committed no schema row (unmanaged
+     * stores); absent entirely on hand-built branch objects, where the merge
+     * falls back to comparing the branch's hash against the fork source's.
+     */
+    schemaAnchor?: Readonly<{
+        version: number;
+        hash: string;
+    }> | undefined;
 }>;
 /**
  * Options for {@link GraphBranch} creation. `id` is optional — when omitted a
@@ -301,9 +315,9 @@ type MergeOptions<G extends GraphDef = GraphDef> = Readonly<{
      * the value contributed by the highest-weight branch wins. Ties fall back to
      * {@link branchOrder} (then canonical value order); branches absent from the map
      * default to weight `0`. Ignored by every other policy. Keyed by
-     * {@link BranchId}, like {@link branchOrder}. Without this map,
-     * `"provenanceWeighted"` has no weights to consult and degrades to
-     * `"lastWriteWins"` semantics.
+     * {@link BranchId}, like {@link branchOrder}. A non-empty map is required when
+     * either property-conflict policy is `"provenanceWeighted"`; otherwise option
+     * validation refuses the merge rather than silently changing policy.
      */
     provenanceWeights?: ReadonlyMap<BranchId, number>;
 }>;
@@ -311,14 +325,14 @@ type MergeOptions<G extends GraphDef = GraphDef> = Readonly<{
  * Object-form arguments for {@link mergeIncremental} (§6.6). The two same-typed
  * stores are NAMED so `forkPoint` (the frozen ancestor the branches forked from, the
  * diff reference) and `target` (the live committed graph that base lookups and the
- * commit land on) cannot be swapped. `options.target` is ignored — `target` is the
- * explicit arg.
+ * commit land on) cannot be swapped. The target is deliberately absent from the
+ * options type because the named `target` argument is authoritative.
  */
 type MergeIncrementalArgs<G extends GraphDef = GraphDef> = Readonly<{
     forkPoint: Store<G>;
     target: Store<G>;
     branches: readonly GraphBranch<G>[];
-    options?: MergeOptions<G>;
+    options?: Omit<MergeOptions<G>, "target">;
 }>;
 /**
  * Records that a set of fork node ids resolved to a single canonical survivor.
@@ -373,13 +387,64 @@ type TypeReconciliation = Readonly<{
 }>;
 /**
  * An item omitted from the merged result (e.g. an edge whose endpoint was
- * deleted, or an incompatible-typed cluster member).
+ * deleted, an incompatible-typed cluster member, or an identity assertion that
+ * lost the survivor rule to an equivalent assertion from another branch).
+ *
+ * Discriminated on `kind` so each variant keeps its own id type: node and edge
+ * ids are branded, while an identity assertion is named by the ledger's plain
+ * assertion id (it is not a graph entity and carries no brand).
  */
 type DroppedItem = Readonly<{
-    kind: "edge" | "node";
-    id: NodeId<NodeType> | EdgeId;
+    kind: "node";
+    id: NodeId<NodeType>;
+    reason: string;
+}> | Readonly<{
+    kind: "edge";
+    id: EdgeId;
+    reason: string;
+}> | Readonly<{
+    kind: "identity";
+    id: string;
     reason: string;
 }>;
+/**
+ * The {@link ValidityEndResolution.precedence} of an entry the INCREMENTAL TARGET
+ * decided rather than the merge: the destination had already moved this row's end
+ * before the merge ran, so every branch claim was discarded and no write was staged.
+ */
+declare const VALIDITY_END_TARGET_PRECEDENCE: "target";
+/**
+ * One inherited row whose end-of-validity the merge RESOLVED: the instant that
+ * stands and every branch that claimed an end for the row (including the ones whose
+ * claim lost the least-claim tie-break).
+ *
+ * `id` is bare because `entity` + `kind` already disambiguate it — a node and an
+ * edge, or two kinds, that share an id string are distinct entries.
+ */
+type ValidityEndResolution = Readonly<{
+    entity: "node" | "edge";
+    kind: string;
+    id: string;
+    /**
+     * The row's end-of-validity as a canonical UTC ISO 8601 string: the instant the
+     * commit WROTE, or — under {@link VALIDITY_END_TARGET_PRECEDENCE} — the instant
+     * the target already held and the merge left alone.
+     */
+    validTo: string;
+    /** Every branch that claimed an end, sorted; length > 1 means arbitration. */
+    claimedBy: readonly BranchId[];
+    /**
+     * Present only as {@link VALIDITY_END_TARGET_PRECEDENCE}, marking an entry the
+     * merge did NOT decide: the incremental target had already moved this end, so
+     * `validTo` is the target's own committed instant, every claim in `claimedBy` was
+     * discarded, and nothing was written or credited for the row.
+     *
+     * ABSENT means the merge decided the end — `validTo` is the instant it wrote and
+     * `claimedBy` names the claims it arbitrated between. A consumer that ignores the
+     * field therefore keeps reading the entries it always read.
+     */
+    precedence?: typeof VALIDITY_END_TARGET_PRECEDENCE;
+}>;
 /**
  * A `(kind, id)` node identity as surfaced in the merge report. Node identity is the
  * PAIR, never the bare id (a `Doctor` and a `SpecialistDoctor` can share an id string),
@@ -437,20 +502,49 @@ type ProvenanceRecord = Readonly<{
     branchId: BranchId;
     sourceId: string;
 }>;
+/**
+ * What the merge actually wrote to the target: node and edge counts plus the
+ * identity-ledger effects. `identity.asserted` counts rows the applier
+ * CREATED — planned assertions the target already held (idempotent exact or
+ * semantic-pair matches, the normal incremental case) are excluded — and
+ * `identity.retracted` counts rows the applier ENDED, excluding already-ended
+ * or unknown ids. Assertions dropped by the survivor rule are enumerated in
+ * {@link MergeReport.dropped} rather than counted here.
+ */
+type MergedCounts = Readonly<{
+    nodes: number;
+    edges: number;
+    identity: Readonly<{
+        asserted: number;
+        retracted: number;
+    }>;
+}>;
 /**
  * The full result of a {@link merge}: counts, every resolution/conflict/
  * reconciliation/drop, and the report-only provenance index.
  */
 type MergeReport<G extends GraphDef = GraphDef> = Readonly<{
-    merged: Readonly<{
-        nodes: number;
-        edges: number;
-    }>;
+    merged: MergedCounts;
     resolutions: readonly EntityResolution[];
     conflicts: readonly PropertyConflict<G>[];
     deleteModifyConflicts: readonly DeleteModifyConflict[];
     typeReconciliations: readonly TypeReconciliation[];
     dropped: readonly DroppedItem[];
+    /**
+     * Every inherited row whose END-OF-VALIDITY the merge resolved, with the instant
+     * that stands and the branches that claimed an end.
+     *
+     * Reported because the resolution is silent by design: two branches ending the
+     * same row at different instants are not in conflict (an ending is a monotone
+     * claim, like a deletion), so the earliest end is taken without a
+     * `PropertyConflict`. This list is how a caller sees that arbitration happened.
+     * It includes the rows where the arbitration discarded EVERY claim because the
+     * incremental target had already moved the end — those carry
+     * `precedence: "target"` and staged no write. Window deltas the commit CANNOT
+     * apply appear in {@link MergeReport.dropped} instead, with reason
+     * `"window-not-applicable"`.
+     */
+    validityEnds: readonly ValidityEndResolution[];
     /**
      * Ambiguous new-vs-base matches (§6.4-A): components that bridged ≥2 committed
      * base entities. Empty on the staged-vs-staged snapshot path.
@@ -540,9 +634,11 @@ declare function computeBaseVersion<G extends GraphDef>(store: Store<G>): Promis
  */
 declare const MERGE_ERROR_CODES: {
     readonly merge: "GRAPH_MERGE_ERROR";
+    readonly invalidOptions: "GRAPH_MERGE_INVALID_OPTIONS";
     readonly branch: "GRAPH_MERGE_BRANCH_ERROR";
     readonly similarityUnavailable: "GRAPH_MERGE_SIMILARITY_UNAVAILABLE";
     readonly conflict: "GRAPH_MERGE_CONFLICT";
+    readonly identityConflict: "GRAPH_MERGE_IDENTITY_CONFLICT";
     readonly baseVersionMismatch: "GRAPH_MERGE_BASE_VERSION_MISMATCH";
 };
 /**
@@ -560,6 +656,13 @@ type MergeErrorOptions = Readonly<{
  * for the orchestrator (comparison-ceiling overruns, commit failures, etc.).
  */
 declare class MergeError extends TypeGraphError {
+    protected static readonly errorCategory: TypeGraphErrorOptions["category"];
+    constructor(message: string, options?: MergeErrorOptions);
+}
+/** Raised when caller-supplied merge options are invalid or unsupported. */
+declare class InvalidMergeOptionsError extends MergeError {
+    protected static readonly errorCategory = "user";
+    readonly code: "GRAPH_MERGE_INVALID_OPTIONS";
     constructor(message: string, options?: MergeErrorOptions);
 }
 /**
@@ -587,6 +690,11 @@ declare class MergeConflictError extends MergeError {
     readonly code: "GRAPH_MERGE_CONFLICT";
     constructor(message: string, options?: MergeErrorOptions);
 }
+/** Raised when identity branches contain opposing or retract/reassert truth. */
+declare class IdentityMergeConflictError extends MergeError {
+    readonly code: "GRAPH_MERGE_IDENTITY_CONFLICT";
+    constructor(message: string, options?: MergeErrorOptions);
+}
 /**
  * Raised by the `merge()` precondition check when a branch's `base@V` token
  * does not match the merge target's current base version (the branch forked
@@ -870,12 +978,21 @@ declare function merge<G extends GraphDef>(store: Store<G>, branches: readonly G
  * through the same three-way merge planner.
  *
  * Object-form args so the two same-typed stores (`forkPoint`, `target`) cannot be
- * swapped. `options.target` is ignored — `target` is the explicit arg.
+ * swapped. The named `target` is authoritative; an untyped caller that also
+ * supplies `options.target` is refused rather than silently ignored.
  *
  * Preconditions (typed errors): every branch forked from `forkPoint`
  * (`branch.base === computeBaseVersion(forkPoint)`); `forkPoint` and `target` share a
  * schema hash (schema drift is fatal; target CONTENT may have advanced); and
  * `onBasePropertyConflict` is `"flag"` (keep-base for committed-row conflicts).
+ *
+ * The fork-point precondition is not merely an entry check: it is re-verified
+ * inside the commit transaction, so `forkPoint` must stay immutable for the
+ * duration of the call. A write to it while the merge is in flight makes every
+ * branch diff describe an ancestor that no longer exists, and is refused with
+ * `BaseVersionMismatchError` rather than committed (see
+ * {@link assertForkPointUnchanged}). The TARGET, by contrast, may advance
+ * throughout — that is what "incremental" means.
  */
 declare function mergeIncremental<G extends GraphDef>(args: MergeIncrementalArgs<G>): Promise<Result<MergeReport<G>, MergeError>>;
 
@@ -964,7 +1081,7 @@ declare const Provenance: Readonly<{
  * shared backend, while a single `Provenance` schema serves all of them.
  */
 declare function provenanceGraphId(targetGraphId: string): string;
-/** Builds the sidecar provenance graph definition for a target graph. */
+/** The schema written by releases before durable sidecar ownership markers. */
 declare function buildProvenanceGraph(targetGraphId: string): Readonly<{
     id: string;
     nodes: {
@@ -994,6 +1111,7 @@ declare function buildProvenanceGraph(targetGraphId: string): Readonly<{
         from: NodeType | EdgeType | string;
         to: NodeType | EdgeType | string;
     }>[];
+    identity: undefined;
     defaults: Readonly<{
         onNodeDelete: DeleteBehavior;
         temporalMode: TemporalMode;
@@ -1009,27 +1127,46 @@ declare function buildProvenanceGraph(targetGraphId: string): Readonly<{
     deprecatedKinds: ReadonlySet<string>;
     __graphDef: true;
 }>;
-/** The concrete sidecar provenance graph type. */
+/**
+ * Public view of the sidecar graph. The ownership kind is deliberately hidden:
+ * it is framework metadata, not provenance data or an application collection.
+ */
 type ProvenanceGraph = ReturnType<typeof buildProvenanceGraph>;
 /** A persisted provenance node (the queryable record). */
 type ProvenanceNode = Node<typeof Provenance>;
 /**
- * Opens — materializing the schema if needed — the provenance store for a target.
- * Pass the target Store in ordinary application code; inspection tools that do
- * not have its GraphDef may instead pass the backend and target graph id.
+ * Opens the provenance store for a target — OPENING OR CREATING, never merely
+ * reading. On a free graph id this claims the ownership marker and registers the
+ * sidecar schema; on an occupied one it throws. There is no read-only entry
+ * point: a tool that wants to inspect an existing sidecar without creating one
+ * must decide for itself (e.g. by checking `backend.getActiveSchema` for
+ * {@link provenanceGraphId}) before calling this.
+ *
+ * Pass the target Store in ordinary application code; callers that do not have
+ * its GraphDef may instead pass the backend and target graph id.
  *
- * Idempotent: safe to call before every persist/query, and shares the backend
- * with the target (so the caller must NOT close it separately — closing the
- * shared backend is the target owner's job).
+ * Idempotent in the sense that matters for the persist/query path: repeated calls
+ * converge on one sidecar and write no second marker. It shares the backend with
+ * the target, so the caller must NOT close it separately — closing the shared
+ * backend is the target owner's job.
  */
 declare function openProvenanceStore<G extends GraphDef>(target: Store<G>): Promise<Store<ProvenanceGraph>>;
-/** Opens a provenance store for standalone inspection without a target GraphDef. */
+/**
+ * Opens (or creates — see above) a provenance store without a target GraphDef,
+ * for callers that hold only the backend and the target's graph id.
+ */
 declare function openProvenanceStore(backend: GraphBackend, targetGraphId: string): Promise<Store<ProvenanceGraph>>;
 /**
  * Upserts one `Provenance` node per record into the sidecar store, keyed by the
  * deterministic id (re-running the same merge is a no-op upsert, never a
  * duplicate). Returns the row count written. The caller wraps this for best-effort
  * behavior — a failure here must not fail an already-committed merge.
+ *
+ * Records that hash to the SAME id are collapsed before the batch: the id is the
+ * contribution's identity, so they are one row by definition — and a single
+ * `bulkUpsertById` batch cannot create the same id twice. Collapsing here is what
+ * makes the returned number the rows actually written for ANY caller, whatever
+ * shape its record list arrived in.
  */
 declare function persistProvenanceRecords(store: Store<ProvenanceGraph>, targetGraphId: string, records: readonly ProvenanceRecord[]): Promise<number>;
 /** Filter for {@link readProvenance}. Each field, when set, narrows the result. */
@@ -1143,4 +1280,4 @@ type KeylessConfig = Readonly<{
     sortFields: readonly string[];
 }>;
 
-export { type BaseAmbiguity, type BaseNodeLookup, type BaseVersion, BaseVersionMismatchError, BranchError, type BranchId, type BranchOptions, type BranchProvenance, type CandidateSource, type ComparisonCeilingPolicy, type ConflictingValue, type DeleteModifyConflict, type DeleteModifyPolicy, type DroppedItem, type Embedder, type EntityResolution, type GraphBranch, type KeylessConfig, MERGE_ERROR_CODES, MERGE_OPTION_DEFAULTS, type MakeBackend, MergeConflictError, MergeError, type MergeIncrementalArgs, type MergeOptions, type MergeReport, type NormalizedMergeOptions, 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, type TypeReconciliation, type WorkingCopyStrategy, asBaseVersion, asBranchId, branch, cloneWorkingCopyStrategy, computeBaseVersion, merge, mergeIncremental, normalizeMergeOptions, openProvenanceStore, persistProvenanceRecords, provenanceGraphId, readProvenance };
+export { type BaseAmbiguity, type BaseNodeLookup, type BaseVersion, BaseVersionMismatchError, BranchError, type BranchId, type BranchOptions, type BranchProvenance, type CandidateSource, type ComparisonCeilingPolicy, type ConflictingValue, type DeleteModifyConflict, type DeleteModifyPolicy, type DroppedItem, type Embedder, type EntityResolution, type GraphBranch, IdentityMergeConflictError, InvalidMergeOptionsError, type KeylessConfig, MERGE_ERROR_CODES, MERGE_OPTION_DEFAULTS, type MakeBackend, MergeConflictError, MergeError, type MergeIncrementalArgs, type MergeOptions, type MergeReport, type MergedCounts, type NormalizedMergeOptions, 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, type TypeReconciliation, VALIDITY_END_TARGET_PRECEDENCE, type ValidityEndResolution, type WorkingCopyStrategy, asBaseVersion, asBranchId, branch, cloneWorkingCopyStrategy, computeBaseVersion, merge, mergeIncremental, normalizeMergeOptions, openProvenanceStore, persistProvenanceRecords, provenanceGraphId, readProvenance };