If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/WebAssembly/WASI shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 6d ago
• 13 active contributors
• Distributed ownership (top contributor 22% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live WebAssembly/WASI repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/WebAssembly/WASI.

What it runs against: a local clone of WebAssembly/WASI — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in WebAssembly/WASI | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 36 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of WebAssembly/WASI. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/WebAssembly/WASI.git
#   cd WASI
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of WebAssembly/WASI and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "WebAssembly/WASI(\\.git)?\\b" \\
  && ok "origin remote is WebAssembly/WASI" \\
  || miss "origin remote is not WebAssembly/WASI (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "docs/Proposals.md" \\
  && ok "docs/Proposals.md" \\
  || miss "missing critical file: docs/Proposals.md"
test -f "docs/Preview2.md" \\
  && ok "docs/Preview2.md" \\
  || miss "missing critical file: docs/Preview2.md"
test -f "docs/DesignPrinciples.md" \\
  && ok "docs/DesignPrinciples.md" \\
  || miss "missing critical file: docs/DesignPrinciples.md"
test -f "proposals/cli/wit/command.wit" \\
  && ok "proposals/cli/wit/command.wit" \\
  || miss "missing critical file: proposals/cli/wit/command.wit"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 36 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~6d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/WebAssembly/WASI"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

WASI (WebAssembly System Interface) is a standardized set of APIs that enable WebAssembly modules to interact with operating system capabilities like file I/O, environment variables, command-line arguments, and process control. It decouples WASM from any single host implementation, allowing portable system-level code to run across different runtimes. WASI Preview 2, now stable, uses the Wit IDL (Interface Definition Language) for modular, cross-language API definitions. Distributed proposal model: core specifications and discussion live in /proposals (e.g., proposals/cli/ with wit/ and wit-0.3.0-draft/ for versioning), while individual API proposals are maintained in separate external repositories referenced in docs/Proposals.md. Docs are centralized in /docs (e.g., DesignPrinciples.md, Preview2.md). Governance and CI automation sit in /.github (workflows, release scripts, validation scripts for proposals).

WebAssembly runtime implementers (like Wasmtime, WasmEdge), WASM language toolchain maintainers (Rust, Go, C compilers targeting WASM), and system-level library developers building portable WASM components that need OS-like capabilities. Secondary audience: standardization committee members and WASM ecosystem coordinators at the W3C WebAssembly Community Group.

Highly mature and stable. WASI Preview 1 launched years ago and is widely deployed; Preview 2 is now officially stable as documented in docs/Preview2.md. The repository shows active maintenance via GitHub Actions CI/CD pipelines (workflows/ci.yml, workflows/publish.yml), formal release processes (RELEASE.md, release.sh), and governed by W3C subgroup structure. This is production-ready infrastructure for WebAssembly standardization.

Low technical risk but governance-dependent. The codebase is primarily specification documents and WIT interface definitions—not a runtime implementation—so dependency bloat is minimal. Risk factors: proposals are scattered across external repositories (per docs/Proposals.md approach), making cross-proposal consistency harder to enforce; the monorepo structure mixes multiple proposal stages (draft vs. stable), which could lead to confusion about which APIs are production-ready; breaking changes between Preview 1 and Preview 2 already occurred, so future upgrades may require migration work.

Active standardization work on modular APIs using Wit IDL. The /proposals/cli/ directory shows an in-progress command-line interface proposal with both stable (wit/) and draft (wit-0.3.0-draft/) versions, indicating iteration on the spec. GitHub workflows (publish-proposal.yml, release.yml) and validation scripts (validate-proposals.js, validate-since.js) suggest ongoing CI/CD improvements for proposal tracking and release automation. The repo is in active governance mode, not feature development.

git clone https://github.com/WebAssembly/WASI.git
cd WASI
# No build step—this is a specification repository.
# Review docs: cat docs/Preview2.md
# Review proposals: ls -la proposals/

No package manager needed; content is Markdown and Wit interface files. For proposal validation, see .github/scripts/validate-proposals.js (requires Node.js).

Daily commands: This is not a runtime—it's a specification repository. To validate proposals: node .github/scripts/validate-proposals.js. To review specs: read Markdown in docs/ and Wit files in proposals/*/wit/. To build tooling against WASI, use an external runtime (Wasmtime, WasmEdge) and language toolchain targeting WASI.

• README.md — Entry point explaining WASI's purpose, Preview 1 vs Preview 2 distinction, and the transition from witx to Wit IDL—essential for understanding the repo's scope and evolution.
• docs/Proposals.md — Central index of all API proposals and their locations; required reading to navigate the modular proposal structure across the codebase.
• docs/Preview2.md — Definitive reference for the stable WASI Preview 2 specification using the Wit IDL; core documentation for all modern API development in this repo.
• docs/DesignPrinciples.md — Establishes architectural and design philosophy that governs all API proposals; mandatory for understanding why decisions are made the way they are.
• proposals/cli/wit/command.wit — Exemplar Wit IDL definition showing the modern API specification format used across all active proposals; reference for correct syntax and structure.
• .github/scripts/validate-proposals.js — Automation that enforces structural and naming conventions across all proposals; understanding this ensures contributions pass CI validation.
• CONTRIBUTING.md — Governance and contribution workflow for proposing, discussing, and advancing new WASI APIs through the standardization process.

Add a New WASI API Proposal

1. Create a new proposal directory under proposals/ with a README explaining the API's purpose, use cases, and design rationale. (proposals/[api-name]/README.md)
2. Define the Wit IDL interface files in proposals/[api-name]/wit/ (e.g., types.wit, world.wit) following the structure of existing proposals like filesystem. (proposals/[api-name]/wit/world.wit)
3. Create imports.md documenting which APIs this proposal imports and any dependencies on other WASI modules. (proposals/[api-name]/imports.md)
4. Add a test suite README under proposals/[api-name]/test/README.md defining conformance test requirements. (proposals/[api-name]/test/README.md)
5. Update docs/Proposals.md to list the new proposal with its status (e.g., 'Phase 1: Research') and link to its README. (docs/Proposals.md)
6. Add code ownership rules in .github/CODEOWNERS to assign reviewers for your proposal directory. (.github/CODEOWNERS)

Evolve an Existing Proposal from Draft to Stable

1. Create a new wit-[version]-draft/ directory (e.g., wit-0.4.0-draft/) to hold the candidate specification before promotion. (proposals/[api-name]/wit-0.4.0-draft/world.wit)
2. Update the Wit IDL files in the draft directory with breaking or additive changes, ensuring the deps.toml and deps.lock remain consistent. (proposals/[api-name]/wit-0.4.0-draft/deps.toml)
3. Review and update proposals/[api-name]/imports.md to document new dependencies or changed APIs. (proposals/[api-name]/imports.md)
4. Once consensus is reached, promote the draft by copying its contents into proposals/[api-name]/wit/ and update .github/scripts/validate-since.js to verify version transitions. (proposals/[api-name]/wit/world.wit)
5. Update docs/Proposals.md to advance the proposal's status (e.g., from 'Phase 2: Design' to 'Phase 3: Standardization'). (docs/Proposals.md)

Add Conformance Tests for an API Proposal

1. Create test case documentation in proposals/[api-name]/test/README.md listing required behaviors and edge cases. (proposals/[api-name]/test/README.md)
2. In your test implementation (external to this repo), reference the Wit IDL types defined in proposals/[api-name]/wit/ as the contract. (proposals/[api-name]/wit/types.wit)
3. Ensure tests verify compliance with the semantics documented in proposal-specific files like proposals/filesystem/path-resolution.md. (proposals/filesystem/path-resolution.md)
4. Publish test results or reference implementations in the test directory so the community can validate implementations. (proposals/[api-name]/test/README.md)

Update Design Principles or API Governance

1. Document changes to high-level principles (capability-based design, modularity, etc.) in docs/DesignPrinciples.md and align with Preview 2 goals. (docs/DesignPrinciples.md)
2. Update docs/Preview2.md if changes affect how Preview 2 modules compose or how the Wit IDL is used across proposals. (docs/Preview2.md)
3. Revise CONTRIBUTING.md if governance, review, or standardization processes change. (CONTRIBUTING.md)
4. Ensure .github/scripts/validate-proposals.js is updated to enforce any new structural or naming conventions. (.github/scripts/validate-proposals.js)

• Wit IDL (Interface Definition Language) — Successor to witx; provides modular, composable type system and enables code generation across multiple target languages; required for Preview 2 standardization.
• GitHub + GitHub Actions — Industry-standard platform for open-source governance, collaborative design

No typical runtime gotchas (no env vars, no services to run). Key subtleties: (1) proposals/cli/ has both wit/ (stable) and wit-0.3.0-draft/ (draft) directories—easy to edit the wrong one when contributing; (2) Individual proposals live in external repos, so this repo is just a hub—changes here don't affect actual runtimes; (3) Wit version pinning in deps.toml can diverge between proposals, causing inconsistency; (4) The since field in proposal metadata is validated by validate-since.js, so if you add a new proposal, you must set a correct since version or CI will fail.

• Wit IDL (Interface Definition Language) — Wit is the core language for defining WASI APIs in Preview 2; understanding its type system, resource definitions, and async patterns is mandatory for any proposal work.
• Component Model — WASI Preview 2 is built on the WebAssembly Component Model, which enables language-independent composition and virtualization of WASM modules—the architectural foundation of all modern WASI APIs.
• Virtualizability — A core WASI design principle (documented in docs/DesignPrinciples.md) ensuring APIs can be mocked, sandboxed, or redirected by the host—critical for security and testing.
• POSIX Compatibility Layer — WASI's design is heavily influenced by POSIX (as noted in the README), but Preview 2 intentionally diverges for better WASM-native semantics; understanding this tension is key to proposal design.
• Proposal Staging & SemVer — WASI uses a staged approach (draft → stable) with semantic versioning per proposal; the CLI proposal shows both wit/ (stable) and wit-0.3.0-draft/ (versioned draft), requiring clear management of compatibility.
• CloudABI Influence — CloudABI (a POSIX subset for sandboxed execution) heavily influenced WASI's capability-based design; recognizing this heritage helps understand why WASI diverges from full POSIX.
• Resource Handles & Linear Types — Wit's resource system (used heavily in WASI APIs like file handles) relies on linear type semantics to ensure safe cleanup and prevent use-after-free in untrusted WASM code.

• WebAssembly/component-model — Defines the Wit IDL and component model that WASI APIs are built on top of—essential dependency for understanding WASI Preview 2 design.
• bytecodealliance/wasmtime — Production WASM runtime that implements and tests WASI APIs defined in this spec, serving as the reference implementation.
• WebAssembly/wasi-libc — C standard library implementation for WASI that translates POSIX system calls to WASI APIs, bridging legacy code to this interface.
• WebAssembly/wasi-proposal-template — Template repository for new WASI proposals, referenced in CONTRIBUTING.md and the README as the starting point for spec contributors.
• WebAssembly/WASI-cli — External repository for the command-line interface proposal shown in proposals/cli/, demonstrating the distributed proposal workflow this repo coordinates.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test documentation and examples for proposals/cli/test/

The proposals/cli/test/ directory exists but only contains a README.md. There are no actual test files, test fixtures, or example implementations showing how to validate CLI proposal conformance. This is a critical gap for contributors wanting to implement WASI CLI. Adding concrete test cases and example test runners would help implementers validate their runtimes.

• [ ] Review proposals/cli/README.md and command.md to extract testable behaviors
• [ ] Create proposals/cli/test/fixtures/ directory with sample WASI modules and expected outputs
• [ ] Create proposals/cli/test/examples/ with reference test implementations in multiple languages (Rust, C, etc.)
• [ ] Update proposals/cli/test/README.md with step-by-step instructions for running tests
• [ ] Add validation scripts similar to .github/scripts/validate-proposals.js for CLI tests

Sync and document wit-0.3.0-draft versions across all proposals

Both proposals/cli/ and proposals/clocks/ contain wit-0.3.0-draft directories alongside current wit/ directories, but there's no documentation explaining version management, deprecation status, or migration path. Other proposals (filesystem, random, etc.) may be missing this draft versioning entirely. Standardizing this pattern with clear docs would help contributors understand backwards compatibility strategy.

• [ ] Create docs/VersioningStrategy.md explaining the relationship between wit-0.3.0-draft/ and wit/ folders
• [ ] Audit all proposals/ directories to identify which ones are missing wit-0.3.0-draft versions
• [ ] Add a validation script to .github/scripts/ that checks version consistency across proposals
• [ ] Update CONTRIBUTING.md with version management requirements for new proposals
• [ ] Document deprecation timeline for wit-0.3.0-draft in each affected proposal's README.md

Create GitHub Actions workflow for validating WIT file syntax and dependencies across proposals

The repo contains .github/scripts/validate-proposals.js but no corresponding CI workflow that runs on every PR. Each proposal has deps.toml and deps.lock files plus multiple .wit files, but there's no automated validation that these files are syntactically correct or that dependency versions are consistent. This creates risk of broken proposals being merged.

• [ ] Create .github/workflows/validate-wit.yml that runs on pull requests
• [ ] Add validation steps to check all proposals/*/wit/deps.lock match deps.toml
• [ ] Integrate existing .github/scripts/validate-proposals.js into the workflow
• [ ] Add WIT syntax validation using the wac/wit-tools (similar to install-tools/action.yml pattern)
• [ ] Add a step validating that docs/Proposals.md is updated when proposals change

• Add missing .since version field validation to proposals that predate Preview 2—search proposals/*/wit/*.wit for files missing the @since annotation and add it per docs/WitInWasi.md guidance.
• Expand docs/DesignPrinciples.md with concrete code examples showing how each principle (e.g., virtualizability, modularity) manifests in actual Wit definitions from proposals/cli/wit/*.wit.
• Document the version migration path from Preview 1 to Preview 2 in a new docs/Migration.md file, extracting lessons from the wit/ vs wit-0.3.0-draft/ pattern seen in the CLI proposal and linking to external proposal repos.

The WASI repository demonstrates a generally secure posture for a specification/documentation project. No critical vulnerabilities were identified. The codebase primarily consists of specification files (WIT interface definitions), documentation, and CI/CD configuration. No hardcoded secrets, SQL injection risks, or XSS vectors were detected. The repository uses GitHub Actions for CI/CD with automated dependency management via Dependabot. Minor recommendations include ensuring proper access controls on release workflows and maintaining security scanning of any Node.js scripts used in automation. The lack of application code, database interactions, and web-facing components significantly reduces the attack surface.

• Medium · Automated Dependabot Configuration — .github/dependabot.yml. The repository has a .github/dependabot.yml configuration file for automated dependency updates. While this is a good security practice, it should be monitored to ensure that automated updates don't introduce breaking changes or security regressions without proper review. Fix: Ensure that dependabot pull requests are reviewed thoroughly before merging. Consider setting up required reviews and status checks for automated dependency updates.
• Low · Release Script Access Control — .github/scripts/release.sh. The .github/scripts/release.sh script is part of the release workflow and could potentially be used to publish artifacts. Ensure proper access controls are in place for who can trigger releases. Fix: Verify that release workflows have appropriate branch protection rules and that only authorized maintainers can trigger releases. Review the release.yml workflow for proper gating.
• Low · Validation Scripts Dependencies — .github/scripts/validate-proposals.js, .github/scripts/validate-since.js. Node.js validation scripts (validate-proposals.js, validate-since.js) are present but their dependencies are not visible in the provided file structure. These scripts may have transitive vulnerabilities. Fix: Ensure a package-lock.json or similar lockfile is committed and regularly scanned with npm audit or similar tools. Include dependency scanning in CI/CD pipeline.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.