docs(postgres): document direct-policy semantics of user search aggregates

[rohilsurana]

Summary

SearchUserProjects / SearchUserOrganizations (admin search aggregates) return only resources the principal holds a direct policy on. The membership listing path (ListProjectsByUser etc.) additionally expands group-held policies and org-level inheritance — so an org admin with no direct project policies sees every org project in listings but zero in search.

This divergence is pre-existing and became visible once the listing semantics were made explicit in the membership package. After review, the decision is to keep both behaviors as-is and document them:

• the search aggregates answer "what is this principal explicitly granted" — the right semantics for an admin auditing direct grants
• the membership path answers "what can this principal access" — the right semantics for end-user listings

Mirroring membership's 3-way inheritance union into the aggregate SQL would add significant complexity for semantics that aren't clearly wanted in admin search; narrowing the listing path would regress end-user behavior.

Changes

Doc comments on UserProjectsRepository.buildBaseQuery and UserOrgsRepository.buildBaseQuery explaining the intentional divergence and warning against "fixing" one side to match the other without a product decision. No functional changes.

Test plan

• go build ./... and postgres repo tests pass (comment-only change)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
frontier	Ready	Preview, Comment	Jun 12, 2026 9:46am

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: bbadcf52-0b39-46e6-a724-411b54100f36

📥 Commits

Reviewing files that changed from the base of the PR and between ad53ea6 and d22d05c.

📒 Files selected for processing (2)

• internal/store/postgres/user_orgs_repository.go
• internal/store/postgres/user_projects_repository.go

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Enhanced internal documentation for repository query methods to clarify policy-level filtering behavior and intended scope differences.

Walkthrough

This PR adds clarifying documentation comments to two repository query methods. buildBaseQuery in the user organizations repository and buildBaseQuery in the user projects repository are documented to explain their intentionally narrower semantics: they return only direct org-level or project-level policy grants, deliberately excluding group-held and inheritance-based expansion that occurs in the broader membership listing paths.

Changes

Policy Query Method Documentation

Layer / File(s)	Summary
buildBaseQuery documentation clarification internal/store/postgres/user_orgs_repository.go, internal/store/postgres/user_projects_repository.go	Multi-line comments added to buildBaseQuery in both repositories explaining that each method returns only direct policy grants (org-level or project-level) and intentionally diverges from broader membership listing paths.

---

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

---

Possibly related PRs

• raystack/frontier#1648: Both PRs adjust documentation comments above buildBaseQuery in user_projects_repository.go to clarify the "direct policy only" semantics versus broader membership-based listing.

---

Suggested reviewers

• whoAbhishekSah

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coveralls]

Coverage Report for CI Build 27408055809

Coverage remained the same at 43.285%

Details

• Coverage remained the same as the base build.
• Patch coverage: No coverable lines changed in this PR.
• No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	37154
Covered Lines:	16082
Line Coverage:	43.28%
Coverage Strength:	12.3 hits per line

---

💛 - Coveralls