@atscript/db 0.1.127 → 0.1.129

package/dist/{db-error-DXwEzmYJ.cjs → db-error-C4JuLcvb.cjs}

@@ -50,6 +50,27 @@ var CasExhaustedError = class extends DbError {
 		this.lastSeenVersion = lastSeenVersion;
 	}
 };
+/**
+* Thrown by `AtscriptDbTable.touchMany` (`require: 'all'`, the default) when
+* fewer rows than keys matched their expected version — at least one row is
+* stale or missing. Nothing was written (the pre-count refused before the
+* first statement, or the SQL transaction rolled every bump back). Surfaced
+* as HTTP 409 by moost-db.
+*/
+var CasMismatchError = class extends DbError {
+	matched;
+	expected;
+	name = "CasMismatchError";
+	constructor(matched, expected) {
+		const message = `touchMany: ${matched} of ${expected} rows matched — stale or missing rows`;
+		super("CAS_MISMATCH", [{
+			path: "$cas",
+			message
+		}], message);
+		this.matched = matched;
+		this.expected = expected;
+	}
+};
 //#endregion
 Object.defineProperty(exports, "CasExhaustedError", {
 	enumerable: true,
@@ -57,6 +78,12 @@ Object.defineProperty(exports, "CasExhaustedError", {
 		return CasExhaustedError;
 	}
 });
+Object.defineProperty(exports, "CasMismatchError", {
+	enumerable: true,
+	get: function() {
+		return CasMismatchError;
+	}
+});
 Object.defineProperty(exports, "DbError", {
 	enumerable: true,
 	get: function() {

package/dist/{db-error-BHPXOKzc.mjs → db-error-COrO58t5.mjs}

@@ -50,5 +50,26 @@ var CasExhaustedError = class extends DbError {
 		this.lastSeenVersion = lastSeenVersion;
 	}
 };
+/**
+* Thrown by `AtscriptDbTable.touchMany` (`require: 'all'`, the default) when
+* fewer rows than keys matched their expected version — at least one row is
+* stale or missing. Nothing was written (the pre-count refused before the
+* first statement, or the SQL transaction rolled every bump back). Surfaced
+* as HTTP 409 by moost-db.
+*/
+var CasMismatchError = class extends DbError {
+	matched;
+	expected;
+	name = "CasMismatchError";
+	constructor(matched, expected) {
+		const message = `touchMany: ${matched} of ${expected} rows matched — stale or missing rows`;
+		super("CAS_MISMATCH", [{
+			path: "$cas",
+			message
+		}], message);
+		this.matched = matched;
+		this.expected = expected;
+	}
+};
 //#endregion
-export { DbError as n, DepthLimitExceededError as r, CasExhaustedError as t };
+export { DepthLimitExceededError as i, CasMismatchError as n, DbError as r, CasExhaustedError as t };

package/dist/{db-readable-BkAGccv9.d.mts → db-readable-B7eYWS5q.d.cts}

@@ -1,6 +1,6 @@
-import { f as TFieldOps } from "./ops-DJRnNTVo.mjs";
-import { 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";
+import { f as TFieldOps } from "./ops-AqhV7s9o.cjs";
 import { AggregateControls, AggregateExpr, AggregateExpr as AggregateExpr$1, AggregateFn, AggregateQuery, AggregateQuery as AggregateQuery$1, AggregateResult, FieldOpsFor, FilterExpr, FilterExpr as FilterExpr$1, TypedWithRelation, Uniquery, Uniquery as Uniquery$1, UniqueryControls, UniqueryControls as UniqueryControls$1, UniqueryInsights, WithRelation, WithRelation as WithRelation$1 } from "@uniqu/core";
+import { 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";
 
 //#region src/query/uniqu-select.d.ts
 /**
@@ -55,6 +55,12 @@ interface TGenericLogger {
 declare const NoopLogger: TGenericLogger;
 //#endregion
 //#region src/table/table-metadata.d.ts
+/**
+ * Finds the nearest ancestor of `path` that belongs to `set`.
+ * Used by both the build pipeline (in `_classifyFields`) and
+ * runtime reconstruction on the Readable.
+ */
+declare function findAncestorInSet(path: string, set: ReadonlySet<string>): string | undefined;
 /** Returns true if the annotated type IS the `db.geoPoint` primitive (tag-based). */
 declare function isGeoPointType(fieldType: TAtscriptAnnotatedType): boolean;
 /**
@@ -118,6 +124,22 @@ declare class TableMetadata {
   leafByPhysical: Map<string, TDbFieldMeta>;
   /** Leaf field descriptors indexed by logical path (write/patch/filter paths). */
   leafByLogical: Map<string, TDbFieldMeta>;
+  /**
+   * Non-ignored field descriptors keyed by logical path, excluding navigation
+   * relations and their descendants. Unlike `leafByLogical` (relational
+   * adapters only) this is built for every adapter, so the core path guard
+   * (`guardPaths`) can answer "does this path have physical storage here?"
+   * on nested-object adapters too.
+   */
+  descriptorByPath: Map<string, TDbFieldMeta>;
+  /**
+   * Logical paths stored as a single JSON column (`storage === 'json'`,
+   * non-ignored descriptors). Retained after build — unlike the build-time
+   * `jsonFields` set — so the path guard can classify JSON descendants on
+   * relational adapters. Empty on nested-object adapters (they keep native
+   * dotted paths as descriptors).
+   */
+  jsonParents: ReadonlySet<string>;
   private _built;
   private _identifications?;
   private _collateMap;
@@ -166,6 +188,14 @@ declare class TableMetadata {
   private _classifyFields;
   /** Returns the `__`-separated parent prefix for a dot-separated path, or empty string for top-level paths. */
   private _flattenedPrefix;
+  /** Nearest `@db.encrypted` ancestor of `path` (exclusive), or `undefined`. */
+  /**
+   * Indexes non-ignored descriptors by logical path and retains the JSON-parent
+   * set. Navigation relations and their descendants are skipped even when the
+   * adapter keeps them as descriptors (nested-object adapters do) — they are
+   * loaded with `$with`, never addressed as columns of this table.
+   */
+  private _buildGuardIndexes;
   /**
    * Indexes `fieldDescriptors` into two lookup maps for unified
    * read/write field classification in the RelationalFieldMapper.
@@ -244,6 +274,13 @@ interface TFieldMeta {
    * present in read responses. UIs render it as a set-only input.
    */
   writeOnly?: boolean;
+  /**
+   * Present (true) when the field is index-backed (explicit `@db.index*`,
+   * primary key or unique field). Advisory only — a hint for UIs that want to
+   * steer users toward cheap sort keys; it never affects whether a `$sort`
+   * is accepted (`sortable` does). Since 0.1.128.
+   */
+  indexed?: boolean;
 }
 /** Built-in CRUD operation names; map 1:1 to public method names. */
 type TCrudOp = "query" | "pages" | "one" | "geo" | "insert" | "update" | "replace" | "remove";
@@ -543,6 +580,57 @@ interface TColumnDiff {
     oldName: string;
     conflictsWith: string;
   }>;
+  /**
+   * The primary-key FIELD SET differs between the live table and the model
+   * (set semantics — a composite-key reorder is not a change, consistent with
+   * the schema hash). Column names are physical; a renamed PK column is
+   * compared under its new name. Only reported when the table exists.
+   * @since 0.1.128
+   */
+  primaryKeyChanged?: TPrimaryKeyChange;
+}
+/** Old and new primary-key column sets of a table whose key definition moved. */
+interface TPrimaryKeyChange {
+  /** Physical PK columns currently in the database (after rename mapping). */
+  from: string[];
+  /** Physical PK columns the model declares. */
+  to: string[];
+}
+/**
+ * A live foreign-key constraint as introspected from the database
+ * (outbound: declared on the table that owns it).
+ */
+interface TExistingForeignKey {
+  /** Local (referencing) columns, in constraint order. */
+  fields: string[];
+  /** Referenced table name. */
+  targetTable: string;
+  /** Referenced columns, in constraint order. */
+  targetFields: string[];
+}
+/**
+ * A live foreign key that REFERENCES a given table (inbound edge), as returned
+ * by `BaseDbAdapter.getReferencingForeignKeys(tableName)`.
+ */
+interface TReferencingForeignKey {
+  /** The referencing (child) table. */
+  table: string;
+  /** Referencing columns on `table`, in constraint order. */
+  fields: string[];
+  /** Referenced columns on the queried table, in constraint order. */
+  targetFields: string[];
+}
+/** Kind of a physical database object, as returned by `BaseDbAdapter.getObjectKind`. */
+type TDbObjectKind = "table" | "view" | "materialized";
+/** Options accepted by `BaseDbAdapter.ensureTable`. */
+interface TEnsureTableOptions {
+  /**
+   * Table names whose inline FOREIGN KEY constraints must be omitted from
+   * CREATE TABLE — the constraints are added afterwards by `syncForeignKeys()`.
+   * Schema sync passes the members of a foreign-key cycle so they can be
+   * created in any order.
+   */
+  deferForeignKeysTo?: ReadonlySet<string>;
 }
 /** Result of applying column diff to the database. */
 interface TSyncColumnResult {
@@ -684,6 +772,102 @@ interface TDbRelation {
   /** Junction type reference for 'via' (M:N) relations. */
   viaType?: () => TAtscriptAnnotatedType;
 }
+/**
+ * Write payload for insert / patch paths: every key optional, and optional
+ * columns additionally accept `null` (an explicit NULL — `undefined` means
+ * "absent" and is dropped before the row reaches defaults or validation).
+ */
+type DbPatch<D> = { [K in keyof D]?: undefined extends D[K] ? D[K] | null : D[K] } & Record<string, unknown>;
+/**
+ * Write payload for full-row replace paths: required keys stay required,
+ * optional columns additionally accept `null` (explicit NULL).
+ */
+type DbRow<D> = { [K in keyof D]: undefined extends D[K] ? D[K] | null : D[K] } & Record<string, unknown>;
+/** Built-in write actions a moost-db `AsDbController` endpoint performs. */
+type TDbWriteAction = "insert" | "insertMany" | "replace" | "replaceMany" | "update" | "updateMany";
+/**
+ * Context handed to a write {@link TWriteOptions.guard} (since 0.1.128) — and
+ * through it to `AsDbController.guardWrite()`. The table invokes the guard
+ * exactly once, inside its own transaction, after `undefined`-pruning,
+ * defaults and validation and before encryption / nested-relation phases.
+ */
+interface TDbWriteGuardContext<Row = Record<string, unknown>> {
+  /** The table method the guard runs for (`insertOne` → `insert`, `insertMany` → `insertMany`, …). */
+  readonly action: TDbWriteAction;
+  /**
+   * insert/replace: validated rows with SDK-side defaults applied (plaintext,
+   * nav data still attached); update: validated patches with the identifying
+   * PK/unique fields present and `$cas` removed. Mutate in place to enrich —
+   * the table re-validates the rows after the guard.
+   */
+  readonly rows: Row[];
+  /** Parallel to `rows`: expected version lifted from `$cas`, or `undefined`. */
+  readonly expectedVersions: ReadonlyArray<number | undefined>;
+  /**
+   * Lazy, memoised pre-image of `rows[i]` by its identifying filter, read
+   * inside the transaction. `null` when the row is missing OR when it carries
+   * no identifying key yet (e.g. auto-increment inserts) — never throws.
+   */
+  current(i: number): Promise<Row | null>;
+}
+/**
+ * Context handed to a delete {@link TDeleteOptions.guard} (since 0.1.128) —
+ * and through it to `AsDbController.guardRemove()`. Runs inside the table's
+ * transaction; an id that resolves to no filter never reaches the guard
+ * (`deleteOne` answers `{ deletedCount: 0 }`).
+ */
+interface TDbRemoveGuardContext<Row = Record<string, unknown>> {
+  /** The id `deleteOne` was called with. */
+  readonly id: unknown;
+  /** `table.resolveIdFilter(id)` — never null here. */
+  readonly filter: FilterExpr;
+  /** Lazy, memoised pre-image of the row about to be deleted (`null` when missing). */
+  current(): Promise<Row | null>;
+}
+/** A validated-stage write guard — see {@link TWriteOptions.guard}. */
+type TDbWriteGuard<Row = Record<string, unknown>> = (ctx: TDbWriteGuardContext<Row>) => void | Promise<void>;
+/** A validated-stage delete guard — see {@link TDeleteOptions.guard}. */
+type TDbRemoveGuard<Row = Record<string, unknown>> = (ctx: TDbRemoveGuardContext<Row>) => void | Promise<void>;
+/** Options of `AtscriptDbTable.touchMany` (since 0.1.129). */
+interface TTouchManyOptions {
+  /**
+   * `'all'` (default): every key must match its stored version — a stale or
+   * missing row throws `DbError("CAS_MISMATCH")` and no version moves.
+   * `'any'`: bump whatever matches and report the honest counts.
+   */
+  require?: "all" | "any";
+}
+/** Options of `insertOne/Many`, `replaceOne` / `bulkReplace`, `updateOne` / `bulkUpdate`. */
+interface TWriteOptions<Row = Record<string, unknown>> {
+  /** Nested-relation write recursion limit (default 3). */
+  maxDepth?: number;
+  /**
+   * Validated-stage guard (since 0.1.128): invoked exactly once inside the
+   * table's transaction, after defaults + validation and before encryption
+   * and nested-relation phases, with the rows the table is about to write.
+   * Rows may be enriched in place — they are validated again afterwards. A
+   * throw rolls the transaction back and propagates unchanged. Never runs
+   * for the nested re-entries a deep write performs on related tables.
+   */
+  guard?: TDbWriteGuard<Row>;
+}
+/** Options of `deleteOne`. */
+interface TDeleteOptions<Row = Record<string, unknown>> {
+  /**
+   * Validated-stage guard (since 0.1.128): invoked inside the table's
+   * transaction after the id resolved to a filter and before cascade /
+   * delete. A throw rolls the transaction back and propagates unchanged.
+   */
+  guard?: TDbRemoveGuard<Row>;
+}
+/**
+ * Adds `null` to every optional property of `O`. Optional columns store SQL
+ * NULL / Mongo null, and the runtime validator accepts `null` for optional
+ * props — so filter shapes (`{ note: null }`, `{ note: { $ne: null } }`) and
+ * row shapes must admit it at the type level too. Homomorphic: keys and
+ * required properties are unchanged; applying it twice is a no-op.
+ */
+type NullableOptional<O> = { [K in keyof O]: undefined extends O[K] ? O[K] | null : O[K] };
 //#endregion
 //#region src/base-adapter.d.ts
 /**
@@ -710,6 +894,15 @@ interface TDbRelation {
  * - `this._table.isView` — whether this is a view (vs a table)
  */
 declare abstract class BaseDbAdapter {
+  /**
+   * The readable this adapter serves. UNSET on an administrative adapter:
+   * `DbSpace` creates one from the factory without a readable for the
+   * name-taking schema-sync primitives (`dropTableByName`, `dropViewByName`,
+   * `dropTablesByName`, `getReferencingForeignKeys`, `getObjectKind`,
+   * `getExistingColumnsForTable`, `hasRows(tableName)`), so those must derive
+   * everything — the schema included — from the driver/connection, never from
+   * `this._table`.
+   */
   protected _table: AtscriptDbReadable<any, any, any, any, any, any, any>;
   /**
    * Resolves the correct insertedId: prefers the user-supplied PK value
@@ -738,7 +931,9 @@ declare abstract class BaseDbAdapter {
   protected _log(...args: unknown[]): void;
   /**
    * Runs `fn` inside a database transaction. Nested calls (from related tables
-   * within the same async chain) reuse the existing transaction automatically.
+   * within the same async chain) reuse the existing transaction automatically
+   * — "existing" meaning a transaction of the same {@link _transactionOwner};
+   * inside another adapter family's transaction this opens its own.
    *
    * The generic layer handles nesting detection via `AsyncLocalStorage`.
    * Adapters override `_beginTransaction`, `_commitTransaction`, and
@@ -746,7 +941,17 @@ declare abstract class BaseDbAdapter {
    */
   withTransaction<T>(fn: () => Promise<T>): Promise<T>;
   /**
-   * Returns the opaque transaction state from the current async context.
+   * The object a transaction state is branded with (since 0.1.128). Every
+   * adapter instance that returns the same owner shares one transaction —
+   * override to return the driver / pool / client the adapter was constructed
+   * with, so all tables of a space join it. The default (the adapter class)
+   * suits adapters without a connection object (in-memory, mocks).
+   */
+  protected _transactionOwner(): unknown;
+  /**
+   * Returns the opaque transaction state of THIS adapter's owner from the
+   * current async context — `undefined` when no transaction is open or only
+   * another adapter family's transaction is (its state is never handed out).
    * Adapters use this to retrieve DB-specific state (e.g., MongoDB `ClientSession`).
    */
   protected _getTransactionState(): unknown;
@@ -755,7 +960,7 @@ declare abstract class BaseDbAdapter {
    * Adapters that override `withTransaction` (e.g., to use MongoDB's
    * `session.withTransaction()` Convenient API) use this to set up the
    * shared context so that nested adapters see the same session.
-   * If a context already exists (nesting), it's reused.
+   * If a context of the same owner already exists (nesting), it's reused.
    */
   protected _runInTransactionContext<T>(state: unknown, fn: () => Promise<T>): Promise<T>;
   /**
@@ -797,11 +1002,14 @@ declare abstract class BaseDbAdapter {
    */
   supportsNestedObjects(): boolean;
   /**
-   * Whether the DB engine handles static `@db.default "value"` natively
-   * via column-level DEFAULT clauses in CREATE TABLE.
-   * When `true`, `_applyDefaults()` skips client-side value defaults,
-   * letting the DB apply its own DEFAULT. SQL adapters return `true`;
-   * document stores (MongoDB) return `false` and apply defaults client-side.
+   * Whether the DB engine carries static `@db.default "value"` defaults in
+   * its DDL (`DEFAULT` clauses in `CREATE TABLE`).
+   *
+   * @deprecated since 0.1.128 — no longer consulted: the table layer fills
+   * static value defaults SDK-side on every adapter before validation, and the
+   * SQL adapters emit their DDL `DEFAULT` clauses regardless of this flag.
+   * Kept as a capability hint for tooling; nothing in the generic layer
+   * branches on it.
    */
   supportsNativeValueDefaults(): boolean;
   /**
@@ -838,9 +1046,12 @@ declare abstract class BaseDbAdapter {
   canFilterField(fd: TDbFieldMeta): boolean;
   /**
    * Whether this adapter can sort by a given field.
-   * Default: scalar columns yes, JSON-stored columns no. Mongo's array sort
-   * (min/max element) is a footgun for generic UI sort headers, so the default
-   * stays conservative even for adapters that technically support it.
+   * Default: scalar columns yes; JSON-stored columns, `@db.json` objects and
+   * arrays no. Mongo's array sort (min/max element) is a footgun for generic
+   * UI sort headers, so the default stays conservative even for adapters that
+   * technically support it — the veto keys on `designType` as well as
+   * `storage` because nested-object adapters keep arrays / `@db.json` values
+   * inline as `storage: 'column'` (since 0.1.128).
    */
   canSortField(fd: TDbFieldMeta): boolean;
   /**
@@ -961,6 +1172,14 @@ declare abstract class BaseDbAdapter {
     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).
@@ -1090,8 +1309,14 @@ declare abstract class BaseDbAdapter {
   /**
    * Ensures the table exists in the database, creating it if needed.
    * Uses `this._table.tableName`, `this._table.schema`, etc.
+   *
+   * @param opts - Optional (since 0.1.128). Relational adapters that emit
+   *   inline FOREIGN KEY constraints must omit those whose target is in
+   *   `opts.deferForeignKeysTo` — schema sync adds them afterwards through
+   *   {@link syncForeignKeys} so a foreign-key cycle can be created in any
+   *   order. Adapters without inline constraints ignore the parameter.
    */
-  abstract ensureTable(): Promise<void>;
+  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.
@@ -1128,8 +1353,13 @@ declare abstract class BaseDbAdapter {
    *
    * Returns undefined if the adapter cannot introspect table options.
    * In that case, schema sync falls back to stored snapshot.
+   *
+   * @param tableName - Introspect this table instead of the adapter's own
+   *   (schema sync passes the OLD name of a table that is about to be
+   *   renamed, as for `getExistingColumnsForTable`). Defaults to the bound
+   *   table.
    */
-  getExistingTableOptions?(): Promise<TExistingTableOption[]>;
+  getExistingTableOptions?(tableName?: string): Promise<TExistingTableOption[]>;
   /**
    * Applies non-destructive table option changes (e.g., MySQL ALTER TABLE ENGINE=X).
    * Called for each non-destructive change in the diff.
@@ -1205,6 +1435,58 @@ declare abstract class BaseDbAdapter {
    * Optional — only relational adapters implement this.
    */
   dropViewByName?(viewName: string): Promise<void>;
+  /**
+   * Drops several tables that reference each other (a foreign-key cycle) as
+   * one operation. Schema sync only calls this for cycles whose members are
+   * ALL being removed. Default: {@link dropTableByName} in the given order —
+   * enough for engines that tolerate it (SQLite with FK checks off, MySQL with
+   * FOREIGN_KEY_CHECKS=0); PostgreSQL overrides it with one multi-table
+   * `DROP TABLE a, b` statement.
+   * @since 0.1.128
+   */
+  dropTablesByName(tableNames: string[]): Promise<void>;
+  /**
+   * Whether the table has at least one row. Schema sync uses it in the
+   * pre-flight phase to refuse a primary-key change on a populated table.
+   * Override with an EXISTS/LIMIT 1 probe — this default is `count() > 0`,
+   * a full scan on some engines, and it can only answer for the adapter's
+   * OWN table: for another `tableName` (or on an administrative adapter
+   * without a readable) it returns `undefined` ("cannot tell"), which schema
+   * sync treats as a refusal.
+   *
+   * @param tableName - Check this table instead of the adapter's own (schema
+   *   sync passes the OLD name of a table that is about to be renamed).
+   * @returns `true`/`false`, or `undefined` when the adapter cannot tell.
+   * @since 0.1.128
+   */
+  hasRows(tableName?: string): Promise<boolean | undefined>;
+  /**
+   * Live foreign keys that REFERENCE `tableName` (inbound edges), from any
+   * table in the database — including tables whose models are no longer in
+   * the sync inventory. Schema sync uses it to order drops (children before
+   * parents), to refuse dropping a table that an unmanaged table still
+   * references, and to refuse a primary-key change that a live FK depends on.
+   * Optional — engines without physical foreign keys omit it.
+   * @since 0.1.128
+   */
+  getReferencingForeignKeys?(tableName: string): Promise<TReferencingForeignKey[]>;
+  /**
+   * Kind of the physical object stored under `name`, or `undefined` when
+   * nothing exists. Schema sync refuses a run when a physical table sits
+   * where a managed view is declared (or a view where a table is declared)
+   * instead of silently creating/skipping over it.
+   * Optional — adapters without the method skip the check.
+   * @since 0.1.128
+   */
+  getObjectKind?(name: string): Promise<TDbObjectKind | undefined>;
+  /**
+   * Rewrites the table's primary key from `change.from` to `change.to`.
+   * Called only on an EMPTY table (schema sync refuses populated ones) after
+   * new columns were added and before stale columns are dropped, so both
+   * column sets exist. Adapters without it fall back to {@link recreateTable}.
+   * @since 0.1.128
+   */
+  rebuildPrimaryKey?(change: TPrimaryKeyChange): Promise<void>;
   /**
    * Renames a table/collection from `oldName` to the adapter's current table name.
    * Used by schema sync when `@db.table.renamed` is present.
@@ -1422,7 +1704,7 @@ declare function resolveDesignType(fieldType: TAtscriptAnnotatedType): string;
  * {@link AtscriptDbTable} (adds write operations) and {@link AtscriptDbView}
  * (adds view plan/DDL).
  */
-declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>, _FlatType = FlatOf<T>, A extends BaseDbAdapter = BaseDbAdapter, IdType = PrimaryKeyOf<T>, OwnProps = OwnPropsOf<T>, NavType extends Record<string, unknown> = NavPropsOf<T>> {
+declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>, _FlatType = NullableOptional<FlatOf<T>>, A extends BaseDbAdapter = BaseDbAdapter, IdType = PrimaryKeyOf<T>, OwnProps = NullableOptional<OwnPropsOf<T>>, NavType extends Record<string, unknown> = NavPropsOf<T>> {
   protected readonly _type: T;
   protected readonly adapter: A;
   protected readonly logger: TGenericLogger;
@@ -1733,4 +2015,4 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   }, thisTableName: string, alias?: string): TDbForeignKey | undefined;
 }
 //#endregion
-export { TIdentification as $, TDbActionLevel as A, TDbIndexType as B, TCascadeResolver as C, TCrudPermissions as D, TCrudOp as E, TDbDeleteResult as F, TDbStorageType as G, TDbInsertResult as H, TDbFieldMeta as I, TExistingTableOption as J, TDbUpdateResult as K, TDbForeignKey as L, TDbCollation as M, TDbDefaultFn as N, TDbActionInfo as O, TDbDefaultValue as P, TIdDescriptor as Q, TDbIndex as R, PrimaryKeyOf$1 as S, TColumnDiff as T, TDbReferentialAction as U, TDbInsertManyResult as V, TDbRelation as W, TFkLookupResolver as X, TFieldMeta as Y, TFkLookupTarget as Z, FieldOpsFor as _, TGenericLogger as _t, TDbEncryptionOptions as a, TTableOptionDiff as at, NavPropsOf$1 as b, BaseDbAdapter as c, TWriteTableResolver as ct, AggregateFn as d, UniqueryControls$1 as dt, TMetaResponse as et, AggregateQuery$1 as f, WithRelation$1 as ft, DbQuery as g, NoopLogger as gt, DbControls as h, isGeoPointType as ht, DbEncryption as i, TSyncColumnResult as it, TDbActionProcessor as j, TDbActionIntent as k, AggregateControls as l, TypedWithRelation as lt, AtscriptDbWritable as m, isGeoIndexableType as mt, DbResponse as n, TRelationInfo as nt, DocumentFieldMapper as o, TTableResolver as ot, AggregateResult as p, TableMetadata as pt, TExistingColumn as q, resolveDesignType as r, TSearchIndexInfo as rt, FieldMappingStrategy as s, TValueFormatterPair as st, AtscriptDbReadable as t, TMetadataOverrides as tt, AggregateExpr$1 as u, Uniquery$1 as ut, FilterExpr$1 as v, UniquSelect as vt, TCascadeTarget as w, OwnPropsOf$1 as x, FlatOf$1 as y, TDbIndexField as z };
+export { TDbWriteAction as $, TCrudPermissions as A, findAncestorInSet as At, TDbForeignKey as B, NullableOptional as C, TWriteOptions as Ct, TCascadeTarget as D, UniqueryControls$1 as Dt, TCascadeResolver as E, Uniquery$1 as Et, TDbCollation as F, UniquSelect as Ft, TDbInsertResult as G, TDbIndexField as H, TDbDefaultFn as I, TDbRelation as J, TDbObjectKind as K, TDbDefaultValue as L, TDbActionIntent as M, isGeoPointType as Mt, TDbActionLevel as N, NoopLogger as Nt, TColumnDiff as O, WithRelation$1 as Ot, TDbActionProcessor as P, TGenericLogger as Pt, TDbUpdateResult as Q, TDbDeleteResult as R, NavPropsOf$1 as S, TValueFormatterPair as St, PrimaryKeyOf$1 as T, TypedWithRelation as Tt, TDbIndexType as U, TDbIndex as V, TDbInsertManyResult as W, TDbRemoveGuardContext as X, TDbRemoveGuard as Y, TDbStorageType as Z, DbQuery as _, TSearchIndexInfo as _t, TDbEncryptionOptions as a, TExistingForeignKey as at, FilterExpr$1 as b, TTableResolver as bt, BaseDbAdapter as c, TFkLookupResolver as ct, AggregateFn as d, TIdentification as dt, TDbWriteGuard as et, AggregateQuery$1 as f, TMetaResponse as ft, DbPatch as g, TRelationInfo as gt, DbControls as h, TReferencingForeignKey as ht, DbEncryption as i, TExistingColumn as it, TDbActionInfo as j, isGeoIndexableType as jt, TCrudOp as k, TableMetadata as kt, AggregateControls as l, TFkLookupTarget as lt, AtscriptDbWritable as m, TPrimaryKeyChange as mt, DbResponse as n, TDeleteOptions as nt, DocumentFieldMapper as o, TExistingTableOption as ot, AggregateResult as p, TMetadataOverrides as pt, TDbReferentialAction as q, resolveDesignType as r, TEnsureTableOptions as rt, FieldMappingStrategy as s, TFieldMeta as st, AtscriptDbReadable as t, TDbWriteGuardContext as tt, AggregateExpr$1 as u, TIdDescriptor as ut, DbRow as v, TSyncColumnResult as vt, OwnPropsOf$1 as w, TWriteTableResolver as wt, FlatOf$1 as x, TTouchManyOptions as xt, FieldOpsFor as y, TTableOptionDiff as yt, TDbFieldMeta as z };