mirror of
https://github.com/marcoallegretti/WEFT_OS.git
synced 2026-11-22 08:13:59 +00:00
Merge remote-tracking branch 'origin/fix/separate-app-data' into fix/session-owned-ipc-relay
This commit is contained in:
commit
cda9c14426
37 changed files with 2864 additions and 20 deletions
121
.agents/README.md
Normal file
121
.agents/README.md
Normal 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.
|
||||
39
.agents/agents/architecture-debt-scout.md
Normal file
39
.agents/agents/architecture-debt-scout.md
Normal 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.
|
||||
30
.agents/agents/continuous-refactoring.md
Normal file
30
.agents/agents/continuous-refactoring.md
Normal 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.
|
||||
26
.agents/agents/continuous-simplicity.md
Normal file
26
.agents/agents/continuous-simplicity.md
Normal 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.
|
||||
56
.agents/agents/reviewer.md
Normal file
56
.agents/agents/reviewer.md
Normal 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.
|
||||
56
.agents/commands/implement.md
Normal file
56
.agents/commands/implement.md
Normal 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.
|
||||
36
.agents/commands/maintenance.md
Normal file
36
.agents/commands/maintenance.md
Normal 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.
|
||||
43
.agents/commands/release.md
Normal file
43
.agents/commands/release.md
Normal 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
43
.agents/commands/scope.md
Normal 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.
|
||||
43
.agents/commands/verify.md
Normal file
43
.agents/commands/verify.md
Normal 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.
|
||||
174
.agents/scripts/check_toolkit.py
Normal file
174
.agents/scripts/check_toolkit.py
Normal 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())
|
||||
3
.agents/scripts/requirements.txt
Normal file
3
.agents/scripts/requirements.txt
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
markdown-it-py==4.2.0
|
||||
mdurl==0.1.2
|
||||
PyYAML==6.0.3
|
||||
240
.agents/scripts/test_toolkit.py
Normal file
240
.agents/scripts/test_toolkit.py
Normal 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
128
.agents/scripts/verify.py
Normal 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())
|
||||
59
.agents/skills/weft-appd-sessions/SKILL.md
Normal file
59
.agents/skills/weft-appd-sessions/SKILL.md
Normal 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.
|
||||
55
.agents/skills/weft-compositor-input/SKILL.md
Normal file
55
.agents/skills/weft-compositor-input/SKILL.md
Normal 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.
|
||||
53
.agents/skills/weft-documentation/SKILL.md
Normal file
53
.agents/skills/weft-documentation/SKILL.md
Normal 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.
|
||||
54
.agents/skills/weft-integration-verification/SKILL.md
Normal file
54
.agents/skills/weft-integration-verification/SKILL.md
Normal 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.
|
||||
53
.agents/skills/weft-linux-deployment/SKILL.md
Normal file
53
.agents/skills/weft-linux-deployment/SKILL.md
Normal 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.
|
||||
57
.agents/skills/weft-packages-data/SKILL.md
Normal file
57
.agents/skills/weft-packages-data/SKILL.md
Normal 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.
|
||||
58
.agents/skills/weft-runtime-capabilities/SKILL.md
Normal file
58
.agents/skills/weft-runtime-capabilities/SKILL.md
Normal 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.
|
||||
72
.agents/skills/weft-servo-rendering/SKILL.md
Normal file
72
.agents/skills/weft-servo-rendering/SKILL.md
Normal 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
63
.github/ISSUE_TEMPLATE/change.yml
vendored
Normal 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
5
.github/ISSUE_TEMPLATE/config.yml
vendored
Normal 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
58
.github/ISSUE_TEMPLATE/decision.yml
vendored
Normal 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
58
.github/ISSUE_TEMPLATE/maintenance.yml
vendored
Normal 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
29
.github/pull_request_template.md
vendored
Normal 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. -->
|
||||
29
.github/workflows/ci.yml
vendored
29
.github/workflows/ci.yml
vendored
|
|
@ -7,15 +7,9 @@ on:
|
|||
pull_request:
|
||||
|
||||
jobs:
|
||||
# Crates that must compile on every supported host platform.
|
||||
cross-platform:
|
||||
runs-on: ${{ matrix.os }}
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
os:
|
||||
- ubuntu-latest
|
||||
- windows-latest
|
||||
# Crates that build without Wayland or other Linux system libraries.
|
||||
portable:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
|
|
@ -24,14 +18,14 @@ jobs:
|
|||
components: rustfmt, clippy
|
||||
- name: cargo fmt
|
||||
run: cargo fmt --all --check
|
||||
- name: cargo clippy (cross-platform crates)
|
||||
- name: cargo clippy (portable crates)
|
||||
run: >
|
||||
cargo clippy --workspace
|
||||
--exclude weft-compositor
|
||||
--exclude weft-servo-shell
|
||||
--exclude weft-app-shell
|
||||
--all-targets -- -D warnings
|
||||
- name: cargo test (cross-platform crates)
|
||||
- name: cargo test (portable crates)
|
||||
run: >
|
||||
cargo test --workspace
|
||||
--exclude weft-compositor
|
||||
|
|
@ -133,3 +127,16 @@ jobs:
|
|||
cargo check
|
||||
-p weft-app-shell
|
||||
--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
1
.gitignore
vendored
|
|
@ -1,4 +1,5 @@
|
|||
/target/
|
||||
__pycache__/
|
||||
/.windsurf/
|
||||
/docu_dev/
|
||||
|
||||
|
|
|
|||
368
AGENTS.md
Normal file
368
AGENTS.md
Normal 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
657
BLUEPRINT.md
Normal 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
77
CONTRIBUTING.md
Normal 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.
|
||||
|
|
@ -75,12 +75,13 @@ See `docs/building.md` for full instructions including Wasm component builds, Ni
|
|||
|
||||
## 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
|
||||
- `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
|
||||
- `contributor-toolkit` — links, metadata and catalog of the contributor toolkit, and runner tests
|
||||
|
||||
## Security
|
||||
|
||||
|
|
@ -99,3 +100,7 @@ See `docs/security.md`. Key points:
|
|||
- Stylo: `https://github.com/marcoallegretti/stylo` at `f1ba4969`, through the root `[patch]`
|
||||
- Patches: `backdrop-filter` parsing (Stylo) and rendering (Servo)
|
||||
- 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`.
|
||||
|
|
|
|||
|
|
@ -157,10 +157,8 @@ pub fn run() -> anyhow::Result<()> {
|
|||
false
|
||||
}
|
||||
};
|
||||
if render_ok {
|
||||
if let Err(e) = backend.submit(Some(&[full_damage])) {
|
||||
tracing::warn!(?e, "backend submit failed");
|
||||
}
|
||||
if render_ok && let Err(e) = backend.submit(Some(&[full_damage])) {
|
||||
tracing::warn!(?e, "backend submit failed");
|
||||
}
|
||||
|
||||
state.space.elements().for_each(|window| {
|
||||
|
|
|
|||
|
|
@ -625,6 +625,14 @@ fn package_store_roots() -> Vec<PathBuf> {
|
|||
mod tests {
|
||||
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"))]
|
||||
#[test]
|
||||
fn engine_disabled_build_refuses_to_run_components() {
|
||||
|
|
@ -640,7 +648,14 @@ mod tests {
|
|||
|
||||
#[test]
|
||||
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();
|
||||
if let Some(v) = prior {
|
||||
unsafe { std::env::set_var("WEFT_APP_STORE", v) };
|
||||
}
|
||||
assert!(
|
||||
roots
|
||||
.iter()
|
||||
|
|
@ -650,6 +665,7 @@ mod tests {
|
|||
|
||||
#[test]
|
||||
fn package_store_roots_uses_weft_app_store_when_set() {
|
||||
let _env = env_lock();
|
||||
// SAFETY: test binary is single-threaded at this point.
|
||||
unsafe { std::env::set_var("WEFT_APP_STORE", "/custom/store") };
|
||||
let roots = package_store_roots();
|
||||
|
|
@ -659,6 +675,7 @@ mod tests {
|
|||
|
||||
#[test]
|
||||
fn resolve_package_finds_installed_package() {
|
||||
let _env = env_lock();
|
||||
use std::fs;
|
||||
let store =
|
||||
std::env::temp_dir().join(format!("weft_runtime_resolve_{}", std::process::id()));
|
||||
|
|
@ -689,6 +706,7 @@ mod tests {
|
|||
|
||||
#[test]
|
||||
fn resolve_package_errors_on_unknown_id() {
|
||||
let _env = env_lock();
|
||||
let store =
|
||||
std::env::temp_dir().join(format!("weft_runtime_resolve_empty_{}", std::process::id()));
|
||||
let _ = std::fs::create_dir_all(&store);
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
## 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):
|
||||
|
||||
|
|
@ -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:
|
||||
|
||||
- `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`
|
||||
- `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
|
||||
- `contributor-toolkit` — `python .agents/scripts/verify.py toolkit`
|
||||
|
|
|
|||
|
|
@ -22,7 +22,7 @@ The guest is the validation target for:
|
|||
|
||||
## 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:
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue