Card Discovery Refinement Alignment [Spec + Impl]

[rhuss]

Review Guide for full context: motivation, key decisions, and scope boundaries.

Spec for review

PR #372 introduced card discovery on AgentRuntime. This follow-up aligns the API surface with Kubernetes conventions and the community refinement document before external consumers lock in the current field names and condition types.

Why now

The card discovery API has no consumers yet. Field renames and condition type changes are free today but require migration tomorrow. This is the last window to get the API right before it becomes a compatibility constraint.

Proposed changes (spec only, no code yet)

Transport security visibility (new transportSecurity field on CardStatus)

A card fetched over plain HTTP within the cluster network has no transport-level identity guarantee. Platform engineers currently cannot tell from the AgentRuntime status whether a card was fetched securely. Adding transportSecurity ("mTLS" or "plainHTTP") makes the security posture observable without digging into operator logs.

Condition model cleanup (rename CardSynced to CardFetched)

• CardSynced implies ongoing synchronization, which is misleading for an event-driven, non-polling architecture
• CardSynced True CardSynced stutters in kubectl describe output (condition type and reason are identical)
• Transport-aware reasons (Fetched vs FetchedInsecure) give immediate security posture visibility
• WorkloadNotReady split from ServiceNotFound maps each reason to one diagnostic action

Field name accuracy

• cardId renamed to cardHash: the field holds a SHA-256 content hash for change detection, not a unique identifier
• fetchedAt renamed to lastCardFetchTime: disambiguates "when the controller fetched it" from "when the agent created it"

Protocol-aware port resolution

• kagenti.io/port annotation override for multi-port Services where auto-detection picks the wrong port
• Port named a2a takes priority over generic http since we're fetching A2A protocol cards specifically

Artifacts

File	Purpose
spec.md	4 user stories, 9 functional requirements, 5 success criteria
plan.md	Technical context, constitution check, file map
tasks.md	31 tasks across 6 phases
research.md	6 research decisions
data-model.md	CardStatus field changes, condition model
REVIEWERS.md	Review guide

Assisted-By: 🤖 Claude Code

[pdettori]

Review Summary

This is a well-structured spec that makes the right architectural call at the right time. The API surface improvements are genuine — better naming, security observability, clearer diagnostics — and the cost is minimal given the absence of external consumers.

The synthesis approach is sound: cherry-picking transport security awareness and workload readiness from the refinement doc while preserving PR #372's event-driven model and FetchSkipped semantics. The timing argument for breaking changes is valid.

A few design questions below (none blocking), mostly around ensuring the spec is explicit on edge cases that will matter during implementation.

Areas reviewed: Data model, condition semantics, port resolution, workload readiness, CRD UX
Commits: 3, all signed-off
CI: All passing (E2E pending)

[rhuss]

what's the difference between "Protocol" and "TransportSecurity" ?

[rhuss]

They are orthogonal concepts:

• protocol = the application-level agent discovery protocol ("a2a"), identifying which card endpoint convention was used
• transportSecurity = the transport layer authentication used for the fetch ("mtls" or "http")

An A2A card can be fetched over either transport. protocol tells you what was fetched, transportSecurity tells you how securely it was fetched.