From a236a3a9f4f7a90288beed6ffc6412bdbc0b042e Mon Sep 17 00:00:00 2001 From: Marco Allegretti Date: Tue, 10 Mar 2026 18:47:10 +0100 Subject: [PATCH] Add WEFT architecture and interface design documents --- docs/architecture/baseline.md | 66 ++++++++ docs/architecture/wasm-servo-channel.md | 177 ++++++++++++++++++++ docs/architecture/weft-shell-protocol.md | 197 +++++++++++++++++++++++ docs/upstream/servo-audit-backlog.md | 30 ++++ infra/vm/linux-dev-environment.md | 43 +++++ 5 files changed, 513 insertions(+) create mode 100644 docs/architecture/baseline.md create mode 100644 docs/architecture/wasm-servo-channel.md create mode 100644 docs/architecture/weft-shell-protocol.md create mode 100644 docs/upstream/servo-audit-backlog.md create mode 100644 infra/vm/linux-dev-environment.md diff --git a/docs/architecture/baseline.md b/docs/architecture/baseline.md new file mode 100644 index 0000000..29937ee --- /dev/null +++ b/docs/architecture/baseline.md @@ -0,0 +1,66 @@ +# WEFT OS Architecture Baseline + +This document records the implementation baseline derived from the authoritative blueprint in `docu_dev/WEFT-OS-COMPREHENSIVE-BLUEPRINT.md`. + +## Authority + +The comprehensive blueprint is the source of truth for technical direction in this repository. + +The earlier concept and integrative blueprint documents are secondary references. They are useful only where they do not conflict with the comprehensive blueprint. + +## Defined foundation + +The current defined foundation is: + +- Linux kernel +- systemd for the initial prototype +- Smithay for the Wayland compositor +- Servo as the system shell renderer running as a Wayland client +- Wasmtime for application execution +- Rust for all core system components + +## System shape + +The intended top-level structure is: + +```text +Linux kernel + -> weft-compositor + -> servo-shell + -> weft-appd +``` + +`weft-compositor` owns Wayland surfaces, surface stacking, input routing, and compositing. + +`servo-shell` renders the system shell UI from HTML and CSS as a Wayland client. + +`weft-appd` is the process supervisor and capability broker for application launch and lifecycle management. + +## Open blockers + +The following items are not treated as solved in this repository: + +- `weft-shell-protocol` specification +- Wasm–Servo channel design +- Servo Wayland input audit through winit +- per-app Servo isolation model +- SpiderMonkey stability verification relevant to UI-side JavaScript + +## Consequences for repository scope + +Until the open blockers are closed at design level, this repository should avoid: + +- broad multi-crate scaffolding for unresolved runtime boundaries +- developer SDK or packaging tooling built against unstable contracts +- application examples that imply the Wasm–Servo contract is already decided + +## Historical mismatches that are not implementation authority + +The earlier concept document is not used as implementation truth where it conflicts with the comprehensive blueprint. + +Examples of mismatches already identified: + +- unsigned package examples versus the authoritative signed bundle requirement +- simplified permission names versus the authoritative capability taxonomy +- a historical top-level `shaders/` directory versus the authoritative package layout +- broader early-language discussion that does not define current core-system policy diff --git a/docs/architecture/wasm-servo-channel.md b/docs/architecture/wasm-servo-channel.md new file mode 100644 index 0000000..33b7e34 --- /dev/null +++ b/docs/architecture/wasm-servo-channel.md @@ -0,0 +1,177 @@ +# 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. diff --git a/docs/architecture/weft-shell-protocol.md b/docs/architecture/weft-shell-protocol.md new file mode 100644 index 0000000..d06d605 --- /dev/null +++ b/docs/architecture/weft-shell-protocol.md @@ -0,0 +1,197 @@ +# WEFT Shell Protocol Design + +This document defines the WEFT-specific protocol boundary between `weft-compositor` and `servo-shell`. + +## Status + +Defined for WEFT repository planning and future implementation. + +Not implemented. + +Not proposed as a standard Wayland extension. + +## Participants + +- `weft-compositor` +- `servo-shell` + +`weft-compositor` is authoritative for: + +- Wayland connection ownership +- surface lifecycle +- input focus at the surface level +- surface stacking between independent client surfaces +- output geometry and presentation timing + +`servo-shell` is authoritative for: + +- shell DOM structure +- shell chrome layout +- window metadata presentation inside the shell UI +- shell requests to create, move, resize, and destroy shell-managed windows + +## Problem boundary + +The shell needs to represent desktop windows as DOM elements while the compositor owns the actual client surfaces. + +The protocol exists to let the shell request and manage compositor-backed window surfaces without pretending that app content lives inside Servo's DOM tree. + +## Object model + +The protocol defines a shell session and a set of shell-managed window objects. + +### Shell session + +A shell session is created when `servo-shell` binds the WEFT global. + +The session has exactly one active owner. + +If the shell disconnects, the compositor invalidates the session and destroys all shell-owned protocol objects. + +### Shell window object + +A shell window object represents a compositor-managed surface slot associated with one visual shell window. + +Each shell window object has: + +- `window_id` +- `app_id` +- `title` +- `role` +- `geometry` +- `state` +- `z_hint` + +`window_id` is generated by the compositor and is stable only for the lifetime of the session. + +## Core requests + +### `create_window` + +Sent by `servo-shell` to request creation of a shell-managed window slot. + +Inputs: + +- `app_id` +- `title` +- `role` +- initial `geometry` +- initial `state` + +Result: + +- success with assigned `window_id` +- failure with a reason code + +The compositor creates the server-side object and returns a `window_id`. + +### `update_window_metadata` + +Sent by `servo-shell` when title, role, or state hints change. + +Metadata updates are advisory except where explicitly marked authoritative in this document. + +### `set_window_geometry` + +Sent by `servo-shell` to request a geometry change. + +The compositor validates the request against output bounds, policy, and current window state. + +The compositor is not required to honor the requested geometry exactly. + +### `destroy_window` + +Sent by `servo-shell` when the shell no longer wants the window slot. + +The compositor destroys the protocol object and any shell-owned chrome surfaces associated with it. + +## Core compositor events + +### `window_configured` + +Sent by the compositor when the effective geometry or state changes. + +`servo-shell` must treat this as authoritative and update its DOM layout to match. + +### `focus_changed` + +Sent by the compositor when surface-level focus changes. + +The shell updates visual focus state but does not override compositor focus directly. + +### `window_closed` + +Sent by the compositor when a window object is no longer valid. + +After this event, the `window_id` is dead and cannot be reused by the shell. + +### `presentation_feedback` + +Sent by the compositor to report frame presentation timing relevant to shell-managed surfaces. + +This event exists to align shell animations and resize flows with compositor timing. + +## Surface ownership rules + +The compositor owns the actual application content surfaces. + +The shell may own separate chrome surfaces where needed. + +The shell does not embed application pixels into the Servo DOM. + +The compositor remains the authority for final stacking and composition. + +## Failure model + +### Shell crash + +If `servo-shell` disconnects: + +- the compositor invalidates the shell session +- shell-owned protocol objects are destroyed +- application surfaces remain alive if supervised elsewhere +- a restarted shell receives a new session and must rebuild its model + +### Compositor crash + +If `weft-compositor` crashes: + +- Wayland connections are lost +- the shell must reconnect after compositor restart +- all protocol object identifiers from the prior session are invalid +- the shell rebuilds state from the authoritative process manager once the compositor is ready + +### Stale identifiers + +A `window_id` is session-scoped. + +A stale `window_id` must be rejected by the compositor. + +## Security model + +The shell can request metadata and geometry changes, but the compositor enforces: + +- output bounds +- focus routing +- stacking policy +- lifecycle validity + +The shell is not trusted to define final compositor state. + +## Test requirements + +Implementation work against this protocol must include: + +- unit tests for object lifecycle and stale identifier rejection +- integration tests for shell reconnect behavior +- integration tests for compositor restart handling +- validation of focus and configure event ordering + +## Deferred topics + +This document does not define: + +- client application protocol toward `weft-appd` +- package or launcher metadata schemas +- accessibility mappings +- persistence of shell layout state across sessions diff --git a/docs/upstream/servo-audit-backlog.md b/docs/upstream/servo-audit-backlog.md new file mode 100644 index 0000000..cf45268 --- /dev/null +++ b/docs/upstream/servo-audit-backlog.md @@ -0,0 +1,30 @@ +# Servo Audit Backlog + +This backlog maps WEFT requirements to the upstream audit and contribution work needed before WEFT can rely on Servo for system-shell and app-UI duties. + +## Rules + +- No item is marked resolved without upstream evidence. +- A local workaround does not close an upstream dependency gap. +- Every audit item must end in one of: verified, upstream issue, local design adjustment, or blocked. + +## Backlog + +| Area | WEFT requirement | Current status | Next action | Exit condition | +| --- | --- | --- | --- | --- | +| Wayland input | Shell-grade keyboard, pointer, touch, and IME behavior | Not verified in this repository | Audit Servo and winit behavior on Linux Wayland | Verified behavior or upstream issues filed for confirmed gaps | +| Wayland surface pipeline | Correct damage tracking, presentation timing, and buffer path behavior | Not verified in this repository | Audit Servo -> WebRender -> wgpu -> Wayland path | Explicit verification or upstream issue set | +| WebGPU completeness | Stable GPU app rendering path on Linux Mesa | Not verified in this repository | Compare Servo WebGPU coverage to WEFT needs | Verified required subset or upstream issue set | +| Multiprocess isolation | App UI crash isolation from shell UI | Known to be incomplete as a WEFT assumption | Audit Servo multiprocess and content-process behavior | Written gap assessment with next action | +| JavaScript runtime stability | Sufficient stability for system-shell and app UI JavaScript | Not verified in this repository | Audit current Servo main behavior and issue tracker | Verified risk record or upstream issue set | +| Accessibility | Linux AT-SPI readiness for shell and app UI | Not verified in this repository | Audit current AccessKit and Servo Linux path | Verified support state or upstream issue set | + +## Local follow-up outputs expected from each audit + +Each audit should produce: + +- a reproducible environment description +- exact upstream revision or release under test +- observed result +- links to upstream issues if gaps are confirmed +- the WEFT planning consequence diff --git a/infra/vm/linux-dev-environment.md b/infra/vm/linux-dev-environment.md new file mode 100644 index 0000000..22784b5 --- /dev/null +++ b/infra/vm/linux-dev-environment.md @@ -0,0 +1,43 @@ +# Linux Development Environment + +WEFT OS is developed on a Windows workstation, but the authoritative runtime target for system work is a Linux VM or QEMU guest. + +## Baseline target + +Use a recent Linux distribution with: + +- systemd as PID 1 +- Wayland-capable graphics stack +- Mesa userspace drivers +- a recent Rust toolchain compatible with `rust-toolchain.toml` + +## Purpose of the guest environment + +The guest is the validation target for: + +- systemd service assumptions +- Wayland compositor bring-up +- Servo Wayland client behavior +- Wasmtime runtime supervision assumptions + +## Host versus target boundary + +The Windows host is acceptable for editing, documentation, and workspace validation. + +The Linux guest is authoritative for: + +- graphics stack behavior +- compositor and shell startup order +- systemd unit behavior +- process supervision assumptions tied to Linux userspace + +## Minimum guest setup goals for the next implementation wave + +- install Rust toolchain matching `rust-toolchain.toml` +- install build essentials needed by Rust crates in this repository +- confirm `cargo fmt`, `cargo clippy`, and `cargo test` run successfully +- prepare a repeatable guest definition for future compositor and shell work + +## Current status + +This repository does not yet automate guest provisioning. That work should begin only after the foundational workspace and design documents are stable.