[Framework] Complete managed Consumer-to-Provider invocation

[XnLemon]

Framework objective

Complete the managed Install -> Invoke -> Record stage of the NeKiro Agent Framework:

Register -> Discover -> Install -> Invoke -> Record

Consumer B -> Control Plane Gateway -> A2A Router -> Provider A
                                      -> Invocation Ledger

Consumer never connects to Provider directly. Every managed Agent-to-Agent invocation goes through A2A Router, which owns exact Release resolution, runtime instance selection, scoped Router credentials, authorization context, lineage propagation, failure semantics, and audit recording.

Program map

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

#90 is the integration closure: it does not create a second registry or transport shortcut. It composes Catalog publication, Workspace authorization, #89 runtime discovery, Router policy, A2A transport, and Ledger into one externally verifiable E2E path.

Required E2E behavior

1. Provider A publishes an immutable Card/Release and registers a ready runtime instance for that exact Release.
2. Consumer B is authorized through Workspace Installation/Permission for that exact Release and capability.
3. Consumer B invokes the platform boundary; it does not receive or dial Provider A's runtime address.
4. Control Plane resolves authorization and dispatches to A2A Router.
5. Router resolves the exact Release, consumes the watched Directory snapshot, selects one ready instance, issues scoped credentials, and pins the complete Invocation lifecycle to it.
6. Provider A may perform a child Agent call only by re-entering Router with preserved root_task_id, parent_invocation_id, and trace_id.
7. Ledger records append-only safe invocation metadata and final outcome.
8. Deregistration, expiry, watch failure, missing authorization, or missing exact target fails closed with distinct semantics.

Goals

• Preserve the semantic Gateway -> Router boundary for every managed invocation.
• Resolve the Workspace-authorized exact Release before runtime selection.
• Preserve exact Agent/Release/Card provenance and canonical audience.
• Propagate task, invocation, cancellation, root/parent, and trace lineage across Agent-to-Agent calls.
• Support JSON, SSE, and cancellation without payload transformation, buffering, rerouting, or automatic retry.
• Append safe Invocation metadata to Ledger without inputs, outputs, credentials, tokens, or provider bodies.
• Prove lifecycle removal and recovery using Router-observed topology state rather than inferring watch behavior from a transport error.

External Gateway boundary

Router-owned discovery is sufficient for the Framework E2E and is the current direction:

Control Plane Gateway -> Router -> watched exact-Release instance -> Provider

Envoy Gateway, APISIX, Higress, or another external data plane may later be integrated around this boundary, but it is not required to close this issue. Any future adapter needs a separate ownership decision and acceptance plan; it may not replace the semantic Control Plane Gateway, bypass Router, or become a second discovery authority for the same route.

Non-goals

• Implementing proxy data planes inside Core.
• Allowing Console, external clients, or Consumer Agents to bypass Gateway/Router.
• Letting an external Gateway own Agent Card, Release, Workspace, Installation, Permission, Router policy, or Ledger facts.
• Adding automatic retry, failover, default upstream, alternate Release/provider/endpoint, stale dump/cache, or implicit provider switching.
• Requiring an external Gateway adapter to complete the base Router-owned E2E closure.

Deliverables

• Add an ADR defining semantic/external Gateway boundaries, discovery ownership, readiness, reconcile, drain, SSE, affinity, and failure semantics.
• Add provider-neutral external Gateway models, lifecycle interfaces, capability reporting, deterministic fakes, and conformance tests.
• Document Router-owned discovery and external Gateway operations.
• Implement Router-owned watched topology consumption for exact authorized Releases.
• Prove Provider A registration -> Consumer B managed invocation -> Router forwarding -> Provider response -> Ledger record in Samples/Stack with exact repository revisions.
• Prove JSON, SSE, cancellation, nested Router re-entry, and root/parent/trace lineage on the same managed path.
• Prove deregistration/expiry is observed as empty topology before subsequent Router invocation fails closed, then prove replacement recovery without Router restart.
• Add safe authenticated topology/readiness/status evidence needed by the E2E, without endpoints, provider internals, credentials, or payloads.

Acceptance criteria

• No managed Consumer -> Provider direct path exists.
• Workspace authorization and exact Release resolution happen before runtime selection.
• JSON, SSE, and cancellation stay pinned to one selected instance.
• Child Agent calls re-enter Router and preserve root/parent/trace lineage.
• Ledger records only safe append-only metadata, exact provenance, and correct outcome.
• Missing authorization, missing exact Release, empty topology, provider outage, deregistration/expiry, and transport failure remain distinguishable.
• No fallback, retry, alternate endpoint/Release/provider, or stale success is introduced.
• The E2E is pinned to exact Core, Samples, and Stack commit SHAs and passes required CI.

Optional follow-up

Selecting and implementing a concrete Envoy Gateway, APISIX, or Higress adapter is a separate provider-integration slice after its deployment and discovery ownership are approved. It must preserve Router authorization, exact provenance, scoped credentials, lineage, SSE/cancellation affinity, no retry, and Ledger invariants.

Related work

• Configuration/watch foundation: [Framework] Build configuration and dynamic-governance foundation #88
• Provider registration and runtime discovery: [Framework] Register and discover exact-Release runtime instances #89
• 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 Gateway forwarding, SSE/cancellation affinity, drain, credential context, and no-retry evidence are tracked in NeKiro-project/NeKiro-Samples#3. Full provider orchestration remains Stack-owned.

[XnLemon]

Core PR #98 adds the operator runbook for the existing provider-neutral external Gateway boundary. No Envoy Gateway, APISIX, or Higress adapter is claimed complete; provider-specific Stack acceptance remains open.

[XnLemon]

#98 has merged as 0d32fb4 and contributes only the external-Gateway operator runbook plus the Router-owned discovery path boundary. It does not claim an Envoy Gateway, APISIX, or Higress adapter, provider readiness/status projection, or selected-provider Stack acceptance. Those checklist items correctly remain open. NeKiro-project/NeKiro-Stack#3 currently validates configured Router instance routing and is still open; it is not provider-adapter acceptance for this issue.

中文

#98 已以 0d32fb4 合并；对本 issue 的贡献仅包括 external Gateway 运维文档和 Router-owned discovery 路径边界。它没有宣称完成 Envoy Gateway、APISIX、Higress adapter、provider readiness/status projection 或 selected-provider Stack acceptance，因此这些 checklist 项继续保持未勾选。NeKiro-project/NeKiro-Stack#3 当前验证的是配置驱动的 Router 实例路由，而且仍为 open；它不等同于本 issue 的 provider adapter acceptance。

[XnLemon]

Core PR #99 has merged as b69a14a and contributes only the Router-owned Nacos discovery boundary plus operator documentation to this issue.

No provider-specific external Gateway adapter has been added: Envoy Gateway, APISIX, Higress, provider status/metrics, and selected-provider Stack acceptance remain unchecked. Stack PR NeKiro-project/NeKiro-Stack#4 validates Router-owned Nacos discovery, not external Gateway provider acceptance.

Fallback delta: removed 0, retained 0, added 0, net +0.

[XnLemon]

Core PR #104 has merged as 3790b9e and completes the Router-owned Nacos discovery path: the A2A Router, not an external Gateway, owns continuous topology observation and endpoint selection for an exact authorized Release. Invocation JSON/SSE/cancellation affinity remains inside Router transport, and failures do not switch provider, endpoint, or Release.

This does not complete an Envoy Gateway, APISIX, or Higress adapter, provider status projection, or selected-provider Stack acceptance. Those items remain unchecked and are now tracked as explicit follow-up work in #105.

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