docs(ui): the searchableFields boundary is allowed-set membership, not field type (#6897)

[os-project-manager]

Fixes#6897

Premise: valid, and re-measured rather than trusted

The card was filed ~1h before dispatch, so I re-measured both directions from scratch at
both layers before touching prose — the dispatch order and the card body were treated
as leads, not as the record.

content/docs/ui/views.mdx:106 (landed by PR #6670) said:

Entries must be the object's own columns: a lookup (project_id) or a dotted path
(project_id.name) is refused, and every toolbar search on the list then returns
400 INVALID_FIELD (#4254)

The dotted-path half is correct. The lookup half is false, and it is false in a way that
is self-contradictory in its own terms: a lookup is one of the object's own columns.
The real boundary is membership in the object's server-resolved allowed set
(resolveSearchFieldResolution, packages/spec/src/data/search-fields.ts:119), whose
declared branch is searchableFields?.filter((f) => all[f]) — filtered by existence,
never by type. The type lists (SEARCHABLE_TEXTUAL_TYPES / SEARCHABLE_ENUM_TYPES) are
reached only from autoDefaultFields, i.e. the no-declaration branch.

Why it matters, concretely: an author following the old row would delete a narrowing
that works, and an AI author would refuse to emit one.

Measured — the REAL ingress gate, four directions

Object support_case declaring searchableFields: ['subject', 'account_id'] where
account_id is { type: 'lookup', reference: 'crm_account' }, plus a twin open_case
with the identical field map and no declaration. Driven through a real ObjectQL
engine and ObjectStackProtocolImplementation.findData (so
assertSearchFieldsAreSearchable really runs), with two rows planted so the term lives in
exactly one column each — c1 carries it only in the lookup, c2 only in the text column
the object left out. That planting is what makes "accepted" mean scanned rather than
merely not thrown.

direction	request	result
A declared LOOKUP	searchFields: ['account_id'] on support_case	ACCEPTED, and really scanned — returned exactly ['c1']
B TEXT outside the set	searchFields: ['account_name'] on support_case	REFUSED — status: 400, code: 'INVALID_FIELD', field: 'account_name'
C mirror image, no declaration	same two names on open_case	text accepted (returned ['c2']), lookup refused by TYPE
D dotted path	searchFields: ['account_id.name']	REFUSED on both branches — the old row's correct half

A and B are the pair the card names: a text column refused and a lookup accepted on
the same object, which no type-based reading can produce. C is what makes A and B mean
something rather than read as a coincidence — it shows the type list is real, just
reachable only from the other branch.

The two verbatim runtime messages, which are themselves the boundary stated twice:

Field 'account_name' on object 'support_case' is not searchable. The object declares
'searchableFields' (subject, account_id), which is the set 'search' scans — a field
outside it cannot be a search target until it is added there.
Field 'account_id' on object 'open_case' is not searchable. With no 'searchableFields'
declared, 'search' scans the text-like columns (text / email / phone / url / autonumber /
textarea / markdown / select / status), and 'account_id' is type 'lookup'. Declare
'searchableFields' on the object to choose the searchable set explicitly.

Lint layer, re-run rather than trusted — the "SKILL.md parity (#6675)" block landed by the
merged PR #6898, including the two directions above:

✓ objectstack-ui SKILL.md parity (#6675) > a lookup INSIDE the object's declared set is
accepted; a text column OUTSIDE it is not
✓ objectstack-ui SKILL.md parity (#6675) > with no object declaration, the auto-default
type list decides
✓ objectstack-ui SKILL.md parity (#6675) > `searchableFields: []` is ABSENT, not
"search off" — it resolves to the FULL allowed set
Test Files 1 passed (1) Tests 33 passed (33)

The measurement harness was a scratch file, run in the foreground and deleted before the
commit; git status is clean apart from the one edited page.

What changed — one file, content/docs/ui/views.mdx

1. The searchableFields row now states the rule as set membership and stops
   prescribing against a supported configuration. It also gets shorter: the cell was
   already the longest in the table, and the correct rule needs a two-row table to state
   honestly, so the cell links down instead of trying to carry it.
2. A new ### Toolbar search (searchableFields) section, immediately after the
   properties table. The dispatch asked whether the surrounding prose repeats the same
   type-first error — on this page it does not; line 106 was the only occurrence. But a
   corrected one-line cell would still have left the page teaching nothing about which
   set is meant, which is the mental model the card says is the real damage. The section
   carries: the allowed-set table (declared vs auto-default), the both-directions sentence
   (declared lookup accepted / outside-text refused), the dotted-path clause with the
   stored-mirror link preserved, a warn callout for the one-bad-entry blast radius, and
   the os validate / runtime verdict table.

Terminology deliberately mirrorsskills/objectstack-ui/SKILL.md → "Toolbar Search
(searchableFields, ADR-0061)" (merged PR #6898, #6675) so the docs corpus and the skills
corpus say the same thing in the same words. Both intra-repo anchors were computed with
the repo's own github-slugger@2.0.0 rather than guessed
(#toolbar-search-searchablefields, #global-search--searchable--searchablefields), with
the two already-linked headings on the page used as controls.

On "reverse verification" — reported straight, not template-shaped

There is no direction in which restoring the old prose turns a test red: documentation
sentences are not asserted by anything in this repo, so manufacturing a before-red /
after-green artifact here would be a fabrication that reads as verification.

The evidence that carries this change is the opposite move and it is real: the old row's
claim, executed against the harness above, is falsified by direction A — the request
the row says returns 400 INVALID_FIELD returns rows instead, and returns exactly the row
whose term lives only in the lookup column.

Sibling pages: checked, all already correct

The card asked to check the pages landed by the same PR before editing. Each states the
set-membership rule already, so none needed a change and none is touched:

• content/docs/data-modeling/schema-design.mdx:134,143 — "If the object declares no
  searchableFields at all…"; "searchableFields admits any field the object declares".
• content/docs/api/data-api.mdx:27,144 — "its declared searchableFields, or a
  text-like auto-default when none are declared"; the three-causes split.
• content/docs/protocol/objectql/query-syntax.mdx:862 and
  content/docs/data-modeling/queries.mdx:508 — same phrasing.

The type-first error was unique to views.mdx:106.

Gates (foreground, inside the shared verification lock)

pnpm lint exit 0, no output
check:doc-authoring ✓ self-test + 374 files clean — no bare metadata literals
check:docs-audit-scope ✓ 32 + 22 self-test cases; 179 hand-written doc(s) in sync
check:nul-bytes ✓ self-test 56 assertions; OK (6420 tracked text files)
check:adr-links ✓ 531 relative link destination(s) resolve
check:role-word OK (44 baselined file(s), no new occurrences)
check:quick-reference-counts ✓ 13 section(s) match their tables
check:skill-examples ✅ 208 prose examples type-check against @objectstack/spec

check:skill-examples covers this page's four os:check blocks
(content/docs/ui/views.mdx:16 / 172 / 404 / 438 — the last three shifted by the
insertion); all four still type-check. fumadocs-mdx regenerates the page cleanly, so the
new callout and tables parse. Control-byte self-scan beyond the gate:
grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]' content/docs/ui/views.mdx — no hits.

Docs Drift Check does not fire here: it triggers on packages/**, and this PR touches
none.

Scope — deliberately not done

• skills/objectstack-ui/SKILL.md untouched. It is the source of truth as of PR
  docs(skills): objectstack-ui 补 searchableFields 章节 —— 工具栏搜索的收窄语义与失败边界 (#6675) #6898; this PR brings the docs page into agreement with it, never the reverse.
• packages/lint/src/validate-searchable-fields.ts and
  packages/metadata-protocol/src/protocol.ts untouched — that is The searchable-fields hints prescribe a "text/formula" mirror — the formula half never works, so the tool output now contradicts the docs that quote it #6673 (the hint
  strings that prescribe a formula mirror), dispatched in parallel. I read both while
  measuring and have no correction to add to that card.
• No docs/adr/ changes, no content/docs/releases/ changes.
• content/docs/ is a domain-boundary-contested path (域标签词表有两个未入表条目:domain:spec-tooling(在用,文件面与 devx 完全重叠)与 domain:ui(一例,与 repo:objectui 重复) #5469, unruled — the
  domain:spec-tooling seat also lands here). The diff is deliberately one file and one
  section; nothing outside content/docs/ui/views.mdx is touched.
• No changeset: content/docs/-only prose, releasing no package — skip-changeset
  applied by hand, following the precedent of PR docs(protocol): preserveAudit 的 readonly 白名单只在 UPDATE 半边成立 —— state-machine.mdx 的 create 半边旧说法 (#6827) #6880 (also docs-only, also labelled by
  the authoring agent).

---

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:22am