@atscript/db-mongo 0.1.107 → 0.1.109

package/dist/index.cjs

@@ -3,6 +3,13 @@ const require_mongo_filter = require("./mongo-filter-z_hLPMyv.cjs");
 let _atscript_db = require("@atscript/db");
 let mongodb = require("mongodb");
 //#region src/lib/path-utils.ts
+function joinPath(prefix, segment) {
+	return prefix ? `${prefix}.${segment}` : segment;
+}
+function isArrayPath(flatMap, path) {
+	const type = flatMap.get(path);
+	return type !== void 0 && (0, _atscript_db.resolveDesignType)(type) === "array";
+}
 function hasAncestorIn(path, set) {
 	let dot = path.indexOf(".");
 	while (dot !== -1) {
@@ -157,7 +164,7 @@ var CollectionPatcher = class {
 	* @private
 	*/
 	flattenPayload(payload, prefix = "") {
-		const evalKey = (k) => prefix ? `${prefix}.${k}` : k;
+		const evalKey = (k) => joinPath(prefix, k);
 		for (const [_key, value] of Object.entries(payload)) {
 			const key = evalKey(_key);
 			const flatType = this.collection.flatMap.get(key);
@@ -770,27 +777,44 @@ function buildSearchStage(host, text, indexName, controls) {
 	const searchIndex = index;
 	const fuzzy = resolveSearchFuzzy(searchIndex, controls);
 	const strategy = searchIndex.strategy ?? "compound";
-	const autocompletePaths = autocompleteFieldPaths(searchIndex);
-	const textClause = () => ({ text: {
+	const paths = collectSearchPathsCached(searchIndex);
+	const fuzzyOpt = fuzzy ? { fuzzy } : {};
+	const textOp = (path) => ({ text: {
 		query: text,
-		path: { wildcard: "*" },
-		...fuzzy ? { fuzzy } : {}
+		path,
+		...fuzzyOpt
 	} });
-	const autocompleteClause = (path) => ({ autocomplete: {
+	const autocompleteOp = (path) => ({ autocomplete: {
 		query: text,
 		path,
-		...fuzzy ? { fuzzy } : {}
+		...fuzzyOpt
 	} });
-	let body;
-	if (strategy === "text" || autocompletePaths.length === 0) body = textClause();
-	else if (strategy === "autocomplete") {
-		const clauses = autocompletePaths.map(autocompleteClause);
-		body = clauses.length === 1 ? clauses[0] : { compound: {
-			should: clauses,
-			minimumShouldMatch: 1
+	const textClause = () => textOp({ wildcard: "*" });
+	const wrapEmbedded = (chain, operator) => {
+		let wrapped = operator;
+		for (let i = chain.length - 1; i >= 0; i--) wrapped = { embeddedDocument: {
+			path: chain[i],
+			operator: wrapped
 		} };
-	} else body = { compound: {
-		should: [textClause(), ...autocompletePaths.map(autocompleteClause)],
+		return wrapped;
+	};
+	const embeddedTextClause = (chain, leaves) => wrapEmbedded(chain, textOp(leaves.length === 1 ? leaves[0] : leaves));
+	const embeddedAutocompleteClause = (chain, leaf) => wrapEmbedded(chain, autocompleteOp(leaf));
+	const wantWord = strategy === "text" || strategy === "compound";
+	const wantAutocomplete = strategy === "autocomplete" || strategy === "compound";
+	const clauses = [];
+	if (wantWord) {
+		clauses.push(textClause());
+		for (const group of paths.arrayGroups) if (group.textLeaves.length > 0) clauses.push(embeddedTextClause(group.chain, group.textLeaves));
+	}
+	if (wantAutocomplete) {
+		for (const path of paths.autocompleteOutside) clauses.push(autocompleteOp(path));
+		for (const group of paths.arrayGroups) for (const leaf of group.autocompleteLeaves) clauses.push(embeddedAutocompleteClause(group.chain, leaf));
+	}
+	let body;
+	if (clauses.length <= 1) body = clauses[0] ?? textClause();
+	else body = { compound: {
+		should: clauses,
 		minimumShouldMatch: 1
 	} };
 	return {
@@ -811,13 +835,65 @@ function resolveSearchFuzzy(index, controls) {
 	const maxEdits = override === void 0 ? index.fuzzy?.maxEdits : Number(override);
 	return maxEdits === 1 || maxEdits === 2 ? { maxEdits } : void 0;
 }
-/** Field paths in this index that carry an `autocomplete` mapping. */
-function autocompleteFieldPaths(index) {
-	const fields = index.definition.mappings?.fields;
-	if (!fields) return [];
-	const paths = [];
-	for (const [path, mapping] of Object.entries(fields)) if ((Array.isArray(mapping) ? mapping : [mapping]).some((m) => m.type === "autocomplete")) paths.push(path);
-	return paths;
+/**
+* An index's mapping tree is immutable once schema sync builds it, and the index
+* object is cached for the adapter's lifetime — so the walk runs once per index,
+* not once per query (`buildSearchStage` is on the search hot path).
+*/
+const searchPathsCache = /* @__PURE__ */ new WeakMap();
+function collectSearchPathsCached(index) {
+	let cached = searchPathsCache.get(index);
+	if (!cached) {
+		cached = collectSearchPaths(index.definition.mappings?.fields);
+		searchPathsCache.set(index, cached);
+	}
+	return cached;
+}
+/**
+* Walks an index's nested mapping tree, classifying each searchable leaf by how
+* it must be queried: a plain dotted path (top-level / `document`-nested) vs.
+* scoped under an `embeddedDocuments` array root (queried via `embeddedDocument`).
+* Word-matching for non-array fields rides the wildcard `text` clause, so only
+* autocomplete leaves are tracked outside arrays.
+*/
+function collectSearchPaths(fields) {
+	const out = {
+		autocompleteOutside: [],
+		arrayGroups: []
+	};
+	const byChain = /* @__PURE__ */ new Map();
+	const walk = (map, prefix, chain) => {
+		if (!map) return;
+		for (const [key, mapping] of Object.entries(map)) {
+			const path = joinPath(prefix, key);
+			const list = Array.isArray(mapping) ? mapping : [mapping];
+			const embedded = list.find((m) => m.type === "embeddedDocuments");
+			const document = list.find((m) => m.type === "document");
+			if (embedded?.fields) walk(embedded.fields, path, [...chain, path]);
+			else if (document?.fields) walk(document.fields, path, chain);
+			else {
+				const isAutocomplete = list.some((m) => m.type === "autocomplete");
+				const isText = list.some((m) => m.type === "string");
+				if (chain.length > 0) {
+					const chainKey = chain.join(">");
+					let group = byChain.get(chainKey);
+					if (!group) {
+						group = {
+							chain,
+							textLeaves: [],
+							autocompleteLeaves: []
+						};
+						byChain.set(chainKey, group);
+						out.arrayGroups.push(group);
+					}
+					if (isText) group.textLeaves.push(path);
+					if (isAutocomplete) group.autocompleteLeaves.push(path);
+				} else if (isAutocomplete) out.autocompleteOutside.push(path);
+			}
+		}
+	};
+	walk(fields, "", []);
+	return out;
 }
 /** Builds a $vectorSearch aggregation stage from a pre-computed vector. */
 function buildVectorSearchStage(host, vector, indexName, limit) {
@@ -1176,11 +1252,8 @@ function arraySafePath(host, physicalPath, logicalPath) {
 	for (let i = 0; i < logicalSegments.length; i++) {
 		const isLeaf = i === logicalSegments.length - 1;
 		out.push(isLeaf ? physicalLeaf : logicalSegments[i]);
-		prefix = prefix ? `${prefix}.${logicalSegments[i]}` : logicalSegments[i];
-		if (!isLeaf) {
-			const type = host._table.flatMap.get(prefix);
-			if (type && (0, _atscript_db.resolveDesignType)(type) === "array") out.push("$[]");
-		}
+		prefix = joinPath(prefix, logicalSegments[i]);
+		if (!isLeaf && isArrayPath(host._table.flatMap, prefix)) out.push("$[]");
 	}
 	return out.join(".");
 }
@@ -1190,9 +1263,8 @@ function pathCrossesArray(host, logicalPath) {
 	if (segments.length < 2) return false;
 	let prefix = "";
 	for (let i = 0; i < segments.length - 1; i++) {
-		prefix = prefix ? `${prefix}.${segments[i]}` : segments[i];
-		const type = host._table.flatMap.get(prefix);
-		if (type && (0, _atscript_db.resolveDesignType)(type) === "array") return true;
+		prefix = joinPath(prefix, segments[i]);
+		if (isArrayPath(host._table.flatMap, prefix)) return true;
 	}
 	return false;
 }
@@ -1440,6 +1512,7 @@ function fieldMappingEqual(a, b) {
 	for (const [type, av] of am) {
 		const bv = bm.get(type);
 		if (!bv || av.analyzer !== bv.analyzer || av.tokenization !== bv.tokenization || av.minGrams !== bv.minGrams || av.maxGrams !== bv.maxGrams || av.foldDiacritics !== bv.foldDiacritics) return false;
+		if (!fieldsMatch(av.fields, bv.fields)) return false;
 	}
 	return true;
 }
@@ -1484,6 +1557,14 @@ var MongoAdapter = class MongoAdapter extends _atscript_db.BaseDbAdapter {
 	_vectorThresholds = /* @__PURE__ */ new Map();
 	/** Cached search index lookup. */
 	_searchIndexesMap;
+	/**
+	* Search-field mappings recorded during `onFieldScanned`, applied in
+	* `onAfterFlatten`. Deferred because resolving a nested field's container
+	* shape (`document` vs `embeddedDocuments`) needs `this._table.flatMap`, which
+	* is only safe to read once the metadata build is marked complete — i.e. in
+	* `onAfterFlatten`, not mid-scan (the `flatMap` getter would re-enter `build`).
+	*/
+	_pendingSearchFields = [];
 	/** Physical field names with @db.default.increment → optional start value. */
 	_incrementFields = /* @__PURE__ */ new Map();
 	/** Physical field names that have a non-binary collation (nocase/unicode). */
@@ -1708,10 +1789,14 @@ var MongoAdapter = class MongoAdapter extends _atscript_db.BaseDbAdapter {
 			const startValue = metadata.get("db.default.increment");
 			this._incrementFields.set(physicalName, typeof startValue === "number" ? startValue : void 0);
 		}
-		for (const index of metadata.get("db.mongo.search.text") || []) this._addFieldToSearchIndex("search_text", index.indexName, field, [index.analyzer ? {
-			type: "string",
-			analyzer: index.analyzer
-		} : { type: "string" }]);
+		for (const index of metadata.get("db.mongo.search.text") || []) this._pendingSearchFields.push({
+			indexName: index.indexName,
+			field,
+			mappings: [index.analyzer ? {
+				type: "string",
+				analyzer: index.analyzer
+			} : { type: "string" }]
+		});
 		for (const ac of metadata.get("db.mongo.search.autocomplete") || []) {
 			const autocomplete = {
 				type: "autocomplete",
@@ -1724,7 +1809,11 @@ var MongoAdapter = class MongoAdapter extends _atscript_db.BaseDbAdapter {
 				type: "string",
 				analyzer: ac.analyzer
 			} : { type: "string" };
-			this._addFieldToSearchIndex("search_text", ac.indexName, field, [autocomplete, companion]);
+			this._pendingSearchFields.push({
+				indexName: ac.indexName,
+				field,
+				mappings: [autocomplete, companion]
+			});
 		}
 		const vectorIndex = metadata.get("db.search.vector");
 		if (vectorIndex) {
@@ -1766,6 +1855,8 @@ var MongoAdapter = class MongoAdapter extends _atscript_db.BaseDbAdapter {
 		};
 	}
 	onAfterFlatten() {
+		for (const pending of this._pendingSearchFields) this._addFieldToSearchIndex("search_text", pending.indexName, pending.field, pending.mappings);
+		this._pendingSearchFields = [];
 		for (const [key, value] of this._vectorFilters.entries()) {
 			const index = this._mongoIndexes.get(key);
 			if (index && index.type === "vector") index.definition.fields?.push({
@@ -2219,10 +2310,45 @@ var MongoAdapter = class MongoAdapter extends _atscript_db.BaseDbAdapter {
 		const name = _name || "DEFAULT";
 		let index = this._mongoIndexes.get(mongoIndexKey(type, name));
 		if (!index && type === "search_text") index = this._setSearchIndex(type, name, { mappings: { fields: {} } });
-		if (index) {
-			const fields = index.definition.mappings.fields;
-			fields[fieldName] = mergeFieldMappings(fields[fieldName], mappings);
+		if (!index) return;
+		const rootFields = index.definition.mappings.fields;
+		const segments = fieldName.split(".");
+		const topKey = this._table.columnMap.get(segments[0]) ?? segments[0];
+		if (segments.length === 1) {
+			rootFields[topKey] = mergeFieldMappings(rootFields[topKey], mappings);
+			return;
+		}
+		let cursor = rootFields;
+		let prefix = "";
+		for (let i = 0; i < segments.length - 1; i++) {
+			const segment = segments[i];
+			prefix = joinPath(prefix, segment);
+			const nodeType = isArrayPath(this._table.flatMap, prefix) ? "embeddedDocuments" : "document";
+			cursor = this._descendSearchNode(cursor, i === 0 ? topKey : segment, nodeType, fieldName);
 		}
+		const leaf = segments[segments.length - 1];
+		cursor[leaf] = mergeFieldMappings(cursor[leaf], mappings);
+	}
+	/**
+	* Returns (creating if needed) the nested `fields` map of the container node
+	* at `segment`, reusing a same-typed sibling node so multiple searchable
+	* fields under one parent (e.g. `identity.name` + `identity.tagline`) merge
+	* instead of clobbering.
+	*/
+	_descendSearchNode(fields, segment, nodeType, fullPath) {
+		const existing = fields[segment];
+		if (existing && !Array.isArray(existing) && (existing.type === "document" || existing.type === "embeddedDocuments")) {
+			if (existing.type !== nodeType) this._log(`search index: conflicting container type for "${fullPath}" (${existing.type} vs ${nodeType}); keeping ${existing.type}`);
+			existing.fields ??= {};
+			return existing.fields;
+		}
+		if (existing) this._log(`search index: field "${segment}" used as both value and parent in "${fullPath}"`);
+		const node = {
+			type: nodeType,
+			fields: {}
+		};
+		fields[segment] = node;
+		return node.fields;
 	}
 };
 /**

package/dist/index.d.cts

@@ -191,6 +191,16 @@ type TVectorSimilarity = "cosine" | "euclidean" | "dotProduct";
  * `type: "autocomplete"` enables prefix/typeahead (edgeGram) or substring (nGram).
  * A field may carry several mappings at once (an array of these) — e.g. an
  * autocomplete field double-mapped as `string` so exact-word hits still rank.
+ *
+ * Container nodes carry `fields` instead of leaf attributes:
+ * - `type: "document"` — a single embedded object (`identity: Identity`). Atlas
+ *   does NOT accept a dotted mapping key, so each parent object on a nested path
+ *   must be its own `document` node. Nested fields are reachable by the dotted
+ *   query path and by a `{ wildcard: "*" }` `text` operator.
+ * - `type: "embeddedDocuments"` — an array of objects (`items: Item[]`). Atlas
+ *   cannot index array-of-object fields under a `document` node; they MUST use
+ *   `embeddedDocuments` and be queried via the `embeddedDocument` operator
+ *   (the wildcard `text` operator does not reach them).
  */
 interface TSearchFieldMapping {
   type: string;
@@ -199,6 +209,8 @@ interface TSearchFieldMapping {
   minGrams?: number;
   maxGrams?: number;
   foldDiacritics?: boolean;
+  /** Nested mappings for `document` / `embeddedDocuments` container nodes. */
+  fields?: Record<string, TSearchFieldMapping | TSearchFieldMapping[]>;
 }
 interface TMongoSearchIndexDefinition {
   mappings?: {
@@ -227,6 +239,18 @@ declare class MongoAdapter extends BaseDbAdapter {
   protected _vectorThresholds: Map<string, number>;
   /** Cached search index lookup. */
   protected _searchIndexesMap?: Map<string, TMongoIndex>;
+  /**
+   * Search-field mappings recorded during `onFieldScanned`, applied in
+   * `onAfterFlatten`. Deferred because resolving a nested field's container
+   * shape (`document` vs `embeddedDocuments`) needs `this._table.flatMap`, which
+   * is only safe to read once the metadata build is marked complete — i.e. in
+   * `onAfterFlatten`, not mid-scan (the `flatMap` getter would re-enter `build`).
+   */
+  protected _pendingSearchFields: Array<{
+    indexName: string | undefined;
+    field: string;
+    mappings: TSearchFieldMapping[];
+  }>;
   /** Physical field names with @db.default.increment → optional start value. */
   protected _incrementFields: Map<string, number | undefined>;
   /** Physical field names that have a non-binary collation (nocase/unicode). */
@@ -408,6 +432,13 @@ declare class MongoAdapter extends BaseDbAdapter {
    * instead of overwriting one another.
    */
   protected _addFieldToSearchIndex(type: TSearchIndex["type"], _name: string | undefined, fieldName: string, mappings: TSearchFieldMapping[]): void;
+  /**
+   * Returns (creating if needed) the nested `fields` map of the container node
+   * at `segment`, reusing a same-typed sibling node so multiple searchable
+   * fields under one parent (e.g. `identity.name` + `identity.tagline`) merge
+   * instead of clobbering.
+   */
+  private _descendSearchNode;
 }
 //#endregion
 //#region src/lib/mongo-filter.d.ts

package/dist/index.d.mts

@@ -191,6 +191,16 @@ type TVectorSimilarity = "cosine" | "euclidean" | "dotProduct";
  * `type: "autocomplete"` enables prefix/typeahead (edgeGram) or substring (nGram).
  * A field may carry several mappings at once (an array of these) — e.g. an
  * autocomplete field double-mapped as `string` so exact-word hits still rank.
+ *
+ * Container nodes carry `fields` instead of leaf attributes:
+ * - `type: "document"` — a single embedded object (`identity: Identity`). Atlas
+ *   does NOT accept a dotted mapping key, so each parent object on a nested path
+ *   must be its own `document` node. Nested fields are reachable by the dotted
+ *   query path and by a `{ wildcard: "*" }` `text` operator.
+ * - `type: "embeddedDocuments"` — an array of objects (`items: Item[]`). Atlas
+ *   cannot index array-of-object fields under a `document` node; they MUST use
+ *   `embeddedDocuments` and be queried via the `embeddedDocument` operator
+ *   (the wildcard `text` operator does not reach them).
  */
 interface TSearchFieldMapping {
   type: string;
@@ -199,6 +209,8 @@ interface TSearchFieldMapping {
   minGrams?: number;
   maxGrams?: number;
   foldDiacritics?: boolean;
+  /** Nested mappings for `document` / `embeddedDocuments` container nodes. */
+  fields?: Record<string, TSearchFieldMapping | TSearchFieldMapping[]>;
 }
 interface TMongoSearchIndexDefinition {
   mappings?: {
@@ -227,6 +239,18 @@ declare class MongoAdapter extends BaseDbAdapter {
   protected _vectorThresholds: Map<string, number>;
   /** Cached search index lookup. */
   protected _searchIndexesMap?: Map<string, TMongoIndex>;
+  /**
+   * Search-field mappings recorded during `onFieldScanned`, applied in
+   * `onAfterFlatten`. Deferred because resolving a nested field's container
+   * shape (`document` vs `embeddedDocuments`) needs `this._table.flatMap`, which
+   * is only safe to read once the metadata build is marked complete — i.e. in
+   * `onAfterFlatten`, not mid-scan (the `flatMap` getter would re-enter `build`).
+   */
+  protected _pendingSearchFields: Array<{
+    indexName: string | undefined;
+    field: string;
+    mappings: TSearchFieldMapping[];
+  }>;
   /** Physical field names with @db.default.increment → optional start value. */
   protected _incrementFields: Map<string, number | undefined>;
   /** Physical field names that have a non-binary collation (nocase/unicode). */
@@ -408,6 +432,13 @@ declare class MongoAdapter extends BaseDbAdapter {
    * instead of overwriting one another.
    */
   protected _addFieldToSearchIndex(type: TSearchIndex["type"], _name: string | undefined, fieldName: string, mappings: TSearchFieldMapping[]): void;
+  /**
+   * Returns (creating if needed) the nested `fields` map of the container node
+   * at `segment`, reusing a same-typed sibling node so multiple searchable
+   * fields under one parent (e.g. `identity.name` + `identity.tagline`) merge
+   * instead of clobbering.
+   */
+  private _descendSearchNode;
 }
 //#endregion
 //#region src/lib/mongo-filter.d.ts

package/dist/index.mjs

@@ -2,6 +2,13 @@ import { t as buildMongoFilter } from "./mongo-filter-DceAGI-S.mjs";
 import { AtscriptDbView, BaseDbAdapter, DbError, DbSpace, computeInsights, getDbFieldOp, getKeyProps, resolveDesignType } from "@atscript/db";
 import { MongoClient, MongoServerError, ObjectId } from "mongodb";
 //#region src/lib/path-utils.ts
+function joinPath(prefix, segment) {
+	return prefix ? `${prefix}.${segment}` : segment;
+}
+function isArrayPath(flatMap, path) {
+	const type = flatMap.get(path);
+	return type !== void 0 && resolveDesignType(type) === "array";
+}
 function hasAncestorIn(path, set) {
 	let dot = path.indexOf(".");
 	while (dot !== -1) {
@@ -156,7 +163,7 @@ var CollectionPatcher = class {
 	* @private
 	*/
 	flattenPayload(payload, prefix = "") {
-		const evalKey = (k) => prefix ? `${prefix}.${k}` : k;
+		const evalKey = (k) => joinPath(prefix, k);
 		for (const [_key, value] of Object.entries(payload)) {
 			const key = evalKey(_key);
 			const flatType = this.collection.flatMap.get(key);
@@ -769,27 +776,44 @@ function buildSearchStage(host, text, indexName, controls) {
 	const searchIndex = index;
 	const fuzzy = resolveSearchFuzzy(searchIndex, controls);
 	const strategy = searchIndex.strategy ?? "compound";
-	const autocompletePaths = autocompleteFieldPaths(searchIndex);
-	const textClause = () => ({ text: {
+	const paths = collectSearchPathsCached(searchIndex);
+	const fuzzyOpt = fuzzy ? { fuzzy } : {};
+	const textOp = (path) => ({ text: {
 		query: text,
-		path: { wildcard: "*" },
-		...fuzzy ? { fuzzy } : {}
+		path,
+		...fuzzyOpt
 	} });
-	const autocompleteClause = (path) => ({ autocomplete: {
+	const autocompleteOp = (path) => ({ autocomplete: {
 		query: text,
 		path,
-		...fuzzy ? { fuzzy } : {}
+		...fuzzyOpt
 	} });
-	let body;
-	if (strategy === "text" || autocompletePaths.length === 0) body = textClause();
-	else if (strategy === "autocomplete") {
-		const clauses = autocompletePaths.map(autocompleteClause);
-		body = clauses.length === 1 ? clauses[0] : { compound: {
-			should: clauses,
-			minimumShouldMatch: 1
+	const textClause = () => textOp({ wildcard: "*" });
+	const wrapEmbedded = (chain, operator) => {
+		let wrapped = operator;
+		for (let i = chain.length - 1; i >= 0; i--) wrapped = { embeddedDocument: {
+			path: chain[i],
+			operator: wrapped
 		} };
-	} else body = { compound: {
-		should: [textClause(), ...autocompletePaths.map(autocompleteClause)],
+		return wrapped;
+	};
+	const embeddedTextClause = (chain, leaves) => wrapEmbedded(chain, textOp(leaves.length === 1 ? leaves[0] : leaves));
+	const embeddedAutocompleteClause = (chain, leaf) => wrapEmbedded(chain, autocompleteOp(leaf));
+	const wantWord = strategy === "text" || strategy === "compound";
+	const wantAutocomplete = strategy === "autocomplete" || strategy === "compound";
+	const clauses = [];
+	if (wantWord) {
+		clauses.push(textClause());
+		for (const group of paths.arrayGroups) if (group.textLeaves.length > 0) clauses.push(embeddedTextClause(group.chain, group.textLeaves));
+	}
+	if (wantAutocomplete) {
+		for (const path of paths.autocompleteOutside) clauses.push(autocompleteOp(path));
+		for (const group of paths.arrayGroups) for (const leaf of group.autocompleteLeaves) clauses.push(embeddedAutocompleteClause(group.chain, leaf));
+	}
+	let body;
+	if (clauses.length <= 1) body = clauses[0] ?? textClause();
+	else body = { compound: {
+		should: clauses,
 		minimumShouldMatch: 1
 	} };
 	return {
@@ -810,13 +834,65 @@ function resolveSearchFuzzy(index, controls) {
 	const maxEdits = override === void 0 ? index.fuzzy?.maxEdits : Number(override);
 	return maxEdits === 1 || maxEdits === 2 ? { maxEdits } : void 0;
 }
-/** Field paths in this index that carry an `autocomplete` mapping. */
-function autocompleteFieldPaths(index) {
-	const fields = index.definition.mappings?.fields;
-	if (!fields) return [];
-	const paths = [];
-	for (const [path, mapping] of Object.entries(fields)) if ((Array.isArray(mapping) ? mapping : [mapping]).some((m) => m.type === "autocomplete")) paths.push(path);
-	return paths;
+/**
+* An index's mapping tree is immutable once schema sync builds it, and the index
+* object is cached for the adapter's lifetime — so the walk runs once per index,
+* not once per query (`buildSearchStage` is on the search hot path).
+*/
+const searchPathsCache = /* @__PURE__ */ new WeakMap();
+function collectSearchPathsCached(index) {
+	let cached = searchPathsCache.get(index);
+	if (!cached) {
+		cached = collectSearchPaths(index.definition.mappings?.fields);
+		searchPathsCache.set(index, cached);
+	}
+	return cached;
+}
+/**
+* Walks an index's nested mapping tree, classifying each searchable leaf by how
+* it must be queried: a plain dotted path (top-level / `document`-nested) vs.
+* scoped under an `embeddedDocuments` array root (queried via `embeddedDocument`).
+* Word-matching for non-array fields rides the wildcard `text` clause, so only
+* autocomplete leaves are tracked outside arrays.
+*/
+function collectSearchPaths(fields) {
+	const out = {
+		autocompleteOutside: [],
+		arrayGroups: []
+	};
+	const byChain = /* @__PURE__ */ new Map();
+	const walk = (map, prefix, chain) => {
+		if (!map) return;
+		for (const [key, mapping] of Object.entries(map)) {
+			const path = joinPath(prefix, key);
+			const list = Array.isArray(mapping) ? mapping : [mapping];
+			const embedded = list.find((m) => m.type === "embeddedDocuments");
+			const document = list.find((m) => m.type === "document");
+			if (embedded?.fields) walk(embedded.fields, path, [...chain, path]);
+			else if (document?.fields) walk(document.fields, path, chain);
+			else {
+				const isAutocomplete = list.some((m) => m.type === "autocomplete");
+				const isText = list.some((m) => m.type === "string");
+				if (chain.length > 0) {
+					const chainKey = chain.join(">");
+					let group = byChain.get(chainKey);
+					if (!group) {
+						group = {
+							chain,
+							textLeaves: [],
+							autocompleteLeaves: []
+						};
+						byChain.set(chainKey, group);
+						out.arrayGroups.push(group);
+					}
+					if (isText) group.textLeaves.push(path);
+					if (isAutocomplete) group.autocompleteLeaves.push(path);
+				} else if (isAutocomplete) out.autocompleteOutside.push(path);
+			}
+		}
+	};
+	walk(fields, "", []);
+	return out;
 }
 /** Builds a $vectorSearch aggregation stage from a pre-computed vector. */
 function buildVectorSearchStage(host, vector, indexName, limit) {
@@ -1175,11 +1251,8 @@ function arraySafePath(host, physicalPath, logicalPath) {
 	for (let i = 0; i < logicalSegments.length; i++) {
 		const isLeaf = i === logicalSegments.length - 1;
 		out.push(isLeaf ? physicalLeaf : logicalSegments[i]);
-		prefix = prefix ? `${prefix}.${logicalSegments[i]}` : logicalSegments[i];
-		if (!isLeaf) {
-			const type = host._table.flatMap.get(prefix);
-			if (type && resolveDesignType(type) === "array") out.push("$[]");
-		}
+		prefix = joinPath(prefix, logicalSegments[i]);
+		if (!isLeaf && isArrayPath(host._table.flatMap, prefix)) out.push("$[]");
 	}
 	return out.join(".");
 }
@@ -1189,9 +1262,8 @@ function pathCrossesArray(host, logicalPath) {
 	if (segments.length < 2) return false;
 	let prefix = "";
 	for (let i = 0; i < segments.length - 1; i++) {
-		prefix = prefix ? `${prefix}.${segments[i]}` : segments[i];
-		const type = host._table.flatMap.get(prefix);
-		if (type && resolveDesignType(type) === "array") return true;
+		prefix = joinPath(prefix, segments[i]);
+		if (isArrayPath(host._table.flatMap, prefix)) return true;
 	}
 	return false;
 }
@@ -1439,6 +1511,7 @@ function fieldMappingEqual(a, b) {
 	for (const [type, av] of am) {
 		const bv = bm.get(type);
 		if (!bv || av.analyzer !== bv.analyzer || av.tokenization !== bv.tokenization || av.minGrams !== bv.minGrams || av.maxGrams !== bv.maxGrams || av.foldDiacritics !== bv.foldDiacritics) return false;
+		if (!fieldsMatch(av.fields, bv.fields)) return false;
 	}
 	return true;
 }
@@ -1483,6 +1556,14 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 	_vectorThresholds = /* @__PURE__ */ new Map();
 	/** Cached search index lookup. */
 	_searchIndexesMap;
+	/**
+	* Search-field mappings recorded during `onFieldScanned`, applied in
+	* `onAfterFlatten`. Deferred because resolving a nested field's container
+	* shape (`document` vs `embeddedDocuments`) needs `this._table.flatMap`, which
+	* is only safe to read once the metadata build is marked complete — i.e. in
+	* `onAfterFlatten`, not mid-scan (the `flatMap` getter would re-enter `build`).
+	*/
+	_pendingSearchFields = [];
 	/** Physical field names with @db.default.increment → optional start value. */
 	_incrementFields = /* @__PURE__ */ new Map();
 	/** Physical field names that have a non-binary collation (nocase/unicode). */
@@ -1707,10 +1788,14 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 			const startValue = metadata.get("db.default.increment");
 			this._incrementFields.set(physicalName, typeof startValue === "number" ? startValue : void 0);
 		}
-		for (const index of metadata.get("db.mongo.search.text") || []) this._addFieldToSearchIndex("search_text", index.indexName, field, [index.analyzer ? {
-			type: "string",
-			analyzer: index.analyzer
-		} : { type: "string" }]);
+		for (const index of metadata.get("db.mongo.search.text") || []) this._pendingSearchFields.push({
+			indexName: index.indexName,
+			field,
+			mappings: [index.analyzer ? {
+				type: "string",
+				analyzer: index.analyzer
+			} : { type: "string" }]
+		});
 		for (const ac of metadata.get("db.mongo.search.autocomplete") || []) {
 			const autocomplete = {
 				type: "autocomplete",
@@ -1723,7 +1808,11 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 				type: "string",
 				analyzer: ac.analyzer
 			} : { type: "string" };
-			this._addFieldToSearchIndex("search_text", ac.indexName, field, [autocomplete, companion]);
+			this._pendingSearchFields.push({
+				indexName: ac.indexName,
+				field,
+				mappings: [autocomplete, companion]
+			});
 		}
 		const vectorIndex = metadata.get("db.search.vector");
 		if (vectorIndex) {
@@ -1765,6 +1854,8 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 		};
 	}
 	onAfterFlatten() {
+		for (const pending of this._pendingSearchFields) this._addFieldToSearchIndex("search_text", pending.indexName, pending.field, pending.mappings);
+		this._pendingSearchFields = [];
 		for (const [key, value] of this._vectorFilters.entries()) {
 			const index = this._mongoIndexes.get(key);
 			if (index && index.type === "vector") index.definition.fields?.push({
@@ -2218,10 +2309,45 @@ var MongoAdapter = class MongoAdapter extends BaseDbAdapter {
 		const name = _name || "DEFAULT";
 		let index = this._mongoIndexes.get(mongoIndexKey(type, name));
 		if (!index && type === "search_text") index = this._setSearchIndex(type, name, { mappings: { fields: {} } });
-		if (index) {
-			const fields = index.definition.mappings.fields;
-			fields[fieldName] = mergeFieldMappings(fields[fieldName], mappings);
+		if (!index) return;
+		const rootFields = index.definition.mappings.fields;
+		const segments = fieldName.split(".");
+		const topKey = this._table.columnMap.get(segments[0]) ?? segments[0];
+		if (segments.length === 1) {
+			rootFields[topKey] = mergeFieldMappings(rootFields[topKey], mappings);
+			return;
+		}
+		let cursor = rootFields;
+		let prefix = "";
+		for (let i = 0; i < segments.length - 1; i++) {
+			const segment = segments[i];
+			prefix = joinPath(prefix, segment);
+			const nodeType = isArrayPath(this._table.flatMap, prefix) ? "embeddedDocuments" : "document";
+			cursor = this._descendSearchNode(cursor, i === 0 ? topKey : segment, nodeType, fieldName);
 		}
+		const leaf = segments[segments.length - 1];
+		cursor[leaf] = mergeFieldMappings(cursor[leaf], mappings);
+	}
+	/**
+	* Returns (creating if needed) the nested `fields` map of the container node
+	* at `segment`, reusing a same-typed sibling node so multiple searchable
+	* fields under one parent (e.g. `identity.name` + `identity.tagline`) merge
+	* instead of clobbering.
+	*/
+	_descendSearchNode(fields, segment, nodeType, fullPath) {
+		const existing = fields[segment];
+		if (existing && !Array.isArray(existing) && (existing.type === "document" || existing.type === "embeddedDocuments")) {
+			if (existing.type !== nodeType) this._log(`search index: conflicting container type for "${fullPath}" (${existing.type} vs ${nodeType}); keeping ${existing.type}`);
+			existing.fields ??= {};
+			return existing.fields;
+		}
+		if (existing) this._log(`search index: field "${segment}" used as both value and parent in "${fullPath}"`);
+		const node = {
+			type: nodeType,
+			fields: {}
+		};
+		fields[segment] = node;
+		return node.fields;
 	}
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-mongo",
-  "version": "0.1.107",
+  "version": "0.1.109",
   "description": "Mongodb plugin for atscript.",
   "keywords": [
     "atscript",
@@ -46,17 +46,17 @@
     "access": "public"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.77",
-    "@atscript/typescript": "^0.1.77",
+    "@atscript/core": "^0.1.78",
+    "@atscript/typescript": "^0.1.78",
     "mongodb": "^6.17.0",
     "mongodb-memory-server-core": "^10.0.0",
-    "unplugin-atscript": "^0.1.77"
+    "unplugin-atscript": "^0.1.78"
   },
   "peerDependencies": {
-    "@atscript/core": "^0.1.77",
-    "@atscript/typescript": "^0.1.77",
+    "@atscript/core": "^0.1.78",
+    "@atscript/typescript": "^0.1.78",
     "mongodb": "^6.17.0",
-    "@atscript/db": "^0.1.107"
+    "@atscript/db": "^0.1.109"
   },
   "scripts": {
     "postinstall": "asc -f dts",