Observation-class docs gap, recorded while implementing #7057 (the cursor / distinct / WriteObservabilityOptions alignment on the same page). Filed unassigned — recording only, no ownership taken. Deliberately NOT fixed in #7057's PR: that card's dispatch scoped the surface to the three ruled divergences, and this is a fourth of a different class (an omission, not a retired key still documented).
The gap
content/docs/kernel/contracts/data-engine.mdx opens its EngineQueryOptions code block with "Defined by EngineQueryOptionsSchema in @objectstack/spec", then lists every member of that schema except searchFields.
searchFields is a real, declared, enforced option — packages/spec/src/data/data-engine.zod.ts (verified on origin/main @ 5087ac6):
searchFields: z.array(z.string()).optional(),
Its own doc comment records that it was "enforced but undeclared until #4371 (option 2) made the engine reject undeclared option keys" — so it has been a first-class authorable key since that change. The generated reference page already carries it (content/docs/references/data/data-engine.mdx, ## EngineQueryOptions table); only the hand-written contract page is missing it.
Why observation-class, not a defect
Nobody following this page breaks: the omission costs a reader knowledge of one option, it does not make them write something the schema rejects. That is the opposite direction from #7057's ruled divergences, which documented keys the schema now refuses by name. Grading left to triage.
Fix sketch
One line in the code block, alongside search, e.g.
searchFields?: string[]; — fields the search expansion may match against, intersected with the object's declared/derived searchable set (ADR-0061).
Refs: #7057 (the card this was found under), #4371 (the change that made the key declared), ADR-0061.
Generated by Claude Code
Observation-class docs gap, recorded while implementing #7057 (the
cursor/distinct/WriteObservabilityOptionsalignment on the same page). Filed unassigned — recording only, no ownership taken. Deliberately NOT fixed in #7057's PR: that card's dispatch scoped the surface to the three ruled divergences, and this is a fourth of a different class (an omission, not a retired key still documented).The gap
content/docs/kernel/contracts/data-engine.mdxopens itsEngineQueryOptionscode block with "Defined byEngineQueryOptionsSchemain@objectstack/spec", then lists every member of that schema exceptsearchFields.searchFieldsis a real, declared, enforced option —packages/spec/src/data/data-engine.zod.ts(verified onorigin/main@5087ac6):Its own doc comment records that it was "enforced but undeclared until #4371 (option 2) made the engine reject undeclared option keys" — so it has been a first-class authorable key since that change. The generated reference page already carries it (
content/docs/references/data/data-engine.mdx,## EngineQueryOptionstable); only the hand-written contract page is missing it.Why observation-class, not a defect
Nobody following this page breaks: the omission costs a reader knowledge of one option, it does not make them write something the schema rejects. That is the opposite direction from #7057's ruled divergences, which documented keys the schema now refuses by name. Grading left to triage.
Fix sketch
One line in the code block, alongside
search, e.g.searchFields?: string[];— fields thesearchexpansion may match against, intersected with the object's declared/derived searchable set (ADR-0061).Refs: #7057 (the card this was found under), #4371 (the change that made the key declared), ADR-0061.
Generated by Claude Code