@zakkster/lite-signal 1.2.0 → 1.2.2

package/Signal.js

@@ -1,26 +1,23 @@
 /**
- * @zakkster/lite-signal v1.2.0
+ * @zakkster/lite-signal v1.2.2
  * --------------------
- * Hybrid Doubly-Linked-List Reactive Graph Engine — decoupled (Signal1_3) base
+ * Hybrid Doubly-Linked-List Reactive Graph Engine -- decoupled (Signal1_3) base
  * with the two 1.1.3 performance fixes ported in:
- *   1. pullComputed clean short-circuit (markEpoch) — kills the dynamic-graph
+ *   1. pullComputed clean short-circuit (markEpoch) -- kills the dynamic-graph
  *      regression: "large web app" 4900ms -> 665ms, "wide dense" 4472 -> 952.
- *   2. allocateLink: O(1) tailSub dedup replaces the O(N) prefix scan — divergent
+ *   2. allocateLink: O(1) tailSub dedup replaces the O(N) prefix scan -- divergent
  *      re-tracking is O(N) not O(N^2) (600-dep flip micro: 1373ms -> 62ms).
  * Ownership tree + L1/L2/L3 layering + observer/owner split are UNCHANGED; they
  * were never the regression. Same EDGE NOTE as 1.1.3 applies to fix (2): a nested
  * re-read of the same source can retain one bounded, dispose-reclaimed link.
  *
- * Original header:
- * v1.3.2: Hybrid Doubly-Linked-List Reactive Graph Engine.
- *
  * Performance model:
  * - ReactiveLink DLL object pool guarantees O(1) graph edge allocation.
  * - Inlined O(1) cursor fast-path for stable steady-state reads.
  * - Divergence triggers immediate tail-severing to bound worst-case complexity.
  * - O(1) Owner Context Tree ensures automatic teardown of nested observers.
  *
- * ── ARCHITECTURE: three layers + a public API, with a strict dependency direction ──
+ * -- ARCHITECTURE: three layers + a public API, with a strict dependency direction --
  *
  *   L1  GRAPH TOPOLOGY      allocateLink, freeLink, severTail
  *       Owns the ReactiveLink pool and the dep/sub doubly-linked lists.
@@ -29,7 +26,7 @@
  *   L2  OWNERSHIP / LIFECYCLE   createNode, disposeNode, runCleanup
  *       Owns the owner tree and node death + user cleanup.
  *       INVARIANT: never touches the `activeObserverCurrentDep` cursor.
- *       Sanctioned downward edge → L1: disposeNode walks a dying node's own
+ *       Sanctioned downward edge -> L1: disposeNode walks a dying node's own
  *       dep/sub lists and calls freeLink to extract it from the graph.
  *
  *   L3  PROPAGATION / EXECUTION   markDownstream, flushEffects, executeEffect, pullComputed
@@ -37,18 +34,18 @@
  *       (a pure propagation primitive). executeEffect/pullComputed are the
  *       ORCHESTRATORS: they drive the cursor + severTail (L1) AND, before a
  *       re-run, call runCleanup (L2) to cascade-dispose owned children.
- *       Sanctioned upward call → L2: executeEffect/pullComputed → runCleanup.
+ *       Sanctioned upward call -> L2: executeEffect/pullComputed -> runCleanup.
  *
  *   API  signal, computed, effect, dispose, batch, untrack, onCleanup, stats, destroy
  *
- *   The only cross-layer edges are L3→runCleanup and L2→freeLink. The graph of
+ *   The only cross-layer edges are L3->runCleanup and L2->freeLink. The graph of
  *   dependencies is acyclic; nothing in L1 reaches up, nothing in L2 touches
  *   the cursor, and the engine is the single place the two subsystems meet.
  *
- * ── OWNER vs OBSERVER ──
+ * -- OWNER vs OBSERVER --
  *   `currentObserver` = the node whose READS establish dependencies (tracking).
  *   `currentOwner`    = the node that OWNS anything created right now (lifecycle).
- *   Today they move together, so behaviour is unchanged — but they are distinct
+ *   Today they move together, so behaviour is unchanged -- but they are distinct
  *   pointers so future runWithOwner/createRoot can attach ownership without
  *   establishing reactive dependencies (and untrack can suppress tracking
  *   without orphaning created nodes). createNode and onCleanup key off the
@@ -60,6 +57,11 @@ const FLAG_EFFECT = 1 << 1;
 const FLAG_QUEUED = 1 << 2;
 const FLAG_COMPUTING = 1 << 3;
 const FLAG_HAS_ERROR = 1 << 4;
+
+// Hoisted equality default. Object.is lookup is fast under V8 IC but a module-
+// scope const is monomorphic without ICs. Replaces the per-call lookup in
+// signal() and computed() construction.
+const OBJECT_IS = Object.is;
 const FLAG_SIGNAL = 1 << 5;
 
 /**
@@ -110,7 +112,7 @@ class ReactiveNode {
         this.headSub = null;
         this.tailSub = null;
 
-        // Owner Context Tree (Auto-Disposal of Nested Observers) — 1.2.0.
+        // Owner Context Tree (Auto-Disposal of Nested Observers) -- 1.2.0.
         // An effect/computed created inside another effect/computed is "owned"
         // by it. When the owner re-runs or is disposed, owned children are
         // cascade-disposed before the new run. Plain signals are NOT adopted
@@ -168,7 +170,7 @@ export class CapacityError extends Error {
  *
  * Use this when you need multiple independent reactive graphs (e.g. one per
  * Twitch Extension viewer, one per worker, one per test). The top-level
- * helpers ({@link signal}, {@link effect}, …) delegate to a single shared
+ * helpers ({@link signal}, {@link effect}, ...) delegate to a single shared
  * default registry; call {@link setDefaultRegistry} to swap that for your own.
  *
  * @param {object} [config]
@@ -223,7 +225,7 @@ export function createRegistry(config) {
     let batchDepth = 0;
     let isTrackingDeps = false;
 
-    // ── Node identity + observer-lifecycle introspection (ported from 1.1.5) ──
+    // -- Node identity + observer-lifecycle introspection (ported from 1.1.5) --
     let nodeSeq = 1 | 0;
     let lifecycleCount = 0 | 0;
     const lifecycleMap = new WeakMap();
@@ -246,19 +248,19 @@ export function createRegistry(config) {
     const flushErrorBuffer = [];
     let flushErrorCount = 0;
 
-    // ═══ L1 · GRAPH TOPOLOGY ══════════════════════════════════════
+    // === L1 * GRAPH TOPOLOGY ======================================
     // Owns the ReactiveLink pool and the dep/sub lists. Pure edge mechanics:
-    // INVARIANT — must never touch node.owner / firstOwned.
+    // INVARIANT -- must never touch node.owner / firstOwned.
 
-    // ─── HYBRID ALLOCATOR ─────────────────────────────────────────
+    // --- HYBRID ALLOCATOR -----------------------------------------
 
     /**
-     * Establish (or reuse) a dependency link from `source` → `target`.
+     * Establish (or reuse) a dependency link from `source` -> `target`.
      *
-     * Fast path: cursor match (re-tracking same dep at same position) — O(1), no allocation.
-     * Mid path: O(1) tailSub dedup (1.1.4 rewrite) — divergent retracking stays O(N) overall,
-     *           not O(N²).
-     * Cold path: pool exhausted → grow or throw per policy.
+     * Fast path: cursor match (re-tracking same dep at same position) -- O(1), no allocation.
+     * Mid path: O(1) tailSub dedup (1.1.4 rewrite) -- divergent retracking stays O(N) overall,
+     *           not O(N^2).
+     * Cold path: pool exhausted -> grow or throw per policy.
      *
      * SEVER-FIRST: on a cursor-miss divergence the unmatched dep tail is freed
      * BEFORE any new link is allocated, so peak link usage never exceeds steady
@@ -272,10 +274,24 @@ export function createRegistry(config) {
      *
      * @private
      */
+        // --- Graph-mutation hook (1.2.1 keystone prototype) ---------------------
+        // Single nullable listener; every fire point is `if (mutationHook !== null)`
+        // -- branch-predicted free when absent, allocation-free when present
+        // (opcode + two int args). Enables push-based devtools (watchGraph) and the
+        // recompute profiler. Opcodes: 1 node-create, 2 node-dispose, 3 link-add,
+        // 4 link-remove, 5 recompute.
+    let mutationHook = null;
+    function onGraphMutation(fn) {
+        if (fn !== null && typeof fn !== "function") throw new TypeError("onGraphMutation: listener must be a function or null");
+        const prev = mutationHook;
+        mutationHook = fn;
+        return () => { if (mutationHook === fn) mutationHook = prev; };
+    }
+
     function allocateLink(source, target) {
         // Eligibility gate (restored from 1.1.5): an observer disposed mid-run (self-dispose, or
         // an outer observer torn down while suspended) has flags cleared to 0. Linking would splice
-        // a dead, pool-bound node back into source's subscriber list — a phantom edge. Cold path only.
+        // a dead, pool-bound node back into source's subscriber list -- a phantom edge. Cold path only.
         if (target.flags === 0) return null;
         let expected = activeObserverCurrentDep;
 
@@ -326,7 +342,7 @@ export function createRegistry(config) {
 
         link.nextSub = null;
         link.prevSub = source.tailSub;
-        const _was0 = lifecycleCount !== 0 && source.headSub === null;   // 0→1 detect (pre-link)
+        const _was0 = lifecycleCount !== 0 && source.headSub === null;   // 0->1 detect (pre-link)
         if (source.tailSub !== null) source.tailSub.nextSub = link;
         else source.headSub = link;
         source.tailSub = link;
@@ -338,15 +354,17 @@ export function createRegistry(config) {
         if (tail !== null) tail.nextDep = link;
         else target.headDep = link;
         target.tailDep = link;
+        if (mutationHook !== null) mutationHook(3, source.id, target.id);
     }
 
     /** Return a link to the free pool and unlink it from the source's sub list. @private */
     function freeLink(link, target, source) {
+        if (mutationHook !== null) mutationHook(4, link.source !== null ? link.source.id : -1, link.target !== null ? link.target.id : -1);
         const pSub = link.prevSub;
         const nSub = link.nextSub;
         if (pSub !== null) pSub.nextSub = nSub; else source.headSub = nSub;
         if (nSub !== null) nSub.prevSub = pSub; else source.tailSub = pSub;
-        if (lifecycleCount !== 0 && source.headSub === null) fireDisconnect(source);   // 1→0
+        if (lifecycleCount !== 0 && source.headSub === null) fireDisconnect(source);   // 1->0
 
         link.source = null;
         link.target = null;
@@ -382,20 +400,21 @@ export function createRegistry(config) {
         }
     }
 
-    // ═══ L2 · OWNERSHIP / LIFECYCLE ═══════════════════════════════
+    // === L2 * OWNERSHIP / LIFECYCLE ===============================
     // Owns the owner tree, node death, and user cleanup.
-    // INVARIANT — must never touch the activeObserverCurrentDep cursor.
-    // Sanctioned downward edge → L1: disposeNode calls freeLink to extract a
+    // INVARIANT -- must never touch the activeObserverCurrentDep cursor.
+    // Sanctioned downward edge -> L1: disposeNode calls freeLink to extract a
     // dying node from the graph.
 
-    // ─── LIFECYCLE & OWNERSHIP ───────────────────────────────────────
+    // --- LIFECYCLE & OWNERSHIP ---------------------------------------
 
     function disposeNode(node) {
+        if (mutationHook !== null) mutationHook(2, node.id, node.flags | 0);
         if (node.flags === 0) return;
 
         // RACE WITH ACTIVE TRACKING: an effect/computed may call dispose on
         // itself from inside its own body (#141). Once we tear the node down
-        // its dep-list, FLAG_COMPUTING, and cursor become stale immediately —
+        // its dep-list, FLAG_COMPUTING, and cursor become stale immediately --
         // any read() that runs in the REST of the body would otherwise try to
         // hang a fresh link off a freed slot. Null the tracking state now so
         // subsequent reads in this call stack become no-ops, and let
@@ -433,7 +452,7 @@ export function createRegistry(config) {
 
         runCleanup(node);
 
-        // CROSS-EDGE L2→L1: extract this node's own edges from the graph.
+        // CROSS-EDGE L2->L1: extract this node's own edges from the graph.
         let dLink = node.headDep;
         while (dLink !== null) {
             const next = dLink.nextDep;
@@ -489,7 +508,7 @@ export function createRegistry(config) {
      * Claim a node from the free pool, reinitialise, and return it.
      * Grows pool per `policy` if exhausted (or throws CapacityError under "throw").
      * Adopts the new node into `currentOwner` if there is one AND the new node is
-     * an observer (computed/effect) — plain signals are not adopted (see ReactiveNode
+     * an observer (computed/effect) -- plain signals are not adopted (see ReactiveNode
      * comment on the owner tree).
      * @private
      */
@@ -517,57 +536,68 @@ export function createRegistry(config) {
         node.nextFree = null;
         activeNodes = (activeNodes + 1) | 0;
 
+        // 1.2.2: Clean free-list invariant (Andrii's recommendation).
+        //
+        // Every node leaving the pool is guaranteed-clean for the seven fields
+        // {headDep, tailDep, headSub, tailSub, revertEpoch, preBatchValue,
+        // preBatchVersion}: dispose() clears them on the recycle path, and the
+        // ReactiveNode constructor initializes them to the same values on the
+        // fresh-allocation path (pool growth at lines above). Re-writing them
+        // here was defense against a state that cannot exist.
+        //
+        // What stays: fields that define the new lifetime (value, flags, id,
+        // firstOwned, conditional owner-tree wiring) AND fields dispose does
+        // not touch (version, evalVersion, markEpoch -- used by the propagation
+        // and pull machinery, must be reset for the new lifetime).
         node.value = value;
         node.flags = flags | 0;
-        node.headDep = null;
-        node.tailDep = null;
-        node.headSub = null;
-        node.tailSub = null;
         node.version = 0;
         node.evalVersion = 0;
         node.markEpoch = 0;
-        node.revertEpoch = 0;
-        node.preBatchValue = undefined;
-        node.preBatchVersion = 0;
         node.id = nodeSeq; nodeSeq = (nodeSeq + 1) | 0;   // fresh identity per allocation (ported from 1.1.5)
 
-        // Wire into Owner Context (lifecycle, not tracking — keyed off currentOwner).
+        // Wire into Owner Context (lifecycle, not tracking -- keyed off currentOwner).
         // ONLY observers (computed/effect) are adopted: a re-running owner disposes
         // its nested observers (which would otherwise leak dep links), but plain
         // signals have no deps to leak, and disposing them breaks lazy-allocation
         // libraries (lite-store allocates a key's signal on first read, INSIDE the
-        // reading computed — adopting it meant that computed's next run wiped the
+        // reading computed -- adopting it meant that computed's next run wiped the
         // store key). Signals are therefore never owner-adopted.
-        // firstOwned is reset unconditionally (reuse-safety: a recycled former-owner
-        // must not carry stale children into runCleanup). prevOwned/nextOwned are
-        // written only on the adoption path -- an unadopted node is in no owner's
-        // firstOwned chain, so its prevOwned/nextOwned are never traversed and may
-        // stay stale. Saves two writes per signal and per top-level computed/effect.
-        node.firstOwned = null;
+        //
+        // 1.2.2 clean free-list invariant (extended to the owner tree):
+        // owner / prevOwned / firstOwned are all guaranteed-null on every node
+        // leaving the pool. Both teardown paths null them -- disposeNode (lines
+        // ~451-453) on direct dispose, runCleanup (lines ~609-615) on parent
+        // cascade -- and the ReactiveNode constructor inits them to null on the
+        // fresh-allocation path. The three former null-writes here (firstOwned,
+        // the adoption-path prevOwned, and the else-branch owner) were defense
+        // against a state that cannot exist. Only the writes that establish the
+        // NEW lifetime remain: owner + nextOwned + the parent's chain splice on
+        // the adoption path. nextOwned is written unconditionally on adoption
+        // (it takes the prior firstOwned, which may be non-null), so it is a
+        // real lifetime write, not a redundant clear.
         if (currentOwner !== null && (flags & (FLAG_COMPUTED | FLAG_EFFECT)) !== 0) {
             node.owner = currentOwner;
-            node.prevOwned = null;
             node.nextOwned = currentOwner.firstOwned;
             if (currentOwner.firstOwned !== null) {
                 currentOwner.firstOwned.prevOwned = node;
             }
             currentOwner.firstOwned = node;
-        } else {
-            node.owner = null;
         }
 
+        if (mutationHook !== null) mutationHook(1, node.id, node.flags | 0);
         return node;
     }
 
     /**
      * Cascade-dispose owned children inside-out (deepest first), then invoke this
      * node's own cleanup if any. Cascade order is the v1.2 conformance fix for
-     * #238 / #241 / #243 — nested cleanups must fire grandchild → child → outer
+     * #238 / #241 / #243 -- nested cleanups must fire grandchild -> child -> outer
      * so that a parent's cleanup still sees its own state intact.
      * @private
      */
     function runCleanup(node) {
-        // Cascade children FIRST — deepest cleanups fire before shallowest.
+        // Cascade children FIRST -- deepest cleanups fire before shallowest.
         // This matches the universal invariant in the upstream conformance suite
         // (#238 / #241 / #243): nested cleanups run inside-out on owner-tree
         // disposal, mirroring the parent-knows-best assumption shared with
@@ -606,19 +636,19 @@ export function createRegistry(config) {
         }
     }
 
-    // ═══ L3 · PROPAGATION / EXECUTION ═════════════════════════════
+    // === L3 * PROPAGATION / EXECUTION =============================
     // markDownstream is owner-free AND cursor-free (a pure propagation
     // primitive). executeEffect/pullComputed are the orchestrators: they drive
     // the cursor + severTail (L1) and, before a re-run, call runCleanup (L2) to
-    // cascade-dispose owned children. Sanctioned upward call → L2: runCleanup.
+    // cascade-dispose owned children. Sanctioned upward call -> L2: runCleanup.
 
-    // ─── EXECUTION ENGINE ─────────────────────────────────────────
+    // --- EXECUTION ENGINE -----------------------------------------
 
     /**
      * Mark all transitive subscribers of `startNode` dirty.
      * Iterative DFS via the markStack to avoid call-stack growth.
      * Effects are enqueued for the flush phase; computeds are merely marked
-     * (their re-evaluation is lazy — triggered by the next read).
+     * (their re-evaluation is lazy -- triggered by the next read).
      * @private
      */
     function markDownstream(startNode) {
@@ -654,7 +684,7 @@ export function createRegistry(config) {
      * effects scheduled mid-flush land in the next pass. Individual effect throws
      * are caught and buffered; at end-of-flush a single throw is rethrown directly,
      * multiple throws are aggregated into an `AggregateError` (1.2.0). Exceeds
-     * `maxFlushPasses` (default 100) → Error prefixed `"CycleError:"`.
+     * `maxFlushPasses` (default 100) -> Error prefixed `"CycleError:"`.
      * @private
      */
     function flushEffects() {
@@ -714,7 +744,7 @@ export function createRegistry(config) {
      * Run an effect's compute body, re-tracking dependencies.
      * Short-circuits if no dependency has bumped its version since last eval.
      * If the body self-disposes (node.gen advances during the body), skips the
-     * post-body bookkeeping (severTail, flag clear, evalVersion bump) — that
+     * post-body bookkeeping (severTail, flag clear, evalVersion bump) -- that
      * gen-snapshot guard is the v1.2 conformance fix for #141.
      * @private
      */
@@ -744,7 +774,7 @@ export function createRegistry(config) {
         }
 
         node.flags = (node.flags & ~FLAG_QUEUED) | FLAG_COMPUTING;
-        runCleanup(node);   // CROSS-EDGE L3→L2: dispose owned children before re-run
+        runCleanup(node);   // CROSS-EDGE L3->L2: dispose owned children before re-run
         if ((node.flags & FLAG_EFFECT) === 0) return;
 
         const prevObserver = currentObserver;
@@ -760,9 +790,10 @@ export function createRegistry(config) {
         // SELF-DISPOSE DETECTION: snapshot the gen. disposeNode bumps gen,
         // so if it advanced during the body the node was disposed (and may
         // already have been recycled into a different role). Skip the
-        // dep-list / flag / version mutations in that case — they would
+        // dep-list / flag / version mutations in that case -- they would
         // either crash on the freed link list or corrupt the new resident.
         const savedGen = node.gen;
+        if (mutationHook !== null) mutationHook(5, node.id, 0);
         try {
             node.computeFn();
         } finally {
@@ -788,7 +819,7 @@ export function createRegistry(config) {
      * Errors thrown by computeFn are captured in `node.value` with FLAG_HAS_ERROR;
      * subsequent reads re-throw until a dependency change re-runs computeFn.
      *
-     * Same gen-snapshot self-dispose guard as executeEffect — see #141 fix.
+     * Same gen-snapshot self-dispose guard as executeEffect -- see #141 fix.
      *
      * @private
      */
@@ -825,7 +856,7 @@ export function createRegistry(config) {
         if (shouldRun) {
             if ((node.flags & FLAG_COMPUTING) !== 0) throw new Error("CycleError: Circular dependency detected.");
             node.flags |= FLAG_COMPUTING;
-            runCleanup(node);   // CROSS-EDGE L3→L2: dispose owned children before recompute
+            runCleanup(node);   // CROSS-EDGE L3->L2: dispose owned children before recompute
 
             const prevObserver = currentObserver;
             const prevOwner = currentOwner;
@@ -837,8 +868,9 @@ export function createRegistry(config) {
             activeObserverCurrentDep = node.headDep;
             isTrackingDeps = true;
 
-            // Same self-dispose detection as executeEffect — see comment there.
+            // Same self-dispose detection as executeEffect -- see comment there.
             const savedGen = node.gen;
+            if (mutationHook !== null) mutationHook(5, node.id, 0);
             try {
                 const newValue = node.computeFn();
                 const eq = node.equals;
@@ -854,7 +886,7 @@ export function createRegistry(config) {
                     node.version = globalVersion;
                 } else {
                     // The body disposed `node` and then threw. The error has
-                    // nowhere to land — the caller of the read that triggered
+                    // nowhere to land -- the caller of the read that triggered
                     // this pull has already had its tracking state torn down.
                     // Swallow rather than corrupt a recycled slot. The
                     // canonical thrown-computed test (#168 / cached error)
@@ -879,9 +911,9 @@ export function createRegistry(config) {
         return node.value;
     }
 
-    // ─── PUBLIC API ──────────────────────────────────────────────────
+    // --- PUBLIC API --------------------------------------------------
 
-    // ─── shared accessor methods (one set per registry, not per primitive) ───────
+    // --- shared accessor methods (one set per registry, not per primitive) -------
     // update/subscribe are method-invoked (s.update(fn), s.subscribe(fn)), so `this`
     // is the read function and this[NODE_PTR] is the node. set() and peek() stay
     // closures: set() is the hot write path (a closure over `node` beats the
@@ -906,8 +938,16 @@ export function createRegistry(config) {
     // arrows. Method-invoked, so `this` is the read function and this[NODE_PTR]
     // is the node. Signal: direct value read. Computed: pull (still respects
     // the cached/short-circuit fast paths since pullComputed handles them).
-    function sharedSignalPeek() { return this[NODE_PTR].value; }
-    function sharedComputedPeek() { return pullComputed(this[NODE_PTR]); }
+    function sharedSignalPeek() {
+        const node = this[NODE_PTR];
+        if (this[NODE_GEN] !== node.gen) return undefined;   // stale handle: slot recycled (ABA guard, matches read())
+        return node.value;
+    }
+    function sharedComputedPeek() {
+        const node = this[NODE_PTR];
+        if (this[NODE_GEN] !== node.gen) return undefined;
+        return pullComputed(node);
+    }
 
     /**
      * Create a reactive signal.
@@ -921,11 +961,20 @@ export function createRegistry(config) {
      */
     function signal(initial, opts) {
         const node = createNode(initial, FLAG_SIGNAL);
-        node.equals = (opts !== undefined && opts.equals !== undefined) ? opts.equals : Object.is;
+        node.equals = (opts !== undefined && opts.equals !== undefined) ? opts.equals : OBJECT_IS;
         node.version = globalVersion;
         statSignals++;
 
+        // birthGen pinned at construction. The set/read closures check
+        // `node.gen === birthGen` to detect stale handles after dispose +
+        // pool-slot recycling. Without this, a retained set() from a disposed
+        // signal can overwrite the recycled slot's new resident; a retained
+        // read() inside an active observer can create a phantom subscription
+        // to the recycled slot. See probe-c1-stale-set.mjs / probe-c1-stale-read.mjs.
+        const birthGen = node.gen;
+
         const read = () => {
+            if (node.gen !== birthGen) return undefined;
             if (isTrackingDeps && currentObserver !== null) {
                 let expected = activeObserverCurrentDep;
                 if (expected !== null && expected.source === node) {
@@ -942,6 +991,7 @@ export function createRegistry(config) {
         // path, and a closure over `node` beats a shared method's this[NODE_PTR]
         // load. Keeping it a closure also restores detached `const {set}=signal()`.
         read.set = (value) => {
+            if (node.gen !== birthGen) return;
             const eq = node.equals;
             if (eq && eq(node.value, value)) return;
             if (batchDepth > 0 && node.revertEpoch !== batchEpoch) {
@@ -982,10 +1032,13 @@ export function createRegistry(config) {
     function computed(fn, opts) {
         const node = createNode(undefined, FLAG_COMPUTED);
         node.computeFn = fn;
-        node.equals = (opts !== undefined && opts.equals !== undefined) ? opts.equals : Object.is;
+        node.equals = (opts !== undefined && opts.equals !== undefined) ? opts.equals : OBJECT_IS;
         statComputeds++;
 
+        const birthGen = node.gen;
+
         const read = () => {
+            if (node.gen !== birthGen) return undefined;
             if (isTrackingDeps && currentObserver !== null) {
                 let expected = activeObserverCurrentDep;
                 if (expected !== null && expected.source === node) {
@@ -1039,7 +1092,7 @@ export function createRegistry(config) {
             const gen = node.gen | 0;
             // Cache the gen-bound thunk so re-schedules reuse the same closure.
             // The inline guard preserves ABA correctness across dispose+recycle
-            // (gen bumps on disposeNode → stale thunk no-ops).
+            // (gen bumps on disposeNode -> stale thunk no-ops).
             node.schedulerThunk = () => {
                 if (node.gen === gen && (node.flags & FLAG_EFFECT) !== 0) executeEffect(node);
             };
@@ -1063,6 +1116,16 @@ export function createRegistry(config) {
             }
         };
 
+        // Effect handles are first-class introspection handles (1.2.1): stamp
+        // the same NODE_PTR / NODE_GEN pair signal() and computed() stamp, so
+        // describe / track / dependencies / graph / findPath / ownerTree work
+        // when handed the dispose handle directly. NODE_GEN mirrors birthGen
+        // -- introspection validity agrees exactly with the disposer's own
+        // stale-guard. (Pre-existing gap on every prior version: the disposer
+        // was a bare closure and liveNode() reported live effects as stale.)
+        disposeFn[NODE_PTR] = node;
+        disposeFn[NODE_GEN] = birthGen;
+
         if (firstRunError !== null) {
             disposeFn();
             throw firstRunError;
@@ -1084,7 +1147,7 @@ export function createRegistry(config) {
 
     /**
      * Coalesce multiple synchronous writes into a single effect-flush pass.
-     * Nested batches are merged — only the outermost close triggers the flush.
+     * Nested batches are merged -- only the outermost close triggers the flush.
      *
      * Pre-batch revert (1.2.0): if a signal is set, then set back to its
      * pre-batch value (under its `equals`) before the outer close, the version
@@ -1163,7 +1226,7 @@ export function createRegistry(config) {
     }
 
     /**
-     * Snapshot of registry counters. Useful for diagnostics and tests —
+     * Snapshot of registry counters. Useful for diagnostics and tests --
      * e.g. asserting that `activeNodes` returns to a baseline after teardown.
      * @returns {RegistryStats}
      */
@@ -1255,11 +1318,11 @@ export function createRegistry(config) {
     }
 
     function hasObservers(handle) {
-        const node = handle != null ? handle[NODE_PTR] : undefined;
+        const node = liveNode(handle);
         return node !== undefined && node.headSub !== null;
     }
     function observeObservers(handle, opts) {
-        const node = handle != null ? handle[NODE_PTR] : undefined;
+        const node = liveNode(handle);
         if (node === undefined) throw new TypeError("observeObservers: argument is not a reactive handle");
         let e = lifecycleMap.get(node);
         if (e === undefined) {
@@ -1281,37 +1344,71 @@ export function createRegistry(config) {
     function describeNode(node) {
         const fl = node.flags;
         const kind = (fl & FLAG_EFFECT) !== 0 ? "effect" : (fl & FLAG_COMPUTED) !== 0 ? "computed" : "signal";
+        // Plain property assignment, not Object.defineProperty.
+        // Object.keys() never includes symbol-keyed properties regardless of
+        // descriptor -- enumerable: false was defending nothing. Confirmed
+        // empirically: `o[Symbol()] = x; Object.keys(o)` returns only
+        // string-keyed enumerable props.
         const d = {id: node.id, kind, value: node.value};
-        Object.defineProperty(d, NODE_PTR, {value: node, enumerable: false});
+        d[NODE_PTR] = node;
+        d[NODE_GEN] = node.gen;   // descriptors are re-walkable handles; stamp gen so the ABA guard holds for them too
         return d;
     }
+    // Gen-guarded handle resolution (1.2.1): with the v1.2 owner tree, the
+    // ENGINE recycles slots autonomously (owner re-run cascade-disposes owned
+    // children), so stale handles are a normal occurrence -- introspecting the
+    // slot's NEW resident through an old handle reports the wrong node.
+    // read()/set() already guard via closure-captured birthGen; the
+    // introspection surface must apply the same ABA guard via NODE_GEN.
+    function liveNode(handle) {
+        if (handle == null) return undefined;
+        const node = handle[NODE_PTR];
+        if (node === undefined) return undefined;
+        if (handle[NODE_GEN] !== node.gen) return undefined;   // stale: slot recycled
+        return node;
+    }
     function nodeId(handle) {
-        const node = handle != null ? handle[NODE_PTR] : undefined;
+        const node = liveNode(handle);
         return node !== undefined ? node.id : undefined;
     }
     function describe(handle) {
-        const node = handle != null ? handle[NODE_PTR] : undefined;
+        const node = liveNode(handle);
         return node !== undefined ? describeNode(node) : undefined;
     }
     function forEachObserver(handle, fn) {
-        const node = handle != null ? handle[NODE_PTR] : undefined;
+        const node = liveNode(handle);
         if (node === undefined) return;
         let l = node.headSub;
         while (l !== null) { const nx = l.nextSub; fn(describeNode(l.target)); l = nx; }
     }
+    /** Iterate this node's OWNED children (v1.2 owner tree). Additive 1.3 API
+     *  prototype: lets devtools/studio walk + render the ownership hierarchy
+     *  (cascade-disposal domains), which is invisible through dep/sub edges. */
+    function forEachOwned(handle, fn) {
+        const node = liveNode(handle);
+        if (node === undefined) return;
+        let c = node.firstOwned;
+        while (c !== null) { const nx = c.nextOwned; fn(describeNode(c)); c = nx; }
+    }
+    /** Descriptor of this node's owner, or undefined (top-level / stale handle). */
+    function ownerOf(handle) {
+        const node = liveNode(handle);
+        if (node === undefined || node.owner === null) return undefined;
+        return describeNode(node.owner);
+    }
     function forEachSource(handle, fn) {
-        const node = handle != null ? handle[NODE_PTR] : undefined;
+        const node = liveNode(handle);
         if (node === undefined) return;
         let l = node.headDep;
         while (l !== null) { const nx = l.nextDep; fn(describeNode(l.source)); l = nx; }
     }
 
-    return {signal, computed, effect, dispose, batch, untrack, onCleanup, stats, destroy, isTracking, hasObservers, observeObservers, forEachObserver, forEachSource, nodeId, describe};
+    return {signal, computed, effect, dispose, batch, untrack, onCleanup, stats, destroy, isTracking, hasObservers, observeObservers, forEachObserver, forEachSource, forEachOwned, ownerOf, nodeId, describe, onGraphMutation};
 }
 
-// ─────────────────────────────────────────────────────────────────
+// -----------------------------------------------------------------
 // GLOBAL BINDINGS
-// ─────────────────────────────────────────────────────────────────
+// -----------------------------------------------------------------
 
 let defaultRegistry = createRegistry();
 
@@ -1375,6 +1472,15 @@ export function forEachObserver(handle, fn) {
 export function forEachSource(handle, fn) {
     return defaultRegistry.forEachSource(handle, fn);
 }
+export function onGraphMutation(fn) {
+    return defaultRegistry.onGraphMutation(fn);
+}
+export function forEachOwned(handle, fn) {
+    return defaultRegistry.forEachOwned(handle, fn);
+}
+export function ownerOf(handle) {
+    return defaultRegistry.ownerOf(handle);
+}
 export function nodeId(handle) {
     return defaultRegistry.nodeId(handle);
 }