WEFT_OS/docs/architecture/wasm-servo-channel.md

# Wasm–Servo Channel Design

This document defines the initial WEFT direction for communication between an application's Wasm core and its HTML UI.

## Status

Defined as the WEFT repository direction for implementation planning.

Not implemented.

Requires further upstream-facing discussion where Servo integration points are affected.

## Problem statement

A WEFT application has two isolated parts:

- `core.wasm` running under Wasmtime
- `ui/index.html` rendered by Servo

They must exchange application events and state updates without collapsing process isolation or introducing ambient authority.

## Decision

The initial WEFT direction is a brokered message channel with these properties:

- `weft-appd` owns the session
- the Wasm core and HTML UI are peers, not parent and child
- all payloads are structured messages
- all messages cross an explicit broker boundary
- neither side receives direct ambient access to system resources through the channel

## Transport shape

The selected transport model is:

- one app session broker owned by `weft-appd`
- one message stream from Wasm core to broker
- one message stream from UI to broker
- broker validation before delivery in either direction

The transport must support:

- ordered delivery within a session
- bounded message size
- explicit backpressure
- session teardown on process death

This document does not lock the implementation to a specific byte framing library.

It does lock the architecture to brokered message passing rather than shared memory or in-process embedding.

## Why this direction was selected

This direction was selected because it preserves the design constraints already established in the authoritative blueprint:

- process isolation remains intact
- capability mediation stays outside the UI runtime
- the shell and app model do not depend on embedding Wasmtime into Servo
- the design does not depend on Worker support being complete in Servo
- the design avoids shared-memory synchronization complexity in the first implementation track

## Explicitly rejected directions for the initial WEFT track

### Shared memory ring buffer

Rejected for the initial track because it increases synchronization complexity, failure complexity, and debugging cost before the protocol contract is stable.

### In-process Wasmtime hosted directly inside Servo

Rejected for the initial track because it collapses the process boundary too early and would require a much larger Servo-side architectural commitment before WEFT has closed the surrounding interface contracts.

### Worker-based UI execution model as the primary plan

Rejected for the initial track because Worker support should not be treated as a closed dependency assumption for WEFT planning.

## Session model

Each launched app receives an app session identified by a session identifier created by `weft-appd`.

The session owns:

- the approved capability set
- the Wasm process handle
- the UI browsing-context handle
- the two channel endpoints
- the teardown state

A session ends when either side dies, the app is closed, or the broker invalidates the session.

## Message model

All messages are structured and versioned.

Every message includes:

- `session_id`
- `stream_id`
- `message_type`
- `sequence`
- `payload`

Message classes:

- UI event messages
- state update messages
- lifecycle messages
- error messages

The broker validates message class and payload shape before forwarding.

## Capability boundary

The channel is not a capability transport.

Capabilities are granted only through app launch and host-managed handles.

The UI cannot escalate privileges by sending broker messages.

The Wasm core cannot mint new authority by sending channel payloads.

## Failure model

### Wasm process crash

If the Wasm process dies:

- the broker closes the Wasm endpoint
- the UI receives a terminal session error event
- the app session is torn down unless explicit recovery is later designed

### UI crash

If the UI browsing context dies:

- the broker closes the UI endpoint
- the Wasm endpoint is terminated by `weft-appd`
- the app session ends

### Broker restart or broker failure

If the broker fails, the session is invalid.

Both sides must be treated as disconnected.

Session recovery is not implicit.

## Performance budget

The initial design target is correctness and isolation first.

Performance requirements for future implementation work:

- message transport must not permit unbounded queue growth
- large binary payloads are out of scope for the control channel
- high-frequency UI state churn must be coalesced before transport where possible

This document does not claim a measured latency target because no implementation exists yet.

## Observability requirements

Any implementation of this design must expose:

- session creation and teardown events
- message validation failures
- endpoint disconnect reasons
- queue pressure indicators

## Open implementation questions

These questions remain open for the implementation phase and any Servo-facing discussion:

- the exact UI-side binding surface presented to application JavaScript
- the exact framing and serialization format
- whether the UI endpoint is surfaced through a custom embedder API or another browser-facing transport mechanism
- whether a limited reconnect path is worth supporting

The open questions do not change the architectural decision that the channel is brokered and process-separated.