finding: the list-query normalizer's `where` arity note still says a repeated `?filter=` is refused by `isFilterAST` failing

[hotlong]

Observation-class finding, split out of #7390 while implementing it. Unassigned, filed per Prime Directive #10. Comment-only drift — no runtime behaviour is wrong.

The sentence

packages/metadata-protocol/src/protocol.ts, in the docblock above ARRAY_VALUED_QUERY_SLOTS (the #7321 arity survey), the where row reads:

where — a FILTER AST is an array (['status','=','open']), so a blanket arity refusal here would reject the AST body form outright. A repeated ?filter= is still refused, one block down, by isFilterAST failing to read it.

The first sentence is correct and load-bearing — it is exactly why #7386's arity gate skips this slot, and #7390 quotes the same reasoning.

The last sentence has two problems, one of them older than #7390:

1. It was always describing the defect as if it were the answer. isFilterAST failing produces malformedFilterArrayError — a 400 telling a caller whose filters were each well-formed that their filter is malformed, listing the AST operator vocabulary. That is finding: a repeated ?filter= on GET /data/:object cannot be told from a filter AST, so it is diagnosed as a malformed filter (and, rarely, succeeds) #7390's entire finding: the refusal is correct, the diagnosis is not. "Still refused" reads as handled.
2. It is now stale for the route it describes. finding: a repeated ?filter= on GET /data/:object cannot be told from a filter AST, so it is diagnosed as a malformed filter (and, rarely, succeeds) #7390 moves the arity judgement for this slot to the REST querystring ingress (packages/rest, assertFilterParamSuppliedOnce), which is the only layer that can make it — on a querystring an array is a repetition and can be nothing else. A repeated ?filter= on GET /data/:object no longer reaches this block at all.

It also does not mention the second shape at all: ?filter=status&filter=%3D&filter=open spelled a valid AST and succeeded with a filter nobody expressed, which is the sharper half of #7390.

Why it matters more than a typo

This docblock is the survey a future author reads to decide whether a slot needs arity treatment. A reader who takes "still refused, one block down" at face value concludes the filter slot is covered and stops — which is roughly how the gap survived from #7321 to #7390. The sentence should say that arity for this slot is judged at the querystring ingress and name #7390, so the next reader is told which layer owns it.

Deliberately not fixed in #7390's PR: that card's ruling put the enforcement in packages/rest and explicitly kept it out of packages/metadata-protocol, and protocol.ts is a hot shared file. Same handling as #7707 / #7874, which corrected stale comments in their own PRs.

Dedup

Searched open issues for ARRAY_VALUED_QUERY_SLOTS, isFilterAST, malformedFilterArrayError, stale comment, and arity survey. Hits: #7390 (the parent), #7321 / #7386 (the arity gate, both closed) — none covers this comment.

---

Generated by Claude Code

[hotlong]

Triage (findings round): promoted finding → pm:queue, routed domain:metadata (the docblock lives in packages/metadata-protocol/src/protocol.ts), type Task, documentation.

Grading rationale: comment-only, but load-bearing comment — this docblock is the arity survey a future author reads to decide whether a slot needs treatment, and "still refused, one block down" reading as handled is exactly how the #7321→#7390 gap survived. Cheap, concrete, single-file. Scope: rewrite the where row to say arity for this slot is judged at the REST querystring ingress (assertFilterParamSuppliedOnce, #7390), name the succeeded-with-a-filter-nobody-expressed shape, and drop the stale "isFilterAST failing" claim. Docs-only → skip-changeset.

Serial note for the dispatching seat: protocol.ts is a hot shared file and #8136 (queued this round) sweeps the same file's producer messages — these two must not be in flight together; fold this docblock fix into #8136's PR as a declared rider, or run it strictly after. Preference: fold as rider, one PR touching the hot file once.

Size/model suggestion: S-mechanical, sonnet (or absorbed into #8136's M/opus dispatch).

---

Generated by Claude Code

[huangyiirene]

Claim: PM loop round 12
Session: session_01AmES43BMDg4bPrxTdi5q7t
Branch: claude/issue-8003-array-valued-query-slots-docblock
Worktree: objectstack-issue-8003
Domain: domain:metadata
File surface: packages/metadata-protocol/src/protocol.ts — region: the ARRAY_VALUED_QUERY_SLOTS docblock only (comment text; zero runtime change). (stop on breach; explain in the report)
Container & model: S mechanical, mode:subagent, model: sonnet
Serial constraints cleared: protocol.ts is hot and #8136 is claimed on it this round, but that card's declared region is client-facing message construction in error paths — disjoint from this docblock. Merge main before opening the PR and again if #8136 lands first; let the merge queue arbitrate, ⛔ do not hand-order.

skip-changeset applied — comment-only, releases nothing.

Verified on origin/main before dispatch: ARRAY_VALUED_QUERY_SLOTS is live at packages/metadata-protocol/src/protocol.ts:1763 with the #7321 survey docblock immediately below it. Confirm the exact stale sentence still reads as the card quotes it before editing — if it has already been corrected, that is a legitimate premise_still_valid: false with no PR.

---

Generated by Claude Code

[huangyiirene]

os-dev-report

{
  "issue": 8003,
  "status": "done",
  "branch": "claude/issue-8003-array-valued-query-slots-docblock",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/8151",
  "premise_still_valid": true,
  "summary": "Confirmed the stale `where` row read exactly as quoted in the issue at protocol.ts:1748-1751 on origin/main, then rewrote its last sentence: it now says arity for this slot is judged one layer up at the REST querystring ingress (assertFilterParamSuppliedOnce, #7390), that a repeated ?filter= on GET /data/:object never reaches this block, and names the sharper #7390 finding that ?filter=status&filter=%3D&filter=open spells a valid AST and succeeds with a filter nobody expressed. The first sentence (why a blanket refusal here would reject the AST body form) was kept unchanged. Diff is comment-only: 7 insertions, 2 deletions, one file.",
  "tests": "pnpm --filter '@objectstack/metadata-protocol^...' build: green (dependency closure, 13 packages). pnpm --filter '@objectstack/metadata-protocol' build: green (tsup ESM/CJS/DTS all succeeded). npx tsc --noEmit -p packages/metadata-protocol/tsconfig.json (package has no typecheck script, carries a measured DEBT ledger entry of 63 errors in scripts/check-type-check-coverage.mjs): re-measured at exactly 63 errors post-edit, matching the ledger baseline with no increase; grep confirmed none of the 63 are in protocol.ts itself (all in test files). npx eslint packages/metadata-protocol/src/protocol.ts --no-inline-config: clean, no output. node scripts/check-nul-bytes.mjs: OK (7421 files scanned). No test suite run beyond typecheck since this is a comment-only change with no behavior to cover.",
  "open_questions": [],
  "out_of_scope_findings": []
}

---

Generated by Claude Code

[huangyiirene]

ACCEPT — PR #8151.

Verified against GitHub rather than against the report:

• Scope honoured exactly. One file, +7/−2, and the diff is entirely inside the ARRAY_VALUED_QUERY_SLOTS docblock — the declared region. protocol.ts had two other claimed editors this round ([finding] metadata-protocol interpolates raw driver text into client-facing messages — three downstream sanitizers each have a hole because of it (option C of #8086) #8136 on error-path message construction, finding: ?preview=draft self-inflicts an invalid diagnostic — the injected _draft key is validated, so the read carries _diagnostics.valid:false #7656 on the _draft stamp sites); neither region was touched.
• The load-bearing sentence survived. The first sentence — why a blanket arity refusal here would reject the AST body form — is byte-identical in the diff. That was the half worth protecting, since fix(metadata-protocol): check query-parameter arity in findData's list-query normalizer (#7321) #7386's gate skips this slot because of it.
• The rewrite says what the card asked for: arity for this slot is judged one layer up at the REST querystring ingress (assertFilterParamSuppliedOnce, finding: a repeated ?filter= on GET /data/:object cannot be told from a filter AST, so it is diagnosed as a malformed filter (and, rarely, succeeds) #7390), a repeated ?filter= never reaches this block on GET /data/:object, and — the half the old text omitted entirely — ?filter=status&filter=%3D&filter=open spells a valid AST and succeeds with a filter nobody expressed. A future author reading this survey to decide whether a slot needs arity treatment is now told which layer owns it.
• finding: a repeated ?filter= on GET /data/:object cannot be told from a filter AST, so it is diagnosed as a malformed filter (and, rarely, succeeds) #7390's ruling respected: no runtime logic added or moved into packages/metadata-protocol. Enforcement stays in packages/rest.
• skip-changeset label present, no changeset file. Correct for a comment-only change — an empty-frontmatter changeset would have been rejected by the gate.
• TEST_DEBT handled properly. metadata-protocol has no typecheck script, so the dev ran tsc --noEmit directly and re-measured 63 errors, exactly matching the ledger baseline, with none in protocol.ts itself. That is the right shape: the ledger was measured, not assumed, and not raised.

Not flipping to ready yet — CI started one minute ago. Per this seat's standing rule I flip only once the gate-bearing jobs report completed: success on their own conclusions; "no failures yet" is not a conclusion. A flip checkpoint is armed.

---

Generated by Claude Code