@atscript/db 0.1.142 → 0.1.144

package/dist/agg.d.cts

@@ -1,3 +1,3 @@
-import { n as TResolvedBucket } from "./buckets-Bv4pah66.cjs";
+import { n as TResolvedBucket } from "./buckets-Ba5lP_o9.cjs";
 import { _ as TDbAggregateFn, a as AggregateResult, c as CalendarBucketLabel, d as WeekStart, f as isAggregateExpr, h as resolveAlias, i as AggregateQuery, l as ComputedExpr, m as resolveAggregateSearch, n as AggregateExpr, o as BucketExpr, p as isBucketExpr, r as AggregateFn, s as BucketUnit, t as AggregateControls, u as ResolvedBucket, v as assertAggregateFn } from "./agg-CV7y8nC6.cjs";
 export { type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, type BucketExpr, type BucketUnit, type CalendarBucketLabel, type ComputedExpr, type ResolvedBucket, type TDbAggregateFn, type TResolvedBucket, type WeekStart, assertAggregateFn, isAggregateExpr, isBucketExpr, resolveAggregateSearch, resolveAlias };

package/dist/agg.d.mts

@@ -1,3 +1,3 @@
-import { n as TResolvedBucket } from "./buckets-CjL7F-hp.mjs";
+import { n as TResolvedBucket } from "./buckets-BlJ4cdlr.mjs";
 import { _ as TDbAggregateFn, a as AggregateResult, c as CalendarBucketLabel, d as WeekStart, f as isAggregateExpr, h as resolveAlias, i as AggregateQuery, l as ComputedExpr, m as resolveAggregateSearch, n as AggregateExpr, o as BucketExpr, p as isBucketExpr, r as AggregateFn, s as BucketUnit, t as AggregateControls, u as ResolvedBucket, v as assertAggregateFn } from "./agg-D5DHsAby.mjs";
 export { type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, type BucketExpr, type BucketUnit, type CalendarBucketLabel, type ComputedExpr, type ResolvedBucket, type TDbAggregateFn, type TResolvedBucket, type WeekStart, assertAggregateFn, isAggregateExpr, isBucketExpr, resolveAggregateSearch, resolveAlias };

package/dist/{buckets-Bv4pah66.d.cts → buckets-Ba5lP_o9.d.cts}

@@ -465,6 +465,27 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   get foreignKeys(): ReadonlyMap<string, TDbForeignKey>;
   /** Navigational relation metadata from `@db.rel.to` / `@db.rel.from`. */
   get relations(): ReadonlyMap<string, TDbRelation>;
+  /**
+   * The `@db.rel.FK` entry a `@db.rel.to` relation is backed by — paired
+   * exactly like relation loading and nested writes pair them: by the
+   * relation's alias when it has one, else by the target table. `undefined`
+   * for an unknown name, a `@db.rel.from` / `@db.rel.via` relation (their key
+   * lives on the other table) or a TO relation without a matching FK.
+   *
+   * @since 0.1.143
+   */
+  foreignKeyOf(relationName: string): TDbForeignKey | undefined;
+  /**
+   * Logical paths stored as ONE JSON column (`storage: "json"` — `@db.json`
+   * fields and nested objects / arrays a relational adapter serializes): the
+   * engine cannot address a sub-path of such a column in a projection,
+   * filter or sort, so a permission layer treats it atomically (visible whole
+   * or not at all). Navigation fields excluded; empty on document adapters
+   * (they store nested values natively).
+   *
+   * @since 0.1.143
+   */
+  get jsonParents(): ReadonlySet<string>;
   /** The underlying database adapter instance. */
   get dbAdapter(): A;
   /**
@@ -484,6 +505,28 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
    * of them. Every read path funnels through here.
    */
   private _fromRead;
+  /**
+   * Translates a read query for the adapter. A `$select` that leaves out a
+   * key a `$with` relation joins on — a TO relation's foreign key, the key a
+   * FROM / VIA relation is looked up by — is widened with it for the read
+   * (since 0.1.143), and {@link _finishRead} strips it again once the
+   * relations are loaded: the joined object never reads `null` just because
+   * its key was not selected.
+   */
+  private _translateRead;
+  /** Reconstructs + decrypts a read's rows, loads its `$with` relations and strips widened keys. */
+  private _finishRead;
+  /** `$select` plus the join keys of `withRelations` it leaves out — `undefined` when none is missing. */
+  private _widenSelectForWith;
+  private _joinKeysCache?;
+  /**
+   * The keys of THIS table a `$with` relation joins on: a TO relation's
+   * foreign-key fields; the fields a FROM relation's (or a VIA junction's)
+   * foreign key references — typically the primary key. An adapter that
+   * loads relations natively re-reads the rows by primary key, so it is
+   * always included there. Empty for an unknown or nested (`a.b`) name.
+   */
+  private _joinKeysOf;
   /**
    * Pre-computed field metadata for adapter use.
    */
@@ -656,6 +699,10 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
    * or single-field unique index.
    * The return type excludes nav props unless `$with` is provided in controls.
    *
+   * The id addresses exactly ONE row, primary key first (since 0.1.143) —
+   * see {@link resolveRowFilter}: when a scalar id equals one row's primary
+   * key and another row's unique key, the primary-key row is returned.
+   *
    * ```typescript
    * // Without relations — nav props stripped from result
    * const user = await table.findById('123')
@@ -667,25 +714,100 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   findById<Q extends {
     controls?: UniqueryControls<OwnProps, NavType>;
   } = Record<string, never>>(id: IdType, query?: Q): Promise<DbResponse<DataType, NavType, Q> | null>;
+  /**
+   * Reads the ONE row an id addresses — resolved exactly like
+   * {@link resolveRowFilter} (primary key first, `opts.scope` /
+   * `opts.isFieldVisible` as there) — with `opts.controls` applied, in one
+   * step: the identifications are probed in order with the caller's
+   * controls and the first row found wins, so no pin-then-reread. The row
+   * must also match `opts.scope` (an out-of-scope row answers `null` like a
+   * missing one).
+   *
+   * @since 0.1.143
+   */
+  findOneByRow<Q extends {
+    controls?: UniqueryControls<OwnProps, NavType>;
+  } = Record<string, never>>(id: unknown, opts?: TRowResolveOptions & Q): Promise<DbResponse<DataType, NavType, Q> | null>;
   /**
    * Resolve an id value (scalar or object) into a {@link FilterExpr} using the
-   * same identification resolution as {@link findById}. Public so callers can
+   * same identifications as {@link findById}. Public so callers can
    * AND-combine the id-filter with a row-level read overlay before issuing
    * `findOne` (avoiding the existence leak that `findById` would cause).
    * `opts.isFieldVisible` (since 0.1.134) drops unique indexes over hidden
    * fields — see {@link identificationsVisibleTo}.
+   *
+   * The result is a plain `$or` over every identification the id is
+   * type-compatible with (a scalar can equal one row's primary key AND
+   * another row's unique key), so it may match more than one row. Code that
+   * must address exactly one row — writes, pre-images, `/one` reads — uses
+   * {@link resolveRowFilter} instead.
    */
   resolveIdFilter(id: unknown, opts?: TIdResolveOptions): FilterExpr | null;
   /**
-   * Resolve an id value into a filter expression.
+   * Resolve an id value (scalar or object) into a filter that matches exactly
+   * ONE row, deterministically and primary key first (since 0.1.143):
+   *
+   * - an id that yields a single identification (e.g. a numeric PK with no
+   *   type-compatible unique key) resolves to it without a read;
+   * - an object id carrying the complete primary key resolves by the primary
+   *   key alone — exactly like a write payload is identified;
+   * - otherwise the identifications are tried in order (primary key first,
+   *   then each unique index): the first one that matches a row wins and the
+   *   result is that row's exact primary-key filter;
+   * - when none matches, the first identification is returned (it matches
+   *   nothing, so callers answer "not found" as usual).
+   *
+   * `null` when the id resolves to no identification at all. Every write
+   * (`deleteOne`, the guards' `current()`) and `findById` go through this
+   * resolution; call it inside the write's transaction when the answer must
+   * stay pinned. `opts.isFieldVisible` as in {@link resolveIdFilter}.
+   *
+   * `opts.scope` (a row-level overlay) restricts which rows count as matches
+   * while the identifications are tried — a row outside it never shadows one
+   * inside it, so the answer is the same as if that row did not exist. AND
+   * the scope onto the result to exclude an out-of-scope row the id names
+   * unambiguously. See {@link TRowResolveOptions}.
+   */
+  resolveRowFilter(id: unknown, opts?: TRowResolveOptions): Promise<FilterExpr | null>;
+  /**
+   * Resolve an id value into a filter expression (the `$or` of
+   * {@link _idCandidates}; a single candidate is returned as-is).
+   */
+  protected _resolveIdFilter(id: unknown, opts?: TIdResolveOptions): FilterExpr | null;
+  /**
+   * The ordered identification filters an id value can resolve through —
+   * primary key first, then each unique index.
    *
    * When `preferredId` differs from the PK, scalar ids resolve only against
    * the preferred field (deterministic addressing). Otherwise scalars try PK
    * + every single-field unique index; objects try PK + compound unique
    * indexes. With `opts.isFieldVisible`, only the identifications
-   * {@link identificationsVisibleTo} keeps are tried.
+   * {@link identificationsVisibleTo} keeps are tried. With `pkWins` (the
+   * default), an object id carrying the complete primary key yields the
+   * primary-key filter alone.
    */
-  protected _resolveIdFilter(id: unknown, opts?: TIdResolveOptions): FilterExpr | null;
+  protected _idCandidates(id: unknown, opts?: TIdResolveOptions, pkWins?: boolean): FilterExpr[];
+  /**
+   * Picks the one row a list of identification candidates addresses — see
+   * {@link resolveRowFilter}. A lone candidate needs no read. With a
+   * non-empty `scope`, only rows matching it count as matches.
+   */
+  protected _pinIdCandidates(candidates: FilterExpr[], scope?: FilterExpr): Promise<FilterExpr | null>;
+  /** Sequential fallback of {@link _pinIdCandidates}: first candidate matching a row wins. */
+  private _probeIdCandidates;
+  /**
+   * The exact primary-key filter of `row` (values prepared like ids) — `null`
+   * when the table has no primary key or `row` lacks a key field.
+   */
+  protected _pkFilterFrom(row: Record<string, unknown>): FilterExpr | null;
+  /**
+   * Reads the row `filter` (AND `scope`) matches and returns its exact
+   * primary-key filter (`filter` itself on a table without one); `undefined`
+   * when no row matches.
+   */
+  protected _readPkFilter(filter: FilterExpr, scope?: FilterExpr): Promise<FilterExpr | undefined>;
+  /** `filter` AND a row scope — `filter` itself when the scope is absent or empty. */
+  protected _andScope(filter: FilterExpr, scope?: FilterExpr): FilterExpr;
   /** Build a single-key filter from `idObj` over `fields`, or null if any field is missing/incompatible. */
   private _tryCompoundFilter;
   /**
@@ -777,7 +899,9 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * 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}.
+   * defaults + validation, with the prepared rows; `opts.check` (since
+   * 0.1.143) runs once after every phase with the inserted rows' primary-key
+   * filters — see {@link TWriteOptions}.
    */
   insertMany(payloads: Array<DbPatch<DataType>>, opts?: TWriteOptions<DataType>): Promise<TDbInsertManyResult>;
   /**
@@ -794,7 +918,9 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * 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}.
+   * `$cas` extraction, defaults + validation; `opts.check` (since 0.1.143)
+   * after every phase — see {@link TWriteOptions}. The nested phases run only
+   * for the rows the main replace matched.
    */
   bulkReplace(payloads: Array<DbRow<DataType>>, opts?: TWriteOptions<DataType>): Promise<TDbUpdateResult>;
   /**
@@ -811,7 +937,10 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    *
    * `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}.
+   * present, `$cas` removed); `opts.check` (since 0.1.143) after every
+   * phase — see {@link TWriteOptions}. The nested phases run only for the
+   * rows the main patch matched; a nested TO object patches the row the
+   * STORED foreign key references.
    */
   bulkUpdate(payloads: Array<DbPatch<DataType>>, opts?: TWriteOptions<DataType>): Promise<TDbUpdateResult>;
   /**
@@ -842,13 +971,22 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
   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`.
+   * or single-field unique index. Uses the same resolution logic as `findById`:
+   * the id addresses exactly ONE row, primary key first (since 0.1.143 — see
+   * {@link resolveRowFilter}); an id that could name several rows is pinned
+   * inside the transaction, so the guard, the cascade and the delete all see
+   * the same row.
    *
    * 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}.
+   * `opts.scope` (since 0.1.143) is a row scope: an ambiguous id is pinned
+   * among in-scope rows only (see {@link TRowResolveOptions}) and the delete
+   * — guard `current()` and cascade included — targets the row only while it
+   * matches the scope, so an out-of-scope row answers `{ deletedCount: 0 }`
+   * exactly like a missing one.
    * An id that resolves to no filter answers `{ deletedCount: 0 }` without
    * calling the guard.
    */
@@ -880,12 +1018,60 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    */
   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.
+   * The record filter a guard's `current(i)` reads its pre-image by: `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. Identified
+   * exactly like the write itself (primary key first, then a unique index —
+   * since 0.1.143), so it is always the row the write targets.
    * @internal
    */
-  _readPreImage(row: unknown): Promise<DataType | null>;
+  _recordFilterOrNull(row: unknown, opts?: TIdResolveOptions): FilterExpr | null;
+  /**
+   * Each item's record filter (see {@link _extractRecordFilter}). A nested
+   * FROM re-entry (`_ownedBy`) also pins the child's foreign key to its
+   * parent, so the write never touches a child of another parent.
+   */
+  private _rowFilters;
+  /** Whether `filter` names every primary-key field (so it IS the row's exact key). */
+  private _isPkFilter;
+  /**
+   * The TO relations with their single-field local foreign key (lazily
+   * listed) — what a write pins per item for its nested TO phase.
+   */
+  private _toRelationsCache?;
+  private _toRelations;
+  /** Whether `item` carries a nested TO object (Phase 1 work). */
+  private _carriesNestedTo;
+  /**
+   * Reads — once per write call, inside its transaction — the stored row
+   * each item `need`s, by the item's record filter: its primary key, version
+   * and single-field TO foreign keys, in ONE read for the batch. A pre-image
+   * the guard's `current(i)` already read by the same filter is reused.
+   * `null` = no such row; `undefined` = not needed.
+   */
+  private _pinTargets;
+  /**
+   * The exact primary-key filter of every row the write matched: the record
+   * filter itself when it is the primary key, else the pinned row's key.
+   */
+  private _writtenPkFilters;
+  /** Invokes a {@link TWriteOptions.check} with de-duplicated PK filters (inside the transaction). */
+  private _runWriteCheck;
+  /**
+   * The exact primary-key filter of each inserted row: the logical key from
+   * the row (SDK defaults applied), else the stored key the adapter wrote into
+   * the prepared row (e.g. a driver-assigned `_id`), else — single-field keys
+   * only — the adapter's `insertedIds` (auto-increment).
+   */
+  private _insertedPkFilters;
+  /**
+   * Drops the nested TO objects of every replace item whose main replace
+   * cannot match (pinned row missing, or stale `$cas`) so Phase 1 never
+   * writes a related row for a replace that does nothing. Returns, per item,
+   * whether its TO objects stay (a later 0-match for such an item is a
+   * concurrent change and rolls back).
+   */
+  private _gateNestedTo;
   /**
    * Applies `@db.default` values in place to a row's absent fields — the
    * defaults pass every insert / replace path runs before validation.
@@ -905,6 +1091,16 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * validator reports it against the field instead of a bare `SyntaxError`.
    */
   private _parseValueDefault;
+  /**
+   * The filter an `updateOne` / `replaceOne` of `payload` targets its row by
+   * — the write's own resolution (primary key first, then a unique index;
+   * see {@link _extractRecordFilter}), so a caller explaining a write's
+   * outcome (e.g. a CAS mismatch) reads exactly the row the write addressed.
+   * Throws `NOT_FOUND` when the payload carries no identifying fields.
+   *
+   * @since 0.1.143
+   */
+  recordFilter(payload: Record<string, unknown>, opts?: TIdResolveOptions): FilterExpr;
   /**
    * Extracts a record-identifying filter from a payload.
    *
@@ -1077,6 +1273,12 @@ interface TViewColumnMapping {
    */
   aggFilter?: AtscriptQueryNode;
 }
+/**
+ * Whether `type` declares a view (managed `@db.view.for` or external
+ * `@db.view`) — how `DbSpace.get` tells views from tables.
+ * @since 0.1.143
+ */
+declare function isViewType(type: TAtscriptAnnotatedType): boolean;
 /**
  * Database view abstraction driven by Atscript `@db.view.*` annotations.
  *
@@ -1094,6 +1296,12 @@ declare class AtscriptDbView<T extends TAtscriptAnnotatedType = TAtscriptAnnotat
   private _viewPlan?;
   private _columnMappings?;
   get isView(): boolean;
+  /**
+   * Builds the view's metadata — first stamping its fields with their
+   * sources' read seals (`inheritViewFieldSeals`, once per view type), so
+   * every metadata consumer sees the sealed type.
+   */
+  protected _ensureBuilt(): void;
   /**
    * Whether this is an external view — declared with `@db.view` only,
    * without `@db.view.for`. External views reference pre-existing DB views
@@ -1385,6 +1593,14 @@ declare abstract class BaseDbAdapter {
    * Adapters use this to retrieve DB-specific state (e.g., MongoDB `ClientSession`).
    */
   protected _getTransactionState(): unknown;
+  /**
+   * `true` when the current async context runs inside a REAL transaction of
+   * this adapter (its owner) — one a throw rolls back (since 0.1.143).
+   * `false` outside any transaction and inside a pass-through
+   * `withTransaction` (adapters without transaction primitives such as the
+   * in-memory one, a standalone MongoDB topology).
+   */
+  isInTransaction(): boolean;
   /**
    * Runs `fn` inside the transaction ALS context with the given state.
    * Adapters that override `withTransaction` (e.g., to use MongoDB's
@@ -1665,6 +1881,14 @@ declare abstract class BaseDbAdapter {
    * UI uses this to show index picker. Override in adapters that support search.
    */
   getSearchIndexes(): TSearchIndexInfo[];
+  private _physicalToLogical?;
+  /**
+   * The LOGICAL field paths an index reads (its `fields` carry physical
+   * names) — what adapters report as {@link TSearchIndexInfo.fields}. A
+   * derived column never shadows the regular field sharing its physical name.
+   * @since 0.1.143
+   */
+  protected _indexLogicalPaths(index: TDbIndex): string[];
   /**
    * Whether this adapter can run TEXT search — `search()`, `searchWithCount()`
    * and the grouped `$search` path all gate on it. Vector capability is a
@@ -2270,6 +2494,19 @@ interface TSearchIndexInfo {
   description?: string;
   /** Index type: text search or vector similarity search. */
   type?: "text" | "vector";
+  /**
+   * LOGICAL field paths the index reads. Absent when the adapter cannot tell
+   * (e.g. a dynamic document search mapping) — treat it as "every field"
+   * (fail closed) when gating access by field visibility.
+   * @since 0.1.143
+   */
+  fields?: string[];
+  /**
+   * `true` on the index of its `type` that answers a request naming none
+   * (at most one per type).
+   * @since 0.1.143
+   */
+  isDefault?: boolean;
 }
 /** Relation summary in a meta response. */
 interface TRelationInfo {
@@ -2825,6 +3062,16 @@ interface AtscriptDbTableLike {
   getMetadata(): TableMetadata;
   isValidFieldPath(path: string, visited?: Set<string>): boolean;
 }
+/**
+ * Nested FROM re-entry option (internal): pins every child's foreign key
+ * `field` to its parent in the write's row filter; a `strict` item that
+ * matches nothing → `CONFLICT`.
+ * @internal
+ */
+interface TNestedOwner {
+  field: string;
+  strict?: ReadonlyArray<boolean>;
+}
 /** Minimal writable table interface for nested creation/update. */
 interface AtscriptDbWritable {
   insertOne(payload: Record<string, unknown>, opts?: {
@@ -2840,6 +3087,7 @@ interface AtscriptDbWritable {
   bulkReplace(payloads: Array<Record<string, unknown>>, opts?: {
     maxDepth?: number;
     _depth?: number;
+    _ownedBy?: TNestedOwner;
   }): Promise<TDbUpdateResult>;
   updateOne(payload: Record<string, unknown>, opts?: {
     maxDepth?: number;
@@ -2847,6 +3095,7 @@ interface AtscriptDbWritable {
   bulkUpdate(payloads: Array<Record<string, unknown>>, opts?: {
     maxDepth?: number;
     _depth?: number;
+    _ownedBy?: TNestedOwner;
   }): Promise<TDbUpdateResult>;
   findOne(query: unknown): Promise<Record<string, unknown> | null>;
   count(query: {
@@ -2941,10 +3190,33 @@ interface TDbWriteGuardContext<Row = Record<string, unknown>> {
   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
+   * inside the transaction. Identified exactly like the write (primary key
+   * first, then a unique index — since 0.1.143), so it is always the row the
+   * write targets. `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>;
+  /**
+   * Every row's pre-image in ONE read (since 0.1.143): parallel to `rows`,
+   * each entry exactly what `current(i)` resolves to — a single `findMany`
+   * by the rows' record filters inside the transaction, which fills the
+   * same per-index memo (an index `current(i)` already read is reused, a
+   * later `current(i)` reads nothing). Prefer it over a `current(i)` loop
+   * for batches.
+   */
+  currentAll(): Promise<Array<Row | null>>;
+  /**
+   * The exact filter the write identifies `rows[i]` by (since 0.1.143) —
+   * its primary key, else the unique index it carries (see `current(i)`),
+   * each naming at most ONE row — or `null` when the row has no identifying
+   * key yet (e.g. an auto-increment insert). The filter `current(i)` reads
+   * by; memoised per index on first use (change a row's identifying fields
+   * before asking, not after). Combine it with a policy filter to check
+   * the batch in the database without reading it — every targeted row
+   * matches `policy` iff `count({ $and: [{ $or: filters }, policy] })`
+   * equals the number of DISTINCT filters (a missing row counts as a miss).
+   */
+  filterFor(i: number): FilterExpr | null;
 }
 /**
  * Context handed to a delete {@link TDeleteOptions.guard} (since 0.1.128) —
@@ -2955,7 +3227,10 @@ interface TDbWriteGuardContext<Row = Record<string, unknown>> {
 interface TDbRemoveGuardContext<Row = Record<string, unknown>> {
   /** The id `deleteOne` was called with. */
   readonly id: unknown;
-  /** `table.resolveIdFilter(id)` — never null here. */
+  /**
+   * The exact filter the delete targets — `table.resolveRowFilter(id)`, pinned
+   * inside the transaction (primary key first, since 0.1.143). Never null here.
+   */
   readonly filter: FilterExpr;
   /** Lazy, memoised pre-image of the row about to be deleted (`null` when missing). */
   current(): Promise<Row | null>;
@@ -2978,6 +3253,12 @@ interface TTouchManyOptions {
  * `isFieldVisible` (since 0.1.134, see {@link TIdResolveOptions}) applies to the
  * top-level rows only — a payload without its primary key identifies through
  * a unique index; nested-relation writes ignore it.
+ *
+ * The nested re-entries a deep write performs on related tables get neither
+ * `guard`, `check` nor `isFieldVisible` — they run with the table's own
+ * integrity rules only (a nested write touches only rows related to the
+ * record being written). A permission layer that must authorize related
+ * tables rejects nested payloads up front.
  */
 interface TWriteOptions<Row = Record<string, unknown>> extends TIdResolveOptions {
   /** Nested-relation write recursion limit (default 3). */
@@ -2991,9 +3272,51 @@ interface TWriteOptions<Row = Record<string, unknown>> extends TIdResolveOptions
    * for the nested re-entries a deep write performs on related tables.
    */
   guard?: TDbWriteGuard<Row>;
+  /**
+   * Post-write check (since 0.1.143): invoked exactly once per top-level call,
+   * inside the table's transaction, AFTER the main write and every
+   * nested-relation phase — see {@link TDbWriteCheckContext}. A throw rolls
+   * the transaction back (when `ctx.transactional`) and propagates unchanged.
+   * Never runs for the nested re-entries a deep write performs on related tables.
+   */
+  check?: TDbWriteCheck;
+}
+/**
+ * Context handed to a write {@link TWriteOptions.check} (since 0.1.143) — and
+ * through it to `AsDbController.checkWrite()`. Lets a permission layer verify
+ * the POST-image of a write with the database's own filter semantics (a
+ * row-level "WITH CHECK"): count the written rows that still match a policy
+ * filter and throw when one does not.
+ */
+interface TDbWriteCheckContext {
+  /** The table method the check runs for (`insertOne` → `insert`, …). */
+  readonly action: TDbWriteAction;
+  /**
+   * One exact primary-key filter per row the call wrote (inserted rows by
+   * their resulting PK, updated / replaced rows by the PK of the row the
+   * write actually targeted), de-duplicated. Rows the write matched nothing
+   * for are absent.
+   */
+  readonly filters: ReadonlyArray<Record<string, unknown>>;
+  /**
+   * `true` when the check runs inside a real transaction, so a throw rolls
+   * the write back. `false` on adapters whose transaction is a pass-through
+   * (e.g. a standalone MongoDB) — the write is already durable, so a caller
+   * that needs a hard guarantee must validate BEFORE the write instead.
+   */
+  readonly transactional: boolean;
+  /** Counts rows matching `filter` inside the check's transaction. */
+  count(filter: Record<string, unknown>): Promise<number>;
 }
-/** Options of `deleteOne`. `isFieldVisible` since 0.1.134 — see {@link TIdResolveOptions}. */
-interface TDeleteOptions<Row = Record<string, unknown>> extends TIdResolveOptions {
+/** A post-write check — see {@link TWriteOptions.check}. */
+type TDbWriteCheck = (ctx: TDbWriteCheckContext) => void | Promise<void>;
+/**
+ * Options of `deleteOne`. `isFieldVisible` since 0.1.134 — see
+ * {@link TIdResolveOptions}. `scope` since 0.1.143 — see
+ * {@link TRowResolveOptions}; on `deleteOne` it also restricts the delete
+ * itself (an out-of-scope row is not deleted, `{ deletedCount: 0 }`).
+ */
+interface TDeleteOptions<Row = Record<string, unknown>> extends TRowResolveOptions {
   /**
    * Validated-stage guard (since 0.1.128): invoked inside the table's
    * transaction after the id resolved to a filter and before cascade /
@@ -3012,6 +3335,24 @@ interface TIdResolveOptions {
    */
   isFieldVisible?: (path: string) => boolean;
 }
+/**
+ * Options of `resolveRowFilter` (and `deleteOne`) — see {@link TIdResolveOptions}.
+ *
+ * @since 0.1.143
+ */
+interface TRowResolveOptions extends TIdResolveOptions {
+  /**
+   * Row scope (e.g. a per-request row-level read overlay). When an id could
+   * name several rows (a scalar equal to one row's primary key and another
+   * row's unique key), only rows matching `scope` count while the
+   * identifications are tried primary key first — so a row outside the scope
+   * can never shadow one inside it, and the outcome is exactly what it would
+   * be if the out-of-scope row did not exist. It does not filter the result
+   * itself: AND the scope onto the returned filter (or guard the write) to
+   * exclude an out-of-scope row the id names unambiguously. Empty = no scope.
+   */
+  scope?: FilterExpr;
+}
 /**
  * Adds `null` to every optional property of `O`. Optional columns store SQL
  * NULL / Mongo null, and the runtime validator accepts `null` for optional
@@ -3109,4 +3450,4 @@ declare function isJsonValueField(fd: TDbFieldMeta): boolean;
  */
 declare function jsonValueAncestor(path: string, jsonValueParents: ReadonlySet<string>): string | undefined;
 //#endregion
-export { TDbWriteGuard as $, IntegrityStrategy as $t, TDbActionInfo as A, UniqueryControls$1 as At, TDbIndex as B, AtscriptDbView as Bt, OwnPropsOf$1 as C, TTouchManyOptions as Ct, TColumnDiff as D, TWriteTableResolver as Dt, TCascadeTarget as E, TWriteOptions as Et, TDbDefaultFn as F, ALL_BUCKET_UNITS as Ft, TDbObjectKind as G, AtscriptQueryFieldRef$1 as Gt, TDbIndexType as H, isAtscriptDbView as Ht, TDbDefaultValue as I, BaseDbAdapter as It, TDbRemoveGuard as J, TViewJoin as Jt, TDbReferentialAction as K, AtscriptQueryNode$1 as Kt, TDbDeleteResult as L, DbSpace as Lt, TDbActionLevel as M, TableMetadata as Mt, TDbActionProcessor as N, isGeoIndexableType as Nt, TCrudOp as O, TypedWithRelation as Ot, TDbCollation as P, isGeoPointType as Pt, TDbWriteAction as Q, AtscriptDbTable as Qt, TDbFieldMeta as R, TAdapterFactory as Rt, NullableOptional as S, TTableResolver as St, TCascadeResolver as T, TViewJsonType as Tt, TDbInsertManyResult as U, aliasTargetOf as Ut, TDbIndexField as V, TViewColumnMapping as Vt, TDbInsertResult as W, AtscriptQueryComparison as Wt, TDbStorageType as X, isFieldRef as Xt, TDbRemoveGuardContext as Y, TViewPlan as Yt, TDbUpdateResult as Z, translateQueryTree as Zt, DbRow as _, TReferencingForeignKey as _t, jsonValueAncestor as a, TDbEncryptionOptions as an, TExistingColumn as at, FlatOf$1 as b, TSyncColumnResult as bt, AggregateControls as c, TReadControls as cn, TFieldMeta as ct, AggregateQuery$1 as d, UniquSelect as dn, TIdDescriptor as dt, NativeIntegrity as en, TDbWriteGuardContext as et, AggregateResult as f, TIdResolveOptions as ft, DbQuery as g, TPrimaryKeyChange as gt, DbPatch as h, TMetadataOverrides as ht, isJsonValueField as i, DbEncryption as in, TEnsureTableOptions as it, TDbActionIntent as j, WithRelation$1 as jt, TCrudPermissions as k, Uniquery$1 as kt, AggregateExpr$1 as l, NoopLogger as ln, TFkLookupResolver as lt, DbControls as m, TMetaResponse as mt, TResolvedBucket as n, DbResponse as nn, TDerivedChangeReason as nt, normalizeComputedSelect as o, DocumentFieldMapper as on, TExistingForeignKey as ot, AtscriptDbWritable as p, TIdentification as pt, TDbRelation as q, AtscriptRef as qt, isBucketableField as r, resolveDesignType as rn, TDerivedColumn as rt, resolveCalendarBuckets as s, FieldMappingStrategy as sn, TExistingTableOption as st, TBucketFieldSource as t, AtscriptDbReadable as tn, TDeleteOptions as tt, AggregateFn$1 as u, TGenericLogger as un, TFkLookupTarget as ut, FieldOpsFor as v, TRelationInfo as vt, PrimaryKeyOf$1 as w, TValueFormatterPair as wt, NavPropsOf$1 as x, TTableOptionDiff as xt, FilterExpr$1 as y, TSearchIndexInfo as yt, TDbForeignKey as z, TDbSpaceOptions as zt };
+export { TDbWriteAction as $, TViewJoin as $t, TCrudPermissions as A, TWriteOptions as At, TDbForeignKey as B, BaseDbAdapter as Bt, NullableOptional as C, TSearchIndexInfo as Ct, TCascadeTarget as D, TTouchManyOptions as Dt, TCascadeResolver as E, TTableResolver as Et, TDbCollation as F, WithRelation$1 as Ft, TDbInsertResult as G, TViewColumnMapping as Gt, TDbIndexField as H, TAdapterFactory as Ht, TDbDefaultFn as I, TableMetadata as It, TDbRelation as J, aliasTargetOf as Jt, TDbObjectKind as K, isAtscriptDbView as Kt, TDbDefaultValue as L, isGeoIndexableType as Lt, TDbActionIntent as M, TypedWithRelation as Mt, TDbActionLevel as N, Uniquery$1 as Nt, TColumnDiff as O, TValueFormatterPair as Ot, TDbActionProcessor as P, UniqueryControls$1 as Pt, TDbUpdateResult as Q, AtscriptRef as Qt, TDbDeleteResult as R, isGeoPointType as Rt, NavPropsOf$1 as S, TRowResolveOptions as St, PrimaryKeyOf$1 as T, TTableOptionDiff as Tt, TDbIndexType as U, TDbSpaceOptions as Ut, TDbIndex as V, DbSpace as Vt, TDbInsertManyResult as W, AtscriptDbView as Wt, TDbRemoveGuardContext as X, AtscriptQueryFieldRef$1 as Xt, TDbRemoveGuard as Y, AtscriptQueryComparison as Yt, TDbStorageType as Z, AtscriptQueryNode$1 as Zt, DbQuery as _, TMetaResponse as _t, jsonValueAncestor as a, NativeIntegrity as an, TDerivedChangeReason as at, FilterExpr$1 as b, TReferencingForeignKey as bt, AggregateControls as c, resolveDesignType as cn, TExistingColumn as ct, AggregateQuery$1 as d, DocumentFieldMapper as dn, TFieldMeta as dt, TViewPlan as en, TDbWriteCheck as et, AggregateResult as f, FieldMappingStrategy as fn, TFkLookupResolver as ft, DbPatch as g, UniquSelect as gn, TIdentification as gt, DbControls as h, TGenericLogger as hn, TIdResolveOptions as ht, isJsonValueField as i, IntegrityStrategy as in, TDeleteOptions as it, TDbActionInfo as j, TWriteTableResolver as jt, TCrudOp as k, TViewJsonType as kt, AggregateExpr$1 as l, DbEncryption as ln, TExistingForeignKey as lt, AtscriptDbWritable as m, NoopLogger as mn, TIdDescriptor as mt, TResolvedBucket as n, translateQueryTree as nn, TDbWriteGuard as nt, normalizeComputedSelect as o, AtscriptDbReadable as on, TDerivedColumn as ot, AtscriptDbTableLike as p, TReadControls as pn, TFkLookupTarget as pt, TDbReferentialAction as q, isViewType as qt, isBucketableField as r, AtscriptDbTable as rn, TDbWriteGuardContext as rt, resolveCalendarBuckets as s, DbResponse as sn, TEnsureTableOptions as st, TBucketFieldSource as t, isFieldRef as tn, TDbWriteCheckContext as tt, AggregateFn$1 as u, TDbEncryptionOptions as un, TExistingTableOption as ut, DbRow as v, TMetadataOverrides as vt, OwnPropsOf$1 as w, TSyncColumnResult as wt, FlatOf$1 as x, TRelationInfo as xt, FieldOpsFor as y, TPrimaryKeyChange as yt, TDbFieldMeta as z, ALL_BUCKET_UNITS as zt };