docs(objectql): search-companion's $search sentence says $icontains, and the __search reader is named expandSearchToFilter

[os-musk]

Fixes #13984

Comment-only, zero behaviour. Two lines of packages/objectql/src/search-companion.ts change, plus a changeset. The two corrections are distinct claims and are listed separately, as triage asked.

1. The module docblock's operator spelling (:6)

The opening sentence read:

 * `$search` (ADR-0061 Tier 1) is a `$contains` over source columns, so typing

The source-column clauses compile to $icontains. Measured on this branch:

• packages/objectql/src/search-filter.ts:101 — fieldClausesForTerm, returning [{ [field]: { $icontains: term } }] at :109 (the enum raw-value fallback) and :111 (the textual path).
• The adjudication is in that file's own header at :23: [#7641] The case-insensitive operator is $icontains, NOT $contains.

Only the operator spelling changed. The argument the sentence carries is untouched and still holds: typing zhangwei cannot hit a stored 张伟 under EITHER operator, because case folding does not transliterate. It is a false spelling inside a correct argument, which is precisely why it read as fine and survived.

Every line number the card cites was verified against this tree with no drift: search-filter.ts:23, :109, :111, :137-143 are all exactly where the card puts them.

2. A stale identifier in the same docblock family (:286)

provisionSearchCompanion's docblock named the companion column's only reader buildSearchFilter. That is not an export of search-filter.ts, nor of anything else in the repo — git grep buildSearchFilter over packages and apps hits only this one line plus two frozen CHANGELOG copies of it. The reader is expandSearchToFilter, the name this same file already uses correctly 50 lines above at :236.

Deliberately NOT touched: two $contains in this file are CORRECT

Do NOT batch-replace this file — two $contains in it are CORRECT.

• search-companion.ts:237 — "ORed { __search: { $contains: term } } into every $search against it"
• search-companion.ts:286 — "which emits { __search: { $contains: term } }"

Both describe the hidden __search companion clause, where the case-SENSITIVE operator is the right spelling and is deliberate: the column is a normalized blob already lowercase on both sides, so $contains over two folded values is exact, not a case bug. search-filter.ts:137-143 says so in the imperative — "Do not 'align' the two." A naive whole-file find-and-replace here would turn two correct sentences false. Only :6 was wrong.

Verified after the edit: grep -c '__search: { $contains: term }' still returns 2, and grep -c 'buildSearchFilter' returns 0.

Measurement: does either correction reach dist/*.d.ts?

After pnpm --filter '@objectstack/objectql...' build, grepping all six emitted declaration files:

probe	core.d.ts / .d.mts	index.d.ts / .d.mts	util-C5RtxP_I.d.ts / .d.mts
correction 1 — "over source columns, so typing"	0	0	0
correction 1 — module docblock title "Search-normalization companion column"	0	0	0
correction 2 — "reader is expandSearchToFilter"	0	0	1
positive control — doc line of the exported SEARCH_COMPANION_FIELD	0	0	1
positive control — the exported name provisionSearchCompanion	1	1	13

The positive controls are what make the zeros readable: JSDoc attached to an exported declaration does reach the emitted declarations here, so a 0 on the module docblock is a real absence and not a broken grep.

• Correction 1 is ABSENT from every declaration file — a floating module-level block followed by an import is dropped by the declaration emitter, as the dispatch hypothesised.
• Correction 2 is PRESENT at packages/objectql/dist/util-C5RtxP_I.d.ts:1466 (and the .d.mts twin), because it sits inside the JSDoc of the exported provisionSearchCompanion.

Changeset decision, and a declared deviation

.changeset/search-companion-docblock.md — @objectstack/objectql patch. No skip-changeset label.

The dispatch's letter was: a patch changeset only if the MODULE docblock reaches dist/*.d.ts, else skip-changeset. The module docblock does not reach it. But the measurement turned up a fact that clause did not anticipate: correction 2 does reach the shipped declarations, so the npm tarball's bytes change and a consumer's editor hover on provisionSearchCompanion stops naming a function that does not exist. The skip-changeset criterion is "publishes nothing from any package", which this diff fails. The precedent is .changeset/action-execute-ledger-dead.md, a data-only patch changeset taken for exactly this reason: "these ledgers ship in the npm tarball and this is published data."

Taking the changeset is also the safe direction — it is additive, whereas applying skip-changeset to a diff that does change published bytes would silence a gate that ought to speak. Raised here as an explicit deviation from the letter of the dispatch clause rather than taken silently.

Clause-②: no

Read from my own diff rather than from the dispatch: both changed lines sit inside /** ... */ comment blocks. No accept/reject behaviour, no schema, no public type, no gate moves. The emitted declaration's doc text changes at util-C5RtxP_I.d.ts:1466; the declared types are byte-identical.

The same correction campaign covers three surfaces, on three separate cards

Named here so the three do not drift into three different wordings. Both of the others remain open, keep their own review path, and are untouched by this branch, which edits one file.

• [finding] engine.ts ADR-0061 docblock still describes search expansion as $or of $contains — the implementation and its own neighbor file say $icontains #13744 — packages/objectql/src/engine.ts, the origin card this finding was filed from.
• [finding] The published docs still describe the ADR-0061 search expansion as $or of $contains in six places — and one of them tells the reader the case-insensitivity question is "still open" when #7641 closed it #13988 — the content/docs/** sites plus the spec .describe() generation source. That one reaches packages/spec and therefore lights Clause-②; this one does not.

Verification

Everything below ran on ced1f11cf (git rev-parse --short HEAD, taken after the final commit).

The gate union was re-derived on this final tree, not taken from the dispatch seed: node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands at commit ced1f11cf returned 30 commands over the 2-file change set. All 30 ran, plus pnpm check:adr-anchors (named by the dispatch but not in the derived union), plus the always-runs. Every exit code was captured after a redirect to a file, never through a pipe.

Green — 27 of the 30 derived, and every always-run:

• pnpm lint (whole repo, eslint . --no-inline-config) — exit 0, no findings. Not narrowed: the full repo scan ran.
• pnpm check:nul-bytes — "check-nul-bytes: OK (scanned 7967 text file(s) ... no raw ASCII control bytes)."
• pnpm check:error-status-conformance — "every derivable runtime status is documented, and every documented status is reachable."
• pnpm --filter @objectstack/objectql typecheck — exit 0, and it carries check:test-typecheck: "OK — @objectstack/objectql's test layer compiles under packages/objectql/tsconfig.test.json". So the test layer is measured, not excluded.
• The two [#7641] pins — pnpm --filter @objectstack/objectql exec vitest run --maxWorkers=2 src/search-filter.test.ts src/global-search-palette-recall.test.ts → "Test Files 2 passed (2) / Tests 28 passed (28)". The two named pin titles live in those files at search-filter.test.ts:140 and global-search-palette-recall.test.ts:352.
• pnpm check:adr-anchors — "check-adr-anchors: OK (53 anchored file(s), every governing ADR still referenced ...)". scripts/adr-anchors/packages__objectql__src__search-companion.ts.json still anchors ADR-0015 / ADR-0045 / ADR-0061 and the correction touched no ADR id, as the card predicted.
• The other 26 derived gates all exit 0, including check-empty-changeset, check-changeset-no-major, check:doc-authoring, check:published-files and check:test-source-alias.

NOT MEASURED — 3 of the derived 30 exited 3. In each gate's own words this is neither green nor red:

• node scripts/check-test-completeness.mjs — "the local reading for this gate is NOT MEASURED. It is not a red, and there is nothing here to fix." It needs a saved turbo run test log, which CI tees in on every invocation.
• node scripts/pm/check-half-states.mjs — "Nothing was swept ... it is no reading at all." It needs repo-scoped REST reads, and those answer 403 in this container.
• pnpm check:dual-build-cjs-loads — "PREREQUISITE NOT MET — this gate reads built output, and some package has no dist/ ... This is NOT a pass: nothing was measured." I built only @objectstack/objectql and its dependency closure; the gate wants a whole-repo pnpm build, which CI performs. A comment-only diff cannot move CJS load behaviour.

No ablation is owed. The diff is comment-only: there is no guard to delete and no assertion whose failure could be demonstrated.

Heavy runs (the build, the pin tests) went through scripts/pm/os-verify-lock.sh; both printed VERDICT command-exit 0.

🤖 Generated with Claude Code

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 1 changed file(s) yielded no anchor (packages/objectql/src/search-companion.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/objectql/src/search-companion.ts) — pages documenting those are invisible to this run
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 16 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 7085f90531e9ab7c9fe07b758287d7dfbe1549b3 → packageMentionDocs.

[os-musk]

Landing provenance (engine execution seat, session_0112hMx9hjJ9BgB28X97DS68) — flipped to ready at 14:36Z and auto-merge (squash) armed at 14:36:56Z on head ced1f11cf.

• ACCEPT on the card: [finding] search-companion.ts docblock calls the ADR-0061 $search expansion "a $contains over source columns" — source columns compile to $icontains #13984 (comment 5510866525).
• Pre-landing checks at flip time: every check run on ced1f11cf completed with conclusion success or skipped (33 runs, perPage: 50; Lint & Repo Gates success at 14:27:59Z, all Type Check jobs success); node scripts/pm/check-governed-merges.mjs --test on the PR's 2 changed paths: 0 of 2 hit the register — not governed.
• Clause-② self-reading no, concurred at ACCEPT: two comment lines; declared types byte-identical; @objectstack/objectql: patch because the second correction ships in the published declarations (measured). No needs:contract-review carrier.
• Closing keyword: Fixes #13984 only; the card closes at MERGED and its pm:dispatched is stripped in the landing record.

---

Generated by Claude Code