[nl0]

The need

quilt3's admin API returns roles from quilt3.admin.roles, and on the users and
policies it returns. None of them says whether a role's workspace role is ready
to vend sessions on, which the registry adds in quiltdata/enterprise#1169 (not
merged yet). Without that, an admin scripting against quilt3 cannot tell whether
a role's users get its workspace role or the fallback. The spec change is
quiltdata/quilt-specs#109 (The clients read readiness). This stacks on
#5361, which takes the field into the shared schema.

What changed

• quilt3.admin.ManagedRole and UnmanagedRole carry workspace_role_ready,
  read from the registry's workspaceRoleReady wherever quilt3 reads a role:
  the roles API, a user's role and extra roles, and a policy's roles.
• The generated client and the API reference follow.

Verification

• In api/python/: uv run poe lint, uv run poe fmt --check,
  uv run poe test-cov (699 passed, 1 xfailed) and uv run poe gql-check all
  pass. uv run poe testdocs passes with 42 tests.
• tests/test_admin_api.py has a ready managed role and an unready unmanaged
  role, which the existing role, user and policy tests parse.
• The API reference is regenerated with uv run poe gendocs.

Links

• Expose workspace-role readiness on quilt3.admin's roles #5361 is the base, where the shared
  schema takes the field. This targets its branch and is retargeted to master
  once it merges.
• https://github.com/quiltdata/enterprise/pull/1169 is the registry change that
  serves the field. Merge after it.
• https://github.com/quiltdata/quilt-specs/pull/109 is the spec change.

Risk and rollback

quilt3's role selections now ask for the field. Against a registry that predates
enterprise#1169, every quilt3.admin call that returns a role, user or policy
therefore fails GraphQL validation. As with earlier additions to these
selections, a quilt3 release that carries this needs stacks that serve the
field. The two dataclasses gain a required field, which breaks code that
constructs them itself. Reverting removes the field from the selections and the
models.

The optionality note

Opens: scripts can report a role's readiness, or wait on it. Closes: quilt3's
admin client no longer runs against registries that lack the field.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge once the registry version serving the required field is available, as documented.

Summary

The PR exposes registry workspace-role readiness on quilt3 admin role objects, updates the generated GraphQL client and tests, and documents the new field and registry-version requirement. The latest change links the changelog entry to this PR.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Registry[Registry GraphQL workspaceRoleReady] --> Selection[Role selections]
  Selection --> Client[Generated client models]
  Client --> Admin[quilt3.admin role objects]

Loading

_{Reviews (2) · Last reviewed commit: "Link the changelog entry to its pull req..."}

[Copilot]

Copilot review overview

🔵 Needs a closer look

The changes require final human review because they are too complex or risky for automated approval.

Review effort: Lite
Findings: None

What changed in this PR

Adds workspace-role readiness to quilt3 admin role models and all relevant GraphQL selections.

Changes:

• Adds workspace_role_ready to managed and unmanaged roles.
• Updates generated GraphQL client code and queries.
• Updates tests, API reference, and changelog.

File	Description
docs/​CHANGELOG.md	Updated as part of this pull request.
docs/​api-reference/​Admin.md	Updated as part of this pull request.
api/​python/​tests/​test_admin_api.py	Updated as part of this pull request.
api/​python/​quilt3/​admin/​types.py	Updated as part of this pull request.
api/​python/​quilt3/​_graphql_client/​fragments.py	Updated as part of this pull request.
api/​python/​quilt3/​_graphql_client/​client.py	Updated as part of this pull request.
api/​python/​quilt3-graphql/​queries.graphql	Updated as part of this pull request.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 54.49%. Comparing base (e2c4c3f) to head (375d909).

Additional details and impacted files

@@                        Coverage Diff                        @@
##           dp-workspace-roles-readiness    #5362       +/-   ##
=================================================================
+ Coverage                         42.24%   54.49%   +12.25%     
=================================================================
  Files                               767      860       +93     
  Lines                             27099    34988     +7889     
  Branches                           6794     6794               
=================================================================
+ Hits                              11448    19067     +7619     
- Misses                            13890    14160      +270     
  Partials                           1761     1761               

Flag	Coverage Δ
api-python	94.00% <100.00%> (?)
catalog	38.41% <ø> (ø)
lambda	?

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[nl0]

@greptileai re-review at head 375d909, please — the changelog entry now links this pull request.

[nl0]

Folded into #5361, which now carries the whole clients change.