Skip to content

docs(wit): freeze WIT clarifications, fix macro nits#257

Open
mfw78 wants to merge 4 commits into
feat/m1-echo-venuefrom
fix/m1-intent-sweep
Open

docs(wit): freeze WIT clarifications, fix macro nits#257
mfw78 wants to merge 4 commits into
feat/m1-echo-venuefrom
fix/m1-intent-sweep

Conversation

@mfw78

@mfw78 mfw78 commented Jul 7, 2026

Copy link
Copy Markdown
Contributor

Summary

Stacked fixes from the M1 QA sweep against feat/m1-echo-venue: a WIT freeze
clarification for nexum-value-flow amount encoding and the native-token
variant, a macro correctness fix for venue manifests, and a doc-comment
spelling normalisation, plus documentation of a deliberate charging asymmetry
in the pool router. No wire format, identifier, or behavioural change to the
base set introduced by this stack.

Changes

  • docs(wit): mandate minimal-length canonical big-endian encoding for
    asset-amount's amount field and require decoders to compare amounts by
    value, not by byte equality [finding wit: author the nexum:value-flow types package (0.1) with an identifier-hygiene gate #226/amount, minor]
  • docs(wit): document native-token(offchain) as representable-but-
    intentionally-invalid; consumers MUST reject that pairing since an
    off-chain settlement domain has no gas token [finding wit: author the nexum:value-flow types package (0.1) with an identifier-hygiene gate #226/native-token,
    minor]
  • fix(macros): made the shared missing-[capabilities] error macro-neutral
    so a venue crate is no longer told to use #[nexum_sdk::module]
    [finding sdk: add the #[nexum::venue] proc-macro (adapter cdylib glue + per-component world) #232, nit]
  • fix(macros): mirrored synthesize's package-accumulation loop in
    synthesize_venue so a future non-packageless venue capability reaches the
    resolve path (the base package set is unchanged today, since all
    venue-permitted capabilities are currently packageless) [venue-authoring,
    nit]
  • docs: normalised authorise/authorisation doc comments to British -ise
    spelling across nexum-intent/types.wit, header.rs, reference.rs, and
    world.rs (recognises); doc comments only, no identifier or API name
    changes [integration-hygiene, nit]
  • docs(runtime): documented the deliberate pool submit charge asymmetry in
    submit()'s doc comment: a forwarded submission is charged once the guard
    admits it regardless of venue outcome, while a derive-stage non-decode
    venue error is left uncharged so the caller may retry

Test plan

All five ran inside nix develop --command with --locked and
--config 'build.target-dir="/code/nxm/runtime/target"'
(RUSTFLAGS/RUSTDOCFLAGS=-D warnings, mirroring just ci):

  • cargo fmt --all -- --check = PASS
  • cargo clippy --workspace --all-targets --all-features -- -D warnings = PASS (exit 0)
  • cargo doc --workspace --no-deps (RUSTDOCFLAGS=-D warnings) = PASS (exit 0)
  • cargo build --release --target wasm32-wasip2 (example, twap-monitor, ethflow-watcher, price-alert, balance-tracker, stop-loss, flaky-bomb, fuel-bomb, memory-bomb) = PASS (exit 0)
  • cargo test --workspace --all-features --no-fail-fast = PASS (exit 0), 42 suites test result: ok, zero failed/ignored-as-failure

Delta sweep (4cff6f2...HEAD): no em-dashes and no #NNN issue references in
.rs/.wit files; commit range 4cff6f2..HEAD carries no attribution
strings; the four new fix commits likewise carry none.

Notes for reviewer

Part of #137.

Stacked on feat/m1-echo-venue; merges bottom-up after the fault train,
retarget to develop then.

@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from 13741b7 to 8d095ee Compare July 7, 2026 23:12
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from b94e368 to 5e26fdd Compare July 7, 2026 23:12
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from 8d095ee to 68190c9 Compare July 8, 2026 00:43
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from 5e26fdd to edd352a Compare July 8, 2026 00:43
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from 68190c9 to e66606e Compare July 8, 2026 01:19
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from edd352a to 3820c21 Compare July 8, 2026 01:19
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from e66606e to 94d8ec0 Compare July 8, 2026 01:44
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from 3820c21 to f11ba28 Compare July 8, 2026 01:44
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from 94d8ec0 to de36021 Compare July 8, 2026 02:11
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from f11ba28 to 28887ff Compare July 8, 2026 02:11
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from de36021 to 19575f2 Compare July 8, 2026 02:20
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from 28887ff to 1f65126 Compare July 8, 2026 02:20
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from 19575f2 to ec68bb0 Compare July 8, 2026 02:23
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from 1f65126 to 3f8c32b Compare July 8, 2026 02:23
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from ec68bb0 to 8ae0b2d Compare July 8, 2026 03:03
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from 3f8c32b to 64c47a3 Compare July 8, 2026 03:03
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from 8ae0b2d to 66d59f7 Compare July 8, 2026 05:00
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from 64c47a3 to 9743625 Compare July 8, 2026 05:00
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from 66d59f7 to 00ba716 Compare July 8, 2026 05:31
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from 9743625 to c469a9b Compare July 8, 2026 05:31
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from 00ba716 to f90c713 Compare July 8, 2026 06:21
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from c469a9b to 43e266c Compare July 8, 2026 06:21
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from f90c713 to e42929e Compare July 8, 2026 06:40
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from 43e266c to 39a3de9 Compare July 8, 2026 06:40
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from e42929e to 575d3db Compare July 8, 2026 07:07
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from 39a3de9 to 8696e02 Compare July 8, 2026 07:07
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from 575d3db to ab3ddbf Compare July 8, 2026 07:21
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from 8696e02 to 4e63518 Compare July 8, 2026 07:21
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from ab3ddbf to 64eb18b Compare July 8, 2026 07:36
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from 4e63518 to 84cc8eb Compare July 8, 2026 07:36
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from 04392c5 to 4409b1d Compare July 8, 2026 09:02
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from 2e26b5c to cabc179 Compare July 8, 2026 09:02
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from 4409b1d to 3999e56 Compare July 8, 2026 09:19
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from cabc179 to ac900b2 Compare July 8, 2026 09:19
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from 3999e56 to 7b4684b Compare July 8, 2026 12:10
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from ac900b2 to 4c0f712 Compare July 8, 2026 12:10
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from 7b4684b to 914e504 Compare July 8, 2026 12:20
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from 4c0f712 to fe80890 Compare July 8, 2026 12:20
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from 914e504 to 9f47623 Compare July 8, 2026 12:50
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from fe80890 to baa7cea Compare July 8, 2026 12:50
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from 9f47623 to 252c34b Compare July 8, 2026 13:44
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from baa7cea to 8ad52b6 Compare July 8, 2026 13:44
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from 252c34b to 4af0dba Compare July 8, 2026 14:00
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from 8ad52b6 to f3ab7fa Compare July 8, 2026 14:00
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from 4af0dba to f752e14 Compare July 8, 2026 14:09
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from f3ab7fa to f3aa963 Compare July 8, 2026 14:09

@jean-neiverth jean-neiverth left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nitpick: crates/nexum-runtime/src/host/pool_router.rs - the new charge-asymmetry doc explains that forwarded submissions are charged once the guard admits them, and decode failures are charged to prevent garbage-feeding. It is silent on whether guard denials consume quota (they do not - the charge happens after the guard). Worth stating explicitly so a reader does not have to trace the control flow to confirm.

@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from f752e14 to 9587c6f Compare July 8, 2026 22:33
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch 2 times, most recently from 7fec137 to 801b244 Compare July 8, 2026 23:05
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from 9587c6f to 453dd31 Compare July 8, 2026 23:05
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from 801b244 to d458e05 Compare July 8, 2026 23:24
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from 31d67a0 to b58db82 Compare July 8, 2026 23:29
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from d458e05 to 34ae51c Compare July 8, 2026 23:29
mfw78 added 4 commits July 9, 2026 02:09
…chain)

Mandate minimal-length big-endian for asset-amount and require decoders
to compare by value, so the same amount has one canonical wire form
across the binding targets. Document native-token(offchain) as
representable-but-invalid: an off-chain settlement domain has no gas
token, so consumers must reject the pairing rather than interpret it.
…venue packages

The shared missing-[capabilities] error named #[nexum_sdk::module] even
on the venue path; make it macro-neutral so a venue crate is not told to
use the wrong attribute. Mirror synthesize's package-accumulation loop in
synthesize_venue so a future venue capability carrying an extra WIT
package reaches the resolve path (all venue capabilities are packageless
today, so the base set is unchanged).
Align the authorise/authorisation prose in the intent WIT and the
conformance kit with the British spelling used elsewhere and with the
authorisation identifier itself. Doc comments only; no identifier, wire
format, or API name changes.
State the deliberate rule that a forwarded submission is charged once the
guard admits it regardless of the venue outcome, while a derive-stage
non-decode venue error is left uncharged so the caller may retry.
@mfw78 mfw78 force-pushed the feat/m1-echo-venue branch from b58db82 to 6f13c4d Compare July 9, 2026 02:09
@mfw78 mfw78 force-pushed the fix/m1-intent-sweep branch from 34ae51c to 6be460b Compare July 9, 2026 02:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

pr-train Part of the current stacked PR train; lands in sequence, do not merge out of order.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants