@nicia-ai/typegraph 0.34.0 → 0.36.0

package/dist/{store-view-D09po4H6.d.cts → store-view-9KDOpZzF.d.cts}

@@ -1,8 +1,8 @@
-import { K as KindRegistry, G as GraphDef, w as EdgeKinds, t as NodeKinds, v as AllNodeTypes, c as SchemaManagerOptions, d as SchemaValidationResult } from './manager-ms9cKdc6.cjs';
-import { T as TemporalMode, A as AnyEdgeType, N as NodeType, g as EdgeType, E as EdgeRegistration, e as EdgeId, d as NodeId, b as NodeRegistration, K as KindEntity, m as Cardinality, q as EndpointExistence, f as KindAnnotations, s as UniquenessScope, n as Collation, G as GraphExtension } from './extension-types-YGFJPrzK.cjs';
+import { K as KindRegistry, G as GraphDef, w as EdgeKinds, t as NodeKinds, v as AllNodeTypes, c as SchemaManagerOptions, d as SchemaValidationResult } from './manager-DwQi8eV0.cjs';
+import { T as TemporalMode, N as NodeType, A as AnyEdgeType, g as EdgeType, E as EdgeRegistration, d as NodeId, K as KindEntity, b as NodeRegistration, e as EdgeId, s as UniquenessScope, n as Collation, f as KindAnnotations, m as Cardinality, q as EndpointExistence, G as GraphExtension } from './extension-types-ixRpJVUp.cjs';
 import { z } from 'zod';
-import { b7 as ValueType, b8 as PredicateExpression, b9 as VectorMetricType, ae as FulltextQueryMode, Q as QueryAst, J as JsonPointer, P as FieldRef, ax as ParameterRef, G as GraphBackend, aP as TransactionBackend, ao as JsonPointerInput, aQ as TraversalExpansion, p as SqlDialect, aL as SqlSchema, ba as Traversal, bb as NodePredicate, bc as ProjectedField, aw as OrderSpec, bd as GroupBySpec, ak as HybridFusionOptions, be as RecursiveCyclePolicy, W as TraversalDirection$1, bf as EdgeRow, bg as NodeRow, aa as ExternalRecordedReadSource, X as AdoptedTransaction, L as AggregateExpr, a3 as CompiledSelectSql, F as FulltextStrategy, V as VectorStrategy, bh as VectorSlotMap, bi as RecordedReadBinding, bj as SelectiveField, bk as ComposableQuery, bl as SetOperationType, bm as SetOperation, aJ as SortDirection, bn as VectorMetric, m as JsonSchema, bo as TransactionOptions } from './types-DkNnF-7K.cjs';
-import { b as MaterializeIndexesOptions, M as MaterializeIndexesResult } from './materialize-indexes-D20xNluI.cjs';
+import { bc as ValueType, bd as PredicateExpression, ag as FulltextQueryMode, be as VectorMetricType, Q as QueryAst, J as JsonPointer, P as FieldRef, az as ParameterRef, aq as JsonPointerInput, G as GraphBackend, aS as TransactionBackend, aT as TraversalExpansion, f as SqlDialect, aO as SqlSchema, bf as Traversal, bg as NodePredicate, bh as ProjectedField, ay as OrderSpec, bi as AggregateOrderSpec, bj as GroupBySpec, am as HybridFusionOptions, bk as RecursiveCyclePolicy, W as TraversalDirection$1, bl as NodeRow, aa as ExternalRecordedReadSource, bm as EdgeRow, X as AdoptedTransaction, L as AggregateExpr, aM as SortDirection, a3 as CompiledSelectSql, F as FulltextStrategy, V as VectorStrategy, bn as VectorSlotMap, bo as RecordedReadBinding, bp as SelectiveField, bq as ComposableQuery, br as SetOperationType, bs as SetOperation, bt as VectorMetric, z as JsonSchema, bu as TransactionOptions } from './fulltext-strategy-CDkSSYhq.cjs';
+import { b as MaterializeIndexesOptions, M as MaterializeIndexesResult } from './materialize-indexes-B4e9360H.cjs';
 
 /**
  * Embedding type for vector search.
@@ -354,7 +354,11 @@ type MatchesOptions = Readonly<{
      */
     mode?: FulltextQueryMode;
     /**
-     * Language override. Default: per-row language as stored at insert time.
+     * Language override for query parsing. Default: the kind's declared
+     * language when every kind in the alias shares one (a plan-time
+     * constant, so PostgreSQL can serve the match from the GIN index);
+     * mixed-language subclass aliases fall back to the per-row language
+     * column.
      */
     language?: string;
     /** Minimum relevance score to include. */
@@ -373,6 +377,17 @@ type SimilarToOptions = Readonly<{
      * For inner_product: minimum inner product value.
      */
     minScore?: number;
+    /**
+     * Opt into approximate retrieval: each declaring kind's candidates come
+     * from the engine's native ANN structure (pgvector HNSW/IVFFlat scans,
+     * vec0 `MATCH … k=`, libSQL `vector_top_k`) instead of an exact
+     * distance scan. This is a SEMANTIC change — results are subject to the
+     * index's recall, and predicates composed alongside constrain the ANN
+     * candidate set (exact on pgvector/vec0; bounded by over-fetch on
+     * libSQL). A slot declared with `indexType: "none"` falls back to the
+     * exact scan. Default: exact.
+     */
+    approximate?: boolean;
 }>;
 /**
  * Creates a field reference.
@@ -789,9 +804,13 @@ type SelectableNodeMeta = Readonly<{
  * For aliases declared via `fromDynamic` / `toDynamic` this resolves to
  * `DynamicSelectableNode` — same wire shape, schema properties typed
  * `unknown` for narrowing at the call site.
+ *
+ * `id` carries the same `NodeId<N>` brand as `Node<N>` (see `store/types.ts`)
+ * so a projected id can be passed straight back into `getById`/`getByIds`
+ * without a cast.
  */
 type SelectableNode<N extends NodeType> = IsDynamicNodeType<N> extends true ? DynamicSelectableNode : Readonly<{
-    id: string;
+    id: NodeId<N>;
     kind: N["kind"];
     meta: SelectableNodeMeta;
 }> & Readonly<z.infer<N["schema"]>>;
@@ -813,6 +832,46 @@ type SelectableEdgeMeta = Readonly<{
  * - System metadata is under `edge.meta.*`
  *
  * Dynamic-mode counterpart: see `SelectableNode`.
+ *
+ * `traverse(edgeKind, alias)` defaults to `expand: "inverse"` (see
+ * `GraphAlgorithms`/`QueryBuilder.traverse`'s `defaultTraversalExpansion`),
+ * which UNIONs in rows for the *registered inverse* edge kind alongside the
+ * requested one — `EdgeAlias<E>`'s `E` stays pinned to the single requested
+ * kind regardless, so under the default expansion mode the row backing
+ * `alias` can genuinely be a different edge kind (with different endpoint
+ * kinds and a different props schema — `inverseOf(edgeA, edgeB)` doesn't
+ * require `edgeA`/`edgeB` to share a schema) than `E` says. Three distinct
+ * consequences follow:
+ *
+ * - `kind: E["kind"]` is a **literal type that can already be wrong today**
+ *   — not a branding gap, a plain type-accuracy gap. It's typed as the
+ *   requested kind (e.g. `"manages"`) but the runtime value can be the
+ *   inverse kind (e.g. `"managedBy"`); see the `"proves why edge
+ *   id/kind/schema props can't be trusted"` test in
+ *   `tests/query-execution.test.ts` for a concrete repro. This predates
+ *   and is independent of the id/endpoint branding question below.
+ * - The flattened `z.infer<E["schema"]>` properties have the same
+ *   type-accuracy gap as `kind`, for the same reason: `ctx.e.role` is typed
+ *   against the requested kind's schema, but an inverse-branch row's real
+ *   props came from a different schema and may not have a `role` field at
+ *   all (reading it returns `undefined`, not a type error).
+ * - `id`/`fromId`/`toId` stay plain `string`, unlike `SelectableNode`'s
+ *   `id: NodeId<N>` — a real ergonomics gap, but not an accuracy one: `string`
+ *   never overclaims. Branding them would compile but be actively wrong:
+ *   e.g. `store.edges.<E>.getById()` filters on `row.kind !== kind` and
+ *   silently returns `undefined` for a mismatched-kind id — worse than the
+ *   unsafe cast it would have replaced.
+ *
+ * Proving any of these safe requires tracking `expand` mode (`"none"` vs
+ * not) at the type level through `TraversalBuilder`/`EdgeAlias` — evaluated
+ * for #235 and deliberately not built: the machinery would touch every
+ * traversal-entry overload for a benefit that only applies when a caller
+ * opts out of the default expansion. When you know a traversal is
+ * single-kind (e.g. via `expand: "none"`), re-brand `id`/`fromId`/`toId`
+ * explicitly with `asNodeId`/`asEdgeId` (see #223) — e.g.
+ * `asNodeId<typeof Person>(edge.fromId)` for a `Person -> Company` edge —
+ * and don't trust `kind` or schema properties without independently
+ * verifying the traversal can't have expanded.
  */
 type SelectableEdge<E extends AnyEdgeType = EdgeType> = IsDynamicEdgeType<E> extends true ? DynamicSelectableEdge : Readonly<{
     id: string;
@@ -914,6 +973,8 @@ type QueryBuilderState = Readonly<{
     predicates: readonly NodePredicate[];
     projection: readonly ProjectedField[];
     orderBy: readonly OrderSpec[];
+    /** ORDER BY entries added via `ExecutableAggregateQuery.orderBy()`. */
+    aggregateOrderBy: readonly AggregateOrderSpec[];
     limit: number | undefined;
     offset: number | undefined;
     temporalMode: TemporalMode;
@@ -1196,6 +1257,82 @@ type StoreHooks = Readonly<{
 type BaseStoreOptions = Readonly<{
     /** Observability hooks for monitoring */
     hooks?: StoreHooks;
+    /**
+     * Maintain a durable, graph-wide revision anchor for TypeGraph writes:
+     * a random per-graph origin plus a monotonic revision clock. `branch()` uses
+     * this anchor to validate that its base has not moved without
+     * re-fingerprinting every live row, and cannot confuse a coincident clock in
+     * a separately created store for its original base. `history: true` enables
+     * the same tracking automatically through its recorded-time commit clock.
+     *
+     * This is intentionally opt-in for live stores: each successful graph write
+     * advances the anchor inside its write transaction. On PostgreSQL, those
+     * transactions take a graph-scoped advisory lock until commit; writes to the
+     * same graph therefore serialize. Enable it for branchable graphs, but size
+     * high-throughput multi-writer workloads for that trade-off.
+     *
+     * Writes performed directly through a backend — including raw graph-table
+     * writes through `tx.sql` — bypass the anchor and are outside the
+     * revision-tracking contract.
+     */
+    revisionTracking?: boolean;
+    /**
+     * Automatic planner-statistics refresh after large autocommit bulk
+     * writes (bulkCreate and bulkInsert on nodes and edges). Stale statistics after a
+     * bulk load are a whole class of planner cliffs: the planner keeps
+     * pre-load row estimates until ANALYZE runs. When a single
+     * autocommit bulk write reaches the threshold
+     * ({@link AUTO_REFRESH_STATISTICS_ROW_THRESHOLD} rows by default),
+     * the store runs `refreshStatistics()` after the write commits.
+     * Pass a number to change the threshold, or `false` to disable.
+     * Bulk writes inside a caller-provided transaction never
+     * auto-refresh (statistics cannot see uncommitted rows); refresh
+     * manually after commit. `importGraph` handles its own refresh.
+     */
+    autoRefreshStatistics?: false | number;
+    /**
+     * Skip the write for an `upsertById` (or `bulkUpsertById` item) whose
+     * validated props are value-identical to the existing live row. Default
+     * off.
+     *
+     * Enable this for at-least-once / replay materializers. An event log that
+     * re-delivers a byte-identical change, or a full replay that reprocesses an
+     * already-materialized log, would otherwise rewrite every row it touches:
+     * today an `upsertById` on an existing id calls `updateNode`
+     * unconditionally, allocating a fresh recorded instant and a new history row
+     * per re-delivery. A rebuild — the workload replay is recommended for — is
+     * the one that inflates recorded history most, with a dense band of
+     * "changes" that changed nothing.
+     *
+     * When enabled, an upsert that would not change the stored value performs
+     * **no write at all**: no `updateNode`, no recorded-time capture, no history
+     * row, no revision-anchor advance, and no `update` operation hooks (nothing
+     * happened, so nothing is reported). It resolves with the **existing** node,
+     * preserving its original `validFrom` / `updatedAt` / `version`.
+     *
+     * Receipt shape is unchanged and needs no new signal: a coalesced upsert
+     * still counts as one write intent (`writes.total` includes it), but
+     * captures nothing (`receipt.recorded` stays `undefined` when it is the only
+     * write) — the same shape a no-op delete already produces, so a consumer
+     * that carries the prior anchor forward on `recorded === undefined` handles
+     * it unchanged.
+     *
+     * A write is coalesced only when **all** of the following hold; otherwise the
+     * normal write happens:
+     *   1. An existing row is found for the id (else it is a create).
+     *   2. That row is not soft-deleted (a deleted row resurrects — a real
+     *      change — and is never coalesced).
+     *   3. The caller passed no explicit `validFrom` / `validTo` (an explicit
+     *      temporal override is a deliberate request and is never coalesced;
+     *      applied per item in the bulk path).
+     *   4. The new props, merged over the stored props and run through the
+     *      kind's Zod schema (defaults applied, values normalized), are deeply
+     *      value-identical to the stored props (key order aside).
+     *
+     * Default-off because some consumers *want* an audit row per re-delivery as
+     * proof the event was reprocessed; coalescing removes that signal.
+     */
+    coalesceUnchangedUpserts?: boolean;
     /** SQL schema configuration from createSqlSchema(...) for custom table names */
     schema?: SqlSchema;
     /** Query default behaviors. */
@@ -1255,6 +1392,60 @@ type StoreOptions = LiveStoreOptions | HistoryStoreOptions;
 interface StoreRef<T> {
     current: T;
 }
+/**
+ * Result plus write summary. Returned by `store.transactionWithReceipt(fn)`,
+ * `store.withRecordedTransaction(externalTx, fn)` (the adopted-commit path), and
+ * `tx.measure(fn)` (a scoped sub-receipt). See {@link TransactionReceipt}.
+ */
+type TransactionOutcome<T> = Readonly<{
+    result: T;
+    receipt: TransactionReceipt;
+}>;
+/**
+ * Transaction write summary.
+ *
+ * Receipt counts are completed write intents at the collection surface, not
+ * rows affected:
+ *
+ * 1. Every successful completion of a write method on `tx.nodes.*` /
+ *    `tx.edges.*` counts. The authoritative method list is
+ *    {@link NodeWrites} / {@link EdgeWrites}.
+ * 2. Bulk methods count by input length; an empty bulk call (`bulkCreate([])`)
+ *    counts 0.
+ * 3. Single-row methods count 1 on resolve — including `delete` of an absent
+ *    id and `getOrCreate*` that found an existing row. Consumers that need
+ *    "did anything actually change" semantics apply their own per-operation
+ *    policy.
+ * 4. A method that rejects counts 0 — even when the backend applied part of a
+ *    bulk input before failing. On SQLite a failed statement does not abort
+ *    the surrounding transaction, so a caller that catches the rejection and
+ *    commits can persist rows the receipt never counted. Do not read the
+ *    receipt as rows-affected in that scenario.
+ * 5. A node `delete` under `cascade` / `disconnect` removes connected edges
+ *    through the backend, not the edge-collection surface; those removals do
+ *    not appear in `edges`.
+ * 6. Rows-affected fidelity is intentionally out of scope for this first
+ *    version; a future extension could ask backends to return row counts.
+ */
+type TransactionReceipt = Readonly<{
+    writes: Readonly<{
+        /** Completed node write intents by node kind. */
+        nodes: Readonly<Record<string, number>>;
+        /** Completed edge write intents by edge kind. */
+        edges: Readonly<Record<string, number>>;
+        /** Sum of all node and edge write intents. */
+        total: number;
+    }>;
+    /**
+     * The recorded commit instant allocated for this store's graph by this
+     * transaction. Undefined when history capture is off, the transaction is
+     * read-only, or no captured writes were flushed. **Always undefined on a
+     * scoped receipt from {@link ScopedMeasure}** (`tx.measure`) — the recorded
+     * instant is a per-transaction flush concern allocated once when the whole
+     * transaction's capture flushes, unknowable mid-transaction.
+     */
+    recorded?: RecordedInstant;
+}>;
 /**
  * Behavior when a get-or-create operation matches an existing record.
  */
@@ -1327,7 +1518,11 @@ type EdgeGetOrCreateByEndpointsOptions<E extends AnyEdgeType> = Readonly<{
  * Provides ergonomic CRUD operations for a single node type.
  */
 type NodeCollection<N extends NodeType, CN extends string = string> = Readonly<{
-    /** Create a new node */
+    /**
+     * Create a new node.
+     *
+     * `validFrom` defaults to the operation's creation timestamp when omitted.
+     */
     create: (props: z.input<N["schema"]>, options?: Readonly<{
         id?: string;
         validFrom?: string;
@@ -1374,6 +1569,8 @@ type NodeCollection<N extends NodeType, CN extends string = string> = Readonly<{
      * Use this for dynamic dispatch (changesets, migrations, imports) where
      * the data shape is determined at runtime, not compile time.
      * The return type is fully typed — only the input gate is relaxed.
+     *
+     * `validFrom` defaults to the operation's creation timestamp when omitted.
      */
     createFromRecord: (data: Record<string, unknown>, options?: Readonly<{
         id?: string;
@@ -1385,6 +1582,9 @@ type NodeCollection<N extends NodeType, CN extends string = string> = Readonly<{
      *
      * If a node with the given ID exists, updates it with the provided props.
      * Otherwise, creates a new node with that ID.
+     *
+     * `validFrom` only applies on the create branch, defaulting to the
+     * operation's creation timestamp when omitted; it has no effect on update.
      */
     upsertById: (id: string, props: z.input<N["schema"]>, options?: Readonly<{
         validFrom?: string;
@@ -1396,6 +1596,9 @@ type NodeCollection<N extends NodeType, CN extends string = string> = Readonly<{
      * Use this for dynamic dispatch (changesets, migrations, imports) where
      * the data shape is determined at runtime, not compile time.
      * The return type is fully typed — only the input gate is relaxed.
+     *
+     * `validFrom` only applies on the create branch, defaulting to the
+     * operation's creation timestamp when omitted; it has no effect on update.
      */
     upsertByIdFromRecord: (id: string, data: Record<string, unknown>, options?: Readonly<{
         validFrom?: string;
@@ -1406,6 +1609,8 @@ type NodeCollection<N extends NodeType, CN extends string = string> = Readonly<{
      *
      * More efficient than calling create() multiple times.
      * Use `bulkInsert` for the dedicated fast path that skips returning results.
+     *
+     * `validFrom` defaults to the operation's creation timestamp when omitted.
      */
     bulkCreate: (items: readonly Readonly<{
         props: z.input<N["schema"]>;
@@ -1418,6 +1623,9 @@ type NodeCollection<N extends NodeType, CN extends string = string> = Readonly<{
      *
      * For each item, if a node with the given ID exists, updates it.
      * Otherwise, creates a new node with that ID.
+     *
+     * `validFrom` only applies on the create branch, defaulting to the
+     * operation's creation timestamp when omitted; it has no effect on update.
      */
     bulkUpsertById: (items: readonly Readonly<{
         id: string;
@@ -1431,6 +1639,8 @@ type NodeCollection<N extends NodeType, CN extends string = string> = Readonly<{
      * This is the dedicated fast path for bulk inserts. Unlike `bulkCreate`
      * with `returnResults: false`, the intent is unambiguous: no results
      * are returned and the operation is wrapped in a transaction.
+     *
+     * `validFrom` defaults to the operation's creation timestamp when omitted.
      */
     bulkInsert: (items: readonly Readonly<{
         props: z.input<N["schema"]>;
@@ -1565,6 +1775,8 @@ type EdgeCollection<E extends AnyEdgeType, From extends NodeType = NodeType, To
     /**
      * Create a new edge.
      *
+     * `validFrom` defaults to the operation's creation timestamp when omitted.
+     *
      * @param from - Source node (must be one of the allowed 'from' types)
      * @param to - Target node (must be one of the allowed 'to' types)
      * @param args - Edge properties (optional if schema is empty) and creation options
@@ -1644,6 +1856,8 @@ type EdgeCollection<E extends AnyEdgeType, From extends NodeType = NodeType, To
      *
      * More efficient than calling create() multiple times.
      * Use `bulkInsert` for the dedicated fast path that skips returning results.
+     *
+     * `validFrom` defaults to the operation's creation timestamp when omitted.
      */
     bulkCreate: (items: readonly Readonly<{
         from: NodeRef<From>;
@@ -1658,6 +1872,9 @@ type EdgeCollection<E extends AnyEdgeType, From extends NodeType = NodeType, To
      *
      * For each item, if an edge with the given ID exists, updates it.
      * Otherwise, creates a new edge with that ID.
+     *
+     * `validFrom` only applies on the create branch, defaulting to the
+     * operation's creation timestamp when omitted; it has no effect on update.
      */
     bulkUpsertById: (items: readonly Readonly<{
         id: EdgeId<E>;
@@ -1673,6 +1890,8 @@ type EdgeCollection<E extends AnyEdgeType, From extends NodeType = NodeType, To
      * This is the dedicated fast path for bulk inserts. Unlike `bulkCreate`
      * with `returnResults: false`, the intent is unambiguous: no results
      * are returned and the operation is wrapped in a transaction.
+     *
+     * `validFrom` defaults to the operation's creation timestamp when omitted.
      */
     bulkInsert: (items: readonly Readonly<{
         from: NodeRef<From>;
@@ -1861,6 +2080,14 @@ type RecordedStoreViewNodeCollections<G extends GraphDef> = {
 type RecordedStoreViewEdgeCollections<G extends GraphDef> = {
     [K in keyof G["edges"] & string]-?: TypedRecordedStoreViewEdgeCollection<G["edges"][K]>;
 };
+/**
+ * Whether — and why — `tx.sql` can be used on a transaction context. A single
+ * required discriminant covering exactly the four states raw-SQL access can be
+ * in, so a portable caller branches on capability instead of truthiness-testing
+ * `tx.sql` (which is present-but-throwing under history / revision tracking).
+ * See {@link TransactionContext.sqlAvailability} for the per-value semantics.
+ */
+type SqlAvailability = "available" | "history" | "revisionTracking" | "unavailable";
 /**
  * A typed transaction context with collection API.
  *
@@ -1902,11 +2129,44 @@ type RecordedStoreViewEdgeCollections<G extends GraphDef> = {
  * Its type is the `AdoptedTransaction` union; cast to your concrete
  * Drizzle database type at the call site.
  *
- * When the store was created with `{ history: true }`, `tx.sql` is present but
- * replaced by a fail-loud guard because raw SQL would bypass recorded-time
- * capture. Use the typed `tx.nodes` / `tx.edges` collections inside
- * `transaction()`, or use `store.withRecordedTransaction(externalTx, fn)` when
- * the relational layer owns the transaction boundary.
+ * When the store was created with `{ history: true }` or
+ * `{ revisionTracking: true }`, `tx.sql` is **present but throwing**: every
+ * access raises {@link ConfigurationError} because raw SQL would bypass
+ * recorded-time capture or the revision anchor. The static type marks it
+ * `sql?: never` so a mistaken `tx.sql.run(...)` fails to typecheck; at runtime
+ * it is a fail-loud guard, not `undefined`. Use the typed `tx.nodes` /
+ * `tx.edges` collections inside `transaction()`, or
+ * `store.withRecordedTransaction(externalTx, fn)` when the relational layer
+ * owns the transaction boundary.
+ *
+ * **Feature detection — branch on {@link sqlAvailability}, not on `tx.sql`'s
+ * truthiness.** Because `tx.sql` is present-but-throwing under history or
+ * revision tracking, `if (tx.sql)` reads truthy and then throws. The honest
+ * discriminant is `tx.sqlAvailability`:
+ *
+ * ```typescript
+ * await store.transaction(async (tx) => {
+ *   switch (tx.sqlAvailability) {
+ *     case "available": {
+ *       const sqlTx = tx.sql as NodePgDatabase; // usable raw handle
+ *       await sqlTx.insert(rows).values(row);
+ *       break;
+ *     }
+ *     case "unavailable":
+ *       // non-transactional backend: tx.sql === undefined, no atomicity
+ *       await fallbackWithoutAtomicity();
+ *       break;
+ *     case "history":
+ *     case "revisionTracking":
+ *       // raw SQL disabled here — write your own tables through the external
+ *       // handle passed to store.withRecordedTransaction instead
+ *       break;
+ *   }
+ * });
+ * ```
+ *
+ * `tx.sql === undefined` still means exactly "non-transactional fallback"
+ * (`sqlAvailability === "unavailable"`).
  *
  * @example
  * ```typescript
@@ -1921,6 +2181,26 @@ type TransactionContext<G extends GraphDef> = Readonly<{
     nodes: GraphNodeCollections<G>;
     edges: GraphEdgeCollections<G>;
     sql?: AdoptedTransaction;
+    /**
+     * Honest capability discriminant for `tx.sql` on this transaction. Prefer
+     * this over truthiness-testing `tx.sql`, which is present-but-throwing under
+     * history capture or revision tracking.
+     *
+     * - `"available"` — `tx.sql` is the usable raw handle bound to this
+     *   transaction.
+     * - `"history"` — history capture is on; `tx.sql` is present but every access
+     *   throws {@link ConfigurationError} (`details.code`
+     *   `RECORDED_CAPTURE_RAW_SQL_DISABLED`). Use `tx.nodes` / `tx.edges`, or
+     *   `store.withRecordedTransaction` with your own external handle for
+     *   cross-store atomicity.
+     * - `"revisionTracking"` — same shape as `"history"` (`details.code`
+     *   `REVISION_TRACKING_RAW_SQL_DISABLED`).
+     * - `"unavailable"` — non-transactional fallback
+     *   (`backend.capabilities.transactions === false`, e.g. Cloudflare D1,
+     *   `drizzle-orm/neon-http`); `tx.sql` is `undefined` and there is no
+     *   atomicity.
+     */
+    sqlAvailability: SqlAvailability;
     /**
      * The transaction-scoped backend the collections are bound to, for advanced
      * raw reads that must observe the transaction's snapshot (e.g. graph-merge's
@@ -1944,6 +2224,40 @@ type TransactionContext<G extends GraphDef> = Readonly<{
      */
     runNodeOperationHooks<T>(operation: "create" | "update" | "delete", kind: string, id: string, fn: () => Promise<T>): Promise<T>;
 }>;
+/**
+ * Scoped write measurement, available only on the receipt-enabled transaction
+ * contexts (`transactionWithReceipt`, `withRecordedTransaction`). Runs `fn`,
+ * passing it a **scoped context** — a second view over the same transaction — and
+ * returns a {@link TransactionOutcome} whose receipt counts exactly the writes
+ * made *through that scoped context* (`scoped.nodes` / `scoped.edges`).
+ *
+ * Attribution is by **which context you write through**, not by timing. A write
+ * through the scoped context counts in both the scope and the outer receipt (it
+ * happened in the transaction); a write through the outer `tx` during the scope
+ * counts only in the outer receipt. This makes overlapping and concurrent
+ * measures safe by construction — two scopes running under `Promise.all`, each
+ * writing through its own scoped context, never cross-count. Nesting composes:
+ * `scoped.measure(...)` opens a child scope that counts in itself, every
+ * ancestor scope, and the outer receipt.
+ *
+ * Counts otherwise inherit {@link TransactionReceipt} (bulk by input length, a
+ * rejected write counts 0). The returned receipt's `recorded` is **always
+ * `undefined`**: the recorded commit instant is a per-transaction flush concern,
+ * unknowable mid-transaction.
+ */
+type ScopedMeasure<Context> = <T>(fn: (scoped: Context) => Promise<T>) => Promise<TransactionOutcome<T>>;
+/**
+ * A {@link TransactionContext} that also exposes {@link ScopedMeasure}. Only the
+ * receipt-enabled entry points (`transactionWithReceipt`,
+ * `withRecordedTransaction`) hand a callback this type; plain `transaction()`
+ * contexts have no recorder and therefore no `measure`, keeping that path
+ * zero-overhead. Assignable to {@link TransactionContext}, so a projector helper
+ * typed `(tx: TransactionContext<G>) => ...` accepts a measurable context. The
+ * scoped context handed to `measure` is itself measurable, so scopes nest.
+ */
+type MeasurableTransactionContext<G extends GraphDef> = TransactionContext<G> & Readonly<{
+    measure: ScopedMeasure<MeasurableTransactionContext<G>>;
+}>;
 /**
  * Replace branded `NodeId` / `EdgeId` with plain `string` in each
  * method's parameter list. Return types are preserved unchanged.
@@ -2048,6 +2362,33 @@ declare class ExecutableAggregateQuery<G extends GraphDef, Aliases extends Alias
      * Builds the query AST.
      */
     toAst(): QueryAst;
+    /**
+     * Orders results by a grouped field or aggregate alias.
+     *
+     * `key` is one of the output names passed to `.aggregate({...})` — either
+     * a grouped field (e.g. `genre`) or an aggregate alias (e.g. `bookCount`).
+     * Both are ordered the same way: by referencing the SELECT-list output
+     * column, since every `.aggregate()` field is projected with an alias.
+     *
+     * Chain multiple calls to sort by more than one key, in call order:
+     * `.orderBy("genre").orderBy("bookCount", "desc")` sorts by genre first,
+     * then by book count within each genre.
+     *
+     * @example
+     * ```typescript
+     * // Top 2 authors by book count
+     * store.query()
+     *   .from("Author", "a")
+     *   .traverse("wrote", "e")
+     *   .to("Book", "b")
+     *   .groupByNode("a")
+     *   .aggregate({ author: field("a", "name"), bookCount: count("b") })
+     *   .orderBy("bookCount", "desc")
+     *   .limit(2)
+     *   .execute();
+     * ```
+     */
+    orderBy<K extends keyof R & string>(key: K, direction?: SortDirection): ExecutableAggregateQuery<G, Aliases, R>;
     /**
      * Limits the number of results.
      */
@@ -2078,6 +2419,30 @@ declare class ExecutableAggregateQuery<G extends GraphDef, Aliases extends Alias
     execute(): Promise<readonly AggregateResult<R>[]>;
 }
 
+/**
+ * Temporal Filter Compilation
+ *
+ * Generates SQL clauses for temporal filtering based on valid_from/valid_to
+ * and deleted_at timestamps. Consolidates the previously duplicated temporal
+ * filter functions into a single, parameterized implementation.
+ */
+
+/**
+ * How a "current" valid-time read instant is emitted into compiled SQL:
+ *
+ * - `"literal"` — bound as a concrete value at compile time
+ *   ({@link currentReadInstant}). The instant is frozen into the compiled
+ *   statement, so the statement must be recompiled to observe a newer "now".
+ * - `"placeholder"` — bound as a reserved execution-time placeholder
+ *   ({@link currentReadInstantPlaceholder}). The statement can be compiled
+ *   once and reused across executions, filling a fresh instant each call.
+ *
+ * Defaults to `"literal"` everywhere except the query builder's compiled
+ * template cache, which opts into `"placeholder"` so a reused/prepared query
+ * never freezes "now" the way a cached literal would (the #246 regression).
+ */
+type ReadInstantMode = "literal" | "placeholder";
+
 /**
  * Query Compiler Module
  *
@@ -2120,6 +2485,8 @@ type CompileQueryOptions = Readonly<{
      * declare the field. Callers build it from the graph's node schemas.
      */
     vectorSlots?: VectorSlotMap | undefined;
+    /** Per-kind declared fulltext language (see buildFulltextLanguages). */
+    fulltextLanguages?: ReadonlyMap<string, string> | undefined;
     /**
      * Recorded read relation to use when the AST carries `recordedAsOf`.
      * Supplying a recorded timestamp without this binding is rejected so the
@@ -2127,15 +2494,40 @@ type CompileQueryOptions = Readonly<{
      * the store was only configured for live/valid-time reads.
      */
     recordedReadBinding?: RecordedReadBinding | undefined;
+    /**
+     * How the "current" valid-time read instant is emitted. Defaults to
+     * `"literal"` (a value frozen at compile time). The query builder's
+     * compiled template cache passes `"placeholder"` so the instant is a
+     * reserved execution-time slot, letting one compiled statement be reused
+     * across executions with a fresh "now" each call. See {@link ReadInstantMode}.
+     */
+    readInstant?: ReadInstantMode | undefined;
 }>;
 
+/**
+ * PreparedQuery — a pre-validated, parameterized query.
+ *
+ * Created via `ExecutableQuery.prepare()`. Builds and structurally validates
+ * the query AST once at prepare time (so a malformed query fails fast, before
+ * the first `execute()`).
+ *
+ * Fast path: when the backend can compile and run raw SQL (`compileSql` +
+ * `executeRaw`), the statement is compiled ONCE into a cached template whose
+ * "current" read instant and user `param()` refs are reserved placeholders
+ * (see {@link buildReadInstantTemplate}). Every `execute()` fills those
+ * placeholders — a fresh instant plus the call's bindings — and runs the
+ * cached SQL text directly, so a reused prepared query never recompiles and
+ * never freezes "now" the way a cached literal instant would (the #246
+ * regression).
+ *
+ * Fallback: on a backend without raw execution (custom/async), substitutes
+ * parameter refs into the AST, compiles fresh per call, and executes via the
+ * standard `backend.execute` path.
+ */
+
 type PreparedQueryConfig<R> = Readonly<{
     ast: QueryAst;
     unoptimizedAst: QueryAst;
-    sqlText: string | undefined;
-    sqlParams: readonly unknown[] | undefined;
-    unoptimizedSqlText: string | undefined;
-    unoptimizedSqlParams: readonly unknown[] | undefined;
     backend: GraphBackend;
     dialect: SqlDialect;
     graphId: string;
@@ -2146,7 +2538,9 @@ type PreparedQueryConfig<R> = Readonly<{
     schemaIntrospector: SchemaIntrospector;
 }>;
 /**
- * A pre-compiled, parameterized query.
+ * A pre-validated, parameterized query — see the module doc comment above for
+ * how a reused prepared query runs a cached SQL template with a fresh read
+ * instant filled per call.
  *
  * @example
  * ```typescript
@@ -2195,10 +2589,6 @@ type UnionableQueryState = Readonly<{
     traversals?: readonly Traversal[];
     selectFn?: (context: SelectContext<AliasMap, EdgeAliasMap>) => unknown;
 }>;
-/**
- * A query formed by combining multiple queries with set operations.
- * Supports chaining: q1.union(q2).intersect(q3)
- */
 declare class UnionableQuery<G extends GraphDef, R> {
     #private;
     constructor(config: QueryBuilderConfig, state: UnionableQueryState);
@@ -2267,7 +2657,7 @@ declare class ExecutableQuery<G extends GraphDef, Aliases extends AliasMap, Edge
     #private;
     constructor(config: QueryBuilderConfig, state: QueryBuilderState, selectFunction: (context: SelectContext<Aliases, EdgeAliases, RecursiveAliases>) => R);
     /**
-     * Builds the query AST.
+     * Builds the query AST (memoized — the instance is immutable).
      */
     toAst(): QueryAst;
     /**
@@ -2337,8 +2727,12 @@ declare class ExecutableQuery<G extends GraphDef, Aliases extends AliasMap, Edge
      */
     compile(): CompiledSelectSql;
     /**
-     * Creates a prepared (pre-compiled) query that can be executed
-     * multiple times with different parameter bindings.
+     * Creates a prepared (pre-validated) query that can be executed multiple
+     * times with different parameter bindings. Builds and structurally
+     * validates the AST once (a malformed query fails fast, here, instead of on
+     * first use); the prepared query then compiles once into a reusable template
+     * and fills a fresh read instant per execute() — see PreparedQuery's class
+     * doc comment.
      *
      * Use `param("name")` in predicates to create parameterized slots,
      * then pass values via `prepared.execute({ name: "value" })`.
@@ -2950,16 +3344,6 @@ type RebuildFulltextResult = Readonly<{
     skippedTruncated: boolean;
 }>;
 
-/**
- * Store-level search helpers.
- *
- * `fulltextSearch` is a thin typed wrapper over `backend.fulltextSearch`.
- * `hybridSearch` runs a vector and a fulltext query in parallel and
- * fuses the two ranked lists with Reciprocal Rank Fusion. RRF is
- * rank-based, so it papers over score-scale differences between
- * pgvector/sqlite-vec (distance-derived) and tsvector/FTS5 (BM25-style).
- */
-
 /**
  * A fulltext search hit. `N` defaults to the generic `Node`; the
  * `store.search.fulltext<K>(kind)` facade narrows it to the concrete
@@ -2994,7 +3378,36 @@ type HybridSearchHit<N = Node> = Readonly<{
     /** Sub-result from the fulltext half, if it ranked this node. */
     fulltext?: FulltextSearchHit<N>;
 }>;
-type FulltextSearchOptions = Readonly<{
+/**
+ * Scope options shared by every facade search leg.
+ *
+ * `where` and `includeSubClasses` compile into the search statement's
+ * candidate set (a subquery produced by the store's own query compiler), so
+ * filtering happens INSIDE the engine's top-k — never by post-filtering a
+ * ranked list. `offset` is rank-relative pagination: the engine fetches
+ * `limit + offset` ranked candidates and discards the leading page.
+ */
+type SearchScopeOptions<N extends NodeType = NodeType> = Readonly<{
+    /**
+     * Predicate over the node's properties, compiled by the shared query
+     * compiler into the candidate subquery. Requires a query-capable store.
+     * The facade instantiates `N` to the searched kind's node type, so the
+     * accessor is fully typed at the call site; the base instantiation
+     * exposes the system accessors (`id`, `kind`) for standalone option
+     * values.
+     */
+    where?: (accessor: NodeAccessor<N>) => Predicate;
+    /** Rows to skip after ranking (rank-relative pagination). */
+    offset?: number;
+    /**
+     * Expand the searched kind to include its `subClassOf` descendants.
+     * Vector legs search each declaring kind's storage and merge by score;
+     * kinds that don't declare the embedding field are skipped (mirroring
+     * the query builder). Requires a query-capable store.
+     */
+    includeSubClasses?: boolean;
+}>;
+type FulltextSearchOptions<N extends NodeType = NodeType> = SearchScopeOptions<N> & Readonly<{
     /** The user-supplied query string. */
     query: string;
     /** Max results. Required. */
@@ -3002,8 +3415,10 @@ type FulltextSearchOptions = Readonly<{
     /** Query parser mode. Default: "websearch". */
     mode?: FulltextQueryMode;
     /**
-     * Language override for query parsing. Default: per-row language as
-     * stored at insert time.
+     * Language override for query parsing. Default: the kind's
+     * declared language (the same config rows were indexed with),
+     * which keeps the parsed tsquery a plan-time constant on
+     * PostgreSQL so the GIN index can serve the match.
      */
     language?: string;
     /** Minimum relevance score to include in results. */
@@ -3036,7 +3451,7 @@ type HybridVectorOptions = Readonly<{
  * vector half of `HybridSearchOptions` but flattens it because the
  * standalone path doesn't fuse against fulltext.
  */
-type VectorSearchOptions = Readonly<{
+type VectorSearchOptions<N extends NodeType = NodeType> = SearchScopeOptions<N> & Readonly<{
     /** Field path of the embedding column on the node kind. */
     fieldPath: string;
     /** Query embedding to compare against. */
@@ -3073,7 +3488,7 @@ type HybridFulltextOptions = Readonly<{
     minScore?: number;
     includeSnippets?: boolean;
 }>;
-type HybridSearchOptions = Readonly<{
+type HybridSearchOptions<N extends NodeType = NodeType> = SearchScopeOptions<N> & Readonly<{
     vector: HybridVectorOptions;
     fulltext: HybridFulltextOptions;
     fusion?: HybridFusionOptions;
@@ -3105,10 +3520,17 @@ type HybridSearchOptions = Readonly<{
  * when) the literal is statically known.
  */
 type ResolveNode<G extends GraphDef, K extends string> = K extends NodeKinds<G> ? G["nodes"][K] extends NodeRegistration<infer N extends NodeType> ? Node<N> : Node : Node;
+/**
+ * The registered `NodeType` behind a kind literal — the accessor-level
+ * companion of {@link ResolveNode}, used to type `where` predicates.
+ * Falls back to the base `NodeType` for dynamic (string) kinds.
+ */
+type ResolveNodeType<G extends GraphDef, K extends string> = K extends NodeKinds<G> ? G["nodes"][K] extends NodeRegistration<infer N extends NodeType> ? N : NodeType : NodeType;
 type StoreSearchContext = Readonly<{
     graphId: string;
     backend: GraphBackend;
     registry: KindRegistry;
+    createQuery?: () => QueryBuilder<GraphDef>;
 }>;
 /**
  * Search-related operations exposed via `store.search`.
@@ -3157,7 +3579,7 @@ declare class StoreSearch<G extends GraphDef> {
      * configured with) and resolves the matching node IDs back to typed
      * `Node` objects.
      */
-    fulltext<K extends string>(nodeKind: K, options: FulltextSearchOptions): Promise<readonly FulltextSearchHit<ResolveNode<G, K>>[]>;
+    fulltext<K extends string>(nodeKind: K, options: FulltextSearchOptions<ResolveNodeType<G, K>>): Promise<readonly FulltextSearchHit<ResolveNode<G, K>>[]>;
     /**
      * Runs a vector similarity search against nodes of the given kind.
      *
@@ -3169,7 +3591,7 @@ declare class StoreSearch<G extends GraphDef> {
      * Pure vector — no fulltext leg, no fusion. For combined
      * vector+fulltext ranking, use `hybrid`.
      */
-    vector<K extends string>(nodeKind: K, options: VectorSearchOptions): Promise<readonly VectorSearchHit<ResolveNode<G, K>>[]>;
+    vector<K extends string>(nodeKind: K, options: VectorSearchOptions<ResolveNodeType<G, K>>): Promise<readonly VectorSearchHit<ResolveNode<G, K>>[]>;
     /**
      * Runs a vector + fulltext hybrid search and fuses the results with
      * Reciprocal Rank Fusion.
@@ -3179,7 +3601,7 @@ declare class StoreSearch<G extends GraphDef> {
      * over-fetch is 4× `limit` from each source — tune via `vector.k` /
      * `fulltext.k` for higher-recall corpora.
      */
-    hybrid<K extends string>(nodeKind: K, options: HybridSearchOptions): Promise<readonly HybridSearchHit<ResolveNode<G, K>>[]>;
+    hybrid<K extends string>(nodeKind: K, options: HybridSearchOptions<ResolveNodeType<G, K>>): Promise<readonly HybridSearchHit<ResolveNode<G, K>>[]>;
     /**
      * Rebuilds the fulltext index from existing node data.
      *
@@ -3566,6 +3988,18 @@ declare class Store<G extends GraphDef> {
      * @internal
      */
     get historyEnabled(): boolean;
+    /**
+     * Whether this Store advances a durable revision anchor for graph writes.
+     *
+     * @internal
+     */
+    get revisionTrackingEnabled(): boolean;
+    /**
+     * SQL schema that owns the durable revision clock relation.
+     *
+     * @internal
+     */
+    get revisionSchema(): SqlSchema;
     /**
      * Whether this store has a recorded read relation bound for reconstruction.
      *
@@ -3813,6 +4247,24 @@ declare class Store<G extends GraphDef> {
      * success), not the global clock.
      */
     recordedNow(): Promise<RecordedInstant | undefined>;
+    /**
+     * Returns the durable graph revision used by graph branching. It is undefined
+     * until the first successful tracked write, which is itself a stable initial
+     * anchor. Unlike {@link recordedNow}, this is also available on a live Store
+     * created with `{ revisionTracking: true }`.
+     *
+     * @internal
+     */
+    revisionNow(): Promise<string | undefined>;
+    /**
+     * Returns the durable random namespace for this graph's revision clock. A
+     * tracked base token combines it with {@link revisionNow}, preventing a
+     * branch from one independent store from matching a coincident timestamp in
+     * another store.
+     *
+     * @internal
+     */
+    revisionOriginNow(): Promise<string>;
     /**
      * Returns a read-only {@link StoreView} pinned to an arbitrary public
      * temporal mode. Use {@link Store.asOf} for the common valid-time case;
@@ -3967,12 +4419,16 @@ declare class Store<G extends GraphDef> {
      *   transaction**, for writing the caller's own relational tables in
      *   the same atomic boundary (the graph-owned counterpart of
      *   {@link Store.withTransaction}). See {@link TransactionContext}
-     *   for per-backend semantics; it is `undefined` only on the
-     *   non-transactional fallback.
-     *   When the store was created with `{ history: true }`, `tx.sql` is
-     *   replaced by a fail-loud guard because raw SQL would bypass
-     *   recorded-time capture; use the typed collections inside
-     *   `transaction()` or {@link Store.withRecordedTransaction}.
+     *   for per-backend semantics. To decide at runtime whether `tx.sql` is
+     *   usable, branch on `tx.sqlAvailability` rather than truthiness-testing
+     *   `tx.sql` — under history capture or revision tracking `tx.sql` is
+     *   present-but-throwing (`sqlAvailability` is `"history"` /
+     *   `"revisionTracking"`), and it is `undefined` only on the non-transactional
+     *   fallback (`sqlAvailability === "unavailable"`). When it reports
+     *   `"history"` / `"revisionTracking"`, raw SQL is disabled because it would
+     *   bypass recorded-time capture or the revision anchor; use the typed
+     *   collections inside `transaction()` or
+     *   {@link Store.withRecordedTransaction}.
      *
      * @example
      * ```typescript
@@ -3997,6 +4453,16 @@ declare class Store<G extends GraphDef> {
      * });
      * ```
      *
+     * **`tx.sql` shares the one pinned connection — await it, don't overlap it.**
+     * TypeGraph serializes the statements *its own* collections issue, so a
+     * `Promise.all` of graph writes is safe. A statement you issue through
+     * `tx.sql` bypasses that queue: run it concurrently with a graph write (or
+     * with another `tx.sql` statement) and two queries race on the one
+     * transaction connection — the exact overlap Postgres removes in `pg@9`.
+     * Await each `tx.sql` statement before starting the next write. TypeGraph
+     * cannot police this: it never sees the raw handle's traffic, so it also
+     * cannot drain a raw statement still in flight when the transaction commits.
+     *
      * **Backends without transactions.** When `backend.capabilities.transactions`
      * is `false` (Cloudflare D1, `drizzle-orm/neon-http`), this method runs the
      * callback against the same backend used outside `transaction()` — writes
@@ -4022,6 +4488,49 @@ declare class Store<G extends GraphDef> {
      */
     transaction<T>(this: HistoryStore<G>, fn: (tx: HistoryTransactionContext<G>) => Promise<T>, options?: TransactionOptions): Promise<T>;
     transaction<T>(fn: (tx: TransactionContext<G>) => Promise<T>, options?: TransactionOptions): Promise<T>;
+    /**
+     * Runs a transaction exactly like {@link transaction} and additionally
+     * returns a {@link TransactionOutcome} whose receipt summarizes the
+     * completed write intents on the transaction-scoped collection surface.
+     *
+     * A dedicated method (rather than an option on `transaction()`) keeps the
+     * return type tied to static dispatch: forwarding options through wrappers
+     * can never change what a call returns. See {@link TransactionReceipt} for
+     * exact count semantics.
+     *
+     * The receipt does not count writes that bypass the `tx.nodes.*` /
+     * `tx.edges.*` collections, such as direct backend writes, raw SQL, or
+     * import helpers. The adopted-commit sibling
+     * {@link Store.withRecordedTransaction} also returns a
+     * {@link TransactionOutcome}; only `withTransaction` (whose commit belongs
+     * entirely to the caller with no flush point) produces no receipt. On
+     * non-transactional backends, the receipt is still returned, but it describes
+     * operations that individually committed rather than one atomic commit; if the
+     * callback rejects on such a backend, no receipt is returned even though
+     * earlier operations committed individually.
+     *
+     * For stores created with `{ history: true }`, `receipt.recorded` is the
+     * recorded commit instant this transaction allocated for the store's
+     * graph, or `undefined` when nothing was captured.
+     *
+     * The callback receives a {@link MeasurableTransactionContext}: call
+     * `tx.measure((scoped) => ...)` to scope a sub-receipt to the writes made
+     * through the `scoped` context (e.g. to attribute writes to user code the
+     * caller invokes, excluding its own bookkeeping written through `tx`). See
+     * {@link MeasurableTransactionContext} for semantics.
+     *
+     * @example
+     * ```typescript
+     * const outcome = await store.transactionWithReceipt(async (tx) => {
+     *   const alice = await tx.nodes.Person.create({ name: "Alice" });
+     *   return alice.id;
+     * });
+     * outcome.result; // Alice's id
+     * outcome.receipt.writes; // { nodes: { Person: 1 }, edges: {}, total: 1 }
+     * ```
+     */
+    transactionWithReceipt<T>(this: HistoryStore<G>, fn: (tx: MeasurableHistoryTransactionContext<G>) => Promise<T>, options?: TransactionOptions): Promise<TransactionOutcome<T>>;
+    transactionWithReceipt<T>(fn: (tx: MeasurableTransactionContext<G>) => Promise<T>, options?: TransactionOptions): Promise<TransactionOutcome<T>>;
     /**
      * Adopts a caller-owned, already-open Drizzle transaction so the graph
      * store and the caller's relational writes commit or roll back as one
@@ -4064,13 +4573,24 @@ declare class Store<G extends GraphDef> {
      * }); // one COMMIT / ROLLBACK across both layers
      * ```
      *
+     * **The caller owns the connection — don't overlap writes on it.** The graph
+     * store and your Drizzle writes share the one connection the caller's
+     * transaction pinned. TypeGraph serializes the statements *its* collections
+     * issue, but your raw Drizzle statements (and any graph write run alongside
+     * them) are yours to sequence: a `Promise.all` mixing the two races two
+     * queries on that connection — the overlap Postgres removes in `pg@9`. Await
+     * each write before starting the next.
+     *
      * Not available when the store was created with `{ history: true }`: a
      * caller-owned transaction context would let writes happen after capture has
-     * lost its flush point, so this throws `ConfigurationError`
-     * (`RECORDED_CAPTURE_REQUIRES_CALLBACK_TRANSACTION`). Use
-     * {@link Store.withRecordedTransaction} on a history-enabled store, which
-     * adopts the same external transaction but flushes recorded-time capture
-     * before the caller commits.
+     * lost its flush point. On a {@link HistoryStore} this is a **compile error**
+     * at the call site (the `externalTx` argument is rejected against a message
+     * type naming {@link Store.withRecordedTransaction}); the runtime guard still
+     * throws `ConfigurationError`
+     * (`RECORDED_CAPTURE_REQUIRES_CALLBACK_TRANSACTION`) if the check is
+     * suppressed. Use {@link Store.withRecordedTransaction} on a history-enabled
+     * store, which adopts the same external transaction but flushes recorded-time
+     * capture before the caller commits.
      *
      * @throws {ConfigurationError} when the store has history capture enabled
      *   (use {@link Store.withRecordedTransaction} instead), or when the backend
@@ -4086,7 +4606,7 @@ declare class Store<G extends GraphDef> {
      *   `createStoreWithSchema`). Rolls back the caller's transaction
      *   without emitting any DDL.
      */
-    withTransaction(externalTx: AdoptedTransaction): TransactionContext<G>;
+    withTransaction<This extends Store<G>>(this: This, externalTx: This extends HistoryStore<G> ? HistoryWithTransactionUnavailable : AdoptedTransaction): This extends HistoryStore<G> ? never : TransactionContext<G>;
     /**
      * Adopts a caller-owned transaction while giving recorded-time capture a
      * flush point before the caller commits. Required when `history: true` is
@@ -4097,10 +4617,55 @@ declare class Store<G extends GraphDef> {
      * session, so a graph write made through the transaction context *after* `fn`
      * returns (e.g. retaining `tx` and writing once more before the caller's
      * COMMIT) throws rather than committing uncaptured — the post-flush write
-     * cannot silently diverge history from live state.
+     * cannot silently diverge history from live state. This sealing behavior is
+     * unchanged by the receipt return.
+     *
+     * Returns a {@link TransactionOutcome} — the adopted path is the only way to
+     * get exactly-once cursors and graph writes atomically on a history store, so
+     * it surfaces the same receipt `transactionWithReceipt` does: `receipt.writes`
+     * for drop detection (a non-delete change that wrote nothing) and
+     * `receipt.recorded` as the per-transaction replay anchor. Destructure
+     * `{ result, receipt }`:
+     *
+     * ```typescript
+     * const { result, receipt } = await store.withRecordedTransaction(
+     *   externalTx,
+     *   async (tx) => tx.nodes.Document.update(documentId, props),
+     * );
+     * ```
+     *
+     * `receipt.recorded` is the recorded commit instant this transaction allocated
+     * for the store's graph at the flush point (when `fn` resolved), and is
+     * `undefined` when nothing was captured — a read-only `fn`, or a non-history
+     * store (where the receipt still counts write intents but there is no recorded
+     * time). To attribute writes when `fn` invokes user code that also
+     * bookkeeps, use `tx.measure((scoped) => ...)` and have that code write
+     * through the `scoped` context (see {@link MeasurableTransactionContext}).
+     *
+     * Write your own relational tables through the **external transaction handle
+     * you passed in** (`externalTx`) — it *is* the pinned connection. `tx.sql` is
+     * unavailable here (it is a fail-loud guard under history capture, since raw
+     * SQL bypasses recorded-time capture, and `HistoryTransactionContext` types it
+     * `sql?: never`). Writing through `externalTx` is the sanctioned way to get
+     * cross-store atomicity on a history-enabled store:
+     *
+     * ```typescript
+     * // Async driver (Postgres / libsql):
+     * await db.transaction(async (pgTx) => {
+     *   const { receipt } = await store.withRecordedTransaction(pgTx, async (tx) => {
+     *     await tx.nodes.Document.update(documentId, props); // graph write
+     *   });
+     *   await pgTx.insert(streamCursors).values(cursorRow);  // your own table
+     * }); // one COMMIT / ROLLBACK across both layers
+     * ```
+     *
+     * The graph writes and your `externalTx` statements share the caller's one
+     * pinned connection. TypeGraph serializes the statements its collections
+     * issue; sequence your own raw statements (and don't `Promise.all` them with
+     * graph writes) so two queries never race on that connection.
      */
-    withRecordedTransaction<T>(this: HistoryStore<G>, externalTx: AdoptedTransaction, fn: (tx: HistoryTransactionContext<G>) => Promise<T>): Promise<T>;
-    withRecordedTransaction<T>(externalTx: AdoptedTransaction, fn: (tx: TransactionContext<G>) => Promise<T>): Promise<T>;
+    withRecordedTransaction<T>(this: HistoryStore<G>, externalTx: AdoptedTransaction, fn: (tx: MeasurableHistoryTransactionContext<G>) => Promise<T>): Promise<TransactionOutcome<T>>;
+    withRecordedTransaction<T>(externalTx: AdoptedTransaction, fn: (tx: MeasurableTransactionContext<G>) => Promise<T>): Promise<TransactionOutcome<T>>;
     /**
      * Hard-deletes all data for this graph from the database.
      *
@@ -4358,6 +4923,17 @@ type HistoryTransactionContext<G extends GraphDef> = Omit<TransactionContext<G>,
     backend: HistorySafeTransactionBackend;
     sql?: never;
 }>;
+/**
+ * The {@link HistoryTransactionContext} handed to a `withRecordedTransaction`
+ * callback, extended with {@link ScopedMeasure}. Its `measure` scopes to a child
+ * {@link MeasurableHistoryTransactionContext} (so nested scopes keep the
+ * history-safe `sql?: never` / backend typing). Assignable to
+ * {@link MeasurableTransactionContext} (and hence to {@link TransactionContext}),
+ * so a projector helper typed against either still accepts it.
+ */
+type MeasurableHistoryTransactionContext<G extends GraphDef> = HistoryTransactionContext<G> & Readonly<{
+    measure: ScopedMeasure<MeasurableHistoryTransactionContext<G>>;
+}>;
 type RecordedReadStore<G extends GraphDef> = Store<G> & Readonly<{
     recordedReadBound: true;
 }>;
@@ -4366,6 +4942,15 @@ type HistoryStore<G extends GraphDef> = Store<G> & Readonly<{
     historyEnabled: true;
     recordedReadBound: true;
 }>;
+/**
+ * The `externalTx` parameter type {@link Store.withTransaction} resolves to when
+ * called on a {@link HistoryStore}. A real {@link AdoptedTransaction} is not
+ * assignable to this string literal, so the call is a compile error whose
+ * message names the working alternative. `HistoryStore` cannot be excluded from
+ * the general signature by a `this` constraint alone — it is a subtype of
+ * `Store<G>` — so the block is expressed on the argument instead.
+ */
+type HistoryWithTransactionUnavailable = "withTransaction() is unavailable on a history-enabled store — use store.withRecordedTransaction() so recorded-time capture can flush before the caller commits";
 type ExplicitRecordedReadLiveOptions = LiveStoreOptions & Readonly<{
     recordedRead: NonNullable<LiveStoreOptions["recordedRead"]>;
 }>;
@@ -4616,4 +5201,4 @@ declare class RecordedStoreView<G extends GraphDef> extends CoordinatePinnedView
     get edges(): RecordedStoreViewEdgeCollections<G>;
 }
 
-export { type GetOrCreateAction as $, type AliasMap as A, type BaseTraversalOptions as B, type ConstraintNames as C, DEFAULT_SEARCHABLE_LANGUAGE as D, type EmbeddingMetric as E, type EdgeFindByEndpointsOptions as F, type EdgeGetOrCreateByEndpointsOptions as G, type HistoryStore as H, type EdgeGetOrCreateByEndpointsResult as I, type EdgeIntrospection as J, type EdgeTemporalReads as K, type EdgeWrites as L, type EmbeddingSchema as M, type Node as N, type EmbeddingValue as O, type EmptyAliasMap as P, type QueryCoordinateState as Q, type RecursiveAliasMap as R, Store as S, TraversalBuilder as T, type UniqueIntrospection as U, type EmptyEdgeAliasMap as V, ExecutableAggregateQuery as W, ExecutableQuery as X, type FieldAccessor as Y, type FulltextSearchHit as Z, type FulltextSearchOptions as _, type EmbeddingIndexType as a, type SelectableEdge as a$, type GraphAlgorithms as a0, type GraphEdgeCollections as a1, type GraphNodeCollections as a2, type HistorySafeBackend as a3, type HistorySafeTransactionBackend as a4, type HistoryStoreOptions as a5, type HistoryTransactionContext as a6, type HookContext as a7, type HybridFulltextOptions as a8, type HybridSearchHit as a9, type PathNode as aA, type Predicate as aB, PreparedQuery as aC, type PropsAccessor as aD, type QueryHookContext as aE, type QueryOptions as aF, type ReachableNode as aG, type ReachableOptions as aH, type RebuildFulltextOptions as aI, type RebuildFulltextResult as aJ, type ReclaimedVectorFieldEntry as aK, type RecordedInstant as aL, type RecordedReadStore as aM, RecordedStoreView as aN, type RecordedStoreViewEdgeCollection as aO, type RecordedStoreViewEdgeCollections as aP, type RecordedStoreViewNodeCollection as aQ, type RecordedStoreViewNodeCollections as aR, type RecursiveTraversalOptions as aS, type ReembedFunction as aT, type ReembedVectorFieldOptions as aU, type ReembedVectorFieldResult as aV, type SchemaIntrospection as aW, type SearchableMetadata as aX, type SearchableOptions as aY, type SearchableSchema as aZ, type SelectContext as a_, type HybridSearchOptions as aa, type HybridVectorOptions as ab, type IfExistsMode as ac, type InitialQueryBuilder as ad, type KindIntrospection as ae, type LiveStoreOptions as af, type MaterializeRemovalsEntry as ag, type MaterializeRemovalsOptions as ah, type MaterializeRemovalsResult as ai, type NeighborsOptions as aj, type NoRecordedCoordinate as ak, type NodeAccessor as al, type NodeAlias as am, type NodeBulkFindByIndexOptions as an, type NodeCollection as ao, type NodeCurrentReads as ap, type NodeGetOrCreateByConstraintOptions as aq, type NodeGetOrCreateByConstraintResult as ar, type NodeIdentifier as as, type NodeRef as at, type NodeTemporalReads as au, type NodeWrites as av, type OntologyIntrospection as aw, type OperationHookContext as ax, type PaginateOptions as ay, type PaginatedResult as az, type EdgeAliasMap as b, type SelectableNode as b0, type ShortestPathOptions as b1, type ShortestPathResult as b2, type StoreHooks as b3, type StoreOptions as b4, type StoreProjection as b5, type StoreRef as b6, StoreSearch as b7, StoreView as b8, type StoreViewCanReachOptions as b9, type VectorSearchHit as bA, type VectorSearchOptions as bB, asRecordedInstant as bC, createQueryBuilder as bD, createStore as bE, createStoreWithSchema as bF, createVerifiedStore as bG, defineSubgraphProject as bH, embedding as bI, exists as bJ, fieldRef as bK, getEmbeddingDimensions as bL, getSearchableMetadata as bM, inSubquery as bN, isEmbeddingSchema as bO, isParameterRef as bP, isSearchableSchema as bQ, notExists as bR, notInSubquery as bS, param as bT, searchable as bU, type StoreViewCoordinate as ba, type StoreViewDegreeOptions as bb, type StoreViewEdgeCollection as bc, type StoreViewEdgeCollections as bd, type StoreViewNeighborsOptions as be, type StoreViewNodeCollection as bf, type StoreViewNodeCollections as bg, type StoreViewReachableOptions as bh, type StoreViewShortestPathOptions as bi, type StoreViewSubgraphOptions as bj, type StreamOptions as bk, type SubgraphEdgeResult as bl, type SubgraphNodeResult as bm, type SubgraphOptions as bn, type SubgraphResult as bo, type SubsetEdge as bp, type SubsetNode as bq, type TemporalAlgorithmOptions as br, type TransactionContext as bs, type TraversalDirection as bt, type TypedEdgeCollection as bu, type TypedRecordedStoreViewEdgeCollection as bv, type TypedStoreViewEdgeCollection as bw, UnionableQuery as bx, type UpdateEdgeInput as by, type UpdateNodeInput as bz, QueryBuilder as c, type EmptyRecursiveAliasMap as d, type AggregateResult as e, type AlgorithmCyclePolicy as f, type AnyEdge as g, type AnyNode as h, type BatchResults as i, type BatchableQuery as j, type CreateEdgeInput as k, type CreateNodeInput as l, type DegreeOptions as m, type DynamicEdgeAccessor as n, type DynamicEdgeCollection as o, type DynamicEdgeType as p, type DynamicFieldBuilder as q, type DynamicNodeAccessor as r, type DynamicNodeCollection as s, type DynamicNodeType as t, type DynamicSelectableEdge as u, type DynamicSelectableNode as v, type Edge as w, type EdgeAccessor as x, type EdgeBatchReads as y, type EdgeCollection as z };
+export { type GetOrCreateAction as $, type AliasMap as A, type BaseTraversalOptions as B, type ConstraintNames as C, DEFAULT_SEARCHABLE_LANGUAGE as D, type EmbeddingMetric as E, type EdgeFindByEndpointsOptions as F, type EdgeGetOrCreateByEndpointsOptions as G, type HistoryStore as H, type EdgeGetOrCreateByEndpointsResult as I, type EdgeIntrospection as J, type EdgeTemporalReads as K, type EdgeWrites as L, type EmbeddingSchema as M, type Node as N, type EmbeddingValue as O, type EmptyAliasMap as P, type QueryCoordinateState as Q, type RecursiveAliasMap as R, Store as S, TraversalBuilder as T, type UniqueIntrospection as U, type EmptyEdgeAliasMap as V, ExecutableAggregateQuery as W, ExecutableQuery as X, type FieldAccessor as Y, type FulltextSearchHit as Z, type FulltextSearchOptions as _, type EmbeddingIndexType as a, type SearchScopeOptions as a$, type GraphAlgorithms as a0, type GraphEdgeCollections as a1, type GraphNodeCollections as a2, type HistorySafeBackend as a3, type HistorySafeTransactionBackend as a4, type HistoryStoreOptions as a5, type HistoryTransactionContext as a6, type HistoryWithTransactionUnavailable as a7, type HookContext as a8, type HybridFulltextOptions as a9, type OperationHookContext as aA, type PaginateOptions as aB, type PaginatedResult as aC, type PathNode as aD, type Predicate as aE, PreparedQuery as aF, type PropsAccessor as aG, type QueryHookContext as aH, type QueryOptions as aI, type ReachableNode as aJ, type ReachableOptions as aK, type RebuildFulltextOptions as aL, type RebuildFulltextResult as aM, type ReclaimedVectorFieldEntry as aN, type RecordedInstant as aO, type RecordedReadStore as aP, RecordedStoreView as aQ, type RecordedStoreViewEdgeCollection as aR, type RecordedStoreViewEdgeCollections as aS, type RecordedStoreViewNodeCollection as aT, type RecordedStoreViewNodeCollections as aU, type RecursiveTraversalOptions as aV, type ReembedFunction as aW, type ReembedVectorFieldOptions as aX, type ReembedVectorFieldResult as aY, type SchemaIntrospection as aZ, type ScopedMeasure as a_, type HybridSearchHit as aa, type HybridSearchOptions as ab, type HybridVectorOptions as ac, type IfExistsMode as ad, type InitialQueryBuilder as ae, type KindIntrospection as af, type LiveStoreOptions as ag, type MaterializeRemovalsEntry as ah, type MaterializeRemovalsOptions as ai, type MaterializeRemovalsResult as aj, type MeasurableHistoryTransactionContext as ak, type MeasurableTransactionContext as al, type NeighborsOptions as am, type NoRecordedCoordinate as an, type NodeAccessor as ao, type NodeAlias as ap, type NodeBulkFindByIndexOptions as aq, type NodeCollection as ar, type NodeCurrentReads as as, type NodeGetOrCreateByConstraintOptions as at, type NodeGetOrCreateByConstraintResult as au, type NodeIdentifier as av, type NodeRef as aw, type NodeTemporalReads as ax, type NodeWrites as ay, type OntologyIntrospection as az, type EdgeAliasMap as b, param as b$, type SearchableMetadata as b0, type SearchableOptions as b1, type SearchableSchema as b2, type SelectContext as b3, type SelectableEdge as b4, type SelectableNode as b5, type ShortestPathOptions as b6, type ShortestPathResult as b7, type SqlAvailability as b8, type StoreHooks as b9, type TransactionReceipt as bA, type TraversalDirection as bB, type TypedEdgeCollection as bC, type TypedRecordedStoreViewEdgeCollection as bD, type TypedStoreViewEdgeCollection as bE, UnionableQuery as bF, type UpdateEdgeInput as bG, type UpdateNodeInput as bH, type VectorSearchHit as bI, type VectorSearchOptions as bJ, asRecordedInstant as bK, createQueryBuilder as bL, createStore as bM, createStoreWithSchema as bN, createVerifiedStore as bO, defineSubgraphProject as bP, embedding as bQ, exists as bR, fieldRef as bS, getEmbeddingDimensions as bT, getSearchableMetadata as bU, inSubquery as bV, isEmbeddingSchema as bW, isParameterRef as bX, isSearchableSchema as bY, notExists as bZ, notInSubquery as b_, type StoreOptions as ba, type StoreProjection as bb, type StoreRef as bc, StoreSearch as bd, StoreView as be, type StoreViewCanReachOptions as bf, type StoreViewCoordinate as bg, type StoreViewDegreeOptions as bh, type StoreViewEdgeCollection as bi, type StoreViewEdgeCollections as bj, type StoreViewNeighborsOptions as bk, type StoreViewNodeCollection as bl, type StoreViewNodeCollections as bm, type StoreViewReachableOptions as bn, type StoreViewShortestPathOptions as bo, type StoreViewSubgraphOptions as bp, type StreamOptions as bq, type SubgraphEdgeResult as br, type SubgraphNodeResult as bs, type SubgraphOptions as bt, type SubgraphResult as bu, type SubsetEdge as bv, type SubsetNode as bw, type TemporalAlgorithmOptions as bx, type TransactionContext as by, type TransactionOutcome as bz, QueryBuilder as c, searchable as c0, type EmptyRecursiveAliasMap as d, type AggregateResult as e, type AlgorithmCyclePolicy as f, type AnyEdge as g, type AnyNode as h, type BatchResults as i, type BatchableQuery as j, type CreateEdgeInput as k, type CreateNodeInput as l, type DegreeOptions as m, type DynamicEdgeAccessor as n, type DynamicEdgeCollection as o, type DynamicEdgeType as p, type DynamicFieldBuilder as q, type DynamicNodeAccessor as r, type DynamicNodeCollection as s, type DynamicNodeType as t, type DynamicSelectableEdge as u, type DynamicSelectableNode as v, type Edge as w, type EdgeAccessor as x, type EdgeBatchReads as y, type EdgeCollection as z };