fix(lint): searchable-fields hints prescribe a stored field, not formula (#6673)

[os-project-manager]

Fixes#6673

What changed

Both authoring-time hints for a bad searchableFields entry prescribed mirroring a related record's value onto a formula field — a fix that can never work: a formula field is virtual (no driver materializes a column for it — packages/objectql/src/engine.ts, driver-sql/src/schema-drift.ts, driver-turso/src/remote-transport.ts), so a $contains predicate against one has nothing to scan, and a CEL formula only reads the record's own fields (record.<field>), so it cannot fetch the related title in the first place.

packages/lint/src/validate-searchable-fields.ts:

• :347 (dotted-path entry, searchable-field-unknown): "…or copy the value onto a formula field here." → "…or copy the value onto a stored text field here."
• :414 (a lookup/master_detail column outside the allowed set, searchable-field-unsearchable): "…mirror it onto a text/formula field here…" → "…mirror it onto a stored text field here…"

This matches the prescription already shipped in content/docs/data-modeling/schema-design.mdx and the objectstack-data / objectstack-ui skills (PR #6670, #6898) — the tool's own hint text now agrees with the corpus that quotes it.

Pinned tests in validate-searchable-fields.test.ts were strengthened to assert the new wording and reject "formula". Reverse-verified: reverting either string to the old wording turns both tests red (confirmed locally before restoring the fix).

Scope note — the third string does not exist where the issue described it

The issue also named a third target: packages/metadata-protocol/src/protocol.ts:4780, described as "the runtime dotted-path hint in assertSearchFieldsAreSearchable", currently reading "a formula or rollup field".

I verified this against origin/main and it does not hold up:

• assertSearchFieldsAreSearchable (protocol.ts:4978, the #4254 SEARCH-FIELDS ingress gate) has no formula/rollup prescription at all — its dotted-path hint only says "'search' scans this object's own columns; a related record's column cannot be a search target." (protocol.ts:5056). git log -S "formula" -- packages/metadata-protocol/src/protocol.ts shows the string "formula" was never present in this function, in the file's entire history.
• The text at :4780 ("Denormalise the value onto '${object}' (a formula or rollup field that copies it into a real column) and sort by that.") actually lives in assertSortFieldsExist (protocol.ts:4745) — the SORT axis, #4226/#4256, an unrelated code path guarding ?sort=/orderBy, not searchableFields.
• That SORT hint is not a stray leftover: it's the deliberate recommendation #4256 (same author, closed completed) asked for and got, and it is still consistent with its own, still-current documentation (content/docs/protocol/objectql/query-syntax.mdx:533-534, "Denormalise the value onto the queried object (for example with a formula or rollup field) when you need to sort by it."). Docs and code agree there today — there is no docs-vs-tool contradiction on the SORT axis, unlike the searchableFields case this issue is about.
• Its pinned message test lives in a third package (packages/objectql/src/query-expression-conformance.test.ts:455), outside both packages this card named.

So this PR only touches the two packages/lint strings, which are exactly as described and now fixed. I'm leaving protocol.ts untouched — filing the (possibly real, but separate and cross-domain) SORT-axis question as its own finding for triage rather than guessing at it here. Details in my report to the dispatching PM.

Tests

• pnpm exec vitest run src/validate-searchable-fields.test.ts (packages/lint) — 33/33 pass.
• pnpm exec vitest run (packages/lint, full suite) — 1762 passed, 4 skipped.
• pnpm --filter lint typecheck — clean.
• pnpm exec eslint packages/lint/src/validate-searchable-fields.ts packages/lint/src/validate-searchable-fields.test.ts --no-inline-config — clean.
• node scripts/check-nul-bytes.mjs — OK.
• Reverse-verification: reverted both strings to "formula" wording → both new assertions failed red as expected; restored → green again (rebuilt-from-src, no stale dist/).

Changeset

Added .changeset/searchable-fields-stored-hint.md (patch, @objectstack/lint) — message-text-only fix to a published package's diagnostic output; matches this repo's own precedent for wording-only diagnostic fixes (e.g. .changeset/fault-edge-tombstone-type.md, .changeset/org-axis-dead-alias-branches.md).

---

Generated by 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		Aug 9, 2026 4:21am

[github-actions]

📓 Docs Drift Check

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

3 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)
• content/docs/releases/v17.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.