Listeners & Edges

An edge is a projection, not an authority

Three crates under crates/protocol/ terminate a wire protocol and expose Chio’s own tools through it: chio-mcp-edge, chio-a2a-edge, and chio-acp-edge. Each one takes a set of validated chio_manifest::ToolManifests, projects them into that protocol’s discovery shape, parses that protocol’s JSON-RPC envelope, and dispatches every governed call into chio_kernel::ChioKernel. Capability matching, guard evaluation, and receipt signing happen in the kernel. The edge decides what the answer looks like on the wire and nothing else.

Two more crates sit beside them. chio-cross-protocol holds the one orchestrator the A2A and ACP authoritative paths both run through: capability lineage, scope attenuation, route planning, and trace construction, so neither bridged edge reimplements them against the kernel on its own. Its own architecture note is explicit that it is a library and not an edge, with no transport and no wire format of its own. chio-edge-metrics holds the receipt-write counter type, and only those same three edges depend on it.

Read the shipped-listener line carefully, because it is narrower than the crate list suggests. Two commands terminate MCP inside a shipped binary: chio mcp serve, which wraps an upstream MCP server and runs ChioMcpEdge::serve_stdio over stdin and stdout, and chio mcp serve-http, the remote edge. A2A and ACP ship no listener. Both crates build JSON-RPC response values and, for A2A, Agent Card JSON, and leave the transport to the caller; chio-a2a-edge’s architecture note says outright that the crate has no HTTP server dependency. Their only in-repo consumers are chio-conformance, the fuzz workspace, and the two worked examples, which drive handle_jsonrpc from a stdio line loop.

One decision, three envelopes

The three edges differ in method names, discovery document, and task vocabulary. They agree on everything that matters: manifests in, kernel-signed receipt metadata out, one chio_receipt_write_total increment per terminal outcome.

Neither deferred lifecycle streams. On A2A, message/stream allocates a task id and stores a Working DeferredA2aTask without calling the kernel at all; task/get executes the stored request once through the orchestrator, writes the terminal TaskResponse back into the table, and returns that same stored value on every later poll. ACP is the same shape with tool/resume in place of task/get. Both tables are bounded at 1024 tasks still in a non-terminal status and prune anything older than 5 minutes (MAX_DEFERRED_A2A_TASKS / DEFERRED_A2A_TASK_TTL_MILLIS, and the ACP pair of the same shape), with the sweep running before every stream, poll, and cancel. Terminal tasks are exempt from the cap and are bounded only by the TTL sweep. Both edges check owner_agent_id against the calling agent_id before serving or mutating a task.

That shape is published, not implied. runtime_lifecycle_contract returns a fixed record per lifecycle case, and the edges embed it in their response metadata under runtimeLifecycle so a client can read the delivery mode rather than guess it.

RuntimeLifecycleSurface::AcpAuthoritative => RuntimeLifecycleContract {
    surface: "acp_authoritative".to_string(),
    blocking_entrypoint: "tool/invoke".to_string(),
    stream_entrypoint: "tool/stream".to_string(),
    follow_up_entrypoint: "tool/resume".to_string(),
    cancel_entrypoint: "tool/cancel".to_string(),
    stream_delivery: "resumed_terminal_payload".to_string(),
    partial_output_delivery: "resumed_terminal_payload".to_string(),
    claim_eligible: true,
    compatibility_only: false,
},

There are four cases, not two: A2aAuthoritative, A2aCompatibility, AcpAuthoritative, and AcpCompatibility. The two compatibility records report claim_eligible: false, compatibility_only: true, and "unsupported" for the stream, follow-up, and cancel entrypoints. Branch on claimEligible, not on the method name: the compatibility record reuses the same blocking entrypoint string the authoritative one does.

What an edge refuses to publish

A tool that cannot be projected honestly onto a protocol is withheld from that protocol’s discovery document rather than advertised with a caveat nobody reads. BridgeFidelity is the three-way verdict, and published_by_default() is !matches!(self, Self::Unsupported { .. }).

#[serde(rename_all = "snake_case", tag = "kind")]
pub enum BridgeFidelity {
    Lossless,
    Adapted { caveats: Vec<String> },
    Unsupported { reason: String },
}

The inputs come from the tool definition and from x-chio-* extensions on its input or output schema, read in that order by semantic_hints_for_tool. Five hints exist. Two of them fall back to the tool definition’s latency_hint rather than to a constant, and a third inherits whatever streams_output resolved to.

The sixth extension is the target protocol. x-chio-target-protocol resolves through parse_discovery_protocol to one of six families: native, http, mcp, a2a, acp, and open_ai (the parser also accepts openai, and it trims and lowercases first). Absent, it defaults to the registry’s default, which both the A2A and ACP edges set to Native. Both edges register exactly two executors, McpTargetExecutor from chio-mcp-edge and OpenAiTargetExecutor, so supports_target_protocol is true for exactly three of the six. A tool declaring http, a2a, or acp as its target resolves to Unsupported and is withheld from the A2A and ACP discovery documents; an unparseable value fails edge construction outright. The MCP edge reads no x-chio-target-protocol at all and lists the tool regardless.

The three edges gate differently

A gated tool does not disappear. Both A2A and ACP keep the verdict queryable: bridge_fidelity(id) returns the recorded BridgeFidelity including Unsupported entries that never reached the discovery document, and the reason string names the cause. For a published-but-lossy tool, the caveat list on Adapted is the honest description of the gap: on A2A a stream-capable tool carries the caveat that chunks are collated into the terminal task payload rather than pushed as incremental events.

The one path an authoritative call takes

Both the A2A and ACP edges reach the kernel through the same function, CrossProtocolOrchestrator::execute, supplying only a CapabilityBridge implementation for their envelope shape. The MCP edge reaches the kernel directly on its own tools/call path and appears on the other side of the orchestrator as McpTargetExecutor, the registered executor for an mcp target.

Three steps in that sequence are worth reading literally. Identity fields are validated before any lineage exists and are never trimmed: origin_request_id, kernel_request_id, target_server_id, target_tool_name, and agent_id must be non-empty, unpadded, and free of control characters, so signed lineage describes exactly what the caller submitted. A caller-supplied capability reference is cross-checked against the active capability’s id, its parent hash, and the bridge’s own source_protocol, and a mismatch on the last of those is rejected even when id and hash are correct. And the attenuation is enforced, not merely computed:

let attenuated_scope = attenuate_scope_for_tool(
    &request.capability.scope,
    &request.target_server_id,
    &request.target_tool_name,
);
if !attenuated_scope.is_subset_of(&request.capability.scope) {
    return Err(BridgeError::InvalidAttenuation(
        "attenuated scope must remain a strict subset of the parent capability".to_string(),
    ));
}

attenuate_scope_for_tool keeps only the grants whose server and tool match the concrete target, or match by *, rewrites the wildcard to the concrete pair, and drops resource and prompt grants entirely. What crosses a protocol hop is therefore narrower than the parent capability by construction, and the envelope that records it carries schema chio.cross-protocol-cap.v1.

Route planning runs before dispatch and returns one of three decisions. Select keeps the requested target, Attenuate falls back to a different available one, and Deny refuses. Preference, native fallback, and an outright ban on projected protocols come from a chioControlPlane object inside the governed intent’s context, read under both camelCase and snake_case keys. Two properties of the planner matter operationally: it never selects a non-native target with no registered executor, however the availability map is set, and with no candidate available it fails closed to Deny. A denied route is not an error return. The kernel signs a deny response through sign_planned_deny_response, the orchestrator still assembles route and trace evidence, and the caller gets a receipt-bearing refusal. Route selection evidence and any caller-supplied receipt_context are threaded into an executed kernel call, so they land inside the signed receipt metadata and not only in the return value. A planned deny carries the route evidence but not the caller’s receipt_context: metadata_with_source_receipt_context runs on an executed target and not on the deny branch. The signed route plan itself is covered in Route Plans.

What comes back is one OrchestratedToolCall, whose metadata() renders the chio object each edge attaches to its own protocol response: the full receipt and its id, a receiptRef carrying trace and bridge ids, the decision as allow, deny, or pending_approval, authorityPath fixed at cross_protocol_orchestrator, authoritative: true, the terminal state, the execution nonce, the capability envelope, and the route and trace records. trace_id and session_fingerprint are both SHA-256 over canonical JSON, the first over the request and route identity and the second over agent, capability, source protocol, and bridge id.

The compatibility passthrough is not a receipt path

The A2A and ACP edges each carry a second, explicitly non-authoritative route that bypasses the kernel and calls a raw dyn ToolServerConnection directly. It exists for bounded migration and for tests. It is compiled only under cfg(test) or the compatibility-surface feature, which is not in either crate’s default feature set, and it is reachable only through a wrapper the caller has to name: ChioA2aEdgeCompatibility or ChioAcpEdgeCompatibility.

The responses label themselves. Every passthrough result on a given edge carries the same metadata block, with the authority fields hard-coded rather than derived from a verdict.

#[cfg(any(test, feature = "compatibility-surface"))]
fn passthrough_metadata(reason: Option<&str>) -> Value {
    json!({
        "chio": {
            "receiptId": Value::Null,
            "receipt": Value::Null,
            "decision": "passthrough",
            "capabilityId": Value::Null,
            "authorityPath": "passthrough_compatibility",
            "authoritative": false,
            "compatibilityOnly": true,
            "claimEligible": false,
            "receiptBearing": false,
            "reason": reason,
        }
    })
}

The A2A block adds two keys to that shape: a runtimeLifecycle record built by runtime_lifecycle_metadata(RuntimeLifecycleSurface::A2aCompatibility) and a lifecycle object reporting messageSend: "blocking_terminal_task" and messageStream: "unsupported".

The discovery answer is labelled too. session/list_capabilities on the ACP passthrough attaches compatibility_surface_metadata(), which reports receiptBearingInvoke: false, the compatibility lifecycle record, and an explicit unsupportedLifecycleMethods array naming tool/stream, tool/cancel, and tool/resume. Calling any of those three on the passthrough returns JSON-RPC -32601 with a chio data block repeating authoritative: false.

The A2A passthrough also refuses message/stream with -32601, but it refuses more thinly: jsonrpc_stream_not_supported returns a bare message and no chio data block, so a client cannot read authoritative: false off that error. The permission analogue lives on ACP only. evaluate_permission_passthrough answers from configuration alone: allow when the published capability does not require permission, deny when it does or when the id is unknown, with no capability token consulted at all. A2A exposes no permission method for it to mirror.

The one behavior the passthrough does share with the kernel is its refusal to deadlock. Both edges cross from async into sync through block_on_tool_server_invoke, which mirrors the kernel’s own runtime-flavor gate: block_in_place on a multi-thread runtime, futures::executor::block_on with no runtime active, and a typed SyncBridgeIncompatibleWithCurrentThreadRuntime error under a current-thread runtime rather than parking the only worker thread. The ACP call site converts that error into a failed passthrough response carrying the same non-authoritative metadata.

The kernel-backed ACP preview is the case most easily confused with the passthrough, so read the difference. session/request_permission on the authoritative path runs evaluate_permission_with_kernel, which verifies the capability signature, its validity window, its subject against the calling agent, and the request against the matched grant, and consults verify_dpop_for_permission_preview when the grant requires sender binding. It still returns permission_preview_metadata with authoritative: false and previewOnly: true, because it deliberately does not consume the DPoP nonce a later tool/invoke will spend. The difference between the two previews is the invokeAuthorityPath field: cross_protocol_orchestrator for the kernel-backed one, passthrough_compatibility for the other.

One counter, four outcomes, three instances

Every edge writes the same series, chio_receipt_write_total, declared once in the workspace registry chio-metrics-spec as a counter with a single outcome label. chio-edge-metrics re-exports the registered name rather than redeclaring the string, and implements the counter behind it.

/// Stable exporter order for receipt-write outcome samples.
pub const RECEIPT_WRITE_OUTCOMES: [ReceiptWriteOutcome; 4] = [
    ReceiptWriteOutcome::Allow,
    ReceiptWriteOutcome::Deny,
    ReceiptWriteOutcome::PendingApproval,
    ReceiptWriteOutcome::Error,
];

The error bucket is narrow on purpose, and the three edges narrow it slightly differently. The MCP edge routes kernel errors through record_receipt_write_kernel_error, which excludes exactly two variants: RequestCancelled and UrlElicitationsRequired, both of which are retryable or caller-driven rather than infrastructure faults. The A2A and ACP edges use record_receipt_write_bridge_error, which increments only for BridgeError::Kernel: an unregistered target protocol, a malformed envelope, or a failed attenuation returns an error to the caller and writes no counter at all.

Counter state is per edge, and that is the reason the crate exposes an instance type rather than module-level statics. Each edge declares its own static COUNTERS: ReceiptWriteCounters = ReceiptWriteCounters::new(); and delegates recording and rendering to it. Increments run through fetch_update with saturating_add, so a counter caps at u64::MAX instead of wrapping, which is pinned by receipt_write_counters_saturate_instead_of_wrapping. Both record and total map an unknown label to the error bucket rather than dropping it, so total("totally-unknown") returns the error count.

Rendering is deliberately minimal: one # HELP line, one # TYPE line, and four labelled samples in the fixed order above, so exposition text is byte-stable across scrapes. Each edge’s render_*_edge_metrics_prometheus then appends the receipt-writer liveness gauges, which is why a wedged writer shows up on the same scrape as the outcome totals.

# HELP chio_receipt_write_total Total receipt write outcomes after policy or guard evaluation.
# TYPE chio_receipt_write_total counter
chio_receipt_write_total{outcome="allow"} 128
chio_receipt_write_total{outcome="deny"} 9
chio_receipt_write_total{outcome="pending_approval"} 3
chio_receipt_write_total{outcome="error"} 0
# TYPE chio_receipt_writer_healthy gauge
chio_receipt_writer_healthy 0
# TYPE chio_receipt_writer_liveness gauge
chio_receipt_writer_liveness{state="wedged"} 1

The sample values above are illustrative; the shape, the ordering, and the two gauge lines are exactly what the renderer emits. chio_receipt_writer_healthy is ReceiptWriterLiveness::healthy() rendered as 0 or 1, and that predicate is matches!(self, Self::Healthy | Self::Unknown). Read the two lines together: state="unknown" also reports healthy 1, so a host that has not wired an async writer and passes Unknown looks healthy on the gauge alone. The five states are healthy, saturated, wedged, dead, and unknown.

The shipped Prometheus rules consume this series in exactly one way. deploy/prometheus/chio-recording-rules.yml defines chio:receipt_write_error_ratio_5m, _1h, and _6h as the rate of outcome="error" over the clamped rate of the whole family, and chio-alert-rules.yml pages on a two-window burn (ChioReceiptWriteErrorBudgetBurn1h) and on absent_over_time(chio_receipt_write_total[10m]) (ChioReceiptWriteMetricsMissing), both at severity: p1. A conformance test reads those rule files as text and asserts the numerator: it fails the build if pending_approval appears anywhere in them, and if the family is counted as outcome!="success". Denials and pending approvals are normal traffic and must never enter an error budget.

Choosing what a node terminates

There is no runtime switch that turns an edge on. Which protocols a node terminates is decided by which binary is running and, for an embedded host, by which edge type it constructs. The two shipped MCP listeners are chio mcp serve and chio mcp serve-http. An A2A or ACP edge is constructed in process: ChioA2aEdge::new(A2aEdgeConfig, Vec<ToolManifest>) or ChioAcpEdge::new(AcpEdgeConfig, Vec<ToolManifest>), with the host owning the socket or the pipe.

Construction validates before it publishes. Every manifest passes chio_manifest::validate_manifest first, and any failure rejects the whole edge. The A2A config is validated separately: agent name, version, endpoint URL, and protocol binding must each be non-empty and free of leading or trailing whitespace, and a violation fails construction rather than being trimmed. The ACP config is two fields, require_permission (default true) and default_category (default AcpCategory::Tool), and a published capability’s requires_permission is config.require_permission || tool.has_side_effects.

adapters:
  - id: "petstore"
    protocol: "openapi"
    upstream: "http://localhost:8000"
    spec: "./petstore.yaml"

edges:
  - id: "mcp-bridge"
    protocol: "mcp"
    expose_from: "petstore"

The feature flags are the other half of the decision, and both edges ship with an empty default feature set. compatibility-surface compiles the passthrough into a non-test build; otel on chio-a2a-edge and chio-mcp-edge enables the GenAI span helpers; fuzz on chio-acp-edge and chio-mcp-edge exposes a libFuzzer entry point over the decode-then-dispatch pipeline and is enabled only by the standalone fuzz workspace. Auditing what a node terminates therefore means auditing the enabled feature set as well as the command line.

Guarantees and limits

Next Steps

• Remote MCP Edge · the one edge that ships as a hosted listener, from bind through bearer mode to per-session kernel
• Node Overview · the process these edges live in, and what it owes a cluster
• Bridges · the normative per-protocol fidelity and receipt-continuity contract this page implements
• Node Observability · the metric families a node exports without help, next to the one an edge hands you as a string
• Route Plans · the signed record that pins a delegated dispatch to one bridge and one protocol target