@atscript/db 0.1.164 → 0.1.165

package/dist/plugin.cjs

@@ -33,10 +33,10 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-const require_aggregate_fns = require("./aggregate-fns-DupYzFD7.cjs");
+const require_aggregate_fns = require("./aggregate-fns-CNtrSxGH.cjs");
 const require_search_fields = require("./search-fields-B49-RCWd.cjs");
 require("./consts-BzRfCcH2.cjs");
-const require_view_validation = require("./view-validation-BiDLCYMw.cjs");
+const require_view_validation = require("./view-validation-C0UVLx_H.cjs");
 let _atscript_core = require("@atscript/core");
 let node_path = require("node:path");
 node_path = __toESM(node_path, 1);
@@ -1083,6 +1083,12 @@ const dbIndexAnnotations = { index: {
 		description: (0, _atscript_core.annotationExample)("Full-text search index. Fields sharing the same index name form a composite full-text index. A string member is part of the engine's text index. An integer member (`number.int` and its sizes, `@expect.int`, `@db.default.increment`) is never part of the physical text index: when the whole search term is a whole number (`2946`, `-12`; no leading zeros), rows whose member equals it exactly also match (OR'd with the text match). An integer member must be index-backed — the primary key (first `@meta.id`) or the first field of a `@db.index.plain` / `@db.index.unique`. Floats, decimals and timestamps are refused.", "@db.index.fulltext \"ft_content\"", "title: string", "", "@db.index.fulltext \"ft_content\", 5", "bio: string", "", "@db.index.fulltext \"ft_content\"", "@db.index.unique", "refNo: number.int"),
 		validate(token, args, doc) {
 			const field = token.parentNode;
+			const indexName = args[0]?.text;
+			if (indexName?.startsWith("atscript__")) return [{
+				message: `@db.index.fulltext name "${indexName}" is reserved — names starting with "atscript__" are internal index keys`,
+				severity: 1,
+				range: args[0].range
+			}];
 			const sealed = require_view_validation.sealedSearchProblem(token, doc, "@db.index.fulltext");
 			if (sealed) return [sealed];
 			const verdict = require_view_validation.searchFieldVerdict(field, doc);
@@ -1156,8 +1162,8 @@ function checkCompositeFkCoverage(token, alias, refTypeName, targetStruct, targe
 	for (const [, sibling] of hostStruct.props) {
 		if (sibling.countAnnotations("db.rel.FK") === 0) continue;
 		if (require_view_validation.getAnnotationAlias(sibling, "db.rel.FK") !== alias) continue;
-		const siblingDef = sibling.getDefinition();
-		if (siblingDef && (0, _atscript_core.isRef)(siblingDef) && siblingDef.id === refTypeName) {
+		const siblingDef = require_view_validation.fkChainRef(sibling.getDefinition());
+		if (siblingDef && siblingDef.id === refTypeName) {
 			if (siblingDef.chain.length === 1) covered.add(siblingDef.chain[0].text);
 		}
 	}
@@ -1183,16 +1189,15 @@ const dbRelAnnotations = { rel: {
 				severity: 1,
 				range: token.range
 			});
-			const definition = field.getDefinition();
-			if (!definition || !(0, _atscript_core.isRef)(definition) || !definition.hasChain) {
+			const ref = require_view_validation.fkChainRef(field.getDefinition());
+			if (!ref) {
 				errors.push({
-					message: `@db.rel.FK requires a chain reference type (e.g. User.id), got scalar type`,
+					message: `@db.rel.FK requires a chain reference type (e.g. User.id or User.id | null), got scalar type`,
 					severity: 1,
 					range: token.range
 				});
 				return errors;
 			}
-			const ref = definition;
 			const refTypeName = ref.id;
 			const chainFields = ref.chain.map((c) => c.text);
 			const targetUnwound = doc.unwindType(refTypeName);
@@ -1236,10 +1241,8 @@ const dbRelAnnotations = { rel: {
 					let sameTargetCount = 0;
 					for (const [, prop] of struct.props) {
 						if (prop.countAnnotations("db.rel.FK") === 0) continue;
-						const def = prop.getDefinition();
-						if (!def || !(0, _atscript_core.isRef)(def)) continue;
-						const r = def;
-						if (!r.hasChain) continue;
+						const r = require_view_validation.fkChainRef(prop.getDefinition());
+						if (!r) continue;
 						if (r.id === refTypeName) {
 							if (!require_view_validation.getAnnotationAlias(prop, "db.rel.FK")) sameTargetCount++;
 						}

package/dist/plugin.mjs

@@ -1,7 +1,7 @@
-import { i as NULL_WHEN_EMPTY_AGGREGATE_FNS, t as AGG_ANNOTATIONS } from "./aggregate-fns-DsS9UQVB.mjs";
+import { i as NULL_WHEN_EMPTY_AGGREGATE_FNS, t as AGG_ANNOTATIONS } from "./aggregate-fns-CmtSNIHm.mjs";
 import { c as DERIVED_INCOMPATIBLE, l as JSON_LEAF_TYPES, o as numericTypeProblem, s as DB_ENTITY_ANNOTATIONS, t as ENCRYPTED_INCOMPATIBLE } from "./search-fields-BPNsxrCk.mjs";
 import "./consts-C_-5_pFq.mjs";
-import { A as getParentTypeName, B as validateSiblingStringField, C as viewJoins, D as getDbTableOwner, E as getAnnotationAlias, F as refActionAnnotation, I as searchFieldVerdict, L as validateExclusiveWith, M as isNullableUnion, O as getNavTargetTypeName, P as primitiveBaseType, R as validateFieldBaseType, S as validateRefArgument, T as effectiveAnnotationNames, _ as hasAnyViewAnnotation, c as refuseCiphertext, d as viewFieldSeals, f as viewProps, g as forEachFieldRef, h as findViewCycle, i as encryptedTypeSearchProblem, j as integerMemberIndexProblem, k as getParentStruct, l as sealedSearchProblem, m as findFKFieldsPointingTo, o as isNavProp, p as earlierJoinTargets, s as jsonChainInfo, u as validateViewInterface, v as isAliasDecl, w as viewScopeTypes, x as validateQueryScope, y as isDbSourceDecl, z as validateIncompatible } from "./view-validation-BcgDq7M9.mjs";
+import { A as getParentStruct, B as validateFieldBaseType, C as validateRefArgument, D as getAnnotationAlias, E as effectiveAnnotationNames, H as validateSiblingStringField, I as primitiveBaseType, L as refActionAnnotation, M as integerMemberIndexProblem, O as getDbTableOwner, P as isNullableUnion, R as searchFieldVerdict, S as validateQueryScope, T as viewScopeTypes, V as validateIncompatible, _ as forEachFieldRef, b as isDbSourceDecl, c as refuseCiphertext, d as viewFieldSeals, f as viewProps, g as fkChainRef, h as findViewCycle, i as encryptedTypeSearchProblem, j as getParentTypeName, k as getNavTargetTypeName, l as sealedSearchProblem, m as findFKFieldsPointingTo, o as isNavProp, p as earlierJoinTargets, s as jsonChainInfo, u as validateViewInterface, v as hasAnyViewAnnotation, w as viewJoins, y as isAliasDecl, z as validateExclusiveWith } from "./view-validation-KW77xIKn.mjs";
 import { AnnotationSpec, DEFAULT_FORMAT, annotationExample, getFieldsForType, isArray, isInterface, isPrimitive, isProp, isQueryComparison, isQueryLogical, isRef, isStructure } from "@atscript/core";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -1047,6 +1047,12 @@ const dbIndexAnnotations = { index: {
 		description: annotationExample("Full-text search index. Fields sharing the same index name form a composite full-text index. A string member is part of the engine's text index. An integer member (`number.int` and its sizes, `@expect.int`, `@db.default.increment`) is never part of the physical text index: when the whole search term is a whole number (`2946`, `-12`; no leading zeros), rows whose member equals it exactly also match (OR'd with the text match). An integer member must be index-backed — the primary key (first `@meta.id`) or the first field of a `@db.index.plain` / `@db.index.unique`. Floats, decimals and timestamps are refused.", "@db.index.fulltext \"ft_content\"", "title: string", "", "@db.index.fulltext \"ft_content\", 5", "bio: string", "", "@db.index.fulltext \"ft_content\"", "@db.index.unique", "refNo: number.int"),
 		validate(token, args, doc) {
 			const field = token.parentNode;
+			const indexName = args[0]?.text;
+			if (indexName?.startsWith("atscript__")) return [{
+				message: `@db.index.fulltext name "${indexName}" is reserved — names starting with "atscript__" are internal index keys`,
+				severity: 1,
+				range: args[0].range
+			}];
 			const sealed = sealedSearchProblem(token, doc, "@db.index.fulltext");
 			if (sealed) return [sealed];
 			const verdict = searchFieldVerdict(field, doc);
@@ -1120,8 +1126,8 @@ function checkCompositeFkCoverage(token, alias, refTypeName, targetStruct, targe
 	for (const [, sibling] of hostStruct.props) {
 		if (sibling.countAnnotations("db.rel.FK") === 0) continue;
 		if (getAnnotationAlias(sibling, "db.rel.FK") !== alias) continue;
-		const siblingDef = sibling.getDefinition();
-		if (siblingDef && isRef(siblingDef) && siblingDef.id === refTypeName) {
+		const siblingDef = fkChainRef(sibling.getDefinition());
+		if (siblingDef && siblingDef.id === refTypeName) {
 			if (siblingDef.chain.length === 1) covered.add(siblingDef.chain[0].text);
 		}
 	}
@@ -1147,16 +1153,15 @@ const dbRelAnnotations = { rel: {
 				severity: 1,
 				range: token.range
 			});
-			const definition = field.getDefinition();
-			if (!definition || !isRef(definition) || !definition.hasChain) {
+			const ref = fkChainRef(field.getDefinition());
+			if (!ref) {
 				errors.push({
-					message: `@db.rel.FK requires a chain reference type (e.g. User.id), got scalar type`,
+					message: `@db.rel.FK requires a chain reference type (e.g. User.id or User.id | null), got scalar type`,
 					severity: 1,
 					range: token.range
 				});
 				return errors;
 			}
-			const ref = definition;
 			const refTypeName = ref.id;
 			const chainFields = ref.chain.map((c) => c.text);
 			const targetUnwound = doc.unwindType(refTypeName);
@@ -1200,10 +1205,8 @@ const dbRelAnnotations = { rel: {
 					let sameTargetCount = 0;
 					for (const [, prop] of struct.props) {
 						if (prop.countAnnotations("db.rel.FK") === 0) continue;
-						const def = prop.getDefinition();
-						if (!def || !isRef(def)) continue;
-						const r = def;
-						if (!r.hasChain) continue;
+						const r = fkChainRef(prop.getDefinition());
+						if (!r) continue;
 						if (r.id === refTypeName) {
 							if (!getAnnotationAlias(prop, "db.rel.FK")) sameTargetCount++;
 						}

package/dist/rel.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_nested_writer = require("./nested-writer-yCy6wGuN.cjs");
-const require_relation_loader = require("./relation-loader-DujL_Mh9.cjs");
+const require_nested_writer = require("./nested-writer-DOvdbYG-.cjs");
+const require_relation_loader = require("./relation-loader-BrkakVF_.cjs");
 exports.applyPatchNestedTo = require_nested_writer.applyPatchNestedTo;
 exports.batchInsertNestedFrom = require_nested_writer.batchInsertNestedFrom;
 exports.batchInsertNestedTo = require_nested_writer.batchInsertNestedTo;

package/dist/rel.d.cts

@@ -1,6 +1,6 @@
-import { Jt as TTableResolver, K as TDbForeignKey, an as TableMetadata, cr as TGenericLogger, ct as TDbRelation, en as TWriteTableResolver, fn as BaseDbAdapter, h as AtscriptDbWritable, m as AtscriptDbTableLike } from "./buckets-B8UOod-v.cjs";
+import { K as TDbForeignKey, Yt as TTableResolver, ct as TDbRelation, fr as TGenericLogger, h as AtscriptDbWritable, hn as BaseDbAdapter, m as AtscriptDbTableLike, nn as TWriteTableResolver, sn as TableMetadata } from "./buckets-BDxKfCNo.cjs";
 import { t as DbValidationContext } from "./db-validator-plugin-wRqMYNBI.cjs";
-import { n as findRemoteFK, r as resolveRelationTargetTable, t as findFKForRelation } from "./relation-helpers-DloMywNs.cjs";
+import { n as findRemoteFK, r as resolveRelationTargetTable, t as findFKForRelation } from "./relation-helpers-C4UNWYQu.cjs";
 import { FilterExpr, WithRelation } from "@uniqu/core";
 import { Validator } from "@atscript/typescript/utils";
 

package/dist/rel.d.mts

@@ -1,6 +1,6 @@
-import { Jt as TTableResolver, K as TDbForeignKey, an as TableMetadata, cr as TGenericLogger, ct as TDbRelation, en as TWriteTableResolver, fn as BaseDbAdapter, h as AtscriptDbWritable, m as AtscriptDbTableLike } from "./buckets-CHyspjYP.mjs";
+import { K as TDbForeignKey, Yt as TTableResolver, ct as TDbRelation, fr as TGenericLogger, h as AtscriptDbWritable, hn as BaseDbAdapter, m as AtscriptDbTableLike, nn as TWriteTableResolver, sn as TableMetadata } from "./buckets-CHUgky8T.mjs";
 import { t as DbValidationContext } from "./db-validator-plugin-wRqMYNBI.mjs";
-import { n as findRemoteFK, r as resolveRelationTargetTable, t as findFKForRelation } from "./relation-helpers-zwt19E7r.mjs";
+import { n as findRemoteFK, r as resolveRelationTargetTable, t as findFKForRelation } from "./relation-helpers-hdbuqwjV.mjs";
 import { Validator } from "@atscript/typescript/utils";
 import { FilterExpr, WithRelation } from "@uniqu/core";
 

package/dist/rel.mjs

@@ -1,3 +1,3 @@
-import { t as loadRelationsImpl } from "./relation-loader-Qv3LrQ42.mjs";
-import { B as resolveRelationTargetTable, R as findFKForRelation, a as batchPatchNestedFrom, c as batchReplaceNestedFrom, d as checkDepthOverflow, f as planNestedFromVia, h as validateBatch, i as batchInsertNestedVia, l as batchReplaceNestedTo, m as preValidateNestedFrom, n as batchInsertNestedFrom, o as batchPatchNestedTo, p as planPatchNestedTo, r as batchInsertNestedTo, s as batchPatchNestedVia, t as applyPatchNestedTo, u as batchReplaceNestedVia, z as findRemoteFK } from "./nested-writer-ClUX0DB0.mjs";
+import { t as loadRelationsImpl } from "./relation-loader-BOEVhcBe.mjs";
+import { B as findFKForRelation, H as resolveRelationTargetTable, V as findRemoteFK, a as batchPatchNestedFrom, c as batchReplaceNestedFrom, d as checkDepthOverflow, f as planNestedFromVia, h as validateBatch, i as batchInsertNestedVia, l as batchReplaceNestedTo, m as preValidateNestedFrom, n as batchInsertNestedFrom, o as batchPatchNestedTo, p as planPatchNestedTo, r as batchInsertNestedTo, s as batchPatchNestedVia, t as applyPatchNestedTo, u as batchReplaceNestedVia } from "./nested-writer-BraWjS8a.mjs";
 export { applyPatchNestedTo, batchInsertNestedFrom, batchInsertNestedTo, batchInsertNestedVia, batchPatchNestedFrom, batchPatchNestedTo, batchPatchNestedVia, batchReplaceNestedFrom, batchReplaceNestedTo, batchReplaceNestedVia, checkDepthOverflow, findFKForRelation, findRemoteFK, loadRelationsImpl, planNestedFromVia, planPatchNestedTo, preValidateNestedFrom, resolveRelationTargetTable, validateBatch };

package/dist/{relation-helpers-DloMywNs.d.cts → relation-helpers-C4UNWYQu.d.cts}

@@ -1,4 +1,4 @@
-import { K as TDbForeignKey, ct as TDbRelation } from "./buckets-B8UOod-v.cjs";
+import { K as TDbForeignKey, ct as TDbRelation } from "./buckets-BDxKfCNo.cjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/rel/relation-helpers.d.ts

package/dist/{relation-helpers-zwt19E7r.d.mts → relation-helpers-hdbuqwjV.d.mts}

@@ -1,4 +1,4 @@
-import { K as TDbForeignKey, ct as TDbRelation } from "./buckets-CHyspjYP.mjs";
+import { K as TDbForeignKey, ct as TDbRelation } from "./buckets-CHUgky8T.mjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/rel/relation-helpers.d.ts

package/dist/{relation-loader-Qv3LrQ42.mjs → relation-loader-BOEVhcBe.mjs}

@@ -1,4 +1,4 @@
-import { B as resolveRelationTargetTable, E as andFilters, I as compositeKey, P as relationStaticFilter, R as findFKForRelation, V as slicePerGroup, z as findRemoteFK } from "./nested-writer-ClUX0DB0.mjs";
+import { B as findFKForRelation, H as resolveRelationTargetTable, I as relationStaticFilter, O as andFilters, R as compositeKey, U as slicePerGroup, V as findRemoteFK } from "./nested-writer-BraWjS8a.mjs";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {

package/dist/{relation-loader-DujL_Mh9.cjs → relation-loader-BrkakVF_.cjs}

@@ -1,4 +1,4 @@
-const require_nested_writer = require("./nested-writer-yCy6wGuN.cjs");
+const require_nested_writer = require("./nested-writer-DOvdbYG-.cjs");
 //#region src/rel/relation-loader.ts
 var relation_loader_exports = /* @__PURE__ */ require("./plugin.cjs").__exportAll({
 	ensureSelectIncludesFields: () => ensureSelectIncludesFields,

package/dist/shared.cjs

@@ -2,7 +2,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_search_fields = require("./search-fields-B49-RCWd.cjs");
 const require_object = require("./object-GjsuPNqo.cjs");
 const require_aggregate_rules = require("./aggregate-rules-D_bsCpUI.cjs");
-const require_view_validation = require("./view-validation-BiDLCYMw.cjs");
+const require_view_validation = require("./view-validation-C0UVLx_H.cjs");
 exports.ENCRYPTED_INCOMPATIBLE = require_search_fields.ENCRYPTED_INCOMPATIBLE;
 exports.ENCRYPTED_SEARCH_FEATURES = require_search_fields.ENCRYPTED_SEARCH_FEATURES;
 exports.NAV_ANNOTATIONS = require_view_validation.NAV_ANNOTATIONS;
@@ -15,6 +15,7 @@ exports.encryptedTypeSearchProblem = require_view_validation.encryptedTypeSearch
 exports.findFKFieldsPointingTo = require_view_validation.findFKFieldsPointingTo;
 exports.findStoredField = require_view_validation.findStoredField;
 exports.findViewCycle = require_view_validation.findViewCycle;
+exports.fkChainRef = require_view_validation.fkChainRef;
 exports.forEachFieldRef = require_view_validation.forEachFieldRef;
 exports.getAnnotationAlias = require_view_validation.getAnnotationAlias;
 exports.getDbTableOwner = require_view_validation.getDbTableOwner;
@@ -26,6 +27,7 @@ exports.integerMemberIndexProblem = require_view_validation.integerMemberIndexPr
 exports.isAliasDecl = require_view_validation.isAliasDecl;
 exports.isDbSourceDecl = require_view_validation.isDbSourceDecl;
 exports.isNavProp = require_view_validation.isNavProp;
+exports.isNullMember = require_view_validation.isNullMember;
 exports.isNullableUnion = require_view_validation.isNullableUnion;
 exports.isStrictAggregateStruct = require_aggregate_rules.isStrictAggregateStruct;
 exports.isViewField = require_view_validation.isViewField;

package/dist/shared.d.cts

@@ -1,6 +1,6 @@
 import { s as stableJson } from "./object-Czia_qD4.cjs";
 import { n as ENCRYPTED_SEARCH_FEATURES, t as ENCRYPTED_INCOMPATIBLE } from "./search-fields-CHqqcC3W.cjs";
-import { AnnotationSpec, AtscriptDoc, SemanticInterfaceNode, SemanticNode, SemanticPropNode, SemanticQueryExprNode, SemanticQueryFieldRefNode, SemanticStructureNode, TAnnotationSpecConfig, TAnnotationTokens, TMessages, TQueryScope, Token } from "@atscript/core";
+import { AnnotationSpec, AtscriptDoc, SemanticInterfaceNode, SemanticNode, SemanticPropNode, SemanticQueryExprNode, SemanticQueryFieldRefNode, SemanticRefNode, SemanticStructureNode, TAnnotationSpecConfig, TAnnotationTokens, TMessages, TQueryScope, Token } from "@atscript/core";
 
 //#region src/shared/annotation-utils.d.ts
 /**
@@ -32,6 +32,11 @@ declare function validateIncompatible(token: Token, tag: string, pairs: Readonly
 declare function isViewField(field: SemanticNode): boolean;
 /** Primitive base type (`string`, `number`, `decimal`, …) of a resolved definition, if it is a primitive. */
 declare function primitiveBaseType(def: SemanticNode | undefined): string | undefined;
+/**
+ * `null` in a type expression: the `null` reference or the `null` primitive
+ * (whose `config.type` is `"null"`).
+ */
+declare function isNullMember(node: SemanticNode): boolean;
 /**
  * Whether a definition is a union with a `null` member — `T | null`, or a
  * ref to an alias of one (compile-time mirror of the runtime nullable union,
@@ -130,6 +135,12 @@ interface TFKFieldMatch {
     field: string;
   };
 }
+/**
+ * The chain reference (`User.id`) an `@db.rel.FK` field's type names, else
+ * `undefined`. `User.id | null` names it too (since 0.1.165) — the same
+ * optional foreign key as `field?: User.id`; any other union does not.
+ */
+declare function fkChainRef(def: SemanticNode | undefined): SemanticRefNode | undefined;
 /**
  * Find all `@db.rel.FK` fields on a type that reference `targetTypeName`.
  * Resolves `extends` to include inherited fields.
@@ -258,4 +269,4 @@ declare function encryptedTypeSearchProblem(token: Token, doc: AtscriptDoc): TMe
 /** Name of the nearest `@db.encrypted` prop enclosing `field` (inline nested objects), if any. */
 declare function encryptedAncestorName(field: SemanticNode): string | undefined;
 //#endregion
-export { ENCRYPTED_INCOMPATIBLE, ENCRYPTED_SEARCH_FEATURES, NAV_ANNOTATIONS, NOT_DIMENSION_REASON, TFKFieldMatch, TRefArgumentOptions, type TViewFieldSeals, earlierJoinTargets, effectiveAnnotationNames, encryptedAncestorName, encryptedSearchProblem, encryptedTypeSearchProblem, findFKFieldsPointingTo, findStoredField, findViewCycle, forEachFieldRef, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, integerMemberIndexProblem, isAliasDecl, isDbSourceDecl, isNavProp, isNullableUnion, isStrictAggregateStruct, isViewField, joinTargets, primitiveBaseType, refActionAnnotation, refuseCiphertext, searchFieldVerdict, stableJson, validateExclusiveWith, validateFieldBaseType, validateIncompatible, validateQueryScope, validateRefArgument, validateSiblingStringField, viewFieldSeals, viewJoins, viewScopeTypes };
+export { ENCRYPTED_INCOMPATIBLE, ENCRYPTED_SEARCH_FEATURES, NAV_ANNOTATIONS, NOT_DIMENSION_REASON, TFKFieldMatch, TRefArgumentOptions, type TViewFieldSeals, earlierJoinTargets, effectiveAnnotationNames, encryptedAncestorName, encryptedSearchProblem, encryptedTypeSearchProblem, findFKFieldsPointingTo, findStoredField, findViewCycle, fkChainRef, forEachFieldRef, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, integerMemberIndexProblem, isAliasDecl, isDbSourceDecl, isNavProp, isNullMember, isNullableUnion, isStrictAggregateStruct, isViewField, joinTargets, primitiveBaseType, refActionAnnotation, refuseCiphertext, searchFieldVerdict, stableJson, validateExclusiveWith, validateFieldBaseType, validateIncompatible, validateQueryScope, validateRefArgument, validateSiblingStringField, viewFieldSeals, viewJoins, viewScopeTypes };

package/dist/shared.d.mts

@@ -1,6 +1,6 @@
 import { s as stableJson } from "./object-Czia_qD4.mjs";
 import { n as ENCRYPTED_SEARCH_FEATURES, t as ENCRYPTED_INCOMPATIBLE } from "./search-fields-CHqqcC3W.mjs";
-import { AnnotationSpec, AtscriptDoc, SemanticInterfaceNode, SemanticNode, SemanticPropNode, SemanticQueryExprNode, SemanticQueryFieldRefNode, SemanticStructureNode, TAnnotationSpecConfig, TAnnotationTokens, TMessages, TQueryScope, Token } from "@atscript/core";
+import { AnnotationSpec, AtscriptDoc, SemanticInterfaceNode, SemanticNode, SemanticPropNode, SemanticQueryExprNode, SemanticQueryFieldRefNode, SemanticRefNode, SemanticStructureNode, TAnnotationSpecConfig, TAnnotationTokens, TMessages, TQueryScope, Token } from "@atscript/core";
 
 //#region src/shared/annotation-utils.d.ts
 /**
@@ -32,6 +32,11 @@ declare function validateIncompatible(token: Token, tag: string, pairs: Readonly
 declare function isViewField(field: SemanticNode): boolean;
 /** Primitive base type (`string`, `number`, `decimal`, …) of a resolved definition, if it is a primitive. */
 declare function primitiveBaseType(def: SemanticNode | undefined): string | undefined;
+/**
+ * `null` in a type expression: the `null` reference or the `null` primitive
+ * (whose `config.type` is `"null"`).
+ */
+declare function isNullMember(node: SemanticNode): boolean;
 /**
  * Whether a definition is a union with a `null` member — `T | null`, or a
  * ref to an alias of one (compile-time mirror of the runtime nullable union,
@@ -130,6 +135,12 @@ interface TFKFieldMatch {
     field: string;
   };
 }
+/**
+ * The chain reference (`User.id`) an `@db.rel.FK` field's type names, else
+ * `undefined`. `User.id | null` names it too (since 0.1.165) — the same
+ * optional foreign key as `field?: User.id`; any other union does not.
+ */
+declare function fkChainRef(def: SemanticNode | undefined): SemanticRefNode | undefined;
 /**
  * Find all `@db.rel.FK` fields on a type that reference `targetTypeName`.
  * Resolves `extends` to include inherited fields.
@@ -258,4 +269,4 @@ declare function encryptedTypeSearchProblem(token: Token, doc: AtscriptDoc): TMe
 /** Name of the nearest `@db.encrypted` prop enclosing `field` (inline nested objects), if any. */
 declare function encryptedAncestorName(field: SemanticNode): string | undefined;
 //#endregion
-export { ENCRYPTED_INCOMPATIBLE, ENCRYPTED_SEARCH_FEATURES, NAV_ANNOTATIONS, NOT_DIMENSION_REASON, TFKFieldMatch, TRefArgumentOptions, type TViewFieldSeals, earlierJoinTargets, effectiveAnnotationNames, encryptedAncestorName, encryptedSearchProblem, encryptedTypeSearchProblem, findFKFieldsPointingTo, findStoredField, findViewCycle, forEachFieldRef, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, integerMemberIndexProblem, isAliasDecl, isDbSourceDecl, isNavProp, isNullableUnion, isStrictAggregateStruct, isViewField, joinTargets, primitiveBaseType, refActionAnnotation, refuseCiphertext, searchFieldVerdict, stableJson, validateExclusiveWith, validateFieldBaseType, validateIncompatible, validateQueryScope, validateRefArgument, validateSiblingStringField, viewFieldSeals, viewJoins, viewScopeTypes };
+export { ENCRYPTED_INCOMPATIBLE, ENCRYPTED_SEARCH_FEATURES, NAV_ANNOTATIONS, NOT_DIMENSION_REASON, TFKFieldMatch, TRefArgumentOptions, type TViewFieldSeals, earlierJoinTargets, effectiveAnnotationNames, encryptedAncestorName, encryptedSearchProblem, encryptedTypeSearchProblem, findFKFieldsPointingTo, findStoredField, findViewCycle, fkChainRef, forEachFieldRef, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, integerMemberIndexProblem, isAliasDecl, isDbSourceDecl, isNavProp, isNullMember, isNullableUnion, isStrictAggregateStruct, isViewField, joinTargets, primitiveBaseType, refActionAnnotation, refuseCiphertext, searchFieldVerdict, stableJson, validateExclusiveWith, validateFieldBaseType, validateIncompatible, validateQueryScope, validateRefArgument, validateSiblingStringField, viewFieldSeals, viewJoins, viewScopeTypes };

package/dist/shared.mjs

@@ -1,5 +1,5 @@
 import { n as ENCRYPTED_SEARCH_FEATURES, t as ENCRYPTED_INCOMPATIBLE } from "./search-fields-BPNsxrCk.mjs";
 import { s as stableJson } from "./object-PQ1J8jri.mjs";
 import { n as isStrictAggregateStruct, t as NOT_DIMENSION_REASON } from "./aggregate-rules-jdPrxqWa.mjs";
-import { A as getParentTypeName, B as validateSiblingStringField, C as viewJoins, D as getDbTableOwner, E as getAnnotationAlias, F as refActionAnnotation, I as searchFieldVerdict, L as validateExclusiveWith, M as isNullableUnion, N as isViewField, O as getNavTargetTypeName, P as primitiveBaseType, R as validateFieldBaseType, S as validateRefArgument, T as effectiveAnnotationNames, _ as hasAnyViewAnnotation, a as findStoredField, b as joinTargets, c as refuseCiphertext, d as viewFieldSeals, g as forEachFieldRef, h as findViewCycle, i as encryptedTypeSearchProblem, j as integerMemberIndexProblem, k as getParentStruct, m as findFKFieldsPointingTo, n as encryptedAncestorName, o as isNavProp, p as earlierJoinTargets, r as encryptedSearchProblem, t as NAV_ANNOTATIONS, v as isAliasDecl, w as viewScopeTypes, x as validateQueryScope, y as isDbSourceDecl, z as validateIncompatible } from "./view-validation-BcgDq7M9.mjs";
-export { ENCRYPTED_INCOMPATIBLE, ENCRYPTED_SEARCH_FEATURES, NAV_ANNOTATIONS, NOT_DIMENSION_REASON, earlierJoinTargets, effectiveAnnotationNames, encryptedAncestorName, encryptedSearchProblem, encryptedTypeSearchProblem, findFKFieldsPointingTo, findStoredField, findViewCycle, forEachFieldRef, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, integerMemberIndexProblem, isAliasDecl, isDbSourceDecl, isNavProp, isNullableUnion, isStrictAggregateStruct, isViewField, joinTargets, primitiveBaseType, refActionAnnotation, refuseCiphertext, searchFieldVerdict, stableJson, validateExclusiveWith, validateFieldBaseType, validateIncompatible, validateQueryScope, validateRefArgument, validateSiblingStringField, viewFieldSeals, viewJoins, viewScopeTypes };
+import { A as getParentStruct, B as validateFieldBaseType, C as validateRefArgument, D as getAnnotationAlias, E as effectiveAnnotationNames, F as isViewField, H as validateSiblingStringField, I as primitiveBaseType, L as refActionAnnotation, M as integerMemberIndexProblem, N as isNullMember, O as getDbTableOwner, P as isNullableUnion, R as searchFieldVerdict, S as validateQueryScope, T as viewScopeTypes, V as validateIncompatible, _ as forEachFieldRef, a as findStoredField, b as isDbSourceDecl, c as refuseCiphertext, d as viewFieldSeals, g as fkChainRef, h as findViewCycle, i as encryptedTypeSearchProblem, j as getParentTypeName, k as getNavTargetTypeName, m as findFKFieldsPointingTo, n as encryptedAncestorName, o as isNavProp, p as earlierJoinTargets, r as encryptedSearchProblem, t as NAV_ANNOTATIONS, v as hasAnyViewAnnotation, w as viewJoins, x as joinTargets, y as isAliasDecl, z as validateExclusiveWith } from "./view-validation-KW77xIKn.mjs";
+export { ENCRYPTED_INCOMPATIBLE, ENCRYPTED_SEARCH_FEATURES, NAV_ANNOTATIONS, NOT_DIMENSION_REASON, earlierJoinTargets, effectiveAnnotationNames, encryptedAncestorName, encryptedSearchProblem, encryptedTypeSearchProblem, findFKFieldsPointingTo, findStoredField, findViewCycle, fkChainRef, forEachFieldRef, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, integerMemberIndexProblem, isAliasDecl, isDbSourceDecl, isNavProp, isNullMember, isNullableUnion, isStrictAggregateStruct, isViewField, joinTargets, primitiveBaseType, refActionAnnotation, refuseCiphertext, searchFieldVerdict, stableJson, validateExclusiveWith, validateFieldBaseType, validateIncompatible, validateQueryScope, validateRefArgument, validateSiblingStringField, viewFieldSeals, viewJoins, viewScopeTypes };

package/dist/sync.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_db_error = require("./db-error-DmF1_xrz.cjs");
-const require_column_diff = require("./column-diff-BIGX3sRH.cjs");
-const require_validator = require("./validator-DK9Ijpo7.cjs");
+const require_column_diff = require("./column-diff-DjeUj9kb.cjs");
+const require_db_error = require("./db-error-G3sgvL87.cjs");
+const require_validator = require("./validator-D7E7T0Oy.cjs");
 //#region src/schema/json-column-copy.ts
 const NONE = {
 	copies: [],
@@ -323,11 +323,28 @@ var SyncStore = class {
 	}
 	async ensureControlTable() {
 		if (!this.controlTable) {
-			const { AtscriptControl } = await Promise.resolve().then(() => require("./control-jIVU2hkf.cjs"));
+			const { AtscriptControl } = await Promise.resolve().then(() => require("./control-B5BJypqL.cjs"));
 			this.controlTable = this.space.getTable(AtscriptControl);
 		}
 		await this.controlTable.ensureTable();
 	}
+	/**
+	* Runs `fn` in a transaction of the control table's adapter family — the
+	* space's tables on the same driver join it (since 0.1.165, data steps).
+	*/
+	async inTransaction(fn) {
+		const { AtscriptControl } = await Promise.resolve().then(() => require("./control-B5BJypqL.cjs"));
+		return this.space.getAdapter(AtscriptControl).withTransaction(fn);
+	}
+	/** Which of `ids` have a control row — one query (since 0.1.165, data steps). */
+	async presentControlIds(ids) {
+		if (ids.length === 0) return /* @__PURE__ */ new Set();
+		const rows = await this.controlTable.findMany({
+			filter: { _id: { $in: [...ids] } },
+			controls: { $select: ["_id"] }
+		});
+		return new Set(rows.map((r) => r._id));
+	}
 	async readControlValue(_id) {
 		return (await this.controlTable.findOne({
 			filter: { _id: { $eq: _id } },
@@ -495,7 +512,7 @@ function isExpired(lock, now) {
 	return expiresAt > 0 && expiresAt < now;
 }
 async function readStoredSnapshot(space, tableName, _asView) {
-	const { AtscriptControl } = await Promise.resolve().then(() => require("./control-jIVU2hkf.cjs"));
+	const { AtscriptControl } = await Promise.resolve().then(() => require("./control-B5BJypqL.cjs"));
 	const table = space.getTable(AtscriptControl);
 	await table.ensureTable();
 	const value = (await table.findOne({
@@ -1571,6 +1588,33 @@ function removedBlockers(t, removedTables, removedTableSet, dropEdges) {
 	} else for (const r of removedTables) if (r.snapshot && "foreignKeys" in r.snapshot && r.snapshot.foreignKeys.some((fk) => fk.targetTable === t.dbName)) direct.push(r.name);
 	return reachable(direct, dropEdges);
 }
+/** The `__atscript_control` key a data step is recorded under. */
+function dataStepKey(id) {
+	return `data_step:${id}`;
+}
+/** The steps as given, after checking their ids are non-empty and unique. */
+function checkDataSteps(steps) {
+	if (!steps?.length) return [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const step of steps) {
+		if (typeof step.id !== "string" || step.id === "") throw new Error("syncSchema: every data step needs a non-empty id");
+		if (seen.has(step.id)) throw new Error(`syncSchema: duplicate data step id "${step.id}"`);
+		seen.add(step.id);
+	}
+	return steps;
+}
+/** `result` with its `dataSteps` report — unchanged when no steps were passed. */
+function withSteps(result, steps, ran) {
+	if (steps.length === 0) return result;
+	const done = new Set(ran);
+	return {
+		...result,
+		dataSteps: {
+			ran: [...ran],
+			pending: steps.map((s) => s.id).filter((id) => !done.has(id))
+		}
+	};
+}
 var SchemaSync = class {
 	space;
 	store;
@@ -1588,7 +1632,7 @@ var SchemaSync = class {
 		const tables = [];
 		const views = [];
 		const externalViews = [];
-		for (const type of types) {
+		for (const type of new Set(types)) {
 			if (require_column_diff.aliasTargetOf(type)) continue;
 			const readable = this.space.get(type);
 			if (readable.isView) {
@@ -1716,7 +1760,8 @@ var SchemaSync = class {
 	/**
 	* Acquires the sync lock, waiting for a peer that holds it. Resolves
 	* `"acquired"`, or `"synced-by-peer"` when a non-forced run finds, after a
-	* wait, that the peer stored this schema's hash. A forced run never
+	* wait, that the peer stored this schema's hash (and `peerDone` agrees —
+	* no data step left pending). A forced run never
 	* short-circuits — it waits its turn and runs. Losing the race for a freed
 	* lock to another waiter just waits again, within the same `waitTimeoutMs`.
 	*/
@@ -1724,7 +1769,7 @@ var SchemaSync = class {
 		const deadline = Date.now() + opts.waitTimeoutMs;
 		while (!await this.store.tryAcquireLock(podId, opts.lockTtlMs)) {
 			if (!await this.store.waitForLock(deadline - Date.now(), opts.pollIntervalMs)) throw new Error(`Schema sync lock wait timed out after ${opts.waitTimeoutMs}ms`);
-			if (!opts.force && await this.store.readHash() === hash) return "synced-by-peer";
+			if (!opts.force && await this.store.readHash() === hash && (!opts.peerDone || await opts.peerDone())) return "synced-by-peer";
 		}
 		return "acquired";
 	}
@@ -1744,6 +1789,30 @@ var SchemaSync = class {
 			this.logger.warn("[schema-sync] Failed to release the sync lock — peers wait until it expires:", error instanceof Error ? error.message : error);
 		}
 	}
+	/** Ids of the steps not recorded yet, in order. */
+	async pendingDataSteps(steps) {
+		const done = await this.store.presentControlIds(steps.map((step) => dataStepKey(step.id)));
+		return steps.filter((step) => !done.has(dataStepKey(step.id))).map((step) => step.id);
+	}
+	/**
+	* Runs the pending steps in order, each with its record in one transaction.
+	* A throwing step propagates (rolled back, not recorded). Returns the ids run.
+	*/
+	async runDataSteps(steps, getAbortReason) {
+		const ran = [];
+		const pending = new Set(await this.pendingDataSteps(steps));
+		for (const step of steps) {
+			if (!pending.has(step.id)) continue;
+			this.assertLockHeld(getAbortReason);
+			await this.store.inTransaction(async () => {
+				await step.run(this.space);
+				await this.store.writeControlValue(dataStepKey(step.id), JSON.stringify({ ranAt: Date.now() }));
+			});
+			this.logger.info?.(`[schema-sync] data step "${step.id}" applied`);
+			ran.push(step.id);
+		}
+		return ran;
+	}
 	/**
 	* Runs schema synchronization with distributed locking, in three phases:
 	*
@@ -1768,21 +1837,25 @@ var SchemaSync = class {
 		const force = opts?.force ?? false;
 		const safe = opts?.safe ?? false;
 		const onError = opts?.onError ?? "warn";
+		const steps = checkDataSteps(opts?.dataSteps);
 		const resolved = await this.resolveAndHash(types);
 		const { hash } = resolved;
 		await this.store.ensureControlTable();
 		if (!force) {
-			if (await this.store.readHash() === hash) return {
-				status: "up-to-date",
-				schemaHash: hash,
-				entries: []
-			};
+			if (await this.store.readHash() === hash) {
+				if ((await this.pendingDataSteps(steps)).length === 0) return withSteps({
+					status: "up-to-date",
+					schemaHash: hash,
+					entries: []
+				}, steps, []);
+			}
 		}
 		if (await this.acquireLock(podId, hash, {
 			lockTtlMs,
 			waitTimeoutMs,
 			pollIntervalMs,
-			force
+			force,
+			peerDone: async () => (await this.pendingDataSteps(steps)).length === 0
 		}) === "synced-by-peer") return {
 			status: "synced-by-peer",
 			schemaHash: hash,
@@ -1791,11 +1864,14 @@ var SchemaSync = class {
 		const heartbeat = this.startHeartbeat(podId, lockTtlMs);
 		try {
 			if (!force) {
-				if (await this.store.readHash() === hash) return {
-					status: "synced-by-peer",
-					schemaHash: hash,
-					entries: []
-				};
+				if (await this.store.readHash() === hash) {
+					const ran = await this.runDataSteps(steps, heartbeat.getAbortReason);
+					return withSteps({
+						status: ran.length > 0 ? "synced" : "synced-by-peer",
+						schemaHash: hash,
+						entries: []
+					}, steps, ran);
+				}
 			}
 			const d = await this.discover(resolved, safe);
 			this.assertLockHeld(heartbeat.getAbortReason);
@@ -1808,11 +1884,11 @@ var SchemaSync = class {
 					entries: this.buildPlanEntries(d, safe, refusals)
 				};
 				this.reportOutcome(result, onError);
-				return result;
+				return withSteps(result, steps, []);
 			}
 			const result = await this.execute(d, safe, heartbeat.getAbortReason);
 			this.reportOutcome(result, onError);
-			return result;
+			return withSteps(result, steps, result.entries.some((e) => e.status === "error") ? [] : await this.runDataSteps(steps, heartbeat.getAbortReason));
 		} finally {
 			await heartbeat.stop();
 			await this.releaseLock(podId);
@@ -2437,6 +2513,7 @@ var SchemaSync = class {
 	* as `error` entries (`refused: true`) exactly as `run()` would report them.
 	*/
 	async plan(types, opts) {
+		const steps = checkDataSteps(opts?.dataSteps);
 		const force = opts?.force ?? false;
 		const safe = opts?.safe ?? false;
 		const resolved = await this.resolveAndHash(types);
@@ -2446,18 +2523,23 @@ var SchemaSync = class {
 		const refusals = this.preflight(d, safe);
 		await this.planLiveWork(d, safe);
 		const entries = this.buildPlanEntries(d, safe, refusals);
+		const pending = steps.length > 0 ? await this.pendingDataSteps(steps) : void 0;
+		const withPending = (plan) => pending ? {
+			...plan,
+			pendingDataSteps: pending
+		} : plan;
 		if (!force) {
-			if (await this.store.readHash() === hash) return {
+			if (await this.store.readHash() === hash && !pending?.length) return withPending({
 				status: "up-to-date",
 				schemaHash: hash,
 				entries
-			};
+			});
 		}
-		return {
+		return withPending({
 			status: "changes-needed",
 			schemaHash: hash,
 			entries
-		};
+		});
 	}
 	/** Fallback typeMapper for snapshot-based Path B: compares designType directly, skips unions. */
 	resolveTypeMapper(adapter) {