docs/CURRENT_SCOPE.md · G1–G69 · 56/56 conformance

Compatibility & scope

Exactly what Amber v1.17.0 supports, what is still in Preview, and what is out of scope. Every Stable row links to its contract.

Mirrors docs/CURRENT_SCOPE.md on main. If this page and that file disagree, the file wins. CURRENT_SCOPE.md

StableStable

Graduated under the Graduation Rule: reachable from the amber binary, described without stage reports, covered by tests, limits documented.

  • amber run / eval / repl
    amber run <file> · amber eval <code> · amber repl
    Base
    V8 execution through runtime_minimal; repl is the basic shell.
  • amber test
    amber test [files...]
    Base
    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.Contract
  • amber compile
    amber compile <entry> -o <bin>
    G2
    Host single-executable on Linux/macOS/Windows; no cross-compile, no native addons.Contract
  • amber install
    amber install [--frozen-lockfile]
    G3
    Direct deps from package.json with lockfile pins and SRI checks; not npm/yarn/pnpm.Contract
  • 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.Contract
  • amber run --inspect
    --inspect · --inspect-brk · --inspect-port
    G5
    CDP subset on 127.0.0.1 (Runtime.evaluate); no breakpoints or stepping.Contract
  • --watch
    amber run --watch · amber test --watch
    G6
    Full re-exec on change plus a localhost reload WebSocket; not in-place HMR.Contract
  • amber serve
    amber serve [--port] [script]
    G41
    HTTP/1.1 health document or fetch-handler bridge; one request per connection.Contract
  • 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.Contract
  • TypeScript / TSX
    .ts · .tsx · .mts · .cts · .jsx
    G36
    oxc transpile-only with .ts stack remap; not tsc — no type-checking.Contract
  • amber session / amber mcp
    amber session <tools> · amber mcp <tools>
    Base
    Agent tool execution over stdin JSON-RPC and an MCP stdio server.
  • amber snapshot
    amber snapshot [build|status|clean]
    Base
    Manage V8 startup snapshots with mmap backing.
  • Capability sandbox
    --sandbox · --allow-* · --permission-policy · --audit-log
    Base
    Deny-by-default fs/net/env/run with exact allows and a JSONL audit trail.
  • Deterministic execution
    --seed <u64> · --freeze-time <spec>
    Base
    Seeded Math.random / getRandomValues and a frozen virtual clock.
  • amber:ai
    Tensor · LLM · AgentPipeline
    Base
    In-process TypedArray tensors, local streaming LLM, pipelines. Cargo feature "ai" is empty.
  • WebAssembly streaming
    WebAssembly.compileStreaming · instantiateStreaming
    Base
    V8 Wasm; streaming compile from Response. amber:wasm zero-copy helpers are Preview.
  • WinterTC baseline
    DOMException · URLPattern · navigator · amber:sockets · import.meta
    Base
    ECMA-429 minimum common API, wintertc export conditions, TCP + rustls sockets.
  • CommonJS require
    require · module · require.resolve · createRequire
    G28provisional
    node_modules walk, package.json exports/imports/main; not the Node Module class.Contract
  • fs
    fs · fs/promises
    G8
    Byte I/O, mkdir, stat, fds, readdir dirents, promises; no glob / cp / opendir / statfs.Contract
  • fs.watch / fs.watchFile
    fs.watch · fs.watchFile · fs.unwatchFile
    G64tentative
    Real OS watcher (notify) and stat polling; no fs.promises.watch.Contract
  • path
    path · path.posix
    G17
    POSIX semantics; path.win32 methods are the POSIX implementations.Contract
  • events
    EventEmitter · once
    G18
    Full listener API and static once; no events.on async iterator.Contract
  • buffer
    Buffer
    G19
    from / alloc / concat / toString / slice; readUInt* and compare are outside.Contract
  • os
    platform · arch · cpus · tmpdir · homedir …
    G20
    Host info subset; cpus()[].speed / times are outside.Contract
  • os.hostname
    os.hostname()
    G62
    Real gethostname / GetComputerNameW; not a DNS FQDN.Contract
  • os.networkInterfaces
    os.networkInterfaces()
    G63
    Real OS enumerator; MAC is best-effort.Contract
  • zlib (sync)
    gzipSync · deflateSync · inflateRawSync …
    G21
    Six sync codecs; no brotli, no zlib.constants.Contract
  • zlib (async callbacks)
    gzip · gunzip · deflate · inflate · deflateRaw · inflateRaw
    G48 · G58tentative
    Callbacks on a later tick; no streaming createGzip family.Contract
  • util
    format · inspect · promisify · callbackify · types
    G22 · G59
    Basics plus util.types.isArrayBuffer / isRegExp; inspect ignores depth / colors.Contract
  • 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.Contract
  • crypto
    createHash · createHmac · randomBytes · randomUUID · timingSafeEqual
    G23
    md5 / sha* / blake3 digests; KDF, sign/verify and KeyObject stay Preview.Contract
  • 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.Contract
  • stream
    Readable · Writable · PassThrough · pipe
    G24
    Flowing push / pipe; no backpressure. Transform / Duplex / pipeline stay Preview.Contract
  • child_process (sync)
    execSync · spawnSync
    G25
    Sandbox-aware; no timeout / cwd / env options.Contract
  • child_process (async)
    exec · execFile · spawn
    G47 · G60tentative
    Captured output via callback on a later turn; no live stdio pipes.Contract
  • child_process.fork
    fork · child.send · process.send
    G67tentative
    Real OS process with JSON IPC over localhost TCP.Contract
  • url
    fileURLToPath · pathToFileURL
    G26
    POSIX file URL helpers; legacy parse / format are outside.Contract
  • dns
    lookup · resolve4 · resolve6 · reverse · getServers
    G27 · G65provisional
    Host getaddrinfo / getnameinfo, sync; no dns.promises or setServers.Contract
  • http (server)
    http.createServer · listen · req / res
    G37tentative
    Buffered responses; the http client, Agent, https and http2 are not supported.Contract
  • net
    net.createServer · net.connect
    G45 · G61tentative
    Real TCP listen / accept / connect; no TLS, unix sockets or full duplex parity.Contract
  • querystring
    parse · stringify · escape · unescape
    G38
    Fixed & / = separators; no options.Contract
  • string_decoder
    StringDecoder
    G39 · G68
    utf8, latin1, ascii, base64, hex, utf16le with partial-unit buffering; no base64url.Contract
  • assert
    ok · strictEqual · deepStrictEqual · throws · match · rejects
    G40 · G69
    Strict assertions; loose equal coercion and the deepEqual alias are not pinned.Contract
  • timers
    timers · timers/promises
    G42 · G50
    Module timers and Promise setTimeout / setImmediate with AbortSignal.Contract
  • readline
    createInterface · question
    G46tentative
    One line from host stdin; no history, completer or readline.promises.Contract
  • tty
    tty.isatty
    G49
    Real isatty on Unix; always false on Windows today.Contract
  • vm
    runInThisContext · runInNewContext · Script
    G55 · G66tentative
    Same-context run and a fresh-context property-copy sandbox; not Contextify parity.Contract
  • diagnostics_channel
    channel · subscribe · tracingChannel.traceSync
    G56tentative
    Current-isolate pub/sub; no tracePromise.Contract
  • async_hooks
    AsyncResource · AsyncLocalStorage
    G57tentative
    ALS run / getStore / snapshot; createHook is not supported.Contract
  • fetch
    fetch · Request · Response · Headers
    G9
    Streaming body reader, redirects, integrity, AbortSignal; no browser CORS origin.Contract
  • URL & encoding
    URL · URLSearchParams · TextEncoder · TextDecoder · structuredClone
    G10
    No IDNA; TextDecoder is UTF-8 only.Contract
  • Blob / File / FormData
    Blob · File · FormData
    G11
    Multipart fetch bodies; text() / arrayBuffer() are synchronous.Contract
  • Events & channels
    EventTarget · AbortController · MessageChannel · BroadcastChannel
    G12
    No DOM tree; BroadcastChannel stays within one isolate.Contract
  • Streams, compression, timers
    ReadableStream · CompressionStream · setTimeout · performance
    G13
    Queuing strategies do not apply backpressure.Contract
  • Web Crypto
    crypto.subtle · getRandomValues · randomUUID
    G14
    SHA, HMAC, AES, PBKDF2, ECDH, Ed25519, ECDSA, RSA; no HKDF / RSA-PSS / X25519.Contract
  • WebSocket (client)
    new WebSocket('ws://…')
    G15
    Real ws:// handshake; no subprotocols or permessage-deflate; not a server.Contract
  • Workers
    Worker · worker_threads · navigator.serviceWorker
    G16
    Dedicated workers with JSON messages; no SharedWorker or module workers.Contract
  • atob / btoa
    atob · btoa
    G29
    Standard Base64; throws plain Error, not DOMException.Contract
  • ErrorEvent / onerror
    ErrorEvent · globalThis.onerror
    G30provisional
    Uncaught throws can be handled by onerror; not a document error pipeline.Contract
  • Clipboard (text)
    navigator.clipboard.writeText / readText
    G31
    Process-local text store, not the OS clipboard; no ClipboardItem.Contract
  • DOMParser
    new DOMParser().parseFromString()
    G32
    Read-only HTML / XML parse tree with selectors; not a live DOM.Contract
  • Background Sync
    registration.sync · SyncEvent
    G33
    Fires on the same CLI isolate; not Periodic Sync.Contract
  • Cache Storage
    caches.open · cache.match / put
    G34
    In-process store; not an HTTP cache and not persisted.Contract
  • Service worker fetch
    FetchEvent.respondWith
    G35
    Activated worker intercepts page fetch; scope is not matched.Contract

Ids marked tentative or provisional graduated under the same rule and may still be renumbered.

PreviewPreview

Present in the default build. Useful for experiments; not yet a compatibility promise.

  • PreviewRest 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.

  • PreviewRest of src/web_api/

    Web APIs outside the Stable contracts, such as ExtendableEvent. Treated per-API, not as blanket Web compatibility.

  • Previewamber:wasm

    Zero-copy WebAssembly.Memory / ArrayBuffer helpers and mmap module load.

ExperimentalExperimental

Exists as code or a command surface. Do not rely on it without verifying it yourself.

  • Experimentalamber init · create · add · remove · prune · upgrade · x

    Package and scaffolding commands outside the Stable amber install contract.

  • Experimentalamber debug

    Debug command; use the Stable --inspect CDP subset instead.

  • ExperimentalN-API hello loader

    process.dlopen can load a C hello addon. Not Node ABI compatibility; Prisma and sharp are out of scope.

  • ExperimentalCargo features

    benchmarks and observability are CI-checked. cloudnative, enterprise, multilang and tch are not CI-gated; feature "ai" is empty.

  • ExperimentalDistribution channels

    GHCR image is linux/amd64 only. The winget manifest lives in-repo and is not submitted.

Present in code, not yet classified

These subcommands, flags and amber:* modules exist in the source tree but are not described by CURRENT_SCOPE. Treat them 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 supportedNot supported

Deliberate non-goals for now. Amber fails closed on these instead of shipping stubs.

  • Not supportedSharedWorker · module workers

    new Worker(url, { type: 'module' }) throws.

  • Not supportedPush · Notification · Payment

    Push subscription rejects. These browser surfaces are deferred.

  • Not supportedClipboardItem

    clipboard.read / write reject with an Error naming ClipboardItem.

  • Not supportedhttp client · Agent · https · http2

    Use the Stable Web fetch for outbound HTTP. Only the http server subset is Stable.

  • Not supportedStreaming zlib · brotli

    createGzip / createDeflate families, brotli and zlib.constants are not implemented.

  • Not supportedType-checking

    TypeScript is transpile-only. Run tsc --noEmit in CI if you need type errors.

  • Not supportedfs.glob · fs.cp · fs.opendir · fs.statfs

    Not implemented; also no fs.promises.watch.

  • Not supportedParallel tests · cross-compile

    amber test --parallel exits 2. amber compile only targets the host OS.

  • Not supportednpm workspaces · lifecycle scripts

    amber install does not run scripts, link .bin, or read yarn / pnpm lockfiles.

How something becomes Stable

  1. 1It is reachable through src/main.rs or a documented API in src/lib.rs.
  2. 2Its behavior is described without relying on historical stage reports.
  3. 3Current tests or smoke commands cover the documented behavior.
  4. 4Known limitations are documented next to the capability.
  5. 5Feature-gated work passes a feature check for that feature.
56/56

tests/conformance/ runs small Node-style scripts — fs, streams, crypto, child_process, Express, Fastify, Hono and more — on every change. CI fails if any fixture fails or skips. Passing fixtures are a regression gate, not a claim of drop-in Node compatibility.

Read the scorecard