@nicia-ai/typegraph 0.25.0 → 0.26.0

package/dist/{sqlite-CU3j6rc7.d.ts → sqlite-GKvcDPVn.d.ts}

@@ -1,5 +1,5 @@
 import * as drizzle_orm_sqlite_core from 'drizzle-orm/sqlite-core';
-import { I as IndexDeclaration } from './types-BNWYZ-0-.js';
+import { I as IndexDeclaration } from './types-Dzkr0Eqi.js';
 
 /**
  * Table name configuration.
@@ -12,6 +12,7 @@ type SqliteTableNames = Readonly<{
     embeddings: string;
     fulltext: string;
     indexMaterializations: string;
+    contributionMaterializations: string;
     kindRemovals: string;
     reconciliationMarkers: string;
 }>;
@@ -1066,6 +1067,165 @@ declare function createSqliteTables(names?: Partial<SqliteTableNames>, options?:
         };
         dialect: "sqlite";
     }>;
+    readonly contributionMaterializations: drizzle_orm_sqlite_core.SQLiteTableWithColumns<{
+        name: string;
+        schema: undefined;
+        columns: {
+            graphId: drizzle_orm_sqlite_core.SQLiteColumn<{
+                name: "graph_id";
+                tableName: string;
+                dataType: "string";
+                columnType: "SQLiteText";
+                data: string;
+                driverParam: string;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {
+                length: number | undefined;
+            }>;
+            logicalName: drizzle_orm_sqlite_core.SQLiteColumn<{
+                name: "logical_name";
+                tableName: string;
+                dataType: "string";
+                columnType: "SQLiteText";
+                data: string;
+                driverParam: string;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {
+                length: number | undefined;
+            }>;
+            owner: drizzle_orm_sqlite_core.SQLiteColumn<{
+                name: "owner";
+                tableName: string;
+                dataType: "string";
+                columnType: "SQLiteText";
+                data: string;
+                driverParam: string;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {
+                length: number | undefined;
+            }>;
+            tableName: drizzle_orm_sqlite_core.SQLiteColumn<{
+                name: "table_name";
+                tableName: string;
+                dataType: "string";
+                columnType: "SQLiteText";
+                data: string;
+                driverParam: string;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {
+                length: number | undefined;
+            }>;
+            signature: drizzle_orm_sqlite_core.SQLiteColumn<{
+                name: "signature";
+                tableName: string;
+                dataType: "string";
+                columnType: "SQLiteText";
+                data: string;
+                driverParam: string;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {
+                length: number | undefined;
+            }>;
+            materializedAt: drizzle_orm_sqlite_core.SQLiteColumn<{
+                name: "materialized_at";
+                tableName: string;
+                dataType: "string";
+                columnType: "SQLiteText";
+                data: string;
+                driverParam: string;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {
+                length: number | undefined;
+            }>;
+            lastAttemptedAt: drizzle_orm_sqlite_core.SQLiteColumn<{
+                name: "last_attempted_at";
+                tableName: string;
+                dataType: "string";
+                columnType: "SQLiteText";
+                data: string;
+                driverParam: string;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {
+                length: number | undefined;
+            }>;
+            lastError: drizzle_orm_sqlite_core.SQLiteColumn<{
+                name: "last_error";
+                tableName: string;
+                dataType: "string";
+                columnType: "SQLiteText";
+                data: string;
+                driverParam: string;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {
+                length: number | undefined;
+            }>;
+        };
+        dialect: "sqlite";
+    }>;
     readonly kindRemovals: drizzle_orm_sqlite_core.SQLiteTableWithColumns<{
         name: string;
         schema: undefined;
@@ -2295,6 +2455,165 @@ declare const tables: {
         };
         dialect: "sqlite";
     }>;
+    readonly contributionMaterializations: drizzle_orm_sqlite_core.SQLiteTableWithColumns<{
+        name: string;
+        schema: undefined;
+        columns: {
+            graphId: drizzle_orm_sqlite_core.SQLiteColumn<{
+                name: "graph_id";
+                tableName: string;
+                dataType: "string";
+                columnType: "SQLiteText";
+                data: string;
+                driverParam: string;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {
+                length: number | undefined;
+            }>;
+            logicalName: drizzle_orm_sqlite_core.SQLiteColumn<{
+                name: "logical_name";
+                tableName: string;
+                dataType: "string";
+                columnType: "SQLiteText";
+                data: string;
+                driverParam: string;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {
+                length: number | undefined;
+            }>;
+            owner: drizzle_orm_sqlite_core.SQLiteColumn<{
+                name: "owner";
+                tableName: string;
+                dataType: "string";
+                columnType: "SQLiteText";
+                data: string;
+                driverParam: string;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {
+                length: number | undefined;
+            }>;
+            tableName: drizzle_orm_sqlite_core.SQLiteColumn<{
+                name: "table_name";
+                tableName: string;
+                dataType: "string";
+                columnType: "SQLiteText";
+                data: string;
+                driverParam: string;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {
+                length: number | undefined;
+            }>;
+            signature: drizzle_orm_sqlite_core.SQLiteColumn<{
+                name: "signature";
+                tableName: string;
+                dataType: "string";
+                columnType: "SQLiteText";
+                data: string;
+                driverParam: string;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {
+                length: number | undefined;
+            }>;
+            materializedAt: drizzle_orm_sqlite_core.SQLiteColumn<{
+                name: "materialized_at";
+                tableName: string;
+                dataType: "string";
+                columnType: "SQLiteText";
+                data: string;
+                driverParam: string;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {
+                length: number | undefined;
+            }>;
+            lastAttemptedAt: drizzle_orm_sqlite_core.SQLiteColumn<{
+                name: "last_attempted_at";
+                tableName: string;
+                dataType: "string";
+                columnType: "SQLiteText";
+                data: string;
+                driverParam: string;
+                notNull: true;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {
+                length: number | undefined;
+            }>;
+            lastError: drizzle_orm_sqlite_core.SQLiteColumn<{
+                name: "last_error";
+                tableName: string;
+                dataType: "string";
+                columnType: "SQLiteText";
+                data: string;
+                driverParam: string;
+                notNull: false;
+                hasDefault: false;
+                isPrimaryKey: false;
+                isAutoincrement: false;
+                hasRuntimeDefault: false;
+                enumValues: [string, ...string[]];
+                baseColumn: never;
+                identity: undefined;
+                generated: undefined;
+            }, {}, {
+                length: number | undefined;
+            }>;
+        };
+        dialect: "sqlite";
+    }>;
     readonly kindRemovals: drizzle_orm_sqlite_core.SQLiteTableWithColumns<{
         name: string;
         schema: undefined;

package/dist/{store-BAGuOHDh.d.cts → store-CiS_AGNH.d.ts}

@@ -1,9 +1,9 @@
 import { z } from 'zod';
-import { m as SqlDialect, ac as SqlSchema, F as FulltextStrategy, aq as ValueType, ar as PredicateExpression, as as VectorMetricType, X as FulltextQueryMode, Q as QueryAst, J as JsonPointer, C as FieldRef, a7 as ParameterRef, G as GraphBackend, ae as TransactionBackend, a0 as JsonPointerInput, af as TraversalExpansion, at as Traversal, au as NodePredicate, av as ProjectedField, a6 as OrderSpec, aw as GroupBySpec, _ as HybridFusionOptions, ax as RecursiveCyclePolicy, ay as TraversalDirection$1, az as EdgeRow, aA as NodeRow, A as AggregateExpr, aB as SelectiveField, aC as ComposableQuery, aD as SetOperationType, aE as SetOperation, ab as SortDirection, j as JsonSchema, aF as VectorMetric } from './types--0EslBx5.cjs';
-import { K as KindRegistry, G as GraphDef, t as EdgeKinds, w as NodeKinds, s as AllNodeTypes, c as SchemaManagerOptions, d as SchemaValidationResult } from './manager-BpjBW1JK.cjs';
-import { A as AnyEdgeType, N as NodeType, T as TemporalMode, d as EdgeType, E as EdgeRegistration, i as EdgeId, m as NodeId, b as NodeRegistration, K as KindEntity, f as Cardinality, g as EndpointExistence, e as KindAnnotations, U as UniquenessScope, C as Collation, G as GraphExtension } from './extension-types-D07e_NTw.cjs';
+import { p as SqlDialect, ah as SqlSchema, F as FulltextStrategy, ax as ValueType, ay as PredicateExpression, az as VectorMetricType, a0 as FulltextQueryMode, Q as QueryAst, J as JsonPointer, L as FieldRef, ac as ParameterRef, G as GraphBackend, al as TransactionBackend, a5 as JsonPointerInput, am as TraversalExpansion, aA as Traversal, aB as NodePredicate, aC as ProjectedField, ab as OrderSpec, aD as GroupBySpec, a3 as HybridFusionOptions, aE as RecursiveCyclePolicy, aF as TraversalDirection$1, aG as EdgeRow, aH as NodeRow, U as AdoptedTransaction, K as AggregateExpr, aI as SelectiveField, aJ as ComposableQuery, aK as SetOperationType, aL as SetOperation, ag as SortDirection, m as JsonSchema, aM as VectorMetric } from './types-Dzkr0Eqi.js';
+import { K as KindRegistry, G as GraphDef, t as EdgeKinds, w as NodeKinds, s as AllNodeTypes, c as SchemaManagerOptions, d as SchemaValidationResult } from './manager-C3LxzPcX.js';
+import { A as AnyEdgeType, N as NodeType, T as TemporalMode, e as EdgeType, E as EdgeRegistration, h as EdgeId, m as NodeId, b as NodeRegistration, K as KindEntity, f as Cardinality, k as EndpointExistence, d as KindAnnotations, o as UniquenessScope, g as Collation, G as GraphExtension } from './extension-types-B78CZfA5.js';
 import { SQL } from 'drizzle-orm';
-import { b as MaterializeIndexesOptions, M as MaterializeIndexesResult } from './materialize-indexes-BB9N5uQl.cjs';
+import { b as MaterializeIndexesOptions, M as MaterializeIndexesResult } from './materialize-indexes-DFavFQah.js';
 
 /**
  * Embedding type for vector search.
@@ -1615,6 +1615,41 @@ type GraphEdgeCollections<G extends GraphDef> = {
  * Provides the same `tx.nodes.*` and `tx.edges.*` API as the Store,
  * but operations are executed within the transaction scope.
  *
+ * `tx.sql` is the raw Drizzle handle **bound to this same
+ * transaction** — use it to write the caller's own relational tables
+ * inside the graph-owned transaction so both layers commit or roll
+ * back together (the graph-owned counterpart of
+ * {@link Store.withTransaction}, where the caller owns the boundary):
+ *
+ * ```typescript
+ * await store.transaction(async (tx) => {
+ *   await tx.nodes.Document.update(documentId, props);
+ *   // `tx.sql` is the `AdoptedTransaction` union — cast to your
+ *   // concrete Drizzle database type at the call site.
+ *   const sqlTx = tx.sql as NodePgDatabase;
+ *   await sqlTx.insert(documentVersions).values(versionRow);
+ *   await sqlTx.insert(changeEvents).values(eventRow);
+ * });
+ * ```
+ *
+ * Per-backend semantics:
+ * - **Postgres / libsql** (async drivers): `tx.sql` is the Drizzle
+ *   transaction handle. Using the outer `db` instead would write on a
+ *   *different* connection and silently escape the transaction — so
+ *   `tx.sql` is a correctness requirement there.
+ * - **better-sqlite3**: the single connection, framed by TypeGraph's
+ *   `BEGIN`/`COMMIT`/`ROLLBACK`.
+ * - **Durable Objects (`do-sqlite`)**: the bound Drizzle handle; the
+ *   storage transaction is ambient, so writing the outer `db` also
+ *   enlists — `tx.sql` is the explicit, portable form.
+ *
+ * It is `undefined` only on the non-transactional fallback
+ * (`backend.capabilities.transactions === false` — e.g. Cloudflare
+ * D1, `drizzle-orm/neon-http`), where `store.transaction()` runs the
+ * callback with no atomicity and there is no transaction to enlist.
+ * Its type is the `AdoptedTransaction` union; cast to your concrete
+ * Drizzle database type at the call site.
+ *
  * @example
  * ```typescript
  * await store.transaction(async (tx) => {
@@ -1627,6 +1662,7 @@ type GraphEdgeCollections<G extends GraphDef> = {
 type TransactionContext<G extends GraphDef> = Readonly<{
     nodes: GraphNodeCollections<G>;
     edges: GraphEdgeCollections<G>;
+    sql?: AdoptedTransaction;
 }>;
 /**
  * Replace branded `NodeId` / `EdgeId` with plain `string` in each
@@ -3341,6 +3377,12 @@ declare class Store<G extends GraphDef> {
      * The transaction context provides the same collection API as the Store:
      * - `tx.nodes.Person.create(...)` - Create a node
      * - `tx.edges.worksAt.create(...)` - Create an edge
+     * - `tx.sql` - the raw Drizzle handle **bound to this same
+     *   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.
      *
      * @example
      * ```typescript
@@ -3355,6 +3397,16 @@ declare class Store<G extends GraphDef> {
      * });
      * ```
      *
+     * @example Cross-store write via `tx.sql` (graph-owned boundary):
+     * ```typescript
+     * await store.transaction(async (tx) => {
+     *   await tx.nodes.Document.update(documentId, props);
+     *   // cast `tx.sql` to your concrete Drizzle database type
+     *   const sqlTx = tx.sql as NodePgDatabase;
+     *   await sqlTx.insert(documentVersions).values(versionRow);
+     * });
+     * ```
+     *
      * **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
@@ -3371,6 +3423,62 @@ declare class Store<G extends GraphDef> {
      * ```
      */
     transaction<T>(fn: (tx: TransactionContext<G>) => Promise<T>): Promise<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
+     * Postgres/SQLite transaction (#134).
+     *
+     * Use this when the **relational layer owns the transaction**: the
+     * caller has opened a transaction and needs TypeGraph writes enlisted
+     * on the *same* connection. Unlike {@link transaction}, this opens no
+     * transaction — the caller's transaction is the single commit/rollback
+     * boundary.
+     *
+     * `withTransaction` is driver-agnostic; how the caller opens the
+     * transaction is not. **Async drivers** (node-postgres,
+     * `neon-serverless` Pool, libsql) use `db.transaction(async …)`.
+     * **Synchronous `better-sqlite3`** cannot — its driver rejects an
+     * `async` transaction callback (`Transaction function cannot return a
+     * promise`) and the async continuation would run outside the
+     * rolled-back transaction — so the caller opens the transaction with
+     * explicit `BEGIN`/`COMMIT`/`ROLLBACK` on the single connection
+     * instead. See the "Cross-Store Transactions" recipe for both shapes.
+     *
+     * The returned context reuses this store's already-resolved
+     * schema/registry: it runs **no** schema bootstrap, `evolve`, or
+     * migration, and emits **no DDL** inside the caller's transaction.
+     * Fulltext operations assert the durable materialization marker (a
+     * cached SELECT) and throw {@link StoreNotInitializedError} on a
+     * missing/stale/failed marker rather than migrating mid-transaction —
+     * so boot the parent store via `createStoreWithSchema` once at
+     * startup.
+     *
+     * @example
+     * ```typescript
+     * // Async driver (Postgres / libsql):
+     * await db.transaction(async (sqlTx) => {
+     *   const connector = await createConnectorRow(sqlTx, input); // Drizzle
+     *   const txStore = store.withTransaction(sqlTx);
+     *   await txStore.nodes.ArtifactSource.create({              // TypeGraph
+     *     connectorId: connector.id,
+     *   });
+     * }); // one COMMIT / ROLLBACK across both layers
+     * ```
+     *
+     * @throws {ConfigurationError} when the backend cannot adopt an
+     *   external transaction — either it is not a Drizzle Postgres/SQLite
+     *   backend, or `backend.capabilities.transactions` is `false`
+     *   (`drizzle-orm/neon-http`, Cloudflare D1, SQLite
+     *   `transactionMode: "none"`). A non-atomic fallback is deliberately
+     *   not offered here: the caller's relational write *would* still
+     *   commit, defeating the purpose of cross-store atomicity.
+     * @throws {StoreNotInitializedError} at point of use, when a fulltext
+     *   operation on the returned context observes a missing/stale/failed
+     *   durable materialization marker (parent store not booted via
+     *   `createStoreWithSchema`). Rolls back the caller's transaction
+     *   without emitting any DDL.
+     */
+    withTransaction(externalTx: AdoptedTransaction): TransactionContext<G>;
     /**
      * Hard-deletes all data for this graph from the database.
      *

package/dist/{store-De98Lod4.d.ts → store-DbQLsSor.d.cts}

@@ -1,9 +1,9 @@
 import { z } from 'zod';
-import { m as SqlDialect, ac as SqlSchema, F as FulltextStrategy, aq as ValueType, ar as PredicateExpression, as as VectorMetricType, X as FulltextQueryMode, Q as QueryAst, J as JsonPointer, C as FieldRef, a7 as ParameterRef, G as GraphBackend, ae as TransactionBackend, a0 as JsonPointerInput, af as TraversalExpansion, at as Traversal, au as NodePredicate, av as ProjectedField, a6 as OrderSpec, aw as GroupBySpec, _ as HybridFusionOptions, ax as RecursiveCyclePolicy, ay as TraversalDirection$1, az as EdgeRow, aA as NodeRow, A as AggregateExpr, aB as SelectiveField, aC as ComposableQuery, aD as SetOperationType, aE as SetOperation, ab as SortDirection, j as JsonSchema, aF as VectorMetric } from './types-BNWYZ-0-.js';
-import { K as KindRegistry, G as GraphDef, t as EdgeKinds, w as NodeKinds, s as AllNodeTypes, c as SchemaManagerOptions, d as SchemaValidationResult } from './manager-BKaPQbns.js';
-import { A as AnyEdgeType, N as NodeType, T as TemporalMode, d as EdgeType, E as EdgeRegistration, i as EdgeId, m as NodeId, b as NodeRegistration, K as KindEntity, f as Cardinality, g as EndpointExistence, e as KindAnnotations, U as UniquenessScope, C as Collation, G as GraphExtension } from './extension-types-D07e_NTw.js';
+import { p as SqlDialect, ah as SqlSchema, F as FulltextStrategy, ax as ValueType, ay as PredicateExpression, az as VectorMetricType, a0 as FulltextQueryMode, Q as QueryAst, J as JsonPointer, L as FieldRef, ac as ParameterRef, G as GraphBackend, al as TransactionBackend, a5 as JsonPointerInput, am as TraversalExpansion, aA as Traversal, aB as NodePredicate, aC as ProjectedField, ab as OrderSpec, aD as GroupBySpec, a3 as HybridFusionOptions, aE as RecursiveCyclePolicy, aF as TraversalDirection$1, aG as EdgeRow, aH as NodeRow, U as AdoptedTransaction, K as AggregateExpr, aI as SelectiveField, aJ as ComposableQuery, aK as SetOperationType, aL as SetOperation, ag as SortDirection, m as JsonSchema, aM as VectorMetric } from './types-DZPBXZOK.cjs';
+import { K as KindRegistry, G as GraphDef, t as EdgeKinds, w as NodeKinds, s as AllNodeTypes, c as SchemaManagerOptions, d as SchemaValidationResult } from './manager-Aqzmztkb.cjs';
+import { A as AnyEdgeType, N as NodeType, T as TemporalMode, e as EdgeType, E as EdgeRegistration, h as EdgeId, m as NodeId, b as NodeRegistration, K as KindEntity, f as Cardinality, k as EndpointExistence, d as KindAnnotations, o as UniquenessScope, g as Collation, G as GraphExtension } from './extension-types-B78CZfA5.cjs';
 import { SQL } from 'drizzle-orm';
-import { b as MaterializeIndexesOptions, M as MaterializeIndexesResult } from './materialize-indexes-BYpU2RKh.js';
+import { b as MaterializeIndexesOptions, M as MaterializeIndexesResult } from './materialize-indexes-BQfaAZKA.cjs';
 
 /**
  * Embedding type for vector search.
@@ -1615,6 +1615,41 @@ type GraphEdgeCollections<G extends GraphDef> = {
  * Provides the same `tx.nodes.*` and `tx.edges.*` API as the Store,
  * but operations are executed within the transaction scope.
  *
+ * `tx.sql` is the raw Drizzle handle **bound to this same
+ * transaction** — use it to write the caller's own relational tables
+ * inside the graph-owned transaction so both layers commit or roll
+ * back together (the graph-owned counterpart of
+ * {@link Store.withTransaction}, where the caller owns the boundary):
+ *
+ * ```typescript
+ * await store.transaction(async (tx) => {
+ *   await tx.nodes.Document.update(documentId, props);
+ *   // `tx.sql` is the `AdoptedTransaction` union — cast to your
+ *   // concrete Drizzle database type at the call site.
+ *   const sqlTx = tx.sql as NodePgDatabase;
+ *   await sqlTx.insert(documentVersions).values(versionRow);
+ *   await sqlTx.insert(changeEvents).values(eventRow);
+ * });
+ * ```
+ *
+ * Per-backend semantics:
+ * - **Postgres / libsql** (async drivers): `tx.sql` is the Drizzle
+ *   transaction handle. Using the outer `db` instead would write on a
+ *   *different* connection and silently escape the transaction — so
+ *   `tx.sql` is a correctness requirement there.
+ * - **better-sqlite3**: the single connection, framed by TypeGraph's
+ *   `BEGIN`/`COMMIT`/`ROLLBACK`.
+ * - **Durable Objects (`do-sqlite`)**: the bound Drizzle handle; the
+ *   storage transaction is ambient, so writing the outer `db` also
+ *   enlists — `tx.sql` is the explicit, portable form.
+ *
+ * It is `undefined` only on the non-transactional fallback
+ * (`backend.capabilities.transactions === false` — e.g. Cloudflare
+ * D1, `drizzle-orm/neon-http`), where `store.transaction()` runs the
+ * callback with no atomicity and there is no transaction to enlist.
+ * Its type is the `AdoptedTransaction` union; cast to your concrete
+ * Drizzle database type at the call site.
+ *
  * @example
  * ```typescript
  * await store.transaction(async (tx) => {
@@ -1627,6 +1662,7 @@ type GraphEdgeCollections<G extends GraphDef> = {
 type TransactionContext<G extends GraphDef> = Readonly<{
     nodes: GraphNodeCollections<G>;
     edges: GraphEdgeCollections<G>;
+    sql?: AdoptedTransaction;
 }>;
 /**
  * Replace branded `NodeId` / `EdgeId` with plain `string` in each
@@ -3341,6 +3377,12 @@ declare class Store<G extends GraphDef> {
      * The transaction context provides the same collection API as the Store:
      * - `tx.nodes.Person.create(...)` - Create a node
      * - `tx.edges.worksAt.create(...)` - Create an edge
+     * - `tx.sql` - the raw Drizzle handle **bound to this same
+     *   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.
      *
      * @example
      * ```typescript
@@ -3355,6 +3397,16 @@ declare class Store<G extends GraphDef> {
      * });
      * ```
      *
+     * @example Cross-store write via `tx.sql` (graph-owned boundary):
+     * ```typescript
+     * await store.transaction(async (tx) => {
+     *   await tx.nodes.Document.update(documentId, props);
+     *   // cast `tx.sql` to your concrete Drizzle database type
+     *   const sqlTx = tx.sql as NodePgDatabase;
+     *   await sqlTx.insert(documentVersions).values(versionRow);
+     * });
+     * ```
+     *
      * **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
@@ -3371,6 +3423,62 @@ declare class Store<G extends GraphDef> {
      * ```
      */
     transaction<T>(fn: (tx: TransactionContext<G>) => Promise<T>): Promise<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
+     * Postgres/SQLite transaction (#134).
+     *
+     * Use this when the **relational layer owns the transaction**: the
+     * caller has opened a transaction and needs TypeGraph writes enlisted
+     * on the *same* connection. Unlike {@link transaction}, this opens no
+     * transaction — the caller's transaction is the single commit/rollback
+     * boundary.
+     *
+     * `withTransaction` is driver-agnostic; how the caller opens the
+     * transaction is not. **Async drivers** (node-postgres,
+     * `neon-serverless` Pool, libsql) use `db.transaction(async …)`.
+     * **Synchronous `better-sqlite3`** cannot — its driver rejects an
+     * `async` transaction callback (`Transaction function cannot return a
+     * promise`) and the async continuation would run outside the
+     * rolled-back transaction — so the caller opens the transaction with
+     * explicit `BEGIN`/`COMMIT`/`ROLLBACK` on the single connection
+     * instead. See the "Cross-Store Transactions" recipe for both shapes.
+     *
+     * The returned context reuses this store's already-resolved
+     * schema/registry: it runs **no** schema bootstrap, `evolve`, or
+     * migration, and emits **no DDL** inside the caller's transaction.
+     * Fulltext operations assert the durable materialization marker (a
+     * cached SELECT) and throw {@link StoreNotInitializedError} on a
+     * missing/stale/failed marker rather than migrating mid-transaction —
+     * so boot the parent store via `createStoreWithSchema` once at
+     * startup.
+     *
+     * @example
+     * ```typescript
+     * // Async driver (Postgres / libsql):
+     * await db.transaction(async (sqlTx) => {
+     *   const connector = await createConnectorRow(sqlTx, input); // Drizzle
+     *   const txStore = store.withTransaction(sqlTx);
+     *   await txStore.nodes.ArtifactSource.create({              // TypeGraph
+     *     connectorId: connector.id,
+     *   });
+     * }); // one COMMIT / ROLLBACK across both layers
+     * ```
+     *
+     * @throws {ConfigurationError} when the backend cannot adopt an
+     *   external transaction — either it is not a Drizzle Postgres/SQLite
+     *   backend, or `backend.capabilities.transactions` is `false`
+     *   (`drizzle-orm/neon-http`, Cloudflare D1, SQLite
+     *   `transactionMode: "none"`). A non-atomic fallback is deliberately
+     *   not offered here: the caller's relational write *would* still
+     *   commit, defeating the purpose of cross-store atomicity.
+     * @throws {StoreNotInitializedError} at point of use, when a fulltext
+     *   operation on the returned context observes a missing/stale/failed
+     *   durable materialization marker (parent store not booted via
+     *   `createStoreWithSchema`). Rolls back the caller's transaction
+     *   without emitting any DDL.
+     */
+    withTransaction(externalTx: AdoptedTransaction): TransactionContext<G>;
     /**
      * Hard-deletes all data for this graph from the database.
      *

package/dist/{types-CYga3lZp.d.cts → types-CF7nDH3q.d.cts}

@@ -1,5 +1,5 @@
-import { K as KindEntity } from './extension-types-D07e_NTw.cjs';
-import { J as JsonPointer } from './types--0EslBx5.cjs';
+import { K as KindEntity } from './extension-types-B78CZfA5.cjs';
+import { J as JsonPointer } from './types-DZPBXZOK.cjs';
 
 /**
  * QueryProfiler types.

package/dist/{types-BLmJq4wI.d.ts → types-Cars4JZ1.d.ts}

@@ -1,5 +1,5 @@
-import { K as KindEntity } from './extension-types-D07e_NTw.js';
-import { J as JsonPointer } from './types-BNWYZ-0-.js';
+import { K as KindEntity } from './extension-types-B78CZfA5.js';
+import { J as JsonPointer } from './types-Dzkr0Eqi.js';
 
 /**
  * QueryProfiler types.