[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, validated, and observed 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 the optimistic concurrency contract (resourceVersion/precondition required on status writes).
• Define conflict and stale-write error models for controllers.
• Define the 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 and 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.

Dependencies

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

Implementation Plan

1. #176 — Status subresource schema contract for core and CRD kinds
2. #177 — Status write boundaries and controller authorization enforcement (blocked by #176)
3. #178 — Concurrency and conflict semantics using resourceVersion preconditions (blocked by #176)
4. #179 — Integration tests and controller authoring guide (blocked by #177 and #178)

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.