Declarative Namespace Resource Contract (.spec/.status)

[juliuskrah]

Summary

Define Namespace as a first-class declarative resource using Kubernetes-style .spec (desired state) and .status (observed state), and align API semantics to that contract.

This initiative complements #39 (namespaces introduced via API) and #40 (commerce catalogs via Kubernetes-style YAML). Controller reconciliation and bridging logic are tracked separately and remain out of scope here.

Scope

In Scope

• Define the canonical Namespace resource contract: metadata + .spec + .status.
• Define condition-based status semantics (for example: Ready, AdmissionAccepted, DeletionBlocked) with status, reason, message, and lastTransitionTime.
• Define API behavior for namespace .spec updates and status-subresource style .status updates.
• Define namespace watch semantics (ADDED, MODIFIED, DELETED) and resourceVersion expectations.
• Define validation and admission boundaries for create, update, and delete operations.
• Define tenancy and default rules:
  • policy-driven default namespace creation when none exists
  • auto-select when one namespace is available
  • explicit namespace selection when multiple namespaces exist

Out of Scope

• Controller-manager implementation details for reconciling namespace desired state.
• Cross-resource controller behavior that depends on namespace reconciliation internals.

Acceptance Criteria

• Namespace is documented as a declarative .spec/.status resource contract.
• Condition-based status model is defined (no dependency on .status.phase).
• API semantics for create, update, delete, and status updates are documented.
• Watch semantics and concurrency (resourceVersion) behavior are documented.
• Validation vs. admission responsibilities are documented for namespace operations.
• Follow-up implementation issues are created and linked.

Dependencies

• Depends on: [Initiative] Namespaces #39
• Complements: [Initiative] Kubernetes-style Catalog Frontmatter #40
• Related: [Initiative] Controller Manager Reconciliation Loop for Core Resources and CRDs #165, [Initiative] GraphQL Status Subresource Contract for Controllers #166, [Initiative] Git Event Publication and Admission Integration #169

Open Questions

• Chicken and egg problem: Namespace is a git-backed resource that is saved in a git Repository. A Repository has a Namespace as parent. How is this handled?
  • How should non-namespaced resources such as namespaces be handled?
• What system namespaces should be created
• Deletions and finalizers
• Are Owner References applicable here?
• Should the same considerations be applied to Repository Resource Contract: Kubernetes-style Declarative Markdown Schema #249?

Implementation Plan

1. #171 — Namespace resource contract (.spec/.status)
2. #172 — API semantics, status writes, and optimistic concurrency (blocked by #171)
3. #173 — Validation and admission matrix (blocked by #171)
4. #174 — Watch contract and resourceVersion resume semantics (blocked by #172)

Tracking

• Area: extensions
• Priority: p1 - critical
• Milestone: TBD