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, runtime, test, install — is ODIF: structured JSON with stable codes and typed repair plans that agents consume directly (and humans see pretty-printed from the same stream). Sandboxed-by-default agent execution, an MCP server into the runtime's introspection, and checkpoint/fork primitives for parallel eval loops.

Status

Beta. Breaking changes before 1.0 are still possible and are called out in CHANGELOG.md; there is no LTS yet. 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 it against the published SHA256SUMS, and install per-user (~/.oam/bin, %LOCALAPPDATA%\oam\bin) — no sudo, no admin. Binaries are unsigned and checksummed. oam self-update re-runs the same installer.

Knobs: OAM_VERSION pins a tag, OAM_INSTALL_DIR moves the target directory, OAM_GH_API points at a GitHub Enterprise host.

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).