[Initiative] Tag-Gated Sync Controller for Atomic Release Promotion

[juliuskrah]

Summary

Implement a tag-gated Sync Controller that reconciles Git-tagged catalog state into the live Scylla-backed projection, with atomic promotion and rollback.

The objective is to make release tags the production gate: controllers hydrate and validate tagged state, then atomically flip the active pointer so storefront reads move to a known-good snapshot.

In Scope

• Define the Sync Controller contract that reconciles from Git tags (not branch HEAD) into read-side state.
• Support release-triggered hydration of tagged catalog snapshots.
• Add atomic promotion semantics (single pointer/snapshot switch) after validation passes.
• Support rollback by retargeting to an earlier tag and reconciling to that snapshot.
• Define validation failure behavior so rejected releases never become live.
• Add integration tests for promote, failed promote, and rollback flows.
• Document operational runbooks for release and rollback.

Out of Scope

• CI/CD pipeline authoring for release tags.
• Mutating admission or schema evolution mechanics.
• Replacing Git as source of truth.
• Frontend release UX.

Acceptance Criteria

• Sync only promotes state from explicit release tags.
• Tagged snapshot hydration occurs before live-state promotion.
• Promotion to live state is atomic from reader perspective.
• Rollback to a previous release tag is supported and tested.
• Failed validation prevents promotion and surfaces actionable diagnostics.
• Docs include release/rollback commands and troubleshooting guidance.

Area

infra

Priority

p2 – high

Target Milestone / Release

TBD

[juliuskrah]

Dependencies

• Depends on: [Initiative] Controller Watch API with resourceVersion Resume #131 (Watch API — Sync Controller subscribes to release-tag events via the Watch stream)
• Depends on: [Initiative] Datastore Backend: ScyllaDB with Migrations #102 (ScyllaDB — live projection state is stored in ScyllaDB)
• Depends on: [Initiative] Implement In-Process git-receive-pack Hook Pipeline #110 (Hook pipeline — post-receive hook emits the tag event that triggers reconciliation)
• Related to: [Initiative] Optional KV-Optimized Catalogue Read Layer #112 (KV read-layer — atomic promotion flips the active snapshot pointer in the read layer)