From be4ebc4cea7ffcae78ecf0be6727fff9ebe13645 Mon Sep 17 00:00:00 2001 From: Luiz Gustavo Abou Hatem de Liz Date: Thu, 16 Jul 2026 12:03:25 -0300 Subject: [PATCH] docs(adr-0011): record why request-batch keeps its dead outer chain-error request_batch's outer ChainError never returns Err on the reference host - every failure surfaces per-entry as rpc-result::err, folding the batch independently - so the escape hatch is structurally dead here. The reasoning for keeping it in the WIT contract (a different host could genuinely fail the whole batch atomically before dispatching any entry) already lived in a doc comment; recorded it in ADR-0011 too, per the issue's suggested fallback to flattening the WIT, and cross-linked the two. Fixes #288. --- crates/nexum-runtime/src/host/impls/chain.rs | 3 ++- docs/adr/0011-per-interface-typed-errors.md | 1 + 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/crates/nexum-runtime/src/host/impls/chain.rs b/crates/nexum-runtime/src/host/impls/chain.rs index 3fb67286..32db64fb 100644 --- a/crates/nexum-runtime/src/host/impls/chain.rs +++ b/crates/nexum-runtime/src/host/impls/chain.rs @@ -79,7 +79,8 @@ impl nexum::host::chain::Host for HostState { /// `RpcResult::Err`. This impl folds each entry independently, so a /// failure leaves its neighbours intact; a different host could instead /// short-circuit the batch, so SDK consumers match on each entry, not - /// on the batch call. + /// on the batch call. See ADR-0011's escape-hatch note for why the + /// WIT keeps the outer error despite it being dead here. async fn request_batch( &mut self, chain_id: u64, diff --git a/docs/adr/0011-per-interface-typed-errors.md b/docs/adr/0011-per-interface-typed-errors.md index 662e2445..28dc32ec 100644 --- a/docs/adr/0011-per-interface-typed-errors.md +++ b/docs/adr/0011-per-interface-typed-errors.md @@ -29,3 +29,4 @@ This is a pre-1.0 wire break. CI rebuilds every module wasm on a world change, s - Modules no longer restate their identity or prefix messages; the runtime supplies both. - The numeric `code` and opaque `data` fields are gone. An interface that needs structured detail (the JSON-RPC code, decoded revert bytes) carries it in a typed case instead. - Old bindings do not interoperate with the new world. Because this predates 1.0 and CI rebuilds all module wasms per world change, that break is accepted rather than shimmed. +- `chain-error`'s outer position on `request-batch` (`result, chain-error>`) is structurally dead on the reference host: every failure - a denied method, a node revert, a transport fault - surfaces per-entry as `rpc-result::err`, folding the batch independently, so the outer `Err` arm is never returned. It stays in the WIT contract as an escape hatch for a host that cannot make that same choice - one whose batch transport can only fail atomically before dispatching any entry - not because this host needs it. See the doc comment on `chain::Host::request_batch` (`crates/nexum-runtime/src/host/impls/chain.rs`).