@nicia-ai/typegraph 0.25.1 → 0.27.0

package/dist/{store-CkCvqRUf.d.cts → store-Ojf0NOKk.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-WF5ItKQu.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-Cy3dhwYO.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-DZPBXZOK.cjs';
+import { K as KindRegistry, G as GraphDef, u as EdgeKinds, x as NodeKinds, t as AllNodeTypes, c as SchemaManagerOptions, d as SchemaValidationResult } from './manager-CWa9cgwb.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-BB9N5uQl.cjs';
+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.
      *
@@ -3658,5 +3766,47 @@ declare function createStore<G extends GraphDef>(graph: G, backend: GraphBackend
  * ```
  */
 declare function createStoreWithSchema<G extends GraphDef>(graph: G, backend: GraphBackend, options?: StoreOptions & SchemaManagerOptions): Promise<[Store<G>, SchemaValidationResult]>;
+/**
+ * Creates a Store after **verifying** that the database is at the same
+ * schema version as the code graph — without running any DDL, bootstrap,
+ * or marker writes. The runtime counterpart of `createStoreWithSchema`
+ * for the deployment model in "Database roles & least privilege":
+ *
+ * - **`createStoreWithSchema(graph, backend)`** runs DDL (bootstrap,
+ *   safe auto-migrations, durable contribution materialization). Run it
+ *   once at startup under a privileged role that holds `CREATE` / DDL.
+ * - **`createVerifiedStore(graph, backend)`** is the zero-DDL runtime
+ *   attach with a verification gate. Throws `MigrationError` when the
+ *   persisted schema is behind the code graph (any pending change, safe
+ *   or breaking), `ConfigurationError` when no schema has been
+ *   initialized, or `StoreNotInitializedError` when the schema is
+ *   current but the runtime-contribution markers are missing/stale.
+ *   The runtime can use a least-privilege, DML-only database role.
+ * - **`createStore(graph, backend)`** is the same zero-DDL attach
+ *   *without* the verification gate — fastest, but schema drift goes
+ *   undetected until a hot-path operation trips.
+ *
+ * Folds any persisted graph-extension document into the supplied graph
+ * before building the Store, just like `createStoreWithSchema`.
+ *
+ * @param graph - The graph definition
+ * @param backend - The database backend
+ * @param options - Optional store configuration
+ * @returns A tuple of [store, validationResult] — `result.status` is
+ *   always `"unchanged"` on success
+ *
+ * @example
+ * ```typescript
+ * // Runtime — least-privilege, DML-only role. Zero DDL.
+ * const [store, result] = await createVerifiedStore(graph, backend);
+ * // result.status === "unchanged" — the privileged migrator is current.
+ * ```
+ *
+ * @throws ConfigurationError if no schema has been initialized.
+ * @throws MigrationError if the persisted schema is behind the code graph.
+ * @throws StoreNotInitializedError if runtime-contribution markers are
+ *   missing/stale/failed for this graph on this connection.
+ */
+declare function createVerifiedStore<G extends GraphDef>(graph: G, backend: GraphBackend, options?: StoreOptions): Promise<[Store<G>, SchemaValidationResult]>;
 
-export { type MaterializeRemovalsOptions as $, type AliasMap as A, type BaseTraversalOptions as B, type CreateQueryBuilderOptions as C, DEFAULT_SEARCHABLE_LANGUAGE as D, type EdgeAliasMap as E, type EmbeddingSchema as F, type EmbeddingValue as G, ExecutableAggregateQuery as H, ExecutableQuery as I, type FieldAccessor as J, type FulltextSearchHit as K, type FulltextSearchOptions as L, type GetOrCreateAction as M, type GraphAlgorithms as N, type GraphEdgeCollections as O, type GraphNodeCollections as P, QueryBuilder as Q, type HookContext as R, Store as S, TraversalBuilder as T, type HybridFulltextOptions as U, type HybridSearchHit as V, type HybridSearchOptions as W, type HybridVectorOptions as X, type IfExistsMode as Y, type KindIntrospection as Z, type MaterializeRemovalsEntry as _, type AggregateResult as a, getSearchableMetadata as a$, type MaterializeRemovalsResult as a0, type NeighborsOptions as a1, type Node as a2, type NodeAccessor as a3, type NodeAlias as a4, type NodeCollection as a5, type NodeGetOrCreateByConstraintOptions as a6, type NodeGetOrCreateByConstraintResult as a7, type NodeIdentifier as a8, type NodeRef as a9, type StoreProjection as aA, type StoreRef as aB, StoreSearch as aC, type StreamOptions as aD, type SubgraphEdgeResult as aE, type SubgraphNodeResult as aF, type SubgraphOptions as aG, type SubgraphResult as aH, type SubsetEdge as aI, type SubsetNode as aJ, type TemporalAlgorithmOptions as aK, type TransactionContext as aL, type TraversalDirection as aM, type TypedEdgeCollection as aN, UnionableQuery as aO, type UniqueIntrospection as aP, type UpdateEdgeInput as aQ, type UpdateNodeInput as aR, type VectorSearchHit as aS, type VectorSearchOptions as aT, createStore as aU, createStoreWithSchema as aV, defineSubgraphProject as aW, embedding as aX, exists as aY, fieldRef as aZ, getEmbeddingDimensions as a_, type OntologyIntrospection as aa, type OperationHookContext as ab, type PaginateOptions as ac, type PaginatedResult as ad, type PathNode as ae, type Predicate as af, PreparedQuery as ag, type PropsAccessor as ah, type QueryHookContext as ai, type QueryOptions as aj, type ReachableNode as ak, type ReachableOptions as al, type RebuildFulltextOptions as am, type RebuildFulltextResult as an, type RecursiveTraversalOptions as ao, type SchemaIntrospection as ap, type SearchableMetadata as aq, type SearchableOptions as ar, type SearchableSchema as as, type SelectContext as at, type SelectableEdge as au, type SelectableNode as av, type ShortestPathOptions as aw, type ShortestPathResult as ax, type StoreHooks as ay, type StoreOptions as az, type AlgorithmCyclePolicy as b, inSubquery as b0, isEmbeddingSchema as b1, isParameterRef as b2, isSearchableSchema as b3, notExists as b4, notInSubquery as b5, param as b6, searchable as b7, type AnyEdge as c, type AnyNode as d, type BatchResults as e, type BatchableQuery as f, type ConstraintNames as g, type CreateEdgeInput as h, type CreateNodeInput as i, type DegreeOptions as j, type DynamicEdgeAccessor as k, type DynamicEdgeCollection as l, type DynamicEdgeType as m, type DynamicFieldBuilder as n, type DynamicNodeAccessor as o, type DynamicNodeCollection as p, type DynamicNodeType as q, type DynamicSelectableEdge as r, type DynamicSelectableNode as s, type Edge as t, type EdgeAccessor as u, type EdgeCollection as v, type EdgeFindByEndpointsOptions as w, type EdgeGetOrCreateByEndpointsOptions as x, type EdgeGetOrCreateByEndpointsResult as y, type EdgeIntrospection as z };
+export { type MaterializeRemovalsOptions as $, type AliasMap as A, type BaseTraversalOptions as B, type CreateQueryBuilderOptions as C, DEFAULT_SEARCHABLE_LANGUAGE as D, type EdgeAliasMap as E, type EmbeddingSchema as F, type EmbeddingValue as G, ExecutableAggregateQuery as H, ExecutableQuery as I, type FieldAccessor as J, type FulltextSearchHit as K, type FulltextSearchOptions as L, type GetOrCreateAction as M, type GraphAlgorithms as N, type GraphEdgeCollections as O, type GraphNodeCollections as P, QueryBuilder as Q, type HookContext as R, Store as S, TraversalBuilder as T, type HybridFulltextOptions as U, type HybridSearchHit as V, type HybridSearchOptions as W, type HybridVectorOptions as X, type IfExistsMode as Y, type KindIntrospection as Z, type MaterializeRemovalsEntry as _, type AggregateResult as a, getEmbeddingDimensions as a$, type MaterializeRemovalsResult as a0, type NeighborsOptions as a1, type Node as a2, type NodeAccessor as a3, type NodeAlias as a4, type NodeCollection as a5, type NodeGetOrCreateByConstraintOptions as a6, type NodeGetOrCreateByConstraintResult as a7, type NodeIdentifier as a8, type NodeRef as a9, type StoreProjection as aA, type StoreRef as aB, StoreSearch as aC, type StreamOptions as aD, type SubgraphEdgeResult as aE, type SubgraphNodeResult as aF, type SubgraphOptions as aG, type SubgraphResult as aH, type SubsetEdge as aI, type SubsetNode as aJ, type TemporalAlgorithmOptions as aK, type TransactionContext as aL, type TraversalDirection as aM, type TypedEdgeCollection as aN, UnionableQuery as aO, type UniqueIntrospection as aP, type UpdateEdgeInput as aQ, type UpdateNodeInput as aR, type VectorSearchHit as aS, type VectorSearchOptions as aT, createStore as aU, createStoreWithSchema as aV, createVerifiedStore as aW, defineSubgraphProject as aX, embedding as aY, exists as aZ, fieldRef as a_, type OntologyIntrospection as aa, type OperationHookContext as ab, type PaginateOptions as ac, type PaginatedResult as ad, type PathNode as ae, type Predicate as af, PreparedQuery as ag, type PropsAccessor as ah, type QueryHookContext as ai, type QueryOptions as aj, type ReachableNode as ak, type ReachableOptions as al, type RebuildFulltextOptions as am, type RebuildFulltextResult as an, type RecursiveTraversalOptions as ao, type SchemaIntrospection as ap, type SearchableMetadata as aq, type SearchableOptions as ar, type SearchableSchema as as, type SelectContext as at, type SelectableEdge as au, type SelectableNode as av, type ShortestPathOptions as aw, type ShortestPathResult as ax, type StoreHooks as ay, type StoreOptions as az, type AlgorithmCyclePolicy as b, getSearchableMetadata as b0, inSubquery as b1, isEmbeddingSchema as b2, isParameterRef as b3, isSearchableSchema as b4, notExists as b5, notInSubquery as b6, param as b7, searchable as b8, type AnyEdge as c, type AnyNode as d, type BatchResults as e, type BatchableQuery as f, type ConstraintNames as g, type CreateEdgeInput as h, type CreateNodeInput as i, type DegreeOptions as j, type DynamicEdgeAccessor as k, type DynamicEdgeCollection as l, type DynamicEdgeType as m, type DynamicFieldBuilder as n, type DynamicNodeAccessor as o, type DynamicNodeCollection as p, type DynamicNodeType as q, type DynamicSelectableEdge as r, type DynamicSelectableNode as s, type Edge as t, type EdgeAccessor as u, type EdgeCollection as v, type EdgeFindByEndpointsOptions as w, type EdgeGetOrCreateByEndpointsOptions as x, type EdgeGetOrCreateByEndpointsResult as y, type EdgeIntrospection as z };

package/dist/{types-BpgACExN.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-WF5ItKQu.cjs';
+import { K as KindEntity } from './extension-types-B78CZfA5.cjs';
+import { J as JsonPointer } from './types-DZPBXZOK.cjs';
 
 /**
  * QueryProfiler types.

package/dist/{types-Bz-Pi681.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-DptZHe-l.js';
+import { K as KindEntity } from './extension-types-B78CZfA5.js';
+import { J as JsonPointer } from './types-Dzkr0Eqi.js';
 
 /**
  * QueryProfiler types.

package/dist/{types-DptZHe-l.d.ts → types-DZPBXZOK.d.cts}

@@ -1,6 +1,8 @@
 import { z } from 'zod';
-import { N as NodeType, d as EdgeType, U as UniquenessScope, C as Collation, D as DeleteBehavior, e as KindAnnotations, f as Cardinality, g as EndpointExistence, T as TemporalMode, G as GraphExtension, I as IndexEntity, K as KindEntity, a as NullCheckOp, A as AnyEdgeType } from './extension-types-D07e_NTw.js';
+import { N as NodeType, e as EdgeType, o as UniquenessScope, g as Collation, D as DeleteBehavior, d as KindAnnotations, f as Cardinality, k as EndpointExistence, T as TemporalMode, G as GraphExtension, I as IndexEntity, K as KindEntity, a as NullCheckOp, A as AnyEdgeType } from './extension-types-B78CZfA5.cjs';
 import { SQL } from 'drizzle-orm';
+import { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
+import { BaseSQLiteDatabase } from 'drizzle-orm/sqlite-core';
 
 /** Brand key for MetaEdge */
 declare const META_EDGE_BRAND: "__metaEdge";
@@ -170,6 +172,64 @@ declare function createSqlSchema(names?: Partial<SqlTableNames>): SqlSchema;
  */
 declare const DEFAULT_SQL_SCHEMA: SqlSchema;
 
+/**
+ * A single table TypeGraph owns.
+ */
+type TableContribution = Readonly<{
+    /**
+     * Stable, graph- and deployment-independent identity for the logical
+     * slot this contribution fills (e.g. `"fulltext"`). NOT the physical
+     * table name. Stable across table-name overrides and across strategy
+     * swaps of the *same* logical slot, so #135's durable marker can
+     * survive both.
+     */
+    logicalName: string;
+    /**
+     * Identifies the producer of this contribution (e.g. a strategy id
+     * like `"tsvector"` / `"fts5"`, or `"base"` for core schema tables).
+     * Part of the #135 materialization identity and an input to the
+     * drift signature — a strategy swap on the same `logicalName` is a
+     * legitimate, detectable drift, not a silent reuse.
+     */
+    owner: string;
+    /**
+     * Resolved physical table name after any per-deployment name
+     * override. Part of the #135 materialization identity (custom names
+     * must be distinguishable) and used by diagnostics / the focused
+     * bootstrap ensure.
+     */
+    tableName: string;
+    /**
+     * Idempotent (`CREATE ... IF NOT EXISTS`) statements that
+     * materialize this contribution's table **and its supporting
+     * indexes**. Running the full list is how the runtime ensure
+     * self-heals partial states (table present, index missing) — it is
+     * not a probe-and-skip. Deterministic for a given resolved
+     * configuration: the canonical normalized input to #135's drift
+     * signature.
+     */
+    createDdl: readonly string[];
+    /**
+     * When `true`, the post-schema-load focused ensure
+     * (`loadActiveSchemaWithBootstrap`) materializes this contribution
+     * on every successful schema load.
+     *
+     * **Invariant: only strategy-declared contributions may set this.**
+     * Core/base tables are always `false` — they are created by
+     * drizzle-kit / `bootstrapTables`. This is what lets the boot path
+     * derive runtime contributions straight from the strategy
+     * (`fulltextStrategy.ownedTables`) without walking — and generating
+     * DDL for — every base table.
+     */
+    runtimeEnsure: boolean;
+}>;
+/**
+ * A table a {@link FulltextStrategy} declares it owns. An alias, not a
+ * distinct shape: a strategy's declaration is already authoritative
+ * (no resolution step). The name documents the producer role.
+ */
+type StrategyTableContribution = TableContribution;
+
 /**
  * Fulltext Strategy — pluggable DDL + SQL generation for a dialect's
  * fulltext stack. A strategy owns every SQL statement that touches its
@@ -245,11 +305,20 @@ interface FulltextStrategy {
      */
     snippetExpression(tableName: string, query: string, mode: FulltextQueryMode, language?: string): SQL;
     /**
-     * DDL statements to create the backing table and any supporting
-     * indexes. Idempotent (`CREATE ... IF NOT EXISTS`). Called once from
-     * `bootstrapTables()` on a fresh database.
+     * The tables this strategy owns, as Drizzle-free, already
+     * authoritative `TableContribution`s (`logicalName`, `owner`,
+     * resolved `tableName`, idempotent `createDdl` for the table **and
+     * its supporting indexes**, `runtimeEnsure`). A strategy never
+     * constructs a Drizzle table itself; drizzle-kit visibility, when
+     * applicable, is the schema barrel's responsibility (the default
+     * Postgres strategy's `schema/postgres.ts` exports a matching
+     * `tables.fulltext` — a non-default strategy must export its own).
+     *
+     * Replaces the former `generateDdl(tableName)`: DDL is now one field
+     * of a contribution rather than the strategy's whole storage
+     * surface. (Public API change — see #129.)
      */
-    generateDdl(tableName: string): readonly string[];
+    ownedTables(primaryTableName: string): readonly StrategyTableContribution[];
     /**
      * Emits the statements that upsert a single fulltext row. Returns one
      * or more statements — some backends (SQLite FTS5) cannot emulate
@@ -445,6 +514,33 @@ type SerializedSchema = Readonly<{
  */
 type SchemaHash = string;
 
+type AnyPgDatabase = PgDatabase<PgQueryResultHKT, Record<string, unknown>>;
+
+/**
+ * Controls how the backend manages SQLite transactions.
+ *
+ * - `"sql"`:     TypeGraph issues BEGIN / COMMIT / ROLLBACK SQL directly.
+ *                Default for sync drivers (better-sqlite3, bun:sqlite).
+ * - `"drizzle"`: Delegates to Drizzle's `db.transaction()` method.
+ *                Default for async drivers (libsql, sql.js).
+ * - `"do-sqlite"`: Delegates to the Cloudflare Durable Objects async
+ *                storage transaction runner (`db.$client.transaction`,
+ *                i.e. `ctx.storage.transaction(async ...)`). Drizzle's
+ *                own `db.transaction()` on DO is
+ *                `ctx.storage.transactionSync` and cannot span `await`,
+ *                so it is deliberately not used. Auto-detected for
+ *                `drizzle(ctx.storage)` (#140).
+ * - `"none"`:    Transactions disabled. Default for Cloudflare D1
+ *                (`D1Database.batch` is transactional but not an
+ *                interactive runner — tracked separately).
+ */
+type SqliteTransactionMode = "sql" | "drizzle" | "none" | "do-sqlite";
+type SqliteExecutionProfileHints = Readonly<{
+    isSync?: boolean;
+    transactionMode?: SqliteTransactionMode;
+}>;
+type AnySqliteDatabase = BaseSQLiteDatabase<"sync" | "async", unknown>;
+
 /**
  * SQL Dialect Abstraction Layer
  *
@@ -914,6 +1010,63 @@ type RecordIndexMaterializationParams = Readonly<{
     /** Error message on failure; undefined on success (clears existing). */
     error: string | undefined;
 }>;
+/**
+ * Durable identity of a strategy-owned table contribution (#129),
+ * scoped to a graph. This is the primary key of
+ * `typegraph_contribution_materializations`.
+ *
+ * `logicalName` is the stable slot ("fulltext"); `owner` is the
+ * producing strategy ("tsvector" / "fts5"); `tableName` is the resolved
+ * physical name (custom per-deployment names must be distinguishable).
+ * `graphId` is part of identity here — unlike the index status table
+ * where the physical index name is database-global, two graphs can each
+ * own a logically-identical fulltext contribution.
+ */
+type ContributionMaterializationIdentity = Readonly<{
+    graphId: string;
+    logicalName: string;
+    owner: string;
+    tableName: string;
+}>;
+/**
+ * Per-deployment record that a strategy-owned contribution has been
+ * durably materialized against this database.
+ *
+ * `signature` is intentionally NOT part of the identity: a row with the
+ * same identity but a different signature means "materialized artifact
+ * is stale/drifted" — a loud error on the hot path, never a silent
+ * re-materialize. `materializedAt` is undefined until the first
+ * successful materialization; `lastAttemptedAt` is always set.
+ */
+type ContributionMaterializationRow = Readonly<{
+    graphId: string;
+    logicalName: string;
+    owner: string;
+    tableName: string;
+    signature: string;
+    materializedAt: string | undefined;
+    lastAttemptedAt: string;
+    lastError: string | undefined;
+}>;
+/**
+ * Parameters for upserting a contribution-materialization attempt.
+ * Same success/failure contract as
+ * {@link RecordIndexMaterializationParams}: on failure pass undefined
+ * `materializedAt` so a prior successful timestamp is preserved via
+ * COALESCE, and the error message.
+ */
+type RecordContributionMaterializationParams = Readonly<{
+    graphId: string;
+    logicalName: string;
+    owner: string;
+    tableName: string;
+    signature: string;
+    attemptedAt: string;
+    /** ISO timestamp on success; undefined on failure (preserves existing). */
+    materializedAt: string | undefined;
+    /** Error message on failure; undefined on success (clears existing). */
+    error: string | undefined;
+}>;
 /**
  * One row of the per-deployment `typegraph_kind_removals` table:
  * a graph-extension kind that has been removed from the schema and whose
@@ -955,6 +1108,21 @@ type TransactionOptions = Readonly<{
     /** Transaction isolation level (if supported) */
     isolationLevel?: "read_uncommitted" | "read_committed" | "repeatable_read" | "serializable";
 }>;
+/**
+ * A caller-owned, already-open Drizzle transaction handle that a
+ * TypeGraph store can adopt so both layers commit/rollback together.
+ *
+ * The literal client the caller's transaction runs on — a `PgDatabase`
+ * transaction (node-postgres / `neon-serverless` Pool) or a
+ * `BaseSQLiteDatabase` connection. Async drivers obtain it from
+ * `db.transaction(async (tx) => …)`; synchronous `better-sqlite3` (whose
+ * driver rejects an `async` transaction callback) passes the connection
+ * itself under an explicit `BEGIN`/`COMMIT`/`ROLLBACK`. Passing it to
+ * {@link GraphBackend.adoptTransaction} threads that *literal* client
+ * through TypeGraph's SQL, so graph writes and the caller's own
+ * relational writes share one Postgres/SQLite transaction (#134).
+ */
+type AdoptedTransaction = AnyPgDatabase | AnySqliteDatabase;
 /**
  * Transaction backend — a backend scoped to a transaction.
  *
@@ -968,7 +1136,7 @@ type TransactionOptions = Readonly<{
  * exists to eliminate. Schema commits go through the top-level backend
  * methods only.
  */
-type TransactionBackend = Omit<GraphBackend, "transaction" | "close" | "refreshStatistics" | "commitSchemaVersion" | "setActiveVersion">;
+type TransactionBackend = Omit<GraphBackend, "transaction" | "adoptTransaction" | "close" | "refreshStatistics" | "commitSchemaVersion" | "setActiveVersion">;
 /**
  * The GraphBackend interface abstracts database operations.
  *
@@ -1107,6 +1275,40 @@ type GraphBackend = Readonly<{
      * timestamp survives across error windows.
      */
     recordIndexMaterialization?: (params: RecordIndexMaterializationParams) => Promise<void>;
+    /**
+     * Idempotently ensure ONLY the
+     * `typegraph_contribution_materializations` table exists. Same
+     * focused-bootstrap rationale as `ensureIndexMaterializationsTable`:
+     * a single `CREATE TABLE IF NOT EXISTS` is concurrency-safe under
+     * replica startup, where the full `bootstrapTables` set risks a
+     * Postgres SHARE-lock deadlock.
+     */
+    ensureContributionMaterializationsTable?: () => Promise<void>;
+    /**
+     * Look up the durable materialization marker for one strategy-owned
+     * contribution identity. Returns `undefined` when no row exists
+     * ("never initialized").
+     */
+    getContributionMaterialization?: (identity: ContributionMaterializationIdentity) => Promise<ContributionMaterializationRow | undefined>;
+    /**
+     * Upsert a contribution-materialization attempt — success or failure.
+     * Failure rows preserve any prior `materializedAt` via COALESCE so a
+     * later failed re-attempt doesn't erase the historical success.
+     */
+    recordContributionMaterialization?: (params: RecordContributionMaterializationParams) => Promise<void>;
+    /**
+     * Resolve (once per backend instance, cached) and assert the durable
+     * materialization markers for every `runtimeEnsure` contribution this
+     * backend's strategy declares, for `graphId`. Throws
+     * `StoreNotInitializedError` when a marker is missing, stale
+     * (signature drift), or recorded a failed last attempt.
+     *
+     * This is the single read-side gate the fulltext hot-path wrappers
+     * and `store.transaction()` consult. It performs ZERO DDL and ZERO
+     * marker writes — initialization is the exclusive job of the async
+     * boot path (`createStoreWithSchema` → `ensureRuntimeContributions`).
+     */
+    assertRuntimeContributionsInitialized?: (graphId: string) => Promise<void>;
     /**
      * Bootstraps the per-deployment `typegraph_kind_removals` table so
      * `store.removeKinds()` and `store.materializeRemovals()` can persist
@@ -1149,15 +1351,32 @@ type GraphBackend = Readonly<{
      * deadlock under concurrent replica startup.
      */
     ensureReconciliationMarkersTable?: () => Promise<void>;
+    /**
+     * Materializes every contribution flagged `runtimeEnsure` — the
+     * strategy-owned runtime tables (fulltext today) that drizzle-kit-
+     * managed setups don't create. Called once after a successful schema
+     * load. Deliberately scoped: base/drizzle-visible tables are
+     * `runtimeEnsure: false`, so this does not regress startup into
+     * broad DDL/probing across every table.
+     *
+     * The canonical durable-marker writer (#135): for each runtime
+     * contribution it short-circuits when the marker already records a
+     * matching signature, otherwise runs the idempotent `createDdl` and
+     * records the marker (success or failure) keyed by `graphId`.
+     */
+    ensureRuntimeContributions?: (graphId: string) => Promise<void>;
     /**
      * Bootstraps the fulltext storage table the active `FulltextStrategy`
-     * owns — the strategy owns this DDL because shapes diverge across
-     * stacks (`tsvector` + GIN, FTS5 virtual table, pg_trgm, …) and
-     * the SQLite case can't be Drizzle-modeled at all. Same focused-
-     * bootstrap rationale as the other `ensure*Table` methods:
-     * idempotent and concurrency-safe under replica startup.
+     * owns. Same focused-bootstrap rationale as the other `ensure*Table`
+     * methods: idempotent and concurrency-safe under replica startup.
+     *
+     * Superseded by `ensureRuntimeContributions()` (#129); retained as
+     * a thin back-compat wrapper for backends/callers predating #129. Not
+     * machine-`@deprecated` because the manager still calls it as the
+     * pre-#129 fallback. #135 removed the remaining hot-path callers and
+     * routed this through the durable-marker writer.
      */
-    ensureFulltextTable?: () => Promise<void>;
+    ensureFulltextTable?: (graphId: string) => Promise<void>;
     /**
      * Read the high-water mark schema version for which
      * `materializeRemovals` reconciliation has already verified history
@@ -1225,7 +1444,46 @@ type GraphBackend = Readonly<{
      * statement outside `transaction(...)`.
      */
     executeDdl?: (ddl: string) => Promise<void>;
-    transaction: <T>(fn: (tx: TransactionBackend) => Promise<T>, options?: TransactionOptions) => Promise<T>;
+    /**
+     * `fn` receives the tx-scoped backend and the raw Drizzle handle
+     * **bound to that same transaction** (`AdoptedTransaction`). The
+     * store surfaces the second argument as `TransactionContext.sql` so
+     * callers can write their own relational tables inside the
+     * graph-owned transaction. Implementations MUST pass the *exact*
+     * handle the tx-scoped backend writes through (the Postgres/libsql
+     * tx handle; for better-sqlite3 / do-sqlite the bound connection),
+     * never a fresh one.
+     */
+    transaction: <T>(fn: (tx: TransactionBackend, sql: AdoptedTransaction) => Promise<T>, options?: TransactionOptions) => Promise<T>;
+    /**
+     * Adopt a caller-owned, already-open transaction (#134).
+     *
+     * Returns a transaction-scoped backend bound to the *exact*
+     * `externalTx` client, reusing this backend's already-resolved
+     * schema/strategy config — no `createStoreWithSchema` / `evolve` /
+     * `migrateSchema`, and **no DDL inside the caller's business
+     * transaction**. The caller owns `BEGIN`/`COMMIT`/`ROLLBACK`; this
+     * method neither opens nor closes a transaction. Async drivers
+     * (node-postgres, `neon-serverless` Pool, libsql) wrap with
+     * `db.transaction(async …)`; synchronous `better-sqlite3` must instead
+     * issue explicit `BEGIN`/`COMMIT`/`ROLLBACK` (its driver rejects an
+     * `async` transaction callback).
+     *
+     * Optional and presence-detected like the other capability-scoped
+     * members: only the Drizzle Postgres/SQLite backends provide it.
+     * Implementations MUST throw (not silently degrade) when
+     * `capabilities.transactions` is `false` — a non-atomic fallback is
+     * safe for graph-only writes but dangerous for cross-store flows,
+     * where the caller's relational write *would* still commit.
+     *
+     * Fulltext stays safe by construction: the returned backend's
+     * fulltext methods assert the durable materialization marker (a
+     * cached SELECT, never DDL) at point of use and throw
+     * `StoreNotInitializedError` on a missing/stale/failed marker rather
+     * than migrating mid-transaction. Prefer booting the parent store via
+     * `createStoreWithSchema` so that assertion is a warm-cache no-op.
+     */
+    adoptTransaction?: (externalTx: AdoptedTransaction) => TransactionBackend;
     close: () => Promise<void>;
 }>;
 /**
@@ -2129,4 +2387,4 @@ type RelationalIndexDeclaration = NodeIndexDeclaration | EdgeIndexDeclaration;
 type IndexDeclaration = RelationalIndexDeclaration | VectorIndexDeclaration;
 type SystemColumnName = "graph_id" | "kind" | "id" | "from_kind" | "from_id" | "to_kind" | "to_id" | "deleted_at" | "valid_from" | "valid_to" | "created_at" | "updated_at" | "version";
 
-export { type JsonPointerFor as $, type AggregateExpr as A, type BackendCapabilities as B, type FieldRef as C, type ComparisonOp as D, type EdgeIndexConfig as E, type FulltextStrategy as F, type GraphBackend as G, type AggregateComparisonPredicate as H, type IndexDeclaration as I, type JsonPointer as J, type CommitSchemaVersionExpected as K, type CommitSchemaVersionParams as L, type MetaEdge as M, type NodeIndexConfig as N, type OntologyRelation as O, DEFAULT_SQL_SCHEMA as P, type QueryAst as Q, type RelationalIndexDeclaration as R, type SerializedNodeDef as S, type DeleteFulltextBatchParams as T, type FulltextBatchRow as U, type VectorIndexDeclaration as V, type FulltextCapabilities as W, type FulltextQueryMode as X, type FulltextSearchParams as Y, type FulltextSearchResult as Z, type HybridFusionOptions as _, type EdgeIndexDeclaration as a, type JsonPointerInput as a0, type JsonPointerSegment as a1, type JsonPointerSegments as a2, type JsonPointerSegmentsFor as a3, MAX_JSON_POINTER_DEPTH as a4, type MetaEdgeProperties as a5, type OrderSpec as a6, type ParameterRef as a7, type ResolveJsonPointer as a8, type ResolveJsonPointerSegments as a9, type NodeRow as aA, type SelectiveField as aB, type ComposableQuery as aC, type SetOperationType as aD, type SetOperation as aE, type VectorMetric as aF, type SetActiveVersionParams as aa, type SortDirection as ab, type SqlSchema as ac, type SqlTableNames as ad, type TransactionBackend as ae, type TraversalExpansion as af, type UpsertFulltextBatchParams as ag, type VectorCapabilities as ah, createSqlSchema as ai, fts5Strategy as aj, isMetaEdge as ak, joinJsonPointers as al, jsonPointer as am, normalizeJsonPointer as an, parseJsonPointer as ao, tsvectorStrategy as ap, type ValueType as aq, type PredicateExpression as ar, type VectorMetricType as as, type Traversal as at, type NodePredicate as au, type ProjectedField as av, type GroupBySpec as aw, type RecursiveCyclePolicy as ax, type TraversalDirection as ay, type EdgeRow as az, type NodeIndexDeclaration as b, type IndexWhereExpression as c, type SerializedEdgeDef as d, type SerializedMetaEdge as e, type SerializedOntologyRelation as f, type SerializedClosures as g, type SerializedSchema as h, type SchemaHash as i, type JsonSchema as j, type SerializedOntology as k, type SerializedUniqueConstraint as l, type SqlDialect as m, type EdgeIndexDirection as n, type EdgeIndexWhereBuilder as o, type IndexOrigin as p, type IndexScope as q, type IndexWhereFieldBuilder as r, type IndexWhereInput as s, type NodeIndexWhereBuilder as t, type SystemColumnName as u, type VectorIndexImplementation as v, type VectorIndexMetric as w, type VectorIndexParams as x, type SchemaVersionRow as y, type InferenceType as z };
+export { type FulltextCapabilities as $, type AnySqliteDatabase as A, type BackendCapabilities as B, type VectorIndexParams as C, type SchemaVersionRow as D, type EdgeIndexConfig as E, type FulltextStrategy as F, type GraphBackend as G, type InferenceType as H, type IndexDeclaration as I, type JsonPointer as J, type AggregateExpr as K, type FieldRef as L, type MetaEdge as M, type NodeIndexConfig as N, type OntologyRelation as O, type ComparisonOp as P, type QueryAst as Q, type RelationalIndexDeclaration as R, type SqliteExecutionProfileHints as S, type AggregateComparisonPredicate as T, type AdoptedTransaction as U, type VectorIndexDeclaration as V, type CommitSchemaVersionExpected as W, type CommitSchemaVersionParams as X, DEFAULT_SQL_SCHEMA as Y, type DeleteFulltextBatchParams as Z, type FulltextBatchRow as _, type SqliteTransactionMode as a, type FulltextQueryMode as a0, type FulltextSearchParams as a1, type FulltextSearchResult as a2, type HybridFusionOptions as a3, type JsonPointerFor as a4, type JsonPointerInput as a5, type JsonPointerSegment as a6, type JsonPointerSegments as a7, type JsonPointerSegmentsFor as a8, MAX_JSON_POINTER_DEPTH as a9, type Traversal as aA, type NodePredicate as aB, type ProjectedField as aC, type GroupBySpec as aD, type RecursiveCyclePolicy as aE, type TraversalDirection as aF, type EdgeRow as aG, type NodeRow as aH, type SelectiveField as aI, type ComposableQuery as aJ, type SetOperationType as aK, type SetOperation as aL, type VectorMetric as aM, type MetaEdgeProperties as aa, type OrderSpec as ab, type ParameterRef as ac, type ResolveJsonPointer as ad, type ResolveJsonPointerSegments as ae, type SetActiveVersionParams as af, type SortDirection as ag, type SqlSchema as ah, type SqlTableNames as ai, type StrategyTableContribution as aj, type TableContribution as ak, type TransactionBackend as al, type TraversalExpansion as am, type UpsertFulltextBatchParams as an, type VectorCapabilities as ao, createSqlSchema as ap, fts5Strategy as aq, isMetaEdge as ar, joinJsonPointers as as, jsonPointer as at, normalizeJsonPointer as au, parseJsonPointer as av, tsvectorStrategy as aw, type ValueType as ax, type PredicateExpression as ay, type VectorMetricType as az, type AnyPgDatabase as b, type EdgeIndexDeclaration as c, type NodeIndexDeclaration as d, type IndexWhereExpression as e, type SerializedNodeDef as f, type SerializedEdgeDef as g, type SerializedMetaEdge as h, type SerializedOntologyRelation as i, type SerializedClosures as j, type SerializedSchema as k, type SchemaHash as l, type JsonSchema as m, type SerializedOntology as n, type SerializedUniqueConstraint as o, type SqlDialect as p, type EdgeIndexDirection as q, type EdgeIndexWhereBuilder as r, type IndexOrigin as s, type IndexScope as t, type IndexWhereFieldBuilder as u, type IndexWhereInput as v, type NodeIndexWhereBuilder as w, type SystemColumnName as x, type VectorIndexImplementation as y, type VectorIndexMetric as z };