Add Gateway and Instance Registry acceptance fixtures to Sample Agents

[XnLemon]

Summary

Add deterministic Sample Agent fixtures and repository-owned tests for the external Gateway and Agent Instance Registry/Directory architecture tracked by:

• NeKiro Core Config Center: NeKiro-project/NeKiro#88
• NeKiro Core Instance Registry/Directory: NeKiro-project/NeKiro#89
• NeKiro Core External Gateway integration: NeKiro-project/NeKiro#90

Samples should provide the Agent-side behavior, safe evidence, and reusable test workflow needed to prove Kubernetes/Nacos instance discovery and Envoy Gateway/APISIX/Higress forwarding without making this repository own multi-component deployment orchestration.

Ownership boundary

NeKiro-Samples owns:

• deterministic Sample Agent behavior and test capabilities;
• Agent-side JSON, SSE, cancellation, credential, and instance-identity assertions;
• Sample images/commands and repository-local tests;
• a reusable workflow that validates a selected Core/SDK revision when invoked by the owning orchestration repository.

NeKiro-Stack owns:

• starting PostgreSQL, Control Plane, A2A Router, Gateway, Kubernetes/Nacos, and multiple Agent replicas;
• wiring exact repository revisions and deployment credentials;
• cross-process/browser/product acceptance and provider matrices.

Core owns the provider-neutral abstractions, contracts, trust policy, routing policy, and backend conformance tests. This repository must not copy Core, SDK, Gateway, Registry, or Stack source.

Goals

• Provide at least two distinguishable replicas of the same exact Sample Agent Release.
• Expose safe, deterministic evidence of which replica handled an Invocation without exposing host credentials, tokens, keys, or arbitrary environment values.
• Prove non-streaming and SSE requests preserve the selected instance for the complete response lifecycle.
• Prove tasks/cancel reaches the instance that owns the task rather than being rerouted to another replica.
• Provide deterministic side-effect evidence capable of detecting an unintended Gateway/Router retry or duplicate execution.
• Prove graceful drain behavior: an existing Invocation may complete on the draining instance while new work is routed elsewhere.
• Prove Router-to-Agent credential validation still binds the exact Agent/Release/audience/context through an external Gateway.
• Preserve nested Invocation lineage where a Sample Agent calls another installed Agent through the Router.
• Make the same fixture behavior reusable for Kubernetes and Nacos topologies and for Envoy Gateway, APISIX, and Higress provider acceptance.

Proposed fixtures

The exact Sample capability names and output schema must be decided before implementation, but the fixtures should cover:

1. Replica identity

   • return a configured, non-secret stable instanceId in a test-owned result field;
   • do not return pod names, node names, IP addresses, tokens, keys, or full environment dumps.

2. Streaming affinity

   • emit several deterministic SSE events from one instance;
   • include the same safe instanceId in each test-owned payload;
   • expose enough delay/control for Stack to trigger drain or cancellation while the stream is active.

3. Cancellation ownership

   • retain task ownership in the handling replica;
   • report deterministic canceled/not-cancelable/not-found outcomes according to the supported A2A profile;
   • never invent a successful cancellation on a different replica.

4. Duplicate execution detection

   • provide a deterministic Invocation-scoped execution count or idempotency witness;
   • fail acceptance if one managed Invocation is executed more than once because of an implicit retry.

5. Nested invocation

   • preserve root_task_id, parent_invocation_id, and trace_id through Router-mediated Agent-to-Agent calls in a multi-replica topology.

Non-goals

• Implementing or vendoring Envoy Gateway, APISIX, Higress, Kubernetes, Nacos, Core, SDK, or Stack code.
• Making NeKiro-Samples required CI start a complete external middleware matrix.
• Defining the Core GatewayProvider, InstanceDirectory, selector, load-balance, retry, or fallback policy.
• Registering Agent Card/Release facts in a second store.
• Adding production diagnostic endpoints that expose infrastructure identity or secrets.
• Treating Sample instance identity as platform authorization or durable Ledger provenance.
• Accepting direct unauthenticated calls as equivalent to Router-managed invocations.

Deliverables

• Define versioned Sample capability/input/output schemas for safe replica and execution evidence.
• Add deterministic multi-replica Sample configuration without guessed instance identities.
• Add repository-local unit/integration tests for JSON, SSE, cancellation, duplicate detection, and credential-context checks.
• Add tests proving all events/results for one Invocation carry one stable Sample instanceId.
• Add tests proving forged, missing, wrong-audience, wrong-Release, or wrong-context Router credentials are rejected before Sample business logic.
• Add a reusable workflow that can be called with exact Core and SDK revisions.
• Document the fixtures and the evidence expected from Stack provider acceptance.
• Coordinate a Stack-owned matrix for Kubernetes/Nacos and Envoy Gateway/APISIX/Higress without duplicating orchestration here.

Acceptance criteria

• The same exact Sample Agent Release can run as at least two distinguishable replicas.
• One Invocation never reports mixed replica identity across JSON/SSE/cancellation evidence.
• A cancellation request cannot succeed by reaching a replica that does not own the task.
• An implicit retry or duplicate execution is detected deterministically.
• A draining replica stops receiving new work while an accepted bounded invocation can complete according to the approved policy.
• Gateway forwarding does not weaken Router credential, audience, Release, capability, Invocation, Task, or Trace validation.
• Sample logs and outputs contain no tokens, key material, Authorization headers, arbitrary environment dumps, or Agent credentials.
• Stack can consume the Sample workflow/fixtures using exact revisions without checking Sample source into Core.

Fallback report

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