mirror of
https://github.com/marcoallegretti/WEFT_OS.git
synced 2026-03-27 01:13:09 +00:00
Add WEFT architecture and interface design documents
This commit is contained in:
parent
8b65f81396
commit
a236a3a9f4
5 changed files with 513 additions and 0 deletions
66
docs/architecture/baseline.md
Normal file
66
docs/architecture/baseline.md
Normal file
|
|
@ -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
|
||||||
177
docs/architecture/wasm-servo-channel.md
Normal file
177
docs/architecture/wasm-servo-channel.md
Normal file
|
|
@ -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.
|
||||||
197
docs/architecture/weft-shell-protocol.md
Normal file
197
docs/architecture/weft-shell-protocol.md
Normal file
|
|
@ -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
|
||||||
30
docs/upstream/servo-audit-backlog.md
Normal file
30
docs/upstream/servo-audit-backlog.md
Normal file
|
|
@ -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
|
||||||
43
infra/vm/linux-dev-environment.md
Normal file
43
infra/vm/linux-dev-environment.md
Normal file
|
|
@ -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.
|
||||||
Loading…
Reference in a new issue