Add detailed lists, PDP refresh, user-permissions context and API coverage report

[zeevmoney]

Linear issues

• PER-16337: the remaining P1 API additions (detailed lists, PDP data refresh, a context for get_user_permissions) and the coverage report.
• PER-16336: section 7, "Full compatibility with the Permit backend", whose coverage and drift report this implements for permit-python.
• PER-16737: the P2 items, listed in the report's allowlist as deferred to this ticket.
• PER-16338: the PDP's facts pass-through keeps only the last value of a repeated query parameter; the list()/list_detailed() docstrings say so.

Why

Before this PR, the SDK:

• could not list role assignments or relationship tuples in detail;
• reached detailed resource instances only through the API's deprecated detailed flag;
• could not trigger a PDP data refresh;
• sent no context with get_user_permissions(), so ABAC policies could not read request context there.

Nothing showed which API operations the SDK covers, or noticed when the API gained an operation the SDK neither covers nor excludes on purpose.

What changed

SDK (async and blocking clients, permit/_sync_types.pyi regenerated)

• list_detailed() on permit.api.role_assignments, resource_instances and relationship_tuples.
  • Each sends GET .../detailed with the filters of that module's list(), as keyword-only arguments, and returns the paginated detailed model.
  • list() and list_detailed() build their query with one shared helper per module, and an offline test checks that both send the same query string.
  • Docstrings state the key scope. The two role_assignments docstrings say that with proxy_facts_via_pdp a list filter keeps only its last value.
• resource_instances.list(detailed_key=...) sends the same request as before, and now issues one DeprecationWarning naming list_detailed() and permit 4.0.
  • The warning points at the caller's line on both clients.
  • A call without detailed_key does not warn.
  • The caller-attribution code moved into a private helper that deprecated() also uses. Its behaviour is unchanged.
  • New README Deprecations entry.
• permit.api.pdps.refresh(reason=None), in a new pdps module. It sends POST /v2/pdps/{proj_id}/{env_id}/configs/refresh, and always goes to the API, even with proxy_facts_via_pdp.
  • The docstring says it triggers a data refresh on every PDP in the environment and returns once the refresh is triggered, not once the PDPs finish.
  • It needs an environment-level key with write or admin access, or a broader key with the API context set to the environment.
  • It lists every error: a ValidationError for a reason over 512 characters (nothing is sent), and API 403, 404 and 422.
  • PDPDataRefreshRequest and PDPDataRefreshResponse come from scripts/generate_models.sh output, and their two schema-drift allowlist entries are removed.
  • The sync parity test's sub-API count goes from 18 to 19.
• get_user_permissions(..., context=None) on the Enforcer, permit.Permit and permit.sync.Permit.
  • A context is merged over the context store the same way check() merges it.
  • Without one, the request bytes are unchanged.
  • context={} sends the store's base context alone.
• The sync stub generator sorts imported names case-insensitively, as ruff does. The generated stub is unchanged for existing names.
• README sections for the three additions.

API coverage report

• Recorder. tests/api_coverage_recorder.py is a pytest plugin loaded from tests/conftest.py.
  • It does nothing unless given a record file (--api-coverage-record or PERMIT_API_COVERAGE_RECORD).
  • When enabled, it writes the method, raw path, status, test id and e2e flag of every request the SDK sends. No query strings, headers or bodies are recorded.
• Report script. .github/scripts/api_coverage.py is stdlib only.
  • It matches each recorded request to a spec operation template.
  • It lists covered, missing, excluded, deferred, untested and SDK-only operations, split by GA, EAP and deprecated, for the control plane and the PDP.
  • The end-to-end column shows "not run" when there is no e2e record.
  • Exit 0 is a pass and exit 1 a failure: an untriaged GA operation, a stale or restaged allowlist entry, or an unexplained SDK-only request.
  • Exit 2 means the report did not run: an unreadable spec, too few operations, an invalid allowlist, or a record that is missing, unfinished, from a failed session, or under 400 requests. It is never shown as clean.
• Snapshots. .github/api-specs/ holds the operation inventories of the control-plane spec (263 operations) and of the pinned PDP image's spec (34 operations), each with a source file. A script test fails when PINNED_PDP_IMAGE and the PDP snapshot's source name different images.
• Allowlist. .github/scripts/api_coverage_allowlist.json has 224 operation entries and 16 sdk_only entries, each with one reason:
  • PER-16337's DEFER and EXCLUDE lists;
  • the 11 P2 operations, deferred to PER-16737;
  • 65 untested operations (the SDK has a method, but no offline wire test sends its request yet; PER-16177);
  • proxy-mode routes the PDP forwards but does not list (PER-16338).
• CI.
  • A new API Coverage job in test.yml runs on every PR (not path-filtered, needs pytest, runs unless cancelled). It publishes the report as the job summary and the api-coverage-report artifact.
  • The pytest lanes record their requests and upload them, for the e2e column.
  • The new weekly api-coverage.yml checks the live control-plane spec, uploads a ready replacement snapshot, and alerts Slack like schema-drift.yml does.
  • The Audit Script Tests job runs the new script tests.
• CONTRIBUTING.md has an "API coverage report" section, and its PDP pin and e2e sections mention the snapshot and the record variable.

Behaviour changes

• New public methods: list_detailed() (three modules), permit.api.pdps.refresh(), and the context argument of get_user_permissions(). import permit also exports the two new generated models.
• resource_instances.list(detailed_key=True or False) now issues a DeprecationWarning. Under pytest's warnings-as-errors this fails a consumer's test until it switches to list_detailed().
• ApproveMessage is regenerated from the live spec, which renamed its only field from message to detail. No SDK method returns this model, but code that reads ApproveMessage.message must read detail instead.
• No other runtime change. The recorder plugin does nothing in a normal test run.

How it was tested

• Offline suite: 661 passed, 3 skipped, 0 warnings on pydantic 2.13.5 and on pydantic 1.10.26 (base: 545 passed, 3 skipped). New offline wire tests pin the exact method, path, query, headers and body of every new call on both clients.

• Types: mypy clean on both lanes (107 files), and tests/test_typing_surface.py 4 passed on each. The consumer type-check fixture covers the new methods, and asserts that positional arguments to list_detailed() are a type error.

• Tooling: all pre-commit hooks pass, uv lock --check passes, actionlint and zizmor report nothing.

• CI script tests: 223 passed, 115 of them for the coverage report.

• Coverage report on a fresh record from each lane: exit 0, from 707 offline requests sent by 664 tests.

  • Control-plane GA: 213 = 61 covered + 70 excluded + 22 deferred + 60 untested.
  • PDP GA: 33 = 12 covered + 15 excluded + 1 deferred + 5 untested.

• Gate, run on scratch copies:

  • a new GA operation planted in the snapshot: exit 1;
  • a stale allowlist entry: exit 1;
  • an empty, short, unfinished or missing record: exit 2;
  • an unreadable spec: exit 2;
  • the weekly sequence against the live spec: exit 0, and the live inventory equals the snapshot.

  Tests for these cases are kept.

• Mutation testing: the new tests and gates were checked by breaking the code each one guards. Every mutant failed a test, including the report's default minimums, the 2xx-or-3xx edge of the e2e column, its "not run" cells and the PDP pin check.

• E2e: 42 e2e tests collect. The 9 new ones have not run against a real backend; CI runs them. The e2e column has been checked only with synthetic records so far.

Owner actions before merge

• Watch the new e2e tests in the container-PDP pytest lanes, and test_get_user_permissions_with_a_context in the cloud-PDP job.
• Decide whether API Coverage becomes a required status check.

🤖 Generated with Claude Code

[linear-code]

PER-16337

[github-actions]

Dependency Security Audit

Scanned: pyproject.toml dependencies + dev group, resolved at Python 3.10 (the current resolution, and the lowest versions the published specs permit under each pydantic major)

✅ No known vulnerabilities found.

Both the resolved dependency set and the lowest versions the published specs permit are clean at HIGH and CRITICAL.