objectstack-ai · baozhoutao · Sep 1, 2026 · Sep 1, 2026 · objectstack-ai · baozhoutao
diff --git a/.changeset/dataset-reference-resolution.md b/.changeset/dataset-reference-resolution.md
@@ -0,0 +1,95 @@
+---
+'@objectstack/lint': minor
+---
+
+Resolve an ADR-0021 dataset's own references — base object, `include[]`,
+`dimensions[].field` / `measures[].field`, and filter KEYS — at
+`validate`/`build` (#14105)
+
+A dataset could name a **base object that does not exist**, join a
+**relationship that does not exist**, and bind every dimension and measure to
+**fields that do not exist**, and `objectstack validate` exited **0** with
+`✓ Validation passed`. `objectstack build` also exited 0 and wrote the dangling
+dataset into `dist/objectstack.json`.
+
+The sting was that the author-time rule pass **already walked those exact
+nodes**. Measured on published 17.2.0, each mutation applied on its own and
+confirmed on disk before running:
+
+| mutation | before | after |
+|:----------------------------------------------------|:-------|:------|
+| dimension `field` → a base field that does not exist | passed | `dataset-field-unknown` |
+| dimension `field` → a joined field that does not exist | passed | `dataset-field-unknown` |
+| measure `field` → a field that does not exist | passed | `dataset-field-unknown` |
+| measure filter KEY → a field that does not exist | passed | `dataset-filter-field-unknown` |
+| `include[]` → a relationship that does not exist | passed | `dataset-include-unknown` |
+| `object` → an object that does not exist | passed | `object-reference-unknown` |
+
+The two controls in that measurement — a duplicate measure name
+(`DatasetSchema.superRefine`) and a bad date macro in a **measure filter**
+(`filter-token-unknown`) — both failed the build, so datasets were
+demonstrably in the validation path the whole time. `filter-token-unknown`
+already stood at `datasets[1].measures[1].filter.last_update_at.$lt` and
+reasoned about the **value**; nothing standing in that same position resolved
+the **key**, or the sibling `field` one level up.
+
+This matters more for a dataset than for most metadata because a dataset is the
+semantic layer: dashboards and reports bind its dimensions and measures by name
+(ADR-0021), and the consumer end of that binding is already guarded
+(`widget-dataset-unknown` / `widget-dimension-unknown` / `widget-measure-unknown`,
+#7529/#8902). So the surviving hole was the quiet one — every binding resolves,
+the board renders, and the charts are empty or subtly wrong because the dataset
+underneath addresses columns that do not exist.
+
+**Five verdicts, all `error`.** Four are new rule ids on a new suite member,
+`validateDatasetReferences`:
+
+- `dataset-include-unknown` — an `include[]` entry that resolves to nothing, or
+ to a field that is not a relationship, so no join can be derived from it.
+- `dataset-field-unknown` — a dimension or measure `field` path that resolves to
+ no column, on the base object or on any joined object along the path.
+- `dataset-field-not-included` — the second real check: a dotted path that
+ RESOLVES, but whose relationship prefix was never declared in `include`.
+ ADR-0021 D-C joins only declared paths, so the column is out of the query's
+ reach however real it is.
+- `dataset-filter-field-unknown` — a filter key on `Dataset.filter` or
+ `measures[].filter`, in any of the three authored filter shapes.
+
+The fifth, the base object itself, lands on `validateObjectReferences` as a new
+`datasets[].object` reference site rather than as a sixth id here. That rule's
+charter IS object-name references that are plain `z.string()`, and putting it
+there buys the curated cross-package severity ladder: the platform's own
+`system.datasets.ts` declares five datasets over `sys_*` objects, three of which
+live in packages a stack compiling plugin-auth alone cannot see. All five
+resolve through `PLATFORM_PROVIDED_OBJECT_NAMES`; a local "not in this stack ⇒
+error" check would have reported every one of them. When the base object does
+not resolve, `validateDatasetReferences` skips the dataset entirely, so one typo
+yields one finding rather than one per dimension, measure and filter key.
+
+**Skips, so a finding is never a guess** (ADR-0072 D1): an object this stack
+does not define, an object with no readable field map (ADR-0015 `external` and
+introspected schemas), a registry-injected system column, and any hop *through*
+one — an injected `owner_id` is a lookup at the registry whose target is
+invisible here, so `owner_id.name` is unanswerable rather than a miss. The
+shipped `showcase_task_metrics` dimension `{ field: 'created_at' }` is that skip's
+live case, and every shipped dataset in the repo is silent under the new rule.
+
+**Two reusable seams ship with it**, newly exported, because the same two
+questions are asked at a dashboard widget's filter keys and `sortBy` and at a
+list view's field positions, and three independent copies of a hop-walker drift:
+
+- `object-graph.ts` — `indexObjectGraph` / `resolveFieldPath` / `isUnjudgeable`,
+ answering "what does this `relationship[.relationship].field` path resolve to?"
+ as a discriminated **verdict** union rather than a boolean, so a caller can
+ tell "this hop is not a relationship" from "this leaf does not exist" and write
+ the right prescription. Plus `nearestName` / `suggestName` / `listNames`.
+- `walkFilterFieldKeys` (`filter-walk.ts`) — the FIELD-KEY half of a filter
+ subtree, beside the subtree-finding half that module already owns. It handles
+ all three authored shapes (Mongo condition object, `{ field, operator, value }`
+ rules, `[field, op, value]` triples), because a reader that handles only one
+ shape is the exact bug #3574 was filed against, and it composes a nested
+ condition object into one relationship path so `{ account: { region: … } }`
+ reports `account.region` rather than a bare `region` resolved against the
+ wrong object.
+
+Both hold mechanism only — no rule ids, no severities, no findings.
diff --git a/packages/lint/src/filter-walk.ts b/packages/lint/src/filter-walk.ts
@@ -35,8 +35,21 @@
  * they resolve an additional vocabulary (`AppContextSelector` ids such as
  * `{active_package}`) that is meaningless in a filter, and restricting the walk
  * is what holds false positives at zero.
+ *
+ * ## The two halves of a filter, and where each one is answered
+ *
+ * `walkAuthoredFilters` finds the SUBTREES. Inside one, a rule wants either the
+ * VALUES (`validate-filter-tokens.ts` classifies placeholders in them;
+ * `validate-preset-comparands.ts` judges ordering comparands) or the FIELD KEYS
+ * — the names the query is filtered BY. {@link walkFilterFieldKeys} is the
+ * second half (#14105), and it is here rather than in its first caller because
+ * the shape dispatch is identical to the one `validate-preset-comparands.ts`
+ * already performs on values: the platform authors filters three ways, and a
+ * reader that handles only one shape is the exact bug #3574 was filed against.
  */
 
+import { VALID_AST_OPERATORS } from '@objectstack/spec/data';
+
 /** Any plain metadata record. */
 type AnyRec = Record<string, unknown>;
 
@@ -162,3 +175,122 @@ export function walkAuthoredFilters(
  });
  }
 }
+
+// ── The FIELD-KEY half of a filter subtree (#14105) ──────────────────────────
+
+/** One field position inside an authored filter. */
+export interface FilterFieldKey {
+ /**
+ * The field the condition filters BY, exactly as authored — a bare name
+ * (`status`), or a dotted relationship path (`account.region`, whether
+ * spelled that way or reached by descending a nested condition object).
+ */
+ field: string;
+ /** Config path of the position, e.g. `datasets[1].measures[1].filter.last_update_at`. */
+ path: string;
+}
+
+/** Recursion guard — an authored filter is a bounded document, not a graph. */
+const MAX_KEY_DEPTH = 32;
+
+function isPlainObject(v: unknown): v is AnyRec {
+ return !!v && typeof v === 'object' && !Array.isArray(v) && !(v instanceof Date);
+}
+
+/**
+ * Emit the field positions of one Mongo-style condition NODE.
+ *
+ * `prefix` carries the relationship path accumulated by descending nested
+ * condition objects, so `{ account: { region: { $eq: 'emea' } } }` reports the
+ * single position `account.region` rather than a bare `region` that would
+ * resolve against the wrong object. A node whose value carries `$` operators is
+ * a leaf condition and ends the descent; a `$`-prefixed key that is not a
+ * recognised combinator is skipped and NOT descended, matching
+ * `validate-preset-comparands.ts` — an unrecognised operator's operand shape is
+ * not ours to guess.
+ */
+function conditionFieldKeys(
+ node: AnyRec,
+ path: string,
+ prefix: string,
+ visit: (key: FilterFieldKey) => void,
+ depth: number,
+): void {
+ if (depth > MAX_KEY_DEPTH) return;
+ for (const [key, value] of Object.entries(node)) {
+ const here = `${path}.${key}`;
+ if (key === '$and' || key === '$or') {
+ if (Array.isArray(value)) {
+ value.forEach((arm, i) => {
+ if (isPlainObject(arm)) conditionFieldKeys(arm, `${here}[${i}]`, prefix, visit, depth + 1);
+ });
+ }
+ continue;
+ }
+ if (key === '$not') {
+ if (isPlainObject(value)) conditionFieldKeys(value, here, prefix, visit, depth + 1);
+ continue;
+ }
+ if (key.startsWith('$')) continue; // unrecognised combinator
+ const field = prefix ? `${prefix}.${key}` : key;
+ if (isPlainObject(value) && !Object.keys(value).some((k) => k.startsWith('$'))) {
+ // Nested relation / deep equality — the field position is one level
+ // deeper, so descend rather than reporting the intermediate hop twice.
+ // An EMPTY nested object addresses nothing further; report the hop itself.
+ if (Object.keys(value).length > 0) {
+ conditionFieldKeys(value, here, field, visit, depth + 1);
+ continue;
+ }
+ }
+ visit({ field, path: here });
+ }
+}
+
+/**
+ * Emit every FIELD KEY inside one authored filter subtree, whatever shape it
+ * was authored in — the key half of what `validate-preset-comparands.ts` does
+ * for values, and the traversal `filter-token-unknown` already performs while
+ * reasoning only about the strings it finds.
+ *
+ * Holds no judgement: it does not know which object the filter is bound to and
+ * emits no findings. Resolution is {@link resolveFieldPath}'s job
+ * (`object-graph.ts`) and the verdict is the caller's.
+ */
+export function walkFilterFieldKeys(
+ node: unknown,
+ path: string,
+ visit: (key: FilterFieldKey) => void,
+ depth = 0,
+): void {
+ if (depth > MAX_KEY_DEPTH) return;
+
+ if (Array.isArray(node)) {
+ // Triple: ['field', op, value] — the field position is a non-keyword
+ // string and the operator position is in the AST vocabulary (the
+ // `isFilterAST` test `validate-preset-comparands.ts` uses).
+ if (
+ typeof node[0] === 'string' && typeof node[1] === 'string'
+ && !['and', 'or'].includes(node[0].toLowerCase())
+ && VALID_AST_OPERATORS.has(node[1].toLowerCase())
+ ) {
+ visit({ field: node[0], path: `${path}[0]` });
+ return;
+ }
+ // Group ['and'|'or', ...members] or a bare list — recurse the members.
+ node.forEach((member, i) => {
+ if (typeof member === 'string') return; // the leading keyword
+ walkFilterFieldKeys(member, `${path}[${i}]`, visit, depth + 1);
+ });
+ return;
+ }
+
+ if (!isPlainObject(node)) return;
+
+ // View filter rule: { field, operator[, value] }.
+ if (typeof node.field === 'string' && typeof node.operator === 'string') {
+ visit({ field: node.field, path: `${path}.field` });
+ return;
+ }
+
+ conditionFieldKeys(node, path, '', visit, depth);
+}
diff --git a/packages/lint/src/index.ts b/packages/lint/src/index.ts
@@ -467,6 +467,37 @@ export {
 } from './validate-chart-bindings.js';
 export type { ChartBindingFinding, ChartBindingSeverity } from './validate-chart-bindings.js';
 
+// [#14105] The layer BELOW the chart/widget binding rules above: a dataset's
+// own `include[]`, `dimensions[].field`, `measures[].field` and filter KEYS,
+// resolved against the object graph. Its base-object half is
+// `validateObjectReferences`' `datasets[].object` site.
+export {
+ validateDatasetReferences,
+ DATASET_INCLUDE_UNKNOWN,
+ DATASET_FIELD_UNKNOWN,
+ DATASET_FIELD_NOT_INCLUDED,
+ DATASET_FILTER_FIELD_UNKNOWN,
+} from './validate-dataset-references.js';
+export type { DatasetRefFinding, DatasetRefSeverity } from './validate-dataset-references.js';
+
+// The two reusable seams the rule above is written on, exported because the
+// queued siblings (#14148 widget filter keys + sortBy, #14107 list-view field
+// 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.
+export {
+ indexObjectGraph,
+ resolveFieldPath,
+ isUnjudgeable,
+ nearestName,
+ suggestName,
+ listNames,
+ RELATIONSHIP_FIELD_TYPES,
+} from './object-graph.js';
+export type { ObjectGraph, GraphObject, GraphField, FieldPathVerdict } from './object-graph.js';
+export { walkFilterFieldKeys } from './filter-walk.js';
+export type { FilterFieldKey } from './filter-walk.js';
+
 // #4762 — the two STATIC artifacts an object validation rule carries (a
 // `format` rule's `regex`, a `json_schema` rule's `schema`) are fail-OPEN at
 // runtime: one that does not compile is logged and skipped, so the rule is

diff --git a/.changeset/dataset-reference-resolution.md b/.changeset/dataset-reference-resolution.md
@@ -0,0 +1,95 @@
+---
+'@objectstack/lint': minor
+---
+
+Resolve an ADR-0021 dataset's own references — base object, `include[]`,
+`dimensions[].field` / `measures[].field`, and filter KEYS — at
+`validate`/`build` (#14105)
+
+A dataset could name a **base object that does not exist**, join a
+**relationship that does not exist**, and bind every dimension and measure to
+**fields that do not exist**, and `objectstack validate` exited **0** with
+`✓ Validation passed`. `objectstack build` also exited 0 and wrote the dangling
+dataset into `dist/objectstack.json`.
+
+The sting was that the author-time rule pass **already walked those exact
+nodes**. Measured on published 17.2.0, each mutation applied on its own and
+confirmed on disk before running:
+
+| mutation | before | after |
+|:----------------------------------------------------|:-------|:------|
+| dimension `field` → a base field that does not exist | passed | `dataset-field-unknown` |
+| dimension `field` → a joined field that does not exist | passed | `dataset-field-unknown` |
+| measure `field` → a field that does not exist | passed | `dataset-field-unknown` |
+| measure filter KEY → a field that does not exist | passed | `dataset-filter-field-unknown` |
+| `include[]` → a relationship that does not exist | passed | `dataset-include-unknown` |
+| `object` → an object that does not exist | passed | `object-reference-unknown` |
+
+The two controls in that measurement — a duplicate measure name
+(`DatasetSchema.superRefine`) and a bad date macro in a **measure filter**
+(`filter-token-unknown`) — both failed the build, so datasets were
+demonstrably in the validation path the whole time. `filter-token-unknown`
+already stood at `datasets[1].measures[1].filter.last_update_at.$lt` and
+reasoned about the **value**; nothing standing in that same position resolved
+the **key**, or the sibling `field` one level up.
+
+This matters more for a dataset than for most metadata because a dataset is the
+semantic layer: dashboards and reports bind its dimensions and measures by name
+(ADR-0021), and the consumer end of that binding is already guarded
+(`widget-dataset-unknown` / `widget-dimension-unknown` / `widget-measure-unknown`,
+#7529/#8902). So the surviving hole was the quiet one — every binding resolves,
+the board renders, and the charts are empty or subtly wrong because the dataset
+underneath addresses columns that do not exist.
+
+**Five verdicts, all `error`.** Four are new rule ids on a new suite member,
+`validateDatasetReferences`:
+
+- `dataset-include-unknown` — an `include[]` entry that resolves to nothing, or
+ to a field that is not a relationship, so no join can be derived from it.
+- `dataset-field-unknown` — a dimension or measure `field` path that resolves to
+ no column, on the base object or on any joined object along the path.
+- `dataset-field-not-included` — the second real check: a dotted path that
+ RESOLVES, but whose relationship prefix was never declared in `include`.
+ ADR-0021 D-C joins only declared paths, so the column is out of the query's
+ reach however real it is.
+- `dataset-filter-field-unknown` — a filter key on `Dataset.filter` or
+ `measures[].filter`, in any of the three authored filter shapes.
+
+The fifth, the base object itself, lands on `validateObjectReferences` as a new
+`datasets[].object` reference site rather than as a sixth id here. That rule's
+charter IS object-name references that are plain `z.string()`, and putting it
+there buys the curated cross-package severity ladder: the platform's own
+`system.datasets.ts` declares five datasets over `sys_*` objects, three of which
+live in packages a stack compiling plugin-auth alone cannot see. All five
+resolve through `PLATFORM_PROVIDED_OBJECT_NAMES`; a local "not in this stack ⇒
+error" check would have reported every one of them. When the base object does
+not resolve, `validateDatasetReferences` skips the dataset entirely, so one typo
+yields one finding rather than one per dimension, measure and filter key.
+
+**Skips, so a finding is never a guess** (ADR-0072 D1): an object this stack
+does not define, an object with no readable field map (ADR-0015 `external` and
+introspected schemas), a registry-injected system column, and any hop *through*
+one — an injected `owner_id` is a lookup at the registry whose target is
+invisible here, so `owner_id.name` is unanswerable rather than a miss. The
+shipped `showcase_task_metrics` dimension `{ field: 'created_at' }` is that skip's
+live case, and every shipped dataset in the repo is silent under the new rule.
+
+**Two reusable seams ship with it**, newly exported, because the same two
+questions are asked at a dashboard widget's filter keys and `sortBy` and at a
+list view's field positions, and three independent copies of a hop-walker drift:
+
+- `object-graph.ts` — `indexObjectGraph` / `resolveFieldPath` / `isUnjudgeable`,
+ answering "what does this `relationship[.relationship].field` path resolve to?"
+ as a discriminated **verdict** union rather than a boolean, so a caller can
+ tell "this hop is not a relationship" from "this leaf does not exist" and write
+ the right prescription. Plus `nearestName` / `suggestName` / `listNames`.
+- `walkFilterFieldKeys` (`filter-walk.ts`) — the FIELD-KEY half of a filter
+ subtree, beside the subtree-finding half that module already owns. It handles
+ all three authored shapes (Mongo condition object, `{ field, operator, value }`
+ rules, `[field, op, value]` triples), because a reader that handles only one
+ shape is the exact bug #3574 was filed against, and it composes a nested
+ condition object into one relationship path so `{ account: { region: … } }`
+ reports `account.region` rather than a bare `region` resolved against the
+ wrong object.
+
+Both hold mechanism only — no rule ids, no severities, no findings.
diff --git a/packages/lint/src/filter-walk.ts b/packages/lint/src/filter-walk.ts
@@ -35,8 +35,21 @@
  * they resolve an additional vocabulary (`AppContextSelector` ids such as
  * `{active_package}`) that is meaningless in a filter, and restricting the walk
  * is what holds false positives at zero.
+ *
+ * ## The two halves of a filter, and where each one is answered
+ *
+ * `walkAuthoredFilters` finds the SUBTREES. Inside one, a rule wants either the
+ * VALUES (`validate-filter-tokens.ts` classifies placeholders in them;
+ * `validate-preset-comparands.ts` judges ordering comparands) or the FIELD KEYS
+ * — the names the query is filtered BY. {@link walkFilterFieldKeys} is the
+ * second half (#14105), and it is here rather than in its first caller because
+ * the shape dispatch is identical to the one `validate-preset-comparands.ts`
+ * already performs on values: the platform authors filters three ways, and a
+ * reader that handles only one shape is the exact bug #3574 was filed against.
  */
 
+import { VALID_AST_OPERATORS } from '@objectstack/spec/data';
+
 /** Any plain metadata record. */
 type AnyRec = Record<string, unknown>;
 
@@ -162,3 +175,122 @@ export function walkAuthoredFilters(
  });
  }
 }
+
+// ── The FIELD-KEY half of a filter subtree (#14105) ──────────────────────────
+
+/** One field position inside an authored filter. */
+export interface FilterFieldKey {
+ /**
+ * The field the condition filters BY, exactly as authored — a bare name
+ * (`status`), or a dotted relationship path (`account.region`, whether
+ * spelled that way or reached by descending a nested condition object).
+ */
+ field: string;
+ /** Config path of the position, e.g. `datasets[1].measures[1].filter.last_update_at`. */
+ path: string;
+}
+
+/** Recursion guard — an authored filter is a bounded document, not a graph. */
+const MAX_KEY_DEPTH = 32;
+
+function isPlainObject(v: unknown): v is AnyRec {
+ return !!v && typeof v === 'object' && !Array.isArray(v) && !(v instanceof Date);
+}
+
+/**
+ * Emit the field positions of one Mongo-style condition NODE.
+ *
+ * `prefix` carries the relationship path accumulated by descending nested
+ * condition objects, so `{ account: { region: { $eq: 'emea' } } }` reports the
+ * single position `account.region` rather than a bare `region` that would
+ * resolve against the wrong object. A node whose value carries `$` operators is
+ * a leaf condition and ends the descent; a `$`-prefixed key that is not a
+ * recognised combinator is skipped and NOT descended, matching
+ * `validate-preset-comparands.ts` — an unrecognised operator's operand shape is
+ * not ours to guess.
+ */
+function conditionFieldKeys(
+ node: AnyRec,
+ path: string,
+ prefix: string,
+ visit: (key: FilterFieldKey) => void,
+ depth: number,
+): void {
+ if (depth > MAX_KEY_DEPTH) return;
+ for (const [key, value] of Object.entries(node)) {
+ const here = `${path}.${key}`;
+ if (key === '$and' || key === '$or') {
+ if (Array.isArray(value)) {
+ value.forEach((arm, i) => {
+ if (isPlainObject(arm)) conditionFieldKeys(arm, `${here}[${i}]`, prefix, visit, depth + 1);
+ });
+ }
+ continue;
+ }
+ if (key === '$not') {
+ if (isPlainObject(value)) conditionFieldKeys(value, here, prefix, visit, depth + 1);
+ continue;
+ }
+ if (key.startsWith('$')) continue; // unrecognised combinator
+ const field = prefix ? `${prefix}.${key}` : key;
+ if (isPlainObject(value) && !Object.keys(value).some((k) => k.startsWith('$'))) {
+ // Nested relation / deep equality — the field position is one level
+ // deeper, so descend rather than reporting the intermediate hop twice.
+ // An EMPTY nested object addresses nothing further; report the hop itself.
+ if (Object.keys(value).length > 0) {
+ conditionFieldKeys(value, here, field, visit, depth + 1);
+ continue;
+ }
+ }
+ visit({ field, path: here });
+ }
+}
+
+/**
+ * Emit every FIELD KEY inside one authored filter subtree, whatever shape it
+ * was authored in — the key half of what `validate-preset-comparands.ts` does
+ * for values, and the traversal `filter-token-unknown` already performs while
+ * reasoning only about the strings it finds.
+ *
+ * Holds no judgement: it does not know which object the filter is bound to and
+ * emits no findings. Resolution is {@link resolveFieldPath}'s job
+ * (`object-graph.ts`) and the verdict is the caller's.
+ */
+export function walkFilterFieldKeys(
+ node: unknown,
+ path: string,
+ visit: (key: FilterFieldKey) => void,
+ depth = 0,
+): void {
+ if (depth > MAX_KEY_DEPTH) return;
+
+ if (Array.isArray(node)) {
+ // Triple: ['field', op, value] — the field position is a non-keyword
+ // string and the operator position is in the AST vocabulary (the
+ // `isFilterAST` test `validate-preset-comparands.ts` uses).
+ if (
+ typeof node[0] === 'string' && typeof node[1] === 'string'
+ && !['and', 'or'].includes(node[0].toLowerCase())
+ && VALID_AST_OPERATORS.has(node[1].toLowerCase())
+ ) {
+ visit({ field: node[0], path: `${path}[0]` });
+ return;
+ }
+ // Group ['and'|'or', ...members] or a bare list — recurse the members.
+ node.forEach((member, i) => {
+ if (typeof member === 'string') return; // the leading keyword
+ walkFilterFieldKeys(member, `${path}[${i}]`, visit, depth + 1);
+ });
+ return;
+ }
+
+ if (!isPlainObject(node)) return;
+
+ // View filter rule: { field, operator[, value] }.
+ if (typeof node.field === 'string' && typeof node.operator === 'string') {
+ visit({ field: node.field, path: `${path}.field` });
+ return;
+ }
+
+ conditionFieldKeys(node, path, '', visit, depth);
+}
diff --git a/packages/lint/src/index.ts b/packages/lint/src/index.ts
@@ -467,6 +467,37 @@ export {
 } from './validate-chart-bindings.js';
 export type { ChartBindingFinding, ChartBindingSeverity } from './validate-chart-bindings.js';
 
+// [#14105] The layer BELOW the chart/widget binding rules above: a dataset's
+// own `include[]`, `dimensions[].field`, `measures[].field` and filter KEYS,
+// resolved against the object graph. Its base-object half is
+// `validateObjectReferences`' `datasets[].object` site.
+export {
+ validateDatasetReferences,
+ DATASET_INCLUDE_UNKNOWN,
+ DATASET_FIELD_UNKNOWN,
+ DATASET_FIELD_NOT_INCLUDED,
+ DATASET_FILTER_FIELD_UNKNOWN,
+} from './validate-dataset-references.js';
+export type { DatasetRefFinding, DatasetRefSeverity } from './validate-dataset-references.js';
+
+// The two reusable seams the rule above is written on, exported because the
+// queued siblings (#14148 widget filter keys + sortBy, #14107 list-view field
+// 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.
+export {
+ indexObjectGraph,
+ resolveFieldPath,
+ isUnjudgeable,
+ nearestName,
+ suggestName,
+ listNames,
+ RELATIONSHIP_FIELD_TYPES,
+} from './object-graph.js';
+export type { ObjectGraph, GraphObject, GraphField, FieldPathVerdict } from './object-graph.js';
+export { walkFilterFieldKeys } from './filter-walk.js';
+export type { FilterFieldKey } from './filter-walk.js';
+
 // #4762 — the two STATIC artifacts an object validation rule carries (a
 // `format` rule's `regex`, a `json_schema` rule's `schema`) are fail-OPEN at
 // runtime: one that does not compile is logged and skipped, so the rule is

diff --git a/.changeset/dataset-reference-resolution.md b/.changeset/dataset-reference-resolution.md
@@ -0,0 +1,95 @@
+---
+'@objectstack/lint': minor
+---
+
+Resolve an ADR-0021 dataset's own references — base object, `include[]`,
+`dimensions[].field` / `measures[].field`, and filter KEYS — at
+`validate`/`build` (#14105)
+
+A dataset could name a **base object that does not exist**, join a
+**relationship that does not exist**, and bind every dimension and measure to
+**fields that do not exist**, and `objectstack validate` exited **0** with
+`✓ Validation passed`. `objectstack build` also exited 0 and wrote the dangling
+dataset into `dist/objectstack.json`.
+
+The sting was that the author-time rule pass **already walked those exact
+nodes**. Measured on published 17.2.0, each mutation applied on its own and
+confirmed on disk before running:
+
+| mutation | before | after |
+|:----------------------------------------------------|:-------|:------|
+| dimension `field` → a base field that does not exist | passed | `dataset-field-unknown` |
+| dimension `field` → a joined field that does not exist | passed | `dataset-field-unknown` |
+| measure `field` → a field that does not exist | passed | `dataset-field-unknown` |
+| measure filter KEY → a field that does not exist | passed | `dataset-filter-field-unknown` |
+| `include[]` → a relationship that does not exist | passed | `dataset-include-unknown` |
+| `object` → an object that does not exist | passed | `object-reference-unknown` |
+
+The two controls in that measurement — a duplicate measure name
+(`DatasetSchema.superRefine`) and a bad date macro in a **measure filter**
+(`filter-token-unknown`) — both failed the build, so datasets were
+demonstrably in the validation path the whole time. `filter-token-unknown`
+already stood at `datasets[1].measures[1].filter.last_update_at.$lt` and
+reasoned about the **value**; nothing standing in that same position resolved
+the **key**, or the sibling `field` one level up.
+
+This matters more for a dataset than for most metadata because a dataset is the
+semantic layer: dashboards and reports bind its dimensions and measures by name
+(ADR-0021), and the consumer end of that binding is already guarded
+(`widget-dataset-unknown` / `widget-dimension-unknown` / `widget-measure-unknown`,
+#7529/#8902). So the surviving hole was the quiet one — every binding resolves,
+the board renders, and the charts are empty or subtly wrong because the dataset
+underneath addresses columns that do not exist.
+
+**Five verdicts, all `error`.** Four are new rule ids on a new suite member,
+`validateDatasetReferences`:
+
+- `dataset-include-unknown` — an `include[]` entry that resolves to nothing, or
+ to a field that is not a relationship, so no join can be derived from it.
+- `dataset-field-unknown` — a dimension or measure `field` path that resolves to
+ no column, on the base object or on any joined object along the path.
+- `dataset-field-not-included` — the second real check: a dotted path that
+ RESOLVES, but whose relationship prefix was never declared in `include`.
+ ADR-0021 D-C joins only declared paths, so the column is out of the query's
+ reach however real it is.
+- `dataset-filter-field-unknown` — a filter key on `Dataset.filter` or
+ `measures[].filter`, in any of the three authored filter shapes.
+
+The fifth, the base object itself, lands on `validateObjectReferences` as a new
+`datasets[].object` reference site rather than as a sixth id here. That rule's
+charter IS object-name references that are plain `z.string()`, and putting it
+there buys the curated cross-package severity ladder: the platform's own
+`system.datasets.ts` declares five datasets over `sys_*` objects, three of which
+live in packages a stack compiling plugin-auth alone cannot see. All five
+resolve through `PLATFORM_PROVIDED_OBJECT_NAMES`; a local "not in this stack ⇒
+error" check would have reported every one of them. When the base object does
+not resolve, `validateDatasetReferences` skips the dataset entirely, so one typo
+yields one finding rather than one per dimension, measure and filter key.
+
+**Skips, so a finding is never a guess** (ADR-0072 D1): an object this stack
+does not define, an object with no readable field map (ADR-0015 `external` and
+introspected schemas), a registry-injected system column, and any hop *through*
+one — an injected `owner_id` is a lookup at the registry whose target is
+invisible here, so `owner_id.name` is unanswerable rather than a miss. The
+shipped `showcase_task_metrics` dimension `{ field: 'created_at' }` is that skip's
+live case, and every shipped dataset in the repo is silent under the new rule.
+
+**Two reusable seams ship with it**, newly exported, because the same two
+questions are asked at a dashboard widget's filter keys and `sortBy` and at a
+list view's field positions, and three independent copies of a hop-walker drift:
+
+- `object-graph.ts` — `indexObjectGraph` / `resolveFieldPath` / `isUnjudgeable`,
+ answering "what does this `relationship[.relationship].field` path resolve to?"
+ as a discriminated **verdict** union rather than a boolean, so a caller can
+ tell "this hop is not a relationship" from "this leaf does not exist" and write
+ the right prescription. Plus `nearestName` / `suggestName` / `listNames`.
+- `walkFilterFieldKeys` (`filter-walk.ts`) — the FIELD-KEY half of a filter
+ subtree, beside the subtree-finding half that module already owns. It handles
+ all three authored shapes (Mongo condition object, `{ field, operator, value }`
+ rules, `[field, op, value]` triples), because a reader that handles only one
+ shape is the exact bug #3574 was filed against, and it composes a nested
+ condition object into one relationship path so `{ account: { region: … } }`
+ reports `account.region` rather than a bare `region` resolved against the
+ wrong object.
+
+Both hold mechanism only — no rule ids, no severities, no findings.
diff --git a/packages/lint/src/filter-walk.ts b/packages/lint/src/filter-walk.ts
@@ -35,8 +35,21 @@
  * they resolve an additional vocabulary (`AppContextSelector` ids such as
  * `{active_package}`) that is meaningless in a filter, and restricting the walk
  * is what holds false positives at zero.
+ *
+ * ## The two halves of a filter, and where each one is answered
+ *
+ * `walkAuthoredFilters` finds the SUBTREES. Inside one, a rule wants either the
+ * VALUES (`validate-filter-tokens.ts` classifies placeholders in them;
+ * `validate-preset-comparands.ts` judges ordering comparands) or the FIELD KEYS
+ * — the names the query is filtered BY. {@link walkFilterFieldKeys} is the
+ * second half (#14105), and it is here rather than in its first caller because
+ * the shape dispatch is identical to the one `validate-preset-comparands.ts`
+ * already performs on values: the platform authors filters three ways, and a
+ * reader that handles only one shape is the exact bug #3574 was filed against.
  */
 
+import { VALID_AST_OPERATORS } from '@objectstack/spec/data';
+
 /** Any plain metadata record. */
 type AnyRec = Record<string, unknown>;
 
@@ -162,3 +175,122 @@ export function walkAuthoredFilters(
  });
  }
 }
+
+// ── The FIELD-KEY half of a filter subtree (#14105) ──────────────────────────
+
+/** One field position inside an authored filter. */
+export interface FilterFieldKey {
+ /**
+ * The field the condition filters BY, exactly as authored — a bare name
+ * (`status`), or a dotted relationship path (`account.region`, whether
+ * spelled that way or reached by descending a nested condition object).
+ */
+ field: string;
+ /** Config path of the position, e.g. `datasets[1].measures[1].filter.last_update_at`. */
+ path: string;
+}
+
+/** Recursion guard — an authored filter is a bounded document, not a graph. */
+const MAX_KEY_DEPTH = 32;
+
+function isPlainObject(v: unknown): v is AnyRec {
+ return !!v && typeof v === 'object' && !Array.isArray(v) && !(v instanceof Date);
+}
+
+/**
+ * Emit the field positions of one Mongo-style condition NODE.
+ *
+ * `prefix` carries the relationship path accumulated by descending nested
+ * condition objects, so `{ account: { region: { $eq: 'emea' } } }` reports the
+ * single position `account.region` rather than a bare `region` that would
+ * resolve against the wrong object. A node whose value carries `$` operators is
+ * a leaf condition and ends the descent; a `$`-prefixed key that is not a
+ * recognised combinator is skipped and NOT descended, matching
+ * `validate-preset-comparands.ts` — an unrecognised operator's operand shape is
+ * not ours to guess.
+ */
+function conditionFieldKeys(
+ node: AnyRec,
+ path: string,
+ prefix: string,
+ visit: (key: FilterFieldKey) => void,
+ depth: number,
+): void {
+ if (depth > MAX_KEY_DEPTH) return;
+ for (const [key, value] of Object.entries(node)) {
+ const here = `${path}.${key}`;
+ if (key === '$and' || key === '$or') {
+ if (Array.isArray(value)) {
+ value.forEach((arm, i) => {
+ if (isPlainObject(arm)) conditionFieldKeys(arm, `${here}[${i}]`, prefix, visit, depth + 1);
+ });
+ }
+ continue;
+ }
+ if (key === '$not') {
+ if (isPlainObject(value)) conditionFieldKeys(value, here, prefix, visit, depth + 1);
+ continue;
+ }
+ if (key.startsWith('$')) continue; // unrecognised combinator
+ const field = prefix ? `${prefix}.${key}` : key;
+ if (isPlainObject(value) && !Object.keys(value).some((k) => k.startsWith('$'))) {
+ // Nested relation / deep equality — the field position is one level
+ // deeper, so descend rather than reporting the intermediate hop twice.
+ // An EMPTY nested object addresses nothing further; report the hop itself.
+ if (Object.keys(value).length > 0) {
+ conditionFieldKeys(value, here, field, visit, depth + 1);
+ continue;
+ }
+ }
+ visit({ field, path: here });
+ }
+}
+
+/**
+ * Emit every FIELD KEY inside one authored filter subtree, whatever shape it
+ * was authored in — the key half of what `validate-preset-comparands.ts` does
+ * for values, and the traversal `filter-token-unknown` already performs while
+ * reasoning only about the strings it finds.
+ *
+ * Holds no judgement: it does not know which object the filter is bound to and
+ * emits no findings. Resolution is {@link resolveFieldPath}'s job
+ * (`object-graph.ts`) and the verdict is the caller's.
+ */
+export function walkFilterFieldKeys(
+ node: unknown,
+ path: string,
+ visit: (key: FilterFieldKey) => void,
+ depth = 0,
+): void {
+ if (depth > MAX_KEY_DEPTH) return;
+
+ if (Array.isArray(node)) {
+ // Triple: ['field', op, value] — the field position is a non-keyword
+ // string and the operator position is in the AST vocabulary (the
+ // `isFilterAST` test `validate-preset-comparands.ts` uses).
+ if (
+ typeof node[0] === 'string' && typeof node[1] === 'string'
+ && !['and', 'or'].includes(node[0].toLowerCase())
+ && VALID_AST_OPERATORS.has(node[1].toLowerCase())
+ ) {
+ visit({ field: node[0], path: `${path}[0]` });
+ return;
+ }
+ // Group ['and'|'or', ...members] or a bare list — recurse the members.
+ node.forEach((member, i) => {
+ if (typeof member === 'string') return; // the leading keyword
+ walkFilterFieldKeys(member, `${path}[${i}]`, visit, depth + 1);
+ });
+ return;
+ }
+
+ if (!isPlainObject(node)) return;
+
+ // View filter rule: { field, operator[, value] }.
+ if (typeof node.field === 'string' && typeof node.operator === 'string') {
+ visit({ field: node.field, path: `${path}.field` });
+ return;
+ }
+
+ conditionFieldKeys(node, path, '', visit, depth);
+}
diff --git a/packages/lint/src/index.ts b/packages/lint/src/index.ts
@@ -467,6 +467,37 @@ export {
 } from './validate-chart-bindings.js';
 export type { ChartBindingFinding, ChartBindingSeverity } from './validate-chart-bindings.js';
 
+// [#14105] The layer BELOW the chart/widget binding rules above: a dataset's
+// own `include[]`, `dimensions[].field`, `measures[].field` and filter KEYS,
+// resolved against the object graph. Its base-object half is
+// `validateObjectReferences`' `datasets[].object` site.
+export {
+ validateDatasetReferences,
+ DATASET_INCLUDE_UNKNOWN,
+ DATASET_FIELD_UNKNOWN,
+ DATASET_FIELD_NOT_INCLUDED,
+ DATASET_FILTER_FIELD_UNKNOWN,
+} from './validate-dataset-references.js';
+export type { DatasetRefFinding, DatasetRefSeverity } from './validate-dataset-references.js';
+
+// The two reusable seams the rule above is written on, exported because the
+// queued siblings (#14148 widget filter keys + sortBy, #14107 list-view field
+// 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.
+export {
+ indexObjectGraph,
+ resolveFieldPath,
+ isUnjudgeable,
+ nearestName,
+ suggestName,
+ listNames,
+ RELATIONSHIP_FIELD_TYPES,
+} from './object-graph.js';
+export type { ObjectGraph, GraphObject, GraphField, FieldPathVerdict } from './object-graph.js';
+export { walkFilterFieldKeys } from './filter-walk.js';
+export type { FilterFieldKey } from './filter-walk.js';
+
 // #4762 — the two STATIC artifacts an object validation rule carries (a
 // `format` rule's `regex`, a `json_schema` rule's `schema`) are fail-OPEN at
 // runtime: one that does not compile is logged and skipped, so the rule is

diff --git a/.changeset/dataset-reference-resolution.md b/.changeset/dataset-reference-resolution.md
@@ -0,0 +1,95 @@
+---
+'@objectstack/lint': minor
+---
+
+Resolve an ADR-0021 dataset's own references — base object, `include[]`,
+`dimensions[].field` / `measures[].field`, and filter KEYS — at
+`validate`/`build` (#14105)
+
+A dataset could name a **base object that does not exist**, join a
+**relationship that does not exist**, and bind every dimension and measure to
+**fields that do not exist**, and `objectstack validate` exited **0** with
+`✓ Validation passed`. `objectstack build` also exited 0 and wrote the dangling
+dataset into `dist/objectstack.json`.
+
+The sting was that the author-time rule pass **already walked those exact
+nodes**. Measured on published 17.2.0, each mutation applied on its own and
+confirmed on disk before running:
+
+| mutation | before | after |
+|:----------------------------------------------------|:-------|:------|
+| dimension `field` → a base field that does not exist | passed | `dataset-field-unknown` |
+| dimension `field` → a joined field that does not exist | passed | `dataset-field-unknown` |
+| measure `field` → a field that does not exist | passed | `dataset-field-unknown` |
+| measure filter KEY → a field that does not exist | passed | `dataset-filter-field-unknown` |
+| `include[]` → a relationship that does not exist | passed | `dataset-include-unknown` |
+| `object` → an object that does not exist | passed | `object-reference-unknown` |
+
+The two controls in that measurement — a duplicate measure name
+(`DatasetSchema.superRefine`) and a bad date macro in a **measure filter**
+(`filter-token-unknown`) — both failed the build, so datasets were
+demonstrably in the validation path the whole time. `filter-token-unknown`
+already stood at `datasets[1].measures[1].filter.last_update_at.$lt` and
+reasoned about the **value**; nothing standing in that same position resolved
+the **key**, or the sibling `field` one level up.
+
+This matters more for a dataset than for most metadata because a dataset is the
+semantic layer: dashboards and reports bind its dimensions and measures by name
+(ADR-0021), and the consumer end of that binding is already guarded
+(`widget-dataset-unknown` / `widget-dimension-unknown` / `widget-measure-unknown`,
+#7529/#8902). So the surviving hole was the quiet one — every binding resolves,
+the board renders, and the charts are empty or subtly wrong because the dataset
+underneath addresses columns that do not exist.
+
+**Five verdicts, all `error`.** Four are new rule ids on a new suite member,
+`validateDatasetReferences`:
+
+- `dataset-include-unknown` — an `include[]` entry that resolves to nothing, or
+ to a field that is not a relationship, so no join can be derived from it.
+- `dataset-field-unknown` — a dimension or measure `field` path that resolves to
+ no column, on the base object or on any joined object along the path.
+- `dataset-field-not-included` — the second real check: a dotted path that
+ RESOLVES, but whose relationship prefix was never declared in `include`.
+ ADR-0021 D-C joins only declared paths, so the column is out of the query's
+ reach however real it is.
+- `dataset-filter-field-unknown` — a filter key on `Dataset.filter` or
+ `measures[].filter`, in any of the three authored filter shapes.
+
+The fifth, the base object itself, lands on `validateObjectReferences` as a new
+`datasets[].object` reference site rather than as a sixth id here. That rule's
+charter IS object-name references that are plain `z.string()`, and putting it
+there buys the curated cross-package severity ladder: the platform's own
+`system.datasets.ts` declares five datasets over `sys_*` objects, three of which
+live in packages a stack compiling plugin-auth alone cannot see. All five
+resolve through `PLATFORM_PROVIDED_OBJECT_NAMES`; a local "not in this stack ⇒
+error" check would have reported every one of them. When the base object does
+not resolve, `validateDatasetReferences` skips the dataset entirely, so one typo
+yields one finding rather than one per dimension, measure and filter key.
+
+**Skips, so a finding is never a guess** (ADR-0072 D1): an object this stack
+does not define, an object with no readable field map (ADR-0015 `external` and
+introspected schemas), a registry-injected system column, and any hop *through*
+one — an injected `owner_id` is a lookup at the registry whose target is
+invisible here, so `owner_id.name` is unanswerable rather than a miss. The
+shipped `showcase_task_metrics` dimension `{ field: 'created_at' }` is that skip's
+live case, and every shipped dataset in the repo is silent under the new rule.
+
+**Two reusable seams ship with it**, newly exported, because the same two
+questions are asked at a dashboard widget's filter keys and `sortBy` and at a
+list view's field positions, and three independent copies of a hop-walker drift:
+
+- `object-graph.ts` — `indexObjectGraph` / `resolveFieldPath` / `isUnjudgeable`,
+ answering "what does this `relationship[.relationship].field` path resolve to?"
+ as a discriminated **verdict** union rather than a boolean, so a caller can
+ tell "this hop is not a relationship" from "this leaf does not exist" and write
+ the right prescription. Plus `nearestName` / `suggestName` / `listNames`.
+- `walkFilterFieldKeys` (`filter-walk.ts`) — the FIELD-KEY half of a filter
+ subtree, beside the subtree-finding half that module already owns. It handles
+ all three authored shapes (Mongo condition object, `{ field, operator, value }`
+ rules, `[field, op, value]` triples), because a reader that handles only one
+ shape is the exact bug #3574 was filed against, and it composes a nested
+ condition object into one relationship path so `{ account: { region: … } }`
+ reports `account.region` rather than a bare `region` resolved against the
+ wrong object.
+
+Both hold mechanism only — no rule ids, no severities, no findings.
diff --git a/packages/lint/src/filter-walk.ts b/packages/lint/src/filter-walk.ts
@@ -35,8 +35,21 @@
  * they resolve an additional vocabulary (`AppContextSelector` ids such as
  * `{active_package}`) that is meaningless in a filter, and restricting the walk
  * is what holds false positives at zero.
+ *
+ * ## The two halves of a filter, and where each one is answered
+ *
+ * `walkAuthoredFilters` finds the SUBTREES. Inside one, a rule wants either the
+ * VALUES (`validate-filter-tokens.ts` classifies placeholders in them;
+ * `validate-preset-comparands.ts` judges ordering comparands) or the FIELD KEYS
+ * — the names the query is filtered BY. {@link walkFilterFieldKeys} is the
+ * second half (#14105), and it is here rather than in its first caller because
+ * the shape dispatch is identical to the one `validate-preset-comparands.ts`
+ * already performs on values: the platform authors filters three ways, and a
+ * reader that handles only one shape is the exact bug #3574 was filed against.
  */
 
+import { VALID_AST_OPERATORS } from '@objectstack/spec/data';
+
 /** Any plain metadata record. */
 type AnyRec = Record<string, unknown>;
 
@@ -162,3 +175,122 @@ export function walkAuthoredFilters(
  });
  }
 }
+
+// ── The FIELD-KEY half of a filter subtree (#14105) ──────────────────────────
+
+/** One field position inside an authored filter. */
+export interface FilterFieldKey {
+ /**
+ * The field the condition filters BY, exactly as authored — a bare name
+ * (`status`), or a dotted relationship path (`account.region`, whether
+ * spelled that way or reached by descending a nested condition object).
+ */
+ field: string;
+ /** Config path of the position, e.g. `datasets[1].measures[1].filter.last_update_at`. */
+ path: string;
+}
+
+/** Recursion guard — an authored filter is a bounded document, not a graph. */
+const MAX_KEY_DEPTH = 32;
+
+function isPlainObject(v: unknown): v is AnyRec {
+ return !!v && typeof v === 'object' && !Array.isArray(v) && !(v instanceof Date);
+}
+
+/**
+ * Emit the field positions of one Mongo-style condition NODE.
+ *
+ * `prefix` carries the relationship path accumulated by descending nested
+ * condition objects, so `{ account: { region: { $eq: 'emea' } } }` reports the
+ * single position `account.region` rather than a bare `region` that would
+ * resolve against the wrong object. A node whose value carries `$` operators is
+ * a leaf condition and ends the descent; a `$`-prefixed key that is not a
+ * recognised combinator is skipped and NOT descended, matching
+ * `validate-preset-comparands.ts` — an unrecognised operator's operand shape is
+ * not ours to guess.
+ */
+function conditionFieldKeys(
+ node: AnyRec,
+ path: string,
+ prefix: string,
+ visit: (key: FilterFieldKey) => void,
+ depth: number,
+): void {
+ if (depth > MAX_KEY_DEPTH) return;
+ for (const [key, value] of Object.entries(node)) {
+ const here = `${path}.${key}`;
+ if (key === '$and' || key === '$or') {
+ if (Array.isArray(value)) {
+ value.forEach((arm, i) => {
+ if (isPlainObject(arm)) conditionFieldKeys(arm, `${here}[${i}]`, prefix, visit, depth + 1);
+ });
+ }
+ continue;
+ }
+ if (key === '$not') {
+ if (isPlainObject(value)) conditionFieldKeys(value, here, prefix, visit, depth + 1);
+ continue;
+ }
+ if (key.startsWith('$')) continue; // unrecognised combinator
+ const field = prefix ? `${prefix}.${key}` : key;
+ if (isPlainObject(value) && !Object.keys(value).some((k) => k.startsWith('$'))) {
+ // Nested relation / deep equality — the field position is one level
+ // deeper, so descend rather than reporting the intermediate hop twice.
+ // An EMPTY nested object addresses nothing further; report the hop itself.
+ if (Object.keys(value).length > 0) {
+ conditionFieldKeys(value, here, field, visit, depth + 1);
+ continue;
+ }
+ }
+ visit({ field, path: here });
+ }
+}
+
+/**
+ * Emit every FIELD KEY inside one authored filter subtree, whatever shape it
+ * was authored in — the key half of what `validate-preset-comparands.ts` does
+ * for values, and the traversal `filter-token-unknown` already performs while
+ * reasoning only about the strings it finds.
+ *
+ * Holds no judgement: it does not know which object the filter is bound to and
+ * emits no findings. Resolution is {@link resolveFieldPath}'s job
+ * (`object-graph.ts`) and the verdict is the caller's.
+ */
+export function walkFilterFieldKeys(
+ node: unknown,
+ path: string,
+ visit: (key: FilterFieldKey) => void,
+ depth = 0,
+): void {
+ if (depth > MAX_KEY_DEPTH) return;
+
+ if (Array.isArray(node)) {
+ // Triple: ['field', op, value] — the field position is a non-keyword
+ // string and the operator position is in the AST vocabulary (the
+ // `isFilterAST` test `validate-preset-comparands.ts` uses).
+ if (
+ typeof node[0] === 'string' && typeof node[1] === 'string'
+ && !['and', 'or'].includes(node[0].toLowerCase())
+ && VALID_AST_OPERATORS.has(node[1].toLowerCase())
+ ) {
+ visit({ field: node[0], path: `${path}[0]` });
+ return;
+ }
+ // Group ['and'|'or', ...members] or a bare list — recurse the members.
+ node.forEach((member, i) => {
+ if (typeof member === 'string') return; // the leading keyword
+ walkFilterFieldKeys(member, `${path}[${i}]`, visit, depth + 1);
+ });
+ return;
+ }
+
+ if (!isPlainObject(node)) return;
+
+ // View filter rule: { field, operator[, value] }.
+ if (typeof node.field === 'string' && typeof node.operator === 'string') {
+ visit({ field: node.field, path: `${path}.field` });
+ return;
+ }
+
+ conditionFieldKeys(node, path, '', visit, depth);
+}
diff --git a/packages/lint/src/index.ts b/packages/lint/src/index.ts
@@ -467,6 +467,37 @@ export {
 } from './validate-chart-bindings.js';
 export type { ChartBindingFinding, ChartBindingSeverity } from './validate-chart-bindings.js';
 
+// [#14105] The layer BELOW the chart/widget binding rules above: a dataset's
+// own `include[]`, `dimensions[].field`, `measures[].field` and filter KEYS,
+// resolved against the object graph. Its base-object half is
+// `validateObjectReferences`' `datasets[].object` site.
+export {
+ validateDatasetReferences,
+ DATASET_INCLUDE_UNKNOWN,
+ DATASET_FIELD_UNKNOWN,
+ DATASET_FIELD_NOT_INCLUDED,
+ DATASET_FILTER_FIELD_UNKNOWN,
+} from './validate-dataset-references.js';
+export type { DatasetRefFinding, DatasetRefSeverity } from './validate-dataset-references.js';
+
+// The two reusable seams the rule above is written on, exported because the
+// queued siblings (#14148 widget filter keys + sortBy, #14107 list-view field
+// 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.
+export {
+ indexObjectGraph,
+ resolveFieldPath,
+ isUnjudgeable,
+ nearestName,
+ suggestName,
+ listNames,
+ RELATIONSHIP_FIELD_TYPES,
+} from './object-graph.js';
+export type { ObjectGraph, GraphObject, GraphField, FieldPathVerdict } from './object-graph.js';
+export { walkFilterFieldKeys } from './filter-walk.js';
+export type { FilterFieldKey } from './filter-walk.js';
+
 // #4762 — the two STATIC artifacts an object validation rule carries (a
 // `format` rule's `regex`, a `json_schema` rule's `schema`) are fail-OPEN at
 // runtime: one that does not compile is logged and skipped, so the rule is

diff --git a/.changeset/dataset-reference-resolution.md b/.changeset/dataset-reference-resolution.md
@@ -0,0 +1,95 @@
+---
+'@objectstack/lint': minor
+---
+
+Resolve an ADR-0021 dataset's own references — base object, `include[]`,
+`dimensions[].field` / `measures[].field`, and filter KEYS — at
+`validate`/`build` (#14105)
+
+A dataset could name a **base object that does not exist**, join a
+**relationship that does not exist**, and bind every dimension and measure to
+**fields that do not exist**, and `objectstack validate` exited **0** with
+`✓ Validation passed`. `objectstack build` also exited 0 and wrote the dangling
+dataset into `dist/objectstack.json`.
+
+The sting was that the author-time rule pass **already walked those exact
+nodes**. Measured on published 17.2.0, each mutation applied on its own and
+confirmed on disk before running:
+
+| mutation | before | after |
+|:----------------------------------------------------|:-------|:------|
+| dimension `field` → a base field that does not exist | passed | `dataset-field-unknown` |
+| dimension `field` → a joined field that does not exist | passed | `dataset-field-unknown` |
+| measure `field` → a field that does not exist | passed | `dataset-field-unknown` |
+| measure filter KEY → a field that does not exist | passed | `dataset-filter-field-unknown` |
+| `include[]` → a relationship that does not exist | passed | `dataset-include-unknown` |
+| `object` → an object that does not exist | passed | `object-reference-unknown` |
+
+The two controls in that measurement — a duplicate measure name
+(`DatasetSchema.superRefine`) and a bad date macro in a **measure filter**
+(`filter-token-unknown`) — both failed the build, so datasets were
+demonstrably in the validation path the whole time. `filter-token-unknown`
+already stood at `datasets[1].measures[1].filter.last_update_at.$lt` and
+reasoned about the **value**; nothing standing in that same position resolved
+the **key**, or the sibling `field` one level up.
+
+This matters more for a dataset than for most metadata because a dataset is the
+semantic layer: dashboards and reports bind its dimensions and measures by name
+(ADR-0021), and the consumer end of that binding is already guarded
+(`widget-dataset-unknown` / `widget-dimension-unknown` / `widget-measure-unknown`,
+#7529/#8902). So the surviving hole was the quiet one — every binding resolves,
+the board renders, and the charts are empty or subtly wrong because the dataset
+underneath addresses columns that do not exist.
+
+**Five verdicts, all `error`.** Four are new rule ids on a new suite member,
+`validateDatasetReferences`:
+
+- `dataset-include-unknown` — an `include[]` entry that resolves to nothing, or
+ to a field that is not a relationship, so no join can be derived from it.
+- `dataset-field-unknown` — a dimension or measure `field` path that resolves to
+ no column, on the base object or on any joined object along the path.
+- `dataset-field-not-included` — the second real check: a dotted path that
+ RESOLVES, but whose relationship prefix was never declared in `include`.
+ ADR-0021 D-C joins only declared paths, so the column is out of the query's
+ reach however real it is.
+- `dataset-filter-field-unknown` — a filter key on `Dataset.filter` or
+ `measures[].filter`, in any of the three authored filter shapes.
+
+The fifth, the base object itself, lands on `validateObjectReferences` as a new
+`datasets[].object` reference site rather than as a sixth id here. That rule's
+charter IS object-name references that are plain `z.string()`, and putting it
+there buys the curated cross-package severity ladder: the platform's own
+`system.datasets.ts` declares five datasets over `sys_*` objects, three of which
+live in packages a stack compiling plugin-auth alone cannot see. All five
+resolve through `PLATFORM_PROVIDED_OBJECT_NAMES`; a local "not in this stack ⇒
+error" check would have reported every one of them. When the base object does
+not resolve, `validateDatasetReferences` skips the dataset entirely, so one typo
+yields one finding rather than one per dimension, measure and filter key.
+
+**Skips, so a finding is never a guess** (ADR-0072 D1): an object this stack
+does not define, an object with no readable field map (ADR-0015 `external` and
+introspected schemas), a registry-injected system column, and any hop *through*
+one — an injected `owner_id` is a lookup at the registry whose target is
+invisible here, so `owner_id.name` is unanswerable rather than a miss. The
+shipped `showcase_task_metrics` dimension `{ field: 'created_at' }` is that skip's
+live case, and every shipped dataset in the repo is silent under the new rule.
+
+**Two reusable seams ship with it**, newly exported, because the same two
+questions are asked at a dashboard widget's filter keys and `sortBy` and at a
+list view's field positions, and three independent copies of a hop-walker drift:
+
+- `object-graph.ts` — `indexObjectGraph` / `resolveFieldPath` / `isUnjudgeable`,
+ answering "what does this `relationship[.relationship].field` path resolve to?"
+ as a discriminated **verdict** union rather than a boolean, so a caller can
+ tell "this hop is not a relationship" from "this leaf does not exist" and write
+ the right prescription. Plus `nearestName` / `suggestName` / `listNames`.
+- `walkFilterFieldKeys` (`filter-walk.ts`) — the FIELD-KEY half of a filter
+ subtree, beside the subtree-finding half that module already owns. It handles
+ all three authored shapes (Mongo condition object, `{ field, operator, value }`
+ rules, `[field, op, value]` triples), because a reader that handles only one
+ shape is the exact bug #3574 was filed against, and it composes a nested
+ condition object into one relationship path so `{ account: { region: … } }`
+ reports `account.region` rather than a bare `region` resolved against the
+ wrong object.
+
+Both hold mechanism only — no rule ids, no severities, no findings.
diff --git a/packages/lint/src/filter-walk.ts b/packages/lint/src/filter-walk.ts
@@ -35,8 +35,21 @@
  * they resolve an additional vocabulary (`AppContextSelector` ids such as
  * `{active_package}`) that is meaningless in a filter, and restricting the walk
  * is what holds false positives at zero.
+ *
+ * ## The two halves of a filter, and where each one is answered
+ *
+ * `walkAuthoredFilters` finds the SUBTREES. Inside one, a rule wants either the
+ * VALUES (`validate-filter-tokens.ts` classifies placeholders in them;
+ * `validate-preset-comparands.ts` judges ordering comparands) or the FIELD KEYS
+ * — the names the query is filtered BY. {@link walkFilterFieldKeys} is the
+ * second half (#14105), and it is here rather than in its first caller because
+ * the shape dispatch is identical to the one `validate-preset-comparands.ts`
+ * already performs on values: the platform authors filters three ways, and a
+ * reader that handles only one shape is the exact bug #3574 was filed against.
  */
 
+import { VALID_AST_OPERATORS } from '@objectstack/spec/data';
+
 /** Any plain metadata record. */
 type AnyRec = Record<string, unknown>;
 
@@ -162,3 +175,122 @@ export function walkAuthoredFilters(
  });
  }
 }
+
+// ── The FIELD-KEY half of a filter subtree (#14105) ──────────────────────────
+
+/** One field position inside an authored filter. */
+export interface FilterFieldKey {
+ /**
+ * The field the condition filters BY, exactly as authored — a bare name
+ * (`status`), or a dotted relationship path (`account.region`, whether
+ * spelled that way or reached by descending a nested condition object).
+ */
+ field: string;
+ /** Config path of the position, e.g. `datasets[1].measures[1].filter.last_update_at`. */
+ path: string;
+}
+
+/** Recursion guard — an authored filter is a bounded document, not a graph. */
+const MAX_KEY_DEPTH = 32;
+
+function isPlainObject(v: unknown): v is AnyRec {
+ return !!v && typeof v === 'object' && !Array.isArray(v) && !(v instanceof Date);
+}
+
+/**
+ * Emit the field positions of one Mongo-style condition NODE.
+ *
+ * `prefix` carries the relationship path accumulated by descending nested
+ * condition objects, so `{ account: { region: { $eq: 'emea' } } }` reports the
+ * single position `account.region` rather than a bare `region` that would
+ * resolve against the wrong object. A node whose value carries `$` operators is
+ * a leaf condition and ends the descent; a `$`-prefixed key that is not a
+ * recognised combinator is skipped and NOT descended, matching
+ * `validate-preset-comparands.ts` — an unrecognised operator's operand shape is
+ * not ours to guess.
+ */
+function conditionFieldKeys(
+ node: AnyRec,
+ path: string,
+ prefix: string,
+ visit: (key: FilterFieldKey) => void,
+ depth: number,
+): void {
+ if (depth > MAX_KEY_DEPTH) return;
+ for (const [key, value] of Object.entries(node)) {
+ const here = `${path}.${key}`;
+ if (key === '$and' || key === '$or') {
+ if (Array.isArray(value)) {
+ value.forEach((arm, i) => {
+ if (isPlainObject(arm)) conditionFieldKeys(arm, `${here}[${i}]`, prefix, visit, depth + 1);
+ });
+ }
+ continue;
+ }
+ if (key === '$not') {
+ if (isPlainObject(value)) conditionFieldKeys(value, here, prefix, visit, depth + 1);
+ continue;
+ }
+ if (key.startsWith('$')) continue; // unrecognised combinator
+ const field = prefix ? `${prefix}.${key}` : key;
+ if (isPlainObject(value) && !Object.keys(value).some((k) => k.startsWith('$'))) {
+ // Nested relation / deep equality — the field position is one level
+ // deeper, so descend rather than reporting the intermediate hop twice.
+ // An EMPTY nested object addresses nothing further; report the hop itself.
+ if (Object.keys(value).length > 0) {
+ conditionFieldKeys(value, here, field, visit, depth + 1);
+ continue;
+ }
+ }
+ visit({ field, path: here });
+ }
+}
+
+/**
+ * Emit every FIELD KEY inside one authored filter subtree, whatever shape it
+ * was authored in — the key half of what `validate-preset-comparands.ts` does
+ * for values, and the traversal `filter-token-unknown` already performs while
+ * reasoning only about the strings it finds.
+ *
+ * Holds no judgement: it does not know which object the filter is bound to and
+ * emits no findings. Resolution is {@link resolveFieldPath}'s job
+ * (`object-graph.ts`) and the verdict is the caller's.
+ */
+export function walkFilterFieldKeys(
+ node: unknown,
+ path: string,
+ visit: (key: FilterFieldKey) => void,
+ depth = 0,
+): void {
+ if (depth > MAX_KEY_DEPTH) return;
+
+ if (Array.isArray(node)) {
+ // Triple: ['field', op, value] — the field position is a non-keyword
+ // string and the operator position is in the AST vocabulary (the
+ // `isFilterAST` test `validate-preset-comparands.ts` uses).
+ if (
+ typeof node[0] === 'string' && typeof node[1] === 'string'
+ && !['and', 'or'].includes(node[0].toLowerCase())
+ && VALID_AST_OPERATORS.has(node[1].toLowerCase())
+ ) {
+ visit({ field: node[0], path: `${path}[0]` });
+ return;
+ }
+ // Group ['and'|'or', ...members] or a bare list — recurse the members.
+ node.forEach((member, i) => {
+ if (typeof member === 'string') return; // the leading keyword
+ walkFilterFieldKeys(member, `${path}[${i}]`, visit, depth + 1);
+ });
+ return;
+ }
+
+ if (!isPlainObject(node)) return;
+
+ // View filter rule: { field, operator[, value] }.
+ if (typeof node.field === 'string' && typeof node.operator === 'string') {
+ visit({ field: node.field, path: `${path}.field` });
+ return;
+ }
+
+ conditionFieldKeys(node, path, '', visit, depth);
+}
diff --git a/packages/lint/src/index.ts b/packages/lint/src/index.ts
@@ -467,6 +467,37 @@ export {
 } from './validate-chart-bindings.js';
 export type { ChartBindingFinding, ChartBindingSeverity } from './validate-chart-bindings.js';
 
+// [#14105] The layer BELOW the chart/widget binding rules above: a dataset's
+// own `include[]`, `dimensions[].field`, `measures[].field` and filter KEYS,
+// resolved against the object graph. Its base-object half is
+// `validateObjectReferences`' `datasets[].object` site.
+export {
+ validateDatasetReferences,
+ DATASET_INCLUDE_UNKNOWN,
+ DATASET_FIELD_UNKNOWN,
+ DATASET_FIELD_NOT_INCLUDED,
+ DATASET_FILTER_FIELD_UNKNOWN,
+} from './validate-dataset-references.js';
+export type { DatasetRefFinding, DatasetRefSeverity } from './validate-dataset-references.js';
+
+// The two reusable seams the rule above is written on, exported because the
+// queued siblings (#14148 widget filter keys + sortBy, #14107 list-view field
+// 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.
+export {
+ indexObjectGraph,
+ resolveFieldPath,
+ isUnjudgeable,
+ nearestName,
+ suggestName,
+ listNames,
+ RELATIONSHIP_FIELD_TYPES,
+} from './object-graph.js';
+export type { ObjectGraph, GraphObject, GraphField, FieldPathVerdict } from './object-graph.js';
+export { walkFilterFieldKeys } from './filter-walk.js';
+export type { FilterFieldKey } from './filter-walk.js';
+
 // #4762 — the two STATIC artifacts an object validation rule carries (a
 // `format` rule's `regex`, a `json_schema` rule's `schema`) are fail-OPEN at
 // runtime: one that does not compile is logged and skipped, so the rule is

diff --git a/.changeset/dataset-reference-resolution.md b/.changeset/dataset-reference-resolution.md
@@ -0,0 +1,95 @@
+---
+'@objectstack/lint': minor
+---
+
+Resolve an ADR-0021 dataset's own references — base object, `include[]`,
+`dimensions[].field` / `measures[].field`, and filter KEYS — at
+`validate`/`build` (#14105)
+
+A dataset could name a **base object that does not exist**, join a
+**relationship that does not exist**, and bind every dimension and measure to
+**fields that do not exist**, and `objectstack validate` exited **0** with
+`✓ Validation passed`. `objectstack build` also exited 0 and wrote the dangling
+dataset into `dist/objectstack.json`.
+
+The sting was that the author-time rule pass **already walked those exact
+nodes**. Measured on published 17.2.0, each mutation applied on its own and
+confirmed on disk before running:
+
+| mutation | before | after |
+|:----------------------------------------------------|:-------|:------|
+| dimension `field` → a base field that does not exist | passed | `dataset-field-unknown` |
+| dimension `field` → a joined field that does not exist | passed | `dataset-field-unknown` |
+| measure `field` → a field that does not exist | passed | `dataset-field-unknown` |
+| measure filter KEY → a field that does not exist | passed | `dataset-filter-field-unknown` |
+| `include[]` → a relationship that does not exist | passed | `dataset-include-unknown` |
+| `object` → an object that does not exist | passed | `object-reference-unknown` |
+
+The two controls in that measurement — a duplicate measure name
+(`DatasetSchema.superRefine`) and a bad date macro in a **measure filter**
+(`filter-token-unknown`) — both failed the build, so datasets were
+demonstrably in the validation path the whole time. `filter-token-unknown`
+already stood at `datasets[1].measures[1].filter.last_update_at.$lt` and
+reasoned about the **value**; nothing standing in that same position resolved
+the **key**, or the sibling `field` one level up.
+
+This matters more for a dataset than for most metadata because a dataset is the
+semantic layer: dashboards and reports bind its dimensions and measures by name
+(ADR-0021), and the consumer end of that binding is already guarded
+(`widget-dataset-unknown` / `widget-dimension-unknown` / `widget-measure-unknown`,
+#7529/#8902). So the surviving hole was the quiet one — every binding resolves,
+the board renders, and the charts are empty or subtly wrong because the dataset
+underneath addresses columns that do not exist.
+
+**Five verdicts, all `error`.** Four are new rule ids on a new suite member,
+`validateDatasetReferences`:
+
+- `dataset-include-unknown` — an `include[]` entry that resolves to nothing, or
+ to a field that is not a relationship, so no join can be derived from it.
+- `dataset-field-unknown` — a dimension or measure `field` path that resolves to
+ no column, on the base object or on any joined object along the path.
+- `dataset-field-not-included` — the second real check: a dotted path that
+ RESOLVES, but whose relationship prefix was never declared in `include`.
+ ADR-0021 D-C joins only declared paths, so the column is out of the query's
+ reach however real it is.
+- `dataset-filter-field-unknown` — a filter key on `Dataset.filter` or
+ `measures[].filter`, in any of the three authored filter shapes.
+
+The fifth, the base object itself, lands on `validateObjectReferences` as a new
+`datasets[].object` reference site rather than as a sixth id here. That rule's
+charter IS object-name references that are plain `z.string()`, and putting it
+there buys the curated cross-package severity ladder: the platform's own
+`system.datasets.ts` declares five datasets over `sys_*` objects, three of which
+live in packages a stack compiling plugin-auth alone cannot see. All five
+resolve through `PLATFORM_PROVIDED_OBJECT_NAMES`; a local "not in this stack ⇒
+error" check would have reported every one of them. When the base object does
+not resolve, `validateDatasetReferences` skips the dataset entirely, so one typo
+yields one finding rather than one per dimension, measure and filter key.
+
+**Skips, so a finding is never a guess** (ADR-0072 D1): an object this stack
+does not define, an object with no readable field map (ADR-0015 `external` and
+introspected schemas), a registry-injected system column, and any hop *through*
+one — an injected `owner_id` is a lookup at the registry whose target is
+invisible here, so `owner_id.name` is unanswerable rather than a miss. The
+shipped `showcase_task_metrics` dimension `{ field: 'created_at' }` is that skip's
+live case, and every shipped dataset in the repo is silent under the new rule.
+
+**Two reusable seams ship with it**, newly exported, because the same two
+questions are asked at a dashboard widget's filter keys and `sortBy` and at a
+list view's field positions, and three independent copies of a hop-walker drift:
+
+- `object-graph.ts` — `indexObjectGraph` / `resolveFieldPath` / `isUnjudgeable`,
+ answering "what does this `relationship[.relationship].field` path resolve to?"
+ as a discriminated **verdict** union rather than a boolean, so a caller can
+ tell "this hop is not a relationship" from "this leaf does not exist" and write
+ the right prescription. Plus `nearestName` / `suggestName` / `listNames`.
+- `walkFilterFieldKeys` (`filter-walk.ts`) — the FIELD-KEY half of a filter
+ subtree, beside the subtree-finding half that module already owns. It handles
+ all three authored shapes (Mongo condition object, `{ field, operator, value }`
+ rules, `[field, op, value]` triples), because a reader that handles only one
+ shape is the exact bug #3574 was filed against, and it composes a nested
+ condition object into one relationship path so `{ account: { region: … } }`
+ reports `account.region` rather than a bare `region` resolved against the
+ wrong object.
+
+Both hold mechanism only — no rule ids, no severities, no findings.
diff --git a/packages/lint/src/filter-walk.ts b/packages/lint/src/filter-walk.ts
@@ -35,8 +35,21 @@
  * they resolve an additional vocabulary (`AppContextSelector` ids such as
  * `{active_package}`) that is meaningless in a filter, and restricting the walk
  * is what holds false positives at zero.
+ *
+ * ## The two halves of a filter, and where each one is answered
+ *
+ * `walkAuthoredFilters` finds the SUBTREES. Inside one, a rule wants either the
+ * VALUES (`validate-filter-tokens.ts` classifies placeholders in them;
+ * `validate-preset-comparands.ts` judges ordering comparands) or the FIELD KEYS
+ * — the names the query is filtered BY. {@link walkFilterFieldKeys} is the
+ * second half (#14105), and it is here rather than in its first caller because
+ * the shape dispatch is identical to the one `validate-preset-comparands.ts`
+ * already performs on values: the platform authors filters three ways, and a
+ * reader that handles only one shape is the exact bug #3574 was filed against.
  */
 
+import { VALID_AST_OPERATORS } from '@objectstack/spec/data';
+
 /** Any plain metadata record. */
 type AnyRec = Record<string, unknown>;
 
@@ -162,3 +175,122 @@ export function walkAuthoredFilters(
  });
  }
 }
+
+// ── The FIELD-KEY half of a filter subtree (#14105) ──────────────────────────
+
+/** One field position inside an authored filter. */
+export interface FilterFieldKey {
+ /**
+ * The field the condition filters BY, exactly as authored — a bare name
+ * (`status`), or a dotted relationship path (`account.region`, whether
+ * spelled that way or reached by descending a nested condition object).
+ */
+ field: string;
+ /** Config path of the position, e.g. `datasets[1].measures[1].filter.last_update_at`. */
+ path: string;
+}
+
+/** Recursion guard — an authored filter is a bounded document, not a graph. */
+const MAX_KEY_DEPTH = 32;
+
+function isPlainObject(v: unknown): v is AnyRec {
+ return !!v && typeof v === 'object' && !Array.isArray(v) && !(v instanceof Date);
+}
+
+/**
+ * Emit the field positions of one Mongo-style condition NODE.
+ *
+ * `prefix` carries the relationship path accumulated by descending nested
+ * condition objects, so `{ account: { region: { $eq: 'emea' } } }` reports the
+ * single position `account.region` rather than a bare `region` that would
+ * resolve against the wrong object. A node whose value carries `$` operators is
+ * a leaf condition and ends the descent; a `$`-prefixed key that is not a
+ * recognised combinator is skipped and NOT descended, matching
+ * `validate-preset-comparands.ts` — an unrecognised operator's operand shape is
+ * not ours to guess.
+ */
+function conditionFieldKeys(
+ node: AnyRec,
+ path: string,
+ prefix: string,
+ visit: (key: FilterFieldKey) => void,
+ depth: number,
+): void {
+ if (depth > MAX_KEY_DEPTH) return;
+ for (const [key, value] of Object.entries(node)) {
+ const here = `${path}.${key}`;
+ if (key === '$and' || key === '$or') {
+ if (Array.isArray(value)) {
+ value.forEach((arm, i) => {
+ if (isPlainObject(arm)) conditionFieldKeys(arm, `${here}[${i}]`, prefix, visit, depth + 1);
+ });
+ }
+ continue;
+ }
+ if (key === '$not') {
+ if (isPlainObject(value)) conditionFieldKeys(value, here, prefix, visit, depth + 1);
+ continue;
+ }
+ if (key.startsWith('$')) continue; // unrecognised combinator
+ const field = prefix ? `${prefix}.${key}` : key;
+ if (isPlainObject(value) && !Object.keys(value).some((k) => k.startsWith('$'))) {
+ // Nested relation / deep equality — the field position is one level
+ // deeper, so descend rather than reporting the intermediate hop twice.
+ // An EMPTY nested object addresses nothing further; report the hop itself.
+ if (Object.keys(value).length > 0) {
+ conditionFieldKeys(value, here, field, visit, depth + 1);
+ continue;
+ }
+ }
+ visit({ field, path: here });
+ }
+}
+
+/**
+ * Emit every FIELD KEY inside one authored filter subtree, whatever shape it
+ * was authored in — the key half of what `validate-preset-comparands.ts` does
+ * for values, and the traversal `filter-token-unknown` already performs while
+ * reasoning only about the strings it finds.
+ *
+ * Holds no judgement: it does not know which object the filter is bound to and
+ * emits no findings. Resolution is {@link resolveFieldPath}'s job
+ * (`object-graph.ts`) and the verdict is the caller's.
+ */
+export function walkFilterFieldKeys(
+ node: unknown,
+ path: string,
+ visit: (key: FilterFieldKey) => void,
+ depth = 0,
+): void {
+ if (depth > MAX_KEY_DEPTH) return;
+
+ if (Array.isArray(node)) {
+ // Triple: ['field', op, value] — the field position is a non-keyword
+ // string and the operator position is in the AST vocabulary (the
+ // `isFilterAST` test `validate-preset-comparands.ts` uses).
+ if (
+ typeof node[0] === 'string' && typeof node[1] === 'string'
+ && !['and', 'or'].includes(node[0].toLowerCase())
+ && VALID_AST_OPERATORS.has(node[1].toLowerCase())
+ ) {
+ visit({ field: node[0], path: `${path}[0]` });
+ return;
+ }
+ // Group ['and'|'or', ...members] or a bare list — recurse the members.
+ node.forEach((member, i) => {
+ if (typeof member === 'string') return; // the leading keyword
+ walkFilterFieldKeys(member, `${path}[${i}]`, visit, depth + 1);
+ });
+ return;
+ }
+
+ if (!isPlainObject(node)) return;
+
+ // View filter rule: { field, operator[, value] }.
+ if (typeof node.field === 'string' && typeof node.operator === 'string') {
+ visit({ field: node.field, path: `${path}.field` });
+ return;
+ }
+
+ conditionFieldKeys(node, path, '', visit, depth);
+}
diff --git a/packages/lint/src/index.ts b/packages/lint/src/index.ts
@@ -467,6 +467,37 @@ export {
 } from './validate-chart-bindings.js';
 export type { ChartBindingFinding, ChartBindingSeverity } from './validate-chart-bindings.js';
 
+// [#14105] The layer BELOW the chart/widget binding rules above: a dataset's
+// own `include[]`, `dimensions[].field`, `measures[].field` and filter KEYS,
+// resolved against the object graph. Its base-object half is
+// `validateObjectReferences`' `datasets[].object` site.
+export {
+ validateDatasetReferences,
+ DATASET_INCLUDE_UNKNOWN,
+ DATASET_FIELD_UNKNOWN,
+ DATASET_FIELD_NOT_INCLUDED,
+ DATASET_FILTER_FIELD_UNKNOWN,
+} from './validate-dataset-references.js';
+export type { DatasetRefFinding, DatasetRefSeverity } from './validate-dataset-references.js';
+
+// The two reusable seams the rule above is written on, exported because the
+// queued siblings (#14148 widget filter keys + sortBy, #14107 list-view field
+// 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.
+export {
+ indexObjectGraph,
+ resolveFieldPath,
+ isUnjudgeable,
+ nearestName,
+ suggestName,
+ listNames,
+ RELATIONSHIP_FIELD_TYPES,
+} from './object-graph.js';
+export type { ObjectGraph, GraphObject, GraphField, FieldPathVerdict } from './object-graph.js';
+export { walkFilterFieldKeys } from './filter-walk.js';
+export type { FilterFieldKey } from './filter-walk.js';
+
 // #4762 — the two STATIC artifacts an object validation rule carries (a
 // `format` rule's `regex`, a `json_schema` rule's `schema`) are fail-OPEN at
 // runtime: one that does not compile is logged and skipped, so the rule is

diff --git a/.changeset/dataset-reference-resolution.md b/.changeset/dataset-reference-resolution.md
@@ -0,0 +1,95 @@
+---
+'@objectstack/lint': minor
+---
+
+Resolve an ADR-0021 dataset's own references — base object, `include[]`,
+`dimensions[].field` / `measures[].field`, and filter KEYS — at
+`validate`/`build` (#14105)
+
+A dataset could name a **base object that does not exist**, join a
+**relationship that does not exist**, and bind every dimension and measure to
+**fields that do not exist**, and `objectstack validate` exited **0** with
+`✓ Validation passed`. `objectstack build` also exited 0 and wrote the dangling
+dataset into `dist/objectstack.json`.
+
+The sting was that the author-time rule pass **already walked those exact
+nodes**. Measured on published 17.2.0, each mutation applied on its own and
+confirmed on disk before running:
+
+| mutation | before | after |
+|:----------------------------------------------------|:-------|:------|
+| dimension `field` → a base field that does not exist | passed | `dataset-field-unknown` |
+| dimension `field` → a joined field that does not exist | passed | `dataset-field-unknown` |
+| measure `field` → a field that does not exist | passed | `dataset-field-unknown` |
+| measure filter KEY → a field that does not exist | passed | `dataset-filter-field-unknown` |
+| `include[]` → a relationship that does not exist | passed | `dataset-include-unknown` |
+| `object` → an object that does not exist | passed | `object-reference-unknown` |
+
+The two controls in that measurement — a duplicate measure name
+(`DatasetSchema.superRefine`) and a bad date macro in a **measure filter**
+(`filter-token-unknown`) — both failed the build, so datasets were
+demonstrably in the validation path the whole time. `filter-token-unknown`
+already stood at `datasets[1].measures[1].filter.last_update_at.$lt` and
+reasoned about the **value**; nothing standing in that same position resolved
+the **key**, or the sibling `field` one level up.
+
+This matters more for a dataset than for most metadata because a dataset is the
+semantic layer: dashboards and reports bind its dimensions and measures by name
+(ADR-0021), and the consumer end of that binding is already guarded
+(`widget-dataset-unknown` / `widget-dimension-unknown` / `widget-measure-unknown`,
+#7529/#8902). So the surviving hole was the quiet one — every binding resolves,
+the board renders, and the charts are empty or subtly wrong because the dataset
+underneath addresses columns that do not exist.
+
+**Five verdicts, all `error`.** Four are new rule ids on a new suite member,
+`validateDatasetReferences`:
+
+- `dataset-include-unknown` — an `include[]` entry that resolves to nothing, or
+ to a field that is not a relationship, so no join can be derived from it.
+- `dataset-field-unknown` — a dimension or measure `field` path that resolves to
+ no column, on the base object or on any joined object along the path.
+- `dataset-field-not-included` — the second real check: a dotted path that
+ RESOLVES, but whose relationship prefix was never declared in `include`.
+ ADR-0021 D-C joins only declared paths, so the column is out of the query's
+ reach however real it is.
+- `dataset-filter-field-unknown` — a filter key on `Dataset.filter` or
+ `measures[].filter`, in any of the three authored filter shapes.
+
+The fifth, the base object itself, lands on `validateObjectReferences` as a new
+`datasets[].object` reference site rather than as a sixth id here. That rule's
+charter IS object-name references that are plain `z.string()`, and putting it
+there buys the curated cross-package severity ladder: the platform's own
+`system.datasets.ts` declares five datasets over `sys_*` objects, three of which
+live in packages a stack compiling plugin-auth alone cannot see. All five
+resolve through `PLATFORM_PROVIDED_OBJECT_NAMES`; a local "not in this stack ⇒
+error" check would have reported every one of them. When the base object does
+not resolve, `validateDatasetReferences` skips the dataset entirely, so one typo
+yields one finding rather than one per dimension, measure and filter key.
+
+**Skips, so a finding is never a guess** (ADR-0072 D1): an object this stack
+does not define, an object with no readable field map (ADR-0015 `external` and
+introspected schemas), a registry-injected system column, and any hop *through*
+one — an injected `owner_id` is a lookup at the registry whose target is
+invisible here, so `owner_id.name` is unanswerable rather than a miss. The
+shipped `showcase_task_metrics` dimension `{ field: 'created_at' }` is that skip's
+live case, and every shipped dataset in the repo is silent under the new rule.
+
+**Two reusable seams ship with it**, newly exported, because the same two
+questions are asked at a dashboard widget's filter keys and `sortBy` and at a
+list view's field positions, and three independent copies of a hop-walker drift:
+
+- `object-graph.ts` — `indexObjectGraph` / `resolveFieldPath` / `isUnjudgeable`,
+ answering "what does this `relationship[.relationship].field` path resolve to?"
+ as a discriminated **verdict** union rather than a boolean, so a caller can
+ tell "this hop is not a relationship" from "this leaf does not exist" and write
+ the right prescription. Plus `nearestName` / `suggestName` / `listNames`.
+- `walkFilterFieldKeys` (`filter-walk.ts`) — the FIELD-KEY half of a filter
+ subtree, beside the subtree-finding half that module already owns. It handles
+ all three authored shapes (Mongo condition object, `{ field, operator, value }`
+ rules, `[field, op, value]` triples), because a reader that handles only one
+ shape is the exact bug #3574 was filed against, and it composes a nested
+ condition object into one relationship path so `{ account: { region: … } }`
+ reports `account.region` rather than a bare `region` resolved against the
+ wrong object.
+
+Both hold mechanism only — no rule ids, no severities, no findings.
diff --git a/packages/lint/src/filter-walk.ts b/packages/lint/src/filter-walk.ts
@@ -35,8 +35,21 @@
  * they resolve an additional vocabulary (`AppContextSelector` ids such as
  * `{active_package}`) that is meaningless in a filter, and restricting the walk
  * is what holds false positives at zero.
+ *
+ * ## The two halves of a filter, and where each one is answered
+ *
+ * `walkAuthoredFilters` finds the SUBTREES. Inside one, a rule wants either the
+ * VALUES (`validate-filter-tokens.ts` classifies placeholders in them;
+ * `validate-preset-comparands.ts` judges ordering comparands) or the FIELD KEYS
+ * — the names the query is filtered BY. {@link walkFilterFieldKeys} is the
+ * second half (#14105), and it is here rather than in its first caller because
+ * the shape dispatch is identical to the one `validate-preset-comparands.ts`
+ * already performs on values: the platform authors filters three ways, and a
+ * reader that handles only one shape is the exact bug #3574 was filed against.
  */
 
+import { VALID_AST_OPERATORS } from '@objectstack/spec/data';
+
 /** Any plain metadata record. */
 type AnyRec = Record<string, unknown>;
 
@@ -162,3 +175,122 @@ export function walkAuthoredFilters(
  });
  }
 }
+
+// ── The FIELD-KEY half of a filter subtree (#14105) ──────────────────────────
+
+/** One field position inside an authored filter. */
+export interface FilterFieldKey {
+ /**
+ * The field the condition filters BY, exactly as authored — a bare name
+ * (`status`), or a dotted relationship path (`account.region`, whether
+ * spelled that way or reached by descending a nested condition object).
+ */
+ field: string;
+ /** Config path of the position, e.g. `datasets[1].measures[1].filter.last_update_at`. */
+ path: string;
+}
+
+/** Recursion guard — an authored filter is a bounded document, not a graph. */
+const MAX_KEY_DEPTH = 32;
+
+function isPlainObject(v: unknown): v is AnyRec {
+ return !!v && typeof v === 'object' && !Array.isArray(v) && !(v instanceof Date);
+}
+
+/**
+ * Emit the field positions of one Mongo-style condition NODE.
+ *
+ * `prefix` carries the relationship path accumulated by descending nested
+ * condition objects, so `{ account: { region: { $eq: 'emea' } } }` reports the
+ * single position `account.region` rather than a bare `region` that would
+ * resolve against the wrong object. A node whose value carries `$` operators is
+ * a leaf condition and ends the descent; a `$`-prefixed key that is not a
+ * recognised combinator is skipped and NOT descended, matching
+ * `validate-preset-comparands.ts` — an unrecognised operator's operand shape is
+ * not ours to guess.
+ */
+function conditionFieldKeys(
+ node: AnyRec,
+ path: string,
+ prefix: string,
+ visit: (key: FilterFieldKey) => void,
+ depth: number,
+): void {
+ if (depth > MAX_KEY_DEPTH) return;
+ for (const [key, value] of Object.entries(node)) {
+ const here = `${path}.${key}`;
+ if (key === '$and' || key === '$or') {
+ if (Array.isArray(value)) {
+ value.forEach((arm, i) => {
+ if (isPlainObject(arm)) conditionFieldKeys(arm, `${here}[${i}]`, prefix, visit, depth + 1);
+ });
+ }
+ continue;
+ }
+ if (key === '$not') {
+ if (isPlainObject(value)) conditionFieldKeys(value, here, prefix, visit, depth + 1);
+ continue;
+ }
+ if (key.startsWith('$')) continue; // unrecognised combinator
+ const field = prefix ? `${prefix}.${key}` : key;
+ if (isPlainObject(value) && !Object.keys(value).some((k) => k.startsWith('$'))) {
+ // Nested relation / deep equality — the field position is one level
+ // deeper, so descend rather than reporting the intermediate hop twice.
+ // An EMPTY nested object addresses nothing further; report the hop itself.
+ if (Object.keys(value).length > 0) {
+ conditionFieldKeys(value, here, field, visit, depth + 1);
+ continue;
+ }
+ }
+ visit({ field, path: here });
+ }
+}
+
+/**
+ * Emit every FIELD KEY inside one authored filter subtree, whatever shape it
+ * was authored in — the key half of what `validate-preset-comparands.ts` does
+ * for values, and the traversal `filter-token-unknown` already performs while
+ * reasoning only about the strings it finds.
+ *
+ * Holds no judgement: it does not know which object the filter is bound to and
+ * emits no findings. Resolution is {@link resolveFieldPath}'s job
+ * (`object-graph.ts`) and the verdict is the caller's.
+ */
+export function walkFilterFieldKeys(
+ node: unknown,
+ path: string,
+ visit: (key: FilterFieldKey) => void,
+ depth = 0,
+): void {
+ if (depth > MAX_KEY_DEPTH) return;
+
+ if (Array.isArray(node)) {
+ // Triple: ['field', op, value] — the field position is a non-keyword
+ // string and the operator position is in the AST vocabulary (the
+ // `isFilterAST` test `validate-preset-comparands.ts` uses).
+ if (
+ typeof node[0] === 'string' && typeof node[1] === 'string'
+ && !['and', 'or'].includes(node[0].toLowerCase())
+ && VALID_AST_OPERATORS.has(node[1].toLowerCase())
+ ) {
+ visit({ field: node[0], path: `${path}[0]` });
+ return;
+ }
+ // Group ['and'|'or', ...members] or a bare list — recurse the members.
+ node.forEach((member, i) => {
+ if (typeof member === 'string') return; // the leading keyword
+ walkFilterFieldKeys(member, `${path}[${i}]`, visit, depth + 1);
+ });
+ return;
+ }
+
+ if (!isPlainObject(node)) return;
+
+ // View filter rule: { field, operator[, value] }.
+ if (typeof node.field === 'string' && typeof node.operator === 'string') {
+ visit({ field: node.field, path: `${path}.field` });
+ return;
+ }
+
+ conditionFieldKeys(node, path, '', visit, depth);
+}
diff --git a/packages/lint/src/index.ts b/packages/lint/src/index.ts
@@ -467,6 +467,37 @@ export {
 } from './validate-chart-bindings.js';
 export type { ChartBindingFinding, ChartBindingSeverity } from './validate-chart-bindings.js';
 
+// [#14105] The layer BELOW the chart/widget binding rules above: a dataset's
+// own `include[]`, `dimensions[].field`, `measures[].field` and filter KEYS,
+// resolved against the object graph. Its base-object half is
+// `validateObjectReferences`' `datasets[].object` site.
+export {
+ validateDatasetReferences,
+ DATASET_INCLUDE_UNKNOWN,
+ DATASET_FIELD_UNKNOWN,
+ DATASET_FIELD_NOT_INCLUDED,
+ DATASET_FILTER_FIELD_UNKNOWN,
+} from './validate-dataset-references.js';
+export type { DatasetRefFinding, DatasetRefSeverity } from './validate-dataset-references.js';
+
+// The two reusable seams the rule above is written on, exported because the
+// queued siblings (#14148 widget filter keys + sortBy, #14107 list-view field
+// 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.
+export {
+ indexObjectGraph,
+ resolveFieldPath,
+ isUnjudgeable,
+ nearestName,
+ suggestName,
+ listNames,
+ RELATIONSHIP_FIELD_TYPES,
+} from './object-graph.js';
+export type { ObjectGraph, GraphObject, GraphField, FieldPathVerdict } from './object-graph.js';
+export { walkFilterFieldKeys } from './filter-walk.js';
+export type { FilterFieldKey } from './filter-walk.js';
+
 // #4762 — the two STATIC artifacts an object validation rule carries (a
 // `format` rule's `regex`, a `json_schema` rule's `schema`) are fail-OPEN at
 // runtime: one that does not compile is logged and skipped, so the rule is

diff --git a/.changeset/dataset-reference-resolution.md b/.changeset/dataset-reference-resolution.md
@@ -0,0 +1,95 @@
+---
+'@objectstack/lint': minor
+---
+
+Resolve an ADR-0021 dataset's own references — base object, `include[]`,
+`dimensions[].field` / `measures[].field`, and filter KEYS — at
+`validate`/`build` (#14105)
+
+A dataset could name a **base object that does not exist**, join a
+**relationship that does not exist**, and bind every dimension and measure to
+**fields that do not exist**, and `objectstack validate` exited **0** with
+`✓ Validation passed`. `objectstack build` also exited 0 and wrote the dangling
+dataset into `dist/objectstack.json`.
+
+The sting was that the author-time rule pass **already walked those exact
+nodes**. Measured on published 17.2.0, each mutation applied on its own and
+confirmed on disk before running:
+
+| mutation | before | after |
+|:----------------------------------------------------|:-------|:------|
+| dimension `field` → a base field that does not exist | passed | `dataset-field-unknown` |
+| dimension `field` → a joined field that does not exist | passed | `dataset-field-unknown` |
+| measure `field` → a field that does not exist | passed | `dataset-field-unknown` |
+| measure filter KEY → a field that does not exist | passed | `dataset-filter-field-unknown` |
+| `include[]` → a relationship that does not exist | passed | `dataset-include-unknown` |
+| `object` → an object that does not exist | passed | `object-reference-unknown` |
+
+The two controls in that measurement — a duplicate measure name
+(`DatasetSchema.superRefine`) and a bad date macro in a **measure filter**
+(`filter-token-unknown`) — both failed the build, so datasets were
+demonstrably in the validation path the whole time. `filter-token-unknown`
+already stood at `datasets[1].measures[1].filter.last_update_at.$lt` and
+reasoned about the **value**; nothing standing in that same position resolved
+the **key**, or the sibling `field` one level up.
+
+This matters more for a dataset than for most metadata because a dataset is the
+semantic layer: dashboards and reports bind its dimensions and measures by name
+(ADR-0021), and the consumer end of that binding is already guarded
+(`widget-dataset-unknown` / `widget-dimension-unknown` / `widget-measure-unknown`,
+#7529/#8902). So the surviving hole was the quiet one — every binding resolves,
+the board renders, and the charts are empty or subtly wrong because the dataset
+underneath addresses columns that do not exist.
+
+**Five verdicts, all `error`.** Four are new rule ids on a new suite member,
+`validateDatasetReferences`:
+
+- `dataset-include-unknown` — an `include[]` entry that resolves to nothing, or
+ to a field that is not a relationship, so no join can be derived from it.
+- `dataset-field-unknown` — a dimension or measure `field` path that resolves to
+ no column, on the base object or on any joined object along the path.
+- `dataset-field-not-included` — the second real check: a dotted path that
+ RESOLVES, but whose relationship prefix was never declared in `include`.
+ ADR-0021 D-C joins only declared paths, so the column is out of the query's
+ reach however real it is.
+- `dataset-filter-field-unknown` — a filter key on `Dataset.filter` or
+ `measures[].filter`, in any of the three authored filter shapes.
+
+The fifth, the base object itself, lands on `validateObjectReferences` as a new
+`datasets[].object` reference site rather than as a sixth id here. That rule's
+charter IS object-name references that are plain `z.string()`, and putting it
+there buys the curated cross-package severity ladder: the platform's own
+`system.datasets.ts` declares five datasets over `sys_*` objects, three of which
+live in packages a stack compiling plugin-auth alone cannot see. All five
+resolve through `PLATFORM_PROVIDED_OBJECT_NAMES`; a local "not in this stack ⇒
+error" check would have reported every one of them. When the base object does
+not resolve, `validateDatasetReferences` skips the dataset entirely, so one typo
+yields one finding rather than one per dimension, measure and filter key.
+
+**Skips, so a finding is never a guess** (ADR-0072 D1): an object this stack
+does not define, an object with no readable field map (ADR-0015 `external` and
+introspected schemas), a registry-injected system column, and any hop *through*
+one — an injected `owner_id` is a lookup at the registry whose target is
+invisible here, so `owner_id.name` is unanswerable rather than a miss. The
+shipped `showcase_task_metrics` dimension `{ field: 'created_at' }` is that skip's
+live case, and every shipped dataset in the repo is silent under the new rule.
+
+**Two reusable seams ship with it**, newly exported, because the same two
+questions are asked at a dashboard widget's filter keys and `sortBy` and at a
+list view's field positions, and three independent copies of a hop-walker drift:
+
+- `object-graph.ts` — `indexObjectGraph` / `resolveFieldPath` / `isUnjudgeable`,
+ answering "what does this `relationship[.relationship].field` path resolve to?"
+ as a discriminated **verdict** union rather than a boolean, so a caller can
+ tell "this hop is not a relationship" from "this leaf does not exist" and write
+ the right prescription. Plus `nearestName` / `suggestName` / `listNames`.
+- `walkFilterFieldKeys` (`filter-walk.ts`) — the FIELD-KEY half of a filter
+ subtree, beside the subtree-finding half that module already owns. It handles
+ all three authored shapes (Mongo condition object, `{ field, operator, value }`
+ rules, `[field, op, value]` triples), because a reader that handles only one
+ shape is the exact bug #3574 was filed against, and it composes a nested
+ condition object into one relationship path so `{ account: { region: … } }`
+ reports `account.region` rather than a bare `region` resolved against the
+ wrong object.
+
+Both hold mechanism only — no rule ids, no severities, no findings.
diff --git a/packages/lint/src/filter-walk.ts b/packages/lint/src/filter-walk.ts
@@ -35,8 +35,21 @@
  * they resolve an additional vocabulary (`AppContextSelector` ids such as
  * `{active_package}`) that is meaningless in a filter, and restricting the walk
  * is what holds false positives at zero.
+ *
+ * ## The two halves of a filter, and where each one is answered
+ *
+ * `walkAuthoredFilters` finds the SUBTREES. Inside one, a rule wants either the
+ * VALUES (`validate-filter-tokens.ts` classifies placeholders in them;
+ * `validate-preset-comparands.ts` judges ordering comparands) or the FIELD KEYS
+ * — the names the query is filtered BY. {@link walkFilterFieldKeys} is the
+ * second half (#14105), and it is here rather than in its first caller because
+ * the shape dispatch is identical to the one `validate-preset-comparands.ts`
+ * already performs on values: the platform authors filters three ways, and a
+ * reader that handles only one shape is the exact bug #3574 was filed against.
  */
 
+import { VALID_AST_OPERATORS } from '@objectstack/spec/data';
+
 /** Any plain metadata record. */
 type AnyRec = Record<string, unknown>;
 
@@ -162,3 +175,122 @@ export function walkAuthoredFilters(
  });
  }
 }
+
+// ── The FIELD-KEY half of a filter subtree (#14105) ──────────────────────────
+
+/** One field position inside an authored filter. */
+export interface FilterFieldKey {
+ /**
+ * The field the condition filters BY, exactly as authored — a bare name
+ * (`status`), or a dotted relationship path (`account.region`, whether
+ * spelled that way or reached by descending a nested condition object).
+ */
+ field: string;
+ /** Config path of the position, e.g. `datasets[1].measures[1].filter.last_update_at`. */
+ path: string;
+}
+
+/** Recursion guard — an authored filter is a bounded document, not a graph. */
+const MAX_KEY_DEPTH = 32;
+
+function isPlainObject(v: unknown): v is AnyRec {
+ return !!v && typeof v === 'object' && !Array.isArray(v) && !(v instanceof Date);
+}
+
+/**
+ * Emit the field positions of one Mongo-style condition NODE.
+ *
+ * `prefix` carries the relationship path accumulated by descending nested
+ * condition objects, so `{ account: { region: { $eq: 'emea' } } }` reports the
+ * single position `account.region` rather than a bare `region` that would
+ * resolve against the wrong object. A node whose value carries `$` operators is
+ * a leaf condition and ends the descent; a `$`-prefixed key that is not a
+ * recognised combinator is skipped and NOT descended, matching
+ * `validate-preset-comparands.ts` — an unrecognised operator's operand shape is
+ * not ours to guess.
+ */
+function conditionFieldKeys(
+ node: AnyRec,
+ path: string,
+ prefix: string,
+ visit: (key: FilterFieldKey) => void,
+ depth: number,
+): void {
+ if (depth > MAX_KEY_DEPTH) return;
+ for (const [key, value] of Object.entries(node)) {
+ const here = `${path}.${key}`;
+ if (key === '$and' || key === '$or') {
+ if (Array.isArray(value)) {
+ value.forEach((arm, i) => {
+ if (isPlainObject(arm)) conditionFieldKeys(arm, `${here}[${i}]`, prefix, visit, depth + 1);
+ });
+ }
+ continue;
+ }
+ if (key === '$not') {
+ if (isPlainObject(value)) conditionFieldKeys(value, here, prefix, visit, depth + 1);
+ continue;
+ }
+ if (key.startsWith('$')) continue; // unrecognised combinator
+ const field = prefix ? `${prefix}.${key}` : key;
+ if (isPlainObject(value) && !Object.keys(value).some((k) => k.startsWith('$'))) {
+ // Nested relation / deep equality — the field position is one level
+ // deeper, so descend rather than reporting the intermediate hop twice.
+ // An EMPTY nested object addresses nothing further; report the hop itself.
+ if (Object.keys(value).length > 0) {
+ conditionFieldKeys(value, here, field, visit, depth + 1);
+ continue;
+ }
+ }
+ visit({ field, path: here });
+ }
+}
+
+/**
+ * Emit every FIELD KEY inside one authored filter subtree, whatever shape it
+ * was authored in — the key half of what `validate-preset-comparands.ts` does
+ * for values, and the traversal `filter-token-unknown` already performs while
+ * reasoning only about the strings it finds.
+ *
+ * Holds no judgement: it does not know which object the filter is bound to and
+ * emits no findings. Resolution is {@link resolveFieldPath}'s job
+ * (`object-graph.ts`) and the verdict is the caller's.
+ */
+export function walkFilterFieldKeys(
+ node: unknown,
+ path: string,
+ visit: (key: FilterFieldKey) => void,
+ depth = 0,
+): void {
+ if (depth > MAX_KEY_DEPTH) return;
+
+ if (Array.isArray(node)) {
+ // Triple: ['field', op, value] — the field position is a non-keyword
+ // string and the operator position is in the AST vocabulary (the
+ // `isFilterAST` test `validate-preset-comparands.ts` uses).
+ if (
+ typeof node[0] === 'string' && typeof node[1] === 'string'
+ && !['and', 'or'].includes(node[0].toLowerCase())
+ && VALID_AST_OPERATORS.has(node[1].toLowerCase())
+ ) {
+ visit({ field: node[0], path: `${path}[0]` });
+ return;
+ }
+ // Group ['and'|'or', ...members] or a bare list — recurse the members.
+ node.forEach((member, i) => {
+ if (typeof member === 'string') return; // the leading keyword
+ walkFilterFieldKeys(member, `${path}[${i}]`, visit, depth + 1);
+ });
+ return;
+ }
+
+ if (!isPlainObject(node)) return;
+
+ // View filter rule: { field, operator[, value] }.
+ if (typeof node.field === 'string' && typeof node.operator === 'string') {
+ visit({ field: node.field, path: `${path}.field` });
+ return;
+ }
+
+ conditionFieldKeys(node, path, '', visit, depth);
+}
diff --git a/packages/lint/src/index.ts b/packages/lint/src/index.ts
@@ -467,6 +467,37 @@ export {
 } from './validate-chart-bindings.js';
 export type { ChartBindingFinding, ChartBindingSeverity } from './validate-chart-bindings.js';
 
+// [#14105] The layer BELOW the chart/widget binding rules above: a dataset's
+// own `include[]`, `dimensions[].field`, `measures[].field` and filter KEYS,
+// resolved against the object graph. Its base-object half is
+// `validateObjectReferences`' `datasets[].object` site.
+export {
+ validateDatasetReferences,
+ DATASET_INCLUDE_UNKNOWN,
+ DATASET_FIELD_UNKNOWN,
+ DATASET_FIELD_NOT_INCLUDED,
+ DATASET_FILTER_FIELD_UNKNOWN,
+} from './validate-dataset-references.js';
+export type { DatasetRefFinding, DatasetRefSeverity } from './validate-dataset-references.js';
+
+// The two reusable seams the rule above is written on, exported because the
+// queued siblings (#14148 widget filter keys + sortBy, #14107 list-view field
+// 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.
+export {
+ indexObjectGraph,
+ resolveFieldPath,
+ isUnjudgeable,
+ nearestName,
+ suggestName,
+ listNames,
+ RELATIONSHIP_FIELD_TYPES,
+} from './object-graph.js';
+export type { ObjectGraph, GraphObject, GraphField, FieldPathVerdict } from './object-graph.js';
+export { walkFilterFieldKeys } from './filter-walk.js';
+export type { FilterFieldKey } from './filter-walk.js';
+
 // #4762 — the two STATIC artifacts an object validation rule carries (a
 // `format` rule's `regex`, a `json_schema` rule's `schema`) are fail-OPEN at
 // runtime: one that does not compile is logged and skipped, so the rule is