docs(spec): $exists asks whether a field has a value, not whether a key is present (#14050)

* docs(spec): $exists asks for a value, not a present key (#13709)

The JSDoc on `SpecialOperatorSchema.$exists` read "Field exists check
(primarily for NoSQL)", which describes key-presence. `$exists` stopped
meaning key-presence when the has-value alignment landed (PR #13529 /
9dac1ae); the line was false, not merely stale, and it was the last of
six sites still carrying the old claim.

Replaced with the wording recorded on #13539 and already shipped on the
other five sites, adapted to this file's JSDoc idiom (the sibling `$null`
line annotates which boolean maps to which lowering, so this one does too).
Direction verified against all three evaluators before rewriting.

Prose only: `$exists` is `z.boolean().optional()` before and after, and the
comment is not a `.describe()`, so no generated artifact moves.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mciyv38maJ6HYVMiaM26T1

* docs(changeset): state the measured surfaces, not the assumed one (#13709)

The first draft claimed the corrected JSDoc reaches consumers as `.d.ts`
hover text. Measured on a freshly built dist: zero `.d.ts`/`.d.mts` carry
it (the property's type is inferred from Zod, so no declaration comment is
emitted) — it appears in `dist` only inside `.js.map` sourcemaps.

The surface that does carry it is published SOURCE: this package's `files`
array ships `src/**/*.zod.ts`, so `filter.zod.ts` itself is in the tarball.
Recorded alongside the two negative results, since a PR correcting a false
claim must not ship one.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mciyv38maJ6HYVMiaM26T1

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-support-ai

.changeset/spec-exists-jsdoc-has-value.md

@@ -0,0 +1,37 @@
+---
+'@objectstack/spec': patch
+---
+
+docs(spec): `$exists` JSDoc said key-presence, which has been false since protocol alignment (#13709)
+
+`SpecialOperatorSchema.$exists` carried `Field exists check (primarily for NoSQL) -
+MongoDB: $exists`. That describes key-presence, and key-presence stopped being what
+`$exists` means when the has-value alignment landed (PR #13529 / `9dac1ae017`). The
+line was not stale phrasing — it was false, and it is the last of the six sites that
+carried the old claim; the other five were corrected by PR #13581 / PR #13577.
+
+The corrected wording is the one recorded on #13539 and already shipped on those five
+sites: `$exists` asks whether the field HAS A VALUE (`!= null`), the exact inverse of
+`$null`, never key presence — lowered to `IS NOT NULL` / `IS NULL` on SQL and to
+`{$ne: null}` / `{$eq: null}` on MongoDB. Verified against all three evaluators before
+rewriting: `formula`'s `matchesFilterCondition` (`v === true ? actual != null : actual == null`),
+`objectql`'s `having` face, and the `filter-logic-conformance.ts` table, which enrolls
+`$exists` in both directions.
+
+Prose only. No accept/reject change: `$exists` was and stays `z.boolean().optional()`,
+and the JSDoc is a comment, not a `.describe()` — the schema, its JSON-Schema
+projection and all 15 generated artifacts are byte-identical (`check:generated` green
+on a freshly built `dist`).
+
+Where the corrected line does and does not surface, measured rather than assumed:
+
+- **Published source — yes.** This package's `files` array ships `src/**/*.zod.ts`, so
+  `filter.zod.ts` is in the npm tarball and the comment reaches consumers verbatim.
+  That is the surface this patch is for.
+- **Emitted `.d.ts` — no.** Zero of the emitted `.d.ts`/`.d.mts` carry the text; the
+  property's type is inferred from Zod, so no declaration comment is written. It
+  appears in `dist` only inside `.js.map` sourcemaps.
+- **Generated reference page — no.** `content/docs/references/data/filter.mdx` renders
+  its Description column from `prop.description`, i.e. a Zod `.describe()`; `$exists`
+  carries none, so that cell is empty before and after. Regenerating all 230 pages
+  produces no diff. See #13709 for the follow-up on that empty cell.

packages/spec/src/data/filter.zod.ts

@@ -994,7 +994,11 @@ export const SpecialOperatorSchema = lazySchema(() => z.object({
   /** Is null check - SQL: IS NULL (true) / IS NOT NULL (false) | MongoDB: field: null */
   $null: z.boolean().optional(),
 
-  /** Field exists check (primarily for NoSQL) - MongoDB: $exists */
+  /**
+   * Field HAS A VALUE (`!= null`) — the inverse of `$null`, never key presence.
+   * Lowered to `IS NOT NULL` (true) / `IS NULL` (false) on SQL and to
+   * `{$ne: null}` / `{$eq: null}` on MongoDB.
+   */
   $exists: z.boolean().optional(),
 }));