tracking: V8-free compat — close the perry-jsruntime gap for all sweep packages

[proggeramlug]

Snapshot at v0.5.1008

Compat sweep run without --enable-js-runtime, with the #499 / #947 gate active (default):

Package	V8-free status	Notes
dotenv	✅ PASS	perry-stdlib bundled-dotenv
ioredis	✅ PASS	perry-stdlib bundled-ioredis
jsonwebtoken	✅ PASS	perry-ext-jsonwebtoken
lodash	✅ PASS	perry-stdlib lodash manifest
date-fns	❌ diff (fmt=yyyy-01-dd)	LDML symbol-shadow regression — perry-ext-dayjs::js_datefns_format shadowed the proper perry-stdlib LDML walker. Same family as last week's #993 / #995 / #1000 work; was clean earlier in the session.
debug	❌ compile (perry-jsruntime pulled in)	well-known flip exists but debug's ms submodule still routes to V8 fallback
drizzle	❌ compile (perry-jsruntime pulled in)	needs PR #1065 (sqlite Database/Statement V8 proxies) to land + a native binding for drizzle-orm itself if going fully V8-free
effect	❌ compile (perry-jsruntime pulled in)	#321 tracker: 7/7 listed sub-issues CLOSED, runtime blocker Effect.succeed(42) === undefined on compilePackages path still open. Categorical: arguments magic object used by dual() 148×
express	❌ compile (perry-jsruntime pulled in)	runs through V8 fallback (perry-ext-http-server underneath but middleware chain is in V8)
fastify	❌ runtime (rc=124 timeout)	PR #1066 lands app.close + non-blocking listen — flips to PASS once merged
hono	❌ compile (perry-jsruntime pulled in)	needs compilePackages: ["hono"] to clean-compile; today routes through V8 (PR #987 / #1015 / #1016)
jose	❌ compile (perry-jsruntime pulled in)	works through V8 (PR #1004 / #1010) — would need a native binding to go V8-free
nestjs	❌ compile (perry-jsruntime pulled in)	PR #1067 lands CJS-cycle/require-extractor/process.exit fixes; full route response still needs Reflect.defineMetadata / getMetadata round-trip across the Perry/V8 boundary
ramda	❌ compile (perry-jsruntime pulled in)	works through V8 — needs compilePackages: ["ramda"] clean-compile, or per-function native bindings via the lodash precedent
vitest	❌ compile (perry-jsruntime pulled in)	test-runner — pulls in many transitive deps
zod	❌ compile (perry-jsruntime pulled in)	importer node_modules/zod/v3/errors.js + ZodError.js route to V8; pure-JS but uses Symbol.iterator + extends Error in patterns that don't AOT cleanly

Score: 4/16 link V8-free today.

What "compile without V8" requires per package

For every package that needs V8 today, ONE of:

1. compilePackages clean-compile — Perry's HIR + codegen must handle every JS pattern the package uses. Known categorical blockers:

   • arguments magic object (Effect's dual() uses it 148×; documented in docs/src/language/limitations.md)
   • Reflect.defineMetadata / getMetadata round-trip — NestJS reads 0 instead of the registered route path
   • Lookbehind regex — Rust regex crate doesn't support; test-parity: audit known_failures.json — every entry needs an issue # and date #797 covers known_failures provenance
   • console.dir / console.group* formatting (smaller scope)
   • Lone surrogate handling (WTF-8)
   • Dynamic-stdlib dispatch (path[runtimeVar]()) — already gated by security: refuse dynamic stdlib dispatch (obj[runtimeVar]()) #503; Effect requires PERRY_ALLOW_DYNAMIC_STDLIB=1 opt-in

2. perry-ext-<package> native binding — cookie-cutter Rust crate routed via crates/perry/well_known_bindings.toml. Precedents: perry-ext-bcrypt, perry-ext-argon2, perry-ext-pg, perry-ext-jsonwebtoken, perry-ext-fastify, perry-ext-better-sqlite3 (PR fix(perry-jsruntime): v8 proxies for sqlite Database/Statement (#1022) #1065).

3. perry-stdlib bundled native impl — for packages used by enough programs to justify in-tree (lodash manifest, dayjs/date-fns LDML, fastify, http server, ioredis, dotenv).

Highest-leverage unlocks

Ranked by how many sweep rows flip per fix:

1. arguments magic object — unblocks Effect's compilePackages path (Tracking: Effect framework end-to-end compat (post-#309 / #310) #321) and any idiomatic Node library that uses arguments for data-first/data-last API duality. Plumbing-only in HIR/codegen; runtime support already exists in js_callee_arguments paths.
2. Reflect.defineMetadata / getMetadata cross-boundary — flagged by PR fix(jsruntime): #1021 — nestjs sweep silent exit (CJS cycles + process.exit) #1067 as the remaining gap for nestjs full PASS. The bridge in crates/perry-jsruntime/src/interop.rs wires Reflect onto V8's side but Perry-side compiled Reflect namespace doesn't expose those methods. Note: even fixing this leaves nestjs needing V8 for the decorator runtime — closing this gap is necessary for nestjs's compilePackages path eventually, not for going V8-free today.
3. Lookbehind regex — many packages use (?<=foo)bar; without it they fall back to V8 or fail.
4. compilePackages runtime stability — Effect's Effect.succeed(42) returning undefined through the native compile path is the canonical example. Tracked under Tracking: Effect framework end-to-end compat (post-#309 / #310) #321 (one in-flight agent working on it).
5. More perry-ext-* cookie cutters — hono, ramda, zod, debug, jose. Each is mechanically straightforward but a per-package surface project.

Status of recently-fixed compile paths

PRs landed today that move sweep packages closer to V8-free:

• fix(wasm): #1049 instances 2+3 — wrapForI64 non-i64 return handling #1063 wasm i64 wrapper non-i64 imports (wasm runtime: recurring TypeError: Cannot convert X to a BigInt at i64 boundaries — tracking issue #1049 instances 2+3) — closed
• test(async): #1013 — pin Promise.all + array destructure regression #1064 + test(async): extend #1013 coverage to cross-module property-return shape #1068 Promise.all + array destructure regression pins for const [a, b] = await Promise.all([fn1(), fn2()]) — destructured values are dropped (undefined) when fn returns property access through async; sequential awaits work #1013
• fix(perry-jsruntime): v8 proxies for sqlite Database/Statement (#1022) #1065 drizzle sqlite Database/Statement V8 proxies — still V8 path but unblocks count=1
• fix(fastify): non-blocking listen() + main-thread pump #1066 fastify non-blocking listen + close — flips fastify from rc=124 to PASS
• fix(jsruntime): #1021 — nestjs sweep silent exit (CJS cycles + process.exit) #1067 nestjs CJS-cycle + require-extractor + process.exit — partial; needs Reflect.metadata follow-up
• fix(transform): #1047 — async early return followed by an unreached await #1062 async early-return-with-unreached-await infinite loop (async fn early-return followed by an unreached await infinite-loops #1047)
• fix(async): #1021 async-closure state machine + #1029 re-invocation idempotency #1041 async-closure state machine (compat: async lowering blocks self-fetch (express/fastify/nestjs/hono) #1021) — flipped express + hono from rc=124

Out of scope for this tracker

fastify PASSES with --enable-js-runtime after #1066 lands. The runtime-failure row in the V8-free sweep above is the same root cause as the V8-enabled row — once #1066 is merged both flip together. Listed for completeness.

The date-fns fmt=yyyy-01-dd row is a regression separate from the V8 question — perry-ext-dayjs's js_datefns_format shadowed perry-stdlib's LDML walker. Fixed last week via #993 / #995 / #1000 but reappeared in the current build (LDML uppercase token replace, not LDML run-aware walk). Will file as separate issue.

Definition of done

V8-free sweep reads 16/16 PASS without the --enable-js-runtime flag. Realistic time horizon is multi-month given the categorical blockers (especially arguments and full decorator metadata).

[andrewtdiz]

I will take the current Drizzle/better-sqlite3 V8-free package slice from this tracker.

Current-main validation on e482b26dc994 (2026-06-05 UTC) shows the old Drizzle null/stub failure has moved: drizzle-sqlite now installs and compiles, but the generated binary hangs at runtime before producing stdout. Direct timeout 10s tests/release/packages/drizzle-sqlite/out reproduces it with empty stdout/stderr.

Planned scope is just the better-sqlite3/Drizzle lifecycle path needed for the checked-in sqlite fixture to run and exit. I will leave NestJS, Effect, lookbehind regex, and other V8-free tracker rows for separate cuts.

[andrewtdiz]

Opened PR #4494 for this slice: #4494

On current main base e482b26, the branch fixes the Drizzle SQLite runtime hang/error by aligning constructor prototype fallback behavior and preserving class constructor dynamic props used by the Drizzle SQL namespace path. Validation passed:

• focused parity fixture: node-suite/object/globals/constructor-prototype-chain
• release package harness: tests/release/packages/_harness.sh --filter drizzle-sqlite

[andrewtdiz]

Taking the next NestJS package-compatibility slice in a fresh branch: refresh the \ fixture so it reaches Perry's AOT/native compile path under the no-runtime-JS policy, then address the re-exported class method symbol mismatch if it remains the next compile/link wall. Non-goals for this cut: full Nest runtime parity, Express adapter behavior beyond the fixture's immediate bootstrap path, and broader package tracker cleanup.

[andrewtdiz]

Correction to my prior claim comment: the fixture is tests/release/packages/nestjs-hello. I am taking the NestJS package-compatibility slice that first refreshes that fixture so it reaches Perry AOT/native compilation under the no-runtime-JS policy, then fixes the re-exported class method symbol mismatch if it remains the next compile/link wall. Non-goals are full Nest runtime parity, broad Express adapter behavior, and package tracker cleanup.

[andrewtdiz]

Opened PR #4498: https://github.com/PerryTS/perry/pull/4498\n\nThis cut advances nestjs-hello past the install/trust metadata, dynamic wrapper, private buffer binding, SlowBuffer, and legacy stream/EventEmitter constructor-call walls, then updates WALLS.md to the current default-wrapper/re-export linker wall. Focused checks passed: cargo test -p perry wrap_rewrites_ -- --nocapture, cargo check -p perry-hir, cargo check -p perry, release build, the nestjs-hello harness expected SKIP at the documented wall, parity binaries for stream/EventEmitter constructor calls, cargo fmt --all -- --check, git diff --check, and ./scripts/check_file_size.sh.