refactor(core,app)!: align with @cartesi/rollup, drop the HTTP-era surface

[tuler]

Why

This started as an evaluation of whether @deroll/core and @deroll/app still earn their place now that @cartesi/rollup exists — it already ships a Rollup.run({ advance, inspect }) loop, and the two deroll packages are only ~230 lines combined.

The conclusion was keep both, but stop them restating the protocol:

• @deroll/app earns its place on multi-handler composition. Rollup.run() takes exactly one advance handler and one inspect handler; addAdvanceHandler/addInspectHandler are what let wallet.handler and router.handler be independently authored libraries sharing one loop. It also inverts the accept default (reject unless a handler opts in, which is the safer default for a rollup) and converts host-mode ENODATA into a clean exit.
• @deroll/core earns its place as the composition seam — wallet and router depend on the App interface, not on the concrete app.
• What did not earn its place was the vocabulary. Nine of ~22 exported types had zero consumers outside core/src — request_type: "advance_state", nested data, NoticeResponse = { index }, ReportResponse = Record<string, never> (still carrying its // XXX: should probably be 204 comment) — all leftovers of the removed Rollup HTTP Server transport. The surviving types were near-duplicates of the binding's, but narrower and drifting.

What changed

Protocol types come from @cartesi/rollup. @deroll/core re-exports AdvanceRequest, InspectRequest, RollupRequest, Voucher, DelegateCallVoucher, BytesLike, AddressLike, U256Like and Hex instead of declaring its own copies, so the two cannot drift. viem is no longer a dependency of core at all. core/src/types.ts is now mostly doc comments.

Dead types deleted: RollupAdvanceRequest, RollupInspectRequest, RequestType, RequestData, RequestMetadata, NoticeResponse, ReportResponse, VoucherResponse.

The advance request is flat. AdvanceRequestData/AdvanceRequestMetadata → AdvanceRequest, which also removes the destructuring conversion in the request loop.

-app.addAdvanceHandler(async ({ metadata, payload }) => {
-    console.log(metadata.msgSender);
+app.addAdvanceHandler(({ msgSender, payload }) => {
+    console.log(msgSender);
     return "accept";
 });

Outputs are synchronous, and notice/report payloads are no longer wrapped. Emitting an output is a device write, not I/O the event loop can interleave with — finish pauses the entire guest. Vouchers keep their object argument, since they carry a destination and optional value besides the payload.

-const id = await app.createNotice({ payload: stringToHex("hello") });
-await app.createReport({ payload: stringToHex("hello") });
+const id = app.createNotice(stringToHex("hello"));
+app.createReport(stringToHex("hello"));

Handlers may still be async — they are awaited — but no longer have to be. The wallet and router handlers are now synchronous.

A handler exception rejects the request and is reported. Previously it went to stderr and the next handler ran anyway, which could let a later handler write state on top of a partially applied one, and left the failure invisible from outside the machine. Now the input is rejected immediately, remaining handlers are skipped, and the error is emitted as a report — which survives the rejection.

registerException is now on the App interface. NativeApp always implemented it, but it was missing from the interface createApp returns, so it was unreachable through the public API.

Bonus fix: Router.handler was doing bytesToString(toBytes(buffer)), which only round-tripped correctly because TextEncoder coerces a Buffer via toString(). It now reads the Buffer directly.

Two judgment calls worth reviewing

@cartesi/rollup is a non-optional peerDependency of @deroll/core. This weakens the "no native addon in the pure packages" property — wallet and router now get the tarball in their tree. I chose it anyway because the binding is a singleton native resource (new Rollup() returns -EBUSY if one is already open), so two copies at different versions in one tree is a real failure mode; a non-optional peer forces exactly one hoisted copy. What survives is "the addon is never loaded by the pure packages," which is what matters for their tests. An optional peer would have preserved the stronger claim but broken type resolution when absent.

The Notice/Report/Exception wrapper types are gone. This is a larger API break than just dropping async. Easy to revert to createNotice({ payload }) if preferred.

Verification

• bun run build — 9/9 packages, including @deroll/docs, whose Vocs/twoslash snippets are genuinely typechecked. All 33 affected .mdx pages updated, plus the migration guide.
• bun run lint clean; tsc --noEmit on apps/examples clean.
• 35 tests pass (30 wallet, 5 router).
• End-to-end against the real native binding + libcmt mock: minimal prints the flat request and exits 0; echo emits a correct Notice(bytes) output (c258d6e5 selector, advance-0\n payload); a throwing handler produced a report file with the stack, no output files, and the second handler never ran — the new error policy confirmed at runtime, not just in types.

bun run test at the repo root still fails on @deroll/genext2fs, whose addon needs a C toolchain the dev container lacks. Pre-existing and unrelated to this change; it aborts the turbo run, which is why wallet/router were run directly.

A changeset (minor for core/app/router/wallet) documents each break with diffs, and CLAUDE.md is updated.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
deroll	Ready	Preview	Aug 13, 2026 5:40am
deroll-explorer	Ready	Preview	Aug 13, 2026 5:40am

[changeset-bot]

🦋 Changeset detected

Latest commit: 3a9efd3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@deroll/core	Minor
@deroll/app	Minor
@deroll/router	Minor
@deroll/wallet	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[tuler]

Closing in favor of #205.

This PR kept @deroll/app on the argument that multi-handler composition is real value the binding doesn't provide. That was true when it was opened, and is no longer: @cartesi/rollup@1.0.0-alpha.1 now ships chain and broadcast, the handler types, and a run that resolves when the host mock's inputs are exhausted.

That covered everything @deroll/app and @deroll/core contained, so #205 removes both packages rather than leave them re-exporting someone else's functions. It also pins @cartesi/rollup@1.0.0-alpha.1, which this branch does not.

The work here is not lost — #205 contains these commits and builds on them. Left as a record of the alternative.

---

Generated by Claude Code