Skip to content

feat(host): exports return fault and the host-error envelope dies#217

Open
mfw78 wants to merge 2 commits into
feat/fault-cow-api-errorfrom
feat/fault-teardown
Open

feat(host): exports return fault and the host-error envelope dies#217
mfw78 wants to merge 2 commits into
feat/fault-cow-api-errorfrom
feat/fault-teardown

Conversation

@mfw78

@mfw78 mfw78 commented Jul 6, 2026

Copy link
Copy Markdown
Contributor

Summary

Closes #211; part of the typed-fault train stacked on the epic-80 stack, merges in stack order.

init, on-event, and evaluate now return result<_, fault> and the host-error envelope is gone from the wire, both SDKs, and every module.

Changes

  • Deleted host-error and host-error-kind from types.wit; event-module.wit and query-module.wit switch their exports to result<_, fault>.
  • nexum-runtime: host/error.rs drops the unused unimplemented/internal_error constructors and adds fault_label/fault_message; the supervisor derives its metric label and log kind/message from the fault label instead of a format!("{:?}") allocation on the old HostError; DispatchOutcome::HostError becomes DispatchOutcome::Fault.
  • nexum-sdk: removed HostError/HostErrorKind and their From impls, added From<ChainError> for Fault (the Rpc case folds to Fault::Internal, preserving the node code, message, and revert bytes) and sdk_fault_into_wit in the bindgen macro, replacing convert_err/sdk_err_into_wit.
  • Migrated all seven example and M2 strategy modules plus the four fixtures to return fault; flaky-bomb loses its store_fault shim entirely.
  • Added docs/adr/0011-per-interface-typed-errors.md and swept the full docs/ prose tree (overview chapters, migration guide, tutorial, diagrams, operations, production, qa-signoff, and the linker-extension-seam design note) to describe the fault model instead of the retired envelope, annotating ADR-0009 as superseded in part.

Test plan

  • cargo fmt --all --check
  • cargo clippy --workspace --all-targets --all-features -- -D warnings
  • cargo test --workspace --all-features (200 nexum-runtime unit tests plus all crate suites and doctests, 0 failed, 0 skipped)
  • All 11 module wasms rebuilt with RUSTFLAGS="-D warnings", both in the scratch target and in-tree, so the supervisor e2e and harness tests ran for real (no SKIP: notes)
  • rg 'host-error|HostError|host_error' docs/ returns matches only inside ADR-0011 (the record of the change) and ADR-0009 (its historical body, now flagged superseded)

Notes for reviewer

The shepherd_module_errors_total error_kind label value changes shape: it was Debug-cased (for example InvalidInput) and is now the snake_case fault vocabulary (invalid_input). Anything scraping that label needs updating alongside this merge.

fault_label/fault_message are implemented runtime-local rather than pulling in nexum-sdk's HostFault, since the runtime does not and should not depend on the guest SDK; the label deliberately mirrors the HostFault snake_case vocabulary so the two stay readable side by side.

Module faults drop the old code/data/domain fields and message prefixes per the fault spec, so the balance-tracker warn-log test now asserts on "rpc down" rather than the numeric "503" code.

Two follow-ups are intentionally out of scope: the diagram .mmd sources are updated but the committed .png renders are stale (regeneration needs mermaid-cli, unavailable in this environment), and docs/production.md carries roughly thirty pre-existing em-dashes unrelated to this change that still want a house-style pass.

AI Assistance: Claude Code (Opus 4.8 implementation and adversarial review, Sonnet 5 PR authoring) used for the full change.

mfw78 added 2 commits July 6, 2026 02:53
Module exports (init/on-event/evaluate) now return result<_, fault>.
Module identity is the supervisor's business, so the domain self-naming
and message-prefix duplication in modules die: the supervisor derives
its error metric label and log kind from the fault label via HostFault,
dropping the per-dispatch format debug allocation.

host-error and host-error-kind are deleted from types.wit and every
mirror: the runtime host constructors, both guest SDKs, both SDK test
crates, and the module glue. From<ChainError> for Fault folds a chain
error into the shared vocabulary so a strategy aggregating store and
chain calls returns one fault. ADR-0011 records the per-interface error
model.

All module wasms rebuild; the supervisor e2e suite runs for real.
Sweep the prose docs to match the shipped host-error teardown: WIT
snippets, Rust code samples, mapping tables, and mermaid sources now
describe per-interface typed errors (chain-error, cow-api-error) over
the shared fault vocabulary instead of the deleted host-error /
host-error-kind envelope. Module exports return result<_, fault>, and
identity, local-store, remote-store and messaging report fault directly.

ADR-0011 stays the record of the change; ADR-0009 gains a superseded
note pointing at it, and the migration guide now presents fault as the
0.2 error destination that other chapters link to.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant