feat(host): switch the generic interfaces to fault end to end#215
Open
mfw78 wants to merge 1 commit into
Open
Conversation
Move local-store, remote-store, identity and messaging off the unified host-error and onto the per-interface fault vocabulary. These four only ever produced generic kinds, so the interface is now the failure domain and the seven fault cases carry the cause directly. The WIT fns return result<_, fault>; the runtime host impls construct fault cases (store StorageError folds to internal, the deferred backends report unsupported); the nexum-sdk LocalStoreHost trait returns Result<_, Fault> and a From<Fault> bridge lets a strategy aggregate a store fault and a chain host-error into one return; the bind macro grows convert_fault; the nexum-sdk-test and shepherd-sdk-test store mocks and the raw flaky-bomb call sites move with it. Chain, cow-api and the module exports stay on host-error until their own migration.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #208 (part of the typed-fault train stacked on the epic-80 stack, epic #206; merges in stack order after #213, feat/fault-vocabulary).
Moves the four generic host interfaces (local-store, remote-store, identity, messaging) from the unified
host-errorenvelope to the typedfaultvocabulary end to end: WIT signatures, host implementations, the SDK host trait and macro conversion ladder, mocks, and the one raw wit-bindgen module fixture that needs its own converter.Changes
Each of
wit/nexum-host/{local-store,remote-store,identity,messaging}.witmoves every function fromresult<_, host-error>toresult<_, fault>and pulls inuse types.{fault}(messaging keepsmessagealongside it).identity.witalso updates its doc comment: rejection is now described asfault.denied.Chain, the event-module and query-module exports, and logging are untouched, since they are out of scope for this sub-issue.
crates/nexum-runtime/src/host/error.rsretargetsFrom<StorageError>fromHostErrortoFault(Fault::Internalcarryingerr.to_string()), with the module doc reworded to describe both shapes side by side.HostErrorconstructors stay live, since chain and cow-api impls still return them.The four host impls under
crates/nexum-runtime/src/host/impls/return theFaultassociated error type.Local-store maps
StorageErrorthrough the retargetedFrom; the three deferred backends (remote-store, identity, messaging) returnFault::Unsupportedcarrying the same detail string the priorunimplemented()used.accounts/querycontinue to return an emptyOk.crates/nexum-sdk/src/host.rschangesLocalStoreHosttoResult<_, Fault>and addsimpl From<Fault> for HostError, which is the bridge that lets module strategies still returning a unifiedHostErrorcall the now-fault-typed store methods with a mechanical?.The
Hostdoctest is updated to match.crates/nexum-sdk/src/wit_bindgen_macro.rsaddsconvert_fault, mapping the wit-bindgen-generatedFaultto the SDKFault(including theRateLimitfield), and routes theLocalStoreHostimpl through it.Macro-level docs list the new symbol.
crates/nexum-sdk/src/chain/chainlink.rsupdates the testStubHoststore methods to returnFault.crates/nexum-sdk-test/src/lib.rsandcrates/shepherd-sdk-test/src/lib.rsmoveMockLocalStore/MockHoststore methods,fail_on,check_injected_error,error_patterns, and the max-entries error path ontoFault, with the two crate-internal unit tests updated to match.modules/fixtures/flaky-bomb/src/lib.rsis a raw wit-bindgen module without the SDK macro, so it gets its own smallstore_faulthelper that folds thelocal-storefault back into the exporthost-errorso the counter reads and writes still compose with?.Test plan
cargo fmt --all --checkcargo clippy --workspace --all-targets --all-features -- -D warningscargo doc --workspace --no-depswithRUSTDOCFLAGS=-D warningswasm32-wasip2 --release, in-tree, so supervisor e2e/boot tests resolve fresh artefactscargo test --workspace --all-featurescargo test -p nexum-runtime --all-features(196 passed, 0 failed, 0 skipped), includingsupervisor::tests::restart_flaky_module_recovers_after_backoff, which drives the flaky-bomb guest'slocal_store::get/setacross the wasm boundary against the newresult<_, fault>wire typeNotes for reviewer
From<Fault> for HostErrorinnexum-sdkis new and is the one deliberate aggregation seam in this change.Module strategies (twap-monitor, ethflow-watcher, balance-tracker, stop-loss) each return a single
Result<_, HostError>while mixing a now-fault-typed store call with still-host-error chain and cow-api calls, so the bridge keeps?mechanical across roughly thirty call sites without touching their signatures.It disappears once chain, cow-api, and the export boundary also migrate to fault.
Faultdeliberately omitsdomain/code.Every prior detail string is preserved verbatim in the fault payload (deferred-backend messages,
StorageErrordisplay output, mock injected-error messages); the dropped fields were always static per-interface constants that are redundant once the interface itself is the WASI domain tag.flaky-bombhand-rolls its converter because it uses raw wit-bindgen rather than the SDK macro, and keepsdomain: "local-store"since it constructs the exportHostErrordirectly.Left for a follow-up: prose in
docs/00-overview.md,docs/07-rpc-namespace-design.md,docs/08-platform-generalisation.md,docs/adr/0009, anddocs/migration/0.1-to-0.2.mdstill describes a single unified host-error model. A partial edit here would leave those pages internally inconsistent mid-migration, so a coherent doc pass is deferred until chain, cow-api, and the exports also move.AI Assistance: Claude Code (Opus 4.8 implementation and adversarial review, Sonnet 5 PR authoring) used for the full change.