Watch-first ingestion with (optional!) audit-based attribution

.coverage-baseline

@@ -1 +1 @@
-75.0
+73.6

.devcontainer/Dockerfile

@@ -228,6 +228,20 @@ RUN printf '%s\n' \
     'fi' \
     >> /etc/bash.bashrc
 
+# Install Node.js (provides npm + npx, e.g. for installing Claude Code skills).
+# Dev stage only; CI does not need a JS runtime.
+# NODE_MAJOR -> https://github.com/nodejs/node/releases (track a current LTS line)
+RUN curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key \
+       | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg \
+    && chmod a+r /etc/apt/keyrings/nodesource.gpg \
+    && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_22.x nodistro main" \
+       > /etc/apt/sources.list.d/nodesource.list \
+    && apt-get update \
+    && apt-get -y install --no-install-recommends nodejs \
+    && apt-get autoremove -y \
+    && apt-get clean -y \
+    && rm -rf /var/lib/apt/lists/*
+
 # Install Tilt CLI (local dev loop orchestration; dev stage only)
 RUN arch="$(dpkg --print-architecture)" && \
     case "${arch}" in \

api/v1alpha2/clusterwatchrule_types.go

@@ -130,19 +130,32 @@ type ClusterResourceRule struct {
 
 // ClusterWatchRuleStatus defines the observed state of ClusterWatchRule.
 type ClusterWatchRuleStatus struct {
+	// ObservedGeneration is the latest generation observed by the controller.
+	// +optional
+	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
+
 	// Conditions represent the latest available observations of the ClusterWatchRule's state.
 	// +optional
 	// +patchMergeKey=type
 	// +patchStrategy=merge
 	Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type"`
+
+	// Streams is the bounded stream-readiness roll-up for the types this rule resolves.
+	// +optional
+	Streams *WatchRuleStreamsStatus `json:"streams,omitempty"`
 }
 
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
 // +kubebuilder:resource:scope=Cluster
 // +kubebuilder:printcolumn:name="Target",type=string,JSONPath=`.spec.targetRef.name`
 // +kubebuilder:printcolumn:name="Ready",type=string,JSONPath=`.status.conditions[?(@.type=="Ready")].status`
-// +kubebuilder:printcolumn:name="Status",type=string,JSONPath=`.status.conditions[?(@.type=="Ready")].message`
+// +kubebuilder:printcolumn:name="Reconciling",type=string,JSONPath=`.status.conditions[?(@.type=="Reconciling")].status`
+// +kubebuilder:printcolumn:name="Stalled",type=string,JSONPath=`.status.conditions[?(@.type=="Stalled")].status`
+// +kubebuilder:printcolumn:name="GitTargetReady",type=string,JSONPath=`.status.conditions[?(@.type=="GitTargetReady")].status`
+// +kubebuilder:printcolumn:name="StreamsRunning",type=string,JSONPath=`.status.conditions[?(@.type=="StreamsRunning")].status`
+// +kubebuilder:printcolumn:name="Streams",type=string,JSONPath=`.status.streams.summary`
+// +kubebuilder:printcolumn:name="Reason",type=string,JSONPath=`.status.conditions[?(@.type=="Ready")].reason`
 // +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
 
 // ClusterWatchRule watches resources across the entire cluster.

api/v1alpha2/gittarget_types.go

@@ -100,13 +100,6 @@ type GitTargetStatus struct {
 	// +patchStrategy=merge
 	Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type"`
 
-	// Phase is a small, derived, human-facing summary of the GitTarget's state —
-	// purely a projection of the conditions (Pending / Initializing / Synced /
-	// Degraded), informational only. Automation must gate on the conditions, never
-	// on phase. See docs/design/status-design-git-target.md §3.3.
-	// +optional
-	Phase string `json:"phase,omitempty"`
-
 	// LastReconcileTime is the timestamp of the most recent reconcile attempt.
 	// +optional
 	LastReconcileTime metav1.Time `json:"lastReconcileTime,omitempty"`
@@ -119,39 +112,30 @@ type GitTargetStatus struct {
 	// +optional
 	LastPushTime *metav1.Time `json:"lastPushTime,omitempty"`
 
-	// Materialization is a bounded roll-up of the demand-driven checkpoint state for the
-	// resource types this GitTarget claims.
+	// Streams is the bounded data-plane roll-up over this GitTarget's tracked types.
+	// Counts, never a per-type list, so it stays bounded however many types are watched.
 	// +optional
-	Materialization *GitTargetMaterializationStatus `json:"materialization,omitempty"`
+	Streams *GitTargetStreamsStatus `json:"streams,omitempty"`
 }
 
-// GitTargetMaterializationStatus is a bounded roll-up of the demand-driven materialization
-// state for the types this GitTarget claims: how many it demands and where they sit in the
-// per-type checkpoint lifecycle. It is a summary (counts), not a per-type list, so it stays
-// bounded regardless of how many types are watched.
-type GitTargetMaterializationStatus struct {
-	// ClaimedTypes is how many resource types this GitTarget currently claims (demands).
+// GitTargetStreamsStatus is a bounded roll-up of the stream readiness state for the
+// types this GitTarget tracks.
+type GitTargetStreamsStatus struct {
+	// Summary is the display-only ready/total ratio.
 	// +optional
-	ClaimedTypes int32 `json:"claimedTypes,omitempty"`
+	Summary string `json:"summary,omitempty"`
 
-	// SyncedTypes is how many claimed types have a current checkpoint and are serviceable.
-	// +optional
-	SyncedTypes int32 `json:"syncedTypes,omitempty"`
+	// Total is how many types this target tracks.
+	Total int32 `json:"total"`
 
-	// PendingTypes is how many claimed types are still building their FIRST checkpoint and so are
-	// not yet serviceable (Requested/Syncing). A type refreshing an existing checkpoint (Resyncing)
-	// is NOT pending — it still serves the prior checkpoint and counts as Synced.
-	// +optional
-	PendingTypes int32 `json:"pendingTypes,omitempty"`
+	// Ready is how many tracked types are Streaming.
+	Ready int32 `json:"ready"`
 
-	// FailingTypes is how many claimed types last failed their checkpoint sync.
-	// +optional
-	FailingTypes int32 `json:"failingTypes,omitempty"`
+	// Replaying is how many tracked types are still replaying their initial events.
+	Replaying int32 `json:"replaying"`
 
-	// NotFollowableTypes is how many claimed types are not currently followable — the
-	// claim-vs-refused mismatch an operator should notice.
-	// +optional
-	NotFollowableTypes int32 `json:"notFollowableTypes,omitempty"`
+	// Blocked is how many tracked types cannot currently be watched.
+	Blocked int32 `json:"blocked"`
 
 	// ObservedTime is when this roll-up was last computed.
 	// +optional
@@ -162,10 +146,14 @@ type GitTargetMaterializationStatus struct {
 // +kubebuilder:subresource:status
 // +kubebuilder:printcolumn:name="Provider",type=string,JSONPath=`.spec.providerRef.name`
 // +kubebuilder:printcolumn:name="Branch",type=string,JSONPath=`.spec.branch`
-// +kubebuilder:printcolumn:name="Path",type=string,JSONPath=`.spec.path`
 // +kubebuilder:printcolumn:name="Ready",type=string,JSONPath=`.status.conditions[?(@.type=="Ready")].status`
-// +kubebuilder:printcolumn:name="Phase",type=string,JSONPath=`.status.phase`
-// +kubebuilder:printcolumn:name="Status",type=string,JSONPath=`.status.conditions[?(@.type=="Ready")].message`
+// +kubebuilder:printcolumn:name="Reconciling",type=string,JSONPath=`.status.conditions[?(@.type=="Reconciling")].status`
+// +kubebuilder:printcolumn:name="Stalled",type=string,JSONPath=`.status.conditions[?(@.type=="Stalled")].status`
+// +kubebuilder:printcolumn:name="GitPathAccepted",type=string,JSONPath=`.status.conditions[?(@.type=="GitPathAccepted")].status`
+// +kubebuilder:printcolumn:name="StreamsRunning",type=string,JSONPath=`.status.conditions[?(@.type=="StreamsRunning")].status`
+// +kubebuilder:printcolumn:name="Streams",type=string,JSONPath=`.status.streams.summary`
+// +kubebuilder:printcolumn:name="Reason",type=string,JSONPath=`.status.conditions[?(@.type=="Stalled")].reason`
+// +kubebuilder:printcolumn:name="Status",type=string,JSONPath=`.status.conditions[?(@.type=="Stalled")].message`
 // +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
 
 // GitTarget is the Schema for the gittargets API.

api/v1alpha2/watchrule_types.go

@@ -124,19 +124,61 @@ type ResourceRule struct {
 
 // WatchRuleStatus defines the observed state of WatchRule.
 type WatchRuleStatus struct {
+	// ObservedGeneration is the latest generation observed by the controller.
+	// +optional
+	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
+
 	// Conditions represent the latest available observations of an object's state
 	// +optional
 	// +patchMergeKey=type
 	// +patchStrategy=merge
 	Conditions []metav1.Condition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type"`
+
+	// Streams is the bounded stream-readiness roll-up for the types this rule resolves.
+	// +optional
+	Streams *WatchRuleStreamsStatus `json:"streams,omitempty"`
+}
+
+// WatchRuleStreamsStatus is a bounded roll-up of the stream-readiness state for the
+// types a WatchRule or ClusterWatchRule resolves.
+type WatchRuleStreamsStatus struct {
+	// Summary is the display-only ready/total ratio.
+	// +optional
+	Summary string `json:"summary,omitempty"`
+
+	// Total is how many types this rule resolves.
+	Total int32 `json:"total"`
+
+	// Ready is how many resolved types are Streaming.
+	Ready int32 `json:"ready"`
+
+	// Replaying is how many resolved types are still replaying their initial events.
+	Replaying int32 `json:"replaying"`
+
+	// Blocked is how many resolved types cannot currently be watched.
+	Blocked int32 `json:"blocked"`
+
+	// PendingSample is a bounded sample of types not yet ready.
+	// +optional
+	// +kubebuilder:validation:MaxItems=5
+	PendingSample []string `json:"pendingSample,omitempty"`
+
+	// ObservedTime is when this roll-up was last computed.
+	// +optional
+	ObservedTime *metav1.Time `json:"observedTime,omitempty"`
 }
 
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
 // +kubebuilder:resource:scope=Namespaced
 // +kubebuilder:printcolumn:name="Target",type=string,JSONPath=`.spec.targetRef.name`
 // +kubebuilder:printcolumn:name="Ready",type=string,JSONPath=`.status.conditions[?(@.type=="Ready")].status`
-// +kubebuilder:printcolumn:name="Status",type=string,JSONPath=`.status.conditions[?(@.type=="Ready")].message`
+// +kubebuilder:printcolumn:name="Reconciling",type=string,JSONPath=`.status.conditions[?(@.type=="Reconciling")].status`
+// +kubebuilder:printcolumn:name="Stalled",type=string,JSONPath=`.status.conditions[?(@.type=="Stalled")].status`
+// +kubebuilder:printcolumn:name="GitTargetReady",type=string,JSONPath=`.status.conditions[?(@.type=="GitTargetReady")].status`
+// +kubebuilder:printcolumn:name="StreamsRunning",type=string,JSONPath=`.status.conditions[?(@.type=="StreamsRunning")].status`
+// +kubebuilder:printcolumn:name="Streams",type=string,JSONPath=`.status.streams.summary`
+// +kubebuilder:printcolumn:name="Reason",type=string,JSONPath=`.status.conditions[?(@.type=="Ready")].reason`
 // +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
 
 // WatchRule watches namespaced resources within its own namespace.