@scriptc/runtime 0.0.21 → 0.0.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scriptc/runtime",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "description": "scriptc native runtime — C sources, compiled into every scriptc binary",
   "license": "Apache-2.0",
   "homepage": "https://scriptc.dev",

package/src/scr_assert.c

@@ -444,6 +444,8 @@ static bool scr_assert_dyn_same_value(const ScrDyn *a, const ScrDyn *b) {
        * === — exact for SameValue too, since wrap-time scalar
        * normalization leaves only reference kinds behind. */
       return a == b || scr_dyn_jsval_ops()->strict_eq(a->v.jsval.cell, b->v.jsval.cell);
+    case SCR_DYN_TYPED_REF:
+      return scr_dyn_strict_eq(a, b);
     default:
       return a == b; /* ARR/OBJ/BYTES: node identity */
   }
@@ -459,6 +461,18 @@ static bool scr_assert_dyn_same_value(const ScrDyn *a, const ScrDyn *b) {
  * memo here where Node carries one (documented divergence). */
 static bool scr_assert_dyn_deep_eq(const ScrDyn *a, const ScrDyn *b) {
   if (a == b) return true;
+  if (a->kind == SCR_DYN_TYPED_REF || b->kind == SCR_DYN_TYPED_REF) {
+    ScrDyn *ma = a->kind == SCR_DYN_TYPED_REF
+                     ? scr_dyn_typed_ref_materialize(a)
+                     : scr_dyn_retain((ScrDyn *)a);
+    ScrDyn *mb = b->kind == SCR_DYN_TYPED_REF
+                     ? scr_dyn_typed_ref_materialize(b)
+                     : scr_dyn_retain((ScrDyn *)b);
+    bool same = scr_assert_dyn_deep_eq(ma, mb);
+    scr_dyn_release(ma);
+    scr_dyn_release(mb);
+    return same;
+  }
   if (a->kind != b->kind) {
     /* A MIXED comparison with an island side (wrapped engine object vs
      * dyn data): Node walks both structurally — a plain `false` would
@@ -524,6 +538,8 @@ static bool scr_assert_dyn_deep_eq(const ScrDyn *a, const ScrDyn *b) {
       if (scr_dyn_jsval_ops()->strict_eq(a->v.jsval.cell, b->v.jsval.cell)) return true;
       scr_dyn_isl_fence(a, "deepStrictEqual");
       return false;
+    case SCR_DYN_TYPED_REF:
+      return false; /* both mixed and same-kind capsules returned above */
   }
   return false; /* unreachable */
 }
@@ -684,6 +700,12 @@ static void scr_assert_cf_value(ScrAssertBuf *b, const ScrDyn *d, size_t indent,
       ab_cstr(b, "[island value]");
       return;
     }
+    case SCR_DYN_TYPED_REF: {
+      ScrDyn *materialized = scr_dyn_typed_ref_materialize(d);
+      scr_assert_cf_value(b, materialized, indent, depth);
+      scr_dyn_release(materialized);
+      return;
+    }
     case SCR_DYN_OBJ: {
       /* The null-proto dictionary renders with Node's prefix in the
        * failure diff too (assertion_error.js inspects both sides). */
@@ -928,6 +950,7 @@ static bool scr_assert_print_myers(ScrAssertBuf *b, const ScrDiffOp *diff, size_
 static bool scr_assert_dyn_is_object(const ScrDyn *d) {
   return d->kind == SCR_DYN_ARR || d->kind == SCR_DYN_OBJ || d->kind == SCR_DYN_BYTES ||
          d->kind == SCR_DYN_HANDLE || d->kind == SCR_DYN_PROMISE ||
+         d->kind == SCR_DYN_TYPED_REF ||
          scr_dyn_isl_typeof_is(d, "object"); /* engine-held: the engine's typeof */
 }
 

package/src/scr_async.c

@@ -1802,8 +1802,11 @@ bool scr_loop_run(ScrPromise *top_level) {
     }
     if (scr_ready_len > 0 || scr_nt_head != NULL || scr_nunhandled > 0) continue;
     /* Quiescent between turns (microtasks drained, nothing running):
-     * collect any cycles the turn left behind. No-op on an empty buffer. */
-    scr_collect_cycles();
+     * collect any cycles the turn left behind. One SCHEDULED pass — almost
+     * always a nursery one, sized to the turn's own garbage. A full sweep
+     * here would walk the whole live heap every turn, which is precisely
+     * what the generations exist to avoid. No-op on an empty buffer. */
+    scr_cyc_collect_scheduled();
     /* Stream tick dispatch (scr_stream.c, when linked): the deferred
      * next-tick emissions ('data' flow kicks, 'readable'/'end'/'finish'/
      * 'drain'/'error'/'close') fire now, FIRST — the nextTick station.

package/src/scr_bytes.c

@@ -86,6 +86,13 @@ void scr_bytes_release_v(void *b) { scr_bytes_release((ScrBytes *)b); }
 
 double scr_bytes_len(const ScrBytes *b) { return (double)b->len; }
 
+void scr_bytes_copy_contents(ScrBytes *dst, const ScrBytes *src) {
+  if (dst->elem != src->elem || dst->len != src->len) {
+    scr_trap("scriptc: typed array snapshot shape changed\n");
+  }
+  memcpy(dst->data, src->data, dst->len * scr_bytes_elem_size(dst->elem));
+}
+
 double scr_bytes_byte_len(const ScrBytes *b) {
   return (double)(b->len * scr_bytes_elem_size(b->elem));
 }

package/src/scr_cycle.c

@@ -1,4 +1,4 @@
-/* Reference-cycle collector: synchronous Bacon–Rajan trial deletion (see
+/* Reference-cycle collector: generational Bacon–Rajan trial deletion (see
  * "Concurrent Cycle Collection in Reference Counted Systems", the
  * synchronous algorithm) over cycle-headered objects only — the object
  * model and the trace/teardown contract live in scr_runtime.h.
@@ -29,6 +29,58 @@
  * Recursion depth equals the traced structure's depth — same property as
  * the existing recursive releases (deep lists recurse deeply; acceptable
  * for now, revisit with an explicit stack if it ever traps).
+ *
+ * ── generations ──────────────────────────────────────────────────────
+ * A pass costs O(objects reachable from its candidates), and a candidate
+ * deep in a live structure reaches all of it — so collecting on a fixed
+ * candidate count makes total work QUADRATIC in a growing live heap. A
+ * splay tree is the worst case: re-linking a node buffers it, the walk
+ * from it drags in every node below, and none of it is ever garbage.
+ *
+ * So the collector is generational, in the shape CPython uses for this
+ * same algorithm. Each header carries a `gen`; a pass names the oldest
+ * generation it will walk and SKIPS every object above it, exactly as it
+ * skips NULL and immortals. Objects that survive a pass are promoted, so
+ * the next nursery pass never walks them again: the cost of a nursery pass
+ * is proportional to what has been allocated since the last one, not to
+ * the live heap.
+ *
+ * Restricting the walk stays sound because trial deletion is already
+ * conservative in the right direction. An edge from a skipped (older)
+ * object into the walked set is never trial-deleted, so its target keeps
+ * that count, reads as externally referenced, and survives — the same
+ * answer the collector gives for a reference held by the stack. Edges the
+ * other way are simply not followed; the older object was not a candidate
+ * for freeing in this pass. What this gives up is cycles that SPAN
+ * generations: those are invisible to a nursery pass and are found by the
+ * full pass, which walks every generation and so is exactly the old
+ * algorithm.
+ *
+ * Scheduling. One counter drives the release path: candidates buffered
+ * since the last pass. When it trips, the pass runs at the nursery level
+ * unless either full-pass condition holds:
+ *   heap growth    the live cycle-headered heap is a fraction past its size
+ *                  after the last full pass — the standard mature-generation
+ *                  rule, which catches garbage made from fresh allocation;
+ *   mature backlog the mature candidate buffer has reached a fraction of the
+ *                  live heap. This one is not redundant: live data that is
+ *                  unlinked INTO a dead cycle grows no counter at all (it
+ *                  was tallied when it was allocated) and is invisible to a
+ *                  nursery pass, so without it a program that churns its
+ *                  long-lived structures would never collect anything.
+ *   scheduled age  a mature candidate has waited through a nursery's worth
+ *                  of event-loop checkpoints. Candidate COUNT cannot bound
+ *                  the garbage behind one root, and an idle heap does not
+ *                  trip growth, so this keeps a sparse mature backlog from
+ *                  floating forever without putting a full walk on every
+ *                  turn.
+ * The first two bound collection work to a constant factor of mutator work —
+ * one heap-sized walk per live/N candidates — while the scheduled age is the
+ * liveness backstop, limiting its forced full walks to one per nursery's worth
+ * of checkpoints while mature roots wait. That is the trade: a fixed root
+ * threshold bounds floating garbage tightly and pays unbounded time for it;
+ * this bounds ordinary mutator-triggered work and lets garbage float in
+ * proportion, but not forever.
  */
 #include "scr_runtime.h"
 
@@ -42,70 +94,210 @@ static void scr_cyc_oom(void) {
   scr_trap("scriptc: out of memory\n");
 }
 
+/* Live cycle-headered objects — what the full-pass trigger watches. */
+static size_t scr_cyc_live = 0;
+
 void *scr_cyc_alloc(size_t size, ScrTraceFn trace, ScrCycFreeFn free_fn) {
   ScrCycHdr *h = calloc(1, sizeof(ScrCycHdr) + size);
   if (!h) scr_cyc_oom();
   h->trace = trace;
   h->free_fn = free_fn;
   h->color = SCR_CYC_BLACK;
+  h->gen = SCR_CYC_NURSERY;
+  scr_cyc_live++;
   return h + 1;
 }
 
-void scr_cyc_free(void *obj) { free(scr_cyc_hdr(obj)); }
+void scr_cyc_free(void *obj) {
+  scr_cyc_live--;
+  free(scr_cyc_hdr(obj));
+}
+
+/* A pointer vector that only ever grows (these reuse their capacity across
+ * passes rather than churning it). Pointer, count and capacity live in ONE
+ * struct on purpose: buffering a candidate is the hot path, and splitting
+ * them across three arrays indexed by generation would touch three cache
+ * lines per release where the original single buffer touched one. */
+typedef struct {
+  void **v;
+  size_t n, cap;
+} ScrVec;
 
-/* ── the candidate-root buffer ────────────────────────────────────────── */
+static void scr_cyc_grow(ScrVec *vec) {
+  vec->cap = vec->cap ? vec->cap * 2 : 64;
+  void **grown = realloc(vec->v, vec->cap * sizeof *grown);
+  if (!grown) scr_cyc_oom();
+  vec->v = grown;
+}
+
+static void scr_cyc_push(ScrVec *vec, void *obj) {
+  if (vec->n == vec->cap) scr_cyc_grow(vec);
+  vec->v[vec->n++] = obj;
+}
 
-static void **scr_roots = NULL;
-static size_t scr_nroots = 0, scr_roots_cap = 0;
+/* ── the candidate-root buffers (one per generation) ──────────────────── */
+
+static ScrVec scr_roots[SCR_CYC_NGENS];
 static bool scr_collecting = false;
 
-static size_t scr_cyc_threshold(void) {
+/* The candidates of the pass in flight, gathered across the generations it
+ * collects so the phases can walk them without re-filtering the buffers. */
+static ScrVec scr_cands;
+
+/* Nursery survivors awaiting promotion (see scr_scan_black). */
+static ScrVec scr_promote;
+
+/* The gathered white set (freed after the walk completes). */
+static ScrVec scr_white;
+
+/* Cross-generation targets pinned by the white set (see scr_xg_pin_visit),
+ * one entry per skipped edge. Drained after the teardowns. */
+static ScrVec scr_xgen;
+
+/* Objects above this generation are invisible to the pass in flight. */
+static unsigned scr_gen_limit = SCR_CYC_MATURE;
+
+static size_t scr_cyc_pass(unsigned gen_limit);
+
+/* ── when to collect ──────────────────────────────────────────────────── */
+
+#define SCR_CYC_NURSERY_CANDIDATES 256 /* nursery trigger */
+#define SCR_CYC_FULL_GROWTH_DIV 4      /* full pass per +1/4 of live heap */
+#define SCR_CYC_FULL_FLOOR 4096        /* ...but not below this many objects */
+
+/* Live count as of the end of the last full pass. */
+static size_t scr_cyc_live_after_full = 0;
+
+static size_t scr_cyc_nursery_threshold(void) {
   static size_t cached = 0;
   if (cached == 0) {
     const char *env = getenv("SCR_CYCLE_THRESHOLD");
     long v = env ? strtol(env, NULL, 10) : 0;
-    cached = v > 0 ? (size_t)v : 256;
+    cached = v > 0 ? (size_t)v : SCR_CYC_NURSERY_CANDIDATES;
   }
   return cached;
 }
 
+/* Buffered candidates across both generations, and the count at which the
+ * release path next collects. Keeping a running total (rather than summing
+ * the buffers) is what holds the hot path to one load and one compare, as
+ * it was when there was a single buffer. The trigger is re-armed at the end
+ * of every pass to "whatever survived, plus a nursery's worth": without that
+ * hysteresis a large mature buffer — which a nursery pass cannot drain —
+ * would re-arm on every single release. Both start at zero, so the first
+ * release runs one trivial pass that arms them properly. */
+static size_t scr_cyc_nbuffered = 0;
+static size_t scr_cyc_trigger = 0;
+
+/* Scheduled nursery passes for which at least one mature root was waiting.
+ * A full pass resets the age; with no mature backlog there is nothing to age. */
+static size_t scr_cyc_scheduled_mature_age = 0;
+
+static size_t scr_cyc_buffered(void) {
+  return scr_roots[SCR_CYC_NURSERY].n + scr_roots[SCR_CYC_MATURE].n;
+}
+
+/* A full pass is due once the live heap has grown a fraction past what it
+ * was when the last one finished. Since a pass resets the baseline to the
+ * live count it leaves behind, an unproductive full pass cannot re-trigger
+ * itself — the next one waits for another fraction of growth. */
+static bool scr_cyc_full_due(void) {
+  size_t base = scr_cyc_live_after_full;
+  if (base < SCR_CYC_FULL_FLOOR) base = SCR_CYC_FULL_FLOOR;
+  return scr_cyc_live > base + base / SCR_CYC_FULL_GROWTH_DIV;
+}
+
+/* Cold half of the release path: pick the generation and collect.
+ *
+ * Heap growth is not the only thing that owes a full pass. Live data that
+ * TURNS INTO garbage — a mature structure unlinked into a dead cycle —
+ * grows no counter at all: those objects were already tallied in
+ * scr_cyc_live when they were allocated, so scr_cyc_full_due stays false
+ * forever, and a nursery pass cannot see them because they are mature. Left
+ * at that, a program that churns its long-lived structures without
+ * allocating would never collect anything. So the mature buffer's own size
+ * is the second full-pass trigger, at a fraction of the live heap: that
+ * bounds uncollected mature candidates proportionally and keeps the
+ * amortized cost linear (one heap-sized walk per live/N candidates). */
+static size_t scr_cyc_mature_threshold(void) {
+  size_t t = scr_cyc_live / SCR_CYC_FULL_GROWTH_DIV;
+  return t < SCR_CYC_NURSERY_CANDIDATES ? SCR_CYC_NURSERY_CANDIDATES : t;
+}
+
+static void scr_cyc_collect_due(void) {
+  bool full = scr_cyc_full_due()
+              || scr_roots[SCR_CYC_MATURE].n >= scr_cyc_mature_threshold();
+  scr_cyc_pass(full ? SCR_CYC_MATURE : SCR_CYC_NURSERY);
+}
+
+/* One scheduled pass, for callers that reach a natural collection point
+ * (the event loop between turns) rather than a threshold. Deliberately NOT
+ * scr_collect_cycles: that one is the exit-time full sweep, and running it
+ * per turn would walk the whole live heap every turn — which is exactly the
+ * cost the generations exist to avoid. */
+void scr_cyc_collect_scheduled(void) {
+  if (scr_cyc_buffered() == 0) {
+    scr_cyc_scheduled_mature_age = 0;
+    return;
+  }
+  if (scr_roots[SCR_CYC_MATURE].n == 0) {
+    scr_cyc_scheduled_mature_age = 0;
+  } else if (++scr_cyc_scheduled_mature_age
+             >= scr_cyc_nursery_threshold()) {
+    scr_cyc_pass(SCR_CYC_MATURE);
+    return;
+  }
+  scr_cyc_collect_due();
+}
+
 void scr_cyc_on_dead(void *obj) {
   ScrCycHdr *h = scr_cyc_hdr(obj);
   if (!h->buffered) return;
-  /* O(1) removal: swap the last entry into the hole. */
+  /* O(1) removal: swap the last entry into the hole. A buffered object's
+   * generation never changes (promotion runs only on objects the pass has
+   * already drained from the buffers), so `gen` names the right one. */
+  ScrVec *b = &scr_roots[h->gen];
   size_t i = h->buf_index;
-  void *last = scr_roots[--scr_nroots];
-  scr_roots[i] = last;
+  void *last = b->v[--b->n];
+  b->v[i] = last;
   if (last != obj) scr_cyc_hdr(last)->buf_index = i;
   h->buffered = 0;
+  scr_cyc_nbuffered--;
+  /* A death must not consume room reserved for a future candidate. */
+  scr_cyc_trigger--;
+  if (h->gen == SCR_CYC_MATURE && b->n == 0)
+    scr_cyc_scheduled_mature_age = 0;
 }
 
+/* THE hot path — every release that leaves an object alive lands here, so
+ * it stays what it has always been: buffer inline, then one compare. */
 void scr_cyc_on_release(void *obj) {
   ScrCycHdr *h = scr_cyc_hdr(obj);
   h->color = SCR_CYC_PURPLE;
   if (!h->buffered) {
-    if (scr_nroots == scr_roots_cap) {
-      scr_roots_cap = scr_roots_cap ? scr_roots_cap * 2 : 64;
-      scr_roots = realloc(scr_roots, scr_roots_cap * sizeof *scr_roots);
-      if (!scr_roots) scr_cyc_oom();
-    }
+    ScrVec *b = &scr_roots[h->gen];
+    if (b->n == b->cap) scr_cyc_grow(b);
     h->buffered = 1;
-    h->buf_index = scr_nroots;
-    scr_roots[scr_nroots++] = obj;
-  }
-  /* Threshold trigger. Never re-entered: a teardown's releases of untraced
-   * children can buffer new candidates mid-collection, but they only wait
-   * for the next pass. */
-  if (!scr_collecting && scr_nroots >= scr_cyc_threshold()) {
-    scr_collect_cycles();
+    h->buf_index = b->n;
+    b->v[b->n++] = obj;
+    scr_cyc_nbuffered++;
   }
+  /* Never re-entered: a teardown's releases of untraced children can buffer
+   * new candidates mid-collection, but they only wait for the next pass. */
+  if (!scr_collecting && scr_cyc_nbuffered >= scr_cyc_trigger)
+    scr_cyc_collect_due();
 }
 
 /* ── trial deletion ───────────────────────────────────────────────────── */
 
-/* Child filter shared by every phase: nothing to do for NULL (unassigned
- * slots) or immortal (interned statics have no header at all). */
-#define SCR_CYC_SKIP(child) ((child) == NULL || SCR_RC(child) == SIZE_MAX)
+/* Child filter shared by every phase — and it MUST be shared by every
+ * phase: scan restores exactly the trial decrements markGray made, so the
+ * two must agree on which edges are internal. Nothing to do for NULL
+ * (unassigned slots), immortal (interned statics have no header at all), or
+ * a generation this pass does not collect. */
+#define SCR_CYC_SKIP(child)                     \
+  ((child) == NULL || SCR_RC(child) == SIZE_MAX \
+   || scr_cyc_hdr(child)->gen > scr_gen_limit)
 
 static void scr_mark_gray(void *obj);
 static void scr_mg_visit(void *child, void *ctx) {
@@ -129,8 +321,15 @@ static void scr_sb_visit(void *child, void *ctx) {
   if (scr_cyc_hdr(child)->color != SCR_CYC_BLACK) scr_scan_black(child);
 }
 static void scr_scan_black(void *obj) {
-  scr_cyc_hdr(obj)->color = SCR_CYC_BLACK;
-  scr_cyc_hdr(obj)->trace(obj, scr_sb_visit, NULL);
+  ScrCycHdr *h = scr_cyc_hdr(obj);
+  h->color = SCR_CYC_BLACK;
+  /* Blackening is what proves a walked object survives, so this is where
+   * promotion is decided — but it is only RECORDED here. Raising `gen` now
+   * would hide the object from SCR_CYC_SKIP partway through the pass, and
+   * this phase has trial decrements left to restore. */
+  if (h->gen < SCR_CYC_MATURE)
+    scr_cyc_push(&scr_promote, obj);
+  h->trace(obj, scr_sb_visit, NULL);
 }
 
 static void scr_scan(void *obj);
@@ -151,10 +350,6 @@ static void scr_scan(void *obj) {
   h->trace(obj, scr_scan_visit, NULL);
 }
 
-/* The gathered white set (freed after the walk completes). */
-static void **scr_white = NULL;
-static size_t scr_nwhite = 0, scr_white_cap = 0;
-
 static void scr_collect_white(void *obj);
 static void scr_cw_visit(void *child, void *ctx) {
   (void)ctx;
@@ -164,54 +359,200 @@ static void scr_cw_visit(void *child, void *ctx) {
 static void scr_collect_white(void *obj) {
   ScrCycHdr *h = scr_cyc_hdr(obj);
   if (h->color != SCR_CYC_WHITE || h->buffered) return;
-  h->color = SCR_CYC_BLACK; /* visited marker — prevents re-gathering */
+  h->color = SCR_CYC_DOOMED; /* gathered — don't gather twice */
   h->trace(obj, scr_cw_visit, NULL);
-  if (scr_nwhite == scr_white_cap) {
-    scr_white_cap = scr_white_cap ? scr_white_cap * 2 : 64;
-    scr_white = realloc(scr_white, scr_white_cap * sizeof *scr_white);
-    if (!scr_white) scr_cyc_oom();
+  scr_cyc_push(&scr_white, obj);
+}
+
+/* ── cross-generation edges ───────────────────────────────────────────── */
+
+/* A restricted pass leaves one edge unaccounted, and it is the one edge that
+ * nothing else accounts either. markGray does not trial-delete an edge into a
+ * generation it refused to walk (SCR_CYC_SKIP), and the teardown contract has
+ * free_fn release exactly the UNTRACED children — because every traced edge
+ * was supposed to have been decremented by markGray. So when a white object
+ * holds a traced edge into an older generation, freeing it drops the edge
+ * while the target keeps the count: a phantom reference that reads as an
+ * external one to every later pass, full ones included. The target and
+ * everything under it would never be reclaimable again.
+ *
+ * So the white set pays those edges off explicitly. The walk cannot do it
+ * inline — a release there could free a survivor that scr_promote still
+ * points at, or cascade into the white set mid-teardown — so it runs in two
+ * halves: PIN each target with a retain while `gen` still holds walk-time
+ * values, then DROP THE PIN AND GIVE UP THE EDGE after the teardowns, when
+ * generations have settled and the white set is gone. Two decrements per
+ * entry, because the pin is one of them — a single release would only undo
+ * the pin and leave the phantom edge exactly where it was. The pin is what
+ * makes the second decrement safe: a teardown's releases of untraced
+ * children can reach a cycle-headered object (that is how they re-buffer
+ * survivors), so without it a target could be freed before the drain runs.
+ *
+ * One entry per skipped edge, so several edges sharing a target settle it
+ * once each.
+ *
+ * Nothing pinned here can be in the white set: a skipped older object's
+ * edges were never trial-deleted, so anything it references kept that count
+ * and was scan-blacked rather than whitened — the same conservatism that
+ * makes restricting the walk sound in the first place. */
+static void scr_xg_pin_visit(void *child, void *ctx) {
+  (void)ctx;
+  if (child == NULL || SCR_RC(child) == SIZE_MAX) return;
+  if (scr_cyc_hdr(child)->gen <= scr_gen_limit) return; /* markGray had it */
+  SCR_RC(child) += 1; /* pin across the teardowns */
+  scr_cyc_push(&scr_xgen, child);
+}
+
+/* Freed by the cross-generation drain, for the caller's fixpoint. */
+static size_t scr_xg_freed = 0;
+
+static void scr_xg_release(void *obj);
+static void scr_xg_child_visit(void *child, void *ctx) {
+  (void)ctx;
+  if (child == NULL || SCR_RC(child) == SIZE_MAX) return;
+  scr_xg_release(child);
+}
+
+/* One genuine release, generically: the header carries everything needed. */
+static void scr_xg_release(void *obj) {
+  ScrCycHdr *h = scr_cyc_hdr(obj);
+  if (SCR_RC(obj) > 1) {
+    SCR_RC(obj) -= 1;
+    scr_cyc_on_release(obj); /* lost a reference: a possible cycle root */
+    return;
   }
-  scr_white[scr_nwhite++] = obj;
+  SCR_RC(obj) = 0;
+  scr_cyc_on_dead(obj); /* out of its candidate buffer before the block goes */
+  h->trace(obj, scr_xg_child_visit, NULL); /* the traced children */
+  h->free_fn(obj); /* the untraced ones, then the block */
+  scr_xg_freed++;
 }
 
-void scr_collect_cycles(void) {
-  if (scr_collecting || scr_nroots == 0) return;
+/* One pass over every candidate at or below `gen_limit`; returns how many
+ * objects it freed. */
+static size_t scr_cyc_pass(unsigned gen_limit) {
+  if (scr_collecting) return 0;
   scr_collecting = true;
+  scr_gen_limit = gen_limit;
 
   /* markRoots: keep live candidates (still purple), drop the rest — an
    * object re-retained since buffering is black; one grayed by an earlier
-   * candidate's walk is already covered by that candidate's subgraph. */
-  size_t out = 0;
-  for (size_t i = 0; i < scr_nroots; i++) {
-    void *obj = scr_roots[i];
-    ScrCycHdr *h = scr_cyc_hdr(obj);
-    if (h->color == SCR_CYC_PURPLE) {
-      scr_mark_gray(obj);
-      h->buf_index = out;
-      scr_roots[out++] = obj;
-    } else {
+   * candidate's walk is already covered by that candidate's subgraph. The
+   * buffers are drained up front (markGray only touches counts directly,
+   * so nothing can re-buffer underneath us) which leaves collectWhite free
+   * to gather members of an earlier root's cycle. Candidates ABOVE the
+   * limit keep their buffer slots and wait for a full pass. */
+  scr_cands.n = 0;
+  for (unsigned g = 0; g <= gen_limit; g++) {
+    for (size_t i = 0; i < scr_roots[g].n; i++) {
+      void *obj = scr_roots[g].v[i];
+      ScrCycHdr *h = scr_cyc_hdr(obj);
       h->buffered = 0;
+      if (h->color == SCR_CYC_PURPLE)
+        scr_cyc_push(&scr_cands, obj);
     }
+    scr_roots[g].n = 0;
   }
-  scr_nroots = out;
+  for (size_t i = 0; i < scr_cands.n; i++) scr_mark_gray(scr_cands.v[i]);
+
+  for (size_t i = 0; i < scr_cands.n; i++) scr_scan(scr_cands.v[i]);
+
+  scr_white.n = 0;
+  for (size_t i = 0; i < scr_cands.n; i++) scr_collect_white(scr_cands.v[i]);
+
+  /* Pin the cross-generation targets of everything about to be freed, while
+   * `gen` still holds the values the walk filtered on (promotion below is
+   * what changes them). A full pass skips no edge, so it pins nothing. */
+  scr_xgen.n = 0;
+  if (gen_limit < SCR_CYC_MATURE) {
+    for (size_t i = 0; i < scr_white.n; i++) {
+      void *obj = scr_white.v[i];
+      scr_cyc_hdr(obj)->trace(obj, scr_xg_pin_visit, NULL);
+    }
+  }
+
+  /* Every phase that consults SCR_CYC_SKIP has run, so the recorded
+   * survivors can graduate now. They are externally referenced, so none of
+   * them is in the white set about to be freed. */
+  for (size_t i = 0; i < scr_promote.n; i++)
+    scr_cyc_hdr(scr_promote.v[i])->gen = SCR_CYC_MATURE;
+  scr_promote.n = 0;
 
-  for (size_t i = 0; i < scr_nroots; i++) scr_scan(scr_roots[i]);
+  /* A restricted pass may have spared a candidate only because the edge
+   * keeping it alive came from a generation it refused to walk — the
+   * deliberate conservatism above. But the candidate buffer is the ONLY
+   * root set this collector has, and markRoots consumed the entry. Dropping
+   * it would retire the one record that this object is a possible cycle
+   * root, and a dead cycle whose members all got spared that way would
+   * never be walked again by any pass, full ones included. So a restricted
+   * pass hands its survivors back as candidates in the generation they were
+   * just promoted into, where a full pass — which skips nothing, and so
+   * judges them on real reference counts — will settle them. A full pass
+   * needs none of this: it walked every edge, so rc > 0 there means a
+   * genuine outside reference and Bacon-Rajan's own reasoning retires the
+   * candidate. Re-buffering costs a walk, never correctness: an object that
+   * is truly live gets re-blackened by the next retain and dropped then. */
+  if (gen_limit < SCR_CYC_MATURE) {
+    for (size_t i = 0; i < scr_cands.n; i++) {
+      void *obj = scr_cands.v[i];
+      ScrCycHdr *h = scr_cyc_hdr(obj);
+      if (h->color == SCR_CYC_DOOMED) continue; /* being freed below */
+      h->color = SCR_CYC_PURPLE;
+      if (!h->buffered) {
+        h->buffered = 1;
+        h->buf_index = scr_roots[h->gen].n;
+        scr_cyc_push(&scr_roots[h->gen], obj);
+      }
+    }
+  }
 
-  /* collectWhite over a drained buffer: clear every buffered flag first so
-   * the recursion can gather buffered members of an earlier root's cycle. */
-  size_t n = scr_nroots;
-  scr_nroots = 0;
-  for (size_t i = 0; i < n; i++) scr_cyc_hdr(scr_roots[i])->buffered = 0;
-  scr_nwhite = 0;
-  for (size_t i = 0; i < n; i++) scr_collect_white(scr_roots[i]);
   /* Teardowns run after the full walk. They may release untraced children
    * (plain RC) — which can re-buffer survivors for the NEXT pass — but
    * never touch traced (white, already-accounted) edges. */
-  for (size_t i = 0; i < scr_nwhite; i++) {
-    void *obj = scr_white[i];
+  size_t freed = scr_white.n;
+  for (size_t i = 0; i < scr_white.n; i++) {
+    void *obj = scr_white.v[i];
     scr_cyc_hdr(obj)->free_fn(obj);
   }
-  scr_nwhite = 0;
+  scr_white.n = 0;
 
+  /* Now drain the pins: the white set is gone and generations have settled,
+   * so each of those edges can be given up for real. A target that survives
+   * lands back in the candidate buffer — it just lost a reference, which is
+   * exactly what makes an object a possible cycle root. */
+  scr_xg_freed = 0;
+  for (size_t i = 0; i < scr_xgen.n; i++) {
+    void *obj = scr_xgen.v[i];
+    /* Drop the pin first. The phantom edge is still counted, so this cannot
+     * reach zero and the release below is the one that settles the object. */
+    SCR_RC(obj) -= 1;
+    scr_xg_release(obj);
+  }
+  scr_xgen.n = 0;
+  freed += scr_xg_freed;
+
+  if (gen_limit >= SCR_CYC_MATURE) {
+    scr_cyc_live_after_full = scr_cyc_live;
+    scr_cyc_scheduled_mature_age = 0;
+  }
+  /* markRoots drained buffers in bulk and teardowns moved the count around;
+   * resync from the buffers themselves and re-arm. */
+  scr_cyc_nbuffered = scr_cyc_buffered();
+  scr_cyc_trigger = scr_cyc_nbuffered + scr_cyc_nursery_threshold();
   scr_collecting = false;
+  return freed;
+}
+
+void scr_collect_cycles(void) {
+  /* The full pass, run to a fixpoint. A teardown's releases can drop the
+   * last reference to a further cycle, so one pass does not always drain
+   * everything reclaimable — and the callers that matter (program exit,
+   * library session reset) are immediately followed by the RC audit and
+   * want nothing reclaimable left behind. Only a pass that freed something
+   * can have buffered anything new, so a pass that comes up empty ends
+   * this; and since each repeat needs a strictly smaller live heap to
+   * continue, it terminates. */
+  while (scr_cyc_pass(SCR_CYC_MATURE)
+         && (scr_roots[SCR_CYC_NURSERY].n || scr_roots[SCR_CYC_MATURE].n)) {
+  }
 }