@objectstack/lint 14.8.0 → 15.0.0

package/dist/index.d.cts

@@ -359,11 +359,16 @@ declare function validateFormLayout(stack: AnyRec$5): FormLayoutFinding[];
  *
  * - `visibility-alias-deprecated` — a `visibleOn` / `visibility` key in authored
  *   source. Autofix intent: rename the key to `visibleWhen` (same value).
- * - `visibility-root-mislayered` — a runtime view/page visibility predicate
- *   rooted at `data.` (the metadata-editing-form root, ADR-0089 §Context). Runtime
- *   record surfaces bind `record` + `current_user` (pages also expose `page.<var>`),
- *   so a `data.`-rooted predicate here is almost always a wrong-layer paste that
- *   silently never matches.
+ * - `visibility-root-mislayered` — a visibility predicate whose binding root does
+ *   not match its layer (ADR-0089 D3, §Context). The check is **bidirectional**:
+ *   - **runtime** view/page surfaces (`*.view.ts` / `*.page.ts`) bind
+ *     `record` + `current_user` (pages also expose `page.<var>`), so a `data.`-rooted
+ *     predicate here is a wrong-layer paste that silently never matches; and
+ *   - **metadata-editing** forms (`*.form.ts` — the row under edit) bind `data`, so
+ *     a `record.`-rooted predicate there is the same bug in the other direction.
+ *   The layer is supplied by the caller (`opts.layer`, default `'runtime'`): the
+ *   app-lint path (`os validate` / `compile`) always lints runtime surfaces, while a
+ *   file-aware caller linting a `*.form.ts` passes `layer: 'metadata'`.
  *
  * Scope: `views` (form `sections` / legacy `groups`, and their `fields`) and
  * `pages` (`regions[].components[]`). Data-field `visibleWhen` is already covered
@@ -372,6 +377,17 @@ declare function validateFormLayout(stack: AnyRec$5): FormLayoutFinding[];
 declare const VISIBILITY_ALIAS_DEPRECATED = "visibility-alias-deprecated";
 declare const VISIBILITY_ROOT_MISLAYERED = "visibility-root-mislayered";
 type VisibilitySeverity = 'error' | 'warning';
+/**
+ * Which binding environment the linted surface belongs to (ADR-0089 §Context):
+ * - `runtime`  — `*.view.ts` / `*.page.ts`; binds `record` + `current_user` (+ `page`).
+ * - `metadata` — `*.form.ts` metadata-editing forms; binds `data` (the row under edit).
+ */
+type VisibilityLayer = 'runtime' | 'metadata';
+/** Options for {@link validateVisibilityPredicates}. */
+interface VisibilityOptions {
+    /** Binding layer of the surface being linted. Defaults to `'runtime'`. */
+    layer?: VisibilityLayer;
+}
 interface VisibilityFinding {
     /** Always `warning` today — both rules are advisory (see module note). */
     severity: VisibilitySeverity;
@@ -394,8 +410,14 @@ type AnyRec$4 = Record<string, unknown>;
  * `visibleOn` / `visibility` aliases before the schema folds them into
  * `visibleWhen`. Returns findings (empty = clean); all advisory (`warning`) —
  * the caller must never fail the build on these alone.
+ *
+ * The binding-root check is layer-directional (ADR-0089 D3): pass
+ * `opts.layer = 'metadata'` when linting a `*.form.ts` metadata-editing form (so a
+ * `record.`-rooted predicate is flagged), or leave it at the `'runtime'` default for
+ * `*.view.ts` / `*.page.ts` surfaces (so a `data.`-rooted predicate is flagged). The
+ * alias-deprecated check is layer-agnostic.
  */
-declare function validateVisibilityPredicates(stack: AnyRec$4): VisibilityFinding[];
+declare function validateVisibilityPredicates(stack: AnyRec$4, opts?: VisibilityOptions): VisibilityFinding[];
 
 declare const CAPABILITY_REFERENCE_UNKNOWN = "capability-reference-unknown";
 type CapabilityRefSeverity = 'error' | 'warning';
@@ -505,4 +527,4 @@ declare function buildAccessMatrix(stack: AnyRec): AccessMatrix;
  */
 declare function diffAccessMatrix(before: AccessMatrix, after: AccessMatrix): string[];
 
-export { APPROVAL_APPROVER_TYPE_UNKNOWN, APPROVAL_ESCALATION_REASSIGN_NO_TARGET, APPROVAL_ROLE_NOT_MEMBERSHIP_TIER, type ApprovalApproverFinding, type ApprovalApproverSeverity, CAPABILITY_REFERENCE_UNKNOWN, CHART_CONFIG_MISSING, CHART_FIELD_UNKNOWN, type CapabilityRefFinding, type CapabilityRefSeverity, type ExprIssue, FIELD_GROUP_EMPTY, FIELD_GROUP_UNDECLARED, FORM_COLSPAN_ABSOLUTE, FORM_FIELD_UNKNOWN, type FormLayoutFinding, type FormLayoutSeverity, type JsxPageFinding, type JsxPageSeverity, LIST_VIEW_FILTERS_IN_VIEWS_MODE, type ListViewModeFinding, type ListViewModeSeverity, MEASURE_AGGREGATE_INCOHERENT, PAGE_SOURCE_CLASSNAME, type ReactPageFinding, type ReactPageSeverity, type ReactPropFinding, type ReactPropSeverity, type RecordTitleFinding, type RecordTitleSeverity, SECURITY_ANCHOR_HIGH_PRIVILEGE, SECURITY_BOOK_AUDIENCE_UNKNOWN_SET, SECURITY_DELEGATION_MISSING_REASON, SECURITY_EXTERNAL_WIDER, SECURITY_GRANT_EXPIRED_AT_AUTHORING, SECURITY_MASTER_DETAIL_UNGRANTED, SECURITY_OWD_ALIAS, SECURITY_OWD_UNSET, SECURITY_PRIVATE_NO_READSCOPE, SECURITY_ROLE_WORD, SECURITY_WILDCARD_VAMA, SEMANTIC_ROLE_FIELD_UNKNOWN, STYLE_CLASSNAME_TAILWIND, STYLE_NODE_MISSING_ID, STYLE_RESPONSIVE_NO_BASE, STYLE_UNKNOWN_CSS_PROPERTY, STYLE_UNKNOWN_TOKEN, type SecurityFinding, type SecuritySeverity, type SemanticRoleFinding, type SemanticRoleSeverity, type SourceStyleFinding, type SourceStyleSeverity, type StyleFinding, type StyleSeverity, TABLE_COUNT_ONLY, TITLE_FORMAT_RETIRED, TITLE_UNRESOLVABLE, VISIBILITY_ALIAS_DEPRECATED, VISIBILITY_ROOT_MISLAYERED, type VisibilityFinding, type VisibilitySeverity, WIDGET_DATASET_UNKNOWN, WIDGET_DIMENSION_UNKNOWN, WIDGET_MEASURE_UNKNOWN, type WidgetBindingFinding, type WidgetBindingSeverity, buildAccessMatrix, diffAccessMatrix, validateApprovalApprovers, validateCapabilityReferences, validateFormLayout, validateJsxPages, validateListViewMode, validatePageSourceStyling, validateReactPageProps, validateReactPages, validateRecordTitle, validateResponsiveStyles, validateSecurityPosture, validateSemanticRoles, validateStackExpressions, validateVisibilityPredicates, validateWidgetBindings };
+export { APPROVAL_APPROVER_TYPE_UNKNOWN, APPROVAL_ESCALATION_REASSIGN_NO_TARGET, APPROVAL_ROLE_NOT_MEMBERSHIP_TIER, type ApprovalApproverFinding, type ApprovalApproverSeverity, CAPABILITY_REFERENCE_UNKNOWN, CHART_CONFIG_MISSING, CHART_FIELD_UNKNOWN, type CapabilityRefFinding, type CapabilityRefSeverity, type ExprIssue, FIELD_GROUP_EMPTY, FIELD_GROUP_UNDECLARED, FORM_COLSPAN_ABSOLUTE, FORM_FIELD_UNKNOWN, type FormLayoutFinding, type FormLayoutSeverity, type JsxPageFinding, type JsxPageSeverity, LIST_VIEW_FILTERS_IN_VIEWS_MODE, type ListViewModeFinding, type ListViewModeSeverity, MEASURE_AGGREGATE_INCOHERENT, PAGE_SOURCE_CLASSNAME, type ReactPageFinding, type ReactPageSeverity, type ReactPropFinding, type ReactPropSeverity, type RecordTitleFinding, type RecordTitleSeverity, SECURITY_ANCHOR_HIGH_PRIVILEGE, SECURITY_BOOK_AUDIENCE_UNKNOWN_SET, SECURITY_DELEGATION_MISSING_REASON, SECURITY_EXTERNAL_WIDER, SECURITY_GRANT_EXPIRED_AT_AUTHORING, SECURITY_MASTER_DETAIL_UNGRANTED, SECURITY_OWD_ALIAS, SECURITY_OWD_UNSET, SECURITY_PRIVATE_NO_READSCOPE, SECURITY_ROLE_WORD, SECURITY_WILDCARD_VAMA, SEMANTIC_ROLE_FIELD_UNKNOWN, STYLE_CLASSNAME_TAILWIND, STYLE_NODE_MISSING_ID, STYLE_RESPONSIVE_NO_BASE, STYLE_UNKNOWN_CSS_PROPERTY, STYLE_UNKNOWN_TOKEN, type SecurityFinding, type SecuritySeverity, type SemanticRoleFinding, type SemanticRoleSeverity, type SourceStyleFinding, type SourceStyleSeverity, type StyleFinding, type StyleSeverity, TABLE_COUNT_ONLY, TITLE_FORMAT_RETIRED, TITLE_UNRESOLVABLE, VISIBILITY_ALIAS_DEPRECATED, VISIBILITY_ROOT_MISLAYERED, type VisibilityFinding, type VisibilityLayer, type VisibilityOptions, type VisibilitySeverity, WIDGET_DATASET_UNKNOWN, WIDGET_DIMENSION_UNKNOWN, WIDGET_MEASURE_UNKNOWN, type WidgetBindingFinding, type WidgetBindingSeverity, buildAccessMatrix, diffAccessMatrix, validateApprovalApprovers, validateCapabilityReferences, validateFormLayout, validateJsxPages, validateListViewMode, validatePageSourceStyling, validateReactPageProps, validateReactPages, validateRecordTitle, validateResponsiveStyles, validateSecurityPosture, validateSemanticRoles, validateStackExpressions, validateVisibilityPredicates, validateWidgetBindings };

package/dist/index.d.ts

@@ -359,11 +359,16 @@ declare function validateFormLayout(stack: AnyRec$5): FormLayoutFinding[];
  *
  * - `visibility-alias-deprecated` — a `visibleOn` / `visibility` key in authored
  *   source. Autofix intent: rename the key to `visibleWhen` (same value).
- * - `visibility-root-mislayered` — a runtime view/page visibility predicate
- *   rooted at `data.` (the metadata-editing-form root, ADR-0089 §Context). Runtime
- *   record surfaces bind `record` + `current_user` (pages also expose `page.<var>`),
- *   so a `data.`-rooted predicate here is almost always a wrong-layer paste that
- *   silently never matches.
+ * - `visibility-root-mislayered` — a visibility predicate whose binding root does
+ *   not match its layer (ADR-0089 D3, §Context). The check is **bidirectional**:
+ *   - **runtime** view/page surfaces (`*.view.ts` / `*.page.ts`) bind
+ *     `record` + `current_user` (pages also expose `page.<var>`), so a `data.`-rooted
+ *     predicate here is a wrong-layer paste that silently never matches; and
+ *   - **metadata-editing** forms (`*.form.ts` — the row under edit) bind `data`, so
+ *     a `record.`-rooted predicate there is the same bug in the other direction.
+ *   The layer is supplied by the caller (`opts.layer`, default `'runtime'`): the
+ *   app-lint path (`os validate` / `compile`) always lints runtime surfaces, while a
+ *   file-aware caller linting a `*.form.ts` passes `layer: 'metadata'`.
  *
  * Scope: `views` (form `sections` / legacy `groups`, and their `fields`) and
  * `pages` (`regions[].components[]`). Data-field `visibleWhen` is already covered
@@ -372,6 +377,17 @@ declare function validateFormLayout(stack: AnyRec$5): FormLayoutFinding[];
 declare const VISIBILITY_ALIAS_DEPRECATED = "visibility-alias-deprecated";
 declare const VISIBILITY_ROOT_MISLAYERED = "visibility-root-mislayered";
 type VisibilitySeverity = 'error' | 'warning';
+/**
+ * Which binding environment the linted surface belongs to (ADR-0089 §Context):
+ * - `runtime`  — `*.view.ts` / `*.page.ts`; binds `record` + `current_user` (+ `page`).
+ * - `metadata` — `*.form.ts` metadata-editing forms; binds `data` (the row under edit).
+ */
+type VisibilityLayer = 'runtime' | 'metadata';
+/** Options for {@link validateVisibilityPredicates}. */
+interface VisibilityOptions {
+    /** Binding layer of the surface being linted. Defaults to `'runtime'`. */
+    layer?: VisibilityLayer;
+}
 interface VisibilityFinding {
     /** Always `warning` today — both rules are advisory (see module note). */
     severity: VisibilitySeverity;
@@ -394,8 +410,14 @@ type AnyRec$4 = Record<string, unknown>;
  * `visibleOn` / `visibility` aliases before the schema folds them into
  * `visibleWhen`. Returns findings (empty = clean); all advisory (`warning`) —
  * the caller must never fail the build on these alone.
+ *
+ * The binding-root check is layer-directional (ADR-0089 D3): pass
+ * `opts.layer = 'metadata'` when linting a `*.form.ts` metadata-editing form (so a
+ * `record.`-rooted predicate is flagged), or leave it at the `'runtime'` default for
+ * `*.view.ts` / `*.page.ts` surfaces (so a `data.`-rooted predicate is flagged). The
+ * alias-deprecated check is layer-agnostic.
  */
-declare function validateVisibilityPredicates(stack: AnyRec$4): VisibilityFinding[];
+declare function validateVisibilityPredicates(stack: AnyRec$4, opts?: VisibilityOptions): VisibilityFinding[];
 
 declare const CAPABILITY_REFERENCE_UNKNOWN = "capability-reference-unknown";
 type CapabilityRefSeverity = 'error' | 'warning';
@@ -505,4 +527,4 @@ declare function buildAccessMatrix(stack: AnyRec): AccessMatrix;
  */
 declare function diffAccessMatrix(before: AccessMatrix, after: AccessMatrix): string[];
 
-export { APPROVAL_APPROVER_TYPE_UNKNOWN, APPROVAL_ESCALATION_REASSIGN_NO_TARGET, APPROVAL_ROLE_NOT_MEMBERSHIP_TIER, type ApprovalApproverFinding, type ApprovalApproverSeverity, CAPABILITY_REFERENCE_UNKNOWN, CHART_CONFIG_MISSING, CHART_FIELD_UNKNOWN, type CapabilityRefFinding, type CapabilityRefSeverity, type ExprIssue, FIELD_GROUP_EMPTY, FIELD_GROUP_UNDECLARED, FORM_COLSPAN_ABSOLUTE, FORM_FIELD_UNKNOWN, type FormLayoutFinding, type FormLayoutSeverity, type JsxPageFinding, type JsxPageSeverity, LIST_VIEW_FILTERS_IN_VIEWS_MODE, type ListViewModeFinding, type ListViewModeSeverity, MEASURE_AGGREGATE_INCOHERENT, PAGE_SOURCE_CLASSNAME, type ReactPageFinding, type ReactPageSeverity, type ReactPropFinding, type ReactPropSeverity, type RecordTitleFinding, type RecordTitleSeverity, SECURITY_ANCHOR_HIGH_PRIVILEGE, SECURITY_BOOK_AUDIENCE_UNKNOWN_SET, SECURITY_DELEGATION_MISSING_REASON, SECURITY_EXTERNAL_WIDER, SECURITY_GRANT_EXPIRED_AT_AUTHORING, SECURITY_MASTER_DETAIL_UNGRANTED, SECURITY_OWD_ALIAS, SECURITY_OWD_UNSET, SECURITY_PRIVATE_NO_READSCOPE, SECURITY_ROLE_WORD, SECURITY_WILDCARD_VAMA, SEMANTIC_ROLE_FIELD_UNKNOWN, STYLE_CLASSNAME_TAILWIND, STYLE_NODE_MISSING_ID, STYLE_RESPONSIVE_NO_BASE, STYLE_UNKNOWN_CSS_PROPERTY, STYLE_UNKNOWN_TOKEN, type SecurityFinding, type SecuritySeverity, type SemanticRoleFinding, type SemanticRoleSeverity, type SourceStyleFinding, type SourceStyleSeverity, type StyleFinding, type StyleSeverity, TABLE_COUNT_ONLY, TITLE_FORMAT_RETIRED, TITLE_UNRESOLVABLE, VISIBILITY_ALIAS_DEPRECATED, VISIBILITY_ROOT_MISLAYERED, type VisibilityFinding, type VisibilitySeverity, WIDGET_DATASET_UNKNOWN, WIDGET_DIMENSION_UNKNOWN, WIDGET_MEASURE_UNKNOWN, type WidgetBindingFinding, type WidgetBindingSeverity, buildAccessMatrix, diffAccessMatrix, validateApprovalApprovers, validateCapabilityReferences, validateFormLayout, validateJsxPages, validateListViewMode, validatePageSourceStyling, validateReactPageProps, validateReactPages, validateRecordTitle, validateResponsiveStyles, validateSecurityPosture, validateSemanticRoles, validateStackExpressions, validateVisibilityPredicates, validateWidgetBindings };
+export { APPROVAL_APPROVER_TYPE_UNKNOWN, APPROVAL_ESCALATION_REASSIGN_NO_TARGET, APPROVAL_ROLE_NOT_MEMBERSHIP_TIER, type ApprovalApproverFinding, type ApprovalApproverSeverity, CAPABILITY_REFERENCE_UNKNOWN, CHART_CONFIG_MISSING, CHART_FIELD_UNKNOWN, type CapabilityRefFinding, type CapabilityRefSeverity, type ExprIssue, FIELD_GROUP_EMPTY, FIELD_GROUP_UNDECLARED, FORM_COLSPAN_ABSOLUTE, FORM_FIELD_UNKNOWN, type FormLayoutFinding, type FormLayoutSeverity, type JsxPageFinding, type JsxPageSeverity, LIST_VIEW_FILTERS_IN_VIEWS_MODE, type ListViewModeFinding, type ListViewModeSeverity, MEASURE_AGGREGATE_INCOHERENT, PAGE_SOURCE_CLASSNAME, type ReactPageFinding, type ReactPageSeverity, type ReactPropFinding, type ReactPropSeverity, type RecordTitleFinding, type RecordTitleSeverity, SECURITY_ANCHOR_HIGH_PRIVILEGE, SECURITY_BOOK_AUDIENCE_UNKNOWN_SET, SECURITY_DELEGATION_MISSING_REASON, SECURITY_EXTERNAL_WIDER, SECURITY_GRANT_EXPIRED_AT_AUTHORING, SECURITY_MASTER_DETAIL_UNGRANTED, SECURITY_OWD_ALIAS, SECURITY_OWD_UNSET, SECURITY_PRIVATE_NO_READSCOPE, SECURITY_ROLE_WORD, SECURITY_WILDCARD_VAMA, SEMANTIC_ROLE_FIELD_UNKNOWN, STYLE_CLASSNAME_TAILWIND, STYLE_NODE_MISSING_ID, STYLE_RESPONSIVE_NO_BASE, STYLE_UNKNOWN_CSS_PROPERTY, STYLE_UNKNOWN_TOKEN, type SecurityFinding, type SecuritySeverity, type SemanticRoleFinding, type SemanticRoleSeverity, type SourceStyleFinding, type SourceStyleSeverity, type StyleFinding, type StyleSeverity, TABLE_COUNT_ONLY, TITLE_FORMAT_RETIRED, TITLE_UNRESOLVABLE, VISIBILITY_ALIAS_DEPRECATED, VISIBILITY_ROOT_MISLAYERED, type VisibilityFinding, type VisibilityLayer, type VisibilityOptions, type VisibilitySeverity, WIDGET_DATASET_UNKNOWN, WIDGET_DIMENSION_UNKNOWN, WIDGET_MEASURE_UNKNOWN, type WidgetBindingFinding, type WidgetBindingSeverity, buildAccessMatrix, diffAccessMatrix, validateApprovalApprovers, validateCapabilityReferences, validateFormLayout, validateJsxPages, validateListViewMode, validatePageSourceStyling, validateReactPageProps, validateReactPages, validateRecordTitle, validateResponsiveStyles, validateSecurityPosture, validateSemanticRoles, validateStackExpressions, validateVisibilityPredicates, validateWidgetBindings };

package/dist/index.js

@@ -1212,10 +1212,22 @@ function predicateSource(v) {
   }
   return void 0;
 }
-function usesDataRoot(source) {
-  return /(^|[^.\w$])data\.\w/.test(source);
+function usesRoot(source, root) {
+  return new RegExp(`(^|[^.\\w$])${root}\\.\\w`).test(source);
 }
-function checkElement(el, where, path, findings) {
+var MISLAYER_BY_LAYER = {
+  runtime: {
+    forbiddenRoot: "data",
+    message: "visibility predicate is rooted at `data.` \u2014 that is the metadata-editing-form root (a `*.form.ts` row under edit), not a runtime surface. A runtime view/page predicate that binds `data.` never matches and the element renders unconditionally (ADR-0089).",
+    hint: "Runtime record surfaces bind `record` + `current_user` (pages also expose `page.<var>`). Use e.g. `record.status == 'open'` instead of `data.status == 'open'`."
+  },
+  metadata: {
+    forbiddenRoot: "record",
+    message: "visibility predicate is rooted at `record.` \u2014 that is the runtime record-surface root (a `*.view.ts` / `*.page.ts` live record), not a metadata-editing form. A `*.form.ts` predicate that binds `record.` never matches and the element renders unconditionally (ADR-0089).",
+    hint: "Metadata-editing forms bind `data` (the row under edit). Use e.g. `data.type == 'grid'` instead of `record.type == 'grid'`."
+  }
+};
+function checkElement(el, where, path, layer, findings) {
   for (const alias of ALIASES) {
     if (el[alias] !== void 0) {
       findings.push({
@@ -1230,21 +1242,23 @@ function checkElement(el, where, path, findings) {
   }
   const raw = el[CANONICAL] ?? el.visibleOn ?? el.visibility;
   const source = predicateSource(raw);
-  if (source && usesDataRoot(source)) {
+  const rule = MISLAYER_BY_LAYER[layer];
+  if (source && usesRoot(source, rule.forbiddenRoot)) {
     findings.push({
       severity: "warning",
       rule: VISIBILITY_ROOT_MISLAYERED,
       where,
       path,
-      message: `visibility predicate is rooted at \`data.\` \u2014 that is the metadata-editing-form root (a \`*.form.ts\` row under edit), not a runtime surface. A runtime view/page predicate that binds \`data.\` never matches and the element renders unconditionally (ADR-0089).`,
-      hint: `Runtime record surfaces bind \`record\` + \`current_user\` (pages also expose \`page.<var>\`). Use e.g. \`record.status == 'open'\` instead of \`data.status == 'open'\`.`
+      message: rule.message,
+      hint: rule.hint
     });
   }
 }
 function isFieldObject(entry) {
   return !!entry && typeof entry === "object" && !Array.isArray(entry);
 }
-function validateVisibilityPredicates(stack) {
+function validateVisibilityPredicates(stack, opts = {}) {
+  const layer = opts.layer ?? "runtime";
   const findings = [];
   const views = asArray12(stack.views);
   for (let i = 0; i < views.length; i++) {
@@ -1258,12 +1272,12 @@ function validateVisibilityPredicates(stack) {
         const sec = sections[s];
         if (!sec || typeof sec !== "object") continue;
         const secPath = `views[${i}].${bucket}[${s}]`;
-        checkElement(sec, where, secPath, findings);
+        checkElement(sec, where, secPath, layer, findings);
         const secFields = Array.isArray(sec.fields) ? sec.fields : [];
         for (let f = 0; f < secFields.length; f++) {
           const entry = secFields[f];
           if (isFieldObject(entry)) {
-            checkElement(entry, where, `${secPath}.fields[${f}]`, findings);
+            checkElement(entry, where, `${secPath}.fields[${f}]`, layer, findings);
           }
         }
       }
@@ -1282,7 +1296,7 @@ function validateVisibilityPredicates(stack) {
       for (let c = 0; c < components.length; c++) {
         const comp = components[c];
         if (comp && typeof comp === "object") {
-          checkElement(comp, where, `pages[${i}].regions[${r}].components[${c}]`, findings);
+          checkElement(comp, where, `pages[${i}].regions[${r}].components[${c}]`, layer, findings);
         }
       }
     }
@@ -1318,6 +1332,9 @@ function validateCapabilityReferences(stack) {
   const findings = [];
   if (!stack || typeof stack !== "object") return findings;
   const known = new Set(PLATFORM_CAPABILITY_NAMES);
+  for (const cap of asArray13(stack.capabilities)) {
+    if (typeof cap.name === "string" && cap.name.length > 0) known.add(cap.name);
+  }
   for (const ps of asArray13(stack.permissions)) {
     for (const cap of asCapArray(ps.systemPermissions)) known.add(cap);
   }
@@ -1328,7 +1345,7 @@ function validateCapabilityReferences(stack) {
       if (typeof name === "string" && name.length > 0) known.add(name);
     }
   }
-  const hint = "Fix the capability name, declare it on a permission set\u2019s systemPermissions, ship a sys_capability seed row, or ignore this if the capability is provided by another installed package (references fail closed at runtime).";
+  const hint = "Fix the capability name, define it with defineCapability (stack.capabilities), declare it on a permission set\u2019s systemPermissions, ship a sys_capability seed row, or ignore this if the capability is provided by another installed package (references fail closed at runtime).";
   const flag = (cap, where, path) => {
     if (known.has(cap)) return;
     findings.push({