diff --git a/crates/nexum-runtime/src/engine_config.rs b/crates/nexum-runtime/src/engine_config.rs index c950cf1f..c1b821d7 100644 --- a/crates/nexum-runtime/src/engine_config.rs +++ b/crates/nexum-runtime/src/engine_config.rs @@ -159,7 +159,7 @@ pub struct EngineConfig { #[serde(default)] pub engine: EngineSection, /// Per-module wasmtime resource limits. Applies uniformly to every - /// module; per-module overrides land in 0.3. + /// module. #[serde(default)] pub limits: ModuleLimits, /// Per-chain RPC URLs keyed by EIP-155 chain id. Numeric TOML keys @@ -176,10 +176,7 @@ pub struct EngineConfig { #[serde(default)] pub extensions: HashMap, /// Modules the supervisor should boot. Each entry resolves a - /// `(component.wasm, module.toml)` pair on the local filesystem - /// for 0.2 - content-addressed resolution (Swarm / OCI / - /// `[[content.sources]]`) lands in 0.3 per - /// `docs/03-module-discovery.md`. + /// `(component.wasm, module.toml)` pair on the local filesystem. #[serde(default)] pub modules: Vec, /// Provider components the supervisor should boot alongside the @@ -271,8 +268,8 @@ fn default_log_backfill_concurrency() -> usize { /// `[engine.metrics]` config. When `enabled = true` the engine starts /// a Prometheus HTTP exporter on `bind_addr` and serves `/metrics`. /// -/// Default: disabled. Operators opt in explicitly so the M3 / M4 -/// runbook smoke runs do not bind a port unintentionally. +/// Default: disabled. Operators opt in explicitly so a run does not +/// bind a port unintentionally. #[derive(Debug, Deserialize)] pub struct MetricsSection { #[serde(default)] diff --git a/crates/nexum-runtime/src/host/impls/identity.rs b/crates/nexum-runtime/src/host/impls/identity.rs index bbea4d44..392ed552 100644 --- a/crates/nexum-runtime/src/host/impls/identity.rs +++ b/crates/nexum-runtime/src/host/impls/identity.rs @@ -1,6 +1,6 @@ -//! `nexum:host/identity`: deferred to 0.3 (keystore / KMS backend). -//! `accounts()` returns an empty roster so guests can probe-then-skip; -//! signing returns `unsupported`. +//! `nexum:host/identity`: unimplemented stub. `accounts()` returns an +//! empty roster so guests can probe-then-skip; signing returns +//! `unsupported`. use crate::bindings::nexum; use crate::bindings::nexum::host::types::Fault; diff --git a/crates/nexum-runtime/src/host/impls/messaging.rs b/crates/nexum-runtime/src/host/impls/messaging.rs index 4cf45da5..459994ab 100644 --- a/crates/nexum-runtime/src/host/impls/messaging.rs +++ b/crates/nexum-runtime/src/host/impls/messaging.rs @@ -1,7 +1,6 @@ -//! `nexum:host/messaging`: the Waku backend is deferred to 0.3, so -//! `publish` reports `unsupported` and `query` returns empty, the same -//! posture as `identity::accounts`. The per-store topic scope is enforced -//! ahead of that stub: a provider carrying a +//! `nexum:host/messaging`: unimplemented stub. `publish` reports +//! `unsupported` and `query` returns empty. The per-store topic scope is +//! enforced ahead of that stub: a provider carrying a //! `[[adapters]].messaging_topics` grant may only publish within it, so //! the egress boundary is live even though delivery is not. diff --git a/crates/nexum-runtime/src/host/impls/remote_store.rs b/crates/nexum-runtime/src/host/impls/remote_store.rs index f2c8661f..1894484f 100644 --- a/crates/nexum-runtime/src/host/impls/remote_store.rs +++ b/crates/nexum-runtime/src/host/impls/remote_store.rs @@ -1,4 +1,5 @@ -//! `nexum:host/remote-store`: deferred to 0.3 (Swarm backend). +//! `nexum:host/remote-store`: unimplemented stub; every call returns the +//! unsupported fault. use crate::bindings::nexum; use crate::bindings::nexum::host::types::Fault; diff --git a/crates/nexum-runtime/src/host/provider_pool.rs b/crates/nexum-runtime/src/host/provider_pool.rs index 55d5e912..b30c7a40 100644 --- a/crates/nexum-runtime/src/host/provider_pool.rs +++ b/crates/nexum-runtime/src/host/provider_pool.rs @@ -44,10 +44,9 @@ const DEFAULT_POLL_INTERVAL: Duration = Duration::from_secs(2); /// Transport retry-layer parameters. `watch_canonical_logs_from` surfaces /// RPC errors to the caller and ends the stream on the first one unless -/// the transport retries it (per alloy's own guidance on that builder). -/// This layer heals transient blips below the poller, so a momentary node -/// hiccup does not force a re-open - and a re-open is exactly where a gap -/// could reappear. +/// the transport retries it. This layer heals transient blips below the +/// poller, so a momentary node hiccup does not force a re-open, which is +/// exactly where a gap could reappear. const RPC_MAX_RETRIES: u32 = 10; const RPC_RETRY_BACKOFF_MS: u64 = 300; /// Compute-units-per-second budget the retry layer paces rate-limited diff --git a/crates/nexum-runtime/src/manifest/mod.rs b/crates/nexum-runtime/src/manifest/mod.rs index da7e0c06..17b49ab2 100644 --- a/crates/nexum-runtime/src/manifest/mod.rs +++ b/crates/nexum-runtime/src/manifest/mod.rs @@ -1,21 +1,16 @@ -//! `module.toml` parser and capability-enforcement helpers (0.2 scope). +//! `module.toml` parser and capability-enforcement helpers. //! -//! 0.2 intentionally ships a slim subset of the manifest spec: -//! -//! - `[capabilities].required` is parsed and validated (names must be in -//! the known capability set; the 0.2 reference engine always provides -//! all of them, so this is a sanity check + future-proofing). -//! - `[capabilities].optional` is parsed and logged; trap-stub fallback -//! for absent optionals is deferred to 0.3. +//! - `[capabilities].required` is parsed and validated: names must be in +//! the known capability set, which the engine always provides. +//! - `[capabilities].optional` is parsed and logged. //! - `[capabilities.http].allow` is parsed and consulted by the //! wasi:http gate before any outbound call. //! - `[config]` is flattened to `Vec<(String, String)>` and passed to the -//! module's `init`. Typed `config-value` variant is deferred to 0.3. +//! module's `init`. //! //! When the manifest file is missing or has no `[capabilities]` section, -//! a deprecation warning is emitted and the engine falls back to 0.1 -//! behaviour (treat every linked capability as required). This fallback -//! will be removed in 0.3. +//! a deprecation warning is emitted and the engine falls back to treating +//! every linked capability as required. //! //! ## Layout //! diff --git a/crates/nexum-runtime/src/manifest/types.rs b/crates/nexum-runtime/src/manifest/types.rs index 1960dc61..a90f4abd 100644 --- a/crates/nexum-runtime/src/manifest/types.rs +++ b/crates/nexum-runtime/src/manifest/types.rs @@ -29,8 +29,8 @@ pub struct Manifest { pub config: toml::Table, /// Event subscriptions the runtime wires before calling /// `_init`. See `docs/02-modules-events-packaging.md` for the - /// schema; 0.2 implements `block` and `chain-log` kinds, `cron` is - /// parsed and ignored (deferred to 0.3). + /// schema. Implements `block` and `chain-log` kinds; `cron` is + /// parsed and ignored. #[serde(default, rename = "subscription")] pub subscriptions: Vec, /// Extension-owned sections: every non-core top-level key, parsed @@ -54,7 +54,7 @@ pub type ExtensionSections = BTreeMap; /// fails loudly rather than silently disabling an event source. #[derive(Debug, Clone)] pub enum Subscription { - /// New-block events. Fan-out is shared per chain - the + /// New-block events. Fan-out is shared per chain: the /// supervisor opens one subscription per chain id and routes to /// every module that asked for blocks on that chain. Block { @@ -62,7 +62,7 @@ pub enum Subscription { chain_id: u64, }, /// Chain-log events matching `address` + topic-0. Fan-out is - /// per-module - the supervisor opens one subscription per + /// per-module: the supervisor opens one subscription per /// `[[subscription]]` entry and tags emitted events with the /// owning module. ChainLog { @@ -71,7 +71,7 @@ pub enum Subscription { /// Contract address as `0x`-prefixed 20-byte hex. Optional. address: Option, /// Topic-0 of the event the module wants to consume. `0x`- - /// prefixed 32-byte hex. Optional - when absent the + /// prefixed 32-byte hex. Optional: when absent the /// subscription matches every event from the address(es). event_signature: Option, /// Resume across engine restarts. When `true` the host persists a @@ -87,10 +87,9 @@ pub enum Subscription { /// tolerates dropping the oldest missed blocks. max_lookback: Option, }, - /// Cron-scheduled tick. 0.2 parses but does not dispatch; the + /// Cron-scheduled tick. Parsed but not dispatched; the /// supervisor emits a warning so the operator knows the - /// declaration is currently inert. `schedule` is preserved so a - /// 0.3 dispatcher can pick it up without re-parsing the manifest. + /// declaration is currently inert. `schedule` is preserved verbatim. Cron { /// Standard 5-field cron expression. #[allow(dead_code)] diff --git a/crates/nexum-runtime/src/runtime/event_loop.rs b/crates/nexum-runtime/src/runtime/event_loop.rs index 3b848306..265e2885 100644 --- a/crates/nexum-runtime/src/runtime/event_loop.rs +++ b/crates/nexum-runtime/src/runtime/event_loop.rs @@ -670,7 +670,7 @@ mod tests { /// `open_block_streams` spawns one independent reconnect task per chain. /// Per-chain task isolation means a slow or reconnecting chain does not - /// delay events from other chains — each chain has its own mpsc channel + /// delay events from other chains: each chain has its own mpsc channel /// and backoff timer. #[tokio::test] async fn open_block_streams_opens_one_task_per_chain() { diff --git a/crates/nexum-runtime/src/runtime/restart_policy.rs b/crates/nexum-runtime/src/runtime/restart_policy.rs index 7b80dd62..26be7eb7 100644 --- a/crates/nexum-runtime/src/runtime/restart_policy.rs +++ b/crates/nexum-runtime/src/runtime/restart_policy.rs @@ -16,14 +16,13 @@ //! | ... | doubles | //! | 9+ | capped at 5 minutes | //! -//! State is in-memory per supervisor process. Persistence across -//! engine restarts is out of scope (a separate 0.3 / M5 follow-up -//! that lands alongside `submitted:{uid}` cross-restart dedup). +//! State is in-memory per supervisor process; it does not persist +//! across engine restarts. use std::time::Duration; /// Hard cap on the restart backoff. After ~8 doublings we plateau -/// here. Tuneable in 0.3 via `engine.toml::[engine.restart]`. +/// here. pub const RESTART_MAX_BACKOFF: Duration = Duration::from_secs(300); /// Compute the wait window the supervisor honours before the next diff --git a/crates/nexum-runtime/src/supervisor/tests.rs b/crates/nexum-runtime/src/supervisor/tests.rs index 829eae09..96bbb443 100644 --- a/crates/nexum-runtime/src/supervisor/tests.rs +++ b/crates/nexum-runtime/src/supervisor/tests.rs @@ -192,7 +192,7 @@ async fn run_does_not_bail_when_both_stream_kinds_are_empty() { // supervisor boundary, without loading a real wasm module. /// Block and chain-log streams are both consumed within the same `run()` -/// session — the `biased` select does not starve either event kind. One +/// session: the `biased` select does not starve either event kind. One /// item of each kind is queued before the loop starts; `run()`'s returned /// tally must show both were drained. A regression that breaks either /// select arm (or reorders the `biased` polling so one side never fires) @@ -259,8 +259,8 @@ async fn run_delivers_block_and_chain_log_events_without_starvation() { /// After `run()` returns on the shutdown path, all reconnect tasks are /// drained: the Shutdown arm calls `tasks.shutdown()`, which aborts every /// handle and then joins each one, so no task detaches and outlives the -/// engine. (The companion contract — a task parked on a dropped receiver -/// exits with `ReceiverGone` on its own — is asserted directly in +/// engine. (The companion contract, a task parked on a dropped receiver +/// exiting with `ReceiverGone` on its own, is asserted directly in /// `event_loop::tests::reconnect_task_exits_receiver_gone_when_receiver_drops`; /// it cannot be observed here because `TaskSet::shutdown` aborts first.) /// Issue #58. diff --git a/crates/nexum-runtime/src/test_utils/harness.rs b/crates/nexum-runtime/src/test_utils/harness.rs index 10d808d6..7dc21eef 100644 --- a/crates/nexum-runtime/src/test_utils/harness.rs +++ b/crates/nexum-runtime/src/test_utils/harness.rs @@ -641,7 +641,7 @@ chain_id = 1 rt.wait().await.expect("clean shutdown"); } - /// Blocks pushed in order arrive at the module in the same order — + /// Blocks pushed in order arrive at the module in the same order: /// the per-chain stream, the select, and the dispatch path preserve /// delivery order. Issue #56's ordering guarantee, asserted on the /// module's own log records rather than inferred from termination. @@ -693,7 +693,7 @@ chain_id = 1 /// so a block that was picked up finishes its wasmtime call and its /// log record survives `wait()`. The test first proves the dispatch /// completed (log line present), then shuts down and re-reads the same - /// record after the engine is fully torn down — if teardown dropped or + /// record after the engine is fully torn down: if teardown dropped or /// truncated completed work, the second read fails. Issue #58. #[tokio::test] async fn harness_shutdown_preserves_completed_dispatch() { diff --git a/crates/nexum-sdk-test/src/lib.rs b/crates/nexum-sdk-test/src/lib.rs index 1da359e2..6d8b31b4 100644 --- a/crates/nexum-sdk-test/src/lib.rs +++ b/crates/nexum-sdk-test/src/lib.rs @@ -51,7 +51,7 @@ //! //! The traits report failures as [`nexum_sdk::host::Fault`] rather than //! the `Fault` `wit_bindgen::generate!` emits per-module. A module -//! bridges with a trivial converter on its own crate boundary - see the +//! bridges with a trivial converter on its own crate boundary; see the //! tutorial for the exact shape. //! //! Domain test crates compose these mocks with their own scripted @@ -600,11 +600,11 @@ impl RemoteStoreHost for MockRemoteStore { /// /// # Fidelity vs the real `redb` store /// -/// Two gaps remain (deferred to the `MockRuntime` refactor, #94): -/// - **No transaction semantics** - `redb` wraps each `on_event` in an +/// Two gaps vs `redb`: +/// - **No transaction semantics**: `redb` wraps each `on_event` in an /// implicit write transaction (commit on `Ok`, rollback on trap); this /// mock commits every `set` immediately. -/// - **No concurrent access** - the backing `RefCell` is single-threaded, +/// - **No concurrent access**: the backing `RefCell` is single-threaded, /// whereas `redb` uses MVCC. #[derive(Default)] pub struct MockLocalStore { diff --git a/crates/nexum-sdk/src/lib.rs b/crates/nexum-sdk/src/lib.rs index 9961cc24..c131660b 100644 --- a/crates/nexum-sdk/src/lib.rs +++ b/crates/nexum-sdk/src/lib.rs @@ -5,11 +5,10 @@ //! use them regardless of which world it exports. Domain layers such as //! the CoW SDK depend on this crate and add their own surface on top. //! -//! The crate is the shared companion to the per-module -//! `wit_bindgen::generate!` invocation: modules keep their own -//! wit-bindgen call (which emits the world-specific `Guest` trait, -//! `Fault` shape, and host import shims into the module's own -//! crate) and pull helpers and canonical primitive types from here. +//! Modules keep their own `wit_bindgen::generate!` call, which emits +//! the world-specific `Guest` trait, `Fault` shape, and host import +//! shims into the module's own crate, and pull helpers and canonical +//! primitive types from here. //! //! ## What lives here //! @@ -69,14 +68,10 @@ //! sink so module authors emit `tracing::info!(...)` with no host //! parameter to thread. //! -//! ## Why no `wit_bindgen::generate!` here -//! -//! The macro emits types into the calling crate (the module's -//! cdylib). Re-exporting wit-bindgen output from a library crate -//! would duplicate symbols and break the component-export contract. -//! Helpers in this SDK therefore take primitive types (`&[u8]`, -//! `Option<&str>`, slices) rather than the per-module `Fault` -//! type; modules unpack their `Fault` on the way in. +//! Helpers take primitive types (`&[u8]`, `Option<&str>`, slices) +//! rather than the per-module `Fault` type, so this library emits no +//! wit-bindgen output of its own; modules unpack their `Fault` on the +//! way in. //! //! [`Address`]: alloy_primitives::Address //! [`B256`]: alloy_primitives::B256 diff --git a/crates/nexum-sdk/src/wit_bindgen_macro.rs b/crates/nexum-sdk/src/wit_bindgen_macro.rs index 98059b8b..003af051 100644 --- a/crates/nexum-sdk/src/wit_bindgen_macro.rs +++ b/crates/nexum-sdk/src/wit_bindgen_macro.rs @@ -1,10 +1,7 @@ //! Declarative macro that generates the `WitBindgenHost` adapter -//! every module ships in `lib.rs`. -//! -//! Before this macro existed, each module hand-rolled ~80 lines of -//! mechanical glue: the `struct WitBindgenHost;` plus the core trait -//! impls plus the fault, chain-error, and level conversions. The code -//! differed across modules in zero places that were not bugs. +//! every module ships in `lib.rs`: the `struct WitBindgenHost;` plus +//! the core trait impls and the fault, chain-error, and level +//! conversions. //! //! The adapter is capability-selected: the `caps: [...]` form emits //! only the pieces backed by the module's declared capabilities diff --git a/tools/load-gen/src/main.rs b/tools/load-gen/src/main.rs index 15a05760..60d20588 100644 --- a/tools/load-gen/src/main.rs +++ b/tools/load-gen/src/main.rs @@ -1,11 +1,11 @@ -//! Anvil-side load generator for shepherd's M4 load test. +//! Anvil-side load generator for the runtime load test. //! //! Connects to an Anvil fork of Sepolia, impersonates the pinned test -//! EOA (no signer required - `anvil_impersonateAccount` skips +//! EOA (no signer required: `anvil_impersonateAccount` skips //! signature verification), and submits N `ComposableCoW.create(...)` //! plus M `CoWSwapEthFlow.createOrder(...)` calls per new block. The //! resulting `ConditionalOrderCreated` and `OrderPlacement` events are -//! what shepherd's twap-monitor and ethflow-watcher dispatch on. +//! what the twap-monitor and ethflow-watcher modules dispatch on. //! //! Knobs (`--help` for the full list): //! - `--anvil ` WebSocket URL of the Anvil fork @@ -13,9 +13,8 @@ //! - `--ethflow-per-block M` calls to CoWSwapEthFlow.createOrder per block //! - `--duration ` wall-clock window the loop runs for //! -//! Pinned identities mirror `docs/operations/e2e-prep.md`: -//! EOA, ComposableCoW, TWAP handler, CoWSwapEthFlow, WETH9, COW token, -//! Safe. These are constant across the Sepolia fork. +//! Pinned identities: EOA, ComposableCoW, TWAP handler, CoWSwapEthFlow, +//! WETH9, COW token, Safe. These are constant across the Sepolia fork. #![cfg_attr(not(test), warn(unused_crate_dependencies))]