Repository navigation
docs: data-engine.mdx EngineQueryOptions block omits searchFields, declared on the schema since #4371 #7170
Description
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
Activity
docs(kernel): the hand-written IDataEngine contract page shows search…
os-help commentedon Aug 10, 2026
Claim: PM loop round 7 —
domain:spec-toolingseat (#6018)Session:
session_01KJATVrh6V2ysutYUJigh3BBranch:
claude/issue-7170-data-engine-searchfieldsWorktree:
objectstack-issue-7170File surface:
content/docs/kernel/contracts/data-engine.mdxonly (one line in theEngineQueryOptionsblock). Stop on breach; explain in the report.This card was filed by this lane's own dev under #7057 and deliberately left out of that PR as a fourth divergence of a different class; triage has since graded it and returned it to
pm:queue. Same page as the merged #7173, so the lane has per-path familiarity — which is exactly why the dispatch pins re-reading rather than reusing it.Premise re-verified live on
origin/mainbefore claiming:searchFieldsis still declared —packages/spec/src/data/data-engine.zod.ts:149,searchFields: z.array(z.string()).optional(). The card's premise holds.merge=os-regencontent/docs/references/**tree), so the edit is not regenerated away.8b06bba84(EngineQueryOptionsSchema.searchrejects the bare query string that ADR-0061 D1 calls canonical — so every engine caller that wants it mustas any, losing the whole query's checking #7178 → PR fix(spec):EngineQueryOptionsSchema.searchaccepts the canonical bare query string (#7178) #7249) landed after our docs(kernel): align data-engine contract page with the shipped engine seam (#7057) #7173 and changedEngineQueryOptionsSchema.searchto accept the canonical bare query string — i.e. it edited the neighbouring line this addition sits next to. The card's line anchors are from before that commit. Anchor on text, never on line numbers, and re-read the block live; the siblingsearchprose may already say something the new line must agree with rather than contradict.sonnet— mechanical S-card: one line, in a block whose content is already independently pinned by the generated reference page (content/docs/references/data/data-engine.mdx,## EngineQueryOptionstable), which the dev should diff the hand-written block against rather than trusting the card's suggested wording.Generated by Claude Code
fix(spec): `EngineQueryOptionsSchema.search` accepts the canonical ba…
docs(data-engine): add searchFields to EngineQueryOptions block (obje…