@atscript/db 0.1.161 → 0.1.163

package/dist/validator-DX97RzC2.d.mts

@@ -0,0 +1,108 @@
+import { TAtscriptAnnotatedType, TAtscriptTypeArray, TAtscriptTypeObject, TValidatorPlugin, Validator } from "@atscript/typescript/utils";
+
+//#region src/patch/patch-types.d.ts
+interface TArrayPatch<A extends readonly unknown[]> {
+  $replace?: A;
+  $insert?: A;
+  $upsert?: A;
+  $update?: Array<Partial<TArrayElement<A>>>;
+  $remove?: Array<Partial<TArrayElement<A>>>;
+}
+type TArrayElement<ArrayType extends readonly unknown[]> = ArrayType extends ReadonlyArray<infer ElementType> ? ElementType : never;
+/**
+ * Maps each property of T into a patch payload:
+ * - Array properties become `TArrayPatch<T[K]>`
+ * - Non-array properties become `Partial<T[K]>`
+ */
+type TDbPatch<T> = { [K in keyof T]?: T[K] extends Array<infer _> ? TArrayPatch<T[K]> : Partial<T[K]> };
+/**
+ * Extracts `@expect.array.key` properties from an array-of-objects type.
+ * These keys uniquely identify an element inside the array and are used
+ * for `$update`, `$remove`, and `$upsert` operations.
+ *
+ * @param def - Atscript array type definition.
+ * @returns Set of property names marked as keys; empty set if none.
+ */
+declare function getKeyProps(def: TAtscriptAnnotatedType<TAtscriptTypeArray>): Set<string>;
+//#endregion
+//#region src/shared/server-stamped.d.ts
+/**
+ * The annotations whose field the server writes on every update — the write
+ * sets `@db.onUpdate.now` to the current time and increments
+ * `@db.onUpdate.inc` — so a client value is overwritten (now) or dropped
+ * (inc). Dependency-free: UI and plugin code can import it from
+ * `@atscript/db/validator` without pulling the compiler into a bundle.
+ * @since 0.1.163
+ */
+declare const SERVER_STAMPED_ON_UPDATE_KEYS: ReadonlySet<string>;
+/**
+ * Whether a field's metadata marks it as stamped by the server on every
+ * update (`@db.onUpdate.now` or `@db.onUpdate.inc`) — e.g. to render it
+ * read-only in an edit form.
+ * @since 0.1.163
+ */
+declare function isServerStampedOnUpdate(metadata: {
+  has(key: string): boolean;
+}): boolean;
+//#endregion
+//#region src/validator.d.ts
+/** Write operation mode for validator configuration. */
+type ValidatorMode = "insert" | "patch" | "replace";
+/** Singleton db validator plugin — stateless, safe to share across all validators. */
+declare const dbPlugin: TValidatorPlugin;
+/**
+ * Builds a validator for a given write mode.
+ *
+ * Shared between server-side (`AtscriptDbTable`) and client-side (`ClientValidator`).
+ * Both use the same plugin, same `replace`, same `partial` logic.
+ *
+ * @param type - The annotated type to validate against.
+ * @param mode - The write operation mode.
+ * @param extraPlugins - Additional adapter-specific plugins (prepended before the db plugin).
+ * @param opts - `unknownProps` overrides the validator's unknown-property policy
+ *   (used by db-client's `lenientWrites`, where the served type may be a
+ *   projection of the full server-side type).
+ */
+declare function buildDbValidator(type: TAtscriptAnnotatedType, mode: ValidatorMode, extraPlugins?: TValidatorPlugin[], opts?: {
+  unknownProps?: "strip" | "ignore" | "error";
+}): Validator<any>;
+/**
+ * Path-aware `partial` callback for patch/update validation — the single
+ * implementation shared by the server's `bulkUpdate` validator and the
+ * client's patch preflight:
+ *
+ * - the root object is partial (a patch names only the fields it touches)
+ * - nav-relation subtrees are partial (nested data is validated by its own table)
+ * - `@db.patch.strategy "merge"` blocks are partial (the decomposer merges
+ *   per leaf, so absent keys survive server-side by design)
+ *
+ * Every other nested object stays strict: non-merge blocks are `$set` as a
+ * whole (replace semantics), so their required fields really are required.
+ */
+declare function buildPatchPartial(navPaths: ReadonlySet<string>): (def: TAtscriptAnnotatedType<TAtscriptTypeObject>, path: string) => boolean;
+/** Returns true if the annotated type is a navigation relation (TO/FROM/VIA). */
+declare function isNavRelation(type: TAtscriptAnnotatedType): boolean;
+/**
+ * Forces nav fields non-optional so the plugin handles null/undefined checks.
+ * The Validator caches replace results internally, so this allocates at most once per type node.
+ */
+declare function forceNavNonOptional(type: TAtscriptAnnotatedType): TAtscriptAnnotatedType;
+/** Result of {@link buildValidationContext}. */
+interface ValidationContext {
+  /** Flat map of dotted field paths → annotated types (same shape the server builds). */
+  flatMap: Map<string, TAtscriptAnnotatedType>;
+  /** Set of field paths that are navigation relations (TO/FROM/VIA). */
+  navFields: ReadonlySet<string>;
+}
+/**
+ * Builds a lightweight validation context from a deserialized Atscript type.
+ *
+ * This is the client-side equivalent of the server's `TableMetadata.build()`,
+ * without any adapter-specific processing (physical columns, index resolution, etc.).
+ *
+ * @param type - A deserialized annotated type (from `deserializeAnnotatedType(meta.type)`).
+ * @returns `flatMap` and `navFields` suitable for passing to `createDbValidatorPlugin` via `DbValidationContext`.
+ */
+declare function buildValidationContext(type: TAtscriptAnnotatedType<TAtscriptTypeObject>): ValidationContext;
+//#endregion
+export { buildValidationContext as a, isNavRelation as c, TArrayPatch as d, TDbPatch as f, buildPatchPartial as i, SERVER_STAMPED_ON_UPDATE_KEYS as l, ValidatorMode as n, dbPlugin as o, getKeyProps as p, buildDbValidator as r, forceNavNonOptional as s, ValidationContext as t, isServerStampedOnUpdate as u };

package/dist/{validator-B3fPJjS1.mjs → validator-DuDWsIdQ.mjs}

@@ -1,4 +1,4 @@
-import { i as DepthLimitExceededError } from "./db-error-eSsQX7rt.mjs";
+import { i as DepthLimitExceededError } from "./db-error-hraC12B9.mjs";
 import { getDbFieldOp } from "./ops.mjs";
 import { createAnnotatedTypeNode, flattenAnnotatedType } from "@atscript/typescript/utils";
 //#region src/shared/union-shape.ts
@@ -261,8 +261,9 @@ function createDbValidatorPlugin() {
 			const baseMeta = columnUnionBase(def)?.metadata;
 			const defaulted = !(belowAmbiguous(dbCtx, ctx.path) || ctx.root !== void 0 && pathBelowAmbiguous(ctx.root, ctx.path));
 			const has = (key) => defaulted && (meta.has(key) || baseMeta?.has(key) === true);
-			const serverManaged = has("db.default") || has("db.default.increment") || has("db.default.uuid") || has("db.default.now") || dbCtx.mode === "replace" && has("db.onUpdate.now") || meta.has("db.column.version") || meta.has("db.column.derived");
+			const serverManaged = has("db.default") || has("db.default.increment") || has("db.default.uuid") || has("db.default.now") || dbCtx.mode === "replace" && has("db.onUpdate.now") || meta.has("db.column.version") || meta.has("db.onUpdate.inc") || meta.has("db.column.derived");
 			const hasFK = meta.has("db.rel.FK");
+			if (dbCtx.keyless && meta.has("meta.id") && !ctx.path.includes(".")) return true;
 			if (serverManaged || hasFK) {
 				if (dbCtx.mode === "replace" && meta.has("meta.id") && !ctx.path.includes(".")) return;
 				return true;

package/dist/validator.cjs

@@ -1,7 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_db_error = require("./db-error-JcfJqqpk.cjs");
-const require_validator = require("./validator-B4YDLUkj.cjs");
-const require_object = require("./object-Djg28csK.cjs");
+const require_db_error = require("./db-error-DmF1_xrz.cjs");
+const require_validator = require("./validator-DK9Ijpo7.cjs");
+const require_server_stamped = require("./server-stamped-B6XbUQ4p.cjs");
+const require_object = require("./object-GjsuPNqo.cjs");
 const require_ops = require("./ops.cjs");
 exports.$cas = require_ops.$cas;
 exports.$dec = require_ops.$dec;
@@ -13,6 +14,7 @@ exports.$replace = require_ops.$replace;
 exports.$update = require_ops.$update;
 exports.$upsert = require_ops.$upsert;
 exports.DbError = require_db_error.DbError;
+exports.SERVER_STAMPED_ON_UPDATE_KEYS = require_server_stamped.SERVER_STAMPED_ON_UPDATE_KEYS;
 exports.buildDbValidator = require_validator.buildDbValidator;
 exports.buildPatchPartial = require_validator.buildPatchPartial;
 exports.buildValidationContext = require_validator.buildValidationContext;
@@ -24,5 +26,6 @@ exports.isDbFieldOp = require_ops.isDbFieldOp;
 exports.isEmptyObject = require_object.isEmptyObject;
 exports.isNavRelation = require_validator.isNavRelation;
 exports.isPlainObject = require_object.isPlainObject;
+exports.isServerStampedOnUpdate = require_server_stamped.isServerStampedOnUpdate;
 exports.reconcileCas = require_ops.reconcileCas;
 exports.separateCas = require_ops.separateCas;

package/dist/validator.d.cts

@@ -1,5 +1,6 @@
+import { r as DbError } from "./db-error-B_DRL1E9.cjs";
 import { a as $mul, c as $update, d as TDbFieldOp, g as separateCas, h as reconcileCas, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-AqhV7s9o.cjs";
-import { a as isPlainObject, i as isEmptyObject } from "./object-CtPYTIvy.cjs";
-import { a as buildValidationContext, c as isNavRelation, d as getKeyProps, i as buildPatchPartial, l as TArrayPatch, m as DbError, n as ValidatorMode, o as dbPlugin, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as TDbPatch } from "./validator-B3xlbrWf.cjs";
-import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.cjs";
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, DbError, type DbValidationContext, type TArrayPatch, type TDbCas, type TDbFieldOp, type TDbPatch, ValidationContext, ValidatorMode, buildDbValidator, buildPatchPartial, buildValidationContext, createDbValidatorPlugin, dbPlugin, forceNavNonOptional, getKeyProps, isDbFieldOp, isEmptyObject, isNavRelation, isPlainObject, reconcileCas, separateCas };
+import { a as isPlainObject, i as isEmptyObject } from "./object-Czia_qD4.cjs";
+import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-wRqMYNBI.cjs";
+import { a as buildValidationContext, c as isNavRelation, d as TArrayPatch, f as TDbPatch, i as buildPatchPartial, l as SERVER_STAMPED_ON_UPDATE_KEYS, n as ValidatorMode, o as dbPlugin, p as getKeyProps, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as isServerStampedOnUpdate } from "./validator-DX97RzC2.cjs";
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, DbError, type DbValidationContext, SERVER_STAMPED_ON_UPDATE_KEYS, type TArrayPatch, type TDbCas, type TDbFieldOp, type TDbPatch, ValidationContext, ValidatorMode, buildDbValidator, buildPatchPartial, buildValidationContext, createDbValidatorPlugin, dbPlugin, forceNavNonOptional, getKeyProps, isDbFieldOp, isEmptyObject, isNavRelation, isPlainObject, isServerStampedOnUpdate, reconcileCas, separateCas };

package/dist/validator.d.mts

@@ -1,5 +1,6 @@
+import { r as DbError } from "./db-error-B_DRL1E9.mjs";
 import { a as $mul, c as $update, d as TDbFieldOp, g as separateCas, h as reconcileCas, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-AqhV7s9o.mjs";
-import { a as isPlainObject, i as isEmptyObject } from "./object-CtPYTIvy.mjs";
-import { a as buildValidationContext, c as isNavRelation, d as getKeyProps, i as buildPatchPartial, l as TArrayPatch, m as DbError, n as ValidatorMode, o as dbPlugin, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as TDbPatch } from "./validator-B3xlbrWf.mjs";
-import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.mjs";
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, DbError, type DbValidationContext, type TArrayPatch, type TDbCas, type TDbFieldOp, type TDbPatch, ValidationContext, ValidatorMode, buildDbValidator, buildPatchPartial, buildValidationContext, createDbValidatorPlugin, dbPlugin, forceNavNonOptional, getKeyProps, isDbFieldOp, isEmptyObject, isNavRelation, isPlainObject, reconcileCas, separateCas };
+import { a as isPlainObject, i as isEmptyObject } from "./object-Czia_qD4.mjs";
+import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-wRqMYNBI.mjs";
+import { a as buildValidationContext, c as isNavRelation, d as TArrayPatch, f as TDbPatch, i as buildPatchPartial, l as SERVER_STAMPED_ON_UPDATE_KEYS, n as ValidatorMode, o as dbPlugin, p as getKeyProps, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as isServerStampedOnUpdate } from "./validator-DX97RzC2.mjs";
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, DbError, type DbValidationContext, SERVER_STAMPED_ON_UPDATE_KEYS, type TArrayPatch, type TDbCas, type TDbFieldOp, type TDbPatch, ValidationContext, ValidatorMode, buildDbValidator, buildPatchPartial, buildValidationContext, createDbValidatorPlugin, dbPlugin, forceNavNonOptional, getKeyProps, isDbFieldOp, isEmptyObject, isNavRelation, isPlainObject, isServerStampedOnUpdate, reconcileCas, separateCas };

package/dist/validator.mjs

@@ -1,5 +1,6 @@
-import { r as DbError } from "./db-error-eSsQX7rt.mjs";
-import { a as forceNavNonOptional, c as getKeyProps, i as dbPlugin, n as buildPatchPartial, o as isNavRelation, r as buildValidationContext, s as createDbValidatorPlugin, t as buildDbValidator } from "./validator-B3fPJjS1.mjs";
-import { a as isPlainObject, i as isEmptyObject } from "./object-TkiJQ-Dp.mjs";
+import { r as DbError } from "./db-error-hraC12B9.mjs";
+import { a as forceNavNonOptional, c as getKeyProps, i as dbPlugin, n as buildPatchPartial, o as isNavRelation, r as buildValidationContext, s as createDbValidatorPlugin, t as buildDbValidator } from "./validator-DuDWsIdQ.mjs";
+import { n as isServerStampedOnUpdate, t as SERVER_STAMPED_ON_UPDATE_KEYS } from "./server-stamped-BoP56K9M.mjs";
+import { a as isPlainObject, i as isEmptyObject } from "./object-PQ1J8jri.mjs";
 import { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, isDbFieldOp, reconcileCas, separateCas } from "./ops.mjs";
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, DbError, buildDbValidator, buildPatchPartial, buildValidationContext, createDbValidatorPlugin, dbPlugin, forceNavNonOptional, getKeyProps, isDbFieldOp, isEmptyObject, isNavRelation, isPlainObject, reconcileCas, separateCas };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, DbError, SERVER_STAMPED_ON_UPDATE_KEYS, buildDbValidator, buildPatchPartial, buildValidationContext, createDbValidatorPlugin, dbPlugin, forceNavNonOptional, getKeyProps, isDbFieldOp, isEmptyObject, isNavRelation, isPlainObject, isServerStampedOnUpdate, reconcileCas, separateCas };

package/dist/{validation-utils-BGjqc2jU.mjs → view-validation-BcgDq7M9.mjs}

@@ -1,16 +1,59 @@
-import { i as DB_ENTITY_ANNOTATIONS, t as searchKindOf } from "./search-fields-CE8cmj9X.mjs";
-import { AnnotationSpec, isArray, isInterface, isPrimitive, isQueryComparison, isQueryLogical, isRef, isStructure } from "@atscript/core";
+import { i as NULL_WHEN_EMPTY_AGGREGATE_FNS, o as SUPPORTED_AGGREGATE_FNS, t as AGG_ANNOTATIONS } from "./aggregate-fns-DsS9UQVB.mjs";
+import { i as searchKindOf, l as JSON_LEAF_TYPES, n as ENCRYPTED_SEARCH_FEATURES, r as SEARCH_PROBLEM, s as DB_ENTITY_ANNOTATIONS } from "./search-fields-BPNsxrCk.mjs";
+import { AnnotationSpec, annotationExample, isArray, isInterface, isPrimitive, isProp, isQueryComparison, isQueryLogical, isRef, isStructure } from "@atscript/core";
 //#region src/shared/annotation-utils.ts
-/** Asserts the field carrying this annotation does not also carry any of `others`. */
-function validateExclusiveWith(token, selfName, others) {
+/**
+* Names of a field's effective annotations: its own plus the ones it inherits
+* through its type ref (`price: Order.price`), with the `passedWhenReferred:
+* false` ones dropped — the set codegen writes into the field's runtime
+* metadata (`AtscriptDoc.evalAnnotationsForNode`). Compile checks that mirror
+* a runtime metadata check read this, not the own-only `countAnnotations`.
+* @since 0.1.162
+*/
+function effectiveAnnotationNames(field, doc) {
+	const names = new Set(field.annotations?.map((a) => a.name));
+	for (const a of doc?.evalAnnotationsForNode(field) ?? []) names.add(a.name);
+	return names;
+}
+/**
+* Asserts the field carrying this annotation does not also carry any of
+* `others` — its own or inherited through its type ref (since 0.1.162).
+*/
+function validateExclusiveWith(token, selfName, others, doc) {
 	const errors = [];
 	const field = token.parentNode;
-	for (const { key, displayName } of others) if (field.countAnnotations(key) > 0) errors.push({
-		message: `${selfName} cannot coexist with ${displayName ?? `@${key}`} on the same field — pick one form, not both`,
+	const effective = effectiveAnnotationNames(field, doc);
+	for (const { key, displayName } of others) {
+		if (!effective.has(key)) continue;
+		const inherited = field.countAnnotations(key) === 0;
+		errors.push({
+			message: inherited ? `${selfName} cannot coexist with ${displayName ?? `@${key}`}, which this field inherits from its type reference — pick one form, not both` : `${selfName} cannot coexist with ${displayName ?? `@${key}`} on the same field — pick one form, not both`,
+			severity: 1,
+			range: token.range
+		});
+	}
+	return errors;
+}
+/**
+* Reports each of `pairs` (`[annotation, why]`) the field carrying `token`
+* also carries — its own or inherited through its type ref (the field's
+* effective annotations, what the runtime mirror reads off the metadata):
+* `${tag} cannot coexist with @${annotation} — ${why}`.
+* @since 0.1.162
+*/
+function validateIncompatible(token, tag, pairs, doc) {
+	const effective = effectiveAnnotationNames(token.parentNode, doc);
+	return pairs.filter(([name]) => effective.has(name)).map(([name, why]) => ({
+		message: `${tag} cannot coexist with @${name} — ${why}`,
 		severity: 1,
 		range: token.range
-	});
-	return errors;
+	}));
+}
+/** Whether a prop is a field of a view interface (`@db.view` / `@db.view.for`). */
+function isViewField(field) {
+	const struct = field.ownerNode;
+	const owner = struct && isStructure(struct) ? struct.ownerNode : void 0;
+	return !!owner && isInterface(owner) && (owner.countAnnotations("db.view") > 0 || owner.countAnnotations("db.view.for") > 0);
 }
 /** Primitive base type (`string`, `number`, `decimal`, …) of a resolved definition, if it is a primitive. */
 function primitiveBaseType(def) {
@@ -52,15 +95,19 @@ function searchFieldVerdict(field, doc) {
 	const leaf = doc.unwindType(def.id, def.chain)?.def;
 	const base = primitiveBaseType(leaf);
 	if (base === void 0) return { kind: "other" };
+	const effective = effectiveAnnotationNames(field, doc);
 	const kind = searchKindOf({
 		base,
 		tags: isPrimitive(leaf) ? leaf.tags : void 0,
-		expectInt: field.countAnnotations("expect.int") > 0,
-		increment: field.countAnnotations("db.default.increment") > 0,
-		now: field.countAnnotations("db.default.now") > 0,
-		precision: field.countAnnotations("db.column.precision") > 0
+		expectInt: effective.has("expect.int"),
+		increment: effective.has("db.default.increment"),
+		now: effective.has("db.default.now"),
+		precision: effective.has("db.column.precision")
 	});
-	if (typeof kind === "object") return kind;
+	if (typeof kind === "object") {
+		if (kind.problem === SEARCH_PROBLEM.float && isViewField(field)) return { problem: SEARCH_PROBLEM.floatViewField };
+		return kind;
+	}
 	return { kind: kind === "integer" ? "integer" : base === "string" ? "string" : "other" };
 }
 /**
@@ -173,12 +220,7 @@ function getAnnotationAlias(prop, annotationName) {
 */
 function refActionAnnotation(name) {
 	return new AnnotationSpec({
-		description: `Referential action when the target ${name === "onDelete" ? "row is deleted" : "key is updated"}. Only valid on @db.rel.FK fields.\n\n**Example:**
-\`\`\`atscript
-@db.rel.FK
-@db.rel.${name} "cascade"\nauthorId: User.id
-\`\`\`
-`,
+		description: annotationExample(`Referential action when the target ${name === "onDelete" ? "row is deleted" : "key is updated"}. Only valid on @db.rel.FK fields.`, "@db.rel.FK", `@db.rel.${name} "cascade"`, "authorId: User.id"),
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		argument: {
@@ -468,4 +510,306 @@ function forEachFieldRef(expr, fn) {
 	}
 }
 //#endregion
-export { validateExclusiveWith as C, searchFieldVerdict as S, validateSiblingStringField as T, getParentTypeName as _, hasAnyViewAnnotation as a, primitiveBaseType as b, joinTargets as c, viewJoins as d, viewScopeTypes as f, getParentStruct as g, getNavTargetTypeName as h, forEachFieldRef as i, validateQueryScope as l, getDbTableOwner as m, findFKFieldsPointingTo as n, isAliasDecl as o, getAnnotationAlias as p, findViewCycle as r, isDbSourceDecl as s, earlierJoinTargets as t, validateRefArgument as u, integerMemberIndexProblem as v, validateFieldBaseType as w, refActionAnnotation as x, isNullableUnion as y };
+//#region src/shared/view-validation.ts
+/** `@db.agg.*` annotations that are never NULL (the counts: 0 over no value). */
+const NULL_SAFE_AGG_ANNOTATIONS = SUPPORTED_AGGREGATE_FNS.filter((fn) => !NULL_WHEN_EMPTY_AGGREGATE_FNS.has(fn)).map((fn) => `db.agg.${fn}`);
+/**
+* Walks a chain ref step by step (`Order.payload`, `Order.payload.customer`, …)
+* and reports the JSON root, arrays, encryption, optionality and the leaf type.
+* A chain shorter than 2 is not a field path (`resolved: false`).
+* @since 0.1.141
+*/
+function jsonChainInfo(ref, doc) {
+	const typeName = ref.id ?? "";
+	const chain = ref.chain.map((t) => t.text);
+	const info = {
+		typeName,
+		chain,
+		resolved: false,
+		viaArray: false,
+		viaEncrypted: false,
+		optional: false
+	};
+	if (!typeName || chain.length < 2) return info;
+	for (let i = 1; i <= chain.length; i++) {
+		const step = doc.unwindType(typeName, chain.slice(0, i));
+		if (!step) return info;
+		const node = step.node;
+		const prop = node && isProp(node) ? node : void 0;
+		if (prop?.has("optional")) info.optional = true;
+		if (prop && prop.countAnnotations("db.encrypted") > 0) info.viaEncrypted = true;
+		const isJsonProp = prop !== void 0 && prop.countAnnotations("db.json") > 0;
+		const isArr = isArray(step.def);
+		if (isArr) info.viaArray = true;
+		if (info.jsonRoot === void 0 && (isJsonProp || isArr)) info.jsonRoot = i;
+		if (i === chain.length) info.leafType = primitiveBaseType(step.def);
+	}
+	info.resolved = true;
+	return info;
+}
+/**
+* The read seals a view field takes from the source field it reads, as the
+* compiler sees them (compile-time mirror of the runtime `sourceFieldSeals`,
+* which stamps them onto the view column — these annotations are
+* `passedWhenReferred: false`, so they are not in the field's own metadata):
+* - `writeOnly` — the source path or an ancestor object is `@db.writeOnly`;
+* - `encrypted` — the source path or an ancestor object is `@db.encrypted`.
+*
+* (A `@db.json` source is no seal: a view reads a primitive JSON column's
+* typed value, and an object one needs its own `@db.json`.)
+*
+* The source is the chain ref (`pin?: Account.pin`), or else the entry table's
+* same-named field (or an aggregate's field) of a `@db.view.for` view. A source
+* field that is itself a view field passes on its own seals. Computed fields
+* and fields of anything but a view report no seal.
+* @since 0.1.162
+*/
+function viewFieldSeals(field, doc, depth = 0) {
+	const seals = {
+		writeOnly: false,
+		encrypted: false
+	};
+	if (depth > 8 || !isViewField(field) || field.countAnnotations("db.compute") > 0) return seals;
+	let typeName;
+	let path;
+	const def = field.getDefinition();
+	if (def && isRef(def) && def.hasChain) {
+		typeName = def.id;
+		path = def.chain.map((t) => t.text);
+	} else {
+		const view = field.ownerNode.ownerNode;
+		typeName = getAnnotationAlias(view, "db.view.for");
+		const agg = field.annotations?.find((a) => AGG_ANNOTATIONS.includes(a.name));
+		const aggField = agg?.args[0]?.text;
+		if (agg && (!aggField || aggField === "*")) return seals;
+		path = (aggField ?? field.id ?? "").split(".");
+	}
+	if (!typeName || !path.length || !path[0]) return seals;
+	let step = doc.unwindType(typeName, [path[0]]);
+	for (let i = 1; step; i++) {
+		const node = step.node;
+		if (node && isProp(node)) {
+			if (node.countAnnotations("db.writeOnly") > 0) seals.writeOnly = true;
+			if (node.countAnnotations("db.encrypted") > 0) seals.encrypted = true;
+			const inner = viewFieldSeals(node, step.doc, depth + 1);
+			seals.writeOnly ||= inner.writeOnly;
+			seals.encrypted ||= inner.encrypted;
+		}
+		if (i === path.length) break;
+		step = propStep(step, path[i]);
+	}
+	return seals;
+}
+/** The step to the `name` prop of `step`'s object definition — its type ref resolved. */
+function propStep(step, name) {
+	const def = step.def;
+	const prop = isInterface(def) || isStructure(def) ? def.props.get(name) : void 0;
+	const propDef = prop?.getDefinition();
+	if (!prop || !propDef) return void 0;
+	if (!isRef(propDef)) return {
+		doc: step.doc,
+		node: prop,
+		def: propDef
+	};
+	const unwound = step.doc.unwindType(propDef.id, propDef.chain);
+	return unwound && {
+		doc: unwound.doc,
+		node: prop,
+		def: unwound.def
+	};
+}
+/** {@link viewFieldSeals} of `field`, computed on first use. */
+function lazySeals(field, doc) {
+	let seals;
+	return () => seals ??= viewFieldSeals(field, doc);
+}
+/**
+* A search annotation (`@db.column.searchable` / `@db.index.fulltext`) on a
+* view field whose source is `@db.writeOnly` — a search hit would reveal the
+* sealed value (the runtime refuses it at sync and on every query), or
+* `undefined`. The field's own `@db.writeOnly` is reported by that spec.
+* @since 0.1.162
+*/
+function viewSourceSealProblem(token, doc, annotation, seals = lazySeals(token.parentNode, doc)) {
+	const field = token.parentNode;
+	if (field.countAnnotations("db.writeOnly") > 0) return void 0;
+	if (!seals().writeOnly) return void 0;
+	return {
+		message: `${annotation} on "${field.id}", which reads a @db.writeOnly source field — search results would reveal the sealed value`,
+		severity: 1,
+		range: token.range
+	};
+}
+/**
+* A search / index feature (`@db.column.searchable`, `@db.index.fulltext`,
+* `@db.index.geo`, `@db.search.vector`, `@db.search.filter`) on a field that
+* would read ciphertext: a field inside an `@db.encrypted` object, or a view
+* field over an encrypted source — or `undefined`. The field's own
+* `@db.encrypted` is reported by that spec.
+* @since 0.1.162
+*/
+function encryptedSearchProblem(token, doc, annotation) {
+	return encryptedProblem(token, annotation, lazySeals(token.parentNode, doc));
+}
+function encryptedProblem(token, annotation, seals) {
+	const field = token.parentNode;
+	if (field.countAnnotations("db.encrypted") > 0) return void 0;
+	const where = encryptedAncestorName(field);
+	const why = where !== void 0 ? `it is inside the @db.encrypted field "${where}"` : seals().encrypted ? "it reads a @db.encrypted source field" : void 0;
+	if (!why) return void 0;
+	return {
+		message: `${annotation} on "${field.id}" — ${why}; search over ciphertext is impossible`,
+		severity: 1,
+		range: token.range
+	};
+}
+/**
+* {@link viewSourceSealProblem}, else {@link encryptedSearchProblem} — the
+* view field's source seals computed once.
+*/
+function sealedSearchProblem(token, doc, annotation) {
+	const seals = lazySeals(token.parentNode, doc);
+	return viewSourceSealProblem(token, doc, annotation, seals) ?? encryptedProblem(token, annotation, seals);
+}
+/**
+* An annotation's `validate` refusing it on a field that reads ciphertext
+* ({@link encryptedSearchProblem}) — for the search features of sibling
+* adapter plugins too.
+* @since 0.1.162
+*/
+function refuseCiphertext(annotation) {
+	return (token, _args, doc) => {
+		const problem = encryptedSearchProblem(token, doc, annotation);
+		return problem ? [problem] : [];
+	};
+}
+/**
+* Navigation relation annotations — a navigation field holds another table's
+* rows, never part of this table's stored value.
+* @since 0.1.162
+*/
+const NAV_ANNOTATIONS = [
+	"db.rel.to",
+	"db.rel.from",
+	"db.rel.via"
+];
+/** Whether a prop is a navigation field ({@link NAV_ANNOTATIONS}). */
+function isNavProp(prop) {
+	return NAV_ANNOTATIONS.some((key) => prop.countAnnotations(key) > 0);
+}
+/**
+* Walks the fields stored in `root` (an interface, a structure or a type ref)
+* depth-first — nested objects and type refs included, navigation fields and
+* arrays skipped — and returns the first non-`undefined` result of `visit`.
+* `path` is the field's dotted path below `prefix`; `viaRef` tells whether
+* a type ref was followed to reach it.
+* @since 0.1.162
+*/
+function findStoredField(root, doc, visit, prefix = "") {
+	const seen = /* @__PURE__ */ new Set();
+	const walk = (def, defDoc, viaRef, prefix) => {
+		if (!def || seen.has(def)) return void 0;
+		seen.add(def);
+		if (isRef(def)) {
+			const unwound = defDoc.unwindType(def.id, def.chain);
+			return unwound ? walk(unwound.def, unwound.doc, true, prefix) : void 0;
+		}
+		const props = isInterface(def) || isStructure(def) ? def.props : void 0;
+		if (!props) return void 0;
+		for (const [name, prop] of props) {
+			if (isNavProp(prop)) continue;
+			const path = prefix ? `${prefix}.${name}` : name;
+			const found = visit(prop, path, viaRef) ?? walk(prop.getDefinition(), defDoc, viaRef, path);
+			if (found !== void 0) return found;
+		}
+	};
+	return walk(root, doc, false, prefix);
+}
+/**
+* A search feature ({@link ENCRYPTED_SEARCH_FEATURES}) declared inside the
+* TYPE of the `@db.encrypted` field carrying `token`, reached through a type
+* ref (`@db.encrypted profile: Address`, where `Address` has
+* `@db.index.fulltext city`) — the shared type's own annotations cannot see
+* that this use encrypts them. Fields declared inline are reported by their
+* own annotation (see {@link encryptedSearchProblem}).
+* @since 0.1.162
+*/
+function encryptedTypeSearchProblem(token, doc) {
+	const field = token.parentNode;
+	const found = findStoredField(field.getDefinition(), doc, (prop, path, viaRef) => {
+		if (!viaRef) return void 0;
+		const feature = ENCRYPTED_SEARCH_FEATURES.find((key) => prop.countAnnotations(key) > 0);
+		return feature ? {
+			path,
+			feature
+		} : void 0;
+	}, field.id ?? "");
+	if (!found) return void 0;
+	return {
+		message: `@db.encrypted on "${field.id}" — its type declares @${found.feature} on "${found.path}"; search over ciphertext is impossible`,
+		severity: 1,
+		range: token.range
+	};
+}
+/** Name of the nearest `@db.encrypted` prop enclosing `field` (inline nested objects), if any. */
+function encryptedAncestorName(field) {
+	for (let node = field.ownerNode; node; node = node.ownerNode) if (isProp(node) && node.countAnnotations("db.encrypted") > 0) return node.id;
+}
+/** Props of a view interface (its own structure; views don't use `extends`). */
+function viewProps(owner) {
+	if (isInterface(owner)) return owner.props;
+	const def = owner.getDefinition();
+	return def && isStructure(def) ? def.props : void 0;
+}
+/**
+* VW8: a chain ref that passes through a `@db.json` or array node reads a
+* JSON leaf, which views can only extract as a string / number / boolean.
+* Intermediate nodes that `unwindType` can't reach are skipped (sync-time
+* resolution reports them).
+*/
+function validateJsonChain(fieldName, ref, doc, range) {
+	const info = jsonChainInfo(ref, doc);
+	if (!info.resolved || info.jsonRoot === void 0 || info.jsonRoot >= info.chain.length) return [];
+	if (info.leafType !== void 0 && JSON_LEAF_TYPES.has(info.leafType)) return [];
+	return [{
+		message: `Field "${fieldName}" reads "${info.typeName}.${info.chain.join(".")}" inside a JSON-stored field — it must end at a string, number or boolean leaf`,
+		severity: 1,
+		range
+	}];
+}
+/**
+* Whole-view checks, run once per `@db.view.for` interface:
+*
+* - VW7 — a field reading from a left-joined table must be optional (the
+*   join yields NULL for unmatched rows); `@db.agg.count` / `countDistinct`
+*   fields are exempt (they count 0, never NULL).
+* - VW8 — a chain ref through a `@db.json` or array node must end at a
+*   primitive string / number / boolean leaf.
+* @since 0.1.136
+*/
+function validateViewInterface(owner, doc) {
+	const errors = [];
+	const props = viewProps(owner);
+	if (!props) return errors;
+	const leftJoined = /* @__PURE__ */ new Set();
+	for (const join of viewJoins(owner)) {
+		const target = join.args[0]?.text;
+		if (target && join.args[2]?.text === "left") leftJoined.add(target);
+	}
+	for (const [fieldName, prop] of props) {
+		const def = prop.getDefinition();
+		if (!def || !isRef(def)) continue;
+		const ref = def;
+		const range = (prop.token("identifier") ?? ref.token("identifier"))?.range;
+		if (!range) continue;
+		if (ref.id && leftJoined.has(ref.id) && !prop.has("optional") && !NULL_SAFE_AGG_ANNOTATIONS.some((name) => prop.countAnnotations(name) > 0)) errors.push({
+			message: `Field "${fieldName}" reads from left-joined "${ref.id}" and must be optional (${fieldName}?: …)`,
+			severity: 1,
+			range
+		});
+		errors.push(...validateJsonChain(fieldName, ref, doc, range));
+	}
+	return errors;
+}
+//#endregion
+export { getParentTypeName as A, validateSiblingStringField as B, viewJoins as C, getDbTableOwner as D, getAnnotationAlias as E, refActionAnnotation as F, searchFieldVerdict as I, validateExclusiveWith as L, isNullableUnion as M, isViewField as N, getNavTargetTypeName as O, primitiveBaseType as P, validateFieldBaseType as R, validateRefArgument as S, effectiveAnnotationNames as T, hasAnyViewAnnotation as _, findStoredField as a, joinTargets as b, refuseCiphertext as c, viewFieldSeals as d, viewProps as f, forEachFieldRef as g, findViewCycle as h, encryptedTypeSearchProblem as i, integerMemberIndexProblem as j, getParentStruct as k, sealedSearchProblem as l, findFKFieldsPointingTo as m, encryptedAncestorName as n, isNavProp as o, earlierJoinTargets as p, encryptedSearchProblem as r, jsonChainInfo as s, NAV_ANNOTATIONS as t, validateViewInterface as u, isAliasDecl as v, viewScopeTypes as w, validateQueryScope as x, isDbSourceDecl as y, validateIncompatible as z };