Roam v7 migration: full gap analysis, blockers, and staged transition plan

[fasterthanlime]

Context snapshot (2026-03-03)

Dodeca currently tracks roam via git branch = "main", but its lockfile resolves to Roam 3.0.0 at commit 8dad8a5b5a8b3aac6e0f0043854a29020176d6af (2026-02-09).

Evidence:

• Cargo.toml still depends on old crate set (roam, roam-session, roam-tracing, etc.)
• Cargo.lock resolves:
  • roam 3.0.0
  • roam-session 3.0.0
  • roam-shm 3.0.0
  • all from the same git commit 8dad8a5...

Target runtime in current Roam repo is now 7.0.0-alpha.1 (workspace version), with the v7 migration guide and changelog documenting hard breaks.

Why this issue exists

We need a durable migration note for moving dodeca from old Roam APIs to v7.

This is not a mechanical dependency bump. The breakage is architectural around session/runtime setup, caller construction, SHM orchestration, and devtools/browser virtual connection wiring.

High-level compatibility verdict

There is no clean one-step upgrade path.

There is a clean staged migration path if we refactor around v7 primitives in order:

1. service trait signature updates
2. caller/session bootstrap updates
3. SHM host/guest orchestration rewrite
4. devtools + tunnel model rewrite

What dodeca uses today (old Roam surface)

1) Service impls require &Context

Large surface area still uses old service impl signatures with &roam::Context / &dodeca_cell_runtime::Context.

A quick scan found ~75 method impls across ~28 files.

Representative examples:

• crates/dodeca/src/cells.rs
• crates/dodeca/src/cell_server.rs
• crates/dodeca/src/content_service.rs
• crates/dodeca/src/template_host.rs
• many cells/*/src/main.rs

2) Clients built from ConnectionHandle

Current code relies on generated clients accepting ConnectionHandle directly.

Examples:

• HostServiceClient::new(handle.clone())
• BrowserServiceClient::new(handle)
• many cell runtime callsites using cloned ConnectionHandle

3) Old handshake helpers and transport-level setup

Current code uses:

• accept_framed
• HandshakeConfig
• WsTransport
• MessageTransport adapter traits

Examples:

• crates/dodeca-devtools/src/state.rs
• cells/cell-http/src/devtools.rs

4) Old SHM host/driver orchestration

Current host runtime assumes monolithic SHM orchestration APIs:

• ShmHost::create(...)
• MultiPeerHostDriver::builder(...)
• driver_handle.create_peer(...)
• driver_handle.add_peer_with_diagnostics(...)
• IncomingConnections
• spawn args and guest establish helpers (SpawnArgs, establish_guest_with_diagnostics)

Core codepaths:

• crates/dodeca/src/cells.rs
• crates/dodeca/src/host.rs
• crates/dodeca/src/cell_server.rs
• crates/dodeca-cell-runtime/src/lib.rs

5) Old dispatcher composition utilities

Current runtime depends on old session-layer dispatcher helpers:

• RoutedDispatcher
• ServiceDispatcher
• ForwardingDispatcher
• LateBoundForwarder
• LateBoundHandle

Used heavily in:

• crates/dodeca/src/host.rs
• cells/cell-http/src/devtools.rs
• crates/dodeca-cell-runtime/src/lib.rs

6) Tunnel-specific helpers that are absent in v7 facade

HTTP cell plumbing depends on:

• roam::Tunnel
• roam::tunnel_pair()
• roam::tunnel_stream(...)
• roam::DEFAULT_TUNNEL_CHUNK_SIZE

Used in:

• cells/cell-http-proto/src/lib.rs
• cells/cell-http/src/tunnel.rs
• crates/dodeca/src/cell_server.rs

What changed in Roam v7 that directly breaks dodeca

A) Service impl signature break

From migration guide/changelog:

• service impls no longer receive &Context
• owned-return methods return values directly
• borrowed-return methods use call: impl roam::Call<T, E>

Direct impact: every current impl with _cx: &Context fails.

B) Client construction break

From v7 docs:

• ConnectionHandle is no longer a Caller
• generated clients must be built from driver.caller()

Direct impact: existing Client::new(handle) callsites fail.

C) Session bootstrap break

From v7 docs:

• old accept_framed / initiate_framed replaced by
  session::acceptor(...) / session::initiator(...) + .establish()
• then create Driver::new(handle, handler, parity)

Direct impact: all old handshake helpers and wiring patterns fail.

D) SHM orchestration surface changed

The v7 guide explicitly says old host orchestration symbols are not part of current API shape.

Current v7 roam-shm exposes lower-level pieces:

• Segment
• HostHub
• PreparedPeer / GuestSpawnTicket
• guest_link_from_*
• ShmLink

Even though there are thin compatibility aliases (MultiPeerHostDriver = ShmHost etc.), they are not equivalent to the old builder/driver orchestration API dodeca currently depends on.

E) Virtual connection model changed/explicit

v7 uses session-level virtual connections:

• SessionHandle::open_connection(...)
• optional .on_connection(...) acceptor hooks

Dodeca’s browser/devtools virtual-connection flow currently relies on old forwarding abstractions and old connection handle APIs; this needs explicit redesign against v7 session semantics.

F) Crate topology changed

Roam workspace moved from roam-session/roam-wire era to roam-core + roam-types model.

Dodeca depends on old crate names/types throughout the codebase.

Concrete hotspots to migrate first

Runtime bootstrap and shared helpers

• crates/dodeca-cell-runtime/src/lib.rs
• crates/dodeca/src/cells.rs
• crates/dodeca/src/host.rs

Devtools/browser bridge

• crates/dodeca-devtools/src/state.rs
• cells/cell-http/src/devtools.rs
• crates/dodeca/src/cell_server.rs
• crates/dodeca-protocol/src/lib.rs

HTTP tunnel path

• cells/cell-http-proto/src/lib.rs
• cells/cell-http/src/tunnel.rs
• crates/dodeca/src/cell_server.rs

Service implementations (signature churn)

• all #[roam::service] impls in crates/ and cells/

Proposed staged migration plan

Phase 0: lock migration branch + inventory

• Create dedicated branch for v7 migration.
• Freeze and commit current roam API inventory (search output + affected files list).
• Keep this issue as source of truth for migration order.

Phase 1: dependency and crate-surface pivot (compile-break intentionally)

• Update dependencies from old roam crate set to current v7 set.
• Remove/replace direct imports of removed crates/types (roam-session, roam-wire, old tracing crate surface, etc.).
• Expect build to break broadly; that is acceptable at this phase.

Phase 2: service trait signature migration

• Rewrite all service impls from old context form to v7 form.
• For methods currently using cx.conn_id() semantics, carry connection identity through explicit state/session handling rather than method context.
• Verify no generated/manual trait mismatch remains.

Phase 3: caller model migration

• Introduce explicit driver ownership where clients are built.
• Replace all Client::new(ConnectionHandle) style code with Client::new(driver.caller()).
• Ensure driver lifetime is correctly tied to callsites that need outbound RPC.

Phase 4: session bootstrap migration

• Replace all old handshake helper flows with:
  • session::initiator(conduit).establish() or
  • session::acceptor(conduit).establish()
• Instantiate Driver explicitly with parity.
• Ensure session run loop + driver run loop orchestration is correct in host, cells, wasm/devtools.

Phase 5: SHM host/guest rewrite (largest block)

• Rebuild cell orchestration around v7 SHM primitives:
  • segment lifecycle
  • peer preparation (HostHub)
  • guest ticket passing
  • link creation (ShmLink)
  • per-peer session+driver setup
• Replace old dynamic peer driver handle model (create_peer, add_peer_with_diagnostics) with v7 equivalent architecture.
• Re-implement lazy cell spawning integration on top of new primitives.

Phase 6: browser/devtools virtual-connection rewrite

• Replace old forwarding abstractions with explicit v7 virtual-connection patterns:
  • SessionHandle::open_connection(...)
  • .on_connection(...) acceptance where needed
• Reconcile browser registration path that currently relies on connection ID from old context.
• Keep route subscription and event push semantics unchanged at API boundary.

Phase 7: tunnel path redesign

• Replace roam::Tunnel helpers with v7-compatible channel or link abstraction.
• Preserve L4 tunnel behavior (browser TCP <-> cell HTTP) and backpressure.
• Update proto/service shape if needed.

Phase 8: tracing/diagnostics parity

• Replace old roam-tracing integration points with v7 telemetry/tracing approach (or temporary local tracing fallback).
• Restore required diagnostics used by SIGUSR1/debug workflows.

Phase 9: integration and compliance test pass

• Run full dodeca test/integration suite, including serve mode + devtools + multi-cell behavior.
• Validate no silent regressions in:
  • lazy spawning
    n - cell crash handling
  • websocket/devtools reconnect
  • tunnel throughput behavior
  • shutdown semantics

Risk areas / likely surprises

• Connection identity propagation: old Context gave convenient per-call access.
• Devtools browser callback plumbing: old forwarding helpers hid complexity.
• SHM dynamic peer lifecycle + crash recovery semantics.
• Tunnel API replacement details (high chance of behavioral regressions if rushed).
• Tracing parity (old custom integration may not map 1:1).

Suggested acceptance criteria

• Dodeca builds and runs on Roam v7 dependency set only.
• No remaining imports/usages of removed v3-era APIs.
• All service impls compile with v7 generated traits.
• Browser devtools can:
  • connect
  • subscribe
  • receive pushed events
  • run scope/eval RPC
• HTTP tunnel path works under concurrent browser load.
• Lazy cell spawning and automatic respawn/failure handling behave as before.
• End-to-end tests green.

Notes for future me

• Do not attempt a single giant PR that mixes mechanical signature churn with SHM redesign and devtools rewrite in one diff.
• Land migration in stacked phases with temporary compatibility shims inside dodeca where needed.
• Prefer preserving behavior first, then cleanup/refactor once v7 baseline is stable.
• Keep this issue updated with checklists and linked PRs per phase.