@atscript/db 0.1.110 → 0.1.111

package/dist/{db-view-CHprAlvK.mjs → db-view-BllUecjK.mjs}

@@ -2101,6 +2101,31 @@ var NativeIntegrity = class extends IntegrityStrategy {
 	}
 };
 //#endregion
+//#region src/shared/failure-collector.ts
+/**
+* Collects failures from a batch of independent operations so one failing
+* operation (e.g. CREATE UNIQUE INDEX over duplicate rows) doesn't abort the
+* rest. Run every operation through `attempt`, then call `throwIfAny()` to
+* rethrow the collected failures as a single aggregate error — so the caller
+* (schema sync) still marks the entry errored and skips persisting the schema
+* hash, and the next boot retries.
+*/
+function createFailureCollector(what) {
+	const failures = [];
+	return {
+		attempt: async (label, op) => {
+			try {
+				await op();
+			} catch (error) {
+				failures.push(`${label}: ${error.message}`);
+			}
+		},
+		throwIfAny: () => {
+			if (failures.length > 0) throw new Error(`${what} failed for ${failures.length} operation(s): ${failures.join("; ")}`);
+		}
+	};
+}
+//#endregion
 //#region src/base-adapter.ts
 const EMPTY_DEFAULT_FNS = /* @__PURE__ */ new Set();
 const txStorage = new AsyncLocalStorage();
@@ -2387,6 +2412,7 @@ var BaseDbAdapter = class {
 		const existingNames = new Set(managed.map((i) => i.name));
 		const existingColumns = new Map(managed.filter((i) => i.columns).map((i) => [i.name, i.columns]));
 		const desiredNames = /* @__PURE__ */ new Set();
+		const { attempt, throwIfAny } = createFailureCollector("index sync");
 		for (const index of this._table.indexes.values()) {
 			if (opts.warnUnsupportedTypes?.types.includes(index.type)) {
 				this.logger.warn(`[${opts.warnUnsupportedTypes.adapter}] ${index.type} index "${index.name}" declared but not supported by this adapter — skipped`);
@@ -2395,19 +2421,20 @@ var BaseDbAdapter = class {
 			if (opts.shouldSkipType?.(index.type)) continue;
 			desiredNames.add(index.key);
 			if (!existingNames.has(index.key)) {
-				await opts.createIndex(index);
+				await attempt(`create index "${index.key}"`, () => opts.createIndex(index));
 				continue;
 			}
 			if (index.type === "plain" || index.type === "unique") {
 				const liveColumns = existingColumns.get(index.key);
 				const desiredColumns = index.fields.map((f) => f.name);
-				if (liveColumns && (liveColumns.length !== desiredColumns.length || liveColumns.some((c, i) => c !== desiredColumns[i]))) {
+				if (liveColumns && (liveColumns.length !== desiredColumns.length || liveColumns.some((c, i) => c !== desiredColumns[i]))) await attempt(`rebuild index "${index.key}"`, async () => {
 					await opts.dropIndex(index.key);
 					await opts.createIndex(index);
-				}
+				});
 			}
 		}
-		for (const name of existingNames) if (!desiredNames.has(name)) await opts.dropIndex(name);
+		for (const name of existingNames) if (!desiredNames.has(name)) await attempt(`drop index "${name}"`, () => opts.dropIndex(name));
+		throwIfAny();
 	}
 	/**
 	* Returns available search indexes for this adapter.
@@ -3678,4 +3705,4 @@ var AtscriptDbView = class extends AtscriptDbReadable {
 	}
 };
 //#endregion
-export { NoopLogger as S, FieldMappingStrategy as _, ApplicationIntegrity as a, isGeoIndexableType as b, NativeIntegrity as c, assertGeoPoint as d, guardAggregate as f, DocumentFieldMapper as g, RelationalFieldMapper as h, decomposePatch as i, AtscriptDbReadable as l, guardQuery as m, AtscriptDbTable as n, BaseDbAdapter as o, guardFilter as p, assertNoVersionWrites as r, IntegrityStrategy as s, AtscriptDbView as t, resolveDesignType as u, UniquSelect as v, isGeoPointType as x, TableMetadata as y };
+export { NoopLogger as C, isGeoPointType as S, DocumentFieldMapper as _, ApplicationIntegrity as a, TableMetadata as b, IntegrityStrategy as c, resolveDesignType as d, assertGeoPoint as f, RelationalFieldMapper as g, guardQuery as h, decomposePatch as i, NativeIntegrity as l, guardFilter as m, AtscriptDbTable as n, BaseDbAdapter as o, guardAggregate as p, assertNoVersionWrites as r, createFailureCollector as s, AtscriptDbView as t, AtscriptDbReadable as u, FieldMappingStrategy as v, isGeoIndexableType as x, UniquSelect as y };

package/dist/{db-view-BIbH65VE.cjs → db-view-UfGVUAol.cjs}

@@ -2101,6 +2101,31 @@ var NativeIntegrity = class extends IntegrityStrategy {
 	}
 };
 //#endregion
+//#region src/shared/failure-collector.ts
+/**
+* Collects failures from a batch of independent operations so one failing
+* operation (e.g. CREATE UNIQUE INDEX over duplicate rows) doesn't abort the
+* rest. Run every operation through `attempt`, then call `throwIfAny()` to
+* rethrow the collected failures as a single aggregate error — so the caller
+* (schema sync) still marks the entry errored and skips persisting the schema
+* hash, and the next boot retries.
+*/
+function createFailureCollector(what) {
+	const failures = [];
+	return {
+		attempt: async (label, op) => {
+			try {
+				await op();
+			} catch (error) {
+				failures.push(`${label}: ${error.message}`);
+			}
+		},
+		throwIfAny: () => {
+			if (failures.length > 0) throw new Error(`${what} failed for ${failures.length} operation(s): ${failures.join("; ")}`);
+		}
+	};
+}
+//#endregion
 //#region src/base-adapter.ts
 const EMPTY_DEFAULT_FNS = /* @__PURE__ */ new Set();
 const txStorage = new node_async_hooks.AsyncLocalStorage();
@@ -2387,6 +2412,7 @@ var BaseDbAdapter = class {
 		const existingNames = new Set(managed.map((i) => i.name));
 		const existingColumns = new Map(managed.filter((i) => i.columns).map((i) => [i.name, i.columns]));
 		const desiredNames = /* @__PURE__ */ new Set();
+		const { attempt, throwIfAny } = createFailureCollector("index sync");
 		for (const index of this._table.indexes.values()) {
 			if (opts.warnUnsupportedTypes?.types.includes(index.type)) {
 				this.logger.warn(`[${opts.warnUnsupportedTypes.adapter}] ${index.type} index "${index.name}" declared but not supported by this adapter — skipped`);
@@ -2395,19 +2421,20 @@ var BaseDbAdapter = class {
 			if (opts.shouldSkipType?.(index.type)) continue;
 			desiredNames.add(index.key);
 			if (!existingNames.has(index.key)) {
-				await opts.createIndex(index);
+				await attempt(`create index "${index.key}"`, () => opts.createIndex(index));
 				continue;
 			}
 			if (index.type === "plain" || index.type === "unique") {
 				const liveColumns = existingColumns.get(index.key);
 				const desiredColumns = index.fields.map((f) => f.name);
-				if (liveColumns && (liveColumns.length !== desiredColumns.length || liveColumns.some((c, i) => c !== desiredColumns[i]))) {
+				if (liveColumns && (liveColumns.length !== desiredColumns.length || liveColumns.some((c, i) => c !== desiredColumns[i]))) await attempt(`rebuild index "${index.key}"`, async () => {
 					await opts.dropIndex(index.key);
 					await opts.createIndex(index);
-				}
+				});
 			}
 		}
-		for (const name of existingNames) if (!desiredNames.has(name)) await opts.dropIndex(name);
+		for (const name of existingNames) if (!desiredNames.has(name)) await attempt(`drop index "${name}"`, () => opts.dropIndex(name));
+		throwIfAny();
 	}
 	/**
 	* Returns available search indexes for this adapter.
@@ -3768,6 +3795,12 @@ Object.defineProperty(exports, "assertNoVersionWrites", {
 		return assertNoVersionWrites;
 	}
 });
+Object.defineProperty(exports, "createFailureCollector", {
+	enumerable: true,
+	get: function() {
+		return createFailureCollector;
+	}
+});
 Object.defineProperty(exports, "decomposePatch", {
 	enumerable: true,
 	get: function() {

package/dist/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_db_error = require("./db-error-DXwEzmYJ.cjs");
-const require_db_view = require("./db-view-BIbH65VE.cjs");
+const require_db_view = require("./db-view-UfGVUAol.cjs");
 const require_ops = require("./ops.cjs");
 const require_validator = require("./validator-BSk8lPH1.cjs");
 let node_crypto = require("node:crypto");
@@ -377,6 +377,7 @@ Object.defineProperty(exports, "computeInsights", {
 	}
 });
 exports.createDbValidatorPlugin = require_validator.createDbValidatorPlugin;
+exports.createFailureCollector = require_db_view.createFailureCollector;
 exports.decomposePatch = require_db_view.decomposePatch;
 exports.forceNavNonOptional = require_validator.forceNavNonOptional;
 exports.getDbFieldOp = require_ops.getDbFieldOp;

package/dist/index.d.cts

@@ -215,4 +215,18 @@ declare function decomposePatch(payload: Record<string, unknown>, table: Atscrip
  */
 declare function assertNoVersionWrites(data: Record<string, unknown>, versionColumn: string): void;
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, CasExhaustedError, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbQuery, type DbResponse, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type TAdapterFactory, type TArrayPatch, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TExistingColumn, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TIdDescriptor, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TRelationInfo, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WithOptimisticRetryOptions, type WithRelation, assertGeoPoint, assertNoVersionWrites, buildDbValidator, buildValidationContext, computeInsights, createDbValidatorPlugin, decomposePatch, forceNavNonOptional, getDbFieldOp, getKeyProps, guardAggregate, guardFilter, guardQuery, isDbFieldOp, isGeoIndexableType, isGeoPointType, isNavRelation, isPrimitive, resolveDesignType, separateCas, separateFieldOps, translateQueryTree, walkFilter, withOptimisticRetry };
+//#region src/shared/failure-collector.d.ts
+/**
+ * Collects failures from a batch of independent operations so one failing
+ * operation (e.g. CREATE UNIQUE INDEX over duplicate rows) doesn't abort the
+ * rest. Run every operation through `attempt`, then call `throwIfAny()` to
+ * rethrow the collected failures as a single aggregate error — so the caller
+ * (schema sync) still marks the entry errored and skips persisting the schema
+ * hash, and the next boot retries.
+ */
+declare function createFailureCollector(what: string): {
+  attempt: (label: string, op: () => Promise<unknown>) => Promise<void>;
+  throwIfAny: () => void;
+};
+//#endregion
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, CasExhaustedError, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbQuery, type DbResponse, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type TAdapterFactory, type TArrayPatch, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TExistingColumn, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TIdDescriptor, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TRelationInfo, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WithOptimisticRetryOptions, type WithRelation, 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 };

package/dist/index.d.mts

@@ -215,4 +215,18 @@ declare function decomposePatch(payload: Record<string, unknown>, table: Atscrip
  */
 declare function assertNoVersionWrites(data: Record<string, unknown>, versionColumn: string): void;
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, CasExhaustedError, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbQuery, type DbResponse, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type TAdapterFactory, type TArrayPatch, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TExistingColumn, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TIdDescriptor, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TRelationInfo, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WithOptimisticRetryOptions, type WithRelation, assertGeoPoint, assertNoVersionWrites, buildDbValidator, buildValidationContext, computeInsights, createDbValidatorPlugin, decomposePatch, forceNavNonOptional, getDbFieldOp, getKeyProps, guardAggregate, guardFilter, guardQuery, isDbFieldOp, isGeoIndexableType, isGeoPointType, isNavRelation, isPrimitive, resolveDesignType, separateCas, separateFieldOps, translateQueryTree, walkFilter, withOptimisticRetry };
+//#region src/shared/failure-collector.d.ts
+/**
+ * Collects failures from a batch of independent operations so one failing
+ * operation (e.g. CREATE UNIQUE INDEX over duplicate rows) doesn't abort the
+ * rest. Run every operation through `attempt`, then call `throwIfAny()` to
+ * rethrow the collected failures as a single aggregate error — so the caller
+ * (schema sync) still marks the entry errored and skips persisting the schema
+ * hash, and the next boot retries.
+ */
+declare function createFailureCollector(what: string): {
+  attempt: (label: string, op: () => Promise<unknown>) => Promise<void>;
+  throwIfAny: () => void;
+};
+//#endregion
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, CasExhaustedError, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbQuery, type DbResponse, DbSpace, type DbValidationContext, DocumentFieldMapper, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type OwnPropsOf, type PrimaryKeyOf, RelationalFieldMapper, type TAdapterFactory, type TArrayPatch, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TExistingColumn, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TIdDescriptor, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TRelationInfo, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TValueFormatterPair, type TViewColumnMapping, type TViewJoin, type TViewPlan, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WithOptimisticRetryOptions, type WithRelation, 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 };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { n as DbError, t as CasExhaustedError } from "./db-error-BHPXOKzc.mjs";
-import { S as NoopLogger, _ as FieldMappingStrategy, a as ApplicationIntegrity, b as isGeoIndexableType, c as NativeIntegrity, d as assertGeoPoint, f as guardAggregate, g as DocumentFieldMapper, h as RelationalFieldMapper, i as decomposePatch, l as AtscriptDbReadable, m as guardQuery, n as AtscriptDbTable, o as BaseDbAdapter, p as guardFilter, r as assertNoVersionWrites, s as IntegrityStrategy, t as AtscriptDbView, u as resolveDesignType, v as UniquSelect, x as isGeoPointType, y as TableMetadata } from "./db-view-CHprAlvK.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-BllUecjK.mjs";
 import { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, getDbFieldOp, isDbFieldOp, separateCas, 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-C7plt6Kf.mjs";
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
@@ -339,4 +339,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, DbEncryption, DbError, DbSpace, DocumentFieldMapper, FieldMappingStrategy, IntegrityStrategy, NativeIntegrity, NoopLogger, RelationalFieldMapper, TableMetadata, UniquSelect, assertGeoPoint, assertNoVersionWrites, buildDbValidator, buildValidationContext, computeInsights, createDbValidatorPlugin, 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, 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 };

package/dist/plugin.cjs

@@ -2,13 +2,14 @@ Object.defineProperties(exports, {
 	__esModule: { value: true },
 	[Symbol.toStringTag]: { value: "Module" }
 });
-const require_validation_utils = require("./validation-utils-CR4H3_nc.cjs");
+const require_validation_utils = require("./validation-utils-B7SXPkm7.cjs");
 let _atscript_core = require("@atscript/core");
 //#region src/plugin/annotations/agg.ts
 const dbAggAnnotations = { agg: {
 	sum: new _atscript_core.AnnotationSpec({
 		description: "Declares a view field as SUM of a source column.",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		argument: {
 			name: "field",
 			type: "string",
@@ -21,6 +22,7 @@ const dbAggAnnotations = { agg: {
 	avg: new _atscript_core.AnnotationSpec({
 		description: "Declares a view field as AVG of a source column.",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		argument: {
 			name: "field",
 			type: "string",
@@ -33,6 +35,7 @@ const dbAggAnnotations = { agg: {
 	count: new _atscript_core.AnnotationSpec({
 		description: "Declares a view field as COUNT. Without argument: COUNT(*). With field name argument: COUNT(field) (non-null count).",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		argument: {
 			name: "field",
 			type: "string",
@@ -46,6 +49,7 @@ const dbAggAnnotations = { agg: {
 	min: new _atscript_core.AnnotationSpec({
 		description: "Declares a view field as MIN of a source column.",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		argument: {
 			name: "field",
 			type: "string",
@@ -55,6 +59,7 @@ const dbAggAnnotations = { agg: {
 	max: new _atscript_core.AnnotationSpec({
 		description: "Declares a view field as MAX of a source column.",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		argument: {
 			name: "field",
 			type: "string",
@@ -94,6 +99,7 @@ const dbAmountAnnotations = { amount: { currency: {
 	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"],
+		passedWhenReferred: false,
 		multiple: false,
 		argument: {
 			name: "fieldName",
@@ -121,6 +127,7 @@ const dbColumnAnnotations = {
 	patch: { strategy: new _atscript_core.AnnotationSpec({
 		description: "Defines the **patching strategy** for updating nested objects.\n\n- **\"replace\"** → The field or object will be **fully replaced**.\n- **\"merge\"** → The field or object will be **merged recursively** (applies only to objects, not arrays).\n\n**Example:**\n```atscript\n@db.patch.strategy \"merge\"\nsettings: {\n  notifications: boolean\n  preferences: {\n    theme: string\n  }\n}\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		multiple: false,
 		argument: {
 			name: "strategy",
@@ -150,6 +157,7 @@ const dbColumnAnnotations = {
 		$self: new _atscript_core.AnnotationSpec({
 			description: "Overrides the physical column name in the database. For nested (flattened) fields, the parent prefix is still prepended automatically.\n\n**Example:**\n```atscript\n@db.column \"first_name\"\nfirstName: string\n// → physical column: first_name\n\n// Nested:\naddress: {\n  @db.column \"zip_code\"\n  zip: string\n}\n// → physical column: address__zip_code\n```\n",
 			nodeType: ["prop"],
+			passedWhenReferred: false,
 			argument: {
 				name: "name",
 				type: "string",
@@ -159,6 +167,7 @@ const dbColumnAnnotations = {
 		renamed: new _atscript_core.AnnotationSpec({
 			description: "Specifies the previous local field name for column rename migration. The sync engine generates ALTER TABLE RENAME COLUMN instead of drop+add.\n\n**Example:**\n```atscript\n@db.column.renamed \"zip\"\npostalCode: string\n// Renames address__zip → address__postalCode\n```\n",
 			nodeType: ["prop"],
+			passedWhenReferred: false,
 			argument: {
 				name: "oldName",
 				type: "string",
@@ -168,6 +177,7 @@ const dbColumnAnnotations = {
 		collate: new _atscript_core.AnnotationSpec({
 			description: "Portable collation for string comparison and sorting. Adapters map the generic value to their native collation.\n\n- **\"binary\"** — exact byte comparison (case-sensitive)\n- **\"nocase\"** — case-insensitive comparison\n- **\"unicode\"** — full Unicode-aware sorting\n\nFor adapter-specific collations, use `@db.<engine>.collate` instead.\n\n**Example:**\n```atscript\n@db.column.collate \"nocase\"\nusername: string\n```\n",
 			nodeType: ["prop"],
+			passedWhenReferred: false,
 			argument: {
 				name: "collation",
 				type: "string",
@@ -185,6 +195,7 @@ const dbColumnAnnotations = {
 		precision: new _atscript_core.AnnotationSpec({
 			description: "Sets decimal precision and scale for database storage. Adapters map this to their native decimal type (e.g., `DECIMAL(10,2)` in SQL, ignored in MongoDB).\n\nFor `decimal` fields the runtime value is a string; for `number` fields this is a DB storage hint only.\n\n**Example:**\n```atscript\n@db.column.precision 10, 2\nprice: decimal\n```\n",
 			nodeType: ["prop"],
+			passedWhenReferred: false,
 			argument: [{
 				name: "precision",
 				type: "number",
@@ -200,11 +211,13 @@ const dbColumnAnnotations = {
 		}),
 		dimension: new _atscript_core.AnnotationSpec({
 			description: "Marks a field as a dimension — groupable in aggregate queries ($groupBy). Dimension fields automatically receive a database index during schema sync.",
-			nodeType: ["prop"]
+			nodeType: ["prop"],
+			passedWhenReferred: false
 		}),
 		measure: new _atscript_core.AnnotationSpec({
 			description: "Marks a field as a measure — aggregatable in aggregate queries (sum, avg, count, min, max). Only valid on numeric or decimal fields.",
 			nodeType: ["prop"],
+			passedWhenReferred: false,
 			validate(token, _args, doc) {
 				return require_validation_utils.validateFieldBaseType(token, doc, "@db.column.measure", ["number", "decimal"]);
 			}
@@ -214,6 +227,7 @@ const dbColumnAnnotations = {
 		version: new _atscript_core.AnnotationSpec({
 			description: "Marks a numeric column as the row's version for optimistic concurrency control (OCC). The adapter auto-increments this column on every UPDATE, and callers may pass `$cas: { <col>: N }` in a write payload to make the update conditional on the current version. Direct writes to the version column (as plain SET, `$inc`, or `$mul`) are rejected.\n\n**Constraints:**\n- At most one version column per table.\n- Must resolve to an integer type (`int`, `int32`, `int64`, etc.).\n- Default value on insert is `0`.\n\n**Example:**\n```atscript\n@db.column.version\nversion: int\n```\n",
 			nodeType: ["prop"],
+			passedWhenReferred: false,
 			validate(token, _args, doc) {
 				const errors = require_validation_utils.validateFieldBaseType(token, doc, "@db.column.version", "number");
 				if (token.parentNode.has("optional")) errors.push({
@@ -239,6 +253,7 @@ const dbColumnAnnotations = {
 		$self: new _atscript_core.AnnotationSpec({
 			description: "Sets a static DB-level default value (used in DDL DEFAULT clause). For string fields the value is used as-is; for other types it is parsed as JSON.\n\n**Example:**\n```atscript\n@db.default \"active\"\nstatus: string\n```\n",
 			nodeType: ["prop"],
+			passedWhenReferred: false,
 			argument: {
 				name: "value",
 				type: "string",
@@ -248,6 +263,7 @@ const dbColumnAnnotations = {
 		increment: new _atscript_core.AnnotationSpec({
 			description: "Auto-incrementing integer default. Each adapter maps this to its native mechanism (e.g., `AUTO_INCREMENT` in MySQL, `INTEGER PRIMARY KEY` in SQLite, counter collection in MongoDB).\n\n**Example:**\n```atscript\n@db.default.increment\nid: number.int\n\n// With optional start value:\n@db.default.increment 1000\nid: number.int\n```\n",
 			nodeType: ["prop"],
+			passedWhenReferred: false,
 			argument: {
 				optional: true,
 				name: "start",
@@ -261,6 +277,7 @@ const dbColumnAnnotations = {
 		uuid: new _atscript_core.AnnotationSpec({
 			description: "UUID generation default. Each adapter maps this to its native mechanism (e.g., `DEFAULT (UUID())` in MySQL, `gen_random_uuid()` in PostgreSQL, app-level in SQLite).\n\n**Example:**\n```atscript\n@db.default.uuid\nid: string.uuid\n```\n",
 			nodeType: ["prop"],
+			passedWhenReferred: false,
 			validate(token, args, doc) {
 				return require_validation_utils.validateFieldBaseType(token, doc, "db.default.uuid", "string");
 			}
@@ -268,6 +285,7 @@ const dbColumnAnnotations = {
 		now: new _atscript_core.AnnotationSpec({
 			description: "Current timestamp default. Each adapter maps this to its native mechanism (e.g., `DEFAULT CURRENT_TIMESTAMP` in MySQL, `DEFAULT now()` in PostgreSQL).\n\n**Example:**\n```atscript\n@db.default.now\ncreatedAt: number.timestamp\n```\n",
 			nodeType: ["prop"],
+			passedWhenReferred: false,
 			validate(token, args, doc) {
 				return require_validation_utils.validateFieldBaseType(token, doc, "db.default.now", ["number", "string"]);
 			}
@@ -276,6 +294,7 @@ const dbColumnAnnotations = {
 	json: new _atscript_core.AnnotationSpec({
 		description: "Forces a field to be stored as a single JSON column instead of being flattened into separate columns. Use on nested object fields that should remain as JSON in the database.\n\n**Example:**\n```atscript\n@db.json\nmetadata: { key: string, value: string }\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		validate(token, _args, doc) {
 			const errors = [];
 			const definition = token.parentNode.getDefinition();
@@ -293,6 +312,7 @@ const dbColumnAnnotations = {
 	ignore: new _atscript_core.AnnotationSpec({
 		description: "Excludes a field from the database schema. The field exists in the Atscript type but has no column in the DB.\n\n**Example:**\n```atscript\n@db.ignore\ndisplayName: string\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		validate(token, _args, _doc) {
 			const errors = [];
 			if (token.parentNode.countAnnotations("meta.id") > 0) errors.push({
@@ -306,6 +326,7 @@ const dbColumnAnnotations = {
 	encrypted: new _atscript_core.AnnotationSpec({
 		description: "Encrypts this field at rest. Values are AES-256-GCM encrypted by the core layer before reaching the database and decrypted on read — transparent to application code.\n\nConstraints: the field cannot be filtered, sorted, indexed, used as PK/FK, patched with arithmetic ops, or referenced by search/vector/geo features.\n\n**Example:**\n```atscript\n@db.encrypted\napiToken?: string\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		multiple: false,
 		validate(token, _args, _doc) {
 			const errors = [];
@@ -344,6 +365,7 @@ function columnCapability(capability, verb) {
 @db.table.${capability} "manual"\nexport interface User {
 ` + example + "}\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		multiple: false,
 		validate(token, _args, _doc) {
 			const errors = [];
@@ -363,6 +385,7 @@ const dbIndexAnnotations = { index: {
 	plain: new _atscript_core.AnnotationSpec({
 		description: "Standard (non-unique) index for query performance. Fields sharing the same index name form a composite index.\n\n**Example:**\n```atscript\n@db.index.plain \"idx_timeline\", \"desc\"\ncreatedAt: number.timestamp\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		multiple: true,
 		mergeStrategy: "append",
 		argument: [{
@@ -381,6 +404,7 @@ const dbIndexAnnotations = { index: {
 	unique: new _atscript_core.AnnotationSpec({
 		description: "Unique index — ensures no two rows/documents have the same value(s). Fields sharing the same index name form a composite unique constraint.\n\n**Example:**\n```atscript\n@db.index.unique \"tenant_email\"\nemail: string.email\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		multiple: true,
 		mergeStrategy: "append",
 		argument: {
@@ -393,6 +417,7 @@ const dbIndexAnnotations = { index: {
 	fulltext: new _atscript_core.AnnotationSpec({
 		description: "Full-text search index. Fields sharing the same index name form a composite full-text index.\n\n**Example:**\n```atscript\n@db.index.fulltext \"ft_content\"\ntitle: string\n\n@db.index.fulltext \"ft_content\", 5\nbio: string\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		multiple: true,
 		mergeStrategy: "append",
 		argument: [{
@@ -410,6 +435,7 @@ const dbIndexAnnotations = { index: {
 	geo: new _atscript_core.AnnotationSpec({
 		description: "Geospatial index on a `db.geoPoint` field. Enables `geoSearch()` (distance-ranked) and accelerates `$geoWithin` filters.\n\n**Example:**\n```atscript\n@db.index.geo\ngeo: db.geoPoint\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		multiple: false,
 		argument: {
 			optional: true,
@@ -425,6 +451,7 @@ 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",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		argument: {
 			optional: true,
 			name: "alias",
@@ -509,6 +536,7 @@ const dbRelAnnotations = { rel: {
 	to: new _atscript_core.AnnotationSpec({
 		description: "Forward navigational property — the FK is on **this** interface. The compiler resolves the matching @db.rel.FK by target type or alias.\n\n**Example:**\n```atscript\n@db.rel.to\nauthor?: User\n\n// With alias\n@db.rel.to \"author\"\nauthor?: User\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		argument: {
 			optional: true,
 			name: "alias",
@@ -592,6 +620,7 @@ const dbRelAnnotations = { rel: {
 	from: new _atscript_core.AnnotationSpec({
 		description: "Inverse navigational property — the FK is on the **target** interface, pointing back to this one.\n\n**Example:**\n```atscript\n@db.rel.from\nposts: Post[]\n\n// With alias\n@db.rel.from \"original\"\ncomments: Comment[]\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		argument: {
 			optional: true,
 			name: "alias",
@@ -680,6 +709,7 @@ const dbRelAnnotations = { rel: {
 	via: new _atscript_core.AnnotationSpec({
 		description: "Declares a many-to-many navigational property through an explicit junction table. `@db.rel.via` is self-sufficient — no `@db.rel.from` pairing is needed.\n\n**Example:**\n```atscript\n@db.rel.via PostTag\ntags: Tag[]\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		argument: {
 			name: "junction",
 			type: "ref",
@@ -739,6 +769,7 @@ const dbRelAnnotations = { rel: {
 	filter: new _atscript_core.AnnotationSpec({
 		description: "Applies a filter to a navigational property, restricting which related records are loaded.\n\n**Example:**\n```atscript\n@db.rel.from\n@db.rel.filter `Post.published = true`\npublishedPosts: Post[]\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		argument: {
 			name: "condition",
 			type: "query",
@@ -778,6 +809,7 @@ const dbSearchAnnotations = { search: {
 		$self: new _atscript_core.AnnotationSpec({
 			description: "Marks a field as a **vector embedding** for **similarity search**.\n\n- Each adapter maps this to its native vector type and index:\n  - **MongoDB** → Atlas `$vectorSearch` index\n  - **MySQL 9+** → `VECTOR(N)` column + `VEC_DISTANCE_*` functions\n  - **PostgreSQL** → pgvector `vector(N)` column + distance operators\n  - **SQLite** → `BLOB` column + `vec0` virtual index (requires the `sqlite-vec` extension; falls back to JSON `TEXT` when unavailable)\n\n**Example:**\n```atscript\n@db.search.vector 1536, \"cosine\"\nembedding: db.vector\n```\n",
 			nodeType: ["prop"],
+			passedWhenReferred: false,
 			multiple: false,
 			argument: [
 				{
@@ -822,6 +854,7 @@ const dbSearchAnnotations = { search: {
 		threshold: new _atscript_core.AnnotationSpec({
 			description: "Sets a **default minimum similarity threshold** for vector search queries on this field.\n\n- Results with a similarity score below this threshold are excluded.\n- Query-time `$threshold` control overrides this default.\n- Value range: `0` to `1` (where `1` means exact match).\n\n**Example:**\n```atscript\n@db.search.vector 1536, \"cosine\"\n@db.search.vector.threshold 0.7\nembedding: db.vector\n```\n",
 			nodeType: ["prop"],
+			passedWhenReferred: false,
 			multiple: false,
 			argument: {
 				optional: false,
@@ -834,6 +867,7 @@ const dbSearchAnnotations = { search: {
 	filter: new _atscript_core.AnnotationSpec({
 		description: "Assigns a field as a **pre-filter** for a **vector search index**.\n\n- Filters allow vector search queries to return results only within a specific subset.\n- The referenced index must be defined using `@db.search.vector`.\n\n**Example:**\n```atscript\n@db.search.vector 1536, \"cosine\"\nembedding: db.vector\n\n@db.search.filter \"embedding\"\ncategory: string\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		multiple: true,
 		argument: {
 			optional: false,
@@ -1074,6 +1108,7 @@ const dbUnitAnnotations = { unit: {
 	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"],
+		passedWhenReferred: false,
 		multiple: false,
 		argument: {
 			name: "fieldName",

package/dist/plugin.mjs

@@ -1,10 +1,11 @@
-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-D4R08oed.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-MWOP1Ts4.mjs";
 import { AnnotationSpec, isArray, isInterface, isPrimitive, isRef, isStructure } from "@atscript/core";
 //#region src/plugin/annotations/agg.ts
 const dbAggAnnotations = { agg: {
 	sum: new AnnotationSpec({
 		description: "Declares a view field as SUM of a source column.",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		argument: {
 			name: "field",
 			type: "string",
@@ -17,6 +18,7 @@ const dbAggAnnotations = { agg: {
 	avg: new AnnotationSpec({
 		description: "Declares a view field as AVG of a source column.",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		argument: {
 			name: "field",
 			type: "string",
@@ -29,6 +31,7 @@ const dbAggAnnotations = { agg: {
 	count: new AnnotationSpec({
 		description: "Declares a view field as COUNT. Without argument: COUNT(*). With field name argument: COUNT(field) (non-null count).",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		argument: {
 			name: "field",
 			type: "string",
@@ -42,6 +45,7 @@ const dbAggAnnotations = { agg: {
 	min: new AnnotationSpec({
 		description: "Declares a view field as MIN of a source column.",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		argument: {
 			name: "field",
 			type: "string",
@@ -51,6 +55,7 @@ const dbAggAnnotations = { agg: {
 	max: new AnnotationSpec({
 		description: "Declares a view field as MAX of a source column.",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		argument: {
 			name: "field",
 			type: "string",
@@ -90,6 +95,7 @@ const dbAmountAnnotations = { amount: { currency: {
 	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"],
+		passedWhenReferred: false,
 		multiple: false,
 		argument: {
 			name: "fieldName",
@@ -117,6 +123,7 @@ const dbColumnAnnotations = {
 	patch: { strategy: new AnnotationSpec({
 		description: "Defines the **patching strategy** for updating nested objects.\n\n- **\"replace\"** → The field or object will be **fully replaced**.\n- **\"merge\"** → The field or object will be **merged recursively** (applies only to objects, not arrays).\n\n**Example:**\n```atscript\n@db.patch.strategy \"merge\"\nsettings: {\n  notifications: boolean\n  preferences: {\n    theme: string\n  }\n}\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		multiple: false,
 		argument: {
 			name: "strategy",
@@ -146,6 +153,7 @@ const dbColumnAnnotations = {
 		$self: new AnnotationSpec({
 			description: "Overrides the physical column name in the database. For nested (flattened) fields, the parent prefix is still prepended automatically.\n\n**Example:**\n```atscript\n@db.column \"first_name\"\nfirstName: string\n// → physical column: first_name\n\n// Nested:\naddress: {\n  @db.column \"zip_code\"\n  zip: string\n}\n// → physical column: address__zip_code\n```\n",
 			nodeType: ["prop"],
+			passedWhenReferred: false,
 			argument: {
 				name: "name",
 				type: "string",
@@ -155,6 +163,7 @@ const dbColumnAnnotations = {
 		renamed: new AnnotationSpec({
 			description: "Specifies the previous local field name for column rename migration. The sync engine generates ALTER TABLE RENAME COLUMN instead of drop+add.\n\n**Example:**\n```atscript\n@db.column.renamed \"zip\"\npostalCode: string\n// Renames address__zip → address__postalCode\n```\n",
 			nodeType: ["prop"],
+			passedWhenReferred: false,
 			argument: {
 				name: "oldName",
 				type: "string",
@@ -164,6 +173,7 @@ const dbColumnAnnotations = {
 		collate: new AnnotationSpec({
 			description: "Portable collation for string comparison and sorting. Adapters map the generic value to their native collation.\n\n- **\"binary\"** — exact byte comparison (case-sensitive)\n- **\"nocase\"** — case-insensitive comparison\n- **\"unicode\"** — full Unicode-aware sorting\n\nFor adapter-specific collations, use `@db.<engine>.collate` instead.\n\n**Example:**\n```atscript\n@db.column.collate \"nocase\"\nusername: string\n```\n",
 			nodeType: ["prop"],
+			passedWhenReferred: false,
 			argument: {
 				name: "collation",
 				type: "string",
@@ -181,6 +191,7 @@ const dbColumnAnnotations = {
 		precision: new AnnotationSpec({
 			description: "Sets decimal precision and scale for database storage. Adapters map this to their native decimal type (e.g., `DECIMAL(10,2)` in SQL, ignored in MongoDB).\n\nFor `decimal` fields the runtime value is a string; for `number` fields this is a DB storage hint only.\n\n**Example:**\n```atscript\n@db.column.precision 10, 2\nprice: decimal\n```\n",
 			nodeType: ["prop"],
+			passedWhenReferred: false,
 			argument: [{
 				name: "precision",
 				type: "number",
@@ -196,11 +207,13 @@ const dbColumnAnnotations = {
 		}),
 		dimension: new AnnotationSpec({
 			description: "Marks a field as a dimension — groupable in aggregate queries ($groupBy). Dimension fields automatically receive a database index during schema sync.",
-			nodeType: ["prop"]
+			nodeType: ["prop"],
+			passedWhenReferred: false
 		}),
 		measure: new AnnotationSpec({
 			description: "Marks a field as a measure — aggregatable in aggregate queries (sum, avg, count, min, max). Only valid on numeric or decimal fields.",
 			nodeType: ["prop"],
+			passedWhenReferred: false,
 			validate(token, _args, doc) {
 				return validateFieldBaseType(token, doc, "@db.column.measure", ["number", "decimal"]);
 			}
@@ -210,6 +223,7 @@ const dbColumnAnnotations = {
 		version: new AnnotationSpec({
 			description: "Marks a numeric column as the row's version for optimistic concurrency control (OCC). The adapter auto-increments this column on every UPDATE, and callers may pass `$cas: { <col>: N }` in a write payload to make the update conditional on the current version. Direct writes to the version column (as plain SET, `$inc`, or `$mul`) are rejected.\n\n**Constraints:**\n- At most one version column per table.\n- Must resolve to an integer type (`int`, `int32`, `int64`, etc.).\n- Default value on insert is `0`.\n\n**Example:**\n```atscript\n@db.column.version\nversion: int\n```\n",
 			nodeType: ["prop"],
+			passedWhenReferred: false,
 			validate(token, _args, doc) {
 				const errors = validateFieldBaseType(token, doc, "@db.column.version", "number");
 				if (token.parentNode.has("optional")) errors.push({
@@ -235,6 +249,7 @@ const dbColumnAnnotations = {
 		$self: new AnnotationSpec({
 			description: "Sets a static DB-level default value (used in DDL DEFAULT clause). For string fields the value is used as-is; for other types it is parsed as JSON.\n\n**Example:**\n```atscript\n@db.default \"active\"\nstatus: string\n```\n",
 			nodeType: ["prop"],
+			passedWhenReferred: false,
 			argument: {
 				name: "value",
 				type: "string",
@@ -244,6 +259,7 @@ const dbColumnAnnotations = {
 		increment: new AnnotationSpec({
 			description: "Auto-incrementing integer default. Each adapter maps this to its native mechanism (e.g., `AUTO_INCREMENT` in MySQL, `INTEGER PRIMARY KEY` in SQLite, counter collection in MongoDB).\n\n**Example:**\n```atscript\n@db.default.increment\nid: number.int\n\n// With optional start value:\n@db.default.increment 1000\nid: number.int\n```\n",
 			nodeType: ["prop"],
+			passedWhenReferred: false,
 			argument: {
 				optional: true,
 				name: "start",
@@ -257,6 +273,7 @@ const dbColumnAnnotations = {
 		uuid: new AnnotationSpec({
 			description: "UUID generation default. Each adapter maps this to its native mechanism (e.g., `DEFAULT (UUID())` in MySQL, `gen_random_uuid()` in PostgreSQL, app-level in SQLite).\n\n**Example:**\n```atscript\n@db.default.uuid\nid: string.uuid\n```\n",
 			nodeType: ["prop"],
+			passedWhenReferred: false,
 			validate(token, args, doc) {
 				return validateFieldBaseType(token, doc, "db.default.uuid", "string");
 			}
@@ -264,6 +281,7 @@ const dbColumnAnnotations = {
 		now: new AnnotationSpec({
 			description: "Current timestamp default. Each adapter maps this to its native mechanism (e.g., `DEFAULT CURRENT_TIMESTAMP` in MySQL, `DEFAULT now()` in PostgreSQL).\n\n**Example:**\n```atscript\n@db.default.now\ncreatedAt: number.timestamp\n```\n",
 			nodeType: ["prop"],
+			passedWhenReferred: false,
 			validate(token, args, doc) {
 				return validateFieldBaseType(token, doc, "db.default.now", ["number", "string"]);
 			}
@@ -272,6 +290,7 @@ const dbColumnAnnotations = {
 	json: new AnnotationSpec({
 		description: "Forces a field to be stored as a single JSON column instead of being flattened into separate columns. Use on nested object fields that should remain as JSON in the database.\n\n**Example:**\n```atscript\n@db.json\nmetadata: { key: string, value: string }\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		validate(token, _args, doc) {
 			const errors = [];
 			const definition = token.parentNode.getDefinition();
@@ -289,6 +308,7 @@ const dbColumnAnnotations = {
 	ignore: new AnnotationSpec({
 		description: "Excludes a field from the database schema. The field exists in the Atscript type but has no column in the DB.\n\n**Example:**\n```atscript\n@db.ignore\ndisplayName: string\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		validate(token, _args, _doc) {
 			const errors = [];
 			if (token.parentNode.countAnnotations("meta.id") > 0) errors.push({
@@ -302,6 +322,7 @@ const dbColumnAnnotations = {
 	encrypted: new AnnotationSpec({
 		description: "Encrypts this field at rest. Values are AES-256-GCM encrypted by the core layer before reaching the database and decrypted on read — transparent to application code.\n\nConstraints: the field cannot be filtered, sorted, indexed, used as PK/FK, patched with arithmetic ops, or referenced by search/vector/geo features.\n\n**Example:**\n```atscript\n@db.encrypted\napiToken?: string\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		multiple: false,
 		validate(token, _args, _doc) {
 			const errors = [];
@@ -340,6 +361,7 @@ function columnCapability(capability, verb) {
 @db.table.${capability} "manual"\nexport interface User {
 ` + example + "}\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		multiple: false,
 		validate(token, _args, _doc) {
 			const errors = [];
@@ -359,6 +381,7 @@ const dbIndexAnnotations = { index: {
 	plain: new AnnotationSpec({
 		description: "Standard (non-unique) index for query performance. Fields sharing the same index name form a composite index.\n\n**Example:**\n```atscript\n@db.index.plain \"idx_timeline\", \"desc\"\ncreatedAt: number.timestamp\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		multiple: true,
 		mergeStrategy: "append",
 		argument: [{
@@ -377,6 +400,7 @@ const dbIndexAnnotations = { index: {
 	unique: new AnnotationSpec({
 		description: "Unique index — ensures no two rows/documents have the same value(s). Fields sharing the same index name form a composite unique constraint.\n\n**Example:**\n```atscript\n@db.index.unique \"tenant_email\"\nemail: string.email\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		multiple: true,
 		mergeStrategy: "append",
 		argument: {
@@ -389,6 +413,7 @@ const dbIndexAnnotations = { index: {
 	fulltext: new AnnotationSpec({
 		description: "Full-text search index. Fields sharing the same index name form a composite full-text index.\n\n**Example:**\n```atscript\n@db.index.fulltext \"ft_content\"\ntitle: string\n\n@db.index.fulltext \"ft_content\", 5\nbio: string\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		multiple: true,
 		mergeStrategy: "append",
 		argument: [{
@@ -406,6 +431,7 @@ const dbIndexAnnotations = { index: {
 	geo: new AnnotationSpec({
 		description: "Geospatial index on a `db.geoPoint` field. Enables `geoSearch()` (distance-ranked) and accelerates `$geoWithin` filters.\n\n**Example:**\n```atscript\n@db.index.geo\ngeo: db.geoPoint\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		multiple: false,
 		argument: {
 			optional: true,
@@ -421,6 +447,7 @@ 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",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		argument: {
 			optional: true,
 			name: "alias",
@@ -505,6 +532,7 @@ const dbRelAnnotations = { rel: {
 	to: new AnnotationSpec({
 		description: "Forward navigational property — the FK is on **this** interface. The compiler resolves the matching @db.rel.FK by target type or alias.\n\n**Example:**\n```atscript\n@db.rel.to\nauthor?: User\n\n// With alias\n@db.rel.to \"author\"\nauthor?: User\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		argument: {
 			optional: true,
 			name: "alias",
@@ -588,6 +616,7 @@ const dbRelAnnotations = { rel: {
 	from: new AnnotationSpec({
 		description: "Inverse navigational property — the FK is on the **target** interface, pointing back to this one.\n\n**Example:**\n```atscript\n@db.rel.from\nposts: Post[]\n\n// With alias\n@db.rel.from \"original\"\ncomments: Comment[]\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		argument: {
 			optional: true,
 			name: "alias",
@@ -676,6 +705,7 @@ const dbRelAnnotations = { rel: {
 	via: new AnnotationSpec({
 		description: "Declares a many-to-many navigational property through an explicit junction table. `@db.rel.via` is self-sufficient — no `@db.rel.from` pairing is needed.\n\n**Example:**\n```atscript\n@db.rel.via PostTag\ntags: Tag[]\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		argument: {
 			name: "junction",
 			type: "ref",
@@ -735,6 +765,7 @@ const dbRelAnnotations = { rel: {
 	filter: new AnnotationSpec({
 		description: "Applies a filter to a navigational property, restricting which related records are loaded.\n\n**Example:**\n```atscript\n@db.rel.from\n@db.rel.filter `Post.published = true`\npublishedPosts: Post[]\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		argument: {
 			name: "condition",
 			type: "query",
@@ -774,6 +805,7 @@ const dbSearchAnnotations = { search: {
 		$self: new AnnotationSpec({
 			description: "Marks a field as a **vector embedding** for **similarity search**.\n\n- Each adapter maps this to its native vector type and index:\n  - **MongoDB** → Atlas `$vectorSearch` index\n  - **MySQL 9+** → `VECTOR(N)` column + `VEC_DISTANCE_*` functions\n  - **PostgreSQL** → pgvector `vector(N)` column + distance operators\n  - **SQLite** → `BLOB` column + `vec0` virtual index (requires the `sqlite-vec` extension; falls back to JSON `TEXT` when unavailable)\n\n**Example:**\n```atscript\n@db.search.vector 1536, \"cosine\"\nembedding: db.vector\n```\n",
 			nodeType: ["prop"],
+			passedWhenReferred: false,
 			multiple: false,
 			argument: [
 				{
@@ -818,6 +850,7 @@ const dbSearchAnnotations = { search: {
 		threshold: new AnnotationSpec({
 			description: "Sets a **default minimum similarity threshold** for vector search queries on this field.\n\n- Results with a similarity score below this threshold are excluded.\n- Query-time `$threshold` control overrides this default.\n- Value range: `0` to `1` (where `1` means exact match).\n\n**Example:**\n```atscript\n@db.search.vector 1536, \"cosine\"\n@db.search.vector.threshold 0.7\nembedding: db.vector\n```\n",
 			nodeType: ["prop"],
+			passedWhenReferred: false,
 			multiple: false,
 			argument: {
 				optional: false,
@@ -830,6 +863,7 @@ const dbSearchAnnotations = { search: {
 	filter: new AnnotationSpec({
 		description: "Assigns a field as a **pre-filter** for a **vector search index**.\n\n- Filters allow vector search queries to return results only within a specific subset.\n- The referenced index must be defined using `@db.search.vector`.\n\n**Example:**\n```atscript\n@db.search.vector 1536, \"cosine\"\nembedding: db.vector\n\n@db.search.filter \"embedding\"\ncategory: string\n```\n",
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		multiple: true,
 		argument: {
 			optional: false,
@@ -1070,6 +1104,7 @@ const dbUnitAnnotations = { unit: {
 	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"],
+		passedWhenReferred: false,
 		multiple: false,
 		argument: {
 			name: "fieldName",

package/dist/shared.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_validation_utils = require("./validation-utils-CR4H3_nc.cjs");
+const require_validation_utils = require("./validation-utils-B7SXPkm7.cjs");
 exports.findFKFieldsPointingTo = require_validation_utils.findFKFieldsPointingTo;
 exports.getAnnotationAlias = require_validation_utils.getAnnotationAlias;
 exports.getDbTableOwner = require_validation_utils.getDbTableOwner;

package/dist/shared.mjs

@@ -1,2 +1,2 @@
-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-D4R08oed.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-MWOP1Ts4.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-BIbH65VE.cjs");
+const require_db_view = require("./db-view-UfGVUAol.cjs");
 //#region src/schema/schema-hash.ts
 /** Extracts sorted field snapshots from a readable's field descriptors. */
 function extractFieldSnapshots(fields, typeMapper) {
@@ -930,6 +930,7 @@ var SchemaSync = class {
 	* Runs schema synchronization with distributed locking.
 	*/
 	async run(types, opts) {
+		this.logger = opts?.logger ?? this.logger;
 		const podId = opts?.podId ?? crypto.randomUUID();
 		const lockTtlMs = opts?.lockTtlMs ?? 3e4;
 		const waitTimeoutMs = opts?.waitTimeoutMs ?? 6e4;

package/dist/sync.d.cts

@@ -235,6 +235,11 @@ interface TSyncOptions {
   force?: boolean;
   /** Safe mode — skip destructive operations (column drops, table drops). Default: false. */
   safe?: boolean;
+  /**
+   * Logger for sync progress and failures (index/FK DDL errors are logged,
+   * not thrown). Default: NoopLogger — pass `console` to surface them.
+   */
+  logger?: TGenericLogger;
 }
 interface TSyncResult {
   status: "up-to-date" | "synced" | "synced-by-peer";
@@ -244,7 +249,7 @@ interface TSyncResult {
 declare class SchemaSync {
   private readonly space;
   private readonly store;
-  private readonly logger;
+  private logger;
   constructor(space: DbSpace, logger?: TGenericLogger);
   /**
    * Resolves types into categorized readables and computes the schema hash.

package/dist/sync.d.mts

@@ -235,6 +235,11 @@ interface TSyncOptions {
   force?: boolean;
   /** Safe mode — skip destructive operations (column drops, table drops). Default: false. */
   safe?: boolean;
+  /**
+   * Logger for sync progress and failures (index/FK DDL errors are logged,
+   * not thrown). Default: NoopLogger — pass `console` to surface them.
+   */
+  logger?: TGenericLogger;
 }
 interface TSyncResult {
   status: "up-to-date" | "synced" | "synced-by-peer";
@@ -244,7 +249,7 @@ interface TSyncResult {
 declare class SchemaSync {
   private readonly space;
   private readonly store;
-  private readonly logger;
+  private logger;
   constructor(space: DbSpace, logger?: TGenericLogger);
   /**
    * Resolves types into categorized readables and computes the schema hash.

package/dist/sync.mjs

@@ -1,4 +1,4 @@
-import { S as NoopLogger } from "./db-view-CHprAlvK.mjs";
+import { C as NoopLogger } from "./db-view-BllUecjK.mjs";
 //#region src/schema/schema-hash.ts
 /** Extracts sorted field snapshots from a readable's field descriptors. */
 function extractFieldSnapshots(fields, typeMapper) {
@@ -929,6 +929,7 @@ var SchemaSync = class {
 	* Runs schema synchronization with distributed locking.
 	*/
 	async run(types, opts) {
+		this.logger = opts?.logger ?? this.logger;
 		const podId = opts?.podId ?? crypto.randomUUID();
 		const lockTtlMs = opts?.lockTtlMs ?? 3e4;
 		const waitTimeoutMs = opts?.waitTimeoutMs ?? 6e4;

package/dist/{validation-utils-CR4H3_nc.cjs → validation-utils-B7SXPkm7.cjs}

@@ -116,6 +116,7 @@ function refActionAnnotation(name) {
 \`\`\`
 `,
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		argument: {
 			name: "action",
 			type: "string",

package/dist/{validation-utils-D4R08oed.mjs → validation-utils-MWOP1Ts4.mjs}

@@ -116,6 +116,7 @@ function refActionAnnotation(name) {
 \`\`\`
 `,
 		nodeType: ["prop"],
+		passedWhenReferred: false,
 		argument: {
 			name: "action",
 			type: "string",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db",
-  "version": "0.1.110",
+  "version": "0.1.111",
   "description": "Database adapter utilities for atscript.",
   "keywords": [
     "atscript",
@@ -71,14 +71,14 @@
     "access": "public"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.78",
-    "@atscript/typescript": "^0.1.78",
+    "@atscript/core": "^0.1.79",
+    "@atscript/typescript": "^0.1.79",
     "@uniqu/core": "^0.1.6",
-    "unplugin-atscript": "^0.1.78"
+    "unplugin-atscript": "^0.1.79"
   },
   "peerDependencies": {
-    "@atscript/core": "^0.1.78",
-    "@atscript/typescript": "^0.1.78",
+    "@atscript/core": "^0.1.79",
+    "@atscript/typescript": "^0.1.79",
     "@uniqu/core": "^0.1.6"
   },
   "scripts": {