fix(lint): resolve dotted dashboard filter fields on the object graph and drop the SYSTEM_FIELDS union

[baozhoutao]

Fixes #14275

dashboard-filter-field-unknown resolves a dashboard-level filter's effective field
against every bound widget's dataset object. It shipped with two limitations, both now
closed by migrating that branch onto the resolveFieldPath / joinablePrefixes /
injectedColumnsFor seam — exactly as #14148 did one key over, on the widget's own
filter.

Head SHA for every reading below: e685f7839.

The two gaps

1. Every dotted path was skipped outright. The branch carried

if (field.includes('.')) continue;

whose comment said a relationship path "can't be checked here". Accurate when nothing in
packages/lint could walk hops; false since resolveFieldPath landed (#14267 for
#14105). So filterBindings: { dateRange: 'account.signed_at' } was unjudged whether or
not account existed, whether or not signed_at existed on it, and whether or not
account was declared in the dataset's include. The consequence is the sharper one on
this position: a dashboard filter is ANDed into every widget's analytics query, so
one unjudged dotted re-target degrades the whole board, not one tile.

2. Existence was decided against the flat SYSTEM_FIELDS union. The test was
objectFields.has(field) || SYSTEM_FIELDS.has(field), which answers "could this name be
a system column anywhere". object-graph.ts deliberately does not do that, and says
why: on ownership: 'none' the platform injects no owner_id, so the union answered a
real defect as resolvable. The same holds for systemFields: { audit: false } and the
bare dateRange default, created_at.

The migration

The (a1) loop body now mirrors (a2) limb for limb:

• skips 1 and 2 taken once per widget off the shared graph (an object this stack
  does not define, or one with no readable field map) — replacing the old
  objectFieldTypes.get(datasetObject) guard, which was truthy for an object with zero
  typed fields and therefore reported every filter field on it;
• resolveFieldPath(graph, datasetObject, field) per filter, with isUnjudgeable
  verdicts never reported (ADR-0072 D1);
• an existence miss errors as dashboard-filter-field-unknown, keeping the id;
• the joinablePrefixes(dataset.include) clause for a dotted path;
• the lint: view-filter / page-binding field checks resolve against the blanket SYSTEM_FIELDS union, so the #8116 unprovisioned-anchor warning cannot reach filter surfaces #8340 provenance warning, unchanged in wording.

Message shapes. The explicit-vs-inherited wording is kept byte-for-byte for a
bare column — that is the whole shipped population, and this PR narrows an accept set
rather than re-wording what already fires. A dotted miss is rendered through
describeFieldPathVerdict, so it names which hop failed ("traverses account, which
is not a field on object crm_deal"); a bare "has no field a.b" would send the author
looking for a column nobody wrote.

The id decision

New error id dashboard-filter-field-not-included (exported from the barrel,
documented in the module doc's rule list) rather than reusing the existence id. It
mirrors WIDGET_FILTER_FIELD_NOT_INCLUDED and the family's one-id-per-class
convention that PR #14368 pinned: the repair is a different edit — declare the join,
versus point the filter at something real — and a reader filtering CI output by id
should be able to tell those apart.

Consequence stated rather than left implicit: validateWidgetBindings is
surfaces: CLI_AND_RUNTIME, so the new error id joins the #7529 runtime publish gate
alongside the rule's other errors, as one "this board cannot render"
reference-integrity class (the 2026-08-15 ruling that put all of them there). The
existing "exactly the six" assertion in runtime-gate.test.ts is scoped to the cases it
exercises and is unchanged.

The #8340 answer

dashboard-filter-field-unprovisioned stays, and unprovisionedAnchors stays as its
source. The verdict's injected marker cannot replace it — the marker says the leaf
resolved through the injected set, never whether the anchor has storage behind it;
that derivation is unprovisionedInjectedColumns in the spec. What the marker does is
gate the question, which is strictly better than the union membership test it
replaces: only a leaf that resolved because it is injected can be an unprovisioned
anchor (an author-declared column of the same name is one they vouch for, #7859).

It also now travels: the anchor is looked up on verdict.object / verdict.field —
the object the leaf landed on — so a dotted filter path ending on an ADR-0015 external
object is answered too. The old branch could not do that at all; it skipped every dotted
field before reaching the provenance test. Pinned by a new test.

SYSTEM_FIELDS and the #8999 census

The import is dropped — the branch was this file's only read site. That makes the
validate-widget-bindings.ts row in system-fields-consumers.test.ts's LEDGER stale, so
it is deleted in the same commit, with a note recording why the file left the
population (a shrinking population is the one direction that census cannot distinguish
from a broken analyzer). The rule still references the #8116 provenance API, so its
obligation did not lapse with the row. The other nine consumers are untouched.

Fixture pass over the shipped dashboards

Per the triage ruling's standing condition. A throwaway probe (deleted before commit;
the tree is clean) ran validateWidgetBindings over each shipped stack twice — once
with the rule as of the merge base 8eeca27db, once with this branch's — in one
process, so both readings are over byte-identical metadata.

stack	objects	dashboards	dashboard filters	filter x widget reaches	BASE dash-filter findings	HEAD dash-filter findings	BASE all findings	HEAD all findings
examples/app-showcase	24	3	4 (0 dotted)	38	0	0	0	0
examples/app-crm	6	1	0	0	0	0	0	0
examples/app-todo	1	1	0	0	0	0	0	0
platform-objects system_overview	53	1	1 (0 dotted)	9	0	0	2	2

Before/after on the corpus: 0 dashboard-filter findings, 0 dashboard-filter findings.
The false-positive budget is paid at zero. The platform stack's 2 findings are
chart-config-missing warnings on two widgets, identical on both sides and untouched by
this change (filed unassigned as #14436). The platform row is assembled rather than
imported — that package ships objects, datasets and the dashboard as separate exports
and no module composes them — so every export carrying name + fields was taken as an
object def.

CONTROLS — so a zero is a measurement, not a vacuous green. One shipped dashboard,
mutated, pushed through the same two calls; each control isolates one gap:

• Control 1 (gap 1). app-showcase › showcase_chart_gallery › kpi_total_tasks,
  its filter re-pointed at no_such_rel.no_such_col — BASE 0, HEAD 1
  (dashboard-filter-field-unknown), message: "…the effective field
  no_such_rel.no_such_col traverses no_such_rel, which is not a field on object
  showcase_task."
• Control 2 (gap 2). Same dashboard, showcase_task set to ownership: 'none' and
  the filter pointed at owner_id — BASE 0, HEAD 1
  (dashboard-filter-field-unknown).

Tests

packages/lint/src/validate-widget-bindings.test.ts, 24 new cases in four blocks plus
one rewrite:

• rewritten, not deleted — the case that pinned "a dotted path is skipped". Its
  block now states why: the assertion kept passing precisely because the rule had
  stopped asking the question. It asserts the head-hop miss is now named.
• gap 1: clean dotted path through a declared include; unknown hop (with the "did you
  mean"); unknown leaf, reported against the object the leaf lives on; a hop that is
  not a relationship; the explicit filterBindings wording; the false opt-out still
  silent; the injected-hop skip (owner_id.name is unknowable, not a miss); skip 2.
• the include clause: undeclared prefix errors; a bare base column needs no join; no
  double-report when the path also fails to resolve; the ADR-0021 implicit-prefix rule
  (account.owner includes account); not suppressible.
• gap 2: owner_id on ownership: 'none' reports, and the mutation twin (drop
  ownership) stays silent, so the test cannot pass for a rule that simply flags every
  injected column; the same pair for created_at under systemFields: { audit: false }.
• lint: view-filter / page-binding field checks resolve against the blanket SYSTEM_FIELDS union, so the #8116 unprovisioned-anchor warning cannot reach filter surfaces #8340: the anchor travels to the leaf's external object on a dotted path.
• acceptance: both new answers fail validate and build, and the clean shape
  passes both.

Verification (all at e685f7839, after the final commit)

what	command	reading
package suite	pnpm --filter @objectstack/lint test	93 files, 2805 tests passed
package typecheck	pnpm --filter @objectstack/lint run typecheck	exit 0
downstream consumer	pnpm --filter @objectstack/metadata-protocol exec vitest run src/protocol.runtime-authoring-gate.test.ts	1 file, 29 passed
shipped apps	pnpm --filter @objectstack/example-showcase --filter @objectstack/example-crm --filter @objectstack/example-todo test	26/364, 5/45, 4/106 — all passed
repo-wide lint	pnpm lint (eslint . --no-inline-config)	exit 0, whole repo, not narrowed
spec artifacts after merging main	pnpm --filter @objectstack/spec check:generated	All 15 generated artifacts are up to date
derived gate family	node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands	34 families
reconciliation	node scripts/pm/dispatch-gates.mjs --repo … --ran ran.list	34 derived, 34 run, 0 UNRUN

Every gate's exit code was captured by redirect before any pipe. 31 of 34 exit 0.
The other three are exit 3 = PREREQUISITE NOT MET = NOT MEASURED, never a pass and
never a finding — each says so in its own verdict text:

• node scripts/check-test-completeness.mjs — grades a saved turbo run test log; the
  family names it with no argument, and its own text says the local reading is NOT
  MEASURED.
• pnpm check:dual-build-cjs-loads — reads built output; six packages have no dist/
  without a full pnpm build.
• pnpm check:type-check-debt — --re-measure refuses without the whole workspace
  closure built, because measuring from here would measure a different world.

pnpm check:type-check-coverage (the sibling that does not re-measure) is exit 0.

One further NOT MEASURED, stated rather than glossed: @objectstack/lint's typecheck
program does not include *.test.ts — verified with tsc --noEmit --listFiles,
which lists validate-widget-bindings.ts and neither test file. That is this package's
pre-existing, ledgered TEST_DEBT (the coverage gate counts 16 such packages), not
something this PR introduced or is closing; the new tests are compiled and run by
vitest, and the suite is green.

main was merged into the branch before this reading, pnpm install --frozen-lockfile
re-run, and the packages/spec closure rebuilt, per the post-merge build-state rule.

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint, touching 2 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/lint/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

⛔ 2 release-owned page(s) name something this change touched. These are read-only:

• content/docs/releases/v16.mdx (via validateWidgetBindings (symbol, a top-level function))
• content/docs/releases/v17.mdx (via validateWidgetBindings (symbol, a top-level function))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/lint/src/index.ts) — pages documenting those are invisible to this run
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 5 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json bd8795ea1476e1b27cd8157ee95ea93aedb4e183 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from c2201f7f22e6c4106cad20acbc512c686857f76e — the merge of head e685f7839b747e24fc2bbd0e7eaf1da958df45ab into base bd8795ea1476e1b27cd8157ee95ea93aedb4e183, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin c2201f7f22e6c4106cad20acbc512c686857f76e && git checkout c2201f7f22e6c4106cad20acbc512c686857f76e
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin bd8795ea1476e1b27cd8157ee95ea93aedb4e183 e685f7839b747e24fc2bbd0e7eaf1da958df45ab && git checkout -B drift-repro bd8795ea1476e1b27cd8157ee95ea93aedb4e183 && git merge --no-ff e685f7839b747e24fc2bbd0e7eaf1da958df45ab

node scripts/docs-audit/affected-docs.mjs --json bd8795ea1476e1b27cd8157ee95ea93aedb4e183

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs bd8795ea1476e1b27cd8157ee95ea93aedb4e183 → pass the list as
args.docs, on the commit named under Which tree this was computed on.