mirror of
https://github.com/marcoallegretti/WEFT_OS.git
synced 2026-03-26 17:03: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