# Compatibility & scope (Amber v1.17.0)

> What Amber v1.17.0 supports: Stable contracts, Preview and Experimental surfaces, and deliberate non-goals, mirrored from docs/CURRENT_SCOPE.md.

HTML: https://amberjs.com/compatibility · Index for agents: https://amberjs.com/llms.txt

Source of truth: [docs/CURRENT_SCOPE.md](https://github.com/zh30/amberjs/blob/main/docs/CURRENT_SCOPE.md). If this page and that file disagree, the file wins.

- Stable contracts: G1–G69 (some rows group several ids; some are marked tentative or provisional).
- Node conformance scorecard: **56/56 PASS** ([scorecard](https://github.com/zh30/amberjs/blob/main/tests/conformance/scorecard.md)). CI fails if fewer than 55 pass or any fixture fails or is skipped. A passing fixture is a regression gate; it does not by itself make an API Stable.
- Performance: Amber publishes no current performance numbers. Older benchmark tables in the repository are historical.

## Stable

Pinned by a contract document and an executable CI test. Limits are listed next to each API; anything not listed is not promised.

### CLI & tooling

| Capability | API | Id | Limits | Contract |
| :--- | :--- | :--- | :--- | :--- |
| amber run / eval / repl | `amber run <file> · amber eval <code> · amber repl` | base scope | V8 execution through runtime_minimal; repl is the basic shell. | — |
| amber test | `amber test [files...]` | base scope | Jest-style describe / test / expect with discovery. --parallel exits 2. | — |
| amber bundle | `amber bundle <entry>` | G1 | oxc IIFE bundle; static import/require only; not webpack/esbuild parity. | [BUNDLE_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/BUNDLE_CONTRACT.md) |
| amber compile | `amber compile <entry> -o <bin>` | G2 | Host single-executable on Linux/macOS/Windows; no cross-compile, no native addons. | [COMPILE_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/COMPILE_CONTRACT.md) |
| amber install | `amber install [--frozen-lockfile]` | G3 | Direct deps from package.json with lockfile pins and SRI checks; not npm/yarn/pnpm. | [INSTALL_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/INSTALL_CONTRACT.md) |
| amber run --export-tools | `amber run --export-tools <file>` | G4 | Prints tool schemas as JSON and exits; never executes the file or calls a model. | [EXPORT_TOOLS_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/EXPORT_TOOLS_CONTRACT.md) |
| amber run --inspect | `--inspect · --inspect-brk · --inspect-port` | G5 | CDP subset on 127.0.0.1 (Runtime.evaluate); no breakpoints or stepping. | [INSPECT_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/INSPECT_CONTRACT.md) |
| --watch | `amber run --watch · amber test --watch` | G6 | Full re-exec on change plus a localhost reload WebSocket; not in-place HMR. | [WATCH_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/WATCH_CONTRACT.md) |
| amber serve | `amber serve [--port] [script]` | G41 | HTTP/1.1 health document or fetch-handler bridge; one request per connection. | [SERVE_HTTP_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/SERVE_HTTP_CONTRACT.md) |
| amber serve --https | `amber serve --https --cert --key` | G7 | rustls TLS, HTTP/1.1 only; no HTTP/2, keep-alive, chunked bodies or static files. | [SERVE_HTTPS_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/SERVE_HTTPS_CONTRACT.md) |
| TypeScript / TSX | `.ts · .tsx · .mts · .cts · .jsx` | G36 | oxc transpile-only with .ts stack remap; not tsc — no type-checking. | [TYPESCRIPT_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/TYPESCRIPT_CONTRACT.md) |
| amber session / amber mcp | `amber session <tools> · amber mcp <tools>` | base scope | Agent tool execution over stdin JSON-RPC and an MCP stdio server. | — |
| amber snapshot | `amber snapshot [build\|status\|clean]` | base scope | Manage V8 startup snapshots with mmap backing. | — |

### Runtime

| Capability | API | Id | Limits | Contract |
| :--- | :--- | :--- | :--- | :--- |
| Capability sandbox | `--sandbox · --allow-* · --permission-policy · --audit-log` | base scope | Deny-by-default fs/net/env/run with exact allows and a JSONL audit trail. | — |
| Deterministic execution | `--seed <u64> · --freeze-time <spec>` | base scope | Seeded Math.random / getRandomValues and a frozen virtual clock. | — |
| amber:ai | `Tensor · LLM · AgentPipeline` | base scope | In-process TypedArray tensors, local streaming LLM, pipelines. Cargo feature "ai" is empty. | — |
| WebAssembly streaming | `WebAssembly.compileStreaming · instantiateStreaming` | base scope | V8 Wasm; streaming compile from Response. amber:wasm zero-copy helpers are Preview. | — |
| WinterTC baseline | `DOMException · URLPattern · navigator · amber:sockets · import.meta` | base scope | ECMA-429 minimum common API, wintertc export conditions, TCP + rustls sockets. | — |

### Node.js APIs

| Capability | API | Id | Limits | Contract |
| :--- | :--- | :--- | :--- | :--- |
| CommonJS require | `require · module · require.resolve · createRequire` | G28 (provisional) | node_modules walk, package.json exports/imports/main; not the Node Module class. | [REQUIRE_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/REQUIRE_CONTRACT.md) |
| fs | `fs · fs/promises` | G8 | Byte I/O, mkdir, stat, fds, readdir dirents, promises; no glob / cp / opendir / statfs. | [FS_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/FS_CONTRACT.md) |
| fs.watch / fs.watchFile | `fs.watch · fs.watchFile · fs.unwatchFile` | G64 (tentative) | Real OS watcher (notify) and stat polling; no fs.promises.watch. | [FS_WATCH_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/FS_WATCH_CONTRACT.md) |
| path | `path · path.posix` | G17 | POSIX semantics; path.win32 methods are the POSIX implementations. | [PATH_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/PATH_CONTRACT.md) |
| events | `EventEmitter · once` | G18 | Full listener API and static once; no events.on async iterator. | [NODE_EVENTS_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/NODE_EVENTS_CONTRACT.md) |
| buffer | `Buffer` | G19 | from / alloc / concat / toString / slice; readUInt* and compare are outside. | [BUFFER_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/BUFFER_CONTRACT.md) |
| os | `platform · arch · cpus · tmpdir · homedir …` | G20 | Host info subset; cpus()[].speed / times are outside. | [OS_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/OS_CONTRACT.md) |
| os.hostname | `os.hostname()` | G62 | Real gethostname / GetComputerNameW; not a DNS FQDN. | [OS_HOSTNAME_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/OS_HOSTNAME_CONTRACT.md) |
| os.networkInterfaces | `os.networkInterfaces()` | G63 | Real OS enumerator; MAC is best-effort. | [OS_NETWORK_INTERFACES_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/OS_NETWORK_INTERFACES_CONTRACT.md) |
| zlib (sync) | `gzipSync · deflateSync · inflateRawSync …` | G21 | Six sync codecs; no brotli, no zlib.constants. | [ZLIB_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/ZLIB_CONTRACT.md) |
| zlib (async callbacks) | `gzip · gunzip · deflate · inflate · deflateRaw · inflateRaw` | G48 · G58 (tentative) | Callbacks on a later tick; no streaming createGzip family. | [ZLIB_ASYNC_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/ZLIB_ASYNC_CONTRACT.md) |
| util | `format · inspect · promisify · callbackify · types` | G22 · G59 | Basics plus util.types.isArrayBuffer / isRegExp; inspect ignores depth / colors. | [UTIL_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/UTIL_CONTRACT.md) |
| process | `nextTick · env · cwd · stdout.write · hrtime · memoryUsage` | G22 · G44 · G53 · G54 | Basics only; hrtime is epoch-based, heap numbers are estimates; exit / stdin stay Preview. | [PROCESS_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/PROCESS_CONTRACT.md) |
| crypto | `createHash · createHmac · randomBytes · randomUUID · timingSafeEqual` | G23 | md5 / sha* / blake3 digests; KDF, sign/verify and KeyObject stay Preview. | [NODE_CRYPTO_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/NODE_CRYPTO_CONTRACT.md) |
| crypto cipheriv | `createCipheriv · createDecipheriv (AES-CBC / GCM / CTR)` | G43 · G51 · G52 | AES-128/192/256 CBC, GCM (auth tag, AAD) and CTR; no password createCipher. | [NODE_CRYPTO_CIPHERIV_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/NODE_CRYPTO_CIPHERIV_CONTRACT.md) |
| stream | `Readable · Writable · PassThrough · pipe` | G24 | Flowing push / pipe; no backpressure. Transform / Duplex / pipeline stay Preview. | [NODE_STREAM_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/NODE_STREAM_CONTRACT.md) |
| child_process (sync) | `execSync · spawnSync` | G25 | Sandbox-aware; no timeout / cwd / env options. | [CHILD_PROCESS_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/CHILD_PROCESS_CONTRACT.md) |
| child_process (async) | `exec · execFile · spawn` | G47 · G60 (tentative) | Captured output via callback on a later turn; no live stdio pipes. | [CHILD_PROCESS_ASYNC_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/CHILD_PROCESS_ASYNC_CONTRACT.md) |
| child_process.fork | `fork · child.send · process.send` | G67 (tentative) | Real OS process with JSON IPC over localhost TCP. | [CHILD_PROCESS_FORK_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/CHILD_PROCESS_FORK_CONTRACT.md) |
| url | `fileURLToPath · pathToFileURL` | G26 | POSIX file URL helpers; legacy parse / format are outside. | [NODE_URL_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/NODE_URL_CONTRACT.md) |
| dns | `lookup · resolve4 · resolve6 · reverse · getServers` | G27 · G65 (provisional) | Host getaddrinfo / getnameinfo, sync; no dns.promises or setServers. | [DNS_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/DNS_CONTRACT.md) |
| http (server) | `http.createServer · listen · req / res` | G37 (tentative) | Buffered responses; the http client, Agent, https and http2 are not supported. | [HTTP_SERVER_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/HTTP_SERVER_CONTRACT.md) |
| net | `net.createServer · net.connect` | G45 · G61 (tentative) | Real TCP listen / accept / connect; no TLS, unix sockets or full duplex parity. | [NET_SERVER_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/NET_SERVER_CONTRACT.md) |
| querystring | `parse · stringify · escape · unescape` | G38 | Fixed & / = separators; no options. | [QUERYSTRING_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/QUERYSTRING_CONTRACT.md) |
| string_decoder | `StringDecoder` | G39 · G68 | utf8, latin1, ascii, base64, hex, utf16le with partial-unit buffering; no base64url. | [STRING_DECODER_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/STRING_DECODER_CONTRACT.md) |
| assert | `ok · strictEqual · deepStrictEqual · throws · match · rejects` | G40 · G69 | Strict assertions; loose equal coercion and the deepEqual alias are not pinned. | [ASSERT_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/ASSERT_CONTRACT.md) |
| timers | `timers · timers/promises` | G42 · G50 | Module timers and Promise setTimeout / setImmediate with AbortSignal. | [TIMERS_MODULE_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/TIMERS_MODULE_CONTRACT.md) |
| readline | `createInterface · question` | G46 (tentative) | One line from host stdin; no history, completer or readline.promises. | [READLINE_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/READLINE_CONTRACT.md) |
| tty | `tty.isatty` | G49 | Real isatty on Unix; always false on Windows today. | [TTY_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/TTY_CONTRACT.md) |
| vm | `runInThisContext · runInNewContext · Script` | G55 · G66 (tentative) | Same-context run and a fresh-context property-copy sandbox; not Contextify parity. | [VM_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/VM_CONTRACT.md) |
| diagnostics_channel | `channel · subscribe · tracingChannel.traceSync` | G56 (tentative) | Current-isolate pub/sub; no tracePromise. | [DIAGNOSTICS_CHANNEL_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/DIAGNOSTICS_CHANNEL_CONTRACT.md) |
| async_hooks | `AsyncResource · AsyncLocalStorage` | G57 (tentative) | ALS run / getStore / snapshot; createHook is not supported. | [ASYNC_HOOKS_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/ASYNC_HOOKS_CONTRACT.md) |

### Web APIs

| Capability | API | Id | Limits | Contract |
| :--- | :--- | :--- | :--- | :--- |
| fetch | `fetch · Request · Response · Headers` | G9 | Streaming body reader, redirects, integrity, AbortSignal; no browser CORS origin. | [FETCH_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/FETCH_CONTRACT.md) |
| URL & encoding | `URL · URLSearchParams · TextEncoder · TextDecoder · structuredClone` | G10 | No IDNA; TextDecoder is UTF-8 only. | [URL_ENCODING_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/URL_ENCODING_CONTRACT.md) |
| Blob / File / FormData | `Blob · File · FormData` | G11 | Multipart fetch bodies; text() / arrayBuffer() are synchronous. | [BLOB_FORMDATA_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/BLOB_FORMDATA_CONTRACT.md) |
| Events & channels | `EventTarget · AbortController · MessageChannel · BroadcastChannel` | G12 | No DOM tree; BroadcastChannel stays within one isolate. | [EVENTS_CHANNELS_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/EVENTS_CHANNELS_CONTRACT.md) |
| Streams, compression, timers | `ReadableStream · CompressionStream · setTimeout · performance` | G13 | Queuing strategies do not apply backpressure. | [STREAMS_TIMERS_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/STREAMS_TIMERS_CONTRACT.md) |
| Web Crypto | `crypto.subtle · getRandomValues · randomUUID` | G14 | SHA, HMAC, AES, PBKDF2, ECDH, Ed25519, ECDSA, RSA; no HKDF / RSA-PSS / X25519. | [WEB_CRYPTO_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/WEB_CRYPTO_CONTRACT.md) |
| WebSocket (client) | `new WebSocket('ws://…')` | G15 | Real ws:// handshake; no subprotocols or permessage-deflate; not a server. | [WEBSOCKET_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/WEBSOCKET_CONTRACT.md) |
| Workers | `Worker · worker_threads · navigator.serviceWorker` | G16 | Dedicated workers with JSON messages; no SharedWorker or module workers. | [WORKERS_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/WORKERS_CONTRACT.md) |
| atob / btoa | `atob · btoa` | G29 | Standard Base64; throws plain Error, not DOMException. | [ATOB_BTOA_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/ATOB_BTOA_CONTRACT.md) |
| ErrorEvent / onerror | `ErrorEvent · globalThis.onerror` | G30 (provisional) | Uncaught throws can be handled by onerror; not a document error pipeline. | [ERROR_EVENT_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/ERROR_EVENT_CONTRACT.md) |
| Clipboard (text) | `navigator.clipboard.writeText / readText` | G31 | Process-local text store, not the OS clipboard; no ClipboardItem. | [CLIPBOARD_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/CLIPBOARD_CONTRACT.md) |
| DOMParser | `new DOMParser().parseFromString()` | G32 | Read-only HTML / XML parse tree with selectors; not a live DOM. | [DOMPARSER_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/DOMPARSER_CONTRACT.md) |
| Background Sync | `registration.sync · SyncEvent` | G33 | Fires on the same CLI isolate; not Periodic Sync. | [BACKGROUND_SYNC_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/BACKGROUND_SYNC_CONTRACT.md) |
| Cache Storage | `caches.open · cache.match / put` | G34 | In-process store; not an HTTP cache and not persisted. | [CACHE_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/CACHE_CONTRACT.md) |
| Service worker fetch | `FetchEvent.respondWith` | G35 | Activated worker intercepts page fetch; scope is not matched. | [SW_FETCH_CONTRACT.md](https://github.com/zh30/amberjs/blob/main/docs/SW_FETCH_CONTRACT.md) |

## Preview

In the default build and usable, but the contract or edge cases are still being tightened.

- **Rest of src/nodejs_core/** — Node modules and methods outside the contracts above: stream Transform / Duplex / pipeline, crypto KDF / sign / KeyObject, process.exit / stdin, perf_hooks, and more.
- **Rest of src/web_api/** — Web APIs outside the Stable contracts, such as ExtendableEvent. Treated per-API, not as blanket Web compatibility.
- **amber:wasm** — Zero-copy WebAssembly.Memory / ArrayBuffer helpers and mmap module load.

## Experimental

Code exists, but it is not a product promise until it is re-verified.

- **amber init · create · add · remove · prune · upgrade · x** — Package and scaffolding commands outside the Stable amber install contract.
- **amber debug** — Debug command; use the Stable --inspect CDP subset instead.
- **N-API hello loader** — process.dlopen can load a C hello addon. Not Node ABI compatibility; Prisma and sharp are out of scope.
- **Cargo features** — benchmarks and observability are CI-checked. cloudnative, enterprise, multilang and tch are not CI-gated; feature "ai" is empty.
- **Distribution channels** — GHCR image is linux/amd64 only. The winget manifest lives in-repo and is not submitted.

### Present in the binary but not classified by CURRENT_SCOPE (treated as Experimental)

`amber fmt`, `amber lint`, `amber bench`, `amber task`, `amber types`, `amber lsp`, `amber profile`, `amber deploy`, `amber record / replay`, `--virtual-fs`, `--import-map`, `amber:mcp`, `amber:kv`, `amber:bus`, `amber:grammar`, `amber:checkpoint`, `amber:weights`, `amber:tools`, `amber:security`, `amber:std`, `amber:db`, `amber:vector`, `amber:pool`, `amber:ffi`

## Not supported (non-goals)

Deliberately out of scope today. Where possible Amber throws or rejects instead of returning fake data.

- **SharedWorker · module workers** — new Worker(url, { type: 'module' }) throws.
- **Push · Notification · Payment** — Push subscription rejects. These browser surfaces are deferred.
- **ClipboardItem** — clipboard.read / write reject with an Error naming ClipboardItem.
- **http client · Agent · https · http2** — Use the Stable Web fetch for outbound HTTP. Only the http server subset is Stable.
- **Streaming zlib · brotli** — createGzip / createDeflate families, brotli and zlib.constants are not implemented.
- **Type-checking** — TypeScript is transpile-only. Run tsc --noEmit in CI if you need type errors.
- **fs.glob · fs.cp · fs.opendir · fs.statfs** — Not implemented; also no fs.promises.watch.
- **Parallel tests · cross-compile** — amber test --parallel exits 2. amber compile only targets the host OS.
- **npm workspaces · lifecycle scripts** — amber install does not run scripts, link .bin, or read yarn / pnpm lockfiles.