api-manifest: stub flag exists but is never set — populate it, cross-check with stub_diag, and surface in docs + a strict mode

[proggeramlug]

The structural gap

The API manifest already has the field that solves the stub-tracking problem, and nothing uses it:

• ApiEntry.stub: bool exists in crates/perry-api-manifest/src/lib.rs (~line 54), added so the unimplemented-API check (Compile-time error for unimplemented Node / Web APIs #463) wouldn't error on intentional no-ops.
• Zero of ~2,500 entries set it. The method()/property()/class() helper constructors hardcode stub: false (the only 6 occurrences of the literal in entries.rs) and there is no setter/builder to override it.
• Meanwhile stub_diag.rs (Stub registry + first-call runtime diagnostic for no-op stubs #464) maintains a separate STUB_MANIFEST registry + perry_stub_warn first-call diagnostics — but it's only wired into 3 files (stdlib_stubs.rs, global_fetch.rs, stub_diag.rs itself). The two stub registries don't know about each other.

Result: the manifest drives the .d.ts, docs/src/api/reference.md, the compile-time unimplemented-API check, and the CI drift guard (manifest_consistency.rs) — and every one of those surfaces presents stubs as fully supported. There is no machine-readable difference between fs.readFile (real) and dns.resolve4 (loopback fake).

Work items

• Add a builder (.stub()) on the entry helpers; annotate the known stub clusters: dns/dgram (node:dns + node:dgram are loopback-only fakes — implement real network I/O behind a deterministic-mode flag #4911), child_process.spawn (child_process.spawn() returns null; exec() is secretly synchronous — finish real async subprocess support #4912), Atomics wait/notify (Atomics.wait/notify/waitAsync are non-blocking fakes — real blocking + cross-agent wakeups (follow-up to #4794) #4913), cluster distribution (node:cluster: socket/listening-handle distribution missing — workers can't actually share a port #4914), BYOB streams (Web Streams residuals: BYOB readers + ByteLengthQueuingStrategy still throw (post-#1545) #4915), v8 snapshot/inspector/repl (Diagnostics fakes: v8 heap snapshot is an empty-but-valid graph; inspector/repl sessions look real but aren't #4916), the stdlib-adapter list (stdlib adapters: silently-ignored options and success-returning no-ops (zlib opts, http.Agent pooling, mongodb findOne string, mysql2/pg metadata, worker ref/unref, fastify upgrade, backoff opts) #4917).
• Consider three states (Real | Partial | Stub) — http.Agent is real but doesn't pool; v8.getHeapStatistics returns real-but-approximate numbers.
• CI cross-check: every symbol in stub_diag.rs's STUB_MANIFEST must correspond to a manifest entry with stub != false, and vice versa for no-op-detected entries — one source of truth, drift-guarded like manifest_consistency.rs already does for arity.
• Surface it: generated .d.ts gets @deprecated-style /** @perryStub */ doc tags; reference.md gets a ⚠ column; perry --print-api-manifest prints the flag.
• Wire perry_stub_warn into every stub: true dispatch path (most stubs today warn nothing).
• Opt-in strictness: PERRY_STRICT_STUBS=1 (or --error-on-stub) turns first stub call into a thrown ERR_PERRY_UNIMPLEMENTED — makes package-compat work measurable instead of anecdotal, per the audit recommendation.

Why this is the keystone

Every other issue in the stub epic fixes one lie. This one makes new lies impossible to ship: an API can be real, or it can be visibly fake — never silently fake.

[proggeramlug]

Done and merged in PR #4929 (a389f9cdf). The manifest stub flag is now populated via const .stub()/.stub_note() builders (100 entries across 7 clusters), surfaced in .d.ts/reference.md/--print-api-manifest, drift-guarded by tests/stub_inventory.rs, wired to first-call perry_stub_warn, and enforced by PERRY_STRICT_STUBS=1 (throws ERR_PERRY_UNIMPLEMENTED).

Design note on the proposed stub_diag↔manifest cross-check: the runtime STUB_MANIFEST is build-target-conditional (harmonyos UI platform stubs — real on macOS/iOS), so it can't be literally cross-checked against the host-independent API_MANIFEST. The inventory drift-guard achieves the same "one source of truth, drift-guarded" intent instead.