@dereekb/dbx-components-mcp 13.11.6 → 13.11.7

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.7",
   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.7",
+    "@dereekb/dbx-core": "13.11.7",
+    "@dereekb/dbx-firebase": "13.11.7",
+    "@dereekb/dbx-form": "13.11.7",
+    "@dereekb/dbx-web": "13.11.7",
+    "@dereekb/firebase": "13.11.7",
+    "@dereekb/firebase-server": "13.11.7",
+    "@dereekb/rxjs": "13.11.7",
+    "@dereekb/util": "13.11.7",
     "@uirouter/angular": "21.0.0",
     rxjs: "^7.8.2"
   },
   devDependencies: {
-    "@dereekb/model": "13.11.6"
+    "@dereekb/model": "13.11.7"
   }
 };
 
@@ -14280,6 +14280,14 @@ 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";
+
+// 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_NAMES = ["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 +14297,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_NAMES);
+  for (const call of sourceFile.getDescendantsOfKind(SyntaxKind4.CallExpression)) {
+    const expr = call.getExpression();
+    if (!Node11.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 (!Node11.isTypeReference(typeNode)) {
+    return void 0;
+  }
+  const nameNode = typeNode.getTypeName();
+  if (!Node11.isIdentifier(nameNode)) {
+    return void 0;
+  }
+  return nameNode.getText();
+}
 function findDataInterfaces(sourceFile, groupInterface) {
   const out = [];
   const groupName = groupInterface?.name;
@@ -14309,7 +14357,8 @@ 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());
+    out.push({ name, line: iface.getStartLineNumber(), dbxModelTag, dbxModelSubObjectTag, fields });
   }
   return out;
 }
@@ -14379,6 +14428,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) {
@@ -15141,7 +15201,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 +15221,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 +15409,32 @@ 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_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,15 +17061,11 @@ 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) {
+    checkSubObjectFactoryCallSites(file, violations, context);
     return violations;
   }
   checkFileLevel(file, violations);
@@ -16996,6 +17078,8 @@ function runRules(file, options) {
     checkDeclarationOrder(file, model, violations);
   }
   checkFieldNameLengths(file, violations, options);
+  checkSubObjectInterfaceTags(file, violations);
+  checkSubObjectFactoryCallSites(file, violations, context);
   return violations;
 }
 function checkFieldNameLengths(file, violations, options) {
@@ -17035,7 +17119,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 +17130,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 +17143,49 @@ 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 checkFileLevel(file, violations) {
   const { groupInterface, groupTypes, firstModelLine, models, name } = file;
   if (groupInterface) {
@@ -17759,10 +17887,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 +17914,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 = {
@@ -26250,10 +26399,26 @@ function collectHandlerBindingsFromValue(options) {
     if (Node19.isIdentifier(callee)) {
       return collectHandlerBindingsFromIdentifier({ name: callee.getText(), sf, index, trustedExternal, resolved, unresolved, visited });
     }
+    return false;
   }
   if (Node19.isIdentifier(inner)) {
     return collectHandlerBindingsFromIdentifier({ name: inner.getText(), sf, index, trustedExternal, resolved, unresolved, visited });
   }
+  if (Node19.isArrayLiteralExpression(inner)) {
+    let any = false;
+    for (const el of inner.getElements()) {
+      if (Node19.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) {

package/generated/rule-catalog.generated.json

@@ -479,7 +479,7 @@
     "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`) — 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` → `@dbxModelVariable hours`, `@dbxModelVariable ub` → `@dbxModelVariable usedBudget`). To exempt fields whose long name legitimately equals the short name, add them to `modelValidate.ignoredFieldNames`."
   },
@@ -499,8 +499,8 @@
     "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 — 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` → `userUid`, `n` → `name`, `crAt` → `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 — 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` → `userUid`, `n` → `name`, `crAt` → `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."
   },
   {
@@ -687,6 +687,32 @@
     "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 — interfaces declared outside the validated source set, generic parameters, inline types — 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_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 — `@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 — 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 — `@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 — 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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-components-mcp",
-  "version": "13.11.6",
+  "version": "13.11.7",
   "type": "module",
   "bin": {
     "dbx-components-mcp": "dbx-components-mcp.js"
@@ -15,19 +15,19 @@
     "@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.7",
+    "@dereekb/dbx-core": "13.11.7",
+    "@dereekb/dbx-firebase": "13.11.7",
+    "@dereekb/dbx-form": "13.11.7",
+    "@dereekb/dbx-web": "13.11.7",
+    "@dereekb/firebase": "13.11.7",
+    "@dereekb/firebase-server": "13.11.7",
+    "@dereekb/rxjs": "13.11.7",
+    "@dereekb/util": "13.11.7",
     "@uirouter/angular": "21.0.0",
     "rxjs": "^7.8.2"
   },
   "devDependencies": {
-    "@dereekb/model": "13.11.6"
+    "@dereekb/model": "13.11.7"
   }
 }