@atscript/db 0.1.54 → 0.1.56

package/dist/{db-view-B1j_IKSf.mjs → db-view-DNwX6_4x.mjs}

@@ -1,8 +1,9 @@
-import { a as batchPatchNestedTo, c as batchReplaceNestedTo, d as preValidateNestedFrom, f as validateBatch, h as DbError, i as batchPatchNestedFrom, l as batchReplaceNestedVia, m as remapDeleteFkViolation, n as batchInsertNestedTo, o as batchPatchNestedVia, p as enrichFkViolation, r as batchInsertNestedVia, s as batchReplaceNestedFrom, t as batchInsertNestedFrom, u as checkDepthOverflow } from "./nested-writer-CNDyhg2L.mjs";
+import { t as DbError } from "./db-error-Cepx-RsQ.mjs";
 import { resolveAlias } from "./agg.mjs";
 import { n as findRemoteFK, t as findFKForRelation } from "./relation-helpers-CLasawQq.mjs";
 import { separateFieldOps } from "./ops.mjs";
-import { i as forceNavNonOptional, r as dbPlugin, s as getKeyProps, t as buildDbValidator } from "./validator-D_7Fqzs4.mjs";
+import { i as forceNavNonOptional, r as dbPlugin, s as getKeyProps, t as buildDbValidator } from "./validator-BB5h1Le3.mjs";
+import { a as batchPatchNestedTo, c as batchReplaceNestedTo, d as preValidateNestedFrom, f as validateBatch, i as batchPatchNestedFrom, l as batchReplaceNestedVia, m as remapDeleteFkViolation, n as batchInsertNestedTo, o as batchPatchNestedVia, p as enrichFkViolation, r as batchInsertNestedVia, s as batchReplaceNestedFrom, t as batchInsertNestedFrom, u as checkDepthOverflow } from "./nested-writer-CT2rLURx.mjs";
 import { flattenAnnotatedType, isAnnotatedType } from "@atscript/typescript/utils";
 import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/logger.ts
@@ -1096,6 +1097,15 @@ 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 DbError("INVALID_QUERY", [{
 			path: "$search",
@@ -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) checkDepthOverflow(payloads, maxDepth, this._meta);
 		return enrichFkViolation(this._meta, () => this.adapter.withTransaction(async () => {
 			const items = payloads.map((p) => this._applyDefaults({ ...p }));
-			validateBatch(this.getValidator("insert"), items, {
+			const validator = this.getValidator("insert");
+			const ctx = {
 				mode: "insert",
 				navFields: this._meta.navFields
-			});
+			};
+			this._applyDepthCtx(ctx, depth);
+			validateBatch(validator, items, ctx);
 			const host = this;
 			if (canNest) await batchInsertNestedTo(host, items, maxDepth, depth);
 			const prepared = [];
@@ -2460,10 +2475,13 @@ var AtscriptDbTable = class extends AtscriptDbReadable {
 		return enrichFkViolation(this._meta, () => this.adapter.withTransaction(async () => {
 			const items = payloads.map((p) => this._applyDefaults({ ...p }));
 			const originals = canNest ? payloads.map((p) => ({ ...p })) : [];
-			validateBatch(this.getValidator("bulkReplace"), items, {
+			const validator = this.getValidator("bulkReplace");
+			const ctx = {
 				mode: "replace",
 				navFields: this._meta.navFields
-			});
+			};
+			this._applyDepthCtx(ctx, depth);
+			validateBatch(validator, items, ctx);
 			const host = this;
 			if (canNest) await 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) checkDepthOverflow(payloads, maxDepth, this._meta);
 		return enrichFkViolation(this._meta, () => this.adapter.withTransaction(async () => {
-			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);
+			validateBatch(validator, payloads, ctx);
 			const originals = canNest ? payloads.map((p) => ({ ...p })) : [];
 			const host = this;
 			if (canNest) await batchPatchNestedTo(host, payloads, maxDepth, depth);
@@ -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.

package/dist/index.cjs

@@ -1,8 +1,9 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_nested_writer = require("./nested-writer-BIQ6EfaR.cjs");
-const require_db_view = require("./db-view-DjDKgytJ.cjs");
+const require_db_error = require("./db-error-D8tQhNgM.cjs");
+const require_db_view = require("./db-view-DIGN4079.cjs");
 const require_ops = require("./ops.cjs");
-const require_validator = require("./validator-0iGuvGOD.cjs");
+const require_validator = require("./validator-BIuw_T0k.cjs");
+require("./nested-writer-v_LPR1yJ.cjs");
 let _uniqu_core = require("@uniqu/core");
 //#region src/table/db-space.ts
 /**
@@ -152,7 +153,7 @@ exports.AtscriptDbReadable = require_db_view.AtscriptDbReadable;
 exports.AtscriptDbTable = require_db_view.AtscriptDbTable;
 exports.AtscriptDbView = require_db_view.AtscriptDbView;
 exports.BaseDbAdapter = require_db_view.BaseDbAdapter;
-exports.DbError = require_nested_writer.DbError;
+exports.DbError = require_db_error.DbError;
 exports.DbSpace = DbSpace;
 exports.DocumentFieldMapper = require_db_view.DocumentFieldMapper;
 exports.FieldMappingStrategy = require_db_view.FieldMappingStrategy;

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { $ as TValueFormatterPair, A as TDbForeignKey, B as TExistingColumn, C as TCascadeTarget, D as TDbDefaultValue, E as TDbDefaultFn, F as TDbInsertResult, G as TIdDescriptor, H as TFieldMeta, I as TDbReferentialAction, J as TRelationInfo, K as TMetaResponse, L as TDbRelation, M as TDbIndexField, N as TDbIndexType, O as TDbDeleteResult, P as TDbInsertManyResult, Q as TTableResolver, R as TDbStorageType, S as TCascadeResolver, T as TDbCollation, U as TFkLookupResolver, V as TExistingTableOption, W as TFkLookupTarget, X as TSyncColumnResult, Y as TSearchIndexInfo, Z as TTableOptionDiff, _ as DbQuery, a as FieldMappingStrategy, at as UniquSelect, b as NavPropsOf, c as NoopLogger, d as AggregateExpr, et as TWriteTableResolver, f as AggregateFn, g as DbControls, h as AtscriptDbWritable, i as DocumentFieldMapper, it as WithRelation, j as TDbIndex, k as TDbFieldMeta, l as TGenericLogger, m as AggregateResult, n as DbResponse, nt as Uniquery, o as BaseDbAdapter, p as AggregateQuery, q as TMetadataOverrides, r as resolveDesignType, rt as UniqueryControls, s as TableMetadata, t as AtscriptDbReadable, tt as TypedWithRelation, u as AggregateControls, v as FieldOpsFor, w as TColumnDiff, x as OwnPropsOf, y as FilterExpr, z as TDbUpdateResult } from "./db-readable-ktHqF277.cjs";
+import { $ as TTableResolver, A as TDbFieldMeta, B as TDbUpdateResult, C as TDbActionIntent, D as TDbDefaultFn, E as TDbCollation, F as TDbInsertManyResult, G as TFkLookupTarget, H as TExistingTableOption, I as TDbInsertResult, J as TMetadataOverrides, K as TIdDescriptor, L as TDbReferentialAction, M as TDbIndex, N as TDbIndexField, O as TDbDefaultValue, P as TDbIndexType, Q as TTableOptionDiff, R as TDbRelation, S as TDbActionInfo, T as TDbActionProcessor, U as TFieldMeta, V as TExistingColumn, W as TFkLookupResolver, X as TSearchIndexInfo, Y as TRelationInfo, Z as TSyncColumnResult, _ as NavPropsOf, a as FieldMappingStrategy, at as WithRelation, b as TCascadeTarget, c as AggregateExpr, ct as TGenericLogger, d as AggregateResult, et as TValueFormatterPair, f as AtscriptDbWritable, g as FilterExpr, h as FieldOpsFor, i as DocumentFieldMapper, it as UniqueryControls, j as TDbForeignKey, k as TDbDeleteResult, l as AggregateFn, lt as UniquSelect, m as DbQuery, n as DbResponse, nt as TypedWithRelation, o as BaseDbAdapter, ot as TableMetadata, p as DbControls, q as TMetaResponse, r as resolveDesignType, rt as Uniquery, s as AggregateControls, st as NoopLogger, t as AtscriptDbReadable, tt as TWriteTableResolver, u as AggregateQuery, v as OwnPropsOf, w as TDbActionLevel, x as TColumnDiff, y as TCascadeResolver, z as TDbStorageType } from "./db-readable-Cwjbk6o_.cjs";
 import { a as $remove, c as $upsert, d as getDbFieldOp, f as isDbFieldOp, i as $mul, l as TDbFieldOp, n as $inc, o as $replace, p as separateFieldOps, r as $insert, s as $update, t as $dec, u as TFieldOps } from "./ops-DXJ4Zw0P.cjs";
-import { a as AtscriptQueryComparison, c as AtscriptRef, d as translateQueryTree, f as AtscriptDbTable, i as TViewColumnMapping, l as TViewJoin, m as NativeIntegrity, n as TAdapterFactory, o as AtscriptQueryFieldRef, p as IntegrityStrategy, r as AtscriptDbView, s as AtscriptQueryNode, t as DbSpace, u as TViewPlan } from "./db-space-DB0MT6B3.cjs";
-import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-Cz4QoDWg.cjs";
+import { a as AtscriptQueryComparison, c as AtscriptRef, d as translateQueryTree, f as AtscriptDbTable, i as TViewColumnMapping, l as TViewJoin, m as NativeIntegrity, n as TAdapterFactory, o as AtscriptQueryFieldRef, p as IntegrityStrategy, r as AtscriptDbView, s as AtscriptQueryNode, t as DbSpace, u as TViewPlan } from "./db-space-CQg17vv7.cjs";
+import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-DRGMCEn3.cjs";
 import { c as TArrayPatch, i as buildValidationContext, l as TDbPatch, n as ValidatorMode, o as forceNavNonOptional, r as buildDbValidator, s as isNavRelation, t as ValidationContext, u as getKeyProps } from "./validator-_z_A3cKa.cjs";
 import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, Uniquery as Uniquery$1, computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
 
@@ -81,7 +81,7 @@ declare class ApplicationIntegrity extends IntegrityStrategy {
 }
 //#endregion
 //#region src/db-error.d.ts
-type DbErrorCode = "CONFLICT" | "FK_VIOLATION" | "NOT_FOUND" | "CASCADE_CYCLE" | "INVALID_QUERY";
+type DbErrorCode = "CONFLICT" | "FK_VIOLATION" | "NOT_FOUND" | "CASCADE_CYCLE" | "INVALID_QUERY" | "DEPTH_EXCEEDED";
 declare class DbError extends Error {
   readonly code: DbErrorCode;
   readonly errors: Array<{
@@ -114,4 +114,4 @@ declare class DbError extends Error {
  */
 declare function decomposePatch(payload: Record<string, unknown>, table: AtscriptDbTable): Record<string, unknown>;
 //#endregion
-export { $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, type DbControls, DbError, type DbErrorCode, type DbQuery, type DbResponse, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type OwnPropsOf, RelationalFieldMapper, type TAdapterFactory, type TArrayPatch, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbStorageType, type TDbUpdateResult, type TExistingColumn, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TIdDescriptor, type TMetaResponse, type TMetadataOverrides, type TRelationInfo, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WithRelation, buildDbValidator, buildValidationContext, computeInsights, createDbValidatorPlugin, decomposePatch, forceNavNonOptional, getDbFieldOp, getKeyProps, isDbFieldOp, isNavRelation, isPrimitive, resolveDesignType, separateFieldOps, translateQueryTree, walkFilter };
+export { $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, type DbControls, DbError, type DbErrorCode, type DbQuery, type DbResponse, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type OwnPropsOf, RelationalFieldMapper, type TAdapterFactory, type TArrayPatch, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbStorageType, type TDbUpdateResult, type TExistingColumn, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TIdDescriptor, type TMetaResponse, type TMetadataOverrides, type TRelationInfo, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WithRelation, buildDbValidator, buildValidationContext, computeInsights, createDbValidatorPlugin, decomposePatch, forceNavNonOptional, getDbFieldOp, getKeyProps, isDbFieldOp, isNavRelation, isPrimitive, resolveDesignType, separateFieldOps, translateQueryTree, walkFilter };

package/dist/index.d.mts

@@ -1,8 +1,8 @@
-import { $ as TValueFormatterPair, A as TDbForeignKey, B as TExistingColumn, C as TCascadeTarget, D as TDbDefaultValue, E as TDbDefaultFn, F as TDbInsertResult, G as TIdDescriptor, H as TFieldMeta, I as TDbReferentialAction, J as TRelationInfo, K as TMetaResponse, L as TDbRelation, M as TDbIndexField, N as TDbIndexType, O as TDbDeleteResult, P as TDbInsertManyResult, Q as TTableResolver, R as TDbStorageType, S as TCascadeResolver, T as TDbCollation, U as TFkLookupResolver, V as TExistingTableOption, W as TFkLookupTarget, X as TSyncColumnResult, Y as TSearchIndexInfo, Z as TTableOptionDiff, _ as DbQuery, a as FieldMappingStrategy, at as UniquSelect, b as NavPropsOf, c as NoopLogger, d as AggregateExpr, et as TWriteTableResolver, f as AggregateFn, g as DbControls, h as AtscriptDbWritable, i as DocumentFieldMapper, it as WithRelation, j as TDbIndex, k as TDbFieldMeta, l as TGenericLogger, m as AggregateResult, n as DbResponse, nt as Uniquery, o as BaseDbAdapter, p as AggregateQuery, q as TMetadataOverrides, r as resolveDesignType, rt as UniqueryControls, s as TableMetadata, t as AtscriptDbReadable, tt as TypedWithRelation, u as AggregateControls, v as FieldOpsFor, w as TColumnDiff, x as OwnPropsOf, y as FilterExpr, z as TDbUpdateResult } from "./db-readable-GBjlsJXR.mjs";
-import { a as $remove, c as $upsert, d as getDbFieldOp, f as isDbFieldOp, i as $mul, l as TDbFieldOp, n as $inc, o as $replace, p as separateFieldOps, r as $insert, s as $update, t as $dec, u as TFieldOps } from "./ops-DcHDxrjX.mjs";
-import { a as AtscriptQueryComparison, c as AtscriptRef, d as translateQueryTree, f as AtscriptDbTable, i as TViewColumnMapping, l as TViewJoin, m as NativeIntegrity, n as TAdapterFactory, o as AtscriptQueryFieldRef, p as IntegrityStrategy, r as AtscriptDbView, s as AtscriptQueryNode, t as DbSpace, u as TViewPlan } from "./db-space-DpaXOdRp.mjs";
-import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-KC4aNIQq.mjs";
-import { c as TArrayPatch, i as buildValidationContext, l as TDbPatch, n as ValidatorMode, o as forceNavNonOptional, r as buildDbValidator, s as isNavRelation, t as ValidationContext, u as getKeyProps } from "./validator-BeXlQISk.mjs";
+import { $ as TTableResolver, A as TDbFieldMeta, B as TDbUpdateResult, C as TDbActionIntent, D as TDbDefaultFn, E as TDbCollation, F as TDbInsertManyResult, G as TFkLookupTarget, H as TExistingTableOption, I as TDbInsertResult, J as TMetadataOverrides, K as TIdDescriptor, L as TDbReferentialAction, M as TDbIndex, N as TDbIndexField, O as TDbDefaultValue, P as TDbIndexType, Q as TTableOptionDiff, R as TDbRelation, S as TDbActionInfo, T as TDbActionProcessor, U as TFieldMeta, V as TExistingColumn, W as TFkLookupResolver, X as TSearchIndexInfo, Y as TRelationInfo, Z as TSyncColumnResult, _ as NavPropsOf, a as FieldMappingStrategy, at as WithRelation, b as TCascadeTarget, c as AggregateExpr, ct as TGenericLogger, d as AggregateResult, et as TValueFormatterPair, f as AtscriptDbWritable, g as FilterExpr, h as FieldOpsFor, i as DocumentFieldMapper, it as UniqueryControls, j as TDbForeignKey, k as TDbDeleteResult, l as AggregateFn, lt as UniquSelect, m as DbQuery, n as DbResponse, nt as TypedWithRelation, o as BaseDbAdapter, ot as TableMetadata, p as DbControls, q as TMetaResponse, r as resolveDesignType, rt as Uniquery, s as AggregateControls, st as NoopLogger, t as AtscriptDbReadable, tt as TWriteTableResolver, u as AggregateQuery, v as OwnPropsOf, w as TDbActionLevel, x as TColumnDiff, y as TCascadeResolver, z as TDbStorageType } from "./db-readable-B9Irll4q.mjs";
+import { a as $remove, c as $upsert, d as getDbFieldOp, f as isDbFieldOp, i as $mul, l as TDbFieldOp, n as $inc, o as $replace, p as separateFieldOps, r as $insert, s as $update, t as $dec, u as TFieldOps } from "./ops-C61kelof.mjs";
+import { a as AtscriptQueryComparison, c as AtscriptRef, d as translateQueryTree, f as AtscriptDbTable, i as TViewColumnMapping, l as TViewJoin, m as NativeIntegrity, n as TAdapterFactory, o as AtscriptQueryFieldRef, p as IntegrityStrategy, r as AtscriptDbView, s as AtscriptQueryNode, t as DbSpace, u as TViewPlan } from "./db-space-CAcEB09Y.mjs";
+import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-DDvYyv5t.mjs";
+import { c as TArrayPatch, i as buildValidationContext, l as TDbPatch, n as ValidatorMode, o as forceNavNonOptional, r as buildDbValidator, s as isNavRelation, t as ValidationContext, u as getKeyProps } from "./validator-DttN2e5_.mjs";
 import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, Uniquery as Uniquery$1, computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
 
 //#region src/strategies/relational-field-mapper.d.ts
@@ -81,7 +81,7 @@ declare class ApplicationIntegrity extends IntegrityStrategy {
 }
 //#endregion
 //#region src/db-error.d.ts
-type DbErrorCode = "CONFLICT" | "FK_VIOLATION" | "NOT_FOUND" | "CASCADE_CYCLE" | "INVALID_QUERY";
+type DbErrorCode = "CONFLICT" | "FK_VIOLATION" | "NOT_FOUND" | "CASCADE_CYCLE" | "INVALID_QUERY" | "DEPTH_EXCEEDED";
 declare class DbError extends Error {
   readonly code: DbErrorCode;
   readonly errors: Array<{
@@ -114,4 +114,4 @@ declare class DbError extends Error {
  */
 declare function decomposePatch(payload: Record<string, unknown>, table: AtscriptDbTable): Record<string, unknown>;
 //#endregion
-export { $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, type DbControls, DbError, type DbErrorCode, type DbQuery, type DbResponse, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type OwnPropsOf, RelationalFieldMapper, type TAdapterFactory, type TArrayPatch, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbStorageType, type TDbUpdateResult, type TExistingColumn, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TIdDescriptor, type TMetaResponse, type TMetadataOverrides, type TRelationInfo, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WithRelation, buildDbValidator, buildValidationContext, computeInsights, createDbValidatorPlugin, decomposePatch, forceNavNonOptional, getDbFieldOp, getKeyProps, isDbFieldOp, isNavRelation, isPrimitive, resolveDesignType, separateFieldOps, translateQueryTree, walkFilter };
+export { $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, type DbControls, DbError, type DbErrorCode, type DbQuery, type DbResponse, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type OwnPropsOf, RelationalFieldMapper, type TAdapterFactory, type TArrayPatch, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbStorageType, type TDbUpdateResult, type TExistingColumn, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TIdDescriptor, type TMetaResponse, type TMetadataOverrides, type TRelationInfo, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WithRelation, buildDbValidator, buildValidationContext, computeInsights, createDbValidatorPlugin, decomposePatch, forceNavNonOptional, getDbFieldOp, getKeyProps, isDbFieldOp, isNavRelation, isPrimitive, resolveDesignType, separateFieldOps, translateQueryTree, walkFilter };

package/dist/index.mjs

@@ -1,7 +1,8 @@
-import { h as DbError } from "./nested-writer-CNDyhg2L.mjs";
-import { a as BaseDbAdapter, c as AtscriptDbReadable, d as DocumentFieldMapper, f as FieldMappingStrategy, h as NoopLogger, i as ApplicationIntegrity, l as resolveDesignType, m as TableMetadata, n as AtscriptDbTable, o as IntegrityStrategy, p as UniquSelect, r as decomposePatch, s as NativeIntegrity, t as AtscriptDbView, u as RelationalFieldMapper } from "./db-view-B1j_IKSf.mjs";
+import { t as DbError } from "./db-error-Cepx-RsQ.mjs";
+import { a as BaseDbAdapter, c as AtscriptDbReadable, d as DocumentFieldMapper, f as FieldMappingStrategy, h as NoopLogger, i as ApplicationIntegrity, l as resolveDesignType, m as TableMetadata, n as AtscriptDbTable, o as IntegrityStrategy, p as UniquSelect, r as decomposePatch, s as NativeIntegrity, t as AtscriptDbView, u as RelationalFieldMapper } from "./db-view-DNwX6_4x.mjs";
 import { $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, getDbFieldOp, isDbFieldOp, separateFieldOps } from "./ops.mjs";
-import { a as isNavRelation, i as forceNavNonOptional, n as buildValidationContext, o as createDbValidatorPlugin, s as getKeyProps, t as buildDbValidator } from "./validator-D_7Fqzs4.mjs";
+import { a as isNavRelation, i as forceNavNonOptional, n as buildValidationContext, o as createDbValidatorPlugin, s as getKeyProps, t as buildDbValidator } from "./validator-BB5h1Le3.mjs";
+import "./nested-writer-CT2rLURx.mjs";
 import { computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
 //#region src/table/db-space.ts
 /**

package/dist/{nested-writer-CNDyhg2L.mjs → nested-writer-CT2rLURx.mjs}

@@ -1,16 +1,6 @@
+import { n as DepthLimitExceededError, t as DbError } from "./db-error-Cepx-RsQ.mjs";
 import { r as resolveRelationTargetTable } from "./relation-helpers-CLasawQq.mjs";
 import { ValidatorError } from "@atscript/typescript/utils";
-//#region src/db-error.ts
-var DbError = class extends Error {
-	name = "DbError";
-	constructor(code, errors, message) {
-		super(message ?? errors[0]?.message ?? "Database error");
-		this.code = code;
-		this.errors = errors;
-		this.stack = void 0;
-	}
-};
-//#endregion
 //#region src/table/error-utils.ts
 /**
 * Prefixes error paths with a nav field context.
@@ -89,10 +79,13 @@ function validateBatch(validator, items, ctx) {
 	for (let i = 0; i < items.length; i++) try {
 		validator.validate(items[i], false, ctx);
 	} catch (error) {
-		if (error instanceof ValidatorError && items.length > 1) throw new ValidatorError(error.errors.map((err) => ({
-			...err,
-			path: `[${i}].${err.path}`
-		})));
+		if (items.length > 1) {
+			if (error instanceof ValidatorError) throw new ValidatorError(error.errors.map((err) => ({
+				...err,
+				path: `[${i}].${err.path}`
+			})));
+			if (error instanceof DepthLimitExceededError) throw new DepthLimitExceededError(`[${i}].${error.field}`, error.declared, error.actual);
+		}
 		throw error;
 	}
 }
@@ -621,4 +614,4 @@ async function viaReplace(targetTable, junctionTable, targets, parentPK, targetP
 	}
 }
 //#endregion
-export { batchPatchNestedTo as a, batchReplaceNestedTo as c, preValidateNestedFrom as d, validateBatch as f, DbError as h, batchPatchNestedFrom as i, batchReplaceNestedVia as l, remapDeleteFkViolation as m, batchInsertNestedTo as n, batchPatchNestedVia as o, enrichFkViolation as p, batchInsertNestedVia as r, batchReplaceNestedFrom as s, batchInsertNestedFrom as t, checkDepthOverflow as u };
+export { batchPatchNestedTo as a, batchReplaceNestedTo as c, preValidateNestedFrom as d, validateBatch as f, batchPatchNestedFrom as i, batchReplaceNestedVia as l, remapDeleteFkViolation as m, batchInsertNestedTo as n, batchPatchNestedVia as o, enrichFkViolation as p, batchInsertNestedVia as r, batchReplaceNestedFrom as s, batchInsertNestedFrom as t, checkDepthOverflow as u };

package/dist/{nested-writer-BIQ6EfaR.cjs → nested-writer-v_LPR1yJ.cjs}

@@ -1,16 +1,6 @@
+const require_db_error = require("./db-error-D8tQhNgM.cjs");
 const require_relation_helpers = require("./relation-helpers-BYvsE1tR.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
-//#region src/db-error.ts
-var DbError = class extends Error {
-	name = "DbError";
-	constructor(code, errors, message) {
-		super(message ?? errors[0]?.message ?? "Database error");
-		this.code = code;
-		this.errors = errors;
-		this.stack = void 0;
-	}
-};
-//#endregion
 //#region src/table/error-utils.ts
 /**
 * Prefixes error paths with a nav field context.
@@ -31,7 +21,7 @@ async function wrapNestedError(navField, fn) {
 		return await fn();
 	} catch (error) {
 		if (error instanceof _atscript_typescript_utils.ValidatorError) throw new _atscript_typescript_utils.ValidatorError(prefixErrorPaths(error.errors, navField));
-		if (error instanceof DbError) throw new DbError(error.code, prefixErrorPaths(error.errors, navField));
+		if (error instanceof require_db_error.DbError) throw new require_db_error.DbError(error.code, prefixErrorPaths(error.errors, navField));
 		throw error;
 	}
 }
@@ -44,14 +34,14 @@ async function enrichFkViolation(meta, fn) {
 	try {
 		return await fn();
 	} catch (error) {
-		if (error instanceof DbError && error.code === "FK_VIOLATION" && error.errors.every((err) => !err.path)) {
+		if (error instanceof require_db_error.DbError && error.code === "FK_VIOLATION" && error.errors.every((err) => !err.path)) {
 			const msg = error.errors[0]?.message ?? error.message;
 			const errors = [];
 			for (const [, fk] of meta.foreignKeys) for (const field of fk.fields) errors.push({
 				path: field,
 				message: msg
 			});
-			throw new DbError("FK_VIOLATION", errors.length > 0 ? errors : error.errors);
+			throw new require_db_error.DbError("FK_VIOLATION", errors.length > 0 ? errors : error.errors);
 		}
 		throw error;
 	}
@@ -64,7 +54,7 @@ async function remapDeleteFkViolation(tableName, fn) {
 	try {
 		return await fn();
 	} catch (error) {
-		if (error instanceof DbError && error.code === "FK_VIOLATION") throw new DbError("CONFLICT", [{
+		if (error instanceof require_db_error.DbError && error.code === "FK_VIOLATION") throw new require_db_error.DbError("CONFLICT", [{
 			path: tableName,
 			message: `Cannot delete from "${tableName}": referenced by child records (RESTRICT)`
 		}]);
@@ -89,10 +79,13 @@ function validateBatch(validator, items, ctx) {
 	for (let i = 0; i < items.length; i++) try {
 		validator.validate(items[i], false, ctx);
 	} catch (error) {
-		if (error instanceof _atscript_typescript_utils.ValidatorError && items.length > 1) throw new _atscript_typescript_utils.ValidatorError(error.errors.map((err) => ({
-			...err,
-			path: `[${i}].${err.path}`
-		})));
+		if (items.length > 1) {
+			if (error instanceof _atscript_typescript_utils.ValidatorError) throw new _atscript_typescript_utils.ValidatorError(error.errors.map((err) => ({
+				...err,
+				path: `[${i}].${err.path}`
+			})));
+			if (error instanceof require_db_error.DepthLimitExceededError) throw new require_db_error.DepthLimitExceededError(`[${i}].${error.field}`, error.declared, error.actual);
+		}
 		throw error;
 	}
 }
@@ -321,13 +314,13 @@ async function batchPatchNestedTo(host, items, maxDepth, depth) {
 					filter: pkFilter,
 					controls: {}
 				});
-				if (!current) throw new DbError("NOT_FOUND", [{
+				if (!current) throw new require_db_error.DbError("NOT_FOUND", [{
 					path: navField,
 					message: `Cannot patch relation '${navField}' — source record not found`
 				}]);
 				fkValue = fk.localFields.length === 1 ? current[fk.localFields[0]] : void 0;
 			}
-			if (fkValue === null || fkValue === void 0) throw new DbError("FK_VIOLATION", [{
+			if (fkValue === null || fkValue === void 0) throw new require_db_error.DbError("FK_VIOLATION", [{
 				path: fk.localFields[0],
 				message: `Cannot patch relation '${navField}' — foreign key '${fk.localFields[0]}' is null`
 			}]);
@@ -621,12 +614,6 @@ async function viaReplace(targetTable, junctionTable, targets, parentPK, targetP
 	}
 }
 //#endregion
-Object.defineProperty(exports, "DbError", {
-	enumerable: true,
-	get: function() {
-		return DbError;
-	}
-});
 Object.defineProperty(exports, "batchInsertNestedFrom", {
 	enumerable: true,
 	get: function() {

package/dist/ops.d.mts

@@ -1,2 +1,2 @@
-import { a as $remove, c as $upsert, d as getDbFieldOp, f as isDbFieldOp, i as $mul, l as TDbFieldOp, n as $inc, o as $replace, p as separateFieldOps, r as $insert, s as $update, t as $dec, u as TFieldOps } from "./ops-DcHDxrjX.mjs";
+import { a as $remove, c as $upsert, d as getDbFieldOp, f as isDbFieldOp, i as $mul, l as TDbFieldOp, n as $inc, o as $replace, p as separateFieldOps, r as $insert, s as $update, t as $dec, u as TFieldOps } from "./ops-C61kelof.mjs";
 export { $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, TDbFieldOp, TFieldOps, getDbFieldOp, isDbFieldOp, separateFieldOps };

package/dist/plugin.cjs

@@ -2,7 +2,7 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_validation_utils = require("./validation-utils-BiG3pLP0.cjs");
+const require_validation_utils = require("./validation-utils-B9WJv9aH.cjs");
 let _atscript_core = require("@atscript/core");
 //#region src/plugin/annotations/agg.ts
 const dbAggAnnotations = { agg: {
@@ -155,7 +155,9 @@ const dbColumnAnnotations = {
 			validate(token, _args, doc) {
 				return require_validation_utils.validateFieldBaseType(token, doc, "@db.column.measure", ["number", "decimal"]);
 			}
-		})
+		}),
+		filterable: columnCapability("filterable", "filtering"),
+		sortable: columnCapability("sortable", "sorting")
 	},
 	default: {
 		$self: new _atscript_core.AnnotationSpec({
@@ -226,6 +228,30 @@ const dbColumnAnnotations = {
 		}
 	})
 };
+function columnCapability(capability, verb) {
+	const example = capability === "filterable" ? "  @db.column.filterable\n  email: string\n" : "  @db.column.sortable\n  createdAt: number.timestamp\n";
+	return new _atscript_core.AnnotationSpec({
+		description: `Marks a column as ${capability} in the readable controller's query/pages endpoints. Relevant only when the host \`@db.table\` interface opts into strict mode with \`@db.table.${capability} 'manual'\`; otherwise ${verb} is open on all columns (default-open, back-compat).
+
+**Example:**
+\`\`\`atscript
+@db.table "users"
+@db.table.${capability} "manual"\nexport interface User {
+` + example + "}\n```\n",
+		nodeType: ["prop"],
+		multiple: false,
+		validate(token, _args, _doc) {
+			const errors = [];
+			const owner = require_validation_utils.getDbTableOwner(token);
+			if (!owner || owner.countAnnotations("db.table") === 0) errors.push({
+				message: `@db.column.${capability} is only valid on fields of a @db.table interface`,
+				severity: 1,
+				range: token.range
+			});
+			return errors;
+		}
+	});
+}
 //#endregion
 //#region src/plugin/annotations/index-ann.ts
 const dbIndexAnnotations = { index: {
@@ -281,7 +307,7 @@ const dbIndexAnnotations = { index: {
 //#region src/plugin/annotations/rel.ts
 const dbRelAnnotations = { rel: {
 	FK: new _atscript_core.AnnotationSpec({
-		description: "Declares a foreign key constraint on this field. The field must use a chain reference type (e.g., `User.id`) to specify the FK target.\n\n**Example:**\n```atscript\n@db.rel.FK\nauthorId: User.id\n\n// With alias (required when multiple FKs point to the same type)\n@db.rel.FK \"author\"\nauthorId: User.id\n```\n",
+		description: "Declares a foreign key reference on this field. The field must use a chain reference type (e.g., `User.id`) whose target is a primary key (`@meta.id`) or unique (`@db.index.unique`) field.\n\n**Dual role:**\n- On a `@db.table` interface, `@db.rel.FK` additionally drives DB-relation semantics —   relation loading with `@db.rel.to` / `@db.rel.from`, junction pairing with `@db.rel.via`, etc.\n- On any other interface (value-help sources, WF forms, plain interfaces), `@db.rel.FK`   acts purely as the value-help indicator: the client-side picker resolver uses it to   decide which fields render a value-help picker. The target's `@db.http.path` (stamped   by its readable controller) supplies the picker URL.\n\n**Example:**\n```atscript\n@db.rel.FK\nauthorId: User.id\n\n// With alias (required when multiple FKs point to the same type)\n@db.rel.FK \"author\"\nauthorId: User.id\n```\n",
 		nodeType: ["prop"],
 		argument: {
 			optional: true,
@@ -293,12 +319,6 @@ const dbRelAnnotations = { rel: {
 			const errors = [];
 			const field = token.parentNode;
 			const alias = args[0]?.text;
-			const owner = require_validation_utils.getDbTableOwner(token);
-			if (!owner || owner.countAnnotations("db.table") === 0) errors.push({
-				message: "@db.rel.FK is only valid on fields of a @db.table interface",
-				severity: 1,
-				range: token.range
-			});
 			if (field.countAnnotations("db.rel.to") > 0 || field.countAnnotations("db.rel.from") > 0) errors.push({
 				message: "A field cannot be both a foreign key and a navigational property",
 				severity: 1,
@@ -705,6 +725,8 @@ const dbSearchAnnotations = { search: {
 //#region src/plugin/annotations/table.ts
 const dbTableAnnotations = {
 	table: {
+		filterable: tableCapability("filterable"),
+		sortable: tableCapability("sortable"),
 		$self: new _atscript_core.AnnotationSpec({
 			description: "Marks an interface as a database-persisted entity (table in SQL, collection in MongoDB). If the name argument is omitted, the adapter derives the table name from the interface name.\n\n**Example:**\n```atscript\n@db.table \"users\"\nexport interface User { ... }\n```\n",
 			nodeType: ["interface"],
@@ -771,8 +793,75 @@ const dbTableAnnotations = {
 			description: "Sync method: \"drop\" (lossy) or \"recreate\" (lossless with data copy).",
 			values: ["drop", "recreate"]
 		}
+	}) },
+	depth: { limit: new _atscript_core.AnnotationSpec({
+		description: "Security guard on nested-write payloads. `N` is a non-negative integer declaring the maximum depth a client may nest `@db.rel.from` children in insert, replace, or patch payloads. Writes deeper than `N` are rejected at the server boundary with HTTP 400 before any DB access.\n\n**Default when absent:** `0` — any nested-write payload is rejected. Authors opt in explicitly to `N >= 1` when they want the server to accept deep writes. This is a security / blast-radius control, not a performance knob.\n\n**Scope:** affects only write acceptance. Has no effect on `/meta` serialization, read/query paths, or wire shape — the meta endpoint always ships FK refs as the shallow `{ id, metadata }` shape regardless of this annotation.\n\n**Example:**\n```atscript\n@db.table \"authors\"\n@db.depth.limit 2\nexport interface Author { ... }\n```\n",
+		nodeType: ["interface"],
+		multiple: false,
+		argument: {
+			name: "depth",
+			type: "number",
+			description: "Non-negative integer: maximum nesting depth accepted for nested writes."
+		},
+		validate(token, args, _doc) {
+			const errors = [];
+			const owner = token.parentNode;
+			if (owner.countAnnotations("db.table") === 0) errors.push({
+				message: "@db.depth.limit is only valid on @db.table interfaces",
+				severity: 1,
+				range: token.range
+			});
+			if (owner.countAnnotations("db.depth.limit") > 1) errors.push({
+				message: "Multiple @db.depth.limit annotations on the same interface",
+				severity: 1,
+				range: token.range
+			});
+			const raw = args[0]?.text;
+			if (raw !== void 0) {
+				const num = Number(raw);
+				if (!Number.isFinite(num) || !Number.isInteger(num) || num < 0) errors.push({
+					message: `@db.depth.limit depth must be a non-negative integer, got '${raw}'`,
+					severity: 1,
+					range: args[0].range
+				});
+			}
+			return errors;
+		}
 	}) }
 };
+function tableCapability(capability) {
+	const example = capability === "filterable" ? "  @db.column.filterable\n  email: string\n  // other fields not filterable via the controller\n" : "  @db.column.sortable\n  createdAt: number.timestamp\n  // other fields not sortable via the controller\n";
+	const verb = capability === "filterable" ? "filter" : "sort";
+	return new _atscript_core.AnnotationSpec({
+		description: `Controls ${verb}-gating on the readable controller's \`/query\` and \`/pages\` endpoints.\n\n- **\`'auto'\`** (default when the annotation is absent) — every column is ${capability}.\n- **\`'manual'\`** — only fields annotated \`@db.column.${capability}\` are ${capability};   all others are rejected with HTTP 400.
+
+Writing the annotation explicitly as \`@db.table.${capability} 'auto'\` has the same runtime effect as omitting it; use it to document intent.
+
+**Example:**
+\`\`\`atscript
+@db.table "users"
+@db.table.${capability} "manual"\nexport interface User {
+` + example + "}\n```\n",
+		nodeType: ["interface"],
+		multiple: false,
+		argument: {
+			optional: true,
+			name: "mode",
+			type: "string",
+			description: `${verb[0].toUpperCase()}${verb.slice(1)}-gating mode: 'auto' (default) or 'manual'.`,
+			values: ["auto", "manual"]
+		},
+		validate(token, _args, _doc) {
+			const errors = [];
+			if (token.parentNode.countAnnotations("db.table") === 0) errors.push({
+				message: `@db.table.${capability} requires @db.table on the same interface`,
+				severity: 1,
+				range: token.range
+			});
+			return errors;
+		}
+	});
+}
 //#endregion
 //#region src/plugin/annotations/view.ts
 const dbViewAnnotations = { view: {
@@ -964,6 +1053,7 @@ const dbPlugin = () => ({
 				ignore: dbColumnAnnotations.ignore,
 				http: dbTableAnnotations.http,
 				sync: dbTableAnnotations.sync,
+				depth: dbTableAnnotations.depth,
 				rel: dbRelAnnotations.rel,
 				view: dbViewAnnotations.view,
 				agg: dbAggAnnotations.agg,