fix(spec): $like / $ilike _ is one Unicode code point on every JS face - #20222

📓 Docs Drift Check

5 anchor(s) derived from 2 changed package(s); no hand-written page names any of them. ⚠️ 2 changed file(s) yielded no anchor (packages/spec/api-surface/data.json, packages/spec/export-origins/data.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin ef8deacbdac297ee94797aea951836bfc11c69c5 && git checkout ef8deacbdac297ee94797aea951836bfc11c69c5
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 805af4f290565955d6e6b56ee46fed45f721d955 713d1504d6e9c710c94dae8efaeda953e478b932 && git checkout -B drift-repro 805af4f290565955d6e6b56ee46fed45f721d955 && git merge --no-ff 713d1504d6e9c710c94dae8efaeda953e478b932

node scripts/docs-audit/affected-docs.mjs --json 805af4f290565955d6e6b56ee46fed45f721d955

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 713d1504d6e9c710c94dae8efaeda953e478b932

① Derived judgments

• u is safe for every pattern the translation can emit — RIGHT. Read at head: likePatternToRegexSource (packages/spec/src/data/filter.zod.ts:1365-1402) emits only ^, $, [\s\S]*, [\s\S], [Xx] (the foldAscii fold, ASCII letters only), \ + one of \ ^ $ . * + ? ( ) [ ] { } | / (the regex at :1399), or the input unit bare. That escape set is exactly the u-mode identity-escape set (SyntaxCharacter plus /), and the three characters u refuses bare (], {, }) are in it. asciiCaseInsensitiveRegexSource is not on the $like path (it serves $icontains); the $ilike fold is the inline [Aa] class. Executed (review/probe-u-flag.out, tsx over the head's TS source): 1320 patterns × 2 folds — every code unit 0x00–0xFF bare, escaped, mid-pattern and doubled; lone high and low surrogates; escaped 😀; regex-meta shapes ({2}, (?, [a-z], \d, \p{L}, \1, \k …) — 0 newly refused under u, 0 newly accepted, 2636 compile under both, 0 throw under both (4 dangling-escape shapes skipped, refused at every door before compile). The changeset's "No pattern is newly refused" holds; no new 500 or undeclared refusal at a request door. Formula would have masked a new throw anyway (packages/formula/src/matches-filter.ts:374-379 catches and answers false); driver-memory's doors would not — and there is nothing to mask.
• Every JS face compiles through u — RIGHT, census done on the head. Non-test git grep under packages/**: likePatternToRegexSource has no caller outside filter.zod.ts (only CHANGELOG/generated mentions); likePatternToRegExp is called at memory-driver.ts:1399 ($like/$ilike door) and :1647 (AST like/ilike door) and by matchesLikePattern (filter.zod.ts:1430); matchesLikePattern is called by memory-matcher.ts:640 (reference matcher) and formula/src/matches-filter.ts:377. No new RegExp( in driver/formula/spec sources touches a like source (the remaining sites are escapeRegex and $icontains). memory-analytics.ts:373 hands a $contains substring (with %/_ escaped) to GLOB, so no _ wildcard reaches it. The built dist/ carries "u" in all four builds (data/index.{js,mjs}, browser/data/index.{js,mjs} at :1069-1072) and no flagless compile of the like source. objectui (/home/user/objectui, HEAD 5c61e524 and the pinned .objectui-sha f8a9d0fb): 0 hits for the three symbols (control grep hits); its only $like mention, packages/core/src/adapters/ValueDataSource.ts:642, documents that the matcher refuses $like/$ilike ("no pattern engine"). Not a missed site; out of this PR's scope.
• Each changed published sentence — RIGHT on every measured face; see ③ for the MySQL arm. LIKE_DESCRIPTION is bound at filter.zod.ts:1145 and :1612 (both copies) and the generated content/docs/references/data/filter.mdx carries the new sentence in all four $like rows; the dist shared/index.js carries the string. The built .d.ts (packages/spec/dist/filter.zod-D7MYdk7G.d.ts:230-252) declares likePatternToRegExp and holds every new docblock phrase ("The source means this ONLY under the u flag", "never hand this source", "exactly the identity escapes u", "No i flag, ever", the GLOB-table row). The changeset table was re-derived through matchesLikePattern against a flagless compile of the same source: _ on 😀 false→true; __ on 😀 true→false; a_b on a😀b false→true; a__b on a😀b true→false and on a😀😀b false→true; the $ilike twin identical — exactly the table, nothing else in it moved. The SQLite faces already counted code points: likePatternToGlobPattern maps _ to GLOB ? (filter.zod.ts:1502); driver-sql reaches it via likePatternPredicate → sqliteLikePatternMatch → sqliteLikePatternPlan (sql-driver.ts:3800, :3824, :3941-3946); SqliteWasmDriver extends SqlDriver (sqlite-wasm-driver.ts:67) and inherits it; driver-turso remote calls it at remote-transport.ts:3449 and :3491, local inherits SqlDriver. The new driver tests pin real engine answers, not parity alone: better-sqlite3 :memory: (driver-sql), sql.js :memory: (sqlite-wasm), and three turso transports (libsql local :memory:, the better-sqlite3 stub, and a real @libsql/client file::memory:), each asserting literal code-point row sets per family cell plus a hex(v) storage premise and one cross-face leg.
• % under u — RIGHT, no undeclared movement class. Movement census (probe-u-flag.out §4, 28 patterns × 2 folds × 32 values): BMP-only values (x, ab, a\nb, é, 中文, �, NUL, %, _, \) — 0 cells moved; well-formed-pair values — 62 cells moved, all of them either the family cells or a pattern holding a lone surrogate against a value holding a pair (e.g. % + U+DE00 on 😀 true→false), which the PR pins; values holding ONLY lone surrogates (\uD83D, \uDE00, a\uD83Db, U+DE00 U+D83D …) — 0 cells moved; the 24 lone-surrogate cells that moved all hold a well-formed pair in the value. So "values made only of characters inside the BMP answer exactly as before" holds even counting a lone surrogate as a BMP code point, and every moved cell is inside the changeset's "only for values holding a character outside the BMP" clause. [\s\S]* never splits a pair under u (% + lone low surrogate on 😀 is false; flagless it was true).
• memory-driver.ts — RIGHT. Both doors pass the same fold as before: canonical === 'ilike' at :1399 and op === '$ilike' at :1647, unchanged from the removed lines. mingo 7.2.4 (node_modules/.pnpm/mingo@7.2.4): normalize() (esm/util/_internal.js:474-484) rebuilds $regex as new RegExp(expr.$regex, expr.$options); with no $options the second argument is undefined, which the RegExp constructor reads as "keep the pattern's own flags" — proved in node: flags stay "u" and test('😀') is true, whereas a string $options (even '') would clobber the flag to "" and answer false. The predicate itself calls b.exec(x) on that object (esm/operators/_predicates.js:101-105). The driver passes no $options on either door. End to end: memory-20143-like-code-point.test.ts asserts literal code-point rows on find() through the $ door, find() through the AST door and match() on the reference matcher — 11/11 green in my worktree. The reference matcher (memory-matcher.ts:640) goes through matchesLikePattern, so all three doors share the one compilation.
• Tests — RIGHT, substantive. Every new suite asserts the NEW row sets per face against literal rows (FAMILY tables of 10 cells over 9 values, per face), not merely the absence of old assertions; the spec suite also keeps the flagless reading as a control and asserts each control cell differs from its code-point cell. Re-run here in a detached worktree at the head (/home/user/objectstack-review-20222, removed afterwards): spec 23/23, formula 12/12, driver-memory 11/11 from TS source; driver-sql 12/12 on better-sqlite3, driver-sqlite-wasm 12/12 on sql.js, driver-turso 12/12 on libsql local, the better-sqlite3 stub and a real @libsql/client file::memory: engine (after building the spec, formula, types, core, metadata-core, observability, refd-timer-testkit and driver-sql dists those suites resolve through). No existing test file is modified or deleted (diff vs merge base 585c9af5: 12 files, +779/−21, all deletions inside filter.zod.ts and memory-driver.ts). git grep on origin/main for astral characters (😀, fromCodePoint(0x1f…), \uD83D, surrogate) in spec/formula/driver test files near like: none; the only __ pins (*-20024-like-stored-nul.test.ts) hold BMP-only rows (ab, eu, NUL shapes), so no UTF-16 pin was flipped silently and the 20024 grids' matchesLikePattern oracle answers as before. CI at head: 34 success / 5 skipped / 0 failing, complete; the Lint & Repo Gates job that hosts the seven locally NOT-MEASURED gates is green.

② Semver level

• minor on spec, formula, driver-memory — RIGHT for this repo. All six packages are 17.4.0, published, in the one Changesets fixed group of 69; no .changeset/pre.json. scripts/check-changeset-no-major.mjs (header, "LAUNCH-WINDOW GUARD") refuses major until GA: "During the launch window we ship breaking changes as minor", breaking-ness carried by the body's declaration plus the ADR-0087 disposition, "not by the level". AGENTS.md :1074-1075: yes takes at least minor, (narrowing) is BREAKING. A BREAKING minor is therefore the coherent (and only permitted) grade; major would have been refused. Run offline against origin/main: check-changeset-no-major exit 0 ("no major bump"; the level axis is PR-scoped and CI's Check Changeset is green at head).
• (narrowing) when the set moves both ways — RIGHT. check-adr-0087-registration.mjs breakingDeclaration() (:629-642) takes the narrowing arm as signal (4) ([finding] An accept-set narrowing owes a **BREAKING** banner in core but not in platform-objects — and the ADR-0087 classifier reads the banner #16421), states that widening adds no signal, and its self-test fixture pins exactly this spelling: "the narrowing arm beside a yes value — a diff that widens AND narrows" → Clause-②: yes (narrowing). The arm carries the breaking half; the PR body's bare Clause-②: yes is the claim line the level axis reads.
• ADR-0087 not-required (no-migration-prescription) — RIGHT. Run offline against origin/main: exit 0, reading [clause-②-narrowing] not-required (no-migration-prescription); the category is re-validated statement-against-statement (refused only when the body carries a FROM→TO prescription, which it does not). Nothing authorable is removed or renamed (api-surface: 0 breaking, 1 added); objectstack migrate meta has nothing to rewrite.
• formula bumped with untouched source — RIGHT. AGENTS.md :1071: a changeset for "anything that publishes"; @objectstack/formula's published behaviour (matchesFilterCondition $like/$ilike) moves through its spec dependency, and the CHANGELOG entry is what an upgrading formula consumer greps. In a fixed group the level propagates regardless; naming the package places the notice where it is read.

③ Boundary flags

• Out-of-lane driver-memory source (domain:engine). memory-driver.ts +12/−8 on the two mingo doors, recorded by the seat as a claim-surface amendment (ACCEPT 5855574230) under the producer-side clause; measurement placed the flag choice in those two call sites, so a spec-only change would have left both doors on UTF-16. The seat states no other open PR touches memory-driver.ts; not re-measured here.
• Three hand-written docs still say "one character" — content/docs/api/client-sdk.mdx:553, content/docs/deployment/troubleshooting.mdx:148, packages/client/src/query-builder.ts:88; also the conformance-ledger note packages/spec/src/data/filter-text-conformance.ts:315 ("any one character"). All remain true under the reading the spec now defines; none defines the unit. Carrier: none, as the PR records.
• likePatternToRegexSource stays exported. A consumer can still new RegExp(source) flagless and get the UTF-16 reading; the only guard is the docblock prohibition (filter.zod.ts:1339-1350). No consumer outside the spec in this repo or in objectui at HEAD or at the pin. A follow-up (deprecation, or a grep gate over new RegExp(likePatternToRegexSource) would make the prohibition enforced rather than declared; not this card.
• mingo $options hazard. The u flag survives mingo only because neither door passes $options; a future door passing $options: '' would silently drop it (proved above). The new driver-memory test covers the two existing doors, not a future one.
• Postgres unmeasured — likePatternPredicate (sql-driver.ts:3950-3954) binds the pattern verbatim to LIKE … ESCAPE, where _ is one character in a UTF-8 database: consistent with the sentence. Not executed (no PG here; CI's live PG job exercises temporal conformance, not this cell).
• MySQL arm: derived contradiction with the new sentence, pre-existing, unmeasured — needs a card. likePatternPredicate on mysql (sql-driver.ts:3956-3960) emits CAST(?? AS BINARY) LIKE CAST(? AS BINARY) ESCAPE ?, and the driver's own docblock (:3510) calls that comparison "byte-wise". MySQL's LIKE over binary strings matches byte by byte, so _ consumes one UTF-8 byte there: 😀 would need four _ and é two, on the one face the same LIKE_DESCRIPTION names as answering $like ("the SQL family (driver-sql …)"). The new sentence ("ONE _, never two, as SQL LIKE counts it") is true of SQL LIKE over character strings and of every measured face, and the MySQL divergence already broke the OLD sentence for every non-ASCII character before this PR — but the PR sharpens the promise without carving out the arm it declares unmeasured. Not measured here (no docker daemon, no MySQL). Not blocking this PR's declared scope (the card and triage set PG/MySQL aside; the spec text is the contract and the arm is the face defect), but it is a finding class (a) candidate for the engine lane: the MySQL $like lowering should count characters (e.g. compare in utf8mb4_bin rather than via BINARY), or the description must name the exception.
• Unpaired surrogates — declared unmeasured by the PR; my census shows values made only of lone surrogates do not move, and moved cells all hold a pair. UTF-8 SQLite cannot store a lone surrogate, so no cross-face cell exists.
• REST not re-measured here. The card's HTTP measurement was on a sqlite-wasm stack (already the code-point answer). The JS-face doors the REST data API reaches (find with where on driver-memory; formula for write-side check) are the doors the new suites drive; no HTTP run was made in this review.

Implemented-by: claude/issue-20143-like-underscore-code-point
Reviewed-by: session_01Rjy9MeetSfq34PKn81CRiN

VERDICT: PASS