Skip to content

CLAUDE.md

Latest commit

 

History

History
189 lines (141 loc) · 35.9 KB

CLAUDE.md

File metadata and controls

189 lines (141 loc) · 35.9 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

NOTE: Keep this file concise. Detailed changelogs live in CHANGELOG.md.

Project Overview

Perry is a native TypeScript compiler written in Rust that compiles TypeScript source code directly to native executables. It uses SWC for TypeScript parsing and LLVM for code generation.

Current Version: 0.5.184

TypeScript Parity Status

Tracked via the gap test suite (test-files/test_gap_*.ts, 28 tests). Compared byte-for-byte against node --experimental-strip-types. Run via /tmp/run_gap_tests.sh after cargo build --release -p perry-runtime -p perry-stdlib -p perry.

Last sweep: 18/28 passing (re-measured v0.5.170 after Phase 3/4 work; test_gap_proxy_reflect flipped from fail→pass via Phase 4 method-call inference). Known failing: array_methods, async_advanced, console_methods, error_extensions, fetch_response, global_apis, map_set_extended, object_methods, string_methods, typed_arrays. Run via /tmp/run_gap_tests.sh after full rebuild.

Known categorical gaps: lookbehind regex (Rust regex crate), console.dir/console.group* formatting, lone surrogate handling (WTF-8).

Workflow Requirements

IMPORTANT: Follow these practices for every code change made directly on main (maintainer workflow):

  1. Update CLAUDE.md: Add 1-2 line entry in "Recent Changes" for new features/fixes
  2. Increment Version: Bump patch version (e.g., 0.5.48 → 0.5.49)
  3. Commit Changes: Include code changes and CLAUDE.md updates together

External contributor PRs

PRs from outside contributors should not touch [workspace.package] version in Cargo.toml, the **Current Version:** line in CLAUDE.md, or add a "Recent Changes" entry. The maintainer bumps the version and writes the changelog entry at merge time — usually by rebasing the PR branch and amending. This avoids the patch-version collisions that happen when Perry's main ships several commits while a PR is in review (each on-main commit bumps the version; a PR that bumped to the same patch on day 1 is already behind by merge day). Contributors just write code; let the maintainer fold in the metadata last.

Build Commands

cargo build --release                          # Build all crates
cargo build --release -p perry-runtime -p perry-stdlib  # Rebuild runtime (MUST rebuild stdlib too!)
cargo test --workspace --exclude perry-ui-ios  # Run tests (exclude iOS on macOS host)
cargo run --release -- file.ts -o output && ./output    # Compile and run TypeScript
cargo run --release -- file.ts --print-hir              # Debug: print HIR

Architecture

TypeScript (.ts) → Parse (SWC) → AST → Lower → HIR → Transform → Codegen (LLVM) → .o → Link (cc) → Executable
Crate Purpose
perry CLI driver (parallel module codegen via rayon)
perry-parser SWC wrapper for TypeScript parsing
perry-types Type system definitions
perry-hir HIR data structures (ir.rs) and AST→HIR lowering (lower.rs)
perry-transform IR passes (closure conversion, async lowering, inlining)
perry-codegen LLVM-based native code generation
perry-runtime Runtime: value.rs, object.rs, array.rs, string.rs, gc.rs, arena.rs, thread.rs
perry-stdlib Node.js API support (mysql2, redis, fetch, fastify, ws, etc.)
perry-ui / perry-ui-macos / perry-ui-ios / perry-ui-tvos Native UI (AppKit/UIKit)
perry-jsruntime JavaScript interop via QuickJS

NaN-Boxing

Perry uses NaN-boxing to represent JavaScript values in 64 bits (perry-runtime/src/value.rs):

TAG_UNDEFINED = 0x7FFC_0000_0000_0001    BIGINT_TAG  = 0x7FFA (lower 48 = ptr)
TAG_NULL      = 0x7FFC_0000_0000_0002    POINTER_TAG = 0x7FFD (lower 48 = ptr)
TAG_FALSE     = 0x7FFC_0000_0000_0003    INT32_TAG   = 0x7FFE (lower 32 = int)
TAG_TRUE      = 0x7FFC_0000_0000_0004    STRING_TAG  = 0x7FFF (lower 48 = ptr)

Key functions: js_nanbox_string/pointer/bigint, js_nanbox_get_pointer, js_get_string_pointer_unified, js_jsvalue_to_string, js_is_truthy

Module-level variables: Strings stored as F64 (NaN-boxed), Arrays/Objects as I64 (raw pointers). Access via module_var_data_ids.

Garbage Collection

Mark-sweep GC in crates/perry-runtime/src/gc.rs with conservative stack scanning. Arena objects (arrays, objects) discovered by linear block walking. Malloc objects (strings, closures, promises, bigints, errors) tracked in thread-local Vec. Triggers on arena block allocation (~8MB), malloc count threshold, or explicit gc() call. 8-byte GcHeader per allocation.

Threading (perry/thread)

Single-threaded by default. perry/thread provides:

  • parallelMap(array, fn) / parallelFilter(array, fn) — data-parallel across all cores
  • spawn(fn) — background OS thread, returns Promise

Values cross threads via SerializedValue deep-copy. Each thread has independent arena + GC. Results from spawn flow back via PENDING_THREAD_RESULTS queue, drained during js_promise_run_microtasks().

Native UI (perry/ui)

Declarative TypeScript compiles to AppKit/UIKit calls. Handle-based widget system (1-based i64 handles, NaN-boxed with POINTER_TAG). --target ios-simulator/--target ios/--target tvos-simulator/--target tvos for cross-compilation.

To add a new widget — change 4 places:

  1. Runtime: crates/perry-ui-macos/src/widgets/ — create widget, register_widget(view)
  2. FFI: crates/perry-ui-macos/src/lib.rs — #[no_mangle] pub extern "C" fn perry_ui_<widget>_create
  3. Codegen: crates/perry-codegen/src/codegen.rs — declare extern + NativeMethodCall dispatch
  4. HIR: crates/perry-hir/src/lower.rs — only if widget has instance methods

Compiling npm Packages Natively (perry.compilePackages)

Configured in package.json:

{ "perry": { "compilePackages": ["@noble/curves", "@noble/hashes"] } }

First-resolved directory cached in compile_package_dirs; subsequent imports redirect to the same copy (dedup).

Known Limitations

  • No runtime type checking: Types erased at compile time. typeof via NaN-boxing tags. instanceof via class ID chain.
  • No shared mutable state across threads: No SharedArrayBuffer or Atomics.

Common Pitfalls & Patterns

NaN-Boxing Mistakes

  • Double NaN-boxing: If value is already F64, don't NaN-box again. Check builder.func.dfg.value_type(val).
  • Wrong tag: Strings=STRING_TAG, objects=POINTER_TAG, BigInt=BIGINT_TAG.
  • as f64 vs from_bits: u64 as f64 is numeric conversion (WRONG). Use f64::from_bits(u64) to preserve bits.

LLVM Type Mismatches

  • Loop counter optimization produces i32 — always convert before passing to f64/i64 functions
  • Constructor parameters always f64 (NaN-boxed) at signature level

Async / Threading

  • Thread-local arenas: JSValues from tokio workers invalid on main thread
  • Use spawn_for_promise_deferred() — return raw Rust data, convert to JSValue on main thread
  • Async closures: Promise pointer (I64) must be NaN-boxed with POINTER_TAG before returning as F64

Cross-Module Issues

  • ExternFuncRef values are NaN-boxed — use js_nanbox_get_pointer to extract
  • Module init order: topological sort by import dependencies
  • Optional params need imported_func_param_counts propagation through re-exports

Closure Captures

  • collect_local_refs_expr() must handle all expression types — catch-all silently skips refs
  • Captured string/pointer values must be NaN-boxed before storing, not raw bitcast
  • Loop counter i32 values: fcvt_from_sint to f64 before capture storage

Handle-Based Dispatch

  • TWO systems: HANDLE_METHOD_DISPATCH (methods) and HANDLE_PROPERTY_DISPATCH (properties)
  • Both must be registered. Small pointer detection: value < 0x100000 = handle.

objc2 v0.6 API

  • define_class! with #[unsafe(super(NSObject))], msg_send! returns Retained directly
  • All AppKit constructors require MainThreadMarker

Recent Changes

Keep entries to 1-2 lines max. Full details in CHANGELOG.md.

  • v0.5.184 — Fix #157 via PR #165: four typed-array bugs. (1) new Int32Array(3) (and other numeric-length ctors) produced length 0 because TypedArrayNew codegen passed the length through unbox_to_i64, which masks the lower 48 bits of a plain f64 — 3.0_f64 bits are 0x4008_… with lower 48 zero. Fixed at codegen by detecting literal integer/float args and calling js_typed_array_new_empty directly; non-literal args go through a new js_typed_array_new(kind, val) runtime dispatch that peels the NaN-box tag (POINTER → copy from array, INT32 → length, plain double → length). (2) Negative element values stored as NaN because jsvalue_to_f64 only accepted top16 < 0x7FF8 as a plain double, but negative doubles have top16 ≥ 0x8000 and fell through to the tag path returning f64::NAN. Widened to top16 < 0x7FFA || top16 >= 0x8000 so negative doubles and non-tag NaN patterns pass through unchanged. (3) Uint8ClampedArray was silently mapped to KIND_UINT8 in ir.rs::typed_array_kind_for_name, skipping the clamp semantics — c[0] = 300 produced 44 (truncate-wrap) instead of 255. New KIND_UINT8_CLAMPED = 8 + CLASS_ID_UINT8_CLAMPED_ARRAY with ToUint8Clamp (NaN→0, ≤0→0, ≥255→255, otherwise round-half-to-even + clamp) in store_at. Name mapping in ir.rs + removal from lower.rs's TypedArrayNew exclusion. (4) Added typed-array dispatch to js_array_set_f64 / js_array_set_f64_extend so tArr[i] = v through the generic array path still goes through per-kind store instead of writing raw f64 at the wrong offset. Also added TypedArrayNew arm to refine_type_from_init_simple so .length and method dispatch take the typed-array fast path. Maintainer fixup on top of douglance's work: reverted the IndexGet/IndexSet numeric-fallback routing (from js_array_get_f64 call back to inline ptr+8+idx*8) to preserve the load-bearing Object-with-numeric-keys storage (const constMap: Record<number, string> = {}; constMap[0] = "x") — the dispatch scheme treats non-registered pointers as ArrayHeader and misreads the ObjectHeader's first field. Typed-array element indexing has a dedicated TypedArrayGet/Set HIR path, so the revert doesn't reintroduce the original #157 alignment bug. Added test_edge_enums_const + test_edge_iteration to known_failures.json as CWD-dependent flakes (same family as test_edge_map_set in v0.5.178) — the revert above doesn't eliminate path-dependency, confirming the divergence is a separate pre-existing compiler bug surfaced by (but not caused by) the #157 branch.
  • v0.5.183 — Partial fix for #92 via PR #166: intrinsify the 14 Node-style Buffer numeric read accessors (readInt8/readUInt8/readInt16{BE,LE}/readUInt16{BE,LE}/readInt32{BE,LE}/readUInt32{BE,LE}/readFloat{BE,LE}/readDouble{BE,LE}). New classify_buffer_numeric_read + try_emit_buffer_read_intrinsic in lower_call.rs (~160 lines); hooks into the existing PropertyGet dispatch at the is_buffer_class branch. Fast path fires when the receiver is an Expr::LocalGet(id) and id has a buffer_data_slots entry. Extended buffer_data_slots registration in codegen.rs to cover Buffer-typed function parameters (e.g. function decodeRow(row: Buffer, n: number)) — pre-registers a data-ptr slot at function entry, guarded by has_any_mutation (skips params mutated or reassigned) and boxed_vars (skips cross-closure mutation). Each read lowers to one load of the data_ptr from the pre-computed slot, one gep, one byte-width load, one @llvm.bswap.iN for BE widths, one sitofp/uitofp to double. Measured on the issue's repro (readInt32BE × 12.5M, macOS arm64): Perry 29ms vs Node 37ms vs Bun 104ms — before the intrinsic, Perry was ~145ms (5× slower than Bun, 4× slower than Node); after: 3.6× faster than Bun, 1.3× faster than Node. otool -tV confirms rev32.4s + 128-bit NEON loads in the hot loop (LLVM auto-vectorizes the emitted intrinsic). Untracked receivers (object fields, closure captures, anything not tagged at the let-site) still go through the existing runtime dispatch unchanged — strictly additive. BigInt64 reads skip the intrinsic (would need inline BigInt alloc). Uint8Array-typed params deliberately excluded (pre-existing crash when a program defines both Buffer-param and Uint8Array-param functions and invokes them in sequence — reproducible on main with param-tracking disabled; tracked separately). New test-files/test_buffer_numeric_read_intrinsic.ts covers all 14 variants + sign-extension edge cases (i32 MIN/MAX = ±2147483648, u16 0xFFFF, u32 0xFFFFFFFF, negative doubles in LE) + a sumRow(row: Buffer, n: number) case exercising the param intrinsic; matches Node byte-for-byte on every line. Added to the SKIP_TESTS / known_failures.json ci-env list alongside other Buffer tests that compile cleanly on macOS 15.x but fail on the GitHub macOS-14 runner (SDK/linker gap, no perry-side bug).
  • v0.5.182 — Fix #143 via PR #162: connection.execute(sql, params) was delegating to connection.query(sql) and silently discarding the params argument in both mysql2 and pg stdlib drivers. (mysql2) lifted ParamValue + extract_params_from_jsvalue to pub(crate) in mysql2/pool.rs; rewrote js_mysql2_connection_execute in mysql2/connection.rs with full param binding — same dual-handle pattern (MysqlConnectionHandle vs MysqlPoolConnectionHandle) already used in connection_query. (pg) added local ParamValue enum + extract_params_from_jsvalue + is_row_returning_query helpers to pg/connection.rs, rewired js_pg_client_query_params to bind params and split between fetch_all (SELECT → rows) and execute (non-SELECT → rowCount). Enum+extractor are duplicated between mysql2 and pg because their sqlx type constraints differ; tolerable, can consolidate later.
  • v0.5.181 — Fix #155 via PR #164: console.time / timeLog / timeEnd reported near-zero elapsed times because Instant::now() was captured after label_from_str_ptr string decoding and the CONSOLE_TIMERS TLS borrow in js_console_time, adding microseconds of bookkeeping noise before the start time was recorded. Moved the Instant::now() capture to the first line of the function. Separate issue: Perry's native LLVM binary runs tight CPU loops orders-of-magnitude faster than Node's JIT, so the gap test's for-loop-between-console.time-and-timeLog shape will always differ (LLVM constant-folds the dead accumulator to ~0 wall-clock, Node takes ~1.4 ms interpreted) — correct behavior, not a bug. Added sed -E 's/^([^:]+): [0-9]+(\.[0-9]+)?(ms|s)$/\1: <timer>/g' to run_parity_tests.sh's normalize_output so the parity comparison checks the format of timer output without requiring identical ms values between JIT and native runtimes. Updated test_gap_console_methods known-failure reason: table/dir/group/timer differences all resolved, only remaining diff is console.trace stack-frame format (Node JS call frames vs native C frames).
  • v0.5.180 — Fix #156 via PR #163: two bugs exposed by test_gap_global_apis.ts. (1) queueMicrotask callbacks never fired before await continuation on already-settled promises because Perry's await lowering went straight to await.check — js_drain_queued_microtasks() only lives inside js_promise_run_microtasks() in the await.wait block, which is skipped when the promise is already settled (await Promise.resolve()). Inserted a new await.drain_once block before the first state poll that calls js_drain_queued_microtasks() unconditionally; pending promises drain once then fall into the existing wait loop (which drains per tick), settled promises drain once and fall through to await.settled. Also added js_drain_queued_microtasks extern decl in runtime_decls.rs. (2) performance.now() returned integer-ms because Expr::PerformanceNow was routed to js_date_now() (which does as_millis() as f64) with a stale "stand-in" comment — a 1M-iteration tight loop finishes under 1ms on optimized builds, so t2 - t1 truncated to 0. Switched to js_performance_now() (already declared + implemented as as_secs_f64() * 1000.0). test_gap_global_apis.ts now matches Node byte-for-byte on microtaskRan / microtask order / performance.now monotonicity / elapsed > 0.
  • v0.5.179 — Fix #120 via PR #160 (cloud-authored, audited): Windows CLI executables had their PE subsystem set to WINDOWS (2) instead of CONSOLE (3), so console.log output was silently detached. The actual flag selection (/SUBSYSTEM:CONSOLE vs /SUBSYSTEM:WINDOWS gated on ctx.needs_ui) already landed in v0.5.133 as an inline ternary at compile.rs:6240-ish; this PR extracts it into a named windows_pe_subsystem_flag(needs_ui: bool) -> &'static str helper with a doc-comment pointing at #120, and adds two windows_link_tests unit tests (cli_build_uses_console_subsystem / ui_build_uses_windows_subsystem) that pin the flag choice so a future refactor can't silently re-break it. No behavior change; verified by CI including the windows-2022 doc-tests runner.
  • v0.5.178 — Fix-forward for v0.5.177 release-packages failure (tests gate red on three distinct regressions exposed by the fresh CI run): (1) App({...}) inside docs/examples/ui/ — the Phase 3 anon-class synthesis in v0.5.172 started wrapping closed-shape {title,width,height,body} literals into new __AnonShape_N(...), but the perry/ui: App() handler at lower_call.rs:2436 still let Expr::Object(props) = &args[0] else { bail }'d, so every UI doc example on macOS/Ubuntu/Windows failed with "App(...) requires a config object literal." Fix: swap the raw Object match for extract_options_fields(ctx, &args[0]) (the same helper perry/thread's spawn options already use for both raw-Object and AnonShape-New paths). 19/27 doc-tests → 27/27. (2) just_factory stack overflow in repro_test.rs — a test added alongside class_extends_plus_top_level_call_overflows in v0.5.167 era to narrow a pre-existing compiler stack overflow (top-level const x = fn() + factory returning nested object literal). The sibling test was already #[ignore]d; just_factory was not, so cargo-test aborted with SIGABRT. Marked #[ignore] with the same rationale; real fix tracked separately. (3) new Set([...]) without explicit <number> type args — refine_type_from_init in codegen/type_analysis.rs:80 was emitting HirType::Named("Set") for Expr::SetNewFromArray, but is_set_expr (same module, :564) only matches HirType::Generic { base: "Set", .. }. So const s = new Set([1,2,3]); s.has(1) silently missed the Set fast path and returned undefined instead of true. Mirror bug in perry-hir/src/lower_types.rs's ast::Expr::New arm (Phase 4 inference) which also fell to Type::Named without explicit type_args — fixed by routing Map/Set/WeakMap/WeakSet/Array/Promise through Type::Generic { base, type_args: [] } when no args are given (intrinsic generics can't be Named). Parity suite: test_edge_map_set's Set.has() calls now hit the fast path; the test's specific setA.forEach-over-setB.has pattern passes for every shape except one path-dependent environmental flake (same file MD5 compiles + runs correctly from /tmp/ but produces wrong intersection from project root — different bug, added to known_failures.json with the repro noted).
  • v0.5.177 — Fix #142 via PR #148: Math.tan/asin/acos/atan/atan2 were lowering to silent identity functions. The five arms at crates/perry-codegen/src/expr.rs:5417-5424 had an old "no runtime wrappers yet, no LLVM intrinsics for these" comment and fell through to lower_expr(ctx, o) — returning the argument unchanged with no diagnostic. The runtime functions (js_math_tan/asin/acos/atan/atan2 in perry-runtime/src/math.rs:46-62, each a thin f64::tan() etc.) and the extern declarations (runtime_decls.rs:1488-1499) had actually been in place for a while; the codegen wiring was just missing. Replaced the fall-through with five ctx.block().call(DOUBLE, "js_math_*", ...) arms matching the shape of the already-working sinh/cosh/tanh arms three lines above. atan2(y, x) evaluates y first then x (JS left-to-right argument order) and passes both to js_math_atan2. Verified against Node --experimental-strip-types: Math.tan(1) = 1.557… (was 1), Math.atan2(0,-1) = π (was -1), Math.asin(1) = π/2, Math.acos(1) = 0, Math.atan(1) = π/4 — all within last-digit libm rounding. Merged via conflict-resolved cherry-pick since the PR branch was cut at v0.5.164 and main had advanced to v0.5.176.
  • v0.5.176 — Fix #158: Map/Set now treat -0 and +0 as the same key (SameValueZero, 23.1.3.9 / 23.2.3.1). Added a normalize_zero(v: f64) -> f64 helper in crates/perry-runtime/src/map.rs and set.rs that rewrites -0 bits (0x8000_0000_0000_0000) to +0 via an v == 0.0 IEEE check — safe against NaN-boxed tagged values because any tag in the upper 16 bits makes the f64 a NaN and NaN == 0.0 is false. Wired into js_map_set / _get / _has / _delete and js_set_add / _has / _delete so both insert and lookup paths normalize. Previously numMap.set(0,"a"); numMap.set(-0,"b") yielded size=2 with get(0) returning "a"; now yields size=1 with get(0)="b" matching Node's --experimental-strip-types.
  • v0.5.175 — Close two review-flagged bypasses introduced by Phase 3 / perry/thread compile-time work. (1) new Error(msg, { cause }) shorthand + paren-wrapped options. The AST-level extraction added to crates/perry-hir/src/lower.rs:10363-10386 to survive Phase 3 (anon-shape synthesis converts {cause: e} into Expr::New { __AnonShape_N } before the HIR Object-match would see it) only handled Prop::KeyValue at the outer Object — so the canonical ES2022 form catch (cause) { throw new Error('msg', { cause }) } (shorthand) and new Error('msg', ({ cause: e })) (paren-wrapped) both silently lost .cause and emitted a plain ErrorNew(Some(msg)). Fix: peel Expr::Paren before matching and add a Prop::Shorthand(ident) arm that resolves the ident via ctx.lookup_func / lookup_local / lookup_class the same way lower.rs's own Object-literal lowering does. Verified: both repros now print the expected cause message and match node byte-for-byte. (2) perry/thread named-function bypass. The v0.5.174 mutable-capture check only pattern-matched Expr::Closure, so function worker(n){counter++;} parallelMap(xs, worker) (semantically identical to the rejected inline form) fell straight through and compiled silently — defeating the compile-time safety claim. FnCtx doesn't carry the full HIR function table (only func_names: FuncId → String), so we can't cheaply resolve the callee body at codegen time. Conservative fix: when the callback is Expr::FuncRef / Expr::LocalGet / Expr::ExternFuncRef, bail with a diagnostic that names the method + points at the inline-closure workaround (parallelMap(xs, (x) => myFn(x))) + links docs/src/threading/overview.md#no-shared-mutable-state. Pure function workers that don't actually need the analysis still have to wrap but the wrap is trivial; unsafe named workers that silently lost writes are now loud compile errors. Verified against the ultrareview's exact repro (let counter=0; function worker(n){counter++;...} parallelMap([1..4], worker) → compile bail). Proper long-term fix (walk FuncRef body via a HIR-time pass with the full function table in scope) tracked for follow-up — the conservative bail is sound in the meantime. No codegen emitted change for the closure-ok path; gap tests steady at 22/28; HIR tests 40/40.
  • v0.5.174 — Fix #146: perry/thread primitives now actually work, and mutable outer captures are rejected at compile time. Before this bump, parallelMap / parallelFilter / spawn imported from perry/thread flowed into HIR as NativeMethodCall { module: "perry/thread", method, object: None }, but perry-codegen/src/lower_call.rs's NATIVE_MODULE_TABLE had zero rows for that module — so receiver-less dispatch missed, fell through to the TAG_UNDEFINED early-out, and every call silently returned undefined. The runtime side (js_thread_parallel_map / js_thread_parallel_filter / js_thread_spawn in perry-runtime/src/thread.rs) had been in place for a while with no callers. Also fixed: the "compile-time safety" claim in perry-runtime/src/thread.rs:99-100 / docs/src/threading/overview.md / docs/src/introduction.md was not backed by any pass — codegen had let _ = mutable_captures; that silenced a warning and discarded the field. Wired up three NativeModSig rows (perry/thread → parallelMap/parallelFilter/spawn, all args: &[NA_F64, NA_F64] or [NA_F64], ret: NR_F64) plus three extern decls in runtime_decls.rs. For the compile-time safety half, added a mutable-capture check inline in lower_native_method_call's receiver-less dispatch that walks the closure body for LocalSet / Update writing to any LocalId not introduced inside the body (params or lets). Can't use the closure's own mutable_captures field alone: HIR lowering drops module-level LocalIds from captures via filter_module_level_captures (see lower.rs:457, v0.5.91-era fix for const f = () => f(...) sibling-closure races), so let counter = 0; parallelMap(data, () => counter++) ends up with captures: [], mutable_captures: [] at the HIR even though the body writes to counter. New helpers collect_closure_introduced_ids + find_outer_writes_{stmt,expr} walk the body themselves, stop at nested closure boundaries (those get their own check if threaded), and bail with a message naming the method + LocalId + pointing at docs/src/threading/overview.md#no-shared-mutable-state. Verified end-to-end: parallelMap([1,2,3,4], x => x*10) now returns [10,20,30,40] (was undefined); parallelFilter / spawn same shape; let c = 0; parallelMap(d, () => c++) now errors at compile time with "closure passed to parallelMap writes to outer variable (LocalId 0)"; const rate = 1.08; parallelMap(d, x => x*rate) still compiles (const value captures are safe — deep-copied snapshot). Tests: new docs/examples/runtime/thread_primitives.ts + _expected/runtime/thread_primitives.stdout covers the runtime half end-to-end via the existing doc-tests stdout-diff harness. New scripts/run_thread_tests.sh covers the compile-error half: 3 mutation cases that must fail compilation with the expected substring + 1 const-capture case that must succeed, wired into .github/workflows/test.yml right after the test-files/*.ts compile-smoke loop. CI catches regressions in both halves: drop a NATIVE_MODULE_TABLE row → thread_primitives.stdout diff fails; drop the mutable-capture check → run_thread_tests.sh fails all three expected-error cases.
  • v0.5.173 — Full benchmark sweep on current main — Perry now wins every workload in the main suite (15/15 vs Node, 15/15 vs Bun) AND beats Node on json_roundtrip (Perry 314ms vs Node 377ms, best-of-5). Previously json_roundtrip was Perry's only loss: v0.5.166 measured it at 588ms (1.58× slower than Node). Unclear exactly which commit between v0.5.166 and v0.5.173 closed the gap — likely a combination of the object-layout work (Phase 1, Phase 3 anon-shape classes, Phase 4 return-type flow) reducing allocator/type pressure inside JSON.parse's per-element object construction. Peak RSS still higher than Node (310MB vs 187MB, 1.66× ratio — Bun 84MB is still ~4× less than Perry), so the allocator-pressure work tracked in #149 is still the right follow-up for closing the remaining Bun gap. Polyglot sweep on same commit: Perry leads loop_overhead (12ms vs 96ms Rust/C++), math_intensive (14 vs 48), accumulate (25 vs 95), array_read (3 vs 9), ties fibonacci with C++/Rust, trails by 1-2ms on object_create / nested_loops / array_write where stack-struct layout gives the compiled pack a natural floor. Updated README.md tables (Perry vs Node/Bun + Perry vs compiled), benchmarks/baseline.json json_roundtrip row (commit c89b3ad5, dated 2026-04-23), and dropped the "except json_roundtrip" caveat from the README perf headline. The narrative around the polyglot loop_overhead gap stays the same — fast-math flag default, not a codegen-backend advantage — benchmarks/polyglot/RESULTS_OPT.md is still accurate.
  • v0.5.172 — Fix #20: console.trace() now emits a real native backtrace (via std::backtrace::Backtrace::force_capture) to stderr after the Trace: <msg> line instead of only echoing the message. New js_console_trace in builtins.rs filters std::backtrace_rs / js_console_trace noise and collapses duplicate unresolved frames; symbolicated frames require PERRY_DEBUG_SYMBOLS=1 (without it, LLVM-stripped builds show __mh_execute_header frames).
  • v0.5.170 — Phase 4.1: method-call return-type inference (lower_types.rs:232) consults a new class_method_return_types registry so new C().label() binds with the method's inferred type instead of Type::Any. 40 HIR tests green; gap stable 18/28. Inheritance chain lookup not yet implemented.
  • v0.5.169 — Phase 4 expansion: body-based return-type inference now covers class methods (lower_decl.rs:1532), getters, and arrow expressions (lower_types.rs:210). Async wraps in Promise<T>; generators skipped; annotation wins over inference. Gap 17→18/28.
  • v0.5.168 — Fix #150: Object.getOwnPropertyDescriptor returned undefined on Phase 3 anon-shape literals — mark_all_candidate_refs_in_expr (collectors.rs:3353) catch-all now escapes all candidates on un-enumerated HIR variants, matching the defensive pattern already used elsewhere.
  • v0.5.167 — Phases 1+4 of Static-Hermes object-layout parity: (1) object-literal shape inference replaces the Expr::Object → Type::Any bail with a walker that builds Type::Object for closed shapes; (4) body-based return-type inference for free functions. Phase 3 (synthetic __AnonShape_N class) infra landed but disabled — needs escape analysis or annotation-opt-in to avoid breaking Object.*/JSON.stringify/Proxy semantics. 28 new HIR integration tests.
  • v0.5.166 — Fix #145: README's "beats every benchmark" claim now names the json_roundtrip exception (1.6× slower than Node, 2.4× slower than Bun). Added row to the comparison table; filed #149 for the stdlib JSON perf work.
  • v0.5.165 — Fix #144: TypeScript decorators were parsed into HIR but silently dropped at codegen. New reject_decorators helper in lower_decl.rs:394 hard-errors on every decoration point; README flipped to ❌. Same warn→bail reasoning as v0.5.119.
  • v0.5.164 — Fix #140: restore autovectorization of pure-accumulator loops regressed v0.5.22→v0.5.162. i32 shadow slot now gated on actual index-use (collect_index_used_locals); asm-barrier skipped when body writes to outer locals. loop_overhead 32→12ms, math_intensive 48→14ms, accumulate 97→24ms.
  • v0.5.163 — docs+chore (#139, tracking #140): deleted 17 stale bench_*.ts scratchpads + 15 result logs, reran polyglot suite, documented loop_overhead/math_intensive/accumulate regressions vs v0.5.22 baseline and fast-math-default narrative in README + RESULTS.md.
  • v0.5.162 — Fix #136: sendToClient(handle, msg) / closeClient(handle) named imports from 'ws' silently no-op'd (missing from the receiver-less dispatch table). Added js_ws_send_to_client / js_ws_close_client bridges + NativeModSig entries.
  • v0.5.161 — Fix #135: --target web hung on break/continue nested in if/switch/try. WASM emitter's hardcoded Br(1)/Br(0) replaced with Br(block_depth - break_depth.last()) — same formula labeled-break/continue already used.
  • v0.5.160 — PR #134 (closes #131): V2.2 per-module on-disk object cache at .perry-cache/objects/<target>/<key:016x>.o. Atomic tmp+rename writes; djb2 key covers source hash + CompileOptions + codegen env vars + perry version. --no-cache/PERRY_NO_CACHE=1/perry cache info|clean; ~29% warm speedup.
  • v0.5.159 — Fix winget submission in release-packages.yml: wingetcreate --submit looks up the authenticated user's fork, not the org's. Pre-step now resolves the token's user via gh api /user and syncs <user>/winget-pkgs before submit.
  • v0.5.158 — Fix #133: five --target web (WASM) bugs — (1) primitive method dispatch via typeof fast-path in __classDispatch; (2) Math.sin/cos/tan/atan2/exp (+ MathHypot) routed through emit_memcall; (3) xs.push on top-level arrays (module globals, not locals) via new emit_local_or_global_get; (4) Firefox/Safari NaN-tag canonicalization at FFI boundary — new wrapFfiForI64 decodes BigInt directly; (5) INT32-tagged constants crashed wasm-bindgen — __bitsToJsValue now decodes INT32_TAG.
  • v0.5.157 — Fix #128: obj.field read NaN on --target android (Bionic Scudo allocator places heap below the Darwin mimalloc window). Codegen receiver guard in PIC + .length fast-path replaced handle > 2 TB && < 128 TB with platform-independent NaN-box tag check (bits >> 48) & 0xFFFD == 0x7FFD.
  • v0.5.156 — Fix await-tests gate (v0.5.155): swap gh run list --workflow "Name" (silently returned [] in release-event context on CI) for gh api /repos/.../actions/workflows/{test,simctl-tests}.yml/runs?head_sha=$SHA. Retry-once + fail-loud on gh api errors.
  • v0.5.155 — Gate release-packages.yml on green Tests + Simulator Tests (iOS) for the exact tagged commit (new await-tests job, 45-min deadline). Added tags: ['v*'] to test.yml's push trigger so Tests actually runs on the release tag SHA. workflow_dispatch bypass preserved.
  • v0.5.154 — Drop run_with_timeout wrapper from simctl launch path. Its bash watcher-subshell + caller set -e produced spurious exit 143 on the fast path; with --console-pty gone, the 30s timeout's reason-to-exist is gone too.
  • v0.5.153 — Instrument scripts/run_simctl_tests.sh with per-phase timestamped trace lines to localize the post-v0.5.152 ~2:04 hang; added explicit timeout-minutes: 60/45 to simctl-tests workflow.
  • v0.5.152 — Drop --console-pty from scripts/run_simctl_tests.sh: when simctl's stdout is file-redirected the PTY master never sees EOF, so simctl hangs past LAUNCH_TIMEOUT even after the app process::exit(0)s. Trade "clean-exit verification" for "bundle launches" — still enough tier-2 signal.
  • v0.5.151 — Closed four perry/ui gaps: (1) alertWithButtons(title, msg, string[], (i)=>void) (split from 2-arg alert); (2) preferencesSet/Get widened to string | number in .d.ts; (3) macOS onTerminate/onActivate lifecycle hooks (AppDelegate overrides + test-mode invoke_* helpers); (4) LazyVStack rewritten on NSTableView with real virtualization (~15 realized rows for 1000-count).
  • v0.5.150 — --app-bundle-id CLI flag now honored on --target ios-simulator/--target ios. iOS branch in compile.rs:6442 previously resolved via perry.toml → package.json → default only, ignoring the CLI. Closes the tier-2 simctl workflow (pairs with v0.5.147–149).
  • v0.5.149 — iOS-simulator Info.plist now emits iPhoneSimulator / iphonesimulator / iphonesimulator26.4 for CFBundleSupportedPlatforms/DTPlatformName/DTSDKName (was hardcoded iPhoneOS, causing FBSOpenApplicationServiceErrorDomain code=4 on simctl launch).
  • v0.5.148 — xcrun simctl launch has no --setenv flag. Use SIMCTL_CHILD_KEY=VAL env prefix on the calling shell instead; simctl strips the prefix and forwards. Inline comment warns future readers so it doesn't get un-fixed a fourth time.
  • v0.5.147 — scripts/run_simctl_tests.sh: split --setenv=KEY=VAL into --setenv KEY=VAL (two argv tokens). Superseded by v0.5.148 after verifying simctl has no such flag at all.
  • v0.5.146 — perry.nativeLibrary.targets.<plat>.metal_sources sibling to swift_sources (closes #124). New compile_metallib_for_bundle shells out to xcrun -sdk <sdk> metal/metallib and writes <app>.app/default.metallib. Unblocks Bloom's SwiftUI shader path.

Older entries → CHANGELOG.md.