feat(lint): catch a stale searchableFields entry at authoring time (#4254 follow-up)

[os-zhuang]

The gap

searchableFields is z.array(z.string()) in both object.zod.ts (ADR-0061) and the list-view schema, so nothing checked that an entry names a field that exists. Rename a field and the old name stays behind: Zod-valid, shipped, pointing at a column that is gone.

The engine tolerates it, which is exactly what kept the drift invisible — resolveSearchFields filters the declaration down to fields that exist (searchableFields?.filter((f) => all[f])) and says nothing. The tolerance fails in the direction nobody expects:

• some entries stale → $search scans a narrower set than the object declares. Records that should match do not, and the response is indistinguishable from "no such record".
• every entry stale → the filtered set is empty, so resolution falls through to the auto-default (name/title + short-text). A declaration whose whole purpose is to choose the searchable set ends up selecting one the author never wrote — the "asked narrower, answered wider" inversion REST 列表：sort / select / expand 指向不存在的字段时被静默丢弃（filter 轴已收口，这三条轴还没有） #4226 closed on the projection axis.

And it stops being quiet downstream. Clients echo the declaration verbatim as the $searchFields override (objectui's list search sends schema.searchableFields), so once the REST read path validates that override against the object (#4254), a stale entry the engine had been silently skipping becomes a 400 INVALID_FIELD on every list search for that object — a request-time break whose cause is an authoring typo made long before.

The rule

searchable-field-unknown, appended to REFERENCE_INTEGRITY_RULES — so it reaches os validate, os lint and os compile with no CLI edit, the wiring contract that suite exists to provide. It covers the object's own declaration and the list views that narrow it (objects[].listViews, a defineView default list, named listViews), resolving each entry against the bound object's declared fields.

Gating (error), unlike the advisory field-existence rules. page-field-unknown / form-field-unknown / semantic-role-field-unknown are warnings because they describe a consumer that skips an unknown name and renders the rest. This one describes a declaration that either selects the wrong set or refuses the request outright — the same call validate-flow-template-paths makes for a filter-position token, where the miss widens the query instead of shrinking the page.

Existence only. A field that exists but is an odd search target (a json column) is not flagged: an explicit searchableFields is authoritative — the engine scans exactly what it names — so declaring one is a choice, not drift.

Three skips keep false positives near zero (ADR-0072 D1 — one dead finding and authors stop trusting the linter): an object this stack does not define (may come from another package), an object with no authored field map (external / datasource-introspected), and registry-injected system columns. That last set is derived from the spec's own FIELD_GROUP_SYSTEM_FIELDS + SystemFieldName rather than hand-copied — this package already carries five slightly-different copies of that list, which is #3786's lesson going unlearned. (Converging the existing five is a separate cleanup, not folded in here.)

Dotted paths are flagged, unlike in every sibling rule. They skip owner_id.name because the query engine resolves the traversal; search does not — resolveSearchFields matches the field map by exact string, so a dotted entry is dropped exactly like a typo, and it is the spelling most likely borrowed from select/sort. It gets its own fix hint.

Verification

• packages/lint — 38 files / 564 tests green, including 22 new cases: the stale entry, a clean control, the legacy array field map, each skip, the dotted path, and one per list-view surface. Severity is pinned, since a silent downgrade to warning would make os validate exit 0.
• packages/cli — 64 files / 628 tests green (it consumes the suite).
• Against real shipped metadata: os validate passes on showcase (23 objects / 202 fields), crm and todo — no false positive. Injecting email into the showcase account object's declaration fails it with the precise path and exit 1:

✗ Reference integrity check failed (1 issue)
  • object "showcase_account": searchableFields entry "email" is not a field on object "showcase_account". …
      rule: searchable-field-unknown  at objects[0].searchableFields[3]

• main merged in and the full suite re-run afterwards (Multi-agent discipline chore: version packages #10) — the merge moved packages/lint/package.json and spec/src/data, so this was re-verified on the rebuilt tree, not the pre-merge one.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Jul 31, 2026 6:17am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/lint.

2 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/automation/hook-bodies.mdx (via @objectstack/lint)
• content/docs/permissions/authorization.mdx (via @objectstack/lint)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.

[os-zhuang]

Two out-of-scope gaps noticed while writing this rule, filed rather than folded in (Prime Directive #10):

• lint: <ListView searchableFields> on a React page is not checked against the object's fields #4329 — <ListView searchableFields> on a React page is the same drift class on a surface this rule does not reach. No live instance is broken today; the one in the showcase is clean.
• lint: five hand-copied SYSTEM_FIELDS lists in packages/lint should derive from the spec's declarations #4330 — the five hand-copied SYSTEM_FIELDS lists in this package. This PR deliberately derives from the spec's FIELD_GROUP_SYSTEM_FIELDS + SystemFieldName instead of adding a sixth; converging the existing five needs a decision about validate-flow-template-paths' extra names (name, owner, record_type), which is not a mechanical merge.