@atscript/db 0.1.161 → 0.1.163

package/dist/{buckets-B4T_alUe.d.cts → buckets-B8UOod-v.d.cts}

@@ -1,3 +1,4 @@
+import { r as DbError } from "./db-error-B_DRL1E9.cjs";
 import { f as TFieldOps } from "./ops-AqhV7s9o.cjs";
 import { AggregateControls, AggregateExpr, AggregateExpr as AggregateExpr$1, AggregateFn, AggregateFn as AggregateFn$1, AggregateQuery, AggregateQuery as AggregateQuery$1, AggregateResult, BucketUnit, FieldOpsFor, FilterExpr, FilterExpr as FilterExpr$1, NullsPlacement, NullsPlacement as NullsPlacement$1, RelationOp, ResolvedBucket, ResolvedRowOrderKey, ResolvedSelectExpr, TypedWithRelation, Uniquery, Uniquery as Uniquery$1, UniqueryControls, UniqueryControls as UniqueryControls$1, UniqueryInsights, WithRelation, WithRelation as WithRelation$1 } from "@uniqu/core";
 import { AtscriptExprNode, AtscriptExprNode as AtscriptExprNode$1, AtscriptOrderItem, AtscriptQueryComparison, AtscriptQueryFieldRef, AtscriptQueryFieldRef as AtscriptQueryFieldRef$1, AtscriptQueryNode, AtscriptQueryNode as AtscriptQueryNode$1, AtscriptRef, FlatOf, FlatOf as FlatOf$1, NavPropsOf, NavPropsOf as NavPropsOf$1, OwnPropsOf, OwnPropsOf as OwnPropsOf$1, PrimaryKeyOf, PrimaryKeyOf as PrimaryKeyOf$1, TAtscriptAnnotatedType, TAtscriptDataType, TAtscriptTypeObject, TMetadataMap, TSerializedAnnotatedType, TValidatorOptions, TValidatorPlugin, Validator } from "@atscript/typescript/utils";
@@ -761,6 +762,14 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
    * @internal Adapter-facing surface; not part of the consumer API.
    */
   get versionColumnPhysical(): string | undefined;
+  /**
+   * Physical column names of the `@db.onUpdate.inc` fields (since 0.1.162):
+   * adapters add `col = col + 1` to every replace. Empty when there are none.
+   *
+   * @internal Adapter-facing surface; not part of the consumer API.
+   */
+  get onUpdateIncPhysical(): readonly string[];
+  private _onUpdateIncPhysical?;
   /**
    * Logical paths of the `@db.column.version.exempt` fields, including objects
    * whose direct children are all exempt. A patch that writes only these (and
@@ -860,7 +869,7 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
    * `query` with {@link _withPkTieBreak} applied and its `$nulls` resolved
    * ({@link NullsSource.resolveSort}) — a copy when either changes.
    */
-  private _withStableSort;
+  protected _withStableSort(query: Uniquery): Uniquery;
   private _nullsCache?;
   /** NULL-placement resolution for this table (`$nulls`, `@db.sort.nulls`; since 0.1.153). */
   private get _nulls();
@@ -949,18 +958,43 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
    * Creates a new validator with custom options.
    */
   createValidator(opts?: Partial<TValidatorOptions>): Validator<T, DataType>;
+  /**
+   * The row lock a `findOne` / `findMany` asked for (`opts.lock`, since
+   * 0.1.162), validated — `undefined` when none was asked for.
+   *
+   * @throws DbError `INVALID_QUERY` — bad `lock` / `wait` value, a view, a
+   *   grouped / aggregate / `$count` read, or no `withTransaction` scope of
+   *   this table's adapter; `LOCK_NOT_SUPPORTED` — the adapter cannot lock.
+   */
+  private _readLock;
   /**
    * Finds a single record matching the query.
    * The return type automatically excludes nav props unless they are
    * explicitly requested via `$with`.
+   *
+   * `opts.lock` (since 0.1.162) makes it a locking read — see
+   * {@link TReadLockOptions}:
+   *
+   * ```typescript
+   * await adapter.withTransaction(async () => {
+   *   const order = await orders.findOne({ filter: { id }, controls: {} }, { lock: 'update' })
+   *   // … the row stays locked until the transaction ends
+   * })
+   * ```
    */
-  findOne<Q extends Uniquery<OwnProps, NavType>>(query: Q): Promise<DbResponse<DataType, NavType, Q> | null>;
+  findOne<Q extends Uniquery<OwnProps, NavType>>(query: Q, opts?: TReadLockOptions): Promise<DbResponse<DataType, NavType, Q> | null>;
+  /** {@link findOne} of a guarded query with an already validated lock. */
+  private _findOne;
   /**
    * Finds all records matching the query.
    * The return type automatically excludes nav props unless they are
    * explicitly requested via `$with`.
+   *
+   * `opts.lock` (since 0.1.162) makes it a locking read — see
+   * {@link TReadLockOptions}. Sort by the primary key when locking several
+   * rows, so concurrent transactions take the locks in the same order.
    */
-  findMany<Q extends Uniquery<OwnProps, NavType>>(query: Q): Promise<Array<DbResponse<DataType, NavType, Q>>>;
+  findMany<Q extends Uniquery<OwnProps, NavType>>(query: Q, opts?: TReadLockOptions): Promise<Array<DbResponse<DataType, NavType, Q>>>;
   /**
    * `findMany` for the generic `$with` loader. With `partitionBy` (logical
    * fields), `$skip` / `$limit` apply per group of rows sharing those fields'
@@ -1118,11 +1152,14 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
    *
    * // With relations — only requested nav props appear
    * const user = await table.findById('123', { controls: { $with: [{ name: 'posts' }] } })
+   *
+   * // Locking read inside a transaction (since 0.1.162) — see TReadLockOptions
+   * const user = await table.findById('123', { lock: 'update' })
    * ```
    */
   findById<Q extends {
     controls?: UniqueryControls<OwnProps, NavType>;
-  } = Record<string, never>>(id: IdType, query?: Q): Promise<DbResponse<DataType, NavType, Q> | null>;
+  } = Record<string, never>>(id: IdType, query?: Q & TReadLockOptions): Promise<DbResponse<DataType, NavType, Q> | null>;
   /**
    * Reads the ONE row an id addresses — resolved exactly like
    * {@link resolveRowFilter} (primary key first, `opts.scope` /
@@ -1132,11 +1169,18 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
    * must also match `opts.scope` (an out-of-scope row answers `null` like a
    * missing one).
    *
+   * `opts.lock` / `opts.wait` (since 0.1.162) lock the row found — see
+   * {@link TReadLockOptions}. The id is then resolved to its one row first
+   * (an unlocked read, exactly like {@link resolveRowFilter}) and that row is
+   * read with the lock: with `wait: 'skipLocked'` a row another transaction
+   * holds answers `null` — never a lower-precedence identification naming a
+   * different row.
+   *
    * @since 0.1.143
    */
   findOneByRow<Q extends {
     controls?: UniqueryControls<OwnProps, NavType>;
-  } = Record<string, never>>(id: unknown, opts?: TRowResolveOptions & Q): Promise<DbResponse<DataType, NavType, Q> | null>;
+  } = Record<string, never>>(id: unknown, opts?: TRowResolveOptions & TReadLockOptions & Q): Promise<DbResponse<DataType, NavType, Q> | null>;
   /**
    * Resolve an id value (scalar or object) into a {@link FilterExpr} using the
    * same identifications as {@link findById}. Public so callers can
@@ -1424,9 +1468,77 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * calling the guard.
    */
   deleteOne(id: IdType, opts?: TDeleteOptions<DataType>): Promise<TDbDeleteResult>;
-  updateMany(filter: FilterExpr<FlatType>, data: DbPatch<DataType>): Promise<TDbUpdateResult>;
+  /**
+   * Patches every row matching `filter` with `data` (own fields only — no
+   * relations, no `$cas`). Since 0.1.162 the payload is validated in `patch`
+   * mode, exactly like {@link updateOne}: a type mismatch, `null` on a
+   * non-nullable field, `@meta.required` or `@expect.*` failures throw a
+   * `ValidatorError` before any statement runs.
+   *
+   * `opts.limit` (since 0.1.162) bounds the write to the first `limit` matching
+   * rows in `opts.sort` order (default: primary key ascending; the primary key
+   * always breaks ties). Loop until `matchedCount === 0` to process every
+   * match in batches. Not exposed over HTTP.
+   */
+  updateMany(filter: FilterExpr<FlatType>, data: DbPatch<DataType>, opts?: TBulkWriteOptions<FlatType>): Promise<TDbUpdateResult>;
+  /**
+   * Replaces the own fields of every row matching `filter` with `data`. The
+   * payload is validated in `replace` mode (since 0.1.162) — every required
+   * field must be present — except the primary key, which the filter
+   * replaces as a row picker.
+   */
   replaceMany(filter: FilterExpr<FlatType>, data: DbRow<DataType>): Promise<TDbUpdateResult>;
-  deleteMany(filter: FilterExpr<FlatType>): Promise<TDbDeleteResult>;
+  /**
+   * Deletes every row matching `filter` (application-level cascades run first
+   * where the adapter has no native foreign keys).
+   *
+   * `opts.limit` (since 0.1.162) bounds the delete to the first `limit`
+   * matching rows in `opts.sort` order (default: primary key ascending; the
+   * primary key always breaks ties) — for retention sweeps that keep each
+   * statement small. Loop until `deletedCount === 0`, not until it is below
+   * `limit`: a concurrent writer can make one round delete fewer rows while
+   * matches remain. Not exposed over HTTP.
+   */
+  deleteMany(filter: FilterExpr<FlatType>, opts?: TBulkWriteOptions<FlatType>): Promise<TDbDeleteResult>;
+  /**
+   * Runs a bounded write. `native` (default: `supportsWriteLimit()`) hands
+   * `write` the physical filter and the bound; otherwise the primary keys of
+   * the picked rows are read first and `write` gets `filter AND keys` per
+   * key batch (no bound) — a pick that finds nothing writes nothing.
+   *
+   * When the write affected no rows although a row still matches — a
+   * concurrent transaction deleted or changed the picked rows between the
+   * pick and the write — it runs again, at most
+   * {@link BOUNDED_WRITE_RETRIES} more times; an emulated write's next pick
+   * is that check. Rows still matching after the last attempt throw a
+   * retryable `SERIALIZATION_FAILURE`. So `0` means nothing matched (a loop
+   * until `0` cannot stop early); fewer than `limit` stays possible.
+   * A native write whose adapter reports `writeLimitIsAtomic()` is never
+   * re-checked.
+   */
+  private _runBounded;
+  /** Whether any row still matches a bounded write's filter (a one-row key read). */
+  private _boundStillMatches;
+  /**
+   * Application-level cascade, then the delete. `translate` maps `filter` to
+   * the adapter's physical filter (identity for an already-physical one).
+   */
+  private _cascadeDelete;
+  /**
+   * Validates `opts` of a bounded `updateMany` / `deleteMany` and returns the
+   * translated read of the rows it picks (filter, order with the primary-key
+   * tie-breaker, `limit`, primary-key projection), or `undefined` when the
+   * write is unbounded.
+   */
+  private _writeBound;
+  /** `updateMany` / `replaceMany` write the table's own fields only. */
+  private _rejectNavWrite;
+  /**
+   * A logical patch → the adapter's physical `{ update, ops }`: nested
+   * merge-strategy objects decomposed into dot-paths (so nested field ops are
+   * caught), field ops separated, keys translated.
+   */
+  private _translatePatch;
   /**
    * Synchronizes indexes between Atscript definitions and the database.
    */
@@ -1566,7 +1678,11 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * them once the patch is known to write something.
    */
   private _stampOnUpdate;
-  /** Sets the top-level `@db.onUpdate.now` columns of a non-empty patch to `now`. */
+  /**
+   * Sets the top-level `@db.onUpdate.now` columns of a non-empty patch to
+   * `now` and increments its `@db.onUpdate.inc` counters (`$inc: 1`).
+   * `force`: stamp an empty patch too (a touch writes the row).
+   */
   private _stampTopLevel;
   /** {@link _nestedDefaultFillable} per nested default path. */
   private _fillableDefaults?;
@@ -1738,6 +1854,13 @@ interface TViewSource {
   designType: string;
   /** Set for a relational object stored as one column per leaf. */
   flattened?: true;
+  /**
+   * Set when the path is itself a JSON-stored column (relational) — a
+   * `@db.json` field, an array or a structured mixed union — so
+   * {@link column} holds its JSON text, not the typed value.
+   * @since 0.1.162
+   */
+  jsonColumn?: true;
   /**
    * `true` when the value may be absent: the path or an ancestor segment is
    * optional, or it reads inside a JSON-stored value.
@@ -1797,6 +1920,9 @@ interface TViewColumnMapping {
   /**
    * Set when the source is a primitive leaf inside a JSON column
    * ({@link sourceColumn}): the path within it and the leaf's declared type.
+   * Since 0.1.162 also set, with an empty `path` (the JSON root), when the
+   * source is itself a primitive `@db.json` column — the view reads its typed
+   * value, not the JSON text.
    * @since 0.1.136
    */
   json?: {
@@ -2140,8 +2266,87 @@ declare const ALL_BUCKET_UNITS: ReadonlySet<BucketUnit>;
  * @since 0.1.147
  */
 type TViewCapability = "compute" | "firstJoin";
+/**
+ * Every isolation level, weakest first — what an adapter that provides them
+ * all returns from `isolationLevels()`. @since 0.1.162
+ */
+declare const ALL_ISOLATION_LEVELS: ReadonlySet<TDbIsolationLevel>;
 /** Every view capability — what the bundled adapters return from `viewCapabilities()`. @since 0.1.147 */
 declare const ALL_VIEW_CAPABILITIES: ReadonlySet<TViewCapability>;
+/**
+ * What an adapter hands `BaseDbAdapter.syncIndexesWithDiff`: the three
+ * DB-specific primitives plus how to compare and skip.
+ * @since 0.1.162 (inline before)
+ */
+interface TIndexDiffOptions {
+  /**
+   * Existing indexes. When `columns` is provided (ordered column names),
+   * plain/unique indexes whose definition no longer matches the model are
+   * dropped and recreated — a name match alone is not enough (e.g. a
+   * composite index that gained or lost a member keeps its name).
+   */
+  listExisting(): Promise<Array<{
+    name: string;
+    columns?: string[];
+  }>>;
+  createIndex(index: TDbIndex): Promise<void>;
+  dropIndex(name: string): Promise<void>;
+  prefix?: string;
+  /**
+   * Renders one desired key part for the drift comparison, so adapters whose
+   * `listExisting` reports more than a bare column name (e.g. MySQL's
+   * `col(255)` key-length prefix) can render the model side identically.
+   * Default: the column name.
+   * @since 0.1.128
+   */
+  renderDesiredColumn?(index: TDbIndex, field: TDbIndex["fields"][number]): string;
+  /**
+   * An index this diff does not build: a string — the warning to log (e.g. a
+   * geo index without PostGIS); `null` — skipped silently (e.g. an index type
+   * the adapter maintains itself); `undefined` — built. A skipped index is not
+   * desired — never reported as work to do, and a stale one is dropped.
+   * @since 0.1.162
+   */
+  skipIndex?(index: TDbIndex): string | null | undefined;
+  /**
+   * Skips (silently) every index of a type this returns `true` for.
+   * @deprecated since 0.1.162 — use {@link TIndexDiffOptions.skipIndex} (return `null`).
+   */
+  shouldSkipType?(type: TDbIndex["type"]): boolean;
+  /**
+   * Index types the adapter does not support — warned about and skipped.
+   * @deprecated since 0.1.162 — use {@link TIndexDiffOptions.skipIndex} (return the warning).
+   */
+  warnUnsupportedTypes?: {
+    adapter: string;
+    types: ReadonlyArray<TDbIndex["type"]>;
+  };
+  /**
+   * Prefixed indexes the adapter manages itself, outside the model's
+   * `indexes` (e.g. PostgreSQL's pgvector HNSW indexes) — never dropped as
+   * stale here.
+   * @since 0.1.162
+   */
+  isUnmanaged?(name: string): boolean;
+  /**
+   * Compute the changes only — no DDL (`planIndexes`).
+   * @since 0.1.162
+   */
+  dryRun?: boolean;
+}
+/**
+ * What an adapter hands `BaseDbAdapter.syncForeignKeysWithDiff`: its
+ * foreign-key constraint primitives.
+ * @since 0.1.162
+ */
+interface TForeignKeyDiffOptions {
+  /** The live table's foreign-key constraints: constraint name → local column names. */
+  listExisting(): Promise<ReadonlyMap<string, string[]>>;
+  dropConstraint(name: string): Promise<void>;
+  addConstraint(fk: TDbForeignKey): Promise<void>;
+  /** Compute the changes only — no DDL (`planForeignKeys`). */
+  dryRun?: boolean;
+}
 /**
  * Abstract base class for database adapters.
  *
@@ -2228,6 +2433,31 @@ declare abstract class BaseDbAdapter {
    * `expectedVersion`; a violation throws).
    */
   protected _versionColumnFor(opts?: TDbUpdateOptions, expectedVersion?: number): string | undefined;
+  /**
+   * `@db.onUpdate.inc` columns (physical names, since 0.1.162) as a field-op
+   * increment by one, or `undefined` when the table declares none. A replace
+   * path renders it next to the replacement data (the core leaves these
+   * columns out of the payload); the patch paths get the `$inc` from the core.
+   */
+  protected _onUpdateIncOps(): TFieldOps | undefined;
+  /**
+   * Whether `updateMany` / `deleteMany` render a row bound
+   * ({@link TDbWriteLimit}) natively in one statement (since 0.1.162). When
+   * `false` (the default) the core emulates a bounded write: it reads the
+   * primary keys of the first `limit` matching rows in order, then writes the
+   * rows matching the filter AND those keys.
+   */
+  supportsWriteLimit(): boolean;
+  /**
+   * Whether a native bounded write ({@link supportsWriteLimit}) picks and
+   * writes its rows atomically — a row a concurrent transaction deletes or
+   * moves out of the filter is passed over and the next match taken, so `0`
+   * affected rows always means nothing matched (MySQL's
+   * `UPDATE/DELETE … ORDER BY … LIMIT`). When `false` (the default) the core
+   * probes for a remaining match after a bounded write that affected no rows
+   * and retries it a few times (since 0.1.162).
+   */
+  writeLimitIsAtomic(): boolean;
   /**
    * Logs a debug message if verbose mode is enabled.
    * Adapters call this to log DB operations with zero overhead when disabled.
@@ -2242,8 +2472,58 @@ declare abstract class BaseDbAdapter {
    * The generic layer handles nesting detection via `AsyncLocalStorage`.
    * Adapters override `_beginTransaction`, `_commitTransaction`, and
    * `_rollbackTransaction` to provide raw DB-specific transaction primitives.
+   *
+   * `opts.isolation` (since 0.1.162) sets the isolation level of the
+   * transaction this call opens — "at least this level". An adapter whose
+   * {@link isolationLevels} lacks it throws `ISOLATION_NOT_SUPPORTED`. A
+   * nested call joins the open transaction; it may request a level only when
+   * that transaction was opened with the same or a stricter one, else it
+   * throws `INVALID_QUERY` (the level of a running transaction cannot change).
+   */
+  withTransaction<T>(fn: () => Promise<T>, opts?: TTransactionOptions): Promise<T>;
+  /**
+   * The isolation levels {@link withTransaction} can open a transaction at
+   * (since 0.1.162). Default: none — a requested level throws
+   * `ISOLATION_NOT_SUPPORTED`. Override and apply the level in
+   * {@link _beginTransaction} (`opts.isolation`).
    */
-  withTransaction<T>(fn: () => Promise<T>): Promise<T>;
+  isolationLevels(): ReadonlySet<TDbIsolationLevel>;
+  /**
+   * The level every transaction of this adapter runs at regardless of the
+   * request (since 0.1.162) — SQLite's `BEGIN IMMEDIATE` is always
+   * serializable. A nested `withTransaction` asking for any level then joins
+   * without error. Default `undefined` (the engine default / what was asked).
+   */
+  protected _inherentIsolation(): TDbIsolationLevel | undefined;
+  /**
+   * Validates a `withTransaction` isolation request against
+   * {@link isolationLevels} — the requested level, or `undefined`.
+   * @throws DbError `INVALID_QUERY` (unknown level) / `ISOLATION_NOT_SUPPORTED`.
+   */
+  protected _checkIsolation(opts: TTransactionOptions | undefined): TDbIsolationLevel | undefined;
+  /** The `ISOLATION_NOT_SUPPORTED` error of a `withTransaction` isolation request. */
+  protected _isolationNotSupported(message: string): DbError;
+  /**
+   * A nested `withTransaction` asked for `requested` while a transaction
+   * opened at `open` runs: fine when `open` is at least as strict.
+   * @throws DbError `INVALID_QUERY` otherwise.
+   */
+  protected _assertJoinIsolation(open: TDbIsolationLevel | undefined, requested: TDbIsolationLevel): void;
+  /**
+   * Whether the readable layer may pass a row lock on `DbQuery.lock` to
+   * `findOne` / `findMany` (since 0.1.162). Default `false` — a locking read
+   * throws `LOCK_NOT_SUPPORTED`. An adapter whose transaction already
+   * serialises writers may return `true` and ignore the lock.
+   */
+  supportsReadLocks(): boolean;
+  /**
+   * `true` inside a `withTransaction` scope of this adapter's owner — a real
+   * transaction or a pass-through one (adapters without transaction
+   * primitives, such as the in-memory one). Unlike {@link isInTransaction} a
+   * pass-through scope counts. Used to require a scope for locking reads.
+   * @since 0.1.162
+   */
+  inTransactionScope(): boolean;
   /**
    * The object a transaction state is branded with (since 0.1.128). Every
    * adapter instance that returns the same owner shares one transaction —
@@ -2277,9 +2557,10 @@ declare abstract class BaseDbAdapter {
   protected _runInTransactionContext<T>(state: unknown, fn: () => Promise<T>): Promise<T>;
   /**
    * Starts a raw transaction. Returns opaque state stored in the async context.
-   * Override in adapters that support transactions.
+   * Override in adapters that support transactions. `opts.isolation` (since
+   * 0.1.162) is set only to a level of {@link isolationLevels}.
    */
-  protected _beginTransaction(): Promise<unknown>;
+  protected _beginTransaction(_opts?: TTransactionOptions): Promise<unknown>;
   /** Commits the raw transaction. Override in adapters that support transactions. */
   protected _commitTransaction(_state: unknown): Promise<void>;
   /** Rolls back the raw transaction. Override in adapters that support transactions. */
@@ -2334,6 +2615,16 @@ declare abstract class BaseDbAdapter {
    * to generate the value client-side or leave it for the DB.
    */
   nativeDefaultFns(): ReadonlySet<TDbDefaultFn>;
+  /**
+   * How this engine's introspection (`getExistingColumns`) reports the
+   * model default `desired` (`serializeDefaultValue` form) of `field` when
+   * it cannot report it exactly — e.g. MySQL reports a 4-byte character of a
+   * literal default as `?` while the column stores it intact. Schema sync
+   * treats a live default equal to this as unchanged. Optional — omit when
+   * introspection reports defaults faithfully.
+   * @since 0.1.162
+   */
+  reportedDefault?(desired: string, field: TDbFieldMeta): string;
   /**
    * Calendar-bucket units (`{ $bucket, $field }` in an aggregate `$select`)
    * this adapter can group by, over IANA time zones. Empty (the default) =
@@ -2584,48 +2875,27 @@ declare abstract class BaseDbAdapter {
    *
    * @example
    * ```typescript
-   * async syncIndexes() {
-   *   await this.syncIndexesWithDiff({
+   * protected override _syncIndexes(dryRun: boolean) {
+   *   return this.syncIndexesWithDiff({
+   *     dryRun,
    *     listExisting: async () => this.driver.all('PRAGMA index_list(...)'),
    *     createIndex: async (index) => this.driver.exec('CREATE INDEX ...'),
    *     dropIndex: async (name) => this.driver.exec('DROP INDEX ...'),
-   *     shouldSkipType: (type) => type === 'fulltext',
+   *     skipIndex: (index) => (index.type === 'fulltext' ? null : undefined),
    *   })
    * }
    * ```
    */
-  protected syncIndexesWithDiff(opts: {
-    /**
-     * Existing indexes. When `columns` is provided (ordered column names),
-     * plain/unique indexes whose definition no longer matches the model are
-     * dropped and recreated — a name match alone is not enough (e.g. a
-     * composite index that gained or lost a member keeps its name).
-     */
-    listExisting(): Promise<Array<{
-      name: string;
-      columns?: string[];
-    }>>;
-    createIndex(index: TDbIndex): Promise<void>;
-    dropIndex(name: string): Promise<void>;
-    prefix?: string;
-    shouldSkipType?(type: TDbIndex["type"]): boolean;
-    /**
-     * Renders one desired key part for the drift comparison, so adapters whose
-     * `listExisting` reports more than a bare column name (e.g. MySQL's
-     * `col(255)` key-length prefix) can render the model side identically.
-     * Default: the column name.
-     * @since 0.1.128
-     */
-    renderDesiredColumn?(index: TDbIndex, field: TDbIndex["fields"][number]): string;
-    /**
-     * Index types declared on the model but not supported by this adapter —
-     * warns and skips (models stay portable; sync never errors on these).
-     */
-    warnUnsupportedTypes?: {
-      adapter: string;
-      types: ReadonlyArray<TDbIndex["type"]>;
-    };
-  }): Promise<void>;
+  protected syncIndexesWithDiff(opts: TIndexDiffOptions): Promise<TIndexChange[]>;
+  /**
+   * Template method for foreign-key constraint synchronization: drops the
+   * live constraints the model does not declare and adds the declared ones
+   * the live table lacks — matched by their sorted local columns
+   * ({@link fkKey}). A failing statement throws. Returns the changes (made,
+   * or with `dryRun` only computed).
+   * @since 0.1.162
+   */
+  protected syncForeignKeysWithDiff(opts: TForeignKeyDiffOptions): Promise<TForeignKeyChange[]>;
   /**
    * Returns available search indexes for this adapter.
    * UI uses this to show index picker. Override in adapters that support search.
@@ -2800,15 +3070,33 @@ declare abstract class BaseDbAdapter {
   /** `opts.keepVersion` — skip the version bump; see {@link TDbUpdateOptions}. */
   abstract updateMany(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, opts?: TDbUpdateOptions): Promise<TDbUpdateResult>;
   abstract replaceMany(filter: FilterExpr, data: Record<string, unknown>): Promise<TDbUpdateResult>;
-  abstract deleteMany(filter: FilterExpr): Promise<TDbDeleteResult>;
+  /** `opts.limit` — bounded delete, sent only when {@link supportsWriteLimit} (since 0.1.162). */
+  abstract deleteMany(filter: FilterExpr, opts?: TDbDeleteManyOptions): Promise<TDbDeleteResult>;
   /**
    * Synchronizes indexes between the Atscript definitions and the database.
-   * Uses `this._table.indexes` for the full index definitions. Schema sync
+   * Uses `this._table.indexes` for the full index definitions. Returns the
+   * changes it made (since 0.1.162) — schema sync reports them on the run
+   * entry; `void` reports none. Schema sync
    * passes `opts` when safe mode skipped work the indexes depend on (see
    * {@link TSyncIndexesOptions}); an adapter whose indexes do not depend on it
-   * ignores them.
+   * ignores them. Default: {@link _syncIndexes} without `dryRun`.
+   */
+  syncIndexes(opts?: TSyncIndexesOptions): Promise<void | TIndexChange[]>;
+  /**
+   * The index changes {@link syncIndexes} would make now — no DDL. Schema
+   * sync's plan reports them (`entry.indexChanges`) and marks the entry
+   * `alter`; a run reports what `syncIndexes` returns.
+   * @since 0.1.162
    */
-  abstract syncIndexes(opts?: TSyncIndexesOptions): Promise<void>;
+  planIndexes(opts?: TSyncIndexesOptions): Promise<TIndexChange[]>;
+  /**
+   * The one index pass behind {@link syncIndexes} (`dryRun: false`) and
+   * {@link planIndexes} (`dryRun: true` — compute the changes, no DDL).
+   * Adapters implement this (usually over {@link syncIndexesWithDiff}). An
+   * adapter that overrides `syncIndexes` instead plans no index work.
+   * @since 0.1.162
+   */
+  protected _syncIndexes(dryRun: boolean, _opts?: TSyncIndexesOptions): Promise<TIndexChange[]>;
   /**
    * Ensures the table exists in the database, creating it if needed.
    * Uses `this._table.tableName`, `this._table.schema`, etc.
@@ -2820,11 +3108,6 @@ declare abstract class BaseDbAdapter {
    *   order. Adapters without inline constraints ignore the parameter.
    */
   abstract ensureTable(opts?: TEnsureTableOptions): Promise<void>;
-  /**
-   * Synchronizes foreign key constraints between Atscript definitions and the database.
-   * Uses `this._table.foreignKeys` for the full FK definitions.
-   * Optional — only relational adapters need to implement this.
-   */
   /**
    * Post-sync hook called after all table operations (columns, indexes, FKs)
    * are complete. Adapters can use this for finalization work such as
@@ -2832,7 +3115,22 @@ declare abstract class BaseDbAdapter {
    * Optional — most adapters don't need this.
    */
   afterSyncTable?(): Promise<void>;
-  syncForeignKeys?(): Promise<void>;
+  /**
+   * Synchronizes foreign key constraints between Atscript definitions and
+   * the live table — adds the missing ones, drops the ones the model does
+   * not declare (matched by their local columns). Returns what it changed
+   * (since 0.1.162); schema sync reports it on the run entry. Optional —
+   * only relational adapters implement it (usually over
+   * {@link syncForeignKeysWithDiff}); without it, schema sync recreates the
+   * table to change its foreign keys (when the adapter can).
+   */
+  syncForeignKeys?(): Promise<void | TForeignKeyChange[]>;
+  /**
+   * The changes {@link syncForeignKeys} would make now — no DDL. Schema
+   * sync's plan reports them with the snapshot-based FK diff.
+   * @since 0.1.162
+   */
+  planForeignKeys?(): Promise<TForeignKeyChange[]>;
   /**
    * Drops FK constraints identified by their canonical local column key.
    * Called by the sync executor before column operations to remove stale FKs
@@ -3140,6 +3438,12 @@ declare class TableMetadata {
    * @since 0.1.156
    */
   onUpdateNow: Set<string>;
+  /**
+   * Top-level fields annotated with `@db.onUpdate.inc`: `0` on insert, `+1` in
+   * the same statement on every update and replace.
+   * @since 0.1.162
+   */
+  onUpdateInc: Set<string>;
   /** Logical path → `@db.column` override (top-level keys only on document storage). */
   columnMap: Map<string, string>;
   dimensions: string[];
@@ -3429,6 +3733,67 @@ interface DbQuery {
   controls: DbControls;
   /** Pre-computed query insights (field → operators). Adapters may use this to apply query-time behaviour (e.g. collation). */
   insights?: UniqueryInsights;
+  /**
+   * Row lock the read takes (`findOne` / `findMany` with `{ lock }`; since
+   * 0.1.162). Only ever set on a table read inside a transaction of the
+   * adapter's owner, and only when `supportsReadLocks()` is true. SQL
+   * adapters render `FOR UPDATE` / `FOR SHARE` [`NOWAIT` / `SKIP LOCKED`];
+   * an adapter whose transaction already serialises writers may ignore it.
+   */
+  lock?: TDbReadLock;
+}
+/** Lock strength of a locking read: exclusive (`update`) or shared (`share`). */
+type TDbLockMode = "update" | "share";
+/**
+ * What a locking read does when a row is locked by another transaction:
+ * `block` (default) waits for it; `nowait` fails at once with a retryable
+ * `DbError("LOCK_TIMEOUT")`; `skipLocked` leaves the locked rows out of the
+ * result.
+ */
+type TDbLockWait = "block" | "nowait" | "skipLocked";
+/** The resolved row lock handed to the adapter on {@link DbQuery.lock}. */
+interface TDbReadLock {
+  mode: TDbLockMode;
+  wait: TDbLockWait;
+}
+/**
+ * Second argument of `findOne` / `findMany` (and part of the `findById` /
+ * `findOneByRow` options): a locking read. Server-side only — it is never a
+ * query control, so it cannot arrive over HTTP.
+ *
+ * A lock requires a `withTransaction` scope of the table's adapter and a
+ * table (not a view); `$groupBy` / aggregate `$select` / `$count` reads are
+ * rejected. Only the root rows are locked — `$with` relations load with
+ * plain reads. The locks are held until the outermost transaction commits
+ * or rolls back.
+ *
+ * @since 0.1.162
+ */
+interface TReadLockOptions {
+  /** `'update'` — exclusive row lock (`FOR UPDATE`); `'share'` — shared lock (`FOR SHARE`). */
+  lock?: TDbLockMode;
+  /** Behaviour on a row locked by another transaction (default `'block'`); requires `lock`. */
+  wait?: TDbLockWait;
+}
+/**
+ * Transaction isolation level. Semantics are "at least this level": an
+ * engine that always runs stricter (SQLite) satisfies every level.
+ * @since 0.1.162
+ */
+type TDbIsolationLevel = "read committed" | "repeatable read" | "serializable";
+/**
+ * Options of `withTransaction(fn, opts)` (since 0.1.162). Apply to the
+ * outermost call only — a nested call joins the open transaction and may
+ * request an isolation level only when the open transaction was started with
+ * the same or a stricter one (otherwise `INVALID_QUERY`).
+ */
+interface TTransactionOptions {
+  /**
+   * Isolation level of the transaction. An adapter that cannot provide it
+   * throws `DbError("ISOLATION_NOT_SUPPORTED")`. Omitted: the engine default
+   * (PostgreSQL READ COMMITTED, MySQL REPEATABLE READ).
+   */
+  isolation?: TDbIsolationLevel;
 }
 /** Describes an available search index exposed by a database adapter. */
 interface TSearchIndexInfo {
@@ -3846,6 +4211,48 @@ interface TDbUpdateOptions {
    * the option keeps bumping (the pre-0.1.150 behaviour).
    */
   keepVersion?: boolean;
+  /**
+   * Bounded update (`updateMany(filter, data, { limit })`, since 0.1.162):
+   * write at most `limit.limit` rows, the first ones in `limit.sort` order.
+   * Sent only to an adapter whose {@link BaseDbAdapter.supportsWriteLimit}
+   * is `true`; the core emulates it for the others.
+   */
+  limit?: TDbWriteLimit;
+}
+/**
+ * The row bound of a bounded `updateMany` / `deleteMany` as the adapter
+ * receives it (since 0.1.162): physical column names, the primary key always
+ * included in `sort` as the final tie-breaker so the order is total.
+ */
+interface TDbWriteLimit {
+  /** Positive integer — the most rows the statement may touch. */
+  limit: number;
+  /** Physical column → direction. Never empty. */
+  sort: Record<string, 1 | -1>;
+  /** Resolved NULL placement per `sort` key (see `DbControls.$nulls`). */
+  nulls?: DbControls["$nulls"];
+}
+/** Per-call options of an adapter `deleteMany` (since 0.1.162). */
+interface TDbDeleteManyOptions {
+  /** Bounded delete — see {@link TDbWriteLimit}. Sent only when `supportsWriteLimit()`. */
+  limit?: TDbWriteLimit;
+}
+/**
+ * Options of `AtscriptDbTable.updateMany` / `deleteMany` (since 0.1.162).
+ * Not exposed over HTTP.
+ */
+interface TBulkWriteOptions<FlatType = Record<string, unknown>> {
+  /**
+   * Touch at most this many matching rows (a positive integer). Loop until a
+   * call reports `0` to process every match in batches.
+   */
+  limit?: number;
+  /**
+   * The order in which a bounded write picks rows (`$sort` shape). Defaults
+   * to the primary key ascending; the primary key is always appended as the
+   * final tie-breaker. Needs `limit`.
+   */
+  sort?: Partial<Record<keyof FlatType & string, 1 | -1>>;
 }
 interface TDbDeleteResult {
   deletedCount: number;
@@ -4225,6 +4632,30 @@ interface TSyncIndexesOptions {
    */
   keepColumns?: readonly string[];
 }
+/**
+ * One managed index `syncIndexes` creates (`add`), drops (`drop`) or drops
+ * and recreates because its definition drifted (`rebuild`) — returned by
+ * `BaseDbAdapter.syncIndexes` / `planIndexes` and reported on schema-sync
+ * entries (`entry.indexChanges`). `name` is the physical index name (or the
+ * adapter's artifact for it, e.g. SQLite's FTS5 table).
+ * @since 0.1.162
+ */
+interface TIndexChange {
+  name: string;
+  action: "add" | "drop" | "rebuild";
+}
+/**
+ * One foreign key `syncForeignKeys` adds to the live table (missing there,
+ * e.g. dropped by hand) or drops from it (not in the model) — matched by
+ * the sorted local columns. `targetTable` is set for an added constraint;
+ * a dropped one may leave it out.
+ * @since 0.1.162
+ */
+interface TForeignKeyChange {
+  fields: string[];
+  targetTable?: string;
+  action: "add" | "drop";
+}
 /** Result of applying column diff to the database. */
 interface TSyncColumnResult {
   added: string[];
@@ -4725,4 +5156,4 @@ declare function isJsonValueField(fd: TDbFieldMeta): boolean;
  */
 declare function jsonValueAncestor(path: string, jsonValueParents: ReadonlySet<string>): string | undefined;
 //#endregion
-export { TDbInsertResult as $, ALL_VIEW_CAPABILITIES as $t, TColumnDiff as A, REL_FILTER_MAX_NODES as An, TPrimaryKeyChange as At, TDbDefaultFn as B, isResolvedRelationFilter as Bn, TValueFormatterPair as Bt, NavPropsOf$1 as C, IntegrityStrategy as Cn, TIdDescriptor as Ct, PrimaryKeyOf$1 as D, DbResponse as Dn, TJsonCopyTarget as Dt, OwnPropsOf$1 as E, AtscriptDbReadable as En, TInsertOptions as Et, TDbActionLevel as F, TRelationStaticFilter as Fn, TSyncColumnResult as Ft, TDbIndex as G, FieldMappingStrategy as Gn, Uniquery$1 as Gt, TDbDeleteResult as H, DbEncryption as Hn, TWriteOptions as Ht, TDbActionProcessor as I, andFilters as In, TSyncIndexesOptions as It, TDbInsertIgnoreOptions as J, TGenericLogger as Jn, TableMetadata as Jt, TDbIndexField as K, TReadControls as Kn, UniqueryControls$1 as Kt, TDbActionTargetSummary as L, containsRelationFilter as Ln, TTableOptionDiff as Lt, TCrudPermissions as M, TRelGuardState as Mn, TRelationInfo as Mt, TDbActionInfo as N, TRelationFilterJunction as Nn, TRowResolveOptions as Nt, TCascadeResolver as O, resolveDesignType as On, TMetaResponse as Ot, TDbActionIntent as P, TRelationFilterTable as Pn, TSearchIndexInfo as Pt, TDbInsertManyResult as Q, UniquSelect as Qn, ALL_BUCKET_UNITS as Qt, TDbAvailableActions as R, forEachResolvedRelation as Rn, TTableResolver as Rt, FlatOf$1 as S, AtscriptDbTable as Sn, TFkLookupTarget as St, NullsPlacement$1 as T, TCascadePin as Tn, TIdentification as Tt, TDbFieldMeta as U, TDbEncryptionOptions as Un, TWriteTableResolver as Ut, TDbDefaultValue as V, relationStaticFilter as Vn, TViewJsonType as Vt, TDbForeignKey as W, DocumentFieldMapper as Wn, TypedWithRelation as Wt, TDbInsertIgnoreSlot as X, TFirstLast as Xn, isGeoPointType as Xt, TDbInsertIgnoreResult as Y, TExprAggregate as Yn, isGeoIndexableType as Yt, TDbInsertManyIgnoreResult as Z, TRowOrderKey as Zn, TPathPresence as Zt, DbPatch as _, TViewJoin as _n, TExistingColumn as _t, isJsonValueField as a, AtscriptDbView as an, TDbStorageType as at, FieldOpsFor as b, isFieldRef as bn, TFieldMeta as bt, resolveCalendarBuckets as c, isViewType as cn, TDbWriteAction as ct, AggregateFn$1 as d, AtscriptExprNode$1 as dn, TDbWriteGuard as dt, BaseDbAdapter as en, TDbObjectKind as et, AggregateQuery$1 as f, AtscriptOrderItem as fn, TDbWriteGuardContext as ft, DbControls as g, AtscriptRef as gn, TEnsureTableOptions as gt, AtscriptDbWritable as h, AtscriptQueryNode$1 as hn, TDerivedColumn as ht, isBucketableField as i, TDbSpaceOptions as in, TDbRemoveGuardContext as it, TCrudOp as j, ResolvedRelationFilter as jn, TReferencingForeignKey as jt, TCascadeTarget as k, REL_FILTER_MAX_DEPTH as kn, TMetadataOverrides as kt, AggregateControls as l, TViewReadPlan as ln, TDbWriteCheck as lt, AtscriptDbTableLike as m, AtscriptQueryFieldRef$1 as mn, TDerivedChangeReason as mt, TComputedSelect as n, DbSpace as nn, TDbRelation as nt, jsonValueAncestor as o, TViewColumnMapping as on, TDbUpdateOptions as ot, AggregateResult as p, AtscriptQueryComparison as pn, TDeleteOptions as pt, TDbIndexType as q, NoopLogger as qn, WithRelation$1 as qt, TResolvedBucket as r, TAdapterFactory as rn, TDbRemoveGuard as rt, normalizeComputedSelect as s, isAtscriptDbView as sn, TDbUpdateResult as st, TBucketFieldSource as t, TViewCapability as tn, TDbReferentialAction as tt, AggregateExpr$1 as u, aliasTargetOf as un, TDbWriteCheckContext as ut, DbQuery as v, TViewPlan as vn, TExistingForeignKey as vt, NullableOptional as w, NativeIntegrity as wn, TIdResolveOptions as wt, FilterExpr$1 as x, translateQueryTree as xn, TFkLookupResolver as xt, DbRow as y, evaluateExpr as yn, TExistingTableOption as yt, TDbCollation as z, hasRelationOp as zn, TTouchManyOptions as zt };
+export { TDbInsertManyIgnoreResult as $, hasRelationOp as $n, TWriteOptions as $t, TCascadeTarget as A, AtscriptRef as An, TForeignKeyChange as At, TDbCollation as B, AtscriptDbReadable as Bn, TReadLockOptions as Bt, NavPropsOf$1 as C, TViewReadPlan as Cn, TEnsureTableOptions as Ct, PrimaryKeyOf$1 as D, AtscriptQueryComparison as Dn, TFieldMeta as Dt, OwnPropsOf$1 as E, AtscriptOrderItem as En, TExistingTableOption as Et, TDbActionIntent as F, translateQueryTree as Fn, TInsertOptions as Ft, TDbFieldMeta as G, ResolvedRelationFilter as Gn, TSyncColumnResult as Gt, TDbDefaultValue as H, resolveDesignType as Hn, TRelationInfo as Ht, TDbActionLevel as I, AtscriptDbTable as In, TJsonCopyTarget as It, TDbIndexField as J, TRelationFilterTable as Jn, TTableResolver as Jt, TDbForeignKey as K, TRelGuardState as Kn, TSyncIndexesOptions as Kt, TDbActionProcessor as L, IntegrityStrategy as Ln, TMetaResponse as Lt, TCrudOp as M, TViewPlan as Mn, TIdResolveOptions as Mt, TCrudPermissions as N, evaluateExpr as Nn, TIdentification as Nt, TBulkWriteOptions as O, AtscriptQueryFieldRef$1 as On, TFkLookupResolver as Ot, TDbActionInfo as P, isFieldRef as Pn, TIndexChange as Pt, TDbInsertIgnoreSlot as Q, forEachResolvedRelation as Qn, TViewJsonType as Qt, TDbActionTargetSummary as R, NativeIntegrity as Rn, TMetadataOverrides as Rt, FlatOf$1 as S, isViewType as Sn, TDerivedColumn as St, NullsPlacement$1 as T, AtscriptExprNode$1 as Tn, TExistingForeignKey as Tt, TDbDeleteManyOptions as U, REL_FILTER_MAX_DEPTH as Un, TRowResolveOptions as Ut, TDbDefaultFn as V, DbResponse as Vn, TReferencingForeignKey as Vt, TDbDeleteResult as W, REL_FILTER_MAX_NODES as Wn, TSearchIndexInfo as Wt, TDbInsertIgnoreOptions as X, andFilters as Xn, TTransactionOptions as Xt, TDbIndexType as Y, TRelationStaticFilter as Yn, TTouchManyOptions as Yt, TDbInsertIgnoreResult as Z, containsRelationFilter as Zn, TValueFormatterPair as Zt, DbPatch as _, TAdapterFactory as _n, TDbWriteGuard as _t, isJsonValueField as a, TableMetadata as an, FieldMappingStrategy as ar, TDbObjectKind as at, FieldOpsFor as b, TViewColumnMapping as bn, TDeleteOptions as bt, resolveCalendarBuckets as c, TPathPresence as cn, TGenericLogger as cr, TDbRelation as ct, AggregateFn$1 as d, ALL_VIEW_CAPABILITIES as dn, TRowOrderKey as dr, TDbStorageType as dt, TWriteTableResolver as en, isResolvedRelationFilter as er, TDbInsertManyResult as et, AggregateQuery$1 as f, BaseDbAdapter as fn, UniquSelect as fr, TDbUpdateOptions as ft, DbControls as g, DbSpace as gn, TDbWriteCheckContext as gt, AtscriptDbWritable as h, TViewCapability as hn, TDbWriteCheck as ht, isBucketableField as i, WithRelation$1 as in, DocumentFieldMapper as ir, TDbLockWait as it, TColumnDiff as j, TViewJoin as jn, TIdDescriptor as jt, TCascadeResolver as k, AtscriptQueryNode$1 as kn, TFkLookupTarget as kt, AggregateControls as l, ALL_BUCKET_UNITS as ln, TExprAggregate as lr, TDbRemoveGuard as lt, AtscriptDbTableLike as m, TIndexDiffOptions as mn, TDbWriteAction as mt, TComputedSelect as n, Uniquery$1 as nn, DbEncryption as nr, TDbIsolationLevel as nt, jsonValueAncestor as o, isGeoIndexableType as on, TReadControls as or, TDbReadLock as ot, AggregateResult as p, TForeignKeyDiffOptions as pn, TDbUpdateResult as pt, TDbIndex as q, TRelationFilterJunction as qn, TTableOptionDiff as qt, TResolvedBucket as r, UniqueryControls$1 as rn, TDbEncryptionOptions as rr, TDbLockMode as rt, normalizeComputedSelect as s, isGeoPointType as sn, NoopLogger as sr, TDbReferentialAction as st, TBucketFieldSource as t, TypedWithRelation as tn, relationStaticFilter as tr, TDbInsertResult as tt, AggregateExpr$1 as u, ALL_ISOLATION_LEVELS as un, TFirstLast as ur, TDbRemoveGuardContext as ut, DbQuery as v, TDbSpaceOptions as vn, TDbWriteGuardContext as vt, NullableOptional as w, aliasTargetOf as wn, TExistingColumn as wt, FilterExpr$1 as x, isAtscriptDbView as xn, TDerivedChangeReason as xt, DbRow as y, AtscriptDbView as yn, TDbWriteLimit as yt, TDbAvailableActions as z, TCascadePin as zn, TPrimaryKeyChange as zt };