Epic: stub elimination — every registered API is real or fails loud

[proggeramlug]

Epic: every registered API is real, or it fails loud

Full-tree stub audit (2026-06-10, runtime + stdlib + api-manifest, verified against current main). A "stub" here means: an API that is registered and callable by name but returns a no-op, a hardcoded/fake value, or silently wrong behavior. For a native compiler, "compiles fine, runs wrong" is the worst failure mode — this epic exists so that by v1.0 no API can lie. (Spun out of the stable-release/versioning discussion; this is a 0.8-line "honest surface" gate.)

Policy (the actual deliverable)

Every API is in exactly one of three states, machine-readable in the manifest and enforced by CI:

1. Real — behaves like Node.
2. Partial — documented subset; out-of-subset input throws, never silently degrades.
3. Stub — flagged stub: true, emits perry_stub_warn on first call, visible in .d.ts/reference docs, throws under PERRY_STRICT_STUBS=1.

Keystone issue: #4918 (manifest stub flag is never set; two stub registries don't know about each other).

Stub inventory — sub-issues

Issue	Cluster	Severity
#4911	node:dns + node:dgram loopback-only fakes	SILENT-LIE
#4912	child_process.spawn() returns null; exec() secretly synchronous	LOUD + SILENT-LIE
#4913	Atomics.wait/notify/waitAsync non-blocking fakes (post-#4794)	SILENT-LIE
#4914	node:cluster — no socket/listening-handle distribution	SILENT-LIE
#4915	Web Streams BYOB readers + ByteLengthQueuingStrategy throw (post-#1545)	LOUD
#4916	v8 heap snapshot = empty-but-valid graph; inspector/repl look real	SILENT-LIE
#4917	stdlib adapters: ignored options + success-returning no-ops (zlib/http.Agent/mongodb/mysql2/pg/worker_threads/fastify/backoff)	mixed
#4918	Keystone: manifest stub: true population + CI cross-check + strict mode	infra

Pre-existing open issues that are stub-class (tracked there, listed for completeness)

• globals: make WeakRef and FinalizationRegistry actually weak #2656 — WeakRef/FinalizationRegistry not actually weak ("API exists, semantics lie")
• runtime: expose Atomics operations for SharedArrayBuffer views #2876 — Atomics ops on SAB views (interacts with Atomics.wait/notify/waitAsync are non-blocking fakes — real blocking + cross-agent wakeups (follow-up to #4794) #4913)
• Compile a standard Express app: full blocker inventory (codegen emits undefined @perry_closure_* globals → linked-but-crashing binary) #3527 — codegen emits undefined @perry_closure_* globals → linked-but-crashing binary (the linker-level analog of a stub: fail loud at link time)

Found-but-not-filed (intentional / by-design, no action unless policy changes)

• stdlib_stubs.rs link-time fallbacks (WebSocket/fetch/readline when perry-stdlib isn't linked) — legitimate, but should all route through perry_stub_warn (folded into api-manifest: stub flag exists but is never set — populate it, cross-check with stub_diag, and surface in docs + a strict mode #4918).
• ui_harmonyos_stubs.rs — platform-gated zero-returning UI symbols (perry/ui FFI symbols undefined on --target harmonyos (perry_ui_embed_nsview, others) — block on .so load #395); exactly what the manifest stub field was invented for.
• node:vm SourceTextModule — throws ERR_PERRY_VM_UNIMPLEMENTED with issue pointer; this is the model behavior the rest should copy.
• node:stream _read() throwing "not implemented" — correct Node semantics, not a stub.

Audit notes (claims checked and dropped)

• async context (AsyncLocalStorage/async_hooks) — real since AsyncLocalStorage: real async-context tracking across await / microtasks / timers #788/async_hooks: real createHook lifecycle + asyncId tracking #789 closed (May 16); CLAUDE.md's "name-only stubs" note is stale and should be updated.
• node:tty "always reports non-TTY" — not confirmed; tty raw-mode work (TUI gap: readline + tty.setRawMode + raw-mode stdin reader #347/process.stdin: support listener removal and lifecycle detach for TUI teardown #3962) landed for the ink push.
• node:net loopback-only — not confirmed on current main; dropped from node:dns + node:dgram are loopback-only fakes — implement real network I/O behind a deterministic-mode flag #4911.

Done when

All eight sub-issues closed (or individually re-triaged with rationale here), and the #4918 CI gate is the thing preventing recurrence — not this list.

[proggeramlug]

Keystone landed — stub surface is now honest (PR #4929, merged a389f9cdf)

The #4918 keystone is complete and merged, which is the epic's "Done when" recurrence-prevention gate:

• ApiEntry.stub is now actually populated (it existed but was set on 0 of ~2,500 entries). Added const .stub()/.stub_note(reason) builders + a stub_note field (distinguishes a pure no-op from a real-but-partial API without an enum migration).
• 100 entries flagged across 7 clusters. The generated .d.ts (@perryStub <note>), reference.md (⚠ column), and --print-api-manifest JSON surface them automatically.
• CI drift guard crates/perry-api-manifest/tests/stub_inventory.rs pins the exact inventory, requires every stub to carry an issue-tagged reason, and allowlists which modules may contain stubs — so a new silent lie can't ship without a reviewed change.
• Runtime honesty: flagged runtime paths emit a first-call perry_stub_warn and, under PERRY_STRICT_STUBS=1, throw ERR_PERRY_UNIMPLEMENTED instead of returning a fake.

Per-sub-issue status

Issue	State
#4918 keystone	✅ Done — closing.
#4911 dns/dgram	Honest floor done (flagged + warn + strict-throw). Open for real getaddrinfo/hickory resolver + real UDP sockets behind PERRY_DETERMINISTIC_NET.
#4912 spawn/exec	Re-triaged: spawn is real since #1780 (verified). Premise was stale; left unflagged. Open only for exec() same-tick-callback timing.
#4913 Atomics	Honest floor done (warn/throw on the genuinely-blocking path only; timeout=0 polls + not-equal untouched). Open for real shared-SAB + futex wakeups.
#4914 cluster	Flagged. Open for socket/listening-handle distribution.
#4915 BYOB streams	Flagged (already throws; now visible). Open for real BYOB readers + ByteLengthQueuingStrategy.
#4916 v8/inspector/repl	Heap snapshots flagged + warn + strict-throw. Open for real GC-heap-graph snapshot + inspector/repl audit.
#4917 stdlib adapters	zlib/http.Agent/worker/mongodb/backoff flagged. Open for the real per-adapter implementations.

Also done

• Corrected the stale AsyncLocalStorage/async_hooks "name-only stubs" note in CLAUDE.md (real since AsyncLocalStorage: real async-context tracking across await / microtasks / timers #788/async_hooks: real createHook lifecycle + asyncId tracking #789, per this epic's audit).

The seven implementation issues stay open for their real halves (multi-stage by their own framing); the manifest now makes them visibly fake rather than silently fake, which is the floor this epic set. Closing the keystone #4918.

[proggeramlug]

Epic complete — closing

All eight sub-issues are now closed:

Issue	Resolution
#4918 keystone	Manifest stub flag populated (100 entries), first-call perry_stub_warn, PERRY_STRICT_STUBS=1 throws, CI drift guard stub_inventory.rs — PR #4929
#4911 dns/dgram	Real network I/O (getaddrinfo + hickory resolver, real UDP sockets); PERRY_DETERMINISTIC_NET=1 keeps the deterministic mode
#4912 child_process	spawn verified real (stale premise); exec/execFile routed through the async spawn reactor — PR #4941
#4913 Atomics	Real cross-agent wait/notify/waitAsync (global SAB backing + futex table) — PR #4952
#4914 cluster	SO_REUSEPORT port sharing + fork IPC listening round-trip — PR #4963
#4915 BYOB streams	Real BYOB readers + ByteLengthQueuingStrategy — PR #4966
#4916 v8/inspector	Real heap snapshot from GC walk (Node-v26 format) + inspector/repl honesty — PR #4979
#4917 stdlib adapters	Real semantics (or loud warn) for zlib opts, http.Agent, backoff opts, fastify upgrade, worker ref/unref, mongodb findOne, mysql2/pg metadata — PR #4996

The recurrence-prevention gate is in place and is the thing enforcing the policy going forward: crates/perry-api-manifest/tests/stub_inventory.rs pins the exact stub inventory in CI, requires an issue-tagged reason per entry, and allowlists which modules may contain stubs — a new silent lie can't ship without a reviewed change. Stub state is visible in .d.ts (@perryStub), reference.md, and --print-api-manifest, and flagged paths warn on first call / throw under PERRY_STRICT_STUBS=1.

Pre-existing stub-class issues remain tracked separately: #2656 (WeakRef/FinalizationRegistry), #2876 (Atomics on SAB views), #3527 (undefined @perry_closure_* globals).