@atscript/db 0.1.63 → 0.1.65

package/dist/{db-readable-D3bZPucw.d.cts → db-readable-BZN2QKud.d.cts}

@@ -83,6 +83,8 @@ declare class TableMetadata {
   columnMap: Map<string, string>;
   dimensions: string[];
   measures: string[];
+  /** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
+  quantityRefByField: Map<string, string>;
   pathToPhysical: Map<string, string>;
   physicalToPath: Map<string, string>;
   flattenedParents: Set<string>;
@@ -394,6 +396,14 @@ interface TDbFieldMeta {
   collate?: TDbCollation;
   /** Whether this field participates in any index (@db.index.plain, @db.index.unique, @db.index.fulltext). */
   isIndexed?: boolean;
+  /** Literal currency code from `@db.amount.currency 'EUR'`. */
+  currencyCode?: string;
+  /** Sibling field path from `@db.amount.currency.ref 'fieldName'`. */
+  currencyRefField?: string;
+  /** Literal unit-of-measure from `@db.unit 'kg'`. */
+  unitCode?: string;
+  /** Sibling field path from `@db.unit.ref 'fieldName'`. */
+  unitRefField?: string;
   /**
    * For FK fields: the resolved field metadata of the referenced (target) PK column.
    * Adapters use this in `typeMapper` to produce matching DB types for FK columns
@@ -738,6 +748,27 @@ declare abstract class BaseDbAdapter {
    * by finding child records and deleting/nullifying them before the parent.
    */
   supportsNativeForeignKeys(): boolean;
+  /**
+   * Whether this adapter can apply equality/range filters on a given field.
+   * Default: scalar columns yes, JSON-stored columns (arrays, `@db.json`
+   * objects) no — most SQL engines cannot filter into a raw JSON value.
+   *
+   * Adapters that natively understand JSON storage (e.g. MongoDB filters arrays
+   * with implicit `$in` and dot-paths into embedded documents) override to
+   * return `true` for `storage === 'json'`.
+   *
+   * Used by `AsDbReadableController.buildMetaResponse()` to gate the
+   * `filterable` flag exposed to UIs — the adapter's answer is a hard gate
+   * even when the field carries `@db.column.filterable`.
+   */
+  canFilterField(fd: TDbFieldMeta): boolean;
+  /**
+   * Whether this adapter can sort by a given field.
+   * Default: scalar columns yes, JSON-stored columns no. Mongo's array sort
+   * (min/max element) is a footgun for generic UI sort headers, so the default
+   * stays conservative even for adapters that technically support it.
+   */
+  canSortField(fd: TDbFieldMeta): boolean;
   /**
    * Whether this adapter handles `$with` relation loading natively.
    * When `true`, the table layer delegates to {@link loadRelations}
@@ -1322,6 +1353,10 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   aggregate(query: AggregateQuery): Promise<Array<Record<string, unknown>>>;
   /** Whether the underlying adapter supports text search. */
   isSearchable(): boolean;
+  /** Whether the adapter can filter on a given field (proxies adapter capability). */
+  canFilterField(fd: TDbFieldMeta): boolean;
+  /** Whether the adapter can sort by a given field (proxies adapter capability). */
+  canSortField(fd: TDbFieldMeta): boolean;
   /** Returns available search indexes from the adapter. */
   getSearchIndexes(): TSearchIndexInfo[];
   /**

package/dist/{db-readable-Dj9to0bC.d.mts → db-readable-vjbawUvu.d.mts}

@@ -83,6 +83,8 @@ declare class TableMetadata {
   columnMap: Map<string, string>;
   dimensions: string[];
   measures: string[];
+  /** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
+  quantityRefByField: Map<string, string>;
   pathToPhysical: Map<string, string>;
   physicalToPath: Map<string, string>;
   flattenedParents: Set<string>;
@@ -394,6 +396,14 @@ interface TDbFieldMeta {
   collate?: TDbCollation;
   /** Whether this field participates in any index (@db.index.plain, @db.index.unique, @db.index.fulltext). */
   isIndexed?: boolean;
+  /** Literal currency code from `@db.amount.currency 'EUR'`. */
+  currencyCode?: string;
+  /** Sibling field path from `@db.amount.currency.ref 'fieldName'`. */
+  currencyRefField?: string;
+  /** Literal unit-of-measure from `@db.unit 'kg'`. */
+  unitCode?: string;
+  /** Sibling field path from `@db.unit.ref 'fieldName'`. */
+  unitRefField?: string;
   /**
    * For FK fields: the resolved field metadata of the referenced (target) PK column.
    * Adapters use this in `typeMapper` to produce matching DB types for FK columns
@@ -738,6 +748,27 @@ declare abstract class BaseDbAdapter {
    * by finding child records and deleting/nullifying them before the parent.
    */
   supportsNativeForeignKeys(): boolean;
+  /**
+   * Whether this adapter can apply equality/range filters on a given field.
+   * Default: scalar columns yes, JSON-stored columns (arrays, `@db.json`
+   * objects) no — most SQL engines cannot filter into a raw JSON value.
+   *
+   * Adapters that natively understand JSON storage (e.g. MongoDB filters arrays
+   * with implicit `$in` and dot-paths into embedded documents) override to
+   * return `true` for `storage === 'json'`.
+   *
+   * Used by `AsDbReadableController.buildMetaResponse()` to gate the
+   * `filterable` flag exposed to UIs — the adapter's answer is a hard gate
+   * even when the field carries `@db.column.filterable`.
+   */
+  canFilterField(fd: TDbFieldMeta): boolean;
+  /**
+   * Whether this adapter can sort by a given field.
+   * Default: scalar columns yes, JSON-stored columns no. Mongo's array sort
+   * (min/max element) is a footgun for generic UI sort headers, so the default
+   * stays conservative even for adapters that technically support it.
+   */
+  canSortField(fd: TDbFieldMeta): boolean;
   /**
    * Whether this adapter handles `$with` relation loading natively.
    * When `true`, the table layer delegates to {@link loadRelations}
@@ -1322,6 +1353,10 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   aggregate(query: AggregateQuery): Promise<Array<Record<string, unknown>>>;
   /** Whether the underlying adapter supports text search. */
   isSearchable(): boolean;
+  /** Whether the adapter can filter on a given field (proxies adapter capability). */
+  canFilterField(fd: TDbFieldMeta): boolean;
+  /** Whether the adapter can sort by a given field (proxies adapter capability). */
+  canSortField(fd: TDbFieldMeta): boolean;
   /** Returns available search indexes from the adapter. */
   getSearchIndexes(): TSearchIndexInfo[];
   /**

package/dist/{db-space-CK11BW4j.d.cts → db-space-CxGLp-no.d.mts}

@@ -1,6 +1,6 @@
-import { B as TDbInsertResult, J as TFkLookupResolver, N as TDbDeleteResult, W as TDbUpdateResult, dt as TableMetadata, it as TTableResolver, o as BaseDbAdapter, ot as TWriteTableResolver, pt as TGenericLogger, t as AtscriptDbReadable, x as TCascadeResolver, z as TDbInsertManyResult } from "./db-readable-D3bZPucw.cjs";
-import { FilterExpr } from "@uniqu/core";
+import { B as TDbInsertResult, J as TFkLookupResolver, N as TDbDeleteResult, W as TDbUpdateResult, dt as TableMetadata, it as TTableResolver, o as BaseDbAdapter, ot as TWriteTableResolver, pt as TGenericLogger, t as AtscriptDbReadable, x as TCascadeResolver, z as TDbInsertManyResult } from "./db-readable-vjbawUvu.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
 /**

package/dist/{db-space-Dy4GqZrK.d.mts → db-space-Dnjxe6Bt.d.cts}

@@ -1,6 +1,6 @@
-import { B as TDbInsertResult, J as TFkLookupResolver, N as TDbDeleteResult, W as TDbUpdateResult, dt as TableMetadata, it as TTableResolver, o as BaseDbAdapter, ot as TWriteTableResolver, pt as TGenericLogger, t as AtscriptDbReadable, x as TCascadeResolver, z as TDbInsertManyResult } from "./db-readable-Dj9to0bC.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 { B as TDbInsertResult, J as TFkLookupResolver, N as TDbDeleteResult, W as TDbUpdateResult, dt as TableMetadata, it as TTableResolver, o as BaseDbAdapter, ot as TWriteTableResolver, pt as TGenericLogger, t as AtscriptDbReadable, x as TCascadeResolver, z as TDbInsertManyResult } from "./db-readable-BZN2QKud.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
 /**

package/dist/{db-view-Jj46sTBk.cjs → db-view-B028LhoI.cjs}

@@ -64,6 +64,8 @@ var TableMetadata = class {
 	columnMap = /* @__PURE__ */ new Map();
 	dimensions = [];
 	measures = [];
+	/** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
+	quantityRefByField = /* @__PURE__ */ new Map();
 	pathToPhysical = /* @__PURE__ */ new Map();
 	physicalToPath = /* @__PURE__ */ new Map();
 	flattenedParents = /* @__PURE__ */ new Set();
@@ -361,6 +363,12 @@ var TableMetadata = class {
 			const fromLocal = this._columnFromMap.get(path);
 			let renamedFrom;
 			if (fromLocal) renamedFrom = isFlattened ? this._flattenedPrefix(path) + fromLocal : fromLocal;
+			const currencyCode = type.metadata.get("db.amount.currency");
+			const currencyRefField = type.metadata.get("db.amount.currency.ref");
+			const unitCode = type.metadata.get("db.unit");
+			const unitRefField = type.metadata.get("db.unit.ref");
+			const quantityRef = currencyRefField ?? unitRefField;
+			if (quantityRef) this.quantityRefByField.set(path, quantityRef);
 			descriptors.push({
 				path,
 				type,
@@ -374,7 +382,11 @@ var TableMetadata = class {
 				flattenedFrom: isFlattened ? path : void 0,
 				renamedFrom,
 				collate: this._collateMap.get(path),
-				isIndexed: indexedFields.has(path) || void 0
+				isIndexed: indexedFields.has(path) || void 0,
+				currencyCode,
+				currencyRefField,
+				unitCode,
+				unitRefField
 			});
 		}
 		this._resolveFkTargetFields(descriptors);
@@ -1407,6 +1419,19 @@ var AtscriptDbReadable = class {
 				}]);
 			}
 		}
+		const { quantityRefByField } = this._meta;
+		if ($select && quantityRefByField.size > 0) {
+			const groupBySet = new Set($groupBy);
+			for (const item of $select) {
+				if (typeof item === "string") continue;
+				if (item.$field === "*") continue;
+				const refField = quantityRefByField.get(item.$field);
+				if (refField && !groupBySet.has(refField)) throw new require_db_error.DbError("INVALID_QUERY", [{
+					path: "$select",
+					message: `Aggregate "${item.$fn}(${item.$field})" requires "${refField}" in $groupBy — quantity-ref-tagged fields must be grouped by their dimension`
+				}]);
+			}
+		}
 		const dbQuery = this._fieldMapper.translateAggregateQuery(query, this._meta);
 		return (await this.adapter.aggregate(dbQuery)).map((row) => {
 			const mapped = {};
@@ -1422,6 +1447,14 @@ var AtscriptDbReadable = class {
 	isSearchable() {
 		return this.adapter.isSearchable();
 	}
+	/** Whether the adapter can filter on a given field (proxies adapter capability). */
+	canFilterField(fd) {
+		return this.adapter.canFilterField(fd);
+	}
+	/** Whether the adapter can sort by a given field (proxies adapter capability). */
+	canSortField(fd) {
+		return this.adapter.canSortField(fd);
+	}
 	/** Returns available search indexes from the adapter. */
 	getSearchIndexes() {
 		return this.adapter.getSearchIndexes();
@@ -1821,6 +1854,31 @@ var BaseDbAdapter = class {
 		return false;
 	}
 	/**
+	* Whether this adapter can apply equality/range filters on a given field.
+	* Default: scalar columns yes, JSON-stored columns (arrays, `@db.json`
+	* objects) no — most SQL engines cannot filter into a raw JSON value.
+	*
+	* Adapters that natively understand JSON storage (e.g. MongoDB filters arrays
+	* with implicit `$in` and dot-paths into embedded documents) override to
+	* return `true` for `storage === 'json'`.
+	*
+	* Used by `AsDbReadableController.buildMetaResponse()` to gate the
+	* `filterable` flag exposed to UIs — the adapter's answer is a hard gate
+	* even when the field carries `@db.column.filterable`.
+	*/
+	canFilterField(fd) {
+		return fd.storage !== "json";
+	}
+	/**
+	* Whether this adapter can sort by a given field.
+	* Default: scalar columns yes, JSON-stored columns no. Mongo's array sort
+	* (min/max element) is a footgun for generic UI sort headers, so the default
+	* stays conservative even for adapters that technically support it.
+	*/
+	canSortField(fd) {
+		return fd.storage !== "json";
+	}
+	/**
 	* Whether this adapter handles `$with` relation loading natively.
 	* When `true`, the table layer delegates to {@link loadRelations}
 	* instead of using the generic batch-loading strategy.

package/dist/{db-view-T2BrLhwh.mjs → db-view-DiItd0YG.mjs}

@@ -64,6 +64,8 @@ var TableMetadata = class {
 	columnMap = /* @__PURE__ */ new Map();
 	dimensions = [];
 	measures = [];
+	/** path → sibling-ref path for `@db.amount.currency.ref` / `@db.unit.ref`. */
+	quantityRefByField = /* @__PURE__ */ new Map();
 	pathToPhysical = /* @__PURE__ */ new Map();
 	physicalToPath = /* @__PURE__ */ new Map();
 	flattenedParents = /* @__PURE__ */ new Set();
@@ -361,6 +363,12 @@ var TableMetadata = class {
 			const fromLocal = this._columnFromMap.get(path);
 			let renamedFrom;
 			if (fromLocal) renamedFrom = isFlattened ? this._flattenedPrefix(path) + fromLocal : fromLocal;
+			const currencyCode = type.metadata.get("db.amount.currency");
+			const currencyRefField = type.metadata.get("db.amount.currency.ref");
+			const unitCode = type.metadata.get("db.unit");
+			const unitRefField = type.metadata.get("db.unit.ref");
+			const quantityRef = currencyRefField ?? unitRefField;
+			if (quantityRef) this.quantityRefByField.set(path, quantityRef);
 			descriptors.push({
 				path,
 				type,
@@ -374,7 +382,11 @@ var TableMetadata = class {
 				flattenedFrom: isFlattened ? path : void 0,
 				renamedFrom,
 				collate: this._collateMap.get(path),
-				isIndexed: indexedFields.has(path) || void 0
+				isIndexed: indexedFields.has(path) || void 0,
+				currencyCode,
+				currencyRefField,
+				unitCode,
+				unitRefField
 			});
 		}
 		this._resolveFkTargetFields(descriptors);
@@ -1407,6 +1419,19 @@ var AtscriptDbReadable = class {
 				}]);
 			}
 		}
+		const { quantityRefByField } = this._meta;
+		if ($select && quantityRefByField.size > 0) {
+			const groupBySet = new Set($groupBy);
+			for (const item of $select) {
+				if (typeof item === "string") continue;
+				if (item.$field === "*") continue;
+				const refField = quantityRefByField.get(item.$field);
+				if (refField && !groupBySet.has(refField)) throw new DbError("INVALID_QUERY", [{
+					path: "$select",
+					message: `Aggregate "${item.$fn}(${item.$field})" requires "${refField}" in $groupBy — quantity-ref-tagged fields must be grouped by their dimension`
+				}]);
+			}
+		}
 		const dbQuery = this._fieldMapper.translateAggregateQuery(query, this._meta);
 		return (await this.adapter.aggregate(dbQuery)).map((row) => {
 			const mapped = {};
@@ -1422,6 +1447,14 @@ var AtscriptDbReadable = class {
 	isSearchable() {
 		return this.adapter.isSearchable();
 	}
+	/** Whether the adapter can filter on a given field (proxies adapter capability). */
+	canFilterField(fd) {
+		return this.adapter.canFilterField(fd);
+	}
+	/** Whether the adapter can sort by a given field (proxies adapter capability). */
+	canSortField(fd) {
+		return this.adapter.canSortField(fd);
+	}
 	/** Returns available search indexes from the adapter. */
 	getSearchIndexes() {
 		return this.adapter.getSearchIndexes();
@@ -1821,6 +1854,31 @@ var BaseDbAdapter = class {
 		return false;
 	}
 	/**
+	* Whether this adapter can apply equality/range filters on a given field.
+	* Default: scalar columns yes, JSON-stored columns (arrays, `@db.json`
+	* objects) no — most SQL engines cannot filter into a raw JSON value.
+	*
+	* Adapters that natively understand JSON storage (e.g. MongoDB filters arrays
+	* with implicit `$in` and dot-paths into embedded documents) override to
+	* return `true` for `storage === 'json'`.
+	*
+	* Used by `AsDbReadableController.buildMetaResponse()` to gate the
+	* `filterable` flag exposed to UIs — the adapter's answer is a hard gate
+	* even when the field carries `@db.column.filterable`.
+	*/
+	canFilterField(fd) {
+		return fd.storage !== "json";
+	}
+	/**
+	* Whether this adapter can sort by a given field.
+	* Default: scalar columns yes, JSON-stored columns no. Mongo's array sort
+	* (min/max element) is a footgun for generic UI sort headers, so the default
+	* stays conservative even for adapters that technically support it.
+	*/
+	canSortField(fd) {
+		return fd.storage !== "json";
+	}
+	/**
 	* Whether this adapter handles `$with` relation loading natively.
 	* When `true`, the table layer delegates to {@link loadRelations}
 	* instead of using the generic batch-loading strategy.

package/dist/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_db_error = require("./db-error-D8tQhNgM.cjs");
-const require_db_view = require("./db-view-Jj46sTBk.cjs");
+const require_db_view = require("./db-view-B028LhoI.cjs");
 const require_ops = require("./ops.cjs");
 const require_validator = require("./validator-BIuw_T0k.cjs");
 require("./nested-writer-v_LPR1yJ.cjs");

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-import { $ as TMetadataOverrides, A as TDbCollation, B as TDbInsertResult, C as TColumnDiff, D as TDbActionIntent, E as TDbActionInfo, F as TDbForeignKey, G as TExistingColumn, H as TDbRelation, I as TDbIndex, J as TFkLookupResolver, K as TExistingTableOption, L as TDbIndexField, M as TDbDefaultValue, N as TDbDeleteResult, O as TDbActionLevel, P as TDbFieldMeta, Q as TMetaResponse, R as TDbIndexType, S as TCascadeTarget, T as TCrudPermissions, U as TDbStorageType, V as TDbReferentialAction, W as TDbUpdateResult, X as TIdDescriptor, Y as TFkLookupTarget, Z as TIdentification, _ as FlatOf, a as FieldMappingStrategy, at as TValueFormatterPair, b as PrimaryKeyOf, c as AggregateExpr, ct as Uniquery, d as AggregateResult, dt as TableMetadata, et as TRelationInfo, f as AtscriptDbWritable, ft as NoopLogger, g as FilterExpr, h as FieldOpsFor, i as DocumentFieldMapper, it as TTableResolver, j as TDbDefaultFn, k as TDbActionProcessor, l as AggregateFn, lt as UniqueryControls, m as DbQuery, mt as UniquSelect, n as DbResponse, nt as TSyncColumnResult, o as BaseDbAdapter, ot as TWriteTableResolver, p as DbControls, pt as TGenericLogger, q as TFieldMeta, r as resolveDesignType, rt as TTableOptionDiff, s as AggregateControls, st as TypedWithRelation, t as AtscriptDbReadable, tt as TSearchIndexInfo, u as AggregateQuery, ut as WithRelation, v as NavPropsOf, w as TCrudOp, x as TCascadeResolver, y as OwnPropsOf, z as TDbInsertManyResult } from "./db-readable-D3bZPucw.cjs";
+import { $ as TMetadataOverrides, A as TDbCollation, B as TDbInsertResult, C as TColumnDiff, D as TDbActionIntent, E as TDbActionInfo, F as TDbForeignKey, G as TExistingColumn, H as TDbRelation, I as TDbIndex, J as TFkLookupResolver, K as TExistingTableOption, L as TDbIndexField, M as TDbDefaultValue, N as TDbDeleteResult, O as TDbActionLevel, P as TDbFieldMeta, Q as TMetaResponse, R as TDbIndexType, S as TCascadeTarget, T as TCrudPermissions, U as TDbStorageType, V as TDbReferentialAction, W as TDbUpdateResult, X as TIdDescriptor, Y as TFkLookupTarget, Z as TIdentification, _ as FlatOf, a as FieldMappingStrategy, at as TValueFormatterPair, b as PrimaryKeyOf, c as AggregateExpr, ct as Uniquery, d as AggregateResult, dt as TableMetadata, et as TRelationInfo, f as AtscriptDbWritable, ft as NoopLogger, g as FilterExpr, h as FieldOpsFor, i as DocumentFieldMapper, it as TTableResolver, j as TDbDefaultFn, k as TDbActionProcessor, l as AggregateFn, lt as UniqueryControls, m as DbQuery, mt as UniquSelect, n as DbResponse, nt as TSyncColumnResult, o as BaseDbAdapter, ot as TWriteTableResolver, p as DbControls, pt as TGenericLogger, q as TFieldMeta, r as resolveDesignType, rt as TTableOptionDiff, s as AggregateControls, st as TypedWithRelation, t as AtscriptDbReadable, tt as TSearchIndexInfo, u as AggregateQuery, ut as WithRelation, v as NavPropsOf, w as TCrudOp, x as TCascadeResolver, y as OwnPropsOf, z as TDbInsertManyResult } from "./db-readable-BZN2QKud.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-CK11BW4j.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-Dnjxe6Bt.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";

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { $ as TMetadataOverrides, A as TDbCollation, B as TDbInsertResult, C as TColumnDiff, D as TDbActionIntent, E as TDbActionInfo, F as TDbForeignKey, G as TExistingColumn, H as TDbRelation, I as TDbIndex, J as TFkLookupResolver, K as TExistingTableOption, L as TDbIndexField, M as TDbDefaultValue, N as TDbDeleteResult, O as TDbActionLevel, P as TDbFieldMeta, Q as TMetaResponse, R as TDbIndexType, S as TCascadeTarget, T as TCrudPermissions, U as TDbStorageType, V as TDbReferentialAction, W as TDbUpdateResult, X as TIdDescriptor, Y as TFkLookupTarget, Z as TIdentification, _ as FlatOf, a as FieldMappingStrategy, at as TValueFormatterPair, b as PrimaryKeyOf, c as AggregateExpr, ct as Uniquery, d as AggregateResult, dt as TableMetadata, et as TRelationInfo, f as AtscriptDbWritable, ft as NoopLogger, g as FilterExpr, h as FieldOpsFor, i as DocumentFieldMapper, it as TTableResolver, j as TDbDefaultFn, k as TDbActionProcessor, l as AggregateFn, lt as UniqueryControls, m as DbQuery, mt as UniquSelect, n as DbResponse, nt as TSyncColumnResult, o as BaseDbAdapter, ot as TWriteTableResolver, p as DbControls, pt as TGenericLogger, q as TFieldMeta, r as resolveDesignType, rt as TTableOptionDiff, s as AggregateControls, st as TypedWithRelation, t as AtscriptDbReadable, tt as TSearchIndexInfo, u as AggregateQuery, ut as WithRelation, v as NavPropsOf, w as TCrudOp, x as TCascadeResolver, y as OwnPropsOf, z as TDbInsertManyResult } from "./db-readable-Dj9to0bC.mjs";
+import { $ as TMetadataOverrides, A as TDbCollation, B as TDbInsertResult, C as TColumnDiff, D as TDbActionIntent, E as TDbActionInfo, F as TDbForeignKey, G as TExistingColumn, H as TDbRelation, I as TDbIndex, J as TFkLookupResolver, K as TExistingTableOption, L as TDbIndexField, M as TDbDefaultValue, N as TDbDeleteResult, O as TDbActionLevel, P as TDbFieldMeta, Q as TMetaResponse, R as TDbIndexType, S as TCascadeTarget, T as TCrudPermissions, U as TDbStorageType, V as TDbReferentialAction, W as TDbUpdateResult, X as TIdDescriptor, Y as TFkLookupTarget, Z as TIdentification, _ as FlatOf, a as FieldMappingStrategy, at as TValueFormatterPair, b as PrimaryKeyOf, c as AggregateExpr, ct as Uniquery, d as AggregateResult, dt as TableMetadata, et as TRelationInfo, f as AtscriptDbWritable, ft as NoopLogger, g as FilterExpr, h as FieldOpsFor, i as DocumentFieldMapper, it as TTableResolver, j as TDbDefaultFn, k as TDbActionProcessor, l as AggregateFn, lt as UniqueryControls, m as DbQuery, mt as UniquSelect, n as DbResponse, nt as TSyncColumnResult, o as BaseDbAdapter, ot as TWriteTableResolver, p as DbControls, pt as TGenericLogger, q as TFieldMeta, r as resolveDesignType, rt as TTableOptionDiff, s as AggregateControls, st as TypedWithRelation, t as AtscriptDbReadable, tt as TSearchIndexInfo, u as AggregateQuery, ut as WithRelation, v as NavPropsOf, w as TCrudOp, x as TCascadeResolver, y as OwnPropsOf, z as TDbInsertManyResult } from "./db-readable-vjbawUvu.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-Dy4GqZrK.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-CxGLp-no.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";

package/dist/index.mjs

@@ -1,5 +1,5 @@
 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-T2BrLhwh.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-DiItd0YG.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-BB5h1Le3.mjs";
 import "./nested-writer-CT2rLURx.mjs";

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-B9WJv9aH.cjs");
+const require_validation_utils = require("./validation-utils-Bs1yOXNx.cjs");
 let _atscript_core = require("@atscript/core");
 //#region src/plugin/annotations/agg.ts
 const dbAggAnnotations = { agg: {
@@ -63,6 +63,59 @@ const dbAggAnnotations = { agg: {
 	})
 } };
 //#endregion
+//#region src/plugin/annotations/amount.ts
+const CURRENCY_CODE_PATTERN = /^[A-Z0-9]{2,10}$/;
+const dbAmountAnnotations = { amount: { currency: {
+	$self: new _atscript_core.AnnotationSpec({
+		description: "Hard-coded **currency code** for this amount field. Use when a table stores amounts in a single, fixed currency.\n\nFor per-row currency, use `@db.amount.currency.ref 'fieldName'` instead.\n\nOnly valid on `decimal` fields — money in floating-point is wrong.\n\n**Example:**\n```atscript\n@db.amount.currency 'EUR'\namount: decimal\n```\n",
+		nodeType: ["prop"],
+		multiple: false,
+		argument: {
+			name: "code",
+			type: "string",
+			description: "Currency code — uppercase 2–10 alphanumerics (ISO 4217 or custom: 'EUR', 'USD', 'BTC')."
+		},
+		validate(token, args, doc) {
+			const errors = [];
+			errors.push(...require_validation_utils.validateFieldBaseType(token, doc, "@db.amount.currency", "decimal"));
+			errors.push(...require_validation_utils.validateExclusiveWith(token, "@db.amount.currency", [{
+				key: "db.amount.currency.ref",
+				displayName: "@db.amount.currency.ref"
+			}]));
+			const code = args[0]?.text;
+			if (code && !CURRENCY_CODE_PATTERN.test(code)) errors.push({
+				message: `@db.amount.currency '${code}': invalid currency code (expected 2–10 uppercase letters or digits)`,
+				severity: 1,
+				range: token.range
+			});
+			return errors;
+		}
+	}),
+	ref: new _atscript_core.AnnotationSpec({
+		description: "Binds this amount to a **sibling field** that holds its currency code. Use when each row may have a different currency.\n\nThe referenced field should be of type `db.currencyCode` (or at least a `string`).\n\nOnly valid on `decimal` fields.\n\n**Example:**\n```atscript\ncurrency: db.currencyCode\n@db.amount.currency.ref 'currency'\namount: decimal\n```\n",
+		nodeType: ["prop"],
+		multiple: false,
+		argument: {
+			name: "fieldName",
+			type: "string",
+			description: "Name of the sibling property holding the currency code."
+		},
+		validate(token, args, doc) {
+			const errors = [];
+			errors.push(...require_validation_utils.validateFieldBaseType(token, doc, "@db.amount.currency.ref", "decimal"));
+			errors.push(...require_validation_utils.validateExclusiveWith(token, "@db.amount.currency.ref", [{
+				key: "db.amount.currency",
+				displayName: "@db.amount.currency"
+			}, {
+				key: "db.unit.ref",
+				displayName: "@db.unit.ref"
+			}]));
+			errors.push(...require_validation_utils.validateSiblingStringField(token, args, doc, "@db.amount.currency.ref"));
+			return errors;
+		}
+	})
+} } };
+//#endregion
 //#region src/plugin/annotations/column.ts
 const dbColumnAnnotations = {
 	patch: { strategy: new _atscript_core.AnnotationSpec({
@@ -927,6 +980,53 @@ Writing the annotation explicitly as \`@db.table.${capability} 'auto'\` has the
 	});
 }
 //#endregion
+//#region src/plugin/annotations/unit.ts
+const UNIT_HOST_TYPES = ["decimal", "number"];
+const dbUnitAnnotations = { unit: {
+	$self: new _atscript_core.AnnotationSpec({
+		description: "Hard-coded **unit of measure** for this quantity field. Use when a table stores all values for this field in a single, fixed unit.\n\nFor per-row units, use `@db.unit.ref 'fieldName'` instead.\n\nValid on `decimal` and `number` fields. Unlike `@db.amount.currency`, the unit code is free-form (`'kg'`, `'rpm'`, `'qps'`, …) — no ISO-style validation.\n\nAggregations on a unit-tagged field do not need grouping when the unit is a fixed literal — the constraint is satisfied schema-wide.\n\n**Example:**\n```atscript\n@db.unit 'kg'\nweight: decimal\n```\n",
+		nodeType: ["prop"],
+		multiple: false,
+		argument: {
+			name: "code",
+			type: "string",
+			description: "Unit code (free-form: 'kg', 'g', 'lb', 'm', 'rpm', 'qps', etc.)."
+		},
+		validate(token, _args, doc) {
+			const errors = [];
+			errors.push(...require_validation_utils.validateFieldBaseType(token, doc, "@db.unit", UNIT_HOST_TYPES));
+			errors.push(...require_validation_utils.validateExclusiveWith(token, "@db.unit", [{
+				key: "db.unit.ref",
+				displayName: "@db.unit.ref"
+			}]));
+			return errors;
+		}
+	}),
+	ref: new _atscript_core.AnnotationSpec({
+		description: "Binds this quantity to a **sibling field** that holds its unit. Use when different rows may carry different units (e.g. mixed kg/lb measurements).\n\nThe referenced field must be a `string`.\n\nValid on `decimal` and `number` fields. Aggregating this field forces the referenced unit field into `$groupBy` at runtime — summing rows with different units is rejected.\n\n**Example:**\n```atscript\nunit: string\n@db.unit.ref 'unit'\nweight: decimal\n```\n",
+		nodeType: ["prop"],
+		multiple: false,
+		argument: {
+			name: "fieldName",
+			type: "string",
+			description: "Name of the sibling property holding the unit code."
+		},
+		validate(token, args, doc) {
+			const errors = [];
+			errors.push(...require_validation_utils.validateFieldBaseType(token, doc, "@db.unit.ref", UNIT_HOST_TYPES));
+			errors.push(...require_validation_utils.validateExclusiveWith(token, "@db.unit.ref", [{
+				key: "db.unit",
+				displayName: "@db.unit"
+			}, {
+				key: "db.amount.currency.ref",
+				displayName: "@db.amount.currency.ref"
+			}]));
+			errors.push(...require_validation_utils.validateSiblingStringField(token, args, doc, "@db.unit.ref"));
+			return errors;
+		}
+	})
+} };
+//#endregion
 //#region src/plugin/annotations/view.ts
 const dbViewAnnotations = { view: {
 	$self: new _atscript_core.AnnotationSpec({
@@ -1121,15 +1221,27 @@ const dbPlugin = () => ({
 				rel: dbRelAnnotations.rel,
 				view: dbViewAnnotations.view,
 				agg: dbAggAnnotations.agg,
-				search: dbSearchAnnotations.search
+				search: dbSearchAnnotations.search,
+				amount: dbAmountAnnotations.amount,
+				unit: dbUnitAnnotations.unit
 			} },
-			primitives: { db: { extensions: { vector: {
-				type: {
-					kind: "array",
-					of: "number"
+			primitives: { db: { extensions: {
+				vector: {
+					type: {
+						kind: "array",
+						of: "number"
+					},
+					documentation: "Represents a **vector embedding** (array of numbers) for **similarity search**.\n\n- Equivalent to `number[]` but explicitly marks the field as a vector embedding.\n- Each adapter maps this to its native vector type:\n  - **MongoDB** → BSON array\n  - **MySQL 9+** → `VECTOR(N)`\n  - **PostgreSQL** → pgvector `vector(N)`\n  - **SQLite** → JSON\n\n**Example:**\n```atscript\n@db.search.vector 1536, \"cosine\"\nembedding: db.vector\n```\n"
 				},
-				documentation: "Represents a **vector embedding** (array of numbers) for **similarity search**.\n\n- Equivalent to `number[]` but explicitly marks the field as a vector embedding.\n- Each adapter maps this to its native vector type:\n  - **MongoDB** → BSON array\n  - **MySQL 9+** → `VECTOR(N)`\n  - **PostgreSQL** → pgvector `vector(N)`\n  - **SQLite** → JSON\n\n**Example:**\n```atscript\n@db.search.vector 1536, \"cosine\"\nembedding: db.vector\n```\n"
-			} } } }
+				currencyCode: {
+					type: "string",
+					documentation: "Represents a **currency code** — typically ISO 4217 (`'USD'`, `'EUR'`, `'JPY'`) but accepts any uppercase alphanumeric code 2–10 chars long, so crypto and custom codes (`'BTC'`, `'USDC'`, `'POINTS'`) fit too.\n\nPair with `@db.amount.currency.ref 'fieldName'` on a `decimal` field to bind the amount to its row-level currency. The validator checks that the ref target resolves to this type (or a plain `string`).\n\n**Example:**\n```atscript\ncurrency: db.currencyCode\n@db.amount.currency.ref 'currency'\namount: decimal\n```\n",
+					annotations: { "expect.pattern": [{
+						pattern: "^[A-Z0-9]{2,10}$",
+						message: "Invalid currency code (expected 2–10 uppercase letters or digits)"
+					}] }
+				}
+			} } }
 		};
 	}
 });

package/dist/plugin.mjs

@@ -1,4 +1,4 @@
-import { a as getAnnotationAlias, c as getParentStruct, d as validateFieldBaseType, i as validateRefArgument, l as getParentTypeName, n as hasAnyViewAnnotation, o as getDbTableOwner, r as validateQueryScope, s as getNavTargetTypeName, t as findFKFieldsPointingTo, u as refActionAnnotation } from "./validation-utils-Bh7RVrVl.mjs";
+import { a as getAnnotationAlias, c as getParentStruct, d as validateExclusiveWith, f as validateFieldBaseType, i as validateRefArgument, l as getParentTypeName, n as hasAnyViewAnnotation, o as getDbTableOwner, p as validateSiblingStringField, r as validateQueryScope, s as getNavTargetTypeName, t as findFKFieldsPointingTo, u as refActionAnnotation } from "./validation-utils-eaBuT39W.mjs";
 import { AnnotationSpec, isArray, isInterface, isPrimitive, isRef, isStructure } from "@atscript/core";
 //#region src/plugin/annotations/agg.ts
 const dbAggAnnotations = { agg: {
@@ -59,6 +59,59 @@ const dbAggAnnotations = { agg: {
 	})
 } };
 //#endregion
+//#region src/plugin/annotations/amount.ts
+const CURRENCY_CODE_PATTERN = /^[A-Z0-9]{2,10}$/;
+const dbAmountAnnotations = { amount: { currency: {
+	$self: new AnnotationSpec({
+		description: "Hard-coded **currency code** for this amount field. Use when a table stores amounts in a single, fixed currency.\n\nFor per-row currency, use `@db.amount.currency.ref 'fieldName'` instead.\n\nOnly valid on `decimal` fields — money in floating-point is wrong.\n\n**Example:**\n```atscript\n@db.amount.currency 'EUR'\namount: decimal\n```\n",
+		nodeType: ["prop"],
+		multiple: false,
+		argument: {
+			name: "code",
+			type: "string",
+			description: "Currency code — uppercase 2–10 alphanumerics (ISO 4217 or custom: 'EUR', 'USD', 'BTC')."
+		},
+		validate(token, args, doc) {
+			const errors = [];
+			errors.push(...validateFieldBaseType(token, doc, "@db.amount.currency", "decimal"));
+			errors.push(...validateExclusiveWith(token, "@db.amount.currency", [{
+				key: "db.amount.currency.ref",
+				displayName: "@db.amount.currency.ref"
+			}]));
+			const code = args[0]?.text;
+			if (code && !CURRENCY_CODE_PATTERN.test(code)) errors.push({
+				message: `@db.amount.currency '${code}': invalid currency code (expected 2–10 uppercase letters or digits)`,
+				severity: 1,
+				range: token.range
+			});
+			return errors;
+		}
+	}),
+	ref: new AnnotationSpec({
+		description: "Binds this amount to a **sibling field** that holds its currency code. Use when each row may have a different currency.\n\nThe referenced field should be of type `db.currencyCode` (or at least a `string`).\n\nOnly valid on `decimal` fields.\n\n**Example:**\n```atscript\ncurrency: db.currencyCode\n@db.amount.currency.ref 'currency'\namount: decimal\n```\n",
+		nodeType: ["prop"],
+		multiple: false,
+		argument: {
+			name: "fieldName",
+			type: "string",
+			description: "Name of the sibling property holding the currency code."
+		},
+		validate(token, args, doc) {
+			const errors = [];
+			errors.push(...validateFieldBaseType(token, doc, "@db.amount.currency.ref", "decimal"));
+			errors.push(...validateExclusiveWith(token, "@db.amount.currency.ref", [{
+				key: "db.amount.currency",
+				displayName: "@db.amount.currency"
+			}, {
+				key: "db.unit.ref",
+				displayName: "@db.unit.ref"
+			}]));
+			errors.push(...validateSiblingStringField(token, args, doc, "@db.amount.currency.ref"));
+			return errors;
+		}
+	})
+} } };
+//#endregion
 //#region src/plugin/annotations/column.ts
 const dbColumnAnnotations = {
 	patch: { strategy: new AnnotationSpec({
@@ -923,6 +976,53 @@ Writing the annotation explicitly as \`@db.table.${capability} 'auto'\` has the
 	});
 }
 //#endregion
+//#region src/plugin/annotations/unit.ts
+const UNIT_HOST_TYPES = ["decimal", "number"];
+const dbUnitAnnotations = { unit: {
+	$self: new AnnotationSpec({
+		description: "Hard-coded **unit of measure** for this quantity field. Use when a table stores all values for this field in a single, fixed unit.\n\nFor per-row units, use `@db.unit.ref 'fieldName'` instead.\n\nValid on `decimal` and `number` fields. Unlike `@db.amount.currency`, the unit code is free-form (`'kg'`, `'rpm'`, `'qps'`, …) — no ISO-style validation.\n\nAggregations on a unit-tagged field do not need grouping when the unit is a fixed literal — the constraint is satisfied schema-wide.\n\n**Example:**\n```atscript\n@db.unit 'kg'\nweight: decimal\n```\n",
+		nodeType: ["prop"],
+		multiple: false,
+		argument: {
+			name: "code",
+			type: "string",
+			description: "Unit code (free-form: 'kg', 'g', 'lb', 'm', 'rpm', 'qps', etc.)."
+		},
+		validate(token, _args, doc) {
+			const errors = [];
+			errors.push(...validateFieldBaseType(token, doc, "@db.unit", UNIT_HOST_TYPES));
+			errors.push(...validateExclusiveWith(token, "@db.unit", [{
+				key: "db.unit.ref",
+				displayName: "@db.unit.ref"
+			}]));
+			return errors;
+		}
+	}),
+	ref: new AnnotationSpec({
+		description: "Binds this quantity to a **sibling field** that holds its unit. Use when different rows may carry different units (e.g. mixed kg/lb measurements).\n\nThe referenced field must be a `string`.\n\nValid on `decimal` and `number` fields. Aggregating this field forces the referenced unit field into `$groupBy` at runtime — summing rows with different units is rejected.\n\n**Example:**\n```atscript\nunit: string\n@db.unit.ref 'unit'\nweight: decimal\n```\n",
+		nodeType: ["prop"],
+		multiple: false,
+		argument: {
+			name: "fieldName",
+			type: "string",
+			description: "Name of the sibling property holding the unit code."
+		},
+		validate(token, args, doc) {
+			const errors = [];
+			errors.push(...validateFieldBaseType(token, doc, "@db.unit.ref", UNIT_HOST_TYPES));
+			errors.push(...validateExclusiveWith(token, "@db.unit.ref", [{
+				key: "db.unit",
+				displayName: "@db.unit"
+			}, {
+				key: "db.amount.currency.ref",
+				displayName: "@db.amount.currency.ref"
+			}]));
+			errors.push(...validateSiblingStringField(token, args, doc, "@db.unit.ref"));
+			return errors;
+		}
+	})
+} };
+//#endregion
 //#region src/plugin/annotations/view.ts
 const dbViewAnnotations = { view: {
 	$self: new AnnotationSpec({
@@ -1117,15 +1217,27 @@ const dbPlugin = () => ({
 				rel: dbRelAnnotations.rel,
 				view: dbViewAnnotations.view,
 				agg: dbAggAnnotations.agg,
-				search: dbSearchAnnotations.search
+				search: dbSearchAnnotations.search,
+				amount: dbAmountAnnotations.amount,
+				unit: dbUnitAnnotations.unit
 			} },
-			primitives: { db: { extensions: { vector: {
-				type: {
-					kind: "array",
-					of: "number"
+			primitives: { db: { extensions: {
+				vector: {
+					type: {
+						kind: "array",
+						of: "number"
+					},
+					documentation: "Represents a **vector embedding** (array of numbers) for **similarity search**.\n\n- Equivalent to `number[]` but explicitly marks the field as a vector embedding.\n- Each adapter maps this to its native vector type:\n  - **MongoDB** → BSON array\n  - **MySQL 9+** → `VECTOR(N)`\n  - **PostgreSQL** → pgvector `vector(N)`\n  - **SQLite** → JSON\n\n**Example:**\n```atscript\n@db.search.vector 1536, \"cosine\"\nembedding: db.vector\n```\n"
 				},
-				documentation: "Represents a **vector embedding** (array of numbers) for **similarity search**.\n\n- Equivalent to `number[]` but explicitly marks the field as a vector embedding.\n- Each adapter maps this to its native vector type:\n  - **MongoDB** → BSON array\n  - **MySQL 9+** → `VECTOR(N)`\n  - **PostgreSQL** → pgvector `vector(N)`\n  - **SQLite** → JSON\n\n**Example:**\n```atscript\n@db.search.vector 1536, \"cosine\"\nembedding: db.vector\n```\n"
-			} } } }
+				currencyCode: {
+					type: "string",
+					documentation: "Represents a **currency code** — typically ISO 4217 (`'USD'`, `'EUR'`, `'JPY'`) but accepts any uppercase alphanumeric code 2–10 chars long, so crypto and custom codes (`'BTC'`, `'USDC'`, `'POINTS'`) fit too.\n\nPair with `@db.amount.currency.ref 'fieldName'` on a `decimal` field to bind the amount to its row-level currency. The validator checks that the ref target resolves to this type (or a plain `string`).\n\n**Example:**\n```atscript\ncurrency: db.currencyCode\n@db.amount.currency.ref 'currency'\namount: decimal\n```\n",
+					annotations: { "expect.pattern": [{
+						pattern: "^[A-Z0-9]{2,10}$",
+						message: "Invalid currency code (expected 2–10 uppercase letters or digits)"
+					}] }
+				}
+			} } }
 		};
 	}
 });

package/dist/rel.d.cts

@@ -1,4 +1,4 @@
-import { F as TDbForeignKey, H as TDbRelation, dt as TableMetadata, it as TTableResolver, o as BaseDbAdapter, ot as TWriteTableResolver, pt as TGenericLogger } from "./db-readable-D3bZPucw.cjs";
+import { F as TDbForeignKey, H as TDbRelation, dt as TableMetadata, it as TTableResolver, o as BaseDbAdapter, ot as TWriteTableResolver, pt as TGenericLogger } from "./db-readable-BZN2QKud.cjs";
 import { t as DbValidationContext } from "./db-validator-plugin-DRGMCEn3.cjs";
 import { FilterExpr, WithRelation } from "@uniqu/core";
 import { Validator } from "@atscript/typescript/utils";

package/dist/rel.d.mts

@@ -1,4 +1,4 @@
-import { F as TDbForeignKey, H as TDbRelation, dt as TableMetadata, it as TTableResolver, o as BaseDbAdapter, ot as TWriteTableResolver, pt as TGenericLogger } from "./db-readable-Dj9to0bC.mjs";
+import { F as TDbForeignKey, H as TDbRelation, dt as TableMetadata, it as TTableResolver, o as BaseDbAdapter, ot as TWriteTableResolver, pt as TGenericLogger } from "./db-readable-vjbawUvu.mjs";
 import { t as DbValidationContext } from "./db-validator-plugin-DDvYyv5t.mjs";
 import { Validator } from "@atscript/typescript/utils";
 import { FilterExpr, WithRelation } from "@uniqu/core";

package/dist/shared.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_validation_utils = require("./validation-utils-B9WJv9aH.cjs");
+const require_validation_utils = require("./validation-utils-Bs1yOXNx.cjs");
 exports.findFKFieldsPointingTo = require_validation_utils.findFKFieldsPointingTo;
 exports.getAnnotationAlias = require_validation_utils.getAnnotationAlias;
 exports.getDbTableOwner = require_validation_utils.getDbTableOwner;
@@ -8,6 +8,8 @@ exports.getParentStruct = require_validation_utils.getParentStruct;
 exports.getParentTypeName = require_validation_utils.getParentTypeName;
 exports.hasAnyViewAnnotation = require_validation_utils.hasAnyViewAnnotation;
 exports.refActionAnnotation = require_validation_utils.refActionAnnotation;
+exports.validateExclusiveWith = require_validation_utils.validateExclusiveWith;
 exports.validateFieldBaseType = require_validation_utils.validateFieldBaseType;
 exports.validateQueryScope = require_validation_utils.validateQueryScope;
 exports.validateRefArgument = require_validation_utils.validateRefArgument;
+exports.validateSiblingStringField = require_validation_utils.validateSiblingStringField;

package/dist/shared.d.cts

@@ -1,6 +1,13 @@
 import { AnnotationSpec, AtscriptDoc, SemanticInterfaceNode, SemanticNode, SemanticPropNode, SemanticStructureNode, TMessages, Token } from "@atscript/core";
 
 //#region src/shared/annotation-utils.d.ts
+/** Asserts the field carrying this annotation does not also carry any of `others`. */
+declare function validateExclusiveWith(token: Token, selfName: string, others: Array<{
+  key: string;
+  displayName?: string;
+}>): TMessages;
+/** Asserts `args[0]` names a sibling property whose primitive base type is `string`. */
+declare function validateSiblingStringField(token: Token, args: Token[], doc: AtscriptDoc, selfName: string): TMessages;
 /**
  * Traverse from annotation token → prop → structure → interface
  * to check if the parent interface has @db.table.
@@ -68,4 +75,4 @@ declare function hasAnyViewAnnotation(node: SemanticNode): boolean;
  */
 declare function validateQueryScope(queryToken: Token, allowedTypes: string[], unqualifiedTarget: string | null, doc: AtscriptDoc): TMessages;
 //#endregion
-export { TFKFieldMatch, findFKFieldsPointingTo, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, refActionAnnotation, validateFieldBaseType, validateQueryScope, validateRefArgument };
+export { TFKFieldMatch, findFKFieldsPointingTo, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, refActionAnnotation, validateExclusiveWith, validateFieldBaseType, validateQueryScope, validateRefArgument, validateSiblingStringField };

package/dist/shared.d.mts

@@ -1,6 +1,13 @@
 import { AnnotationSpec, AtscriptDoc, SemanticInterfaceNode, SemanticNode, SemanticPropNode, SemanticStructureNode, TMessages, Token } from "@atscript/core";
 
 //#region src/shared/annotation-utils.d.ts
+/** Asserts the field carrying this annotation does not also carry any of `others`. */
+declare function validateExclusiveWith(token: Token, selfName: string, others: Array<{
+  key: string;
+  displayName?: string;
+}>): TMessages;
+/** Asserts `args[0]` names a sibling property whose primitive base type is `string`. */
+declare function validateSiblingStringField(token: Token, args: Token[], doc: AtscriptDoc, selfName: string): TMessages;
 /**
  * Traverse from annotation token → prop → structure → interface
  * to check if the parent interface has @db.table.
@@ -68,4 +75,4 @@ declare function hasAnyViewAnnotation(node: SemanticNode): boolean;
  */
 declare function validateQueryScope(queryToken: Token, allowedTypes: string[], unqualifiedTarget: string | null, doc: AtscriptDoc): TMessages;
 //#endregion
-export { TFKFieldMatch, findFKFieldsPointingTo, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, refActionAnnotation, validateFieldBaseType, validateQueryScope, validateRefArgument };
+export { TFKFieldMatch, findFKFieldsPointingTo, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, refActionAnnotation, validateExclusiveWith, validateFieldBaseType, validateQueryScope, validateRefArgument, validateSiblingStringField };

package/dist/shared.mjs

@@ -1,2 +1,2 @@
-import { a as getAnnotationAlias, c as getParentStruct, d as validateFieldBaseType, i as validateRefArgument, l as getParentTypeName, n as hasAnyViewAnnotation, o as getDbTableOwner, r as validateQueryScope, s as getNavTargetTypeName, t as findFKFieldsPointingTo, u as refActionAnnotation } from "./validation-utils-Bh7RVrVl.mjs";
-export { findFKFieldsPointingTo, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, refActionAnnotation, validateFieldBaseType, validateQueryScope, validateRefArgument };
+import { a as getAnnotationAlias, c as getParentStruct, d as validateExclusiveWith, f as validateFieldBaseType, i as validateRefArgument, l as getParentTypeName, n as hasAnyViewAnnotation, o as getDbTableOwner, p as validateSiblingStringField, r as validateQueryScope, s as getNavTargetTypeName, t as findFKFieldsPointingTo, u as refActionAnnotation } from "./validation-utils-eaBuT39W.mjs";
+export { findFKFieldsPointingTo, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, refActionAnnotation, validateExclusiveWith, validateFieldBaseType, validateQueryScope, validateRefArgument, validateSiblingStringField };

package/dist/sync.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_db_view = require("./db-view-Jj46sTBk.cjs");
+const require_db_view = require("./db-view-B028LhoI.cjs");
 require("./validator-BIuw_T0k.cjs");
 require("./nested-writer-v_LPR1yJ.cjs");
 //#region src/schema/schema-hash.ts

package/dist/sync.d.cts

@@ -1,5 +1,5 @@
-import { C as TColumnDiff, F as TDbForeignKey, G as TExistingColumn, K as TExistingTableOption, M as TDbDefaultValue, P as TDbFieldMeta, U as TDbStorageType, pt as TGenericLogger, rt as TTableOptionDiff, t as AtscriptDbReadable } from "./db-readable-D3bZPucw.cjs";
-import { r as AtscriptDbView, t as DbSpace } from "./db-space-CK11BW4j.cjs";
+import { C as TColumnDiff, F as TDbForeignKey, G as TExistingColumn, K as TExistingTableOption, M as TDbDefaultValue, P as TDbFieldMeta, U as TDbStorageType, pt as TGenericLogger, rt as TTableOptionDiff, t as AtscriptDbReadable } from "./db-readable-BZN2QKud.cjs";
+import { r as AtscriptDbView, t as DbSpace } from "./db-space-Dnjxe6Bt.cjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/schema/sync-entry.d.ts

package/dist/sync.d.mts

@@ -1,5 +1,5 @@
-import { C as TColumnDiff, F as TDbForeignKey, G as TExistingColumn, K as TExistingTableOption, M as TDbDefaultValue, P as TDbFieldMeta, U as TDbStorageType, pt as TGenericLogger, rt as TTableOptionDiff, t as AtscriptDbReadable } from "./db-readable-Dj9to0bC.mjs";
-import { r as AtscriptDbView, t as DbSpace } from "./db-space-Dy4GqZrK.mjs";
+import { C as TColumnDiff, F as TDbForeignKey, G as TExistingColumn, K as TExistingTableOption, M as TDbDefaultValue, P as TDbFieldMeta, U as TDbStorageType, pt as TGenericLogger, rt as TTableOptionDiff, t as AtscriptDbReadable } from "./db-readable-vjbawUvu.mjs";
+import { r as AtscriptDbView, t as DbSpace } from "./db-space-CxGLp-no.mjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/schema/sync-entry.d.ts

package/dist/sync.mjs

@@ -1,4 +1,4 @@
-import { h as NoopLogger } from "./db-view-T2BrLhwh.mjs";
+import { h as NoopLogger } from "./db-view-DiItd0YG.mjs";
 import "./validator-BB5h1Le3.mjs";
 import "./nested-writer-CT2rLURx.mjs";
 //#region src/schema/schema-hash.ts

package/dist/{validation-utils-B9WJv9aH.cjs → validation-utils-Bs1yOXNx.cjs}

@@ -1,5 +1,49 @@
 let _atscript_core = require("@atscript/core");
 //#region src/shared/annotation-utils.ts
+/** Asserts the field carrying this annotation does not also carry any of `others`. */
+function validateExclusiveWith(token, selfName, others) {
+	const errors = [];
+	const field = token.parentNode;
+	for (const { key, displayName } of others) if (field.countAnnotations(key) > 0) errors.push({
+		message: `${selfName} cannot coexist with ${displayName ?? `@${key}`} on the same field — pick one form, not both`,
+		severity: 1,
+		range: token.range
+	});
+	return errors;
+}
+/** Resolves a field/prop's primitive base type, or `undefined` if it isn't a ref-to-primitive. */
+function getPrimitiveBaseType(node, doc) {
+	const def = node.getDefinition();
+	if (!def || !(0, _atscript_core.isRef)(def)) return void 0;
+	const unwound = doc.unwindType(def.id, def.chain);
+	if (!unwound || !(0, _atscript_core.isPrimitive)(unwound.def)) return void 0;
+	const ct = unwound.def.config.type;
+	return typeof ct === "object" ? ct.kind === "final" ? ct.value : ct.kind : ct;
+}
+/** Asserts `args[0]` names a sibling property whose primitive base type is `string`. */
+function validateSiblingStringField(token, args, doc, selfName) {
+	const errors = [];
+	const fieldName = args[0]?.text;
+	if (!fieldName) return errors;
+	const struct = getParentStruct(token);
+	if (!struct) return errors;
+	const sibling = struct.props.get(fieldName);
+	if (!sibling) {
+		errors.push({
+			message: `${selfName} '${fieldName}': no sibling field named '${fieldName}' on this type`,
+			severity: 1,
+			range: token.range
+		});
+		return errors;
+	}
+	const baseType = getPrimitiveBaseType(sibling, doc);
+	if (baseType !== void 0 && baseType !== "string") errors.push({
+		message: `${selfName} '${fieldName}': sibling field must be a string, got '${baseType}'`,
+		severity: 1,
+		range: token.range
+	});
+	return errors;
+}
 /**
 * Traverse from annotation token → prop → structure → interface
 * to check if the parent interface has @db.table.
@@ -31,12 +75,9 @@ function getParentTypeName(token) {
 */
 function validateFieldBaseType(token, doc, annotationName, expectedType) {
 	const errors = [];
-	const definition = token.parentNode.getDefinition();
-	if (!definition || !(0, _atscript_core.isRef)(definition)) return errors;
-	const unwound = doc.unwindType(definition.id, definition.chain);
-	if (!unwound || !(0, _atscript_core.isPrimitive)(unwound.def)) return errors;
-	const ct = unwound.def.config.type;
-	const baseType = typeof ct === "object" ? ct.kind === "final" ? ct.value : ct.kind : ct;
+	const field = token.parentNode;
+	const baseType = getPrimitiveBaseType(field, doc);
+	if (baseType === void 0) return errors;
 	const allowed = Array.isArray(expectedType) ? expectedType : [expectedType];
 	if (!allowed.includes(baseType)) errors.push({
 		message: `${annotationName} is not compatible with type "${baseType}" — requires ${allowed.join(" or ")}`,
@@ -316,6 +357,12 @@ Object.defineProperty(exports, "refActionAnnotation", {
 		return refActionAnnotation;
 	}
 });
+Object.defineProperty(exports, "validateExclusiveWith", {
+	enumerable: true,
+	get: function() {
+		return validateExclusiveWith;
+	}
+});
 Object.defineProperty(exports, "validateFieldBaseType", {
 	enumerable: true,
 	get: function() {
@@ -334,3 +381,9 @@ Object.defineProperty(exports, "validateRefArgument", {
 		return validateRefArgument;
 	}
 });
+Object.defineProperty(exports, "validateSiblingStringField", {
+	enumerable: true,
+	get: function() {
+		return validateSiblingStringField;
+	}
+});

package/dist/{validation-utils-Bh7RVrVl.mjs → validation-utils-eaBuT39W.mjs}

@@ -1,5 +1,49 @@
 import { AnnotationSpec, isArray, isInterface, isPrimitive, isQueryComparison, isQueryLogical, isRef, isStructure } from "@atscript/core";
 //#region src/shared/annotation-utils.ts
+/** Asserts the field carrying this annotation does not also carry any of `others`. */
+function validateExclusiveWith(token, selfName, others) {
+	const errors = [];
+	const field = token.parentNode;
+	for (const { key, displayName } of others) if (field.countAnnotations(key) > 0) errors.push({
+		message: `${selfName} cannot coexist with ${displayName ?? `@${key}`} on the same field — pick one form, not both`,
+		severity: 1,
+		range: token.range
+	});
+	return errors;
+}
+/** Resolves a field/prop's primitive base type, or `undefined` if it isn't a ref-to-primitive. */
+function getPrimitiveBaseType(node, doc) {
+	const def = node.getDefinition();
+	if (!def || !isRef(def)) return void 0;
+	const unwound = doc.unwindType(def.id, def.chain);
+	if (!unwound || !isPrimitive(unwound.def)) return void 0;
+	const ct = unwound.def.config.type;
+	return typeof ct === "object" ? ct.kind === "final" ? ct.value : ct.kind : ct;
+}
+/** Asserts `args[0]` names a sibling property whose primitive base type is `string`. */
+function validateSiblingStringField(token, args, doc, selfName) {
+	const errors = [];
+	const fieldName = args[0]?.text;
+	if (!fieldName) return errors;
+	const struct = getParentStruct(token);
+	if (!struct) return errors;
+	const sibling = struct.props.get(fieldName);
+	if (!sibling) {
+		errors.push({
+			message: `${selfName} '${fieldName}': no sibling field named '${fieldName}' on this type`,
+			severity: 1,
+			range: token.range
+		});
+		return errors;
+	}
+	const baseType = getPrimitiveBaseType(sibling, doc);
+	if (baseType !== void 0 && baseType !== "string") errors.push({
+		message: `${selfName} '${fieldName}': sibling field must be a string, got '${baseType}'`,
+		severity: 1,
+		range: token.range
+	});
+	return errors;
+}
 /**
 * Traverse from annotation token → prop → structure → interface
 * to check if the parent interface has @db.table.
@@ -31,12 +75,9 @@ function getParentTypeName(token) {
 */
 function validateFieldBaseType(token, doc, annotationName, expectedType) {
 	const errors = [];
-	const definition = token.parentNode.getDefinition();
-	if (!definition || !isRef(definition)) return errors;
-	const unwound = doc.unwindType(definition.id, definition.chain);
-	if (!unwound || !isPrimitive(unwound.def)) return errors;
-	const ct = unwound.def.config.type;
-	const baseType = typeof ct === "object" ? ct.kind === "final" ? ct.value : ct.kind : ct;
+	const field = token.parentNode;
+	const baseType = getPrimitiveBaseType(field, doc);
+	if (baseType === void 0) return errors;
 	const allowed = Array.isArray(expectedType) ? expectedType : [expectedType];
 	if (!allowed.includes(baseType)) errors.push({
 		message: `${annotationName} is not compatible with type "${baseType}" — requires ${allowed.join(" or ")}`,
@@ -268,4 +309,4 @@ function validateQueryScope(queryToken, allowedTypes, unqualifiedTarget, doc) {
 	return errors;
 }
 //#endregion
-export { getAnnotationAlias as a, getParentStruct as c, validateFieldBaseType as d, validateRefArgument as i, getParentTypeName as l, hasAnyViewAnnotation as n, getDbTableOwner as o, validateQueryScope as r, getNavTargetTypeName as s, findFKFieldsPointingTo as t, refActionAnnotation as u };
+export { getAnnotationAlias as a, getParentStruct as c, validateExclusiveWith as d, validateFieldBaseType as f, validateRefArgument as i, getParentTypeName as l, hasAnyViewAnnotation as n, getDbTableOwner as o, validateSiblingStringField as p, validateQueryScope as r, getNavTargetTypeName as s, findFKFieldsPointingTo as t, refActionAnnotation as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db",
-  "version": "0.1.63",
+  "version": "0.1.65",
   "description": "Database adapter utilities for atscript.",
   "keywords": [
     "atscript",
@@ -69,13 +69,13 @@
   "devDependencies": {
     "@atscript/core": "^0.1.50",
     "@atscript/typescript": "^0.1.50",
-    "@uniqu/core": "^0.1.5",
+    "@uniqu/core": "^0.1.6",
     "unplugin-atscript": "^0.1.50"
   },
   "peerDependencies": {
     "@atscript/core": "^0.1.50",
     "@atscript/typescript": "^0.1.50",
-    "@uniqu/core": "^0.1.5"
+    "@uniqu/core": "^0.1.6"
   },
   "scripts": {
     "postinstall": "asc -f dts",