oam

The reliable TypeScript runtime for the AI era.

Fast is table stakes. Reliable is the product.

oam is a JavaScript/TypeScript runtime built in Rust on V8, designed around three ideas:

1. Types-aware execution. oam strips and runs TypeScript instantly (oxc), while a warm TypeScript 7 (tsgo) sidecar streams full type diagnostics concurrently — never blocking execution. Node strips without checking; Bun executes types-blind. oam closes the loop.
2. Reliability with receipts. Public conformance dashboards (Node's own test suite, WinterTC ECMA-429, WPT), soak farms, crash-rate telemetry, a behavior-change log on every release, and an LTS commitment. Claims come with reproducible numbers or they don't ship.
3. Built for the AI era, owned by no model vendor. Every diagnostic oam emits — parse, type, resolve, runtime, test, install — is ODIF: structured JSON with stable codes and source spans that agents consume directly (and humans see pretty-printed from the same stream). Typed repair plans are the design goal: the envelope reserves a repairs field, but nothing populates it yet. Today oam ships an MCP server (oam mcp) that checks, runs and explains code for agents, Node's permission model as an opt-in sandbox (--permission plus --allow-* grants; a run without it is all-granted, as in Node), and oam.fork(), a pool of pre-warmed isolates for parallel eval loops — not checkpoint/restore of a running isolate.

Status

Beta. Breaking changes before 1.0 are still possible and are called out in CHANGELOG.md; there is no LTS yet, so security fixes land on the latest release only — SECURITY.md says how they are disclosed. npm resolution against existing node_modules, CommonJS interop, the node: builtins (fs, path, process, Buffer, events, util, assert, os, tty, module, stream, http, async_hooks — AsyncLocalStorage rides V8's continuation-preserved embedder data), TypeScript and JSX/TSX without a build step, node:vm on real V8 contexts including vm.SourceTextModule, node's permission model (--permission plus the --allow-* grants), and oam test (fresh isolate per file, mocking + fake timers). Real packages run unmodified: zod, lodash, ms, chalk, debug, semver, @opentelemetry/context-async-hooks, eventsource-parser, split2, jsonwebtoken, etag, uuid.

Receipts, all generated and regenerated by the CI gate (scripts/ci-local.sh), never hand-edited:

• CONFORMANCE-NODE.md — a vendored subset of Node's own test suite. 439/442 pass-over-runnable (99.3%) on windows-aarch64, the host of the receipt committed here; the scorecard is regenerated per host, so a checkout built elsewhere reports its own. Read it with docs/node-divergences.md, which qualifies the denominator and lists what oam deliberately does differently — all three remaining failures are deliberate and named there.
• CONFORMANCE.md — WPT URL percentages, a Node differential suite (same script, both runtimes, byte-identical stdout), and builtin surface coverage.

See ROADMAP.md, docs/why-oam.md (how oam compares to Node, Deno and Bun, and when to pick one of those instead), and docs/cli-reference.md (commands, Node-compat flags, environment variables).

oam run hello.ts        # strip + execute instantly, types stream concurrently
oam test                # *.test.ts in fresh isolates, ODIF output for agents
oam check               # tsgo type-check with a warm daemon

Installing

curl -fsSL https://oamjs.org/install.sh | sh       # Linux / macOS
irm https://oamjs.org/install.ps1 | iex            # Windows

Both installers pick the binary for your OS/arch, verify the release, and install per-user (~/.oam/bin, %LOCALAPPDATA%\oam\bin) — no sudo, no admin. oam self-update updates in place with the same checks.

From v0.18.0 every release carries a RELEASE-MANIFEST signed with oam's release key (fingerprints in SECURITY.md). Both installers and oam self-update verify that signature and take the binary's checksum from the signed manifest. The installers need an ssh-keygen with -Y (OpenSSH 8.1+) for this. Releases before v0.18.0 are checked against pinned SHA256SUMS digests. The Windows binaries are Authenticode-signed (publisher "Yaw Labs LLC"). The macOS binaries are signed with oam's own pinned, self-signed identity, not Apple Developer ID, and are not notarized: Gatekeeper still blocks a browser download, while curl and brew installs are unaffected. install/README.md has the details.

Knobs: OAM_VERSION pins a tag, OAM_INSTALL_DIR moves the target directory, OAM_GH_API points at a GitHub Enterprise host, OAM_INSECURE_SKIP_SIGNATURE=1 installs on a host with no usable ssh-keygen, without checking the signature.

Building

Rust stable (see rust-toolchain.toml). Five targets have shipped binaries: windows-x64, windows-arm64, macos-x64, macos-arm64, linux-x64. linux-arm64 builds from the same tree but has never been released — the V8 snapshot forbids cross-compiling, so it needs a native ARM Linux builder, and the installer refuses that target by name rather than guessing.

cargo build --workspace
cargo test --workspace

Architecture (short version)

• crates/oam_engine — the only crate that touches V8 (rusty_v8). Isolates, snapshots, code cache.
• crates/oam_core — event loop, op system, Promise<->Future bridge.
• crates/oam_diagnostics — ODIF, the diagnostic envelope everything else speaks.
• crates/oam_cli — the oam binary.
• xtask — repo automation (V8 bump bot, snapshot rebuilds, packaging).

Wider layout (loader, web/node compat, http, test runner, package manager, sandbox, tsgo sidecar, inspector) lands per the roadmap; crates are created when their workstream starts.

Governance

• License: Apache-2.0, forever. Contributions under DCO; no CLA. Apache-2.0 rather than MIT (or an MIT/Apache dual) is deliberate: oam is a VM, and Apache's §3 patent grant with defensive termination binds every user. A dual license would let a patent aggressor elect the MIT arm and keep its rights — and it would buy nothing in return, since several Apache-2.0-only crates (ring, sync_wrapper, self_cell) are statically linked, so the shipped binary can never be GPLv2-compatible regardless.
• Attribution: THIRD_PARTY_LICENSES.md reproduces the notices for the ~380 Rust crates linked into the binary, generated by cargo about generate about.hbs -o THIRD_PARTY_LICENSES.md and drift-gated by CI. NOTICE carries everything that tool cannot see: V8 itself, the 16 third-party trees bundled inside the prebuilt V8 static library (ICU, abseil, highway, libc++ and the rest), the vendored Node.js sources, and the vendored web-platform-tests data. None of those appear in the cargo graph — the v8 crate declares itself MIT, which covers only its Rust bindings — so that section is hand-maintained and must be revisited on a V8 bump.
• GOVERNANCE.md — the oam Covenant, foundation triggers, succession.
• AI-POLICY.md — oam is heavily AI-developed, with identical review gates for human and AI changes, enforced changeset limits, and published provenance. The mega-merge failure mode is structurally impossible here, by policy and by CI.
• RELIABILITY.md — the scorecard: what we measure, publish, and gate on.

Domain: https://oamjs.org — the installer and update channel serve from there exclusively. It also carries the pages the binary itself links to: debugging with the inspector, the diagnostic code reference that every --json diagnostic points at, and the ODIF envelope. Everything else lives here, beside the code it describes.

Distribution: the install script is canonical. An npm package is planned under @yawlabs/oam — that name is not published yet, so install via the script above (bare oam on npm belongs to an unrelated project).