[Framework] Build configuration and dynamic-governance foundation

[XnLemon]

Framework objective

Build the configuration and dynamic-governance foundation beneath the NeKiro Agent Framework:

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

NeKiro is not a collection of directly connected, pluggable Agents. Provider, Consumer, Control Plane, A2A Router, Registry, Workspace, and Ledger are independently deployed participants joined by versioned contracts and explicit trust boundaries. This issue gives those boundaries one strict, provider-neutral way to read bootstrap configuration and observe approved dynamic state.

It does not own Agent registration, runtime topology, Workspace authorization, invocation transport, or Ledger facts.

Program map

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

• [Framework] Build configuration and dynamic-governance foundation #88: provider-neutral snapshots, watches, revisions, typed failures, and safe status.
• [Framework] Register and discover exact-Release runtime instances #89: Provider registration leases and Router-owned runtime discovery for an exact Release.
• [Framework] Complete managed Consumer-to-Provider invocation #90: Consumer invocation through Control Plane and Router, including authorization, lineage, credentials, failure semantics, and Ledger audit.

Ownership

config_center/                  opaque snapshot/watch/publish mechanics
apps/control-plane/internal/   Control Plane schema, validation and readiness
apps/a2a-router/internal/      Router schema, policy and invocation application
registry/                      Provider registration and runtime topology (#89)
gateway/ + a2a-router          managed invocation boundary (#90)

config_center/ owns only provider-neutral opaque bytes, immutable snapshots, gap-free initial/watch handoff, local revisions, typed outcomes, and explicit read/publish capabilities. Control Plane and Router remain owners of their typed schemas, validation, readiness, policy decisions, and runtime application.

Bootstrap provider address, namespace, authentication, and TLS material remain explicit deployment configuration. An authoritative source that is unavailable or invalid must not fall back to environment variables, File, middleware dumps, cached state, or an older revision.

Role in the E2E path

• Register / Discover: supplies explicit provider configuration and watched bindings; it does not become Catalog, Registry, or Directory.
• Install: cannot alter Workspace authorization, Installation, Permission, exact Release, Card digest, or provenance.
• Invoke: Router captures one validated immutable policy/topology snapshot for the complete JSON, SSE, and cancellation lifecycle.
• Record: configuration values, credentials, tokens, payloads, and provider internals never enter Ledger or safe status output.

Goals

• Define provider-neutral snapshot, watch, lifecycle, revision, and typed failure contracts.
• Validate the abstraction with deterministic File and Nacos adapters.
• Keep administrative publish/delete capabilities separate from runtime read capabilities.
• Keep service-owned typed configuration and validation in each deployment boundary.
• Apply accepted dynamic updates atomically as immutable snapshots.
• Preserve exact-Release authorization and fail closed on missing, invalid, deleted, stale, or interrupted state.
• Expose only safe revision/freshness evidence needed to prove that Router consumed a topology transition.

Non-goals

• Building a configuration-center server.
• Replacing Catalog as the Agent Card/Release fact source.
• Owning Provider registration, lease/heartbeat, health discovery, instance selection, Workspace authorization, or Ledger.
• Introducing retry, provider switching, alternate endpoint/Release, stale-cache success, source precedence, or fallback.
• Distributing private keys, bearer tokens, database credentials, or other secrets through a generic document.
• Making every startup field hot-reloadable.

Deliverables

• Add an ADR defining ownership, bootstrap, revision/watch semantics, reloadability, readiness, secrecy, and failure behavior.
• Update AGENTS.md and configuration ownership documentation.
• Define root config_center interfaces, typed errors, snapshots, subscriptions, and explicit factories.
• Add deterministic File and Nacos adapters with one provider-neutral conformance suite.
• Refactor service loaders to accept injected sources while preserving strict, command-scoped validation.
• Define versioned service-configuration and governance documents at process boundaries.
• Add immutable Router runtime-policy/topology consumption with one snapshot per complete Invocation.
• Add safe readiness evidence and operator documentation.
• Add authenticated, versioned, safe status evidence for observed topology state, local revision, and freshness.
• Split registration/discovery into [Framework] Register and discover exact-Release runtime instances #89 and managed invocation into [Framework] Complete managed Consumer-to-Provider invocation #90.

Acceptance criteria

• File and Nacos satisfy the same snapshot/watch/error contract.
• Missing, empty, invalid, unauthorized, unavailable, deleted, stale, and interrupted states remain distinct.
• Dynamic policy cannot change authorization or immutable Release provenance.
• Status reads are observational only: they do not probe, reconnect, retry, or mutate watch state.
• No endpoint, source token, provider metadata, configuration content, credential, Agent payload, or private key is exposed through logs, events, status, or Ledger.
• Core unit, conformance, race, service-integration, and Stack acceptance are proportional to each change.

Related work

• Runtime registration and discovery: [Framework] Register and discover exact-Release runtime instances #89
• Managed Consumer -> Router -> Provider 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]

Companion architecture issues are now tracked in #89 (Agent Instance Registry/Directory) and #90 (External Gateway integration). Sample Agent acceptance fixtures are tracked in NeKiro-project/NeKiro-Samples#3.

[XnLemon]

Runtime integration is now in Core PR #98, Samples PR NeKiro-project/NeKiro-Samples#4, and Stack PR NeKiro-project/NeKiro-Stack#3. The checked items are limited to injected loaders, the versioned File-backed routing document/provider, one snapshot per Invocation, safe readiness, and operator documentation. Nacos, metrics/status, and broader governance fields remain open.

[XnLemon]

Core runtime integration has now merged through #98 as 0d32fb4. This closes the File-backed application integration slice: injected service loaders, the Router-owned router-instance-directory.v1 document, one immutable directory snapshot per Invocation, exact-Release instance selection, stream/cancel endpoint affinity, safe readiness, and the runtime operations runbook. Review closure also restricts selectors to changing only endpoint host/port, preserves caller cancellation, and aligns DNS/port-name validation. All required CI, Linux/Windows Config Center tests, Registry tests, race validation, vet, and patch coverage passed.

NeKiro-project/NeKiro-Samples#4 and NeKiro-project/NeKiro-Stack#3 remain open. Nacos, metrics/status projection, broader governance fields, and multi-instance policy remain unchecked.

中文

Core 运行时接入已通过 #98 合并，merge commit 为 0d32fb4。本轮完成了 File-backed 应用层接入：服务配置 source 注入、Router 自有的 router-instance-directory.v1 文档、每个 Invocation 一份不可变目录快照、精确 Release 实例选择、stream/cancel endpoint 固定、安全 readiness 和运行时运维文档。Review 收尾还限制 selector 只能修改 endpoint host/port，保留调用方取消语义，并统一 DNS/port-name 校验。required CI、Linux/Windows Config Center、Registry、race、vet 和 patch coverage 均通过。

NeKiro-project/NeKiro-Samples#4 与 NeKiro-project/NeKiro-Stack#3 仍为 open。Nacos、metrics/status、更广的 governance 字段和多实例策略继续保持未勾选。