[Initiative] API-Driven Namespace Creation and Lifecycle

[juliuskrah]

Summary

Implement API-driven namespace lifecycle management so namespaces can be created, listed, and deleted via service APIs. This establishes the namespace control plane required for namespace-scoped repository creation and multi-tenant isolation.

Parent initiative: #39

Scope

In Scope

• Add API endpoints (or GraphQL mutations/queries) for namespace creation, retrieval/listing, and deletion.
• Validate namespace identifiers (format, length, reserved names, uniqueness).
• Persist namespace metadata and audit fields (created_at, created_by, updated_at, updated_by).
• Enforce idempotent behaviour for create requests and deterministic errors for conflicts.
• Add simple authorisation checks so only permitted callers can create/delete namespaces.
• Add integration tests for create, duplicate create, delete, and invalid input scenarios.
• Document namespace API contract and examples in docs/.

Out of Scope

• Namespace federation or sharing across tenants.
• UI workflows for namespace management.
• Declarative namespace creation via manifest files similar to k8s. Tracked separately see [Initiative] Kubernetes-style Catalog Frontmatter #40
• Full enterprise IAM integration beyond current authorisation capabilities. Tracked separately see [Initiative] OIDC Integration Module #44, [Initiative] Headless User Management Module #45 [Initiative] Fine-Grained Authorization with OpenFGA/SpiceDB #50

Acceptance Criteria

• A client can create namespaces via API.
• Namespace names are validated and uniqueness is enforced.
• Duplicate create requests produce deterministic behaviour (clear conflict or idempotent success).
• Namespace deletion is auditable and respects authorisation rules.
• Integration tests cover create/list/delete and failure paths.
• Documentation includes API request/response examples.

Dependencies

• Subtask of: [Initiative] Namespaces #39
• Supports: [Initiative] API driven repository creation #67

Tracking

• Milestone: TBD