Merge remote-tracking branch 'upstream/main'

Brings in 39 upstream commits (a3b31c0..7d1dc9c) on top of the
local context-mode experimental patches (b72f6f9, c3d1141, 6d28ca7).

Resolution notes:

* The local CHANGELOG.md diverged only in home-directory paths
  (`/Users/amlug/...` vs `~/projects/...`) that upstream scrubbed in
  PerryTS#7165. CHANGELOG.md is FROZEN at v0.5.1264 (see
  `changelog.d/README.md`), so the file is restored to its state at
  the merge base (df7214b, the v0.5.1264 version bump). The new
  context-mode entries go in `changelog.d/7220-context-mode-patches.md`
  instead, per the per-PR fragment policy.

* The five perry-related file changes (eval_classifier, expr_new,
  alias_tracking, freshness, lib) all auto-merged cleanly. The
  workspace reorg from `perry/...` to `crates/perry/...` is picked
  up via git's rename detection, so the `freshness.rs` patch rides
  along at its new path.

* No upstream-side changes were dropped or hand-edited.

Author: Brad McCormack

.github/workflows/gc-root-dominance.yml

@@ -0,0 +1,153 @@
+name: GC Root Dominance
+
+# Static gate for the invariant a GC-managed value's root store must DOMINATE
+# every subsequent site that can trigger a collection (#7154).
+#
+# Two bugs of this class shipped before there was an instrument for it. #7184:
+# the root store was emitted but its shadow-slot index fell outside the pushed
+# frame, so `js_shadow_slot_bind` bounds-checked it into a silent no-op. #7192:
+# the store was emitted in-frame but AFTER a call that allocates. Both present
+# identically — a *rooted* slot holding a dangling pointer, surfacing cycles
+# later as "TypeError: value is not a function" — and neither is visible to any
+# runtime GC probe, because at the moment of the collection there is nothing
+# for the collector to find. A static pass over the emitted IR is the only
+# instrument that sees them before they crash, which is why this is a gate and
+# not a benchmark.
+#
+# THIS JOB IS DESIGNED TO BE ABLE TO FAIL, and is checked against all four ways
+# a gate can be unable to (CLAUDE.md):
+#
+#   1. no `continue-on-error`, no `|| true`, no pipe between the checker and
+#      the shell's exit status;
+#   2. NOT yet in branch protection's required contexts. This was deliberate at
+#      first — a new gate has never been green, so promoting it immediately
+#      blocks every open PR — but the second step was never taken, and in the
+#      meantime the job WAS red on `main` and blocked nothing: the five
+#      ClassExprFresh hits now tracked in #7211 have been reported on every run
+#      since #7198 and went unread. That is hazard 2 doing exactly what the
+#      corollary in CLAUDE.md warns about.
+#
+#      **ACTION REQUIRED, and it is not something this workflow can do to
+#      itself**: with the allowlist below the job is green on `main`, so a
+#      repo admin must add `gc-root-dominance` to branch protection's required
+#      contexts. Until that happens this file is documentation, not a gate.
+#      See docs/src/internals/gc-rooting-invariant.md, "Promoting this gate".
+#   3. `concurrency` cancels pull-request runs only, never `main` runs;
+#   4. the subject is ASSERTED live, not assumed, at three levels.
+#      `--self-test` proves the checker still reports a planted violation in
+#      hand-written IR and still clears the control. `--seeded-violations`
+#      goes further and plants collection points into the REAL corpus,
+#      requiring every one to be reported -- that is what catches the case
+#      where perry's emitted IR drifts to a shape the parser can no longer
+#      read, which frozen fixtures cannot detect. And `--min-files` /
+#      `--min-binds` / `--min-funcs` refuse a clean verdict over a corpus with
+#      too few modules, root stores or functions to have exercised anything.
+#      An empty `.perry-trace/llvm` is a routine outcome of a failed compile,
+#      so "0 violations" over 0 files must be an error rather than a pass.
+#
+# Known-remaining violations live in scripts/gc_root_dominance_allowlist.json,
+# one named entry each with an issue and a written justification -- NOT a
+# numeric threshold, which cannot tell a new violation from an old one. An
+# entry that matches nothing fails the build, so a fixed bug's entry must be
+# deleted rather than left to widen coverage later.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  # Per-event groups, cancelling PR runs only. A shared group with an
+  # unconditional cancel-in-progress starves `main`: on a deep runner queue
+  # every merge cancels the previous main run before it reaches a runner, and a
+  # gate that is always cancelled never fails. Same reasoning as gc-ratchet.yml.
+  group: gc-root-dominance-${{ github.event_name }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+env:
+  CARGO_TERM_COLOR: always
+  MACOSX_DEPLOYMENT_TARGET: "13.0"
+
+jobs:
+  gc-root-dominance:
+    runs-on: macos-14
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      # Fast structural failure first: prove the checker can still fail before
+      # spending a compiler build on it. This is the arm that would have caught
+      # `PERRY_GC_FORCE_EVACUATE` being inert for every test that "exercised"
+      # it (#6942/#6946).
+      - name: Checker self-test (can this gate still fail?)
+        run: python3 scripts/gc_root_dominance_check.py --self-test
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache cargo
+        uses: actions/cache@v6
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-gcdom-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: ${{ runner.os }}-cargo-
+
+      - name: Build perry and the runtime archives
+        run: |
+          set -euo pipefail
+          # perry-runtime and perry-stdlib are rlib-only; the .a files come from
+          # the -static wrapper crates. The package set is fixed so cargo
+          # feature unification matches every other job that builds the
+          # compiler.
+          cargo build --release -p perry -p perry-runtime-static -p perry-stdlib-static
+          for artifact in perry libperry_runtime.a libperry_stdlib.a; do
+            test -s "target/release/$artifact" \
+              || { echo "::error::target/release/$artifact was not produced"; exit 1; }
+          done
+
+      # The source list and the env knobs live in the script, not here, so that
+      # reproducing a CI failure is one command rather than a re-read of this
+      # YAML. A retyped invocation that drops PERRY_GC_MOVING_LOOP_POLLS
+      # produces IR in which the bug is not expressible at all, and the local
+      # run then "cannot reproduce" a real finding.
+      - name: Emit the IR corpus
+        run: ./scripts/gc_root_dominance_corpus.sh ir-corpus
+
+      - name: Check root-store dominance
+        run: |
+          set -euo pipefail
+          # No pipe: the checker's own exit status is the job's.
+          #
+          # The floors are asserted, not hoped for. On the corpus as of this
+          # commit the run reports ~1993 functions / 117 modules / 2501 root
+          # stores, so these sit below that with room for churn and well above
+          # "something compiled". Raise them when the corpus grows; never lower
+          # one to make a run pass -- a shrinking corpus is the finding.
+          #
+          # --seeded-violations plants 40 collection points into this very IR
+          # and requires all 40 to be reported. That is the arm that fails if
+          # the checker has stopped understanding perry's output, which is the
+          # only way a green verdict here could be a lie.
+          python3 scripts/gc_root_dominance_check.py ir-corpus \
+            --moving-only \
+            --min-files 90 --min-binds 1500 --min-funcs 1200 \
+            --allowlist scripts/gc_root_dominance_allowlist.json \
+            --seeded-violations 40 \
+            -v
+
+      - name: Upload the IR corpus on failure
+        if: failure()
+        uses: actions/upload-artifact@v7
+        with:
+          name: gc-root-dominance-ir
+          path: ir-corpus
+          retention-days: 7

.github/workflows/test.yml

@@ -967,6 +967,20 @@ jobs:
         if: github.event_name != 'pull_request'
         run: ./scripts/gc_repsel_matrix.sh --no-build --arms all --json gc-repsel-matrix.json
 
+      # GATING, and deliberately so. CLAUDE.md's GC knob kill-policy requires
+      # every GC knob to have an arm that exercises it; the #7154 instruments
+      # (PERRY_GC_PROTECT_FROMSPACE, PERRY_GC_ZEAL) would otherwise be dark
+      # knobs on the subsystem with this repo's worst history of configuration
+      # rot. This asserts BOTH defaults — inert with the knobs unset, live with
+      # them set — and refuses to pass unless the zeal arm forced strictly more
+      # collections than the pressure-only arm, so it cannot go green having
+      # run zero copying minors (the #6942 / #7024 / #7025 failure mode).
+      # The detection property itself is a required-gate unit test:
+      # gc/tests/fromspace_protect.rs::quarantine_catches_a_planted_stale_from_space_deref.
+      # ~20s: the fixture is sized for ~1200 back-edge polls, not #7154's 240k.
+      - name: GC rooting-bug instruments (inert-when-off, live-when-on)
+        run: ./scripts/gc_instrument_smoke.sh target/release/perry
+
       - name: Run GC write-barrier stress tests
         # Informational: these are ~200s nondeterministic corruption-window
         # hunts (#5029). Kept out of the gate so a flake never blocks a PR.
@@ -1218,6 +1232,7 @@ jobs:
           python3 scripts/compiler_output_regression.py census-self-test
           python3 scripts/compiler_output_regression.py census-knob-isolation-self-test
           python3 scripts/compiler_output_regression.py census-determinism-self-test
+          python3 scripts/compiler_output_regression.py census-temp-hygiene-self-test
           python3 -m unittest tests.test_repsel_census
 
       - name: Build compiler
@@ -1235,6 +1250,21 @@ jobs:
             --repeat 2 \
             --jobs 4
 
+      # #7144. The other consequence of content-addressing the `.ll`: workers
+      # holding identical IR share the name, so #7135 stopped deleting it and
+      # nothing else did — one leftover per distinct IR ever compiled. CI never
+      # saw it (runner temp dirs are reclaimed) while developer machines
+      # reached 29 GB. This step compiles with `TMPDIR` pointed at an empty
+      # directory and asserts it is still empty afterwards; note that a
+      # repeat-and-compare check would NOT have caught it, because identical
+      # IR reuses the identical name.
+      - name: Temp-directory hygiene
+        run: |
+          python3 scripts/compiler_output_regression.py census-temp-hygiene \
+            --perry target/debug/perry \
+            --repeat 2 \
+            --jobs 4
+
       - name: Promotion census
         run: |
           python3 scripts/compiler_output_regression.py census \

.gitignore

@@ -40,6 +40,8 @@ benchmarks/suite/assets/
 
 # `perry compile --trace llvm` dumps per-module .ll files here.
 .perry-trace/
+# scripts/gc_root_dominance_corpus.sh output (regenerate, never commit)
+ir-corpus/
 
 # Compiled test executables in the project root (no extension)
 /test_*

CLAUDE.md

@@ -8,7 +8,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 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.1269
+**Current Version:** 0.5.1277
 
 
 ## TypeScript Parity Status
@@ -132,6 +132,19 @@ Generational mark-sweep GC in `crates/perry-runtime/src/gc.rs` (default since v0
 
 **Escape hatches**: `PERRY_GEN_GC=0`/`off`/`false` reverts to full mark-sweep (bisection only). `PERRY_GEN_GC_EVACUATE=0`/`off`/`false` disables policy evacuation; `=1`/`on`/`true` is accepted as auto-policy allowed, not unconditional evacuation. `PERRY_GC_FORCE_EVACUATE=1` stress-copies every marked non-pinned nursery object only when generated write barriers are active and policy evacuation is allowed. `PERRY_GC_VERIFY_EVACUATION=1` panics if any mutable live slot still points at a forwarded nursery object after an evacuation/rewrite cycle. `PERRY_WRITE_BARRIERS=0`/`off`/`false` disables codegen-emitted write barriers at compile time and runtime exact helper barriers at runtime for benchmark/debug bisection; unset, `=1`/`on`/`true` keep barriers enabled. `PERRY_GC_DIAG=1` prints per-cycle diagnostics, including evacuation-policy decisions for considered cycles and `barriers_inactive` skips.
 
+### Rooting-bug instruments (#7154 family) — what each knob ACTUALLY gates
+
+A "GC value live but not rooted across a collection point" bug is invisible at collection time: there is nothing for the collector to find. It surfaces one or more cycles later, in a different function, as `TypeError: value is not a function`. These three knobs exist to collapse that latency. **All default-off; every boolean knob's OFF state is asserted in `gc/tests/fromspace_protect.rs`** (`…_DEPTH` is a magnitude, not a mode, so its floor and default are asserted instead). The instruments are **sabotage-tested**, not merely exercised: `quarantine_catches_a_planted_stale_from_space_deref` plants a #7184/#7192-shaped stale from-space pointer and asserts the instrument distinguishes it from the live object that would otherwise be recycled into those bytes — so a green protected run means the detector works, not that nothing was tried.
+
+| knob | gates EXACTLY | does NOT |
+|---|---|---|
+| `PERRY_GC_PROTECT_FROMSPACE=1` (or `poison`) | the from-space reset performed by the **copying minor** (`arena::copying_reset_from_spaces_and_flip`). Retired Eden + active-survivor blocks are detached into a bounded quarantine, poison-filled (`0xDEADBEEFBAADF0DE`, `obj_type = 0xDE`) and, at `=1`, `mprotect(PROT_NONE)`d. A stale deref then SIGSEGVs at the faulting instruction; the installed reporter names the address, the retiring minor, and the last-known object's `obj_type`/size, then restores `SIG_DFL` and re-faults so a core/debugger still sees the real site. `poison` skips `mprotect`. | change the non-moving minor's `arena_reset_empty_blocks`, the full mark-sweep's reclaim, old-gen defrag, or the malloc sweep. **A run with zero copying minors protects nothing** — check that `PERRY_GC_DIAG=1` prints a `[gc-fromspace-protect] retired_set=#N` line. |
+| `PERRY_GC_PROTECT_FROMSPACE_DEPTH=N` (default 4) | how many retired page-sets stay quarantined. Evicted sets are restored to RW and **recycled back into Eden**, never `dealloc`'d, so footprint is bounded at `N × from-space bytes`. `0` is clamped to 1 — a depth of 0 would read as ON and protect nothing. **Raise this when a suspected bug does not fault**: a value can cross hundreds of collections between its last valid observation and its stale use (one per back-edge poll under zeal). #7154's `new C(…)` reproducer needs `800` — its constructor crosses 600 polls, so the default 4 misses it silently. | — |
+| `PERRY_GC_ZEAL=1` | forces an evacuating minor at every **GC safepoint**: `js_gc_loop_safepoint` (loop back-edge) and the outermost microtask-pump safepoint. It bypasses exactly two things — the `GC_SAFEPOINT_PENDING` requirement in `js_gc_loop_safepoint`, and the `gc_budgeted_due_trigger()` "is anything due?" test in `gc_safepoint_moving_minor`. Also makes `gc_force_evacuate_enabled()` true, so survivors actually MOVE. | bypass `gc_safepoint_moving_minor`'s **entry guards**: a safepoint reached mid-allocation (`GC_FLAG_IN_ALLOC`), suppressed (`GC_FLAG_SUPPRESSED`), inside an unsafe FFI zone, under a non-zero `GC_ROOT_LOCK_DEPTH`, or during a budgeted cycle still returns without collecting. Nor does it override an explicit `PERRY_GEN_GC_EVACUATE=0` — that wins, and with it set zeal moves nothing and surfaces nothing. Nor does it emit loop polls — those need the **compile-time** `PERRY_GC_MOVING_LOOP_POLLS=1` (default off since #7161). Zeal on a binary compiled without polls only fires at event-loop boundaries; a compute-only loop never collects. Check `crate::gc::zeal_forced_collections()` is nonzero. There is deliberately **no level 2**: the alloc-point arm forces a conservative stack scan, which makes the copying minor ineligible, so an "every allocation" zeal would run non-moving minors and move nothing. |
+| `PERRY_GC_FROMSPACE_SCAN_ABORT=1` | now **implies** `PERRY_GC_FROMSPACE_SCAN=1`. It used to be inert alone (the scan never ran, so nothing aborted, and the run reported success). | — |
+
+`PERRY_GC_ZEAL=1 PERRY_GC_PROTECT_FROMSPACE=1` together is the pairing that turns a #7154 bug into an immediate precise fault. Compile *and* run with `PERRY_GC_MOVING_LOOP_POLLS=1` for in-loop coverage.
+
 ### GC knob kill-policy (binding)
 
 **Every GC env knob either has a required CI arm exercising its OFF state, or it is deleted after one release of soak.** At most one diagnostic-only knob may exist at a time, and it must be labelled untested.
@@ -237,3 +250,4 @@ Corollary: a *new* gate has never been green, so promoting it to required immedi
 - **Async-to-generator transform, body locals.** It boxes every body local into a shared mutable cell typed `Any`. Two consequences seen in the wild: per-iteration `let`/`const` bindings collapse for closures created in a loop, and computed numeric-key calls (`arr[i](x)`) lose their type proof and silently resolve by *method name*, evaporating the call.
 - **Native base-class subclassing.** A native base's surface is installed at `super()` time and its parent edge lives in the class registry; keying any of that on a literal `extends` name loses it for fieldless classes, indirect subclasses, and class expressions.
 - **Two prototype-resolution paths.** `CLASS_PROTOTYPE_OBJECTS` (synthetic: `Object.create`, plain-function ctors) vs `CLASS_DECL_PROTOTYPE_OBJECTS` (declared classes). `in`/`for…in` and `getPrototypeOf` have disagreed about the same chain.
+- **Root-store dominance in codegen.** *A GC-managed value's root store must **dominate** every subsequent site that can collect.* Three ways it has broken, all shipped: the store's slot index fell outside the pushed shadow frame so `js_shadow_slot_bind` bounds-checked it into a silent no-op (#7184); the store was emitted in-frame but **after** a call that allocates (#7192); and the value lives in a plain `alloca_entry` that is neither a shadow slot nor a temp root, so the collector never rewrites it (`lower_call/new.rs`'s inline-ctor `this_slot`, closed by #7207; `--unrooted-allocas` is the detector for that shape, and its remaining hits are #7210's). All three present identically — a *rooted* slot holding a dangling pointer, surfacing cycles later as `TypeError: value is not a function` — and **none is visible to any runtime GC probe**, because at the moment of the collection there is nothing for the collector to find. That is why #7154's from-space scan only ever saw offenders whose targets had already died. The instrument is static: `scripts/gc_root_dominance_check.py` over `--trace llvm` output (`--self-test` proves it can still fail). Only bites under `PERRY_GC_MOVING_LOOP_POLLS=1`, off by default since #7161 — so a green default run says nothing about this class. **Full writeup, every known shape and how to check your work: `docs/src/internals/gc-rooting-invariant.md`.** The CI gate is `gc-root-dominance.yml` over `scripts/gc_root_dominance_corpus.sh`; known-remaining hits are named one-per-entry in `scripts/gc_root_dominance_allowlist.json` (an entry that matches nothing FAILS, so a fix must delete its entry). A fifth shape is open as #7211: `ClassExprFresh` roots only when it thinks the static *initializers* collect, and never asks whether its own emitted `js_object_set_field_by_name` does — the sophisticated version of the mistake, where the author wrote a rooting predicate and it asked the wrong question.