docs(spec): define gRPC and CLI apply surface for ADLC Kinds

[hypershell-builder]

Specification change only

This PR changes specification only (specs/**). No implementation code,
protobuf, or CLI code is touched here. After a human merges it, the reconcile
skill will see the new spec-vs-code gap and implement the gRPC stubs and any
remaining CLI wiring to match on a later run.

Refs #467.

Desired behavior

PR #452 introduced the ADLC extension Kinds (AgentRuntime, SandboxTemplate,
ProviderSpec, ProviderBinding, InferenceRoute, SecretSource) with a REST
surface at /api/hypershell/ext/, but did not give them the full-stack-pipeline
treatment for the gRPC and CLI stages. This PR captures the desired state:

• gRPC: each control-plane-reconciled ADLC Kind SHALL have a gRPC contract
  (proto message + List/Watch + status write RPC) generated the same way as
  the existing Kinds, and the control plane SHALL be driven by AgentRuntime
  watch-stream events (filtered by cluster_id, with status written back over
  gRPC) rather than polling the REST /ext/ API. This matches the
  informer-reconciler pattern used for Gateway.
• CLI apply / kustomize: hsctl apply (both -f and -k) SHALL support all
  six ADLC extension Kinds, dispatched to /api/hypershell/ext/. The apply
  command code already supports these Kinds; this change brings the spec's
  "Supported Kinds" table (previously marking three as planned and omitting
  three) up to the desired state.

Spec files changed

• specs/platform/control-plane.spec.md
  • Corrected the stale Watcher and watch-stream enumeration: dropped the removed
    GatewayReleases/GatewayNetworks, added RoleBindings and the ADLC Kinds.
  • Added Requirement: gRPC Contract and Watch Coverage for ADLC Kinds with
    three scenarios (per-cluster watch, reconcile-over-gRPC, status write-back).
• specs/platform/data-model.spec.md
  • Expanded the hsctl apply Supported Kinds table to all six ADLC Kinds.
  • Added Requirement: hsctl apply Supports ADLC Extension Kinds with three
    scenarios (apply from file, apply all Kinds from a Kustomize directory,
    unknown-kind is skipped not fatal).

Grounding done

• Confirmed proto only exists for gateways, managed_clusters, role_bindings,
  common (components/api-server/proto/hypershell/v1/); no proto for any ADLC
  Kind. feat(adlc): add Agent Declarative Lifecycle Configuration spec #452 deleted the gateway_networks/gateway_releases proto and plugins.
• Confirmed hsctl apply (components/cli/cmd/hsctl/apply/cmd.go) already lists
  all six ADLC Kinds in isSupportedKind/applyResource and maps them to the
  /ext/ paths in components/cli/pkg/urls/urls.go; CLI create/get/delete
  commands for the ADLC Kinds also already exist (feat(cli): add ADLC extension kinds to hsctl with grouped help #466).
• Confirmed the ADLC content lives in data-model.spec.md (the separate
  specs/adlc/agents.spec.md from feat(adlc): add Agent Declarative Lifecycle Configuration spec #452 no longer exists), so these are
  amendments to existing specs rather than a new spec/registry row.

Open question (why needs-decision)

The CLI part is a straightforward spec-catches-up-to-code change. The gRPC
surface is an architecture decision a maintainer should confirm before
reconcile implements it (captured inline in the new control-plane requirement):

1. Which ADLC Kinds get a hub gRPC watch stream? Recommended: AgentRuntime
   watched; SandboxTemplate/ProviderSpec/SecretSource read on demand via
   Get/List. Must a change to a shared config Kind re-reconcile dependent
   AgentRuntimes (which would require watching them)?
2. Hub gRPC vs. gateway gRPC for gateway-side Kinds. AgentWorkspace,
   WorkspaceMembership, ProviderBinding, InferenceRoute are provisioned via
   the gateway gRPC API during reconcile. Confirm ProviderBinding and
   InferenceRoute do not also need a hub watch stream.

The drafted scenarios assume (1) AgentRuntime watched and (2) gateway-side
Kinds provisioned via the gateway gRPC API; adjust if the maintainer decides
otherwise.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Repository YAML (base), Central YAML (inherited)
• Review profile: CHILL
• Plan: Advanced
• Run ID: c87bad7d-0f0e-4836-8340-8f4086e101b3

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[hypershell-delivery]

Amber review

Status: Complete

View the submitted review.

[hypershell-delivery]

Verdict

This is a clean, specification-only change: it corrects the stale Watcher Kind enumeration in control-plane.spec.md, adds a well-scoped gRPC watch/contract requirement for the control-plane-reconciled ADLC Kinds, and documents the already-implemented hsctl apply support for the six ADLC extension Kinds. I verified the doc claims against the code (apply dispatch, /ext/ prefix, watcher enumeration) and found them accurate; the only substantive issue is cross-PR coordination the maintainers should resolve before reconcile implements the new gRPC surface.

What I checked

• hsctl apply claims are accurate. The data-model table now marks the six ADLC Kinds ✅ implemented for apply; components/cli/cmd/hsctl/apply/cmd.go (isSupportedKind + the dispatch switch, lines ~287-335) handles all six and routes them to urls.*Path under ExtAPIPrefix = "/api/hypershell/ext" (components/cli/pkg/urls/urls.go), matching the spec's /api/hypershell/ext/agent_runtimes examples. The unknown-kind-skip and create-or-update (POST vs PATCH) behavior in the new scenarios also matches the code.
• Watcher enumeration correction is accurate. The control plane watches Gateways, ManagedClusters, and RoleBindings today (WatchRoleBindings in cmd/hypershell-controller/main.go); GatewayReleases/GatewayNetworks are gone. The corrected prose and the admin-credential-files scenario now reflect that.
• gRPC/ADLC requirement is desired-state and appropriately gated. No AgentRuntime reconciler or gRPC contract exists in the control plane yet; the new requirement correctly frames this as future work and the embedded DECISION NEEDED block defers the per-Kind watch surface to a maintainer. Good practice.
• No panic, no code, no secret handling, no em dashes.

Cross-PR coordination

One material coordination issue needs a maintainer decision.

This PR makes AgentRuntime a new control-plane-reconciled Kind driven by a gRPC List seed + Watch stream + status write-back, and corrects the canonical set of watched Kinds to Gateways, ManagedClusters, RoleBindings plus the ADLC Kinds. The open world-synchronization spec PR defines an authoritative "complete API inventory" contract for every control-plane-reconciled Kind, but its Kind list still enumerates Fleet/GatewayRelease/GatewayNetwork and omits any ADLC Kind, and it mandates per-Kind primitives (a control-plane-only paginated List, a resource_revision on every list/watch/delete payload, and an inventory watermark) that this PR's ADLC gRPC contract does not yet specify. Maintainers must decide (a) whether AgentRuntime participates in periodic world synchronization, and (b) if so, ensure the ADLC List/Watch contract this PR introduces is designed to satisfy that spec's resource_revision/watermark/deterministic-pagination inventory requirements, and reconcile the two conflicting enumerations of the control-plane-reconciled Kind set. This is best settled before either spec's reconcile implementation starts, so the ADLC gRPC surface is defined once rather than twice.

Relatedly, the open reconciliation-contract PR introduces a shared behavior contract that "all reconcilers SHALL follow" (durable queues, resync, revision-based versioning). If it lands, the AgentRuntime reconcile loop and gRPC status write-back specified here must conform to it; the maintainer confirming this PR's DECISION NEEDED block should align the ADLC contract with that shared contract rather than specify a divergent one.

Previous concerns

No prior Amber review findings are on record for this pull request (the allowed review history is empty), so there are no earlier concerns to re-verify.

Findings Summary (ordered by severity, highest first)

1. [Coordination] ADLC Kinds become control-plane-reconciled with a new gRPC List/Watch contract; this must be reconciled with the open world-synchronization inventory contract (Kind set + resource_revision/watermark/pagination) and the shared reconciliation contract - Cross-PR (see Cross-PR coordination).
2. [Minor] The hsctl apply "Supported Kinds" table marks the six ADLC Kinds ✅ implemented without noting that the /ext/ surface is labeled "experimental, unsupported, subject to change" in the CLI help - Doc Consistency (data-model.spec.md L849-L854).

Convention Checklist

Convention	Result
No panic() in production code	N/A (spec-only)
Spec claims match implementation (apply dispatch, /ext/ prefix, watcher set)	Pass
Internal cross-reference consistency (requirement anchors, Kind names)	Pass
No em dashes	Pass
Conventional commit message	Pass

[hypershell-delivery]

[Minor] Doc consistency. These six ADLC Kinds are marked ✅ implemented here, which is accurate for hsctl apply support (isSupportedKind + the dispatch switch in components/cli/cmd/hsctl/apply/cmd.go route all six under ExtAPIPrefix = "/api/hypershell/ext"). However, the CLI help groups the same /ext/ commands as "Extensions (hypershell/ext/) - experimental, unsupported, subject to change". Consider adding a short note here (or reusing that wording) so ✅ implemented is not read as a stability/GA guarantee for the extension surface. Confidence: High.