gc: the PYPY_GC_DEBUG nurseries, a debug_check_consistency with a body, gc.get_count's second element, and the comments that outran the code - #1516

`pin_root` returns the normalized live word and is `#[must_use]` with a
message that sanctions `let _ =` for liveness-only pins. Six functions
spelled it that way and then read the pre-pin local, so the value handed
to the comparison was the one `normalize_published_slot` replaced:

  scan_dict_key_reentrant        key.obj
  scan_set_key_reentrant         key.obj
  w_set_contains_key_for_update  stored.obj, key.obj
  w_set_remove_key_for_update    stored.obj, key.obj
  error_is_exception             err.exc_object
  fileio_writebuf                view

At the four walk sites the read-back that repairs it already ran, one or
two statements below the comparison it was needed for. `err` is a shared
reference, so that one takes a local instead of writing back.

`fileio_writebuf`'s pin also had no `push_roots` bracket, so its slot
stayed on the shadow stack after the call returned.

Assisted-by: Claude

… walker

`CompiledCodeRegistry`, `CompiledCodeRegion`, `SafepointMap`,
`SafepointEntry`, `scan_frame` and `find_region` were never populated and
never consulted outside `collector.rs`'s own test module. Their only
non-test toucher, `MiniMarkGC::jit_free`, retained over a vec that is
always empty and has no production caller, so the `GcAllocator::jit_free`
trait method and its `GcHandle` forward go with it. `GcMap` had no
consumer besides `SafepointEntry` and follows.

`set_active_extra_root_walker` has no caller repo-wide, so
`ACTIVE_EXTRA_ROOT_WALKER` was never set and the two
`walk_active_extra_roots` calls in the minor drag-out and the labelled
root enumeration could not yield a root. The multi-registrar
`shadow_stack::walk_extra_roots` runs at both sites already.

Three of the removed types documented a role no backend performs:
`SafepointMap` said the Cranelift backend builds them during
compilation, `GcMap` said the backend records one at each guard.

Assisted-by: Claude

Comments only; no behaviour changes.

`at_outermost_activation` tests `EVAL_NESTING <= 2`, so module level and
one called function's loop both collect and refusal starts at depth 3.
`gc_interp::safepoint`'s doc and the `EvalActivationGuard::enter` comment
both described it as firing at the outermost activation only.

`get_possibly_forwarded_header` called its nursery case latent on the
grounds that every finalizer-queue registrant is stable-allocated.
`list_descr_new` takes its header from `w_list_new`, the collecting
nursery arm, and registers a finalizer for a builtin-layout subclass.

`rescan_major_stack_roots_black_and_drain` said a JitFrame lives in the
old generation. `alloc_off_gc_jitframe` returns `alloc_zeroed` memory
outside the GC heap, and it is reached only from the dynasm entry frames
and `dynasm_realloc_frame`; the other jitframe paths are nursery bumps.

`register_gc_alloc_collecting_hook` named the elidable bigint payload
helpers as its callers. The rooted sibling also carries every list
header, `w_weakref_new`, and builtin `str()`.

Assisted-by: Claude

The check was one `debug_assert_eq!` on `raw_malloc_might_sweep`, gated
at its call sites. Upstream opens the body with `if self.DEBUG:` and
asserts for real, so move the gate inside and drop the `debug_assert!`:
the checks now survive a release build, which is what `PYPY_GC_DEBUG`
arms them for, and a run that does not set it pays one load.

Adds the two list invariants the body opens with — no young
raw-malloced objects and no young objects with weakrefs — and the heap
half from `GCBase.debug_check_consistency`: enumerate every root, trace
the reachable graph, and run `debug_check_object` on each object once.
`debug_check_object` asserts that a pinned object is in the nursery, and
that any other is not and carries neither `GCFLAG_VISITED_RMY` nor
`GCFLAG_PINNED` out of the collection.

`OldGen::young_rawmalloced_is_empty` is the accessor the first of those
invariants reads.

`rawmalloc_sweep_candidates_require_sweeping_state` now arms the level
and loses its `#[cfg(debug_assertions)]`, since the assertion it expects
is no longer compiled out of a release build.

Assisted-by: Claude

`register_mutator`'s doc said unregistration was armed by a
`GcMutatorRegistration` thread-local in `init_gc_subsystem`. No such type
exists. The pairing is `pyre_interpreter::module::thread`'s `RuntimeThread`,
armed by `enter_runtime_thread` touching `RUNTIME_THREAD` right after this
call, and that order is load-bearing: `register_mutator` is where the thread
first touches all five root structures, so their destructors are registered
before `RuntimeThread`'s and run after it.

The two `TODO:` markers, on `pop_to` and `depth()`, described the `try_with`
both already use, and cited a `Drop` impl for `JitDriver` that does not exist.
State them as the rationale they are, and record that no caller is TLS-owned
today.

`try_pop_to`'s doc claimed it differs from `pop_to` by tolerating a
torn-down thread-local. Both reach it through `try_with`; the difference is
the balance assertion. Its callers are `Drop` impls, while
`ExportedState::release_roots` and `Trace::release_roots` are `Drop` paths
that keep the assert, so say it is a choice per site.

Assisted-by: Claude

… barrier

`TypeInfoLayout`'s doc said the reserved word makes the size match
`rffi.sizeof(GCData.TYPE_INFO) = 16`. `GCData.TYPE_INFO` is four words —
infobits, customdata, fixedsize, ofstoptrs — so 32 bytes on 64-bit, and
`VARSIZE_TYPE_INFO` extends it to eight; `get_type_id` allocates the narrow
struct for a fixed-size type and the wide one for a varsize type, so upstream's
per-entry size is not uniform. The row here is smaller, not equal, and the
reserved word is there to keep `TypeEntry`'s stride a power of two. The same
doc already said 32 bytes two sentences later.

`MAX_TYPES`'s doc called 1024 generous headroom above "the dozen-or-so types
pyre currently registers". A stock interpreter registers 867. Record the count
and the command that re-derives it.

`writebarrier_before_move` has no non-test caller and its guard rejects every
object pyre can build, because the only non-test setter of `HAS_CARDS`,
`alloc_in_oldgen_with_cards`, has no production caller either. Record which
sites owe the call when that changes: `W_ListObject`'s `object_insert`,
`object_remove` and `object_drain` shift items with a bare `ptr::copy`, where
upstream reaches the barrier through `rgc.ll_arraymove`.

Assisted-by: Claude

`moduledef.py` binds no `get_count`, `set_threshold`/`get_threshold`,
`set_debug`/`get_debug` or `freeze`/`unfreeze`/`get_freeze_count`, so these
answer to 3.14 alone and have no implementation to follow. Say so in the module
doc, and record that nothing grades them: `lib-python/conftest.py`'s testmap
skips `test_gc` as an implementation detail and `cpython_tests/run.py` carries
that skip forward, so the assertions live in `extra_tests/snippets/`.

`GC_THRESHOLD`'s doc said the collector has no generational allocation counters
to drive. It has counters; none shares `threshold0`'s unit. What schedules a
collection is `get_total_memory_used` against
`next_major_collection_threshold`, a byte reading, and the one knob retunable
after construction, `set_max_heap_size`, is a byte ceiling; an old-gen live
object count does exist as the arena collection's `live_objects`.

`GC_DEBUG`'s doc named no flag. `DEBUG_SAVEALL` is the one that shows why the
word cannot drive anything: with no refcount to have reclaimed acyclic garbage
first, the population reaching `OldGen::sweep_arenas_step`'s free-or-keep
callback is everything that died since the last major — 317 objects over 12
type ids inside the single collection `test_saveall` brackets expecting one.

`freeze`'s doc did not say why rooting the live set is not the same operation:
a frozen object in 3.14 is skipped by the cyclic collector but still reclaimed
by refcount, while a rooted one is immortal until `unfreeze` with its `__del__`
deferred.

Assisted-by: Claude

…st major

Two of the three elements 3.14 reports are collection counts, not object
counts: element 1 is the generation-0 collections run since generation 1 was
collected, element 2 the generation-1 collections since generation 2 was. Under
the generation mapping `NUM_GENERATIONS` already publishes, a minor is the
generation-0 collection and a major collects both older generations, so
element 1 is the minors since the last major and element 2 is zero because
nothing collects generation 1 alone.

Add `minor_collections_at_major_end` and `GcAllocator::minor_collections_since_major`,
installed by all three backends through
`set_active_minor_collections_since_major`.

The sample is taken at the FINALIZING -> SCANNING transition, not in
`finish_incremental_cycle`. That function is the sweep-to-finalize seam, and
`do_collect_full` runs a minor before every remaining step, so one more minor
still runs after it; sampling there left `gc.collect()` reporting a minor the
collection had not finished running. `minors_accumulate_until_a_major_finishes`
covers both the accumulation and the reset.

Element 0 stays zero and now says why. The allocation seam is keyed by a majit
type id, and the tracked predicate is not a function of that key —
`cpython_object_is_gc` reaches the object's type and, for a type object, the
object itself, so one type id covers a tracked heap type and an untracked
static one. A decidable bit would still undercount: every backend emits the
nursery bump inline and merges several objects into one, and a virtualized
allocation is removed outright.

Measured on `pyre-dynasm`: `(0, 0, 0)` at startup, `(0, 2, 0)` after 200000
appends, `(0, 0, 0)` after `gc.collect()`.

Assisted-by: Claude

collector.rs, nursery.rs, shadow_stack.rs and trace.rs opened with a
`///` block describing the module, which documents the `use` statement
that follows it rather than the module. Each of those imports is
private, so the text reached no rendered page. The other eleven
majit-gc modules already use `//!`.

Assisted-by: Claude

The `Nursery::reset` comment named `clear_gc_fields` as the only store
the zero-fill covers. `NewArrayClear` is the second: the wasm codegen
lowers it exactly like `NewArray`, and `wasm_jit_alloc_array` stamps the
length and nothing else, so the clear half comes from the recycled bytes
being zero. The `ZeroArray` the pass emits never reaches wasm, and the
codegen declines a trace carrying one rather than rely on the allocator.

Also record that the omission covers every op rather than some
allocation shapes, that `remove_ref_constants` does run on wasm, and
that a request routed to old-gen outright is cleared by
`alloc_in_oldgen_clear` on every target, so only the nursery-overflow
spill needs `clear_nursery_substitute`.

Assisted-by: Claude

…upstream duty

The registry doc said the table drops when the loop token is freed. On
cranelift a bridge's table is pinned a second time by every `BridgeData`
that can dispatch to the bridge, so it outlives the CLT it was registered
against while a fail descr in another token holds one; only dynasm has
the CLT as sole holder. Nothing dispatches `Backend::free_loop` either —
the release is `Arc` drop at memmgr eviction.

Also record why no `clear_gcref_tracer` analog is owed: upstream zeroes
`array_length` because its slot array is reserved inside the code block
and freed with it, while here the slots are the table's own `Box`.

Assisted-by: Claude

The module doc ended in a phase plan whose last entry read "this commit",
and it never said the decisive fact: upstream's transformer inserts
push_roots/pop_roots automatically around the operations that can
collect, while every bracket here is hand-written. Replace the plan with
the current state, the deviation, and the census of hand-written sites
with the command that re-derives it — 1376 scopes, 2604 pins and 3571
read-backs across 163 files.

Also name what the missing pass gates: the born-old interpreter
allocation in gc_interp and the non-moving safepoint major.

Assisted-by: Claude

`gc.collect(n)` bounded its generation against `NUM_GENERATIONS` and then
discarded it, so every generation ran a full collection and `gc.get_count`'s
second element could only move through allocation.  Route the generation to
`MiniMarkGC::do_collect` -- the `incminimark.py collect(gen)` port, which had
no callers -- through a new `GcAllocator::collect_generation` and the
active-backend hook, the path `get_objects` already carries a generation over.
`gc_sync`'s singleton is not the GC cranelift and wasm own, so the removed
`majit_gc::gc_collect_gen` could not have served this.

The declared default generation was 0 and is now the oldest, so a bare
`gc.collect()` keeps running a full collection.

`gc.collect(0)` now moves `gc.get_count()[1]` the way 3.14 moves it --
(0,0,0) -> (0,1,0) -> (0,2,0) -> (0,0,0) on CPython, dynasm and cranelift
alike.  Rewrite the snippet around that rather than around appending 200000
tuples until a minor happens to land.

Assisted-by: Claude