[Framework] Register and discover exact-Release runtime instances

[XnLemon]

Framework objective

Implement the Register -> Discover stage of the NeKiro Agent Framework:

Provider registers an exact-Release instance
  -> Registry/Directory watches its lease and lifecycle
  -> A2A Router resolves one ready instance
  -> Consumer can invoke it only through Router

This issue owns ephemeral runtime topology. Catalog remains the only source of immutable Agent Card and Release facts; Workspace remains the authorization owner; Router remains the invocation and instance-selection owner.

Program map

#88 Configuration/watch foundation
  -> #89 Register + Discover exact-Release runtime instances
  -> #90 Install + Invoke through Router + Record in Ledger

#89 bridges published Release identity to a live Provider process. Registration is not publication: it may report that a process is ready to serve an existing exact Release, but it may never create, rewrite, or substitute that Release.

Goals

• Define provider-neutral registration, lease/heartbeat, snapshot, and watch contracts.
• Preserve AgentID, exact ReleaseID, Card digest/provenance, endpoint, audience, stable instance identity, state, zone, and weight.
• Normalize Kubernetes EndpointSlice and Nacos lifecycle semantics without leaking provider SDK types into consumers.
• Let Provider runtimes explicitly register ready instances and observe terminal lease failure.
• Let Router continuously watch one selected provider and use one immutable topology snapshot per Invocation.
• Make deletion, draining, expiry, stale revision, watch interruption, and backend outage explicit and observable.
• Provide safe topology status so E2E acceptance can distinguish “Router observed an empty topology” from “Router selected a stale endpoint and transport failed.”

Required ownership and invariants

• Registration never publishes or rewrites an Agent Card/Release.
• A registered instance must match the exact authorized Release target and safe metadata contract.
• Runtime startup fails if initial registration fails; serving/readiness ends when the lease becomes terminal.
• Shutdown explicitly deregisters the instance.
• Router selects only a ready instance for the already-authorized exact Release.
• JSON, SSE, and tasks/cancel remain pinned to the selected endpoint for the complete Invocation.
• Consumer never receives or dials the Provider endpoint directly.
• No retry, provider switch, alternate Release/endpoint, stale-cache success, or hidden fallback.
• Registration metadata, status, logs, events, and Ledger never contain credentials or Agent payloads.

Non-goals

• Owning Agent Card, Release, Workspace, Installation, Permission, or Ledger facts.
• Allowing Consumer to discover or invoke Provider directly.
• Making Directory select another version or alter JWT audience/provenance.
• Implementing load balancing, circuit breaking, retry, failover, or traffic policy inside the Directory.
• Treating Kubernetes and Nacos as concurrent discovery authorities without an approved federation policy.

Deliverables

• Add an ADR defining ownership, exact target identity, provider selection, watch ordering, freshness, drain, and outage behavior.
• Add root provider-neutral Registry/Directory models and interfaces.
• Implement Kubernetes EndpointSlice and Nacos Directory adapters.
• Add one backend-neutral snapshot/watch/error conformance suite and deterministic fakes.
• Add Router readiness projection with safe state codes.
• Implement Router continuous snapshot consumption and one endpoint choice per Invocation.
• Merge provider-neutral registration/lease capability and explicit Nacos ephemeral register/heartbeat/deregister lifecycle (PR feat(registry): add Nacos runtime registration lease #106).
• Integrate the Core registration lease into owning Sample Provider runtimes.
• Prove registration, discovery, explicit deregistration/expiry, observed empty topology, Router fail-closed behavior, and replacement recovery in Stack using exact revisions.
• Add authenticated safe topology revision/freshness status without endpoints, source tokens, provider metadata, credentials, or payloads.
• Update ownership documentation and the [Framework] Build configuration and dynamic-governance foundation #88 integration plan.

Acceptance criteria

• Kubernetes and Nacos Directory adapters satisfy the same required behavior contract.
• Provider registration is ready-only, exact-Release-bound, terminal, and explicitly cleaned up.
• Missing, empty, invalid, unauthorized, unavailable, deleted, draining, expired, and stale states remain distinct.
• Provider A registers in Nacos, Router observes it, and Consumer B reaches it only through the managed Router path.
• After deregistration/expiry, Router observably consumes the empty topology before the next Invocation fails closed; a stale endpoint transport failure is not sufficient evidence.
• A replacement instance can register and become callable without restarting Router.
• Registry topology cannot alter Catalog/Workspace authorization or Ledger provenance.

Related work

• Configuration/watch foundation: [Framework] Build configuration and dynamic-governance foundation #88
• Managed invocation and Ledger closure: [Framework] Complete managed Consumer-to-Provider invocation #90
• Current implementation tracker: [Task] Complete runtime registration, freshness status, and Gateway acceptance #105

Fallback report

Fallback delta: removed 0, retained 0, added 0, net +0
Added fallback evidence: none

[XnLemon]

Sample Agent fixtures for multi-replica identity, SSE/cancellation affinity, drain, and duplicate-execution detection are tracked in NeKiro-project/NeKiro-Samples#3. Full provider orchestration remains Stack-owned.

[XnLemon]

Router-side runtime consumption is implemented in Core PR #98 and proven with exact revisions in NeKiro-project/NeKiro-Stack#3 using the observable replica from NeKiro-project/NeKiro-Samples#4. Nacos, provider freshness metrics/status, Gateway consumption, and multi-instance selection policy remain open.

[XnLemon]

Router snapshot consumption has merged through #98 as 0d32fb4. The Router now resolves the already-authorized exact Release against the configured directory, requires exactly one ready matching TCP endpoint, pins JSON/SSE/cancellation to that endpoint, preserves the canonical credential audience and all Target identity fields, and fails closed without retry, alternate endpoint, or stale fallback. Required CI and focused race coverage passed.

NeKiro-project/NeKiro-Samples#4 and NeKiro-project/NeKiro-Stack#3 remain open. Nacos, provider freshness metrics/status, Gateway directory consumption, and an approved multi-instance selection policy remain unchecked.

中文

Router snapshot 消费已通过 #98 合并，merge commit 为 0d32fb4。Router 现在会使用配置目录匹配已授权的精确 Release，要求恰好一个匹配端口的 ready TCP endpoint，并将 JSON/SSE/cancellation 固定到该 endpoint；canonical credential audience 和全部 Target 身份字段保持不变，失败时不会 retry、切换 endpoint 或使用 stale fallback。required CI 和针对性 race 覆盖均通过。

NeKiro-project/NeKiro-Samples#4 与 NeKiro-project/NeKiro-Stack#3 仍为 open。Nacos、provider freshness metrics/status、Gateway directory consumption 和多实例选择策略继续保持未勾选。