[kriszyp]

⊙ Problem

Two relationship-query rules changed in v5.4.0 (Keep an AND group's estimate finite when a sibling condition is filter-only), and the docs did not describe them:

• AND conditions on one to-many relationship must be met by one related record. In v5.3.5, name=Acme&products.name=Cable&products.price=ge=number:30 matched Acme even though its Cable costs 10. A collection DELETE with those conditions deleted Acme.
• A relationship condition inside an OR only decides which parents match. Text said an outer relationship filter always narrows select(). That is false for an OR.

🤔 Is the requirement right?

Yes. Both rules are on harper main; tests enforce them. The DELETE case alone makes the first rule worth calling out.

💡 Solution

• Add both rules beside the existing Join behavior text in REST querying and the Resource API. Each rule gets an example and a changed v5.4.0 badge. Look hardest at the OR rule's mixed AND case: it is the least obvious one.
• Limit the existing "outer filters narrow the selection" sentences to AND, on both pages and in the 5.4 release notes.

⚖️ Alternatives

🤔 The examples were run locally, not added to the fixture harness

The paired fixture must match harper main byte for byte. New cases would need a harper PR, which is outside this task. harper main's HTTP suite already runs the OR and DELETE cases on this same sample data.

🔧 Changes

• reference/resources/resource-api.md: two bold-lead paragraphs after Join behavior, each with a Brand.search example: same related record and OR decides parents only. The Join behavior, Constraining, nested-options and sort sentences now say the narrowing applies to and conditions. The rule paragraph also notes that a collection DELETE follows the same rule. The pending-release note now links harper#3724.
• reference/rest/querying.md: two #### subsections at the end of Nested Select with Joins, each with an http example: same related record and OR decides parents only. The join paragraph, the Filtering-and-Paging lead, the outer-sort paragraph and the nested option reference now say the narrowing applies to &. The pending-release note now links harper#3724.
• release-notes/v5-lincoln/5.4.md: the two rules, and an upgrade-impact sentence for queries and collection DELETE.

🤔 Prior-version results on reference pages

Each rule ends with one sentence on what v5.3.5 returned, so a reader still on 5.3 can see the difference. These sentences are easy to drop once 5.4 ships.

🤔 New text sits above the "not released yet" note

It relies on the VersionBadge, like the to-many sort paragraph on the same page.

✅ Verification

• I extracted every new request and both snippets from the Markdown and ran them against a scratch build of harper main @ 509ff2c78 and against harper@5.3.5 from npm, using the docs fixture schema and sample data. Each documented result matches, for main and for the v5.3.5 sentences.
• format:check, lint, typecheck, test:examples (13 pass; fixture parity also passes with HARPER_CORE_FIXTURE_ROOT set to harper main's copy), test:workflows and build all pass. The new anchors resolve in the built HTML.

Observed responses (main / 5.3.5)

Request	main	5.3.5
name=Acme&products.name=Cable&products.price=ge=number:30	[]	Acme
name=Acme&products.name=Keyboard&products.price=ge=number:30&select(id,name,products{name,price})	Acme [Keyboard]	Acme [Keyboard, Dock]
collection DELETE with the Cable conditions	nothing deleted	Acme deleted
(products.name=Cable|id=44)&select(id,products{name})	Acme: all 3; Studio Gear: both	Acme [Cable]; Studio Gear []
products.price=ge=number:30&(products.name=Cable|id=44)&select(...)	Acme [Keyboard, Dock]; Studio Gear [Stand, Monitor]	[]
products.name=Keyboard&products.name=Mouse	[]	[]
programmatic AND snippet / OR snippet	[] / as the OR row	Acme / as the OR row

_{🤖 Generated by Claude Opus 5.5; posted via @kriszyp.}

Related PRs: #775 overlaps (qualifies its to-many sort wording), #760 independent (edits other sections of resource-api.md)
Complexity: easy

Origin — the dispatch brief this PR was written from

Document same-record AND matching and OR-only-filters-rows for relationship conditions (harper#3724, v5.4)

Document two relationship-query rules that HarperFast/harper#3724 (merged 2026-11-02, release target v5.4) made order-independent. The current docs (reference/resources/resource-api.md ~1130-1222 "Join behavior" and nested relationship selection, reference/rest/querying.md "Relationships and Joins" and "Filtering and Paging Each Relationship") already describe HarperFast/harper#3775 (AND conditions on a to-many relationship restrict its select()) but not these rules:

1. Same related record. Conditions of one AND group on the same to-many relationship must all be met by ONE related record, whichever condition leads the query. Example: GET /Parent/?children.name=child 10&children.label=label 6 matches a parent only if a single child has both name child 10 and label label 6; a parent with one child named child 10 and another labelled label 6 does not match. Before #3724 the result depended on which condition the planner led with (a non-leading AND matched children separately); #3775 had pinned that, and #3724 changed it to same-record. Call this out as a v5.4 behavior change with a VersionBadge type="changed" version="v5.4.0". A to-one relationship trivially has one related record.
2. OR decides rows only. A relationship condition inside an OR (| in REST, operator: 'or' programmatically) decides which parent rows match; it does not restrict which related records select() returns for that parent. Example: ?(children.name=a|status=active)&select(id,children) returns matching parents with all their children, not only children named a. Contrast with the AND case, where the outer condition restricts the selected children.

Read the harper PR body and resources/DESIGN.md (the estimator/lead/scope/OR section added by #3724) and the tests unitTests/resources/relationshipConditionScope.test.js and the HTTP suite nested-relationship-docs.test.ts in HarperFast/harper main to confirm exact semantics before writing; do not document planner internals (lead selection, estimates). If the repo's scripts/fixtures/nested-relationship-docs examples harness can express these cases, add examples there so scripts/nested-relationship-examples.test.mjs checks them against a real server. Keep the existing page structure; add short subsections or bullets beside the existing Join behavior text in both pages rather than new pages.

Acceptance

Both rules documented in resource-api.md and rest/querying.md with one REST and one programmatic example each, marked as v5.4 behavior (VersionBadge); examples verified against harper main (via the nested-relationship examples harness if it fits, otherwise by running them locally and saying so in the PR body); docs build and existing example tests pass.

_{Dispatch: task documentation-relationship-and-or-same-record · queued by kris-session · ran by claude/opus/xhigh · worker kzyp-xps-1}

_{Ready-For-Promotion: 0781b67 urgency=normal late=none}

_{Review-Coverage: authored=claude; ran=gemini,cursor-composer,codex; adjudicated=domain; declined=cursor-grok,muse; rounds=2; full=1 @ 0781b67}

_{Review-Attention: skim ~2m (decisions: inline-prior-version-behavior, new-sections-above-pending-admonition) @ 0781b67}

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-779

This preview will update automatically when you push new commits.

[gemini-code-assist]

Code Review

This pull request updates the documentation for the Resource API, REST querying, and the v5.4 release notes to describe new behaviors in version 5.4.0 regarding nested relationship constraints. Specifically, it explains that AND-joined filters on the same to-many relationship must be met by a single related record, and that relationship filters inside an OR group only determine parent matches without restricting the returned related records. There are no review comments, so I have no feedback to provide.

[github-actions]

🧹 Preview Cleanup

The preview deployment for this PR has been removed.