Merge remote-tracking branch 'origin/fix/separate-app-data' into fix/session-owned-ipc-relay

This commit is contained in:
Marco Allegretti 2026-10-09 11:37:17 +00:00
commit cda9c14426
No known key found for this signature in database
37 changed files with 2864 additions and 20 deletions

121
.agents/README.md Normal file
View file

@ -0,0 +1,121 @@
# WEFT OS contributor toolkit
Procedures, review roles, area knowledge and a verification runner for
contributors. [AGENTS.md](../AGENTS.md) is the engineering
contract; [BLUEPRINT.md](../BLUEPRINT.md) is the accepted product direction;
[CONTRIBUTING.md](../CONTRIBUTING.md) is the maintainer-facing summary.
These files help apply the contract. They do not grant permissions, approve
decisions, schedule work or change the [working mode](../AGENTS.md#4-working-modes).
If a guide here seems to disagree with `AGENTS.md`, the contract wins and the
guide needs fixing.
## Start
1. Read `AGENTS.md`, identify the accepted scope and the owning component.
2. Load only the skills that match the boundary you are changing.
3. Use [scope](commands/scope.md) for an unverified report or proposal, and
[implement](commands/implement.md) for accepted, verifiable work.
4. Select checks and evidence with [verify](commands/verify.md), then have the
[reviewer](agents/reviewer.md) inspect the actual diff.
## Commands
Commands are portable Markdown procedures. Follow them as checklists.
| Command | Input | Result |
|---|---|---|
| [scope](commands/scope.md) | Report, defect or proposal | Evidence-backed issue draft with owner, acceptance criterion and proof |
| [implement](commands/implement.md) | Issue or accepted scope | Reviewed atomic change on a descriptive branch |
| [verify](commands/verify.md) | Scope or diff | Coverage map and actual check results |
| [maintenance](commands/maintenance.md) | One named maintenance role | One justified issue, or one isolated reviewed change |
| [release](commands/release.md) | Milestone scope and candidate commit | Candidate evidence and a promotion recommendation |
## Roles
Roles are checklists for a reviewer or a focused pass over the code. A role
file does nothing until a task invokes it.
| Role | Responsibility |
|---|---|
| [reviewer](agents/reviewer.md) | Review a specified diff for correctness, scope, ownership and evidence without editing it |
| [architecture-debt-scout](agents/architecture-debt-scout.md) | Report the strongest present ownership or boundary problem; never edit repository files |
| [continuous-simplicity](agents/continuous-simplicity.md) | Remove one duplicated decision, unnecessary state or misleading fallback path |
| [continuous-refactoring](agents/continuous-refactoring.md) | Resolve one structural problem while preserving behavior, ownership and proof |
## Skills
Each skill is a `SKILL.md` with `name` and `description` metadata. The `weft-`
prefix keeps them distinct from skills installed by other projects.
| Skill | Load when changing |
|---|---|
| [weft-compositor-input](skills/weft-compositor-input/SKILL.md) | Smithay compositor, Wayland protocols, surfaces, focus, geometry, input, DRM or winit backends |
| [weft-servo-rendering](skills/weft-servo-rendering/SKILL.md) | Servo embedding, painting and presentation, the Servo fork and Stylo overrides, system UI and app pages |
| [weft-runtime-capabilities](skills/weft-runtime-capabilities/SKILL.md) | Wasmtime host, WIT, WASI preopens, host imports, grants, file portal, seccomp |
| [weft-appd-sessions](skills/weft-appd-sessions/SKILL.md) | Session lifecycle, readiness, child supervision, cleanup, appd IPC, WebSocket bridge |
| [weft-packages-data](skills/weft-packages-data/SKILL.md) | Manifests, `weft-pack`, signing and trust, installation, updates, app data, EROFS images |
| [weft-linux-deployment](skills/weft-linux-deployment/SKILL.md) | Nix flake and VM, systemd units, native dependencies, installed paths and endpoints |
| [weft-integration-verification](skills/weft-integration-verification/SKILL.md) | End-to-end fixtures, pixels and input, failure injection, reliability and evidence records |
| [weft-documentation](skills/weft-documentation/SKILL.md) | Public documentation, the blueprint, this toolkit, templates and the runner |
## Verification runner
[`scripts/verify.py`](scripts/verify.py) runs the repository's actual check
profiles. It needs Python 3.10 or newer. It works from any directory, runs fixed
argument arrays from the repository root without a shell, stops at the first
failure and returns its status. It never formats files, installs packages or
toolchain targets, regenerates expectations, signs packages, commits or
publishes. It sets `RUSTUP_AUTO_INSTALL=0`, so a missing pinned toolchain or
component fails the check instead of being downloaded; install it with
`rustup show` or `rustup component add`.
```sh
python .agents/scripts/verify.py --help
python .agents/scripts/verify.py portable linux --dry-run
python .agents/scripts/verify.py portable linux
```
| Profile | Runs | Prerequisites |
|---|---|---|
| `toolkit` | Link, anchor, metadata, catalog and issue-form checks; runner tests | `pip install -r .agents/scripts/requirements.txt` |
| `portable` | `cargo fmt --check`; Clippy and tests for crates that need no Linux system libraries | Pinned toolchain |
| `linux` | Clippy and tests for `weft-compositor` and the feature-disabled shells | Linux Wayland, input, DRM and systemd development libraries |
| `servo-embed` | `cargo check` of both Servo hosts with the real renderer feature | As `linux`, plus the Servo build dependencies; long first build |
| `runtime` | Clippy and tests for `weft-runtime` with `wasmtime-runtime,net-fetch` | Pinned toolchain |
| `demos` | `cargo check` of the demo components for `wasm32-wasip2` | `rustup target add wasm32-wasip2` |
| `packages` | `weft-pack check` and `weft-pack verify` of the demo packages | Pinned toolchain |
All Cargo commands use `--locked`. Local `[patch]` overrides used for
cross-repository development change the resolved graph and make locked checks
fail; run the runner without them for evidence about the committed graph.
The runner covers compilation, lints, unit tests and package checks. It does not
run a compositor, render pixels, launch a session, boot the VM or exercise a
real component's host imports. Select that evidence with
[verify](commands/verify.md). Profiles are not a replacement for
[CI](../.github/workflows/ci.yml), and a passing profile is not approval to
publish, merge or release. No hooks are installed by this toolkit; if you call
the runner from a local hook, configure it in your own client or Git setup.
## Maintaining the toolkit
Put area knowledge in a skill, repeatable steps in a command, review criteria in
a role and executable checks in `scripts/`. Link to the contract and to the
owning source instead of restating policy or freezing implementation status.
List every command, role and skill in its table above; `toolkit` fails when a
document is not linked from this catalog. Changes to the runner need a test
showing failure behavior.
`check_toolkit.py` parses CommonMark links, images and reference links in this
directory and in the top-level contributor documents. It ignores code spans,
code blocks and HTML comments. It checks that local targets exist inside the
repository, that `#fragment` links into Markdown files match a GitHub-style
heading anchor, that metadata is a YAML mapping with unique string `name` and
`description` fields and a `name` matching its path, and that issue forms parse.
External URLs, raw HTML and the truth of the instructions still need review.
The structure follows the
[Resina Design System contributor toolkit](https://github.com/marcoallegretti/Resina-Design_System/tree/1e768064f57a1e403ab271822383e732795905a6/.agents)
at revision `1e768064f57a1e403ab271822383e732795905a6`. WEFT's contract,
ownership and evidence requirements determine its contents.

View file

@ -0,0 +1,39 @@
---
name: architecture-debt-scout
description: Find the strongest present ownership or boundary problem in WEFT OS with evidence and report it; never edit repository files.
---
# Architecture debt scout
Run through [maintenance](../commands/maintenance.md) under the contract's
[maintenance rules](../../AGENTS.md#8-maintenance). You may read the whole
repository and its history. You edit no repository files and create no branches,
commits or pull requests.
Look for present consequences at WEFT's boundaries:
- Responsibility held by the wrong owner, or two owners for one decision: session
state in both appd and the shell, package roots rediscovered by each child,
geometry decided outside the compositor.
- Authority taken from untrusted input: caller-supplied session IDs, PIDs,
window titles or stdout text treated as identity or readiness.
- Grants declared but not enforced at a host entry, or enforced differently in
WASI, the file portal and the renderer.
- Synthetic success: feature-disabled or fallback paths that report readiness,
delivery or verification.
- Contract drift between bridge and daemon messages, manifest and runtime
loading, image builder and loader, documentation and code.
- Dependency use that differs from the selected revision, or overrides that do
not reach the consuming workspace.
Check the blueprint's [baseline findings](../../BLUEPRINT.md#32-findings-that-determine-the-implementation-order)
and existing issues first: a known, already-scoped problem is not a new finding,
and one owned by the active goal is fixed there.
Apply the threshold: a named affected party, repository evidence, present cost
and an independent acceptance criterion. Return the single highest-value
qualifying problem with file and line evidence, owner and boundary, present
cost, acceptance criterion, expected proof and, where a decision is needed, the
meaningful alternatives. Create or update its issue only within granted
authority. When nothing qualifies, say so and stop. Do not decide architecture
or launch speculative work.

View file

@ -0,0 +1,30 @@
---
name: continuous-refactoring
description: Resolve one concrete structural problem in WEFT OS while preserving accepted behavior, ownership and proof.
---
# Continuous refactoring
Run through [maintenance](../commands/maintenance.md) under the contract's
[maintenance rules](../../AGENTS.md#8-maintenance). Establish the affected
caller, contract or test harness, the present cost and an independent acceptance
criterion.
Valid targets are demonstrated: duplicated logic with a working path on both
sides, coupled responsibilities that prevent testing, repeated conversions,
modules with several reasons to change, or structure that blocks a required
fixture. The blueprint names candidates that become justified once working paths
and regression evidence exist: shared package resolution, one effective-grants
model, one session cleanup owner, one bridge message contract and common Servo
host and input behavior. Extract a boundary only when that evidence exists.
Behavior, public contracts and ownership stay unchanged. Moving responsibility
between owners or changing a public contract needs a
[decision](../../AGENTS.md#9-decisions-and-authority): record it and stop the
change. Scope follows the acceptance criterion and ownership, not a file or line
budget.
Establish preservation proof first, refactor completely, run
[verify](../commands/verify.md) and have the [reviewer](reviewer.md) inspect the
committed range. Return the structural result, the contracts left unchanged and
the actual checks. Stop after one result.

View file

@ -0,0 +1,26 @@
---
name: continuous-simplicity
description: Remove one evidenced duplicated decision, unnecessary state or misleading fallback path while preserving WEFT OS behavior and ownership.
---
# Continuous simplicity
Run through [maintenance](../commands/maintenance.md) under the contract's
[maintenance rules](../../AGENTS.md#8-maintenance). Establish the affected
caller, contributor or contract, the present cost and the acceptance criterion
before changing anything.
Candidates are concrete: the same decision computed in two places, state that
can disagree with its source, a fallback that hides a failure or reports success
it did not achieve, an obsolete path, indirection without a second caller, or
documentation that restates and contradicts code. Prefer deletion and existing
concepts. Do not optimize for line count, merge distinct privileges or failure
domains, or replace explicit errors and authority checks with something shorter.
Removing a misleading fallback can change observable behavior from silent
success to explicit failure. That is in scope when the fallback contradicts the
contract; state the change and prove the new failure mode.
Establish preservation evidence first, implement, run [verify](../commands/verify.md)
and have the [reviewer](reviewer.md) inspect the committed range. Stop after one
issue and pull request result; simplification never becomes the primary goal.

View file

@ -0,0 +1,56 @@
---
name: reviewer
description: Review a specified WEFT OS diff for correctness, ownership, scope and evidence without editing it.
---
# Review a change
Input: the acceptance criterion, a base/head range or pull request diff, and the
validation evidence claimed. Read [AGENTS.md](../../AGENTS.md) and the
[skills](../README.md#skills) for the boundaries touched.
Inspect the actual change first: `git diff <base> <head>` for commits, or both
`git diff --staged` and `git diff` for uncommitted work. An empty `git diff HEAD`
after a commit means the wrong range was chosen, not that nothing changed. Read
the surrounding code and contracts needed to understand the behavior; do not turn
the review into repository-wide cleanup.
You report findings. You do not edit the change, approve decisions or releases,
or publish anything beyond the authority granted for the review.
Check:
1. **Behavior.** Does the change do what the acceptance criterion says on every
path, including errors, cancellation, timeouts, partial failure and teardown?
Are resources (processes, sockets, relays, mounts, temporary files) settled?
2. **Proof.** Would the named tests or fixtures fail if the behavior broke? Do
they exercise the real boundary, or a mock, a feature-disabled build or a log
line? Were expectations, fixtures or signatures changed with a contractual
reason? Were the claimed checks actually run, against the committed graph?
3. **Ownership.** Does each responsibility stay with its owner from the
[blueprint](../../BLUEPRINT.md#4-architecture-and-ownership)? Is a second
source of truth created for session state, grants, package resolution or
geometry? Is a decision of direction hidden inside cleanup?
4. **Trust and data.** Can application content, a forged session identifier or a
symlink obtain access it was not granted? Is user data preserved across
failure, update and uninstall? Are secrets and payloads kept out of logs?
5. **Compatibility.** Are manifest, WIT, protocol, IPC and package format changes
deliberate, versioned or converted? Do documentation and code agree?
6. **Dependencies.** Is every external API used as it exists in the revision the
lockfile selects? Are overrides applied at the workspace root?
7. **Scope and quality.** Is the change focused and atomic, free of unrelated
edits, generated or local-environment files, synthetic success paths and
unjustified abstraction? Are commit and pull request texts free of
attribution, trailers and process narration?
Each finding states severity, file and line, the concrete consequence, the
evidence you read or ran, and the required correction. Separate verified defects
from suspicions. **Blocking** findings concern correctness, promised behavior,
trust, data preservation, compatibility, accepted scope or required evidence.
Lower-impact findings are nonblocking. Do not manufacture findings or raise
preferences to blockers; unrelated debt does not block this change.
Return the findings, the checks you performed and whether any blocking finding
remains. Say so only after completing the review. State if you authored the
change or share its context, so the limitation can be reported honestly. Keep
this output separate from published pull request text.

View file

@ -0,0 +1,56 @@
---
name: implement
description: Carry accepted scope through proof, implementation, validation and diff review to one atomic result.
---
# Implement accepted scope
Input: an issue or an explicitly accepted task with an acceptance criterion.
Read [AGENTS.md](../../AGENTS.md) and the matching [skills](../README.md#skills).
This procedure applies the [reviewed change loop](../../AGENTS.md#5-reviewed-change-loop)
to contribution work and to each step of primary development. It adds no
approval layer: in primary development, continue to the next accepted step after
each accepted result.
1. **Inspect and confirm scope.** Verify the problem against current source and
evidence. If the acceptance criterion or proof is missing, use
[scope](scope.md). An issue is not a decision; if one is required and
unresolved, prepare it and work on something independent.
2. **Prepare the branch.** Inspect `git status`, the current branch, worktrees and
remotes. Fetch `main` and branch from it, or from the unmerged branch the work
depends on, with a descriptive
[branch name](../../AGENTS.md#14-branches-commits-and-publication). Preserve
unrelated changes; never commit contribution work directly to `main`.
3. **Review the plan.** Name the owner, the boundary touched, compatibility
promises affected and the proof. Check uncertain APIs in the dependency
source selected by the lockfile. Fix it here if the design crosses ownership.
4. **Establish proof.** Reproduce a defect first. For new behavior, add the
fixture or contract case that fails without the change. Identify which
evidence needs a real environment (compositor, renderer, VM) and whether it is
available.
5. **Implement** the smallest complete change. Keep manifests, WIT, protocol,
IPC types, documentation and callers coherent. No synthetic success paths.
6. **Validate** with [verify](verify.md): the smallest sufficient profiles plus
any boundary-specific evidence. Fix failures within scope. Explain every
changed expectation; never re-bless output to make it pass.
7. **Review the actual diff** with the [reviewer](../agents/reviewer.md), from a
reviewer who did not write it when available, otherwise as a fresh separate
pass whose limitation you state. Review `git diff <base> <head>` for commits,
or both staged and unstaged diffs before committing.
8. **Correct, revalidate and re-review** until no blocking finding remains.
Recheck after material corrections, rebases and conflict resolutions.
9. **Commit atomically.** Inspect `git status` and the complete diff; exclude
generated, transient and local-environment files (for example lockfile changes
caused by local `[patch]` overrides). Write the message for maintainers.
10. **Publish within authority.** If pushing or opening a pull request is
authorized and available, fill the
[pull request template](../../.github/pull_request_template.md) and inspect
automated review integrations first. Otherwise return the local result and
the prepared description.
11. **Reassess** the goal from the new repository state and continue with the
next dependent step.
Report what changed, what proves it, the checks actually run with results, and
material limitations. A separately actionable problem found on the way goes
through the [maintenance threshold](../../AGENTS.md#8-maintenance) instead of
the pull request body. Completing a change grants no merge or release authority.

View file

@ -0,0 +1,36 @@
---
name: maintenance
description: Run one maintenance role for one qualifying problem from the verified current main, isolated from primary development.
---
# Run one maintenance task
Input: one named role, [architecture-debt-scout](../agents/architecture-debt-scout.md),
[continuous-simplicity](../agents/continuous-simplicity.md) or
[continuous-refactoring](../agents/continuous-refactoring.md), and optionally a
candidate problem. Read [maintenance](../../AGENTS.md#8-maintenance) in the
contract and load the role.
1. **Verify the base.** Fetch `main` and record its revision. If freshness cannot
be verified, state the revision you used and the limitation. Never switch,
reset or edit the active development checkout.
2. **Apply the threshold.** Find the strongest problem that has a named affected
party, present repository evidence, present cost and an independent acceptance
criterion. A problem inside the active goal's acceptance criterion belongs to
that goal, not here. If nothing qualifies, report that and stop.
3. **Check for existing work.** Search issues and pull requests for the same
underlying problem and update the existing one instead of duplicating. Report
incomplete duplicate checking when access is unavailable.
4. **Record it.** Draft the issue with [scope](scope.md) and the
[maintenance form](../../.github/ISSUE_TEMPLATE/maintenance.yml), creating or
updating it only within granted authority. The scout stops here.
5. **Isolate.** For simplicity or refactoring, add a worktree from the fetched
`main`, for example `git worktree add ../weft-share-package-resolution -b refactor/share-package-resolution origin/main`.
Use a branch name that describes the change, not the role.
6. **Change and review.** Follow [implement](implement.md) from proof to one
reviewed pull request, or to a prepared local result when publication is not
authorized. If the change turns out to need a
[decision](../../AGENTS.md#9-decisions-and-authority), stop it and record
the decision needed.
7. **Stop.** One run handles one problem. Do not continue collecting
opportunities, and do not merge.

View file

@ -0,0 +1,43 @@
---
name: release
description: Prepare a 0.0.x or 0.1.0 candidate's evidence and recommend promotion without promoting it automatically.
---
# Prepare a release stage
Input: the milestone scope, the target version and stage, and the exact
candidate commit. Read [versions and releases](../../AGENTS.md#13-versions-and-releases),
the blueprint's [version progression](../../BLUEPRINT.md#121-version-progression)
and, for stable `0.1.0`, the [stable release gate](../../BLUEPRINT.md#14-stable-release-gate).
1. **Inventory.** List existing tags, published releases and the versions in
`Cargo.toml`, crate manifests and package manifests. Choose the next unused
`0.0.x` for an accepted milestone scope; never reuse, move or rewrite a
published tag or release. Record how the unreleased workspace value `0.1.0`
is reconciled.
2. **Check the stage contract.** `alpha.N` needs defined scope, ownership and
fixtures with incompleteness stated. `beta.N` needs the declared scope
implemented, relevant integration and failure paths passing and interfaces,
support scope and budgets frozen. `rc.N` needs the exact candidate complete
for its scope, the required matrix passing, independent technical review and
ready artifacts and migration behavior. Final, released as the plain version
without a `-final` suffix, needs every scoped promise to pass.
3. **Collect candidate evidence** for that exact commit with [verify](verify.md):
every applicable runner profile plus the blueprint fixtures and target
environments in scope. Record commit, environment, features, commands, results
and artifact digests. A missing environment leaves the gate incomplete.
4. **Obtain independent technical review** of the candidate with the
[reviewer](../agents/reviewer.md), aimed at showing it is not ready. A self
review does not satisfy a release gate; an unavailable reviewer leaves the gate
pending while other authorized work continues.
5. **Resolve or scope.** Blocking findings prevent promotion. Corrections after
review invalidate the affected evidence: rebuild the candidate, rerun the
affected checks and re-review. Unsupported features are excluded explicitly,
not left as silent success paths.
6. **Prepare release notes** for maintainers: scope, support matrix, known
limitations, compatibility and migration notes, commit and artifact digests,
and the evidence actually executed.
7. **Recommend.** Return the evidence, open findings and a recommendation.
Promotion, tagging and publication happen only under granted release
authority, and publish the artifact that was tested. If final metadata
requires a rebuild, verify that rebuilt artifact before publishing it.

43
.agents/commands/scope.md Normal file
View file

@ -0,0 +1,43 @@
---
name: scope
description: Establish a reported problem or proposal and draft verifiable scope with owner, acceptance criterion and proof.
---
# Establish the scope
Input: a defect report, desired behavior or proposal. Read
[AGENTS.md](../../AGENTS.md), the relevant sections of
[BLUEPRINT.md](../../BLUEPRINT.md) and the matching
[skills](../README.md#skills). The result is a draft; this procedure neither
implements it nor authorizes publication.
1. **Inspect.** Read the implemented source, the public contract involved
(manifest, WIT, shell protocol, IPC types) and the selected dependency source
when an external API matters. Check whether the blueprint already records the
problem, for example in its [baseline findings](../../BLUEPRINT.md#32-findings-that-determine-the-implementation-order).
2. **Reproduce** where practical, with the exact commit, environment, features
and command. Separate observations from assumptions and say which level of
[evidence](../../BLUEPRINT.md#111-evidence-levels) each observation reached.
3. **Name the owner** from the
[ownership table](../../BLUEPRINT.md#4-architecture-and-ownership) and the
affected user, caller or contract. If nobody is worse off today, stop: there
is no issue.
4. **Check for duplicates** among existing issues and pull requests. If access is
unavailable, say that duplicate checking is incomplete.
5. **Decide the path.** Ordinary work within accepted architecture becomes a
change. A material departure from accepted direction, compatibility, trust,
support scope or data policy needs a
[decision](../../AGENTS.md#9-decisions-and-authority): prepare the evidence,
alternatives and trade-offs and mark implementation as waiting for it.
6. **Draft** against the matching form:
[defect or change](../../.github/ISSUE_TEMPLATE/change.yml),
[maintenance](../../.github/ISSUE_TEMPLATE/maintenance.yml) or
[decision](../../.github/ISSUE_TEMPLATE/decision.yml).
The draft states observed and expected behavior, evidence with file and line
references, owner and affected boundary, present impact, one acceptance
criterion, the proof that would fail today and pass afterwards, and relevant
non-goals. A claim without a verification surface is unfinished scope.
Return the draft plus any missing evidence or decision. Create or update an
issue only when that is part of the authorized task.

View file

@ -0,0 +1,43 @@
---
name: verify
description: Map a change to the evidence that proves it, run the applicable checks and report actual results and gaps.
---
# Select and run the evidence
Input: accepted scope and a diff or explicit base/head range. Read the
[proof rules](../../AGENTS.md#6-proof-before-implementation), the blueprint's
[verification profiles](../../BLUEPRINT.md#112-verification-profiles) and
[acceptance fixtures](../../BLUEPRINT.md#113-required-acceptance-fixtures), and
[CI](../../.github/workflows/ci.yml).
List the observable behaviors the change affects, not the files. For each,
name the check that would fail if it were wrong and classify it as direct proof,
incidental coverage or missing. Then select:
| Affected area | Runner profiles | Evidence the runner cannot provide |
|---|---|---|
| Portable crates (`weft-appd`, `weft-pack`, `weft-ipc-types`, `weft-file-portal`, `weft-mount-helper`, `weft-build-meta`, `weft-runtime` stub) | `portable` | Child processes, sockets and filesystems exercised for real where the change depends on them |
| `weft-compositor` | `portable linux` | Nested winit session with real clients; DRM session on the declared target |
| Servo hosts | `linux servo-embed` | Painted and presented pixels, input, resize and idle wakeup on a running compositor |
| `weft-runtime` engine or host imports | `portable runtime` | Actual component fixtures for allowed, denied and failure paths; a Linux build of the `seccomp` feature when it is touched |
| WIT, demo components | `demos packages` | Instantiating the rebuilt component under `weft-runtime` |
| Package tooling, signing, demo packages | `portable packages` | Tamper, interruption and data-retention fixtures |
| Dependency or fork change | Every profile whose crates resolve the changed package | Resolved graph inspection; the rendered or runtime behavior the change claims |
| Nix, systemd, VM | None directly | `infra/vm/build.sh` and a booted graphical image |
| Contributor documentation and toolkit | `toolkit` | Manual consistency with `AGENTS.md` and the blueprint |
Run the selected profiles with `python .agents/scripts/verify.py <profiles>`, or
the equivalent commands directly, and record actual exit results. Run them
against the committed graph, without local `[patch]` overrides.
A missing native library, toolchain target, display, GPU, VM or Nix installation
is unavailable evidence: name it and the boundary left unverified. Never count a
skip, a feature-disabled build or a mocked boundary as proof of the real path.
Choose expensive checks by risk; do not repeat unrelated ones once the risk is
resolved. Release gates need the complete matrix in [release](release.md).
Return a compact table of behaviors, proof and status; the commands actually run
with results; remaining gaps; and the single most valuable missing check if one
exists. Do not change product code to probe coverage unless that experiment is
authorized and isolated.

View file

@ -0,0 +1,174 @@
"""Check contributor documents: local links and anchors, toolkit metadata, catalog and issue forms."""
import re
import sys
from pathlib import Path
from urllib.parse import unquote, urlsplit
try:
import yaml
from markdown_it import MarkdownIt
except ImportError as error:
sys.exit(f"{error}; install .agents/scripts/requirements.txt to run the toolkit checks")
ROOT = Path(__file__).resolve().parents[2]
MARKDOWN = MarkdownIt("commonmark")
FRONTMATTER = re.compile(r"\A---\n(.*?)\n---(?:\n|\Z)", re.DOTALL)
CATALOGUED = ("commands", "agents", "skills")
TOP_LEVEL = ("AGENTS.md", "CONTRIBUTING.md", "README.md", "BLUEPRINT.md",
".github/pull_request_template.md")
SLUG_DROP = re.compile(r"[^\w\- ]", re.UNICODE)
def body(source):
match = FRONTMATTER.match(source)
return source[match.end():] if match else source
def tokens(source):
for block in MARKDOWN.parse(body(source)):
yield block
yield from block.children or []
def local_links(path, source, *, images=True):
"""Yield (target, resolved path, fragment) for each relative link or image."""
for token in tokens(source):
if token.type == "link_open":
target = token.attrGet("href")
elif images and token.type == "image":
target = token.attrGet("src")
else:
continue
if not target:
continue
url = urlsplit(target)
if url.scheme or url.netloc:
continue
resolved = (path.parent / unquote(url.path)).resolve() if url.path else path.resolve()
yield target, resolved, unquote(url.fragment)
def anchors(source):
"""Return GitHub-style heading anchors, including numbered duplicates."""
result, seen = set(), {}
blocks = MARKDOWN.parse(body(source))
for index, block in enumerate(blocks):
if block.type != "heading_open":
continue
inline = blocks[index + 1]
text = "".join(child.content for child in inline.children or []
if child.type in ("text", "code_inline"))
slug = SLUG_DROP.sub("", text.strip().lower()).replace(" ", "-")
count = seen.get(slug, 0)
seen[slug] = count + 1
result.add(slug if count == 0 else f"{slug}-{count}")
return result
def metadata_fields(source):
"""Return name/description from a YAML mapping with unique string fields, else None."""
try:
node = yaml.compose(source, Loader=yaml.SafeLoader)
except yaml.YAMLError:
return None
if not isinstance(node, yaml.MappingNode):
return None
fields = {}
for key, value in node.value:
if (not isinstance(key, yaml.ScalarNode) or key.tag != "tag:yaml.org,2002:str"
or key.value in fields):
return None
fields[key.value] = value
result = {}
for name in ("name", "description"):
value = fields.get(name)
if not isinstance(value, yaml.ScalarNode) or value.tag != "tag:yaml.org,2002:str":
return None
result[name] = value.value
return result
def check_issue_forms(root):
errors = []
for path in sorted((root / ".github/ISSUE_TEMPLATE").glob("*.yml")):
label = path.relative_to(root)
try:
form = yaml.safe_load(path.read_text(encoding="utf-8"))
except yaml.YAMLError as error:
errors.append(f"{label}: invalid YAML: {error}")
continue
if path.name == "config.yml":
if not isinstance(form, dict) or "blank_issues_enabled" not in form:
errors.append(f"{label}: missing blank_issues_enabled")
continue
if (not isinstance(form, dict) or not isinstance(form.get("name"), str)
or not isinstance(form.get("description"), str)
or not isinstance(form.get("body"), list) or not form["body"]):
errors.append(f"{label}: issue form needs name, description and a nonempty body")
continue
ids = [item.get("id") for item in form["body"]
if isinstance(item, dict) and item.get("type") != "markdown"]
if None in ids or len(ids) != len(set(ids)):
errors.append(f"{label}: every input needs a unique id")
return errors
def check(root):
root = root.resolve()
toolkit = root / ".agents"
catalog_path = toolkit / "README.md"
if not catalog_path.is_file():
return ["missing .agents/README.md"]
catalog = catalog_path.read_text(encoding="utf-8")
catalog_targets = {resolved for _, resolved, _ in local_links(catalog_path, catalog,
images=False)}
errors = []
documents = sorted(toolkit.rglob("*.md")) + [root / name for name in TOP_LEVEL]
anchor_cache = {}
for path in documents:
label = path.relative_to(root)
if not path.is_file():
errors.append(f"missing {label}")
continue
source = path.read_text(encoding="utf-8")
for target, resolved, fragment in local_links(path, source):
if not resolved.is_relative_to(root) or not resolved.exists():
errors.append(f"{label}: broken local link {target}")
continue
if fragment and resolved.suffix == ".md":
if resolved not in anchor_cache:
anchor_cache[resolved] = anchors(resolved.read_text(encoding="utf-8"))
if fragment not in anchor_cache[resolved]:
errors.append(f"{label}: missing anchor {target}")
relative = path.relative_to(toolkit) if path.is_relative_to(toolkit) else None
if relative and relative.parts[0] in CATALOGUED:
match = FRONTMATTER.match(source)
if not match:
errors.append(f"{label}: missing front matter")
continue
fields = metadata_fields(match[1])
expected = path.parent.name if path.name == "SKILL.md" else path.stem
if not fields or fields["name"] != expected or not fields["description"].strip():
errors.append(f"{label}: name must match path and description must be nonempty; "
"use a YAML mapping with unique string fields")
if path.resolve() not in catalog_targets:
errors.append(f"{label}: absent from toolkit catalog")
for kind in CATALOGUED:
if not list((toolkit / kind).rglob("*.md")):
errors.append(f"no documents in .agents/{kind}")
return errors + check_issue_forms(root)
def main():
errors = check(ROOT)
if errors:
print("\n".join(errors), file=sys.stderr)
return 1
print("Contributor toolkit links, anchors, metadata, catalog and issue forms passed.")
return 0
if __name__ == "__main__":
raise SystemExit(main())

View file

@ -0,0 +1,3 @@
markdown-it-py==4.2.0
mdurl==0.1.2
PyYAML==6.0.3

View file

@ -0,0 +1,240 @@
import contextlib
import importlib.util
import io
import subprocess
import sys
import tempfile
import unittest
from pathlib import Path
from unittest.mock import patch
HERE = Path(__file__).resolve().parent
ROOT = HERE.parents[1]
def load(name):
spec = importlib.util.spec_from_file_location(f"weft_toolkit_{name}", HERE / f"{name}.py")
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
return module
checker = load("check_toolkit")
verify = load("verify")
SKILL = "---\nname: example\ndescription: An example skill.\n---\n[Contract](../../../AGENTS.md)\n"
COMMAND = "---\nname: run\ndescription: An example command.\n---\n# Run\n"
ROLE = "---\nname: role\ndescription: An example role.\n---\n# Role\n"
CATALOG = ("[Example](skills/example/SKILL.md)\n[Run](commands/run.md)\n"
"[Role](agents/role.md)\n")
FORM = ("name: Change\ndescription: A change.\nbody:\n"
" - type: markdown\n attributes:\n value: Intro\n"
" - type: textarea\n id: observed\n attributes:\n label: Observed\n")
class ToolkitCheck(unittest.TestCase):
def setUp(self):
directory = tempfile.TemporaryDirectory()
self.addCleanup(directory.cleanup)
self.root = Path(directory.name)
for name in checker.TOP_LEVEL:
path = self.root / name
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text("# Contract\n\n## 2. Evidence levels\n", encoding="utf-8")
self.skill = self.write(".agents/skills/example/SKILL.md", SKILL)
self.write(".agents/commands/run.md", COMMAND)
self.write(".agents/agents/role.md", ROLE)
self.catalog = self.write(".agents/README.md", CATALOG)
self.form = self.write(".github/ISSUE_TEMPLATE/change.yml", FORM)
self.write(".github/ISSUE_TEMPLATE/config.yml", "blank_issues_enabled: false\n")
def write(self, relative, text):
path = self.root / relative
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(text, encoding="utf-8")
return path
def errors_containing(self, text):
return [error for error in checker.check(self.root) if text in error]
def append_to_skill(self, text):
self.skill.write_text(SKILL + text + "\n", encoding="utf-8")
def test_valid_toolkit_passes(self):
self.assertEqual(checker.check(self.root), [])
def test_missing_contract_breaks_links(self):
(self.root / "AGENTS.md").unlink()
self.assertTrue(self.errors_containing("broken local link"))
def test_link_outside_repository_is_rejected(self):
self.append_to_skill("[Outside](../../../../outside.md)")
self.assertTrue(self.errors_containing("broken local link"))
def test_existing_and_missing_anchors(self):
self.append_to_skill("[Levels](../../../AGENTS.md#2-evidence-levels)")
self.assertEqual(checker.check(self.root), [])
self.append_to_skill("[Levels](../../../AGENTS.md#3-missing)")
self.assertTrue(self.errors_containing("missing anchor"))
def test_same_document_anchor(self):
self.skill.write_text(SKILL + "## Local `code` heading\n[Here](#local-code-heading)\n",
encoding="utf-8")
self.assertEqual(checker.check(self.root), [])
self.skill.write_text(SKILL + "[Here](#absent)\n", encoding="utf-8")
self.assertTrue(self.errors_containing("missing anchor"))
def test_duplicate_headings_receive_numbered_anchors(self):
self.skill.write_text(SKILL + "## Step\n## Step\n[Second](#step-1)\n", encoding="utf-8")
self.assertEqual(checker.check(self.root), [])
def test_literal_examples_are_not_links(self):
for example in ["`[X](missing.md)`", "```md\n[X](missing.md)\n```",
"<!-- [X](missing.md) -->", r"\[X](missing.md)"]:
with self.subTest(example=example):
self.append_to_skill(example)
self.assertEqual(checker.check(self.root), [])
def test_reference_links_are_checked(self):
self.append_to_skill("[Missing][doc]\n\n[doc]: missing.md")
self.assertTrue(self.errors_containing("broken local link"))
def test_metadata_must_match_path_and_be_unique_strings(self):
for fields in ["name: other\ndescription: Example.", "name: example\ndescription:",
"name: example\ndescription: 42", "name: example\nname: example\n"
"description: Example.", "name: example\ndescription: [unterminated"]:
with self.subTest(fields=fields):
self.skill.write_text(f"---\n{fields}\n---\n", encoding="utf-8")
self.assertTrue(self.errors_containing("name must match path"))
def test_missing_front_matter_is_rejected(self):
self.skill.write_text("# No metadata\n", encoding="utf-8")
self.assertTrue(self.errors_containing("missing front matter"))
def test_uncatalogued_document_is_rejected(self):
self.catalog.write_text("[Example](skills/example/SKILL.md)\n", encoding="utf-8")
errors = self.errors_containing("absent from toolkit catalog")
self.assertEqual(len(errors), 2)
def test_catalog_needs_a_visible_link(self):
self.catalog.write_text("`[Example](skills/example/SKILL.md)`\n"
"[Run](commands/run.md)\n[Role](agents/role.md)\n",
encoding="utf-8")
self.assertTrue(self.errors_containing("absent from toolkit catalog"))
def test_empty_toolkit_directory_is_rejected(self):
(self.root / ".agents/agents/role.md").unlink()
self.catalog.write_text("[Example](skills/example/SKILL.md)\n[Run](commands/run.md)\n",
encoding="utf-8")
self.assertTrue(self.errors_containing("no documents in .agents/agents"))
def test_issue_forms_are_validated(self):
self.form.write_text("name: Change\nbody: []\n", encoding="utf-8")
self.assertTrue(self.errors_containing("issue form needs"))
self.form.write_text(FORM + " - type: input\n id: observed\n", encoding="utf-8")
self.assertTrue(self.errors_containing("unique id"))
self.form.write_text("name: [unterminated\n", encoding="utf-8")
self.assertTrue(self.errors_containing("invalid YAML"))
def test_repository_toolkit_passes(self):
self.assertEqual(checker.check(ROOT), [])
def test_missing_dependencies_fail_with_instructions(self):
result = subprocess.run([sys.executable, "-I", "-S", "-B", str(HERE / "check_toolkit.py")],
capture_output=True, text=True, check=False)
self.assertEqual(result.returncode, 1)
self.assertIn("requirements.txt", result.stderr)
class Runner(unittest.TestCase):
def run_quietly(self, argv):
with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()):
return verify.main(argv)
def test_dry_run_from_another_directory_executes_nothing(self):
with tempfile.TemporaryDirectory() as directory:
result = subprocess.run(
[sys.executable, str(HERE / "verify.py"), "portable", "demos", "--dry-run"],
cwd=directory, capture_output=True, text=True, check=False,
)
self.assertEqual(list(Path(directory).iterdir()), [])
self.assertEqual(result.returncode, 0, result.stderr)
self.assertIn("cargo fmt --all --check", result.stdout)
self.assertIn("--target wasm32-wasip2", result.stdout)
def test_dry_run_calls_no_subprocess(self):
with patch.object(verify.subprocess, "run") as run:
self.assertEqual(self.run_quietly(list(verify.PROFILES) + ["--dry-run"]), 0)
run.assert_not_called()
def test_commands_run_from_repository_root(self):
with patch.object(verify.subprocess, "run") as run:
run.return_value = subprocess.CompletedProcess([], 0)
self.assertEqual(self.run_quietly(["servo-embed"]), 0)
self.assertEqual(run.call_count, 2)
for call in run.call_args_list:
self.assertEqual(call.kwargs["cwd"], ROOT)
self.assertEqual(call.kwargs["env"]["RUSTUP_AUTO_INSTALL"], "0")
self.assertIsInstance(call.args[0], list)
def test_failure_stops_remaining_checks_and_keeps_status(self):
with patch.object(verify.subprocess, "run") as run:
run.return_value = subprocess.CompletedProcess([], 7)
self.assertEqual(self.run_quietly(["portable", "linux"]), 7)
self.assertEqual(run.call_count, 1)
def test_failure_in_later_command_stops_profile(self):
statuses = [subprocess.CompletedProcess([], 0), subprocess.CompletedProcess([], 101)]
with patch.object(verify.subprocess, "run", side_effect=statuses) as run:
self.assertEqual(self.run_quietly(["portable", "linux"]), 101)
self.assertEqual(run.call_count, 2)
def test_signal_termination_is_failure(self):
with patch.object(verify.subprocess, "run") as run:
run.return_value = subprocess.CompletedProcess([], -9)
self.assertEqual(self.run_quietly(["toolkit"]), 1)
def test_missing_executable_is_failure(self):
with patch.object(verify.subprocess, "run", side_effect=FileNotFoundError("cargo")):
self.assertEqual(self.run_quietly(["linux"]), 1)
def test_real_failing_command_propagates(self):
failing = {"failing": ("fails", [[sys.executable, "-c", "raise SystemExit(3)"]])}
with patch.dict(verify.PROFILES, failing):
self.assertEqual(self.run_quietly(["failing"]), 3)
def test_unknown_profile_is_rejected_before_execution(self):
with patch.object(verify.subprocess, "run") as run:
with self.assertRaises(SystemExit) as error:
self.run_quietly(["unknown"])
self.assertEqual(error.exception.code, 2)
run.assert_not_called()
def test_repeated_profiles_run_once(self):
with patch.object(verify.subprocess, "run") as run:
run.return_value = subprocess.CompletedProcess([], 0)
self.run_quietly(["servo-embed", "servo-embed"])
self.assertEqual(run.call_count, 2)
def test_profiles_never_mutate_install_or_publish(self):
forbidden = {"install", "add", "update", "fix", "publish", "push", "commit", "sign",
"uninstall", "--bless", "--fix", "--allow-dirty"}
for name, (_, commands) in verify.PROFILES.items():
for command in commands:
with self.subTest(profile=name, command=command):
self.assertTrue(all(isinstance(part, str) for part in command))
self.assertFalse(forbidden.intersection(command))
if command[:2] == ["cargo", "fmt"]:
self.assertIn("--check", command)
def test_cargo_checks_use_the_locked_graph(self):
for name, (_, commands) in verify.PROFILES.items():
for command in commands:
if command[0] == "cargo" and command[1] != "fmt":
with self.subTest(profile=name, command=command):
self.assertIn("--locked", command)
if __name__ == "__main__":
unittest.main()

128
.agents/scripts/verify.py Normal file
View file

@ -0,0 +1,128 @@
"""Run WEFT OS verification profiles without installing, formatting or publishing anything.
Each profile is a fixed list of argument arrays executed from the repository root.
The runner stops at the first failing command and returns its exit status.
"""
import argparse
import os
import subprocess
import sys
from pathlib import Path
ROOT = Path(__file__).resolve().parents[2]
# Stop rustup from installing the pinned toolchain or its components on demand.
ENVIRONMENT = {**os.environ, "RUSTUP_AUTO_INSTALL": "0"}
LINUX_CRATES = ["weft-compositor", "weft-servo-shell", "weft-app-shell"]
DEMOS = ["examples/org.weft.demo.counter", "examples/org.weft.demo.notes"]
DEMO_KEY = "examples/keys/weft-sign.pub"
RUNTIME_FEATURES = "wasmtime-runtime,net-fetch"
def _packages(flag, crates):
return [part for crate in crates for part in (flag, crate)]
PROFILES = {
"toolkit": (
"Contributor toolkit links, catalog, metadata and runner tests",
[
[sys.executable, "-B", ".agents/scripts/check_toolkit.py"],
[sys.executable, "-B", "-m", "unittest", "discover", "-s", ".agents/scripts",
"-p", "test_*.py"],
],
),
"portable": (
"Formatting, Clippy and tests for crates that need no Linux system libraries (CI portable)",
[
["cargo", "fmt", "--all", "--check"],
["cargo", "clippy", "--workspace", *_packages("--exclude", LINUX_CRATES),
"--all-targets", "--locked", "--", "-D", "warnings"],
["cargo", "test", "--workspace", *_packages("--exclude", LINUX_CRATES), "--locked"],
],
),
"linux": (
"Clippy and tests for the Wayland compositor and feature-disabled shells (CI linux-only)",
[
["cargo", "clippy", *_packages("-p", LINUX_CRATES), "--all-targets", "--locked",
"--", "-D", "warnings"],
["cargo", "test", *_packages("-p", LINUX_CRATES), "--locked"],
],
),
"servo-embed": (
"Type-check both Servo hosts with the real renderer feature (CI servo-embed-linux)",
[
["cargo", "check", "-p", "weft-servo-shell", "--features", "servo-embed", "--locked"],
["cargo", "check", "-p", "weft-app-shell", "--features", "servo-embed", "--locked"],
],
),
"runtime": (
"Clippy and tests for weft-runtime with the Wasmtime engine and fetch enabled",
[
["cargo", "clippy", "-p", "weft-runtime", "--features", RUNTIME_FEATURES,
"--all-targets", "--locked", "--", "-D", "warnings"],
["cargo", "test", "-p", "weft-runtime", "--features", RUNTIME_FEATURES, "--locked"],
],
),
"demos": (
"Check the demo components for wasm32-wasip2 against their own lockfiles",
[
["cargo", "check", "--locked", "--manifest-path", f"{demo}/Cargo.toml",
"--target", "wasm32-wasip2", "--target-dir", "target/examples"]
for demo in DEMOS
],
),
"packages": (
"Validate the demo packages and verify their committed signatures with weft-pack",
[
command
for demo in DEMOS
for command in (
["cargo", "run", "--quiet", "--locked", "-p", "weft-pack", "--", "check", demo],
["cargo", "run", "--quiet", "--locked", "-p", "weft-pack", "--", "verify", demo,
"--key", DEMO_KEY],
)
],
),
}
def describe():
width = max(map(len, PROFILES))
lines = [f" {name:<{width}} {summary}" for name, (summary, _) in PROFILES.items()]
return "profiles:\n" + "\n".join(lines)
def main(argv=None):
parser = argparse.ArgumentParser(
description=__doc__,
epilog=describe(),
formatter_class=argparse.RawDescriptionHelpFormatter,
)
parser.add_argument("profiles", nargs="+", choices=PROFILES, metavar="profile",
help="one or more profiles, run in the given order")
parser.add_argument("--dry-run", action="store_true",
help="print the commands without running them")
args = parser.parse_args(argv)
for profile in dict.fromkeys(args.profiles):
for command in PROFILES[profile][1]:
print(f"[{profile}] {subprocess.list2cmdline(command)}", flush=True)
if args.dry_run:
continue
try:
result = subprocess.run(command, cwd=ROOT, env=ENVIRONMENT, check=False)
except OSError as error:
print(f"[{profile}] cannot run {command[0]}: {error}", file=sys.stderr)
return 1
if result.returncode != 0:
print(f"[{profile}] failed with exit status {result.returncode}", file=sys.stderr)
return result.returncode if result.returncode > 0 else 1
return 0
if __name__ == "__main__":
raise SystemExit(main())

View file

@ -0,0 +1,59 @@
---
name: weft-appd-sessions
description: Use for weft-appd session lifecycle, readiness, child supervision and cleanup, the appd IPC and WebSocket bridge, and compositor association.
---
# Appd sessions and IPC
Owner: `weft-appd` owns resolved package selection, effective grants, session
identity, child supervision, readiness and cleanup. The shells display that
state; they do not keep a second authoritative copy. Read the blueprint's
[resolved package descriptor](../../../BLUEPRINT.md#41-one-resolved-package-descriptor),
[role-separated protocol](../../../BLUEPRINT.md#61-role-separated-protocol) and
[single lifecycle owner](../../../BLUEPRINT.md#62-single-lifecycle-owner).
## Where things live
| Concern | Source |
|---|---|
| Daemon, session registry, request dispatch | [appd main.rs](../../../crates/weft-appd/src/main.rs) |
| Child spawning, preopens, systemd wrapping, data paths | [runtime.rs](../../../crates/weft-appd/src/runtime.rs) |
| Unix socket messages | [ipc.rs](../../../crates/weft-appd/src/ipc.rs) |
| Browser-facing WebSocket server | [ws.rs](../../../crates/weft-appd/src/ws.rs) |
| Compositor association client | [compositor_client.rs](../../../crates/weft-appd/src/compositor_client.rs), [weft-ipc-types](../../../crates/weft-ipc-types/src/lib.rs) |
| Image mount path | [mount.rs](../../../crates/weft-appd/src/mount.rs) |
| Injected app bridge | [app-shell embedder](../../../crates/weft-app-shell/src/embedder.rs) |
| Shell-side client | [system-ui.html](../../../infra/shell/system-ui.html) |
## Working rules
- One session model: `Starting -> Running -> Stopping -> Stopped`, with
structured terminal reasons. `Running` requires the component initialized,
session IPC connected, the document and bridge initialized and the surface's
first frame presented. Stdout text cannot establish readiness.
- Every exit path enters the same cleanup: spawn failure, invalid package,
initialization failure, timeout, cancellation, guest trap, child crash,
explicit close and daemon shutdown. Owned resources include both children,
portals, relays, sockets, compositor associations, temporary directories and
mounts.
- Use a process-group or systemd mechanism that is valid for the selected
systemd and preserves ownership; verify `systemd-run` argument combinations
against the installed version. Terminate gracefully for a bounded time, then
forcibly, and await settlement instead of sleeping.
- A caller-supplied `session_id` is a routing claim. Bind role, session and
generation on the server, authenticate the browser bootstrap, and never
deliver private payloads to unrelated subscribers.
- The bridge and daemon share one versioned semantic envelope. Bound frame size,
queued messages and bytes and concurrency; preserve partial frames across
cancellation; do not hold the registry lock across awaits; remove closed
relays; resynchronize from a snapshot after overflow.
- Default logs exclude application payloads, clipboard contents, saved notes and
credentials.
## Evidence
`python .agents/scripts/verify.py portable` runs the appd and IPC unit tests.
Lifecycle and protocol claims need fixtures with real child processes and
sockets: each startup phase failing or cancelled, children crashing, fragmented
and concurrent frames, full queues, forged and stale credentials, and checks that
no owned process, socket, relay or mount remains.

View file

@ -0,0 +1,55 @@
---
name: weft-compositor-input
description: Use for the Smithay compositor, Wayland protocols, surfaces, focus, geometry, input routing and the DRM and winit backends.
---
# Compositor, Wayland and input
Owner: `weft-compositor` owns surfaces, accepted geometry, focus, stacking, work
areas, input routing and presentation. Appd owns session identity; the shells
request and render. Read the blueprint's
[surface and window contract](../../../BLUEPRINT.md#72-surface-and-window-contract),
[input requirements](../../../BLUEPRINT.md#73-required-input-and-accessibility-behavior)
and [backend completion](../../../BLUEPRINT.md#74-backend-specific-completion).
## Where things live
| Concern | Source |
|---|---|
| Wayland globals and handlers (xdg-shell, layer-shell, DMA-BUF state, presentation) | [state.rs](../../../crates/weft-compositor/src/state.rs) |
| Keyboard, pointer and wheel routing | [input.rs](../../../crates/weft-compositor/src/input.rs) |
| `zweft-shell-unstable-v1` server side | [protocols/mod.rs](../../../crates/weft-compositor/src/protocols/mod.rs), [protocol XML](../../../protocol/weft-shell-unstable-v1.xml) |
| Appd association channel | [appd_ipc.rs](../../../crates/weft-compositor/src/appd_ipc.rs), [weft-ipc-types](../../../crates/weft-ipc-types/src/lib.rs) |
| Nested backend | [backend/winit.rs](../../../crates/weft-compositor/src/backend/winit.rs) |
| DRM/KMS, udev, libinput, session | [backend/drm.rs](../../../crates/weft-compositor/src/backend/drm.rs), [backend/drm_device.rs](../../../crates/weft-compositor/src/backend/drm_device.rs) |
## Working rules
- Verify Smithay behavior in the `smithay 0.7` source selected by `Cargo.lock`
(output frame submission, DMA-BUF global creation, seat and focus handling),
not in newer upstream examples. Advertise only globals the compositor actually
serves.
- Bind surfaces to sessions through trusted launch or connection evidence and
observed client identity, with opaque IDs and generations. A PID, title or
custom shell-protocol request is not authority. Only the trusted shell acquires
privileged roles such as `panel`.
- Effective xdg geometry and acknowledged configure state must agree; echoing a
`set_geometry` request does not move a surface.
- Prevent stuck keys and buttons after focus loss, client exit, drag
cancellation and output changes. Keep logical and physical coordinates
consistent across scale changes.
- DRM paths need the frame completion transition, presentation feedback,
idle and empty-frame scheduling that resumes on commits, session pause and
activation, and error recovery. Do not replace existing layer rendering on a
false premise.
## Evidence
`python .agents/scripts/verify.py portable linux` covers compilation, lints and
the protocol unit tests in `protocols/mod.rs`. It does not run a compositor.
Geometry, focus, stacking, input and presentation claims need a nested winit
session with real clients, and DRM claims need a DRM session on the declared
target; see [integration verification](../weft-integration-verification/SKILL.md).
The compositor and both shells generate their protocol code from the same XML,
so a protocol change affects all three; check them with the `linux` and
`servo-embed` profiles and keep the interface version deliberate.

View file

@ -0,0 +1,53 @@
---
name: weft-documentation
description: Use for WEFT OS public documentation, the blueprint, this contributor toolkit, issue and pull request templates and the verification runner.
---
# Documentation and the toolkit
[AGENTS.md](../../../AGENTS.md) is the only policy source. The
[blueprint](../../../BLUEPRINT.md) holds accepted direction. Public documentation
in [README.md](../../../README.md) and [docs/](../../../docs/architecture.md)
describes implemented behavior and must agree with source.
## Working rules
- Verify every command, path, feature, environment variable and API you document
against the current source, and run commands where practical. Keep blueprint
intent, implemented behavior and executed evidence distinct: "implemented",
"verified" and "planned" are different claims.
- Correct documentation that contradicts source instead of working around it;
for example, a pin file that disagrees with `Cargo.lock`, or a signing
description that differs from the implemented inventory.
- Link durable decisions and requirements to their owning artifact. Toolkit files
provide procedures and area knowledge, never a second policy, permissions,
schedules or an internal log.
- Write issues, pull requests, commits and release notes for maintainers: the
problem, the resulting behavior and the evidence. No attribution, trailers,
prompts or process narration.
- Keep Markdown portable: standard CommonMark links and tables, YAML front matter
with `name` and `description` only, no client-specific syntax required to
follow a procedure.
## Toolkit changes
Add area knowledge in a skill, repeatable steps in a command, review criteria in
a role and executable checks in `.agents/scripts/`. Update the
[catalog](../../README.md) for every new document. Then run:
```sh
pip install -r .agents/scripts/requirements.txt
python .agents/scripts/verify.py toolkit
```
That checks links, anchors, metadata, catalog coverage and issue forms, and runs
the runner tests. For runner changes, add tests for failure propagation,
unknown input, missing executables and execution from another directory. Review
the instructions manually against `AGENTS.md`, the blueprint and CI; passing
checks does not establish that the instructions are true.
Changes to the blueprint or contract are governance changes: follow the
[reviewed loop](../../../AGENTS.md#5-reviewed-change-loop), check every document
that links to the changed sections, and seek a
[decision](../../../AGENTS.md#9-decisions-and-authority) for a material change of
direction.

View file

@ -0,0 +1,54 @@
---
name: weft-integration-verification
description: Use for end-to-end and visual evidence in WEFT OS — real sessions, pixels and native input, failure injection, reliability runs and evidence records.
---
# Integration and visual verification
Integration evidence shows what unit tests cannot: real frames, native input,
real child processes, real components and an installed system. Read the
blueprint's [evidence levels](../../../BLUEPRINT.md#111-evidence-levels),
[verification profiles](../../../BLUEPRINT.md#112-verification-profiles),
[acceptance fixtures](../../../BLUEPRINT.md#113-required-acceptance-fixtures) and
[user journeys](../../../BLUEPRINT.md#22-required-user-journeys).
## Fixture design
- Choose the fixture before implementing. It must fail when the promised
behavior breaks and must not restate the implementation or only grep a success
log.
- For rendering, use a deterministic page with known color regions, text,
scrolling content, a text field, an interactive counter and a controlled
animation. Compare actual pixels read back after painting at the relevant
scales and sizes, including first frame, resize and idle wakeup.
- For input, drive the real native path on a running compositor: key press and
release, modifiers, declared US and Italian layouts with non-ASCII text,
buttons, motion, wheel, focus changes and scale changes. Check for stuck input
after focus loss and client exit.
- For lifecycle, inject failures at each startup phase and after `Running`:
missing binary, invalid package, renderer failure, runtime trap, crash,
cancellation and timeout. Assert a terminal reason and that no owned process,
socket, relay or mount remains.
- For data, use Notes with empty, non-ASCII, multi-line, quoted and literal
backslash text, delayed replies, failed writes and competing writers; repeat
after close, daemon restart, update and reboot.
- Counter and Notes are conformance applications: their happy paths are
necessary but insufficient.
## Running and recording
The [runner](../../scripts/verify.py) provides only build, lint, unit and
package checks. Integration fixtures run in the environment they claim: a nested
winit session for nested-desktop evidence, a DRM session on the declared target,
the booted reference image for installed behavior. Keep captures and logs under
ignored paths such as `target/`; commit fixtures, not their outputs.
Record for each run the commit, environment (host, compositor backend, GPU or
virtual device, Mesa, kernel), enabled features, exact command, observed result
and diagnostics. A screenshot shows pixels, not input routing or accessibility.
An unavailable display, GPU or VM leaves the gate incomplete; say which boundary
remained unverified.
Reliability qualification follows the blueprint targets: repeated clean boots,
launch and close cycles without orphans, mixed interactive and idle runs.
Performance and budget claims need measurements on the reference target.

View file

@ -0,0 +1,53 @@
---
name: weft-linux-deployment
description: Use for the Nix flake and reference VM, systemd units, native dependencies, installed paths, endpoints and service activation.
---
# Linux deployment
Owner: Linux and systemd own the seat, session substrate, service lifecycle and
process and resource boundaries. The installed closure must carry the real
feature-enabled product. Read the blueprint's
[release profile](../../../BLUEPRINT.md#21-required-release-profile),
[installed session](../../../BLUEPRINT.md#102-installed-session) and
[developer workflow](../../../BLUEPRINT.md#103-diagnostics-and-developer-workflow).
## Where things live
| Concern | Source |
|---|---|
| Flake, toolchain, dev shell | [flake.nix](../../../flake.nix), [flake.lock](../../../flake.lock) |
| Package derivations and features | [weft-packages.nix](../../../infra/nixos/weft-packages.nix) |
| VM configuration | [configuration.nix](../../../infra/nixos/configuration.nix) |
| VM build and run | [build.sh](../../../infra/vm/build.sh), [run.sh](../../../infra/vm/run.sh) |
| Service units | [infra/systemd](../../../infra/systemd/weft-appd.service) |
| Native build dependencies | [building.md](../../../docs/building.md), [CI](../../../.github/workflows/ci.yml) |
| Environment variables | [architecture.md](../../../docs/architecture.md) and the `std::env` reads in each crate |
## Working rules
- Keep one authoritative Nix and systemd configuration; make development units
and scripts consistent with it.
- The closure includes the feature-enabled binaries (`servo-embed` for both
shells, `wasmtime-runtime` for the runtime), the shell HTML and UI assets at
installed paths, reference packages with an explicit trust configuration, the
binary paths appd needs, and explicit activation and dependencies.
- Pass the real compositor display and daemon endpoints; never guess names such
as `wayland-1`. Keep persistent data and ephemeral runtime storage separate.
- Fill fixed-output hashes, including Servo's git `outputHashes`, from an actual
build, never by copying an unrelated value.
- Never fabricate `pkg-config` files or library versions to satisfy a build.
Repair the environment or exclude the feature explicitly. Do not commit
machine-specific usernames or checkout paths.
- Record the exact VM machine, graphics device, kernel, Mesa, CPU and memory
used for evidence. A headless VM or a successful evaluation is not graphical
acceptance.
## Evidence
The runner has no Nix or VM profile. Build with `bash infra/vm/build.sh` and run
with `bash infra/vm/run.sh` where Nix with flakes is available, and record the
environment. Installed-system claims need a fresh graphical boot that starts the
complete system without checkout paths or manual repair, plus persistence across
reboot and update. A missing Nix installation or virtualization support is
unavailable evidence.

View file

@ -0,0 +1,57 @@
---
name: weft-packages-data
description: Use for wapp.toml manifests, weft-pack, signing and trust, installation and updates, app data storage and EROFS dm-verity images.
---
# Packages, trust, data and updates
Owner: package tooling owns manifest validation, content identity, trust,
staging, activation and retention. User data has its own lifecycle and is never
owned by installed package bytes. Read the blueprint's
[packages, trust, storage and updates](../../../BLUEPRINT.md#9-packages-trust-storage-and-updates)
and [Notes requirements](../../../BLUEPRINT.md#82-notes).
## Where things live
| Concern | Source |
|---|---|
| `check`, `info`, `install`, `uninstall`, `list`, `generate-key`, `sign`, `verify`, `bundle`, `unbundle`, `build-image`, `build-verity` | [weft-pack](../../../crates/weft-pack/src/main.rs) |
| Manifests | [counter wapp.toml](../../../examples/org.weft.demo.counter/wapp.toml), [notes wapp.toml](../../../examples/org.weft.demo.notes/wapp.toml) |
| Demo signing fixture keys | [examples/keys](../../../examples/keys/weft-sign.pub) |
| Data and package roots used at launch | [appd runtime.rs](../../../crates/weft-appd/src/runtime.rs) |
| Image mount and privileged helper | [appd mount.rs](../../../crates/weft-appd/src/mount.rs), [weft-mount-helper](../../../crates/weft-mount-helper/src/main.rs) |
## Working rules
- The implemented signature covers the recursively enumerated package inventory,
including UI content and excluding the signature file, and both demo
signatures verify under it. Preserve that compatibility deliberately when
formalizing the format; do not re-sign demos to match a different description.
Correct documentation that describes a narrower inventory.
- Demo keys are fixtures and never production signing authority. Release
private keys stay outside the repository.
- Separate verified and development installation policies. Verified installs
fail closed on invalid, missing, revoked or untrusted signatures; development
installs are explicit and visibly marked.
- Validate IDs, entry containment, duplicates, link policy and the actual
component before trust decisions. Bind each app ID and its retained data to a
publisher key policy.
- Install and update through staging, validation, verification, immutable
content and atomic activation. Failure preserves the previous active revision
and user data; a live session stays pinned to its revision; uninstall keeps
data unless an explicit purge is requested.
- Migrating the existing `apps/<id>/data` layout needs detection, backup, conflict
handling and a test proving Notes contents survive. Keep it out of unrelated
cleanups.
- Verified image mode never falls back to a mutable directory, and the privileged
helper is enabled only after its caller authorization and failure paths are
specified and tested.
## Evidence
`python .agents/scripts/verify.py portable packages` runs the package unit tests
and checks and verifies the committed demo packages. Trust, install and update
claims need tamper, interruption, publisher-ownership, active-update and
uninstall fixtures from the blueprint's
[acceptance list](../../../BLUEPRINT.md#113-required-acceptance-fixtures), and
persistence claims need reruns after reinstall, restart and reboot.

View file

@ -0,0 +1,58 @@
---
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.

View file

@ -0,0 +1,72 @@
---
name: weft-servo-rendering
description: Use for the Servo embedders, painting and presentation, the Servo fork and Stylo overrides, the system UI and application pages.
---
# Servo rendering and the forks
Owners: `weft-servo-shell` renders trusted system chrome; `weft-app-shell`
renders one untrusted application document and its narrow bridge. Neither holds
session lifecycle. Read the blueprint's
[Servo host contract](../../../BLUEPRINT.md#71-servo-host-contract),
[system interface](../../../BLUEPRINT.md#8-system-interface-and-application-behavior)
and [build policy](../../../BLUEPRINT.md#101-one-reproducible-product-build).
## Where things live
| Concern | Source |
|---|---|
| System shell host and event loop | [weft-servo-shell embedder](../../../crates/weft-servo-shell/src/embedder.rs), [main.rs](../../../crates/weft-servo-shell/src/main.rs) |
| Application host, `resolve_weft_app_url` (app ID and `ui.entry` to a `file://` URL), injected bridge | [weft-app-shell embedder](../../../crates/weft-app-shell/src/embedder.rs), [main.rs](../../../crates/weft-app-shell/src/main.rs) |
| Key mapping | [servo-shell keyutils](../../../crates/weft-servo-shell/src/keyutils.rs), [app-shell keyutils](../../../crates/weft-app-shell/src/keyutils.rs) |
| Shell protocol clients | [servo-shell client](../../../crates/weft-servo-shell/src/shell_client.rs), [app-shell client](../../../crates/weft-app-shell/src/shell_client.rs) |
| System UI page and UI kit | [system-ui.html](../../../infra/shell/system-ui.html), [weft-ui-kit.js](../../../infra/shell/weft-ui-kit.js) |
| Pin notes (not authoritative for the selected revision) | [SERVO_PIN.md](../../../crates/weft-servo-shell/SERVO_PIN.md) |
## Selected revisions
The Servo and Stylo revisions are the ones `Cargo.lock` records for the `servo`
and `stylo` packages, not a branch name or `SERVO_PIN.md`. Servo comes from the
`marcoallegretti/servo` fork; Stylo currently comes from upstream `servo/stylo`,
because no root-level override selects the `marcoallegretti/stylo` fork. Inspect
them with:
```sh
grep -A2 'name = "servo"' Cargo.lock
grep -A2 'name = "stylo"' Cargo.lock
```
Read the `servo` crate (`components/servo`), shared embedder input types and
rendering contexts at that revision before using an API. Servo's own `[patch]`
tables do not apply to WEFT: a Stylo override that a Servo-fork feature depends
on must be declared in WEFT's root `Cargo.toml` and confirmed in the resolved
graph. Each fork patch keeps a purpose, upstream status and removal condition.
For cross-repository work, clone the forks next to WEFT and point Cargo at them
with local `[patch]` entries outside the repository. Those overrides rewrite
`Cargo.lock`; never commit that change, and rerun checks without the overrides
before reporting evidence for the committed graph.
## Working rules
- A frame exists only after `WebView::paint` and the backend's present
operation. Event-loop progress, a READY message or a softbuffer present of an
unpainted buffer is not a rendered frame. Readback follows painting.
- Handle zero-size and minimized windows, resize, output scale, first frame,
idle wakeup and shutdown without continuous unbounded repainting.
- Keep the trust distinction: system-control endpoints and credentials never
reach application documents. Policy for package resources, navigation,
downloads, file URLs and network requests is enforced in the engine or OS, not
in page JavaScript.
- Treat manifest names, descriptions and icons as untrusted in the launcher; no
unsafe HTML injection. Use one endpoint configuration and bridge.
- Extract common host, render and input code only after one working path exists
in both hosts.
## Evidence
`python .agents/scripts/verify.py servo-embed` type-checks both hosts with the
real renderer. Without `servo-embed` the shells build as stubs; their success is
not rendering evidence. Rendering, input and backdrop or transparency claims need
the deterministic page and pixel checks described in
[integration verification](../weft-integration-verification/SKILL.md).

63
.github/ISSUE_TEMPLATE/change.yml vendored Normal file
View file

@ -0,0 +1,63 @@
name: Defect or change
description: Report a concrete defect or propose an ordinary change within accepted architecture.
body:
- type: markdown
attributes:
value: |
Use a title that states the defect or the behavior that should hold. Search existing issues
and pull requests first. Use the Decision form for a material change of product direction,
public compatibility, trust boundaries, support scope or data policy.
- type: textarea
id: observed
attributes:
label: Observed
description: What happens now, and who or what is affected (user journey, caller, contract, test harness, contributor).
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected
description: What should hold instead. Cite the implemented contract or the BLUEPRINT.md section, and say which one applies.
validations:
required: true
- type: textarea
id: evidence
attributes:
label: Evidence
description: Commit, environment (host, compositor backend, GPU or VM), enabled features, exact reproduction steps and actual output, with file and line references.
validations:
required: true
- type: textarea
id: owner
attributes:
label: Owner and boundary
description: The owning component (compositor, servo-shell, app-shell, appd, runtime, package tooling, portal, deployment) and any public contract touched (wapp.toml, WIT, shell protocol, IPC types).
validations:
required: true
- type: textarea
id: impact
attributes:
label: Why it matters now
description: The concrete present impact. A hypothetical future need or a stylistic preference is not enough.
validations:
required: true
- type: textarea
id: acceptance
attributes:
label: Acceptance criterion
description: One independently checkable condition that resolves this issue. Keep unrelated work out of scope.
validations:
required: true
- type: textarea
id: proof
attributes:
label: Expected proof
description: The test, component or integration fixture, pixel check or measurement that fails today and will pass afterwards, and the environment it needs. Compilation and mocks do not prove rendering, input, isolation or persistence.
validations:
required: true
- type: textarea
id: scope
attributes:
label: Scope and related work
description: Related issues, pull requests or blueprint findings, and explicit non-goals.

5
.github/ISSUE_TEMPLATE/config.yml vendored Normal file
View file

@ -0,0 +1,5 @@
blank_issues_enabled: false
contact_links:
- name: Contribution guide
url: https://github.com/marcoallegretti/WEFT_OS/blob/main/CONTRIBUTING.md
about: Read the contribution workflow, ownership and validation guidance before opening an issue or pull request.

58
.github/ISSUE_TEMPLATE/decision.yml vendored Normal file
View file

@ -0,0 +1,58 @@
name: Decision
description: Request a maintainer decision on a material change of direction, compatibility, trust boundaries, support scope or data policy.
body:
- type: markdown
attributes:
value: |
This form requests a decision before implementation; opening it does not approve the change.
Ordinary implementation of an accepted BLUEPRINT.md boundary does not need this form.
Search existing decisions and issues first.
- type: textarea
id: observed
attributes:
label: Observed
description: The current problem and the concrete affected user, caller or contract.
validations:
required: true
- type: textarea
id: direction
attributes:
label: Accepted direction affected
description: The BLUEPRINT.md section, public contract or support promise this would change, and how.
validations:
required: true
- type: textarea
id: evidence
attributes:
label: Evidence
description: Commit, source references, executed checks and the selected dependency revisions that establish the problem. Separate verified facts from assumptions.
validations:
required: true
- type: textarea
id: alternatives
attributes:
label: Alternatives and trade-offs
description: Viable options including keeping the current direction, with their costs for ownership, security, data, compatibility and schedule.
validations:
required: true
- type: textarea
id: decision
attributes:
label: Decision requested
description: The specific decision needed and the work it unblocks. Independent authorized work continues meanwhile.
validations:
required: true
- type: textarea
id: acceptance
attributes:
label: Acceptance criterion
description: The independently evaluable outcome an accepted option must satisfy.
validations:
required: true
- type: textarea
id: proof
attributes:
label: Expected proof
description: The fixtures, measurements or integration evidence that will show the chosen option works.
validations:
required: true

58
.github/ISSUE_TEMPLATE/maintenance.yml vendored Normal file
View file

@ -0,0 +1,58 @@
name: Maintenance
description: Report one present ownership, boundary, enforcement or structural problem that is independent of active development.
body:
- type: markdown
attributes:
value: |
Search existing issues and pull requests for the same underlying problem first. Maintenance
preserves accepted behavior, public contracts and ownership; use the Decision form if
resolving the problem changes them. One problem maps to one branch and one pull request.
- type: textarea
id: observed
attributes:
label: Observed
description: One concrete problem (responsibility held by the wrong owner, authority taken from untrusted input, a grant declared but not enforced, a duplicated decision, unnecessary state, a misleading fallback, coupling or an obsolete path) and who or what it affects today.
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected
description: The intended structure and the behavior, contracts and ownership that must stay unchanged.
validations:
required: true
- type: textarea
id: evidence
attributes:
label: Evidence
description: Commit and file and line references that demonstrate the problem and its present cost.
validations:
required: true
- type: textarea
id: owner
attributes:
label: Owner and boundary
description: The owning component and why the problem can be resolved without a decision of direction.
validations:
required: true
- type: textarea
id: impact
attributes:
label: Why it matters now
description: The observable present cost. Generic cleanup wishes and speculative abstractions do not qualify.
validations:
required: true
- type: textarea
id: acceptance
attributes:
label: Acceptance criterion
description: One independently verifiable outcome.
validations:
required: true
- type: textarea
id: proof
attributes:
label: Expected proof
description: The checks or fixtures that show the problem is resolved and the accepted behavior is preserved.
validations:
required: true

29
.github/pull_request_template.md vendored Normal file
View file

@ -0,0 +1,29 @@
## Problem and scope
<!-- The concrete problem and its present impact. Link the issue (Closes #...) or the accepted scope. For a material change of direction, link the decision that approved it. -->
## What changed
<!-- The resulting behavior or structure, for a reader without access to your working notes. State relevant exclusions. -->
## Ownership
<!-- The owning component and the public contracts touched (wapp.toml, WIT, shell protocol, IPC types, package format). Explain how ownership and compatibility are preserved, or how an approved change keeps them coherent. -->
## What proves it
<!-- The test, component fixture, integration fixture, pixel check or measurement that fails without this change and passes with it. Explain any changed expectation, fixture or signature. Compilation and mocks do not prove rendering, native input, isolation or persistence. -->
## Validation performed
<!-- Actual commands and results, e.g. python .agents/scripts/verify.py portable linux. Name the environment for integration evidence (backend, GPU or virtual device, VM). List checks not run and why. -->
## Manual verification
<!-- What automation cannot establish, the environment and scenario used, and the observed result. If none is needed, say why automated evidence covers the scope. -->
## Limitations and related issues
<!-- Limitations that affect evaluation or use. Link separately actionable problems as issues; do not store future work here or leave a supported path knowingly incomplete. -->
<!-- Keep this text about the project problem, change and evidence. No model or provider attribution, co-author or generated-by trailers, reviewer counts or personas, prompts or process narration. -->

View file

@ -7,15 +7,9 @@ on:
pull_request: pull_request:
jobs: jobs:
# Crates that must compile on every supported host platform. # Crates that build without Wayland or other Linux system libraries.
cross-platform: portable:
runs-on: ${{ matrix.os }} runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
os:
- ubuntu-latest
- windows-latest
steps: steps:
- uses: actions/checkout@v4 - uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable - uses: dtolnay/rust-toolchain@stable
@ -24,14 +18,14 @@ jobs:
components: rustfmt, clippy components: rustfmt, clippy
- name: cargo fmt - name: cargo fmt
run: cargo fmt --all --check run: cargo fmt --all --check
- name: cargo clippy (cross-platform crates) - name: cargo clippy (portable crates)
run: > run: >
cargo clippy --workspace cargo clippy --workspace
--exclude weft-compositor --exclude weft-compositor
--exclude weft-servo-shell --exclude weft-servo-shell
--exclude weft-app-shell --exclude weft-app-shell
--all-targets -- -D warnings --all-targets -- -D warnings
- name: cargo test (cross-platform crates) - name: cargo test (portable crates)
run: > run: >
cargo test --workspace cargo test --workspace
--exclude weft-compositor --exclude weft-compositor
@ -133,3 +127,16 @@ jobs:
cargo check cargo check
-p weft-app-shell -p weft-app-shell
--features servo-embed --features servo-embed
# Contributor contract, toolkit documents and verification runner.
contributor-toolkit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- name: install toolkit check dependencies
run: python -m pip install -r .agents/scripts/requirements.txt
- name: check contributor toolkit
run: python .agents/scripts/verify.py toolkit

1
.gitignore vendored
View file

@ -1,4 +1,5 @@
/target/ /target/
__pycache__/
/.windsurf/ /.windsurf/
/docu_dev/ /docu_dev/

368
AGENTS.md Normal file
View file

@ -0,0 +1,368 @@
# WEFT OS engineering contract
This is the single engineering contract for everyone who changes WEFT OS:
maintainers and external contributors. It governs scope, evidence, review, validation, branches and publication.
[`.agents/`](.agents/README.md) contains linked procedures, review roles, area
knowledge and a verification runner. Those files help apply this contract. They
do not define competing policy, grant permissions, schedule work, change the
active working mode or add approval steps. Local tool configuration may point
here; it must not restate, weaken or reinterpret these rules.
## 1. Sources of truth
| Question | Authority |
|---|---|
| Accepted product direction, ownership, support scope and completion criteria | [BLUEPRINT.md](BLUEPRINT.md) |
| Implemented behavior | Source code and the checks that actually executed against it |
| Public contracts | Package manifests (`wapp.toml`), [WIT](crates/weft-runtime/wit/weft-app.wit), the [shell protocol](protocol/weft-shell-unstable-v1.xml), [IPC types](crates/weft-ipc-types/src/lib.rs) and the versioned specifications that replace them |
| Selected dependency APIs | [Cargo.lock](Cargo.lock) and the demo lockfiles, at the exact selected revisions |
| Engineering process | This file |
The blueprint describes where WEFT is going. It is not evidence that a behavior
exists. Code that resembles a blueprint requirement does not satisfy it until
the requirement's acceptance evidence passes. Existing documentation, pin files
and version labels cannot establish behavior on their own; where they disagree
with source or executed checks, the documentation is wrong and needs correcting.
Before changing a public contract, inspect existing compatibility promises and
callers. Preserve compatibility deliberately or provide a tested conversion or
error path.
When evidence contradicts the blueprint, preserve its intent, establish why the
discrepancy exists and choose the maintainable evidence-backed solution. A
material change of direction follows [section 9](#9-decisions-and-authority).
## 2. Evidence
Never invent an API, protocol behavior, platform guarantee, capability or
measurement. Verify uncertain assumptions against the selected dependency
revision before relying on them: read the source of the crate version recorded
in the lockfile (Servo, Stylo, Smithay, Wasmtime, wasmtime-wasi, Tokio, winit,
surfman and others), not current upstream documentation or memory. Record the
revision used when the result matters to the change.
Research order: repository contracts and evidence, selected dependency source,
upstream documentation for that version, relevant standards or protocols,
comparable mature implementations, then a measured experiment.
The blueprint's [evidence levels](BLUEPRINT.md#111-evidence-levels) define what
each kind of check can establish. In particular:
- Compilation, type-checking and clippy prove that code builds, not that it
renders, routes input, isolates, persists or recovers.
- Mocked sockets, DOMs, processes or compositors prove the logic exercised
against the mock, not the real boundary.
- A capability string in a manifest, a host function registration or a
frontend check does not prove enforcement.
- A success log line, `READY` message or exit code `0` from a feature-disabled
build does not prove readiness of the product path.
- A skipped check, missing environment or unavailable device is an incomplete
gate, never a pass.
Record the commit, environment, enabled features, exact command or harness,
result and useful diagnostics for evidence other contributors will rely on.
Distinguish tests that executed from tests that were only designed.
## 3. Ownership
Every change has an owner from the
[blueprint ownership table](BLUEPRINT.md#4-architecture-and-ownership). Identify
it before implementation. Do not let a component implicitly acquire
responsibility that belongs elsewhere:
- `weft-compositor` owns surfaces, geometry, focus, stacking, input routing and
presentation.
- `weft-appd` owns package selection, effective grants, session identity, child
supervision, readiness and cleanup.
- `weft-runtime` owns component instantiation and enforced host calls.
- `weft-servo-shell` and `weft-app-shell` render; they hold no second copy of
session lifecycle and no authority the session did not grant.
- Package tooling owns validation, content identity, trust, staging and
activation; it does not own user data.
Keep the UI and Wasm runtime in separate processes. Share code where behavior is
actually common, without merging privileges or failure domains. Do not replace
the compositor, browser engine or runtime as a shortcut around finishing their
contracts. Introduce a shared crate or abstraction only when it removes present
duplication or establishes a single source of truth.
## 4. Working modes
The modes below do not mix silently. Loading an `.agents/` file never switches
mode.
**Primary development** advances the blueprint under maintainer direction. A
goal may span many consecutive changes. At the start of a new goal, read the
blueprint and inspect the relevant source, manifests, tests, CI, lockfiles,
pins and Git state. Afterwards, reinspect the changed boundary and new evidence
for each step instead of repeating full discovery. Continue autonomously through
successive accepted changes while authorized independent work remains; do not
stop after a single patch or pull request. Fix related debt inside the active
acceptance criterion.
**Contribution** carries one issue or explicitly accepted scope through an
isolated branch to a pull request.
**Maintenance** handles exactly one qualifying problem that is unrelated to the
active goal, under [section 8](#8-maintenance). It never modifies the active
development checkout.
## 5. Reviewed change loop
Apply this loop to every workflow: primary development, fixes, simplification,
refactoring, dependency changes, build and packaging, documentation, governance
and release preparation.
1. **Inspect** current evidence and the implemented and accepted contract.
2. **State** the present problem, owner, bounded scope, observable acceptance
criterion and the proof that will show it.
3. **Review scope** — ownership, proof and design — before changing the affected
boundary.
4. **Implement** one coherent result, preserving unrelated work.
5. **Validate** with the smallest sufficient checks for the changed behavior and
its concrete risks.
6. **Review the actual diff** against acceptance, compatibility, security, data
and failure behavior.
7. **Correct** findings, revalidate and review the corrected content.
8. **Accept** an atomic result only when no blocking finding remains, then
**reassess** the next dependent step from the new repository state.
Do not stop after planning when implementation and verification are possible.
Do not advance dependent work while a blocking finding is open.
## 6. Proof before implementation
Identify what proves a change before or alongside implementing it. For a defect,
reproduce the failure first. For new behavior, establish the fixture, contract
case or invariant that will fail when the behavior is wrong. Proof must fail
when the promised behavior breaks; a test that restates the implementation or
only inspects a success log is not proof.
| Change | Expected proof |
|---|---|
| Parser, serialization, state machine | Unit or contract tests with accepting and rejecting cases |
| Host import or capability | Actual component fixture: allowed, denied and failure paths |
| IPC or session protocol | Integration test over the real transport: framing, authorization, limits, cancellation |
| Session lifecycle | Child-process fixtures for each start, failure, cancellation and teardown path, checking owned resources settle |
| Rendering or presentation | Deterministic page with known pixels on the supported backend; readback after paint |
| Input or window management | Native input and geometry on a real compositor backend |
| Filesystem confinement | Traversal, symlink and replacement-race cases against the real implementation |
| Package trust, install or update | Tamper, interruption and data-retention fixtures |
| Installed system | Built and booted reference image |
| Dependency change | Resolved graph inspection plus the checks of every affected boundary |
| Performance claim | Repeatable measurement on the named target |
| Documentation or toolkit | Claims checked against source; links, catalog and metadata checks |
A change without an identifiable proof surface is not ready unless the
limitation is intrinsic and stated in the result. Never update expected output,
re-sign fixtures or regenerate artifacts merely to turn a failing check green;
explain the contractual reason for every changed expectation.
## 7. Definition of done
A change is done when its contract is coherent and evidenced, not when it
compiles.
- No synthetic success: feature-disabled builds, stubs and fallbacks must not
report readiness, success or enforcement they do not provide.
- No silent no-ops for unsupported operations; fail explicitly with a useful
diagnostic.
- No product UI or documentation that promises unavailable behavior.
- No placeholder paths left knowingly incomplete in a supported product path.
- Security and data preservation are part of the first implementation, not a
later hardening stage.
- Accessibility, keyboard operation, scaling and declared keyboard layouts are
product requirements where the change touches them.
Prefer small explicit APIs, deletion over new abstraction and existing concepts
over new ones. Add a dependency only for concrete value.
## 8. Maintenance
Maintenance work never rides inside an unrelated development branch and never
switches or edits the active development checkout.
An issue is justified only when all of these hold: a concrete affected user,
caller, contract, test harness or contributor can be named; repository evidence
demonstrates the problem; it matters in the current state; and it has an
independently verifiable acceptance criterion. Stylistic preferences,
hypothetical future needs and generic cleanup wishes do not qualify. Search for
an existing issue or pull request first and update it instead of duplicating.
One maintenance run handles one qualifying problem:
1. Verify the current default branch (`main`) by fetching it. If freshness
cannot be verified, state the actual revision and the limitation.
2. Create one isolated worktree and one descriptive branch from it.
3. Follow the [reviewed loop](#5-reviewed-change-loop) to one reviewed pull
request, or to a prepared local result when publication is not authorized.
4. Stop. Do not continue collecting opportunities.
The maintenance roles in [`.agents/agents/`](.agents/README.md#roles) apply this
section:
- **Architecture debt scout** inspects and reports the strongest justified
issue. It edits no repository files and creates no implementation branches or
commits. It may prepare or publish that issue only within granted authority.
When nothing meets the threshold, it says so and stops.
- **Continuous simplicity** removes duplicated decisions, unnecessary state and
misleading fallback paths without changing accepted behavior.
- **Continuous refactoring** changes internal structure while preserving accepted
behavior, ownership and proof.
Neither simplification nor refactoring is a license for repeated architecture
replacement or line-count optimization at the expense of explicit authority,
errors or useful tests. If a maintenance change turns out to need a decision
under [section 9](#9-decisions-and-authority), stop it and record the decision
needed.
## 9. Decisions and authority
Make ordinary engineering decisions within accepted architecture without asking.
Decisions already accepted in the blueprint and authorization already granted
remain effective; do not request them again.
Seek a maintainer decision only for a material departure from accepted product
direction, public compatibility promises, trust boundaries, support scope or
destructive data policy, or when required authority is missing. Prepare the
problem, evidence, alternatives and trade-offs first, and continue independent
authorized work meanwhile. Do not disguise a change of direction as cleanup or
an implementation detail.
Publication, merge, release and deployment follow the authority actually
granted for them. A successful review, green CI or a passing hook grants none of
them by itself. Preserve branch protections, existing branches, other
contributors' work and unrelated working-tree changes.
## 10. Review
Review the actual change: a staged and unstaged diff, or an explicit
`git diff <base> <head>` range. An empty `git diff HEAD` after committing is not
a review of the committed change. Recheck material corrections, rebases and
conflict resolutions before integration, and review the final aggregate change
for cross-step effects before a pull request or release candidate.
Prefer a reviewer who did not author the change. When none is available, use a
fresh, separate critical pass and state that limitation honestly. Never present
self-review as independent review.
A **blocking** finding concerns correctness, promised behavior, trust, data
preservation, compatibility, accepted scope or required evidence. Fix it before
dependent work advances. An unrelated improvement goes to separately scoped
maintenance. Preferences are not blockers and findings are not a quota.
[Reviewer](.agents/agents/reviewer.md) describes the review procedure.
## 11. Validation
Run the smallest sufficient set for the change and expand it for a concrete
affected boundary, regression risk or release gate. Do not repeatedly run
unrelated expensive suites once the remaining risk is resolved, and never weaken,
skip or re-bless a required check to make it pass.
The [verification runner](.agents/scripts/verify.py) runs the repository's
actual check profiles; [verify](.agents/commands/verify.md) maps changes to
profiles and to evidence the runner cannot provide. [CI](.github/workflows/ci.yml)
remains the integration gate. Demo applications are separate workspaces; root
workspace tests do not cover them. Feature-disabled builds cannot stand in for
the `servo-embed` or `wasmtime-runtime` product paths.
## 12. Dependencies and forks
Servo is consumed from the `marcoallegretti/servo` fork (`servo-weft` branch).
Stylo currently resolves to upstream `servo/stylo`; the `marcoallegretti/stylo`
fork applies to WEFT only once a root-level override selects it and the resolved
graph confirms it. The selected revisions are those in `Cargo.lock`, not
`SERVO_PIN.md` or a branch name.
- Apply required Cargo overrides at the consuming workspace root. A dependency's
own `[patch]` table does not apply transitively. Inspect the resolved graph and
verify each claimed fix on the selected code.
- Keep a purpose, upstream status and removal condition for every retained fork
patch.
- Local path overrides used for cross-repository development change the resolved
graph. Do not commit the lockfile changes they cause and do not present
results from them as evidence for the committed graph.
- A dependency update needs scope, compatibility evidence, relevant security
review and the same reviewed loop as product code.
- Never fabricate `pkg-config` metadata, native library versions or readiness
messages to make a build pass. Repair the supported environment or exclude
the unsupported feature explicitly.
- Do not copy machine-specific usernames or checkout paths into documented
workflows.
## 13. Versions and releases
Follow the blueprint's [version progression](BLUEPRINT.md#121-version-progression):
scoped `0.0.x` releases toward stable `0.1.0`, each moving through
`alpha.N -> beta.N -> rc.N -> final`, where final is the plain version without
a `-final` suffix. Assign the next `0.0.x` to an accepted
milestone scope after inspecting existing tags and published releases. Reconcile
the unreleased workspace value `0.1.0` deliberately.
Promotion is an explicit evidence-based decision under release authority. No
label, test count, absence of bug reports or successful build promotes a
candidate automatically. A release candidate requires the complete evidence for
its scope and an independent technical review of that exact candidate; an
unavailable required reviewer leaves the gate pending. Corrections after
candidate approval invalidate the affected evidence. Never rewrite or move
published tags or releases. Publish the artifact that was tested.
## 14. Branches, commits and publication
Branch from the verified current `main` unless the work depends on another
unmerged branch; then say so. Name every branch after the concrete change,
with a type prefix:
```text
fix/authorize-session-messages
refactor/share-servo-frame-loop
feat/keyboard-app-switching
build/enable-servo-vm-packages
test/reject-portal-symlink-escapes
docs/add-weft-contribution-contract
```
Reject task numbers, lane, phase or role labels, model or provider names and
generic names such as `maintenance`, `stability` or `cleanup`. Link the issue
from the pull request instead of naming the branch after it.
Commits are atomic, focused and revertible. Before committing, inspect
`git status` and the complete diff, and confirm no generated, transient or
local-environment files are included. Keep subjects short and technical; add a
body when it explains the problem, resulting behavior or evidence.
Branch names, commit messages, issues, pull requests, review comments and
release notes are written for maintainers: the concrete problem, the resulting
behavior, the affected boundaries and the validation actually performed. Do not
include model or provider attribution, co-author or generated-by trailers,
reviewer counts or personas, prompts, internal role handoffs or process
narration. A technical validation section with real commands and results is
useful.
Reusable governance files, the adopted blueprint and protocol or product
documentation are intentional tracked artifacts. Temporary plans, transcripts,
review notes, scratch output and internal progress reports stay out of Git.
A decision that exists only in a conversation does not exist for the project:
record durable decisions in the owning public artifact.
Before an action that can trigger automated public review or publication,
inspect the repository's integrations. Do not knowingly trigger publication that
conflicts with this section or bypass a required protection to avoid it.
## 15. Code
Follow the workspace configuration: edition 2024, the pinned toolchain in
[`rust-toolchain.toml`](rust-toolchain.toml) and `unsafe_code = "forbid"` where
crates inherit workspace lints. Keep `cargo fmt` and `clippy -D warnings`
clean. Do not silence a diagnostic without understanding its cause.
Product, helper and privileged subprocesses use exact executable paths and
argument arrays. Bound queues, frames, payloads and operation lifetimes. Keep
secrets, application payloads, clipboard contents and saved user data out of
default logs.
Prefer self-explanatory names and structure. Comment non-obvious invariants,
protocol constraints and safety reasoning; avoid narrative comments. Remove dead
code instead of commenting it out.

657
BLUEPRINT.md Normal file
View file

@ -0,0 +1,657 @@
# WEFT OS — Stability Blueprint
**Target:** a usable, supportable `0.1.0` Linux desktop and application environment.
**Baseline inspected:** WEFT `b99cc73a4704615521c38ca84dc46dc1bd641bc6` (`main`, 13 March 2026).
**Contributor reference inspected:** Resina Design System `1e768064f57a1e403ab271822383e732795905a6` (`master`, 8 October 2026).
**Prepared:** 8 October 2026.
**Status:** source-verified development specification. The requirements below are the proposed completion contract; they are not a certification that the current implementation satisfies them.
## 1. Purpose and authority
WEFT is a Linux desktop in which Servo renders the system interface and application interfaces, Smithay manages Wayland presentation and input, Wasmtime executes application components, and `weft-appd` supervises their sessions. Applications combine a web interface with a separate Wasm component. A package manifest declares their identity, entries and requested host capabilities. This blueprint preserves that product model and completes its missing boundaries. [Existing architecture][architecture] [Workspace][workspace]
The intended user outcome is concrete: boot into the desktop, discover installed applications, launch and use them, switch and close them, preserve their data, install updates, and recover from a failed application without losing control of the desktop.
When this blueprint is adopted:
- `AGENTS.md` is the single engineering policy. It governs scope, validation, review, contribution and publication.
- This blueprint defines the accepted product direction, ownership, support scope and completion criteria.
- Versioned manifest, IPC, WIT and packaging specifications define public contracts. Existing compatibility promises must be inspected before changing them; this document does not silently erase them.
- Source and executed checks establish implemented behavior. Documentation and version labels cannot establish behavior independently.
- `.agents/` provides linked procedures and area knowledge. Reading a guide does not change the active task, grant authority, schedule maintenance or introduce a new approval requirement.
Reconcile any earlier local blueprint before implementation. Historical repository documentation referred to `docu_dev/WEFT-OS-COMPREHENSIVE-BLUEPRINT.md`, but its contents were not available in the inspected tracked tree. Do not claim to have incorporated unseen requirements. Preserve compatible decisions, identify material contradictions and prepare a concrete decision only where the accepted direction actually changes. [Historical baseline][historical-baseline]
This is durable product documentation and can be tracked in the repository when adopted. Temporary investigation notes, execution transcripts, review scratch files and progress reports are not product documentation.
## 2. Meaning of stable
### 2.1 Required release profile
Stable `0.1.0` means the complete supported path works on a named reference environment. It does not imply compatibility with every architecture, GPU, Linux distribution or checked-in backend.
| Profile | Status required for `0.1.0` | Scope |
|---|---|---|
| Linux `x86_64` nested session | Required | Real Smithay winit backend, both Servo hosts, Wasmtime, package tooling, session supervisor and reference applications |
| Bootable Linux `x86_64` reference VM | Required | Pinned Nix image, systemd session startup, graphical shell, real application execution, persistent storage, shutdown/reboot and recovery |
| Reference VM graphics | Required | One recorded QEMU/KVM configuration, virtual GPU, renderer path and host requirements; exercise DRM if the image uses it |
| Physical devices | Conditional | Support only devices and configurations present in the executed support matrix |
| Additional CPU architectures or host operating systems | Conditional | Utility compilation alone does not establish desktop support |
| EROFS/dm-verity packages | Conditional | May be supported only after the complete image, identity, privilege and failure-path contract in section 9 passes |
Choose the exact VM machine, graphics device, kernel/Mesa, CPU and memory settings during environment recovery and record them. QEMU with virtio-gpu is a candidate to evaluate, not a compatibility result established by this audit. A headless VM or successful Nix evaluation cannot satisfy graphical acceptance.
During environment recovery, boot a minimal instance of the intended reference VM and present a real compositor diagnostic surface. This checks the selected graphics/seat path early; full installed-product acceptance remains the later reference-image milestone. Continue independent nested fixes while arranging this target check.
The mandatory initial application model is one primary window per session, with explicitly supported dialogs and popups. Closing that primary application window terminates its session. Background execution needs a separate accepted contract and must not emerge from an unobserved runtime process.
Keyboard, mouse, wheel, app switching, resizing, focus and text editing are required. Validate declared US and Italian keyboard configurations. Touch, stylus, complex IME workflows, multi-monitor arrangements, native assistive-technology integration and advanced GPU APIs must not be advertised without corresponding complete fixtures. Features outside the supported profile must be visibly unavailable or clearly documented; they must not silently succeed.
### 2.2 Required user journeys
1. A fresh reference image boots into a usable system interface without terminal repairs or development checkout paths.
2. The launcher lists actual installed packages and exposes truthful launching, running, failed and stopped states.
3. Counter changes state through its real Wasm component and returns that state to its rendered interface.
4. Notes preserves exact text through save, close, reopen, daemon restart, package update and VM reboot.
5. Two applications run together, switch through keyboard and shell controls, receive correct input, and close independently.
6. A failed runtime, renderer, startup or package update produces an actionable error and converges to a recoverable state.
7. Undeclared host operations and forged session messages are denied at the host boundary.
8. A documented developer workflow builds, validates, installs, launches, diagnoses, updates and removes a real application package.
Counter and Notes are conformance applications. Passing their happy paths is necessary but insufficient: permission denial, malformed input, update interruption, process failure and graphical recovery are separate release gates.
## 3. Evidence and current baseline
### 3.1 What was verified
The audit inspected the tracked workspace, demos, manifests, WIT, dependency lockfile, graphics hosts, supervisor, package tools, service/Nix definitions and available CI metadata. The Resina contributor contract and complete `.agents/` tree were inspected at the reference revision above.
Additional bounded checks executed outside the Rust product build:
- The actual injected JavaScript bridge was exercised in Node with a mocked WebSocket; its messages were compared with the daemon's declared request/response shapes.
- The actual Notes frontend was exercised with a mocked DOM and controlled replies, reproducing stale-response replacement of newer edits.
- Both committed demo signatures were verified with Python's Ed25519 implementation against the canonical inventory algorithm in `weft-pack`: both were valid, covering nine files each.
- Temporary filesystem probes demonstrated the symlink behavior and package/data coupling relevant to the inspected path logic. These were source-directed probes, not execution of the Rust portal or installer.
- The current `systemd-run --user --scope --wait ... -- /usr/bin/true` argument combination was rejected with `--wait may not be combined with --scope`. No application service was launched by that check.
The execution environment did not contain Cargo, rustc or Nix. No full Rust compilation, real Servo window, running Wasm application session, DRM session or reference VM was executed during this audit. Those checks remain mandatory work. Passing observations below must not be broadened into unexecuted runtime claims.
### 3.2 Findings that determine the implementation order
| ID | Observed baseline | Consequence and required response |
|---|---|---|
| E01 | The selected Servo revision differs from `SERVO_PIN.md`; both embedders use APIs absent or changed in that revision. [Lockfile][lockfile] [Pin document][servo-pin] [App embedder][app-embedder] [Selected input API][servo-input] [Selected render API][servo-render] | Recover one reproducible dependency graph and compile both real embedding configurations before relying on graphics claims. |
| E02 | Both host frame paths omit `WebView.paint`; the EGL path has no actual presentation. [System embedder][system-embedder] [App embedder][app-embedder] [Servo rendering contract][servo-webview] | Implement paint and present, then verify pixels, wakeups, resize and idle recovery. |
| E03 | The workspace does not apply Servo's dependency-level Stylo patch; the selected upstream property remains gated. [Workspace][workspace] [Lockfile][lockfile] [Servo patch][servo-patch] [Stylo gate][stylo-gate] | Put necessary overrides at the workspace root and verify the selected graph and rendered feature. Parsing or a pin document is insufficient. |
| E04 | Without the runtime feature, `weft-runtime` prints readiness and exits; the feature-disabled app shell prints readiness and parks. The system shell instead reports its missing feature. Nix shell builds omit `servo-embed`. [Runtime][runtime] [App host][app-main] [System host][system-main] [Nix packages][nix-packages] | Separate limited build fixtures from product binaries. Ship and test actual engines; no synthetic success path may satisfy readiness. |
| E05 | The systemd launch path combines `--scope` and `--wait`. [Session implementation][appd-runtime] | Replace it with a valid, tested ownership mechanism that includes all session processes. |
| E06 | The UI bridge sends bare payloads, while the daemon expects tagged requests; replies are also differently wrapped. WebSocket clients enter the common dispatcher and receive common broadcasts without a session-specific authenticated binding. [Bridge][app-embedder] [Daemon messages][appd-ipc] [WebSocket server][appd-ws] | Define a single semantic protocol, separate system control from app messaging, and authorize each connection before repairing demo interaction. |
| E07 | Host imports are registered without applying effective per-session grants. Read-only and writable preopens converge to unrestricted directory/file permissions. The portal checks lexical prefixes before following paths. [Runtime][runtime] [Session preopens][appd-runtime] [Portal][file-portal] | Enforce capabilities at every host entry, preserve access modes and use filesystem confinement that survives symlinks and races. |
| E08 | Appd marks a session running before UI readiness; UI spawn/exit and several early failures do not share complete cleanup. IPC paths contain stale relay and lock/cancellation risks. [Session implementation][appd-runtime] [Daemon lifecycle][appd-main] | Give the session one owner, readiness contract and cleanup path; test every child failure and fragmented/cancelled transport. |
| E09 | Pending PID associations are not consumed; focus/destroy requests only log; toplevels start at the same position; custom geometry requests do not establish effective placement. [Compositor association][compositor-appd] [Compositor state][compositor-state] | Implement authenticated session/surface association and compositor-owned focus, geometry, stacking and destruction. |
| E10 | DRM submission lacks the completion transition, idle/empty-frame scheduling is incomplete, activation only logs, and the DMA-BUF global is not created. Layer rendering exists; layer input hit-testing is incomplete. [DRM backend][drm] [State][compositor-state] [Input][compositor-input] | Complete the selected backend's presentation, recovery and input contract; do not replace already existing layer rendering on a false premise. |
| E11 | Default app data lives under the installed package directory; installation rejects an existing package and removal deletes that tree. [Session data paths][appd-runtime] [Package operations][pack] | Separate user data before an update workflow. Never require uninstalling the old package to update it. |
| E12 | Signing covers the recursively enumerated inventory, including UI assets, while documentation describes only manifest plus Wasm. Installation does not establish trust by invoking signature verification. Both committed signatures are valid under the implemented inventory algorithm. [Package signing/install][pack] [Existing security documentation][security] | Preserve the working cryptographic behavior, define trust policy and enforce it transactionally. Correct the documentation; do not “repair” valid signatures by signing the wrong content. |
| E13 | Image builder and loader disagree on companion filenames; mount failure can fall back to a mutable directory; runtime, UI and capability resolution can use different roots. [Image builder][pack] [Mount loader][mount] [Session resolver][appd-runtime] | Resolve one verified package descriptor and make verified-mode failures fail closed. |
| E14 | Manifest entry paths lack complete confinement, Wasm checking is only a magic-prefix check, and runtime loading ignores the declared module entry. Installation writes directly into its final destination. [Package validation][pack] [Runtime entry][runtime] | Use shared manifest/entry validation, component validation and recoverable staging before activation. |
| E15 | Notes can overwrite newer editor content with a late reply and transforms literal backslash sequences. [Notes UI][notes-ui] [Notes component][notes-runtime] | Use structured serialization, revision-aware replies and atomic persistence with an explicit concurrent-writer policy. |
| E16 | Nix/session configuration omits required features/assets or launch configuration, guesses a Wayland display, and disables VM graphics. [Nix packages][nix-packages] [Nix configuration][nix-config] [Flake][flake] [Service units][services] | Produce and exercise one coherent installed image, with real assets, endpoints and activation. |
At the inspected HEAD, the available GitHub run metadata reported successful portable Ubuntu/Windows jobs and failed Linux-only/Servo jobs. The old detailed logs were unavailable; the audit does not assign a historical CI failure to a particular finding above. Re-run the exact relevant configurations to establish current results. [Recorded CI run][ci-run]
The manifest already declares `0.1.0`; the inspected checkout contained no tags and the release listing was empty. A manifest number is not release qualification. Inventory current remote refs and published artifacts again before assigning versions. [Workspace version][workspace] [Releases][releases]
### 3.3 Questions requiring execution, not assumptions
- Demo components and host WASI dependencies show different WIT patch versions (`0.2.6` and `0.2.3`); Wasmtime's linker has compatible-version behavior. A textual version difference alone does not establish an ABI defect. Instantiate actual components and exercise imports. [Wasmtime linker][wasmtime-linker]
- Validate the fetch response shape against an actual component. Do not report an ABI mismatch from a Rust tuple versus WIT record appearance alone.
- Clipboard and notifications call real external helpers; they are not logging stubs. Their services, permission enforcement and behavior still need integration evidence. [Runtime host functions][runtime]
- The mount helper contains a privileged execution path, but the inspected Nix image does not establish a functioning setuid deployment. Review and test privilege before enabling it; do not describe a hypothetical deployed privilege escalation as an observed VM exploit. [Mount helper][mount-helper] [Nix packages][nix-packages]
- No performance, battery, hardware compatibility or accessibility-service result was established by the audit.
## 4. Architecture and ownership
| Owner | Authoritative responsibility | Must not own implicitly |
|---|---|---|
| Linux and systemd | Seat/session substrate, service lifecycle and enforced process/resource boundaries | Product session identity inferred from arbitrary child output |
| `weft-compositor` | Surface ownership, geometry, focus, stacking, work areas, input routing and presentation | Application data, package trust or unvalidated shell privilege |
| `weft-servo-shell` | System chrome, launcher, navigation and user-visible session controls | A second authoritative copy of app/session lifecycle |
| `weft-appd` | Resolved package selection, grants, session identity, child supervision, readiness and cleanup | Unbounded global application broadcasts or frontend-supplied authority |
| `weft-runtime` | Component instantiation, WIT host calls and enforced WASI resource access | Package selection independent of appd or unrestricted ambient imports |
| `weft-app-shell` | One application's document, rendering and narrow session bridge | System-control credentials, another app's data or privileged shell roles |
| Package tooling/store | Manifest validation, content identity, trust, staging, activation and retention | User data lifecycle coupled to installed bytes |
| Portals/host services | Operations on explicitly granted resources | A second, weaker permission model |
Keep the UI and Wasm runtime in separate processes. Share code where behavior is actually common, without merging their privileges or failure domains. Do not replace the compositor or browser engine as a shortcut around finishing their contracts.
### 4.1 One resolved package descriptor
Before spawning children, appd must resolve and validate one immutable launch descriptor:
| Field | Required meaning |
|---|---|
| Package identity | Validated application ID, package version and immutable content identity |
| Package root | Exact validated root of that selected revision |
| Runtime entry | Contained, validated `[runtime].module` |
| UI entry | Contained, validated `[ui].entry` from the same revision |
| Effective grants | Manifest requests intersected with explicit host/user policy |
| Data root | Persistent application storage independent of package bytes |
| Session identity | Opaque session ID plus generation/epoch sufficient to reject stale references |
| Owned resources | Supervisor-controlled handles/endpoints required by the chosen launch path |
Runtime, app shell, portals and compositor registration must derive from this descriptor. Do not independently rediscover package roots, parse a different manifest or infer identity from a title/PID. An active session remains pinned to its selected revision across package updates.
Implement one manifest parser and resolution contract at the narrow shared boundary where required. A new shared crate is justified only when it removes actual duplication; the crate structure itself is not a release goal.
### 4.2 Manifest and component compatibility
Specify schema version, identifier rules, required entries, supported capability syntax and unknown-field/version behavior. Preserve existing manifest compatibility deliberately or provide a tested conversion/error path. Validate entry containment, file kinds, link policy and package identity before execution.
Validate an actual WebAssembly component and the required world/imports/exports using the selected toolchain; four magic bytes do not establish compatibility. Maintain one canonical WIT source and generated bindings or a checked synchronization mechanism. Each supported host import needs an actual component fixture proving its ABI, allowed behavior, denial and error handling.
## 5. Security and capability contract
### 5.1 Threat model
Treat both packaged web content and the Wasm component as untrusted application code. They must not read another app's data, obtain undeclared host operations, issue system lifecycle commands, impersonate another session or assign themselves privileged surface roles.
Treat the compositor, supervisor, installed package resolver, host policy and trusted system shell as the control boundary. Bootstrap authority must come from a trusted channel and observed peer identity, not from application-provided metadata.
The initial product does not promise protection from an arbitrary hostile native process already running as the same host user or an administrator who modifies the installation. State that scope explicitly. It does not excuse unsafe privileged helpers, application-facing host APIs or package code escaping the declared resource boundary. Do not claim that separate processes or a syscall blocklist alone provide complete confinement.
The renderer must obey the same declared authority as its component. Define policy for package resources, external navigation, downloads, local file URLs, network requests and subprocess/service access. Enforcement must exist at the engine or operating-system boundary; frontend JavaScript checks are insufficient. If the selected Servo build cannot enforce a required boundary, complete an effective containment mechanism or narrow the supported content policy through an explicit product decision before release. Do not advertise a sandbox that has only been implemented on the Wasm side.
### 5.2 Effective grants
The default is no application access beyond the documented minimal execution resources. The supervisor derives effective grants once, and each host operation checks them. Unknown or unsupported capability requests fail clearly. Installing a signature-valid package does not automatically approve all its permissions.
| Resource | Required behavior |
|---|---|
| Package content | Read-only access to the selected revision; no package path outside it |
| Private app data | App-specific root; read and read/write remain distinct |
| User-selected directories | Actual platform directory resolution and explicit grant; no guessed home subdirectory treated as authority |
| File portal | Same mode/path policy as WASI; operations confined against traversal, symlinks and races |
| Fetch | Explicit supported schemes, destinations/ports, methods and budgets; authorize redirect destinations and define credential forwarding |
| Clipboard | Separate read/write grants, usable platform service, bounded payloads and meaningful errors |
| Notifications | Individual grant, actual delivery path, bounded content and actionable failure |
Filesystem confinement must use descriptor-relative or equivalent kernel-supported operations that enforce the policy during the operation. `canonicalize()` followed by reopening an attacker-controlled path is not sufficient against replacement races. Cover intermediate and final symlinks, `..`, nonexistent write targets and links changed during access. Apply the same constraints to installation, extraction and manifest entry resolution.
Fetch must have explicit connect/overall deadlines, request and response limits, and cancellation behavior. Handle each redirected destination under the grant. Keep HTTP error statuses distinct from transport errors. If domain grants are supported, specify normalization, subdomain matching, ports and the treatment of resolved local/private destinations rather than leaving those decisions to the HTTP library.
No host import, including a convenience helper, may bypass the effective policy. Every compiled and advertised import belongs in the conformance matrix; absent support must not be represented as a successful no-op.
### 5.3 Resource and privilege limits
Apply session ownership and resource limits to the runtime, renderer and helpers together. Bound memory, active processes, queued messages/bytes, in-flight requests, logs, host response sizes and operation lifetimes. Use finite configurable defaults and measure them on the reference target; freeze release budgets before beta. Do not invent measured performance claims.
Before enabling a privileged helper, specify its caller authorization, allowable package identifiers, trusted store roots, output locations, command paths and environment. Use exact executable paths and argument arrays. Reject arbitrary caller-controlled mount sources/destinations. Apply appropriate read-only, `nodev` and `nosuid` policies and prove cleanup after every failure. Privilege must not be enabled merely to bypass a failing development configuration.
## 6. IPC and session lifecycle
### 6.1 Role-separated protocol
System control and application messaging must have separate authority, even if a transport implementation is shared.
| Connection | Authority |
|---|---|
| Trusted system shell/administrative client | Authorized catalog, lifecycle and window operations |
| Application bridge/runtime | Only the operations and private messages of its own authenticated session |
| Diagnostic client | Only the explicitly granted diagnostic/control subset |
Bind role, session and generation on the server. A caller-provided `session_id` is a routing claim, not authentication. Never deliver private payloads to unrelated subscribers. Do not expose a system-control secret inside application content.
Use private local endpoints with appropriate ownership and permissions. A browser-facing WebSocket requires an authenticated session bootstrap with expiry, replay handling and termination behavior. Loopback binding and Origin validation are additional controls; neither substitutes for authorization. Keep credentials out of logs and unintended URLs/referrers, and ensure a reconnect cannot acquire a different session.
Define a versioned semantic envelope with message kind, request correlation, payload, result/error and session generation as appropriate. Native framing and browser serialization may differ, but the bridge and daemon must share these meanings. Publish real request/response examples from the tested contract. App content should use a small bridge API, without rebuilding daemon envelopes or receiving administration messages.
Bound frame size, queued message count, queued bytes and per-connection concurrency. Preserve partial frames across cancellation. Do not hold the session registry lock while awaiting socket/channel work or reacquire it through an error branch. Closed relays must be removed. Detect overflow or missed events and resynchronize from an authoritative snapshot; do not continue with silently stale state. Tokio specifically documents cancellation concerns for `read_line`; choose a framing primitive or buffered decoder with the required behavior. [Tokio I/O contract][tokio-lines]
### 6.2 Single lifecycle owner
Use one session model, with structured terminal reasons:
```mermaid
stateDiagram-v2
[*] --> Starting
Starting --> Running: Required readiness reached
Starting --> Stopping: Failure, timeout or cancellation
Running --> Stopping: Close, exit, crash or shutdown
Stopping --> Stopped: All resources settled
Stopped --> [*]
```
`Running` means the component is initialized, session IPC is connected, the application document and bridge are initialized, and the associated surface has reached the defined first-frame presentation condition. A minimized or temporarily occluded session can remain running; initial readiness and ongoing visibility are different facts.
Readiness must use trusted host signaling. The component's `notify.ready` is one input to the host lifecycle, not authority to bypass UI readiness. Arbitrary stdout text cannot establish readiness. Drain stdout/stderr from process creation onward, independently of lifecycle signals.
Authenticated session bootstrap and the narrowly defined initialization exchange must be permitted while `Starting`. Specify which messages are legal in each lifecycle state. Do not require `Running` to complete an exchange that is itself necessary for readiness. Bound startup traffic and apply the same grants, session binding and cleanup rules as during normal execution.
A user close request must allow the application's declared unsaved-change policy to complete before primary-surface destruction and session teardown. Define cancellation and a bounded response timeout. Once close is accepted, settle the entire session. Explicit force termination, crashes and system-session shutdown have separate documented policies and must not be reported as a successful save. This interaction precedes `Running -> Stopping`; it does not require another independent lifecycle model.
A session owns both children, portal/helper processes, relays, sockets, compositor associations, temporary directories and optional mounts. Every exit path enters the same cleanup mechanism: spawn failure, malformed package, initialization failure, timeout, cancellation, guest trap, child crash, explicit close and daemon shutdown. Do not let renderer failure leave an apparently running invisible application.
Use a valid process-group or systemd mechanism that preserves that ownership. Attempt graceful termination for a bounded interval, then terminate remaining owned processes and await settlement. Do not sleep for an arbitrary duration and assume cleanup finished. Test direct and systemd paths only if both are supported; otherwise remove the unsupported path from product promises.
On daemon failure, use durable/OS-backed ownership to reconcile or terminate owned stale sessions. Do not infer ownership from a recycled PID, a matching directory prefix or an untrusted client claim. The initial policy may restart applications explicitly after cleanup; it does not promise restoration of arbitrary in-memory application state. Prevent restart loops and retain useful terminal reasons.
## 7. Rendering, windowing and input
### 7.1 Servo host contract
Recover the exact selected API first. Implement frame notification, repaint scheduling, `WebView.paint`, backend presentation and meaningful error handling. Event-loop progress alone is not a rendered frame. Readback must follow painting, and EGL requires a real present operation. [Selected Servo contract][servo-webview] [Rendering context][servo-render]
Handle zero-size/minimized windows, resize, output scale, logical/physical coordinates, graphics context lifetime, first frame, waking from idle and shutdown. Keep reusable rendering resources alive where required. Do not hide missing wakeups with continuous unbounded repainting.
Use a deterministic page with known color regions, text, scrolling content, a text field, an interactive counter and controlled animation. Check actual pixels and input results on the supported path. For transparency/backdrop effects, verify the selected dependency graph and rendered behavior; unsupported effects need an honest usable fallback in the UI.
After one working path exists, extract demonstrated common host/render/input behavior from the two embedders. Preserve the distinction between trusted system chrome and an untrusted application document. Do not build a generic engine abstraction without a present requirement.
### 7.2 Surface and window contract
The compositor owns accepted geometry, stacking, focus and work areas. Appd owns session identity. The shell issues requests and renders the resulting state. Bind surfaces through trusted launch/connection evidence and observed client identity, with opaque window/session IDs and generations. PID alone is not durable authority.
Support creation, activation, move/resize under the selected window policy, maximize/restore, close, child dialogs/popups and destruction. Effective Wayland geometry and acknowledged state must agree. Define one coherent relationship with xdg configure/acknowledgement; an echoed custom geometry request does not move a surface.
Establish painting and hit-testing order for background, application work area, panel/navigation, overlays and popups. Define input regions, reserved work areas, parentage, dismissal and focus restoration. Only the trusted shell can acquire privileged roles. A normal opaque toplevel labelled `panel` cannot substitute for that behavior.
A multi-surface shell hosted by one trusted Servo process is a reasonable implementation. A single-document implementation is also acceptable if it proves correct clipping, transparency, ordering and input regions. Choose once based on the selected APIs and a working fixture; keep product ownership unchanged.
### 7.3 Required input and accessibility behavior
Forward key press/release, modifiers, mouse buttons, motion, enter/leave, wheel, focus changes and scale changes correctly. Preserve physical/logical coordinate consistency. Prevent stuck keys/buttons after focus loss, client exit, drag cancellation or output changes. Verify declared keyboard layouts and non-ASCII editing through the real native path.
The system UI requires semantic controls, accessible names, logical keyboard order, visible focus, no keyboard traps, Escape/dismiss behavior and focus return for overlays. Verify theme contrast and reduced-motion behavior. Native screen-reader/AT-SPI support requires an actual accessibility inspector and assistive-technology test with the selected engine; a dependency name or DOM attribute does not establish platform integration.
### 7.4 Backend-specific completion
For the nested backend, verify real surfaces, resizing, input, focus, idle wakeups and application failure recovery. For every release path using DRM, additionally implement and test:
- Completion of queued frames, including the required `frame_submitted()` transition.
- Synchronization and presentation feedback tied to successful presentation.
- Empty-frame and idle scheduling that resumes on input/content commits.
- Render/submission error recovery.
- Session pause and activation.
- The declared output add/remove and mode-change behavior.
- Cursor and DMA-BUF mechanisms actually advertised to clients.
Use the selected Smithay contracts; unsupported globals must not be advertised. [Smithay output contract][smithay-output] [DMA-BUF global contract][smithay-dmabuf]
## 8. System interface and application behavior
The launcher must derive its catalog from validated installed packages. Treat manifest names, descriptions, icons and other metadata as untrusted input; avoid unsafe HTML injection. Use one authoritative endpoint configuration and bridge rather than a second hardcoded WebSocket connection in the page.
Provide launch, activate/switch and close actions, including keyboard access to system navigation. The taskbar must activate applications as well as terminate them. Loading and failure states must correspond to authoritative lifecycle state and explain what the user can do next. Reconnecting the shell must restore a coherent snapshot without duplicate or stale applications.
Show only supported settings and controls. Theme or visual refinement must preserve readable text, focus, error states and performance. Shutdown/reboot must use the supported image's authorized host path. Do not put implementation details, development roles or internal status claims in product UI.
### 8.1 Counter
Counter is the smallest complete proof of application execution. A user action must reach the real component; the component's reply must drive the rendered value. Local JavaScript state cannot stand in for the component. Closing Counter must settle its runtime, renderer, relays and compositor state.
### 8.2 Notes
Notes is the reference for persistent user data. Use a real serialization implementation and preserve Unicode, whitespace, actual newlines and literal backslash sequences exactly. No ad hoc replacement of `\\n` with newline or string concatenation for structured JSON.
Associate load/save replies with the operation and editor revision that produced them. A late response must never overwrite edits made after that operation began. Define an explicit concurrent-writer policy, such as revision-checked writes with a visible conflict, and test it. Do not silently accept lost updates.
Persist through a temporary file and recoverable atomic replacement, with durability semantics appropriate to the filesystem and the acknowledgement promised to the UI. Keep the previous saved copy when writing fails. Acknowledge a save only after the specified persistence operation succeeds. Show unsaved changes and actionable failures; closing must follow a defined unsaved-change policy.
The reference fixture must cover empty text, non-ASCII text, multiple lines, quotes, literal backslashes, delayed load/save responses, a failed write, repeated saves and competing writers. Repeat persistence checks after reinstall/update, app and daemon restart, and VM reboot.
## 9. Packages, trust, storage and updates
### 9.1 Independent storage lifecycles
Use distinct locations and ownership for immutable package revisions, persistent application data, disposable cache and session runtime resources. Resolve platform directories from the supported environment. Do not place writable data beneath content that is signed, removed or replaced during package operations.
A suitable logical layout is:
| Store | Lifecycle |
|---|---|
| Package revisions, keyed by app ID and content identity | Immutable after activation; retained while referenced by sessions or rollback policy |
| App data, keyed by app ID | Persists independently across package updates and ordinary uninstall |
| App cache | Reconstructible; cleanup must not remove user data |
| Session runtime resources | Private, ephemeral and settled by the session owner |
Choose actual XDG/system paths once and use the common resolver. Preserve overrides only where their behavior and authority are explicit. Migrating the existing `apps/<id>/data` layout requires detection, backup/recovery behavior, conflict handling and a test proving existing Notes contents survive. Do not hide data migration inside an unrelated cleanup.
### 9.2 Package identity and trust
Specify canonical inventory ordering, path representation, supported file types, normalization and signature algorithm. The current implementation signs a hash of the recursively enumerated inventory, including UI content and excluding the signature file; the supplied demos verify under that algorithm. Preserve compatibility deliberately when formalizing the format. [Canonical implementation][pack]
Validate IDs, entry paths, duplicates, link policy and package structure before trust decisions. For the initial format, rejecting package symlinks is a reasonable simplification; if links are supported, define and enforce their integrity and confinement consistently across archives, signing, copying and runtime access. No format may verify one set of bytes and then execute different bytes after a race or mutable replacement.
Define two explicit operating policies:
- **Verified installation:** trust is established against an authorized key/store policy; invalid, missing, revoked or untrusted signatures fail closed. Verification must cover all executed and rendered package content.
- **Development installation:** unsigned/local content is allowed only through an explicit developer choice and visibly identified as such. It must not silently replace or masquerade as a verified revision.
The distributed reference image uses verified packages for its shipped applications. Demo keys are fixtures and must never become production signing authority. Keep release private keys outside the repository. Document how trusted keys are added, removed and rotated, and how installed/running revisions respond to revocation. A networked key service or general PKI is unnecessary unless a concrete distribution requirement justifies it.
Bind each installed application ID and its retained data to an authorized publisher/update-key policy. A generally trusted key must not be able to replace an unrelated publisher's application merely by reusing its ID. Preserve that ownership record across ordinary uninstall while data remains. Key rotation or ownership transfer requires the established authorization and an explicit transition. Refuse developer-install collisions with a verified identity, or use a separate development identity and data namespace. A new package requesting additional grants must follow the explicit grant policy; prior approval does not silently expand with an update.
Signed bytes establish origin/integrity under a trust policy, not safety or unrestricted permissions. Grant approval and signature verification remain separate decisions.
### 9.3 Transactional installation and update
The supported package workflow must:
1. Stage a complete candidate revision in a controlled location on the target filesystem.
2. Validate its structure, manifest, component and entries.
3. Verify its canonical content and trust under the selected installation policy.
4. Establish immutable, correctly owned installed content.
5. Activate the revision through a recoverable atomic transition.
6. Retain the previous revision while active sessions or rollback retention require it.
7. Clean unreferenced staging/revisions through a defined recovery policy.
A failed validation, full disk, denied write, crash or interruption must preserve the previous active revision when one exists; a failed first installation must leave the package uninstalled without phantom activation. User data remains intact in either case. A live session remains pinned to its original package bytes. Uninstall removes availability for new launches and follows an explicit policy for live sessions; it preserves user data by default. Purging data is a separate, explicit destructive action.
Package rollback and data rollback are different operations. If an application changes its data schema, define compatibility and recovery for that actual migration before shipping it. Do not invent a generic migration framework or imply that switching package revisions reverses user data automatically.
### 9.4 Verified images
If EROFS/dm-verity is part of a supported release profile, the builder and loader must share artifact names, version identity and metadata. Authenticate the image identity, root hash and necessary companion data under the package trust model. Verify that runtime, UI, manifest and grants refer to the same mounted revision.
A mount or verification failure in verified mode must not select an unverified mutable directory. Privileged operations must satisfy section 5.3. Test invalid image/hash pairs, tampered metadata, missing tools, caller authorization, partial mount failure, process termination and cleanup. Until these gates pass, keep this mode out of the supported image and document that limitation accurately.
Verified directory packages can satisfy the initial package profile only when their installed content cannot be modified by application code and the trust/identity checks remain effective through launch. Merely marking a same-user directory read-only by convention is insufficient.
## 10. Build, deployment and dependency policy
### 10.1 One reproducible product build
Record the actual Rust toolchain, target, workspace feature set, lockfiles, Servo/Stylo revisions, native libraries and build commands. Build both Servo hosts with their real renderer feature and the runtime with its real Wasmtime feature. Keep feature-disabled paths clearly confined to limited tooling checks; they cannot be distributed as functioning product components.
The selected dependency graph is authoritative for APIs. The inspected Cargo lockfile selects Servo `8e7dc40bff42448980b7249798f17e3131547138` and Stylo `dca3934667dae76c49bb579b268c5eb142d09c6a`; these are recovery evidence, not a direction to preserve old revisions indefinitely. Confirm whether the selected compatible stack should be repaired or updated in a bounded dependency change. [Lockfile][lockfile]
Apply required Cargo overrides at the consuming workspace root; dependency-level patch tables do not apply transitively. Inspect the resolved graph and verify each claimed fix on the actual selected code. Keep a short purpose, upstream status and removal condition for retained fork patches. [Cargo patch rules][cargo-patch]
Never fabricate `pkg-config` metadata, native library versions or readiness messages to pass a build. Repair the supported environment or clearly exclude an unsupported feature. Do not copy machine-specific usernames or checkout paths into the documented workflow.
Dependency updates need scope, compatibility evidence, relevant security review and the same per-step review as product code. Before beta, check the actual chosen versions against current upstream fixes/advisories and release support requirements. Record the assessment rather than assuming either that the latest tip is suitable or that an old pin is safe.
### 10.2 Installed session
Choose one authoritative Nix/systemd configuration and make supporting development units/scripts consistent with it. The installed closure must include:
- Correct feature-enabled binaries and runtime native dependencies.
- Shell HTML and required UI assets at real installed paths.
- Reference application packages with an explicit trust configuration.
- The actual app-shell and runtime paths, and paths for enabled portals/helpers, passed to appd.
- Explicit service activation/dependencies and truthful readiness.
- The real compositor display and daemon endpoints, without guessed names such as `wayland-1`.
- A seat/session arrangement that works in the reference VM.
- Separate persistent data and ephemeral runtime storage.
- Bounded restart behavior, diagnostics and authorized shutdown/reboot.
Build and boot the complete graphical closure from a clean environment. Verify updates/rebuilds preserve persistent data. No checkout-relative assets, manual environment repair or silently disabled product checks may be necessary for the documented release path.
### 10.3 Diagnostics and developer workflow
Document one supported path from checkout to real system and one installed-package workflow: build, check, verify, install, inspect, launch, status, terminate, update and uninstall. Existing commands plus a small diagnostic harness are sufficient; a new general CLI framework is not a goal.
Emit structured error categories for invalid packages, denied grants, startup timeouts, child exits, transport failures and rendering failures. Correlate diagnostics with safe session identifiers. Default logs must not dump application payloads, clipboard contents, saved notes or credentials. Preserve useful terminal reasons without indefinite log growth.
## 11. Verification contract
### 11.1 Evidence levels
| Level | What it can establish | What it cannot establish alone |
|---|---|---|
| Source inspection | Ownership, missing paths, API use and policy inconsistencies | Successful execution |
| Unit or pure contract test | Deterministic parser, state, serialization or boundary behavior | Full child-process, graphics or platform integration |
| Actual component/protocol integration | ABI, message semantics, grants and exercised lifecycle paths | Installed desktop behavior unless it runs that path |
| Graphical nested execution | Presented pixels, native input and desktop interactions on that backend | Reference-image boot or unrelated DRM behavior |
| Booted image and target-specific tests | Installed closure, session startup and behavior on the named target | Compatibility with untested devices |
| Failure and soak qualification | Defined recovery/reliability behavior within measured conditions | Absence of every possible defect |
Record commit, environment, selected features, command/harness, result and useful diagnostics. A missing environment or skipped required test is an incomplete gate, not a pass. Distinguish tests executed from tests only designed. Fixtures must fail when the promised behavior is broken; avoid tests that restate the implementation or only inspect a success log.
### 11.2 Verification profiles
Create profiles from commands that actually exist in the recovered repository. Names below describe responsibilities; they are not a claim that corresponding commands are currently installed.
| Profile | Required coverage |
|---|---|
| Contributor documentation | Policy consistency, Markdown links/catalog/metadata, runner behavior and actual diff review |
| Portable Rust/tooling | Relevant format/lint/tests for supported portable crates; no desktop-support inference |
| Linux product build | Correct runtime and Servo features, native dependencies, locked graph and required Linux crates |
| Component and protocol | Actual Wasm fixtures, canonical WIT, authenticated bridge, framing, limits and denied operations |
| Nested desktop | Real shell/app pixels, Counter, Notes, input, geometry, switching, lifecycle and reconnection |
| Package and data | Trust, confinement, atomic activation, interruption, retained data and live revision pinning |
| Reference image | Build, graphical boot, installed assets/endpoints, persistence, shutdown and service recovery |
| DRM or optional feature | Feature-specific positive, negative and recovery scenarios on the declared target |
| Release qualification | Full supported matrix, regression/failure suite, reliability runs, exact artifacts and independent review |
Demos are excluded from the current root workspace; their builds and actual component fixtures must be included explicitly where relevant. Default `cargo test --workspace` cannot prove their execution or the feature-enabled product behavior. [Workspace exclusions][workspace]
Use the smallest sufficient validation set for each change. Expand testing for a concrete affected boundary, regression risk or release gate. Do not repeatedly run unrelated expensive suites after the remaining risk is resolved. Conversely, do not weaken required checks or regenerate expectations merely to make a failing result green.
### 11.3 Required acceptance fixtures
| Fixture | Observable acceptance |
|---|---|
| Real first frame | Both hosts paint and present known content; no fake readiness or permanently blank surface |
| Initialization exchange | A UI that needs an initial component response completes its authenticated bootstrap while Starting and reaches truthful readiness |
| Counter | UI action reaches the actual component and its returned value updates the DOM |
| Notes exactness | Unicode, newlines, quotes and literal backslashes round-trip exactly |
| Notes ordering | Delayed load/save replies cannot replace newer edits; concurrent writes follow the declared policy |
| Notes close policy | Save/discard/cancel behavior follows the declared policy before teardown; forced termination never claims a successful save |
| Notes durability | Failed write preserves prior content; close/reopen, reboot and package update preserve successful saves |
| Two sessions | Switch and close independently; focus, stacking and payload delivery match ownership |
| Unauthorized client | Forged/mismatched/stale credentials cannot call system operations or access another session |
| Capability denial | Every advertised host import has allowed, denied and failure-path component tests |
| Filesystem confinement | Read-only writes, parent traversal, intermediate/final symlinks and replacement races are rejected |
| Entry validation | Escaping paths, wrong component world, missing entries and invalid identities fail before launch |
| Startup failures | Missing binaries, renderer failure, invalid package and readiness timeout produce a terminal reason and complete cleanup |
| Cancellation/crash | Runtime/UI death and cancellation at each startup phase leave no owned processes, relays, sockets or mounts |
| Framing/backpressure | Fragmentation, cancellation, concurrent traffic, full queues and closed relays do not corrupt frames or deadlock appd |
| Reconnection | Daemon/shell restart follows ownership policy and restores a coherent catalog/session snapshot |
| Geometry/input | Move/resize/maximize, focus, wheel, declared layouts and scale changes work without stuck input or coordinate drift |
| Idle/redraw | Input/content changes resume rendering after idle; no unbounded repaint loop is required |
| Package integrity | Tampering with executable, manifest or UI content fails verified installation/launch |
| Publisher ownership | A different trusted key cannot take over an app ID or retained data, including after uninstall; developer collisions are isolated/refused; authorized key rotation preserves ownership |
| First-install interruption | Failure leaves the package uninstalled, data intact and staging recoverable/removable; partial content is never active |
| Update interruption | Failure preserves the previously active revision, intact user data and recoverable staging |
| Active update | Existing session retains its package revision while a new launch resolves the new revision |
| Uninstall/migration | User data survives ordinary removal and legacy-layout migration; purge is explicit |
| Host services | Supported fetch/notification/clipboard behavior works in the installed environment and respects grants |
| Reference boot | Fresh graphical image starts the complete system without checkout paths or manual fixes |
| DRM recovery | Supported session deactivate/reactivate and output changes resume presentation correctly |
| Optional image mode | Tamper, mount failure and interrupted cleanup never downgrade verified execution |
For reliability qualification, adopt these initial acceptance targets and freeze any justified adjustments before beta:
- 20 consecutive clean reference-VM boots without failed session bring-up.
- 100 application launch/activate/close cycles without orphan processes or stale sessions.
- A two-hour mixed interactive run plus a separate idle/resume test.
- No uncaught host crash, deadlock, lost acknowledged data, cross-session disclosure or unbounded process/queue growth in those runs.
These are proposed acceptance targets, not measured baseline results. Measure launch time, input responsiveness, idle CPU, memory and log/queue growth on the reference target. Select and document acceptable budgets before beta; release candidates must meet the frozen budgets or present a reviewed scope decision before promotion.
## 12. Development sequence
Use dependency order and complete observable results. Do not begin with a repository-wide rewrite or treat security/data preservation as a late hardening stage.
| Milestone | Complete result | Exit evidence | Dependencies |
|---|---|---|---|
| Reproducible product build | One selected dependency graph, truthful feature configuration, real nested shell and app-host frames | Clean feature-enabled build; selected graph/pin agreement; pixel/input fixture | Contributor contract and supported environment recorded |
| Isolated application path | One resolved package/session identity, authenticated bridge, initial grants, renderer/package-resource/network restrictions, independent data, owned cleanup, Counter and Notes | Real component round-trip; exact Notes persistence; two-session denial; undeclared renderer/runtime operations denied; child/startup failure fixtures | Product build |
| Operable desktop | Authoritative windows, focus/stacking, geometry, shell activation, input, accessible keyboard navigation and state resynchronization | Two-app desktop workflow; layouts, wheel, resize/scale; close/reconnect and idle recovery | Isolated application path |
| Complete declared capabilities | Expand and qualify the supported operations within the established renderer/component boundaries; all advertised imports and budgets are enforced | Positive/negative actual component tests, portal race/confinement tests, browser resource policy and installed host-service fixtures | Isolated application path; product graphics |
| Recoverable package management | Shared validation, trust, staged activation, live revision pinning, retained data, migration and uninstall semantics | Tamper, interruption, rollback-compatibility, data-migration and update-during-session fixtures | Package identity and independent data established earlier |
| Bootable reference image | One coherent graphical Nix/systemd closure with real assets, endpoint propagation and backend recovery | Fresh build/boot, real app usage, persistence/reboot and DRM tests if selected | Desktop, capabilities and package paths integrated |
| Complete supported distribution | Honest support matrix, application authoring guide, package diagnostics, optional modes either qualified or clearly unavailable | Clean-checkout and installed workflows reproduced; documented features map to passing fixtures | Reference image and supported feature set |
| Stability qualification | Candidate contains the complete declared scope with measured budgets and no blocking defects | Full acceptance matrix, failure/soak runs, candidate artifacts and independent technical review | All required supported paths |
The **first implementation task** is to recover the truthful full-feature baseline: select the dependency graph, repair the actual Servo API use, paint/present a reference frame, and verify the product feature configuration. Split this into reviewed coherent changes where needed. Do not combine it with speculative visual redesign or package-format redesign.
The **first integrated application milestone** must already include authenticated IPC, one package identity, publisher/data ownership, renderer and runtime resource restrictions, data outside package content and owned cleanup. Unsupported host imports must fail explicitly until implemented. Early development may use controlled local fixtures, but must not publish sandbox, trust or stability claims beyond the exercised contract.
Later milestones may proceed in parallel only when they have independent contracts and acceptance criteria. Shared schemas, lifecycle owners and dependency decisions require coordination before edits; parallel work must not create competing sources of truth. Every branch still passes its own review and integration gates.
### 12.1 Version progression
Use scoped `0.0.x` releases toward stable `0.1.0`. Assign the next available `0.0.x` to an accepted milestone scope after inspecting existing refs and publication history. Do not mechanically assign a new version to every commit or promise a fixed count of intermediate releases.
The current unreleased manifest value `0.1.0` must be reconciled deliberately. Do not rewrite published tags, force users onto a lower published version or change application/package versions accidentally. Document whether the existing workspace value was only a development placeholder before establishing the next prerelease.
Each planned version follows `alpha.N -> beta.N -> rc.N -> final`:
For example: `0.0.1-alpha.1`, `0.0.1-beta.1`, `0.0.1-rc.1`, then `0.0.1`. “Final” names the promotion stage, not a literal `-final` version suffix.
| Stage | Entry/exit contract |
|---|---|
| `alpha.N` | Scope, ownership and fixtures defined; bounded implementation proceeds through reviewed steps; known incompleteness is explicit |
| `beta.N` | The version's declared scope is implemented; relevant integration and failure paths pass; interfaces/support/budgets are frozen for qualification |
| `rc.N` | Exact candidate is feature-complete for its scope; required matrix and independent technical review pass; artifacts and migration/recovery behavior are ready |
| Final for a `0.0.x` version | That version's scoped promises pass; remaining product milestones stay explicit and the release is not presented as stable `0.1.0` |
| Stable `0.1.0` | Every required product journey, trust/data boundary, supported target and release gate in this blueprint passes |
Promotion is an explicit evidence-based decision under existing release authority. No label, test count, lack of bug reports or successful compile triggers promotion automatically. Corrections after candidate approval invalidate affected evidence; material changes require a new candidate and review. Publish the tested artifact. If final version metadata or packaging requires a rebuild, verify that final artifact under the applicable candidate gates before publication.
## 13. Contribution, review and continuous simplification
### 13.1 Toolkit structure
Adapt the actual Resina arrangement to WEFT. Retain the distinction between the root contract and optional linked knowledge; do not copy design-system-specific backends, schemas or contribution hierarchy. [Resina contract][resina-contract] [Resina toolkit][resina-toolkit]
| Path | Responsibility |
|---|---|
| `AGENTS.md` | Canonical engineering policy, scope, review, validation and publication rules |
| `.agents/README.md` | Catalog, precedence, entry points and actual capabilities |
| `.agents/commands/` | Scope/specification, implementation, verification, maintenance and release procedures |
| `.agents/agents/` | Reviewer, architecture-debt scout, continuous simplicity and continuous refactoring responsibilities |
| `.agents/skills/` | Focused WEFT area knowledge linked to canonical contracts and selected sources |
| `.agents/scripts/verify.py` | Small portable runner for actual repository verification profiles |
| `CONTRIBUTING.md` and issue/PR templates | Maintainer-facing contribution expectations and useful problem/behavior/evidence fields |
Area knowledge should cover compositor/input, Servo, runtime/capabilities, appd lifecycle/IPC, packages/data/trust, Linux deployment, integration/visual verification and documentation. Combine related subjects where that produces a useful guide. Do not duplicate root policy in every file or create empty guides for symmetry.
Commands are portable Markdown procedures, not a claim that every client has automatically registered slash commands. Any metadata must be internally consistent and compatible with the chosen consumer. The runner uses argument arrays, resolves the repository root, works from another directory, fails on required failures and supports dry-run. It must not silently install dependencies, mutate files, bless expectations, skip required checks or publish changes. Test its meaningful behavior, especially failure propagation and missing prerequisites. [Resina runner reference][resina-runner]
### 13.2 Every coherent step is reviewed
Apply this loop to primary development, bug fixes, simplification, refactoring, dependencies, documentation, governance, packaging and release work:
1. Inspect current evidence and the relevant implemented/accepted contract.
2. State the present problem, owner, bounded scope, observable acceptance and proof.
3. Review that scope and design before changing the affected boundary.
4. Implement one coherent result, preserving unrelated work.
5. Run the smallest sufficient checks for the changed behavior and concrete risks.
6. Review the actual diff against acceptance, compatibility, security, data and failure behavior.
7. Correct findings, revalidate and review the corrected content.
8. Accept the atomic result only when blockers are resolved; then reassess the next dependent step.
Review a real staged/unstaged diff or explicit base-to-head commit range. An empty `git diff HEAD` after committing is not review of the committed change. Recheck material rebases, conflict resolutions and corrections before integration. Review the final aggregate change for cross-step effects when preparing a PR or candidate.
Use a reviewer who did not author the change when available. If that is unavailable, use a fresh separate critical pass and record its limitation honestly; never claim independent review occurred. Release gates require independent technical review of the candidate. An unavailable required release reviewer leaves that release gate pending while other authorized work continues.
A blocking finding concerns correctness, promised behavior, trust, data preservation, compatibility, the accepted scope or required evidence. Fix it before advancing dependent work. A present but unrelated improvement belongs in separately scoped maintenance; speculative preferences must not become blockers or recurring issue quotas.
Review is an engineering checkpoint, not a requirement for a new human confirmation at every step. Decisions already accepted in this blueprint and prior authorization remain effective.
### 13.3 Autonomous primary development and bounded maintenance
Continue primary development through successive accepted changes toward the active goal. Do not stop after a single patch or PR when more authorized independent work remains. Reinspect the changed boundary and new evidence rather than repeating full repository discovery for each step.
Fix related debt within the active acceptance criterion. For unrelated maintenance, require an affected user/contract, present evidence and cost, and an independently verifiable acceptance criterion. Check for existing work first. Base an isolated worktree and descriptive branch on a verified current revision of the default branch, preserving the active development checkout. If freshness cannot be verified, state the actual revision and limitation. Each separately invoked maintenance run handles one qualifying problem and stops after its issue or reviewed PR; primary development continues independently. Publication follows existing authority. When publication is not authorized or available, prepare the local result and concrete issue/PR content without publishing it.
The debt scout identifies the strongest justified issue without editing repository files or creating implementation branches or commits; it may prepare or publish that issue only within granted authority. It must not manufacture a backlog or launch speculative work. Simplicity removes duplicated decisions, unnecessary state and misleading fallback paths. Refactoring changes internal structure while preserving the accepted behavior and proof. Neither is a license for repeated architecture replacement.
High-value candidates already supported by the audit are shared package resolution, a single effective-grants model, one session cleanup owner, one bridge/message contract and common Servo host/input behavior. Extract them when the working path and regression evidence justify the boundary. Do not optimize for line-count reduction at the expense of explicit authority, errors or useful tests.
Seek a new decision only for a material departure from accepted product direction, public compatibility promises, trust boundaries, support scope, destructive data policy or missing authority. Prepare the alternatives and evidence first, and continue independent authorized work. Ordinary implementation of an accepted boundary must not trigger repeated architecture approval requests.
### 13.4 Branches and publication text
Use descriptive technical branch names in every workflow:
| Change | Suitable branch |
|---|---|
| Contributor contract | `docs/add-weft-contribution-contract` |
| Real frame presentation | `fix/servo-frame-presentation` |
| Session authorization | `fix/authorize-session-messages` |
| Data preservation | `fix/preserve-notes-on-package-update` |
| Shared package resolution | `refactor/share-package-resolution` |
| Keyboard app switching | `feat/keyboard-app-switching` |
| Installed Servo features | `build/enable-servo-vm-packages` |
| Portal regression coverage | `test/reject-portal-symlink-escapes` |
Reject generic task/lane/phase labels, model/provider names, role names and generic “maintenance” or “stability” branches. The branch must describe the actual change even when the change originated during maintenance. Discover the real default branch; do not copy Resina's `master` assumption into WEFT's `main` workflow.
Public branch names, commit subjects/bodies, issue/PR titles and descriptions, comments, release notes and product text must describe the concrete problem, resulting behavior, affected boundaries and actual validation. Do not include model/provider attribution, generated-by/co-author trailers, reviewer counts/personas, prompts, internal role handoffs or process narration. A technical “Validation” section with real commands and results is useful; claims about how many reviewers participated are not product evidence.
Keep commits atomic and technically named. Reusable governance files, this adopted blueprint and legitimate protocol/product documentation are intentional tracked artifacts. Temporary plans, transcripts, review scratch files and internal progress reports stay out of Git.
Preserve unrelated working-tree changes, existing branches and protections. Never use a successful review as implicit merge, release or deployment authority. Honor existing authorization without requesting it again. Before a public action, inspect applicable repository integrations and controls; do not knowingly trigger incompatible branded publication or bypass required protections to avoid it. Resolve an actual conflict explicitly while continuing safe authorized work.
## 14. Stable release gate
Stable `0.1.0` is ready only when all applicable statements are true for the exact candidate:
- The full feature-enabled product builds from the documented pinned environment.
- Both Servo hosts present real content and respond correctly to required input/window events.
- The reference image boots into the usable desktop without manual repair.
- The complete Counter and Notes workflows run through actual components and host processes.
- Session identity, authenticated IPC, grants and renderer restrictions enforce the declared boundaries.
- All child failures, startup cancellation, daemon/shell recovery and teardown paths settle owned resources.
- Package integrity, transactional activation, live version pinning and data retention survive their negative/failure fixtures.
- Every advertised host import and supported backend has actual integration evidence.
- Declared keyboard accessibility, support matrix and installed developer/user workflows are verified.
- Measured budgets and the frozen reliability targets pass.
- Known failures in these promises are resolved; unsupported features are clearly excluded and unavailable as successful product paths.
- Documentation, manifest/WIT/IPC contracts, selected dependencies, build configuration and observed behavior agree.
- The candidate has independent technical review, and material findings/corrections have been revalidated and reviewed.
- Release metadata identifies the commit, artifact digests, environment, support scope, compatibility/migration notes and known limitations accurately.
- Publication follows the established authority and repository protections; tags and artifacts refer to the tested candidate.
## 15. Source references
Inline repository links are pinned to the inspected revisions unless they intentionally identify a live release listing or recorded CI run. Upstream links identify the API versions used to verify baseline findings. Recheck them against the selected implementation revision when work begins.
[workspace]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/Cargo.toml
[architecture]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/docs/architecture.md
[historical-baseline]: https://github.com/marcoallegretti/WEFT_OS/blob/a236a3a9f4f7a90288beed6ffc6412bdbc0b042e/docs/architecture/baseline.md
[security]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/docs/security.md
[lockfile]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/Cargo.lock
[servo-pin]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/crates/weft-servo-shell/SERVO_PIN.md
[app-embedder]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/crates/weft-app-shell/src/embedder.rs
[system-embedder]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/crates/weft-servo-shell/src/embedder.rs
[app-main]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/crates/weft-app-shell/src/main.rs
[system-main]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/crates/weft-servo-shell/src/main.rs
[runtime]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/crates/weft-runtime/src/main.rs
[appd-runtime]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/crates/weft-appd/src/runtime.rs
[appd-main]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/crates/weft-appd/src/main.rs
[appd-ipc]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/crates/weft-appd/src/ipc.rs
[appd-ws]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/crates/weft-appd/src/ws.rs
[file-portal]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/crates/weft-file-portal/src/main.rs
[compositor-appd]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/crates/weft-compositor/src/appd_ipc.rs
[compositor-state]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/crates/weft-compositor/src/state.rs
[compositor-input]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/crates/weft-compositor/src/input.rs
[drm]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/crates/weft-compositor/src/backend/drm.rs
[pack]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/crates/weft-pack/src/main.rs
[mount]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/crates/weft-appd/src/mount.rs
[mount-helper]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/crates/weft-mount-helper/src/main.rs
[notes-ui]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/examples/org.weft.demo.notes/ui/index.html
[notes-runtime]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/examples/org.weft.demo.notes/src/main.rs
[nix-packages]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/infra/nixos/weft-packages.nix
[nix-config]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/infra/nixos/configuration.nix
[flake]: https://github.com/marcoallegretti/WEFT_OS/blob/b99cc73a4704615521c38ca84dc46dc1bd641bc6/flake.nix
[services]: https://github.com/marcoallegretti/WEFT_OS/tree/b99cc73a4704615521c38ca84dc46dc1bd641bc6/infra/systemd
[ci-run]: https://github.com/marcoallegretti/WEFT_OS/actions/runs/23053354517
[releases]: https://github.com/marcoallegretti/WEFT_OS/releases
[servo-input]: https://github.com/marcoallegretti/servo/blob/8e7dc40bff42448980b7249798f17e3131547138/components/shared/embedder/input_events.rs#L195-L202
[servo-render]: https://github.com/marcoallegretti/servo/blob/8e7dc40bff42448980b7249798f17e3131547138/components/shared/paint/rendering_context.rs#L305-L371
[servo-webview]: https://github.com/marcoallegretti/servo/blob/8e7dc40bff42448980b7249798f17e3131547138/components/servo/webview.rs#L47-L69
[servo-patch]: https://github.com/marcoallegretti/servo/blob/8e7dc40bff42448980b7249798f17e3131547138/Cargo.toml#L348-L356
[stylo-gate]: https://github.com/servo/stylo/blob/dca3934667dae76c49bb579b268c5eb142d09c6a/style/properties/longhands.toml#L351-L359
[smithay-output]: https://github.com/Smithay/smithay/blob/v0.7.0/src/backend/drm/output.rs#L503-L637
[smithay-dmabuf]: https://github.com/Smithay/smithay/blob/v0.7.0/src/wayland/dmabuf/mod.rs#L585-L609
[cargo-patch]: https://doc.rust-lang.org/cargo/reference/overriding-dependencies.html#the-patch-section
[tokio-lines]: https://docs.rs/tokio/1.50.0/tokio/io/trait.AsyncBufReadExt.html#method.read_line
[wasmtime-linker]: https://github.com/bytecodealliance/wasmtime/blob/v30.0.2/crates/wasmtime/src/runtime/component/linker.rs#L28-L55
[resina-contract]: https://github.com/marcoallegretti/Resina-Design_System/blob/1e768064f57a1e403ab271822383e732795905a6/AGENTS.md
[resina-toolkit]: https://github.com/marcoallegretti/Resina-Design_System/blob/1e768064f57a1e403ab271822383e732795905a6/.agents/README.md
[resina-runner]: https://github.com/marcoallegretti/Resina-Design_System/blob/1e768064f57a1e403ab271822383e732795905a6/.agents/scripts/verify.py

77
CONTRIBUTING.md Normal file
View file

@ -0,0 +1,77 @@
# Contributing to WEFT OS
[AGENTS.md](AGENTS.md) is the engineering contract for every contribution.
[BLUEPRINT.md](BLUEPRINT.md) describes the accepted product direction toward
`0.1.0`. This guide points to the workflow; the contract
defines the requirements.
The [contributor toolkit](.agents/README.md) provides procedures, review roles,
area knowledge and a verification runner.
## Describe a verifiable change
Search [existing issues](https://github.com/marcoallegretti/WEFT_OS/issues) and
pull requests first, then open a
[new issue](https://github.com/marcoallegretti/WEFT_OS/issues/new/choose):
- **Defect or change** for a concrete problem or ordinary work within accepted
architecture.
- **Maintenance** for one present ownership, boundary, enforcement or structural
problem outside active development.
- **Decision** for a material change of product direction, public compatibility,
trust boundaries, support scope or data policy. Opening it does not approve the
change.
Each form asks for observed and expected behavior, evidence, the owning
component, present impact, an acceptance criterion and the proof that would
show the change works. The [maintenance threshold](AGENTS.md#8-maintenance)
separates a present problem from a cleanup preference.
## Find the owner
Each component owns specific responsibilities, listed in the blueprint's
[ownership table](BLUEPRINT.md#4-architecture-and-ownership). Public contracts
are the package manifests, the [host WIT](crates/weft-runtime/wit/weft-app.wit),
the [shell protocol](protocol/weft-shell-unstable-v1.xml) and the
[IPC types](crates/weft-ipc-types/src/lib.rs). Selected dependency APIs are
those in [Cargo.lock](Cargo.lock), including the Servo fork and the Stylo revision.
## Prove and implement the change
Follow the [reviewed change loop](AGENTS.md#5-reviewed-change-loop): confirm
scope, name the proof, implement, validate, review the actual diff, correct and
commit atomically. Reproduce a defect before fixing it. Compilation, mocks and
capability declarations do not prove rendering, native input, isolation or
persistence; see [proof before implementation](AGENTS.md#6-proof-before-implementation).
Branch from the current `main` with a descriptive name such as
`fix/authorize-session-messages` or `refactor/share-servo-frame-loop`; the
[branch rules](AGENTS.md#14-branches-commits-and-publication) list what to avoid.
Install the native dependencies from [docs/building.md](docs/building.md) and
run the relevant [runner](.agents/README.md#verification-runner) profiles, for
example:
```sh
python .agents/scripts/verify.py portable linux
python .agents/scripts/verify.py servo-embed
pip install -r .agents/scripts/requirements.txt
python .agents/scripts/verify.py toolkit
```
[verify](.agents/commands/verify.md) maps each kind of change to its profiles and
to the evidence the runner cannot provide, such as a running compositor, real
pixels, actual components or a booted image. Report checks that could not run
and why.
## Submit a pull request
The [pull request template](.github/pull_request_template.md) asks for the
problem and scope, what changed, ownership, what proves it, the validation
actually performed, manual verification and material limitations. Write for a
maintainer who has no access to your working notes: no attribution, generated-by
or co-author trailers, prompts or process narration.
Contribution work is reviewed from its actual diff, preferably by someone who
did not write it. Maintainers decide merges and release promotion; a green CI
run or a review does not merge or release anything by itself.

View file

@ -75,12 +75,13 @@ See `docs/building.md` for full instructions including Wasm component builds, Ni
## CI ## CI
Jobs on every push and pull request: Jobs on every push to `main` and on pull requests:
- `cross-platform` — fmt, clippy, tests on Ubuntu and Windows - `portable` — fmt, clippy and tests for the crates that need no Linux system libraries
- `linux-only` — clippy and tests for compositor and shell crates - `linux-only` — clippy and tests for compositor and shell crates
- `runtime-grants` — clippy for `weft-runtime` with its Wasm engine and fetch, and `tests/runtime/check_grants.py` - `runtime-grants` — clippy for `weft-runtime` with its Wasm engine and fetch, and `tests/runtime/check_grants.py`
- `servo-embed-linux` — `cargo check --features servo-embed` for both servo crates - `servo-embed-linux` — `cargo check --features servo-embed` for both servo crates
- `contributor-toolkit` — links, metadata and catalog of the contributor toolkit, and runner tests
## Security ## Security
@ -99,3 +100,7 @@ See `docs/security.md`. Key points:
- Stylo: `https://github.com/marcoallegretti/stylo` at `f1ba4969`, through the root `[patch]` - Stylo: `https://github.com/marcoallegretti/stylo` at `f1ba4969`, through the root `[patch]`
- Patches: `backdrop-filter` parsing (Stylo) and rendering (Servo) - Patches: `backdrop-filter` parsing (Stylo) and rendering (Servo)
- See `crates/weft-servo-shell/SERVO_PIN.md` for Servo integration status and known limitations - See `crates/weft-servo-shell/SERVO_PIN.md` for Servo integration status and known limitations
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md). [AGENTS.md](AGENTS.md) is the engineering contract and [BLUEPRINT.md](BLUEPRINT.md) the accepted direction toward `0.1.0`.

View file

@ -157,10 +157,8 @@ pub fn run() -> anyhow::Result<()> {
false false
} }
}; };
if render_ok { if render_ok && let Err(e) = backend.submit(Some(&[full_damage])) {
if let Err(e) = backend.submit(Some(&[full_damage])) { tracing::warn!(?e, "backend submit failed");
tracing::warn!(?e, "backend submit failed");
}
} }
state.space.elements().for_each(|window| { state.space.elements().for_each(|window| {

View file

@ -625,6 +625,14 @@ fn package_store_roots() -> Vec<PathBuf> {
mod tests { mod tests {
use super::*; use super::*;
/// Serialises the tests that read or change WEFT_APP_STORE; the test
/// harness runs tests on parallel threads that share the environment.
static ENV_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());
fn env_lock() -> std::sync::MutexGuard<'static, ()> {
ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner())
}
#[cfg(not(feature = "wasmtime-runtime"))] #[cfg(not(feature = "wasmtime-runtime"))]
#[test] #[test]
fn engine_disabled_build_refuses_to_run_components() { fn engine_disabled_build_refuses_to_run_components() {
@ -640,7 +648,14 @@ mod tests {
#[test] #[test]
fn package_store_roots_includes_system_path() { fn package_store_roots_includes_system_path() {
let _env = env_lock();
let prior = std::env::var_os("WEFT_APP_STORE");
// SAFETY: env_lock serialises every test that touches the environment.
unsafe { std::env::remove_var("WEFT_APP_STORE") };
let roots = package_store_roots(); let roots = package_store_roots();
if let Some(v) = prior {
unsafe { std::env::set_var("WEFT_APP_STORE", v) };
}
assert!( assert!(
roots roots
.iter() .iter()
@ -650,6 +665,7 @@ mod tests {
#[test] #[test]
fn package_store_roots_uses_weft_app_store_when_set() { fn package_store_roots_uses_weft_app_store_when_set() {
let _env = env_lock();
// SAFETY: test binary is single-threaded at this point. // SAFETY: test binary is single-threaded at this point.
unsafe { std::env::set_var("WEFT_APP_STORE", "/custom/store") }; unsafe { std::env::set_var("WEFT_APP_STORE", "/custom/store") };
let roots = package_store_roots(); let roots = package_store_roots();
@ -659,6 +675,7 @@ mod tests {
#[test] #[test]
fn resolve_package_finds_installed_package() { fn resolve_package_finds_installed_package() {
let _env = env_lock();
use std::fs; use std::fs;
let store = let store =
std::env::temp_dir().join(format!("weft_runtime_resolve_{}", std::process::id())); std::env::temp_dir().join(format!("weft_runtime_resolve_{}", std::process::id()));
@ -689,6 +706,7 @@ mod tests {
#[test] #[test]
fn resolve_package_errors_on_unknown_id() { fn resolve_package_errors_on_unknown_id() {
let _env = env_lock();
let store = let store =
std::env::temp_dir().join(format!("weft_runtime_resolve_empty_{}", std::process::id())); std::env::temp_dir().join(format!("weft_runtime_resolve_empty_{}", std::process::id()));
let _ = std::fs::create_dir_all(&store); let _ = std::fs::create_dir_all(&store);

View file

@ -2,7 +2,7 @@
## Prerequisites ## Prerequisites
Linux (x86_64 or aarch64). Building on Windows is supported for workspace validation only; runtime components require Linux kernel interfaces. Linux (x86_64 or aarch64). WEFT OS is built and validated on Linux only; runtime components require Linux kernel interfaces.
System packages (openSUSE): System packages (openSUSE):
@ -142,7 +142,8 @@ See `infra/nixos/weft-packages.nix` for the package derivations. Its `outputHash
Jobs run on every push to `main` and on pull requests: Jobs run on every push to `main` and on pull requests:
- `cross-platform` — fmt, clippy, tests on Ubuntu and Windows (excludes Wayland crates) - `portable` — fmt, clippy, tests for the crates that need no Linux system libraries (excludes Wayland crates)
- `linux-only` — clippy and tests for `weft-compositor`, `weft-servo-shell`, `weft-app-shell` - `linux-only` — clippy and tests for `weft-compositor`, `weft-servo-shell`, `weft-app-shell`
- `runtime-grants` — clippy and a build of `weft-runtime` with `wasmtime-runtime,net-fetch`, then `tests/runtime/check_grants.py`, which runs a probe component under each kind of capability grant - `runtime-grants` — clippy and a build of `weft-runtime` with `wasmtime-runtime,net-fetch`, then `tests/runtime/check_grants.py`, which runs a probe component under each kind of capability grant
- `servo-embed-linux` — `cargo check --features servo-embed` for servo-shell and app-shell - `servo-embed-linux` — `cargo check --features servo-embed` for servo-shell and app-shell
- `contributor-toolkit` — `python .agents/scripts/verify.py toolkit`

View file

@ -22,7 +22,7 @@ The guest is the validation target for:
## Host versus target boundary ## Host versus target boundary
The Windows host is acceptable for editing, documentation, and workspace validation. The Windows host is acceptable for editing and documentation. Builds and tests are validated on Linux only; CI does not build on Windows.
The Linux guest is authoritative for: The Linux guest is authoritative for: