@atscript/db 0.1.127 → 0.1.129

package/dist/{db-space-B_ASuDaR.d.mts → db-space-C2UCnGHd.d.cts}

@@ -1,6 +1,6 @@
-import { C as TCascadeResolver, F as TDbDeleteResult, H as TDbInsertResult, K as TDbUpdateResult, V as TDbInsertManyResult, X as TFkLookupResolver, _t as TGenericLogger, a as TDbEncryptionOptions, c as BaseDbAdapter, ct as TWriteTableResolver, i as DbEncryption, ot as TTableResolver, pt as TableMetadata, t as AtscriptDbReadable } from "./db-readable-BkAGccv9.mjs";
-import { AtscriptQueryComparison, AtscriptQueryFieldRef, AtscriptQueryFieldRef as AtscriptQueryFieldRef$1, AtscriptQueryNode, AtscriptQueryNode as AtscriptQueryNode$1, AtscriptRef, FlatOf, NavPropsOf, OwnPropsOf, PrimaryKeyOf, TAtscriptAnnotatedType, TAtscriptDataType, Validator } from "@atscript/typescript/utils";
+import { C as NullableOptional, Ct as TWriteOptions, E as TCascadeResolver, G as TDbInsertResult, Pt as TGenericLogger, Q as TDbUpdateResult, R as TDbDeleteResult, W as TDbInsertManyResult, a as TDbEncryptionOptions, bt as TTableResolver, c as BaseDbAdapter, ct as TFkLookupResolver, g as DbPatch, ht as TReferencingForeignKey, i as DbEncryption, kt as TableMetadata, nt as TDeleteOptions, t as AtscriptDbReadable, v as DbRow, wt as TWriteTableResolver, xt as TTouchManyOptions } from "./db-readable-B7eYWS5q.cjs";
 import { FilterExpr } from "@uniqu/core";
+import { AtscriptQueryComparison, AtscriptQueryFieldRef, AtscriptQueryFieldRef as AtscriptQueryFieldRef$1, AtscriptQueryNode, AtscriptQueryNode as AtscriptQueryNode$1, AtscriptRef, FlatOf, NavPropsOf, OwnPropsOf, PrimaryKeyOf, TAtscriptAnnotatedType, TAtscriptDataType, Validator } from "@atscript/typescript/utils";
 
 //#region src/strategies/integrity.d.ts
 /**
@@ -24,7 +24,7 @@ declare class NativeIntegrity extends IntegrityStrategy {
 }
 //#endregion
 //#region src/table/db-table.d.ts
-declare class AtscriptDbTable<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>> extends AtscriptDbReadable<T, DataType, FlatType, A, IdType, OwnProps, NavType> {
+declare class AtscriptDbTable<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>> extends AtscriptDbReadable<T, DataType, FlatType, A, IdType, OwnProps, NavType> {
   protected _cascadeResolver?: TCascadeResolver;
   protected _fkLookupResolver?: TFkLookupResolver;
   protected readonly _integrity: IntegrityStrategy;
@@ -53,9 +53,7 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * Inserts a single record. Delegates to {@link insertMany} for unified
    * nested creation support.
    */
-  insertOne(payload: Partial<DataType> & Record<string, unknown>, opts?: {
-    maxDepth?: number;
-  }): Promise<TDbInsertResult>;
+  insertOne(payload: DbPatch<DataType>, opts?: TWriteOptions<DataType>): Promise<TDbInsertResult>;
   /**
    * Inserts multiple records with batch-optimized nested creation.
    *
@@ -66,17 +64,16 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * (they receive our PKs as their FKs). Fully recursive — nested records
    * with their own nav data trigger further batch inserts at each level.
    * Recursive up to `maxDepth` (default 3).
+   *
+   * `opts.guard` (since 0.1.128) runs once inside the transaction, after
+   * defaults + validation, with the prepared rows — see {@link TWriteOptions}.
    */
-  insertMany(payloads: Array<Partial<DataType> & Record<string, unknown>>, opts?: {
-    maxDepth?: number;
-  }): Promise<TDbInsertManyResult>;
+  insertMany(payloads: Array<DbPatch<DataType>>, opts?: TWriteOptions<DataType>): Promise<TDbInsertManyResult>;
   /**
    * Replaces a single record identified by primary key(s).
    * Delegates to {@link bulkReplace} for unified nested relation support.
    */
-  replaceOne(payload: DataType & Record<string, unknown>, opts?: {
-    maxDepth?: number;
-  }): Promise<TDbUpdateResult>;
+  replaceOne(payload: DbRow<DataType>, opts?: TWriteOptions<DataType>): Promise<TDbUpdateResult>;
   /**
    * Replaces multiple records with deep nested relation support.
    *
@@ -84,37 +81,69 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * replaced first (their PKs become our FKs), FROM dependents are replaced
    * after (they receive our PKs as their FKs), VIA relations clear and
    * re-create junction rows. Fully recursive up to `maxDepth` (default 3).
+   *
+   * `opts.guard` (since 0.1.128) runs once inside the transaction, after
+   * `$cas` extraction, defaults + validation — see {@link TWriteOptions}.
    */
-  bulkReplace(payloads: Array<DataType & Record<string, unknown>>, opts?: {
-    maxDepth?: number;
-  }): Promise<TDbUpdateResult>;
+  bulkReplace(payloads: Array<DbRow<DataType>>, opts?: TWriteOptions<DataType>): Promise<TDbUpdateResult>;
   /**
    * Partially updates a single record identified by primary key(s).
    * Delegates to {@link bulkUpdate} for unified nested relation support.
    */
-  updateOne(payload: Partial<DataType> & Record<string, unknown>, opts?: {
-    maxDepth?: number;
-  }): Promise<TDbUpdateResult>;
+  updateOne(payload: DbPatch<DataType>, opts?: TWriteOptions<DataType>): Promise<TDbUpdateResult>;
   /**
    * Partially updates multiple records with deep nested relation support.
    *
    * Only TO relations (1:1, N:1) are supported for patching. FROM/VIA
    * relations will error — use {@link bulkReplace} for those.
    * Recursive up to `maxDepth` (default 3).
+   *
+   * `opts.guard` (since 0.1.128) runs once inside the transaction, after
+   * `$cas` extraction and validation, with the patches (identifying fields
+   * present, `$cas` removed) — see {@link TWriteOptions}.
+   */
+  bulkUpdate(payloads: Array<DbPatch<DataType>>, opts?: TWriteOptions<DataType>): Promise<TDbUpdateResult>;
+  /**
+   * Batch versioned touch (since 0.1.129): bumps the version of every listed
+   * row by exactly one, each row guarded by its own expected version. This is
+   * the batch fence `updateMany(orFilter, {})` used to be before 0.1.128 (an
+   * empty patch is a no-op since then and takes no lock).
+   *
+   * Each key carries the primary key field(s) (composite supported) plus the
+   * version column and NOTHING else — a touch has no payload. Unique indexes
+   * do not identify a touch key. `undefined`-valued properties are ignored,
+   * like in every write payload. Empty `keys` → `{ 0, 0 }` without a statement.
+   *
+   * `require: 'all'` (default): one count over the whole key set runs FIRST;
+   * a stale or missing row throws {@link CasMismatchError} before any write.
+   * The bumps then run as `updateMany(orFilter, {})` chunks of at most
+   * {@link TOUCH_MANY_CHUNK} keys inside one adapter transaction; a summed
+   * `matchedCount` short of `keys.length` (a row moved between the count and
+   * the bump) throws the same error — SQL engines roll every bump back. The
+   * pre-count is therefore a deliberate double check on SQL: it is what makes
+   * the guarantee hold on adapters whose `withTransaction` is a passthrough
+   * (the memory adapter, a Mongo standalone topology) — there it covers the
+   * common stale case and the residual race window is accepted.
+   * `require: 'any'`: no pre-count, the honest summed result is returned.
+   *
+   * No `guard`, no `onWrite`; not exposed over HTTP.
    */
-  bulkUpdate(payloads: Array<Partial<DataType> & Record<string, unknown>>, opts?: {
-    maxDepth?: number;
-  }): Promise<TDbUpdateResult>;
+  touchMany(keys: Array<DbPatch<DataType>>, opts?: TTouchManyOptions): Promise<TDbUpdateResult>;
   /**
    * Deletes a single record by any type-compatible identifier — primary key
    * or single-field unique index. Uses the same resolution logic as `findById`.
    *
    * When the adapter does not support native foreign keys (e.g. MongoDB),
    * cascade and setNull actions are applied before the delete.
-   */
-  deleteOne(id: IdType): Promise<TDbDeleteResult>;
-  updateMany(filter: FilterExpr<FlatType>, data: Partial<DataType> & Record<string, unknown>): Promise<TDbUpdateResult>;
-  replaceMany(filter: FilterExpr<FlatType>, data: Record<string, unknown>): Promise<TDbUpdateResult>;
+   *
+   * `opts.guard` (since 0.1.128) runs inside the transaction once the id has
+   * resolved to a filter, before cascade / delete — see {@link TDeleteOptions}.
+   * An id that resolves to no filter answers `{ deletedCount: 0 }` without
+   * calling the guard.
+   */
+  deleteOne(id: IdType, opts?: TDeleteOptions<DataType>): Promise<TDbDeleteResult>;
+  updateMany(filter: FilterExpr<FlatType>, data: DbPatch<DataType>): Promise<TDbUpdateResult>;
+  replaceMany(filter: FilterExpr<FlatType>, data: DbRow<DataType>): Promise<TDbUpdateResult>;
   deleteMany(filter: FilterExpr<FlatType>): Promise<TDbDeleteResult>;
   /**
    * Synchronizes indexes between Atscript definitions and the database.
@@ -140,11 +169,31 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    */
   protected _encryptItems(items: Array<Record<string, unknown>>, mode: "write" | "patch"): Promise<void>;
   /**
-   * Applies default values for fields that are missing from the payload.
-   * Defaults handled natively by the DB engine are skipped — the field stays
-   * absent so the DB's own DEFAULT clause applies.
+   * Lazy pre-image read for a guard's `current(i)`: `null` when the row has
+   * no identifying key (e.g. an auto-increment insert) or the key cannot be
+   * resolved — never throws for a missing key.
+   * @internal
+   */
+  _readPreImage(row: unknown): Promise<DataType | null>;
+  /**
+   * Applies `@db.default` values in place to a row's absent fields — the
+   * defaults pass every insert / replace path runs before validation.
+   * Static value defaults (`@db.default 'x'`) are filled on EVERY adapter
+   * (since 0.1.128 — writing the column's own default explicitly is
+   * equivalent to leaving it to the DDL `DEFAULT`, and write guards see the
+   * full row). Function defaults (`now` / `uuid` / `increment` / custom) the
+   * adapter handles natively are NOT filled — the field stays absent so the
+   * engine's own default applies. The version column is never touched.
    */
   protected _applyDefaults(data: Record<string, unknown>): Record<string, unknown>;
+  /**
+   * The JS value for a `@db.default 'literal'`: strings (including unions of
+   * string literals) are used as-is, every other design type is parsed as
+   * JSON — the same value the SQL adapters put into the DDL `DEFAULT` clause.
+   * A literal that is not valid JSON falls back to the raw string so the
+   * validator reports it against the field instead of a bare `SyntaxError`.
+   */
+  private _parseValueDefault;
   /**
    * Extracts a record-identifying filter from a payload.
    *
@@ -235,7 +284,7 @@ interface TViewColumnMapping {
  * const users = await activeUsers.findMany({ filter: {}, controls: {} })
  * ```
  */
-declare class AtscriptDbView<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>> extends AtscriptDbReadable<T, DataType, FlatType, A, IdType, OwnProps, NavType> {
+declare class AtscriptDbView<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>> extends AtscriptDbReadable<T, DataType, FlatType, A, IdType, OwnProps, NavType> {
   private _viewPlan?;
   get isView(): boolean;
   /**
@@ -267,6 +316,16 @@ declare class AtscriptDbView<T extends TAtscriptAnnotatedType = TAtscriptAnnotat
    */
   getViewColumnMappings(): TViewColumnMapping[];
 }
+/**
+ * Structural type guard for views: `true` when the readable reports
+ * `isView`, whether or not it is an `AtscriptDbView` instance of THIS copy
+ * of `@atscript/db`. Adapters must use this (or `readable.isView`) instead of
+ * `instanceof AtscriptDbView` — in a bundle that carries two copies of the
+ * core (app bundle + external adapter), `instanceof` is false and the adapter
+ * would create an empty physical table under the view's name.
+ * @since 0.1.128
+ */
+declare function isAtscriptDbView(readable: AtscriptDbReadable<any, any, any, any, any, any, any>): readable is AtscriptDbView<any, any, any, any, any, any, any>;
 //#endregion
 //#region src/table/db-space.d.ts
 /**
@@ -343,6 +402,25 @@ declare class DbSpace {
    * Drops a view by name. Used by schema sync to remove views no longer in the schema.
    */
   dropViewByName(viewName: string): Promise<void>;
+  /**
+   * Drops a group of mutually referencing tables as one operation.
+   * Used by schema sync to remove a foreign-key cycle no longer in the schema.
+   * @since 0.1.128
+   */
+  dropTablesByName(tableNames: string[]): Promise<void>;
+  /**
+   * Live foreign keys referencing `tableName`, or `undefined` when the
+   * adapter cannot introspect them. Used by schema sync for drop ordering
+   * and surviving-reference checks of tables without a registered readable.
+   * @since 0.1.128
+   */
+  getReferencingForeignKeys(tableName: string): Promise<TReferencingForeignKey[] | undefined>;
+  /**
+   * A factory-fresh adapter with NO registered readable. Only the name-taking
+   * primitives may run on it (`dropTableByName`, `dropViewByName`,
+   * `dropTablesByName`, `getReferencingForeignKeys`) — adapters derive the
+   * schema for those from the driver/connection, not from a bound table.
+   */
   private _getAdminAdapter;
   /**
    * Finds all child tables with FKs pointing to the given parent table name.
@@ -356,4 +434,4 @@ declare class DbSpace {
   private _getFkLookupTarget;
 }
 //#endregion
-export { TViewColumnMapping as a, AtscriptQueryNode$1 as c, TViewPlan as d, translateQueryTree as f, NativeIntegrity as h, AtscriptDbView as i, AtscriptRef as l, IntegrityStrategy as m, TAdapterFactory as n, AtscriptQueryComparison as o, AtscriptDbTable as p, TDbSpaceOptions as r, AtscriptQueryFieldRef$1 as s, DbSpace as t, TViewJoin as u };
+export { TViewColumnMapping as a, AtscriptQueryFieldRef$1 as c, TViewJoin as d, TViewPlan as f, NativeIntegrity as g, IntegrityStrategy as h, AtscriptDbView as i, AtscriptQueryNode$1 as l, AtscriptDbTable as m, TAdapterFactory as n, isAtscriptDbView as o, translateQueryTree as p, TDbSpaceOptions as r, AtscriptQueryComparison as s, DbSpace as t, AtscriptRef as u };

package/dist/{db-space-CSntT6yS.d.cts → db-space-DdIPYD0Q.d.mts}

@@ -1,6 +1,6 @@
-import { C as TCascadeResolver, F as TDbDeleteResult, H as TDbInsertResult, K as TDbUpdateResult, V as TDbInsertManyResult, X as TFkLookupResolver, _t as TGenericLogger, a as TDbEncryptionOptions, c as BaseDbAdapter, ct as TWriteTableResolver, i as DbEncryption, ot as TTableResolver, pt as TableMetadata, t as AtscriptDbReadable } from "./db-readable-C0nDKX8A.cjs";
-import { FilterExpr } from "@uniqu/core";
+import { C as NullableOptional, Ct as TWriteOptions, E as TCascadeResolver, G as TDbInsertResult, Pt as TGenericLogger, Q as TDbUpdateResult, R as TDbDeleteResult, W as TDbInsertManyResult, a as TDbEncryptionOptions, bt as TTableResolver, c as BaseDbAdapter, ct as TFkLookupResolver, g as DbPatch, ht as TReferencingForeignKey, i as DbEncryption, kt as TableMetadata, nt as TDeleteOptions, t as AtscriptDbReadable, v as DbRow, wt as TWriteTableResolver, xt as TTouchManyOptions } from "./db-readable-Bn1bV_eC.mjs";
 import { AtscriptQueryComparison, AtscriptQueryFieldRef, AtscriptQueryFieldRef as AtscriptQueryFieldRef$1, AtscriptQueryNode, AtscriptQueryNode as AtscriptQueryNode$1, AtscriptRef, FlatOf, NavPropsOf, OwnPropsOf, PrimaryKeyOf, TAtscriptAnnotatedType, TAtscriptDataType, Validator } from "@atscript/typescript/utils";
+import { FilterExpr } from "@uniqu/core";
 
 //#region src/strategies/integrity.d.ts
 /**
@@ -24,7 +24,7 @@ declare class NativeIntegrity extends IntegrityStrategy {
 }
 //#endregion
 //#region src/table/db-table.d.ts
-declare class AtscriptDbTable<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>> extends AtscriptDbReadable<T, DataType, FlatType, A, IdType, OwnProps, NavType> {
+declare class AtscriptDbTable<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>> extends AtscriptDbReadable<T, DataType, FlatType, A, IdType, OwnProps, NavType> {
   protected _cascadeResolver?: TCascadeResolver;
   protected _fkLookupResolver?: TFkLookupResolver;
   protected readonly _integrity: IntegrityStrategy;
@@ -53,9 +53,7 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * Inserts a single record. Delegates to {@link insertMany} for unified
    * nested creation support.
    */
-  insertOne(payload: Partial<DataType> & Record<string, unknown>, opts?: {
-    maxDepth?: number;
-  }): Promise<TDbInsertResult>;
+  insertOne(payload: DbPatch<DataType>, opts?: TWriteOptions<DataType>): Promise<TDbInsertResult>;
   /**
    * Inserts multiple records with batch-optimized nested creation.
    *
@@ -66,17 +64,16 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * (they receive our PKs as their FKs). Fully recursive — nested records
    * with their own nav data trigger further batch inserts at each level.
    * Recursive up to `maxDepth` (default 3).
+   *
+   * `opts.guard` (since 0.1.128) runs once inside the transaction, after
+   * defaults + validation, with the prepared rows — see {@link TWriteOptions}.
    */
-  insertMany(payloads: Array<Partial<DataType> & Record<string, unknown>>, opts?: {
-    maxDepth?: number;
-  }): Promise<TDbInsertManyResult>;
+  insertMany(payloads: Array<DbPatch<DataType>>, opts?: TWriteOptions<DataType>): Promise<TDbInsertManyResult>;
   /**
    * Replaces a single record identified by primary key(s).
    * Delegates to {@link bulkReplace} for unified nested relation support.
    */
-  replaceOne(payload: DataType & Record<string, unknown>, opts?: {
-    maxDepth?: number;
-  }): Promise<TDbUpdateResult>;
+  replaceOne(payload: DbRow<DataType>, opts?: TWriteOptions<DataType>): Promise<TDbUpdateResult>;
   /**
    * Replaces multiple records with deep nested relation support.
    *
@@ -84,37 +81,69 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * replaced first (their PKs become our FKs), FROM dependents are replaced
    * after (they receive our PKs as their FKs), VIA relations clear and
    * re-create junction rows. Fully recursive up to `maxDepth` (default 3).
+   *
+   * `opts.guard` (since 0.1.128) runs once inside the transaction, after
+   * `$cas` extraction, defaults + validation — see {@link TWriteOptions}.
    */
-  bulkReplace(payloads: Array<DataType & Record<string, unknown>>, opts?: {
-    maxDepth?: number;
-  }): Promise<TDbUpdateResult>;
+  bulkReplace(payloads: Array<DbRow<DataType>>, opts?: TWriteOptions<DataType>): Promise<TDbUpdateResult>;
   /**
    * Partially updates a single record identified by primary key(s).
    * Delegates to {@link bulkUpdate} for unified nested relation support.
    */
-  updateOne(payload: Partial<DataType> & Record<string, unknown>, opts?: {
-    maxDepth?: number;
-  }): Promise<TDbUpdateResult>;
+  updateOne(payload: DbPatch<DataType>, opts?: TWriteOptions<DataType>): Promise<TDbUpdateResult>;
   /**
    * Partially updates multiple records with deep nested relation support.
    *
    * Only TO relations (1:1, N:1) are supported for patching. FROM/VIA
    * relations will error — use {@link bulkReplace} for those.
    * Recursive up to `maxDepth` (default 3).
+   *
+   * `opts.guard` (since 0.1.128) runs once inside the transaction, after
+   * `$cas` extraction and validation, with the patches (identifying fields
+   * present, `$cas` removed) — see {@link TWriteOptions}.
+   */
+  bulkUpdate(payloads: Array<DbPatch<DataType>>, opts?: TWriteOptions<DataType>): Promise<TDbUpdateResult>;
+  /**
+   * Batch versioned touch (since 0.1.129): bumps the version of every listed
+   * row by exactly one, each row guarded by its own expected version. This is
+   * the batch fence `updateMany(orFilter, {})` used to be before 0.1.128 (an
+   * empty patch is a no-op since then and takes no lock).
+   *
+   * Each key carries the primary key field(s) (composite supported) plus the
+   * version column and NOTHING else — a touch has no payload. Unique indexes
+   * do not identify a touch key. `undefined`-valued properties are ignored,
+   * like in every write payload. Empty `keys` → `{ 0, 0 }` without a statement.
+   *
+   * `require: 'all'` (default): one count over the whole key set runs FIRST;
+   * a stale or missing row throws {@link CasMismatchError} before any write.
+   * The bumps then run as `updateMany(orFilter, {})` chunks of at most
+   * {@link TOUCH_MANY_CHUNK} keys inside one adapter transaction; a summed
+   * `matchedCount` short of `keys.length` (a row moved between the count and
+   * the bump) throws the same error — SQL engines roll every bump back. The
+   * pre-count is therefore a deliberate double check on SQL: it is what makes
+   * the guarantee hold on adapters whose `withTransaction` is a passthrough
+   * (the memory adapter, a Mongo standalone topology) — there it covers the
+   * common stale case and the residual race window is accepted.
+   * `require: 'any'`: no pre-count, the honest summed result is returned.
+   *
+   * No `guard`, no `onWrite`; not exposed over HTTP.
    */
-  bulkUpdate(payloads: Array<Partial<DataType> & Record<string, unknown>>, opts?: {
-    maxDepth?: number;
-  }): Promise<TDbUpdateResult>;
+  touchMany(keys: Array<DbPatch<DataType>>, opts?: TTouchManyOptions): Promise<TDbUpdateResult>;
   /**
    * Deletes a single record by any type-compatible identifier — primary key
    * or single-field unique index. Uses the same resolution logic as `findById`.
    *
    * When the adapter does not support native foreign keys (e.g. MongoDB),
    * cascade and setNull actions are applied before the delete.
-   */
-  deleteOne(id: IdType): Promise<TDbDeleteResult>;
-  updateMany(filter: FilterExpr<FlatType>, data: Partial<DataType> & Record<string, unknown>): Promise<TDbUpdateResult>;
-  replaceMany(filter: FilterExpr<FlatType>, data: Record<string, unknown>): Promise<TDbUpdateResult>;
+   *
+   * `opts.guard` (since 0.1.128) runs inside the transaction once the id has
+   * resolved to a filter, before cascade / delete — see {@link TDeleteOptions}.
+   * An id that resolves to no filter answers `{ deletedCount: 0 }` without
+   * calling the guard.
+   */
+  deleteOne(id: IdType, opts?: TDeleteOptions<DataType>): Promise<TDbDeleteResult>;
+  updateMany(filter: FilterExpr<FlatType>, data: DbPatch<DataType>): Promise<TDbUpdateResult>;
+  replaceMany(filter: FilterExpr<FlatType>, data: DbRow<DataType>): Promise<TDbUpdateResult>;
   deleteMany(filter: FilterExpr<FlatType>): Promise<TDbDeleteResult>;
   /**
    * Synchronizes indexes between Atscript definitions and the database.
@@ -140,11 +169,31 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    */
   protected _encryptItems(items: Array<Record<string, unknown>>, mode: "write" | "patch"): Promise<void>;
   /**
-   * Applies default values for fields that are missing from the payload.
-   * Defaults handled natively by the DB engine are skipped — the field stays
-   * absent so the DB's own DEFAULT clause applies.
+   * Lazy pre-image read for a guard's `current(i)`: `null` when the row has
+   * no identifying key (e.g. an auto-increment insert) or the key cannot be
+   * resolved — never throws for a missing key.
+   * @internal
+   */
+  _readPreImage(row: unknown): Promise<DataType | null>;
+  /**
+   * Applies `@db.default` values in place to a row's absent fields — the
+   * defaults pass every insert / replace path runs before validation.
+   * Static value defaults (`@db.default 'x'`) are filled on EVERY adapter
+   * (since 0.1.128 — writing the column's own default explicitly is
+   * equivalent to leaving it to the DDL `DEFAULT`, and write guards see the
+   * full row). Function defaults (`now` / `uuid` / `increment` / custom) the
+   * adapter handles natively are NOT filled — the field stays absent so the
+   * engine's own default applies. The version column is never touched.
    */
   protected _applyDefaults(data: Record<string, unknown>): Record<string, unknown>;
+  /**
+   * The JS value for a `@db.default 'literal'`: strings (including unions of
+   * string literals) are used as-is, every other design type is parsed as
+   * JSON — the same value the SQL adapters put into the DDL `DEFAULT` clause.
+   * A literal that is not valid JSON falls back to the raw string so the
+   * validator reports it against the field instead of a bare `SyntaxError`.
+   */
+  private _parseValueDefault;
   /**
    * Extracts a record-identifying filter from a payload.
    *
@@ -235,7 +284,7 @@ interface TViewColumnMapping {
  * const users = await activeUsers.findMany({ filter: {}, controls: {} })
  * ```
  */
-declare class AtscriptDbView<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>> extends AtscriptDbReadable<T, DataType, FlatType, A, IdType, OwnProps, NavType> {
+declare class AtscriptDbView<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>> extends AtscriptDbReadable<T, DataType, FlatType, A, IdType, OwnProps, NavType> {
   private _viewPlan?;
   get isView(): boolean;
   /**
@@ -267,6 +316,16 @@ declare class AtscriptDbView<T extends TAtscriptAnnotatedType = TAtscriptAnnotat
    */
   getViewColumnMappings(): TViewColumnMapping[];
 }
+/**
+ * Structural type guard for views: `true` when the readable reports
+ * `isView`, whether or not it is an `AtscriptDbView` instance of THIS copy
+ * of `@atscript/db`. Adapters must use this (or `readable.isView`) instead of
+ * `instanceof AtscriptDbView` — in a bundle that carries two copies of the
+ * core (app bundle + external adapter), `instanceof` is false and the adapter
+ * would create an empty physical table under the view's name.
+ * @since 0.1.128
+ */
+declare function isAtscriptDbView(readable: AtscriptDbReadable<any, any, any, any, any, any, any>): readable is AtscriptDbView<any, any, any, any, any, any, any>;
 //#endregion
 //#region src/table/db-space.d.ts
 /**
@@ -343,6 +402,25 @@ declare class DbSpace {
    * Drops a view by name. Used by schema sync to remove views no longer in the schema.
    */
   dropViewByName(viewName: string): Promise<void>;
+  /**
+   * Drops a group of mutually referencing tables as one operation.
+   * Used by schema sync to remove a foreign-key cycle no longer in the schema.
+   * @since 0.1.128
+   */
+  dropTablesByName(tableNames: string[]): Promise<void>;
+  /**
+   * Live foreign keys referencing `tableName`, or `undefined` when the
+   * adapter cannot introspect them. Used by schema sync for drop ordering
+   * and surviving-reference checks of tables without a registered readable.
+   * @since 0.1.128
+   */
+  getReferencingForeignKeys(tableName: string): Promise<TReferencingForeignKey[] | undefined>;
+  /**
+   * A factory-fresh adapter with NO registered readable. Only the name-taking
+   * primitives may run on it (`dropTableByName`, `dropViewByName`,
+   * `dropTablesByName`, `getReferencingForeignKeys`) — adapters derive the
+   * schema for those from the driver/connection, not from a bound table.
+   */
   private _getAdminAdapter;
   /**
    * Finds all child tables with FKs pointing to the given parent table name.
@@ -356,4 +434,4 @@ declare class DbSpace {
   private _getFkLookupTarget;
 }
 //#endregion
-export { TViewColumnMapping as a, AtscriptQueryNode$1 as c, TViewPlan as d, translateQueryTree as f, NativeIntegrity as h, AtscriptDbView as i, AtscriptRef as l, IntegrityStrategy as m, TAdapterFactory as n, AtscriptQueryComparison as o, AtscriptDbTable as p, TDbSpaceOptions as r, AtscriptQueryFieldRef$1 as s, DbSpace as t, TViewJoin as u };
+export { TViewColumnMapping as a, AtscriptQueryFieldRef$1 as c, TViewJoin as d, TViewPlan as f, NativeIntegrity as g, IntegrityStrategy as h, AtscriptDbView as i, AtscriptQueryNode$1 as l, AtscriptDbTable as m, TAdapterFactory as n, isAtscriptDbView as o, translateQueryTree as p, TDbSpaceOptions as r, AtscriptQueryComparison as s, DbSpace as t, AtscriptRef as u };