fix(lint): refuse a list view's dotted field reference where the runtime door refuses it (#14368)

#14107's rule judges only the HEAD segment of a list-view field reference, so a
dotted path whose head resolves to a real relationship field passed `os validate`
and `os build` clean while every query door a list view reaches refuses it by
name. That half was recorded in the rule's docblock and pinned in tests rather
than closed, because its failure mode is the opposite of the silent-blank class
#14107 gates: a loud `400 INVALID_FIELD` on the first fetch.

Adds it as a second finding class with its own id, `list-view-field-dotted`,
scoped by the DOOR rather than by the position table:

  - projection (`columns[]`): both doors refuse a dotted entry unconditionally;
  - filter (`filter`, `tabs[].filter`, `userFilters.tabs[].filter`,
    `filterableFields`, `userFilters.fields`): judged by the same
    `classifyDottedFilterHead` the runtime doors ask, so the #8371 carve-outs
    the doors serve are not refused at author time.

`gantt.quickFilters[].field` and `gantt.tooltipFields[]` are excluded: measured
client-side, applied in memory over already-fetched rows through walkers that
split on `.`, so a dot-path is served there rather than refused. Every renderer
binding that reaches no measured door stays unjudged.

`GraphField` gains an optional `multiple` flag (additive) so the shared seam can
answer the classifier's second input without a second copy of the field read.


Claude-Session: https://claude.ai/code/session_01WLJQhde67SeTccsmnBVarV

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

Author: claude[bot]

.changeset/list-view-dotted-field-refs.md

@@ -0,0 +1,46 @@
+---
+"@objectstack/lint": minor
+---
+
+fix(lint): refuse a list view's dotted field reference at author time where the runtime door refuses it (#14282)
+
+An accept-set narrowing on `validateListViewFieldRefs`, the #14107 rule — shipped
+as `minor`, matching the level that landing and the two family landings before it
+(#14105, #14148) were given.
+
+#14107 judges only the HEAD segment of a list-view field reference, so a dotted
+path whose head resolves to a real relationship field (`columns: [{ field:
+'owner.name' }]`) passed `os validate` and `os build` clean while every query
+door a list view reaches refuses it by name. That half was recorded in the rule's
+docblock and pinned in tests rather than closed, because its failure mode is the
+opposite of the silent-blank class #14107 gates: a loud `400 INVALID_FIELD` on
+the first fetch. This is the ruled resolution of that half, as a second finding
+class with its own id, `list-view-field-dotted`, so one class can be suppressed
+or filtered without silencing the other (the convention
+`validate-sortable-fields` and `validate-searchable-fields` already follow).
+
+The class is scoped by the DOOR, not by the position table, because some
+list-view positions are read client-side out of the fetched row and walk a dotted
+path perfectly well:
+
+- **Projection** — `columns[]`, in both authored spellings. Clients build the
+  `$select` projection from them, and both doors refuse a dotted entry
+  unconditionally (`assertProjectionHasNoDottedPaths` on the engine boundary,
+  `assertProjectionFieldsExist` at the REST ingress).
+- **Filter** — the view's `filter`, its `tabs[].filter`, its
+  `userFilters.tabs[].filter`, and the two positions declaring which names an end
+  user may filter on (`filterableFields`, `userFilters.fields`). Here the rule
+  asks the same `classifyDottedFilterHead` the runtime doors ask, so the #8371
+  carve-outs the doors serve — structured/JSON heads, array-valued heads, heads
+  whose type is unreadable — are NOT refused at author time.
+
+Deliberately excluded, each measured rather than assumed:
+`gantt.quickFilters[].field` and `gantt.tooltipFields[]`, which the renderer
+resolves IN MEMORY over already-fetched rows through walkers that split on `.`
+(the spec describes the former as "Record field / dot-path", and the measurement
+agreed); and every renderer binding that reaches no query door, which stays
+unjudged rather than acquiring a verdict nobody measured.
+
+Existing behaviour is untouched: a dotted path whose head resolves to nothing
+still reports `list-view-field-unknown`, `sort[]` keeps its owner, and the
+shipped example corpus was measured at zero findings both before and after.

packages/lint/src/index.ts

@@ -435,9 +435,14 @@ export type {
 // 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.
+// [#14282] The same rule's SECOND finding class: a dotted reference at a
+// position whose name reaches a query door (the `$select` projection, or the
+// compiled filter), where that door refuses it by name — the loud-failing half
+// #14107 recorded and left open.
 export {
   validateListViewFieldRefs,
   LIST_VIEW_FIELD_UNKNOWN,
+  LIST_VIEW_FIELD_DOTTED,
 } from './validate-list-view-field-refs.js';
 export type {
   ListViewFieldRefFinding,

packages/lint/src/object-graph.ts

@@ -82,6 +82,19 @@ export interface GraphField {
    * tolerant consumer Prime Directive #12 refuses, so only `reference` is read.
    */
   reference?: string;
+  /**
+   * The declared `multiple: true` flag, when the author wrote one.
+   *
+   * Read here because the dotted-path verdict a caller may reach for
+   * ({@link classifyDottedFilterHead} in `@objectstack/spec/data`) is a
+   * function of BOTH `type` and `multiple`: an array-valued head is
+   * deliberately unjudged there, since a numeric-index dotted path genuinely
+   * reaches into it on two of three backends. A caller handed only `type`
+   * would have to re-derive the flag from the raw stack, which is the second
+   * copy this module exists to prevent. Additive (#14282): every existing
+   * consumer that ignores the key keeps its verdicts byte-for-byte.
+   */
+  multiple?: boolean;
 }
 
 /**
@@ -128,6 +141,7 @@ function graphObjectOf(obj: AnyRec): GraphObject | null {
     fields.set(n, {
       type: typeof f.type === 'string' ? f.type : undefined,
       reference: strName(f.reference),
+      multiple: f.multiple === true ? true : undefined,
     });
   }
   if (names.size === 0) return null;

packages/lint/src/validate-list-view-field-refs.test.ts

@@ -15,6 +15,7 @@ import { validateReferenceIntegrity } from './reference-integrity-suite.js';
 import {
   validateListViewFieldRefs,
   LIST_VIEW_FIELD_UNKNOWN,
+  LIST_VIEW_FIELD_DOTTED,
   type ListViewFieldRefFinding,
 } from './validate-list-view-field-refs.js';
 import { SORT_FIELD_UNKNOWN } from './validate-sortable-fields.js';
@@ -39,6 +40,12 @@ const OBJECTS = [
       { name: 'cover', type: 'image', label: 'Cover' },
       { name: 'parent', type: 'lookup', reference: 'duly_task', label: 'Parent' },
       { name: 'owner', type: 'lookup', reference: 'duly_person', label: 'Owner' },
+      // [#14282] The three head shapes the FILTER door treats differently.
+      // `payload` is the ruled carve-out (`STRUCTURED_JSON_TYPES`, live on
+      // memory and mongodb); `score` is virtual; `tags` is array-valued.
+      { name: 'payload', type: 'json', label: 'Payload' },
+      { name: 'score', type: 'formula', label: 'Score' },
+      { name: 'tags', type: 'text', multiple: true, label: 'Tags' },
     ],
   },
   {
@@ -297,31 +304,271 @@ describe('#14107 — the "did you mean" comes from the shared seam', () => {
 /**
  * The recorded dotted-path decision (see the rule's module docblock): the HEAD
  * segment is judged and relationship hops are NOT walked, because a list view
- * compiles no joins and all three runtime doors refuse a dotted reference.
- * Both halves are pinned — the half that reports, and the half that stays
- * deliberately silent — so a later "improvement" that starts walking hops has
- * to delete a test that says why.
+ * compiles no joins and the runtime doors refuse a dotted reference.
+ *
+ * ⚠️ This block used to pin BOTH halves — the half that reports, and a half
+ * that stayed deliberately silent (`owner.name` and `title.x` in `columns`
+ * passing clean). #14282 is the card that half was recorded for, and it ruled
+ * the other way: those two now report, as {@link LIST_VIEW_FIELD_DOTTED}. The
+ * cases were rewritten rather than deleted, so the pair still reads as one
+ * decision — what changed is which class each lands in, not whether the rule
+ * has an opinion. The `#14282` block below carries the new half in full.
  */
-describe('#14107 — dotted paths', () => {
+describe('#14107 — dotted paths, HEAD-segment resolution', () => {
   it('a dotted path whose HEAD resolves to nothing is reported', () => {
     const findings = validateListViewFieldRefs(stackWith(mutate({ columns: [{ field: 'ownr.name' }] })));
     expect(findings).toHaveLength(1);
+    expect(findings[0].rule).toBe(LIST_VIEW_FIELD_UNKNOWN);
     expect(findings[0].message).toContain('"ownr"');
     // The author reads back what they typed, not only the segment judged.
     expect(findings[0].message).toContain('ownr.name');
     expect(findings[0].message).toContain('compiles');
   });
 
-  it('a dotted path whose head resolves is left to the runtime doors', () => {
+  it('hops are still NOT walked — a bad LEAF under a good head is not judged as a leaf', () => {
+    // `owner` resolves, `duly_person` has no `nope`. Were hops walked, this
+    // would be a `field-unknown` on `duly_person`. It is not: the finding is
+    // the #14282 dotted class, which never mentions the leaf at all.
+    const findings = validateListViewFieldRefs(stackWith(mutate({ columns: [{ field: 'owner.nope' }] })));
+    expect(findings).toHaveLength(1);
+    expect(findings[0].rule).toBe(LIST_VIEW_FIELD_DOTTED);
+    expect(findings[0].message).not.toContain('duly_person');
+  });
+});
+
+/**
+ * [#14282] The SECOND finding class: a dotted reference at a position whose
+ * name reaches a query door, where that door refuses it by name.
+ *
+ * The scoping is by DOOR, not by position — see the rule's module note. So
+ * this block pins three things and not one: which positions report, which
+ * deliberately do not (the measured client-side ones, `gantt.quickFilters`
+ * first among them), and that the FILTER positions ask the same
+ * `classifyDottedFilterHead` the runtime door asks, rather than refusing what
+ * the door serves.
+ */
+describe('#14282 — a dotted reference the PROJECTION door refuses', () => {
+  it('a dotted `columns[].field` whose head resolves is now reported', () => {
     const findings = validateListViewFieldRefs(stackWith(mutate({ columns: [{ field: 'owner.name' }] })));
-    expect(findings).toEqual([]);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].rule).toBe(LIST_VIEW_FIELD_DOTTED);
+    expect(findings[0].severity).toBe('error');
+    expect(findings[0].path).toBe('views[0].list.columns[0].field');
+    expect(findings[0].message).toContain('owner.name');
+    expect(findings[0].message).toContain('assertProjectionHasNoDottedPaths');
+    expect(findings[0].hint).toContain('"owner"');
+  });
+
+  it('the bare-string `columns[]` spelling is judged too', () => {
+    const findings = validateListViewFieldRefs(stackWith(mutate({ columns: ['owner.name'] })));
+    expect(findings).toHaveLength(1);
+    expect(findings[0].rule).toBe(LIST_VIEW_FIELD_DOTTED);
+    expect(findings[0].path).toBe('views[0].list.columns[0]');
   });
 
-  it('a dotted path through a non-relationship head is also left alone', () => {
-    // `title` is a text field; `title.x` is refused at query time, not here.
+  it('the projection door has NO head carve-out, so a scalar head reports too', () => {
+    // `title` is a text field. `assertProjectionHasNoDottedPaths` filters on
+    // `f.includes('.')` alone — the head's type never enters that door.
     const findings = validateListViewFieldRefs(stackWith(mutate({ columns: [{ field: 'title.x' }] })));
+    expect(findings).toHaveLength(1);
+    expect(findings[0].rule).toBe(LIST_VIEW_FIELD_DOTTED);
+  });
+
+  it('a structured/JSON head is reported at a COLUMN even though the filter door serves it', () => {
+    // The #8371 carve-out is the FILTER door's, not the projection door's.
+    // Getting this wrong in either direction is the whole point of scoping the
+    // class by door rather than by "a list view compiles no joins".
+    const findings = validateListViewFieldRefs(stackWith(mutate({ columns: [{ field: 'payload.theme' }] })));
+    expect(findings).toHaveLength(1);
+    expect(findings[0].rule).toBe(LIST_VIEW_FIELD_DOTTED);
+  });
+
+  it('an undotted column is untouched by the new class', () => {
+    expect(validateListViewFieldRefs(stackWith(FULL_LIST_VIEW))).toEqual([]);
+  });
+});
+
+describe('#14282 — a dotted key the FILTER door refuses, and the ones it serves', () => {
+  const filterOn = (field: string): AnyRec => ({
+    filter: [{ field, operator: 'equals', value: 'x' }],
+  });
+
+  it('a relation head is refused — it stores an id, not an embedded document', () => {
+    const findings = validateListViewFieldRefs(stackWith(mutate(filterOn('owner.name'))));
+    expect(findings).toHaveLength(1);
+    expect(findings[0].rule).toBe(LIST_VIEW_FIELD_DOTTED);
+    expect(findings[0].severity).toBe('error');
+    expect(findings[0].path).toBe('views[0].list.filter[0].field');
+    expect(findings[0].message).toContain('lookup');
+    expect(findings[0].message).toContain('can only match zero records');
+  });
+
+  it('a virtual head is refused — nothing materialises a column to reach into', () => {
+    const findings = validateListViewFieldRefs(stackWith(mutate(filterOn('score.x'))));
+    expect(findings).toHaveLength(1);
+    expect(findings[0].message).toContain('computed');
+  });
+
+  it('a plain scalar head is refused — there is nothing beneath it', () => {
+    const findings = validateListViewFieldRefs(stackWith(mutate(filterOn('title.x'))));
+    expect(findings).toHaveLength(1);
+    expect(findings[0].message).toContain('single scalar value');
+  });
+
+  it('⛔ a structured/JSON head is NOT refused — the #8371 ruling\'s carve-out', () => {
+    // Live on driver-memory and driver-mongodb (2 rows in the #8371
+    // measurement table). Refusing it at author time would delete a working
+    // capability on two of three backends — the exact fail-closed drift the
+    // shared classifier exists to prevent.
+    expect(validateListViewFieldRefs(stackWith(mutate(filterOn('payload.theme'))))).toEqual([]);
+  });
+
+  it('⛔ an array-valued head is NOT refused — a numeric-index path reaches it', () => {
+    expect(validateListViewFieldRefs(stackWith(mutate(filterOn('tags.0'))))).toEqual([]);
+  });
+
+  it('a registry-injected head is NOT refused at a filter — its type is invisible here', () => {
+    // `created_at` resolves through skip 3 with no readable type, and
+    // `classifyDottedFilterHead` answers `null` for an unreadable head.
+    expect(validateListViewFieldRefs(stackWith(mutate(filterOn('created_at.x'))))).toEqual([]);
+  });
+
+  it('the tab and user-filter tab presets are judged on the same axis', () => {
+    const findings = validateListViewFieldRefs(
+      stackWith(
+        mutate({
+          tabs: [{ name: 'mine', filter: [{ field: 'owner.name', operator: 'equals', value: 'x' }] }],
+          userFilters: {
+            fields: [{ field: 'status' }],
+            tabs: [{ name: 'open', filter: [{ field: 'parent.title', operator: 'equals', value: 'x' }] }],
+          },
+        }),
+      ),
+    );
+    expect(idsOf(findings).sort()).toEqual([
+      'views[0].list.tabs[0].filter[0].field',
+      'views[0].list.userFilters.tabs[0].filter[0].field',
+    ]);
+    expect(findings.every((f) => f.rule === LIST_VIEW_FIELD_DOTTED)).toBe(true);
+  });
+
+  it('the two positions that DECLARE end-user filterable names are judged', () => {
+    // objectui folds the resulting conditions into the fetched query
+    // (`buildEffectiveFilter`), so these names become filter keys.
+    const findings = validateListViewFieldRefs(
+      stackWith(
+        mutate({
+          filterableFields: ['owner.name'],
+          userFilters: { fields: [{ field: 'parent.title' }] },
+        }),
+      ),
+    );
+    expect(idsOf(findings).sort()).toEqual([
+      'views[0].list.filterableFields[0]',
+      'views[0].list.userFilters.fields[0].field',
+    ]);
+    expect(findings.every((f) => f.rule === LIST_VIEW_FIELD_DOTTED)).toBe(true);
+  });
+});
+
+describe('#14282 — the measured exclusions: positions read CLIENT-SIDE', () => {
+  it('⛔ `gantt.quickFilters[].field` accepts a dot-path — the card\'s named exception', () => {
+    // Measured, and it went the other way round from the rest of the card.
+    // The spec describes the position as "Record field / dot-path", and
+    // objectui's `ObjectGantt.tsx` applies these filters IN MEMORY over the
+    // already-fetched rows, resolving each through a walker that splits on `.`
+    // and steps through the record object (`resolveFilterKey`). No query door
+    // is involved, so nothing refuses it.
+    const findings = validateListViewFieldRefs(
+      stackWith(mutate({ gantt: { quickFilters: [{ field: 'owner.name' }] } })),
+    );
     expect(findings).toEqual([]);
   });
+
+  it('the head of a gantt quick filter is STILL judged for existence (#14107 is untouched)', () => {
+    const findings = validateListViewFieldRefs(
+      stackWith(mutate({ gantt: { quickFilters: [{ field: 'ownr.name' }] } })),
+    );
+    expect(findings).toHaveLength(1);
+    expect(findings[0].rule).toBe(LIST_VIEW_FIELD_UNKNOWN);
+  });
+
+  it('⛔ `gantt.tooltipFields[]` accepts a dot-path — read through `resolvePath`', () => {
+    const findings = validateListViewFieldRefs(
+      stackWith(mutate({ gantt: { tooltipFields: ['owner.name', { field: 'parent.title' }] } })),
+    );
+    expect(findings).toEqual([]);
+  });
+
+  it('⛔ renderer bindings reach no door this card measured, so they stay unjudged', () => {
+    // Very likely still wrong (the gantt scalars read `record[field]` flat),
+    // but "likely wrong" is not a verdict a gate may invent — and the failure
+    // would be the SILENT class, not this loud one. Recorded as a follow-up.
+    const findings = validateListViewFieldRefs(
+      stackWith(
+        mutate({
+          rowColor: { field: 'owner.name' },
+          kanban: { groupByField: 'owner.name' },
+          calendar: { titleField: 'owner.name' },
+          gallery: { coverField: 'owner.name' },
+          tree: { parentField: 'owner.name' },
+          grouping: { fields: [{ field: 'owner.name' }] },
+          hiddenFields: ['owner.name'],
+          fieldOrder: ['owner.name'],
+        }),
+      ),
+    );
+    expect(findings).toEqual([]);
+  });
+
+  it('a `columns[]` entry\'s nested summary/prefix are unjudged for dotted paths too', () => {
+    const findings = validateListViewFieldRefs(
+      stackWith(
+        mutate({
+          columns: [{ field: 'title', summary: { field: 'owner.name' }, prefix: { field: 'parent.title' } }],
+        }),
+      ),
+    );
+    expect(findings).toEqual([]);
+  });
+});
+
+describe('#14282 — the class does not disturb its neighbours', () => {
+  it('the skips still win over the dotted verdict', () => {
+    // An object this stack does not define: no graph, no verdict of any kind.
+    const stack = stackWith(
+      mutate({ data: { provider: 'object', object: 'sys_elsewhere' }, columns: [{ field: 'owner.name' }] }),
+    );
+    expect(validateListViewFieldRefs(stack)).toEqual([]);
+  });
+
+  it('`sort[]` keeps its owner — no dotted finding is minted for it here', () => {
+    const findings = validateListViewFieldRefs(
+      stackWith(mutate({ sort: [{ field: 'owner.name', order: 'asc' }] })),
+    );
+    expect(findings.filter((f) => f.rule === LIST_VIEW_FIELD_DOTTED)).toEqual([]);
+  });
+
+  it('the two classes carry DIFFERENT rule ids, so one can be suppressed alone', () => {
+    const findings = validateListViewFieldRefs(
+      stackWith(mutate({ columns: [{ field: 'ownr.name' }, { field: 'owner.name' }] })),
+    );
+    expect(findings.map((f) => f.rule)).toEqual([LIST_VIEW_FIELD_UNKNOWN, LIST_VIEW_FIELD_DOTTED]);
+  });
+
+  it('the dotted class gates `validate` and `build`, like the rest of the error tier', () => {
+    const stack = stackWith(mutate({ columns: [{ field: 'owner.name' }] }));
+    for (const command of ['validate', 'build'] as const) {
+      const { errors } = splitBySeverity(runAuthoringRules(command, { normalized: stack }));
+      expect(errors.map((e) => e.rule)).toContain(LIST_VIEW_FIELD_DOTTED);
+    }
+  });
+
+  it('the reference-integrity suite carries the new class too', () => {
+    const stack = stackWith(mutate({ columns: [{ field: 'owner.name' }] }));
+    const findings = validateReferenceIntegrity(stack);
+    expect(findings.some((f) => f.rule === LIST_VIEW_FIELD_DOTTED)).toBe(true);
+  });
 });
 
 describe('#14107 — the skips', () => {