@nicia-ai/typegraph 0.31.0 → 0.32.0

package/dist/{chunk-UIFEEPME.js → chunk-WNORITK6.js}

@@ -1,20 +1,361 @@
 import { quoteIdentifier, EMPTY_REQUIRED_COLUMNS, addRequiredColumn, markSelectiveFieldAsRequired, markFieldRefAsRequired, NODE_COLUMNS, shouldProjectColumn, mapSelectiveSystemFieldToColumn, isIdFieldRef, isAggregateExpr, EDGE_COLUMNS } from './chunk-3EUKJEQ3.js';
-import { loadAndMergeGraphExtensionDocument, ensureSchema, loadAndVerifyGraph, mergeGraphExtension, commitNewSchemaVersion, applyDeprecatedKinds, loadActiveSchemaWithBootstrap, parseSerializedSchema, computeClosuresFromOntology, createEmptyClosures, KindRegistry, extensionKindNames, serializeSchemaProperties, buildGraphExtensionOntologyKeySet, compileTimeOntologyKey, getTypeName, validateNodeProps, validateEdgeProps } from './chunk-XKJQQQVR.js';
-import { nowIso, isKnownKind, validateOptionalIsoDate, getNodeKinds, getEdgeKinds } from './chunk-MAQJYNJR.js';
-import { generateIndexDDL } from './chunk-2ZY4K43M.js';
+import { loadAndMergeGraphExtensionDocument, ensureSchema, loadAndVerifyGraph, mergeGraphExtension, commitNewSchemaVersion, applyDeprecatedKinds, loadActiveSchemaWithBootstrap, parseSerializedSchema, computeClosuresFromOntology, createEmptyClosures, KindRegistry, extensionKindNames, serializeSchemaProperties, buildGraphExtensionOntologyKeySet, compileTimeOntologyKey, getTypeName, validateNodeProps, validateEdgeProps } from './chunk-2BVHPOIG.js';
+import { nowIso, isKnownKind, validateCanonicalIsoDate, validateOptionalCanonicalIsoDate, getNodeKinds, getEdgeKinds } from './chunk-W4ZX2GCP.js';
+import { generateIndexDDL } from './chunk-PIHXFF73.js';
 import { NODE_META_KEYS, EDGE_META_KEYS } from './chunk-IJORSAC3.js';
 import { createSchemaIntrospector, resolveFieldTypeInfoAtJsonPointer, getSearchableMetadata, DEFAULT_SEARCHABLE_LANGUAGE } from './chunk-MXE2U3EX.js';
 import { resolveEmbeddingFields } from './chunk-454I6GDF.js';
 import { IncompatibleChangeError, filterReservedKeys, RESERVED_NODE_KEYS, RESERVED_EDGE_KEYS, RemoveCompileTimeKindError, KindHasReferentsError, validateProjectionField } from './chunk-YCV72E6L.js';
 import { runOptionallyInTransaction } from './chunk-SAJSMR2B.js';
 import { sortedReplacer, canonicalEqual, isMissingTableError } from './chunk-M6OC455F.js';
-import { getDialect, assertVectorMinScore, compileNodeIndexFieldKeys, compileIndexWhere, vectorScoreExpression, vectorMinScoreCondition } from './chunk-2HZGWCB4.js';
+import { getDialect, assertVectorMinScore, compileNodeIndexFieldKeys, compileIndexWhere, vectorScoreExpression, vectorMinScoreCondition } from './chunk-C4C4Q7A6.js';
 import { MAX_PG_IDENTIFIER_LENGTH, DEFAULT_PAGINATION_LIMIT, DEFAULT_STREAM_BATCH_SIZE, sha256Hex, SQLITE_PATH_DELIMITER, PG_ARRAY_START, PG_ARRAY_END, PG_PATH_ELEMENT_SEPARATOR, fnv1aBase36 } from './chunk-2YMGNYXY.js';
 import { ConfigurationError, UnsupportedPredicateError, ValidationError, KindNotFoundError, EndpointError, EagerMaterializationError, CompilerInvariantError, DatabaseOperationError, EdgeNotFoundError, NodeIndexNotFoundError, NodeConstraintNotFoundError, RestrictedDeleteError, NodeNotFoundError, EndpointNotFoundError, UniquenessError, CardinalityError, DisjointError } from './chunk-TQOYM4LN.js';
 import { jsonPointer, parseJsonPointer, resolveJsonPointer, normalizeJsonPointer, joinJsonPointers } from './chunk-K5P5OZXS.js';
 import { sql, Placeholder } from 'drizzle-orm';
 import { nanoid } from 'nanoid';
 
+// src/core/temporal.ts
+function resolveReadCoordinate(mode, asOf, suggestion) {
+  if (mode !== "asOf" && asOf !== void 0) {
+    throw new ValidationError(
+      `Temporal mode "${mode}" does not take an asOf timestamp.`,
+      {
+        issues: [
+          {
+            path: "asOf",
+            message: `asOf is only valid with mode "asOf", not "${mode}"`
+          }
+        ]
+      },
+      {
+        suggestion: 'Pin an instant with store.asOf(timestamp) or store.view({ mode: "asOf", asOf }); drop asOf for other modes.'
+      }
+    );
+  }
+  assertValidAsOf(
+    mode,
+    asOf,
+    suggestion === void 0 ? void 0 : { suggestion }
+  );
+  return { valid: asOf === void 0 ? { mode } : { mode, asOf } };
+}
+function assertValidAsOf(mode, asOf, options) {
+  if (mode === "asOf" && asOf === void 0) {
+    throw new ValidationError(
+      'Temporal mode "asOf" requires a timestamp',
+      {
+        issues: [
+          { path: "asOf", message: "Timestamp is required for asOf mode" }
+        ]
+      },
+      {
+        suggestion: options?.suggestion ?? 'Provide an ISO-8601 timestamp for asOf mode, e.g. "2026-01-01T00:00:00.000Z".'
+      }
+    );
+  }
+  if (asOf !== void 0) {
+    validateCanonicalIsoDate(asOf, "asOf");
+  }
+}
+function describeCoordinate(coordinate) {
+  const { mode, asOf } = coordinate.valid;
+  return asOf === void 0 ? `mode "${mode}"` : `mode "${mode}" asOf ${asOf}`;
+}
+function coordinateContext(coordinate) {
+  const { mode, asOf } = coordinate.valid;
+  return { temporalMode: mode, ...asOf !== void 0 && { asOf } };
+}
+
+// src/store/collections/temporal-read-params.ts
+function withCoordinate(coordinate) {
+  const { mode, asOf } = coordinate.valid;
+  return asOf === void 0 ? { temporalMode: mode } : { temporalMode: mode, asOf };
+}
+function resolveTemporalReadParams(options, defaultTemporalMode) {
+  const { valid } = resolveReadCoordinate(
+    options?.temporalMode ?? defaultTemporalMode,
+    options?.asOf
+  );
+  const { mode, asOf } = valid;
+  const base = {
+    excludeDeleted: mode !== "includeTombstones",
+    temporalMode: mode
+  };
+  if (mode === "current" || mode === "asOf") {
+    return { ...base, asOf: asOf ?? nowIso() };
+  }
+  return base;
+}
+
+// src/store/types.ts
+var CURRENT_ONLY_READ_NAMES = [
+  "findByConstraint",
+  "bulkFindByConstraint",
+  "bulkFindByIndex"
+];
+
+// src/store/store-view.ts
+var NON_KIND_KEYS = /* @__PURE__ */ new Set([
+  "then",
+  "catch",
+  "finally",
+  "toJSON"
+]);
+function createReadOnlyRefusal(entity, method, coordinate) {
+  return () => {
+    throw new ConfigurationError(
+      `'${method}' is not available on a read-only StoreView (${describeCoordinate(coordinate)}). A time-pinned view is a read perspective \u2014 perform writes on the live Store.`,
+      {
+        code: "STORE_VIEW_READ_ONLY",
+        entity,
+        method,
+        ...coordinateContext(coordinate)
+      }
+    );
+  };
+}
+function createCurrentOnlyRefusal(entity, method, coordinate) {
+  return () => Promise.reject(
+    new ConfigurationError(
+      `'${method}' is not available on a StoreView (${describeCoordinate(coordinate)}). Constraint / index / endpoint lookups read current state only and cannot honor a temporal coordinate \u2014 use a current-mode view or the live Store.`,
+      {
+        code: "STORE_VIEW_CURRENT_ONLY",
+        entity,
+        method,
+        ...coordinateContext(coordinate)
+      }
+    )
+  );
+}
+var CURRENT_ONLY_READS = new Set(
+  CURRENT_ONLY_READ_NAMES
+);
+function readOnlyCollectionProxy(reads, live, coordinate, entity) {
+  const isCurrent = coordinate.valid.mode === "current";
+  const target = Object.freeze(reads);
+  return new Proxy(target, {
+    get(target2, property, receiver) {
+      if (typeof property === "string" && !Object.hasOwn(target2, property) && Object.hasOwn(live, property)) {
+        if (CURRENT_ONLY_READS.has(property)) {
+          return isCurrent ? live[property] : createCurrentOnlyRefusal(entity, property, coordinate);
+        }
+        return createReadOnlyRefusal(entity, property, coordinate);
+      }
+      return Reflect.get(target2, property, receiver);
+    },
+    has(target2, property) {
+      return typeof property === "string" && Object.hasOwn(live, property) || Reflect.has(target2, property);
+    },
+    set() {
+      return false;
+    },
+    defineProperty() {
+      return false;
+    },
+    deleteProperty() {
+      return false;
+    }
+  });
+}
+function pinnedNodeCollection(live, coordinate) {
+  const temporal = withCoordinate(coordinate);
+  const reads = {
+    getById: (id) => live.getById(id, temporal),
+    getByIds: (ids) => live.getByIds(ids, temporal),
+    // `live.find` is the NodeCollection read, not Array#find — the
+    // (filter, temporal) shape trips the array-method heuristics.
+    // eslint-disable-next-line unicorn/no-array-callback-reference, unicorn/no-array-method-this-argument
+    find: (filter) => live.find(filter, temporal),
+    count: () => live.count(temporal)
+  };
+  return readOnlyCollectionProxy(
+    reads,
+    live,
+    coordinate,
+    "node"
+  );
+}
+function pinnedEdgeCollection(live, coordinate) {
+  const temporal = withCoordinate(coordinate);
+  const reads = {
+    getById: (id) => live.getById(id, temporal),
+    getByIds: (ids) => live.getByIds(ids, temporal),
+    // `live.find` is the EdgeCollection read, not Array#find — the
+    // (filter, temporal) shape trips the array-method heuristics.
+    // eslint-disable-next-line unicorn/no-array-callback-reference, unicorn/no-array-method-this-argument
+    find: (filter) => live.find(filter, temporal),
+    count: (filter) => live.count(filter, temporal),
+    findFrom: (from) => live.findFrom(from, temporal),
+    findTo: (to) => live.findTo(to, temporal),
+    findByEndpoints: (from, to, options) => live.findByEndpoints(from, to, options, temporal)
+  };
+  return readOnlyCollectionProxy(reads, live, coordinate, "edge");
+}
+function pinnedCollections(live, coordinate, wrap) {
+  const cache = /* @__PURE__ */ new Map();
+  return new Proxy(
+    {},
+    {
+      get(_target, kind) {
+        if (typeof kind !== "string" || NON_KIND_KEYS.has(kind)) return;
+        const cached = cache.get(kind);
+        if (cached !== void 0) return cached;
+        const wrapped = wrap(live[kind], coordinate);
+        cache.set(kind, wrapped);
+        return wrapped;
+      }
+    }
+  );
+}
+var READ_SEARCH_METHOD_NAMES = [
+  "fulltext",
+  "vector",
+  "hybrid"
+];
+var READ_SEARCH_METHODS = new Set(
+  READ_SEARCH_METHOD_NAMES
+);
+function searchRefusal(method, coordinate, isCurrent) {
+  return isCurrent ? new ConfigurationError(
+    `store.search.${method} is a maintenance write and is not available on a read-only StoreView. Run it on the live Store.`,
+    {
+      code: "STORE_VIEW_READ_ONLY",
+      method,
+      ...coordinateContext(coordinate)
+    }
+  ) : new ConfigurationError(
+    `store.search.${method} is not available on a StoreView (${describeCoordinate(coordinate)}). The fulltext / vector index reflects current state only; historical relevance is out of scope for a temporal view. Use a current-mode view or query the live Store.`,
+    {
+      code: "STORE_VIEW_SEARCH_UNSUPPORTED",
+      method,
+      ...coordinateContext(coordinate)
+    }
+  );
+}
+function pinnedSearch(store, coordinate) {
+  const isCurrent = coordinate.valid.mode === "current";
+  const live = isCurrent ? store.search : void 0;
+  return new Proxy({}, {
+    get(target, method, receiver) {
+      if (typeof method !== "string" || NON_KIND_KEYS.has(method)) {
+        return;
+      }
+      if (Object.hasOwn(Object.prototype, method)) {
+        const inheritedValue = Reflect.get(target, method, receiver);
+        return inheritedValue;
+      }
+      if (live !== void 0 && READ_SEARCH_METHODS.has(method)) {
+        return (...args) => live[method](...args);
+      }
+      return () => Promise.reject(searchRefusal(method, coordinate, isCurrent));
+    }
+  });
+}
+var StoreView = class {
+  #store;
+  #coordinate;
+  #nodes;
+  #edges;
+  #search;
+  constructor(store, coordinate) {
+    this.#store = store;
+    this.#coordinate = resolveReadCoordinate(
+      coordinate.mode,
+      coordinate.asOf,
+      'Use store.asOf("2026-01-01T00:00:00.000Z") or store.view({ mode: "asOf", asOf }).'
+    );
+  }
+  /** The temporal mode this view reads in. */
+  get mode() {
+    return this.#coordinate.valid.mode;
+  }
+  /** The pinned `asOf` timestamp, or `undefined` for non-`asOf` modes. */
+  get asOf() {
+    return this.#coordinate.valid.asOf;
+  }
+  /** Read-only node collections pinned to this view's coordinate. */
+  get nodes() {
+    this.#nodes ??= pinnedCollections(
+      this.#store.nodes,
+      this.#coordinate,
+      pinnedNodeCollection
+    );
+    return this.#nodes;
+  }
+  /** Read-only edge collections pinned to this view's coordinate. */
+  get edges() {
+    this.#edges ??= pinnedCollections(
+      this.#store.edges,
+      this.#coordinate,
+      pinnedEdgeCollection
+    );
+    return this.#edges;
+  }
+  /**
+   * A query builder pinned to this view's coordinate. The temporal axis is
+   * sealed: calling `.temporal(...)` on the returned builder throws, so the
+   * view's coordinate cannot be overridden on a per-query basis.
+   */
+  query() {
+    return this.#store.sealedQuery(this.#coordinate);
+  }
+  /** Extracts a subgraph at this view's pinned coordinate. */
+  subgraph(rootId, options) {
+    return this.#store.subgraph(rootId, {
+      ...options,
+      ...withCoordinate(this.#coordinate)
+    });
+  }
+  /** Shortest path between two nodes at this view's pinned coordinate. */
+  shortestPath(from, to, options) {
+    return this.#store.algorithms.shortestPath(from, to, {
+      ...options,
+      ...withCoordinate(this.#coordinate)
+    });
+  }
+  /** Nodes reachable from `from` at this view's pinned coordinate. */
+  reachable(from, options) {
+    return this.#store.algorithms.reachable(from, {
+      ...options,
+      ...withCoordinate(this.#coordinate)
+    });
+  }
+  /** Whether `to` is reachable from `from` at this view's pinned coordinate. */
+  canReach(from, to, options) {
+    return this.#store.algorithms.canReach(from, to, {
+      ...options,
+      ...withCoordinate(this.#coordinate)
+    });
+  }
+  /** The k-hop neighborhood of `node` at this view's pinned coordinate. */
+  neighbors(node, options) {
+    return this.#store.algorithms.neighbors(node, {
+      ...options,
+      ...withCoordinate(this.#coordinate)
+    });
+  }
+  /** Counts active edges incident to `node` at this view's pinned coordinate. */
+  degree(node, options) {
+    return this.#store.algorithms.degree(node, {
+      ...options,
+      ...withCoordinate(this.#coordinate)
+    });
+  }
+  /**
+   * Read-only search facade. On a `current` view the read methods
+   * (`fulltext` / `vector` / `hybrid`) delegate to the live `store.search`,
+   * while the mutating `rebuildFulltext` is refused — the view is read-only.
+   * On any non-`current` pin every search method refuses: the fulltext /
+   * vector index reflects current state only, so historical relevance is
+   * out of scope.
+   */
+  get search() {
+    this.#search ??= pinnedSearch(this.#store, this.#coordinate);
+    return this.#search;
+  }
+};
+
 // src/query/subquery-utils.ts
 function normalizeValueType(valueType) {
   if (valueType === void 0 || valueType === "unknown") {
@@ -2505,7 +2846,7 @@ function runVectorPredicatePass(ast, dialect, vectorStrategy) {
         `Vector minScore must be a finite number, got ${String(minScore)}`
       );
     }
-    if (vectorPredicate.metric === "cosine" && (minScore < -1 || minScore > 1)) {
+    if (vectorPredicate.metric === "cosine" && Math.abs(minScore) > 1) {
       throw new UnsupportedPredicateError(
         `Cosine minScore must be between -1 and 1, got ${String(minScore)}`
       );
@@ -3604,6 +3945,11 @@ function defineSubgraphProject(_graph) {
 }
 async function executeSubgraph(params) {
   const { options } = params;
+  const { valid: coordinate } = resolveReadCoordinate(
+    options.temporalMode ?? params.graph.defaults.temporalMode,
+    options.asOf
+  );
+  const temporalMode = coordinate.mode;
   const maxDepth = Math.min(
     options.maxDepth ?? DEFAULT_SUBGRAPH_MAX_DEPTH,
     MAX_EXPLICIT_RECURSIVE_DEPTH
@@ -3617,8 +3963,8 @@ async function executeSubgraph(params) {
     excludeRoot: options.excludeRoot ?? false,
     direction: options.direction ?? "out",
     cyclePolicy: options.cyclePolicy ?? "prevent",
-    temporalMode: options.temporalMode ?? params.graph.defaults.temporalMode,
-    asOf: options.asOf,
+    temporalMode,
+    asOf: coordinate.asOf,
     dialect: params.dialect,
     schema: params.schema ?? DEFAULT_SQL_SCHEMA,
     backend: params.backend
@@ -8405,27 +8751,34 @@ var QueryBuilder = class _QueryBuilder {
    * Sets temporal mode.
    *
    * @param mode - The temporal mode to use
-   * @param asOf - Required timestamp for "asOf" mode (ISO 8601 string)
-   * @throws ValidationError if mode is "asOf" but no timestamp is provided
+   * @param asOf - Required timestamp for "asOf" mode (ISO 8601 string).
+   *   Rejected for every other mode — pinning an instant is only meaningful
+   *   in "asOf" mode, so `temporal("current", t)` is a caller error, not a
+   *   silently-dropped argument.
+   * @throws ValidationError if mode is "asOf" but no timestamp is provided, or
+   *   if an asOf is supplied with a non-"asOf" mode.
    */
   temporal(mode, asOf) {
-    if (mode === "asOf" && asOf === void 0) {
-      throw new ValidationError(
-        'Temporal mode "asOf" requires a timestamp',
-        {
-          issues: [
-            { path: "asOf", message: "Timestamp is required for asOf mode" }
-          ]
-        },
+    if (this.#config.sealedCoordinate !== void 0) {
+      const coordinate2 = this.#config.sealedCoordinate;
+      throw new ConfigurationError(
+        `.temporal() is not available on a StoreView query \u2014 the view's temporal coordinate (${describeCoordinate(coordinate2)}) is sealed. Re-coordinate on the live Store via store.query() or store.view(...).`,
         {
-          suggestion: `Use .temporal("asOf", "2024-01-15T10:00:00.000Z") or .temporal("current") for current time.`
+          code: "STORE_VIEW_SEALED_QUERY",
+          ...coordinateContext(coordinate2),
+          requestedMode: mode
         }
       );
     }
+    const coordinate = resolveReadCoordinate(
+      mode,
+      asOf,
+      `Use .temporal("asOf", "2024-01-15T10:00:00.000Z") or .temporal("current") for current time.`
+    );
     return new _QueryBuilder(this.#config, {
       ...this.#state,
-      temporalMode: mode,
-      asOf
+      temporalMode: coordinate.valid.mode,
+      asOf: coordinate.valid.asOf
     });
   }
   /**
@@ -9100,8 +9453,12 @@ function createQueryBuilder(graphId, registry, options) {
     defaultTraversalExpansion: options?.defaultTraversalExpansion ?? "inverse",
     ...options?.backend !== void 0 && { backend: options.backend },
     ...options?.dialect !== void 0 && { dialect: options.dialect },
-    ...options?.schema !== void 0 && { schema: options.schema }
+    ...options?.schema !== void 0 && { schema: options.schema },
+    ...options?.sealedCoordinate !== void 0 && {
+      sealedCoordinate: options.sealedCoordinate
+    }
   };
+  const sealed = options?.sealedCoordinate?.valid;
   const initialState = {
     startAlias: "",
     currentAlias: "",
@@ -9113,8 +9470,8 @@ function createQueryBuilder(graphId, registry, options) {
     orderBy: [],
     limit: void 0,
     offset: void 0,
-    temporalMode: "current",
-    asOf: void 0,
+    temporalMode: sealed?.mode ?? "current",
+    asOf: sealed?.asOf,
     groupBy: void 0,
     having: void 0,
     fusion: void 0,
@@ -10511,9 +10868,13 @@ function extractEdgeTypes(graph) {
 var DEFAULT_ALGORITHM_MAX_HOPS = 10;
 var DEFAULT_NEIGHBOR_DEPTH = 1;
 function resolveTemporalOptions(ctx, options) {
+  const { valid } = resolveReadCoordinate(
+    options.temporalMode ?? ctx.defaultTemporalMode,
+    options.asOf
+  );
   return {
-    temporalMode: options.temporalMode ?? ctx.defaultTemporalMode,
-    ...options.asOf !== void 0 && { asOf: options.asOf }
+    temporalMode: valid.mode,
+    ...valid.asOf !== void 0 && { asOf: valid.asOf }
   };
 }
 function resolveTemporalFilter(ctx, options, tableAlias) {
@@ -10792,31 +11153,34 @@ function createEdgeCollection(config) {
     executeUpsertUpdate: executeEdgeUpsertUpdate2,
     executeDelete: executeEdgeDelete2,
     executeHardDelete: executeEdgeHardDelete2,
-    matchesTemporalMode
+    temporalRowMatcher
   } = config;
   const mapRows = (rows) => rows.map((row) => narrowEdge(rowToEdge2(row)));
-  async function findEdgesFrom(from, target) {
-    const rows = await target.findEdgesByKind({
+  function buildEndpointFindParams(endpoint, options) {
+    return {
       graphId,
       kind,
-      fromKind: from.kind,
-      fromId: from.id,
-      excludeDeleted: true
-    });
+      ...endpoint,
+      ...resolveTemporalReadParams(options, defaultTemporalMode)
+    };
+  }
+  async function findEdgesFrom(from, target, options) {
+    const rows = await target.findEdgesByKind(
+      buildEndpointFindParams(
+        { fromKind: from.kind, fromId: from.id },
+        options
+      )
+    );
     return mapRows(rows);
   }
-  async function findEdgesTo(to, target) {
-    const rows = await target.findEdgesByKind({
-      graphId,
-      kind,
-      toKind: to.kind,
-      toId: to.id,
-      excludeDeleted: true
-    });
+  async function findEdgesTo(to, target, options) {
+    const rows = await target.findEdgesByKind(
+      buildEndpointFindParams({ toKind: to.kind, toId: to.id }, options)
+    );
     return mapRows(rows);
   }
-  function buildFindByEndpointsOptions(options) {
-    const result = {};
+  function buildFindByEndpointsOptions(options, temporal) {
+    const result = { ...resolveTemporalReadParams(temporal, defaultTemporalMode) };
     if (options?.matchOn !== void 0)
       result.matchOn = options.matchOn;
     if (options?.props !== void 0) result.props = options.props;
@@ -10834,11 +11198,12 @@ function createEdgeCollection(config) {
       const row = await backend.getEdge(graphId, id);
       if (!row) return void 0;
       if (row.kind !== kind) return void 0;
-      if (!matchesTemporalMode(row, options)) return void 0;
+      if (!temporalRowMatcher(options)(row)) return void 0;
       return narrowEdge(rowToEdge2(row));
     },
     async getByIds(ids, options) {
       if (ids.length === 0) return [];
+      const matches = temporalRowMatcher(options);
       if (backend.getEdges !== void 0) {
         const rows = await backend.getEdges(graphId, ids);
         const rowMap = /* @__PURE__ */ new Map();
@@ -10849,7 +11214,7 @@ function createEdgeCollection(config) {
           const row = rowMap.get(id);
           if (!row) return;
           if (row.kind !== kind) return;
-          if (!matchesTemporalMode(row, options)) return;
+          if (!matches(row)) return;
           return narrowEdge(rowToEdge2(row));
         });
       }
@@ -10858,7 +11223,7 @@ function createEdgeCollection(config) {
           const row = await backend.getEdge(graphId, id);
           if (!row) return;
           if (row.kind !== kind) return;
-          if (!matchesTemporalMode(row, options)) return;
+          if (!matches(row)) return;
           return narrowEdge(rowToEdge2(row));
         })
       );
@@ -10870,19 +11235,19 @@ function createEdgeCollection(config) {
       );
       return narrowEdge(result);
     },
-    async findFrom(from) {
-      return findEdgesFrom(from, backend);
+    async findFrom(from, options) {
+      return findEdgesFrom(from, backend, options);
     },
-    async findTo(to) {
-      return findEdgesTo(to, backend);
+    async findTo(to, options) {
+      return findEdgesTo(to, backend, options);
     },
-    batchFindFrom(from) {
-      return { executeOn: (target) => findEdgesFrom(from, target) };
+    batchFindFrom(from, options) {
+      return { executeOn: (target) => findEdgesFrom(from, target, options) };
     },
-    batchFindTo(to) {
-      return { executeOn: (target) => findEdgesTo(to, target) };
+    batchFindTo(to, options) {
+      return { executeOn: (target) => findEdgesTo(to, target, options) };
     },
-    batchFindByEndpoints(from, to, options) {
+    batchFindByEndpoints(from, to, options, temporal) {
       return {
         executeOn: async (target) => {
           const result = await config.executeFindByEndpoints(
@@ -10892,7 +11257,7 @@ function createEdgeCollection(config) {
             to.kind,
             to.id,
             target,
-            buildFindByEndpointsOptions(options)
+            buildFindByEndpointsOptions(options, temporal)
           );
           return result === void 0 ? [] : [narrowEdge(result)];
         }
@@ -10904,50 +11269,38 @@ function createEdgeCollection(config) {
     async hardDelete(id) {
       await executeEdgeHardDelete2(id, backend);
     },
-    async find(options) {
-      const untypedOptions = options;
-      if (untypedOptions?.where !== void 0) {
+    async find(filter, temporal) {
+      const untypedFilter = filter;
+      if (untypedFilter?.where !== void 0) {
         throw new UnsupportedPredicateError(
           `store.edges.${kind}.find({ where }) is not supported. Use store.query().traverse(...).whereEdge(...) for edge property filters.`,
           { kind, operation: "find" }
         );
       }
-      const mode = options?.temporalMode ?? defaultTemporalMode;
       const params = {
         graphId,
         kind,
-        excludeDeleted: mode !== "includeTombstones",
-        temporalMode: mode
+        ...resolveTemporalReadParams(temporal, defaultTemporalMode)
       };
-      if (mode === "current" || mode === "asOf") {
-        params.asOf = options?.asOf ?? nowIso();
-      }
-      if (options?.from?.kind !== void 0)
-        params.fromKind = options.from.kind;
-      if (options?.from?.id !== void 0) params.fromId = options.from.id;
-      if (options?.to?.kind !== void 0) params.toKind = options.to.kind;
-      if (options?.to?.id !== void 0) params.toId = options.to.id;
-      if (options?.limit !== void 0) params.limit = options.limit;
-      if (options?.offset !== void 0) params.offset = options.offset;
+      if (filter?.from?.kind !== void 0) params.fromKind = filter.from.kind;
+      if (filter?.from?.id !== void 0) params.fromId = filter.from.id;
+      if (filter?.to?.kind !== void 0) params.toKind = filter.to.kind;
+      if (filter?.to?.id !== void 0) params.toId = filter.to.id;
+      if (filter?.limit !== void 0) params.limit = filter.limit;
+      if (filter?.offset !== void 0) params.offset = filter.offset;
       const rows = await backend.findEdgesByKind(params);
       return mapRows(rows);
     },
-    async count(options) {
-      const mode = options?.temporalMode ?? defaultTemporalMode;
+    async count(filter, temporal) {
       const params = {
         graphId,
         kind,
-        excludeDeleted: mode !== "includeTombstones",
-        temporalMode: mode
+        ...resolveTemporalReadParams(temporal, defaultTemporalMode)
       };
-      if (mode === "current" || mode === "asOf") {
-        params.asOf = options?.asOf ?? nowIso();
-      }
-      if (options?.from?.kind !== void 0)
-        params.fromKind = options.from.kind;
-      if (options?.from?.id !== void 0) params.fromId = options.from.id;
-      if (options?.to?.kind !== void 0) params.toKind = options.to.kind;
-      if (options?.to?.id !== void 0) params.toId = options.to.id;
+      if (filter?.from?.kind !== void 0) params.fromKind = filter.from.kind;
+      if (filter?.from?.id !== void 0) params.fromId = filter.from.id;
+      if (filter?.to?.kind !== void 0) params.toKind = filter.to.kind;
+      if (filter?.to?.id !== void 0) params.toId = filter.to.id;
       return backend.countEdgesByKind(params);
     },
     async bulkCreate(items) {
@@ -11048,7 +11401,7 @@ function createEdgeCollection(config) {
       }
       await deleteAll(backend);
     },
-    async findByEndpoints(from, to, options) {
+    async findByEndpoints(from, to, options, temporal) {
       const result = await config.executeFindByEndpoints(
         kind,
         from.kind,
@@ -11056,7 +11409,7 @@ function createEdgeCollection(config) {
         to.kind,
         to.id,
         backend,
-        buildFindByEndpointsOptions(options)
+        buildFindByEndpointsOptions(options, temporal)
       );
       return result === void 0 ? void 0 : narrowEdge(result);
     },
@@ -11171,7 +11524,7 @@ function createNodeCollection(config) {
     executeUpsertUpdate: executeNodeUpsertUpdate2,
     executeDelete: executeNodeDelete2,
     executeHardDelete: executeNodeHardDelete2,
-    matchesTemporalMode,
+    temporalRowMatcher,
     createQuery,
     executeGetOrCreateByConstraint,
     executeBulkGetOrCreateByConstraint,
@@ -11193,16 +11546,17 @@ function createNodeCollection(config) {
     async getById(id, options) {
       const row = await backend.getNode(graphId, kind, id);
       if (!row) return void 0;
-      if (!matchesTemporalMode(row, options)) return void 0;
+      if (!temporalRowMatcher(options)(row)) return void 0;
       return narrowNode(rowToNode2(row));
     },
     async getByIds(ids, options) {
       if (ids.length === 0) return [];
       const rowsById = await getNodeRowsByIds(backend, graphId, kind, ids);
+      const matches = temporalRowMatcher(options);
       return ids.map((id) => {
         const row = rowsById.get(id);
         if (!row) return;
-        if (!matchesTemporalMode(row, options)) return;
+        if (!matches(row)) return;
         return narrowNode(rowToNode2(row));
       });
     },
@@ -11219,50 +11573,40 @@ function createNodeCollection(config) {
     async hardDelete(id) {
       await executeNodeHardDelete2(kind, id, backend);
     },
-    async find(options) {
-      if (options?.where !== void 0 && createQuery === void 0) {
+    async find(filter, temporal) {
+      if (filter?.where !== void 0 && createQuery === void 0) {
         throw new ConfigurationError(
           `store.nodes.${kind}.find({ where }) requires a query-capable store`,
           { kind, operation: "find" }
         );
       }
-      if (options?.where !== void 0 && createQuery !== void 0) {
-        const mode2 = options.temporalMode ?? defaultTemporalMode;
-        let query = createQuery().from(kind, "_n").temporal(
-          mode2,
-          mode2 === "asOf" ? options.asOf ?? nowIso() : void 0
-        ).whereNode("_n", options.where).select((ctx) => ctx._n);
-        if (options.limit !== void 0) query = query.limit(options.limit);
-        if (options.offset !== void 0) query = query.offset(options.offset);
+      if (filter?.where !== void 0 && createQuery !== void 0) {
+        const { temporalMode, asOf } = resolveTemporalReadParams(
+          temporal,
+          defaultTemporalMode
+        );
+        let query = createQuery().from(kind, "_n").temporal(asOf === void 0 ? temporalMode : "asOf", asOf).whereNode("_n", filter.where).select((ctx) => ctx._n);
+        if (filter.limit !== void 0) query = query.limit(filter.limit);
+        if (filter.offset !== void 0) query = query.offset(filter.offset);
         const results = await query.execute();
         return results;
       }
-      const mode = options?.temporalMode ?? defaultTemporalMode;
       const params = {
         graphId,
         kind,
-        excludeDeleted: mode !== "includeTombstones",
-        temporalMode: mode
+        ...resolveTemporalReadParams(temporal, defaultTemporalMode)
       };
-      if (mode === "current" || mode === "asOf") {
-        params.asOf = options?.asOf ?? nowIso();
-      }
-      if (options?.limit !== void 0) params.limit = options.limit;
-      if (options?.offset !== void 0) params.offset = options.offset;
+      if (filter?.limit !== void 0) params.limit = filter.limit;
+      if (filter?.offset !== void 0) params.offset = filter.offset;
       const rows = await backend.findNodesByKind(params);
       return rows.map((row) => narrowNode(rowToNode2(row)));
     },
-    async count(options) {
-      const mode = options?.temporalMode ?? defaultTemporalMode;
+    async count(temporal) {
       const params = {
         graphId,
         kind,
-        excludeDeleted: mode !== "includeTombstones",
-        temporalMode: mode
+        ...resolveTemporalReadParams(temporal, defaultTemporalMode)
       };
-      if (mode === "current" || mode === "asOf") {
-        params.asOf = options?.asOf ?? nowIso();
-      }
       return backend.countNodesByKind(params);
     },
     async upsertById(id, props, options) {
@@ -12593,8 +12937,11 @@ async function validateAndPrepareEdgeCreate(ctx, input, id, backend) {
     kind,
     operation: "create"
   });
-  const validFrom = validateOptionalIsoDate(input.validFrom, "validFrom");
-  const validTo = validateOptionalIsoDate(input.validTo, "validTo");
+  const validFrom = validateOptionalCanonicalIsoDate(
+    input.validFrom,
+    "validFrom"
+  );
+  const validTo = validateOptionalCanonicalIsoDate(input.validTo, "validTo");
   const cardinality = registration.cardinality ?? "many";
   const constraintContext = {
     graphId: ctx.graphId,
@@ -12744,7 +13091,7 @@ async function executeEdgeUpdate(ctx, input, backend) {
       operation: "update",
       id
     });
-    const validTo = validateOptionalIsoDate(input.validTo, "validTo");
+    const validTo = validateOptionalCanonicalIsoDate(input.validTo, "validTo");
     const updateParams = {
       graphId: ctx.graphId,
       id,
@@ -12770,7 +13117,7 @@ async function executeEdgeUpsertUpdate(ctx, input, backend, options) {
     operation: "update",
     id
   });
-  const validTo = validateOptionalIsoDate(input.validTo, "validTo");
+  const validTo = validateOptionalCanonicalIsoDate(input.validTo, "validTo");
   const updateParams = {
     graphId: ctx.graphId,
     id,
@@ -12910,7 +13257,11 @@ async function executeEdgeFindByEndpoints(ctx, kind, fromKind, fromId, toKind, t
     fromId,
     toKind,
     toId,
-    excludeDeleted: true
+    excludeDeleted: options?.excludeDeleted ?? true,
+    ...options?.temporalMode !== void 0 && {
+      temporalMode: options.temporalMode
+    },
+    ...options?.asOf !== void 0 && { asOf: options.asOf }
   });
   if (candidateRows.length === 0) return void 0;
   if (matchOn.length === 0) return rowToEdge(candidateRows[0]);
@@ -13460,8 +13811,11 @@ async function validateAndPrepareNodeCreate(ctx, input, id, backend) {
     kind,
     operation: "create"
   });
-  const validFrom = validateOptionalIsoDate(input.validFrom, "validFrom");
-  const validTo = validateOptionalIsoDate(input.validTo, "validTo");
+  const validFrom = validateOptionalCanonicalIsoDate(
+    input.validFrom,
+    "validFrom"
+  );
+  const validTo = validateOptionalCanonicalIsoDate(input.validTo, "validTo");
   const existingNode = await backend.getNode(ctx.graphId, kind, id);
   if (existingNode && !existingNode.deleted_at) {
     throw createNodeAlreadyExistsError(kind, id);
@@ -13535,7 +13889,7 @@ async function performNodeUpdate(ctx, input, backend, options) {
     operation: "update",
     id
   });
-  const validTo = validateOptionalIsoDate(input.validTo, "validTo");
+  const validTo = validateOptionalCanonicalIsoDate(input.validTo, "validTo");
   await updateUniquenessEntries(
     createUniquenessContext(ctx.graphId, ctx.registry, backend),
     kind,
@@ -14604,7 +14958,7 @@ var Store = class _Store {
       ),
       executeDelete: (kind, id, backend) => executeNodeDelete(ctx, kind, id, backend),
       executeHardDelete: (kind, id, backend) => executeNodeHardDelete(ctx, kind, id, backend),
-      matchesTemporalMode: (row, options) => this.#matchesTemporalMode(row, options),
+      temporalRowMatcher: (options) => this.#temporalRowMatcher(options),
       createQuery: () => this.query(),
       executeGetOrCreateByConstraint: (kind, constraintName, props, backend, options) => executeNodeGetOrCreateByConstraint(
         ctx,
@@ -14655,7 +15009,7 @@ var Store = class _Store {
       executeUpsertUpdate: (input, backend, options) => executeEdgeUpsertUpdate(ctx, input, backend, options),
       executeDelete: (id, backend) => executeEdgeDelete(ctx, id, backend),
       executeHardDelete: (id, backend) => executeEdgeHardDelete(ctx, id, backend),
-      matchesTemporalMode: (row, options) => this.#matchesTemporalMode(row, options),
+      temporalRowMatcher: (options) => this.#temporalRowMatcher(options),
       createQuery: () => this.query(),
       executeGetOrCreateByEndpoints: (kind, fromKind, fromId, toKind, toId, props, backend, options) => executeEdgeGetOrCreateByEndpoints(
         ctx,
@@ -14703,6 +15057,78 @@ var Store = class _Store {
   query() {
     return this.#createQueryForBackend(this.#backend);
   }
+  /**
+   * Internal seam for {@link StoreView.query}: a query builder pinned to a
+   * view's {@link ReadCoordinate} with its temporal axis sealed
+   * (`.temporal()` throws). Not part of the stable public API — construct a
+   * view via {@link Store.view} / {@link Store.asOf} and call `.query()`.
+   */
+  sealedQuery(coordinate) {
+    return this.#createQueryForBackend(this.#backend, coordinate);
+  }
+  // === Temporal Views ===
+  /**
+   * Returns a read-only {@link StoreView} pinned to a valid-time instant.
+   *
+   * The view routes every supported read — `nodes` / `edges` collections,
+   * `query()`, `subgraph()`, and the graph algorithms — through the
+   * `asOf` coordinate, so they observe the graph as it was valid at `T`.
+   * Writes stay on the live `Store`. Mirrors Datomic's `(d/as-of db t)`.
+   *
+   * @example
+   * ```typescript
+   * const past = store.asOf("2026-01-01T00:00:00.000Z");
+   * const alice = await past.nodes.Person.getById(aliceId);
+   * const names = await past
+   *   .query()
+   *   .from("Person", "p")
+   *   .whereNode("p", (p) => p.name.eq("Alice"))
+   *   .select((ctx) => ctx.p.name)
+   *   .execute();
+   * ```
+   *
+   * @param asOf - ISO-8601 timestamp to pin the valid-time coordinate to.
+   */
+  asOf(asOf) {
+    return new StoreView(this, { mode: "asOf", asOf });
+  }
+  /**
+   * Returns a read-only {@link StoreView} pinned to an arbitrary public
+   * temporal mode. Use {@link Store.asOf} for the common valid-time case;
+   * reach for `view` to pin `"current"`, `"includeEnded"`, or
+   * `"includeTombstones"`.
+   *
+   * @example
+   * ```typescript
+   * const withTombstones = store.view({ mode: "includeTombstones" });
+   * const everyEverVersion = await withTombstones.nodes.Person.find();
+   * ```
+   *
+   * @param coordinate - The `(mode, asOf)` coordinate to pin. `asOf` is
+   *   required when `mode` is `"asOf"` and rejected for every other mode.
+   */
+  view(coordinate) {
+    return new StoreView(this, coordinate);
+  }
+  /**
+   * Returns a read-only {@link StoreView} pinned to the current instant,
+   * captured once at construction — a stable point-in-time snapshot. Unlike
+   * `store.view({ mode: "current" })` (which tracks "now" live and can read
+   * different surfaces against slightly different clocks), a snapshot pins one
+   * `asOf` timestamp, so every surface observes the same instant. Sugar for
+   * `store.asOf(new Date().toISOString())`; mirrors Datomic's `(d/db conn)`.
+   *
+   * @example
+   * ```typescript
+   * const snap = store.snapshot();
+   * // Every read on `snap` sees the graph as of one fixed instant.
+   * const a = await snap.nodes.Person.find();
+   * const r = await snap.reachable(rootId, { edges: ["knows"] });
+   * ```
+   */
+  snapshot() {
+    return this.asOf(nowIso());
+  }
   // === Search ===
   /**
    * Search-related operations (fulltext, hybrid, and rebuild).
@@ -14877,13 +15303,24 @@ var Store = class _Store {
    *   // sequential, non-atomic — handle partial-failure recovery yourself
    * }
    * ```
+   *
+   * @param fn The callback run inside the transaction boundary.
+   * @param options Optional {@link TransactionOptions} forwarded to the
+   *   backend (e.g. `isolationLevel: "serializable"` on Postgres). Backends
+   *   without isolation-level support ignore it; the non-transactional
+   *   fallback ignores it entirely.
    */
-  async transaction(fn) {
+  async transaction(fn, options) {
     if (!this.#backend.capabilities.transactions) {
-      return fn({ nodes: this.nodes, edges: this.edges });
+      return fn({
+        nodes: this.nodes,
+        edges: this.edges,
+        backend: this.#backend
+      });
     }
     return this.#backend.transaction(
-      async (txBackend, sql18) => fn(this.#buildTransactionContext(txBackend, sql18))
+      async (txBackend, sql18) => fn(this.#buildTransactionContext(txBackend, sql18)),
+      options
     );
   }
   /**
@@ -14983,7 +15420,7 @@ var Store = class _Store {
       txBackend,
       txEdgeOperations
     );
-    return sql18 === void 0 ? { nodes, edges } : { nodes, edges, sql: sql18 };
+    return sql18 === void 0 ? { nodes, edges, backend: txBackend } : { nodes, edges, sql: sql18, backend: txBackend };
   }
   // === Graph Lifecycle ===
   /**
@@ -15687,33 +16124,40 @@ var Store = class _Store {
     }
   }
   // === Internal: Temporal Filtering ===
-  #matchesTemporalMode(row, options) {
-    const mode = options?.temporalMode ?? this.#graph.defaults.temporalMode;
-    const asOf = options?.asOf ?? nowIso();
-    switch (mode) {
-      case "current":
-      case "asOf": {
-        if (row.deleted_at) return false;
-        if (row.valid_from && asOf < row.valid_from) return false;
-        if (row.valid_to && asOf >= row.valid_to) return false;
-        return true;
-      }
-      case "includeEnded": {
-        return !row.deleted_at;
-      }
-      case "includeTombstones": {
-        return true;
+  #temporalRowMatcher(options) {
+    const { temporalMode, asOf } = resolveTemporalReadParams(
+      options,
+      this.#graph.defaults.temporalMode
+    );
+    return (row) => {
+      switch (temporalMode) {
+        case "current":
+        case "asOf": {
+          if (row.deleted_at) return false;
+          if (asOf !== void 0 && row.valid_from && asOf < row.valid_from)
+            return false;
+          if (asOf !== void 0 && row.valid_to && asOf >= row.valid_to)
+            return false;
+          return true;
+        }
+        case "includeEnded": {
+          return !row.deleted_at;
+        }
+        case "includeTombstones": {
+          return true;
+        }
       }
-    }
+    };
   }
-  #createQueryForBackend(backend) {
+  #createQueryForBackend(backend, sealedCoordinate) {
     return createQueryBuilder(this.graphId, this.#registry, {
       // TransactionBackend omits transaction/close, but query execution only needs
       // the read-path/query capabilities shared with GraphBackend.
       backend,
       dialect: backend.dialect,
       defaultTraversalExpansion: this.#defaultTraversalExpansion,
-      ...this.#schema !== void 0 && { schema: this.#schema }
+      ...this.#schema !== void 0 && { schema: this.#schema },
+      ...sealedCoordinate !== void 0 && { sealedCoordinate }
     });
   }
 };
@@ -15782,6 +16226,6 @@ async function createVerifiedStore(graph, backend, options) {
   return [store, result];
 }
 
-export { DEFAULT_SQL_SCHEMA, ExecutableAggregateQuery, ExecutableQuery, MAX_EXPLICIT_RECURSIVE_DEPTH, MAX_RECURSIVE_DEPTH, PreparedQuery, QueryBuilder, StoreSearch, UnionableQuery, avg, composeFragments, computeUniqueKey, count, countDistinct, countDistinctEdges, countEdges, createFragment, createQueryBuilder, createSqlSchema, createStore, createStoreWithSchema, createVerifiedStore, defineSubgraphProject, exists, field, fieldRef, generateId, having, havingEq, havingGt, havingGte, havingLt, havingLte, inSubquery, isParameterRef, limitFragment, max, min, notExists, notInSubquery, offsetFragment, orderByFragment, param, sum };
-//# sourceMappingURL=chunk-UIFEEPME.js.map
-//# sourceMappingURL=chunk-UIFEEPME.js.map
+export { DEFAULT_SQL_SCHEMA, ExecutableAggregateQuery, ExecutableQuery, MAX_EXPLICIT_RECURSIVE_DEPTH, MAX_RECURSIVE_DEPTH, PreparedQuery, QueryBuilder, StoreSearch, StoreView, UnionableQuery, avg, composeFragments, computeUniqueKey, count, countDistinct, countDistinctEdges, countEdges, createFragment, createQueryBuilder, createSqlSchema, createStore, createStoreWithSchema, createVerifiedStore, defineSubgraphProject, exists, field, fieldRef, generateId, having, havingEq, havingGt, havingGte, havingLt, havingLte, inSubquery, isParameterRef, limitFragment, max, min, notExists, notInSubquery, offsetFragment, orderByFragment, param, sum };
+//# sourceMappingURL=chunk-WNORITK6.js.map
+//# sourceMappingURL=chunk-WNORITK6.js.map