AGENTS.md — wysm

the doctrine of the home is ~/cyber/AGENTS.md; it applies here first. Claude Code receives both files at session start through ~/.config/cyber/agents-md.nu; other agents read them in order.

principles for working with AI coding agents on the cyber wysm runtime. read this and the foundational documents to have full context:

• cyberia/engineering — pipeline contracts, dual-stream optimization, verification dimensions
• cyberia/quality — 12 review passes, severity tiers, audit protocol
• cyberia/projects — repo layout, namespace conventions, git workflow
• cyberia/documentation — Diataxis framework, reference vs docs, spec before code

auditor mindset

the project is supervised by an engineer with 30 years of experience. deception does not work. never fake results, never substitute "looks correct" for "is correct". one time correctly is cheaper than five times beautifully.

what this repo is

a hard fork of wasmi v2.0.0-beta.2 (commit a8f6d806), extended with four cyber-native enhancements: jet substitution, finite-wasm metering, an actor harness, and a trident-lowering on-ramp. the runtime cyb embeds to execute conventional WebAssembly programs (souls) loaded from radio.

wysm is cyber's name for the runtime. wasm/WASM is the WebAssembly format. wasmi is the upstream project. cyber-side crates use the wysm- prefix; upstream crates keep their wasmi_* names.

see specs/wysm.md for the full design.

companion repos

upstream tracking

origin is wasmi-labs/wasmi as the upstream remote. cyber-specific commits live on main. merge upstream releases as their own commits; never rebase to hide divergence.

git fetch upstream
git merge upstream/main

document non-trivial divergence in specs/patches.md.

do not touch zones

• Cargo.toml workspace dependency versions — discuss before changing
• crates/wasmi/, crates/wasmi_ir/, crates/wasmi_core/, crates/wasmi_collections/ — upstream code. modify only when adding a jet hook or metering hook; document the patch in specs/patches.md
• LICENSE-APACHE, LICENSE-MIT — preserve dual-license attribution
• specs/ — canonical spec, change there first then propagate to code

cyber-specific code lives in new crates: crates/wysm-jet, crates/wysm-meter, crates/wysm-harness, crates/wysm-trident. additions to these are free.

git workflow

• atomic commits — one logical change per commit
• conventional prefixes: feat:, fix:, refactor:, docs:, test:, chore:
• never amend upstream-derived commits — keep the upstream lineage clean for merge tooling
• commit on completion; do not wait for the user to say "commit"

build matrix

cargo build --no-default-features --features unstable     # tier-1
cargo build --no-default-features --features portable-dispatch  # tier-2

shell: nushell

use nu -c '...' or nu script.nu for scripting. reserve bash for git.

testing

• unit tests in the crate they test (#[cfg(test)])
• integration tests for new crates go in crates/<crate>/tests/
• differential tests for jets — every jet is tested against its reference wasm implementation over a corpus. mismatches are CI errors, not silent fallback
• benchmark against upstream wasmi on every PR — regressions in dispatch throughput are bugs