Expose workspace-role readiness on quilt3.admin's roles

[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. The registry's role types gain that field in
quiltdata/enterprise#1169, which is not merged yet. Without it, an admin
scripting against quilt3 cannot tell whether a role's users get its workspace
role or the fallback. With the data-products option on, the same registry
change makes a managed or built-in role's arn its derived workspace-role ARN,
known before that role exists. The spec change is quiltdata/quilt-specs#109
(The clients read readiness, on the decision Readiness is a field; the ARN
stays non-null).

What changed

• The shared schema's ManagedRole and UnmanagedRole carry
  workspaceRoleReady: Boolean! and the new description of arn, taken as
  enterprise#1169's own hunks at 52a214c0. The rest of that file's drift
  belongs to other registry changes and is not taken. The catalog's generated
  types follow, and nothing in the catalog reads the field.
• quilt3.admin.ManagedRole and UnmanagedRole carry workspace_role_ready,
  read 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 catalog/: npm run gql:generate && git diff --exit-code,
  npm run lint, npm run typecheck, npm test, and npm run build all pass.
• 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.
• Diffing shared/graphql/schema.graphql against enterprise's
  registry/quilt_server/graphql/schema.graphql at 52a214c0 leaves only the
  other changes' drift.
• test-lambda (shared) fails. The external W3C validator that its Excel
  preview test calls now reports a new message about <style scoped>. This
  change touches nothing under lambdas/, and the check passed on master at
  e6aef94e.

Links

• https://github.com/quiltdata/enterprise/pull/1169 is the registry change that
  serves the field. Merge after it; the schema copy is re-synced to its merge
  commit when it merges.
• 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. Known limit, left as it is: with the option on, while a
role is still being provisioned, the admin Roles page's "Open AWS Console" link,
built from arn alone, can open an IAM role that does not exist yet. Reverting
restores the previous schema copy, generated code and models.

The optionality note

Opens: scripts can report a role's readiness or wait on it, and the catalog can
read it later. 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 serving the new field is deployed, as the documented compatibility requirement specifies.

Summary

The PR exposes workspace-role readiness through the shared GraphQL schema and quilt3.admin role models, regenerates client types, and updates tests and documentation.

• Both managed and unmanaged roles now carry readiness in the Python client’s role selections and public results.
• Catalog generated types reflect the shared schema; Catalog does not yet select the field.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Registry[Registry role readiness] --> Schema[Shared GraphQL schema]
  Schema --> Selection[Python role selections]
  Selection --> Generated[Generated client models]
  Generated --> Admin[quilt3.admin role results]
  Schema --> Catalog[Catalog generated types]

Loading

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 56.32%. Comparing base (e6aef94) to head (9c5c8a4).

Additional details and impacted files

@@             Coverage Diff             @@
##           master    #5361       +/-   ##
===========================================
+ Coverage   38.41%   56.32%   +17.90%     
===========================================
  Files         753      874      +121     
  Lines       24866    37221    +12355     
  Branches     6794     6794               
===========================================
+ Hits         9552    20963    +11411     
- Misses      13553    14497      +944     
  Partials     1761     1761               

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

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.

[Copilot]

Copilot review overview

🟢 Approval recommended

All reviewed changes are synchronized generated or schema updates with no unresolved issues.

Review effort: Lite
Findings: None

What changed in this PR

Adds workspace-role readiness fields and updated ARN documentation to shared GraphQL role types, with synchronized catalog-generated artifacts.

Changes:

• Adds workspaceRoleReady to managed and unmanaged roles.
• Updates ARN documentation.
• Regenerates catalog GraphQL types and schema metadata.

File	Description
shared/​graphql/​schema.graphql	Adds readiness fields and ARN documentation.
catalog/​app/​model/​graphql/​types.generated.ts	Adds generated TypeScript fields.
catalog/​app/​model/​graphql/​schema.generated.ts	Updates generated schema metadata.

---

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

[nl0]

@greptileai re-review at head e2c4c3f, please — the description's Links now name the stacked quilt3 change, #5362; the code is unchanged.

[Copilot]

Copilot review overview

🟢 Approval recommended

The schema and generated artifacts are synchronized, with no runtime query changes or unresolved issues.

Review effort: Lite
Findings: None

[nl0]

@greptileai re-review at head 9c5c8a4, please — this now carries the whole clients change: quilt3.admin's role models expose workspace_role_ready, with the regenerated client, API reference and a changelog entry; title and description updated to match.

[Copilot]

Copilot review overview

🔵 Needs a closer look

The change spans shared schemas, generated artifacts, and Python API contracts with a required registry dependency and compatibility impact.

Review effort: Lite
Findings: None

[nl0]

On the compatibility impact the Copilot overview names: it is deliberate and stated in Risk and rollback and in the changelog entry. quilt3.admin's selections follow the registry they are generated against, as when #4690 added isService to the shared user selection, so a quilt3 release carrying this waits for stacks that serve the field. A fallback for older registries would be a new mechanism this change does not need.

[nl0]

Parked as a draft: the registry's readiness field this change reads moved to a later change. It stays here for when that change lands.