@atscript/db 0.1.127 → 0.1.128

package/dist/{db-readable-C0nDKX8A.d.cts → db-readable-CkbZn_z-.d.cts}

@@ -1,4 +1,4 @@
-import { f as TFieldOps } from "./ops-DJRnNTVo.cjs";
+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";
 
@@ -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,93 @@ 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 `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 +885,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 +922,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 +932,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 +951,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 +993,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 +1037,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 +1163,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 +1300,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 +1344,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 +1426,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 +1695,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 +2006,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, isGeoIndexableType as At, TDbForeignKey as B, NullableOptional as C, TWriteTableResolver as Ct, TCascadeTarget as D, WithRelation$1 as Dt, TCascadeResolver as E, UniqueryControls$1 as Et, TDbCollation as F, TDbInsertResult as G, TDbIndexField as H, TDbDefaultFn as I, TDbRelation as J, TDbObjectKind as K, TDbDefaultValue as L, TDbActionIntent as M, NoopLogger as Mt, TDbActionLevel as N, TGenericLogger as Nt, TColumnDiff as O, TableMetadata as Ot, TDbActionProcessor as P, UniquSelect as Pt, TDbUpdateResult as Q, TDbDeleteResult as R, NavPropsOf$1 as S, TWriteOptions as St, PrimaryKeyOf$1 as T, Uniquery$1 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, isGeoPointType as jt, TCrudOp as k, findAncestorInSet 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, TypedWithRelation as wt, FlatOf$1 as x, TValueFormatterPair as xt, FieldOpsFor as y, TTableOptionDiff as yt, TDbFieldMeta as z };

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

@@ -1,4 +1,4 @@
-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 { C as NullableOptional, Ct as TWriteTableResolver, E as TCascadeResolver, G as TDbInsertResult, Nt as TGenericLogger, Ot as TableMetadata, Q as TDbUpdateResult, R as TDbDeleteResult, St as TWriteOptions, W as TDbInsertManyResult, a as TDbEncryptionOptions, bt as TTableResolver, c as BaseDbAdapter, ct as TFkLookupResolver, g as DbPatch, ht as TReferencingForeignKey, i as DbEncryption, nt as TDeleteOptions, t as AtscriptDbReadable, v as DbRow } from "./db-readable-BTl4NzNN.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";
 
@@ -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,43 @@ 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<Partial<DataType> & Record<string, unknown>>, opts?: {
-    maxDepth?: number;
-  }): Promise<TDbUpdateResult>;
+  bulkUpdate(payloads: Array<DbPatch<DataType>>, opts?: TWriteOptions<DataType>): 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 +143,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 +258,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 +290,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 +376,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 +408,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 };