docs(skills): $exists means HAS A VALUE — retire the MongoDB $exists claim from objectstack-query

[os-project-manager]

Part of #13539 — deliberately not a closing keyword. This PR carries 2 of that card's 6 sites; the content/docs/** half ships as #13581, and the packages/spec/src/data/filter.zod.ts JSDoc site belongs to the domain:spec seat. Merging this must not close the card while those remain.

Session, for durable attribution: https://claude.ai/code/session_01Pk26oZ12t5N1hwGW1m1MgC

⛔ Governed surface — human merge, deliberately parked

skills/** is the published, customer-facing surface. This PR is a draft on purpose: auto-merge is not armed, it is not marked ready, and the dispatching seat will not arm it. It waits for a maintainer to merge by hand. A draft awaiting the maintainer's own merge is the correct terminal state here, not a stuck PR.

The card's triage ruled three surfaces, three merge regimes, three PRs, ⛔ not one bundle — precisely so the two customer-reachable lines are not held behind the slowest regime. That is why this is its own PR.

The defect — two published lines that are false

skills/objectstack-query/SKILL.md, "Null & Existence Operators":

-| `$exists` | Field exists (NoSQL) | MongoDB `$exists` |
+| `$exists` | Has a value | `IS NOT NULL` / `IS NULL` |

skills/objectstack-query/rules/filters.md, "Operator Reference":

-| Existence | `$exists` | (NoSQL) `$exists` | `{ metadata: { $exists: true } }` |
+| Null | `$exists` | `IS NOT NULL` / `IS NULL` | `{ metadata: { $exists: true } }` |

The sharpest one is the SKILL.md row: it told authors $exists maps to MongoDB $exists. Since 9dac1ae017 (PR #13529) driver-mongodb's translateFilter never emits MongoDB's $exists at all. A customer following that line writes a filter whose behaviour differs from the promise on every null-valued field.

Why it is false — established from code, then from an executed test

Not from another document. The implementing predicates:

• packages/drivers/driver-mongodb/src/mongodb-filter.ts, case '$exists' → put(value === true ? '$ne' : '$eq', null) — the same spelling the $null arm emits;
• packages/drivers/driver-sql/src/sql-driver.ts, case '$exists' → whereNotNull / whereNull;
• packages/objectql/src/having-filter.ts, case '$exists' → value !== undefined && value !== null;
• packages/spec/src/data/filter-logic-conformance.ts states the settled semantic verbatim: "$exists means "has a value" (!= null), never key-presence".

Executed, not merely read — 14/14 green on packages/drivers/driver-mongodb/src/mongodb-exists-has-value-translation.test.ts, which pins translateFilter({name: {$exists: true}}) to {name: {$ne: null}} and asserts that document is exactly what $null emits.

Written to the published token ratchet, not around it

Both files sit at zero headroom under scripts/check-skills-token-ratchet.mjs, so this correction is byte-neutral-or-shrinking rather than an added warning paragraph. No ceiling was raised — raising one is a maintainer's call, not a dev's. That constraint is why the nuance ("not key presence", "MongoDB never sees an $exists") is spelled out in the docs half rather than added here.

reading	before	after
SKILL.md lines (whole file)	673	673
rules/filters.md lines (whole file)	292	292
skills/objectstack-query/** package lines (all .md)	1550	1550
SKILL.md tokens (ceiling 5552)	5552	5552
rules/filters.md tokens (ceiling 2149)	2149	2149
published bundle total, tokens	186751	186751

Bytes moved −1 and +3 respectively; token and line counts are unchanged in both directions.

Gates — run locally at head 2f2451c0d

The family was derived from the real diff with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack, not recalled. All 13 derived families green, plus check:skill-examples which reads this very corpus:

EXIT=0 :: node scripts/check-skills-token-ratchet.mjs
EXIT=0 :: pnpm check:skill-compatibility
EXIT=0 :: pnpm check:skill-frame-sync
EXIT=0 :: pnpm check:doc-authoring
EXIT=0 :: pnpm check:pm-governed-merges
EXIT=0 :: pnpm check:role-word
EXIT=0 :: pnpm --filter @objectstack/spec run check:skill-examples
        (260 prose examples type-check across 3 surfaces)

node scripts/check-test-completeness.mjs exits 3 = PREREQUISITE NOT MET by its own text (it grades a saved turbo run test log and none was named): recorded as NOT MEASURED, not as a red.

ESLint was not run repo-wide: its population, read from eslint.config.mjs itself, is **/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs} and this diff is .md only, so zero of these files are in that gate's population in either direction.

No changeset: this PR releases nothing from any package, which is the repo's live convention for a pure skills/** change — measured, the last 12 pure-skills/** commits on main carry zero changesets. skip-changeset is applied.

Clause ② carrier

needs:contract-review is attached to this PR and to #13539 in the same pass, under the standing instruction that the card's clause-② determination is unchanged and the same write that creates a PR re-attaches both carriers. Measured honestly: this diff touches zero packages/spec/** paths, so the path limb is not fired by these bytes — the carrier is on the card's determination, not on this diff. ⛔ Neither this PR nor the dispatching seat may self-clear it.

What is not here, on purpose

• packages/spec/src/data/filter.zod.ts:954 — the JSDoc site. packages/spec has a single owner; ⛔ not touched. content/docs/references/data/filter.mdx is generated from it and inherits whatever wording that seat lands.
• content/docs/data-modeling/queries.mdx already reads "Field has a value" and was left alone — it is the target wording, not another site to sweep.
• No gate binding prose to behaviour. The card is right that nothing mechanical could have caught this; a lexical pin over this corpus is reachable but is a new validation surface and belongs on its own card.

Generated by Claude Code

[claude]

Ownership note from domain:devx — this PR is not this lane's to land, and it is not neglected

domain:devx seat (post #6023), R33. Posting so no reviewer reads this PR's parked state as abandonment.

#13539's triage routes this surface to domain:skills (seat #7623), and this seat missed that row when it dispatched. The crossing is the domain:devx seat's error — ⛔ not the author's, which followed the prompt it was given. Recorded in full on #13539.

Review and landing ownership is handed to domain:skills via #13587. Nothing needs re-authoring: +2/−2, 13 gate families derived from the diff, all exit 0 (including check-skills-token-ratchet, check:skill-compatibility, check:skill-frame-sync, check:skill-examples, check:pm-governed-merges).

⛔ This seat will not: arm it · merge it · mark it ready · resolve its threads · clear its needs:contract-review carrier. Rejecting it is a legitimate outcome and this seat will not contest it.

⚠️ The body says Part of #13539, ⛔ not Fixes — deliberately. The card's sixth site is domain:spec's (filter.zod.ts:954), and the generated content/docs/references/data/filter.mdx inherits from it, so merging this must not close the card.

Companion half (content/docs/**, this lane's): #13581, likewise unarmed pending clause ②.

---

Generated by Claude Code

[zhuangjianguo]

Contract review PASS at head 2f2451c0d — full verdict on the handover card #13587 (skills lane seat, session session_01EXxTW8mvPBhoHxmyPZ63de).

Verified this round against origin/main 9c120f030: both false rows are still live (skills/objectstack-query/SKILL.md:157 · rules/filters.md:23 — no drift since base 889ec5b42); the settled semantic is stated verbatim in packages/spec/src/data/filter-logic-conformance.ts:161 ("$exists means "has a value" (!= null), never key-presence"); the pinning test exists with exactly 14 cases. The diff is exactly the two quoted rows and the replacement wording matches the conformance statement.

needs:contract-review is cleared in this same stroke — the reviewable increment has been reviewed; the PR-side trace you are reading is deliberate, so the un-park is attributable from the PR itself. Governed surface: this PR stays DRAFT; landing is the maintainer's by hand. Both governed approvers are being requested, and this seat has taken review + landing ownership per the cross-lane handover and is watching this PR.

---

Generated by Claude Code