mirror of
https://github.com/marcoallegretti/WEFT_OS.git
synced 2026-11-22 08:13:59 +00:00
Add AGENTS.md as the single engineering contract: sources of truth, evidence and proof requirements, ownership, working modes, the reviewed change loop, maintenance isolation, decision authority, dependency and fork rules, the 0.0.x to 0.1.0 release progression, and branch and publication rules. Add .agents/ with scope, implement, verify, maintenance and release procedures; reviewer, architecture debt scout, simplicity and refactoring roles; skills for the compositor, Servo rendering, runtime capabilities, appd sessions, packages and data, Linux deployment, integration verification and documentation; and verify.py, which runs the existing check profiles with --locked from any directory, stops on the first failure and supports --dry-run. check_toolkit.py validates local links and heading anchors, metadata, catalog coverage and issue forms. A new contributor-toolkit CI job runs both. The structure follows the Resina Design System toolkit at 1e768064f57a1e403ab271822383e732795905a6, adapted to WEFT. Validation, against the committed lockfiles: - verify.py toolkit: checker passes, 28 runner/checker tests pass - verify.py portable, demos, packages: pass - verify.py linux, runtime, servo-embed: fail on existing defects (clippy collapsible_if in the winit backend, three clippy lints in weft-runtime with wasmtime-runtime, and an E0308 in the selected Servo revision's servo-layout); the runner reports the failing status Add CONTRIBUTING.md, issue forms for defects and changes, maintenance problems and decisions of direction, and a pull request template asking for ownership, proof and the validation actually performed. README.md links the contribution guide.
58 lines
3.3 KiB
Markdown
58 lines
3.3 KiB
Markdown
---
|
|
name: weft-runtime-capabilities
|
|
description: Use for the Wasmtime runtime, WIT host imports, WASI preopens, effective grants, the file portal and seccomp.
|
|
---
|
|
|
|
# Runtime, WASI and capabilities
|
|
|
|
Owner: `weft-runtime` instantiates the component and enforces every host call;
|
|
appd derives the effective grants once from the resolved package. Portals and
|
|
host services act only on explicitly granted resources. Read the blueprint's
|
|
[security and capability contract](../../../BLUEPRINT.md#5-security-and-capability-contract)
|
|
and [component compatibility](../../../BLUEPRINT.md#42-manifest-and-component-compatibility).
|
|
|
|
## Where things live
|
|
|
|
| Concern | Source |
|
|
|---|---|
|
|
| Engine setup, linker, host imports, preopens, seccomp | [weft-runtime main.rs](../../../crates/weft-runtime/src/main.rs) |
|
|
| Host WIT (`weft:app@0.1.0`: notify, ipc, fetch, notifications, clipboard) | [weft-app.wit](../../../crates/weft-runtime/wit/weft-app.wit) |
|
|
| Demo copies of the WIT | `examples/*/wit/deps/weft-app/weft-app.wit` |
|
|
| Capability strings accepted at package check | `is_known_capability` and its `EXACT` list in [weft-pack](../../../crates/weft-pack/src/main.rs) |
|
|
| Capability to preopen mapping at launch | [appd runtime.rs](../../../crates/weft-appd/src/runtime.rs) |
|
|
| File portal | [weft-file-portal](../../../crates/weft-file-portal/src/main.rs) |
|
|
|
|
## Working rules
|
|
|
|
- Features: `wasmtime-runtime` enables the engine, `net-fetch` the fetch import,
|
|
`seccomp` the syscall blocklist. Without `wasmtime-runtime` the binary prints
|
|
READY and exits; that path is a limited build fixture, never product
|
|
evidence.
|
|
- Verify Wasmtime and wasmtime-wasi behavior in the version `Cargo.lock`
|
|
selects, including how the linker treats differing WIT patch versions. A
|
|
textual version difference is not an ABI defect until an actual component
|
|
shows it.
|
|
- Every advertised import checks the effective grant on every call. Absent or
|
|
unsupported operations fail explicitly; they are not successful no-ops.
|
|
- Keep read-only and read/write access distinct through preopens and the
|
|
portal. Confinement uses descriptor-relative or equivalent kernel-enforced
|
|
operations; lexical prefix checks and `canonicalize()` followed by reopening
|
|
are not sufficient against symlinks and replacement races.
|
|
- Fetch needs explicit schemes, destinations, methods, deadlines, size limits
|
|
and redirect authorization; keep HTTP errors distinct from transport errors.
|
|
- Keep one canonical WIT source with a checked synchronization mechanism for its
|
|
copies.
|
|
- Do not describe the seccomp blocklist or process separation as complete
|
|
confinement.
|
|
|
|
## Evidence
|
|
|
|
`python .agents/scripts/verify.py portable runtime` covers the stub and the
|
|
engine-enabled build, lints and unit tests. It does not instantiate a component.
|
|
Host import behavior needs an actual component fixture for the allowed, denied
|
|
and failure paths of each import; confinement needs traversal, symlink and
|
|
race cases against the real portal and preopens. No profile or CI job compiles
|
|
the `seccomp` feature; check it on Linux with
|
|
`cargo clippy -p weft-runtime --features wasmtime-runtime,seccomp --all-targets --locked -- -D warnings`
|
|
and prove filtering with a component or process fixture, not by compilation.
|
|
Rebuild demo components with the `demos` profile when the WIT changes.
|