@nicia-ai/typegraph 0.33.0 → 0.35.0

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

@@ -1,12 +1,12 @@
-import { G as GraphDef, t as NodeKinds, u as GetNodeType } from '../manager-BYl_zyZR.cjs';
-import { S as Store, N as Node, U as UniqueIntrospection } from '../store-view-9jQ2rPum.cjs';
-import { d as NodeId, N as NodeType, e as EdgeId, J as JsonValue, f as KindAnnotations, g as EdgeType, D as DeleteBehavior, T as TemporalMode, h as GraphExtensionVersion, i as ExtensionNodeDef, j as ExtensionEdgeDef, k as ExtensionOntologyRelation, l as ExtensionIndex } from '../extension-types-YGFJPrzK.cjs';
-import { T as TypeGraphError } from '../index-SEvUHDA6.cjs';
+import { G as GraphDef, t as NodeKinds, u as GetNodeType } from '../manager-DwQi8eV0.cjs';
+import { S as Store, N as Node, U as UniqueIntrospection } from '../store-view-BSpqvAxK.cjs';
+import { d as NodeId, N as NodeType, e as EdgeId, J as JsonValue, f as KindAnnotations, g as EdgeType, D as DeleteBehavior, T as TemporalMode, h as GraphExtensionVersion, i as ExtensionNodeDef, j as ExtensionEdgeDef, k as ExtensionOntologyRelation, l as ExtensionIndex } from '../extension-types-ixRpJVUp.cjs';
+import { T as TypeGraphError } from '../index-Bks_3HHK.cjs';
 import { R as Result } from '../result-DWo6mUVz.cjs';
 export { i as isErr, a as isOk, u as unwrap } from '../result-DWo6mUVz.cjs';
-import { G as GraphBackend, M as MetaEdge, I as IndexDeclaration } from '../types-C_UnQOQp.cjs';
+import { G as GraphBackend, M as MetaEdge, I as IndexDeclaration } from '../fulltext-strategy-CDkSSYhq.cjs';
 import { z } from 'zod';
-import '../materialize-indexes-D20xNluI.cjs';
+import '../materialize-indexes-B4e9360H.cjs';
 import 'drizzle-orm';
 import 'drizzle-orm/pg-core';
 import 'drizzle-orm/sqlite-core';
@@ -34,8 +34,10 @@ type BranchId = string & Readonly<{
 }>;
 /**
  * Opaque token identifying the immutable `base@V` a branch was forked from.
- * Combines a schema hash with a content fingerprint (computed in T3). Branded so
- * it cannot be confused with an arbitrary string.
+ * Combines a schema hash with a staleness component. Branded so it cannot be
+ * confused with an arbitrary string. The second component is a
+ * durable revision anchor for stores with revision tracking enabled and a
+ * compatibility content fingerprint otherwise.
  */
 type BaseVersion = string & Readonly<{
     readonly __brand: "BaseVersion";
@@ -486,7 +488,13 @@ type MergeReport<G extends GraphDef = GraphDef> = Readonly<{
  *      This is content-addressed (the public `computeSchemaHash` deliberately
  *      excludes the version number and `generatedAt`, so it is stable across
  *      re-saves of the same schema).
- *   2. A **content fingerprint** — a SHA-256 digest (truncated to a fixed-width
+ *   2. A **revision anchor** when the Store has `revisionTracking` (or
+ *      `history`) enabled — a durable random per-graph origin plus the
+ *      monotonic revision clock. This is O(1) to read and changes after every
+ *      successful Store write; the origin prevents independent stores with
+ *      coincident timestamps from sharing an anchor.
+ *      Stores without tracking retain the compatibility fallback: a
+ *      **content fingerprint**, a SHA-256 digest (truncated to a fixed-width
  *      hex string) of every LIVE node and edge over the base store (`id`,
  *      `updated_at`, the bitemporal `valid_from`/`valid_to`, and canonicalized
  *      `props`; edges also carry their endpoint ids), sorted by id, so two stores
@@ -501,17 +509,20 @@ type MergeReport<G extends GraphDef = GraphDef> = Readonly<{
  * fingerprint would not match its source. (See the working-copy fidelity note in
  * T4.)
  *
- * `computeBaseVersion` is async because schema hashing and live-content
- * enumeration go through async TypeGraph internals. The design's synchronous
- * illustrative signature does not survive contact with the real store surface.
+ * `computeBaseVersion` is async because schema hashing, revision reads, and the
+ * compatibility live-content enumeration go through async TypeGraph internals.
+ * The design's synchronous illustrative signature does not survive contact with
+ * the real store surface.
  */
 
 /**
  * Computes the immutable `base@V` token for a store. Combines the schema hash
- * with a live-content fingerprint into a single branded {@link BaseVersion}.
+ * with a durable revision anchor when tracking is enabled, otherwise with the
+ * compatibility live-content fingerprint.
  *
  * MUST be called on the ORIGINAL base store, not a clone (clones regenerate
- * timestamps and would fingerprint differently).
+ * timestamps and would fingerprint differently when the compatibility path is
+ * in use).
  */
 declare function computeBaseVersion<G extends GraphDef>(store: Store<G>): Promise<BaseVersion>;
 
@@ -590,12 +601,12 @@ declare class BaseVersionMismatchError extends MergeError {
  * Pluggable working-copy strategy: how `branch()` produces an isolated,
  * independently-mutable copy of a base store.
  *
- * The P0 default is a faithful CLONE via the public interchange API
- * ({@link cloneWorkingCopyStrategy}): `exportGraph` the base, then `importGraph`
- * into a fresh store on a caller-provided backend. IDs are preserved by
- * interchange, so the diff engine (T3) can key on stable ids across base and
- * fork. This leverages public entrypoints only, needs zero schema changes, and
- * behaves identically across SQLite and Postgres.
+ * The P0 default is a faithful CLONE via streamed public interchange
+ * ({@link cloneWorkingCopyStrategy}): `exportGraphStream` the base, then
+ * `importGraphStream` into a fresh store on a caller-provided backend. IDs are
+ * preserved by interchange, so the diff engine (T3) can key on stable ids across
+ * base and fork. This leverages public entrypoints only, needs zero schema
+ * changes, and behaves identically across SQLite and Postgres.
  *
  * INTERCHANGE FIDELITY LIMITATION (verified, design §13.x): the interchange
  * `meta` schema has no `deletedAt` field, so a base row that is already
@@ -609,6 +620,18 @@ declare class BaseVersionMismatchError extends MergeError {
  * only) as the immutable reference, never against the clone (clones regenerate
  * `created_at`/`updated_at`, which would otherwise destabilize `base@V`).
  *
+ * `includeTemporal: true` carries `validFrom`/`validTo` through unchanged,
+ * preserving the base's exact valid-time window on the clone: create-time
+ * paths default an omitted `validFrom` to the row's own creation instant
+ * (see #240), and export/import round-trip a still-open-left `valid_from`
+ * (e.g. a row that predates the #240 fix) as an explicit `null` rather than
+ * silently dropping it — see `InterchangeNodeSchema.validFrom`'s doc.
+ * Without either half of this, the clone's re-import would re-stamp the
+ * affected base rows to the CLONE's creation instant instead — narrowing
+ * their validity window and making `asOf` reads on the fork diverge from
+ * identical reads on the base for any instant between the row's real
+ * creation and the clone.
+ *
  * Logical-namespace (copy-on-write within one backend, no full data copy) is a
  * future strategy slot — see the `WorkingCopyStrategy` interface — deferred past
  * P0.
@@ -637,29 +660,35 @@ type WorkingCopyStrategy<G extends GraphDef> = Readonly<{
  * in-process Postgres engine) be constructed lazily at branch time.
  *
  * The returned backend MUST be EMPTY (no rows for the base graph): the clone
- * seeds it from the base via `importGraph` with `onConflict: "error"`, so a
+ * seeds it from the base via `importGraphStream` with `onConflict: "error"`, so a
  * pre-existing row is surfaced as a {@link BranchError} rather than silently
  * skipped (which would leave the working copy diverging from the base).
+ * When the source store uses `revisionTracking`, the backend must also satisfy
+ * that option's transactional revision-clock requirements because the clone
+ * preserves the source's branchability contract.
  */
 type MakeBackend = () => Promise<GraphBackend>;
 /**
- * The P0 default working-copy strategy: faithful clone via export/import.
+ * The P0 default working-copy strategy: faithful clone via streamed interchange.
  *
  * On each `create(baseStore)`:
- *   1. `exportGraph(baseStore, { includeMeta: true, includeDeleted: false })` —
- *      `includeMeta: true` carries `created_at`/`updated_at`; `includeDeleted:
- *      false` keeps the clone to LIVE rows only. Shipping soft-deleted rows is
- *      unsafe: the meta schema has no `deletedAt`, so they would import as live and
- *      resurrect on the fork's diff (see the fidelity note above). `branch()` only
- *      needs the base's live state.
+ *   1. `exportGraphStream(baseStore, { includeMeta: true, includeTemporal: true,
+ *      includeDeleted: false })` — `includeMeta: true` carries
+ *      `created_at`/`updated_at`; `includeTemporal: true` carries
+ *      `validFrom`/`validTo` so the clone's valid-time window matches the base's
+ *      exactly (see the fidelity note above); `includeDeleted: false` keeps the
+ *      clone to LIVE rows only. Shipping soft-deleted rows is unsafe: the meta
+ *      schema has no `deletedAt`, so they would import as live and resurrect on
+ *      the fork's diff (see the fidelity note above). `branch()` only needs the
+ *      base's live state.
  *   2. Create a fresh store over the caller-provided backend with the SAME graph
  *      definition via `createStoreWithSchema`.
- *   3. `importGraph(freshStore, data, { onConflict: "error", ... })` — ids are
+ *   3. `importGraphStream(freshStore, data, { onConflict: "error", ... })` — ids are
  *      preserved so the diff engine can key on them. `onConflict: "error"`
  *      requires the backend to be EMPTY: a pre-existing row is a contract
  *      violation that must surface loudly, never be silently skipped (a skipped
  *      row would leave the clone diverging from the base, so the fork's diff would
- *      report phantom modifications/deletions). `importGraph` RETURNS
+ *      report phantom modifications/deletions). `importGraphStream` RETURNS
  *      `{ success, errors }` rather than throwing on a per-row rejection, so its
  *      result is checked and any failure fails the branch.
  *
@@ -682,7 +711,8 @@ declare function cloneWorkingCopyStrategy<G extends GraphDef>(makeBackend: MakeB
  * branch's own backend seeded with the base's live state.
  *
  * The copy mechanism is pluggable behind {@link WorkingCopyStrategy}. The P0
- * default is the faithful export/import clone ({@link cloneWorkingCopyStrategy}),
+ * default is the faithful streamed-interchange clone
+ * ({@link cloneWorkingCopyStrategy}),
  * which keeps this primitive backend-agnostic: the caller supplies a
  * `makeBackend` factory, and `branch()` never names a concrete backend.
  */
@@ -697,7 +727,7 @@ declare function cloneWorkingCopyStrategy<G extends GraphDef>(makeBackend: MakeB
  * logical-namespace copy-on-write).
  *
  * Returns a {@link Result}: success yields the {@link GraphBranch}; any failure
- * (base-version stamping, backend construction, export/import) is wrapped in a
+ * (base-version stamping, backend construction, streamed interchange) is wrapped in a
  * {@link BranchError} with the underlying cause attached. Errors are returned,
  * never thrown — this is internal-logic surface (the caller converts to a thrown
  * error at the framework boundary).
@@ -814,7 +844,7 @@ type CandidatePair<K extends NodeType = NodeType> = Readonly<{
  *
  *   1. PRECONDITION — compute the target's `base@V` and reject any branch whose
  *      `base` token does not match it (`BaseVersionMismatchError`). A branch
- *      forked from a divergent schema or content fingerprint cannot be merged
+ *      forked from a divergent schema or base revision cannot be merged
  *      safely (design §5.2 / §13.6).
  *   2. STAGE — `stageBranches` (T7): the provenance-tagged UNION of every
  *      branch's state-diff against the immutable base.

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

@@ -1,12 +1,12 @@
-import { G as GraphDef, t as NodeKinds, u as GetNodeType } from '../manager-C0_r0ALf.js';
-import { S as Store, N as Node, U as UniqueIntrospection } from '../store-view-FfE5_7eo.js';
-import { d as NodeId, N as NodeType, e as EdgeId, J as JsonValue, f as KindAnnotations, g as EdgeType, D as DeleteBehavior, T as TemporalMode, h as GraphExtensionVersion, i as ExtensionNodeDef, j as ExtensionEdgeDef, k as ExtensionOntologyRelation, l as ExtensionIndex } from '../extension-types-YGFJPrzK.js';
-import { T as TypeGraphError } from '../index-DGX6D9j1.js';
+import { G as GraphDef, t as NodeKinds, u as GetNodeType } from '../manager-ejUCB52T.js';
+import { S as Store, N as Node, U as UniqueIntrospection } from '../store-view-CKbHFRnn.js';
+import { d as NodeId, N as NodeType, e as EdgeId, J as JsonValue, f as KindAnnotations, g as EdgeType, D as DeleteBehavior, T as TemporalMode, h as GraphExtensionVersion, i as ExtensionNodeDef, j as ExtensionEdgeDef, k as ExtensionOntologyRelation, l as ExtensionIndex } from '../extension-types-ixRpJVUp.js';
+import { T as TypeGraphError } from '../index-6CSUAq-x.js';
 import { R as Result } from '../result-DWo6mUVz.js';
 export { i as isErr, a as isOk, u as unwrap } from '../result-DWo6mUVz.js';
-import { G as GraphBackend, M as MetaEdge, I as IndexDeclaration } from '../types-DGylBhWo.js';
+import { G as GraphBackend, M as MetaEdge, I as IndexDeclaration } from '../fulltext-strategy-B57yvC5Q.js';
 import { z } from 'zod';
-import '../materialize-indexes-CAkIYFV-.js';
+import '../materialize-indexes-te9TPMMJ.js';
 import 'drizzle-orm';
 import 'drizzle-orm/pg-core';
 import 'drizzle-orm/sqlite-core';
@@ -34,8 +34,10 @@ type BranchId = string & Readonly<{
 }>;
 /**
  * Opaque token identifying the immutable `base@V` a branch was forked from.
- * Combines a schema hash with a content fingerprint (computed in T3). Branded so
- * it cannot be confused with an arbitrary string.
+ * Combines a schema hash with a staleness component. Branded so it cannot be
+ * confused with an arbitrary string. The second component is a
+ * durable revision anchor for stores with revision tracking enabled and a
+ * compatibility content fingerprint otherwise.
  */
 type BaseVersion = string & Readonly<{
     readonly __brand: "BaseVersion";
@@ -486,7 +488,13 @@ type MergeReport<G extends GraphDef = GraphDef> = Readonly<{
  *      This is content-addressed (the public `computeSchemaHash` deliberately
  *      excludes the version number and `generatedAt`, so it is stable across
  *      re-saves of the same schema).
- *   2. A **content fingerprint** — a SHA-256 digest (truncated to a fixed-width
+ *   2. A **revision anchor** when the Store has `revisionTracking` (or
+ *      `history`) enabled — a durable random per-graph origin plus the
+ *      monotonic revision clock. This is O(1) to read and changes after every
+ *      successful Store write; the origin prevents independent stores with
+ *      coincident timestamps from sharing an anchor.
+ *      Stores without tracking retain the compatibility fallback: a
+ *      **content fingerprint**, a SHA-256 digest (truncated to a fixed-width
  *      hex string) of every LIVE node and edge over the base store (`id`,
  *      `updated_at`, the bitemporal `valid_from`/`valid_to`, and canonicalized
  *      `props`; edges also carry their endpoint ids), sorted by id, so two stores
@@ -501,17 +509,20 @@ type MergeReport<G extends GraphDef = GraphDef> = Readonly<{
  * fingerprint would not match its source. (See the working-copy fidelity note in
  * T4.)
  *
- * `computeBaseVersion` is async because schema hashing and live-content
- * enumeration go through async TypeGraph internals. The design's synchronous
- * illustrative signature does not survive contact with the real store surface.
+ * `computeBaseVersion` is async because schema hashing, revision reads, and the
+ * compatibility live-content enumeration go through async TypeGraph internals.
+ * The design's synchronous illustrative signature does not survive contact with
+ * the real store surface.
  */
 
 /**
  * Computes the immutable `base@V` token for a store. Combines the schema hash
- * with a live-content fingerprint into a single branded {@link BaseVersion}.
+ * with a durable revision anchor when tracking is enabled, otherwise with the
+ * compatibility live-content fingerprint.
  *
  * MUST be called on the ORIGINAL base store, not a clone (clones regenerate
- * timestamps and would fingerprint differently).
+ * timestamps and would fingerprint differently when the compatibility path is
+ * in use).
  */
 declare function computeBaseVersion<G extends GraphDef>(store: Store<G>): Promise<BaseVersion>;
 
@@ -590,12 +601,12 @@ declare class BaseVersionMismatchError extends MergeError {
  * Pluggable working-copy strategy: how `branch()` produces an isolated,
  * independently-mutable copy of a base store.
  *
- * The P0 default is a faithful CLONE via the public interchange API
- * ({@link cloneWorkingCopyStrategy}): `exportGraph` the base, then `importGraph`
- * into a fresh store on a caller-provided backend. IDs are preserved by
- * interchange, so the diff engine (T3) can key on stable ids across base and
- * fork. This leverages public entrypoints only, needs zero schema changes, and
- * behaves identically across SQLite and Postgres.
+ * The P0 default is a faithful CLONE via streamed public interchange
+ * ({@link cloneWorkingCopyStrategy}): `exportGraphStream` the base, then
+ * `importGraphStream` into a fresh store on a caller-provided backend. IDs are
+ * preserved by interchange, so the diff engine (T3) can key on stable ids across
+ * base and fork. This leverages public entrypoints only, needs zero schema
+ * changes, and behaves identically across SQLite and Postgres.
  *
  * INTERCHANGE FIDELITY LIMITATION (verified, design §13.x): the interchange
  * `meta` schema has no `deletedAt` field, so a base row that is already
@@ -609,6 +620,18 @@ declare class BaseVersionMismatchError extends MergeError {
  * only) as the immutable reference, never against the clone (clones regenerate
  * `created_at`/`updated_at`, which would otherwise destabilize `base@V`).
  *
+ * `includeTemporal: true` carries `validFrom`/`validTo` through unchanged,
+ * preserving the base's exact valid-time window on the clone: create-time
+ * paths default an omitted `validFrom` to the row's own creation instant
+ * (see #240), and export/import round-trip a still-open-left `valid_from`
+ * (e.g. a row that predates the #240 fix) as an explicit `null` rather than
+ * silently dropping it — see `InterchangeNodeSchema.validFrom`'s doc.
+ * Without either half of this, the clone's re-import would re-stamp the
+ * affected base rows to the CLONE's creation instant instead — narrowing
+ * their validity window and making `asOf` reads on the fork diverge from
+ * identical reads on the base for any instant between the row's real
+ * creation and the clone.
+ *
  * Logical-namespace (copy-on-write within one backend, no full data copy) is a
  * future strategy slot — see the `WorkingCopyStrategy` interface — deferred past
  * P0.
@@ -637,29 +660,35 @@ type WorkingCopyStrategy<G extends GraphDef> = Readonly<{
  * in-process Postgres engine) be constructed lazily at branch time.
  *
  * The returned backend MUST be EMPTY (no rows for the base graph): the clone
- * seeds it from the base via `importGraph` with `onConflict: "error"`, so a
+ * seeds it from the base via `importGraphStream` with `onConflict: "error"`, so a
  * pre-existing row is surfaced as a {@link BranchError} rather than silently
  * skipped (which would leave the working copy diverging from the base).
+ * When the source store uses `revisionTracking`, the backend must also satisfy
+ * that option's transactional revision-clock requirements because the clone
+ * preserves the source's branchability contract.
  */
 type MakeBackend = () => Promise<GraphBackend>;
 /**
- * The P0 default working-copy strategy: faithful clone via export/import.
+ * The P0 default working-copy strategy: faithful clone via streamed interchange.
  *
  * On each `create(baseStore)`:
- *   1. `exportGraph(baseStore, { includeMeta: true, includeDeleted: false })` —
- *      `includeMeta: true` carries `created_at`/`updated_at`; `includeDeleted:
- *      false` keeps the clone to LIVE rows only. Shipping soft-deleted rows is
- *      unsafe: the meta schema has no `deletedAt`, so they would import as live and
- *      resurrect on the fork's diff (see the fidelity note above). `branch()` only
- *      needs the base's live state.
+ *   1. `exportGraphStream(baseStore, { includeMeta: true, includeTemporal: true,
+ *      includeDeleted: false })` — `includeMeta: true` carries
+ *      `created_at`/`updated_at`; `includeTemporal: true` carries
+ *      `validFrom`/`validTo` so the clone's valid-time window matches the base's
+ *      exactly (see the fidelity note above); `includeDeleted: false` keeps the
+ *      clone to LIVE rows only. Shipping soft-deleted rows is unsafe: the meta
+ *      schema has no `deletedAt`, so they would import as live and resurrect on
+ *      the fork's diff (see the fidelity note above). `branch()` only needs the
+ *      base's live state.
  *   2. Create a fresh store over the caller-provided backend with the SAME graph
  *      definition via `createStoreWithSchema`.
- *   3. `importGraph(freshStore, data, { onConflict: "error", ... })` — ids are
+ *   3. `importGraphStream(freshStore, data, { onConflict: "error", ... })` — ids are
  *      preserved so the diff engine can key on them. `onConflict: "error"`
  *      requires the backend to be EMPTY: a pre-existing row is a contract
  *      violation that must surface loudly, never be silently skipped (a skipped
  *      row would leave the clone diverging from the base, so the fork's diff would
- *      report phantom modifications/deletions). `importGraph` RETURNS
+ *      report phantom modifications/deletions). `importGraphStream` RETURNS
  *      `{ success, errors }` rather than throwing on a per-row rejection, so its
  *      result is checked and any failure fails the branch.
  *
@@ -682,7 +711,8 @@ declare function cloneWorkingCopyStrategy<G extends GraphDef>(makeBackend: MakeB
  * branch's own backend seeded with the base's live state.
  *
  * The copy mechanism is pluggable behind {@link WorkingCopyStrategy}. The P0
- * default is the faithful export/import clone ({@link cloneWorkingCopyStrategy}),
+ * default is the faithful streamed-interchange clone
+ * ({@link cloneWorkingCopyStrategy}),
  * which keeps this primitive backend-agnostic: the caller supplies a
  * `makeBackend` factory, and `branch()` never names a concrete backend.
  */
@@ -697,7 +727,7 @@ declare function cloneWorkingCopyStrategy<G extends GraphDef>(makeBackend: MakeB
  * logical-namespace copy-on-write).
  *
  * Returns a {@link Result}: success yields the {@link GraphBranch}; any failure
- * (base-version stamping, backend construction, export/import) is wrapped in a
+ * (base-version stamping, backend construction, streamed interchange) is wrapped in a
  * {@link BranchError} with the underlying cause attached. Errors are returned,
  * never thrown — this is internal-logic surface (the caller converts to a thrown
  * error at the framework boundary).
@@ -814,7 +844,7 @@ type CandidatePair<K extends NodeType = NodeType> = Readonly<{
  *
  *   1. PRECONDITION — compute the target's `base@V` and reject any branch whose
  *      `base` token does not match it (`BaseVersionMismatchError`). A branch
- *      forked from a divergent schema or content fingerprint cannot be merged
+ *      forked from a divergent schema or base revision cannot be merged
  *      safely (design §5.2 / §13.6).
  *   2. STAGE — `stageBranches` (T7): the provenance-tagged UNION of every
  *      branch's state-diff against the immutable base.