Listeners & Edges

Discovery per edge

All three take manifests in, return kernel-signed receipt metadata, and write the shared receipt-write metric for governed outcomes. The hello-a2a and hello-acp examples serve the bridged edges over stdin; serve_stdio in examples/hello-a2a/src/lib.rs is the loop.

Deferred tasks

On A2A, message/stream allocates a task id and stores a Working DeferredA2aTask without calling the kernel; task/get executes the stored request once through the orchestrator, writes the terminal TaskResponse back into the table, and returns that stored value on every later poll. ACP has the same shape with tool/resume in place of task/get. Both edges check owner_agent_id against the calling agent_id before serving or changing a task.

Each table lives in process memory and holds at most 1024 tasks in a non-terminal status (MAX_DEFERRED_A2A_TASKS, and the ACP pair of the same shape). A sweep before every stream, poll, and cancel prunes tasks past a 5 minute TTL (DEFERRED_A2A_TASK_TTL_MILLIS). ensure_deferred_task_capacity counts only non-terminal tasks, so terminal ones are bounded by the TTL sweep alone, and a restart clears both tables.

Lifecycle records

runtime_lifecycle_contract returns a fixed record per case, embedded in response metadata under runtimeLifecycle.

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: A2aAuthoritative, A2aCompatibility, AcpAuthoritative, and AcpCompatibility. The compatibility records report claim_eligible: false, compatibility_only: true, and "unsupported" for the stream, follow-up, and cancel entrypoints. They reuse the authoritative blocking entrypoint string, so branch on claimEligible, never on the method name.

Fidelity hints

Hints 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. published_by_default() is !matches!(self, Self::Unsupported { .. }).

The sixth extension, x-chio-target-protocol, resolves through parse_discovery_protocol, which trims and lowercases, to one of six families: native, http, mcp, a2a, acp, and open_ai (it also accepts openai). Absent, it takes the registry default, which both bridged edges set to Native. Both register two executors, McpTargetExecutor from chio-mcp-edge and OpenAiTargetExecutor, in authoritative_target_registry, so supports_target_protocol holds for native, mcp, and open_ai. A tool naming http, a2a, or acp resolves to Unsupported and is withheld from A2A and ACP discovery; an unparseable value fails edge construction. The MCP edge reads no x-chio-target-protocol and lists the tool.

Publication gates per edge

The A2A edge withholds approval-required tools because it cannot project an interactive approval prompt. A second identical qualified id gets a #n ordinal suffix, and looking up the bare name returns an ambiguity error that lists the qualified ids. On ACP, a collision also removes any capability or binding already recorded for that name; re-declaring the identical server and tool pair is not a collision. The MCP edge’s build_exposed_tool_bindings validates each manifest and schema and publishes every remaining tool, without consulting BridgeFidelity, semantic_hints_for_tool, or x-chio-publish.

The MCP projection carries readOnlyHint and destructiveHint, derived from has_side_effects and always each other’s inverse, plus an execution block with taskSupport: "optional" and, when a latency hint exists, a suggestedLatency label.

Route and receipt evidence

The chio metadata object also carries a receiptRef with trace and bridge ids, the terminal state, and the execution nonce. trace_id and session_fingerprint are SHA-256 over canonical JSON: the first over the request and route identity, the second over agent, capability, source protocol, and bridge id.

Route selection evidence and any caller-supplied receipt_context are threaded into an executed kernel call, so they land inside the signed receipt metadata. A route deny carries the route evidence without the caller’s receipt_context, because metadata_with_source_receipt_context runs on an executed target only. The MCP edge appears on the far side of the orchestrator as McpTargetExecutor, the registered executor for an mcp target.

A multi-hop route writes one receipt-write outcome, at the source edge. McpTargetExecutor::execute calls bridge_mcp_tool_call_from_response with record_receipt_write set to false, so an ACP or A2A call routed to an MCP target advances the source edge’s counter alone. Both edges build their McpTargetExecutor as a static with peer_supports_chio_tool_streaming: false, so a bridged MCP hop does not negotiate chunk streaming.

Passthrough metadata

#[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 a runtimeLifecycle record from runtime_lifecycle_metadata(RuntimeLifecycleSurface::A2aCompatibility) and a lifecycle object reporting messageSend: "blocking_terminal_task" and messageStream: "unsupported". On ACP, session/list_capabilities attaches compatibility_surface_metadata(): receiptBearingInvoke: false, the compatibility lifecycle record, and unsupportedLifecycleMethods naming tool/stream, tool/cancel, and tool/resume, each of which returns JSON-RPC -32601 with a chio data block repeating authoritative: false.

The A2A passthrough refuses message/stream with -32601 through jsonrpc_stream_not_supported, a bare message with no chio data block. evaluate_permission_passthrough, on ACP only, answers from configuration: allow when the published capability needs no permission, deny when it does or the id is unknown, with no capability token consulted. invoke_passthrough and handle_send_message_passthrough call no record_receipt_write* helper.

Both edges cross from async into sync through block_on_tool_server_invoke, which mirrors the kernel’s runtime-flavor gate: block_in_place on a multi-thread runtime, futures::executor::block_on with no runtime, and a typed SyncBridgeIncompatibleWithCurrentThreadRuntime error under a current-thread runtime. The ACP call site turns that error into a failed passthrough response with the same metadata.

Kernel-backed permission preview

session/request_permission on the authoritative ACP path runs evaluate_permission_with_kernel, which checks the capability signature, its validity window, its subject against the calling agent, and the request against the matched grant, and calls verify_dpop_for_permission_preview when the grant requires sender binding. It returns permission_preview_metadata with authoritative: false and previewOnly: true, because it leaves the DPoP nonce for the later tool/invoke to spend. The two previews differ in invokeAuthorityPath: cross_protocol_orchestrator for the kernel-backed one, passthrough_compatibility for the passthrough.

Constructing an edge

The running binary decides which protocols a node terminates, and an embedded host decides by the edge types it constructs: ChioA2aEdge::new(A2aEdgeConfig, Vec<ToolManifest>) or ChioAcpEdge::new(AcpEdgeConfig, Vec<ToolManifest>), with the host owning the socket or pipe. Every manifest passes chio_manifest::validate_manifest first, and one failure rejects the edge.

The A2A config’s agent name, version, endpoint URL, and protocol binding must each be non-empty without leading or trailing whitespace; a violation fails construction. The ACP config has two fields: require_permission (default true) and default_category (default AcpCategory::Tool). A published capability’s requires_permission is config.require_permission || tool.has_side_effects.

An edges entry in chio.yaml declares an edge: an id, a protocol string, and the expose_from adapter it publishes. validate_edges checks that ids are unique and non-empty and that expose_from names a declared adapter. Listeners start from the command line or from an edge a host constructs. The rest of the file is in chio.yaml Configuration.

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

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

Both bridged edges ship 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, enabled only by the standalone fuzz workspace. An audit of what a node terminates covers the enabled features as well as the command line.

Receipt-write metrics

Every edge writes chio_receipt_write_total, declared once in chio-metrics-spec as a counter with a single outcome label. chio-edge-metrics re-exports the registered name and implements the counter.

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

The MCP edge records kernel errors through record_receipt_write_kernel_error, which excludes RequestCancelled and UrlElicitationsRequired, both retryable or caller-driven. The bridged edges use record_receipt_write_bridge_error, which counts only BridgeError::Kernel; an unregistered target protocol, a malformed envelope, or a failed attenuation returns an error and writes no counter.

Each edge holds its own static COUNTERS: ReceiptWriteCounters = ReceiptWriteCounters::new();. Increments use fetch_update with saturating_add, so a counter caps at u64::MAX, pinned by receipt_write_counters_saturate_instead_of_wrapping. record and total map an unknown label to the error bucket, so total("totally-unknown") returns the error count.

# 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 shape, the order, and the two gauge lines are what the renderer emits, byte-stable across scrapes. chio_receipt_writer_healthy renders ReceiptWriterLiveness::healthy() as 0 or 1, and that predicate is matches!(self, Self::Healthy | Self::Unknown): a host that passes Unknown reports healthy, so read the liveness line beside it. The five states are healthy, saturated, wedged, dead, and unknown.

render_mcp_edge_metrics_prometheus, render_a2a_edge_metrics_prometheus, and render_acp_edge_metrics_prometheus each return the exposition as a String, and the host that embeds an edge serves it on its scrape route. 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 family. chio-alert-rules.yml pages at severity: p1 on a two-window burn (ChioReceiptWriteErrorBudgetBurn1h) and on absent_over_time(chio_receipt_write_total[10m]) (ChioReceiptWriteMetricsMissing), which fires while the exposition is unserved.

receipt_write_recording_rules_only_count_infrastructure_errors reads the rule files as text and fails the build if pending_approval appears in them or the family is counted as outcome!="success": denials and pending approvals are normal traffic and stay out of the error budget. Node Observability covers the families a node exports on its own.

Edge conformance tests

• acp_edge_emits_chio_receipt_write_total and a2a_edge_emits_chio_receipt_write_total in crates/tooling/chio-conformance/tests/metrics_registry_consumed.rs: a call routed to an MCP target advances the source edge’s allow counter by exactly one (acp_before_target + 1) and leaves the MCP edge’s unchanged.
• permission_preview_accepts_valid_dpop_without_consuming_invocation_nonce in chio-acp-edge/src/tests/all.rs: the preview mirrors invoke-time DPoP policy and leaves the nonce unspent.
• strict_nonce_retries_require_and_accept_stable_request_ids in chio-acp-edge/src/tests/nonce_preflight.rs: under strict execution nonces, a retry needs a stable request id.
• receipt_write_recording_rules_only_count_infrastructure_errors: pending_approval stays out of the error-budget numerator.