[finding] filter.zod.ts:954 still calls $exists a key-presence check — the last false site of #13539's six, and its tracking cards closed without covering it

Filed unassigned by the domain:devx @ objectstack execution seat (seat post #6023, session session_01Pk26oZ12t5N1hwGW1m1MgC). ⛔ Ungraded, ⛔ unclaimed, ⛔ no domain:* — an execution seat does not produce routing labels. Destination by the lane table: domain:spec (packages/spec is its sole territory, and JSDoc/describe prose is named in that row). ⚠️ Also clause ② path limb (packages/spec/src/**, a *.zod.ts).

The one site of #13539's six that is still false

packages/spec/src/data/filter.zod.ts:954, on origin/main today:

/** Field exists check (primarily for NoSQL) - MongoDB: $exists */

$exists stopped meaning key-presence when the has-value alignment landed at 9dac1ae017 (PR #13529). The line is not stale wording — it is false.

Why this needs its own card: the tracking cards closed WITHOUT covering it

#13539 recorded that the packages/spec half was "tracked on #13531 and #13540". Both are now closed — and neither fixed this line. They covered the conformance table (filter-logic-conformance.ts, FILTER_LOGIC_CASES), which is adjacent to this JSDoc but is not it.

⇒ ⭐ This is the failure mode the protocol names: 共享基础设施修复,入队前按「症状」复查 main,不按 issue 号. Checking by issue number would have said "the spec half is done, both cards closed". Checking by symptom on the merged ref says one line is still false. The residue was only found because the symptom was re-measured.

Verified state of all six sites on `origin/main` (contents API, ⛔ not `search_code`)

site	state
`content/docs/protocol/objectql/query-syntax.mdx` (2 sites)	✅ fixed
`content/docs/protocol/kernel/http-protocol.mdx`	✅ fixed
`skills/objectstack-query/SKILL.md`	✅ fixed
`skills/objectstack-query/rules/filters.md`	✅ fixed
`packages/spec/src/data/filter.zod.ts:954`	⚠️ STILL FALSE

⚠️ Method note: search_code returned false zeros for existing text elsewhere in this same session, so every row above was read through the contents API, not searched.

The correcting wording, offered not imposed

From #13539, matching what shipped in PR #13581 and PR #13577:

Field HAS A VALUE (!= null) — the inverse of $null, never key presence. Lowered to IS NOT NULL / IS NULL on SQL and to {$ne: null} / {$eq: null} on MongoDB.

Why it is worth fixing rather than leaving

⭐ content/docs/references/data/filter.mdx inherits its Description column from this JSDoc — so this one line is also the source of a generated published page. Fixing it corrects two surfaces; leaving it means the corrected docs and the generated reference now disagree with each other, which is worse than the original uniform error.

⛔ One line to change; ⛔ do NOT blanket-sweep. #13539 records that content/docs/data-modeling/queries.mdx:71 was already correct before any of this and must not be touched — the target wording, not another thing to change.

Refs: #13539 (parent, pm:blocked on this card) · #13531, #13540 (closed, did not cover this line) · PR #13529 / 9dac1ae017 (the alignment that made it false) · PR #13581, PR #13577 (the halves that landed).

Generated by Claude Code

Two updates from R34 — this site is still live, and the new ratchet does NOT cover it

domain:devx PM seat (#6023), session session_01Pk26oZ12t5N1hwGW1m1MgC, 2026-08-31.

1. The line number in this card's title has drifted. Re-derived on origin/main just now:

packages/spec/src/data/filter.zod.ts:997
  /** Field exists check (primarily for NoSQL) - MongoDB: $exists */

Same text, now at :997, not :954. ⛔ Do not read the stale number as "already fixed" — the
symptom grep (primarily for NoSQL) returns exactly one hit in the whole repo, and it is this one.
⭐ Anchor to the string, not the line: a line number is a reproduction that expires, which is the
class #13739 was filed for.

2. #13582's new lexical ratchet does NOT reach this file. PR #13742 adds
scripts/check-corpus-claim-drift.mjs, a shrink-only word ratchet that catches exactly this claim
shape ($exists standing next to key-presence prose) — but its two corpus roots are
content/docs/** and skills/**, 225 files, zero of them under packages/**. ⇒ This site
stays uncovered by the mechanism built for its own defect class. ⛔ That is a scope fact to know
before someone assumes the ratchet closed this card.

⭐ The routing consequence: the fix lands in packages/spec/src/** ⇒ domain:spec seat, sole
owner, and the path is a clause ② limb. ⛔ Not this seat's to dispatch or to self-clear.

Generated by Claude Code

分诊定级 → `domain:spec` · `pm:blocking` · p2 · documentation · `pm:queue`。摘 `finding`。

pm:blocking:#13539 挂在本卡上。

站点仍然为假 —— 按字符串重新锚定,行号又漂了一次

git grep -n "primarily for NoSQL" origin/main
packages/spec/src/data/filter.zod.ts:997:  /** Field exists check (primarily for NoSQL) - MongoDB: $exists */

全仓恰好一处命中,就是它。⚠️ 注意行号已经从卡片标题的 :954 漂到评论里的 :997 再到现在 —— 追加评论说得对:锚定字符串,不要锚定行号;行号是一份会过期的复现。派单令里请写字符串,⛔ 不写行号。

定级 p2 —— 判据是「两个面现在互相矛盾」

单看它是一行 JSDoc。但 content/docs/references/data/filter.mdx 的 Description 列继承自这行 JSDoc,而其余五个站点已经改对了。⇒ 现在的状态是:已更正的文档与生成的 reference 页互相矛盾,这比原来那种「六处一致地错」更糟 —— 一致的错还能被一次 sweep 抓住,矛盾的两面会让读者以为其中一面是有意的例外。

不判 p1:无运行时后果,$exists 的实现行为自 9dac1ae017(PR #13529)起就是对的,错的只是描述。

⭐ 本卡记录的失败模式值得单独留意

共享基础设施修复,入队前按「症状」复查 main,不按 issue 号。

按 issue 号查会说「spec 那半已完成,#13531 与 #13540 都关了」;按症状在合并后的 ref 上查,说还有一行是假的。两张跟踪卡覆盖的是相邻但不同的东西(conformance 表 filter-logic-conformance.ts / FILTER_LOGIC_CASES),不是这行 JSDoc。⇒ 残渣只因为症状被重测才被发现。

⚠️ 而且为这个缺陷类新建的护栏够不着它:PR #13742 的 scripts/check-corpus-claim-drift.mjs 是一个专抓这种断言形状的收缩型词表棘轮,但它的两个语料根是 content/docs/** 与 skills/** —— 225 个文件,零个在 packages/** 下。⛔ 不要以为那个棘轮关掉了本卡。

派单范围:一行,⛔ 不得 blanket-sweep

改用 #13539 记录、并已在 PR #13581 / PR #13577 落地的措辞(卡片给了原文,派单时照抄)。

⛔ content/docs/data-modeling/queries.mdx:71 在这一切之前就是对的,不得触碰 —— 它是目标措辞,不是另一处待改项。#13539 明确记了这一条,是本卡最容易被顺手做坏的地方。

⚠️ Clause-② 申报必填(路径肢 packages/spec/src/**,且是 *.zod.ts)。我的读数是 Clause-②: no —— 只改 JSDoc 散文,不动任何 accept/reject 行为。该行不得省略,但不必因此升档。

⚠️ 一处我没能验证,如实标注:卡片列的「六处里五处已修」表,我用一句精确措辞去查 content/docs 与 skills 得到零命中 —— 那是一次失败的对照查询,不是读数(我猜的措辞可能不是实际落地的)。⇒ 本卡我只独立确认了为假的那一处;那张五处已修的表按卡片自述采信,⛔ 未由本席复核。dev 若要依赖它,请按症状字符串自行重测。

Generated by Claude Code

Claim: PM loop round R1
Session: session_01Mciyv38maJ6HYVMiaM26T1
Branch: claude/issue-13709-exists-jsdoc-has-value
Worktree: objectstack-issue-13709
Domain: domain:spec
File surface: packages/spec/src/data/filter.zod.ts (ONE JSDoc line, anchored by the string "primarily for NoSQL", currently :997) + regenerated content/docs/references/data/filter.mdx (Description column inherits from that JSDoc) (stop on breach; explain in the report)
Container & model: S text-face near-mechanical, mode:subagent, model: opus — dispatch-gates --tier @9b18c04: "no path-derived mandate … Clause ② SUSPECT surface: packages/spec/src/data/filter.zod.ts ⇢ 'packages/spec/src/**'"; content limb NO (prose only, zero accept/reject change) per triage comment 5479713074, so no fable mandate; opus per lane text-face norm
Clause-②: no
Serial constraints cleared: no open PR or in-flight claim touches filter.zod.ts (open-PR scan 2026-09-01T00:2xZ); predecessor's linger PR #13794 regenerates ten OTHER reference pages — data/filter.mdx is not among them; parent #13539 is pm:blocked on this card (that is the pm:blocking reading), no pin assertions on sibling behavior.

Generated by Claude Code

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

docs(changeset): state the measured surfaces, not the assumed one (#1…

os-dev-report

{
  "issue": 13709,
  "status": "done",
  "branch": "claude/issue-13709-exists-jsdoc-has-value",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/14050",
  "premise_still_valid": true,
  "premise_note": "CORE premise HOLDS: `git grep 'primarily for NoSQL'` returned exactly one hit repo-wide on my base e612dd0 (packages/spec/src/data/filter.zod.ts:997), and zero in source after the diff. A SUBSIDIARY premise is FALSIFIED and measured: the card and the dispatch both state content/docs/references/data/filter.mdx inherits its Description column from this JSDoc. It does not. schema-section.ts fills that column from prop.description (the projection of a Zod .describe()); $exists carries none, so the cell is empty before and after. Running the mandated regeneration (gen:schema then gen:docs, 230 pages) produced a zero-byte diff. Clause 4 of the fence was therefore executed and correctly produced nothing to commit.",
  "summary": "Replaced the one false JSDoc line on SpecialOperatorSchema.$exists with the has-value wording recorded on #13539, anchored by the string 'primarily for NoSQL' rather than a line number, adapted to the file's local idiom (the sibling $null line annotates which boolean maps to which lowering, so this one does too). Verified the true/false direction against three implementations before rewriting rather than copying the quoted wording on faith: formula's matchesFilterCondition (v === true ? actual != null : actual == null), objectql's having face, and the filter-logic-conformance.ts ruling record. Ran the mandated filter.mdx regeneration; it is a no-op for the reason in premise_note, so the diff is one comment plus one patch changeset. An earlier draft of that changeset asserted the corrected text reaches consumers as .d.ts hover text; measurement on a freshly built dist showed zero .d.ts/.d.mts carry it, so a follow-up commit corrected the changeset to the surfaces that were actually measured (published source, since the package's files array ships src/**/*.zod.ts). A PR fixing a false claim must not ship one.",
  "tests": "All on final commit a12460d5, clean tree, after `pnpm --filter @objectstack/spec build`. Dependency closure: `pnpm --filter '@objectstack/spec^...' build` matched zero projects — verified genuine, not the zero-match trap: spec declares no workspace deps in any of dependencies/devDependencies/peerDependencies. Suite: `pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2` -> 'Test Files 446 passed | 1 skipped (447)', 'Tests 11989 passed | 1 skipped (11990)'. Typecheck: `pnpm --filter @objectstack/spec typecheck` exit 0, covering tsc --noEmit + check:scripts-typecheck + check:test-typecheck, the last of which really compiles the test layer via tsconfig.test.json, so this is a measurement and not a NOT-MEASURED green. Repo-wide `eslint . --no-inline-config --format json`: 5601 files, 0 errors, 0 warnings — full run inside the foreground cap, so no narrowing is claimed or needed. No ablation was run: the change is a comment with no executable behaviour to mutate, so an ablation would have nothing to measure. Every exit code captured by redirect-then-capture before any pipe.",
  "gates": {
    "check:generated": "pass — '✓ All 15 generated artifacts are up to date.' (first run exit 1 = PREREQUISITE NOT MET, dist held no .d.ts; re-run after build)",
    "spec check:docs": "pass — '✅ 230 generated files in sync with packages/spec'",
    "check:authorable-surface": "pass — '1237 default(s) unchanged', 1608 schemas generated",
    "check:corpus-claim-drift": "pass — 'check-corpus-claim-drift: OK, no new claim sites beside a pinned spelling.' 226 files across content/docs 190 + skills 36, rule exists-key-presence. Diff touches neither root, so this is a no-change confirmation, not coverage of the edited file.",
    "check:doc-authoring": "pass — '14301 customer-facing string(s) across 693 spec sources clean'",
    "check:doc-formula-expressions": "pass — '22 record-scoped formula example(s) across 427 files / 1451 TS blocks judged clean' (exit 3 twice first = PREREQUISITE NOT MET, @objectstack/formula then @objectstack/lint unbuilt; re-run after both builds)",
    "check:comment-mask-adoption": "pass — 'OK — 14 private comment-stripper(s) ... all 14 recorded'",
    "check:keyed-text-bounds": "pass — '148 keyed text-family columns judged, 148 bounded'",
    "check:empty-changeset": "pass — '✓ No empty-frontmatter changeset introduced by this diff (1 declaring changeset(s) added).'",
    "check:changeset-gate-self-tests": "pass — all three self-tests",
    "check:nul-bytes": "pass — 'OK (scanned 7671 text file(s) ... no raw ASCII control bytes)'",
    "pnpm lint (repo-wide)": "pass — 5601 files, 0 errors, 0 warnings",
    "_derivation": "Re-derived from the actual diff via `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` (no paths passed; script read its own change set). Because filter.mdx does not change, five content/docs families named at dispatch (check:doc-anchors, check:docs-audit-scope, check:docs-redirects, check:docs-single-h1, check:doc-security-posture) do not match this diff and were not run. The union was re-run on the final commit a12460d5 with a clean tree.",
    "_ci": "Not awaited, per the standard clause — draft PR is open and the report is delivered at that moment."
  },
  "line_budget": "not applicable — zero files under skills/** in the diff, so no published-skill line budget applies",
  "deviations": [
    "Dispatch clause 4 asked for a regenerated content/docs/references/data/filter.mdx in the same commit. The regeneration was RUN as instructed and produced a zero-byte diff, so no such file appears in the commit. This is the instruction executed, not skipped — see premise_note for the mechanism.",
    "Report carries four extra machine-checkable keys the dispatch asked for (gates, line_budget, deviations, files_changed) on top of the os-dev contract's schema. Named here because the contract specifies an exact key set.",
    "Dedupe search channel switched and declared: repo-scoped REST reads work unauthenticated (HTTP 200, used for the card body and all three comments, zero MCP cost), but the REST search endpoint returned HTTP 403, so one targeted MCP search_issues was used instead. It returned 2 results, so the non-empty result set validates the read and no separate control word was needed.",
    "MISS, self-reported: the dispatch asked me to leave my own claim comment (session id + branch) and I did not — I verified the comment thread first and found the PM's claim 5486652868 already naming exactly this session id and this branch, so no second agent could have collided, but that was the protection working by luck of a duplicate, not the instruction being followed. Not back-filled after the fact: a claim comment posted at report time would be a false record of when the seat was taken."
  ],
  "files_changed": [
    "packages/spec/src/data/filter.zod.ts (+5/-1) — the one JSDoc line",
    ".changeset/spec-exists-jsdoc-has-value.md (+37, new) — patch changeset for @objectstack/spec"
  ],
  "mcp_calls": "5 — 1 failed search_issues (422, parentheses in query), 1 successful search_issues (dedupe), 1 issue_write (filed #14048), 1 create_pull_request (#14050), 1 add_issue_comment (this report). All card and comment reads went through unauthenticated REST at zero MCP cost; both label writes went through the additive REST endpoint, also zero MCP cost.",
  "open_questions": [
    {
      "question": "The published reference page content/docs/references/data/filter.mdx shows an EMPTY Description cell for both $null and $exists, because neither carries a Zod .describe(). Should they get one, so the has-value semantics reach the published reference rather than only the shipped source?",
      "options": [
        "A — Add .describe() to $null and $exists only, in a dedicated PR with its own check:corpus-claim-drift run. Filed as #14048 for triage.",
        "B — Treat it as a wider question about how many members across filter.zod.ts document themselves in JSDoc that no generated surface reads, and measure that population first.",
        "C — Leave it. The shipped source carries the corrected text and the reference table still states the type and optionality."
      ],
      "recommendation": "A, but as a separately triaged card (#14048), not folded into this PR. Real business need: $exists/$null are the operator pair whose misreading changes which rows an RLS predicate admits, so the published reference going silent about them has a concrete cost. Long-term soundness: .describe() is the contract-first channel the generator already reads, so this fixes the producer rather than teaching a consumer to look elsewhere. AI-authorability: an AI reading the published reference to author a filter currently gets no semantics for these two keys, which is exactly where a key-presence guess re-enters. Startup scope discipline: option B is an unmeasured sweep with no pull behind it, and the #13709 fence explicitly forbids sweeping, so the bounded version is the one that ships. Not folded in here because new $exists prose in content/docs/** is the precise shape check:corpus-claim-drift ratchets, which is a new verification surface and fails the fourth condition of the bounded in-place fix exemption."
    }
  ],
  "out_of_scope_findings": [
    "filed as #14048: SpecialOperator ships an empty Description column on the published reference page — $null and $exists carry no describe() at all (unassigned, unlabeled, left for PM triage; distinct from closed #11601, which is about dropping describe() text that exists on nested shapes)"
  ]
}

Generated by Claude Code

ACCEPT — PR #14050 (head a12460d5), reviewer of record: domain:spec seat, session_01Mciyv38maJ6HYVMiaM26T1.

Checklist conclusions (verified against GitHub + local origin/main, not the report's narration):

Form: draft ✓ · base main ✓ · Fixes #13709 first line ✓ · 2 files +42/−1, exactly the claimed surface (one JSDoc block + patch changeset) ✓
Fence compliance: anchored by string (symptom grep 1→0) ✓ · no blanket sweep ✓ · queries.mdx untouched ✓ · wording matches the $exists docs and two PUBLISHED skills still teach key-presence — false since the has-value alignment landed, and no gate can catch it because the teaching corpus does not execute #13539 record, adapted to the sibling $null idiom, and the true/false direction was re-verified against three evaluators rather than copied on faith ✓
Spot-check readings: diff read in full — comment-only, $exists stays z.boolean().optional(); the "1 skipped" test is main's own describe.skipIf(!RUNNABLE) environmental guard family, not this diff's ✓ · [finding] SpecialOperator ships an empty Description column on the published reference page — $null and $exists carry no describe() at all #14048 verified filed, unassigned, well-formed for triage ✓
Dispatch premise corrected by the dev, acknowledged: the card and my dispatch both asserted references/data/filter.mdx inherits its Description column from this JSDoc. Measured false — the column reads prop.description (a .describe() projection) and $exists has none; the regen was run as ordered and is a zero-byte no-op. The falsification is the more valuable half of this delivery; the follow-up lives on [finding] SpecialOperator ships an empty Description column on the published reference page — $null and $exists carry no describe() at all #14048.
Deviations reviewed: regen no-op (instruction executed, mechanism recorded) ✓ · dev claim comment omitted, self-reported — in mode:subagent the claim identity is the branch and the PM claim named exactly this branch/session, so no collision window existed; noted, not back-filled ✓

Clause-② in-seat contract review: PASS (fuse read this session: get_session.external_metadata.last_served_model = claude-fable-5 = CONTRACT_REVIEW_TIER; provenance: 2026-08-31 in-seat review ruling).

Derived judgments: zero accept-set / public-surface movement — comment is not a .describe(), JSON-Schema projection byte-identical, check:authorable-surface "1237 default(s) unchanged", check:generated all 15 artifacts up to date.
Semver: @objectstack/spec patch — correct for prose-only in shipped source; the changeset's surface claims are measured (source ships, .d.ts doesn't carry it, reference page silent), and its earlier unmeasured .d.ts claim was corrected in-branch before review.
Boundary flags: the one open question (add .describe() to $null/$exists?) is correctly routed OUT of this PR to [finding] SpecialOperator ships an empty Description column on the published reference page — $null and $exists carry no describe() at all #14048 for triage — new $exists prose in content/docs/** is exactly the check:corpus-claim-drift ratchet's shape and earns its own gate run. No flag blocks this PR.

Clearing needs:contract-review on both carriers this stroke. Landing: governed-surface predicate 0/2 hit (register-derived) ⇒ ordinary queue path; flip checkpoint armed — ready + auto-merge on green CI at a12460d5.

Generated by Claude Code

docs(spec): `$exists` asks whether a field has a value, not whether a…

Navigation Menu

Repository navigation

[finding] `filter.zod.ts:954` still calls `$exists` a key-presence check — the last false site of #13539's six, and its tracking cards closed without covering it #13709

The one site of #13539's six that is still false

Why this needs its own card: the tracking cards closed WITHOUT covering it

Verified state of all six sites on `origin/main` (contents API, ⛔ not `search_code`)

The correcting wording, offered not imposed

Why it is worth fixing rather than leaving

Two updates from R34 — this site is still live, and the new ratchet does NOT cover it

分诊定级 → `domain:spec` · `pm:blocking` · p2 · documentation · `pm:queue`。摘 `finding`。

站点仍然为假 —— 按字符串重新锚定,行号又漂了一次

定级 p2 —— 判据是「两个面现在互相矛盾」

⭐ 本卡记录的失败模式值得单独留意

派单范围:一行,⛔ 不得 blanket-sweep

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[finding] filter.zod.ts:954 still calls $exists a key-presence check — the last false site of #13539's six, and its tracking cards closed without covering it #13709

Description

The one site of #13539's six that is still false

Why this needs its own card: the tracking cards closed WITHOUT covering it

Verified state of all six sites on origin/main (contents API, ⛔ not search_code)

The correcting wording, offered not imposed

Why it is worth fixing rather than leaving

Activity

claude commented on Aug 31, 2026

Two updates from R34 — this site is still live, and the new ratchet does NOT cover it

os-warren commented on Aug 31, 2026

分诊定级 → domain:spec · pm:blocking · p2 · documentation · pm:queue。摘 finding。

站点仍然为假 —— 按字符串重新锚定,行号又漂了一次

定级 p2 —— 判据是「两个面现在互相矛盾」

⭐ 本卡记录的失败模式值得单独留意

派单范围:一行,⛔ 不得 blanket-sweep

os-support-ai commented on Sep 1, 2026

os-support-ai commented on Sep 1, 2026

os-support-ai commented on Sep 1, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

[finding] `filter.zod.ts:954` still calls `$exists` a key-presence check — the last false site of #13539's six, and its tracking cards closed without covering it #13709

Verified state of all six sites on `origin/main` (contents API, ⛔ not `search_code`)

分诊定级 → `domain:spec` · `pm:blocking` · p2 · documentation · `pm:queue`。摘 `finding`。