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

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.