fix(lint): resolve every field reference on a list view at validate and build (#14283)

* feat(lint): resolve a list view's field references at validate/build

Every field-naming position on a list view — columns, filter keys,
grouping, rowColor, userFilters, filterableFields, hiddenFields,
fieldOrder and every binding inside the kanban / calendar / gantt /
timeline / gallery / map / tree blocks — was resolved by nothing, on
both `os validate` and `os build`.

Resolution goes through the shared object-graph seam, on the HEAD
segment: a list view compiles no joins and all three runtime doors
refuse a dotted reference, so walking relationship hops here would
bless what the runtime refuses.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WLJQhde67SeTccsmnBVarV

* test(lint): pin the new list-view field-ref rule at the suite and runtime-gate doors

Suite membership plus the runtime publish-gate crossing (refusal + clean
pair) for validateListViewFieldRefs, and the changeset.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WLJQhde67SeTccsmnBVarV

* docs(lint): name the filed follow-up in the dotted-path decision note

The wider narrowing the module docblock defers — a dotted list-view
reference whose head resolves, refused by all three runtime doors — is
filed as #14282; name it so the next author can read the decision.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WLJQhde67SeTccsmnBVarV

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

.changeset/list-view-field-ref-integrity.md

@@ -0,0 +1,64 @@
+---
+"@objectstack/lint": minor
+---
+
+feat(lint): resolve a list view's field references at validate/build (#14107)
+
+Accept-set narrowing, `minor` under the family precedent (#14105, #14148).
+
+A list view names fields in more than twenty places and **none of them was
+resolved against the bound object** — not by `os validate`, and not by `os
+build`, which is the publish gate. Measured on `@objectstack/cli` 17.2.0 from a
+real app, each mutation applied on its own and confirmed on disk: a
+`columns[].field`, a `filter[].field`, a `grouping.fields[].field`, a
+`kanban.groupByField` and a `gantt.startDateField` naming a field that does not
+exist all left `os validate` at `valid: true, warnings: []` and `os build` at
+exit 0, `✓ Build complete`.
+
+Each one fails silently at render, in the way ADR-0078 and the
+`view/layout-without-binding` rule already treat as worth gating: a bad column
+renders blanks, a bad filter key is sent to the engine and matches nothing (an
+empty list indistinguishable from a true zero), a bad gantt start date leaves a
+blank chart, a bad kanban group-by collapses every card into the uncolumned
+bucket. The platform already shipped the *harder* half of this check —
+`view/layout-without-binding` warns when a binding block is **absent**; a block
+that is present but points at a field that does not exist reaches the identical
+end state and got nothing.
+
+The new rule `list-view-field-unknown` (`validateListViewFieldRefs`, a member of
+the reference-integrity suite, so it runs on `validate` / `lint` / `compile` and
+on `view` per-write publish snapshots) resolves every field-naming position on a
+list view against the object graph:
+
+- `columns[]` (bare-string and `{ field }` forms, plus `summary.field` and
+  `prefix.field`), `filter[]` keys, `tabs[].filter[]` keys, `grouping.fields[]`,
+  `rowColor.field`, `userFilters.fields[]`, `userFilters.tabs[].filter[]` keys,
+  `filterableFields[]`, `hiddenFields[]`, `fieldOrder[]`;
+- every field binding inside the `kanban`, `calendar`, `gantt`, `timeline`,
+  `gallery`, `map` and `tree` blocks.
+
+`sort[]` and `searchableFields[]` are deliberately untouched — they already have
+owners (`sort-field-unknown` #9257, `searchable-field-unknown` #6674/#4830),
+each with a runtime-admissibility verdict on top of existence.
+
+Two severity tiers, the `validateFlowTemplatePaths` precedent: `error` where the
+miss changes the data the view returns or collapses the layout it configures
+(every position in the card's measured table), `warning` where the renderer
+drops one decoration and renders the rest (optional colour/title/tooltip/cover
+bindings, a stale `hiddenFields` or `fieldOrder` entry).
+
+Resolution goes through the shared `object-graph.ts` seam (#14105/#14148) — no
+second field-resolution implementation — and judges the **head segment** of a
+dotted reference rather than walking relationship hops: a list view compiles no
+joins, and all three query axes it reaches refuse a dotted path by name
+(`assertProjectionFieldsExist` #7532 / `assertProjectionHasNoDottedPaths` #7589,
+the #8371 dotted filter door, `assertSortFieldsExist` #6994). This is strictly
+wider than "skip dotted paths": `ownr.name` is now reported, where a skip would
+have passed it.
+
+**Migration.** A list view refused by the new rule names a field the bound
+object does not have: correct the spelling (the finding carries a "did you mean"
+and the object's field list) or drop the entry. The three standard skips apply —
+an object this stack does not define, an object with no readable field map
+(ADR-0015 `external`), and registry-injected system columns — plus a fourth on
+this surface: a list view whose `data.provider` is not `object`.

packages/lint/src/index.ts

@@ -427,6 +427,22 @@ export type {
   SortableFieldSeverity,
 } from './validate-sortable-fields.js';
 
+// [#14107] The rest of the list view's field surface — the two rules above own
+// `sort` and `searchableFields`; this one owns every OTHER position that names
+// a field on the bound object (columns, filter keys, grouping, row colour,
+// user filters, and every binding inside the kanban / calendar / gantt /
+// timeline / gallery / map / tree blocks). Resolution goes through the shared
+// `object-graph.ts` seam (#14105/#14148), on the HEAD segment — see that
+// module's dotted-path note.
+export {
+  validateListViewFieldRefs,
+  LIST_VIEW_FIELD_UNKNOWN,
+} from './validate-list-view-field-refs.js';
+export type {
+  ListViewFieldRefFinding,
+  ListViewFieldRefSeverity,
+} from './validate-list-view-field-refs.js';
+
 export { validateActionNameRefs, ACTION_NAME_UNDEFINED } from './validate-action-name-refs.js';
 export type { ActionNameRefFinding, ActionNameRefSeverity } from './validate-action-name-refs.js';
 

packages/lint/src/reference-integrity-suite.test.ts

@@ -18,6 +18,10 @@ describe('reference-integrity suite — membership', () => {
       'validateObjectReferences',
       'validateSearchableFields',
       'validateSortableFields',
+      // [#14107] The rest of the same list view's field surface — every
+      // field-naming position the two members above do not own. Placed beside
+      // them because the three walk the identical rungs.
+      'validateListViewFieldRefs',
       'validateActionNameRefs',
       'validatePageFieldBindings',
       'validateChartBindings',

packages/lint/src/reference-integrity-suite.ts

@@ -50,6 +50,16 @@
  * because a view's declared sort is its FIRST fetch, the refusal is the whole
  * view failing to load, every time, from an authoring typo made long before.
  *
+ * `validateListViewFieldRefs` completes that pair (#14107): the two members
+ * above judge ONE list-view axis each (`sort`, `searchableFields`), and every
+ * OTHER field-naming position on the same record — `columns`, filter keys,
+ * `grouping`, `rowColor`, `userFilters`, `filterableFields`, `hiddenFields`,
+ * `fieldOrder`, and every binding inside the kanban / calendar / gantt /
+ * timeline / gallery / map / tree blocks — was resolved by nothing at all. It
+ * carries BOTH severities, like `validateFlowTemplatePaths`: a position whose
+ * miss empties or mis-selects the view's data gates, one whose miss drops a
+ * decoration advises.
+ *
  * Rules that check SHAPE rather than reference (view containers, responsive
  * styles, seed replay safety, seed state machines, seed/security posture) stay
  * out — they answer a different question and have their own call sites.
@@ -79,6 +89,7 @@
 import { validateObjectReferences } from './validate-object-references.js';
 import { validateSearchableFields } from './validate-searchable-fields.js';
 import { validateSortableFields } from './validate-sortable-fields.js';
+import { validateListViewFieldRefs } from './validate-list-view-field-refs.js';
 import { validateActionNameRefs } from './validate-action-name-refs.js';
 import { validatePageFieldBindings } from './validate-page-field-bindings.js';
 import { validateChartBindings } from './validate-chart-bindings.js';
@@ -187,6 +198,26 @@ export const REFERENCE_INTEGRITY_RULES: readonly ReferenceIntegrityRule[] = [
   // both answer `400 INVALID_SORT` — and a view's sort is its FIRST fetch, so
   // the refusal is the whole view, on every load, traced to nothing.
   { name: 'validateSortableFields', runtimeTypes: ['flow', 'view'], run: validateSortableFields },
+  // [#14107] The REST of the same list view's field surface. The two members
+  // above own `sort` and `searchableFields`; every OTHER field-naming position
+  // on a list view — `columns`, filter keys, `grouping`, `rowColor`,
+  // `userFilters`, `filterableFields`, `hiddenFields`, `fieldOrder` and every
+  // binding inside the kanban / calendar / gantt / timeline / gallery / map /
+  // tree blocks — was resolved by nothing, on both `os validate` and `os
+  // build`. Placed directly after its two siblings because the three walk the
+  // identical rungs (an object's `listViews`, a `defineView` aggregate's
+  // `list` / `listViews`, and the two standalone `views[]` shapes the
+  // `PUT /api/v1/meta/view` door carries), so a rung added to one is read
+  // against the other two.
+  //
+  // `runtimeTypes` gains `view` for exactly the #9313 reason its two siblings
+  // did, and the reason is a property of the SNAPSHOT rather than a
+  // convenience: this member resolves only against `stack.objects`, which the
+  // per-write snapshot does carry, so it has no missing-collection
+  // false-positive channel. The standalone list view a Studio tenant or an
+  // MCP/AI author writes goes through that door and no CLI, so a
+  // build-time-only rule would never reach the author who made the typo.
+  { name: 'validateListViewFieldRefs', runtimeTypes: ['flow', 'view'], run: validateListViewFieldRefs },
   { name: 'validateActionNameRefs', run: validateActionNameRefs },
   { name: 'validatePageFieldBindings', run: validatePageFieldBindings },
   { name: 'validateChartBindings', run: validateChartBindings },

packages/lint/src/runtime-gate.view-writes.test.ts

@@ -29,6 +29,7 @@ import { runRuntimeAuthoringRules } from './runtime-gate.js';
 import { REFERENCE_INTEGRITY_RULES } from './reference-integrity-suite.js';
 import { SORT_FIELD_UNKNOWN, SORT_FIELD_UNSORTABLE } from './validate-sortable-fields.js';
 import { SEARCHABLE_FIELD_UNKNOWN } from './validate-searchable-fields.js';
+import { LIST_VIEW_FIELD_UNKNOWN } from './validate-list-view-field-refs.js';
 
 /** The live object universe the gate resolves against (`RuntimeStackContext.objects`). */
 const objects = [
@@ -127,6 +128,57 @@ describe('a flattened list overlay at the runtime publish gate (#9313)', () => {
     expect(errors, JSON.stringify(errors)).toEqual([]);
   });
 
+  // ── [#14107] the rest of the same overlay's field surface ──
+  //
+  // The two rules above own `sort` and `searchableFields`; every OTHER
+  // field-naming position on the same overlay was resolved by nothing, at this
+  // door as well as at the CLI. Same self rung, same skips, same binding
+  // order — these are the refusal/clean pair that distinguishes a real
+  // crossing from a dispatch-only no-op.
+
+  it('REFUSES a top-level `columns` entry that resolves to no field', () => {
+    const { errors } = gate(overlay({ columns: ['name', 'budgett'] }));
+    const f = errors.find((e) => e.rule === LIST_VIEW_FIELD_UNKNOWN);
+    expect(f, JSON.stringify(errors)).toBeDefined();
+    expect(f!.path).toBe('views[0].columns[1]');
+    expect(f!.where).toContain('flattened list overlay');
+  });
+
+  it('REFUSES a top-level `kanban.groupByField` that resolves to no field', () => {
+    const { errors } = gate(overlay({ kanban: { groupByField: 'statuss', columns: ['name'] } }));
+    const f = errors.find((e) => e.rule === LIST_VIEW_FIELD_UNKNOWN);
+    expect(f, JSON.stringify(errors)).toBeDefined();
+    expect(f!.path).toBe('views[0].kanban.groupByField');
+    expect(f!.message).toContain('Did you mean "status"?');
+  });
+
+  it('REFUSES a top-level `filter` key that resolves to no field', () => {
+    const { errors } = gate(overlay({
+      filter: [{ field: 'budget', operator: 'equals', value: 1 }],
+    }));
+    const f = errors.find((e) => e.rule === LIST_VIEW_FIELD_UNKNOWN);
+    expect(f, JSON.stringify(errors)).toBeDefined();
+    expect(f!.path).toBe('views[0].filter[0].field');
+  });
+
+  it('a fully bound overlay publishes clean across every one of those positions', () => {
+    const result = gate(overlay({
+      columns: ['name', { field: 'status' }],
+      filter: [{ field: 'status', operator: 'equals', value: 'open' }],
+      grouping: { fields: [{ field: 'status' }] },
+      rowColor: { field: 'status' },
+      kanban: { groupByField: 'status', columns: ['name'] },
+      hiddenFields: ['days_open'],
+    }));
+    expect(result.errors, JSON.stringify(result.errors)).toEqual([]);
+    expect(result.rulesRun).toContain('validateReferenceIntegrity');
+  });
+
+  it('a system column in a walked position publishes clean (skip ③)', () => {
+    const { errors } = gate(overlay({ columns: ['name', 'created_at'] }));
+    expect(errors, JSON.stringify(errors)).toEqual([]);
+  });
+
   // ── the granularity wall: exactly two members cross, nothing rides along ──
 
   it('does NOT refuse an overlay for a rowAction naming a stack-level action — no member rides along', () => {
@@ -178,9 +230,19 @@ describe('a flattened list overlay at the runtime publish gate (#9313)', () => {
     // precisely so a fourth crossing has to be argued here; this one's
     // false-positive measurement is `runtime-gate.view-page-refs.test.ts`,
     // which reproduces the phantom findings the collection removes.
+    // [#14107] The fourth crossing, argued here as this list demands. It is the
+    // same KIND of crossing as the first two — a list view's field references,
+    // resolved against `stack.objects`, the one collection every per-write
+    // snapshot carries — so it has no missing-collection false-positive
+    // channel to open; the controls directly below are its measurement, on the
+    // shape the door actually carries. Not crossing it would have been the
+    // #9313 failure inverted: the standalone list view a Studio tenant or an
+    // MCP/AI author writes goes through `PUT /api/v1/meta/view` and no CLI, so
+    // a build-time-only rule never reaches the author who made the typo.
     expect(crossed).toEqual([
       'validateSearchableFields',
       'validateSortableFields',
+      'validateListViewFieldRefs',
       'validateViewPageRefs',
     ]);
     // And every member still judges flow snapshots — the #4463 P1 surface is