@dereekb/dbx-components-mcp 13.11.6 → 13.11.8

package/dbx-components-mcp.js

@@ -5,7 +5,7 @@ const require = __createRequire(import.meta.url);
 // packages/dbx-components-mcp/package.json
 var package_default = {
   name: "@dereekb/dbx-components-mcp",
-  version: "13.11.6",
+  version: "13.11.8",
   type: "module",
   bin: {
     "dbx-components-mcp": "dbx-components-mcp.js"
@@ -20,20 +20,20 @@ var package_default = {
     "@angular/core": "21.2.11",
     "@angular/forms": "21.2.11",
     "@angular/material": "^21.2.9",
-    "@dereekb/dbx-cli": "13.11.6",
-    "@dereekb/dbx-core": "13.11.6",
-    "@dereekb/dbx-firebase": "13.11.6",
-    "@dereekb/dbx-form": "13.11.6",
-    "@dereekb/dbx-web": "13.11.6",
-    "@dereekb/firebase": "13.11.6",
-    "@dereekb/firebase-server": "13.11.6",
-    "@dereekb/rxjs": "13.11.6",
-    "@dereekb/util": "13.11.6",
+    "@dereekb/dbx-cli": "13.11.8",
+    "@dereekb/dbx-core": "13.11.8",
+    "@dereekb/dbx-firebase": "13.11.8",
+    "@dereekb/dbx-form": "13.11.8",
+    "@dereekb/dbx-web": "13.11.8",
+    "@dereekb/firebase": "13.11.8",
+    "@dereekb/firebase-server": "13.11.8",
+    "@dereekb/rxjs": "13.11.8",
+    "@dereekb/util": "13.11.8",
     "@uirouter/angular": "21.0.0",
     rxjs: "^7.8.2"
   },
   devDependencies: {
-    "@dereekb/model": "13.11.6"
+    "@dereekb/model": "13.11.8"
   }
 };
 
@@ -3253,7 +3253,8 @@ var DbxMcpConfig = type16({
   version: "1",
   "modelValidate?": {
     "maxFieldNameLength?": "number>=1",
-    "ignoredFieldNames?": "string[]"
+    "ignoredFieldNames?": "string[]",
+    "ignoredExternalParents?": "string[]"
   },
   "semanticTypes?": ClusterSection,
   "uiComponents?": ClusterSection,
@@ -8066,7 +8067,9 @@ function assembleFile(input) {
     const fields = buildFields({
       converter,
       inheritedProps,
-      enumNames
+      enumNames,
+      subObjectConstIndex: input.subObjectConstIndex,
+      subObjectInterfaceIndex: input.subObjectInterfaceIndex
     });
     const referencedEnums = new Set(fields.flatMap((f) => f.enumRef ? [f.enumRef] : []));
     const relevantEnums = input.enums.filter((e) => referencedEnums.has(e.name));
@@ -8119,6 +8122,12 @@ function buildFields(input) {
     const enumRef = enumFromType ?? enumFromConverter;
     const optional = prop?.optional ?? f.converter.startsWith("optionalFirestore");
     const longName = resolveLongName(f.key, prop?.longName);
+    const subObject = resolveFieldSubObject({
+      converter: f.converter,
+      subObjectConstIndex: input.subObjectConstIndex,
+      subObjectInterfaceIndex: input.subObjectInterfaceIndex,
+      enumNames: input.enumNames
+    });
     const field = {
       name: f.key,
       longName,
@@ -8127,12 +8136,126 @@ function buildFields(input) {
       optional,
       ...prop?.description ? { description: prop.description } : {},
       ...enumRef ? { enumRef } : {},
-      ...prop?.syncFlag ? { syncFlag: prop.syncFlag } : {}
+      ...prop?.syncFlag ? { syncFlag: prop.syncFlag } : {},
+      ...subObject ? { subObject } : {}
     };
     out.push(field);
   }
   return out;
 }
+function resolveFieldSubObject(input) {
+  const { converter, subObjectConstIndex, subObjectInterfaceIndex, enumNames } = input;
+  if (!subObjectConstIndex || !subObjectInterfaceIndex) {
+    return void 0;
+  }
+  const resolved = resolveSubObjectReference(converter, subObjectConstIndex);
+  if (!resolved) {
+    return void 0;
+  }
+  const iface = subObjectInterfaceIndex.get(resolved.interfaceName);
+  if (!iface) {
+    return void 0;
+  }
+  const fields = buildSubObjectFields({ iface, subObjectConstIndex, subObjectInterfaceIndex, enumNames, visited: /* @__PURE__ */ new Set([resolved.interfaceName]) });
+  return { interfaceName: resolved.interfaceName, factoryKind: resolved.factoryKind, fields };
+}
+var INLINE_SUB_OBJECT_RE = /^(firestoreSubObject|firestoreObjectArray|firestoreMap)\s*<\s*([A-Za-z_$][A-Za-z0-9_$]*)\s*>/;
+var WRAPPED_OBJECT_FIELD_RE = /^(firestoreObjectArray|firestoreMap)\s*\(\s*\{\s*objectField:\s*([A-Za-z_$][A-Za-z0-9_$]*)/;
+function resolveSubObjectReference(converter, index) {
+  let result;
+  const trimmed = converter.trim();
+  const inline = INLINE_SUB_OBJECT_RE.exec(trimmed);
+  if (inline) {
+    result = { interfaceName: inline[2], factoryKind: FACTORY_KIND_BY_NAME[inline[1]] };
+  } else {
+    const wrapped = WRAPPED_OBJECT_FIELD_RE.exec(trimmed);
+    if (wrapped) {
+      const entry = index.get(wrapped[2]);
+      if (entry) {
+        const outerKind = FACTORY_KIND_BY_NAME[wrapped[1]];
+        result = { interfaceName: entry.interfaceName, factoryKind: outerKind };
+      }
+    } else {
+      const entry = index.get(trimmed);
+      if (entry) {
+        result = { interfaceName: entry.interfaceName, factoryKind: entry.factoryKind };
+      }
+    }
+  }
+  return result;
+}
+var FACTORY_KIND_BY_NAME = {
+  firestoreSubObject: "object",
+  firestoreObjectArray: "array",
+  firestoreMap: "map"
+};
+function buildSubObjectFields(input) {
+  const out = [];
+  for (const prop of input.iface.props) {
+    out.push(buildSubObjectField({ prop, ...input }));
+  }
+  return out;
+}
+function buildSubObjectField(input) {
+  const { prop, subObjectConstIndex, subObjectInterfaceIndex, enumNames, visited } = input;
+  const enumRef = prop.tsType ? findEnumInType(prop.tsType, enumNames) : void 0;
+  const longName = resolveLongName(prop.name, prop.longName);
+  const nested = resolveNestedSubObjectFromType({ tsType: prop.tsType, subObjectConstIndex, subObjectInterfaceIndex, enumNames, visited });
+  const field = {
+    name: prop.name,
+    longName,
+    converter: "",
+    ...prop.tsType ? { tsType: prop.tsType } : {},
+    optional: prop.optional,
+    ...prop.description ? { description: prop.description } : {},
+    ...enumRef ? { enumRef } : {},
+    ...prop.syncFlag ? { syncFlag: prop.syncFlag } : {},
+    ...nested ? { subObject: nested } : {}
+  };
+  return field;
+}
+function resolveNestedSubObjectFromType(input) {
+  const { tsType, subObjectInterfaceIndex, visited } = input;
+  if (!tsType) return void 0;
+  const peeled = peelArrayAndMaybe(tsType.trim());
+  if (!peeled) return void 0;
+  if (visited.has(peeled.name)) return void 0;
+  const iface = subObjectInterfaceIndex.get(peeled.name);
+  if (!iface) return void 0;
+  const nestedVisited = new Set(visited);
+  nestedVisited.add(peeled.name);
+  const fields = buildSubObjectFields({
+    iface,
+    subObjectConstIndex: input.subObjectConstIndex,
+    subObjectInterfaceIndex,
+    enumNames: input.enumNames,
+    visited: nestedVisited
+  });
+  return { interfaceName: peeled.name, factoryKind: peeled.array ? "array" : "object", fields };
+}
+function peelArrayAndMaybe(raw) {
+  let current = raw;
+  let array = false;
+  const maybeMatch = /^Maybe<\s*(.+)\s*>$/.exec(current);
+  if (maybeMatch) {
+    current = maybeMatch[1].trim();
+  }
+  const readonlyArrayMatch = /^ReadonlyArray<\s*(.+)\s*>$/.exec(current);
+  if (readonlyArrayMatch) {
+    current = readonlyArrayMatch[1].trim();
+    array = true;
+  } else {
+    const arrayMatch = /^(?:readonly\s+)?(.+?)(\s*\[\s*\])$/.exec(current);
+    if (arrayMatch) {
+      current = arrayMatch[1].trim();
+      array = true;
+    }
+  }
+  if (!/^[A-Z][A-Za-z0-9_$]*$/.test(current)) {
+    return void 0;
+  }
+  return { name: current, array };
+}
 function resolveLongName(fieldName, propLongName) {
   let result;
   if (propLongName && LONG_NAME_RE.test(propLongName)) {
@@ -8314,14 +8437,18 @@ function peelTypeNode(node) {
 }
 function readInterfaceTags(jsDocs) {
   let dbxModel = false;
+  let dbxModelSubObject = false;
   for (const jsDoc of jsDocs) {
     for (const tag of jsDoc.getTags()) {
-      if (tag.getTagName() === "dbxModel") {
+      const tagName = tag.getTagName();
+      if (tagName === "dbxModel") {
         dbxModel = true;
+      } else if (tagName === "dbxModelSubObject") {
+        dbxModelSubObject = true;
       }
     }
   }
-  return { dbxModel };
+  return { dbxModel, dbxModelSubObject };
 }
 function readPropertyTags2(jsDocs) {
   let dbxModelVariable;
@@ -8526,6 +8653,40 @@ function extractGroupModelNames(text) {
   return [...seen].sort((a, b) => a.localeCompare(b));
 }
 
+// packages/dbx-components-mcp/src/scan/extract-models/find-sub-object-consts.ts
+import { Node as Node11 } from "ts-morph";
+var SUB_OBJECT_FACTORY_NAMES = /* @__PURE__ */ new Set(["firestoreSubObject", "firestoreObjectArray", "firestoreMap"]);
+function findSubObjectConsts(sf) {
+  const out = [];
+  for (const statement of sf.getVariableStatements()) {
+    for (const decl of statement.getDeclarations()) {
+      const entry = readSubObjectConst(decl);
+      if (entry) out.push(entry);
+    }
+  }
+  return out;
+}
+function readSubObjectConst(decl) {
+  const initializer = decl.getInitializer();
+  if (!initializer || !Node11.isCallExpression(initializer)) return void 0;
+  const expr = initializer.getExpression();
+  if (!Node11.isIdentifier(expr)) return void 0;
+  const factoryName = expr.getText();
+  if (!SUB_OBJECT_FACTORY_NAMES.has(factoryName)) return void 0;
+  const interfaceName = readInterfaceTypeArg2(initializer);
+  if (!interfaceName) return void 0;
+  return { constName: decl.getName(), interfaceName, factoryName };
+}
+function readInterfaceTypeArg2(call) {
+  const typeArgs = call.getTypeArguments();
+  if (typeArgs.length === 0) return void 0;
+  const first = typeArgs[0];
+  if (!Node11.isTypeReference(first)) return void 0;
+  const nameNode = first.getTypeName();
+  if (!Node11.isIdentifier(nameNode)) return void 0;
+  return nameNode.getText();
+}
+
 // packages/dbx-components-mcp/src/scan/extract-models/infer-collection-kind.ts
 var COLLECTION_CALL_RE = /\.(firestoreCollection|rootSingleItemFirestoreCollection|firestoreCollectionWithParent|singleItemFirestoreCollection)\s*\(/g;
 var KIND_BY_METHOD = {
@@ -8571,14 +8732,37 @@ async function extractModels(input) {
   const models = [];
   const modelGroups = [];
   const errors = [];
+  const subObjectConstIndex = /* @__PURE__ */ new Map();
+  const subObjectInterfaceIndex = /* @__PURE__ */ new Map();
+  const parsedFiles = [];
   for (const filePath of files) {
     const sourceFileRel = relative3(baseDir, filePath).split(sep3).join(posix.sep);
     try {
       const text = await readFile2(filePath, "utf8");
-      if (!text.includes("firestoreModelIdentity(") && !text.includes("@dbxModelGroup")) {
+      const hasModelMarker = text.includes("firestoreModelIdentity(") || text.includes("@dbxModelGroup");
+      const hasSubObjectMarker = text.includes("@dbxModelSubObject") || text.includes("firestoreSubObject") || text.includes("firestoreObjectArray") || text.includes("firestoreMap");
+      if (!hasModelMarker && !hasSubObjectMarker) {
         continue;
       }
-      const sf = project.createSourceFile(`/scan/${basename2(filePath)}-${models.length}-${modelGroups.length}.ts`, text, { overwrite: true });
+      const sf = project.createSourceFile(`/scan/${basename2(filePath)}-${parsedFiles.length}.ts`, text, { overwrite: true });
+      parsedFiles.push({ filePath, sourceFileRel, sf, hasModelMarker });
+      for (const c of findSubObjectConsts(sf)) {
+        if (!subObjectConstIndex.has(c.constName)) {
+          subObjectConstIndex.set(c.constName, { interfaceName: c.interfaceName, factoryKind: c.factoryName === "firestoreSubObject" ? "object" : c.factoryName === "firestoreObjectArray" ? "array" : "map" });
+        }
+      }
+      for (const iface of findInterfaces(sf)) {
+        if (iface.tags.dbxModelSubObject && !subObjectInterfaceIndex.has(iface.name)) {
+          subObjectInterfaceIndex.set(iface.name, iface);
+        }
+      }
+    } catch (error) {
+      errors.push({ sourceFile: sourceFileRel, message: error instanceof Error ? error.message : String(error) });
+    }
+  }
+  for (const { sourceFileRel, sf, hasModelMarker } of parsedFiles) {
+    if (!hasModelMarker) continue;
+    try {
       const assembled = assembleFile({
         sourcePackage,
         sourceFile: sourceFileRel,
@@ -8587,7 +8771,9 @@ async function extractModels(input) {
         converters: findConverters(sf),
         enums: findEnums(sf),
         modelGroups: findModelGroups(sf),
-        factoryKinds: findCollectionFactoryCalls(sf)
+        factoryKinds: findCollectionFactoryCalls(sf),
+        subObjectConstIndex,
+        subObjectInterfaceIndex
       });
       for (const m of assembled.models) models.push(m);
       for (const g of assembled.modelGroups) modelGroups.push(g);
@@ -13041,15 +13227,44 @@ function applyFieldsFilter(model, filter) {
   for (const field of model.fields) {
     const nameLower = field.name.toLowerCase();
     const longNameLower = field.longName.toLowerCase();
-    if (filterSet.has(nameLower) || filterSet.has(longNameLower)) {
+    let keep = false;
+    if (filterSet.has(nameLower)) {
+      matched.add(nameLower);
+      keep = true;
+    }
+    if (filterSet.has(longNameLower)) {
+      matched.add(longNameLower);
+      keep = true;
+    }
+    if (field.subObject !== void 0 && subObjectMatches(field.subObject, filterSet, matched)) {
+      keep = true;
+    }
+    if (keep) {
       kept.push(field);
-      if (filterSet.has(nameLower)) matched.add(nameLower);
-      if (filterSet.has(longNameLower)) matched.add(longNameLower);
     }
   }
   const unmatchedFilters = filter.filter((entry) => !matched.has(entry));
   return { kept, unmatchedFilters };
 }
+function subObjectMatches(subObject, filterSet, matched) {
+  let any = false;
+  for (const field of subObject.fields) {
+    const nameLower = field.name.toLowerCase();
+    const longNameLower = field.longName.toLowerCase();
+    if (filterSet.has(nameLower)) {
+      matched.add(nameLower);
+      any = true;
+    }
+    if (filterSet.has(longNameLower)) {
+      matched.add(longNameLower);
+      any = true;
+    }
+    if (field.subObject !== void 0 && subObjectMatches(field.subObject, filterSet, matched)) {
+      any = true;
+    }
+  }
+  return any;
+}
 function firebaseModelStoreShape(model) {
   const result = model.parentIdentityConst ? "sub-collection" : "root";
   return result;
@@ -13098,18 +13313,66 @@ function appendFieldsTable(lines, fields, depth) {
     lines.push("| Field | Description |", "|-------|-------------|");
     for (const field of fields) {
       const desc = describeField(field);
-      lines.push(`| \`${field.name}\` | ${desc} |`);
+      lines.push(`| \`${formatFieldLabel(field)}\` | ${desc} |`);
     }
   } else {
     lines.push("| Field | Description | Type | Converter |", "|-------|-------------|------|-----------|");
     for (const field of fields) {
       const desc = describeField(field);
       const ts = field.tsType ? `\`${field.tsType}\`` : "\u2013";
-      const conv = `\`${field.converter}\``;
-      lines.push(`| \`${field.name}\` | ${desc} | ${ts} | ${conv} |`);
+      const conv = field.converter.length > 0 ? `\`${field.converter}\`` : "\u2013";
+      lines.push(`| \`${formatFieldLabel(field)}\` | ${desc} | ${ts} | ${conv} |`);
     }
   }
+  appendSubObjectSections(lines, fields, depth);
+}
+function formatFieldLabel(field) {
+  if (field.longName && field.longName !== field.name) {
+    return `${field.name} (${field.longName})`;
+  }
+  return field.name;
+}
+function appendSubObjectSections(lines, fields, depth) {
+  for (const field of fields) {
+    if (field.subObject === void 0) continue;
+    appendSubObjectSection({ lines, parentLabel: formatFieldLabel(field), subObject: field.subObject, depth, headingLevel: 3 });
+  }
 }
+function appendSubObjectSection(input) {
+  const { lines, parentLabel, subObject, depth, headingLevel } = input;
+  const heading = "#".repeat(Math.min(Math.max(headingLevel, 2), 6));
+  const kindLabel = SUB_OBJECT_KIND_LABEL[subObject.factoryKind];
+  lines.push("", `${heading} Sub-object: \`${parentLabel}\` \u2192 \`${subObject.interfaceName}\` (${kindLabel})`, "");
+  if (depth === "brief") {
+    lines.push("| Field | Description |", "|-------|-------------|");
+    for (const field of subObject.fields) {
+      const desc = describeField(field);
+      lines.push(`| \`${formatFieldLabel(field)}\` | ${desc} |`);
+    }
+  } else {
+    lines.push("| Field | Description | Type |", "|-------|-------------|------|");
+    for (const field of subObject.fields) {
+      const desc = describeField(field);
+      const ts = field.tsType ? `\`${field.tsType}\`` : "\u2013";
+      lines.push(`| \`${formatFieldLabel(field)}\` | ${desc} | ${ts} |`);
+    }
+  }
+  for (const field of subObject.fields) {
+    if (field.subObject === void 0) continue;
+    appendSubObjectSection({
+      lines,
+      parentLabel: `${parentLabel}.${formatFieldLabel(field)}`,
+      subObject: field.subObject,
+      depth,
+      headingLevel: headingLevel + 1
+    });
+  }
+}
+var SUB_OBJECT_KIND_LABEL = {
+  object: "embedded object",
+  array: "embedded array",
+  map: "embedded map"
+};
 function describeField(field) {
   return (field.description ?? "\u2013").replaceAll("|", String.raw`\|`).replaceAll("\n", " ");
 }
@@ -13407,7 +13670,7 @@ var DBX_MODEL_LOOKUP_TOOL = {
     "Optional inputs:",
     '  \u2022 `scope`: `"all"` (default), `"upstream"` (only `@dereekb/firebase`), or `"downstream"` (only component packages).',
     "  \u2022 `componentDirs`: explicit downstream package directories \u2014 overrides the default `components/*-firebase` discovery.",
-    '  \u2022 `fields`: when the topic resolves to a single model, restrict the rendered fields table to those whose persisted name (e.g. `"fs"`) or longName (e.g. `"fileState"`) appears in the list (case-insensitive). Enums prune to only those referenced by the kept fields. Ignored on catalog/shapes/not-found responses.'
+    '  \u2022 `fields`: when the topic resolves to a single model, restrict the rendered fields table to those whose persisted name (e.g. `"fs"`) or longName (e.g. `"fileState"`) appears in the list (case-insensitive). Filters also match against `@dbxModelSubObject` field names / longNames reachable through a parent field\'s `firestoreSubObject<T>` / `firestoreObjectArray<T>` / `firestoreMap<T>` converter \u2014 the parent field is kept whenever any of its nested sub-object fields match. Enums prune to only those referenced by the kept fields. Ignored on catalog/shapes/not-found responses.'
   ].join("\n"),
   inputSchema: {
     type: "object",
@@ -13950,29 +14213,35 @@ function matchPrefix(value, prefixes) {
 var DBX_MODEL_DECODE_TOOL = {
   name: "dbx_model_decode",
   description: [
-    "Decode a raw @dereekb/firebase Firestore document \u2014 identify the model, expand abbreviated field names to their descriptions, decode enum integer values, and surface foreign-key relationships to other models.",
+    "Decode a @dereekb/firebase Firestore document or model key.",
     "",
-    'Pass `data` as either a JSON string (copied straight from the Firestore console) or an already-parsed object. Pass `model` to skip detection and target a specific model by interface name (`"StorageFile"`), identity constant (`"storageFileIdentity"`), `modelType` (`"storageFile"`), or collection prefix (`"sf"`).',
+    'Document mode \u2014 pass `data` as a JSON string (copied straight from the Firestore console) or an already-parsed object to identify the model, expand abbreviated field names, decode enum integer values, and surface foreign-key relationships. Optionally pass `model` to skip detection and target a specific model by interface name (`"StorageFile"`), identity constant (`"storageFileIdentity"`), `modelType` (`"storageFile"`), or collection prefix (`"sf"`).',
     "",
-    "Auto-detection uses the document's key field (if any), then falls back to scoring each registered model by how many of its distinctive fields are present."
+    'Key mode \u2014 pass just `key` (e.g. `"jwr/hkzQa9W6MpaP99RTlQJcImbWdZm2"`) to resolve the model identity and id from the collection prefix alone, no document required. Subcollection paths like `"nb/abc/nbn/def"` are walked end-to-end so the leaf model is reported alongside its parent chain.',
+    "",
+    "At least one of `data` or `key` is required."
   ].join("\n"),
   inputSchema: {
     type: "object",
     properties: {
       data: {
-        description: "Raw Firestore document \u2014 JSON string or already-parsed object.",
+        description: "Raw Firestore document \u2014 JSON string or already-parsed object. Required for document mode.",
         oneOf: [{ type: "string" }, { type: "object" }]
       },
+      key: {
+        type: "string",
+        description: 'Firestore model key (e.g. `"sf/abc123"` or subcollection path `"nb/abc/nbn/def"`). Used as the sole input in key mode, or as an extra detection hint when paired with `data`.'
+      },
       model: {
         type: "string",
         description: "Optional model hint \u2014 interface name, identity const, model type, or collection prefix."
       }
-    },
-    required: ["data"]
+    }
   }
 };
 var DecodeArgsType = type36({
-  data: "string | object",
+  "data?": "string | object",
+  "key?": "string",
   "model?": "string"
 });
 function parseDecodeArgs(raw) {
@@ -13982,6 +14251,7 @@ function parseDecodeArgs(raw) {
   }
   const result = {
     data: parsed.data,
+    key: parsed.key,
     model: parsed.model
   };
   return result;
@@ -14055,6 +14325,78 @@ function buildPrefixMap() {
   }
   return out;
 }
+function decodeKeyPath(key, hint) {
+  const trimmed = key.trim();
+  if (trimmed.length === 0) {
+    return { error: "Key is empty. Provide a Firestore key like `sf/abc123`." };
+  }
+  const segments = trimmed.split("/").filter((s) => s.length > 0);
+  if (segments.length < 2 || segments.length % 2 !== 0) {
+    return {
+      error: `Invalid Firestore key '${trimmed}'. Expected an even number of segments (\`prefix/id\` pairs). Got ${segments.length} segment(s).`
+    };
+  }
+  const decoded = [];
+  const unresolved = [];
+  for (let i = 0; i < segments.length; i += 2) {
+    const prefix = segments[i];
+    const id = segments[i + 1];
+    const model = getFirebaseModelByPrefix(prefix);
+    if (!model) {
+      unresolved.push(prefix);
+    }
+    decoded.push({ prefix, id, model });
+  }
+  let leaf = decoded[decoded.length - 1];
+  if (!leaf.model && hint) {
+    const fromHint = getFirebaseModel(hint) ?? getFirebaseModelByPrefix(hint);
+    if (fromHint) {
+      leaf = { prefix: leaf.prefix, id: leaf.id, model: fromHint };
+    }
+  }
+  const ancestors2 = decoded.slice(0, -1);
+  return { leaf, ancestors: ancestors2, unresolvedPrefixes: unresolved };
+}
+function formatKeyDecode(input, rawKey) {
+  const lines = [];
+  lines.push("_Model decoded from key prefix._", "");
+  const leaf = input.leaf;
+  if (leaf.model) {
+    lines.push(`**Leaf:** ${leaf.model.name}`);
+    lines.push(`- identityConst: \`${leaf.model.identityConst}\``);
+    lines.push(`- modelType: \`${leaf.model.modelType}\``);
+    lines.push(`- prefix: \`${leaf.prefix}\``);
+    lines.push(`- id: \`${leaf.id}\``);
+    if (leaf.model.modelGroup) {
+      lines.push(`- modelGroup: ${leaf.model.modelGroup}`);
+    }
+    if (leaf.model.parentIdentityConst) {
+      lines.push(`- parentIdentityConst: \`${leaf.model.parentIdentityConst}\``);
+    }
+    lines.push(`- source: \`${leaf.model.sourcePackage}\` (${leaf.model.sourceFile})`);
+  } else {
+    lines.push(`**Leaf:** _unknown_ \u2014 no model registered for prefix \`${leaf.prefix}\``);
+    lines.push(`- prefix: \`${leaf.prefix}\``);
+    lines.push(`- id: \`${leaf.id}\``);
+  }
+  if (input.ancestors.length > 0) {
+    lines.push("", "**Parent chain:**");
+    for (const ancestor of input.ancestors) {
+      if (ancestor.model) {
+        lines.push(`- ${ancestor.model.name} \u2014 prefix \`${ancestor.prefix}\`, id \`${ancestor.id}\``);
+      } else {
+        lines.push(`- _unknown_ \u2014 prefix \`${ancestor.prefix}\` (id \`${ancestor.id}\`)`);
+      }
+    }
+  }
+  if (input.unresolvedPrefixes.length > 0) {
+    const label = input.unresolvedPrefixes.length === 1 ? "prefix" : "prefixes";
+    const list = input.unresolvedPrefixes.map((p) => `\`${p}\``).join(", ");
+    lines.push("", `_Unresolved ${label}: ${list}. Run \`dbx_model_lookup\` to browse known models._`);
+  }
+  lines.push("", `_Key:_ \`${rawKey}\``);
+  return lines.join("\n");
+}
 function runModelDecode(rawArgs) {
   let args;
   try {
@@ -14063,6 +14405,18 @@ function runModelDecode(rawArgs) {
     const message = err instanceof Error ? err.message : String(err);
     return toolError(message);
   }
+  if (args.data === void 0 && args.key === void 0) {
+    return toolError("Provide either `data` (a Firestore document) or `key` (a Firestore model key).");
+  }
+  if (args.data === void 0 && typeof args.key === "string") {
+    const decoded = decodeKeyPath(args.key, args.model);
+    if ("error" in decoded) {
+      return toolError(decoded.error);
+    }
+    const text2 = formatKeyDecode(decoded, args.key);
+    const result2 = { content: [{ type: "text", text: text2 }] };
+    return result2;
+  }
   let document;
   try {
     document = coerceToDocument(args.data);
@@ -14070,15 +14424,16 @@ function runModelDecode(rawArgs) {
     const message = err instanceof Error ? err.message : String(err);
     return toolError(message);
   }
-  const detection = detectModel(document.doc, document.extraKey, args.model);
+  const extraKey = args.key ?? document.extraKey;
+  const detection = detectModel(document.doc, extraKey, args.model);
   if (!detection) {
-    const message = buildUnmatchedMessage(args.model, document);
+    const message = buildUnmatchedMessage(args.model, { ...document, extraKey });
     const result2 = { content: [{ type: "text", text: message }] };
     return result2;
   }
   const prefixes = buildPrefixMap();
   const header = buildDetectionHeader(detection);
-  const body = formatDecode({ model: detection.model, doc: document.doc, prefixes, extraKey: document.extraKey });
+  const body = formatDecode({ model: detection.model, doc: document.doc, prefixes, extraKey });
   const text = `${header}
 
 ${body}`;
@@ -14279,7 +14634,15 @@ function createListAppTool(config) {
 }
 
 // packages/dbx-components-mcp/src/tools/model-validate/extract.ts
-import { Node as Node11, Project as Project4, SyntaxKind as SyntaxKind4 } from "ts-morph";
+import { Node as Node12, Project as Project4, SyntaxKind as SyntaxKind4 } from "ts-morph";
+
+// packages/dbx-components-mcp/src/tools/model-validate/types.ts
+var MAX_FIELD_NAME_LENGTH = 5;
+var ROOT_MODEL_ORDER = ["identity", "interface", "rolesType", "documentClass", "converter", "referenceFn", "collectionType", "collectionFn"];
+var SUBCOLLECTION_MODEL_ORDER = ["identity", "interface", "rolesType", "documentClass", "converter", "referenceFn", "collectionType", "collectionFactoryType", "collectionFn", "referenceGroupFn", "collectionGroupType", "collectionGroupFn"];
+var SUB_OBJECT_FACTORY_NAMES2 = ["firestoreSubObject", "firestoreObjectArray", "firestoreMap"];
+
+// packages/dbx-components-mcp/src/tools/model-validate/extract.ts
 function extractFile(source) {
   const project = new Project4({ useInMemoryFileSystem: true, skipAddingFilesFromTsConfig: true });
   const sourceFile = project.createSourceFile(source.name, source.text, { overwrite: true });
@@ -14289,16 +14652,56 @@ function extractFile(source) {
   const firstModelLine = identities.length > 0 ? Math.min(...identities.map((i) => i.line)) : void 0;
   const models = identities.map((identity) => extractModel(sourceFile, identity));
   const dataInterfaces = findDataInterfaces(sourceFile, groupInterface);
+  const subObjectCalls = findSubObjectFactoryCalls(sourceFile);
   const result = {
     name: source.name,
     groupInterface,
     groupTypes,
     firstModelLine,
     models,
-    dataInterfaces
+    dataInterfaces,
+    subObjectCalls
   };
   return result;
 }
+function findSubObjectFactoryCalls(sourceFile) {
+  const out = [];
+  const factorySet = new Set(SUB_OBJECT_FACTORY_NAMES2);
+  for (const call of sourceFile.getDescendantsOfKind(SyntaxKind4.CallExpression)) {
+    const expr = call.getExpression();
+    if (!Node12.isIdentifier(expr)) {
+      continue;
+    }
+    const factoryName = expr.getText();
+    if (!factorySet.has(factoryName)) {
+      continue;
+    }
+    const typeArgs = call.getTypeArguments();
+    if (typeArgs.length === 0) {
+      continue;
+    }
+    const typeArgName = readTypeReferenceIdentifier(typeArgs[0]);
+    if (!typeArgName) {
+      continue;
+    }
+    out.push({
+      factoryName,
+      typeArgName,
+      line: call.getStartLineNumber()
+    });
+  }
+  return out;
+}
+function readTypeReferenceIdentifier(typeNode) {
+  if (!Node12.isTypeReference(typeNode)) {
+    return void 0;
+  }
+  const nameNode = typeNode.getTypeName();
+  if (!Node12.isIdentifier(nameNode)) {
+    return void 0;
+  }
+  return nameNode.getText();
+}
 function findDataInterfaces(sourceFile, groupInterface) {
   const out = [];
   const groupName = groupInterface?.name;
@@ -14309,10 +14712,50 @@ function findDataInterfaces(sourceFile, groupInterface) {
     }
     const fields = extractInterfaceFields(iface);
     const dbxModelTag = readDbxModelTag(iface.getJsDocs());
-    out.push({ name, line: iface.getStartLineNumber(), dbxModelTag, fields });
+    const dbxModelSubObjectTag = readDbxModelSubObjectTag(iface.getJsDocs());
+    const extendsNames = readExtendsNames(iface);
+    out.push({ name, line: iface.getStartLineNumber(), dbxModelTag, dbxModelSubObjectTag, extendsNames, fields });
+  }
+  return out;
+}
+function readExtendsNames(iface) {
+  const out = [];
+  for (const expr of iface.getExtends()) {
+    const head = expr.getExpression().getText();
+    let resolved = head;
+    if (PASSTHROUGH_TYPE_WRAPPERS2.has(head)) {
+      const typeArgs = expr.getTypeArguments();
+      if (typeArgs.length > 0) {
+        const peeled = peelExtendsTypeNode(typeArgs[0]);
+        if (peeled !== void 0) {
+          resolved = peeled;
+        }
+      }
+    }
+    out.push(resolved);
   }
   return out;
 }
+var PASSTHROUGH_TYPE_WRAPPERS2 = /* @__PURE__ */ new Set(["Partial", "Required", "Readonly", "NonNullable", "MaybeMap", "Pick", "Omit"]);
+function peelExtendsTypeNode(node) {
+  let current = node;
+  while (Node12.isParenthesizedTypeNode(current)) {
+    current = current.getTypeNode();
+  }
+  let result;
+  if (Node12.isTypeReference(current)) {
+    const name = current.getTypeName().getText();
+    if (PASSTHROUGH_TYPE_WRAPPERS2.has(name)) {
+      const inner = current.getTypeArguments();
+      if (inner.length > 0) {
+        result = peelExtendsTypeNode(inner[0]);
+      }
+    } else {
+      result = name;
+    }
+  }
+  return result;
+}
 function extractInterfaceFields(iface) {
   const fields = [];
   for (const prop of iface.getProperties()) {
@@ -14379,6 +14822,17 @@ function readDbxModelTag(jsDocs) {
   }
   return result;
 }
+function readDbxModelSubObjectTag(jsDocs) {
+  let result = false;
+  for (const jsDoc of jsDocs) {
+    for (const tag of jsDoc.getTags()) {
+      if (tag.getTagName() === "dbxModelSubObject") {
+        result = true;
+      }
+    }
+  }
+  return result;
+}
 function readDbxModelVariableTag(jsDocs) {
   let result;
   for (const jsDoc of jsDocs) {
@@ -14418,7 +14872,7 @@ function extractIdentityRefs(alias) {
   if (!typeNode) {
     return refs;
   }
-  if (Node11.isTypeQuery(typeNode)) {
+  if (Node12.isTypeQuery(typeNode)) {
     refs.push(typeNode.getExprName().getText());
   }
   const typeofNodes = typeNode.getDescendantsOfKind(SyntaxKind4.TypeQuery);
@@ -14432,7 +14886,7 @@ function findIdentities2(sourceFile) {
   for (const statement of sourceFile.getVariableStatements()) {
     for (const decl of statement.getDeclarations()) {
       const initializer = decl.getInitializer();
-      if (!initializer || !Node11.isCallExpression(initializer)) {
+      if (!initializer || !Node12.isCallExpression(initializer)) {
         continue;
       }
       if (initializer.getExpression().getText() !== "firestoreModelIdentity") {
@@ -14468,7 +14922,7 @@ function parseIdentityArgs(args) {
   }
   if (args.length === 3) {
     const [parentNode, nameNode, prefixNode] = args;
-    const parentRef = Node11.isIdentifier(parentNode) ? parentNode.getText() : void 0;
+    const parentRef = Node12.isIdentifier(parentNode) ? parentNode.getText() : void 0;
     const result2 = {
       parentIdentityRef: parentRef,
       collectionName: stringLiteralValue2(nameNode),
@@ -14483,7 +14937,7 @@ function stringLiteralValue2(node) {
   if (!node) {
     return void 0;
   }
-  if (Node11.isStringLiteral(node) || Node11.isNoSubstitutionTemplateLiteral(node)) {
+  if (Node12.isStringLiteral(node) || Node12.isNoSubstitutionTemplateLiteral(node)) {
     return node.getLiteralText();
   }
   return void 0;
@@ -14544,7 +14998,7 @@ function detectFactoryCallKind(sourceFile, factoryFnName) {
   const calls = fn.getDescendantsOfKind(SyntaxKind4.CallExpression);
   for (const call of calls) {
     const expr = call.getExpression();
-    if (!Node11.isPropertyAccessExpression(expr)) {
+    if (!Node12.isPropertyAccessExpression(expr)) {
       continue;
     }
     const name = expr.getName();
@@ -15141,7 +15595,7 @@ var RULE_CATALOG = [
     severity: "warning",
     title: "A persisted field's `@dbxModelVariable <longName>` tag value matches the field's short name verbatim, defeating the tag's purpose (the long name should be the field's unabbreviated camelCase variable name)",
     whatItFlags: "A persisted field's `@dbxModelVariable <longName>` tag value matches the field's short name verbatim, defeating the tag's purpose (the long name should be the field's unabbreviated camelCase variable name).",
-    whenItApplies: "Every field on a `@dbxModel` interface where `@dbxModelVariable` is present and its value equals the field's name (e.g. field `h` tagged `@dbxModelVariable h`, field `ub` tagged `@dbxModelVariable ub`). The tag must always carry the unabbreviated form so the catalog and decoder surface a meaningful long name.",
+    whenItApplies: "Every field on a `@dbxModel` interface or on a `@dbxModelSubObject`-tagged embedded sub-object interface where `@dbxModelVariable` is present and its value equals the field's name (e.g. field `h` tagged `@dbxModelVariable h`, field `ub` tagged `@dbxModelVariable ub`). The tag must always carry the unabbreviated form so the catalog and decoder surface a meaningful long name.",
     whenItDoesNotApply: "Fields whose name is already the unabbreviated camelCase form (e.g. `name`, `email`, `id`, `at`) \u2014 add those to `dbx-mcp.config.json` `modelValidate.ignoredFieldNames` to silence the warning workspace-wide.",
     canonicalFix: "Replace the tag value with the field's unabbreviated camelCase variable name (e.g. `@dbxModelVariable h` \u2192 `@dbxModelVariable hours`, `@dbxModelVariable ub` \u2192 `@dbxModelVariable usedBudget`). To exempt fields whose long name legitimately equals the short name, add them to `modelValidate.ignoredFieldNames`."
   },
@@ -15161,8 +15615,8 @@ var RULE_CATALOG = [
     severity: "warning",
     title: "A persisted field is missing its `@dbxModelVariable <name>` JSDoc tag",
     whatItFlags: "A persisted field is missing its `@dbxModelVariable <name>` JSDoc tag.",
-    whenItApplies: "Every field on a `@dbxModel` interface \u2014 the tag carries the human-readable long name the catalog and decoder use when surfacing the field to operators. The long name is the variable name the field would have unabbreviated, written in camelCase (e.g. `uid` \u2192 `userUid`, `n` \u2192 `name`, `crAt` \u2192 `createdAt`).",
-    whenItDoesNotApply: "Fields on embedded sub-object interfaces (no `@dbxModel` parent) and fields the project deliberately leaves untagged (rare).",
+    whenItApplies: "Every field on a `@dbxModel` interface or on a `@dbxModelSubObject`-tagged embedded sub-object interface \u2014 the tag carries the human-readable long name the catalog and decoder use when surfacing the field to operators. The long name is the variable name the field would have unabbreviated, written in camelCase (e.g. `uid` \u2192 `userUid`, `n` \u2192 `name`, `crAt` \u2192 `createdAt`).",
+    whenItDoesNotApply: "Fields on embedded sub-object interfaces that are not tagged with `@dbxModelSubObject` (the tag is opt-in) and fields the project deliberately leaves untagged (rare).",
     canonicalFix: "Append `@dbxModelVariable <longName>` to the field's JSDoc block, where `<longName>` is the field's unabbreviated camelCase variable name."
   },
   {
@@ -15349,6 +15803,48 @@ var RULE_CATALOG = [
     whenItDoesNotApply: "When intentionally module-private.",
     canonicalFix: "Add `export` to the alias."
   },
+  {
+    code: "MODEL_SUBOBJECT_NOT_TAGGED",
+    source: "dbx_model_validate",
+    severity: "warning",
+    title: "An interface is referenced as the first generic type-argument of a sub-object factory call (`firestoreSubObject<T>(...)`, `firestoreObjectArray<T>(...)`, or `firestoreMap<T>(...)`) but its declaration carries neither `@dbxModel` nor `@dbxModelSubObject`. The interface therefore opts out of the workspace's `@dbxModelVariable` long-name conventions even though its fields are persisted to Firestore",
+    whatItFlags: "An interface is referenced as the first generic type-argument of a sub-object factory call (`firestoreSubObject<T>(...)`, `firestoreObjectArray<T>(...)`, or `firestoreMap<T>(...)`) but its declaration carries neither `@dbxModel` nor `@dbxModelSubObject`. The interface therefore opts out of the workspace's `@dbxModelVariable` long-name conventions even though its fields are persisted to Firestore.",
+    whenItApplies: "Any interface declared in the validated source set that is the type-arg of at least one sub-object factory call and lacks both `@dbxModel` and `@dbxModelSubObject`. The warning is emitted once per interface (de-duplicated across all call sites) and anchored at the interface declaration line. Unresolved type-args \u2014 interfaces declared outside the validated source set, generic parameters, inline types \u2014 are silently skipped to avoid false positives.",
+    whenItDoesNotApply: "Interfaces already tagged with `@dbxModel` (top-level models) or `@dbxModelSubObject` (embedded sub-objects), and interfaces referenced only from outside the supplied source set (different package, etc.).",
+    canonicalFix: "Add `@dbxModelSubObject` to the interface's JSDoc block so its fields are subject to `@dbxModelVariable` long-name checks. If the interface is actually a top-level Firestore model, declare a matching `firestoreModelIdentity` and tag it `@dbxModel` instead.",
+    seeAlso: [
+      {
+        kind: "artifact",
+        target: "firestore-model"
+      }
+    ]
+  },
+  {
+    code: "MODEL_SUBOBJECT_PARENT_NOT_TAGGED",
+    source: "dbx_model_validate",
+    severity: "warning",
+    title: "A `@dbxModelSubObject` interface extends a parent interface that is not itself tagged with `@dbxModel` or `@dbxModelSubObject`. The parent's persisted fields flow through the sub-object's converter but never reach the workspace's `@dbxModelVariable` long-name checks. Whether the agent acts depends on whether the parent is owned by this package, but the validator surfaces both classifications so the consuming agent (or developer) can make an informed call",
+    whatItFlags: "A `@dbxModelSubObject` interface extends a parent interface that is not itself tagged with `@dbxModel` or `@dbxModelSubObject`. The parent's persisted fields flow through the sub-object's converter but never reach the workspace's `@dbxModelVariable` long-name checks. Whether the agent acts depends on whether the parent is owned by this package, but the validator surfaces both classifications so the consuming agent (or developer) can make an informed call.",
+    whenItApplies: "Every `@dbxModelSubObject` interface whose `extends` heritage names an untagged parent. The parent is classified `in-package` when its declaration is found in the validated source set, otherwise `external`. Anchored at the sub-object interface line so the caller sees both the child and the parent in one place.",
+    whenItDoesNotApply: "Parents already tagged with `@dbxModel` or `@dbxModelSubObject`; parents whose names appear in `modelValidate.ignoredExternalParents` (suppresses external-only warnings \u2014 in-package parents are never suppressed). Generic parameters, inline types, and TS utility wrappers (`Partial<T>`, `Pick<T, K>`, `Omit<T, K>`, `Readonly<T>`, `MaybeMap<T>`) are unwrapped to the underlying parent name before resolution.",
+    canonicalFix: "In-package parent: add `@dbxModelSubObject` to the parent interface's JSDoc and tag each persisted field with `@dbxModelVariable <longName>`. Alternative: redeclare the inherited fields directly on the child with their own JSDoc + tag (useful when the parent is a shared shape that shouldn't commit to a single longName). External parent: redeclare the inherited fields on the child with `@dbxModelVariable <longName>` tags when surface long-names are needed, or add the parent name to `modelValidate.ignoredExternalParents` in `dbx-mcp.config.json` when the inherited fields are framework plumbing (e.g. `IndexRef.i`, `DateRange.start/end`).",
+    seeAlso: [
+      {
+        kind: "artifact",
+        target: "firestore-model"
+      }
+    ]
+  },
+  {
+    code: "MODEL_SUBOBJECT_TAG_CONFLICT",
+    source: "dbx_model_validate",
+    severity: "error",
+    title: "An interface declaration carries both `@dbxModel` and `@dbxModelSubObject` JSDoc tags. The two tags model mutually exclusive concepts \u2014 `@dbxModel` marks a top-level Firestore model registered in the catalog via `firestoreModelIdentity`, while `@dbxModelSubObject` marks an embedded sub-object interface persisted only as part of a parent model's converter \u2014 so an interface must carry at most one",
+    whatItFlags: "An interface declaration carries both `@dbxModel` and `@dbxModelSubObject` JSDoc tags. The two tags model mutually exclusive concepts \u2014 `@dbxModel` marks a top-level Firestore model registered in the catalog via `firestoreModelIdentity`, while `@dbxModelSubObject` marks an embedded sub-object interface persisted only as part of a parent model's converter \u2014 so an interface must carry at most one.",
+    whenItApplies: "Any interface JSDoc block where both `@dbxModel` and `@dbxModelSubObject` are present.",
+    whenItDoesNotApply: "Interfaces carrying only one of the two tags (or neither).",
+    canonicalFix: "Remove whichever tag does not describe the interface. If the interface has a matching `firestoreModelIdentity` call, keep `@dbxModel`; if it is only embedded inside another model via `firestoreSubObject<T>()`, keep `@dbxModelSubObject`."
+  },
   {
     code: "SUB_MISSING_COLLECTION_FACTORY_FN",
     source: "dbx_model_validate",
@@ -16975,33 +17471,34 @@ function formatSeeAlso(ref) {
   return `Doc: ${ref.target}${tail}`;
 }
 
-// packages/dbx-components-mcp/src/tools/model-validate/types.ts
-var MAX_FIELD_NAME_LENGTH = 5;
-var ROOT_MODEL_ORDER = ["identity", "interface", "rolesType", "documentClass", "converter", "referenceFn", "collectionType", "collectionFn"];
-var SUBCOLLECTION_MODEL_ORDER = ["identity", "interface", "rolesType", "documentClass", "converter", "referenceFn", "collectionType", "collectionFactoryType", "collectionFn", "referenceGroupFn", "collectionGroupType", "collectionGroupFn"];
-
 // packages/dbx-components-mcp/src/tools/model-validate/rules.ts
-function runRules(file, options) {
+function runRules(file, options, context) {
   const violations = [];
-  if (file.models.length === 0) {
-    return violations;
-  }
-  checkFileLevel(file, violations);
-  for (const model of file.models) {
-    checkIdentity(file, model, violations);
-    checkCoreDeclarations(file, model, violations);
-    if (model.variant === "subcollection") {
-      checkSubcollectionExtras(file, model, violations);
-    }
-    checkDeclarationOrder(file, model, violations);
-  }
-  checkFieldNameLengths(file, violations, options);
+  const hasModels = file.models.length > 0;
+  if (hasModels) {
+    checkFileLevel(file, violations);
+    for (const model of file.models) {
+      checkIdentity(file, model, violations);
+      checkCoreDeclarations(file, model, violations);
+      if (model.variant === "subcollection") {
+        checkSubcollectionExtras(file, model, violations);
+      }
+      checkDeclarationOrder(file, model, violations);
+    }
+  }
+  checkFieldNameLengths(file, violations, options, { restrictToTaggedInterfaces: !hasModels });
+  checkSubObjectInterfaceTags(file, violations);
+  checkSubObjectFactoryCallSites(file, violations, context);
+  checkSubObjectParentNotTagged(file, violations, context, options);
   return violations;
 }
-function checkFieldNameLengths(file, violations, options) {
+function checkFieldNameLengths(file, violations, options, scope) {
   const limit = options?.maxFieldNameLength ?? MAX_FIELD_NAME_LENGTH;
   const ignored = options?.ignoredFieldNames;
   for (const iface of file.dataInterfaces) {
+    if (scope.restrictToTaggedInterfaces && !(iface.dbxModelTag || iface.dbxModelSubObjectTag)) {
+      continue;
+    }
     for (const field of iface.fields) {
       if (ignored?.has(field.name)) {
         continue;
@@ -17019,11 +17516,14 @@ function checkFieldNameLengths(file, violations, options) {
       });
     }
   }
-  checkFieldJsDocs(file, violations, options);
+  checkFieldJsDocs(file, violations, options, scope);
 }
-function checkFieldJsDocs(file, violations, options) {
+function checkFieldJsDocs(file, violations, options, scope) {
   const ignored = options?.ignoredFieldNames;
   for (const iface of file.dataInterfaces) {
+    if (scope.restrictToTaggedInterfaces && !(iface.dbxModelTag || iface.dbxModelSubObjectTag)) {
+      continue;
+    }
     for (const field of iface.fields) {
       if (!field.jsDocFirstLine) {
         pushViolation(violations, {
@@ -17035,7 +17535,8 @@ function checkFieldJsDocs(file, violations, options) {
           model: iface.name
         });
       }
-      if (iface.dbxModelTag && field.dbxModelVariableTag === void 0) {
+      const fieldRulesApply = iface.dbxModelTag || iface.dbxModelSubObjectTag;
+      if (fieldRulesApply && field.dbxModelVariableTag === void 0) {
         pushViolation(violations, {
           code: "MODEL_FIELD_MISSING_VARIABLE_TAG",
           severity: "warning",
@@ -17045,7 +17546,7 @@ function checkFieldJsDocs(file, violations, options) {
           model: iface.name
         });
       }
-      if (iface.dbxModelTag && field.dbxModelVariableTag !== void 0 && field.dbxModelVariableTag === field.name && !ignored?.has(field.name)) {
+      if (fieldRulesApply && field.dbxModelVariableTag !== void 0 && field.dbxModelVariableTag === field.name && !ignored?.has(field.name)) {
         pushViolation(violations, {
           code: "MODEL_FIELD_LONG_NAME_EQUALS_NAME",
           severity: "warning",
@@ -17058,6 +17559,95 @@ function checkFieldJsDocs(file, violations, options) {
     }
   }
 }
+function checkSubObjectInterfaceTags(file, violations) {
+  for (const iface of file.dataInterfaces) {
+    if (iface.dbxModelTag && iface.dbxModelSubObjectTag) {
+      pushViolation(violations, {
+        code: "MODEL_SUBOBJECT_TAG_CONFLICT",
+        message: `Interface \`${iface.name}\` carries both \`@dbxModel\` and \`@dbxModelSubObject\`. Use only \`@dbxModel\` for top-level Firestore models; use \`@dbxModelSubObject\` only for embedded sub-objects without a \`firestoreModelIdentity\`.`,
+        file: file.name,
+        line: iface.line,
+        model: iface.name
+      });
+    }
+  }
+}
+function checkSubObjectFactoryCallSites(file, violations, context) {
+  if (!context) {
+    return;
+  }
+  if (file.subObjectCalls.length === 0) {
+    return;
+  }
+  for (const call of file.subObjectCalls) {
+    const entry = context.interfacesByName.get(call.typeArgName);
+    if (!entry) {
+      continue;
+    }
+    const { iface, file: declFile } = entry;
+    if (iface.dbxModelTag || iface.dbxModelSubObjectTag) {
+      continue;
+    }
+    if (context.emittedSubObjectInterfaces.has(call.typeArgName)) {
+      continue;
+    }
+    context.emittedSubObjectInterfaces.add(call.typeArgName);
+    pushViolation(violations, {
+      code: "MODEL_SUBOBJECT_NOT_TAGGED",
+      severity: "warning",
+      message: `Interface \`${iface.name}\` is referenced by \`${call.factoryName}<${iface.name}>(...)\` at ${file.name}:${call.line} but carries neither \`@dbxModel\` nor \`@dbxModelSubObject\`. Tag the interface with \`@dbxModelSubObject\` so its persisted fields are subject to the same \`@dbxModelVariable\` long-name checks as a top-level model.`,
+      file: declFile,
+      line: iface.line,
+      model: iface.name
+    });
+  }
+}
+function checkSubObjectParentNotTagged(file, violations, context, options) {
+  if (!context) {
+    return;
+  }
+  const ignoredExternal = options?.ignoredExternalParents;
+  for (const iface of file.dataInterfaces) {
+    if (!iface.dbxModelSubObjectTag) {
+      continue;
+    }
+    for (const parentName of iface.extendsNames) {
+      const dedupKey = `${iface.name}<-${parentName}`;
+      if (context.emittedSubObjectInterfaces.has(dedupKey)) {
+        continue;
+      }
+      const entry = context.interfacesByName.get(parentName);
+      if (entry) {
+        const parent = entry.iface;
+        if (parent.dbxModelTag || parent.dbxModelSubObjectTag) {
+          continue;
+        }
+        context.emittedSubObjectInterfaces.add(dedupKey);
+        pushViolation(violations, {
+          code: "MODEL_SUBOBJECT_PARENT_NOT_TAGGED",
+          severity: "warning",
+          message: `Interface \`${parentName}\` is extended by \`@dbxModelSubObject\` \`${iface.name}\`. \`${parentName}\` is declared in the same package (${entry.file}) and its fields are persisted via \`${iface.name}\`'s converter but are not validated. Fix (preferred): add \`@dbxModelSubObject\` to \`${parentName}\`'s JSDoc and tag each persisted field with \`@dbxModelVariable <longName>\`. Alternative: redeclare the inherited fields directly on \`${iface.name}\` with their own JSDoc + tag (useful when \`${parentName}\` is a shared shape that you do not want to commit to a single longName).`,
+          file: entry.file,
+          line: parent.line,
+          model: parentName
+        });
+      } else {
+        if (ignoredExternal?.has(parentName)) {
+          continue;
+        }
+        context.emittedSubObjectInterfaces.add(dedupKey);
+        pushViolation(violations, {
+          code: "MODEL_SUBOBJECT_PARENT_NOT_TAGGED",
+          severity: "warning",
+          message: `Interface \`${parentName}\` is extended by \`@dbxModelSubObject\` \`${iface.name}\`, but \`${parentName}\` is declared outside this package (unresolved in the validated source set). Its persisted fields cannot be tagged from here. Decide: (1) if the inherited fields need explicit longNames in this catalog, redeclare them on \`${iface.name}\` with a JSDoc block carrying \`@dbxModelVariable <longName>\` (the redeclaration is structurally compatible \u2014 TypeScript treats it as a field narrowing, not a new property); (2) if the inherited fields are framework plumbing (e.g. \`IndexRef.i\`, \`DateRange.start/end\`) and surface longNames are not needed, suppress this specific warning by adding \`${parentName}\` to \`modelValidate.ignoredExternalParents\` in \`dbx-mcp.config.json\`.`,
+          file: file.name,
+          line: iface.line,
+          model: iface.name
+        });
+      }
+    }
+  }
+}
 function checkFileLevel(file, violations) {
   const { groupInterface, groupTypes, firstModelLine, models, name } = file;
   if (groupInterface) {
@@ -17759,10 +18349,15 @@ function validateFirebaseModelSources(sources, options) {
   let modelsChecked = 0;
   let errorCount = 0;
   let warningCount = 0;
+  const extracteds = [];
   for (const source of sources) {
     const extracted = extractFile(source);
+    extracteds.push(extracted);
     modelsChecked += extracted.models.length;
-    const fileViolations = runRules(extracted, options);
+  }
+  const context = buildCrossFileRuleContext(extracteds);
+  for (const extracted of extracteds) {
+    const fileViolations = runRules(extracted, options, context);
     for (const v of fileViolations) {
       violations.push(v);
       if (v.severity === "error") {
@@ -17781,6 +18376,22 @@ function validateFirebaseModelSources(sources, options) {
   };
   return result;
 }
+function buildCrossFileRuleContext(extracteds) {
+  const interfacesByName = /* @__PURE__ */ new Map();
+  for (const file of extracteds) {
+    for (const iface of file.dataInterfaces) {
+      if (interfacesByName.has(iface.name)) {
+        continue;
+      }
+      interfacesByName.set(iface.name, { file: file.name, iface });
+    }
+  }
+  const context = {
+    interfacesByName,
+    emittedSubObjectInterfaces: /* @__PURE__ */ new Set()
+  };
+  return context;
+}
 
 // packages/dbx-components-mcp/src/tools/model-validate.tool.ts
 var DBX_MODEL_VALIDATE_TOOL = {
@@ -17835,7 +18446,7 @@ var modelValidateTool = /* @__PURE__ */ createModelValidateTool();
 var runModelValidate = modelValidateTool.run;
 
 // packages/dbx-components-mcp/src/tools/model-validate-api/extract.ts
-import { Node as Node12, Project as Project5, SyntaxKind as SyntaxKind5 } from "ts-morph";
+import { Node as Node13, Project as Project5, SyntaxKind as SyntaxKind5 } from "ts-morph";
 function extractFile2(source) {
   const project = new Project5({ useInMemoryFileSystem: true, skipAddingFilesFromTsConfig: true });
   const sourceFile = project.createSourceFile(source.name, source.text, { overwrite: true });
@@ -18001,7 +18612,7 @@ function findCrudConfigType(sourceFile) {
       continue;
     }
     const typeNode = alias.getTypeNode();
-    const summary = typeNode && Node12.isTypeLiteral(typeNode) ? summarizeCrudConfigType(typeNode) : { keys: [], nonNullKeys: [], bareLeafParamsNames: [] };
+    const summary = typeNode && Node13.isTypeLiteral(typeNode) ? summarizeCrudConfigType(typeNode) : { keys: [], nonNullKeys: [], bareLeafParamsNames: [] };
     const result = {
       name: alias.getName(),
       exported: alias.isExported(),
@@ -18015,14 +18626,14 @@ function findCrudConfigType(sourceFile) {
   return void 0;
 }
 function summarizeCrudConfigType(typeLiteral) {
-  if (!Node12.isTypeLiteral(typeLiteral)) {
+  if (!Node13.isTypeLiteral(typeLiteral)) {
     return { keys: [], nonNullKeys: [], bareLeafParamsNames: [] };
   }
   const keys = [];
   const nonNullKeys = [];
   const bareLeafParamsNames = [];
   for (const member of typeLiteral.getMembers()) {
-    if (!Node12.isPropertySignature(member)) {
+    if (!Node13.isPropertySignature(member)) {
       continue;
     }
     const name = member.getName();
@@ -18040,18 +18651,18 @@ function summarizeCrudConfigType(typeLiteral) {
   return { keys, nonNullKeys, bareLeafParamsNames };
 }
 function isNullLiteralType(node) {
-  if (Node12.isLiteralTypeNode(node)) {
+  if (Node13.isLiteralTypeNode(node)) {
     const literal = node.getLiteral();
-    if (Node12.isNullLiteral(literal)) {
+    if (Node13.isNullLiteral(literal)) {
       return true;
     }
   }
   return false;
 }
 function collectBareParamsLeaves(node, out) {
-  if (Node12.isTypeLiteral(node)) {
+  if (Node13.isTypeLiteral(node)) {
     for (const member of node.getMembers()) {
-      if (!Node12.isPropertySignature(member)) {
+      if (!Node13.isPropertySignature(member)) {
         continue;
       }
       const valueNode = member.getTypeNode();
@@ -18061,10 +18672,10 @@ function collectBareParamsLeaves(node, out) {
     }
     return;
   }
-  if (Node12.isTupleTypeNode(node)) {
+  if (Node13.isTupleTypeNode(node)) {
     return;
   }
-  if (Node12.isTypeReference(node)) {
+  if (Node13.isTypeReference(node)) {
     const name = node.getTypeName().getText();
     if (name.endsWith("Params")) {
       out.push(name);
@@ -18081,12 +18692,12 @@ function findCrudConfigConst(sourceFile) {
       const typeNode = decl.getTypeNode();
       const initializer = decl.getInitializer();
       const runtimeKeys = [];
-      if (initializer && Node12.isAsExpression(initializer)) {
+      if (initializer && Node13.isAsExpression(initializer)) {
         const inner = initializer.getExpression();
-        if (Node12.isObjectLiteralExpression(inner)) {
+        if (Node13.isObjectLiteralExpression(inner)) {
           runtimeKeys.push(...collectObjectLiteralKeys(inner));
         }
-      } else if (initializer && Node12.isObjectLiteralExpression(initializer)) {
+      } else if (initializer && Node13.isObjectLiteralExpression(initializer)) {
         runtimeKeys.push(...collectObjectLiteralKeys(initializer));
       }
       const result = {
@@ -18104,7 +18715,7 @@ function findCrudConfigConst(sourceFile) {
 function collectObjectLiteralKeys(obj) {
   const out = [];
   for (const prop of obj.getProperties()) {
-    if (Node12.isPropertyAssignment(prop) || Node12.isShorthandPropertyAssignment(prop)) {
+    if (Node13.isPropertyAssignment(prop) || Node13.isShorthandPropertyAssignment(prop)) {
       out.push(prop.getName());
     }
   }
@@ -18120,7 +18731,7 @@ function findFunctionMap(sourceFile) {
       const initializer = decl.getInitializer();
       let callsFactory = false;
       const factoryArgs = [];
-      if (initializer && Node12.isCallExpression(initializer)) {
+      if (initializer && Node13.isCallExpression(initializer)) {
         const exprText = initializer.getExpression().getText();
         if (exprText === "callModelFirebaseFunctionMapFactory") {
           callsFactory = true;
@@ -18258,18 +18869,18 @@ function extractCastTargetName(node) {
     return void 0;
   }
   let current = node;
-  while (current && Node12.isAsExpression(current)) {
+  while (current && Node13.isAsExpression(current)) {
     const typeNode = current.getTypeNode();
     if (!typeNode) {
       break;
     }
-    if (Node12.isTypeReference(typeNode)) {
+    if (Node13.isTypeReference(typeNode)) {
       const refName = typeNode.getTypeName().getText();
       if (refName === "Type") {
         const args = typeNode.getTypeArguments();
         if (args.length === 1) {
           const arg = args[0];
-          if (Node12.isTypeReference(arg)) {
+          if (Node13.isTypeReference(arg)) {
             return arg.getTypeName().getText();
           }
           return arg.getText();
@@ -18288,7 +18899,7 @@ function extractValidatorProperties(initializer) {
   }
   const out = [];
   for (const prop of obj.getProperties()) {
-    if (!Node12.isPropertyAssignment(prop)) {
+    if (!Node13.isPropertyAssignment(prop)) {
       continue;
     }
     const propAssignment = prop;
@@ -18298,7 +18909,7 @@ function extractValidatorProperties(initializer) {
     const clean = optional ? stripped.slice(0, -1) : stripped;
     const valueNode = propAssignment.getInitializer();
     let hasClearable = false;
-    if (valueNode && Node12.isCallExpression(valueNode)) {
+    if (valueNode && Node13.isCallExpression(valueNode)) {
       const exprText = valueNode.getExpression().getText();
       if (exprText === "clearable") {
         hasClearable = true;
@@ -18310,25 +18921,25 @@ function extractValidatorProperties(initializer) {
 }
 function findArktypeObjectLiteral(initializer) {
   let current = initializer;
-  while (current && Node12.isAsExpression(current)) {
+  while (current && Node13.isAsExpression(current)) {
     current = current.getExpression();
   }
-  if (!current || !Node12.isCallExpression(current)) {
+  if (!current || !Node13.isCallExpression(current)) {
     return void 0;
   }
   const expr = current.getExpression();
-  if (Node12.isIdentifier(expr) && expr.getText() === "type") {
+  if (Node13.isIdentifier(expr) && expr.getText() === "type") {
     const args = current.getArguments();
     const arg = args[0];
-    if (arg && Node12.isObjectLiteralExpression(arg)) {
+    if (arg && Node13.isObjectLiteralExpression(arg)) {
       return arg;
     }
     return void 0;
   }
-  if (Node12.isPropertyAccessExpression(expr) && expr.getName() === "merge") {
+  if (Node13.isPropertyAccessExpression(expr) && expr.getName() === "merge") {
     const args = current.getArguments();
     const arg = args[0];
-    if (arg && Node12.isObjectLiteralExpression(arg)) {
+    if (arg && Node13.isObjectLiteralExpression(arg)) {
       return arg;
     }
   }
@@ -19013,7 +19624,7 @@ import { readdir as readdir2, readFile as readFile4, stat as stat4 } from "node:
 import { join as join4, relative as relative4, sep as sep5 } from "node:path";
 
 // packages/dbx-cli/manifest-extract/src/lib/extract-crud.ts
-import { Node as Node13, Project as Project6 } from "ts-morph";
+import { Node as Node14, Project as Project6 } from "ts-morph";
 var SUPPORTED_VERBS = /* @__PURE__ */ new Set(["create", "read", "update", "delete", "query"]);
 function extractCrudEntries(source) {
   const project = new Project6({ useInMemoryFileSystem: true, skipAddingFilesFromTsConfig: true });
@@ -19039,9 +19650,9 @@ function extractCrudEntries(source) {
   };
   if (crudConfigType) {
     const literal = crudConfigType.getTypeNode();
-    if (literal && Node13.isTypeLiteral(literal)) {
+    if (literal && Node14.isTypeLiteral(literal)) {
       for (const member of literal.getMembers()) {
-        if (!Node13.isPropertySignature(member)) {
+        if (!Node14.isPropertySignature(member)) {
           continue;
         }
         const modelName = member.getName();
@@ -19053,9 +19664,9 @@ function extractCrudEntries(source) {
         if (isNullLiteralType2(valueNode)) {
           continue;
         }
-        if (Node13.isTypeLiteral(valueNode)) {
+        if (Node14.isTypeLiteral(valueNode)) {
           for (const verbMember of valueNode.getMembers()) {
-            if (!Node13.isPropertySignature(verbMember)) {
+            if (!Node14.isPropertySignature(verbMember)) {
               continue;
             }
             const verbName = verbMember.getName();
@@ -19076,9 +19687,9 @@ function extractCrudEntries(source) {
   const functionTypeMap = findTypeAliasByEnding(sourceFile, "FunctionTypeMap");
   if (functionTypeMap) {
     const literal = functionTypeMap.getTypeNode();
-    if (literal && Node13.isTypeLiteral(literal)) {
+    if (literal && Node14.isTypeLiteral(literal)) {
       for (const member of literal.getMembers()) {
-        if (!Node13.isPropertySignature(member)) {
+        if (!Node14.isPropertySignature(member)) {
           continue;
         }
         const key = member.getName();
@@ -19146,9 +19757,9 @@ function inferGroupName2(sourceFile) {
   return void 0;
 }
 function isNullLiteralType2(node) {
-  if (Node13.isLiteralTypeNode(node)) {
+  if (Node14.isLiteralTypeNode(node)) {
     const literal = node.getLiteral();
-    if (Node13.isNullLiteral(literal)) {
+    if (Node14.isNullLiteral(literal)) {
       return true;
     }
   }
@@ -19156,9 +19767,9 @@ function isNullLiteralType2(node) {
 }
 function collectVerbEntries(input) {
   const { modelName, verb, valueNode, entries, fallbackDescription, resolveTypeDocs } = input;
-  if (Node13.isTypeLiteral(valueNode)) {
+  if (Node14.isTypeLiteral(valueNode)) {
     for (const specMember of valueNode.getMembers()) {
-      if (!Node13.isPropertySignature(specMember)) {
+      if (!Node14.isPropertySignature(specMember)) {
         continue;
       }
       const specifier = specMember.getName();
@@ -19200,7 +19811,7 @@ function collectVerbEntries(input) {
   });
 }
 function readTupleParamsResult(node) {
-  if (!Node13.isTupleTypeNode(node)) {
+  if (!Node14.isTupleTypeNode(node)) {
     return void 0;
   }
   const elements = node.getElements();
@@ -19219,7 +19830,7 @@ function readBareParams(node) {
   return { params, result: void 0 };
 }
 function typeNodeName(node) {
-  if (Node13.isTypeReference(node)) {
+  if (Node14.isTypeReference(node)) {
     return node.getTypeName().getText();
   }
   const text = node.getText().trim();
@@ -20058,7 +20669,7 @@ async function collectApiFiles2(rootAbs) {
 // packages/dbx-components-mcp/src/tools/model-api-validate-app/extract-handlers.ts
 import { readFile as readFile8 } from "node:fs/promises";
 import { join as join8 } from "node:path";
-import { Node as Node14, Project as Project8 } from "ts-morph";
+import { Node as Node15, Project as Project8 } from "ts-morph";
 var HANDLER_MAP_REL = "src/app/function/model/crud.functions.ts";
 var VERB_TOKENS = [
   { token: "Create", verb: "create" },
@@ -20086,7 +20697,7 @@ async function extractHandlerEntries(apiAbs, apiDir) {
       const verb = matchVerbFromConstName(name);
       if (!verb) continue;
       const initializer = decl.getInitializer();
-      if (!initializer || !Node14.isObjectLiteralExpression(initializer)) continue;
+      if (!initializer || !Node15.isObjectLiteralExpression(initializer)) continue;
       verbsFound.push(verb);
       collectVerbMap({ verb, mapLiteral: initializer, sourceFileRel, entries });
     }
@@ -20104,7 +20715,7 @@ function matchVerbFromConstName(name) {
 function collectVerbMap(input) {
   const { verb, mapLiteral, sourceFileRel, entries } = input;
   for (const prop of mapLiteral.getProperties()) {
-    if (!Node14.isPropertyAssignment(prop)) continue;
+    if (!Node15.isPropertyAssignment(prop)) continue;
     const model = prop.getName();
     const value = prop.getInitializer();
     if (!value) continue;
@@ -20123,25 +20734,25 @@ function collectVerbMap(input) {
   }
 }
 function readSpecifierHandler(node) {
-  if (!Node14.isCallExpression(node)) return void 0;
+  if (!Node15.isCallExpression(node)) return void 0;
   const expr = node.getExpression();
   if (!expr.getText().endsWith("onCallSpecifierHandler")) return void 0;
   const args = node.getArguments();
   if (args.length === 0) return void 0;
   const firstArg = args[0];
-  if (!Node14.isObjectLiteralExpression(firstArg)) return void 0;
+  if (!Node15.isObjectLiteralExpression(firstArg)) return void 0;
   const out = /* @__PURE__ */ new Map();
   for (const prop of firstArg.getProperties()) {
-    if (!Node14.isPropertyAssignment(prop) && !Node14.isShorthandPropertyAssignment(prop)) continue;
+    if (!Node15.isPropertyAssignment(prop) && !Node15.isShorthandPropertyAssignment(prop)) continue;
     const specifier = prop.getName();
-    const handlerName = readBareHandlerName(Node14.isPropertyAssignment(prop) ? prop.getInitializerOrThrow() : prop) ?? "(unresolved)";
+    const handlerName = readBareHandlerName(Node15.isPropertyAssignment(prop) ? prop.getInitializerOrThrow() : prop) ?? "(unresolved)";
     out.set(specifier, handlerName);
   }
   return out;
 }
 function readBareHandlerName(node) {
-  if (Node14.isIdentifier(node)) return node.getText();
-  if (Node14.isShorthandPropertyAssignment(node)) return node.getName();
+  if (Node15.isIdentifier(node)) return node.getText();
+  if (Node15.isShorthandPropertyAssignment(node)) return node.getName();
   const text = node.getText().split(/\s|\(/)[0];
   if (/^[A-Za-z_]\w*$/.test(text)) return text;
   return void 0;
@@ -20639,7 +21250,7 @@ async function readModelSources(folderPath, files) {
 }
 
 // packages/dbx-components-mcp/src/tools/model-validate-folder/rules.ts
-function runRules3(inspection) {
+function runRules3(inspection, options) {
   const violations = [];
   if (inspection.status === "not-found") {
     pushViolation3(violations, {
@@ -20672,16 +21283,16 @@ function runRules3(inspection) {
   }
   checkRequiredFiles(inspection, violations);
   checkStrayFiles(inspection, violations);
-  checkSourceContents(inspection, violations);
+  checkSourceContents(inspection, violations, options);
   return violations;
 }
-function checkSourceContents(inspection, violations) {
+function checkSourceContents(inspection, violations, options) {
   const sources = inspection.sources;
   if (!sources || sources.length === 0) {
     return;
   }
   const validatorSources = sources.map((s) => ({ name: s.filename, text: s.text }));
-  const result = validateFirebaseModelSources(validatorSources);
+  const result = validateFirebaseModelSources(validatorSources, options);
   for (const v of result.violations) {
     pushViolation3(violations, {
       code: v.code,
@@ -20742,8 +21353,8 @@ function pushViolation3(buffer, violation) {
 }
 
 // packages/dbx-components-mcp/src/tools/model-validate-folder/validate.ts
-function validateModelFolders(inspections) {
-  return aggregateFolderRules({ inspections, runRules: runRules3 });
+function validateModelFolders(inspections, options) {
+  return aggregateFolderRules({ inspections, runRules: (inspection) => runRules3(inspection, options) });
 }
 
 // packages/dbx-components-mcp/src/tools/model-validate-folder.tool.ts
@@ -20777,12 +21388,16 @@ var DBX_MODEL_VALIDATE_FOLDER_TOOL = {
     }
   }
 };
-var modelValidateFolderTool = createFolderValidateTool({
-  definition: DBX_MODEL_VALIDATE_FOLDER_TOOL,
-  inspectFolder,
-  validate: validateModelFolders,
-  format: formatResult3
-});
+// @__NO_SIDE_EFFECTS__
+function createModelValidateFolderTool(options = {}) {
+  const { ruleOptions } = options;
+  return createFolderValidateTool({
+    definition: DBX_MODEL_VALIDATE_FOLDER_TOOL,
+    inspectFolder,
+    validate: (inspections) => validateModelFolders(inspections, ruleOptions),
+    format: formatResult3
+  });
+}
 
 // packages/dbx-components-mcp/src/tools/model-store-scaffold.tool.ts
 import { type as type41 } from "arktype";
@@ -21343,7 +21958,7 @@ function paramsHasFixtureDependencies(params) {
 }
 
 // packages/dbx-components-mcp/src/tools/model-fixture-shared/extract.ts
-import { Node as Node15, Project as Project9, SyntaxKind as SyntaxKind7 } from "ts-morph";
+import { Node as Node16, Project as Project9, SyntaxKind as SyntaxKind7 } from "ts-morph";
 
 // packages/dbx-components-mcp/src/tools/model-fixture-shared/framework-fixtures.ts
 var KNOWN_NON_MODEL_FIXTURE_FAMILIES = [
@@ -21455,7 +22070,7 @@ function extendsByName(cls, baseName) {
   const extendsClause = cls.getExtends();
   if (!extendsClause) return false;
   const expr = extendsClause.getExpression();
-  if (Node15.isIdentifier(expr)) {
+  if (Node16.isIdentifier(expr)) {
     return expr.getText() === baseName;
   }
   return extendsClause.getText().startsWith(baseName);
@@ -21583,14 +22198,14 @@ function readContextFactory(decl) {
   const initializer = decl.getInitializer();
   if (!initializer) return void 0;
   let bodyExpr;
-  if (Node15.isArrowFunction(initializer) || Node15.isFunctionExpression(initializer)) {
+  if (Node16.isArrowFunction(initializer) || Node16.isFunctionExpression(initializer)) {
     bodyExpr = readSingleReturnExpression(initializer);
   } else {
     bodyExpr = initializer;
   }
-  if (!bodyExpr || !Node15.isCallExpression(bodyExpr)) return void 0;
+  if (!bodyExpr || !Node16.isCallExpression(bodyExpr)) return void 0;
   const callee = bodyExpr.getExpression();
-  if (!Node15.isIdentifier(callee)) return void 0;
+  if (!Node16.isIdentifier(callee)) return void 0;
   const calleeName = callee.getText();
   let family;
   if (calleeName !== MODEL_FACTORY_NAME) {
@@ -21605,9 +22220,9 @@ function readContextFactory(decl) {
   let parentFixtureFieldFromGetCollection;
   if (args.length > 0) {
     const first = args[0];
-    if (Node15.isObjectLiteralExpression(first)) {
+    if (Node16.isObjectLiteralExpression(first)) {
       const getCollection = first.getProperty("getCollection");
-      if (getCollection && Node15.isPropertyAssignment(getCollection)) {
+      if (getCollection && Node16.isPropertyAssignment(getCollection)) {
         const fnInit = getCollection.getInitializer();
         const arity = readArrowParameterCount(fnInit);
         if (arity >= 2) {
@@ -21658,7 +22273,7 @@ function familyFromExtends(cls) {
   if (!ext) return void 0;
   const expr = ext.getExpression();
   let baseName;
-  if (Node15.isIdentifier(expr)) {
+  if (Node16.isIdentifier(expr)) {
     baseName = expr.getText();
   } else {
     const text = ext.getText();
@@ -21671,9 +22286,9 @@ function familyFromExtends(cls) {
 function readSingleReturnExpression(fn) {
   const body = fn.getBody();
   if (!body) return void 0;
-  if (Node15.isBlock(body)) {
+  if (Node16.isBlock(body)) {
     for (const stmt of body.getStatements()) {
-      if (Node15.isReturnStatement(stmt)) {
+      if (Node16.isReturnStatement(stmt)) {
         return stmt.getExpression();
       }
     }
@@ -21683,19 +22298,19 @@ function readSingleReturnExpression(fn) {
 }
 function readArrowParameterCount(fn) {
   if (!fn) return 0;
-  if (Node15.isArrowFunction(fn) || Node15.isFunctionExpression(fn) || Node15.isFunctionDeclaration(fn) || Node15.isMethodDeclaration(fn)) {
+  if (Node16.isArrowFunction(fn) || Node16.isFunctionExpression(fn) || Node16.isFunctionDeclaration(fn) || Node16.isMethodDeclaration(fn)) {
     return fn.getParameters().length;
   }
   return 0;
 }
 function readParamsAccessFieldName(fn) {
   if (!fn) return void 0;
-  if (!Node15.isArrowFunction(fn) && !Node15.isFunctionExpression(fn)) return void 0;
+  if (!Node16.isArrowFunction(fn) && !Node16.isFunctionExpression(fn)) return void 0;
   const body = fn.getBody();
   if (!body) return void 0;
   for (const access2 of body.getDescendantsOfKind(SyntaxKind7.PropertyAccessExpression)) {
     const expr = access2.getExpression();
-    if (Node15.isIdentifier(expr) && expr.getText() === "params") {
+    if (Node16.isIdentifier(expr) && expr.getText() === "params") {
       return access2.getName();
     }
   }
@@ -21736,9 +22351,9 @@ function collectSingletonsByFactory(sourceFile) {
   for (const stmt of sourceFile.getVariableStatements()) {
     for (const decl of stmt.getDeclarations()) {
       const init = decl.getInitializer();
-      if (!init || !Node15.isCallExpression(init)) continue;
+      if (!init || !Node16.isCallExpression(init)) continue;
       const callee = init.getExpression();
-      if (!Node15.isIdentifier(callee)) continue;
+      if (!Node16.isIdentifier(callee)) continue;
       out.set(callee.getText(), decl.getName());
     }
   }
@@ -22986,7 +23601,7 @@ import { resolve as resolve32 } from "node:path";
 import { type as type47 } from "arktype";
 
 // packages/dbx-components-mcp/src/tools/model-test-shared/extract.ts
-import { Node as Node16, Project as Project11, SyntaxKind as SyntaxKind8 } from "ts-morph";
+import { Node as Node17, Project as Project11, SyntaxKind as SyntaxKind8 } from "ts-morph";
 var SPEC_FILE_VIRTUAL_PATH = "__spec__/spec.ts";
 var FIXTURE_CONTEXT_SUFFIX = "Context";
 var FIXTURE_FACTORY_SUFFIX = "ContextFactory";
@@ -23007,9 +23622,9 @@ function extractSpecTreeFromText(input) {
   const counts = { describe: 0, it: 0, fixture: 0 };
   const rootChildren = [];
   for (const stmt of sourceFile.getStatements()) {
-    if (!Node16.isExpressionStatement(stmt)) continue;
+    if (!Node17.isExpressionStatement(stmt)) continue;
     const expr = stmt.getExpression();
-    if (!Node16.isCallExpression(expr)) continue;
+    if (!Node17.isCallExpression(expr)) continue;
     const node = walkCall(expr, { prefix, knownFixtureNames, helperNames, counts });
     if (node !== void 0) {
       rootChildren.push(node);
@@ -23175,7 +23790,7 @@ function fixtureNode(input) {
   const { call, calleeName, ctx, line, endLine } = input;
   const args = call.getArguments();
   const argsObject = args[0];
-  const parentVars = Node16.isObjectLiteralExpression(argsObject) ? readParentVars(argsObject) : [];
+  const parentVars = Node17.isObjectLiteralExpression(argsObject) ? readParentVars(argsObject) : [];
   const callback = findCallback(call);
   const varName = callback === void 0 ? void 0 : readCallbackVarName(callback);
   const model = stripFixturePrefix(calleeName, ctx.prefix);
@@ -23213,11 +23828,11 @@ function stripFixturePrefix(name, prefix) {
 }
 function readTitle(arg) {
   if (arg === void 0) return { title: void 0, titleIsTemplate: false };
-  if (Node16.isStringLiteral(arg) || Node16.isNoSubstitutionTemplateLiteral(arg)) {
+  if (Node17.isStringLiteral(arg) || Node17.isNoSubstitutionTemplateLiteral(arg)) {
     const result2 = { title: arg.getLiteralText(), titleIsTemplate: false };
     return result2;
   }
-  if (Node16.isTemplateExpression(arg)) {
+  if (Node17.isTemplateExpression(arg)) {
     const result2 = { title: arg.getText(), titleIsTemplate: true };
     return result2;
   }
@@ -23228,7 +23843,7 @@ function findCallback(call) {
   const args = call.getArguments();
   for (let i = args.length - 1; i >= 0; i--) {
     const a = args[i];
-    if (Node16.isArrowFunction(a) || Node16.isFunctionExpression(a)) {
+    if (Node17.isArrowFunction(a) || Node17.isFunctionExpression(a)) {
       return a;
     }
   }
@@ -23239,7 +23854,7 @@ function readCallbackVarName(callback) {
   if (params.length === 0) return void 0;
   const first = params[0];
   const nameNode = first.getNameNode();
-  if (Node16.isIdentifier(nameNode)) {
+  if (Node17.isIdentifier(nameNode)) {
     return nameNode.getText();
   }
   return void 0;
@@ -23247,13 +23862,13 @@ function readCallbackVarName(callback) {
 function readParentVars(obj) {
   const out = [];
   for (const prop of obj.getProperties()) {
-    if (Node16.isShorthandPropertyAssignment(prop)) {
+    if (Node17.isShorthandPropertyAssignment(prop)) {
       out.push(prop.getName());
       continue;
     }
-    if (Node16.isPropertyAssignment(prop)) {
+    if (Node17.isPropertyAssignment(prop)) {
       const init = prop.getInitializer();
-      if (init !== void 0 && Node16.isIdentifier(init)) {
+      if (init !== void 0 && Node17.isIdentifier(init)) {
         out.push(init.getText());
       }
     }
@@ -23262,10 +23877,10 @@ function readParentVars(obj) {
 }
 function walkCallbackBody(callback, ctx) {
   const body = callback.getBody();
-  if (Node16.isBlock(body)) {
+  if (Node17.isBlock(body)) {
     return walkBlock(body, ctx);
   }
-  if (Node16.isCallExpression(body)) {
+  if (Node17.isCallExpression(body)) {
     const child = walkCall(body, ctx);
     return child === void 0 ? [] : [child];
   }
@@ -23274,9 +23889,9 @@ function walkCallbackBody(callback, ctx) {
 function walkBlock(block, ctx) {
   const children = [];
   for (const stmt of block.getStatements()) {
-    if (!Node16.isExpressionStatement(stmt)) continue;
+    if (!Node17.isExpressionStatement(stmt)) continue;
     const expr = stmt.getExpression();
-    if (!Node16.isCallExpression(expr)) continue;
+    if (!Node17.isCallExpression(expr)) continue;
     const child = walkCall(expr, ctx);
     if (child !== void 0) {
       children.push(child);
@@ -23286,7 +23901,7 @@ function walkBlock(block, ctx) {
 }
 function getCalleeName(call) {
   const expr = call.getExpression();
-  if (Node16.isIdentifier(expr)) return expr.getText();
+  if (Node17.isIdentifier(expr)) return expr.getText();
   return void 0;
 }
 function collectHelpers(sourceFile) {
@@ -23302,7 +23917,7 @@ function collectHelpers(sourceFile) {
     for (const decl of v.getDeclarations()) {
       const init = decl.getInitializer();
       if (init === void 0) continue;
-      if (!Node16.isArrowFunction(init) && !Node16.isFunctionExpression(init)) continue;
+      if (!Node17.isArrowFunction(init) && !Node17.isFunctionExpression(init)) continue;
       const usage = scanForDescribeOrIt(init);
       if (!usage.emitsDescribe && !usage.emitsIt) continue;
       out.push({ name: decl.getName(), line: decl.getStartLineNumber(), endLine: decl.getEndLineNumber(), emitsDescribe: usage.emitsDescribe, emitsIt: usage.emitsIt });
@@ -23316,7 +23931,7 @@ function scanForDescribeOrIt(node) {
     if (descendant.getKind() !== SyntaxKind8.CallExpression) return;
     const call = descendant;
     const expr = call.getExpression();
-    if (!Node16.isIdentifier(expr)) return;
+    if (!Node17.isIdentifier(expr)) return;
     const name = expr.getText();
     if (DESCRIBE_NAMES.has(name)) usage.emitsDescribe = true;
     if (isItName(name)) usage.emitsIt = true;
@@ -24089,10 +24704,10 @@ var modelHierarchyTool = {
 };
 
 // packages/dbx-components-mcp/src/tools/storagefile-m-validate-app/extract.ts
-import { Node as Node18, SyntaxKind as SyntaxKind10 } from "ts-morph";
+import { Node as Node19, SyntaxKind as SyntaxKind10 } from "ts-morph";
 
 // packages/dbx-components-mcp/src/tools/_validate/ast.ts
-import { Node as Node17, Project as Project12, SyntaxKind as SyntaxKind9 } from "ts-morph";
+import { Node as Node18, Project as Project12, SyntaxKind as SyntaxKind9 } from "ts-morph";
 var COMPONENT_VIRTUAL_PREFIX = "__component__/";
 var API_VIRTUAL_PREFIX = "__api__/";
 // @__NO_SIDE_EFFECTS__
@@ -24117,28 +24732,28 @@ function componentRelPath(sourceFile) {
 }
 function unwrapAsExpressions(node) {
   let current = node;
-  while (current && Node17.isAsExpression(current)) {
+  while (current && Node18.isAsExpression(current)) {
     current = current.getExpression();
   }
   return current;
 }
 function asObjectLiteral(node) {
   const inner = unwrapAsExpressions(node);
-  if (inner && Node17.isObjectLiteralExpression(inner)) {
+  if (inner && Node18.isObjectLiteralExpression(inner)) {
     return inner;
   }
   return void 0;
 }
 function asArrayLiteral(node) {
   const inner = unwrapAsExpressions(node);
-  if (inner && Node17.isArrayLiteralExpression(inner)) {
+  if (inner && Node18.isArrayLiteralExpression(inner)) {
     return inner;
   }
   return void 0;
 }
 function readStringLiteralInitializer(decl) {
   const initializer = unwrapAsExpressions(decl.getInitializer());
-  if (initializer && Node17.isStringLiteral(initializer)) {
+  if (initializer && Node18.isStringLiteral(initializer)) {
     return initializer.getLiteralText();
   }
   return void 0;
@@ -24150,37 +24765,37 @@ function typeAnnotationText(node) {
 function getPropertyInitializer(obj, name) {
   const prop = obj.getProperty(name);
   if (!prop) return void 0;
-  if (Node17.isPropertyAssignment(prop)) {
+  if (Node18.isPropertyAssignment(prop)) {
     return prop.getInitializer();
   }
-  if (Node17.isShorthandPropertyAssignment(prop)) {
+  if (Node18.isShorthandPropertyAssignment(prop)) {
     return prop.getNameNode();
   }
   return void 0;
 }
 function readStringProperty2(obj, name) {
   const init = unwrapAsExpressions(getPropertyInitializer(obj, name));
-  if (init && Node17.isStringLiteral(init)) {
+  if (init && Node18.isStringLiteral(init)) {
     return init.getLiteralText();
   }
   return void 0;
 }
 function readIdentifierProperty(obj, name) {
   const init = unwrapAsExpressions(getPropertyInitializer(obj, name));
-  if (init && Node17.isIdentifier(init)) {
+  if (init && Node18.isIdentifier(init)) {
     return init.getText();
   }
   return void 0;
 }
 function findReturnExpression(fn) {
-  if (!Node17.isArrowFunction(fn) && !Node17.isFunctionDeclaration(fn) && !Node17.isFunctionExpression(fn)) {
+  if (!Node18.isArrowFunction(fn) && !Node18.isFunctionDeclaration(fn) && !Node18.isFunctionExpression(fn)) {
     return void 0;
   }
   const body = fn.getBody();
   if (!body) return void 0;
-  if (Node17.isBlock(body)) {
+  if (Node18.isBlock(body)) {
     for (const stmt of body.getStatements()) {
-      if (Node17.isReturnStatement(stmt)) {
+      if (Node18.isReturnStatement(stmt)) {
         return stmt.getExpression();
       }
     }
@@ -24200,7 +24815,7 @@ function findLocalVariable(sf, name) {
   return void 0;
 }
 function collectTypeofReferences(node, out) {
-  if (Node17.isTypeQuery(node)) {
+  if (Node18.isTypeQuery(node)) {
     out.push(node.getExprName().getText());
     return;
   }
@@ -24402,7 +25017,7 @@ function buildApiFunctionIndex(sources) {
       for (const decl of stmt.getDeclarations()) {
         const initializer = unwrapAsExpressions(decl.getInitializer());
         if (!initializer) continue;
-        if (Node18.isArrowFunction(initializer) || Node18.isFunctionExpression(initializer)) {
+        if (Node19.isArrowFunction(initializer) || Node19.isFunctionExpression(initializer)) {
           map.set(decl.getName(), { node: initializer, sourceFile: sf });
         }
       }
@@ -24415,34 +25030,34 @@ function collectInitializerBindingsFromValue(options) {
   const { node, sf, index, resolved, unresolved, visited } = options;
   const inner = unwrapAsExpressions(node);
   if (!inner) return false;
-  if (Node18.isArrayLiteralExpression(inner)) {
+  if (Node19.isArrayLiteralExpression(inner)) {
     for (const el of inner.getElements()) {
-      if (Node18.isSpreadElement(el)) {
+      if (Node19.isSpreadElement(el)) {
         const spreadInner = el.getExpression();
-        if (Node18.isIdentifier(spreadInner)) {
+        if (Node19.isIdentifier(spreadInner)) {
           collectInitializerBindingsFromIdentifier({ name: spreadInner.getText(), sf, index, resolved, unresolved, visited });
-        } else if (Node18.isCallExpression(spreadInner)) {
+        } else if (Node19.isCallExpression(spreadInner)) {
           const callee = spreadInner.getExpression();
-          if (Node18.isIdentifier(callee)) {
+          if (Node19.isIdentifier(callee)) {
             collectInitializerBindingsFromIdentifier({ name: callee.getText(), sf, index, resolved, unresolved, visited });
           }
         }
         continue;
       }
       const elementInner = unwrapAsExpressions(el);
-      if (elementInner && Node18.isIdentifier(elementInner)) {
+      if (elementInner && Node19.isIdentifier(elementInner)) {
         resolved.push(elementInner.getText());
       }
     }
     return true;
   }
-  if (Node18.isCallExpression(inner)) {
+  if (Node19.isCallExpression(inner)) {
     const callee = inner.getExpression();
-    if (Node18.isIdentifier(callee)) {
+    if (Node19.isIdentifier(callee)) {
       return collectInitializerBindingsFromIdentifier({ name: callee.getText(), sf, index, resolved, unresolved, visited });
     }
   }
-  if (Node18.isIdentifier(inner)) {
+  if (Node19.isIdentifier(inner)) {
     return collectInitializerBindingsFromIdentifier({ name: inner.getText(), sf, index, resolved, unresolved, visited });
   }
   return false;
@@ -24481,15 +25096,15 @@ function collectUploadInitializerArray(options) {
   const { initializerArr, sf, index, direct, spreads, resolved, unresolved } = options;
   const visited = /* @__PURE__ */ new Set();
   for (const el of initializerArr.getElements()) {
-    if (Node18.isSpreadElement(el)) {
+    if (Node19.isSpreadElement(el)) {
       const inner2 = el.getExpression();
-      if (Node18.isIdentifier(inner2)) {
+      if (Node19.isIdentifier(inner2)) {
         const name = inner2.getText();
         spreads.push(name);
         collectInitializerBindingsFromIdentifier({ name, sf, index, resolved, unresolved, visited });
-      } else if (Node18.isCallExpression(inner2)) {
+      } else if (Node19.isCallExpression(inner2)) {
         const callee = inner2.getExpression();
-        if (Node18.isIdentifier(callee)) {
+        if (Node19.isIdentifier(callee)) {
           const name = callee.getText();
           spreads.push(name);
           collectInitializerBindingsFromIdentifier({ name, sf, index, resolved, unresolved, visited });
@@ -24498,7 +25113,7 @@ function collectUploadInitializerArray(options) {
       continue;
     }
     const inner = unwrapAsExpressions(el);
-    if (inner && Node18.isIdentifier(inner)) {
+    if (inner && Node19.isIdentifier(inner)) {
       const name = inner.getText();
       direct.push(name);
       resolved.push(name);
@@ -24511,7 +25126,7 @@ function extractUploadServiceCalls(sources, index) {
     const rel = apiRelPath(sf);
     for (const call of sf.getDescendantsOfKind(SyntaxKind10.CallExpression)) {
       const expr = call.getExpression();
-      if (!Node18.isIdentifier(expr) || expr.getText() !== UPLOAD_SERVICE_FACTORY) continue;
+      if (!Node19.isIdentifier(expr) || expr.getText() !== UPLOAD_SERVICE_FACTORY) continue;
       const args = call.getArguments();
       const first = args[0] ? resolveObjectArg(args[0], sf) : void 0;
       if (!first) continue;
@@ -24539,12 +25154,12 @@ function extractUploadServiceCalls(sources, index) {
 function resolveObjectArg(node, sf) {
   const inner = unwrapAsExpressions(node);
   if (!inner) return void 0;
-  if (Node18.isObjectLiteralExpression(inner)) return inner;
-  if (Node18.isIdentifier(inner)) {
+  if (Node19.isObjectLiteralExpression(inner)) return inner;
+  if (Node19.isIdentifier(inner)) {
     const declNode = findLocalVariable(sf, inner.getText());
     if (declNode) {
       const declInit = unwrapAsExpressions(declNode.getInitializer());
-      if (declInit && Node18.isObjectLiteralExpression(declInit)) {
+      if (declInit && Node19.isObjectLiteralExpression(declInit)) {
         return declInit;
       }
     }
@@ -24554,12 +25169,12 @@ function resolveObjectArg(node, sf) {
 function resolveArrayFromProperty(obj, name, sf) {
   const init = unwrapAsExpressions(getPropertyInitializer(obj, name));
   if (!init) return void 0;
-  if (Node18.isArrayLiteralExpression(init)) return init;
-  if (Node18.isIdentifier(init)) {
+  if (Node19.isArrayLiteralExpression(init)) return init;
+  if (Node19.isIdentifier(init)) {
     const declNode = findLocalVariable(sf, init.getText());
     if (declNode) {
       const declInit = unwrapAsExpressions(declNode.getInitializer());
-      if (declInit && Node18.isArrayLiteralExpression(declInit)) {
+      if (declInit && Node19.isArrayLiteralExpression(declInit)) {
         return declInit;
       }
     }
@@ -24570,11 +25185,11 @@ function enclosingFactoryName(node) {
   let current = node.getParent();
   let result;
   while (current) {
-    if (Node18.isFunctionDeclaration(current)) {
+    if (Node19.isFunctionDeclaration(current)) {
       result = current.getName() ?? void 0;
       break;
     }
-    if (Node18.isVariableDeclaration(current)) {
+    if (Node19.isVariableDeclaration(current)) {
       result = current.getName();
       break;
     }
@@ -24628,10 +25243,10 @@ function extractProcessingConfigFromDecl(decl, rel) {
 function readFlowSubtasks(obj) {
   const flowInit = unwrapAsExpressions(getPropertyInitializer(obj, "flow"));
   const subtasks = [];
-  if (flowInit && Node18.isArrayLiteralExpression(flowInit)) {
+  if (flowInit && Node19.isArrayLiteralExpression(flowInit)) {
     for (const el of flowInit.getElements()) {
       const inner = unwrapAsExpressions(el);
-      if (inner && Node18.isObjectLiteralExpression(inner)) {
+      if (inner && Node19.isObjectLiteralExpression(inner)) {
         const subtask = readIdentifierProperty(inner, "subtask");
         if (subtask) subtasks.push(subtask);
       }
@@ -24645,7 +25260,7 @@ function extractProcessingHandlerCalls(sources) {
     const rel = apiRelPath(sf);
     for (const call of sf.getDescendantsOfKind(SyntaxKind10.CallExpression)) {
       const expr = call.getExpression();
-      if (!Node18.isIdentifier(expr) || expr.getText() !== PROCESSING_HANDLER_FACTORY) continue;
+      if (!Node19.isIdentifier(expr) || expr.getText() !== PROCESSING_HANDLER_FACTORY) continue;
       const args = call.getArguments();
       const first = args[0] ? resolveObjectArg(args[0], sf) : void 0;
       if (!first) continue;
@@ -24666,7 +25281,7 @@ function extractProcessingHandlerCalls(sources) {
 }
 function collectProcessorArrayElements(processorsArr, direct, spreads) {
   for (const el of processorsArr.getElements()) {
-    if (Node18.isSpreadElement(el)) {
+    if (Node19.isSpreadElement(el)) {
       addProcessorIdentifierName(el.getExpression(), spreads);
       continue;
     }
@@ -24678,13 +25293,13 @@ function collectProcessorArrayElements(processorsArr, direct, spreads) {
 }
 function addProcessorIdentifierName(node, bucket) {
   if (!node) return;
-  if (Node18.isIdentifier(node)) {
+  if (Node19.isIdentifier(node)) {
     bucket.push(node.getText());
     return;
   }
-  if (Node18.isCallExpression(node)) {
+  if (Node19.isCallExpression(node)) {
     const callee = node.getExpression();
-    if (Node18.isIdentifier(callee)) {
+    if (Node19.isIdentifier(callee)) {
       bucket.push(callee.getText());
     }
   }
@@ -25676,7 +26291,7 @@ var storageFileMValidateFolderTool = createTwoSideValidateTool({
 });
 
 // packages/dbx-components-mcp/src/tools/notification-m-validate-app/extract.ts
-import { Node as Node19, SyntaxKind as SyntaxKind11 } from "ts-morph";
+import { Node as Node20, SyntaxKind as SyntaxKind11 } from "ts-morph";
 var NOTIF_TEMPLATE_TYPE = "NotificationTemplateType";
 var NOTIF_TEMPLATE_TYPE_INFO = "NotificationTemplateTypeInfo";
 var NOTIF_TEMPLATE_TYPE_INFO_ARRAY = "NotificationTemplateTypeInfo[]";
@@ -25797,7 +26412,7 @@ function extractTemplateInfoAggregates(sources) {
         const ids = [];
         for (const el of arr.getElements()) {
           const inner = unwrapAsExpressions(el);
-          if (inner && Node19.isIdentifier(inner)) {
+          if (inner && Node20.isIdentifier(inner)) {
             ids.push(inner.getText());
           }
         }
@@ -25843,7 +26458,7 @@ function extractTaskAllTypesAggregates(sources) {
         const ids = [];
         for (const el of arr.getElements()) {
           const inner = unwrapAsExpressions(el);
-          if (inner && Node19.isIdentifier(inner)) {
+          if (inner && Node20.isIdentifier(inner)) {
             ids.push(inner.getText());
           }
         }
@@ -25871,14 +26486,14 @@ function extractTaskCheckpointAliases(sources) {
   return out;
 }
 function collectStringLiterals(node, out) {
-  if (Node19.isLiteralTypeNode(node)) {
+  if (Node20.isLiteralTypeNode(node)) {
     const lit = node.getLiteral();
-    if (Node19.isStringLiteral(lit)) {
+    if (Node20.isStringLiteral(lit)) {
       out.push(lit.getLiteralText());
     }
     return;
   }
-  if (Node19.isUnionTypeNode(node)) {
+  if (Node20.isUnionTypeNode(node)) {
     for (const child of node.getTypeNodes()) {
       collectStringLiterals(child, out);
     }
@@ -25932,7 +26547,7 @@ function extractTemplateInfoRecord(sources, index) {
 }
 function tryReadTemplateInfoRecord(decl, rel, index) {
   const initializer = unwrapAsExpressions(decl.getInitializer());
-  if (!initializer || !Node19.isCallExpression(initializer)) return void 0;
+  if (!initializer || !Node20.isCallExpression(initializer)) return void 0;
   if (initializer.getExpression().getText() !== TEMPLATE_INFO_RECORD_FACTORY) return void 0;
   const args = initializer.getArguments();
   const arr = args[0] ? asArrayLiteral(args[0]) : void 0;
@@ -25953,15 +26568,15 @@ function tryReadTemplateInfoRecord(decl, rel, index) {
 }
 function classifyInfoRecordArrayElements(arr, direct, spreads) {
   for (const el of arr.getElements()) {
-    if (Node19.isSpreadElement(el)) {
+    if (Node20.isSpreadElement(el)) {
       const inner2 = el.getExpression();
-      if (Node19.isIdentifier(inner2)) {
+      if (Node20.isIdentifier(inner2)) {
         spreads.push(inner2.getText());
       }
       continue;
     }
     const inner = unwrapAsExpressions(el);
-    if (inner && Node19.isIdentifier(inner)) {
+    if (inner && Node20.isIdentifier(inner)) {
       direct.push(inner.getText());
     }
   }
@@ -25988,7 +26603,7 @@ function extractTemplateInfoRecordWiring(sources) {
       const first = args[0];
       if (!first) continue;
       const inner = unwrapAsExpressions(first);
-      if (!inner || !Node19.isIdentifier(inner)) continue;
+      if (!inner || !Node20.isIdentifier(inner)) continue;
       const result = {
         recordIdentifier: inner.getText(),
         sourceFile: rel
@@ -26026,7 +26641,7 @@ function buildApiFunctionIndex2(sources) {
       for (const decl of stmt.getDeclarations()) {
         const initializer = unwrapAsExpressions(decl.getInitializer());
         if (!initializer) continue;
-        if (Node19.isArrowFunction(initializer) || Node19.isFunctionExpression(initializer)) {
+        if (Node20.isArrowFunction(initializer) || Node20.isFunctionExpression(initializer)) {
           map.set(decl.getName(), { node: initializer, sourceFile: sf, relPath: rel });
         }
       }
@@ -26062,11 +26677,11 @@ function extractTemplateConfigsArrayFactory(sources, index) {
     const arr = returnExpr ? asArrayLiteral(returnExpr) : void 0;
     if (arr) {
       for (const el of arr.getElements()) {
-        if (Node19.isSpreadElement(el)) {
+        if (Node20.isSpreadElement(el)) {
           const inner2 = el.getExpression();
-          if (Node19.isCallExpression(inner2)) {
+          if (Node20.isCallExpression(inner2)) {
             const callee = inner2.getExpression();
-            if (Node19.isIdentifier(callee)) {
+            if (Node20.isIdentifier(callee)) {
               const callName = callee.getText();
               spreadCalls.push(callName);
               if (!index.functionsByName.has(callName)) {
@@ -26077,9 +26692,9 @@ function extractTemplateConfigsArrayFactory(sources, index) {
           continue;
         }
         const inner = unwrapAsExpressions(el);
-        if (inner && Node19.isCallExpression(inner)) {
+        if (inner && Node20.isCallExpression(inner)) {
           const callee = inner.getExpression();
-          if (Node19.isIdentifier(callee)) {
+          if (Node20.isIdentifier(callee)) {
             directCalls.push(callee.getText());
           }
         }
@@ -26128,11 +26743,11 @@ function collectFromArrayEntryFactory(name, out, index) {
   const arr = asArrayLiteral(returnExpr);
   if (!arr) return;
   for (const el of arr.getElements()) {
-    if (Node19.isSpreadElement(el)) {
+    if (Node20.isSpreadElement(el)) {
       const inner2 = el.getExpression();
-      if (Node19.isCallExpression(inner2)) {
+      if (Node20.isCallExpression(inner2)) {
         const callee = inner2.getExpression();
-        if (Node19.isIdentifier(callee)) {
+        if (Node20.isIdentifier(callee)) {
           collectFromArrayEntryFactory(callee.getText(), out, index);
         }
       }
@@ -26140,9 +26755,9 @@ function collectFromArrayEntryFactory(name, out, index) {
     }
     const inner = unwrapAsExpressions(el);
     if (!inner) continue;
-    if (Node19.isCallExpression(inner)) {
+    if (Node20.isCallExpression(inner)) {
       const callee = inner.getExpression();
-      if (Node19.isIdentifier(callee)) {
+      if (Node20.isIdentifier(callee)) {
         collectFromSingleEntryFactory(callee.getText(), out, index);
       }
       continue;
@@ -26162,7 +26777,7 @@ function extractTaskServiceCalls(sources, index, trustedExternal) {
     const rel = apiRelPath(sf);
     for (const call of sf.getDescendantsOfKind(SyntaxKind11.CallExpression)) {
       const expr = call.getExpression();
-      if (!Node19.isIdentifier(expr) || expr.getText() !== TASK_SERVICE_FACTORY) continue;
+      if (!Node20.isIdentifier(expr) || expr.getText() !== TASK_SERVICE_FACTORY) continue;
       const args = call.getArguments();
       const first = args[0] ? asObjectLiteral(args[0]) : void 0;
       if (!first) continue;
@@ -26188,13 +26803,13 @@ function collectValidateArrayElements(validateArr) {
   const spreads = [];
   if (!validateArr) return { ids, spreads };
   for (const el of validateArr.getElements()) {
-    if (Node19.isSpreadElement(el)) {
+    if (Node20.isSpreadElement(el)) {
       const inner2 = el.getExpression();
-      if (Node19.isIdentifier(inner2)) spreads.push(inner2.getText());
+      if (Node20.isIdentifier(inner2)) spreads.push(inner2.getText());
       continue;
     }
     const inner = unwrapAsExpressions(el);
-    if (inner && Node19.isIdentifier(inner)) ids.push(inner.getText());
+    if (inner && Node20.isIdentifier(inner)) ids.push(inner.getText());
   }
   return { ids, spreads };
 }
@@ -26207,17 +26822,17 @@ function collectHandlersArrayElements(options) {
   if (!handlersArr) return { handlerTypes, unresolvedSpreads, resolvedBindings, unresolvedBindings };
   const visited = /* @__PURE__ */ new Set();
   for (const el of handlersArr.getElements()) {
-    if (Node19.isSpreadElement(el)) {
+    if (Node20.isSpreadElement(el)) {
       consumeHandlersSpreadElement({ inner: el.getExpression(), sf, index, trustedExternal, unresolvedSpreads, resolvedBindings, unresolvedBindings, visited });
       continue;
     }
     const inner = unwrapAsExpressions(el);
     if (!inner) continue;
-    if (Node19.isIdentifier(inner)) {
+    if (Node20.isIdentifier(inner)) {
       collectHandlerBindingsFromIdentifier({ name: inner.getText(), sf, index, trustedExternal, resolved: resolvedBindings, unresolved: unresolvedBindings, visited });
-    } else if (Node19.isCallExpression(inner)) {
+    } else if (Node20.isCallExpression(inner)) {
       const callee = inner.getExpression();
-      if (Node19.isIdentifier(callee)) {
+      if (Node20.isIdentifier(callee)) {
         collectHandlerBindingsFromIdentifier({ name: callee.getText(), sf, index, trustedExternal, resolved: resolvedBindings, unresolved: unresolvedBindings, visited });
       }
     }
@@ -26226,16 +26841,16 @@ function collectHandlersArrayElements(options) {
 }
 function consumeHandlersSpreadElement(options) {
   const { inner, sf, index, trustedExternal, unresolvedSpreads, resolvedBindings, unresolvedBindings, visited } = options;
-  if (Node19.isCallExpression(inner)) {
+  if (Node20.isCallExpression(inner)) {
     const callee = inner.getExpression();
-    if (Node19.isIdentifier(callee)) {
+    if (Node20.isIdentifier(callee)) {
       const name = callee.getText();
       unresolvedSpreads.push(name);
       collectHandlerBindingsFromIdentifier({ name, sf, index, trustedExternal, resolved: resolvedBindings, unresolved: unresolvedBindings, visited });
     }
     return;
   }
-  if (Node19.isIdentifier(inner)) {
+  if (Node20.isIdentifier(inner)) {
     const name = inner.getText();
     unresolvedSpreads.push(name);
     collectHandlerBindingsFromIdentifier({ name, sf, index, trustedExternal, resolved: resolvedBindings, unresolved: unresolvedBindings, visited });
@@ -26245,15 +26860,31 @@ function collectHandlerBindingsFromValue(options) {
   const { node, sf, index, trustedExternal, resolved, unresolved, visited } = options;
   const inner = unwrapAsExpressions(node);
   if (!inner) return false;
-  if (Node19.isCallExpression(inner)) {
+  if (Node20.isCallExpression(inner)) {
     const callee = inner.getExpression();
-    if (Node19.isIdentifier(callee)) {
+    if (Node20.isIdentifier(callee)) {
       return collectHandlerBindingsFromIdentifier({ name: callee.getText(), sf, index, trustedExternal, resolved, unresolved, visited });
     }
+    return false;
   }
-  if (Node19.isIdentifier(inner)) {
+  if (Node20.isIdentifier(inner)) {
     return collectHandlerBindingsFromIdentifier({ name: inner.getText(), sf, index, trustedExternal, resolved, unresolved, visited });
   }
+  if (Node20.isArrayLiteralExpression(inner)) {
+    let any = false;
+    for (const el of inner.getElements()) {
+      if (Node20.isSpreadElement(el)) {
+        if (collectHandlerBindingsFromValue({ node: el.getExpression(), sf, index, trustedExternal, resolved, unresolved, visited })) {
+          any = true;
+        }
+        continue;
+      }
+      if (collectHandlerBindingsFromValue({ node: el, sf, index, trustedExternal, resolved, unresolved, visited })) {
+        any = true;
+      }
+    }
+    return any;
+  }
   return false;
 }
 function collectHandlerBindingsFromIdentifier(options) {
@@ -26268,7 +26899,7 @@ function collectHandlerBindingsFromIdentifier(options) {
       const typeText = typeNode ? typeNode.getText() : void 0;
       const isHandlerConfigTyped = typeText !== void 0 && (typeText === NOTIF_TASK_SERVICE_HANDLER_CONFIG || typeText.startsWith(`${NOTIF_TASK_SERVICE_HANDLER_CONFIG}<`));
       const declInit = unwrapAsExpressions(localDecl.getInitializer());
-      const isObjectLit = declInit !== void 0 && Node19.isObjectLiteralExpression(declInit);
+      const isObjectLit = declInit !== void 0 && Node20.isObjectLiteralExpression(declInit);
       if (isHandlerConfigTyped && isObjectLit) {
         resolved.push(localDecl.getName());
         resolvedAny = true;
@@ -26299,12 +26930,12 @@ function collectHandlerBindingsFromIdentifier(options) {
 function resolveArrayFromProperty2(obj, name, sf) {
   const init = unwrapAsExpressions(getPropertyInitializer(obj, name));
   if (!init) return void 0;
-  if (Node19.isArrayLiteralExpression(init)) return init;
-  if (Node19.isIdentifier(init)) {
+  if (Node20.isArrayLiteralExpression(init)) return init;
+  if (Node20.isIdentifier(init)) {
     const declNode = findLocalVariable(sf, init.getText());
     if (declNode) {
       const declInit = unwrapAsExpressions(declNode.getInitializer());
-      if (declInit && Node19.isArrayLiteralExpression(declInit)) {
+      if (declInit && Node20.isArrayLiteralExpression(declInit)) {
         return declInit;
       }
     }
@@ -26325,12 +26956,12 @@ function extractTaskHandlerEntries(sources) {
     if (!typeIdent) return;
     const flowInit = unwrapAsExpressions(getPropertyInitializer(obj, "flow"));
     let flowCount;
-    if (flowInit && Node19.isArrayLiteralExpression(flowInit)) {
+    if (flowInit && Node20.isArrayLiteralExpression(flowInit)) {
       flowCount = flowInit.getElements().length;
     }
     let dataArg;
     let checkpointArg;
-    if (Node19.isTypeReference(typeNode)) {
+    if (Node20.isTypeReference(typeNode)) {
       const tArgs = typeNode.getTypeArguments();
       if (tArgs.length >= 1) dataArg = tArgs[0].getText();
       if (tArgs.length >= 2) checkpointArg = tArgs[1].getText();
@@ -27223,7 +27854,7 @@ async function inspectFolder2(path) {
 }
 
 // packages/dbx-components-mcp/src/tools/system-m-validate-folder/extract.ts
-import { Node as Node20, Project as Project13 } from "ts-morph";
+import { Node as Node21, Project as Project13 } from "ts-morph";
 var TYPE_CONSTANT_SUFFIX = "_SYSTEM_STATE_TYPE";
 var DATA_INTERFACE_SUFFIX = "SystemData";
 var CONVERTER_CONFIG_TYPE = "SystemStateStoredDataFieldConverterConfig";
@@ -27287,7 +27918,7 @@ function findDataInterfaces2(sourceFile) {
   return out;
 }
 function extendsSystemStateStoredData(iface) {
-  if (!Node20.isInterfaceDeclaration(iface)) return false;
+  if (!Node21.isInterfaceDeclaration(iface)) return false;
   for (const clause of iface.getExtends()) {
     const text = clause.getText();
     if (text === SYSTEM_STATE_STORED_DATA || text.startsWith(`${SYSTEM_STATE_STORED_DATA}<`) || text === `${SYSTEM_STATE_STORED_DATA}, ${SYSTEM_STATE_STORED_DATA}`) {
@@ -27307,14 +27938,14 @@ function findConverters2(sourceFile) {
     for (const decl of stmt.getDeclarations()) {
       const typeNode = decl.getTypeNode();
       if (!typeNode) continue;
-      if (!Node20.isTypeReference(typeNode)) continue;
+      if (!Node21.isTypeReference(typeNode)) continue;
       const typeName = typeNode.getTypeName().getText();
       if (typeName !== CONVERTER_CONFIG_TYPE) continue;
       const typeArgs = typeNode.getTypeArguments();
       let dataTypeArgument;
       if (typeArgs.length >= 1) {
         const arg = typeArgs[0];
-        if (Node20.isTypeReference(arg)) {
+        if (Node21.isTypeReference(arg)) {
           dataTypeArgument = arg.getTypeName().getText();
         } else {
           dataTypeArgument = arg.getText();
@@ -27361,19 +27992,19 @@ function collectConverterMapKeys(decl) {
   if (!obj) return [];
   const out = [];
   for (const prop of obj.getProperties()) {
-    if (!Node20.isPropertyAssignment(prop)) continue;
+    if (!Node21.isPropertyAssignment(prop)) continue;
     const nameNode = prop.getNameNode();
     const line = prop.getStartLineNumber();
-    if (Node20.isComputedPropertyName(nameNode)) {
+    if (Node21.isComputedPropertyName(nameNode)) {
       const inner = nameNode.getExpression();
       out.push({ raw: inner.getText(), kind: "identifier", line });
       continue;
     }
-    if (Node20.isStringLiteral(nameNode)) {
+    if (Node21.isStringLiteral(nameNode)) {
       out.push({ raw: nameNode.getLiteralText(), kind: "string", line });
       continue;
     }
-    if (Node20.isIdentifier(nameNode)) {
+    if (Node21.isIdentifier(nameNode)) {
       out.push({ raw: nameNode.getText(), kind: "string", line });
       continue;
     }
@@ -27383,10 +28014,10 @@ function collectConverterMapKeys(decl) {
 }
 function unwrapObjectLiteral(node) {
   let current = node;
-  while (current && Node20.isAsExpression(current)) {
+  while (current && Node21.isAsExpression(current)) {
     current = current.getExpression();
   }
-  if (current && Node20.isObjectLiteralExpression(current)) {
+  if (current && Node21.isObjectLiteralExpression(current)) {
     return current;
   }
   return void 0;
@@ -27420,10 +28051,10 @@ function findLastTopLevelExportLine(sourceFile) {
   return last;
 }
 function isExportedTopLevel(stmt) {
-  if (Node20.isVariableStatement(stmt) || Node20.isFunctionDeclaration(stmt) || Node20.isClassDeclaration(stmt) || Node20.isInterfaceDeclaration(stmt) || Node20.isTypeAliasDeclaration(stmt) || Node20.isEnumDeclaration(stmt)) {
+  if (Node21.isVariableStatement(stmt) || Node21.isFunctionDeclaration(stmt) || Node21.isClassDeclaration(stmt) || Node21.isInterfaceDeclaration(stmt) || Node21.isTypeAliasDeclaration(stmt) || Node21.isEnumDeclaration(stmt)) {
     return stmt.isExported();
   }
-  if (Node20.isExportDeclaration(stmt) || Node20.isExportAssignment(stmt)) {
+  if (Node21.isExportDeclaration(stmt) || Node21.isExportAssignment(stmt)) {
     return true;
   }
   return false;
@@ -27734,7 +28365,7 @@ var systemMValidateFolderTool = createFolderValidateTool({
 });
 
 // packages/dbx-components-mcp/src/tools/dbx-asset-validate-app/extract.ts
-import { Node as Node21, Project as Project14 } from "ts-morph";
+import { Node as Node22, Project as Project14 } from "ts-morph";
 var ASSETS_RELPATH = "src/lib/assets.ts";
 var BARREL_RELPATH = "src/lib/index.ts";
 var LOCAL_ASSET_BUILDER = "localAsset";
@@ -27793,11 +28424,11 @@ function extractFromAssetsSource(ctx, sf) {
       const initializer = unwrapAsExpressions(decl.getInitializer());
       if (!initializer) continue;
       const site = { isExported, symbolName: decl.getName(), line: decl.getStartLineNumber(), rel };
-      if (Node21.isCallExpression(initializer)) {
+      if (Node22.isCallExpression(initializer)) {
         handleCallInitializer(ctx, site, initializer);
         continue;
       }
-      if (isExported && Node21.isArrayLiteralExpression(initializer) && typeAnnotationText(decl) === ASSET_PATH_REF_ARRAY_TYPE) {
+      if (isExported && Node22.isArrayLiteralExpression(initializer) && typeAnnotationText(decl) === ASSET_PATH_REF_ARRAY_TYPE) {
         ctx.aggregatorExports.push({ symbolName: site.symbolName, memberNames: collectArrayIdentifiers(initializer.getElements()), sourceFile: rel, line: site.line });
       }
     }
@@ -27807,7 +28438,7 @@ function collectArrayIdentifiers(elements) {
   const out = [];
   for (const el of elements) {
     const inner = unwrapAsExpressions(el);
-    if (inner && Node21.isIdentifier(inner)) {
+    if (inner && Node22.isIdentifier(inner)) {
       out.push(inner.getText());
     }
   }
@@ -27815,11 +28446,11 @@ function collectArrayIdentifiers(elements) {
 }
 function handleCallInitializer(ctx, site, callExpr) {
   const callee = callExpr.getExpression();
-  if (Node21.isIdentifier(callee)) {
+  if (Node22.isIdentifier(callee)) {
     handleIdentifierCallee({ ctx, site, callExpr, calleeName: callee.getText() });
     return;
   }
-  if (Node21.isPropertyAccessExpression(callee)) {
+  if (Node22.isPropertyAccessExpression(callee)) {
     handleFluentMemberCall(ctx, site, callExpr);
   }
 }
@@ -27877,9 +28508,9 @@ function handleRemoteBaseBuilder(ctx, site, arg) {
 }
 function handleFluentMemberCall(ctx, site, callExpr) {
   const callee = callExpr.getExpression();
-  if (!Node21.isPropertyAccessExpression(callee)) return;
+  if (!Node22.isPropertyAccessExpression(callee)) return;
   const identNode = callee.getExpression();
-  if (!Node21.isIdentifier(identNode)) return;
+  if (!Node22.isIdentifier(identNode)) return;
   const memberName = callee.getName();
   if (memberName !== "asset" && memberName !== "assets") return;
   const builderName = identNode.getText();
@@ -27904,7 +28535,7 @@ function handleFluentMemberCall(ctx, site, callExpr) {
     return;
   }
   const arrayInner = unwrapAsExpressions(args[0]);
-  if (!arrayInner || !Node21.isArrayLiteralExpression(arrayInner)) return;
+  if (!arrayInner || !Node22.isArrayLiteralExpression(arrayInner)) return;
   const resolvedPaths = collectFluentArrayPaths({ elements: arrayInner.getElements(), sourceType, folder, remoteBase });
   if (site.isExported) {
     ctx.assetConstants.push({ symbolName: site.symbolName, sourceType, helper, resolved: void 0, resolvedPaths, sourceFile: site.rel, line: site.line });
@@ -27914,7 +28545,7 @@ function collectFluentArrayPaths(input) {
   const out = [];
   for (const el of input.elements) {
     const inner = unwrapAsExpressions(el);
-    if (inner && Node21.isStringLiteral(inner)) {
+    if (inner && Node22.isStringLiteral(inner)) {
       const joined = joinFluent({ sourceType: input.sourceType, folder: input.folder, remoteBase: input.remoteBase, child: inner.getLiteralText() });
       if (joined !== void 0) out.push(joined);
     }
@@ -27947,7 +28578,7 @@ function readStringArg(call) {
 }
 function readStringArgFromNode(node) {
   const inner = unwrapAsExpressions(node);
-  if (inner && Node21.isStringLiteral(inner)) {
+  if (inner && Node22.isStringLiteral(inner)) {
     return inner.getLiteralText();
   }
   return void 0;
@@ -29862,7 +30493,7 @@ import { glob as fsGlob5, readFile as readFile18, stat as stat14 } from "node:fs
 import { dirname as dirname13, isAbsolute as isAbsolute13, resolve as resolve34, sep as sep12 } from "node:path";
 
 // packages/dbx-components-mcp/src/tools/route/extract.ts
-import { Node as Node22, Project as Project15, SyntaxKind as SyntaxKind12 } from "ts-morph";
+import { Node as Node23, Project as Project15, SyntaxKind as SyntaxKind12 } from "ts-morph";
 function extractFile3(source) {
   const project = new Project15({ useInMemoryFileSystem: true, skipAddingFilesFromTsConfig: true });
   const sourceFile = project.createSourceFile(source.name, source.text, { overwrite: true });
@@ -29877,9 +30508,9 @@ function extractFile3(source) {
   }
   for (const arrayLit of findStateArrayLiterals(sourceFile)) {
     for (const element of arrayLit.getElements()) {
-      if (Node22.isObjectLiteralExpression(element)) {
+      if (Node23.isObjectLiteralExpression(element)) {
         addNode({ file: source.name, literal: element, fallbackConstName: void 0, into: collected, issues });
-      } else if (Node22.isIdentifier(element)) {
+      } else if (Node23.isIdentifier(element)) {
         const ref = objectLiteralsByName.get(element.getText());
         if (ref) {
           addNode({ file: source.name, literal: ref.literal, fallbackConstName: element.getText(), into: collected, issues });
@@ -29900,7 +30531,7 @@ function collectStateConsts(sourceFile) {
   for (const stmt of sourceFile.getVariableStatements()) {
     for (const decl of stmt.getDeclarations()) {
       const initializer = decl.getInitializer();
-      if (!initializer || !Node22.isObjectLiteralExpression(initializer)) {
+      if (!initializer || !Node23.isObjectLiteralExpression(initializer)) {
         continue;
       }
       const typeNode = decl.getTypeNode();
@@ -29915,7 +30546,7 @@ function findStateArrayLiterals(sourceFile) {
   for (const stmt of sourceFile.getVariableStatements()) {
     for (const decl of stmt.getDeclarations()) {
       const initializer = decl.getInitializer();
-      if (initializer && Node22.isArrayLiteralExpression(initializer) && declarationIsStateArray(stmt, decl.getName(), initializer)) {
+      if (initializer && Node23.isArrayLiteralExpression(initializer) && declarationIsStateArray(stmt, decl.getName(), initializer)) {
         arrays.push(initializer);
       }
     }
@@ -29929,17 +30560,17 @@ function findStateArrayLiterals(sourceFile) {
       continue;
     }
     for (const arg of call.getArguments()) {
-      if (!Node22.isObjectLiteralExpression(arg)) {
+      if (!Node23.isObjectLiteralExpression(arg)) {
         continue;
       }
       const statesProp = arg.getProperty("states");
-      if (!statesProp || !Node22.isPropertyAssignment(statesProp)) {
+      if (!statesProp || !Node23.isPropertyAssignment(statesProp)) {
         continue;
       }
       const initializer = statesProp.getInitializer();
-      if (initializer && Node22.isArrayLiteralExpression(initializer)) {
+      if (initializer && Node23.isArrayLiteralExpression(initializer)) {
         arrays.push(initializer);
-      } else if (initializer && Node22.isIdentifier(initializer)) {
+      } else if (initializer && Node23.isIdentifier(initializer)) {
         const referenced = findArrayLiteralForIdentifier(sourceFile, initializer);
         if (referenced) {
           arrays.push(referenced);
@@ -29956,10 +30587,10 @@ function declarationIsStateArray(stmt, name, literal) {
     return true;
   }
   for (const element of literal.getElements()) {
-    if (Node22.isObjectLiteralExpression(element) && hasStringNameProperty(element)) {
+    if (Node23.isObjectLiteralExpression(element) && hasStringNameProperty(element)) {
       return true;
     }
-    if (Node22.isIdentifier(element)) {
+    if (Node23.isIdentifier(element)) {
       return true;
     }
   }
@@ -29967,11 +30598,11 @@ function declarationIsStateArray(stmt, name, literal) {
 }
 function hasStringNameProperty(literal) {
   const nameProp = literal.getProperty("name");
-  if (!nameProp || !Node22.isPropertyAssignment(nameProp)) {
+  if (!nameProp || !Node23.isPropertyAssignment(nameProp)) {
     return false;
   }
   const initializer = nameProp.getInitializer();
-  return initializer !== void 0 && (Node22.isStringLiteral(initializer) || Node22.isNoSubstitutionTemplateLiteral(initializer));
+  return initializer !== void 0 && (Node23.isStringLiteral(initializer) || Node23.isNoSubstitutionTemplateLiteral(initializer));
 }
 function findArrayLiteralForIdentifier(sourceFile, identifier) {
   const name = identifier.getText();
@@ -29981,7 +30612,7 @@ function findArrayLiteralForIdentifier(sourceFile, identifier) {
         continue;
       }
       const initializer = decl.getInitializer();
-      if (initializer && Node22.isArrayLiteralExpression(initializer)) {
+      if (initializer && Node23.isArrayLiteralExpression(initializer)) {
         return initializer;
       }
     }
@@ -30031,21 +30662,21 @@ function addNode(options) {
 }
 function stringPropertyValue(literal, key) {
   const prop = literal.getProperty(key);
-  if (!prop || !Node22.isPropertyAssignment(prop)) {
+  if (!prop || !Node23.isPropertyAssignment(prop)) {
     return void 0;
   }
   const initializer = prop.getInitializer();
   if (!initializer) {
     return void 0;
   }
-  if (Node22.isStringLiteral(initializer) || Node22.isNoSubstitutionTemplateLiteral(initializer)) {
+  if (Node23.isStringLiteral(initializer) || Node23.isNoSubstitutionTemplateLiteral(initializer)) {
     return initializer.getLiteralText();
   }
   return void 0;
 }
 function booleanPropertyValue(literal, key) {
   const prop = literal.getProperty(key);
-  if (!prop || !Node22.isPropertyAssignment(prop)) {
+  if (!prop || !Node23.isPropertyAssignment(prop)) {
     return void 0;
   }
   const initializer = prop.getInitializer();
@@ -30062,33 +30693,33 @@ function booleanPropertyValue(literal, key) {
 }
 function identifierPropertyValue(literal, key) {
   const prop = literal.getProperty(key);
-  if (!prop || !Node22.isPropertyAssignment(prop)) {
+  if (!prop || !Node23.isPropertyAssignment(prop)) {
     return void 0;
   }
   const initializer = prop.getInitializer();
   if (!initializer) {
     return void 0;
   }
-  if (Node22.isIdentifier(initializer)) {
+  if (Node23.isIdentifier(initializer)) {
     return initializer.getText();
   }
-  if (Node22.isPropertyAccessExpression(initializer)) {
+  if (Node23.isPropertyAccessExpression(initializer)) {
     return initializer.getText();
   }
   return void 0;
 }
 function objectPropertyKeys(literal, key) {
   const prop = literal.getProperty(key);
-  if (!prop || !Node22.isPropertyAssignment(prop)) {
+  if (!prop || !Node23.isPropertyAssignment(prop)) {
     return [];
   }
   const initializer = prop.getInitializer();
-  if (!initializer || !Node22.isObjectLiteralExpression(initializer)) {
+  if (!initializer || !Node23.isObjectLiteralExpression(initializer)) {
     return [];
   }
   const out = [];
   for (const member of initializer.getProperties()) {
-    if (Node22.isPropertyAssignment(member) || Node22.isShorthandPropertyAssignment(member) || Node22.isMethodDeclaration(member)) {
+    if (Node23.isPropertyAssignment(member) || Node23.isShorthandPropertyAssignment(member) || Node23.isMethodDeclaration(member)) {
       const nameNode = member.getNameNode();
       if (nameNode) {
         out.push(nameNode.getText());
@@ -30099,7 +30730,7 @@ function objectPropertyKeys(literal, key) {
 }
 function collectResolveKeys(literal) {
   const prop = literal.getProperty("resolve");
-  if (!prop || !Node22.isPropertyAssignment(prop)) {
+  if (!prop || !Node23.isPropertyAssignment(prop)) {
     return [];
   }
   const initializer = prop.getInitializer();
@@ -30107,22 +30738,22 @@ function collectResolveKeys(literal) {
     return [];
   }
   const keys = [];
-  if (Node22.isObjectLiteralExpression(initializer)) {
+  if (Node23.isObjectLiteralExpression(initializer)) {
     for (const member of initializer.getProperties()) {
-      if (Node22.isPropertyAssignment(member) || Node22.isShorthandPropertyAssignment(member) || Node22.isMethodDeclaration(member)) {
+      if (Node23.isPropertyAssignment(member) || Node23.isShorthandPropertyAssignment(member) || Node23.isMethodDeclaration(member)) {
         const nameNode = member.getNameNode();
         if (nameNode) {
           keys.push(nameNode.getText());
         }
       }
     }
-  } else if (Node22.isArrayLiteralExpression(initializer)) {
+  } else if (Node23.isArrayLiteralExpression(initializer)) {
     for (const element of initializer.getElements()) {
-      if (Node22.isObjectLiteralExpression(element)) {
+      if (Node23.isObjectLiteralExpression(element)) {
         const tokenProp = element.getProperty("token");
-        if (tokenProp && Node22.isPropertyAssignment(tokenProp)) {
+        if (tokenProp && Node23.isPropertyAssignment(tokenProp)) {
           const tokenInit = tokenProp.getInitializer();
-          if (tokenInit && (Node22.isStringLiteral(tokenInit) || Node22.isIdentifier(tokenInit))) {
+          if (tokenInit && (Node23.isStringLiteral(tokenInit) || Node23.isIdentifier(tokenInit))) {
             keys.push(tokenInit.getText().replaceAll(/^['"]|['"]$/g, ""));
           }
         }
@@ -32191,7 +32822,7 @@ function createSearchModelSnapshotFieldTool(config) {
 import { glob, readFile as readFile19 } from "node:fs/promises";
 import { resolve as resolve35 } from "node:path";
 import { type as type59 } from "arktype";
-import { Node as Node23, Project as Project16 } from "ts-morph";
+import { Node as Node24, Project as Project16 } from "ts-morph";
 var ListAppArgsType2 = type59({
   componentDir: "string",
   "apiDir?": "string",
@@ -32321,7 +32952,7 @@ async function buildListAppReport(input) {
 function findSnapshotConverterCalls(sourceFile) {
   const out = [];
   sourceFile.forEachDescendant((node) => {
-    if (Node23.isCallExpression(node)) {
+    if (Node24.isCallExpression(node)) {
       const expr = node.getExpression();
       const exprText = expr.getText();
       const head = exprText.replace(/<[^>]*>$/, "");
@@ -32336,17 +32967,17 @@ function readFieldsObject(call) {
   const args = call.getArguments();
   if (args.length === 0) return void 0;
   const first = args[0];
-  if (!Node23.isObjectLiteralExpression(first)) return void 0;
+  if (!Node24.isObjectLiteralExpression(first)) return void 0;
   const fieldsProp = first.getProperty("fields");
-  if (fieldsProp === void 0 || !Node23.isPropertyAssignment(fieldsProp)) return void 0;
+  if (fieldsProp === void 0 || !Node24.isPropertyAssignment(fieldsProp)) return void 0;
   const initializer = fieldsProp.getInitializer();
-  if (initializer === void 0 || !Node23.isObjectLiteralExpression(initializer)) return void 0;
+  if (initializer === void 0 || !Node24.isObjectLiteralExpression(initializer)) return void 0;
   return initializer;
 }
 function resolveModelName(call) {
   let current = call.getParent();
   while (current !== void 0) {
-    if (Node23.isVariableDeclaration(current)) {
+    if (Node24.isVariableDeclaration(current)) {
       return current.getName();
     }
     current = current.getParent();
@@ -32356,10 +32987,10 @@ function resolveModelName(call) {
 function extractFieldUsages(fieldsObj, registry) {
   const out = [];
   for (const property of fieldsObj.getProperties()) {
-    if (!Node23.isPropertyAssignment(property) && !Node23.isShorthandPropertyAssignment(property)) continue;
+    if (!Node24.isPropertyAssignment(property) && !Node24.isShorthandPropertyAssignment(property)) continue;
     const fieldName = property.getName();
     let converterText;
-    if (Node23.isShorthandPropertyAssignment(property)) {
+    if (Node24.isShorthandPropertyAssignment(property)) {
       converterText = property.getName();
     } else {
       const initializer = property.getInitializer();
@@ -33882,7 +34513,7 @@ import { type as type64 } from "arktype";
 // packages/dbx-components-mcp/src/tools/model-list-component/extract.ts
 import { readdir as readdir12, readFile as readFile20, stat as stat16 } from "node:fs/promises";
 import { basename as basename6, join as join19, relative as relative11, sep as sep14 } from "node:path";
-import { Node as Node24, Project as Project17 } from "ts-morph";
+import { Node as Node25, Project as Project17 } from "ts-morph";
 var MODEL_SUBPATH3 = "src/lib/model";
 var MODEL_SUBPATH_PREFIX = `${MODEL_SUBPATH3}/`;
 var RESERVED_NAMES = RESERVED_MODEL_FOLDERS.map((r) => r.name);
@@ -34023,7 +34654,7 @@ function findIdentityIn(sourceFile) {
   for (const statement of sourceFile.getVariableStatements()) {
     for (const decl of statement.getDeclarations()) {
       const initializer = decl.getInitializer();
-      if (!initializer || !Node24.isCallExpression(initializer)) continue;
+      if (!initializer || !Node25.isCallExpression(initializer)) continue;
       if (initializer.getExpression().getText() !== "firestoreModelIdentity") continue;
       const args = initializer.getArguments();
       const parsed = parseIdentityArgs2(args);
@@ -34043,13 +34674,13 @@ function parseIdentityArgs2(args) {
     return { parentIdentityRef: void 0, collectionName: stringLiteralValue3(args[0]), collectionPrefix: stringLiteralValue3(args[1]) };
   }
   if (args.length === 3) {
-    const parent = Node24.isIdentifier(args[0]) ? args[0].getText() : void 0;
+    const parent = Node25.isIdentifier(args[0]) ? args[0].getText() : void 0;
     return { parentIdentityRef: parent, collectionName: stringLiteralValue3(args[1]), collectionPrefix: stringLiteralValue3(args[2]) };
   }
   return { parentIdentityRef: void 0, collectionName: void 0, collectionPrefix: void 0 };
 }
 function stringLiteralValue3(node) {
-  if (Node24.isStringLiteral(node) || Node24.isNoSubstitutionTemplateLiteral(node)) {
+  if (Node25.isStringLiteral(node) || Node25.isNoSubstitutionTemplateLiteral(node)) {
     return node.getLiteralText();
   }
   return void 0;
@@ -34211,7 +34842,7 @@ import { type as type65 } from "arktype";
 // packages/dbx-components-mcp/src/tools/server-actions-list-app/extract.ts
 import { readdir as readdir13, readFile as readFile21, stat as stat17 } from "node:fs/promises";
 import { dirname as dirname14, join as join20, relative as relative12, sep as sep15 } from "node:path";
-import { Node as Node25, Project as Project18 } from "ts-morph";
+import { Node as Node26, Project as Project18 } from "ts-morph";
 var ACTION_SERVER_SUFFIX2 = ".action.server.ts";
 var COMMON_MODEL_SUBPATH2 = "src/app/common/model";
 var COMMON_BARREL_REL = "src/app/common/index.ts";
@@ -34348,7 +34979,7 @@ function inspectModuleText(input) {
     for (const decorator of cls.getDecorators()) {
       if (decorator.getName() !== "Module") continue;
       const args = decorator.getArguments();
-      if (args.length === 0 || !Node25.isObjectLiteralExpression(args[0])) continue;
+      if (args.length === 0 || !Node26.isObjectLiteralExpression(args[0])) continue;
       const obj = args[0];
       providedByModule ||= moduleArrayContains(obj, "providers", input.className);
       exportedByModule ||= moduleArrayContains(obj, "exports", input.className);
@@ -34358,16 +34989,16 @@ function inspectModuleText(input) {
 }
 function moduleArrayContains(decoratorArg, propertyName, className) {
   const property = decoratorArg.getProperty(propertyName);
-  if (!property || !Node25.isPropertyAssignment(property)) return false;
+  if (!property || !Node26.isPropertyAssignment(property)) return false;
   const initializer = property.getInitializer();
-  if (!initializer || !Node25.isArrayLiteralExpression(initializer)) return false;
+  if (!initializer || !Node26.isArrayLiteralExpression(initializer)) return false;
   for (const element of initializer.getElements()) {
-    if (Node25.isIdentifier(element) && element.getText() === className) return true;
-    if (Node25.isObjectLiteralExpression(element)) {
+    if (Node26.isIdentifier(element) && element.getText() === className) return true;
+    if (Node26.isObjectLiteralExpression(element)) {
       const provideProp = element.getProperty("provide");
-      if (provideProp && Node25.isPropertyAssignment(provideProp)) {
+      if (provideProp && Node26.isPropertyAssignment(provideProp)) {
         const provideInit = provideProp.getInitializer();
-        if (provideInit && Node25.isIdentifier(provideInit) && provideInit.getText() === className) return true;
+        if (provideInit && Node26.isIdentifier(provideInit) && provideInit.getText() === className) return true;
       }
     }
   }
@@ -34421,11 +35052,11 @@ function collectInterfaceGetters(sourceFile) {
   const out = /* @__PURE__ */ new Map();
   for (const iface of sourceFile.getInterfaces()) {
     for (const member of iface.getMembers()) {
-      if (Node25.isGetAccessorDeclaration(member)) {
+      if (Node26.isGetAccessorDeclaration(member)) {
         out.set(member.getName(), iface.getName());
         continue;
       }
-      if (Node25.isPropertySignature(member)) {
+      if (Node26.isPropertySignature(member)) {
         out.set(member.getName(), iface.getName());
       }
     }
@@ -34437,7 +35068,7 @@ function collectClassGetters(sourceFile) {
   for (const cls of sourceFile.getClasses()) {
     const set = /* @__PURE__ */ new Set();
     for (const member of cls.getMembers()) {
-      if (Node25.isGetAccessorDeclaration(member)) set.add(member.getName());
+      if (Node26.isGetAccessorDeclaration(member)) set.add(member.getName());
     }
     if (set.size > 0) out.set(cls.getName() ?? "<anon>", set);
   }
@@ -34949,7 +35580,7 @@ import { resolve as resolve43 } from "node:path";
 import { type as type67 } from "arktype";
 
 // packages/dbx-components-mcp/src/scan/actions-extract.ts
-import { Node as Node26, SyntaxKind as SyntaxKind13 } from "ts-morph";
+import { Node as Node27, SyntaxKind as SyntaxKind13 } from "ts-morph";
 var ACTION_MARKER = "dbxAction";
 var ACTION_SLUG_TAG = "dbxActionSlug";
 var ACTION_ROLE_TAG = "dbxActionRole";
@@ -35157,7 +35788,7 @@ function filterStates(values) {
 }
 function readEnumMemberLiteral(member) {
   const initializer = member.getInitializer();
-  if (initializer !== void 0 && (Node26.isStringLiteral(initializer) || Node26.isNoSubstitutionTemplateLiteral(initializer))) {
+  if (initializer !== void 0 && (Node27.isStringLiteral(initializer) || Node27.isNoSubstitutionTemplateLiteral(initializer))) {
     return initializer.getLiteralText();
   }
   return member.getName();
@@ -35777,7 +36408,7 @@ import { resolve as resolve45 } from "node:path";
 import { type as type71 } from "arktype";
 
 // packages/dbx-components-mcp/src/scan/pipes-extract.ts
-import { Node as Node27 } from "ts-morph";
+import { Node as Node28 } from "ts-morph";
 var PIPE_MARKER = "dbxPipe";
 var PIPE_SLUG_TAG = "dbxPipeSlug";
 var PIPE_CATEGORY_TAG = "dbxPipeCategory";
@@ -35970,7 +36601,7 @@ function readPipeDecoratorConfig(decorator) {
     return void 0;
   }
   const firstArg = args[0];
-  if (!Node27.isObjectLiteralExpression(firstArg)) {
+  if (!Node28.isObjectLiteralExpression(firstArg)) {
     return void 0;
   }
   const name = readStringProperty(firstArg, "name");
@@ -35983,7 +36614,7 @@ function readPipeDecoratorConfig(decorator) {
 }
 function readBooleanProperty(obj, propName) {
   const prop = obj.getProperty(propName);
-  if (prop === void 0 || !Node27.isPropertyAssignment(prop)) {
+  if (prop === void 0 || !Node28.isPropertyAssignment(prop)) {
     return void 0;
   }
   const initializer = prop.getInitializer();
@@ -39781,7 +40412,6 @@ var DBX_TOOLS = [
   modelApiListAppTool,
   modelApiLookupTool,
   modelApiValidateAppTool,
-  modelValidateFolderTool,
   modelStoreScaffoldTool,
   modelFixtureListAppTool,
   modelFixtureLookupTool,
@@ -39833,7 +40463,7 @@ function createAuthClusterTools(registry) {
 function registerTools(server, options = {}) {
   const underlyingServer = server.server;
   const tools = [...DBX_TOOLS];
-  tools.push(createUiExamplesTool({ examplesRegistry: options.dbxDocsUiExamplesRegistry }), createModelValidateTool({ ruleOptions: options.modelValidateRuleOptions }), createModelFixtureValidateAppTool({ getRegistry: () => options.fixtureModelRegistry }));
+  tools.push(createUiExamplesTool({ examplesRegistry: options.dbxDocsUiExamplesRegistry }), createModelValidateTool({ ruleOptions: options.modelValidateRuleOptions }), createModelValidateFolderTool({ ruleOptions: options.modelValidateRuleOptions }), createModelFixtureValidateAppTool({ getRegistry: () => options.fixtureModelRegistry }));
   if (options.forgeFieldRegistry !== void 0) {
     tools.push(createLookupFormTool({ registry: options.forgeFieldRegistry }), createSearchFormTool({ registry: options.forgeFieldRegistry }), createFormScaffoldTool({ registry: options.forgeFieldRegistry }));
   }
@@ -40158,9 +40788,11 @@ function resolveModelValidateRuleOptions(config) {
     return void 0;
   }
   const ignoredFieldNames = block.ignoredFieldNames === void 0 ? void 0 : new Set(block.ignoredFieldNames);
+  const ignoredExternalParents = block.ignoredExternalParents === void 0 ? void 0 : new Set(block.ignoredExternalParents);
   const result = {
     maxFieldNameLength: block.maxFieldNameLength,
-    ignoredFieldNames
+    ignoredFieldNames,
+    ignoredExternalParents
   };
   return result;
 }