WEFT_OS/.agents/skills/weft-runtime-capabilities/SKILL.md
Marco Allegretti 39869a2a38
docs: add engineering contract, contributor toolkit and templates
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.
2026-10-08 23:40:08 +00:00

3.3 KiB

name description
weft-runtime-capabilities 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 and component compatibility.

Where things live

Concern Source
Engine setup, linker, host imports, preopens, seccomp weft-runtime main.rs
Host WIT (weft:app@0.1.0: notify, ipc, fetch, notifications, clipboard) 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
Capability to preopen mapping at launch appd runtime.rs
File portal weft-file-portal

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.