@atscript/db-sqlite 0.1.127 → 0.1.129

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbUpdateResult, TExistingColumn, TFieldOps, TSearchIndexInfo, TSyncColumnResult, TValueFormatterPair } from "@atscript/db";
+import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TFieldOps, TGenericLogger, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TValueFormatterPair } from "@atscript/db";
 import { TMetadataMap } from "@atscript/typescript/utils";
 import { FilterExpr as FilterExpr$1 } from "@uniqu/core";
 import { TSqlFragment, TSqlFragment as TSqlFragment$1 } from "@atscript/db-sql-tools";
@@ -54,6 +54,176 @@ interface TSqliteDriver {
   readonly hasVectorExt?: boolean;
 }
 //#endregion
+//#region src/better-sqlite3-driver.d.ts
+interface TBetterSqlite3DriverOptions extends Record<string, unknown> {
+  /** Load the optional `sqlite-vec` extension. */
+  vector?: boolean;
+  /** Absolute paths to SQLite loadable extensions, passed to `Database.loadExtension`. */
+  loadExtensions?: string[];
+}
+/**
+ * {@link TSqliteDriver} implementation backed by `better-sqlite3`.
+ *
+ * Accepts either a file path (opens a new database) or a pre-created
+ * `Database` instance from `better-sqlite3`.
+ *
+ * ```typescript
+ * import { BetterSqlite3Driver } from '@atscript/db-sqlite'
+ *
+ * // In-memory database
+ * const driver = new BetterSqlite3Driver(':memory:')
+ *
+ * // File-based database
+ * const driver = new BetterSqlite3Driver('./my-data.db')
+ *
+ * // With sqlite-vec extension loaded
+ * const driver = new BetterSqlite3Driver('./my-data.db', { vector: true })
+ *
+ * // Pre-created instance
+ * import Database from 'better-sqlite3'
+ * const db = new Database(':memory:', { verbose: console.log })
+ * const driver = new BetterSqlite3Driver(db)
+ * ```
+ *
+ * Requires `better-sqlite3` to be installed:
+ * ```bash
+ * pnpm add better-sqlite3
+ * ```
+ *
+ * Vector search support requires the optional `sqlite-vec` package:
+ * ```bash
+ * pnpm add sqlite-vec
+ * ```
+ */
+declare class BetterSqlite3Driver implements TSqliteDriver {
+  private db;
+  readonly hasVectorExt: boolean;
+  constructor(pathOrDb: string | import("better-sqlite3").Database, options?: TBetterSqlite3DriverOptions);
+  run(sql: string, params?: unknown[]): TSqliteRunResult;
+  all<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+  get<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;
+  exec(sql: string): void;
+  close(): void;
+}
+//#endregion
+//#region src/tx-gate.d.ts
+/**
+ * Per-waiter options for the transaction gate (taken from the adapter's
+ * {@link SqliteAdapterOptions} at wait time — the gate itself is per driver).
+ */
+interface SqliteTxWaitOptions {
+  /**
+   * Max milliseconds a waiter blocks for the connection before rejecting with
+   * `DbError("TX_WAIT_TIMEOUT")`. Default: unbounded (matches the mysql2 / pg
+   * pool defaults).
+   */
+  transactionWaitTimeoutMs?: number;
+  /**
+   * Log a warning through `logger` once a waiter has waited this long.
+   * Default: 5000 ms. `0` disables the warning.
+   */
+  transactionWaitWarnMs?: number;
+  /** Logger for the wait warning (the adapter passes its own). */
+  logger?: TGenericLogger;
+}
+/** Options accepted by `SqliteAdapter` / `createAdapter` for the transaction gate. */
+type SqliteAdapterOptions = Pick<SqliteTxWaitOptions, "transactionWaitTimeoutMs" | "transactionWaitWarnMs">;
+/**
+ * One waiter for the gate, created once per `_stmt` / `acquire` call and kept
+ * across wake-ups: the timeout and warn timers are armed ONCE with an absolute
+ * deadline, so `transactionWaitTimeoutMs` bounds the waiter's TOTAL wait
+ * however many transactions run ahead of it, and a re-queued waiter allocates
+ * nothing new. `next()` resolves on the next release (or rejects once the
+ * deadline passed); `dispose()` clears the timers.
+ */
+declare class GateWaiter {
+  private readonly _gate;
+  private _resolve?;
+  private _reject?;
+  private _timeoutTimer?;
+  private _warnTimer?;
+  private _expired?;
+  private readonly _startedAt;
+  constructor(_gate: SqliteTxGate, opts: SqliteTxWaitOptions | undefined);
+  /** Resolves on the NEXT release; rejects with `TX_WAIT_TIMEOUT` once the deadline passed. */
+  next(): Promise<void>;
+  /** Called by the gate on release: wakes the pending `next()` (a no-op when none is pending). */
+  wake(): void;
+  dispose(): void;
+}
+/**
+ * Logical FIFO mutex around the single synchronous SQLite connection.
+ *
+ * SQLite has one connection per driver, so two async contexts cannot each
+ * own a transaction: a second `BEGIN` fails with "cannot start a transaction
+ * within a transaction", and — worse — any statement from another context
+ * that runs while a transaction is open executes INSIDE that transaction
+ * (rolled back with it, reads its uncommitted rows). The gate serialises:
+ *
+ * - {@link acquire} / {@link release} — taken by `BEGIN`, released by
+ *   `COMMIT` / `ROLLBACK`;
+ * - {@link runWhenFree} — plain (non-transactional) statements check
+ *   {@link held} synchronously right before executing and wait otherwise;
+ * - {@link runExclusive} — hold the connection without a transaction (schema sync).
+ *
+ * Fairness: one FIFO waiter list for acquirers and statement waiters alike;
+ * a release wakes every current waiter in registration order, each re-checks
+ * synchronously and re-queues (ahead of any new arrival) if someone ahead took
+ * the gate. A waiter is one object with timers armed once, whatever the
+ * number of wake-ups. The fast path (nothing held) allocates nothing.
+ */
+declare class SqliteTxGate {
+  /** True while a transaction (or an exclusive hold) owns the connection. */
+  held: boolean;
+  /** `Date.now()` when the current holder took the gate (0 when free). */
+  heldSince: number;
+  private _waiters;
+  /** True when the current async context holds this gate via {@link runExclusive}. */
+  get heldByCurrentContext(): boolean;
+  /**
+   * Waits until the gate is free, then takes it synchronously (no `await`
+   * between the check and `held = true`). Pair with {@link release}.
+   */
+  acquire(opts?: SqliteTxWaitOptions): Promise<void>;
+  /** Frees the gate and wakes every waiter (in registration order). */
+  release(): void;
+  /**
+   * Runs one synchronous statement once no transaction holds the connection
+   * (immediately when the gate is free). The `held` check and `fn` run in
+   * the same synchronous segment, so they cannot interleave with a `BEGIN`
+   * from another context.
+   */
+  runWhenFree<R>(fn: () => R, opts?: SqliteTxWaitOptions): Promise<R>;
+  /**
+   * Holds the gate for the duration of `fn` WITHOUT opening a transaction
+   * (nested transactions inside `fn` still `BEGIN`/`COMMIT` on the held
+   * connection without re-acquiring). Re-entrant for the same async context.
+   */
+  runExclusive<T>(fn: () => Promise<T>, opts?: SqliteTxWaitOptions): Promise<T>;
+  /** @internal */
+  _enqueue(waiter: GateWaiter): void;
+  /** @internal */
+  _dequeue(waiter: GateWaiter): void;
+}
+/**
+ * Transaction state returned by `SqliteAdapter._beginTransaction`: releases
+ * the gate the transaction holds exactly once (a transaction opened inside an
+ * exclusive hold owns nothing to release). Ownership across adapters is
+ * decided by the core (`_transactionOwner()` = the driver), not here.
+ */
+declare class SqliteTxState {
+  private readonly _gate;
+  private _holdsGate;
+  constructor(_gate: SqliteTxGate, _holdsGate: boolean);
+  release(): void;
+}
+/**
+ * Returns the gate for a driver instance (one gate per driver — every adapter
+ * of a space shares its driver, so they share the gate; two driver wrappers
+ * around one `Database` would get two gates: construct one driver per database).
+ */
+declare function getSqliteTxGate(driver: TSqliteDriver): SqliteTxGate;
+//#endregion
 //#region src/sqlite-adapter.d.ts
 /**
  * SQLite adapter for {@link AtscriptDbTable}.
@@ -83,14 +253,42 @@ declare class SqliteAdapter extends BaseDbAdapter {
   private _vectorThresholds;
   /** Partition filter fields per vector index (from @db.search.filter). Field paths. */
   private _vectorPartitionFields;
-  constructor(driver: TSqliteDriver);
+  /** Per-driver transaction gate (shared by every adapter over this driver). */
+  private readonly _gate;
+  private readonly _txOptions;
+  constructor(driver: TSqliteDriver, options?: SqliteAdapterOptions);
   onFieldScanned(field: string, _type: unknown, metadata: TMetadataMap<AtscriptMetadata>): void;
   formatValue(field: TDbFieldMeta): TValueFormatterPair | undefined;
   isVectorSearchable(): boolean;
   private _detectVectorSupport;
-  protected _beginTransaction(): Promise<unknown>;
-  protected _commitTransaction(): Promise<void>;
-  protected _rollbackTransaction(): Promise<void>;
+  private _waitOpts;
+  /** Every adapter over this driver shares one transaction — and one gate (since 0.1.128). */
+  protected _transactionOwner(): unknown;
+  /** Inside our own transaction, or holding the connection exclusively. */
+  private _ownsConnection;
+  /**
+   * Runs one synchronous driver statement. Inside our own transaction (or an
+   * exclusive hold) it runs immediately; otherwise it waits until no
+   * transaction is open on the connection. The `held` check and the statement
+   * run in the same synchronous segment, so they cannot interleave with a
+   * `BEGIN` from another context.
+   */
+  private _stmt;
+  /**
+   * Holds the connection for the duration of `fn` WITHOUT opening a
+   * transaction: no other context's statement or transaction can interleave.
+   * Meant for the schema entry points that `await` mid-body or toggle
+   * connection-level PRAGMAs (`ensureTable`, `recreateTable`, `dropColumns`,
+   * `dropTablesByName`, `syncIndexes`) — their DDL must not land inside a
+   * request's transaction (PRAGMA changes are no-ops inside one). Inside our
+   * own transaction `fn` runs directly; re-entrant for the same async
+   * context; nested `withTransaction` calls inside `fn` still BEGIN/COMMIT
+   * on the held connection.
+   */
+  protected _withExclusiveConnection<T>(fn: () => Promise<T>): Promise<T>;
+  protected _beginTransaction(): Promise<SqliteTxState>;
+  protected _commitTransaction(state: unknown): Promise<void>;
+  protected _rollbackTransaction(state: unknown): Promise<void>;
   /** SQLite does not use schemas — override to always exclude schema. */
   resolveTableName(): string;
   /** SQLite enforces FK constraints natively via PRAGMA foreign_keys. */
@@ -113,7 +311,11 @@ declare class SqliteAdapter extends BaseDbAdapter {
   replaceMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
   deleteOne(filter: FilterExpr): Promise<TDbDeleteResult>;
   deleteMany(filter: FilterExpr): Promise<TDbDeleteResult>;
-  ensureTable(): Promise<void>;
+  /**
+   * SQLite accepts forward FK references, so a foreign-key cycle is created
+   * inline in any order — `opts.deferForeignKeysTo` is accepted and ignored.
+   */
+  ensureTable(_opts?: TEnsureTableOptions): Promise<void>;
   private _incrementSeeded;
   /**
    * Seeds the sqlite_sequence table for auto-increment fields that have a start value.
@@ -129,6 +331,25 @@ declare class SqliteAdapter extends BaseDbAdapter {
   dropIndexesForColumns(columns: string[]): Promise<void>;
   dropTableByName(tableName: string): Promise<void>;
   dropViewByName(viewName: string): Promise<void>;
+  /**
+   * Drops a group of mutually referencing tables with FK enforcement off for
+   * the duration (`PRAGMA foreign_keys` is a no-op inside a transaction, so
+   * the exclusive connection hold — not a `BEGIN` — keeps another context's
+   * transaction from overlapping it). Safe because schema sync only passes
+   * groups whose referrers are all inside the group.
+   */
+  dropTablesByName(tableNames: string[]): Promise<void>;
+  hasRows(tableName?: string): Promise<boolean>;
+  /**
+   * Live foreign keys referencing `tableName`: `PRAGMA foreign_key_list` is
+   * outbound-only, so the tables in `sqlite_master` are scanned (a loop
+   * rather than the `pragma_foreign_key_list` table-valued function, which
+   * not every bundled SQLite exposes). Only tables whose CREATE text contains
+   * `REFERENCES` can declare a foreign key — the prefilter is a superset, a
+   * false positive just costs one PRAGMA.
+   */
+  getReferencingForeignKeys(tableName: string): Promise<TReferencingForeignKey[]>;
+  getObjectKind(name: string): Promise<TDbObjectKind | undefined>;
   renameTable(oldName: string): Promise<void>;
   typeMapper(field: TDbFieldMeta): string;
   getExistingColumnsForTable(tableName: string): Promise<TExistingColumn[]>;
@@ -214,58 +435,6 @@ declare class SqliteAdapter extends BaseDbAdapter {
   private _dropAllVecTables;
 }
 //#endregion
-//#region src/better-sqlite3-driver.d.ts
-interface TBetterSqlite3DriverOptions extends Record<string, unknown> {
-  /** Load the optional `sqlite-vec` extension. */
-  vector?: boolean;
-  /** Absolute paths to SQLite loadable extensions, passed to `Database.loadExtension`. */
-  loadExtensions?: string[];
-}
-/**
- * {@link TSqliteDriver} implementation backed by `better-sqlite3`.
- *
- * Accepts either a file path (opens a new database) or a pre-created
- * `Database` instance from `better-sqlite3`.
- *
- * ```typescript
- * import { BetterSqlite3Driver } from '@atscript/db-sqlite'
- *
- * // In-memory database
- * const driver = new BetterSqlite3Driver(':memory:')
- *
- * // File-based database
- * const driver = new BetterSqlite3Driver('./my-data.db')
- *
- * // With sqlite-vec extension loaded
- * const driver = new BetterSqlite3Driver('./my-data.db', { vector: true })
- *
- * // Pre-created instance
- * import Database from 'better-sqlite3'
- * const db = new Database(':memory:', { verbose: console.log })
- * const driver = new BetterSqlite3Driver(db)
- * ```
- *
- * Requires `better-sqlite3` to be installed:
- * ```bash
- * pnpm add better-sqlite3
- * ```
- *
- * Vector search support requires the optional `sqlite-vec` package:
- * ```bash
- * pnpm add sqlite-vec
- * ```
- */
-declare class BetterSqlite3Driver implements TSqliteDriver {
-  private db;
-  readonly hasVectorExt: boolean;
-  constructor(pathOrDb: string | import("better-sqlite3").Database, options?: TBetterSqlite3DriverOptions);
-  run(sql: string, params?: unknown[]): TSqliteRunResult;
-  all<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
-  get<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;
-  exec(sql: string): void;
-  close(): void;
-}
-//#endregion
 //#region src/filter-builder.d.ts
 /**
  * Translates a uniqu filter expression into a parameterized SQL WHERE clause.
@@ -276,6 +445,8 @@ declare class BetterSqlite3Driver implements TSqliteDriver {
 declare function buildWhere(filter: FilterExpr$1): TSqlFragment$1;
 //#endregion
 //#region src/index.d.ts
-declare function createAdapter(connection: string, options?: Record<string, unknown>): DbSpace;
+/** `createAdapter` options: driver options plus the transaction-gate options (since 0.1.128). */
+type TCreateSqliteAdapterOptions = TBetterSqlite3DriverOptions & SqliteAdapterOptions;
+declare function createAdapter(connection: string, options?: TCreateSqliteAdapterOptions): DbSpace;
 //#endregion
-export { BetterSqlite3Driver, SqliteAdapter, type TSqlFragment, type TSqliteDriver, type TSqliteRunResult, buildWhere, createAdapter };
+export { BetterSqlite3Driver, SqliteAdapter, type SqliteAdapterOptions, SqliteTxGate, SqliteTxState, type SqliteTxWaitOptions, type TBetterSqlite3DriverOptions, TCreateSqliteAdapterOptions, type TSqlFragment, type TSqliteDriver, type TSqliteRunResult, buildWhere, createAdapter, getSqliteTxGate };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbUpdateResult, TExistingColumn, TFieldOps, TSearchIndexInfo, TSyncColumnResult, TValueFormatterPair } from "@atscript/db";
+import { BaseDbAdapter, DbQuery, DbSpace, FilterExpr, TColumnDiff, TDbDeleteResult, TDbFieldMeta, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateResult, TEnsureTableOptions, TExistingColumn, TFieldOps, TGenericLogger, TReferencingForeignKey, TSearchIndexInfo, TSyncColumnResult, TValueFormatterPair } from "@atscript/db";
 import { TSqlFragment, TSqlFragment as TSqlFragment$1 } from "@atscript/db-sql-tools";
 import { TMetadataMap } from "@atscript/typescript/utils";
 import { FilterExpr as FilterExpr$1 } from "@uniqu/core";
@@ -54,6 +54,176 @@ interface TSqliteDriver {
   readonly hasVectorExt?: boolean;
 }
 //#endregion
+//#region src/better-sqlite3-driver.d.ts
+interface TBetterSqlite3DriverOptions extends Record<string, unknown> {
+  /** Load the optional `sqlite-vec` extension. */
+  vector?: boolean;
+  /** Absolute paths to SQLite loadable extensions, passed to `Database.loadExtension`. */
+  loadExtensions?: string[];
+}
+/**
+ * {@link TSqliteDriver} implementation backed by `better-sqlite3`.
+ *
+ * Accepts either a file path (opens a new database) or a pre-created
+ * `Database` instance from `better-sqlite3`.
+ *
+ * ```typescript
+ * import { BetterSqlite3Driver } from '@atscript/db-sqlite'
+ *
+ * // In-memory database
+ * const driver = new BetterSqlite3Driver(':memory:')
+ *
+ * // File-based database
+ * const driver = new BetterSqlite3Driver('./my-data.db')
+ *
+ * // With sqlite-vec extension loaded
+ * const driver = new BetterSqlite3Driver('./my-data.db', { vector: true })
+ *
+ * // Pre-created instance
+ * import Database from 'better-sqlite3'
+ * const db = new Database(':memory:', { verbose: console.log })
+ * const driver = new BetterSqlite3Driver(db)
+ * ```
+ *
+ * Requires `better-sqlite3` to be installed:
+ * ```bash
+ * pnpm add better-sqlite3
+ * ```
+ *
+ * Vector search support requires the optional `sqlite-vec` package:
+ * ```bash
+ * pnpm add sqlite-vec
+ * ```
+ */
+declare class BetterSqlite3Driver implements TSqliteDriver {
+  private db;
+  readonly hasVectorExt: boolean;
+  constructor(pathOrDb: string | import("better-sqlite3").Database, options?: TBetterSqlite3DriverOptions);
+  run(sql: string, params?: unknown[]): TSqliteRunResult;
+  all<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
+  get<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;
+  exec(sql: string): void;
+  close(): void;
+}
+//#endregion
+//#region src/tx-gate.d.ts
+/**
+ * Per-waiter options for the transaction gate (taken from the adapter's
+ * {@link SqliteAdapterOptions} at wait time — the gate itself is per driver).
+ */
+interface SqliteTxWaitOptions {
+  /**
+   * Max milliseconds a waiter blocks for the connection before rejecting with
+   * `DbError("TX_WAIT_TIMEOUT")`. Default: unbounded (matches the mysql2 / pg
+   * pool defaults).
+   */
+  transactionWaitTimeoutMs?: number;
+  /**
+   * Log a warning through `logger` once a waiter has waited this long.
+   * Default: 5000 ms. `0` disables the warning.
+   */
+  transactionWaitWarnMs?: number;
+  /** Logger for the wait warning (the adapter passes its own). */
+  logger?: TGenericLogger;
+}
+/** Options accepted by `SqliteAdapter` / `createAdapter` for the transaction gate. */
+type SqliteAdapterOptions = Pick<SqliteTxWaitOptions, "transactionWaitTimeoutMs" | "transactionWaitWarnMs">;
+/**
+ * One waiter for the gate, created once per `_stmt` / `acquire` call and kept
+ * across wake-ups: the timeout and warn timers are armed ONCE with an absolute
+ * deadline, so `transactionWaitTimeoutMs` bounds the waiter's TOTAL wait
+ * however many transactions run ahead of it, and a re-queued waiter allocates
+ * nothing new. `next()` resolves on the next release (or rejects once the
+ * deadline passed); `dispose()` clears the timers.
+ */
+declare class GateWaiter {
+  private readonly _gate;
+  private _resolve?;
+  private _reject?;
+  private _timeoutTimer?;
+  private _warnTimer?;
+  private _expired?;
+  private readonly _startedAt;
+  constructor(_gate: SqliteTxGate, opts: SqliteTxWaitOptions | undefined);
+  /** Resolves on the NEXT release; rejects with `TX_WAIT_TIMEOUT` once the deadline passed. */
+  next(): Promise<void>;
+  /** Called by the gate on release: wakes the pending `next()` (a no-op when none is pending). */
+  wake(): void;
+  dispose(): void;
+}
+/**
+ * Logical FIFO mutex around the single synchronous SQLite connection.
+ *
+ * SQLite has one connection per driver, so two async contexts cannot each
+ * own a transaction: a second `BEGIN` fails with "cannot start a transaction
+ * within a transaction", and — worse — any statement from another context
+ * that runs while a transaction is open executes INSIDE that transaction
+ * (rolled back with it, reads its uncommitted rows). The gate serialises:
+ *
+ * - {@link acquire} / {@link release} — taken by `BEGIN`, released by
+ *   `COMMIT` / `ROLLBACK`;
+ * - {@link runWhenFree} — plain (non-transactional) statements check
+ *   {@link held} synchronously right before executing and wait otherwise;
+ * - {@link runExclusive} — hold the connection without a transaction (schema sync).
+ *
+ * Fairness: one FIFO waiter list for acquirers and statement waiters alike;
+ * a release wakes every current waiter in registration order, each re-checks
+ * synchronously and re-queues (ahead of any new arrival) if someone ahead took
+ * the gate. A waiter is one object with timers armed once, whatever the
+ * number of wake-ups. The fast path (nothing held) allocates nothing.
+ */
+declare class SqliteTxGate {
+  /** True while a transaction (or an exclusive hold) owns the connection. */
+  held: boolean;
+  /** `Date.now()` when the current holder took the gate (0 when free). */
+  heldSince: number;
+  private _waiters;
+  /** True when the current async context holds this gate via {@link runExclusive}. */
+  get heldByCurrentContext(): boolean;
+  /**
+   * Waits until the gate is free, then takes it synchronously (no `await`
+   * between the check and `held = true`). Pair with {@link release}.
+   */
+  acquire(opts?: SqliteTxWaitOptions): Promise<void>;
+  /** Frees the gate and wakes every waiter (in registration order). */
+  release(): void;
+  /**
+   * Runs one synchronous statement once no transaction holds the connection
+   * (immediately when the gate is free). The `held` check and `fn` run in
+   * the same synchronous segment, so they cannot interleave with a `BEGIN`
+   * from another context.
+   */
+  runWhenFree<R>(fn: () => R, opts?: SqliteTxWaitOptions): Promise<R>;
+  /**
+   * Holds the gate for the duration of `fn` WITHOUT opening a transaction
+   * (nested transactions inside `fn` still `BEGIN`/`COMMIT` on the held
+   * connection without re-acquiring). Re-entrant for the same async context.
+   */
+  runExclusive<T>(fn: () => Promise<T>, opts?: SqliteTxWaitOptions): Promise<T>;
+  /** @internal */
+  _enqueue(waiter: GateWaiter): void;
+  /** @internal */
+  _dequeue(waiter: GateWaiter): void;
+}
+/**
+ * Transaction state returned by `SqliteAdapter._beginTransaction`: releases
+ * the gate the transaction holds exactly once (a transaction opened inside an
+ * exclusive hold owns nothing to release). Ownership across adapters is
+ * decided by the core (`_transactionOwner()` = the driver), not here.
+ */
+declare class SqliteTxState {
+  private readonly _gate;
+  private _holdsGate;
+  constructor(_gate: SqliteTxGate, _holdsGate: boolean);
+  release(): void;
+}
+/**
+ * Returns the gate for a driver instance (one gate per driver — every adapter
+ * of a space shares its driver, so they share the gate; two driver wrappers
+ * around one `Database` would get two gates: construct one driver per database).
+ */
+declare function getSqliteTxGate(driver: TSqliteDriver): SqliteTxGate;
+//#endregion
 //#region src/sqlite-adapter.d.ts
 /**
  * SQLite adapter for {@link AtscriptDbTable}.
@@ -83,14 +253,42 @@ declare class SqliteAdapter extends BaseDbAdapter {
   private _vectorThresholds;
   /** Partition filter fields per vector index (from @db.search.filter). Field paths. */
   private _vectorPartitionFields;
-  constructor(driver: TSqliteDriver);
+  /** Per-driver transaction gate (shared by every adapter over this driver). */
+  private readonly _gate;
+  private readonly _txOptions;
+  constructor(driver: TSqliteDriver, options?: SqliteAdapterOptions);
   onFieldScanned(field: string, _type: unknown, metadata: TMetadataMap<AtscriptMetadata>): void;
   formatValue(field: TDbFieldMeta): TValueFormatterPair | undefined;
   isVectorSearchable(): boolean;
   private _detectVectorSupport;
-  protected _beginTransaction(): Promise<unknown>;
-  protected _commitTransaction(): Promise<void>;
-  protected _rollbackTransaction(): Promise<void>;
+  private _waitOpts;
+  /** Every adapter over this driver shares one transaction — and one gate (since 0.1.128). */
+  protected _transactionOwner(): unknown;
+  /** Inside our own transaction, or holding the connection exclusively. */
+  private _ownsConnection;
+  /**
+   * Runs one synchronous driver statement. Inside our own transaction (or an
+   * exclusive hold) it runs immediately; otherwise it waits until no
+   * transaction is open on the connection. The `held` check and the statement
+   * run in the same synchronous segment, so they cannot interleave with a
+   * `BEGIN` from another context.
+   */
+  private _stmt;
+  /**
+   * Holds the connection for the duration of `fn` WITHOUT opening a
+   * transaction: no other context's statement or transaction can interleave.
+   * Meant for the schema entry points that `await` mid-body or toggle
+   * connection-level PRAGMAs (`ensureTable`, `recreateTable`, `dropColumns`,
+   * `dropTablesByName`, `syncIndexes`) — their DDL must not land inside a
+   * request's transaction (PRAGMA changes are no-ops inside one). Inside our
+   * own transaction `fn` runs directly; re-entrant for the same async
+   * context; nested `withTransaction` calls inside `fn` still BEGIN/COMMIT
+   * on the held connection.
+   */
+  protected _withExclusiveConnection<T>(fn: () => Promise<T>): Promise<T>;
+  protected _beginTransaction(): Promise<SqliteTxState>;
+  protected _commitTransaction(state: unknown): Promise<void>;
+  protected _rollbackTransaction(state: unknown): Promise<void>;
   /** SQLite does not use schemas — override to always exclude schema. */
   resolveTableName(): string;
   /** SQLite enforces FK constraints natively via PRAGMA foreign_keys. */
@@ -113,7 +311,11 @@ declare class SqliteAdapter extends BaseDbAdapter {
   replaceMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
   deleteOne(filter: FilterExpr): Promise<TDbDeleteResult>;
   deleteMany(filter: FilterExpr): Promise<TDbDeleteResult>;
-  ensureTable(): Promise<void>;
+  /**
+   * SQLite accepts forward FK references, so a foreign-key cycle is created
+   * inline in any order — `opts.deferForeignKeysTo` is accepted and ignored.
+   */
+  ensureTable(_opts?: TEnsureTableOptions): Promise<void>;
   private _incrementSeeded;
   /**
    * Seeds the sqlite_sequence table for auto-increment fields that have a start value.
@@ -129,6 +331,25 @@ declare class SqliteAdapter extends BaseDbAdapter {
   dropIndexesForColumns(columns: string[]): Promise<void>;
   dropTableByName(tableName: string): Promise<void>;
   dropViewByName(viewName: string): Promise<void>;
+  /**
+   * Drops a group of mutually referencing tables with FK enforcement off for
+   * the duration (`PRAGMA foreign_keys` is a no-op inside a transaction, so
+   * the exclusive connection hold — not a `BEGIN` — keeps another context's
+   * transaction from overlapping it). Safe because schema sync only passes
+   * groups whose referrers are all inside the group.
+   */
+  dropTablesByName(tableNames: string[]): Promise<void>;
+  hasRows(tableName?: string): Promise<boolean>;
+  /**
+   * Live foreign keys referencing `tableName`: `PRAGMA foreign_key_list` is
+   * outbound-only, so the tables in `sqlite_master` are scanned (a loop
+   * rather than the `pragma_foreign_key_list` table-valued function, which
+   * not every bundled SQLite exposes). Only tables whose CREATE text contains
+   * `REFERENCES` can declare a foreign key — the prefilter is a superset, a
+   * false positive just costs one PRAGMA.
+   */
+  getReferencingForeignKeys(tableName: string): Promise<TReferencingForeignKey[]>;
+  getObjectKind(name: string): Promise<TDbObjectKind | undefined>;
   renameTable(oldName: string): Promise<void>;
   typeMapper(field: TDbFieldMeta): string;
   getExistingColumnsForTable(tableName: string): Promise<TExistingColumn[]>;
@@ -214,58 +435,6 @@ declare class SqliteAdapter extends BaseDbAdapter {
   private _dropAllVecTables;
 }
 //#endregion
-//#region src/better-sqlite3-driver.d.ts
-interface TBetterSqlite3DriverOptions extends Record<string, unknown> {
-  /** Load the optional `sqlite-vec` extension. */
-  vector?: boolean;
-  /** Absolute paths to SQLite loadable extensions, passed to `Database.loadExtension`. */
-  loadExtensions?: string[];
-}
-/**
- * {@link TSqliteDriver} implementation backed by `better-sqlite3`.
- *
- * Accepts either a file path (opens a new database) or a pre-created
- * `Database` instance from `better-sqlite3`.
- *
- * ```typescript
- * import { BetterSqlite3Driver } from '@atscript/db-sqlite'
- *
- * // In-memory database
- * const driver = new BetterSqlite3Driver(':memory:')
- *
- * // File-based database
- * const driver = new BetterSqlite3Driver('./my-data.db')
- *
- * // With sqlite-vec extension loaded
- * const driver = new BetterSqlite3Driver('./my-data.db', { vector: true })
- *
- * // Pre-created instance
- * import Database from 'better-sqlite3'
- * const db = new Database(':memory:', { verbose: console.log })
- * const driver = new BetterSqlite3Driver(db)
- * ```
- *
- * Requires `better-sqlite3` to be installed:
- * ```bash
- * pnpm add better-sqlite3
- * ```
- *
- * Vector search support requires the optional `sqlite-vec` package:
- * ```bash
- * pnpm add sqlite-vec
- * ```
- */
-declare class BetterSqlite3Driver implements TSqliteDriver {
-  private db;
-  readonly hasVectorExt: boolean;
-  constructor(pathOrDb: string | import("better-sqlite3").Database, options?: TBetterSqlite3DriverOptions);
-  run(sql: string, params?: unknown[]): TSqliteRunResult;
-  all<T = Record<string, unknown>>(sql: string, params?: unknown[]): T[];
-  get<T = Record<string, unknown>>(sql: string, params?: unknown[]): T | null;
-  exec(sql: string): void;
-  close(): void;
-}
-//#endregion
 //#region src/filter-builder.d.ts
 /**
  * Translates a uniqu filter expression into a parameterized SQL WHERE clause.
@@ -276,6 +445,8 @@ declare class BetterSqlite3Driver implements TSqliteDriver {
 declare function buildWhere(filter: FilterExpr$1): TSqlFragment$1;
 //#endregion
 //#region src/index.d.ts
-declare function createAdapter(connection: string, options?: Record<string, unknown>): DbSpace;
+/** `createAdapter` options: driver options plus the transaction-gate options (since 0.1.128). */
+type TCreateSqliteAdapterOptions = TBetterSqlite3DriverOptions & SqliteAdapterOptions;
+declare function createAdapter(connection: string, options?: TCreateSqliteAdapterOptions): DbSpace;
 //#endregion
-export { BetterSqlite3Driver, SqliteAdapter, type TSqlFragment, type TSqliteDriver, type TSqliteRunResult, buildWhere, createAdapter };
+export { BetterSqlite3Driver, SqliteAdapter, type SqliteAdapterOptions, SqliteTxGate, SqliteTxState, type SqliteTxWaitOptions, type TBetterSqlite3DriverOptions, TCreateSqliteAdapterOptions, type TSqlFragment, type TSqliteDriver, type TSqliteRunResult, buildWhere, createAdapter, getSqliteTxGate };