[Initiative] API Admission Controller (Validating Phase Only)

[juliuskrah]

Summary

Define the admission control interface contract for GitStore catalog writes, aligned with Kubernetes admission semantics but limited to the validating phase only for this initiative.

GitStore will not implement mutating admission in this initiative. The goal is to establish a stable admission request/response interface that downstream work can implement and consume.

This issue is a parent initiative for existing validation work in #105 and establishes the interface dependency needed by #106.

In Scope

• Define the admission flow contract for gitstore-api validation requests and responses.
• Explicitly model Kubernetes-style two-phase semantics in documentation, while implementing only phase 2:
  • Phase 1 (mutating): documented as unsupported in this initiative.
  • Phase 2 (validating): supported and defined as the active path.
• Specify canonical interface types for validating admission:
  • Admission request envelope (resource identity, operation, object payload, context)
  • Admission response envelope (allowed, structured status/errors, diagnostics)
• Define validation result semantics for Git pushes and API-driven write paths.
• Define compatibility expectations so policy engines (e.g., ValidatingAdmissionPolicy Engine for Catalog Objects #106) consume the same interface.
• Document extension points for future mutating support without breaking this contract.

Out of Scope

• Mutating admission controllers or object mutation pipelines.
• Policy authoring UX or external policy engines.
• Broad non-catalog admission use cases outside current GitStore scope.

Acceptance Criteria

• A written admission interface spec exists for GitStore validating admission.
• The spec explicitly states mutating admission is unsupported in this initiative.
• Request and response schemas are defined with required fields and error semantics.
• The interface is suitable for both git hook admission and API pre-flight admission checks.
• Interface-level conformance requirements are documented for downstream implementations.
• [Initiative] Catalog Validation in gitstore-api #105 is tracked under this parent initiative.
• ValidatingAdmissionPolicy Engine for Catalog Objects #106 is explicitly dependent on this initiative's interface definition.

Implementation Notes

• Follow Kubernetes admission model terminology where useful (AdmissionRequest, AdmissionResponse) while keeping GitStore scope minimal.
• Keep this initiative focused on contract definition and validating semantics only.
• Downstream initiatives can implement concrete validators and policy engines once this interface is finalized.

Dependencies

• Required by: ValidatingAdmissionPolicy Engine for Catalog Objects #106
• Blocked by: [Initiative] Kubernetes-style Catalog Frontmatter #40

Tracking

• Milestone: TBD