@atscript/db 0.1.127 → 0.1.128

package/dist/index.mjs

@@ -1,8 +1,8 @@
 import { n as DbError, t as CasExhaustedError } from "./db-error-BHPXOKzc.mjs";
-import { C as NoopLogger, S as isGeoPointType, _ as DocumentFieldMapper, a as ApplicationIntegrity, b as TableMetadata, c as IntegrityStrategy, d as resolveDesignType, f as assertGeoPoint, g as RelationalFieldMapper, h as guardQuery, i as decomposePatch, l as NativeIntegrity, m as guardFilter, n as AtscriptDbTable, o as BaseDbAdapter, p as guardAggregate, r as assertNoVersionWrites, s as createFailureCollector, t as AtscriptDbView, u as AtscriptDbReadable, v as FieldMappingStrategy, x as isGeoIndexableType, y as UniquSelect } from "./db-view-C8rZM5_N.mjs";
+import { A as isGeoIndexableType, C as unsupportedOperatorMessage, D as UniquSelect, E as FieldMappingStrategy, M as NoopLogger, O as TableMetadata, S as sortFieldNames, T as DocumentFieldMapper, _ as guardAggregate, a as decomposePatch, b as guardPaths, c as createFailureCollector, d as AtscriptDbReadable, f as resolveDesignType, g as collectQueryPaths, h as classifyQueryPath, i as assertNoVersionWrites, j as isGeoPointType, k as findAncestorInSet, l as IntegrityStrategy, m as checkHavingKeys, n as isAtscriptDbView, o as ApplicationIntegrity, p as assertGeoPoint, r as AtscriptDbTable, s as BaseDbAdapter, t as AtscriptDbView, u as NativeIntegrity, v as guardFilter, w as RelationalFieldMapper, x as guardQuery, y as guardPath } from "./db-view-Ck0I-PMI.mjs";
+import { a as forceNavNonOptional, c as getKeyProps, l as isEmptyObject, o as isNavRelation, r as buildValidationContext, s as createDbValidatorPlugin, t as buildDbValidator, u as isPlainObject } from "./validator-eKYWf3xf.mjs";
 import { t as DEFAULT_DB_SPACE } from "./consts-C_-5_pFq.mjs";
-import { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, getDbFieldOp, isDbFieldOp, separateCas, separateFieldOps } from "./ops.mjs";
-import { a as forceNavNonOptional, c as getKeyProps, o as isNavRelation, r as buildValidationContext, s as createDbValidatorPlugin, t as buildDbValidator } from "./validator-0vRXN51D.mjs";
+import { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, getDbFieldOp, isDbFieldOp, reconcileCas, separateCas, separateFieldOps } from "./ops.mjs";
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 import { computeInsights, isPrimitive, walkFilter } from "@uniqu/core";
 //#region src/encryption.ts
@@ -149,6 +149,11 @@ var DbEncryption = class {
 * a version conflict (`matchedCount === 0`) it re-reads the row, calls the
 * mutator with the fresh state, and retries — up to `maxAttempts` times.
 *
+* A mutator that returns `undefined` or an empty object `{}` aborts without
+* writing: the helper resolves `{ matchedCount: 1, modifiedCount: 0 }` and the
+* version does not move (since 0.1.128 — previously `{}` reported a fabricated
+* match as well, but through the empty-patch short-circuit).
+*
 * The filter (typically the primary key) is threaded into the update payload
 * so the table layer can extract the row identity. If `mutator` returns
 * fields that overlap with the filter, the patch wins (last-write semantics
@@ -178,6 +183,10 @@ async function withOptimisticRetry(table, filter, mutator, opts) {
 		}]);
 		lastSeenVersion = row[versionColumn];
 		const patch = await mutator(row);
+		if (patch === void 0 || isEmptyObject(patch)) return {
+			matchedCount: 1,
+			modifiedCount: 0
+		};
 		const result = await table.updateOne({
 			...filter,
 			...patch,
@@ -293,6 +302,29 @@ var DbSpace = class {
 		const adapter = this._getAdminAdapter();
 		if (adapter.dropViewByName) await adapter.dropViewByName(viewName);
 	}
+	/**
+	* Drops a group of mutually referencing tables as one operation.
+	* Used by schema sync to remove a foreign-key cycle no longer in the schema.
+	* @since 0.1.128
+	*/
+	async dropTablesByName(tableNames) {
+		await this._getAdminAdapter().dropTablesByName(tableNames);
+	}
+	/**
+	* Live foreign keys referencing `tableName`, or `undefined` when the
+	* adapter cannot introspect them. Used by schema sync for drop ordering
+	* and surviving-reference checks of tables without a registered readable.
+	* @since 0.1.128
+	*/
+	async getReferencingForeignKeys(tableName) {
+		return this._getAdminAdapter().getReferencingForeignKeys?.(tableName);
+	}
+	/**
+	* A factory-fresh adapter with NO registered readable. Only the name-taking
+	* primitives may run on it (`dropTableByName`, `dropViewByName`,
+	* `dropTablesByName`, `getReferencingForeignKeys`) — adapters derive the
+	* schema for those from the driver/connection, not from a bound table.
+	*/
 	_getAdminAdapter() {
 		return this._adminAdapter ??= this.adapterFactory();
 	}
@@ -340,4 +372,4 @@ function translateQueryTree(node, resolveField) {
 	return { [leftField]: { [comp.op]: comp.right } };
 }
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, BaseDbAdapter, CasExhaustedError, DEFAULT_DB_SPACE, DbEncryption, DbError, DbSpace, DocumentFieldMapper, FieldMappingStrategy, IntegrityStrategy, NativeIntegrity, NoopLogger, RelationalFieldMapper, TableMetadata, UniquSelect, assertGeoPoint, assertNoVersionWrites, buildDbValidator, buildValidationContext, computeInsights, createDbValidatorPlugin, createFailureCollector, decomposePatch, forceNavNonOptional, getDbFieldOp, getKeyProps, guardAggregate, guardFilter, guardQuery, isDbFieldOp, isGeoIndexableType, isGeoPointType, isNavRelation, isPrimitive, resolveDesignType, separateCas, separateFieldOps, translateQueryTree, walkFilter, withOptimisticRetry };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, BaseDbAdapter, CasExhaustedError, DEFAULT_DB_SPACE, DbEncryption, DbError, DbSpace, DocumentFieldMapper, FieldMappingStrategy, IntegrityStrategy, NativeIntegrity, NoopLogger, RelationalFieldMapper, TableMetadata, UniquSelect, assertGeoPoint, assertNoVersionWrites, buildDbValidator, buildValidationContext, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, createDbValidatorPlugin, createFailureCollector, decomposePatch, findAncestorInSet, forceNavNonOptional, getDbFieldOp, getKeyProps, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, isAtscriptDbView, isDbFieldOp, isEmptyObject, isGeoIndexableType, isGeoPointType, isNavRelation, isPlainObject, isPrimitive, reconcileCas, resolveDesignType, separateCas, separateFieldOps, sortFieldNames, translateQueryTree, unsupportedOperatorMessage, walkFilter, withOptimisticRetry };

package/dist/{ops-DJRnNTVo.d.cts → ops-AqhV7s9o.d.cts}

@@ -109,6 +109,29 @@ declare function separateFieldOps(data: Record<string, unknown>): TFieldOps | un
  *
  * Zero-allocation on the no-op (no `$cas`) path.
  */
+/**
+ * Reconciles the two spellings of one write item's expected version, in
+ * place (since 0.1.128): the SDK operator `$cas: { [versionColumn]: N }` and a
+ * top-level `[versionColumn]: N` (the HTTP wire shape, where a body's version
+ * column is a CAS predicate, not a SET). Shared by the moost-db controller
+ * (`target: "cas"` — normalises to `$cas` for the table) and the db-client
+ * (`target: "version"` — normalises to the wire shape).
+ *
+ * - neither present → no-op, returns `undefined`
+ * - one present → normalised to `target`, returns the expected version
+ * - both present and equal → normalised once
+ * - both present and different → `DbError("INVALID_QUERY")` at path `$cas`:
+ *   `Ambiguous version: "<col>" and "$cas.<col>" differ`
+ * - `$cas` malformed → {@link separateCas}'s own error (checked first, so a
+ *   malformed `$cas` is never reported as "ambiguous")
+ * - `$cas: undefined` counts as absent (the key is dropped)
+ * - `versionColumn === undefined` with a `$cas` → {@link separateCas}'s
+ *   "table has no @db.column.version" error
+ *
+ * Only a finite number counts as a present version column value — anything
+ * else is left untouched for the write validator to reject.
+ */
+declare function reconcileCas(data: Record<string, unknown>, versionColumn: string | undefined, target: "cas" | "version"): number | undefined;
 declare function separateCas(data: Record<string, unknown>, versionColumn?: string): number | undefined;
 //#endregion
-export { $mul as a, $update as c, TDbFieldOp as d, TFieldOps as f, separateFieldOps as g, separateCas as h, $insert as i, $upsert as l, isDbFieldOp as m, $dec as n, $remove as o, getDbFieldOp as p, $inc as r, $replace as s, $cas as t, TDbCas as u };
+export { separateFieldOps as _, $mul as a, $update as c, TDbFieldOp as d, TFieldOps as f, separateCas as g, reconcileCas as h, $insert as i, $upsert as l, isDbFieldOp as m, $dec as n, $remove as o, getDbFieldOp as p, $inc as r, $replace as s, $cas as t, TDbCas as u };

package/dist/{ops-DJRnNTVo.d.mts → ops-AqhV7s9o.d.mts}

@@ -109,6 +109,29 @@ declare function separateFieldOps(data: Record<string, unknown>): TFieldOps | un
  *
  * Zero-allocation on the no-op (no `$cas`) path.
  */
+/**
+ * Reconciles the two spellings of one write item's expected version, in
+ * place (since 0.1.128): the SDK operator `$cas: { [versionColumn]: N }` and a
+ * top-level `[versionColumn]: N` (the HTTP wire shape, where a body's version
+ * column is a CAS predicate, not a SET). Shared by the moost-db controller
+ * (`target: "cas"` — normalises to `$cas` for the table) and the db-client
+ * (`target: "version"` — normalises to the wire shape).
+ *
+ * - neither present → no-op, returns `undefined`
+ * - one present → normalised to `target`, returns the expected version
+ * - both present and equal → normalised once
+ * - both present and different → `DbError("INVALID_QUERY")` at path `$cas`:
+ *   `Ambiguous version: "<col>" and "$cas.<col>" differ`
+ * - `$cas` malformed → {@link separateCas}'s own error (checked first, so a
+ *   malformed `$cas` is never reported as "ambiguous")
+ * - `$cas: undefined` counts as absent (the key is dropped)
+ * - `versionColumn === undefined` with a `$cas` → {@link separateCas}'s
+ *   "table has no @db.column.version" error
+ *
+ * Only a finite number counts as a present version column value — anything
+ * else is left untouched for the write validator to reject.
+ */
+declare function reconcileCas(data: Record<string, unknown>, versionColumn: string | undefined, target: "cas" | "version"): number | undefined;
 declare function separateCas(data: Record<string, unknown>, versionColumn?: string): number | undefined;
 //#endregion
-export { $mul as a, $update as c, TDbFieldOp as d, TFieldOps as f, separateFieldOps as g, separateCas as h, $insert as i, $upsert as l, isDbFieldOp as m, $dec as n, $remove as o, getDbFieldOp as p, $inc as r, $replace as s, $cas as t, TDbCas as u };
+export { separateFieldOps as _, $mul as a, $update as c, TDbFieldOp as d, TFieldOps as f, separateCas as g, reconcileCas as h, $insert as i, $upsert as l, isDbFieldOp as m, $dec as n, $remove as o, getDbFieldOp as p, $inc as r, $replace as s, $cas as t, TDbCas as u };

package/dist/ops.cjs

@@ -144,6 +144,48 @@ function separateFieldOps(data) {
 *
 * Zero-allocation on the no-op (no `$cas`) path.
 */
+/**
+* Reconciles the two spellings of one write item's expected version, in
+* place (since 0.1.128): the SDK operator `$cas: { [versionColumn]: N }` and a
+* top-level `[versionColumn]: N` (the HTTP wire shape, where a body's version
+* column is a CAS predicate, not a SET). Shared by the moost-db controller
+* (`target: "cas"` — normalises to `$cas` for the table) and the db-client
+* (`target: "version"` — normalises to the wire shape).
+*
+* - neither present → no-op, returns `undefined`
+* - one present → normalised to `target`, returns the expected version
+* - both present and equal → normalised once
+* - both present and different → `DbError("INVALID_QUERY")` at path `$cas`:
+*   `Ambiguous version: "<col>" and "$cas.<col>" differ`
+* - `$cas` malformed → {@link separateCas}'s own error (checked first, so a
+*   malformed `$cas` is never reported as "ambiguous")
+* - `$cas: undefined` counts as absent (the key is dropped)
+* - `versionColumn === undefined` with a `$cas` → {@link separateCas}'s
+*   "table has no @db.column.version" error
+*
+* Only a finite number counts as a present version column value — anything
+* else is left untouched for the write validator to reject.
+*/
+function reconcileCas(data, versionColumn, target) {
+	if ("$cas" in data && data.$cas === void 0) delete data.$cas;
+	const versionValue = versionColumn === void 0 ? void 0 : data[versionColumn];
+	const hasVersion = typeof versionValue === "number" && Number.isFinite(versionValue);
+	const hasCas = "$cas" in data;
+	if (!hasCas && !hasVersion) return void 0;
+	let expected;
+	if (hasCas) {
+		expected = separateCas(data, versionColumn);
+		if (hasVersion && versionValue !== expected) throw new require_db_error.DbError("INVALID_QUERY", [{
+			path: "$cas",
+			message: `Ambiguous version: "${versionColumn}" and "$cas.${versionColumn}" differ`
+		}]);
+	} else expected = versionValue;
+	if (target === "cas") {
+		delete data[versionColumn];
+		data.$cas = { [versionColumn]: expected };
+	} else data[versionColumn] = expected;
+	return expected;
+}
 function separateCas(data, versionColumn) {
 	if (!("$cas" in data)) return void 0;
 	if (versionColumn === void 0) throw new require_db_error.DbError("INVALID_QUERY", [{
@@ -192,5 +234,6 @@ exports.$update = $update;
 exports.$upsert = $upsert;
 exports.getDbFieldOp = getDbFieldOp;
 exports.isDbFieldOp = isDbFieldOp;
+exports.reconcileCas = reconcileCas;
 exports.separateCas = separateCas;
 exports.separateFieldOps = separateFieldOps;

package/dist/ops.d.cts

@@ -1,2 +1,2 @@
-import { a as $mul, c as $update, d as TDbFieldOp, f as TFieldOps, g as separateFieldOps, h as separateCas, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, p as getDbFieldOp, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-DJRnNTVo.cjs";
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, TDbCas, TDbFieldOp, TFieldOps, getDbFieldOp, isDbFieldOp, separateCas, separateFieldOps };
+import { _ as separateFieldOps, a as $mul, c as $update, d as TDbFieldOp, f as TFieldOps, g as separateCas, h as reconcileCas, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, p as getDbFieldOp, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-AqhV7s9o.cjs";
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, TDbCas, TDbFieldOp, TFieldOps, getDbFieldOp, isDbFieldOp, reconcileCas, separateCas, separateFieldOps };

package/dist/ops.d.mts

@@ -1,2 +1,2 @@
-import { a as $mul, c as $update, d as TDbFieldOp, f as TFieldOps, g as separateFieldOps, h as separateCas, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, p as getDbFieldOp, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-DJRnNTVo.mjs";
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, TDbCas, TDbFieldOp, TFieldOps, getDbFieldOp, isDbFieldOp, separateCas, separateFieldOps };
+import { _ as separateFieldOps, a as $mul, c as $update, d as TDbFieldOp, f as TFieldOps, g as separateCas, h as reconcileCas, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, p as getDbFieldOp, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-AqhV7s9o.mjs";
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, TDbCas, TDbFieldOp, TFieldOps, getDbFieldOp, isDbFieldOp, reconcileCas, separateCas, separateFieldOps };

package/dist/ops.mjs

@@ -143,6 +143,48 @@ function separateFieldOps(data) {
 *
 * Zero-allocation on the no-op (no `$cas`) path.
 */
+/**
+* Reconciles the two spellings of one write item's expected version, in
+* place (since 0.1.128): the SDK operator `$cas: { [versionColumn]: N }` and a
+* top-level `[versionColumn]: N` (the HTTP wire shape, where a body's version
+* column is a CAS predicate, not a SET). Shared by the moost-db controller
+* (`target: "cas"` — normalises to `$cas` for the table) and the db-client
+* (`target: "version"` — normalises to the wire shape).
+*
+* - neither present → no-op, returns `undefined`
+* - one present → normalised to `target`, returns the expected version
+* - both present and equal → normalised once
+* - both present and different → `DbError("INVALID_QUERY")` at path `$cas`:
+*   `Ambiguous version: "<col>" and "$cas.<col>" differ`
+* - `$cas` malformed → {@link separateCas}'s own error (checked first, so a
+*   malformed `$cas` is never reported as "ambiguous")
+* - `$cas: undefined` counts as absent (the key is dropped)
+* - `versionColumn === undefined` with a `$cas` → {@link separateCas}'s
+*   "table has no @db.column.version" error
+*
+* Only a finite number counts as a present version column value — anything
+* else is left untouched for the write validator to reject.
+*/
+function reconcileCas(data, versionColumn, target) {
+	if ("$cas" in data && data.$cas === void 0) delete data.$cas;
+	const versionValue = versionColumn === void 0 ? void 0 : data[versionColumn];
+	const hasVersion = typeof versionValue === "number" && Number.isFinite(versionValue);
+	const hasCas = "$cas" in data;
+	if (!hasCas && !hasVersion) return void 0;
+	let expected;
+	if (hasCas) {
+		expected = separateCas(data, versionColumn);
+		if (hasVersion && versionValue !== expected) throw new DbError("INVALID_QUERY", [{
+			path: "$cas",
+			message: `Ambiguous version: "${versionColumn}" and "$cas.${versionColumn}" differ`
+		}]);
+	} else expected = versionValue;
+	if (target === "cas") {
+		delete data[versionColumn];
+		data.$cas = { [versionColumn]: expected };
+	} else data[versionColumn] = expected;
+	return expected;
+}
 function separateCas(data, versionColumn) {
 	if (!("$cas" in data)) return void 0;
 	if (versionColumn === void 0) throw new DbError("INVALID_QUERY", [{
@@ -180,4 +222,4 @@ function separateCas(data, versionColumn) {
 	return foundValue;
 }
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, getDbFieldOp, isDbFieldOp, separateCas, separateFieldOps };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, getDbFieldOp, isDbFieldOp, reconcileCas, separateCas, separateFieldOps };

package/dist/plugin.cjs

@@ -405,7 +405,13 @@ const dbColumnAnnotations = {
 				description: "Starting value for the auto-increment sequence. Adapter-specific behavior; some adapters may ignore this."
 			},
 			validate(token, args, doc) {
-				return require_validation_utils.validateFieldBaseType(token, doc, "db.default.increment", "number");
+				const errors = require_validation_utils.validateFieldBaseType(token, doc, "db.default.increment", "number");
+				if (token.parentNode.countAnnotations("meta.id") === 0) errors.push({
+					message: `@db.default.increment on a field without @meta.id — auto-increment columns must be primary-key columns for schema sync to manage them`,
+					severity: 2,
+					range: token.range
+				});
+				return errors;
 			}
 		}),
 		uuid: new _atscript_core.AnnotationSpec({
@@ -506,7 +512,7 @@ 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).
+		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 every column the adapter can handle (default-open, back-compat) and the annotation is a no-op. Adapter capability always wins: \`@db.json\` / array columns stay non-sortable (and non-filterable on SQL adapters) even when annotated. \`/meta.fields\` advertises exactly what the gate accepts; index-backed columns additionally carry the advisory \`indexed\` flag.
 
 **Example:**
 \`\`\`atscript
@@ -598,7 +604,7 @@ const dbIndexAnnotations = { index: {
 //#region src/plugin/annotations/rel.ts
 const dbRelAnnotations = { rel: {
 	FK: new _atscript_core.AnnotationSpec({
-		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",
+		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- In `/meta` (and `/meta/form/:name`) the marker is inherited through reference chains:   a field declared as `code: Issue.code` where `Issue.code: Dict.code` carries `@db.rel.FK`   is served with `ref` pointing at the terminal field (`Dict.code`) and `db.rel.FK: true`,   so view fields get the dictionary picker. Runtime metadata is untouched.\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"],
 		passedWhenReferred: false,
 		argument: {
@@ -1211,9 +1217,10 @@ 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.
+		description: `Controls ${verb}-gating on the readable controller's \`/query\` and \`/pages\` endpoints.\n\n- **\`'auto'\`** (default when the annotation is absent) — every column the adapter can ${verb} is ${capability} (JSON / array columns are never sortable, and not filterable on SQL adapters).
+- **\`'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.
+\`/meta.fields[*].` + capability + "` advertises exactly what the gate accepts in either mode. The policy applies to " + (capability === "filterable" ? "filters only — `$groupBy`, `$having` keys and aggregate fields use the adapter's physical capability.\n\n" : "`$sort` only.\n\n") + `Writing the annotation explicitly as \`@db.table.${capability} 'auto'\` has the same runtime effect as omitting it; use it to document intent.
 
 **Example:**
 \`\`\`atscript

package/dist/plugin.mjs

@@ -370,7 +370,13 @@ const dbColumnAnnotations = {
 				description: "Starting value for the auto-increment sequence. Adapter-specific behavior; some adapters may ignore this."
 			},
 			validate(token, args, doc) {
-				return validateFieldBaseType(token, doc, "db.default.increment", "number");
+				const errors = validateFieldBaseType(token, doc, "db.default.increment", "number");
+				if (token.parentNode.countAnnotations("meta.id") === 0) errors.push({
+					message: `@db.default.increment on a field without @meta.id — auto-increment columns must be primary-key columns for schema sync to manage them`,
+					severity: 2,
+					range: token.range
+				});
+				return errors;
 			}
 		}),
 		uuid: new AnnotationSpec({
@@ -471,7 +477,7 @@ 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 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).
+		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 every column the adapter can handle (default-open, back-compat) and the annotation is a no-op. Adapter capability always wins: \`@db.json\` / array columns stay non-sortable (and non-filterable on SQL adapters) even when annotated. \`/meta.fields\` advertises exactly what the gate accepts; index-backed columns additionally carry the advisory \`indexed\` flag.
 
 **Example:**
 \`\`\`atscript
@@ -563,7 +569,7 @@ const dbIndexAnnotations = { index: {
 //#region src/plugin/annotations/rel.ts
 const dbRelAnnotations = { rel: {
 	FK: new AnnotationSpec({
-		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",
+		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- In `/meta` (and `/meta/form/:name`) the marker is inherited through reference chains:   a field declared as `code: Issue.code` where `Issue.code: Dict.code` carries `@db.rel.FK`   is served with `ref` pointing at the terminal field (`Dict.code`) and `db.rel.FK: true`,   so view fields get the dictionary picker. Runtime metadata is untouched.\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"],
 		passedWhenReferred: false,
 		argument: {
@@ -1176,9 +1182,10 @@ 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 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.
+		description: `Controls ${verb}-gating on the readable controller's \`/query\` and \`/pages\` endpoints.\n\n- **\`'auto'\`** (default when the annotation is absent) — every column the adapter can ${verb} is ${capability} (JSON / array columns are never sortable, and not filterable on SQL adapters).
+- **\`'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.
+\`/meta.fields[*].` + capability + "` advertises exactly what the gate accepts in either mode. The policy applies to " + (capability === "filterable" ? "filters only — `$groupBy`, `$having` keys and aggregate fields use the adapter's physical capability.\n\n" : "`$sort` only.\n\n") + `Writing the annotation explicitly as \`@db.table.${capability} 'auto'\` has the same runtime effect as omitting it; use it to document intent.
 
 **Example:**
 \`\`\`atscript

package/dist/rel.d.cts

@@ -1,4 +1,4 @@
-import { L as TDbForeignKey, W as TDbRelation, _t as TGenericLogger, c as BaseDbAdapter, ct as TWriteTableResolver, ot as TTableResolver, pt as TableMetadata } from "./db-readable-C0nDKX8A.cjs";
+import { B as TDbForeignKey, Ct as TWriteTableResolver, J as TDbRelation, Nt as TGenericLogger, Ot as TableMetadata, bt as TTableResolver, c as BaseDbAdapter } from "./db-readable-CkbZn_z-.cjs";
 import { t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.cjs";
 import { FilterExpr, WithRelation } from "@uniqu/core";
 import { Validator } from "@atscript/typescript/utils";

package/dist/rel.d.mts

@@ -1,4 +1,4 @@
-import { L as TDbForeignKey, W as TDbRelation, _t as TGenericLogger, c as BaseDbAdapter, ct as TWriteTableResolver, ot as TTableResolver, pt as TableMetadata } from "./db-readable-BkAGccv9.mjs";
+import { B as TDbForeignKey, Ct as TWriteTableResolver, J as TDbRelation, Nt as TGenericLogger, Ot as TableMetadata, bt as TTableResolver, c as BaseDbAdapter } from "./db-readable-BTl4NzNN.mjs";
 import { t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.mjs";
 import { Validator } from "@atscript/typescript/utils";
 import { FilterExpr, WithRelation } from "@uniqu/core";