@atscript/db 0.1.54 → 0.1.56

package/dist/{db-readable-ktHqF277.d.cts → db-readable-Cwjbk6o_.d.cts}

@@ -44,6 +44,120 @@ declare class UniquSelect {
   get hasAggregates(): boolean;
 }
 //#endregion
+//#region src/logger.d.ts
+interface TGenericLogger {
+  error(...messages: any[]): void;
+  warn(...messages: any[]): void;
+  log(...messages: any[]): void;
+  info(...messages: any[]): void;
+  debug(...messages: any[]): void;
+}
+declare const NoopLogger: TGenericLogger;
+//#endregion
+//#region src/table/table-metadata.d.ts
+/**
+ * Computed metadata for a database table or view.
+ *
+ * Contains all field metadata, physical mapping indexes, relation definitions,
+ * and constraint information derived from Atscript annotations. Built lazily
+ * on first access via {@link build}, then immutable.
+ *
+ * This class owns the build pipeline that was previously part of
+ * `AtscriptDbReadable._flatten()`. The Readable delegates all metadata
+ * access to this class.
+ */
+declare class TableMetadata {
+  readonly nestedObjects: boolean;
+  flatMap: Map<string, TAtscriptAnnotatedType>;
+  fieldDescriptors: readonly TDbFieldMeta[];
+  primaryKeys: string[];
+  originalMetaIdFields: string[];
+  indexes: Map<string, TDbIndex>;
+  foreignKeys: Map<string, TDbForeignKey>;
+  relations: Map<string, TDbRelation>;
+  navFields: Set<string>;
+  ignoredFields: Set<string>;
+  uniqueProps: Set<string>;
+  defaults: Map<string, TDbDefaultValue>;
+  columnMap: Map<string, string>;
+  dimensions: string[];
+  measures: string[];
+  pathToPhysical: Map<string, string>;
+  physicalToPath: Map<string, string>;
+  flattenedParents: Set<string>;
+  jsonFields: Set<string>;
+  selectExpansion: Map<string, string[]>;
+  booleanFields: Set<string>;
+  decimalFields: Set<string>;
+  allPhysicalFields: string[];
+  /** Precomputed parent path → child physical column names for fast null-setting. */
+  childrenByParent: Map<string, string[]>;
+  requiresMappings: boolean;
+  /** True when the only mappings needed are simple `@db.column` renames (no nesting/JSON). */
+  onlyColumnRenames: boolean;
+  toStorageFormatters?: Map<string, (value: unknown) => unknown>;
+  fromStorageFormatters?: Map<string, (value: unknown) => unknown>;
+  /** Leaf field descriptors indexed by physical column name (read path). */
+  leafByPhysical: Map<string, TDbFieldMeta>;
+  /** Leaf field descriptors indexed by logical path (write/patch/filter paths). */
+  leafByLogical: Map<string, TDbFieldMeta>;
+  private _built;
+  private _collateMap;
+  private _columnFromMap;
+  constructor(nestedObjects: boolean);
+  get isBuilt(): boolean;
+  /**
+   * Runs the full metadata compilation pipeline. Called once by
+   * `AtscriptDbReadable._ensureBuilt()` on first metadata access.
+   *
+   * Pipeline steps:
+   * 1. `adapter.onBeforeFlatten(type)` — adapter hook
+   * 2. `flattenAnnotatedType()` — collect field tuples, detect nav fields eagerly
+   * 3. Replay non-nav-descendant tuples through annotation scanning + adapter.onFieldScanned
+   * 4. Classify fields and build path maps (skipped for nested-objects adapters)
+   * 5. `adapter.getMetadataOverrides()` → `_applyOverrides()` (PK/unique/inject adjustments)
+   * 6. Build field descriptors (TDbFieldMeta[])
+   * 7. Build leaf field indexes (skipped for nested-objects adapters)
+   * 8. Finalize indexes (resolve field names to physical)
+   * 9. `adapter.onAfterFlatten()` — adapter hook (read-only bookkeeping)
+   * 10. Build allPhysicalFields list
+   */
+  build(type: TAtscriptAnnotatedType<TAtscriptTypeObject>, adapter: BaseDbAdapter, logger: TGenericLogger): void;
+  /**
+   * Applies adapter-provided metadata overrides atomically.
+   * Processing order: injectFields → removePrimaryKeys → addPrimaryKeys → addUniqueFields.
+   */
+  private _applyOverrides;
+  /**
+   * Scans `@db.*` and `@meta.id` annotations on a field during flattening.
+   */
+  private _scanGenericAnnotations;
+  private _addIndexField;
+  /**
+   * Classifies each field as column, flattened, json, or parent-object.
+   * Builds the bidirectional pathToPhysical / physicalToPath maps.
+   */
+  private _classifyFields;
+  /** Returns the `__`-separated parent prefix for a dot-separated path, or empty string for top-level paths. */
+  private _flattenedPrefix;
+  /**
+   * Indexes `fieldDescriptors` into two lookup maps for unified
+   * read/write field classification in the RelationalFieldMapper.
+   */
+  private _buildLeafIndexes;
+  /**
+   * Builds field descriptors, physical-name lookup, and value formatters.
+   * Called once during build() — everything it needs
+   * (flatMap, indexes, columnMap, etc.) is already populated.
+   */
+  private _buildFieldDescriptors;
+  /**
+   * Resolves `fkTargetField` for FK fields in field descriptors.
+   */
+  private _resolveFkTargetFields;
+  private _finalizeIndexes;
+}
+//#endregion
 //#region src/types.d.ts
 /** Controls with resolved projection. Used in the adapter interface. */
 interface DbControls extends Omit<UniqueryControls, "$select"> {
@@ -86,6 +200,34 @@ interface TMetaResponse {
   relations: TRelationInfo[];
   fields: Record<string, TFieldMeta>;
   type: TSerializedAnnotatedType;
+  actions: TDbActionInfo[];
+}
+/** Where the action applies on the UI. */
+type TDbActionLevel = "table" | "row" | "rows";
+/** Semantic intent the UI maps to its own visual language (color, prominence). */
+type TDbActionIntent = "positive" | "negative" | "primary" | "secondary";
+/** How the UI client should handle the action when invoked. */
+type TDbActionProcessor = "backend" | "navigate" | "custom";
+/**
+ * Single action descriptor in the `/meta` envelope. Flat shape — `processor`
+ * is a string discriminator; `value` is its sibling and is always populated.
+ *
+ * - `processor: 'backend'` — UI POSTs to `value` (full HTTP path).
+ * - `processor: 'navigate'` — UI routes to `value` (URL template; `$1` is the row PK).
+ * - `processor: 'custom'`  — UI dispatches `value` as an event name (defaults to action `name`).
+ */
+interface TDbActionInfo {
+  name: string;
+  label: string;
+  level: TDbActionLevel;
+  processor: TDbActionProcessor;
+  value: string;
+  icon?: string;
+  intent?: TDbActionIntent;
+  description?: string;
+  order?: number;
+  default?: boolean;
+  promptText?: string;
 }
 interface TDbInsertResult {
   insertedId: unknown;
@@ -290,6 +432,7 @@ interface AtscriptDbTableLike {
   primaryKeys: readonly string[];
   relations: ReadonlyMap<string, TDbRelation>;
   foreignKeys: ReadonlyMap<string, TDbForeignKey>;
+  getMetadata(): TableMetadata;
 }
 /** Minimal writable table interface for nested creation/update. */
 interface AtscriptDbWritable {
@@ -375,120 +518,6 @@ interface TDbRelation {
   viaType?: () => TAtscriptAnnotatedType;
 }
 //#endregion
-//#region src/logger.d.ts
-interface TGenericLogger {
-  error(...messages: any[]): void;
-  warn(...messages: any[]): void;
-  log(...messages: any[]): void;
-  info(...messages: any[]): void;
-  debug(...messages: any[]): void;
-}
-declare const NoopLogger: TGenericLogger;
-//#endregion
-//#region src/table/table-metadata.d.ts
-/**
- * Computed metadata for a database table or view.
- *
- * Contains all field metadata, physical mapping indexes, relation definitions,
- * and constraint information derived from Atscript annotations. Built lazily
- * on first access via {@link build}, then immutable.
- *
- * This class owns the build pipeline that was previously part of
- * `AtscriptDbReadable._flatten()`. The Readable delegates all metadata
- * access to this class.
- */
-declare class TableMetadata {
-  readonly nestedObjects: boolean;
-  flatMap: Map<string, TAtscriptAnnotatedType>;
-  fieldDescriptors: readonly TDbFieldMeta[];
-  primaryKeys: string[];
-  originalMetaIdFields: string[];
-  indexes: Map<string, TDbIndex>;
-  foreignKeys: Map<string, TDbForeignKey>;
-  relations: Map<string, TDbRelation>;
-  navFields: Set<string>;
-  ignoredFields: Set<string>;
-  uniqueProps: Set<string>;
-  defaults: Map<string, TDbDefaultValue>;
-  columnMap: Map<string, string>;
-  dimensions: string[];
-  measures: string[];
-  pathToPhysical: Map<string, string>;
-  physicalToPath: Map<string, string>;
-  flattenedParents: Set<string>;
-  jsonFields: Set<string>;
-  selectExpansion: Map<string, string[]>;
-  booleanFields: Set<string>;
-  decimalFields: Set<string>;
-  allPhysicalFields: string[];
-  /** Precomputed parent path → child physical column names for fast null-setting. */
-  childrenByParent: Map<string, string[]>;
-  requiresMappings: boolean;
-  /** True when the only mappings needed are simple `@db.column` renames (no nesting/JSON). */
-  onlyColumnRenames: boolean;
-  toStorageFormatters?: Map<string, (value: unknown) => unknown>;
-  fromStorageFormatters?: Map<string, (value: unknown) => unknown>;
-  /** Leaf field descriptors indexed by physical column name (read path). */
-  leafByPhysical: Map<string, TDbFieldMeta>;
-  /** Leaf field descriptors indexed by logical path (write/patch/filter paths). */
-  leafByLogical: Map<string, TDbFieldMeta>;
-  private _built;
-  private _collateMap;
-  private _columnFromMap;
-  constructor(nestedObjects: boolean);
-  get isBuilt(): boolean;
-  /**
-   * Runs the full metadata compilation pipeline. Called once by
-   * `AtscriptDbReadable._ensureBuilt()` on first metadata access.
-   *
-   * Pipeline steps:
-   * 1. `adapter.onBeforeFlatten(type)` — adapter hook
-   * 2. `flattenAnnotatedType()` — collect field tuples, detect nav fields eagerly
-   * 3. Replay non-nav-descendant tuples through annotation scanning + adapter.onFieldScanned
-   * 4. Classify fields and build path maps (skipped for nested-objects adapters)
-   * 5. `adapter.getMetadataOverrides()` → `_applyOverrides()` (PK/unique/inject adjustments)
-   * 6. Build field descriptors (TDbFieldMeta[])
-   * 7. Build leaf field indexes (skipped for nested-objects adapters)
-   * 8. Finalize indexes (resolve field names to physical)
-   * 9. `adapter.onAfterFlatten()` — adapter hook (read-only bookkeeping)
-   * 10. Build allPhysicalFields list
-   */
-  build(type: TAtscriptAnnotatedType<TAtscriptTypeObject>, adapter: BaseDbAdapter, logger: TGenericLogger): void;
-  /**
-   * Applies adapter-provided metadata overrides atomically.
-   * Processing order: injectFields → removePrimaryKeys → addPrimaryKeys → addUniqueFields.
-   */
-  private _applyOverrides;
-  /**
-   * Scans `@db.*` and `@meta.id` annotations on a field during flattening.
-   */
-  private _scanGenericAnnotations;
-  private _addIndexField;
-  /**
-   * Classifies each field as column, flattened, json, or parent-object.
-   * Builds the bidirectional pathToPhysical / physicalToPath maps.
-   */
-  private _classifyFields;
-  /** Returns the `__`-separated parent prefix for a dot-separated path, or empty string for top-level paths. */
-  private _flattenedPrefix;
-  /**
-   * Indexes `fieldDescriptors` into two lookup maps for unified
-   * read/write field classification in the RelationalFieldMapper.
-   */
-  private _buildLeafIndexes;
-  /**
-   * Builds field descriptors, physical-name lookup, and value formatters.
-   * Called once during build() — everything it needs
-   * (flatMap, indexes, columnMap, etc.) is already populated.
-   */
-  private _buildFieldDescriptors;
-  /**
-   * Resolves `fkTargetField` for FK fields in field descriptors.
-   */
-  private _resolveFkTargetFields;
-  private _finalizeIndexes;
-}
-//#endregion
 //#region src/base-adapter.d.ts
 /**
  * Abstract base class for database adapters.
@@ -1106,6 +1135,12 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   constructor(_type: T, adapter: A, logger?: TGenericLogger, _tableResolver?: TTableResolver | undefined);
   /** Ensures metadata is built. Called before any metadata access. */
   protected _ensureBuilt(): void;
+  /**
+   * Built table metadata. Triggers a lazy build on first access — safe to call
+   * from peer tables that need this one's relations / nav fields before any
+   * operation has run against it directly.
+   */
+  getMetadata(): TableMetadata;
   protected _ensureSearchable(): void;
   /** Whether this readable is a view (overridden in AtscriptDbView). */
   get isView(): boolean;
@@ -1280,4 +1315,4 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   }, thisTableName: string, alias?: string): TDbForeignKey | undefined;
 }
 //#endregion
-export { TValueFormatterPair as $, TDbForeignKey as A, TExistingColumn as B, TCascadeTarget as C, TDbDefaultValue as D, TDbDefaultFn as E, TDbInsertResult as F, TIdDescriptor as G, TFieldMeta as H, TDbReferentialAction as I, TRelationInfo as J, TMetaResponse as K, TDbRelation as L, TDbIndexField as M, TDbIndexType as N, TDbDeleteResult as O, TDbInsertManyResult as P, TTableResolver as Q, TDbStorageType as R, TCascadeResolver as S, TDbCollation as T, TFkLookupResolver as U, TExistingTableOption as V, TFkLookupTarget as W, TSyncColumnResult as X, TSearchIndexInfo as Y, TTableOptionDiff as Z, DbQuery as _, FieldMappingStrategy as a, UniquSelect as at, NavPropsOf$1 as b, NoopLogger as c, AggregateExpr$1 as d, TWriteTableResolver as et, AggregateFn as f, DbControls as g, AtscriptDbWritable as h, DocumentFieldMapper as i, WithRelation$1 as it, TDbIndex as j, TDbFieldMeta as k, TGenericLogger as l, AggregateResult as m, DbResponse as n, Uniquery$1 as nt, BaseDbAdapter as o, AggregateQuery$1 as p, TMetadataOverrides as q, resolveDesignType as r, UniqueryControls$1 as rt, TableMetadata as s, AtscriptDbReadable as t, TypedWithRelation as tt, AggregateControls as u, FieldOpsFor as v, TColumnDiff as w, OwnPropsOf$1 as x, FilterExpr$1 as y, TDbUpdateResult as z };
+export { TTableResolver as $, TDbFieldMeta as A, TDbUpdateResult as B, TDbActionIntent as C, TDbDefaultFn as D, TDbCollation as E, TDbInsertManyResult as F, TFkLookupTarget as G, TExistingTableOption as H, TDbInsertResult as I, TMetadataOverrides as J, TIdDescriptor as K, TDbReferentialAction as L, TDbIndex as M, TDbIndexField as N, TDbDefaultValue as O, TDbIndexType as P, TTableOptionDiff as Q, TDbRelation as R, TDbActionInfo as S, TDbActionProcessor as T, TFieldMeta as U, TExistingColumn as V, TFkLookupResolver as W, TSearchIndexInfo as X, TRelationInfo as Y, TSyncColumnResult as Z, NavPropsOf$1 as _, FieldMappingStrategy as a, WithRelation$1 as at, TCascadeTarget as b, AggregateExpr$1 as c, TGenericLogger as ct, AggregateResult as d, TValueFormatterPair as et, AtscriptDbWritable as f, FilterExpr$1 as g, FieldOpsFor as h, DocumentFieldMapper as i, UniqueryControls$1 as it, TDbForeignKey as j, TDbDeleteResult as k, AggregateFn as l, UniquSelect as lt, DbQuery as m, DbResponse as n, TypedWithRelation as nt, BaseDbAdapter as o, TableMetadata as ot, DbControls as p, TMetaResponse as q, resolveDesignType as r, Uniquery$1 as rt, AggregateControls as s, NoopLogger as st, AtscriptDbReadable as t, TWriteTableResolver as tt, AggregateQuery$1 as u, OwnPropsOf$1 as v, TDbActionLevel as w, TColumnDiff as x, TCascadeResolver as y, TDbStorageType as z };

package/dist/{db-space-DB0MT6B3.d.cts → db-space-CAcEB09Y.d.mts}

@@ -1,6 +1,6 @@
-import { F as TDbInsertResult, O as TDbDeleteResult, P as TDbInsertManyResult, Q as TTableResolver, S as TCascadeResolver, U as TFkLookupResolver, et as TWriteTableResolver, l as TGenericLogger, o as BaseDbAdapter, s as TableMetadata, t as AtscriptDbReadable, z as TDbUpdateResult } from "./db-readable-ktHqF277.cjs";
-import { FilterExpr } from "@uniqu/core";
+import { $ as TTableResolver, B as TDbUpdateResult, F as TDbInsertManyResult, I as TDbInsertResult, W as TFkLookupResolver, ct as TGenericLogger, k as TDbDeleteResult, o as BaseDbAdapter, ot as TableMetadata, t as AtscriptDbReadable, tt as TWriteTableResolver, y as TCascadeResolver } from "./db-readable-B9Irll4q.mjs";
 import { AtscriptQueryComparison, AtscriptQueryFieldRef, AtscriptQueryFieldRef as AtscriptQueryFieldRef$1, AtscriptQueryNode, AtscriptQueryNode as AtscriptQueryNode$1, AtscriptRef, FlatOf, NavPropsOf, OwnPropsOf, PrimaryKeyOf, TAtscriptAnnotatedType, TAtscriptDataType, Validator } from "@atscript/typescript/utils";
+import { FilterExpr } from "@uniqu/core";
 
 //#region src/strategies/integrity.d.ts
 /**
@@ -29,6 +29,7 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
   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.
@@ -141,6 +142,18 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    */
   protected _extractRecordFilter(payload: Record<string, unknown>): 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,

package/dist/{db-space-DpaXOdRp.d.mts → db-space-CQg17vv7.d.cts}

@@ -1,6 +1,6 @@
-import { F as TDbInsertResult, O as TDbDeleteResult, P as TDbInsertManyResult, Q as TTableResolver, S as TCascadeResolver, U as TFkLookupResolver, et as TWriteTableResolver, l as TGenericLogger, o as BaseDbAdapter, s as TableMetadata, t as AtscriptDbReadable, z as TDbUpdateResult } from "./db-readable-GBjlsJXR.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 { $ as TTableResolver, B as TDbUpdateResult, F as TDbInsertManyResult, I as TDbInsertResult, W as TFkLookupResolver, ct as TGenericLogger, k as TDbDeleteResult, o as BaseDbAdapter, ot as TableMetadata, t as AtscriptDbReadable, tt as TWriteTableResolver, y as TCascadeResolver } from "./db-readable-Cwjbk6o_.cjs";
 import { FilterExpr } from "@uniqu/core";
+import { AtscriptQueryComparison, AtscriptQueryFieldRef, AtscriptQueryFieldRef as AtscriptQueryFieldRef$1, AtscriptQueryNode, AtscriptQueryNode as AtscriptQueryNode$1, AtscriptRef, FlatOf, NavPropsOf, OwnPropsOf, PrimaryKeyOf, TAtscriptAnnotatedType, TAtscriptDataType, Validator } from "@atscript/typescript/utils";
 
 //#region src/strategies/integrity.d.ts
 /**
@@ -29,6 +29,7 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
   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.
@@ -141,6 +142,18 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    */
   protected _extractRecordFilter(payload: Record<string, unknown>): 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,

package/dist/{db-validator-plugin-Cz4QoDWg.d.cts → db-validator-plugin-DDvYyv5t.d.mts}

@@ -7,6 +7,16 @@ interface DbValidationContext {
   flatMap?: Map<string, TAtscriptAnnotatedType>;
   /** Precomputed nav field names — used to skip field-op validation inside TO/FROM/VIA relations. */
   navFields?: ReadonlySet<string>;
+  /**
+   * Depth-limit enforcement bundle. Set only on the root write call; nested
+   * re-entries leave it unset so the root's check isn't repeated. `limit` is
+   * `@db.depth.limit N`; `fromDepthMap` maps normalized paths (no array
+   * indices) to from-chain depth.
+   */
+  depthCheck?: {
+    limit: number;
+    fromDepthMap: ReadonlyMap<string, number>;
+  };
 }
 /**
  * Validator plugin for database operations.

package/dist/{db-validator-plugin-KC4aNIQq.d.mts → db-validator-plugin-DRGMCEn3.d.cts}

@@ -7,6 +7,16 @@ interface DbValidationContext {
   flatMap?: Map<string, TAtscriptAnnotatedType>;
   /** Precomputed nav field names — used to skip field-op validation inside TO/FROM/VIA relations. */
   navFields?: ReadonlySet<string>;
+  /**
+   * Depth-limit enforcement bundle. Set only on the root write call; nested
+   * re-entries leave it unset so the root's check isn't repeated. `limit` is
+   * `@db.depth.limit N`; `fromDepthMap` maps normalized paths (no array
+   * indices) to from-chain depth.
+   */
+  depthCheck?: {
+    limit: number;
+    fromDepthMap: ReadonlyMap<string, number>;
+  };
 }
 /**
  * Validator plugin for database operations.

package/dist/{db-view-DjDKgytJ.cjs → db-view-DIGN4079.cjs}

@@ -1,8 +1,9 @@
-const require_nested_writer = require("./nested-writer-BIQ6EfaR.cjs");
+const require_db_error = require("./db-error-D8tQhNgM.cjs");
 const require_agg = require("./agg.cjs");
 const require_relation_helpers = require("./relation-helpers-BYvsE1tR.cjs");
 const require_ops = require("./ops.cjs");
-const require_validator = require("./validator-0iGuvGOD.cjs");
+const require_validator = require("./validator-BIuw_T0k.cjs");
+const require_nested_writer = require("./nested-writer-v_LPR1yJ.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
 let node_async_hooks = require("node:async_hooks");
 //#region src/logger.ts
@@ -1096,8 +1097,17 @@ var AtscriptDbReadable = class {
 	_ensureBuilt() {
 		if (!this._meta.isBuilt) this._meta.build(this.type, this.adapter, this.logger);
 	}
+	/**
+	* Built table metadata. Triggers a lazy build on first access — safe to call
+	* from peer tables that need this one's relations / nav fields before any
+	* operation has run against it directly.
+	*/
+	getMetadata() {
+		this._ensureBuilt();
+		return this._meta;
+	}
 	_ensureSearchable() {
-		if (!this.adapter.isSearchable()) throw new require_nested_writer.DbError("INVALID_QUERY", [{
+		if (!this.adapter.isSearchable()) throw new require_db_error.DbError("INVALID_QUERY", [{
 			path: "$search",
 			message: `Table "${this.tableName}" has no search indexes defined`
 		}]);
@@ -1295,7 +1305,7 @@ var AtscriptDbReadable = class {
 		const { $groupBy, $select } = query.controls;
 		if ($select) {
 			const groupBySet = new Set($groupBy);
-			for (const item of $select) if (typeof item === "string" && !groupBySet.has(item)) throw new require_nested_writer.DbError("INVALID_QUERY", [{
+			for (const item of $select) if (typeof item === "string" && !groupBySet.has(item)) throw new require_db_error.DbError("INVALID_QUERY", [{
 				path: "$select",
 				message: `Plain field "${item}" in $select must also appear in $groupBy`
 			}]);
@@ -1304,12 +1314,12 @@ var AtscriptDbReadable = class {
 		if (dimensions.length > 0 || measures.length > 0) {
 			const dimSet = new Set(dimensions);
 			const measSet = new Set(measures);
-			for (const field of $groupBy) if (!dimSet.has(field)) throw new require_nested_writer.DbError("INVALID_QUERY", [{
+			for (const field of $groupBy) if (!dimSet.has(field)) throw new require_db_error.DbError("INVALID_QUERY", [{
 				path: "$groupBy",
 				message: `Field "${field}" is not a dimension`
 			}]);
 			if ($select) {
-				for (const item of $select) if (typeof item !== "string" && item.$field !== "*" && !measSet.has(item.$field)) throw new require_nested_writer.DbError("INVALID_QUERY", [{
+				for (const item of $select) if (typeof item !== "string" && item.$field !== "*" && !measSet.has(item.$field)) throw new require_db_error.DbError("INVALID_QUERY", [{
 					path: "$select",
 					message: `Aggregate field "${item.$field}" is not a measure`
 				}]);
@@ -1977,7 +1987,7 @@ var ApplicationIntegrity = class extends IntegrityStrategy {
 				if (await target.count(filter) < expectedCount) {
 					const sample = firstValues.slice(0, 3).join(", ");
 					const suffix = firstValues.length > 3 ? `, ... (${firstValues.length} total)` : "";
-					throw new require_nested_writer.DbError("FK_VIOLATION", [{
+					throw new require_db_error.DbError("FK_VIOLATION", [{
 						path: fk.fields.join(", "),
 						message: `FK constraint violation: "${fk.fields.join(", ")}" references non-existent record in "${fk.targetTable}" (values: ${sample}${suffix})`
 					}]);
@@ -1998,7 +2008,7 @@ var ApplicationIntegrity = class extends IntegrityStrategy {
 		const parentCtx = cascadeStorage.getStore();
 		const visited = parentCtx?.visited ?? /* @__PURE__ */ new Set();
 		const depth = (parentCtx?.depth ?? 0) + 1;
-		if (depth > MAX_CASCADE_DEPTH) throw new require_nested_writer.DbError("CASCADE_CYCLE", [{
+		if (depth > MAX_CASCADE_DEPTH) throw new require_db_error.DbError("CASCADE_CYCLE", [{
 			path: tableName,
 			message: `Cascade delete aborted: chain exceeded ${MAX_CASCADE_DEPTH} levels, likely caused by a circular or deeply nested cascade relationship`
 		}]);
@@ -2046,7 +2056,7 @@ var ApplicationIntegrity = class extends IntegrityStrategy {
 					const childFilter = this.buildCascadeChildFilter(records, target.fk);
 					if (!childFilter) continue;
 					restrictChecks.push(target.count(childFilter).then((count) => {
-						if (count > 0) throw new require_nested_writer.DbError("CONFLICT", [{
+						if (count > 0) throw new require_db_error.DbError("CONFLICT", [{
 							path: tableName,
 							message: `Cannot delete from "${tableName}": ${count} record(s) in "${target.childTable}" (${target.fk.fields.join(", ")}) reference it (RESTRICT)`
 						}]);
@@ -2358,6 +2368,7 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	_fkLookupResolver;
 	_integrity;
 	validators = /* @__PURE__ */ new Map();
+	_fromDepthMap;
 	constructor(_type, adapter, logger, _tableResolver, _writeTableResolver) {
 		super(_type, adapter, logger, _tableResolver);
 		if (_writeTableResolver) this._writeTableResolver = _writeTableResolver;
@@ -2411,16 +2422,20 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 	*/
 	async insertMany(payloads, opts) {
 		this._ensureBuilt();
-		const maxDepth = opts?.maxDepth ?? 3;
-		const depth = opts?._depth ?? 0;
+		const { _depth, maxDepth: userMax } = opts ?? {};
+		const maxDepth = userMax ?? 3;
+		const depth = _depth ?? 0;
 		const canNest = depth < maxDepth && this._writeTableResolver && this._meta.navFields.size > 0;
 		if (!canNest && this._meta.navFields.size > 0) require_nested_writer.checkDepthOverflow(payloads, maxDepth, this._meta);
 		return require_nested_writer.enrichFkViolation(this._meta, () => this.adapter.withTransaction(async () => {
 			const items = payloads.map((p) => this._applyDefaults({ ...p }));
-			require_nested_writer.validateBatch(this.getValidator("insert"), items, {
+			const validator = this.getValidator("insert");
+			const ctx = {
 				mode: "insert",
 				navFields: this._meta.navFields
-			});
+			};
+			this._applyDepthCtx(ctx, depth);
+			require_nested_writer.validateBatch(validator, items, ctx);
 			const host = this;
 			if (canNest) await require_nested_writer.batchInsertNestedTo(host, items, maxDepth, depth);
 			const prepared = [];
@@ -2460,10 +2475,13 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		return require_nested_writer.enrichFkViolation(this._meta, () => this.adapter.withTransaction(async () => {
 			const items = payloads.map((p) => this._applyDefaults({ ...p }));
 			const originals = canNest ? payloads.map((p) => ({ ...p })) : [];
-			require_nested_writer.validateBatch(this.getValidator("bulkReplace"), items, {
+			const validator = this.getValidator("bulkReplace");
+			const ctx = {
 				mode: "replace",
 				navFields: this._meta.navFields
-			});
+			};
+			this._applyDepthCtx(ctx, depth);
+			require_nested_writer.validateBatch(validator, items, ctx);
 			const host = this;
 			if (canNest) await require_nested_writer.batchReplaceNestedTo(host, items, maxDepth, depth);
 			await this._integrity.validateForeignKeys(items, this._meta, this._fkLookupResolver, this._writeTableResolver);
@@ -2507,11 +2525,14 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		const canNest = depth < maxDepth && this._writeTableResolver && this._meta.navFields.size > 0;
 		if (!canNest && this._meta.navFields.size > 0) require_nested_writer.checkDepthOverflow(payloads, maxDepth, this._meta);
 		return require_nested_writer.enrichFkViolation(this._meta, () => this.adapter.withTransaction(async () => {
-			require_nested_writer.validateBatch(this.getValidator("bulkUpdate"), payloads, {
+			const validator = this.getValidator("bulkUpdate");
+			const ctx = {
 				mode: "patch",
 				flatMap: this.flatMap,
 				navFields: this._meta.navFields
-			});
+			};
+			this._applyDepthCtx(ctx, depth);
+			require_nested_writer.validateBatch(validator, payloads, ctx);
 			const originals = canNest ? payloads.map((p) => ({ ...p })) : [];
 			const host = this;
 			if (canNest) await require_nested_writer.batchPatchNestedTo(host, payloads, maxDepth, depth);
@@ -2673,11 +2694,11 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 				return filter;
 			}
 		}
-		if (pkFields.length === 0) throw new require_nested_writer.DbError("NOT_FOUND", [{
+		if (pkFields.length === 0) throw new require_db_error.DbError("NOT_FOUND", [{
 			path: "",
 			message: "No primary key defined — cannot extract filter"
 		}]);
-		throw new require_nested_writer.DbError("NOT_FOUND", [{
+		throw new require_db_error.DbError("NOT_FOUND", [{
 			path: pkFields[0],
 			message: `Missing primary key field "${pkFields[0]}" in payload`
 		}]);
@@ -2687,6 +2708,47 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		return fieldType ? this.adapter.prepareId(value, fieldType) : value;
 	}
 	/**
+	* 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).
+	*/
+	_getFromDepthMap() {
+		if (!this._fromDepthMap) {
+			const out = /* @__PURE__ */ new Map();
+			for (const [path, def] of this._meta.flatMap) {
+				if (!def.metadata?.has("db.rel.from")) continue;
+				const segments = path.split(".");
+				let prefix = "";
+				let depth = 0;
+				let valid = true;
+				for (let i = 0; i < segments.length; i++) {
+					prefix = prefix ? `${prefix}.${segments[i]}` : segments[i];
+					const pmd = this._meta.flatMap.get(prefix)?.metadata;
+					if (pmd?.has("db.rel.to") || pmd?.has("db.rel.via")) {
+						valid = false;
+						break;
+					}
+					if (pmd?.has("db.rel.from")) depth++;
+				}
+				if (valid) out.set(path, depth);
+			}
+			this._fromDepthMap = out;
+		}
+		return this._fromDepthMap;
+	}
+	/**
+	* 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.
+	*/
+	_applyDepthCtx(ctx, depth) {
+		if (depth !== 0 || this._meta.navFields.size === 0) return;
+		ctx.depthCheck = {
+			limit: this.type.metadata.get("db.depth.limit") ?? 0,
+			fromDepthMap: this._getFromDepthMap()
+		};
+	}
+	/**
 	* 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.