[Initiative] GraphQL Status Subresource Contract for Controllers

[juliuskrah]

Summary

Define a first-class status-subresource contract in GraphQL so standard controllers can report observed state safely without violating desired-state ownership boundaries.

This initiative codifies how .status updates are represented, authorized, and validated for both core resources and CRD kinds.

Scope

In Scope

• Define GraphQL mutation contracts for status updates by resource kind.
• Enforce status-only write boundaries (controllers can update .status, not .spec).
• Define optimistic concurrency contract (resourceVersion/precondition required on status writes).
• Define conflict and stale-write error model for controllers.
• Define authorization model for controller identities to update status.
• Add integration tests for status success path, forbidden spec mutation attempts, and stale version conflicts.
• Document status field ownership patterns for controller authors.

Out of Scope

• Redesign of core spec schemas.
• End-user storefront subscriptions.
• Mutation admission phase changes beyond status ownership enforcement.
• External federation routing.

Acceptance Criteria

• Status mutation contract is documented for core + CRD resources.
• API rejects attempts to mutate .spec through status endpoints.
• API requires and enforces concurrency preconditions for status writes.
• Conflict responses are deterministic and actionable for retry loops.
• Integration tests cover authorization, conflict, and boundary enforcement.
• Controller authoring docs include status ownership rules and retry guidance.

Implementation Notes

• This initiative is the API-level equivalent of Kubernetes status subresources.
• Status updates should be lightweight and frequent; keep payload shape focused on observed fields.
• The contract must integrate with the watch stream so each accepted status update emits the next MODIFIED event with incremented resourceVersion.

Dependencies

• Depends on: [Initiative] Object Lifecycle Versioning Contract for UID and resourceVersion #137 (Object Lifecycle Versioning Contract), [Initiative] Controller Watch API with resourceVersion Resume #131 (Controller Watch API with resourceVersion Resume)
• Related: [Initiative] API Admission Controller (Validating Phase Only) #123 (API Admission Controller), [Initiative] Query Handler Chain of Responsibility for Standard and Extension Kinds #148 (Query Handler Chain), [Initiative] Dynamic GraphQL Schema Synthesis and Stitching for Custom Kinds #149 (Dynamic GraphQL Schema Synthesis and Stitching), [Initiative] Controller Manager Reconciliation Loop for Core Resources and CRDs #165 (Controller Manager Reconciliation Loop for Core Resources and CRDs)

Tracking

• Area: infra
• Priority: p2 - high
• Target Milestone / Release: TBD

[juliuskrah]

Dependency note: Blocked by #165 (controller manager runtime), #131 (resourceVersion watch/resume), and #137 (object lifecycle versioning). This initiative defines API status-write boundaries consumed by controllers created in #165.