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/bytecodealliance/lucet 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 all four use cases

• 15 active contributors
• Distributed ownership (top contributor 32% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 4y ago

_{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 bytecodealliance/lucet repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/bytecodealliance/lucet.

What it runs against: a local clone of bytecodealliance/lucet — 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 bytecodealliance/lucet | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | 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 ≤ 1536 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of bytecodealliance/lucet. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/bytecodealliance/lucet.git
#   cd lucet
#
# 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 bytecodealliance/lucet and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 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 "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "lucet-module/src/lib.rs" \\
  && ok "lucet-module/src/lib.rs" \\
  || miss "missing critical file: lucet-module/src/lib.rs"
test -f "lucet-runtime/lucet-runtime-internals/src/lib.rs" \\
  && ok "lucet-runtime/lucet-runtime-internals/src/lib.rs" \\
  || miss "missing critical file: lucet-runtime/lucet-runtime-internals/src/lib.rs"
test -f "lucetc/src/lib.rs" \\
  && ok "lucetc/src/lib.rs" \\
  || miss "missing critical file: lucetc/src/lib.rs"
test -f "lucet-wasi/src/lib.rs" \\
  && ok "lucet-wasi/src/lib.rs" \\
  || miss "missing critical file: lucet-wasi/src/lib.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1536 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1506d)"
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/bytecodealliance/lucet"
  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).

Lucet is a native WebAssembly compiler and runtime that safely executes untrusted WebAssembly programs through ahead-of-time (AOT) compilation and sandboxing. It powers Fastly's Compute@Edge platform and uses Bytecode Alliance's Cranelift code generator as its core compilation engine. Monorepo structure with Cargo workspace: lucet-runtime (core sandboxing runtime, lucet-runtime-internals, lucet-runtime-macros), lucetc (AOT compiler CLI), lucet-wasi (WebAssembly System Interface bindings), lucet-wiggle (interface generator), lucet-module (compiled artifact format), plus benchmarks/lucet-benchmarks and fuzzing/concurrency test suites. Heavy Rust codebase (1.1M lines) with embedded C (49K) and WebAssembly (35K).

Fastly engineers, edge computing developers, and security-conscious platform builders who need to execute untrusted WebAssembly code with strong isolation guarantees and predictable performance characteristics.

This project has reached end-of-life status (as stated in README). While it was production-grade at Fastly and features mature CI/CD (CircleCI, GitHub Actions, comprehensive Makefile automation), active maintenance has ceased as the team transitioned to Wasmtime. The codebase is stable but no longer receiving feature development or security updates.

This is an EOL project—using it for new systems is not recommended since the maintainers have officially migrated to Wasmtime and ceased maintenance. The monorepo has complex interdependencies across 14 workspace members (lucet-runtime, lucetc compiler, lucet-wasi, etc.), and any encountered issues will not receive upstream fixes. Legacy Cranelift dependency may also become outdated.

Nothing—project is in maintenance mode post-EOL declaration. No active development, PRs, or milestones are visible. The last activity was transitioning users to Wasmtime and documentation remains static.

Clone: git clone --recursive https://github.com/bytecodealliance/lucet && cd lucet. Install Rust via rustup (required for workspace). Build compiler: cargo build --release -p lucetc. Run tests: cargo test (note: profile.test sets rpath=true for runtime linking).

Daily commands: For development: make build (wraps cargo build). For compiler CLI: cargo run -p lucetc -- --help. For benchmarks: cd benchmarks/lucet-benchmarks && cargo bench. No dev server (native compiler, not web-based). Runtime examples in docs/lucet-runtime-example/src/main.rs.

• Cargo.toml — Workspace root defining all 17 member crates including the compiler (lucetc), runtime, and WASI integration—essential for understanding the monorepo structure.
• lucet-module/src/lib.rs — Core abstraction for compiled WebAssembly modules; all code execution flows through module metadata, function tables, and memory layout definitions.
• lucet-runtime/lucet-runtime-internals/src/lib.rs — Runtime sandbox implementation managing instance isolation, memory pooling, and safe execution of untrusted WASM code.
• lucetc/src/lib.rs — AOT compiler frontend orchestrating Cranelift IR generation, codegen, and module serialization for pre-compiled WASM binaries.
• lucet-wasi/src/lib.rs — WASI syscall bindings layer enabling guest WASM programs to safely interact with host OS resources.
• README.md — Critical context: declares Lucet end-of-life status and directs users to Wasmtime—shapes all architectural decisions and maintenance assumptions.
• .cargo/config — Cargo workspace configuration controlling link behavior, optimization levels, and platform-specific build rules for sandboxing.

Add a new WASI syscall binding

1. Define syscall signature in a .witx file in the lucet-wiggle specifications directory (reference: lucet-wiggle/macro/Cargo.toml) (lucet-wiggle/generate/src/lib.rs)
2. Implement the host-side syscall handler function in lucet-wasi, following the pattern of existing fd_read/fd_write implementations (lucet-wasi/src/lib.rs)
3. Register the new syscall in the WASI context's hostcall table by updating the export_wasi_host_calls! macro invocation (lucet-runtime/lucet-runtime-internals/src/lib.rs)
4. Add integration test in lucet-wasi to verify guest can invoke the syscall safely and host resources are properly restricted (lucet-wasi/tests/)

Add a new compiler optimization pass

1. Create new Cranelift IR transformation in lucetc, following the existing pass structure (reference: lucetc/src/lib.rs optimization pipeline) (lucetc/src/lib.rs)
2. Register the pass in the compilation pipeline ordering (emit phase or between IR lowering stages) (lucetc/src/lib.rs)
3. Add unit tests validating the IR transformation on synthetic WASM modules (lucetc/tests/)
4. Benchmark the optimization impact using lucet-benchmarks criterion suite (benchmarks/lucet-benchmarks/benches/benchmarks.rs)

Extend module metadata for custom data storage

1. Add new struct field to the Module definition in lucet-module/src/lib.rs with serialization support (lucet-module/src/lib.rs)
2. Update the module serialization format version and implement forward compatibility in the bincode deserialization layer (lucet-module/src/lib.rs)
3. Populate the new field during compilation in lucetc by extracting data from Cranelift IR or WASM analysis (lucetc/src/lib.rs)
4. Expose the metadata through runtime Instance API for guest introspection if needed (lucet-runtime/lucet-runtime-internals/src/lib.rs)

• Cranelift IR — Multi-backend compiler framework enabling portable, optimized code generation across x86_64, ARM, and other ISAs while maintaining safety invariants.
• Rust + unsafe blocks (audited) — Memory safety at the language level with carefully-controlled unsafe code for sandboxing primitives, reducing attack surface vs. pure C implementations.
• WASI (WebAssembly System Interface) — Standardized syscall ABI enabling guest portability and host resource access control without guest code modification.
• Pooling allocator (userfaultfd) — Pre-allocated, reusable memory pools with lazy fault-driven commitment reduce allocation latency and enable isolation guarantees.
• Bincode serialization — Efficient, versioned binary format for compiled modules enabling fast loading and metadata preservation across compile/runtime boundary.

• AOT compilation over JIT

  • Why: Lucet chose ahead-of-time compilation to eliminate code generation latency and provide deterministic security boundaries.
  • Consequence: Slower deployment of new code (must recompile), but faster instance startup and no runtime code cache attacks.

• Single-threaded instance execution model

  • Why: Simplifies memory isolation guarantees and eliminates need for fine-grained locking within sandbox.
  • Consequence: Multi-threaded guest workloads require coordination through host; limits horizontal scaling within a single instance.

• Linear memory-only WASM support

  • Why: Aligns with practical security model of pre-allocation and simplifies host resource accounting.
  • Consequence: Incompatible with bulk-memory and multi-memory WASM proposals; users must link modules that fit single linear memory.

• End-of-life in favor of Wasmtime

  • Why: Wasmtime reached feature parity (AOT, pooling allocator) and has broader community support.
  • Consequence: No new feature development; users must migrate, but codebase remains usable for reference implementation study.

• JIT compilation or dynamic code generation at runtime
• Multi-threaded instance execution (single-threaded sandbox model)
• Support for WASM proposals beyond core spec (bulk memory, multi-memory, reference types)
• Cross-platform module compatibility beyond x86_64/ARM64 (architecture-specific codegen)
• Active maintenance or security updates (end-of-life project, migrate to Wasmtime)

EOL status is the biggest trap—this codebase will not receive updates. Workspace requires --recursive clone for submodules (see .gitmodules). The Cranelift dependency is pinned in Cargo.lock and may diverge from upstream. userfaultfd sandboxing is Linux-specific (no native macOS/Windows support despite CI running on mac-ci.yml—unclear if runtime fully functional there). The lucet-wasi-sdk requires Clang/LLVM toolchain beyond standard rustup. Profile.test rpath=true is essential for runtime integration tests—omitting it breaks linkage.

• Ahead-of-Time (AOT) Compilation — Lucet's core differentiation—compiling WASM to native code at deploy time rather than runtime; critical for understanding performance vs. JIT tradeoffs.
• WebAssembly Sandboxing via Memory Isolation — Lucet uses pooled memory regions and userfaultfd to prevent untrusted code from accessing host memory; understanding this is essential for security model.
• Cranelift Intermediate Representation (IR) — Lucetc compiles WASM to Cranelift IR before native code generation; knowledge of IR lowering helps debug codegen bugs.
• userfaultfd Pooling Allocator — Lucet's memory allocator uses Linux userfaultfd to catch out-of-bounds WASM memory accesses; understanding fault handling is critical for runtime security.
• WASI (WebAssembly System Interface) — Lucet's lucet-wasi module implements WASI, giving WASM programs access to OS resources; essential for understanding hostcall architecture.
• Procedural Macros for Code Generation — Lucet-wiggle uses Rust procedural macros to generate hostcall stubs from interface specifications; required for extending WASI bindings.
• Artifact Serialization Format — Lucet-module defines a binary format for storing AOT-compiled WASM; understanding this enables tooling around compiled artifacts (lucet-objdump).

• bytecodealliance/wasmtime — Official successor to Lucet; Lucet maintainers explicitly migrated here and Wasmtime now includes AOT and pooling allocator features Lucet pioneered.
• bytecodealliance/cranelift — Underlying code generation engine used by Lucet's compiler backend; required for understanding IR lowering and optimization passes.
• WebAssembly/wasi — WASI specification that Lucet implements via lucet-wasi; defines host function ABI for system calls.
• fastly/lucet-specs — Fastly's test suite and spec compliance repository for Lucet; reference implementation for behavioral correctness.
• bytecodealliance/wasm-micro-runtime — Alternative lightweight WebAssembly runtime in the same ecosystem; useful for comparing design tradeoffs against Lucet's AOT approach.

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 integration tests for lucet-wasi module

The lucet-wasi and lucet-wasi-fuzz directories exist but there are no visible test files in the partial file structure. Given that WASI (WebAssembly System Interface) is critical for real-world WebAssembly applications and Lucet's positioning as a sandboxing compiler, adding thorough integration tests would catch regressions and document expected behavior. This is especially important for an EOL project where existing users need confidence in stability.

• [ ] Create tests/integration.rs or tests/ directory under lucet-wasi/
• [ ] Add tests covering core WASI syscall implementations (file I/O, process control, environment variables)
• [ ] Add tests for lucet-wasi-fuzz to ensure fuzzing targets remain valid
• [ ] Document expected WASI compliance level in docs/src/
• [ ] Ensure tests run in CI via .github/workflows/main.yml

Create architecture documentation for lucet-wiggle code generation system

The lucet-wiggle directory structure shows macro and generate subdirectories (lucet-wiggle/macro and lucet-wiggle/generate), indicating a sophisticated code generation system, but there is no corresponding documentation file (e.g., docs/src/lucet-wiggle.md). New contributors and maintainers need to understand how the wiggle bindings generator works. This is a high-value doc-first contribution that unblocks future maintenance.

• [ ] Create docs/src/lucet-wiggle.md documenting the wiggle macro system
• [ ] Explain how lucet-wiggle/macro and lucet-wiggle/generate interact
• [ ] Add examples showing how to use wiggle for custom host function bindings
• [ ] Link the new doc into docs/src/SUMMARY.md
• [ ] Cross-reference from docs/src/Lucet-components.md

Add missing CI workflow for fuzz target validation

The .github/workflows/fuzz.yml.disabled file exists but is disabled, suggesting fuzzing is not currently validated in CI. Given that lucet-wasi-fuzz and fuzz/ directories are part of the workspace, re-enabling or creating a proper fuzzing workflow would catch crashes and panics early. For an EOL project, keeping fuzzing disabled risks letting security issues slip through undetected in downstream usage.

• [ ] Review .github/workflows/fuzz.yml.disabled to understand why it was disabled
• [ ] Create or re-enable .github/workflows/fuzz.yml with clear fuzzing targets
• [ ] Configure fuzzing to run against lucet-wasi-fuzz and fuzz/ crates with reasonable timeout/iteration limits
• [ ] Ensure fuzzing artifacts (crashes, slow inputs) are captured and reported
• [ ] Add documentation in SECURITY.md about how to report fuzz-discovered issues

• Document the userfaultfd memory allocator architecture in lucet-runtime/lucet-runtime-internals/src/alloc.rs with inline diagrams explaining the pooling strategy; the code lacks clarity on how fault handling prevents escapes.
• Add missing integration tests for lucet-wiggle macro expansion—currently only unit tests exist; test the generated hostcall stubs against actual WASM modules calling them.
• Create a 'migration guide' documentation file mapping Lucet APIs to Wasmtime equivalents for the 3 most common use cases (instance creation, memory access, hostcall definition) since users cannot just drop-in replace the dependency.

The Lucet project presents significant security concerns primarily due to its end-of-life status with ceased maintenance. Users face unpatched vulnerabilities with no active security response capability. Additionally, the project uses outdated compiler toolchain versions (LLVM/Clang 6.0 from ~2018) containing known security issues. The Docker configuration uses non-pinned base images, which may pull updates unpredictably. For a WebAssembly sandbox compiler—a security-critical component—the lack of active maintenance is a critical issue. Users must urgently migrate to Wasmtime or other actively maintained alternatives. The codebase itself may be well-designed, but the operational security posture is severely compromised by the EOL status

• High · End-of-Life Project with No Active Maintenance — README.md, project status. Lucet has reached end-of-life status as stated in the README. Maintenance has ceased, and all users are directed to migrate to Wasmtime. Using an unmaintained WebAssembly compiler/runtime presents significant security risks including unpatched vulnerabilities, lack of security updates, and no incident response. Fix: Migrate to Wasmtime or another actively maintained WebAssembly runtime. If continued use is necessary, conduct a comprehensive security audit and implement a robust patch management strategy for identified vulnerabilities.
• Medium · Outdated Compiler Toolchain in Docker — Dockerfile, lines: clang-6.0, llvm-6.0. The Dockerfile pins clang-6.0 and llvm-6.0, which are significantly outdated (released ~2018). These versions contain multiple known security vulnerabilities and lack modern security features. The fixed versions provide no automatic security updates. Fix: Update to the latest stable versions of LLVM and Clang. Use a version management strategy that allows for regular security updates without requiring manual Dockerfile modifications.
• Medium · Loose Base Image Tag — Dockerfile, line 1: FROM ubuntu:focal. The Dockerfile uses 'ubuntu:focal' which refers to Ubuntu 20.04 LTS. While LTS, the tag doesn't specify a patch version, potentially pulling updates with behavioral changes. For a security-sensitive compiler, reproducible builds are important. Fix: Use specific base image digests (e.g., ubuntu:focal@sha256:...) or at minimum specify a specific date-based tag to ensure reproducible builds and control over security patch timing.
• Medium · Potential Dependency Vulnerabilities - Transitive Dependencies Not Visible — Cargo.toml, all workspace members. The Cargo.toml workspace structure shows 17 member crates, but without visibility into all transitive dependencies, there may be vulnerable crates pulled in as transitive dependencies. The Cargo.lock exists but was not provided for analysis. Fix: Run 'cargo audit' regularly to identify vulnerable dependencies. Implement automated dependency scanning in CI/CD pipeline. Review Cargo.lock periodically for outdated crates and use 'cargo update' carefully with security testing.
• Low · Documentation References Outdated Security Policy Link — SECURITY.md. SECURITY.md references external Bytecode Alliance security policy page. While appropriate, there's no fallback or detailed local security policy, and the project is EOL, so vulnerability reports may not be handled. Fix: For an EOL project, update SECURITY.md to clearly state the project is no longer maintained and provide explicit guidance that security issues should be reported to Wasmtime instead. Maintain a clear timeline for security support.
• Low · Multiple Redundant Environment Variable Declarations — Dockerfile, lines 3 and 5. The Dockerfile sets 'ENV DEBIAN_FRONTEND=noninteractive' twice identically, indicating possible merge errors or incomplete cleanup in maintenance. Fix: Remove duplicate environment variable declaration and consolidate to a single declaration for clarity and best practices.
• Low · Missing Security Headers Documentation — docs/src/Security.md (referenced but not provided), security documentation. No explicit documentation of security features, threat model, or security-relevant design decisions visible in provided files. For a sandboxing WebAssembly compiler, detailed security documentation is important. Fix: Ensure comprehensive security documentation exists covering: threat model, security guarantees, sandbox boundary definitions, and any known limitations. Update this documentation to reflect EOL status.

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.