[Initiative] Hub-and-Spoke CRD Versioning with WASI Conversion Hooks

[juliuskrah]

Summary

Introduce a hub-and-spoke versioning model for CRD-style resources so Git manifests can evolve independently while GraphQL remains a single, continuously evolving endpoint.

Scope

In Scope

• Define per-kind Hub version semantics (single internal storage version).
• Add WASI conversion hook contracts for spoke-to-hub and hub-to-spoke transforms.
• Run write-time up-conversion in the ingest pipeline when pushed manifests use non-hub apiVersion.
• Keep KV projections and synthesised core GraphQL types normalised on hub-version state.
• Define GraphQL evolution rules for deprecated fields mapped from hub state.

Out of Scope

• Versioned GraphQL endpoints (for example /graphql/v1, /graphql/v2).
• Full federation rollout for core kinds (tracked separately).
• UI-level migration tooling for client applications.

Acceptance Criteria

• Every versioned kind can declare exactly one active Hub version.
• Conversion hooks are required before a breaking kind version can be activated.
• Pushes with older apiVersion manifests are accepted only when up-conversion succeeds.
• Stored/indexed read models remain hub-normalised after conversion.
• Schema generation supports backward-compatible field deprecations (@deprecated) for renamed/replaced fields.
• Operational telemetry is emitted for conversion success/failure and version-mismatch events.

Implementation Notes

• Why this is needed: Kubernetes-style resource versioning is explicit and transport-facing, while GraphQL prefers one graph that evolves over time. Hub normalisation preserves internal consistency without fragmenting the API surface.
• Hub-and-spoke mechanics: The Hub version is the canonical internal state. All non-hub versions are spoke representations converted at boundaries.
• Pipeline placement: Conversion should happen after parse and before admission/validation and projection, so policy checks run against canonical hub state.
• Backward compatibility: Deprecated GraphQL fields should resolve from hub data during migration windows to avoid breaking existing storefront or admin clients.
• Safety model: If conversion fails, reject the write with actionable diagnostics and avoid partial projection updates.

Dependencies

• Depends on [Initiative] Separate Markdown Parsing Layer from Catalog Validation #134 (parsing layer separation from validation).
• Depends on [Initiative] Dynamic GraphQL Schema Synthesis and Stitching for Custom Kinds #149 (dynamic schema synthesis and stitching baseline).
• Related to [Initiative] API Admission Controller (Validating Phase Only) #123 and ValidatingAdmissionPolicy Engine for Catalog Objects #106 (validating admission flow and contracts).

[juliuskrah]

Dependency notes: blocked by #134 for parse/validate separation; depends on #149 for runtime schema synthesis baseline; aligns with admission interfaces in #123 and #106.