@nicia-ai/typegraph 0.34.0 → 0.36.0

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

@@ -1,12 +1,12 @@
-import { G as GraphDef, t as NodeKinds, u as GetNodeType } from '../manager-ms9cKdc6.cjs';
-import { S as Store, N as Node, U as UniqueIntrospection } from '../store-view-D09po4H6.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-9KDOpZzF.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-BLtQWKRj.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-DkNnF-7K.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-BZUeN_BU.js';
-import { S as Store, N as Node, U as UniqueIntrospection } from '../store-view-BlgnhEYf.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-DplHC3Nt.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-BFvdmBPV.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-D1Sqeyxy.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.

package/dist/graph-merge/index.js

@@ -1,30 +1,29 @@
-import { createStoreWithSchema } from '../chunk-WLRIWYHQ.js';
-import '../chunk-3EUKJEQ3.js';
-import '../chunk-QV245VMN.js';
-import { exportGraph, importGraph } from '../chunk-T2DWPQNE.js';
-import '../chunk-6SCVW4AS.js';
-import { defineNode, computeSchemaHash, serializeSchema } from '../chunk-K2TGS3EN.js';
+import { createStoreWithSchema } from '../chunk-5DIPR3L3.js';
+import '../chunk-RAXU3RMB.js';
+import { importGraphStream, exportGraphStream } from '../chunk-PZKNKG5M.js';
+import '../chunk-DN5VP4JC.js';
+import { defineNode, computeSchemaHash, serializeSchema } from '../chunk-M75SUBFG.js';
+import { getNodeKinds, getEdgeKinds, defineGraph } from '../chunk-SKCOUWAX.js';
 import { sortedReplacer } from '../chunk-UR7W5YQK.js';
-import { getNodeKinds, getEdgeKinds, defineGraph } from '../chunk-CHXTTSC6.js';
-import '../chunk-SHLY4MCM.js';
-import '../chunk-KUTNI6SI.js';
-import '../chunk-4DIBPQNJ.js';
-import { sha256Hex } from '../chunk-K34OPSJK.js';
-import '../chunk-BVTWD66D.js';
-import { ok, err, isErr, computeTransitiveClosure, isReachable } from '../chunk-ZURTTSCM.js';
-export { isErr, isOk, unwrap } from '../chunk-ZURTTSCM.js';
-import { compareStrings } from '../chunk-4S2FXGBJ.js';
-import { generateId, computeUniqueKey } from '../chunk-A7SZZFAG.js';
-import '../chunk-V3QNTB7Z.js';
-import '../chunk-XXVEULWX.js';
-import '../chunk-2MRAX3UE.js';
-import '../chunk-GZCNZ7QW.js';
-import '../chunk-2EBMPJBO.js';
-import '../chunk-Z5XBMDXU.js';
-import '../chunk-XLUNB2TZ.js';
+import '../chunk-UZV3AZKF.js';
+import '../chunk-OR5ZA5WP.js';
+import { sha256Hex } from '../chunk-W63OVYY4.js';
+import '../chunk-FPIZFYHE.js';
+import '../chunk-5SEGFTZX.js';
+import { ok, err, isErr, computeTransitiveClosure, isReachable } from '../chunk-SXGE7ITL.js';
+export { isErr, isOk, unwrap } from '../chunk-SXGE7ITL.js';
+import '../chunk-S5F7ZLP2.js';
+import { compareStrings } from '../chunk-BYPOGQWK.js';
+import { generateId, computeUniqueKey, lockRecordedGraphWrite, readRevisionOrigin, readRecordedClock } from '../chunk-5VTR2F2K.js';
+import '../chunk-UT3S4SEN.js';
+import '../chunk-IU46OHVW.js';
+import '../chunk-JFUPDJXD.js';
+import '../chunk-OHMP6N2J.js';
+import '../chunk-KBGQIPRQ.js';
+import '../chunk-SNXVDZAJ.js';
 import '../chunk-ITE4IXAK.js';
-import { TypeGraphError } from '../chunk-TQOYM4LN.js';
-import '../chunk-K5P5OZXS.js';
+import { TypeGraphError } from '../chunk-WI7ISNQF.js';
+import '../chunk-G6Q5UM7U.js';
 import { z } from 'zod';
 
 // src/graph-merge/canonical-props.ts
@@ -46,10 +45,14 @@ function edgeStateSignature(edge) {
 }
 function parseRowProps(props) {
   let parsed;
-  try {
-    parsed = JSON.parse(props);
-  } catch {
-    return {};
+  if (typeof props === "string") {
+    try {
+      parsed = JSON.parse(props);
+    } catch {
+      return {};
+    }
+  } else {
+    parsed = props;
   }
   if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
     return {};
@@ -93,7 +96,7 @@ function compareMergeKeys(left, right) {
 var ENUMERATION_PAGE_SIZE = 1e3;
 async function enumerateAllNodes(backend, graphId, kind) {
   const collected = [];
-  let after = void 0;
+  let after;
   for (; ; ) {
     const page = await backend.findNodesByKind({
       graphId,
@@ -115,7 +118,7 @@ async function enumerateAllNodes(backend, graphId, kind) {
 }
 async function enumerateAllEdges(backend, graphId, kind) {
   const collected = [];
-  let after = void 0;
+  let after;
   for (; ; ) {
     const page = await backend.findEdgesByKind({
       graphId,
@@ -344,6 +347,9 @@ function asBaseVersion(value) {
 
 // src/graph-merge/base-version.ts
 var TOKEN_SEPARATOR = "\0";
+var REVISION_COMPONENT_PREFIX = "revision:";
+var REVISION_COMPONENT_SEPARATOR = ":";
+var INITIAL_REVISION = "initial";
 var FALLBACK_SCHEMA_VERSION = 1;
 async function readActiveSchemaVersion(backend, graphId) {
   const active = await backend.getActiveSchema(graphId);
@@ -404,6 +410,16 @@ async function computeContentComponent(backend, graphId, graph) {
   );
 }
 async function computeBaseVersion(store) {
+  if (store.revisionTrackingEnabled) {
+    const [schemaComponent2, origin, revision] = await Promise.all([
+      computeSchemaComponent(store),
+      store.revisionOriginNow(),
+      store.revisionNow()
+    ]);
+    return asBaseVersion(
+      `${schemaComponent2}${TOKEN_SEPARATOR}${revisionComponent(origin, revision)}`
+    );
+  }
   const [schemaComponent, contentComponent] = await Promise.all([
     computeSchemaComponent(store),
     computeContentComponent(store.backend, store.graphId, store.graph)
@@ -412,6 +428,30 @@ async function computeBaseVersion(store) {
     `${schemaComponent}${TOKEN_SEPARATOR}${contentComponent}`
   );
 }
+function revisionComponent(origin, revision) {
+  return `${REVISION_COMPONENT_PREFIX}${origin}${REVISION_COMPONENT_SEPARATOR}${revision ?? INITIAL_REVISION}`;
+}
+function hasRevisionAnchor(version) {
+  return contentComponentOf(version).startsWith(REVISION_COMPONENT_PREFIX);
+}
+function revisionAnchorOf(version) {
+  const revision = revisionPartsOf(version)?.revision;
+  return revision === void 0 || revision === INITIAL_REVISION ? void 0 : revision;
+}
+function revisionOriginOf(version) {
+  return revisionPartsOf(version)?.origin;
+}
+function revisionPartsOf(version) {
+  const component = contentComponentOf(version);
+  if (!component.startsWith(REVISION_COMPONENT_PREFIX)) return void 0;
+  const encoded = component.slice(REVISION_COMPONENT_PREFIX.length);
+  const separator = encoded.indexOf(REVISION_COMPONENT_SEPARATOR);
+  if (separator <= 0 || separator === encoded.length - 1) return void 0;
+  return {
+    origin: encoded.slice(0, separator),
+    revision: encoded.slice(separator + 1)
+  };
+}
 function contentComponentOf(version) {
   const separatorIndex = version.indexOf(TOKEN_SEPARATOR);
   return separatorIndex === -1 ? version : version.slice(separatorIndex + 1);
@@ -486,22 +526,32 @@ var CLONE_IMPORT_BATCH_SIZE = 1e3;
 function cloneWorkingCopyStrategy(makeBackend) {
   return {
     create: async (baseStore) => {
-      const data = await exportGraph(baseStore, {
-        includeMeta: true,
-        includeDeleted: false
-      });
       const backend = await makeBackend();
       try {
         const [freshStore] = await createStoreWithSchema(
           baseStore.graph,
-          backend
+          backend,
+          {
+            // Keep descendants branchable with the same O(1) anchor contract,
+            // but do not copy recorded-time history into the disposable fork.
+            revisionTracking: baseStore.revisionTrackingEnabled
+          }
+        );
+        const result = await importGraphStream(
+          freshStore,
+          exportGraphStream(baseStore, {
+            includeMeta: true,
+            includeTemporal: true,
+            includeDeleted: false,
+            batchSize: CLONE_IMPORT_BATCH_SIZE
+          }),
+          {
+            onConflict: "error",
+            onUnknownProperty: "error",
+            validateReferences: true,
+            batchSize: CLONE_IMPORT_BATCH_SIZE
+          }
         );
-        const result = await importGraph(freshStore, data, {
-          onConflict: "error",
-          onUnknownProperty: "error",
-          validateReferences: true,
-          batchSize: CLONE_IMPORT_BATCH_SIZE
-        });
         if (!result.success) {
           throw new BranchError(
             "Clone import failed: the working copy could not be seeded from the base store. The backend returned by makeBackend() must be empty.",
@@ -899,6 +949,7 @@ var UnionFind = class {
   constructor(compare) {
     this.compare = compare;
   }
+  compare;
   parent = /* @__PURE__ */ new Map();
   /** Adds `value` as its own singleton set if it is not already present. */
   add(value) {
@@ -3338,13 +3389,50 @@ async function commitPlan(target, plan, expectedBaseVersion) {
         tx.nodes,
         tx.edges
       );
-    }, MERGE_COMMIT_TX_OPTIONS)
+    }, mergeCommitTransactionOptions(target))
   );
 }
 var MERGE_COMMIT_TX_OPTIONS = {
   isolationLevel: "serializable"
 };
+function mergeCommitTransactionOptions(target) {
+  return target.historyEnabled ? void 0 : MERGE_COMMIT_TX_OPTIONS;
+}
 async function assertTargetUnchanged(txBackend, target, expectedBaseVersion) {
+  if (hasRevisionAnchor(expectedBaseVersion)) {
+    await lockRecordedGraphWrite(txBackend, target.graphId);
+    const expectedOrigin = revisionOriginOf(expectedBaseVersion);
+    const liveOrigin = await readRevisionOrigin(
+      txBackend,
+      target.revisionSchema,
+      target.graphId
+    );
+    if (liveOrigin !== expectedOrigin) {
+      throw new BaseVersionMismatchError(
+        "The merge branch was forked from a different revision-tracked store; the resolved plan was not applied.",
+        {
+          details: { expectedOrigin, liveOrigin },
+          suggestion: "Merge the branch back into its original base store, or fork a new branch from this target."
+        }
+      );
+    }
+    const liveRevision = await readRecordedClock(
+      txBackend,
+      target.revisionSchema,
+      target.graphId
+    );
+    const expectedRevision = revisionAnchorOf(expectedBaseVersion);
+    if (liveRevision !== expectedRevision) {
+      throw new BaseVersionMismatchError(
+        "The merge target was modified between the revision-anchor check and the commit transaction; the resolved plan was not applied.",
+        {
+          details: { expectedRevision, liveRevision },
+          suggestion: "Re-run the merge (and re-branch if the divergence is real), or route all graph writes through the revision-tracked Store."
+        }
+      );
+    }
+    return;
+  }
   const liveContent = await computeContentComponent(
     txBackend,
     target.graphId,
@@ -4022,6 +4110,9 @@ async function commitIncrementalPlan(target, plan, guard) {
   }
   return withTxConflictRetry(
     () => target.transaction(async (tx) => {
+      if (target.revisionTrackingEnabled) {
+        await lockRecordedGraphWrite(tx.backend, target.graphId);
+      }
       const nodesApi = tx.nodes;
       const edgesApi = tx.edges;
       await assertBaseResolutionStable(tx, guard);
@@ -4029,7 +4120,7 @@ async function commitIncrementalPlan(target, plan, guard) {
       await validateIncrementalNodeWrites(target, nodesApi, plan);
       await validateIncrementalEdgeWrites(target, edgesApi, plan);
       return applyMergePlan(plan, nodesApi, edgesApi);
-    }, MERGE_COMMIT_TX_OPTIONS)
+    }, mergeCommitTransactionOptions(target))
   );
 }
 async function mergeIncremental(args) {