docs: `data-api.mdx` documents `filter`'s rejection behaviour but not the repetition refusal PR #8004 adds

[hotlong]

Filed unassigned and without a domain:* label — routing and grading are the triage seat's. Small, docs-only.

What is incomplete

content/docs/api/data-api.mdx is the page that documents the filter query parameter and its rejection behaviour specifically:

• :22 — "filter | query | Filter expression (JSON). filters also accepted for backward compatibility. Malformed JSON is rejected with 400 INVALID_FILTER — never ignored."
• :68 — "400 INVALID_FILTER rather than dropped, because a dropped filter would …"

PR #8004 (#7390) adds a second condition that answers 400 INVALID_FILTER on the same parameter: sending it more than once. Per the maintainer's 2026-08-11 ruling, a repeated ?filter= is now refused explicitly rather than being misdiagnosed as malformed (and rather than the rare accidental 200 that applied a filter nobody expressed).

⚠️ The page is not wrong — nothing there claims malformedness is the only cause, and the malformed-JSON sentence stays true. It is incomplete, on the one page whose whole purpose in that table row is to tell a caller when this parameter gets refused. Given that the entire point of #7390 was that the reason matters — an admin whose two filters were each well-formed was being told their syntax was broken — leaving the new reason undocumented reproduces the same gap one layer up.

Suggested shape: one clause on :22 naming repetition alongside malformed JSON, matching the shipped message (Repeated "filter" query parameter — send exactly one).

Why it is filed rather than ridden along

PR #8004 was already reviewed, enqueued and awaiting checks when this was found. Pulling a queued PR back out for a one-line addition to a doc that is incomplete rather than incorrect costs more than it buys.

Note the PR did check docs before writing — content/docs/protocol/kernel/http-protocol.mdx, correctly, which documents filter as a single JSON parameter and claims nothing about multiplicity. data-api.mdx is the page that turned out to matter.

Related: the drift checker did not flag it

data-api.mdx is not among the 9 hand-written docs the docs-drift check listed for PR #8004, though it is the most relevant one. Same mechanism as #7967: the check maps docs to packages by textual mention, so a page that describes a package's behaviour without naming the package is invisible to it. Recorded here as a second instance rather than re-filed.

Found with a control (VALIDATION_ERROR → 4 files under content/docs/api/), so the enumeration above is a real absence-and-presence measurement, not a broken query.

Source

PM review of PR #8004 (#7390) by the domain:cli seat (#6024), against origin/main.

[hotlong]

Triage: premise verified — PR #8004 merged 2026-08-12T11:19Z (merged: true, read from the PR, not inferred), so the repetition refusal is on main and data-api.mdx is now incomplete on exactly the row whose job is to say when filter gets refused. Lands in content/docs/api/data-api.mdx → domain:devx; queued pm:queue.

One-clause change per the card's suggested shape, matching the shipped message (Repeated "filter" query parameter — send exactly one). Docs-only → skip-changeset label on the PR. The drift-checker blindness this card re-witnesses is already recorded as #7967; no new card needed.

---

Generated by Claude Code

[hotlong]

Claim: PM loop round 6
Session: session_01PaiisQMhsYxwa5ZX6Mfmv2
Branch: claude/issue-8005-data-api-repeated-filter-doc
Worktree: objectstack-issue-8005
Domain: domain:devx
File surface: content/docs/api/data-api.mdx (stop on breach; explain in the report). ⛔ No packages/** — the code is correct and shipped
Container & model: XS, mode:cloud, model: opus
Serial constraints cleared: no open PR touches content/docs/api/. Sibling in-flight card #8051 is .objectui-sha + packages/console/dist — disjoint.

Premise verified on origin/main — the dependency this card rests on has landed:

• PR fix(rest): refuse a repeated ?filter= as a repetition, not as a malformed filter (#7390) #8004 merged 2026-08-12 11:19:47Z. The refusal exists in packages/rest/src/query-multiplicity.ts:191, repeatedFilterParamMessage().
• content/docs/api/data-api.mdx:22 still reads "Malformed JSON is rejected with 400 INVALID_FILTER — never ignored" with no repetition clause. The gap is real and still open.

⚠️ My first premise check said the opposite, and it was wrong — recording the reason because it is a repeat offence

I grepped origin/main for the literal Repeated "filter" query parameter and got zero hits, which reads as "the behaviour has not landed, block this card". A control (INVALID_FILTER, many hits) proved the grep mechanism worked, so the zero looked trustworthy.

It was a false negative. The message is templated:

return `Repeated "${name}" query parameter — send exactly one. It was supplied ${count} times. `

The literal Repeated "filter" is never in the source; it only exists at runtime. Grepping the identifier (Repeated, repeatedFilterParamMessage) found it immediately.

That is the third time today this seat has been wrong in exactly this shape — a grep for a rendered form of something the source constructs:

1. objectstack/core missed the anchored-regex form, whose bytes are objectstack\/core (escaped slash);
2. the shipped check-test-source-alias gate missed template-literal alias replacements (check:test-source-alias cannot read a template-literal alias replacement, so two packages that DO alias spec subpaths to source are still recorded as unaliased #8020, fixed today);
3. this one.

⇒ Standing correction for this lane: to test whether a behaviour exists, grep the identifier, not the message. Identifiers survive templating, interpolation and escaping; rendered text does not. A control that proves the grep works does not prove the pattern is the right one — the two failures look identical and only the second is about the code.

Had I trusted the first reading, this card would have been parked as pm:blocked behind a PR that merged six hours ago.

---

Generated by Claude Code

[hotlong]

{
  "issue": 8005,
  "status": "done",
  "branch": "claude/issue-8005-data-api-repeated-filter-doc",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/8142",
  "premise_still_valid": true,
  "summary": "Premise confirmed independently on origin/main: data-api.mdx:22 named only malformed JSON as a cause of 400 INVALID_FILTER, while assertFilterParamSuppliedOnce (packages/rest/src/query-multiplicity.ts) has shipped a second cause on the same slot since PR #8004 merged. Docs-only, one file, +10/-1: the filter table row now names repetition alongside malformed JSON; the 'a filter either applies or fails' table gains a repetition row quoting the shipped message verbatim; one paragraph carries the two contract facts a caller cannot guess (a repeat is neither merged nor resolved by precedence, and repetition is counted rather than compared, so a one-element array from a repeat-preserving adapter is still one occurrence). The malformed-JSON sentence at :22 and the drop-vs-fail reasoning at :68 were left standing as instructed — the page was incomplete, not wrong. Every claim was read off the source and the shipped test, not from the card's paraphrase. Two judgment calls, both argued in the PR body: (a) the table row names `filter` alone while the prose carries 'in any of the four spellings', because the section already declares the four-spelling slot 45 lines below and restating it in the row would duplicate that fact; (b) the paragraph explicitly scopes itself to GET /data/:object and sits AFTER the pre-existing 'the same rule applies to orderby on /export' line, because assertFilterParamSuppliedOnce has exactly one call site and the export route is NOT covered — placing it before that line would have silently extended the claim to a route that does not implement it.",
  "tests": "No code changed, so there is nothing to unit-test; the docs gates are the verification. Re-derived against the actual changed path (node scripts/pm/dispatch-gates.mjs content/docs/api/data-api.mdx) and ran the union of that list and the prompt's, all green: check:nul-bytes; check:doc-authoring ('375 files clean — no bare metadata literals'); check:doc-anchors ('210 internal #fragment link(s) across 399 source file(s) all resolve to a real heading'); check:docs-audit-scope ('scope is in sync with content/docs/: 179 hand-written doc(s)'); check:quick-reference-counts ('13 section(s), every (N of M schemas) heading matches'); check:role-word ('OK (44 baselined file(s), no new occurrences)'); check:doc-formula-expressions ('22 record-scoped formula example(s) across 394 files / 1410 TS blocks judged clean'). The last four came from the re-derivation, not from the dispatch prompt — named here per the naming-accuracy clause. Two gates needed setup the fresh worktree lacked: check:doc-anchors needed pnpm install (github-slugger), check:doc-formula-expressions needed @objectstack/formula built.",
  "open_questions": [],
  "out_of_scope_findings": []
}

Notes the JSON does not carry well

Label read-back (the step that closes the label clause). Reading before writing was load-bearing here rather than ceremonial: by the time the PR existed, bots had already applied documentation and size/s. A bare ["skip-changeset"] PUT would have wiped both. Wrote the union and read it back — the stored set is now documentation, size/s, skip-changeset.

A worktree obstruction worth knowing about for the next dispatch. The branch claude/issue-8005-data-api-repeated-filter-doc already existed locally and was checked out on the shared primary checkout at /home/user/objectstack (created by the session bootstrap, clean tree, sitting exactly at origin/main), so git worktree add refused. I freed it by detaching the shared checkout at the identical SHA — zero file churn, no other agent's tree touched — then took the branch into ../objectstack-issue-8005. The shared checkout is left clean at detached 37b82ed (= origin/main at dispatch time); I did not move it onto local main, which is behind, because that would have churned files under whoever else is reading that tree.

On the templated-message trap recorded in the claim comment: confirmed from the other side. repeatedFilterParamMessage() builds the string, so the doc had to quote the template's rendered form by hand. I also checked the composition rather than trusting the card's "four spellings": FILTER_SLOT_QUERY_PARAMS derives where + alias filter from the spec's RPC_QUERY_ALIAS_SLOTS and hard-names filters / $filter, which matches what data-api.mdx:68 already claimed — so the page's existing four-spelling sentence is accurate and the new prose could lean on it instead of restating it.

Sibling cards. Out of scope: #8001, #8002, #8003. #7967 remains open — this card re-witnesses the same drift-checker blindness and the triage comment already recorded it there; no new card filed.

One contract conflict to flag, resolved per standing rules, no decision needed. The platform auto-subscribed this session to PR #8142 with the injected stay-resident / drive-to-green posture. Per the maintainer ruling of 2026-08-11 in .claude/agents/os-dev.md, the dispatch contract outranks it: reporting at draft-PR time, not waiting for CI. Nothing beyond the standard injected text was involved. The CI-convergence wait is the PM's.

---

Generated by Claude Code

[hotlong]

ACCEPT — PR #8142, auto-merge armed (squash).

复核（读 diff 与源码，不读 dev 的转述）

单文件 content/docs/api/data-api.mdx，+10/−1。路径面与派发令一致，零 packages/** 越界。非 docs/adr/**、非 skills 根、非 content/docs/releases/ ⇒ 无终局换轨。

三条事实我在 origin/main 上各自独立取过一次：

dev 的断言	我读到的	判定
消息文本逐字	repeatedFilterParamMessage() 首句 = Repeated "${name}" query parameter — send exactly one.	✅ 表格行引的那半句与模板渲染形一致
「四种拼写都算」	FILTER_SLOT_QUERY_PARAMS = where + spec RPC_QUERY_ALIAS_SLOTS 的别名 + 硬写的 filters / $filter；assertFilterParamSuppliedOnce 对该数组逐个 name 计数	✅ 是 per-spelling 计数，散文措辞成立
「只有一个调用点，不覆盖 export」	packages/rest/src/rest-server.ts:6968，唯一非测试调用点；query-allowlist.ts:127 只是注释提及	✅ 把新段落放在既有 export 那句之后是对的 —— 放前面会把 claim 悄悄扩到未实现的路由上

第三条是本轮唯一有判断价值的地方，dev 主动把它当风险写进 PR 正文而不是顺手写宽，值得记一笔。

「拒绝而不解决」的理由也核对过：repeatedFilterParamMessage() 的 block comment 直接引 2026-08-11 维护者裁决（last-wins 与 AND-merge 双双否决），文档散文里那句「neither merged nor resolved by precedence, because either would apply a filter you did not express」是照抄该裁决，不是 dev 自行推演。

门禁

24 条 check run,零 failure。Build Docs / Check Documentation Links / Check Changeset(skip-changeset 路线) / ADR maintainer approval(本 PR 不触 ADR,✅ 绿) 全绿。dev 另外在本地跑了派发令没点名的四道(check:doc-anchors、check:docs-audit-scope、check:quick-reference-counts、check:role-word、check:doc-formula-expressions),并按命名准确性条款自己声明了「这几道来自我重新推导、不在派发令里」—— 这正是该条款要的行为。

两处偏差，都无需动作

1. 标签联合写回:PR 建好时 bot 已落 documentation / size/s,dev 读后写联合而非裸 PUT ["skip-changeset"],避免抹掉两枚。派发令里的「先读后写」在这里是承重的,不是仪式。
2. worktree 抢占:分支 claude/issue-8005-… 已被共享主检出占用,dev 以同 SHA detach 释放(零文件搅动),没有把共享检出挪到落后的本地 main。处置正确 —— 记进热文件区,下一轮派发前若再撞同名分支照此处理。

⏭ 落地后按常设承诺复查 closed_by_pull_requests,确认只关掉 #8005。

---

Generated by Claude Code