fix(lint): resolve a dashboard widget's own filter keys and options.sortBy at validate/build

.changeset/widget-filter-sortby-resolution.md

@@ -0,0 +1,62 @@
+---
+'@objectstack/lint': minor
+---
+
+Resolve a dashboard widget's OWN `filter` keys and `options.sortBy` at validate/build
+
+A dashboard widget could filter by a column that does not exist, and order by a name
+it never selected, and `objectstack validate` exited 0 with "Validation passed";
+`build` — the publish gate — wrote the dashboard into `dist/objectstack.json`. The
+widget then rendered **empty**.
+
+The surrounding surface was already covered, which is what made the two misses so
+narrow: `widget-dataset-unknown`, `widget-dimension-unknown`, `widget-measure-unknown`,
+`filter-token-unknown` and `dashboard-filter-field-unknown` all failed both gates on the
+same dashboard. On the very same node, the filter TOKEN was checked and the filter
+COLUMN was not — `filter-token-unknown` fires path-precise at
+`…widgets[4].filter.due_date.$lte`, so the traversal already walked the filter tree and
+already knew the widget's dataset. Only the key resolution was missing. And
+`options.sortBy` was declared-≠-enforced in the plainest way available: the spec states
+the contract in its own prose — *"must be one this widget actually selects"* — and
+nothing enforced it.
+
+Why this class of miss is expensive rather than untidy, in the reporter's words: the
+dashboard it was measured on leads with a "not moving" tile — open work untouched more
+than 14 days — and *"an empty tile is indistinguishable from a healthy team: a missing
+number reads as zero, and zero is the answer the manager is hoping for."* The failure is
+silent in the direction the reader wants to believe.
+
+Three gating rule ids, all at the site that already emits `widget-dataset-unknown` /
+`dashboard-filter-field-unknown`, and all failing **`validate` and `build`** (pinned
+end-to-end, not inferred from the registry entry):
+
+- `widget-filter-field-unknown` — a key of the widget's own `filter` resolves to no
+ column on the bound dataset's object graph. Reported path-precise at
+ `dashboards[i].widgets[j].filter.<key>`, matching `filter-token-unknown`'s precision in
+ that same subtree.
+- `widget-filter-field-not-included` — the key resolves, but its relationship prefix is
+ not declared in the dataset's `include`, so ADR-0021 compiles no join and the column is
+ out of the query's reach.
+- `widget-sortby-unselected` — `options.sortBy` names neither a `dimensions[]` nor a
+ `values[]` entry of the widget. A name the dataset declares but the widget did not
+ select gets its own message, because the fix is a selection rather than a spelling.
+
+**A dotted path through a declared `include` is RESOLVED, not skipped.** A widget's
+`filter` is ANDed into the dataset query as `runtimeFilter`, and that compiled query
+carries only the joins `include` declared — so the same two clauses the dataset rule
+applies one level down (existence, then joinability) apply here. The runtime is not a
+backstop for the second: the dataset compiler's `assertDeclared` runs over `dimensions`
+and `measures` only, never over `runtimeFilter`.
+
+Built on the seams that shipped with the dataset-level sibling rather than a second
+implementation: `walkFilterFieldKeys` (all three authored filter shapes) and
+`indexObjectGraph` / `resolveFieldPath`. Two helpers that were local to that rule —
+`joinablePrefixes` and `describeFieldPathVerdict` — moved into the shared seam and are
+now exported, because both are answers this position asks identically and copying either
+would have been the second implementation the seam exists to prevent.
+
+Minor rather than patch: this narrows the accept set. Metadata that built yesterday and
+names a column or an order that does not exist now fails the build — which is the point.
+The three skips every field-existence rule in this package takes are unchanged, so an
+object the stack does not define, an ADR-0015 `external` object with no readable field
+map, and a registry-injected system column are never reported.

packages/lint/src/index.ts

@@ -24,6 +24,13 @@ export {
  WIDGET_LEGACY_ANALYTICS_UNRENDERABLE,
  DASHBOARD_FILTER_FIELD_UNKNOWN,
  DASHBOARD_FILTER_FIELD_UNPROVISIONED,
+ // [#14148] The widget's OWN two references, at the same site: the keys of its
+ // presentation-scope `filter` (resolved on the #14105 object-graph seam, with
+ // the ADR-0021 `include` clause its `runtimeFilter` really is subject to) and
+ // `options.sortBy` against what the widget selects.
+ WIDGET_FILTER_FIELD_UNKNOWN,
+ WIDGET_FILTER_FIELD_NOT_INCLUDED,
+ WIDGET_SORTBY_UNSELECTED,
 } from './validate-widget-bindings.js';
 export type { WidgetBindingFinding, WidgetBindingSeverity } from './validate-widget-bindings.js';
 
@@ -485,16 +492,26 @@ export type { DatasetRefFinding, DatasetRefSeverity } from './validate-dataset-r
 // positions) must reuse ONE mechanism rather than growing a second hop-walker
 // and a second filter-key reader. Both hold mechanism only — no rule ids, no
 // severities, no findings; the judgement stays with the rule that asks.
+// [#14148] `joinablePrefixes` and `describeFieldPathVerdict` joined them when
+// the widget limb landed: both were local to the dataset rule, and both are
+// answers to questions the widget position asks identically — how ADR-0021
+// expands an `include` into joinable prefixes, and how one verdict reads in
+// prose. Copying either would have been the second implementation this seam
+// exists to prevent, one release after it was written to prevent it.
 export {
  indexObjectGraph,
  resolveFieldPath,
  isUnjudgeable,
+ joinablePrefixes,
+ describeFieldPathVerdict,
  nearestName,
  suggestName,
  listNames,
  RELATIONSHIP_FIELD_TYPES,
 } from './object-graph.js';
-export type { ObjectGraph, GraphObject, GraphField, FieldPathVerdict } from './object-graph.js';
+export type {
+ ObjectGraph, GraphObject, GraphField, FieldPathVerdict, FieldPathAccount,
+} from './object-graph.js';
 export { walkFilterFieldKeys } from './filter-walk.js';
 export type { FilterFieldKey } from './filter-walk.js';
 

packages/lint/src/object-graph.ts

@@ -248,6 +248,89 @@ export function resolveFieldPath(
  return { kind: 'field-unknown', object: current, field: leaf, candidates: obj.names };
 }
 
+/**
+ * The relationship prefixes a document declared as joinable.
+ *
+ * ADR-0021: *"Declaring `a.b` implicitly includes the intermediate `a`."* So
+ * every PREFIX of every declared path is joinable, not only the paths as
+ * written — which is why this expands rather than reading `include` verbatim.
+ *
+ * Here rather than in a rule because the SAME `include` governs positions two
+ * different rules judge: a dataset's own `dimensions[].field` / `measures[].field`
+ * / filter keys (#14105), and a dashboard widget's `filter` keys (#14148), whose
+ * condition is ANDed into that same dataset's compiled query as `runtimeFilter`.
+ * Two copies of the prefix expansion would let the two positions drift apart on
+ * a clause that is one sentence of one ADR.
+ */
+export function joinablePrefixes(include: unknown): ReadonlySet<string> {
+ const prefixes = new Set<string>();
+ if (!Array.isArray(include)) return prefixes;
+ for (const entry of include) {
+ if (typeof entry !== 'string' || !entry) continue;
+ const segments = entry.split('.');
+ for (let i = 1; i <= segments.length; i++) {
+ prefixes.add(segments.slice(0, i).join('.'));
+ }
+ }
+ return prefixes;
+}
+
+/** The two halves of a rendered verdict: the finding's message, and its detail. */
+export interface FieldPathAccount {
+ /** What is wrong, in prose, carrying the "did you mean" when there is one. */
+ message: string;
+ /** The supporting field list, for the finding's hint. */
+ detail: string;
+}
+
+/**
+ * Turn a resolution verdict into the message half of an existence finding, or
+ * `undefined` when the verdict is one no rule may report.
+ *
+ * Shared by every position that resolves a field PATH — a dataset dimension, a
+ * measure, a dataset filter key (#14105), a widget filter key (#14148) — so
+ * they cannot drift into N different accounts of the same miss. The caller
+ * supplies `subject` (how the position is named in prose) and owns the rule id,
+ * the severity, the path and the hint's prescription; this function holds none
+ * of them, matching the rest of this module.
+ */
+export function describeFieldPathVerdict(
+ verdict: FieldPathVerdict,
+ path: string,
+ subject: string,
+): FieldPathAccount | undefined {
+ switch (verdict.kind) {
+ case 'ok':
+ case 'unknowable':
+ case 'hop-untargeted':
+ return undefined;
+ case 'hop-unknown':
+ return {
+ message:
+ `${subject} "${path}" traverses "${verdict.segment}", which is not a field on object ` +
+ `"${verdict.object}".${suggestName(verdict.segment, verdict.candidates)}`,
+ detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
+ };
+ case 'hop-not-relationship':
+ return {
+ message:
+ `${subject} "${path}" traverses "${verdict.segment}", which is a` +
+ `${verdict.type ? ` \`${verdict.type}\`` : 'n ordinary'} field on object ` +
+ `"${verdict.object}" and not a relationship — there is nothing to join through.`,
+ detail:
+ `Only ${[...RELATIONSHIP_FIELD_TYPES].sort().join(' / ')} fields are traversable ` +
+ `(ADR-0021 derives every join from the object graph; you never write an ON clause).`,
+ };
+ case 'field-unknown':
+ return {
+ message:
+ `${subject} "${path}" is not a field on object "${verdict.object}".` +
+ `${suggestName(verdict.field, verdict.candidates)}`,
+ detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
+ };
+ }
+}
+
 /**
  * True when the verdict is one no rule may report — the graph could not answer.
  * Callers spell the skip through this predicate rather than re-listing the

packages/lint/src/validate-dataset-references.ts

@@ -118,12 +118,11 @@
 import { walkFilterFieldKeys } from './filter-walk.js';
 import {
  RELATIONSHIP_FIELD_TYPES,
+ describeFieldPathVerdict,
  indexObjectGraph,
  isUnjudgeable,
-listNames,
+joinablePrefixes,
  resolveFieldPath,
- suggestName,
- type FieldPathVerdict,
  type ObjectGraph,
 } from './object-graph.js';
 
@@ -172,72 +171,6 @@ function asArray(v: unknown): AnyRec[] {
  return [];
 }
 
-/**
- * The relationship prefixes a dataset declared as joinable.
- *
- * ADR-0021: *"Declaring `a.b` implicitly includes the intermediate `a`."* So
- * every PREFIX of every declared path is joinable, not only the paths as
- * written — which is why this expands rather than reading `include` verbatim.
- */
-function joinablePrefixes(include: unknown): ReadonlySet<string> {
- const prefixes = new Set<string>();
- if (!Array.isArray(include)) return prefixes;
- for (const entry of include) {
- if (typeof entry !== 'string' || !entry) continue;
- const segments = entry.split('.');
- for (let i = 1; i <= segments.length; i++) {
- prefixes.add(segments.slice(0, i).join('.'));
- }
- }
- return prefixes;
-}
-
-/**
- * Turn a resolution verdict into the message half of an existence finding, or
- * `undefined` when the verdict is one no rule may report.
- *
- * Shared by the three positions that resolve a field PATH (dimension, measure,
- * filter key) so they cannot drift into three different accounts of the same
- * miss. The caller supplies `subject` — how the position is named in prose —
- * and owns the rule id, the path and the hint's prescription.
- */
-function existenceMessage(
- verdict: FieldPathVerdict,
- path: string,
- subject: string,
-): { message: string; detail: string } | undefined {
- switch (verdict.kind) {
- case 'ok':
- case 'unknowable':
- case 'hop-untargeted':
- return undefined;
- case 'hop-unknown':
- return {
- message:
- `${subject} "${path}" traverses "${verdict.segment}", which is not a field on object ` +
- `"${verdict.object}".${suggestName(verdict.segment, verdict.candidates)}`,
- detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
- };
- case 'hop-not-relationship':
- return {
- message:
- `${subject} "${path}" traverses "${verdict.segment}", which is a` +
- `${verdict.type ? ` \`${verdict.type}\`` : 'n ordinary'} field on object ` +
- `"${verdict.object}" and not a relationship — there is nothing to join through.`,
- detail:
- `Only ${[...RELATIONSHIP_FIELD_TYPES].sort().join(' / ')} fields are traversable ` +
- `(ADR-0021 derives every join from the object graph; you never write an ON clause).`,
- };
- case 'field-unknown':
- return {
- message:
- `${subject} "${path}" is not a field on object "${verdict.object}".` +
- `${suggestName(verdict.field, verdict.candidates)}`,
- detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
- };
- }
-}
-
 /** The shared consequence sentence — why an unresolved path is not merely inert. */
 const SILENT_EMPTY =
  'The path is compiled into the analytics query as written, so it addresses a column ' +
@@ -309,7 +242,7 @@ export function validateDatasetReferences(stack: AnyRec): DatasetRefFinding[] {
  return;
  }
 
- const account = existenceMessage(verdict, entry, `include[${ii}]`);
+ const account = describeFieldPathVerdict(verdict, entry, `include[${ii}]`);
  if (!account) return;
  findings.push({
  severity: 'error',
@@ -342,7 +275,7 @@ export function validateDatasetReferences(stack: AnyRec): DatasetRefFinding[] {
  const verdict = resolveFieldPath(graph, object, written);
  if (isUnjudgeable(verdict) || !verdict) return;
 
- const account = existenceMessage(verdict, written, subject);
+ const account = describeFieldPathVerdict(verdict, written, subject);
  if (account) {
  findings.push({
  severity: 'error',

.changeset/widget-filter-sortby-resolution.md

@@ -0,0 +1,62 @@
+---
+'@objectstack/lint': minor
+---
+
+Resolve a dashboard widget's OWN `filter` keys and `options.sortBy` at validate/build
+
+A dashboard widget could filter by a column that does not exist, and order by a name
+it never selected, and `objectstack validate` exited 0 with "Validation passed";
+`build` — the publish gate — wrote the dashboard into `dist/objectstack.json`. The
+widget then rendered **empty**.
+
+The surrounding surface was already covered, which is what made the two misses so
+narrow: `widget-dataset-unknown`, `widget-dimension-unknown`, `widget-measure-unknown`,
+`filter-token-unknown` and `dashboard-filter-field-unknown` all failed both gates on the
+same dashboard. On the very same node, the filter TOKEN was checked and the filter
+COLUMN was not — `filter-token-unknown` fires path-precise at
+`…widgets[4].filter.due_date.$lte`, so the traversal already walked the filter tree and
+already knew the widget's dataset. Only the key resolution was missing. And
+`options.sortBy` was declared-≠-enforced in the plainest way available: the spec states
+the contract in its own prose — *"must be one this widget actually selects"* — and
+nothing enforced it.
+
+Why this class of miss is expensive rather than untidy, in the reporter's words: the
+dashboard it was measured on leads with a "not moving" tile — open work untouched more
+than 14 days — and *"an empty tile is indistinguishable from a healthy team: a missing
+number reads as zero, and zero is the answer the manager is hoping for."* The failure is
+silent in the direction the reader wants to believe.
+
+Three gating rule ids, all at the site that already emits `widget-dataset-unknown` /
+`dashboard-filter-field-unknown`, and all failing **`validate` and `build`** (pinned
+end-to-end, not inferred from the registry entry):
+
+- `widget-filter-field-unknown` — a key of the widget's own `filter` resolves to no
+ column on the bound dataset's object graph. Reported path-precise at
+ `dashboards[i].widgets[j].filter.<key>`, matching `filter-token-unknown`'s precision in
+ that same subtree.
+- `widget-filter-field-not-included` — the key resolves, but its relationship prefix is
+ not declared in the dataset's `include`, so ADR-0021 compiles no join and the column is
+ out of the query's reach.
+- `widget-sortby-unselected` — `options.sortBy` names neither a `dimensions[]` nor a
+ `values[]` entry of the widget. A name the dataset declares but the widget did not
+ select gets its own message, because the fix is a selection rather than a spelling.
+
+**A dotted path through a declared `include` is RESOLVED, not skipped.** A widget's
+`filter` is ANDed into the dataset query as `runtimeFilter`, and that compiled query
+carries only the joins `include` declared — so the same two clauses the dataset rule
+applies one level down (existence, then joinability) apply here. The runtime is not a
+backstop for the second: the dataset compiler's `assertDeclared` runs over `dimensions`
+and `measures` only, never over `runtimeFilter`.
+
+Built on the seams that shipped with the dataset-level sibling rather than a second
+implementation: `walkFilterFieldKeys` (all three authored filter shapes) and
+`indexObjectGraph` / `resolveFieldPath`. Two helpers that were local to that rule —
+`joinablePrefixes` and `describeFieldPathVerdict` — moved into the shared seam and are
+now exported, because both are answers this position asks identically and copying either
+would have been the second implementation the seam exists to prevent.
+
+Minor rather than patch: this narrows the accept set. Metadata that built yesterday and
+names a column or an order that does not exist now fails the build — which is the point.
+The three skips every field-existence rule in this package takes are unchanged, so an
+object the stack does not define, an ADR-0015 `external` object with no readable field
+map, and a registry-injected system column are never reported.

packages/lint/src/index.ts

@@ -24,6 +24,13 @@ export {
  WIDGET_LEGACY_ANALYTICS_UNRENDERABLE,
  DASHBOARD_FILTER_FIELD_UNKNOWN,
  DASHBOARD_FILTER_FIELD_UNPROVISIONED,
+ // [#14148] The widget's OWN two references, at the same site: the keys of its
+ // presentation-scope `filter` (resolved on the #14105 object-graph seam, with
+ // the ADR-0021 `include` clause its `runtimeFilter` really is subject to) and
+ // `options.sortBy` against what the widget selects.
+ WIDGET_FILTER_FIELD_UNKNOWN,
+ WIDGET_FILTER_FIELD_NOT_INCLUDED,
+ WIDGET_SORTBY_UNSELECTED,
 } from './validate-widget-bindings.js';
 export type { WidgetBindingFinding, WidgetBindingSeverity } from './validate-widget-bindings.js';
 
@@ -485,16 +492,26 @@ export type { DatasetRefFinding, DatasetRefSeverity } from './validate-dataset-r
 // positions) must reuse ONE mechanism rather than growing a second hop-walker
 // and a second filter-key reader. Both hold mechanism only — no rule ids, no
 // severities, no findings; the judgement stays with the rule that asks.
+// [#14148] `joinablePrefixes` and `describeFieldPathVerdict` joined them when
+// the widget limb landed: both were local to the dataset rule, and both are
+// answers to questions the widget position asks identically — how ADR-0021
+// expands an `include` into joinable prefixes, and how one verdict reads in
+// prose. Copying either would have been the second implementation this seam
+// exists to prevent, one release after it was written to prevent it.
 export {
  indexObjectGraph,
  resolveFieldPath,
  isUnjudgeable,
+ joinablePrefixes,
+ describeFieldPathVerdict,
  nearestName,
  suggestName,
  listNames,
  RELATIONSHIP_FIELD_TYPES,
 } from './object-graph.js';
-export type { ObjectGraph, GraphObject, GraphField, FieldPathVerdict } from './object-graph.js';
+export type {
+ ObjectGraph, GraphObject, GraphField, FieldPathVerdict, FieldPathAccount,
+} from './object-graph.js';
 export { walkFilterFieldKeys } from './filter-walk.js';
 export type { FilterFieldKey } from './filter-walk.js';
 

packages/lint/src/object-graph.ts

@@ -248,6 +248,89 @@ export function resolveFieldPath(
  return { kind: 'field-unknown', object: current, field: leaf, candidates: obj.names };
 }
 
+/**
+ * The relationship prefixes a document declared as joinable.
+ *
+ * ADR-0021: *"Declaring `a.b` implicitly includes the intermediate `a`."* So
+ * every PREFIX of every declared path is joinable, not only the paths as
+ * written — which is why this expands rather than reading `include` verbatim.
+ *
+ * Here rather than in a rule because the SAME `include` governs positions two
+ * different rules judge: a dataset's own `dimensions[].field` / `measures[].field`
+ * / filter keys (#14105), and a dashboard widget's `filter` keys (#14148), whose
+ * condition is ANDed into that same dataset's compiled query as `runtimeFilter`.
+ * Two copies of the prefix expansion would let the two positions drift apart on
+ * a clause that is one sentence of one ADR.
+ */
+export function joinablePrefixes(include: unknown): ReadonlySet<string> {
+ const prefixes = new Set<string>();
+ if (!Array.isArray(include)) return prefixes;
+ for (const entry of include) {
+ if (typeof entry !== 'string' || !entry) continue;
+ const segments = entry.split('.');
+ for (let i = 1; i <= segments.length; i++) {
+ prefixes.add(segments.slice(0, i).join('.'));
+ }
+ }
+ return prefixes;
+}
+
+/** The two halves of a rendered verdict: the finding's message, and its detail. */
+export interface FieldPathAccount {
+ /** What is wrong, in prose, carrying the "did you mean" when there is one. */
+ message: string;
+ /** The supporting field list, for the finding's hint. */
+ detail: string;
+}
+
+/**
+ * Turn a resolution verdict into the message half of an existence finding, or
+ * `undefined` when the verdict is one no rule may report.
+ *
+ * Shared by every position that resolves a field PATH — a dataset dimension, a
+ * measure, a dataset filter key (#14105), a widget filter key (#14148) — so
+ * they cannot drift into N different accounts of the same miss. The caller
+ * supplies `subject` (how the position is named in prose) and owns the rule id,
+ * the severity, the path and the hint's prescription; this function holds none
+ * of them, matching the rest of this module.
+ */
+export function describeFieldPathVerdict(
+ verdict: FieldPathVerdict,
+ path: string,
+ subject: string,
+): FieldPathAccount | undefined {
+ switch (verdict.kind) {
+ case 'ok':
+ case 'unknowable':
+ case 'hop-untargeted':
+ return undefined;
+ case 'hop-unknown':
+ return {
+ message:
+ `${subject} "${path}" traverses "${verdict.segment}", which is not a field on object ` +
+ `"${verdict.object}".${suggestName(verdict.segment, verdict.candidates)}`,
+ detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
+ };
+ case 'hop-not-relationship':
+ return {
+ message:
+ `${subject} "${path}" traverses "${verdict.segment}", which is a` +
+ `${verdict.type ? ` \`${verdict.type}\`` : 'n ordinary'} field on object ` +
+ `"${verdict.object}" and not a relationship — there is nothing to join through.`,
+ detail:
+ `Only ${[...RELATIONSHIP_FIELD_TYPES].sort().join(' / ')} fields are traversable ` +
+ `(ADR-0021 derives every join from the object graph; you never write an ON clause).`,
+ };
+ case 'field-unknown':
+ return {
+ message:
+ `${subject} "${path}" is not a field on object "${verdict.object}".` +
+ `${suggestName(verdict.field, verdict.candidates)}`,
+ detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
+ };
+ }
+}
+
 /**
  * True when the verdict is one no rule may report — the graph could not answer.
  * Callers spell the skip through this predicate rather than re-listing the

packages/lint/src/validate-dataset-references.ts

@@ -118,12 +118,11 @@
 import { walkFilterFieldKeys } from './filter-walk.js';
 import {
  RELATIONSHIP_FIELD_TYPES,
+ describeFieldPathVerdict,
  indexObjectGraph,
  isUnjudgeable,
-listNames,
+joinablePrefixes,
  resolveFieldPath,
- suggestName,
- type FieldPathVerdict,
  type ObjectGraph,
 } from './object-graph.js';
 
@@ -172,72 +171,6 @@ function asArray(v: unknown): AnyRec[] {
  return [];
 }
 
-/**
- * The relationship prefixes a dataset declared as joinable.
- *
- * ADR-0021: *"Declaring `a.b` implicitly includes the intermediate `a`."* So
- * every PREFIX of every declared path is joinable, not only the paths as
- * written — which is why this expands rather than reading `include` verbatim.
- */
-function joinablePrefixes(include: unknown): ReadonlySet<string> {
- const prefixes = new Set<string>();
- if (!Array.isArray(include)) return prefixes;
- for (const entry of include) {
- if (typeof entry !== 'string' || !entry) continue;
- const segments = entry.split('.');
- for (let i = 1; i <= segments.length; i++) {
- prefixes.add(segments.slice(0, i).join('.'));
- }
- }
- return prefixes;
-}
-
-/**
- * Turn a resolution verdict into the message half of an existence finding, or
- * `undefined` when the verdict is one no rule may report.
- *
- * Shared by the three positions that resolve a field PATH (dimension, measure,
- * filter key) so they cannot drift into three different accounts of the same
- * miss. The caller supplies `subject` — how the position is named in prose —
- * and owns the rule id, the path and the hint's prescription.
- */
-function existenceMessage(
- verdict: FieldPathVerdict,
- path: string,
- subject: string,
-): { message: string; detail: string } | undefined {
- switch (verdict.kind) {
- case 'ok':
- case 'unknowable':
- case 'hop-untargeted':
- return undefined;
- case 'hop-unknown':
- return {
- message:
- `${subject} "${path}" traverses "${verdict.segment}", which is not a field on object ` +
- `"${verdict.object}".${suggestName(verdict.segment, verdict.candidates)}`,
- detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
- };
- case 'hop-not-relationship':
- return {
- message:
- `${subject} "${path}" traverses "${verdict.segment}", which is a` +
- `${verdict.type ? ` \`${verdict.type}\`` : 'n ordinary'} field on object ` +
- `"${verdict.object}" and not a relationship — there is nothing to join through.`,
- detail:
- `Only ${[...RELATIONSHIP_FIELD_TYPES].sort().join(' / ')} fields are traversable ` +
- `(ADR-0021 derives every join from the object graph; you never write an ON clause).`,
- };
- case 'field-unknown':
- return {
- message:
- `${subject} "${path}" is not a field on object "${verdict.object}".` +
- `${suggestName(verdict.field, verdict.candidates)}`,
- detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
- };
- }
-}
-
 /** The shared consequence sentence — why an unresolved path is not merely inert. */
 const SILENT_EMPTY =
  'The path is compiled into the analytics query as written, so it addresses a column ' +
@@ -309,7 +242,7 @@ export function validateDatasetReferences(stack: AnyRec): DatasetRefFinding[] {
  return;
  }
 
- const account = existenceMessage(verdict, entry, `include[${ii}]`);
+ const account = describeFieldPathVerdict(verdict, entry, `include[${ii}]`);
  if (!account) return;
  findings.push({
  severity: 'error',
@@ -342,7 +275,7 @@ export function validateDatasetReferences(stack: AnyRec): DatasetRefFinding[] {
  const verdict = resolveFieldPath(graph, object, written);
  if (isUnjudgeable(verdict) || !verdict) return;
 
- const account = existenceMessage(verdict, written, subject);
+ const account = describeFieldPathVerdict(verdict, written, subject);
  if (account) {
  findings.push({
  severity: 'error',

.changeset/widget-filter-sortby-resolution.md

@@ -0,0 +1,62 @@
+---
+'@objectstack/lint': minor
+---
+
+Resolve a dashboard widget's OWN `filter` keys and `options.sortBy` at validate/build
+
+A dashboard widget could filter by a column that does not exist, and order by a name
+it never selected, and `objectstack validate` exited 0 with "Validation passed";
+`build` — the publish gate — wrote the dashboard into `dist/objectstack.json`. The
+widget then rendered **empty**.
+
+The surrounding surface was already covered, which is what made the two misses so
+narrow: `widget-dataset-unknown`, `widget-dimension-unknown`, `widget-measure-unknown`,
+`filter-token-unknown` and `dashboard-filter-field-unknown` all failed both gates on the
+same dashboard. On the very same node, the filter TOKEN was checked and the filter
+COLUMN was not — `filter-token-unknown` fires path-precise at
+`…widgets[4].filter.due_date.$lte`, so the traversal already walked the filter tree and
+already knew the widget's dataset. Only the key resolution was missing. And
+`options.sortBy` was declared-≠-enforced in the plainest way available: the spec states
+the contract in its own prose — *"must be one this widget actually selects"* — and
+nothing enforced it.
+
+Why this class of miss is expensive rather than untidy, in the reporter's words: the
+dashboard it was measured on leads with a "not moving" tile — open work untouched more
+than 14 days — and *"an empty tile is indistinguishable from a healthy team: a missing
+number reads as zero, and zero is the answer the manager is hoping for."* The failure is
+silent in the direction the reader wants to believe.
+
+Three gating rule ids, all at the site that already emits `widget-dataset-unknown` /
+`dashboard-filter-field-unknown`, and all failing **`validate` and `build`** (pinned
+end-to-end, not inferred from the registry entry):
+
+- `widget-filter-field-unknown` — a key of the widget's own `filter` resolves to no
+ column on the bound dataset's object graph. Reported path-precise at
+ `dashboards[i].widgets[j].filter.<key>`, matching `filter-token-unknown`'s precision in
+ that same subtree.
+- `widget-filter-field-not-included` — the key resolves, but its relationship prefix is
+ not declared in the dataset's `include`, so ADR-0021 compiles no join and the column is
+ out of the query's reach.
+- `widget-sortby-unselected` — `options.sortBy` names neither a `dimensions[]` nor a
+ `values[]` entry of the widget. A name the dataset declares but the widget did not
+ select gets its own message, because the fix is a selection rather than a spelling.
+
+**A dotted path through a declared `include` is RESOLVED, not skipped.** A widget's
+`filter` is ANDed into the dataset query as `runtimeFilter`, and that compiled query
+carries only the joins `include` declared — so the same two clauses the dataset rule
+applies one level down (existence, then joinability) apply here. The runtime is not a
+backstop for the second: the dataset compiler's `assertDeclared` runs over `dimensions`
+and `measures` only, never over `runtimeFilter`.
+
+Built on the seams that shipped with the dataset-level sibling rather than a second
+implementation: `walkFilterFieldKeys` (all three authored filter shapes) and
+`indexObjectGraph` / `resolveFieldPath`. Two helpers that were local to that rule —
+`joinablePrefixes` and `describeFieldPathVerdict` — moved into the shared seam and are
+now exported, because both are answers this position asks identically and copying either
+would have been the second implementation the seam exists to prevent.
+
+Minor rather than patch: this narrows the accept set. Metadata that built yesterday and
+names a column or an order that does not exist now fails the build — which is the point.
+The three skips every field-existence rule in this package takes are unchanged, so an
+object the stack does not define, an ADR-0015 `external` object with no readable field
+map, and a registry-injected system column are never reported.

packages/lint/src/index.ts

@@ -24,6 +24,13 @@ export {
  WIDGET_LEGACY_ANALYTICS_UNRENDERABLE,
  DASHBOARD_FILTER_FIELD_UNKNOWN,
  DASHBOARD_FILTER_FIELD_UNPROVISIONED,
+ // [#14148] The widget's OWN two references, at the same site: the keys of its
+ // presentation-scope `filter` (resolved on the #14105 object-graph seam, with
+ // the ADR-0021 `include` clause its `runtimeFilter` really is subject to) and
+ // `options.sortBy` against what the widget selects.
+ WIDGET_FILTER_FIELD_UNKNOWN,
+ WIDGET_FILTER_FIELD_NOT_INCLUDED,
+ WIDGET_SORTBY_UNSELECTED,
 } from './validate-widget-bindings.js';
 export type { WidgetBindingFinding, WidgetBindingSeverity } from './validate-widget-bindings.js';
 
@@ -485,16 +492,26 @@ export type { DatasetRefFinding, DatasetRefSeverity } from './validate-dataset-r
 // positions) must reuse ONE mechanism rather than growing a second hop-walker
 // and a second filter-key reader. Both hold mechanism only — no rule ids, no
 // severities, no findings; the judgement stays with the rule that asks.
+// [#14148] `joinablePrefixes` and `describeFieldPathVerdict` joined them when
+// the widget limb landed: both were local to the dataset rule, and both are
+// answers to questions the widget position asks identically — how ADR-0021
+// expands an `include` into joinable prefixes, and how one verdict reads in
+// prose. Copying either would have been the second implementation this seam
+// exists to prevent, one release after it was written to prevent it.
 export {
  indexObjectGraph,
  resolveFieldPath,
  isUnjudgeable,
+ joinablePrefixes,
+ describeFieldPathVerdict,
  nearestName,
  suggestName,
  listNames,
  RELATIONSHIP_FIELD_TYPES,
 } from './object-graph.js';
-export type { ObjectGraph, GraphObject, GraphField, FieldPathVerdict } from './object-graph.js';
+export type {
+ ObjectGraph, GraphObject, GraphField, FieldPathVerdict, FieldPathAccount,
+} from './object-graph.js';
 export { walkFilterFieldKeys } from './filter-walk.js';
 export type { FilterFieldKey } from './filter-walk.js';
 

packages/lint/src/object-graph.ts

@@ -248,6 +248,89 @@ export function resolveFieldPath(
  return { kind: 'field-unknown', object: current, field: leaf, candidates: obj.names };
 }
 
+/**
+ * The relationship prefixes a document declared as joinable.
+ *
+ * ADR-0021: *"Declaring `a.b` implicitly includes the intermediate `a`."* So
+ * every PREFIX of every declared path is joinable, not only the paths as
+ * written — which is why this expands rather than reading `include` verbatim.
+ *
+ * Here rather than in a rule because the SAME `include` governs positions two
+ * different rules judge: a dataset's own `dimensions[].field` / `measures[].field`
+ * / filter keys (#14105), and a dashboard widget's `filter` keys (#14148), whose
+ * condition is ANDed into that same dataset's compiled query as `runtimeFilter`.
+ * Two copies of the prefix expansion would let the two positions drift apart on
+ * a clause that is one sentence of one ADR.
+ */
+export function joinablePrefixes(include: unknown): ReadonlySet<string> {
+ const prefixes = new Set<string>();
+ if (!Array.isArray(include)) return prefixes;
+ for (const entry of include) {
+ if (typeof entry !== 'string' || !entry) continue;
+ const segments = entry.split('.');
+ for (let i = 1; i <= segments.length; i++) {
+ prefixes.add(segments.slice(0, i).join('.'));
+ }
+ }
+ return prefixes;
+}
+
+/** The two halves of a rendered verdict: the finding's message, and its detail. */
+export interface FieldPathAccount {
+ /** What is wrong, in prose, carrying the "did you mean" when there is one. */
+ message: string;
+ /** The supporting field list, for the finding's hint. */
+ detail: string;
+}
+
+/**
+ * Turn a resolution verdict into the message half of an existence finding, or
+ * `undefined` when the verdict is one no rule may report.
+ *
+ * Shared by every position that resolves a field PATH — a dataset dimension, a
+ * measure, a dataset filter key (#14105), a widget filter key (#14148) — so
+ * they cannot drift into N different accounts of the same miss. The caller
+ * supplies `subject` (how the position is named in prose) and owns the rule id,
+ * the severity, the path and the hint's prescription; this function holds none
+ * of them, matching the rest of this module.
+ */
+export function describeFieldPathVerdict(
+ verdict: FieldPathVerdict,
+ path: string,
+ subject: string,
+): FieldPathAccount | undefined {
+ switch (verdict.kind) {
+ case 'ok':
+ case 'unknowable':
+ case 'hop-untargeted':
+ return undefined;
+ case 'hop-unknown':
+ return {
+ message:
+ `${subject} "${path}" traverses "${verdict.segment}", which is not a field on object ` +
+ `"${verdict.object}".${suggestName(verdict.segment, verdict.candidates)}`,
+ detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
+ };
+ case 'hop-not-relationship':
+ return {
+ message:
+ `${subject} "${path}" traverses "${verdict.segment}", which is a` +
+ `${verdict.type ? ` \`${verdict.type}\`` : 'n ordinary'} field on object ` +
+ `"${verdict.object}" and not a relationship — there is nothing to join through.`,
+ detail:
+ `Only ${[...RELATIONSHIP_FIELD_TYPES].sort().join(' / ')} fields are traversable ` +
+ `(ADR-0021 derives every join from the object graph; you never write an ON clause).`,
+ };
+ case 'field-unknown':
+ return {
+ message:
+ `${subject} "${path}" is not a field on object "${verdict.object}".` +
+ `${suggestName(verdict.field, verdict.candidates)}`,
+ detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
+ };
+ }
+}
+
 /**
  * True when the verdict is one no rule may report — the graph could not answer.
  * Callers spell the skip through this predicate rather than re-listing the

packages/lint/src/validate-dataset-references.ts

@@ -118,12 +118,11 @@
 import { walkFilterFieldKeys } from './filter-walk.js';
 import {
  RELATIONSHIP_FIELD_TYPES,
+ describeFieldPathVerdict,
  indexObjectGraph,
  isUnjudgeable,
-listNames,
+joinablePrefixes,
  resolveFieldPath,
- suggestName,
- type FieldPathVerdict,
  type ObjectGraph,
 } from './object-graph.js';
 
@@ -172,72 +171,6 @@ function asArray(v: unknown): AnyRec[] {
  return [];
 }
 
-/**
- * The relationship prefixes a dataset declared as joinable.
- *
- * ADR-0021: *"Declaring `a.b` implicitly includes the intermediate `a`."* So
- * every PREFIX of every declared path is joinable, not only the paths as
- * written — which is why this expands rather than reading `include` verbatim.
- */
-function joinablePrefixes(include: unknown): ReadonlySet<string> {
- const prefixes = new Set<string>();
- if (!Array.isArray(include)) return prefixes;
- for (const entry of include) {
- if (typeof entry !== 'string' || !entry) continue;
- const segments = entry.split('.');
- for (let i = 1; i <= segments.length; i++) {
- prefixes.add(segments.slice(0, i).join('.'));
- }
- }
- return prefixes;
-}
-
-/**
- * Turn a resolution verdict into the message half of an existence finding, or
- * `undefined` when the verdict is one no rule may report.
- *
- * Shared by the three positions that resolve a field PATH (dimension, measure,
- * filter key) so they cannot drift into three different accounts of the same
- * miss. The caller supplies `subject` — how the position is named in prose —
- * and owns the rule id, the path and the hint's prescription.
- */
-function existenceMessage(
- verdict: FieldPathVerdict,
- path: string,
- subject: string,
-): { message: string; detail: string } | undefined {
- switch (verdict.kind) {
- case 'ok':
- case 'unknowable':
- case 'hop-untargeted':
- return undefined;
- case 'hop-unknown':
- return {
- message:
- `${subject} "${path}" traverses "${verdict.segment}", which is not a field on object ` +
- `"${verdict.object}".${suggestName(verdict.segment, verdict.candidates)}`,
- detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
- };
- case 'hop-not-relationship':
- return {
- message:
- `${subject} "${path}" traverses "${verdict.segment}", which is a` +
- `${verdict.type ? ` \`${verdict.type}\`` : 'n ordinary'} field on object ` +
- `"${verdict.object}" and not a relationship — there is nothing to join through.`,
- detail:
- `Only ${[...RELATIONSHIP_FIELD_TYPES].sort().join(' / ')} fields are traversable ` +
- `(ADR-0021 derives every join from the object graph; you never write an ON clause).`,
- };
- case 'field-unknown':
- return {
- message:
- `${subject} "${path}" is not a field on object "${verdict.object}".` +
- `${suggestName(verdict.field, verdict.candidates)}`,
- detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
- };
- }
-}
-
 /** The shared consequence sentence — why an unresolved path is not merely inert. */
 const SILENT_EMPTY =
  'The path is compiled into the analytics query as written, so it addresses a column ' +
@@ -309,7 +242,7 @@ export function validateDatasetReferences(stack: AnyRec): DatasetRefFinding[] {
  return;
  }
 
- const account = existenceMessage(verdict, entry, `include[${ii}]`);
+ const account = describeFieldPathVerdict(verdict, entry, `include[${ii}]`);
  if (!account) return;
  findings.push({
  severity: 'error',
@@ -342,7 +275,7 @@ export function validateDatasetReferences(stack: AnyRec): DatasetRefFinding[] {
  const verdict = resolveFieldPath(graph, object, written);
  if (isUnjudgeable(verdict) || !verdict) return;
 
- const account = existenceMessage(verdict, written, subject);
+ const account = describeFieldPathVerdict(verdict, written, subject);
  if (account) {
  findings.push({
  severity: 'error',

.changeset/widget-filter-sortby-resolution.md

@@ -0,0 +1,62 @@
+---
+'@objectstack/lint': minor
+---
+
+Resolve a dashboard widget's OWN `filter` keys and `options.sortBy` at validate/build
+
+A dashboard widget could filter by a column that does not exist, and order by a name
+it never selected, and `objectstack validate` exited 0 with "Validation passed";
+`build` — the publish gate — wrote the dashboard into `dist/objectstack.json`. The
+widget then rendered **empty**.
+
+The surrounding surface was already covered, which is what made the two misses so
+narrow: `widget-dataset-unknown`, `widget-dimension-unknown`, `widget-measure-unknown`,
+`filter-token-unknown` and `dashboard-filter-field-unknown` all failed both gates on the
+same dashboard. On the very same node, the filter TOKEN was checked and the filter
+COLUMN was not — `filter-token-unknown` fires path-precise at
+`…widgets[4].filter.due_date.$lte`, so the traversal already walked the filter tree and
+already knew the widget's dataset. Only the key resolution was missing. And
+`options.sortBy` was declared-≠-enforced in the plainest way available: the spec states
+the contract in its own prose — *"must be one this widget actually selects"* — and
+nothing enforced it.
+
+Why this class of miss is expensive rather than untidy, in the reporter's words: the
+dashboard it was measured on leads with a "not moving" tile — open work untouched more
+than 14 days — and *"an empty tile is indistinguishable from a healthy team: a missing
+number reads as zero, and zero is the answer the manager is hoping for."* The failure is
+silent in the direction the reader wants to believe.
+
+Three gating rule ids, all at the site that already emits `widget-dataset-unknown` /
+`dashboard-filter-field-unknown`, and all failing **`validate` and `build`** (pinned
+end-to-end, not inferred from the registry entry):
+
+- `widget-filter-field-unknown` — a key of the widget's own `filter` resolves to no
+ column on the bound dataset's object graph. Reported path-precise at
+ `dashboards[i].widgets[j].filter.<key>`, matching `filter-token-unknown`'s precision in
+ that same subtree.
+- `widget-filter-field-not-included` — the key resolves, but its relationship prefix is
+ not declared in the dataset's `include`, so ADR-0021 compiles no join and the column is
+ out of the query's reach.
+- `widget-sortby-unselected` — `options.sortBy` names neither a `dimensions[]` nor a
+ `values[]` entry of the widget. A name the dataset declares but the widget did not
+ select gets its own message, because the fix is a selection rather than a spelling.
+
+**A dotted path through a declared `include` is RESOLVED, not skipped.** A widget's
+`filter` is ANDed into the dataset query as `runtimeFilter`, and that compiled query
+carries only the joins `include` declared — so the same two clauses the dataset rule
+applies one level down (existence, then joinability) apply here. The runtime is not a
+backstop for the second: the dataset compiler's `assertDeclared` runs over `dimensions`
+and `measures` only, never over `runtimeFilter`.
+
+Built on the seams that shipped with the dataset-level sibling rather than a second
+implementation: `walkFilterFieldKeys` (all three authored filter shapes) and
+`indexObjectGraph` / `resolveFieldPath`. Two helpers that were local to that rule —
+`joinablePrefixes` and `describeFieldPathVerdict` — moved into the shared seam and are
+now exported, because both are answers this position asks identically and copying either
+would have been the second implementation the seam exists to prevent.
+
+Minor rather than patch: this narrows the accept set. Metadata that built yesterday and
+names a column or an order that does not exist now fails the build — which is the point.
+The three skips every field-existence rule in this package takes are unchanged, so an
+object the stack does not define, an ADR-0015 `external` object with no readable field
+map, and a registry-injected system column are never reported.

packages/lint/src/index.ts

@@ -24,6 +24,13 @@ export {
  WIDGET_LEGACY_ANALYTICS_UNRENDERABLE,
  DASHBOARD_FILTER_FIELD_UNKNOWN,
  DASHBOARD_FILTER_FIELD_UNPROVISIONED,
+ // [#14148] The widget's OWN two references, at the same site: the keys of its
+ // presentation-scope `filter` (resolved on the #14105 object-graph seam, with
+ // the ADR-0021 `include` clause its `runtimeFilter` really is subject to) and
+ // `options.sortBy` against what the widget selects.
+ WIDGET_FILTER_FIELD_UNKNOWN,
+ WIDGET_FILTER_FIELD_NOT_INCLUDED,
+ WIDGET_SORTBY_UNSELECTED,
 } from './validate-widget-bindings.js';
 export type { WidgetBindingFinding, WidgetBindingSeverity } from './validate-widget-bindings.js';
 
@@ -485,16 +492,26 @@ export type { DatasetRefFinding, DatasetRefSeverity } from './validate-dataset-r
 // positions) must reuse ONE mechanism rather than growing a second hop-walker
 // and a second filter-key reader. Both hold mechanism only — no rule ids, no
 // severities, no findings; the judgement stays with the rule that asks.
+// [#14148] `joinablePrefixes` and `describeFieldPathVerdict` joined them when
+// the widget limb landed: both were local to the dataset rule, and both are
+// answers to questions the widget position asks identically — how ADR-0021
+// expands an `include` into joinable prefixes, and how one verdict reads in
+// prose. Copying either would have been the second implementation this seam
+// exists to prevent, one release after it was written to prevent it.
 export {
  indexObjectGraph,
  resolveFieldPath,
  isUnjudgeable,
+ joinablePrefixes,
+ describeFieldPathVerdict,
  nearestName,
  suggestName,
  listNames,
  RELATIONSHIP_FIELD_TYPES,
 } from './object-graph.js';
-export type { ObjectGraph, GraphObject, GraphField, FieldPathVerdict } from './object-graph.js';
+export type {
+ ObjectGraph, GraphObject, GraphField, FieldPathVerdict, FieldPathAccount,
+} from './object-graph.js';
 export { walkFilterFieldKeys } from './filter-walk.js';
 export type { FilterFieldKey } from './filter-walk.js';
 

packages/lint/src/object-graph.ts

@@ -248,6 +248,89 @@ export function resolveFieldPath(
  return { kind: 'field-unknown', object: current, field: leaf, candidates: obj.names };
 }
 
+/**
+ * The relationship prefixes a document declared as joinable.
+ *
+ * ADR-0021: *"Declaring `a.b` implicitly includes the intermediate `a`."* So
+ * every PREFIX of every declared path is joinable, not only the paths as
+ * written — which is why this expands rather than reading `include` verbatim.
+ *
+ * Here rather than in a rule because the SAME `include` governs positions two
+ * different rules judge: a dataset's own `dimensions[].field` / `measures[].field`
+ * / filter keys (#14105), and a dashboard widget's `filter` keys (#14148), whose
+ * condition is ANDed into that same dataset's compiled query as `runtimeFilter`.
+ * Two copies of the prefix expansion would let the two positions drift apart on
+ * a clause that is one sentence of one ADR.
+ */
+export function joinablePrefixes(include: unknown): ReadonlySet<string> {
+ const prefixes = new Set<string>();
+ if (!Array.isArray(include)) return prefixes;
+ for (const entry of include) {
+ if (typeof entry !== 'string' || !entry) continue;
+ const segments = entry.split('.');
+ for (let i = 1; i <= segments.length; i++) {
+ prefixes.add(segments.slice(0, i).join('.'));
+ }
+ }
+ return prefixes;
+}
+
+/** The two halves of a rendered verdict: the finding's message, and its detail. */
+export interface FieldPathAccount {
+ /** What is wrong, in prose, carrying the "did you mean" when there is one. */
+ message: string;
+ /** The supporting field list, for the finding's hint. */
+ detail: string;
+}
+
+/**
+ * Turn a resolution verdict into the message half of an existence finding, or
+ * `undefined` when the verdict is one no rule may report.
+ *
+ * Shared by every position that resolves a field PATH — a dataset dimension, a
+ * measure, a dataset filter key (#14105), a widget filter key (#14148) — so
+ * they cannot drift into N different accounts of the same miss. The caller
+ * supplies `subject` (how the position is named in prose) and owns the rule id,
+ * the severity, the path and the hint's prescription; this function holds none
+ * of them, matching the rest of this module.
+ */
+export function describeFieldPathVerdict(
+ verdict: FieldPathVerdict,
+ path: string,
+ subject: string,
+): FieldPathAccount | undefined {
+ switch (verdict.kind) {
+ case 'ok':
+ case 'unknowable':
+ case 'hop-untargeted':
+ return undefined;
+ case 'hop-unknown':
+ return {
+ message:
+ `${subject} "${path}" traverses "${verdict.segment}", which is not a field on object ` +
+ `"${verdict.object}".${suggestName(verdict.segment, verdict.candidates)}`,
+ detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
+ };
+ case 'hop-not-relationship':
+ return {
+ message:
+ `${subject} "${path}" traverses "${verdict.segment}", which is a` +
+ `${verdict.type ? ` \`${verdict.type}\`` : 'n ordinary'} field on object ` +
+ `"${verdict.object}" and not a relationship — there is nothing to join through.`,
+ detail:
+ `Only ${[...RELATIONSHIP_FIELD_TYPES].sort().join(' / ')} fields are traversable ` +
+ `(ADR-0021 derives every join from the object graph; you never write an ON clause).`,
+ };
+ case 'field-unknown':
+ return {
+ message:
+ `${subject} "${path}" is not a field on object "${verdict.object}".` +
+ `${suggestName(verdict.field, verdict.candidates)}`,
+ detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
+ };
+ }
+}
+
 /**
  * True when the verdict is one no rule may report — the graph could not answer.
  * Callers spell the skip through this predicate rather than re-listing the

packages/lint/src/validate-dataset-references.ts

@@ -118,12 +118,11 @@
 import { walkFilterFieldKeys } from './filter-walk.js';
 import {
  RELATIONSHIP_FIELD_TYPES,
+ describeFieldPathVerdict,
  indexObjectGraph,
  isUnjudgeable,
-listNames,
+joinablePrefixes,
  resolveFieldPath,
- suggestName,
- type FieldPathVerdict,
  type ObjectGraph,
 } from './object-graph.js';
 
@@ -172,72 +171,6 @@ function asArray(v: unknown): AnyRec[] {
  return [];
 }
 
-/**
- * The relationship prefixes a dataset declared as joinable.
- *
- * ADR-0021: *"Declaring `a.b` implicitly includes the intermediate `a`."* So
- * every PREFIX of every declared path is joinable, not only the paths as
- * written — which is why this expands rather than reading `include` verbatim.
- */
-function joinablePrefixes(include: unknown): ReadonlySet<string> {
- const prefixes = new Set<string>();
- if (!Array.isArray(include)) return prefixes;
- for (const entry of include) {
- if (typeof entry !== 'string' || !entry) continue;
- const segments = entry.split('.');
- for (let i = 1; i <= segments.length; i++) {
- prefixes.add(segments.slice(0, i).join('.'));
- }
- }
- return prefixes;
-}
-
-/**
- * Turn a resolution verdict into the message half of an existence finding, or
- * `undefined` when the verdict is one no rule may report.
- *
- * Shared by the three positions that resolve a field PATH (dimension, measure,
- * filter key) so they cannot drift into three different accounts of the same
- * miss. The caller supplies `subject` — how the position is named in prose —
- * and owns the rule id, the path and the hint's prescription.
- */
-function existenceMessage(
- verdict: FieldPathVerdict,
- path: string,
- subject: string,
-): { message: string; detail: string } | undefined {
- switch (verdict.kind) {
- case 'ok':
- case 'unknowable':
- case 'hop-untargeted':
- return undefined;
- case 'hop-unknown':
- return {
- message:
- `${subject} "${path}" traverses "${verdict.segment}", which is not a field on object ` +
- `"${verdict.object}".${suggestName(verdict.segment, verdict.candidates)}`,
- detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
- };
- case 'hop-not-relationship':
- return {
- message:
- `${subject} "${path}" traverses "${verdict.segment}", which is a` +
- `${verdict.type ? ` \`${verdict.type}\`` : 'n ordinary'} field on object ` +
- `"${verdict.object}" and not a relationship — there is nothing to join through.`,
- detail:
- `Only ${[...RELATIONSHIP_FIELD_TYPES].sort().join(' / ')} fields are traversable ` +
- `(ADR-0021 derives every join from the object graph; you never write an ON clause).`,
- };
- case 'field-unknown':
- return {
- message:
- `${subject} "${path}" is not a field on object "${verdict.object}".` +
- `${suggestName(verdict.field, verdict.candidates)}`,
- detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
- };
- }
-}
-
 /** The shared consequence sentence — why an unresolved path is not merely inert. */
 const SILENT_EMPTY =
  'The path is compiled into the analytics query as written, so it addresses a column ' +
@@ -309,7 +242,7 @@ export function validateDatasetReferences(stack: AnyRec): DatasetRefFinding[] {
  return;
  }
 
- const account = existenceMessage(verdict, entry, `include[${ii}]`);
+ const account = describeFieldPathVerdict(verdict, entry, `include[${ii}]`);
  if (!account) return;
  findings.push({
  severity: 'error',
@@ -342,7 +275,7 @@ export function validateDatasetReferences(stack: AnyRec): DatasetRefFinding[] {
  const verdict = resolveFieldPath(graph, object, written);
  if (isUnjudgeable(verdict) || !verdict) return;
 
- const account = existenceMessage(verdict, written, subject);
+ const account = describeFieldPathVerdict(verdict, written, subject);
  if (account) {
  findings.push({
  severity: 'error',

.changeset/widget-filter-sortby-resolution.md

@@ -0,0 +1,62 @@
+---
+'@objectstack/lint': minor
+---
+
+Resolve a dashboard widget's OWN `filter` keys and `options.sortBy` at validate/build
+
+A dashboard widget could filter by a column that does not exist, and order by a name
+it never selected, and `objectstack validate` exited 0 with "Validation passed";
+`build` — the publish gate — wrote the dashboard into `dist/objectstack.json`. The
+widget then rendered **empty**.
+
+The surrounding surface was already covered, which is what made the two misses so
+narrow: `widget-dataset-unknown`, `widget-dimension-unknown`, `widget-measure-unknown`,
+`filter-token-unknown` and `dashboard-filter-field-unknown` all failed both gates on the
+same dashboard. On the very same node, the filter TOKEN was checked and the filter
+COLUMN was not — `filter-token-unknown` fires path-precise at
+`…widgets[4].filter.due_date.$lte`, so the traversal already walked the filter tree and
+already knew the widget's dataset. Only the key resolution was missing. And
+`options.sortBy` was declared-≠-enforced in the plainest way available: the spec states
+the contract in its own prose — *"must be one this widget actually selects"* — and
+nothing enforced it.
+
+Why this class of miss is expensive rather than untidy, in the reporter's words: the
+dashboard it was measured on leads with a "not moving" tile — open work untouched more
+than 14 days — and *"an empty tile is indistinguishable from a healthy team: a missing
+number reads as zero, and zero is the answer the manager is hoping for."* The failure is
+silent in the direction the reader wants to believe.
+
+Three gating rule ids, all at the site that already emits `widget-dataset-unknown` /
+`dashboard-filter-field-unknown`, and all failing **`validate` and `build`** (pinned
+end-to-end, not inferred from the registry entry):
+
+- `widget-filter-field-unknown` — a key of the widget's own `filter` resolves to no
+ column on the bound dataset's object graph. Reported path-precise at
+ `dashboards[i].widgets[j].filter.<key>`, matching `filter-token-unknown`'s precision in
+ that same subtree.
+- `widget-filter-field-not-included` — the key resolves, but its relationship prefix is
+ not declared in the dataset's `include`, so ADR-0021 compiles no join and the column is
+ out of the query's reach.
+- `widget-sortby-unselected` — `options.sortBy` names neither a `dimensions[]` nor a
+ `values[]` entry of the widget. A name the dataset declares but the widget did not
+ select gets its own message, because the fix is a selection rather than a spelling.
+
+**A dotted path through a declared `include` is RESOLVED, not skipped.** A widget's
+`filter` is ANDed into the dataset query as `runtimeFilter`, and that compiled query
+carries only the joins `include` declared — so the same two clauses the dataset rule
+applies one level down (existence, then joinability) apply here. The runtime is not a
+backstop for the second: the dataset compiler's `assertDeclared` runs over `dimensions`
+and `measures` only, never over `runtimeFilter`.
+
+Built on the seams that shipped with the dataset-level sibling rather than a second
+implementation: `walkFilterFieldKeys` (all three authored filter shapes) and
+`indexObjectGraph` / `resolveFieldPath`. Two helpers that were local to that rule —
+`joinablePrefixes` and `describeFieldPathVerdict` — moved into the shared seam and are
+now exported, because both are answers this position asks identically and copying either
+would have been the second implementation the seam exists to prevent.
+
+Minor rather than patch: this narrows the accept set. Metadata that built yesterday and
+names a column or an order that does not exist now fails the build — which is the point.
+The three skips every field-existence rule in this package takes are unchanged, so an
+object the stack does not define, an ADR-0015 `external` object with no readable field
+map, and a registry-injected system column are never reported.

packages/lint/src/index.ts

@@ -24,6 +24,13 @@ export {
  WIDGET_LEGACY_ANALYTICS_UNRENDERABLE,
  DASHBOARD_FILTER_FIELD_UNKNOWN,
  DASHBOARD_FILTER_FIELD_UNPROVISIONED,
+ // [#14148] The widget's OWN two references, at the same site: the keys of its
+ // presentation-scope `filter` (resolved on the #14105 object-graph seam, with
+ // the ADR-0021 `include` clause its `runtimeFilter` really is subject to) and
+ // `options.sortBy` against what the widget selects.
+ WIDGET_FILTER_FIELD_UNKNOWN,
+ WIDGET_FILTER_FIELD_NOT_INCLUDED,
+ WIDGET_SORTBY_UNSELECTED,
 } from './validate-widget-bindings.js';
 export type { WidgetBindingFinding, WidgetBindingSeverity } from './validate-widget-bindings.js';
 
@@ -485,16 +492,26 @@ export type { DatasetRefFinding, DatasetRefSeverity } from './validate-dataset-r
 // positions) must reuse ONE mechanism rather than growing a second hop-walker
 // and a second filter-key reader. Both hold mechanism only — no rule ids, no
 // severities, no findings; the judgement stays with the rule that asks.
+// [#14148] `joinablePrefixes` and `describeFieldPathVerdict` joined them when
+// the widget limb landed: both were local to the dataset rule, and both are
+// answers to questions the widget position asks identically — how ADR-0021
+// expands an `include` into joinable prefixes, and how one verdict reads in
+// prose. Copying either would have been the second implementation this seam
+// exists to prevent, one release after it was written to prevent it.
 export {
  indexObjectGraph,
  resolveFieldPath,
  isUnjudgeable,
+ joinablePrefixes,
+ describeFieldPathVerdict,
  nearestName,
  suggestName,
  listNames,
  RELATIONSHIP_FIELD_TYPES,
 } from './object-graph.js';
-export type { ObjectGraph, GraphObject, GraphField, FieldPathVerdict } from './object-graph.js';
+export type {
+ ObjectGraph, GraphObject, GraphField, FieldPathVerdict, FieldPathAccount,
+} from './object-graph.js';
 export { walkFilterFieldKeys } from './filter-walk.js';
 export type { FilterFieldKey } from './filter-walk.js';
 

packages/lint/src/object-graph.ts

@@ -248,6 +248,89 @@ export function resolveFieldPath(
  return { kind: 'field-unknown', object: current, field: leaf, candidates: obj.names };
 }
 
+/**
+ * The relationship prefixes a document declared as joinable.
+ *
+ * ADR-0021: *"Declaring `a.b` implicitly includes the intermediate `a`."* So
+ * every PREFIX of every declared path is joinable, not only the paths as
+ * written — which is why this expands rather than reading `include` verbatim.
+ *
+ * Here rather than in a rule because the SAME `include` governs positions two
+ * different rules judge: a dataset's own `dimensions[].field` / `measures[].field`
+ * / filter keys (#14105), and a dashboard widget's `filter` keys (#14148), whose
+ * condition is ANDed into that same dataset's compiled query as `runtimeFilter`.
+ * Two copies of the prefix expansion would let the two positions drift apart on
+ * a clause that is one sentence of one ADR.
+ */
+export function joinablePrefixes(include: unknown): ReadonlySet<string> {
+ const prefixes = new Set<string>();
+ if (!Array.isArray(include)) return prefixes;
+ for (const entry of include) {
+ if (typeof entry !== 'string' || !entry) continue;
+ const segments = entry.split('.');
+ for (let i = 1; i <= segments.length; i++) {
+ prefixes.add(segments.slice(0, i).join('.'));
+ }
+ }
+ return prefixes;
+}
+
+/** The two halves of a rendered verdict: the finding's message, and its detail. */
+export interface FieldPathAccount {
+ /** What is wrong, in prose, carrying the "did you mean" when there is one. */
+ message: string;
+ /** The supporting field list, for the finding's hint. */
+ detail: string;
+}
+
+/**
+ * Turn a resolution verdict into the message half of an existence finding, or
+ * `undefined` when the verdict is one no rule may report.
+ *
+ * Shared by every position that resolves a field PATH — a dataset dimension, a
+ * measure, a dataset filter key (#14105), a widget filter key (#14148) — so
+ * they cannot drift into N different accounts of the same miss. The caller
+ * supplies `subject` (how the position is named in prose) and owns the rule id,
+ * the severity, the path and the hint's prescription; this function holds none
+ * of them, matching the rest of this module.
+ */
+export function describeFieldPathVerdict(
+ verdict: FieldPathVerdict,
+ path: string,
+ subject: string,
+): FieldPathAccount | undefined {
+ switch (verdict.kind) {
+ case 'ok':
+ case 'unknowable':
+ case 'hop-untargeted':
+ return undefined;
+ case 'hop-unknown':
+ return {
+ message:
+ `${subject} "${path}" traverses "${verdict.segment}", which is not a field on object ` +
+ `"${verdict.object}".${suggestName(verdict.segment, verdict.candidates)}`,
+ detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
+ };
+ case 'hop-not-relationship':
+ return {
+ message:
+ `${subject} "${path}" traverses "${verdict.segment}", which is a` +
+ `${verdict.type ? ` \`${verdict.type}\`` : 'n ordinary'} field on object ` +
+ `"${verdict.object}" and not a relationship — there is nothing to join through.`,
+ detail:
+ `Only ${[...RELATIONSHIP_FIELD_TYPES].sort().join(' / ')} fields are traversable ` +
+ `(ADR-0021 derives every join from the object graph; you never write an ON clause).`,
+ };
+ case 'field-unknown':
+ return {
+ message:
+ `${subject} "${path}" is not a field on object "${verdict.object}".` +
+ `${suggestName(verdict.field, verdict.candidates)}`,
+ detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
+ };
+ }
+}
+
 /**
  * True when the verdict is one no rule may report — the graph could not answer.
  * Callers spell the skip through this predicate rather than re-listing the

packages/lint/src/validate-dataset-references.ts

@@ -118,12 +118,11 @@
 import { walkFilterFieldKeys } from './filter-walk.js';
 import {
  RELATIONSHIP_FIELD_TYPES,
+ describeFieldPathVerdict,
  indexObjectGraph,
  isUnjudgeable,
-listNames,
+joinablePrefixes,
  resolveFieldPath,
- suggestName,
- type FieldPathVerdict,
  type ObjectGraph,
 } from './object-graph.js';
 
@@ -172,72 +171,6 @@ function asArray(v: unknown): AnyRec[] {
  return [];
 }
 
-/**
- * The relationship prefixes a dataset declared as joinable.
- *
- * ADR-0021: *"Declaring `a.b` implicitly includes the intermediate `a`."* So
- * every PREFIX of every declared path is joinable, not only the paths as
- * written — which is why this expands rather than reading `include` verbatim.
- */
-function joinablePrefixes(include: unknown): ReadonlySet<string> {
- const prefixes = new Set<string>();
- if (!Array.isArray(include)) return prefixes;
- for (const entry of include) {
- if (typeof entry !== 'string' || !entry) continue;
- const segments = entry.split('.');
- for (let i = 1; i <= segments.length; i++) {
- prefixes.add(segments.slice(0, i).join('.'));
- }
- }
- return prefixes;
-}
-
-/**
- * Turn a resolution verdict into the message half of an existence finding, or
- * `undefined` when the verdict is one no rule may report.
- *
- * Shared by the three positions that resolve a field PATH (dimension, measure,
- * filter key) so they cannot drift into three different accounts of the same
- * miss. The caller supplies `subject` — how the position is named in prose —
- * and owns the rule id, the path and the hint's prescription.
- */
-function existenceMessage(
- verdict: FieldPathVerdict,
- path: string,
- subject: string,
-): { message: string; detail: string } | undefined {
- switch (verdict.kind) {
- case 'ok':
- case 'unknowable':
- case 'hop-untargeted':
- return undefined;
- case 'hop-unknown':
- return {
- message:
- `${subject} "${path}" traverses "${verdict.segment}", which is not a field on object ` +
- `"${verdict.object}".${suggestName(verdict.segment, verdict.candidates)}`,
- detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
- };
- case 'hop-not-relationship':
- return {
- message:
- `${subject} "${path}" traverses "${verdict.segment}", which is a` +
- `${verdict.type ? ` \`${verdict.type}\`` : 'n ordinary'} field on object ` +
- `"${verdict.object}" and not a relationship — there is nothing to join through.`,
- detail:
- `Only ${[...RELATIONSHIP_FIELD_TYPES].sort().join(' / ')} fields are traversable ` +
- `(ADR-0021 derives every join from the object graph; you never write an ON clause).`,
- };
- case 'field-unknown':
- return {
- message:
- `${subject} "${path}" is not a field on object "${verdict.object}".` +
- `${suggestName(verdict.field, verdict.candidates)}`,
- detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
- };
- }
-}
-
 /** The shared consequence sentence — why an unresolved path is not merely inert. */
 const SILENT_EMPTY =
  'The path is compiled into the analytics query as written, so it addresses a column ' +
@@ -309,7 +242,7 @@ export function validateDatasetReferences(stack: AnyRec): DatasetRefFinding[] {
  return;
  }
 
- const account = existenceMessage(verdict, entry, `include[${ii}]`);
+ const account = describeFieldPathVerdict(verdict, entry, `include[${ii}]`);
  if (!account) return;
  findings.push({
  severity: 'error',
@@ -342,7 +275,7 @@ export function validateDatasetReferences(stack: AnyRec): DatasetRefFinding[] {
  const verdict = resolveFieldPath(graph, object, written);
  if (isUnjudgeable(verdict) || !verdict) return;
 
- const account = existenceMessage(verdict, written, subject);
+ const account = describeFieldPathVerdict(verdict, written, subject);
  if (account) {
  findings.push({
  severity: 'error',

.changeset/widget-filter-sortby-resolution.md

@@ -0,0 +1,62 @@
+---
+'@objectstack/lint': minor
+---
+
+Resolve a dashboard widget's OWN `filter` keys and `options.sortBy` at validate/build
+
+A dashboard widget could filter by a column that does not exist, and order by a name
+it never selected, and `objectstack validate` exited 0 with "Validation passed";
+`build` — the publish gate — wrote the dashboard into `dist/objectstack.json`. The
+widget then rendered **empty**.
+
+The surrounding surface was already covered, which is what made the two misses so
+narrow: `widget-dataset-unknown`, `widget-dimension-unknown`, `widget-measure-unknown`,
+`filter-token-unknown` and `dashboard-filter-field-unknown` all failed both gates on the
+same dashboard. On the very same node, the filter TOKEN was checked and the filter
+COLUMN was not — `filter-token-unknown` fires path-precise at
+`…widgets[4].filter.due_date.$lte`, so the traversal already walked the filter tree and
+already knew the widget's dataset. Only the key resolution was missing. And
+`options.sortBy` was declared-≠-enforced in the plainest way available: the spec states
+the contract in its own prose — *"must be one this widget actually selects"* — and
+nothing enforced it.
+
+Why this class of miss is expensive rather than untidy, in the reporter's words: the
+dashboard it was measured on leads with a "not moving" tile — open work untouched more
+than 14 days — and *"an empty tile is indistinguishable from a healthy team: a missing
+number reads as zero, and zero is the answer the manager is hoping for."* The failure is
+silent in the direction the reader wants to believe.
+
+Three gating rule ids, all at the site that already emits `widget-dataset-unknown` /
+`dashboard-filter-field-unknown`, and all failing **`validate` and `build`** (pinned
+end-to-end, not inferred from the registry entry):
+
+- `widget-filter-field-unknown` — a key of the widget's own `filter` resolves to no
+ column on the bound dataset's object graph. Reported path-precise at
+ `dashboards[i].widgets[j].filter.<key>`, matching `filter-token-unknown`'s precision in
+ that same subtree.
+- `widget-filter-field-not-included` — the key resolves, but its relationship prefix is
+ not declared in the dataset's `include`, so ADR-0021 compiles no join and the column is
+ out of the query's reach.
+- `widget-sortby-unselected` — `options.sortBy` names neither a `dimensions[]` nor a
+ `values[]` entry of the widget. A name the dataset declares but the widget did not
+ select gets its own message, because the fix is a selection rather than a spelling.
+
+**A dotted path through a declared `include` is RESOLVED, not skipped.** A widget's
+`filter` is ANDed into the dataset query as `runtimeFilter`, and that compiled query
+carries only the joins `include` declared — so the same two clauses the dataset rule
+applies one level down (existence, then joinability) apply here. The runtime is not a
+backstop for the second: the dataset compiler's `assertDeclared` runs over `dimensions`
+and `measures` only, never over `runtimeFilter`.
+
+Built on the seams that shipped with the dataset-level sibling rather than a second
+implementation: `walkFilterFieldKeys` (all three authored filter shapes) and
+`indexObjectGraph` / `resolveFieldPath`. Two helpers that were local to that rule —
+`joinablePrefixes` and `describeFieldPathVerdict` — moved into the shared seam and are
+now exported, because both are answers this position asks identically and copying either
+would have been the second implementation the seam exists to prevent.
+
+Minor rather than patch: this narrows the accept set. Metadata that built yesterday and
+names a column or an order that does not exist now fails the build — which is the point.
+The three skips every field-existence rule in this package takes are unchanged, so an
+object the stack does not define, an ADR-0015 `external` object with no readable field
+map, and a registry-injected system column are never reported.

packages/lint/src/index.ts

@@ -24,6 +24,13 @@ export {
  WIDGET_LEGACY_ANALYTICS_UNRENDERABLE,
  DASHBOARD_FILTER_FIELD_UNKNOWN,
  DASHBOARD_FILTER_FIELD_UNPROVISIONED,
+ // [#14148] The widget's OWN two references, at the same site: the keys of its
+ // presentation-scope `filter` (resolved on the #14105 object-graph seam, with
+ // the ADR-0021 `include` clause its `runtimeFilter` really is subject to) and
+ // `options.sortBy` against what the widget selects.
+ WIDGET_FILTER_FIELD_UNKNOWN,
+ WIDGET_FILTER_FIELD_NOT_INCLUDED,
+ WIDGET_SORTBY_UNSELECTED,
 } from './validate-widget-bindings.js';
 export type { WidgetBindingFinding, WidgetBindingSeverity } from './validate-widget-bindings.js';
 
@@ -485,16 +492,26 @@ export type { DatasetRefFinding, DatasetRefSeverity } from './validate-dataset-r
 // positions) must reuse ONE mechanism rather than growing a second hop-walker
 // and a second filter-key reader. Both hold mechanism only — no rule ids, no
 // severities, no findings; the judgement stays with the rule that asks.
+// [#14148] `joinablePrefixes` and `describeFieldPathVerdict` joined them when
+// the widget limb landed: both were local to the dataset rule, and both are
+// answers to questions the widget position asks identically — how ADR-0021
+// expands an `include` into joinable prefixes, and how one verdict reads in
+// prose. Copying either would have been the second implementation this seam
+// exists to prevent, one release after it was written to prevent it.
 export {
  indexObjectGraph,
  resolveFieldPath,
  isUnjudgeable,
+ joinablePrefixes,
+ describeFieldPathVerdict,
  nearestName,
  suggestName,
  listNames,
  RELATIONSHIP_FIELD_TYPES,
 } from './object-graph.js';
-export type { ObjectGraph, GraphObject, GraphField, FieldPathVerdict } from './object-graph.js';
+export type {
+ ObjectGraph, GraphObject, GraphField, FieldPathVerdict, FieldPathAccount,
+} from './object-graph.js';
 export { walkFilterFieldKeys } from './filter-walk.js';
 export type { FilterFieldKey } from './filter-walk.js';
 

packages/lint/src/object-graph.ts

@@ -248,6 +248,89 @@ export function resolveFieldPath(
  return { kind: 'field-unknown', object: current, field: leaf, candidates: obj.names };
 }
 
+/**
+ * The relationship prefixes a document declared as joinable.
+ *
+ * ADR-0021: *"Declaring `a.b` implicitly includes the intermediate `a`."* So
+ * every PREFIX of every declared path is joinable, not only the paths as
+ * written — which is why this expands rather than reading `include` verbatim.
+ *
+ * Here rather than in a rule because the SAME `include` governs positions two
+ * different rules judge: a dataset's own `dimensions[].field` / `measures[].field`
+ * / filter keys (#14105), and a dashboard widget's `filter` keys (#14148), whose
+ * condition is ANDed into that same dataset's compiled query as `runtimeFilter`.
+ * Two copies of the prefix expansion would let the two positions drift apart on
+ * a clause that is one sentence of one ADR.
+ */
+export function joinablePrefixes(include: unknown): ReadonlySet<string> {
+ const prefixes = new Set<string>();
+ if (!Array.isArray(include)) return prefixes;
+ for (const entry of include) {
+ if (typeof entry !== 'string' || !entry) continue;
+ const segments = entry.split('.');
+ for (let i = 1; i <= segments.length; i++) {
+ prefixes.add(segments.slice(0, i).join('.'));
+ }
+ }
+ return prefixes;
+}
+
+/** The two halves of a rendered verdict: the finding's message, and its detail. */
+export interface FieldPathAccount {
+ /** What is wrong, in prose, carrying the "did you mean" when there is one. */
+ message: string;
+ /** The supporting field list, for the finding's hint. */
+ detail: string;
+}
+
+/**
+ * Turn a resolution verdict into the message half of an existence finding, or
+ * `undefined` when the verdict is one no rule may report.
+ *
+ * Shared by every position that resolves a field PATH — a dataset dimension, a
+ * measure, a dataset filter key (#14105), a widget filter key (#14148) — so
+ * they cannot drift into N different accounts of the same miss. The caller
+ * supplies `subject` (how the position is named in prose) and owns the rule id,
+ * the severity, the path and the hint's prescription; this function holds none
+ * of them, matching the rest of this module.
+ */
+export function describeFieldPathVerdict(
+ verdict: FieldPathVerdict,
+ path: string,
+ subject: string,
+): FieldPathAccount | undefined {
+ switch (verdict.kind) {
+ case 'ok':
+ case 'unknowable':
+ case 'hop-untargeted':
+ return undefined;
+ case 'hop-unknown':
+ return {
+ message:
+ `${subject} "${path}" traverses "${verdict.segment}", which is not a field on object ` +
+ `"${verdict.object}".${suggestName(verdict.segment, verdict.candidates)}`,
+ detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
+ };
+ case 'hop-not-relationship':
+ return {
+ message:
+ `${subject} "${path}" traverses "${verdict.segment}", which is a` +
+ `${verdict.type ? ` \`${verdict.type}\`` : 'n ordinary'} field on object ` +
+ `"${verdict.object}" and not a relationship — there is nothing to join through.`,
+ detail:
+ `Only ${[...RELATIONSHIP_FIELD_TYPES].sort().join(' / ')} fields are traversable ` +
+ `(ADR-0021 derives every join from the object graph; you never write an ON clause).`,
+ };
+ case 'field-unknown':
+ return {
+ message:
+ `${subject} "${path}" is not a field on object "${verdict.object}".` +
+ `${suggestName(verdict.field, verdict.candidates)}`,
+ detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
+ };
+ }
+}
+
 /**
  * True when the verdict is one no rule may report — the graph could not answer.
  * Callers spell the skip through this predicate rather than re-listing the

packages/lint/src/validate-dataset-references.ts

@@ -118,12 +118,11 @@
 import { walkFilterFieldKeys } from './filter-walk.js';
 import {
  RELATIONSHIP_FIELD_TYPES,
+ describeFieldPathVerdict,
  indexObjectGraph,
  isUnjudgeable,
-listNames,
+joinablePrefixes,
  resolveFieldPath,
- suggestName,
- type FieldPathVerdict,
  type ObjectGraph,
 } from './object-graph.js';
 
@@ -172,72 +171,6 @@ function asArray(v: unknown): AnyRec[] {
  return [];
 }
 
-/**
- * The relationship prefixes a dataset declared as joinable.
- *
- * ADR-0021: *"Declaring `a.b` implicitly includes the intermediate `a`."* So
- * every PREFIX of every declared path is joinable, not only the paths as
- * written — which is why this expands rather than reading `include` verbatim.
- */
-function joinablePrefixes(include: unknown): ReadonlySet<string> {
- const prefixes = new Set<string>();
- if (!Array.isArray(include)) return prefixes;
- for (const entry of include) {
- if (typeof entry !== 'string' || !entry) continue;
- const segments = entry.split('.');
- for (let i = 1; i <= segments.length; i++) {
- prefixes.add(segments.slice(0, i).join('.'));
- }
- }
- return prefixes;
-}
-
-/**
- * Turn a resolution verdict into the message half of an existence finding, or
- * `undefined` when the verdict is one no rule may report.
- *
- * Shared by the three positions that resolve a field PATH (dimension, measure,
- * filter key) so they cannot drift into three different accounts of the same
- * miss. The caller supplies `subject` — how the position is named in prose —
- * and owns the rule id, the path and the hint's prescription.
- */
-function existenceMessage(
- verdict: FieldPathVerdict,
- path: string,
- subject: string,
-): { message: string; detail: string } | undefined {
- switch (verdict.kind) {
- case 'ok':
- case 'unknowable':
- case 'hop-untargeted':
- return undefined;
- case 'hop-unknown':
- return {
- message:
- `${subject} "${path}" traverses "${verdict.segment}", which is not a field on object ` +
- `"${verdict.object}".${suggestName(verdict.segment, verdict.candidates)}`,
- detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
- };
- case 'hop-not-relationship':
- return {
- message:
- `${subject} "${path}" traverses "${verdict.segment}", which is a` +
- `${verdict.type ? ` \`${verdict.type}\`` : 'n ordinary'} field on object ` +
- `"${verdict.object}" and not a relationship — there is nothing to join through.`,
- detail:
- `Only ${[...RELATIONSHIP_FIELD_TYPES].sort().join(' / ')} fields are traversable ` +
- `(ADR-0021 derives every join from the object graph; you never write an ON clause).`,
- };
- case 'field-unknown':
- return {
- message:
- `${subject} "${path}" is not a field on object "${verdict.object}".` +
- `${suggestName(verdict.field, verdict.candidates)}`,
- detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
- };
- }
-}
-
 /** The shared consequence sentence — why an unresolved path is not merely inert. */
 const SILENT_EMPTY =
  'The path is compiled into the analytics query as written, so it addresses a column ' +
@@ -309,7 +242,7 @@ export function validateDatasetReferences(stack: AnyRec): DatasetRefFinding[] {
  return;
  }
 
- const account = existenceMessage(verdict, entry, `include[${ii}]`);
+ const account = describeFieldPathVerdict(verdict, entry, `include[${ii}]`);
  if (!account) return;
  findings.push({
  severity: 'error',
@@ -342,7 +275,7 @@ export function validateDatasetReferences(stack: AnyRec): DatasetRefFinding[] {
  const verdict = resolveFieldPath(graph, object, written);
  if (isUnjudgeable(verdict) || !verdict) return;
 
- const account = existenceMessage(verdict, written, subject);
+ const account = describeFieldPathVerdict(verdict, written, subject);
  if (account) {
  findings.push({
  severity: 'error',

.changeset/widget-filter-sortby-resolution.md

@@ -0,0 +1,62 @@
+---
+'@objectstack/lint': minor
+---
+
+Resolve a dashboard widget's OWN `filter` keys and `options.sortBy` at validate/build
+
+A dashboard widget could filter by a column that does not exist, and order by a name
+it never selected, and `objectstack validate` exited 0 with "Validation passed";
+`build` — the publish gate — wrote the dashboard into `dist/objectstack.json`. The
+widget then rendered **empty**.
+
+The surrounding surface was already covered, which is what made the two misses so
+narrow: `widget-dataset-unknown`, `widget-dimension-unknown`, `widget-measure-unknown`,
+`filter-token-unknown` and `dashboard-filter-field-unknown` all failed both gates on the
+same dashboard. On the very same node, the filter TOKEN was checked and the filter
+COLUMN was not — `filter-token-unknown` fires path-precise at
+`…widgets[4].filter.due_date.$lte`, so the traversal already walked the filter tree and
+already knew the widget's dataset. Only the key resolution was missing. And
+`options.sortBy` was declared-≠-enforced in the plainest way available: the spec states
+the contract in its own prose — *"must be one this widget actually selects"* — and
+nothing enforced it.
+
+Why this class of miss is expensive rather than untidy, in the reporter's words: the
+dashboard it was measured on leads with a "not moving" tile — open work untouched more
+than 14 days — and *"an empty tile is indistinguishable from a healthy team: a missing
+number reads as zero, and zero is the answer the manager is hoping for."* The failure is
+silent in the direction the reader wants to believe.
+
+Three gating rule ids, all at the site that already emits `widget-dataset-unknown` /
+`dashboard-filter-field-unknown`, and all failing **`validate` and `build`** (pinned
+end-to-end, not inferred from the registry entry):
+
+- `widget-filter-field-unknown` — a key of the widget's own `filter` resolves to no
+ column on the bound dataset's object graph. Reported path-precise at
+ `dashboards[i].widgets[j].filter.<key>`, matching `filter-token-unknown`'s precision in
+ that same subtree.
+- `widget-filter-field-not-included` — the key resolves, but its relationship prefix is
+ not declared in the dataset's `include`, so ADR-0021 compiles no join and the column is
+ out of the query's reach.
+- `widget-sortby-unselected` — `options.sortBy` names neither a `dimensions[]` nor a
+ `values[]` entry of the widget. A name the dataset declares but the widget did not
+ select gets its own message, because the fix is a selection rather than a spelling.
+
+**A dotted path through a declared `include` is RESOLVED, not skipped.** A widget's
+`filter` is ANDed into the dataset query as `runtimeFilter`, and that compiled query
+carries only the joins `include` declared — so the same two clauses the dataset rule
+applies one level down (existence, then joinability) apply here. The runtime is not a
+backstop for the second: the dataset compiler's `assertDeclared` runs over `dimensions`
+and `measures` only, never over `runtimeFilter`.
+
+Built on the seams that shipped with the dataset-level sibling rather than a second
+implementation: `walkFilterFieldKeys` (all three authored filter shapes) and
+`indexObjectGraph` / `resolveFieldPath`. Two helpers that were local to that rule —
+`joinablePrefixes` and `describeFieldPathVerdict` — moved into the shared seam and are
+now exported, because both are answers this position asks identically and copying either
+would have been the second implementation the seam exists to prevent.
+
+Minor rather than patch: this narrows the accept set. Metadata that built yesterday and
+names a column or an order that does not exist now fails the build — which is the point.
+The three skips every field-existence rule in this package takes are unchanged, so an
+object the stack does not define, an ADR-0015 `external` object with no readable field
+map, and a registry-injected system column are never reported.

packages/lint/src/index.ts

@@ -24,6 +24,13 @@ export {
  WIDGET_LEGACY_ANALYTICS_UNRENDERABLE,
  DASHBOARD_FILTER_FIELD_UNKNOWN,
  DASHBOARD_FILTER_FIELD_UNPROVISIONED,
+ // [#14148] The widget's OWN two references, at the same site: the keys of its
+ // presentation-scope `filter` (resolved on the #14105 object-graph seam, with
+ // the ADR-0021 `include` clause its `runtimeFilter` really is subject to) and
+ // `options.sortBy` against what the widget selects.
+ WIDGET_FILTER_FIELD_UNKNOWN,
+ WIDGET_FILTER_FIELD_NOT_INCLUDED,
+ WIDGET_SORTBY_UNSELECTED,
 } from './validate-widget-bindings.js';
 export type { WidgetBindingFinding, WidgetBindingSeverity } from './validate-widget-bindings.js';
 
@@ -485,16 +492,26 @@ export type { DatasetRefFinding, DatasetRefSeverity } from './validate-dataset-r
 // positions) must reuse ONE mechanism rather than growing a second hop-walker
 // and a second filter-key reader. Both hold mechanism only — no rule ids, no
 // severities, no findings; the judgement stays with the rule that asks.
+// [#14148] `joinablePrefixes` and `describeFieldPathVerdict` joined them when
+// the widget limb landed: both were local to the dataset rule, and both are
+// answers to questions the widget position asks identically — how ADR-0021
+// expands an `include` into joinable prefixes, and how one verdict reads in
+// prose. Copying either would have been the second implementation this seam
+// exists to prevent, one release after it was written to prevent it.
 export {
  indexObjectGraph,
  resolveFieldPath,
  isUnjudgeable,
+ joinablePrefixes,
+ describeFieldPathVerdict,
  nearestName,
  suggestName,
  listNames,
  RELATIONSHIP_FIELD_TYPES,
 } from './object-graph.js';
-export type { ObjectGraph, GraphObject, GraphField, FieldPathVerdict } from './object-graph.js';
+export type {
+ ObjectGraph, GraphObject, GraphField, FieldPathVerdict, FieldPathAccount,
+} from './object-graph.js';
 export { walkFilterFieldKeys } from './filter-walk.js';
 export type { FilterFieldKey } from './filter-walk.js';
 

packages/lint/src/object-graph.ts

@@ -248,6 +248,89 @@ export function resolveFieldPath(
  return { kind: 'field-unknown', object: current, field: leaf, candidates: obj.names };
 }
 
+/**
+ * The relationship prefixes a document declared as joinable.
+ *
+ * ADR-0021: *"Declaring `a.b` implicitly includes the intermediate `a`."* So
+ * every PREFIX of every declared path is joinable, not only the paths as
+ * written — which is why this expands rather than reading `include` verbatim.
+ *
+ * Here rather than in a rule because the SAME `include` governs positions two
+ * different rules judge: a dataset's own `dimensions[].field` / `measures[].field`
+ * / filter keys (#14105), and a dashboard widget's `filter` keys (#14148), whose
+ * condition is ANDed into that same dataset's compiled query as `runtimeFilter`.
+ * Two copies of the prefix expansion would let the two positions drift apart on
+ * a clause that is one sentence of one ADR.
+ */
+export function joinablePrefixes(include: unknown): ReadonlySet<string> {
+ const prefixes = new Set<string>();
+ if (!Array.isArray(include)) return prefixes;
+ for (const entry of include) {
+ if (typeof entry !== 'string' || !entry) continue;
+ const segments = entry.split('.');
+ for (let i = 1; i <= segments.length; i++) {
+ prefixes.add(segments.slice(0, i).join('.'));
+ }
+ }
+ return prefixes;
+}
+
+/** The two halves of a rendered verdict: the finding's message, and its detail. */
+export interface FieldPathAccount {
+ /** What is wrong, in prose, carrying the "did you mean" when there is one. */
+ message: string;
+ /** The supporting field list, for the finding's hint. */
+ detail: string;
+}
+
+/**
+ * Turn a resolution verdict into the message half of an existence finding, or
+ * `undefined` when the verdict is one no rule may report.
+ *
+ * Shared by every position that resolves a field PATH — a dataset dimension, a
+ * measure, a dataset filter key (#14105), a widget filter key (#14148) — so
+ * they cannot drift into N different accounts of the same miss. The caller
+ * supplies `subject` (how the position is named in prose) and owns the rule id,
+ * the severity, the path and the hint's prescription; this function holds none
+ * of them, matching the rest of this module.
+ */
+export function describeFieldPathVerdict(
+ verdict: FieldPathVerdict,
+ path: string,
+ subject: string,
+): FieldPathAccount | undefined {
+ switch (verdict.kind) {
+ case 'ok':
+ case 'unknowable':
+ case 'hop-untargeted':
+ return undefined;
+ case 'hop-unknown':
+ return {
+ message:
+ `${subject} "${path}" traverses "${verdict.segment}", which is not a field on object ` +
+ `"${verdict.object}".${suggestName(verdict.segment, verdict.candidates)}`,
+ detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
+ };
+ case 'hop-not-relationship':
+ return {
+ message:
+ `${subject} "${path}" traverses "${verdict.segment}", which is a` +
+ `${verdict.type ? ` \`${verdict.type}\`` : 'n ordinary'} field on object ` +
+ `"${verdict.object}" and not a relationship — there is nothing to join through.`,
+ detail:
+ `Only ${[...RELATIONSHIP_FIELD_TYPES].sort().join(' / ')} fields are traversable ` +
+ `(ADR-0021 derives every join from the object graph; you never write an ON clause).`,
+ };
+ case 'field-unknown':
+ return {
+ message:
+ `${subject} "${path}" is not a field on object "${verdict.object}".` +
+ `${suggestName(verdict.field, verdict.candidates)}`,
+ detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
+ };
+ }
+}
+
 /**
  * True when the verdict is one no rule may report — the graph could not answer.
  * Callers spell the skip through this predicate rather than re-listing the

packages/lint/src/validate-dataset-references.ts

@@ -118,12 +118,11 @@
 import { walkFilterFieldKeys } from './filter-walk.js';
 import {
  RELATIONSHIP_FIELD_TYPES,
+ describeFieldPathVerdict,
  indexObjectGraph,
  isUnjudgeable,
-listNames,
+joinablePrefixes,
  resolveFieldPath,
- suggestName,
- type FieldPathVerdict,
  type ObjectGraph,
 } from './object-graph.js';
 
@@ -172,72 +171,6 @@ function asArray(v: unknown): AnyRec[] {
  return [];
 }
 
-/**
- * The relationship prefixes a dataset declared as joinable.
- *
- * ADR-0021: *"Declaring `a.b` implicitly includes the intermediate `a`."* So
- * every PREFIX of every declared path is joinable, not only the paths as
- * written — which is why this expands rather than reading `include` verbatim.
- */
-function joinablePrefixes(include: unknown): ReadonlySet<string> {
- const prefixes = new Set<string>();
- if (!Array.isArray(include)) return prefixes;
- for (const entry of include) {
- if (typeof entry !== 'string' || !entry) continue;
- const segments = entry.split('.');
- for (let i = 1; i <= segments.length; i++) {
- prefixes.add(segments.slice(0, i).join('.'));
- }
- }
- return prefixes;
-}
-
-/**
- * Turn a resolution verdict into the message half of an existence finding, or
- * `undefined` when the verdict is one no rule may report.
- *
- * Shared by the three positions that resolve a field PATH (dimension, measure,
- * filter key) so they cannot drift into three different accounts of the same
- * miss. The caller supplies `subject` — how the position is named in prose —
- * and owns the rule id, the path and the hint's prescription.
- */
-function existenceMessage(
- verdict: FieldPathVerdict,
- path: string,
- subject: string,
-): { message: string; detail: string } | undefined {
- switch (verdict.kind) {
- case 'ok':
- case 'unknowable':
- case 'hop-untargeted':
- return undefined;
- case 'hop-unknown':
- return {
- message:
- `${subject} "${path}" traverses "${verdict.segment}", which is not a field on object ` +
- `"${verdict.object}".${suggestName(verdict.segment, verdict.candidates)}`,
- detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
- };
- case 'hop-not-relationship':
- return {
- message:
- `${subject} "${path}" traverses "${verdict.segment}", which is a` +
- `${verdict.type ? ` \`${verdict.type}\`` : 'n ordinary'} field on object ` +
- `"${verdict.object}" and not a relationship — there is nothing to join through.`,
- detail:
- `Only ${[...RELATIONSHIP_FIELD_TYPES].sort().join(' / ')} fields are traversable ` +
- `(ADR-0021 derives every join from the object graph; you never write an ON clause).`,
- };
- case 'field-unknown':
- return {
- message:
- `${subject} "${path}" is not a field on object "${verdict.object}".` +
- `${suggestName(verdict.field, verdict.candidates)}`,
- detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
- };
- }
-}
-
 /** The shared consequence sentence — why an unresolved path is not merely inert. */
 const SILENT_EMPTY =
  'The path is compiled into the analytics query as written, so it addresses a column ' +
@@ -309,7 +242,7 @@ export function validateDatasetReferences(stack: AnyRec): DatasetRefFinding[] {
  return;
  }
 
- const account = existenceMessage(verdict, entry, `include[${ii}]`);
+ const account = describeFieldPathVerdict(verdict, entry, `include[${ii}]`);
  if (!account) return;
  findings.push({
  severity: 'error',
@@ -342,7 +275,7 @@ export function validateDatasetReferences(stack: AnyRec): DatasetRefFinding[] {
  const verdict = resolveFieldPath(graph, object, written);
  if (isUnjudgeable(verdict) || !verdict) return;
 
- const account = existenceMessage(verdict, written, subject);
+ const account = describeFieldPathVerdict(verdict, written, subject);
  if (account) {
  findings.push({
  severity: 'error',

.changeset/widget-filter-sortby-resolution.md

@@ -0,0 +1,62 @@
+---
+'@objectstack/lint': minor
+---
+
+Resolve a dashboard widget's OWN `filter` keys and `options.sortBy` at validate/build
+
+A dashboard widget could filter by a column that does not exist, and order by a name
+it never selected, and `objectstack validate` exited 0 with "Validation passed";
+`build` — the publish gate — wrote the dashboard into `dist/objectstack.json`. The
+widget then rendered **empty**.
+
+The surrounding surface was already covered, which is what made the two misses so
+narrow: `widget-dataset-unknown`, `widget-dimension-unknown`, `widget-measure-unknown`,
+`filter-token-unknown` and `dashboard-filter-field-unknown` all failed both gates on the
+same dashboard. On the very same node, the filter TOKEN was checked and the filter
+COLUMN was not — `filter-token-unknown` fires path-precise at
+`…widgets[4].filter.due_date.$lte`, so the traversal already walked the filter tree and
+already knew the widget's dataset. Only the key resolution was missing. And
+`options.sortBy` was declared-≠-enforced in the plainest way available: the spec states
+the contract in its own prose — *"must be one this widget actually selects"* — and
+nothing enforced it.
+
+Why this class of miss is expensive rather than untidy, in the reporter's words: the
+dashboard it was measured on leads with a "not moving" tile — open work untouched more
+than 14 days — and *"an empty tile is indistinguishable from a healthy team: a missing
+number reads as zero, and zero is the answer the manager is hoping for."* The failure is
+silent in the direction the reader wants to believe.
+
+Three gating rule ids, all at the site that already emits `widget-dataset-unknown` /
+`dashboard-filter-field-unknown`, and all failing **`validate` and `build`** (pinned
+end-to-end, not inferred from the registry entry):
+
+- `widget-filter-field-unknown` — a key of the widget's own `filter` resolves to no
+ column on the bound dataset's object graph. Reported path-precise at
+ `dashboards[i].widgets[j].filter.<key>`, matching `filter-token-unknown`'s precision in
+ that same subtree.
+- `widget-filter-field-not-included` — the key resolves, but its relationship prefix is
+ not declared in the dataset's `include`, so ADR-0021 compiles no join and the column is
+ out of the query's reach.
+- `widget-sortby-unselected` — `options.sortBy` names neither a `dimensions[]` nor a
+ `values[]` entry of the widget. A name the dataset declares but the widget did not
+ select gets its own message, because the fix is a selection rather than a spelling.
+
+**A dotted path through a declared `include` is RESOLVED, not skipped.** A widget's
+`filter` is ANDed into the dataset query as `runtimeFilter`, and that compiled query
+carries only the joins `include` declared — so the same two clauses the dataset rule
+applies one level down (existence, then joinability) apply here. The runtime is not a
+backstop for the second: the dataset compiler's `assertDeclared` runs over `dimensions`
+and `measures` only, never over `runtimeFilter`.
+
+Built on the seams that shipped with the dataset-level sibling rather than a second
+implementation: `walkFilterFieldKeys` (all three authored filter shapes) and
+`indexObjectGraph` / `resolveFieldPath`. Two helpers that were local to that rule —
+`joinablePrefixes` and `describeFieldPathVerdict` — moved into the shared seam and are
+now exported, because both are answers this position asks identically and copying either
+would have been the second implementation the seam exists to prevent.
+
+Minor rather than patch: this narrows the accept set. Metadata that built yesterday and
+names a column or an order that does not exist now fails the build — which is the point.
+The three skips every field-existence rule in this package takes are unchanged, so an
+object the stack does not define, an ADR-0015 `external` object with no readable field
+map, and a registry-injected system column are never reported.

packages/lint/src/index.ts

@@ -24,6 +24,13 @@ export {
  WIDGET_LEGACY_ANALYTICS_UNRENDERABLE,
  DASHBOARD_FILTER_FIELD_UNKNOWN,
  DASHBOARD_FILTER_FIELD_UNPROVISIONED,
+ // [#14148] The widget's OWN two references, at the same site: the keys of its
+ // presentation-scope `filter` (resolved on the #14105 object-graph seam, with
+ // the ADR-0021 `include` clause its `runtimeFilter` really is subject to) and
+ // `options.sortBy` against what the widget selects.
+ WIDGET_FILTER_FIELD_UNKNOWN,
+ WIDGET_FILTER_FIELD_NOT_INCLUDED,
+ WIDGET_SORTBY_UNSELECTED,
 } from './validate-widget-bindings.js';
 export type { WidgetBindingFinding, WidgetBindingSeverity } from './validate-widget-bindings.js';
 
@@ -485,16 +492,26 @@ export type { DatasetRefFinding, DatasetRefSeverity } from './validate-dataset-r
 // positions) must reuse ONE mechanism rather than growing a second hop-walker
 // and a second filter-key reader. Both hold mechanism only — no rule ids, no
 // severities, no findings; the judgement stays with the rule that asks.
+// [#14148] `joinablePrefixes` and `describeFieldPathVerdict` joined them when
+// the widget limb landed: both were local to the dataset rule, and both are
+// answers to questions the widget position asks identically — how ADR-0021
+// expands an `include` into joinable prefixes, and how one verdict reads in
+// prose. Copying either would have been the second implementation this seam
+// exists to prevent, one release after it was written to prevent it.
 export {
  indexObjectGraph,
  resolveFieldPath,
  isUnjudgeable,
+ joinablePrefixes,
+ describeFieldPathVerdict,
  nearestName,
  suggestName,
  listNames,
  RELATIONSHIP_FIELD_TYPES,
 } from './object-graph.js';
-export type { ObjectGraph, GraphObject, GraphField, FieldPathVerdict } from './object-graph.js';
+export type {
+ ObjectGraph, GraphObject, GraphField, FieldPathVerdict, FieldPathAccount,
+} from './object-graph.js';
 export { walkFilterFieldKeys } from './filter-walk.js';
 export type { FilterFieldKey } from './filter-walk.js';
 

packages/lint/src/object-graph.ts

@@ -248,6 +248,89 @@ export function resolveFieldPath(
  return { kind: 'field-unknown', object: current, field: leaf, candidates: obj.names };
 }
 
+/**
+ * The relationship prefixes a document declared as joinable.
+ *
+ * ADR-0021: *"Declaring `a.b` implicitly includes the intermediate `a`."* So
+ * every PREFIX of every declared path is joinable, not only the paths as
+ * written — which is why this expands rather than reading `include` verbatim.
+ *
+ * Here rather than in a rule because the SAME `include` governs positions two
+ * different rules judge: a dataset's own `dimensions[].field` / `measures[].field`
+ * / filter keys (#14105), and a dashboard widget's `filter` keys (#14148), whose
+ * condition is ANDed into that same dataset's compiled query as `runtimeFilter`.
+ * Two copies of the prefix expansion would let the two positions drift apart on
+ * a clause that is one sentence of one ADR.
+ */
+export function joinablePrefixes(include: unknown): ReadonlySet<string> {
+ const prefixes = new Set<string>();
+ if (!Array.isArray(include)) return prefixes;
+ for (const entry of include) {
+ if (typeof entry !== 'string' || !entry) continue;
+ const segments = entry.split('.');
+ for (let i = 1; i <= segments.length; i++) {
+ prefixes.add(segments.slice(0, i).join('.'));
+ }
+ }
+ return prefixes;
+}
+
+/** The two halves of a rendered verdict: the finding's message, and its detail. */
+export interface FieldPathAccount {
+ /** What is wrong, in prose, carrying the "did you mean" when there is one. */
+ message: string;
+ /** The supporting field list, for the finding's hint. */
+ detail: string;
+}
+
+/**
+ * Turn a resolution verdict into the message half of an existence finding, or
+ * `undefined` when the verdict is one no rule may report.
+ *
+ * Shared by every position that resolves a field PATH — a dataset dimension, a
+ * measure, a dataset filter key (#14105), a widget filter key (#14148) — so
+ * they cannot drift into N different accounts of the same miss. The caller
+ * supplies `subject` (how the position is named in prose) and owns the rule id,
+ * the severity, the path and the hint's prescription; this function holds none
+ * of them, matching the rest of this module.
+ */
+export function describeFieldPathVerdict(
+ verdict: FieldPathVerdict,
+ path: string,
+ subject: string,
+): FieldPathAccount | undefined {
+ switch (verdict.kind) {
+ case 'ok':
+ case 'unknowable':
+ case 'hop-untargeted':
+ return undefined;
+ case 'hop-unknown':
+ return {
+ message:
+ `${subject} "${path}" traverses "${verdict.segment}", which is not a field on object ` +
+ `"${verdict.object}".${suggestName(verdict.segment, verdict.candidates)}`,
+ detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
+ };
+ case 'hop-not-relationship':
+ return {
+ message:
+ `${subject} "${path}" traverses "${verdict.segment}", which is a` +
+ `${verdict.type ? ` \`${verdict.type}\`` : 'n ordinary'} field on object ` +
+ `"${verdict.object}" and not a relationship — there is nothing to join through.`,
+ detail:
+ `Only ${[...RELATIONSHIP_FIELD_TYPES].sort().join(' / ')} fields are traversable ` +
+ `(ADR-0021 derives every join from the object graph; you never write an ON clause).`,
+ };
+ case 'field-unknown':
+ return {
+ message:
+ `${subject} "${path}" is not a field on object "${verdict.object}".` +
+ `${suggestName(verdict.field, verdict.candidates)}`,
+ detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
+ };
+ }
+}
+
 /**
  * True when the verdict is one no rule may report — the graph could not answer.
  * Callers spell the skip through this predicate rather than re-listing the

packages/lint/src/validate-dataset-references.ts

@@ -118,12 +118,11 @@
 import { walkFilterFieldKeys } from './filter-walk.js';
 import {
  RELATIONSHIP_FIELD_TYPES,
+ describeFieldPathVerdict,
  indexObjectGraph,
  isUnjudgeable,
-listNames,
+joinablePrefixes,
  resolveFieldPath,
- suggestName,
- type FieldPathVerdict,
  type ObjectGraph,
 } from './object-graph.js';
 
@@ -172,72 +171,6 @@ function asArray(v: unknown): AnyRec[] {
  return [];
 }
 
-/**
- * The relationship prefixes a dataset declared as joinable.
- *
- * ADR-0021: *"Declaring `a.b` implicitly includes the intermediate `a`."* So
- * every PREFIX of every declared path is joinable, not only the paths as
- * written — which is why this expands rather than reading `include` verbatim.
- */
-function joinablePrefixes(include: unknown): ReadonlySet<string> {
- const prefixes = new Set<string>();
- if (!Array.isArray(include)) return prefixes;
- for (const entry of include) {
- if (typeof entry !== 'string' || !entry) continue;
- const segments = entry.split('.');
- for (let i = 1; i <= segments.length; i++) {
- prefixes.add(segments.slice(0, i).join('.'));
- }
- }
- return prefixes;
-}
-
-/**
- * Turn a resolution verdict into the message half of an existence finding, or
- * `undefined` when the verdict is one no rule may report.
- *
- * Shared by the three positions that resolve a field PATH (dimension, measure,
- * filter key) so they cannot drift into three different accounts of the same
- * miss. The caller supplies `subject` — how the position is named in prose —
- * and owns the rule id, the path and the hint's prescription.
- */
-function existenceMessage(
- verdict: FieldPathVerdict,
- path: string,
- subject: string,
-): { message: string; detail: string } | undefined {
- switch (verdict.kind) {
- case 'ok':
- case 'unknowable':
- case 'hop-untargeted':
- return undefined;
- case 'hop-unknown':
- return {
- message:
- `${subject} "${path}" traverses "${verdict.segment}", which is not a field on object ` +
- `"${verdict.object}".${suggestName(verdict.segment, verdict.candidates)}`,
- detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
- };
- case 'hop-not-relationship':
- return {
- message:
- `${subject} "${path}" traverses "${verdict.segment}", which is a` +
- `${verdict.type ? ` \`${verdict.type}\`` : 'n ordinary'} field on object ` +
- `"${verdict.object}" and not a relationship — there is nothing to join through.`,
- detail:
- `Only ${[...RELATIONSHIP_FIELD_TYPES].sort().join(' / ')} fields are traversable ` +
- `(ADR-0021 derives every join from the object graph; you never write an ON clause).`,
- };
- case 'field-unknown':
- return {
- message:
- `${subject} "${path}" is not a field on object "${verdict.object}".` +
- `${suggestName(verdict.field, verdict.candidates)}`,
- detail: `Fields on "${verdict.object}": ${listNames(verdict.candidates)}.`,
- };
- }
-}
-
 /** The shared consequence sentence — why an unresolved path is not merely inert. */
 const SILENT_EMPTY =
  'The path is compiled into the analytics query as written, so it addresses a column ' +
@@ -309,7 +242,7 @@ export function validateDatasetReferences(stack: AnyRec): DatasetRefFinding[] {
  return;
  }
 
- const account = existenceMessage(verdict, entry, `include[${ii}]`);
+ const account = describeFieldPathVerdict(verdict, entry, `include[${ii}]`);
  if (!account) return;
  findings.push({
  severity: 'error',
@@ -342,7 +275,7 @@ export function validateDatasetReferences(stack: AnyRec): DatasetRefFinding[] {
  const verdict = resolveFieldPath(graph, object, written);
  if (isUnjudgeable(verdict) || !verdict) return;
 
- const account = existenceMessage(verdict, written, subject);
+ const account = describeFieldPathVerdict(verdict, written, subject);
  if (account) {
  findings.push({
  severity: 'error',