refactor(perm): single permitted_org seam for the §5.3 dual read (audit)

[vecchp]

What & why

The audit's structural finding (D-1 / the "cleaner design"): the dual read was one
adapter per consumer (HasOrgPermOrGrant, HasPermOrGrant,
report_org_for_user, get_user_permitted_org_dual), each re-deriving "legacy OR
grant" — which is exactly how the C-0/C-8-class misses happened (the sweep forgot a
consumer). This collapses them into one seam:

• common/permissions/selectors.py — permitted_org(user, perm, *, org_id):
  the single org-scoped transition seam. Legacy arm = permissioned_queryset
  (single-join EXISTS) .first() — one query on the common path (pinned member-query
  counts preserved); grant arm = can() (can() never implies existence, so the org
  is re-fetched by pk). Plus has_authority_anywhere (has_perm OR can_anywhere)
  for the member queries' global tier.
• accounts/extensions.py — HasOrgPerm is the dual extension now
  (delegates to permitted_org); HasOrgPermOrGrant is deleted. Schema directives
  revert from @hasOrgPermOrGrant back to @hasOrgPerm (less FE/codegen churn
  at every future slice). HasPermOrGrant's checker delegates to
  has_authority_anywhere.
• reports/permissions.py / accounts/permissions.py — report_org_for_user
  and get_user_permitted_org_dual delegate to permitted_org.

Role-backing a template no longer has to coincide with cutting every consumer over —
every consumer reads the seam, so a domain can land independently, and the legacy
arm is deleted once, from permitted_org, at phase 5. The read predicate
(scopes/visible/can) stays pure-grant; only this transitional org-scoped check
is dual.

Changes

• common/permissions/selectors.py — permitted_org + has_authority_anywhere
• accounts/extensions.py — HasOrgPerm dual; delete HasOrgPermOrGrant
• accounts/permissions.py, reports/permissions.py — delegate to the seam
• teams/schema.py, reports/schema.py, accounts/schema.py — @hasOrgPerm
• schema.graphql — regenerated

Verification

• accounts/common/shelters/teams/reports: 1131 passed (incl. pinned member-query counts)
• ruff format/check clean; mypy strict clean

Summary by Sourcery

Centralize the §5.3 dual-read authorization logic so all organization-scoped consumers transition consistently from legacy permissions to grants.

Enhancements:

• Centralize transitional organization-scoped legacy-or-grant authorization behind a single permission selector seam.
• Update organization-scoped permission extensions and consumers to use the shared transition logic while preserving the existing @hasOrgPerm schema directive.
• Add a shared global authority check for member-management permission tiers.

Chores:

• Regenerate the GraphQL schema for the updated permission directive description.

[sourcery-ai]

Sorry @vecchp, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 1 day and 5 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[sourcery-ai]

Reviewer's Guide

Consolidates all transitional organization-scoped legacy-or-grant authorization behind permitted_org (with a shared global-tier helper), makes HasOrgPerm the sole dual-read GraphQL extension, updates consumers and the generated directive schema, and preserves the documented query-count and authorization behavior.

File-Level Changes

Change	Details	Files
Centralize the §5.3 legacy-or-grant authorization transition behind shared selector seams.	Add permitted_org using the legacy permissioned queryset first, then grant authorization with an explicit organization existence fetch. Add has_authority_anywhere for global legacy permission plus grant-anywhere checks. Route report and member-management permission helpers through the shared org-scoped selector.	apps/betterangels-backend/common/permissions/selectors.py apps/betterangels-backend/accounts/permissions.py apps/betterangels-backend/reports/permissions.py
Make the existing organization permission extension the transitional dual-read implementation and remove the duplicate extension.	Change HasOrgPerm to evaluate each requested permission through permitted_org, preserving any/all semantics and denial behavior. Delete HasOrgPermOrGrant. Delegate the global permission checker’s grant fallback to has_authority_anywhere.	apps/betterangels-backend/accounts/extensions.py
Update GraphQL consumers to use the stable @hasOrgPerm directive and regenerate the schema.	Replace extension imports and usages across account, team, and report schemas. Rename the generated directive and update affected fields in schema.graphql.	apps/betterangels-backend/accounts/schema.py apps/betterangels-backend/teams/schema.py apps/betterangels-backend/reports/schema.py apps/betterangels-backend/schema.graphql
Apply formatting-only cleanup to a report regression test.	Reflow the test function signature without changing its behavior.	apps/betterangels-backend/reports/tests/test_views.py

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[vecchp]

Closing: refactor of the permitted_org single-seam that main never adopted (main = per-domain can()/require_can). Base is the dead §5.3 stack; superseded by #2443's architecture.