@atscript/db 0.1.136 → 0.1.137

package/dist/{buckets-y4EzoX7D.d.mts → buckets-BFG2RYRW.d.mts}

@@ -1,5 +1,5 @@
 import { f as TFieldOps } from "./ops-AqhV7s9o.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 { AtscriptQueryComparison, AtscriptQueryFieldRef, AtscriptQueryFieldRef as AtscriptQueryFieldRef$1, AtscriptQueryNode, AtscriptQueryNode as AtscriptQueryNode$1, AtscriptRef, FlatOf, FlatOf as FlatOf$1, NavPropsOf, NavPropsOf as NavPropsOf$1, OwnPropsOf, OwnPropsOf as OwnPropsOf$1, PrimaryKeyOf, PrimaryKeyOf as PrimaryKeyOf$1, TAtscriptAnnotatedType, TAtscriptDataType, TAtscriptTypeObject, TMetadataMap, TSerializedAnnotatedType, TValidatorOptions, TValidatorPlugin, Validator } from "@atscript/typescript/utils";
 import { AggregateControls, AggregateExpr, AggregateExpr as AggregateExpr$1, AggregateFn, AggregateFn as AggregateFn$1, AggregateQuery, AggregateQuery as AggregateQuery$1, AggregateResult, BucketUnit, FieldOpsFor, FilterExpr, FilterExpr as FilterExpr$1, ResolvedBucket, TypedWithRelation, Uniquery, Uniquery as Uniquery$1, UniqueryControls, UniqueryControls as UniqueryControls$1, UniqueryInsights, WithRelation, WithRelation as WithRelation$1 } from "@uniqu/core";
 
 //#region src/query/uniqu-select.d.ts
@@ -130,6 +130,8 @@ declare abstract class FieldMappingStrategy {
   translateFilter(filter: FilterExpr, meta: TableMetadata): FilterExpr;
   abstract prepareForWrite(payload: Record<string, unknown>, meta: TableMetadata, adapter: BaseDbAdapter): Record<string, unknown>;
   abstract translatePatchKeys(update: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
+  /** `$inc` / `$mul` field-op keys to physical names ({@link physicalPath}). */
+  translateOpsKeys(ops: TFieldOps, meta: TableMetadata): TFieldOps;
   /**
    * Reverse-maps `@db.column` renames on a row read from storage.
    * Renames physical keys back to logical names in-place.
@@ -185,6 +187,7 @@ declare class DocumentFieldMapper extends FieldMappingStrategy {
   protected physicalPath(logical: string, meta: TableMetadata): string;
   protected renamesPaths(meta: TableMetadata): boolean;
   prepareForWrite(payload: Record<string, unknown>, meta: TableMetadata, adapter: BaseDbAdapter): Record<string, unknown>;
+  /** Patch keys (top-level or decomposed dotted) to document paths. */
   translatePatchKeys(update: Record<string, unknown>, meta: TableMetadata): Record<string, unknown>;
 }
 //#endregion
@@ -392,7 +395,7 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   get measures(): readonly string[];
   /** Sync method for structural changes: 'drop' (lossy), 'recreate' (lossless), or undefined (manual). */
   get syncMethod(): "drop" | "recreate" | undefined;
-  /** Logical → physical column name mapping from `@db.column`. */
+  /** Logical → physical column name mapping from `@db.column` (top-level only on document storage). */
   get columnMap(): ReadonlyMap<string, string>;
   /** Default values from `@db.default.*`. */
   get defaults(): ReadonlyMap<string, TDbDefaultValue>;
@@ -636,6 +639,566 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   }, thisTableName: string, alias?: string): TDbForeignKey | undefined;
 }
 //#endregion
+//#region src/strategies/integrity.d.ts
+/**
+ * Strategy for referential integrity enforcement.
+ * Two implementations: {@link NativeIntegrity} (DB handles FK constraints)
+ * and `ApplicationIntegrity` (generic layer validates + cascades).
+ */
+declare abstract class IntegrityStrategy {
+  abstract validateForeignKeys(items: Array<Record<string, unknown>>, meta: TableMetadata, fkLookupResolver: TFkLookupResolver | undefined, writeTableResolver: TWriteTableResolver | undefined, partial?: boolean, excludeTargetTable?: string): Promise<void>;
+  abstract cascadeBeforeDelete(filter: FilterExpr, tableName: string, meta: TableMetadata, cascadeResolver: TCascadeResolver, translateFilter: (f: FilterExpr) => FilterExpr, adapter: BaseDbAdapter): Promise<void>;
+  abstract needsCascade(cascadeResolver: TCascadeResolver | undefined): boolean;
+}
+/**
+ * Integrity strategy for adapters with native FK support (e.g. SQLite, MySQL).
+ * All operations are no-ops — the database engine enforces constraints.
+ */
+declare class NativeIntegrity extends IntegrityStrategy {
+  validateForeignKeys(): Promise<void>;
+  cascadeBeforeDelete(): Promise<void>;
+  needsCascade(): boolean;
+}
+//#endregion
+//#region src/table/db-table.d.ts
+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;
+  protected readonly validators: Map<string, Validator<T, DataType>>;
+  private _fromDepthMap?;
+  constructor(_type: T, adapter: A, logger?: TGenericLogger, _tableResolver?: TTableResolver, _writeTableResolver?: TWriteTableResolver);
+  /**
+   * Sets the cascade resolver for application-level cascade deletes.
+   * Called by DbSpace after table creation.
+   */
+  setCascadeResolver(resolver: TCascadeResolver): void;
+  /**
+   * Sets the FK lookup resolver for application-level FK validation.
+   * Called by DbSpace after table creation.
+   */
+  setFkLookupResolver(resolver: TFkLookupResolver): void;
+  /**
+   * Returns a cached validator for the given purpose.
+   * Built with adapter plugins from {@link BaseDbAdapter.getValidatorPlugins}.
+   *
+   * Standard purposes: `'insert'`, `'update'`, `'patch'`.
+   * Adapters may define additional purposes.
+   */
+  getValidator(purpose: string): Validator<T, DataType>;
+  /**
+   * Inserts a single record. Delegates to {@link insertMany} for unified
+   * nested creation support.
+   */
+  insertOne(payload: DbPatch<DataType>, opts?: TWriteOptions<DataType>): Promise<TDbInsertResult>;
+  /**
+   * Inserts multiple records with batch-optimized nested creation.
+   *
+   * Supports **nested creation**: if payloads include data for navigation
+   * fields (`@db.rel.to` / `@db.rel.from`), related records are created
+   * automatically in batches. TO dependencies are batch-created first
+   * (their PKs become our FKs), FROM dependents are batch-created after
+   * (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<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: DbRow<DataType>, opts?: TWriteOptions<DataType>): Promise<TDbUpdateResult>;
+  /**
+   * Replaces multiple records with deep nested relation support.
+   *
+   * Supports all relation types (TO, FROM, VIA). TO dependencies are
+   * 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<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: 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.
+   */
+  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.
+   *
+   * `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.
+   */
+  syncIndexes(): Promise<void>;
+  /**
+   * Ensures the table/collection exists in the database.
+   */
+  ensureTable(): Promise<void>;
+  /** Engine-agnostic guard for user-supplied mutation filters (updateMany/deleteMany/…). */
+  protected _guardMutationFilter(filter: FilterExpr): void;
+  /**
+   * Encrypts `@db.encrypted` field values in place on (already validated)
+   * write payloads — between validation and `prepareForWrite`, so adapters
+   * only ever see envelope strings.
+   *
+   * Parent objects along an encrypted path are shallow-cloned before
+   * mutation so caller-shared nested objects are never modified.
+   *
+   * In `patch` mode, operator objects (`$inc`, `$insert`, …) targeting an
+   * encrypted field are rejected with `ENC_FIELD_PATCH_OP` — ciphertext is
+   * opaque; only plain re-assignment (which re-encrypts) is allowed.
+   */
+  protected _encryptItems(items: Array<Record<string, unknown>>, mode: "write" | "patch"): Promise<void>;
+  /**
+   * 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.
+   *
+   * Resolution order:
+   * 1. Primary key field(s) — if all PK fields are present in the payload.
+   * 2. Single-field unique index — first `@db.index.unique` field found.
+   * 3. Compound unique index — first compound unique index whose fields are all present.
+   *
+   * Throws when no identifying fields can be found. With `isFieldVisible`
+   * (since 0.1.134), a unique index over a hidden field is skipped, as if it
+   * did not exist — see {@link identificationsVisibleTo}.
+   */
+  protected _extractRecordFilter(payload: Record<string, unknown>, opts?: TIdResolveOptions): FilterExpr;
+  private _prepareFilterValue;
+  /**
+   * Lazy — builds a `normalized-path → from-depth` map from `this._meta.flatMap`
+   * on first use. Only paths reachable through an unbroken chain of `db.rel.from`
+   * nav fields from the root are included (chains crossing `to`/`via` are excluded).
+   */
+  private _getFromDepthMap;
+  /**
+   * Populate the depth-limit bundle on a `DbValidationContext`. Only the root
+   * write call (`depth === 0`) enforces — nested re-entries leave `depthCheck`
+   * unset so the full tree is validated once at the root.
+   */
+  private _applyDepthCtx;
+  /**
+   * Pre-validate items (type validation + FK constraints) without inserting them.
+   * Used by parent tables to validate FROM children before the main insert,
+   * ensuring errors are caught before the parent is committed.
+   *
+   * @param opts.excludeFkTargetTable - Skip FK validation to this table (the parent).
+   */
+  preValidateItems(items: Array<Record<string, unknown>>, opts?: {
+    excludeFkTargetTable?: string;
+  }): Promise<void>;
+  /**
+   * Builds a validator for a given purpose with adapter plugins.
+   *
+   * Uses annotation-based `replace` callback to make `@meta.id` and
+   * `@db.default` fields optional — works at all nesting levels
+   * (including inside nav field target types).
+   */
+  protected _buildValidator(purpose: string): Validator<T, DataType>;
+}
+//#endregion
+//#region src/query/query-tree.d.ts
+/**
+ * `true` when a query-tree operand is a field reference (`{ field, type? }`)
+ * rather than a literal — e.g. the right side of a field-to-field comparison.
+ * @since 0.1.136
+ */
+declare function isFieldRef(value: unknown): value is AtscriptQueryFieldRef;
+/** A single join in a view query plan. */
+interface TViewJoin {
+  targetType: () => TAtscriptAnnotatedType;
+  targetTable: string;
+  condition: AtscriptQueryNode;
+  /**
+   * `inner` (default) drops entry rows without a match; `left` keeps them
+   * with the target's columns as NULL. Joins apply in declaration order.
+   * @since 0.1.136
+   */
+  kind: "inner" | "left";
+}
+/** Resolved view query plan produced by AtscriptDbView. */
+interface TViewPlan {
+  entryType: () => TAtscriptAnnotatedType;
+  entryTable: string;
+  joins: TViewJoin[];
+  filter?: AtscriptQueryNode;
+  having?: AtscriptQueryNode;
+  materialized: boolean;
+}
+/**
+ * Translates a JS-emitted query tree into a FilterExpr.
+ * Resolves field references (type + field path) to physical column names
+ * via the provided resolver function.
+ */
+declare function translateQueryTree(node: AtscriptQueryNode, resolveField: (ref: AtscriptQueryFieldRef) => string): FilterExpr;
+//#endregion
+//#region src/table/view-source.d.ts
+/**
+ * Where a view reads one logical source path from, in PHYSICAL terms.
+ *
+ * Produced by {@link resolveViewSource} — a pure function of the source
+ * table's annotated type that lays the table out with `TableMetadata`'s
+ * rules (flattened `__` columns, `@db.column` renames, `@db.json` / array
+ * JSON columns, document paths on nested-object adapters).
+ * @since 0.1.136
+ */
+interface TViewSource {
+  /**
+   * Physical column (relational) or document path (nested-object adapters).
+   * For a path inside a JSON column this is the JSON column; for a flattened
+   * object it is the object's `__` prefix (no such column exists — its leaves do).
+   */
+  column: string;
+  /** Segments inside {@link column} when the path descends into a JSON column (relational only). */
+  jsonPath?: string[];
+  /** Design type of the addressed node (`string`, `number`, `object`, `array`, …; `unknown` when undeclared). */
+  designType: string;
+  /** Set for a relational object stored as one column per leaf. */
+  flattened?: true;
+  /**
+   * `true` when the value may be absent: the path or an ancestor segment is
+   * optional, or it reads inside a JSON-stored value.
+   */
+  optional: boolean;
+}
+//#endregion
+//#region src/table/db-view.d.ts
+/** Primitive result type of a JSON-leaf extraction. */
+type TViewJsonType = "string" | "number" | "boolean";
+interface TViewColumnMapping {
+  /**
+   * The view's own physical column — its `@db.column` / flattened `__` name
+   * on relational adapters, its document key on nested-object adapters.
+   */
+  viewColumn: string;
+  /**
+   * Logical view field path (`address.city` for a flattened object leaf) —
+   * how `@db.view.having` refers to the column.
+   * @since 0.1.136
+   */
+  viewPath: string;
+  sourceTable: string;
+  /** Physical source column (or document path). `"*"` for `COUNT(*)`. */
+  sourceColumn: string;
+  /**
+   * Set when the source value may be missing for some row: an optional
+   * source field, a leaf inside a JSON-stored value, an undeclared path, or a
+   * column of a left-joined table. Document adapters coalesce such a source
+   * to `null`; a required source is read as a plain path (index-friendly).
+   * @since 0.1.136
+   */
+  nullable?: true;
+  /**
+   * Set when the source is a primitive leaf inside a JSON column
+   * ({@link sourceColumn}): the path within it and the leaf's declared type.
+   * @since 0.1.136
+   */
+  json?: {
+    path: string[];
+    type: TViewJsonType;
+  };
+  /**
+   * Aggregate function name (`sum` | `avg` | `count` | `countDistinct` |
+   * `min` | `max`) if this is an aggregate column.
+   */
+  aggFn?: string;
+  /** Source field for the aggregate function ('*' for COUNT(*)). */
+  aggField?: string;
+  /**
+   * Row predicate of a conditional aggregate — the `@db.agg.*` 2nd argument:
+   * only rows where it holds are aggregated. Refs resolve like
+   * `@db.view.filter` (entry table + joins). @since 0.1.136
+   */
+  aggFilter?: AtscriptQueryNode;
+}
+/**
+ * Database view abstraction driven by Atscript `@db.view.*` annotations.
+ *
+ * Extends {@link AtscriptDbReadable} with view plan resolution — entry table,
+ * joins, filter, and materialization flag. Read operations are inherited;
+ * write operations are not available on views.
+ *
+ * ```typescript
+ * const adapter = new SqliteAdapter(db)
+ * const activeUsers = new AtscriptDbView(ActiveUsersType, adapter)
+ * const users = await activeUsers.findMany({ filter: {}, controls: {} })
+ * ```
+ */
+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?;
+  private _columnMappings?;
+  get isView(): boolean;
+  /**
+   * Whether this is an external view — declared with `@db.view` only,
+   * without `@db.view.for`. External views reference pre-existing DB views
+   * and are not managed (created/dropped) by schema sync.
+   */
+  get isExternal(): boolean;
+  /**
+   * Lazily resolves the view plan from `@db.view.*` metadata.
+   *
+   * - `db.view.for` → entry type ref (required)
+   * - `db.view.joins` → array of `{ target, condition }` (optional, multiple)
+   * - `db.view.filter` → query tree (optional)
+   * - `db.view.materialized` → boolean (optional)
+   */
+  get viewPlan(): TViewPlan;
+  /** Whether the adapter stores nested objects natively (document paths, no JSON columns). */
+  private get _nested();
+  /**
+   * Resolves a view query field ref (join condition, `@db.view.filter`,
+   * conditional-aggregate predicate) to its table name and PHYSICAL source on
+   * this view's adapter — the column (or document path) with `TableMetadata`'s
+   * layout rules, the path inside a JSON column, and whether the value may be
+   * absent. An unqualified ref resolves against the entry table.
+   * @throws for a ref without storage (`@db.ignore`, navigation relation) or
+   *   inside an `@db.encrypted` field (relational adapters).
+   * @since 0.1.136
+   */
+  resolveRefSource(ref: AtscriptQueryFieldRef): {
+    table: string;
+    source: TViewSource;
+  };
+  /**
+   * Resolves a query field ref (join condition, `@db.view.filter`) to a
+   * quoted `table.column` SQL fragment — the PHYSICAL column (flattened
+   * `__` name, `@db.column` rename). An unqualified ref
+   * resolves against the entry table.
+   *
+   * @param ref - The field reference from the query tree.
+   * @param qi - Identifier quoting function (e.g. backtick for MySQL, double-quote for SQLite).
+   *             Defaults to double-quote wrapping for backwards compatibility.
+   * @throws when the ref reads inside a JSON column (not supported in view conditions).
+   */
+  resolveFieldRef(ref: AtscriptQueryFieldRef, qi?: (name: string) => string): string;
+  /**
+   * Maps each view column to its source table and PHYSICAL source column.
+   *
+   * View fields resolve through their chain ref; fields without a ref read
+   * the entry table under the same name; aggregates read their `@db.agg.*`
+   * field from the entry table (or their ref). Source names are
+   * physical (flattened `__` names, `@db.column`, document paths), `viewColumn`
+   * is the view's own physical name, an object field whose source is a
+   * flattened object expands to one mapping per leaf, and a primitive leaf
+   * inside a JSON column carries `json` (rendered by adapters that support
+   * JSON extraction).
+   *
+   * Computed once per view (the plan and the type are immutable).
+   *
+   * @throws for an object field over a JSON column without `@db.json` on the
+   *   view field, a JSON leaf that is not a string / number / boolean, or an
+   *   aggregate other than `count` over `'*'`.
+   */
+  getViewColumnMappings(): TViewColumnMapping[];
+  private _buildColumnMappings;
+  /** One view column over one physical source (a column or a JSON leaf). */
+  private _leafMapping;
+}
+/**
+ * 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
+/**
+ * Adapter factory function. Called once per table/view to create a fresh adapter instance.
+ * Each readable gets its own adapter (1:1 relationship required by BaseDbAdapter).
+ */
+type TAdapterFactory = () => BaseDbAdapter;
+/** Options bag for {@link DbSpace} (second constructor argument). */
+interface TDbSpaceOptions {
+  /** Logger shared by all tables/views in the space. */
+  logger?: TGenericLogger;
+  /** Field-level encryption configuration for `@db.encrypted` fields. */
+  encryption?: TDbEncryptionOptions;
+}
+/**
+ * A database space — a registry of tables and views sharing the same adapter type and driver.
+ *
+ * `DbSpace` solves the cross-table discovery problem: when table A has a relation
+ * to table B, it needs to find and query table B. The space acts as the registry
+ * that makes this possible via the table resolver callback.
+ *
+ * Each table/view gets its own adapter instance (created by the factory), but all
+ * share the same space and can discover each other for `$with` relation loading.
+ *
+ * ```typescript
+ * // SQLite
+ * const driver = new BetterSqlite3Driver(':memory:')
+ * const db = new DbSpace(() => new SqliteAdapter(driver))
+ * const users = db.getTable(UsersType)
+ * const activeUsers = db.getView(ActiveUsersType)
+ * ```
+ */
+declare class DbSpace {
+  protected readonly adapterFactory: TAdapterFactory;
+  private _readables;
+  /** All tables created in this space — used for reverse FK lookup during cascade. */
+  private _allTables;
+  /** Lazily created adapter for administrative ops (drop table/view) that don't need a registered readable. */
+  private _adminAdapter?;
+  protected readonly logger: TGenericLogger;
+  /** Encryption service for `@db.encrypted` fields — validated eagerly at construction. */
+  protected readonly _encryption?: DbEncryption;
+  /**
+   * @param adapterFactory - Creates a fresh adapter per table/view.
+   * @param loggerOrOptions - Either a logger (legacy signature) or a
+   *   {@link TDbSpaceOptions} bag carrying `logger` and/or `encryption`.
+   */
+  constructor(adapterFactory: TAdapterFactory, loggerOrOptions?: TGenericLogger | TDbSpaceOptions);
+  /**
+   * Auto-detects whether the type is a table or view and returns the
+   * appropriate instance. Uses `@db.view` or `@db.view.for` presence to distinguish.
+   */
+  get<T extends TAtscriptAnnotatedType>(type: T, logger?: TGenericLogger): AtscriptDbReadable<T>;
+  /**
+   * Returns the table for the given annotated type.
+   * Creates the table + adapter on first access, caches for subsequent calls.
+   */
+  getTable<T extends TAtscriptAnnotatedType>(type: T, logger?: TGenericLogger): AtscriptDbTable<T>;
+  /**
+   * Returns the view for the given annotated type.
+   * Creates the view + adapter on first access, caches for subsequent calls.
+   */
+  getView<T extends TAtscriptAnnotatedType>(type: T, logger?: TGenericLogger): AtscriptDbView<T>;
+  /**
+   * Returns the adapter for the given annotated type.
+   * Creates the table/view + adapter on first access if needed.
+   */
+  getAdapter(type: TAtscriptAnnotatedType): BaseDbAdapter;
+  /**
+   * Drops a table by name. Used by schema sync to remove tables no longer in the schema.
+   * See `BaseDbAdapter.dropTableByName` for an adapter that does not support it.
+   */
+  dropTableByName(tableName: string): Promise<void>;
+  /**
+   * Drops a view by name. Used by schema sync to remove views no longer in the schema.
+   * See `BaseDbAdapter.dropViewByName` for an adapter that does not support it.
+   */
+  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;
+  /**
+   * A factory-fresh adapter that knows its space (see `BaseDbAdapter.registerSpace`).
+   * Optional call: an adapter built against an older `@atscript/db` copy lacks it.
+   */
+  private _createAdapter;
+  /**
+   * Finds all child tables with FKs pointing to the given parent table name.
+   * Accesses `table.foreignKeys` which triggers `_flatten()` if needed.
+   */
+  private _getCascadeTargets;
+  /**
+   * Resolves a table name to a queryable target for FK validation.
+   * Searches all registered tables for one with the matching table name.
+   */
+  private _getFkLookupTarget;
+}
+//#endregion
 //#region src/base-adapter.d.ts
 /** Every calendar-bucket unit — what an adapter that renders them all returns from `calendarBucketUnits()`. */
 declare const ALL_BUCKET_UNITS: ReadonlySet<BucketUnit>;
@@ -688,6 +1251,15 @@ declare abstract class BaseDbAdapter {
    * index sync, etc.
    */
   registerReadable(readable: AtscriptDbReadable<any, any, any, any, any, any, any>, logger?: TGenericLogger): void;
+  /**
+   * Called by {@link DbSpace} right after its factory builds this adapter —
+   * the administrative one included — before {@link registerReadable}. No-op
+   * by default: override it to share state across a space's adapters when the
+   * adapter has no driver to share it through (the memory adapter keeps one
+   * store per space).
+   * @since 0.1.137
+   */
+  registerSpace(_space: DbSpace): void;
   /**
    * Enables or disables verbose (debug-level) logging for this adapter.
    * When disabled, no log strings are constructed — zero overhead.
@@ -818,6 +1390,17 @@ declare abstract class BaseDbAdapter {
    * @since 0.1.136
    */
   aggregateFns(): ReadonlySet<AggregateFn>;
+  /**
+   * Revision of how this adapter renders a managed view (its SQL / pipeline)
+   * from an unchanged view definition. Stored in each managed view's sync
+   * snapshot when defined, so bumping it recreates every managed view of the
+   * adapter once on the next sync — return a new value whenever a rendering
+   * fix changes what an existing view returns. `undefined` (the default)
+   * leaves the snapshot, and its hash, as before. External views ignore it.
+   *
+   * @since 0.1.137
+   */
+  viewRenderRevision(): string | undefined;
   /**
    * Whether this adapter enforces foreign key constraints natively.
    * When `true`, the generic layer skips application-level cascade/setNull
@@ -1231,16 +1814,20 @@ declare abstract class BaseDbAdapter {
   dropIndexesForColumns?(columns: string[]): Promise<void>;
   /**
    * Drops a table by name (without needing a registered readable).
-   * Used by schema sync to remove tables no longer in the schema.
-   * Optional — only relational adapters implement this.
+   * Used by schema sync to remove tables no longer in the schema. A missing
+   * table is not an error (`DROP TABLE IF EXISTS`). The default throws —
+   * schema sync then reports the removed table as an `error` entry and keeps
+   * it tracked. Since 0.1.137; before, the method was optional and a drop the
+   * adapter lacked was skipped silently while sync reported it done.
    */
-  dropTableByName?(tableName: string): Promise<void>;
+  dropTableByName(tableName: string): Promise<void>;
   /**
    * Drops a view by name (without needing a registered readable).
-   * Used by schema sync to remove views no longer in the schema.
-   * Optional — only relational adapters implement this.
+   * Used by schema sync to remove views no longer in the schema, and to drop
+   * a managed view before recreating it. A missing view is not an error. The
+   * default throws, with the same history as {@link dropTableByName}.
    */
-  dropViewByName?(viewName: string): Promise<void>;
+  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
@@ -1378,6 +1965,7 @@ declare class TableMetadata {
   ignoredFields: Set<string>;
   uniqueProps: Set<string>;
   defaults: Map<string, TDbDefaultValue>;
+  /** Logical path → `@db.column` override (top-level keys only on document storage). */
   columnMap: Map<string, string>;
   dimensions: string[];
   measures: string[];
@@ -1439,14 +2027,14 @@ declare class TableMetadata {
   private _columnFromMap;
   constructor(nestedObjects: boolean);
   get isBuilt(): boolean;
+  /** {@link documentPath} over this table's `columnMap`. */
+  documentPath(path: string): string;
   /**
-   * Logical field path → its physical path in document storage (nested
-   * objects kept inline). `@db.column` renames apply to the annotated key,
-   * and a document renames the TOP-LEVEL key only — nested keys are stored
-   * as-is — so a dotted path under a renamed top-level object renames its
-   * first segment: `profile.bio` under `@db.column 'prof'` → `prof.bio`.
+   * Physical name of a logical path: the document path on nested-object
+   * adapters, else the relational column (`pathToPhysical`, then the
+   * `@db.column` override).
    */
-  documentPath(path: string): string;
+  physicalPath(logical: string): string;
   /**
    * Runs the full metadata compilation pipeline. Called once by
    * `AtscriptDbReadable._ensureBuilt()` on first metadata access.
@@ -2318,4 +2906,4 @@ declare function isJsonValueField(fd: TDbFieldMeta): boolean;
  */
 declare function jsonValueAncestor(path: string, jsonValueParents: ReadonlySet<string>): string | undefined;
 //#endregion
-export { TDbWriteGuard as $, TDbActionInfo as A, findAncestorInSet as At, TDbIndex as B, DocumentFieldMapper as Bt, OwnPropsOf$1 as C, TWriteOptions as Ct, TColumnDiff as D, UniqueryControls$1 as Dt, TCascadeTarget as E, Uniquery$1 as Et, TDbDefaultFn as F, AtscriptDbReadable as Ft, TDbObjectKind as G, TDbIndexType as H, NoopLogger as Ht, TDbDefaultValue as I, DbResponse as It, TDbRemoveGuard as J, TDbReferentialAction as K, TDbDeleteResult as L, resolveDesignType as Lt, TDbActionLevel as M, isGeoPointType as Mt, TDbActionProcessor as N, ALL_BUCKET_UNITS as Nt, TCrudOp as O, WithRelation$1 as Ot, TDbCollation as P, BaseDbAdapter as Pt, TDbWriteAction as Q, TDbFieldMeta as R, DbEncryption as Rt, NullableOptional as S, TValueFormatterPair as St, TCascadeResolver as T, TypedWithRelation as Tt, TDbInsertManyResult as U, TGenericLogger as Ut, TDbIndexField as V, FieldMappingStrategy as Vt, TDbInsertResult as W, UniquSelect as Wt, TDbStorageType as X, TDbRemoveGuardContext as Y, TDbUpdateResult as Z, DbRow as _, TSearchIndexInfo as _t, jsonValueAncestor as a, TExistingTableOption as at, FlatOf$1 as b, TTableResolver as bt, AggregateControls as c, TFkLookupTarget as ct, AggregateQuery$1 as d, TIdentification as dt, TDbWriteGuardContext as et, AggregateResult as f, TMetaResponse as ft, DbQuery as g, TRelationInfo as gt, DbPatch as h, TReferencingForeignKey as ht, isJsonValueField as i, TExistingForeignKey as it, TDbActionIntent as j, isGeoIndexableType as jt, TCrudPermissions as k, TableMetadata as kt, AggregateExpr$1 as l, TIdDescriptor as lt, DbControls as m, TPrimaryKeyChange as mt, TResolvedBucket as n, TEnsureTableOptions as nt, normalizeComputedSelect as o, TFieldMeta as ot, AtscriptDbWritable as p, TMetadataOverrides as pt, TDbRelation as q, isBucketableField as r, TExistingColumn as rt, resolveCalendarBuckets as s, TFkLookupResolver as st, TBucketFieldSource as t, TDeleteOptions as tt, AggregateFn$1 as u, TIdResolveOptions as ut, FieldOpsFor as v, TSyncColumnResult as vt, PrimaryKeyOf$1 as w, TWriteTableResolver as wt, NavPropsOf$1 as x, TTouchManyOptions as xt, FilterExpr$1 as y, TTableOptionDiff as yt, TDbForeignKey as z, TDbEncryptionOptions as zt };
+export { TDbWriteGuard as $, AtscriptDbReadable as $t, TDbActionInfo as A, findAncestorInSet as At, TDbIndex as B, TViewJsonType as Bt, OwnPropsOf$1 as C, TWriteOptions as Ct, TColumnDiff as D, UniqueryControls$1 as Dt, TCascadeTarget as E, Uniquery$1 as Et, TDbDefaultFn as F, DbSpace as Ft, TDbObjectKind as G, AtscriptRef as Gt, TDbIndexType as H, AtscriptQueryComparison as Ht, TDbDefaultValue as I, TAdapterFactory as It, TDbRemoveGuard as J, isFieldRef as Jt, TDbReferentialAction as K, TViewJoin as Kt, TDbDeleteResult as L, TDbSpaceOptions as Lt, TDbActionLevel as M, isGeoPointType as Mt, TDbActionProcessor as N, ALL_BUCKET_UNITS as Nt, TCrudOp as O, WithRelation$1 as Ot, TDbCollation as P, BaseDbAdapter as Pt, TDbWriteAction as Q, NativeIntegrity as Qt, TDbFieldMeta as R, AtscriptDbView as Rt, NullableOptional as S, TValueFormatterPair as St, TCascadeResolver as T, TypedWithRelation as Tt, TDbInsertManyResult as U, AtscriptQueryFieldRef$1 as Ut, TDbIndexField as V, isAtscriptDbView as Vt, TDbInsertResult as W, AtscriptQueryNode$1 as Wt, TDbStorageType as X, AtscriptDbTable as Xt, TDbRemoveGuardContext as Y, translateQueryTree as Yt, TDbUpdateResult as Z, IntegrityStrategy as Zt, DbRow as _, TSearchIndexInfo as _t, jsonValueAncestor as a, FieldMappingStrategy as an, TExistingTableOption as at, FlatOf$1 as b, TTableResolver as bt, AggregateControls as c, UniquSelect as cn, TFkLookupTarget as ct, AggregateQuery$1 as d, TIdentification as dt, DbResponse as en, TDbWriteGuardContext as et, AggregateResult as f, TMetaResponse as ft, DbQuery as g, TRelationInfo as gt, DbPatch as h, TReferencingForeignKey as ht, isJsonValueField as i, DocumentFieldMapper as in, TExistingForeignKey as it, TDbActionIntent as j, isGeoIndexableType as jt, TCrudPermissions as k, TableMetadata as kt, AggregateExpr$1 as l, TIdDescriptor as lt, DbControls as m, TPrimaryKeyChange as mt, TResolvedBucket as n, DbEncryption as nn, TEnsureTableOptions as nt, normalizeComputedSelect as o, NoopLogger as on, TFieldMeta as ot, AtscriptDbWritable as p, TMetadataOverrides as pt, TDbRelation as q, TViewPlan as qt, isBucketableField as r, TDbEncryptionOptions as rn, TExistingColumn as rt, resolveCalendarBuckets as s, TGenericLogger as sn, TFkLookupResolver as st, TBucketFieldSource as t, resolveDesignType as tn, TDeleteOptions as tt, AggregateFn$1 as u, TIdResolveOptions as ut, FieldOpsFor as v, TSyncColumnResult as vt, PrimaryKeyOf$1 as w, TWriteTableResolver as wt, NavPropsOf$1 as x, TTouchManyOptions as xt, FilterExpr$1 as y, TTableOptionDiff as yt, TDbForeignKey as z, TViewColumnMapping as zt };