Pin element-scoping semantics of queries over array-valued properties

[kriszyp]

Pins the element-scoping semantics of queries over array-valued (elements) properties, verifying the two open questions from the RQL 2.0 element-scoped-matching assessment. Tests plus a DESIGN.md row only — no production-code changes.

Chained conditions are same-element scoped on both execution paths. prepareConditions collapses a chained condition (a=ge=X&=le=Y) into a single range comparator before execution, so the indexed path (one range scan over per-element index entries) and the unindexed path (per-element some over the collapsed predicate in attributeComparator) agree: for {skiLengths: [172, 174, 181]}, ge=175&=le=180 correctly does NOT match (no single element is inside the range), while the independent form skiLengths=ge=175&skiLengths=le=180 correctly DOES (181 and 172 witness the legs separately). filterByType never sees chainedConditions — there is no path that silently drops a leg; unsupported chain shapes (|=, non-range comparators, a second &= leg) are rejected loudly.

contains over an array is a per-element toString() substring test for string and numeric elements alike, and never scans by range (full-scan filter on both paths), so indexed and unindexed attributes agree on membership.

Queries run through a real RequestTarget (the object REST constructs from the query string), so the error-path assertions pin the SyntaxViolation messages REST clients actually receive, and fixtures sit on both range bounds so ge/le vs gt/lt inclusivity is exercised exactly.

Three defects were found during verification and filed; each is pinned at current behavior (the raw duplicated index-scan output doubles as the observable proof that the per-element index served the query) with a skipped twin asserting the correct behavior:

• Refs REST chained range conditions (a=ge=X&=le=Y) never coerce the chained leg's value — silent superset or empty results on numeric attributes #2433 — REST chained-leg values are never type-coerced: the collapse builds a mixed-type range ([175, "180"]), silently returning a superset or an empty set on numeric attributes depending on leg order (number:-prefixed values work).
• Refs Indexed multi-value (elements) attributes return one result per matching element — duplicate records from range/contains queries #2434 — index-driven scans over elements attributes yield one result per matching index entry, so a record with two in-range elements comes back twice; the unindexed path returns it once.
• Refs Chained-condition error paths: second &= leg unparseable, |= chain → 500 with wrong message, parseQuery TypeError without query arg #2435 — chained-condition error paths: a second &= leg is unparseable (tokenizer-state fallback), |= chains throw a plain-Error 500 with a wrong message, and parseQuery(str) without a query object crashes with a TypeError on any parse error.

Also adds a Q&A row to resources/DESIGN.md documenting the chain-collapse invariant and pointing at this suite.

For the human reviewer

• Tests titled pins harper#NNNN assert today's wrong results on purpose so the suite stays green until the defect is fixed — at that point they fail loudly and their it.skip twins take over. If you'd rather not pin wrong behavior at all, deleting the pins and keeping only the skipped twins is a small change, at the cost of losing the only green signal that the per-element index (not a table scan) serves these queries.
• The review's decision ledger flags that this PR freezes three behaviors as documented contract: same-element chaining, independently-existential repeated conditions, and numeric contains matching by decimal string. All three match the RQL 2.0 direction, but a human should confirm they are meant to be durable API surface.
• The independent-conditions indexed test uses unique ids (not raw dup counts) because which leg leads the scan is estimate-dependent; the deterministic dup pins live on the single-condition tests.

Verification

• npx mocha unitTests/resources/query-array-scoping.test.js — 17 passing, 4 pending (the skipped defect twins).
• npm run test:unit:resources — 1892 passing, 27 pending, 0 failures.
• End-to-end route: the tests drive RequestTarget → Table.search, the same parse/plan/execute layers REST requests traverse; behavior was additionally probed with programmatic condition shapes, scalar and array attributes, indexed and unindexed.
• Prettier + lint:required clean.

Refs #2433, #2434, #2435

—Claude Fable

🤖 Generated with Claude Code

_{Review-Coverage: authored=claude; ran=codex; blocked=gemini(auth); declined=cursor-grok,cursor-composer,domain; rounds=3 @ 91c8232}

_{Human-Review-Need: 3 @ 91c8232}

[gemini-code-assist]

Code Review

This pull request documents the behavior of chained conditions over array values (SAME-ELEMENT scoping) in DESIGN.md and adds a comprehensive test suite in query-array-scoping.test.js. The review feedback correctly identifies style guide violations in the new test file, specifically recommending the use of the 'node:' prefix for the assert module import and advising the use of explicit strict assertions (assert.strictEqual and assert.deepStrictEqual) instead of loose ones.

[claude]

Reviewed; no blockers found.