[Initiative] Git Event Publication and Admission Integration

[juliuskrah]

Summary

Define a complete event taxonomy and publication contract for gitstore-git-service to emit so that the API control plane (admission controller, policy engine, and controller manager) can reconcile catalog state and enforce policies consistently.

This initiative clarifies which Git operations trigger which control-plane workflows and how draft vs. published state transitions are governed.

Scope

In Scope

• Define canonical Git event types across standard operations (push, branch lifecycle, tag lifecycle, rejection).
• Define catalog-specific events: resource parsed, validation failed, namespace target detected, admission policy evaluation.
• Define event payload contract (ref details, commit SHA, actor identity, policy metadata).
• Define which events are fire-and-forget vs. require acknowledgement/blocking.
• Define how pre-receive events feed into admission validation vs. post-receive events trigger reconciliation.
• Define the draft-vs-published lifecycle: when tags or special branches gate state transitions.
• Document when admission checks run for Git-originated mutations vs. API-originated mutations (should be identical paths).
• Add integration tests covering event emission, event ordering, and duplicate suppression.

Out of Scope

• Webhook delivery to external systems (that's event subscription).
• Real-time metrics/dashboards on event rate.
• Event retention/archival beyond what Git history provides.
• Mutating webhook controllers (that's admission controller scope).

Acceptance Criteria

• Event type taxonomy is documented with clear semantics for each event.
• Payload schema is defined for each event type (ref, commit, actor, policy metadata).
• Pre-receive vs. post-receive event flow is documented (blocking vs. asynchronous).
• Draft-vs-published state transitions are tied to specific events (e.g., tag creation for releases).
• Admission controller integration is documented: how Git events trigger the same validation as API mutations.
• Controller manager integration is documented: which events trigger reconciliation start.
• Integration tests cover all event types, ordering, and duplicate suppression.
• Runbooks document troubleshooting stale/missing events and replay scenarios.

Implementation Notes

Event Classification

Standard Git Ref Events (always fire post-receive):

• branch-created: ref moved from 0000000 to commit_sha, refs/heads/*
• branch-updated: ref moved commit_a → commit_b (fast-forward)
• branch-force-pushed: ref moved commit_a → commit_b (non-fast-forward, history rewrite)
• branch-deleted: ref moved commit_sha → 0000000, refs/heads/*
• tag-created: ref moved 0000000 to object_sha, refs/tags/*
• tag-updated: ref moved old_object → new_object, refs/tags/*
• tag-deleted: ref moved object_sha → 0000000, refs/tags/*
• push-rejected: push failed pre-receive hook (includes failure reason)

Catalog-Specific Events (post-receive, async):

• catalog-resource-parsed: A .md file was parsed into a resource object (Product/Category/Collection/etc).
• catalog-resource-validation-failed: A parsed resource failed schema or admission policy validation.
• catalog-namespace-target: Detected which namespace owns the repository or affected resource.

State Transition Events:

• release-created: A tag matching the release pattern (e.g., release/* or v*) was created AND admission checks passed.
• draft-published: A release tag or special marker moved a draft resource into published state (visibility to storefront).

Draft vs. Published Lifecycle

Draft state:

• Commits on main or draft branch create/update resources that are draft (.status.phase == draft).
• Draft resources are visible to admins but not storefront.
• Draft resources reconcile independently (e.g., inventory controller tracks draft inventory separately).

Publishing:

• Admins (or CI/CD policy) create a release tag (release/v1.0.0) pointing to a commit.
• Tag creation triggers post-receive hook, which:
  1. Emits tag-created event.
  2. Runs the target commit's resources through admission (same validation as Git push).
  3. If admission passes, emits release-created event.
  4. Controller manager observes release-created → transitions .status.phase to published.
  5. KV layer updates so storefront sees published state.

Admission Control Integration

Git-originated mutations (push) and API-originated mutations (GraphQL) must follow the same admission path:

• Pre-receive hook: syntax/auth checks only (fast-fail rejections).
• Post-receive hook (async): parse resources → run admission policies → write .status via API.
• Admission response: structured errors, policy metadata, resource version for optimistic concurrency.

If admission rejects on post-receive, the commit is persisted but marked in .status.admissionFailure. The operator sees the commit in Git history (audit) but the resource is not visible to controllers/storefront.

Dependencies

• Depends on: [Initiative] API Admission Controller (Validating Phase Only) #123 (API Admission Controller), [Initiative] Controller Manager Reconciliation Loop for Core Resources and CRDs #165 (Controller Manager Reconciliation Loop), [Initiative] Universal ScyllaDB Resource Table for CRD-Style Resources #140 (Universal ScyllaDB Resource Table)
• Related: [Initiative] Separate Markdown Parsing Layer from Catalog Validation #134 (Separate Markdown Parsing Layer), [Initiative] gRPC GitEvent Notification Stream from gitstore-git-service to gitstore-api #139 (gRPC GitEvent Notification Stream), [Initiative] Controller Watch API with resourceVersion Resume #131 (Controller Watch API)

Tracking

• Area: infra
• Priority: p2 - high
• Target Milestone / Release: TBD

[juliuskrah]

Dependency note: Blocked by #123 (admission controller semantics), #165 (controller manager must consume events), #140 (universal resource table for draft/published state tracking). Related to #134 (parsing), #139 (gRPC event stream), #131 (watch API for downstream consumption).

[juliuskrah]

Clarifications and Corrections

1. The reconciliation flow is captured in architecture.md

The sequence diagram is in the ## Controller Manager, Reconciliation Loop, and AI Integration section of docs/architecture.md. The draft-vs-published lifecycle described in this issue's Implementation Notes should also be reflected there — updating now.

---

2. Schema validation at pre-receive — corrected model

The K8s approach separates validation into three distinct layers, each with different properties:

Layer	Timing	Where in GitStore	Characteristics
Structural / schema validation	Synchronous	Pre-receive (selective) + post-receive (full)	Static, deterministic, local
Built-in API validation	Synchronous	Post-receive, API handler	Compiled logic (e.g., sku uniqueness, productName exists)
Admission validation	Asynchronous	Post-receive, policy engine	Dynamic, policy-oriented, may be org/external-aware

What pre-receive should do:

• Auth, branch/tag protection, quota (must always be here — fast, no parsing).
• Lightweight structural pass: is the file valid YAML? Are top-level fields (apiVersion, kind, metadata, spec) present and the right type? Is apiVersion a known registered group?
• This is the equivalent of K8s decoding — not schema validation.

What pre-receive should NOT do:

• Full JSON Schema / OpenAPI validation against the CRD spec (expensive, requires full parse).
• CEL rule evaluation.
• Cross-reference checks (productName exists, sku is unique).

What post-receive does (async pipeline):

• Full schema validation: field types, CRD constraints, min/max, required fields.
• CEL-based field rules (equivalent to x-kubernetes-validations).
• Cross-object validation (parent reference resolution, uniqueness).
• Admission policies: org policy, quota by namespace, CEL admission expressions.

Reasoning: Pre-receive must return in under ~200ms for a good push UX. Full schema validation on every changed .md file in a large push would blow that budget. The tradeoff is that the developer gets fast structural feedback from pre-receive, then detailed semantic feedback asynchronously from post-receive (visible in resource .status.conditions).

---

3. .status.phase is an anti-pattern — replaced with conditions

Kubernetes API conventions and kubernetes/kubernetes#7856 explicitly flag phase as deprecated because it is:

• An opaque enum that blocks extension without breaking changes.
• Hard to compose (a resource cannot be in "published" and "admission-failed" simultaneously under a flat phase).

Replacement: typed conditions

status:
  conditions:
    - type: Published
      status: "True"           # or "False"
      reason: ReleaseTagApplied
      message: "Published at release/v1.0.2"
      lastTransitionTime: "..."
    - type: AdmissionAccepted
      status: "True"
      reason: PolicyPassed
      lastTransitionTime: "..."
    - type: Ready
      status: "True"
      reason: ResourceProjected
      lastTransitionTime: "..."

This maps directly to the K8s condition model and composes cleanly:

• Published=False + AdmissionAccepted=False → rejected, not visible.
• Published=False + AdmissionAccepted=True → valid draft.
• Published=True + AdmissionAccepted=True → live to storefront.

The release-created event now triggers a status patch: Published=True, reason=ReleaseTagApplied.

---

4. KV layer deferral

At this stage the KV layer (Redis/Valkey projection) is premature. ScyllaDB already:

• Supports materialized views and secondary indexes for fast read paths.
• Provides sub-millisecond reads with appropriate partition key design.
• Has built-in LWT for the optimistic concurrency needed for status updates.

The KV layer adds: cache invalidation complexity, a new infrastructure component, potential read inconsistency windows, and deployment overhead.

Recommendation: Defer Redis/Valkey until there is a measured reads-per-second gap that ScyllaDB cannot close with schema tuning alone. The architecture proposals 1 & 2 describe KV as a read optimisation option, not a correctness requirement.

This issue removes "KV layer updates so storefront sees published state" from the publishing flow and replaces it with "ScyllaDB projection updated, storefront reads from ScyllaDB directly".

---

5. Independent inventory/pricing per ProductVariant (from #83)

"Independent" means per-variant, per-spec — not shared. From #83:

• Pricing: spec.pricing.priceSet.prices[] is a list of PriceTemplate entries, each with: currency, amount, quantity tier (minQuantity/maxQuantity), time window (availableFromTimestamp/availableUntilTimestamp), and CEL rules (e.g., region.name == 'Europe'). Each variant carries its own complete pricing graph; there is no shared price object between variants.

• Inventory: spec.manageInventory and spec.inventory are variant-level. Variant A and Variant B for the same product can have independently tracked stock levels, reservation policies, and reorder thresholds.

• Visibility (publication state): Each variant has its own conditions[Published] flag. A Winter Coat variant can be published while a Summer Coat variant for the same Product is still draft. This decoupling is intentional — release tags should be able to target a subset of variants or the full product tree, depending on policy.