@nicia-ai/typegraph 0.35.0 → 0.36.0

package/dist/schema/index.cjs

@@ -1,20 +1,20 @@
 'use strict';
 
-var chunkCK5BVQOW_cjs = require('../chunk-CK5BVQOW.cjs');
+var chunkPWGX5DF5_cjs = require('../chunk-PWGX5DF5.cjs');
+var chunk2THZ3TQI_cjs = require('../chunk-2THZ3TQI.cjs');
 require('../chunk-ACSVZPK7.cjs');
-var chunkVPYHY3LJ_cjs = require('../chunk-VPYHY3LJ.cjs');
 require('../chunk-UUT7UN2N.cjs');
 require('../chunk-TEDRJXOG.cjs');
 require('../chunk-D7ZEOS56.cjs');
 require('../chunk-UMDVATGY.cjs');
-require('../chunk-FL472AMI.cjs');
-require('../chunk-GSQ6NPH6.cjs');
-require('../chunk-BLZDPRXT.cjs');
+require('../chunk-J3LEGNQB.cjs');
+require('../chunk-4BCU6VFZ.cjs');
+require('../chunk-RSSQKPSZ.cjs');
 require('../chunk-7YSP4V4R.cjs');
 require('../chunk-H7YNSMA7.cjs');
 require('../chunk-SJDMVITW.cjs');
 require('../chunk-DI74SMXS.cjs');
-require('../chunk-LGEALRC6.cjs');
+require('../chunk-DIK74MXX.cjs');
 require('../chunk-TDXIBCGY.cjs');
 
 // src/schema/deserializer.ts
@@ -55,7 +55,7 @@ function buildRegistryFromClosures(schema) {
   const edgeImplyingClosure = recordToMap(closures.edgeImplyingClosure);
   const nodeKinds = /* @__PURE__ */ new Map();
   const edgeKinds = /* @__PURE__ */ new Map();
-  const registry = new chunkCK5BVQOW_cjs.KindRegistry(nodeKinds, edgeKinds, {
+  const registry = new chunkPWGX5DF5_cjs.KindRegistry(nodeKinds, edgeKinds, {
     subClassAncestors,
     subClassDescendants,
     broaderClosure,
@@ -69,7 +69,7 @@ function buildRegistryFromClosures(schema) {
     edgeImplicationsClosure,
     edgeImplyingClosure
   });
-  chunkCK5BVQOW_cjs.validateImpliesEndpointCompatibility(
+  chunkPWGX5DF5_cjs.validateImpliesEndpointCompatibility(
     buildEdgeEndpointKinds(schema.edges),
     registry
   );
@@ -95,95 +95,95 @@ function simpleRecordToMap(record) {
 
 Object.defineProperty(exports, "applyDeprecatedKinds", {
   enumerable: true,
-  get: function () { return chunkCK5BVQOW_cjs.applyDeprecatedKinds; }
+  get: function () { return chunkPWGX5DF5_cjs.applyDeprecatedKinds; }
 });
 Object.defineProperty(exports, "assertSchemaCurrent", {
   enumerable: true,
-  get: function () { return chunkCK5BVQOW_cjs.assertSchemaCurrent; }
+  get: function () { return chunkPWGX5DF5_cjs.assertSchemaCurrent; }
 });
 Object.defineProperty(exports, "computeSchemaDiff", {
   enumerable: true,
-  get: function () { return chunkCK5BVQOW_cjs.computeSchemaDiff; }
+  get: function () { return chunkPWGX5DF5_cjs.computeSchemaDiff; }
 });
 Object.defineProperty(exports, "computeSchemaHash", {
   enumerable: true,
-  get: function () { return chunkCK5BVQOW_cjs.computeSchemaHash; }
+  get: function () { return chunkPWGX5DF5_cjs.computeSchemaHash; }
 });
 Object.defineProperty(exports, "deserializeWherePredicate", {
   enumerable: true,
-  get: function () { return chunkCK5BVQOW_cjs.deserializeWherePredicate; }
+  get: function () { return chunkPWGX5DF5_cjs.deserializeWherePredicate; }
 });
 Object.defineProperty(exports, "ensureSchema", {
   enumerable: true,
-  get: function () { return chunkCK5BVQOW_cjs.ensureSchema; }
+  get: function () { return chunkPWGX5DF5_cjs.ensureSchema; }
 });
 Object.defineProperty(exports, "getActiveSchema", {
   enumerable: true,
-  get: function () { return chunkCK5BVQOW_cjs.getActiveSchema; }
+  get: function () { return chunkPWGX5DF5_cjs.getActiveSchema; }
 });
 Object.defineProperty(exports, "getMigrationActions", {
   enumerable: true,
-  get: function () { return chunkCK5BVQOW_cjs.getMigrationActions; }
+  get: function () { return chunkPWGX5DF5_cjs.getMigrationActions; }
 });
 Object.defineProperty(exports, "getSchemaChanges", {
   enumerable: true,
-  get: function () { return chunkCK5BVQOW_cjs.getSchemaChanges; }
+  get: function () { return chunkPWGX5DF5_cjs.getSchemaChanges; }
 });
 Object.defineProperty(exports, "initializeSchema", {
   enumerable: true,
-  get: function () { return chunkCK5BVQOW_cjs.initializeSchema; }
+  get: function () { return chunkPWGX5DF5_cjs.initializeSchema; }
 });
 Object.defineProperty(exports, "isBackwardsCompatible", {
   enumerable: true,
-  get: function () { return chunkCK5BVQOW_cjs.isBackwardsCompatible; }
+  get: function () { return chunkPWGX5DF5_cjs.isBackwardsCompatible; }
 });
 Object.defineProperty(exports, "isSchemaInitialized", {
   enumerable: true,
-  get: function () { return chunkCK5BVQOW_cjs.isSchemaInitialized; }
+  get: function () { return chunkPWGX5DF5_cjs.isSchemaInitialized; }
 });
 Object.defineProperty(exports, "loadActiveSchemaWithBootstrap", {
   enumerable: true,
-  get: function () { return chunkCK5BVQOW_cjs.loadActiveSchemaWithBootstrap; }
+  get: function () { return chunkPWGX5DF5_cjs.loadActiveSchemaWithBootstrap; }
 });
 Object.defineProperty(exports, "loadAndMergeGraphExtensionDocument", {
   enumerable: true,
-  get: function () { return chunkCK5BVQOW_cjs.loadAndMergeGraphExtensionDocument; }
+  get: function () { return chunkPWGX5DF5_cjs.loadAndMergeGraphExtensionDocument; }
 });
 Object.defineProperty(exports, "migrateSchema", {
   enumerable: true,
-  get: function () { return chunkCK5BVQOW_cjs.migrateSchema; }
+  get: function () { return chunkPWGX5DF5_cjs.migrateSchema; }
 });
 Object.defineProperty(exports, "parseSerializedSchema", {
   enumerable: true,
-  get: function () { return chunkCK5BVQOW_cjs.parseSerializedSchema; }
+  get: function () { return chunkPWGX5DF5_cjs.parseSerializedSchema; }
 });
 Object.defineProperty(exports, "rollbackSchema", {
   enumerable: true,
-  get: function () { return chunkCK5BVQOW_cjs.rollbackSchema; }
+  get: function () { return chunkPWGX5DF5_cjs.rollbackSchema; }
 });
 Object.defineProperty(exports, "serializeSchema", {
   enumerable: true,
-  get: function () { return chunkCK5BVQOW_cjs.serializeSchema; }
+  get: function () { return chunkPWGX5DF5_cjs.serializeSchema; }
 });
 Object.defineProperty(exports, "createValidationError", {
   enumerable: true,
-  get: function () { return chunkVPYHY3LJ_cjs.createValidationError; }
+  get: function () { return chunk2THZ3TQI_cjs.createValidationError; }
 });
 Object.defineProperty(exports, "validateEdgeProps", {
   enumerable: true,
-  get: function () { return chunkVPYHY3LJ_cjs.validateEdgeProps; }
+  get: function () { return chunk2THZ3TQI_cjs.validateEdgeProps; }
 });
 Object.defineProperty(exports, "validateNodeProps", {
   enumerable: true,
-  get: function () { return chunkVPYHY3LJ_cjs.validateNodeProps; }
+  get: function () { return chunk2THZ3TQI_cjs.validateNodeProps; }
 });
 Object.defineProperty(exports, "validateProps", {
   enumerable: true,
-  get: function () { return chunkVPYHY3LJ_cjs.validateProps; }
+  get: function () { return chunk2THZ3TQI_cjs.validateProps; }
 });
 Object.defineProperty(exports, "wrapZodError", {
   enumerable: true,
-  get: function () { return chunkVPYHY3LJ_cjs.wrapZodError; }
+  get: function () { return chunk2THZ3TQI_cjs.wrapZodError; }
 });
 exports.deserializeSchema = deserializeSchema;
 //# sourceMappingURL=index.cjs.map

package/dist/schema/index.d.cts

@@ -4,7 +4,7 @@ import { s as SerializedSchema, t as SchemaHash, u as SerializedNodeDef, v as Se
 export { z as JsonSchema, C as SerializedOntology, D as SerializedUniqueConstraint } from '../fulltext-strategy-CDkSSYhq.cjs';
 import { a as NullCheckOp, K as KindEntity } from '../extension-types-ixRpJVUp.cjs';
 import { ZodType, ZodError } from 'zod';
-import { V as ValidationIssue, a as ValidationError } from '../index-Bks_3HHK.cjs';
+import { V as ValidationIssue, a as ValidationError } from '../index-BLtQWKRj.cjs';
 import 'drizzle-orm';
 import 'drizzle-orm/pg-core';
 import 'drizzle-orm/sqlite-core';

package/dist/schema/index.d.ts

@@ -4,7 +4,7 @@ import { s as SerializedSchema, t as SchemaHash, u as SerializedNodeDef, v as Se
 export { z as JsonSchema, C as SerializedOntology, D as SerializedUniqueConstraint } from '../fulltext-strategy-B57yvC5Q.js';
 import { a as NullCheckOp, K as KindEntity } from '../extension-types-ixRpJVUp.js';
 import { ZodType, ZodError } from 'zod';
-import { V as ValidationIssue, a as ValidationError } from '../index-6CSUAq-x.js';
+import { V as ValidationIssue, a as ValidationError } from '../index-BFvdmBPV.js';
 import 'drizzle-orm';
 import 'drizzle-orm/pg-core';
 import 'drizzle-orm/sqlite-core';

package/dist/schema/index.js

@@ -1,19 +1,19 @@
-import { KindRegistry, validateImpliesEndpointCompatibility } from '../chunk-K3PPLHY7.js';
-export { applyDeprecatedKinds, assertSchemaCurrent, computeSchemaDiff, computeSchemaHash, deserializeWherePredicate, ensureSchema, getActiveSchema, getMigrationActions, getSchemaChanges, initializeSchema, isBackwardsCompatible, isSchemaInitialized, loadActiveSchemaWithBootstrap, loadAndMergeGraphExtensionDocument, migrateSchema, parseSerializedSchema, rollbackSchema, serializeSchema } from '../chunk-K3PPLHY7.js';
+import { KindRegistry, validateImpliesEndpointCompatibility } from '../chunk-M75SUBFG.js';
+export { applyDeprecatedKinds, assertSchemaCurrent, computeSchemaDiff, computeSchemaHash, deserializeWherePredicate, ensureSchema, getActiveSchema, getMigrationActions, getSchemaChanges, initializeSchema, isBackwardsCompatible, isSchemaInitialized, loadActiveSchemaWithBootstrap, loadAndMergeGraphExtensionDocument, migrateSchema, parseSerializedSchema, rollbackSchema, serializeSchema } from '../chunk-M75SUBFG.js';
+export { createValidationError, validateEdgeProps, validateNodeProps, validateProps, wrapZodError } from '../chunk-SKCOUWAX.js';
 import '../chunk-UR7W5YQK.js';
-export { createValidationError, validateEdgeProps, validateNodeProps, validateProps, wrapZodError } from '../chunk-QWEUYILR.js';
 import '../chunk-OR5ZA5WP.js';
 import '../chunk-W63OVYY4.js';
 import '../chunk-FPIZFYHE.js';
 import '../chunk-5SEGFTZX.js';
-import '../chunk-QOTI55H7.js';
-import '../chunk-RGPG7EOJ.js';
-import '../chunk-I7ZUZKFD.js';
+import '../chunk-SXGE7ITL.js';
+import '../chunk-S5F7ZLP2.js';
+import '../chunk-JFUPDJXD.js';
 import '../chunk-OHMP6N2J.js';
 import '../chunk-KBGQIPRQ.js';
 import '../chunk-SNXVDZAJ.js';
 import '../chunk-ITE4IXAK.js';
-import '../chunk-MP2JQKSG.js';
+import '../chunk-WI7ISNQF.js';
 import '../chunk-G6Q5UM7U.js';
 
 // src/schema/deserializer.ts

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

@@ -1290,6 +1290,49 @@ type BaseStoreOptions = Readonly<{
      * 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. */
@@ -1350,7 +1393,9 @@ interface StoreRef<T> {
     current: T;
 }
 /**
- * Summary returned by `store.transactionWithReceipt(fn)`.
+ * 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;
@@ -1394,7 +1439,10 @@ type TransactionReceipt = Readonly<{
     /**
      * 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.
+     * 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;
 }>;
@@ -2032,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.
  *
@@ -2074,11 +2130,43 @@ type RecordedStoreViewEdgeCollections<G extends GraphDef> = {
  * Drizzle database type at the call site.
  *
  * When the store was created with `{ history: true }` or
- * `{ revisionTracking: true }`, `tx.sql` is present but replaced by a fail-loud
- * guard because raw SQL would bypass recorded-time capture or the revision
- * anchor. Use the typed `tx.nodes` / `tx.edges` collections inside
- * `transaction()`, or use `store.withRecordedTransaction(externalTx, fn)` when
- * the relational layer owns the transaction boundary.
+ * `{ 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
@@ -2093,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
@@ -2116,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.
@@ -4277,13 +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 }` or
-     *   `{ revisionTracking: true }`, `tx.sql` is replaced by a fail-loud guard
-     *   because raw SQL would bypass recorded-time capture or revision tracking;
-     *   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
@@ -4355,11 +4500,12 @@ declare class Store<G extends GraphDef> {
      *
      * The receipt does not count writes that bypass the `tx.nodes.*` /
      * `tx.edges.*` collections, such as direct backend writes, raw SQL, or
-     * import helpers. Adopted transactions (`withTransaction` /
-     * `withRecordedTransaction`) do not produce receipts in this version
-     * because their commit belongs to the caller. On non-transactional
-     * backends, the receipt is still returned, but it describes operations
-     * that individually committed rather than one atomic commit; if the
+     * 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.
      *
@@ -4367,6 +4513,12 @@ declare class Store<G extends GraphDef> {
      * 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) => {
@@ -4377,8 +4529,8 @@ declare class Store<G extends GraphDef> {
      * outcome.receipt.writes; // { nodes: { Person: 1 }, edges: {}, total: 1 }
      * ```
      */
-    transactionWithReceipt<T>(this: HistoryStore<G>, fn: (tx: HistoryTransactionContext<G>) => Promise<T>, options?: TransactionOptions): Promise<TransactionOutcome<T>>;
-    transactionWithReceipt<T>(fn: (tx: TransactionContext<G>) => Promise<T>, options?: TransactionOptions): Promise<TransactionOutcome<T>>;
+    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
@@ -4431,11 +4583,14 @@ declare class Store<G extends GraphDef> {
      *
      * 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
@@ -4451,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
@@ -4462,16 +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:
      *
-     * Like {@link Store.withTransaction}, the graph writes and any raw `tx.sql`
-     * 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.
+     * ```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.
      *
@@ -4729,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;
 }>;
@@ -4737,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"]>;
 }>;
@@ -4987,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 SelectContext 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 SearchScopeOptions as aX, type SearchableMetadata as aY, type SearchableOptions as aZ, type SearchableSchema 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 SelectableEdge as b0, type SelectableNode as b1, type ShortestPathOptions as b2, type ShortestPathResult as b3, type StoreHooks as b4, type StoreOptions as b5, type StoreProjection as b6, type StoreRef as b7, StoreSearch as b8, StoreView as b9, UnionableQuery as bA, type UpdateEdgeInput as bB, type UpdateNodeInput as bC, type VectorSearchHit as bD, type VectorSearchOptions as bE, asRecordedInstant as bF, createQueryBuilder as bG, createStore as bH, createStoreWithSchema as bI, createVerifiedStore as bJ, defineSubgraphProject as bK, embedding as bL, exists as bM, fieldRef as bN, getEmbeddingDimensions as bO, getSearchableMetadata as bP, inSubquery as bQ, isEmbeddingSchema as bR, isParameterRef as bS, isSearchableSchema as bT, notExists as bU, notInSubquery as bV, param as bW, searchable as bX, type StoreViewCanReachOptions as ba, type StoreViewCoordinate as bb, type StoreViewDegreeOptions as bc, type StoreViewEdgeCollection as bd, type StoreViewEdgeCollections as be, type StoreViewNeighborsOptions as bf, type StoreViewNodeCollection as bg, type StoreViewNodeCollections as bh, type StoreViewReachableOptions as bi, type StoreViewShortestPathOptions as bj, type StoreViewSubgraphOptions as bk, type StreamOptions as bl, type SubgraphEdgeResult as bm, type SubgraphNodeResult as bn, type SubgraphOptions as bo, type SubgraphResult as bp, type SubsetEdge as bq, type SubsetNode as br, type TemporalAlgorithmOptions as bs, type TransactionContext as bt, type TransactionOutcome as bu, type TransactionReceipt as bv, type TraversalDirection as bw, type TypedEdgeCollection as bx, type TypedRecordedStoreViewEdgeCollection as by, type TypedStoreViewEdgeCollection 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 };