@zakkster/lite-signal 1.2.0 → 1.2.1

package/CHANGELOG.md

@@ -4,6 +4,125 @@ All notable changes to `@zakkster/lite-signal` are documented here.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [1.2.1] — 2026-06-12
+
+A correctness-and-pauses patch in two halves: the pool allocator stops paying
+for growth in unbounded bursts, and the introspection surface stops lying about
+handles the 1.2.0 owner tree disposed behind your back. Plus the graph-mutation
+hook — the keystone that lets lite-devtools 1.1 / lite-studio 1.1 go push-based.
+Drop-in over 1.2.0: 404-test suite green, 177/178 on
+johnsoncodehk/reactive-framework-test-suite (same single open cell, Inner
+Write #179), hot-path regression gate flat on two hosts.
+
+### Fixed — bounded pool growth (no more construction bursts)
+- Under `onCapacityExceeded: "grow"`, exhausting a pool used to double it by
+  synchronously constructing `currentCapacity` fresh nodes/links — at a
+  524,288-node pool that is a quarter-million 25-field allocations in one
+  pause, in whatever frame triggered it. Growth is now incremental: **one**
+  node/link constructed per free-list miss, pushed into the pool, recycled
+  forever after. The capacity **ledger** still doubles, so `stats()`
+  (`nodePoolCapacity` / `linkPoolCapacity` / `pooledLinks`), the
+  `maxLinks × 16` ceiling, and every `CapacityError` are bit-identical to
+  1.2.0 — only the construction schedule changed. Locked by the existing
+  `test/03-pool` capacity/ceiling/recycle contracts.
+- Benchmark effect (volynetstyle/js-reactivity-benchmark, same host as the
+  1.2.0 baseline run): creation group 489 → 423 ms (−13.5%), with the burst
+  cases roughly halved (`1to2` 112 → 58, `1to8` 113 → 55, `1to4` 81 → 54).
+  Honest redistribution note: rows that previously *fit inside the doubling
+  overshoot* (`createDataSignals` 12.8 → 71.9, `1to1` 17.8 → 43.2) now pay
+  their construction inside the measured window — 1.2.0's overshoot was an
+  accidental prefetch, and the same mechanism produced the pathological
+  bursts. Bounded pauses are the right trade for real applications; the
+  group total still improves.
+- Steady-state hot paths are untouched (update / dynamic-retracking /
+  effect-recycle measured flat on both benchmark hosts).
+
+### Fixed — effect queues / mark stack stay PACKED
+- Pool growth used to pre-size `effectQueueA/B` and the mark stack with
+  `arr.length = newCap` — which permanently converts a PACKED V8 array to
+  HOLEY elements, a silent tax on every subsequent flush read. The queues now
+  grow by sequential append (packed-preserving, auto-amortised) and
+  `destroy()` truncates instead of null-filling to capacity.
+
+### Fixed — `destroy()` iterates physical pools
+- `destroy()` walked `currentNodesCapacity` slots by index; with incremental
+  growth (and any future lazy population) the ledger can exceed the physical
+  pool. It now walks `nodePool.length` / `linkPool.length` and is safe on an
+  empty pool.
+
+### Fixed — stale-handle introspection (the owner-tree follow-up)
+- 1.2.0's owner tree made the engine recycle pool slots **autonomously**: an
+  owner re-run cascade-disposes its owned observers, so holding a stale handle
+  stopped being a user error and became a routine occurrence. The
+  introspection surface — `nodeId` / `describe` / `forEachObserver` /
+  `forEachSource` / `hasObservers` / `observeObservers` — still resolved
+  `NODE_PTR` without a generation check and would happily report the
+  **recycled slot's new resident** (wrong id, wrong value, wrong edges)
+  through an old handle. All six entry points now resolve through a
+  gen-guarded `liveNode()` and report stale handles as `undefined` (or throw
+  the existing `TypeError`, for `observeObservers`) — the same ABA discipline
+  `read()` / `set()` / `dispose()` already had.
+- `describe()` descriptors are now **gen-stamped** alongside the node
+  reference, so the documented "descriptors are re-walkable handles" contract
+  survives the guard: a fresh descriptor walks; one held across a recycle
+  correctly goes stale. Pinned by the existing
+  "forEach* descriptors carry id and are re-walkable" test.
+- **Effect dispose handles are now first-class introspection handles.** On
+  every prior version, `effect()` returned a bare closure carrying neither
+  `NODE_PTR` nor `NODE_GEN` — so `describe` / `nodeId` / `forEachSource`
+  returned `undefined`/empty for a **live** effect handle, and
+  `observeObservers(effectHandle)` threw. The dispose function is now stamped
+  with the same symbol pair as signal/computed handles (`NODE_GEN` mirrors the
+  disposer's own `birthGen`, so introspection validity agrees exactly with its
+  stale-guard). After explicit dispose, slot recycle, or owner-cascade the
+  handle correctly reads stale. Measured cost: two property stores per effect
+  creation (~50 ns on a create/dispose churn microbench) — symmetric with
+  what signal/computed handles already pay, create-path only. Found by the
+  lite-devtools 1.1 cross-probe campaign (`track(effectHandle)` threw).
+- `peek()` had the same hole: `sharedSignalPeek` / `sharedComputedPeek`
+  resolved the slot ungated, so a stale handle's `peek()` returned the new
+  resident's value. Both now gen-check first and return `undefined` when
+  stale — closing the last unguarded entry point in the probe-c1 ABA family.
+  Measured cost: 4M peeks 7.1 → 7.4 ms (≈0.08 ns/op).
+
+### Added — `onGraphMutation(fn)`: the graph-mutation hook
+- Registry-level (and default-registry module export) debug hook, the
+  connection point for push-based tooling. Single nullable listener; every
+  fire point is one `if (mutationHook !== null)` branch and the dispatch is
+  allocation-free — `(opcode, intA, intB)`:
+    - `1` node create — `(id, flags)`, end of `createNode`
+    - `2` node dispose — `(id, flags)`, top of `disposeNode` (cascades included)
+    - `3` link add — `(source.id, target.id)`
+    - `4` link remove — `(source.id, target.id)`
+    - `5` recompute — `(id, 0)`, before an effect re-run / computed re-eval
+- Cost: **zero when unregistered** (hot-path gate flat); registered, the
+  worst case measured is +29% on a dynamic-retracking torture loop (11.4M
+  events for 400K writes) — a debug-mode tax paid only while a consumer is
+  attached, proportional to event volume.
+- **Listener contract: observe only — never throw, never mutate the graph.**
+  The hook fires synchronously inside mutation points; lite-devtools 1.1
+  multiplexes all of its consumers behind one registration, isolates their
+  exceptions, and unregisters when the last consumer stops (returning the
+  engine to the zero-cost state). `onGraphMutation` returns an unsubscribe
+  that restores the previously registered listener.
+
+### Added — owner-tree introspection: `forEachOwned` / `ownerOf`
+- The 1.2.0 owner tree finally gets a (read-only, gen-guarded) window:
+  `forEachOwned(handle, fn)` iterates a node's owned children as standard
+  re-walkable descriptors; `ownerOf(handle)` returns the owner's descriptor
+  or `undefined` (top-level or stale). Same descriptor conventions as
+  `forEachObserver` / `forEachSource`; garbage input is a no-op /
+  `undefined`. This is what lite-devtools 1.1 builds `ownerTree()` and the
+  `graph({owners: true})` ownership edges on
+  (`capabilities().owners === true` from this release).
+
+### Compatibility
+- No behavioural change for live handles; stale handles now read as stale
+  everywhere instead of as the slot's next tenant. Allocation strategy is
+  unobservable through the public API. Tooling floor: lite-devtools ≥ 1.1.0
+  detects `onGraphMutation` / `forEachOwned` at load and degrades to its
+  1.0 polling behaviour on older engines.
+
 ## [1.2.0] — 2026-06-11
 
 A structural refactor that internally splits the engine into three named layers

package/README.md

@@ -220,10 +220,21 @@ Computeds are **pull-based** — they're not in the effect queue. Reading a comp
 
 ```ts
 import {
+  // Core
   signal, computed, effect,
-  batch, untrack, onCleanup,
-  createRegistry, setDefaultRegistry,
-  stats, CapacityError
+  batch, untrack, onCleanup, isTracking,
+  // Registry / lifecycle
+  createRegistry, setDefaultRegistry, dispose, destroy,
+  stats, CapacityError,
+  // Introspection (1.1.4 / 1.1.5 / 1.2.1)
+  hasObservers, observeObservers,
+  forEachObserver, forEachSource,
+  nodeId, describe,
+  forEachOwned, ownerOf,        // 1.2.1
+  // Debug hook (1.2.1)
+  onGraphMutation,
+  // Watchers
+  watch, when, whenAsync,
 } from "@zakkster/lite-signal";
 ```
 
@@ -328,18 +339,61 @@ hasObservers(now);                  // O(1): is anyone subscribed right now? (a
 // Walk the live graph in either direction (lite-devtools):
 forEachObserver(sum, d => console.log(d.kind, d.value));  // subscribers of `sum`
 forEachSource(sum,   d => console.log(d.kind, d.value));  // dependencies of `sum`
+
+// 1.2.1: walk the owner tree (cascade-disposal domains)
+forEachOwned(effectHandle, d => console.log(d.kind, d.id));  // observers this one will cascade-dispose
+ownerOf(innerComputedDesc);                                  // descriptor of the enclosing effect/computed
 ```
 
-Six functions (top-level + per-registry) — four in 1.1.4, two more in 1.1.5 — for auto-pausing wrappers and graph inspection:
+Eight functions (top-level + per-registry) — four in 1.1.4, two in 1.1.5, two more in 1.2.1 — for auto-pausing wrappers and graph inspection:
 
 - **`hasObservers(handle)` → `boolean`** — O(1) (`node.headSub !== null`). The auto-pause predicate.
 - **`observeObservers(handle, { onConnect?, onDisconnect? })` → `unobserve`** — fires on the 0→1 and 1→0 observer transitions *after* registration (transition-only — no immediate fire if already observed). Re-tracking a persistently-read source does **not** churn. This is the hook `lite-time` / `lite-raf` use to run a clock only while a derived value is watched. Throws `TypeError` on a non-handle.
 - **`forEachObserver(handle, fn)` / `forEachSource(handle, fn)`** — walk subscribers / dependencies; `fn` gets a `{ id, kind, value }` descriptor (`kind` ∈ `"signal" | "computed" | "effect"`; `id` added in 1.1.5). No-op on a non-handle.
 - **`nodeId(handle)` → `number | undefined`** *(1.1.5)* — the node's stable per-allocation id; the dedupe key for graph traversal. `undefined` on a non-handle.
-- **`describe(handle)` → `{ id, kind, value } | undefined`** *(1.1.5)* — the handle's own descriptor. **Re-walkable**: pass it back into `forEachObserver`/`forEachSource` to recurse the graph. `undefined` on a non-handle.
+- **`describe(handle)` → `{ id, kind, value } | undefined`** *(1.1.5)* — the handle's own descriptor. **Re-walkable**: pass it back into any `forEach*` to recurse the graph. `undefined` on a non-handle.
+- **`forEachOwned(handle, fn)`** *(1.2.1)* — walk this node's owned children (lifetime-binding edges from the 1.2 owner tree). The dep/sub edges show DATA FLOW; the owner edges show LIFETIME BINDING — when this handle re-runs or is disposed, every owned child is cascade-disposed. No-op on a non-handle, top-level handle with no children, or stale handle.
+- **`ownerOf(handle)` → `{ id, kind, value } | undefined`** *(1.2.1)* — descriptor of `handle`'s owner, or `undefined` for top-level / stale handles. The inverse of `forEachOwned`: walks UP the owner tree.
 
 The surface is gated by an internal lifecycle counter: when nothing is being observed, the hot path adds a single branch-predicted `count !== 0` check in link alloc/free and nothing else — **zero steady-state cost when unused**.
 
+#### Stale-handle guard (1.2.1)
+
+The 1.2.0 owner tree makes the engine recycle pool slots autonomously: when an effect or computed re-runs, every observer it created in its previous body is cascade-disposed. **Holding a stale handle stopped being a user error and became routine.** Pre-1.2.1, the introspection surface plus `peek()` resolved `NODE_PTR` ungated and would happily report the recycled slot's NEW resident — wrong id, wrong value, wrong edges.
+
+1.2.1 generation-checks every entry point that resolves a handle (the same ABA discipline `dispose()` always had):
+
+- `nodeId`, `describe`, `hasObservers`, `forEachObserver`, `forEachSource`, `forEachOwned`, `ownerOf`, `signal.peek()`, `computed.peek()`, `signal()`/`computed()` read, `signal.set()` → return `undefined` / are no-ops on stale handles.
+- `observeObservers` throws `TypeError` (matching the existing non-handle contract).
+
+Descriptors returned by `describe()` and the `forEach*` walkers are themselves gen-stamped, so the documented "descriptors are re-walkable handles" contract survives the guard: a fresh descriptor walks, one held across a recycle correctly goes stale.
+
+### onGraphMutation (1.2.1)
+
+```ts
+// Push-based devtools / studio integration. Single listener, allocation-free dispatch.
+const unsub = onGraphMutation((opcode, intA, intB) => {
+  switch (opcode) {
+    case 1: devtools.onNodeCreate(intA, intB);  break;   // intA = node.id, intB = node.flags
+    case 2: devtools.onNodeDispose(intA);       break;   //   ditto (cascade-disposed children included)
+    case 3: devtools.onLinkAdd(intA, intB);     break;   // intA = source.id, intB = target.id
+    case 4: devtools.onLinkRemove(intA, intB);  break;
+    case 5: devtools.onRecompute(intA);         break;   // before each effect re-run / computed re-eval
+  }
+});
+
+// Stop listening — restores the previous registration (or null), engine returns to zero-cost state.
+unsub();
+```
+
+A registry-level (and top-level) debug hook for push-based tooling — the connection point lite-devtools 1.1 and lite-studio 1.1 use to walk away from polling. Single nullable listener; every fire point in the engine is one `if (mutationHook !== null) mutationHook(opcode, intA, intB)`:
+
+- **Zero cost when unregistered** — branch-predicted null check per mutation point, same as the lifecycle counter pattern.
+- **Allocation-free when registered** — three integers, no objects, no closures. Worst-case measured cost on a dynamic-retracking torture loop (11.4M events over 400K writes) is +29% — a debug-mode tax proportional to event volume, paid only while a consumer is attached.
+- **LIFO stacking** — `onGraphMutation(a); onGraphMutation(b); unsubB()` restores `a`. Used by lite-devtools 1.1 to multiplex multiple consumers behind one engine registration.
+
+**Listener contract: observe only — never throw, never mutate the graph from inside.** The hook fires synchronously inside mutation points; mutating from the callback corrupts the in-flight operation. Wrap any downstream work that could touch the registry in a microtask.
+
 ### onCleanup
 
 ```ts
@@ -641,6 +695,9 @@ Three tiers, all reproducible.
 - **`18-identity_test.mjs`** — Node identity (1.1.5; 5 tests). Unique/stable ids; `nodeId`/`describe` return `undefined` for a non-handle; the descriptor's visible shape is `{ id, kind, value }`; `forEach*` descriptors carry `id` and are **re-walkable** (`nodeId`/`forEachSource` accept a descriptor); identity walks are non-perturbing (add no observers).
 - **`19-v12-additions_test.mjs`** — v1.2.0 release-prep regressions (24 tests across 8 suites). Shared `peek` (one closure per registry, identical reference across primitives, no tracking, two registries hold independent peeks). Owner-adoption rule (signals not adopted, computeds/effects adopted, cascade drains correctly). Pre-batch revert (signal-level, propagates through computeds, respects custom `equals`, nested batches, final-different-value still fires). Multi-throw aggregation (`AggregateError` with both errors carried, single-throw unwrapped, engine survives). `CycleError` via `maxFlushPasses` (default + custom). `maxLinks` config branch under `throw` and `grow`. Documented disposed-signal semantics (read undefined, set silent no-op, dispose idempotent). Scheduler-thunk ABA guard across a recycled pool slot.
 - **`20-axis-stress_test.mjs`** — engine-invariant regression guards along eight orthogonal "axes" (16 tests across 9 suites). Pins lite-signal's actual contract on: batch semantics under exception (writes commit; pre-batch revert holds; effects see the post-throw value), connect/disconnect lifecycle re-entrancy (`observeObservers` from inside an `onConnect`, transition-only registration), untrack does NOT suppress owner adoption (a nested effect created via `untrack` is still owner-cascaded), untrack inside a computed body (no hidden dep leaks; tracked source re-evaluates), queue safety under self-dispose mid-flush (no UAF), value-dependent cycle detection (computed graph closes a cycle, `CycleError` thrown), nested-effect creation order (effects run synchronously on creation; immediately-stopped one still ran), synchronous flush (no scheduler in the default path; batch coalesces). Plus a bonus suite: 1,000 effect-create-then-dispose cycles return pool to baseline; `dispose()` idempotent; `dispose()` on foreign values safe.
+- **`21-perf-pins_test.mjs`** — v1.2.1 construction-shape pins (6 tests). Locks the canonical handle shapes (`signal` 6 own props: peek/set/update/subscribe + NODE_PTR/NODE_GEN; `computed` 4: peek/subscribe + NODE_PTR/NODE_GEN) so a future "let's unify them" change has to be explicit. Locks the 1.2.1 ABA guards: detached `const {set} = signal()` keeps working on a LIVE signal; `read()` returns `undefined` and skips dep-tracking on a stale handle (no phantom subscription to the recycled slot); `set()` on a stale handle is a no-op across three corruption tiers (disposed slot, recycled slot, downstream propagation); `peek()` returns `undefined` for stale signal and computed handles.
+- **`22-mutation-hook_test.mjs`** — 1.2.1 `onGraphMutation` semantics (12 tests across 2 suites). Registration: unsubscribe returns a function; `null` argument clears and the unsub restores the prior listener; non-function/non-null throws `TypeError`; multiple registrations stack LIFO; registries are isolated (no cross-talk). Opcode emission: `1` node-create fires with `(id, flags)` for signal (32) / computed (1) / effect (2); `2` node-dispose fires for cascade-disposed owned children; `3` link-add fires with `(source.id, target.id)` on dependency record; `4` link-remove fires when a dep-set flip severs the tail; `5` recompute fires on initial eval AND re-eval; the hook fires synchronously inside the mutation (listener sees its own event before the caller returns); payload is always three plain numbers — no objects, no closures.
+- **`23-owner-introspection_test.mjs`** — 1.2.1 owner-tree introspection + effect-disposer regression (22 tests across 4 suites). `ownerOf`: undefined for top-level / garbage input / stale handle; returns the enclosing effect's descriptor for a child created inside an effect body. `forEachOwned`: no-op for handles with no owned children / garbage input / stale handle; iterates owned children as `{id, kind, value}` descriptors. Gen-guarded introspection (ABA fix): `nodeId` / `describe` / `hasObservers` return undefined / false for stale handles; `observeObservers` throws `TypeError`; `forEachObserver` / `forEachSource` are no-ops; descriptors returned by `describeNode` are themselves gen-stamped so a descriptor obtained pre-recycle correctly walks as a no-op post-recycle (the "descriptors are re-walkable handles" contract survives the guard). Plus the 1.2.1 effect-dispose-handle fix: passing the effect's disposer directly to `describe` / `nodeId` / `forEachSource` / `forEachOwned` / `ownerOf` / `hasObservers` works as a first-class introspection handle (pre-fix it was a bare closure and returned `undefined` for a *live* effect); after `fx()` dispose the same handle correctly goes stale on every entry point; the disposer's `NODE_GEN` mirrors the effect node's birthGen exactly.
 
 ```bash
 npm test

package/Signal.d.ts

@@ -121,6 +121,35 @@ export type Unobserve = () => void;
 /** Anything carrying a node identity that the introspection surface can read. */
 export type ReactiveHandle = Signal<any> | Computed<any>;
 
+// ─── Graph-mutation hook (1.2.1) ──────────────────────────────────────────────
+
+/**
+ * Opcode passed as the first argument to a {@link GraphMutationListener}.
+ *
+ *  - `1` node create.    `(intA, intB) = (node.id, node.flags)`.
+ *  - `2` node dispose.   `(intA, intB) = (node.id, node.flags)` — fires for every node
+ *                        disposed, including cascaded owner-tree children.
+ *  - `3` link add.       `(intA, intB) = (source.id, target.id)`.
+ *  - `4` link remove.    `(intA, intB) = (source.id, target.id)` — `-1` if the link
+ *                        was already nulled (defensive, rare).
+ *  - `5` recompute.      `(intA, intB) = (node.id, 0)` — fires just before an effect
+ *                        re-run or a computed re-eval.
+ */
+export type GraphMutationOpcode = 1 | 2 | 3 | 4 | 5;
+
+/**
+ * Listener registered with {@link Registry.onGraphMutation}. Called synchronously
+ * inside each mutation point with three integers — no objects allocated.
+ *
+ * **Contract: observe only.** Listeners MUST NOT throw and MUST NOT mutate the
+ * graph from inside the callback. Both will corrupt the engine's state. Wrap any
+ * downstream work in a microtask if it could touch the registry.
+ */
+export type GraphMutationListener = (opcode: GraphMutationOpcode, intA: number, intB: number) => void;
+
+/** Idempotent unsubscriber returned by {@link Registry.onGraphMutation}. */
+export type GraphMutationUnsubscribe = () => void;
+
 // ─── Errors ───────────────────────────────────────────────────────────────────
 
 /** Thrown when a pool ceiling is hit. */
@@ -177,16 +206,35 @@ export interface Registry {
     forEachObserver(handle: ReactiveHandle, fn: (descriptor: NodeDescriptor) => void): void;
     /** Walk the sources (dependencies) of `handle`. No-op on a non-handle. */
     forEachSource(handle: ReactiveHandle, fn: (descriptor: NodeDescriptor) => void): void;
-    /** Stable node id of `handle` (1.1.5+), or undefined for a non-handle. */
+    /** Walk the owned children of `handle` -- nodes whose lifetime is bound to this
+     *  one by the 1.2 owner tree (1.2.1+). Top-level handles and signals have no
+     *  owned children; effects/computeds may own nested observers created inside
+     *  their bodies. No-op on a non-handle or stale handle. */
+    forEachOwned(handle: ReactiveHandle, fn: (descriptor: NodeDescriptor) => void): void;
+    /** Descriptor of `handle`'s owner, or `undefined` for top-level handles, stale
+     *  handles, or non-handles (1.2.1+). The owner is the effect or computed inside
+     *  whose body `handle` was created -- the node that will cascade-dispose it
+     *  on re-run or explicit dispose. */
+    ownerOf(handle: ReactiveHandle): NodeDescriptor | undefined;
+    /** Stable node id of `handle` (1.1.5+), or undefined for a non-handle or stale handle. */
     nodeId(handle: ReactiveHandle): number | undefined;
-    /** The own descriptor of `handle` (1.1.5+), or undefined for a non-handle. Re-walkable:
-     *  the returned descriptor may be passed back into forEachObserver/forEachSource. */
+    /** The own descriptor of `handle` (1.1.5+), or undefined for a non-handle or stale handle.
+     *  Re-walkable: the returned descriptor may be passed back into forEachObserver/
+     *  forEachSource/forEachOwned/ownerOf. Descriptors are gen-stamped (1.2.1+): a
+     *  descriptor obtained pre-recycle goes stale and walks as undefined post-recycle. */
     describe(handle: ReactiveHandle): NodeDescriptor | undefined;
+    /** Register a single graph-mutation listener (1.2.1+). Replaces any existing
+     *  listener and returns an unsubscribe that restores the previous one on call.
+     *  Listener is invoked synchronously at each mutation point with three integers:
+     *  `(opcode, intA, intB)` -- see {@link GraphMutationOpcode}. Cost when no
+     *  listener is registered: one branch-predicted `null` check per mutation point.
+     *  @throws TypeError if `fn` is not a function or null. */
+    onGraphMutation(fn: GraphMutationListener | null): GraphMutationUnsubscribe;
     onCleanup(fn: () => void): void;
     stats(): RegistryStats;
     /** Reset everything: nodes, links, queues, global clock. Outstanding dispose
      *  closures become safe no-ops. Outstanding read/set closures still reference
-     *  pool slots — they will silently misbehave; use a fresh registry afterwards. */
+     *  pool slots -- they will silently misbehave; use a fresh registry afterwards. */
     destroy(): void;
 }
 
@@ -222,10 +270,16 @@ export function observeObservers(handle: ReactiveHandle, hooks?: ObserveObserver
 export function forEachObserver(handle: ReactiveHandle, fn: (descriptor: NodeDescriptor) => void): void;
 /** Top-level binding of {@link Registry.forEachSource}. */
 export function forEachSource(handle: ReactiveHandle, fn: (descriptor: NodeDescriptor) => void): void;
+/** Top-level binding of {@link Registry.forEachOwned} (1.2.1+). */
+export function forEachOwned(handle: ReactiveHandle, fn: (descriptor: NodeDescriptor) => void): void;
+/** Top-level binding of {@link Registry.ownerOf} (1.2.1+). */
+export function ownerOf(handle: ReactiveHandle): NodeDescriptor | undefined;
 /** Top-level binding of {@link Registry.nodeId}. */
 export function nodeId(handle: ReactiveHandle): number | undefined;
 /** Top-level binding of {@link Registry.describe}. */
 export function describe(handle: ReactiveHandle): NodeDescriptor | undefined;
+/** Top-level binding of {@link Registry.onGraphMutation} (1.2.1+). */
+export function onGraphMutation(fn: GraphMutationListener | null): GraphMutationUnsubscribe;
 export function onCleanup(fn: () => void): void;
 export function stats(): RegistryStats;
 export declare function destroy(): void;

package/Signal.js

@@ -1,5 +1,5 @@
 /**
- * @zakkster/lite-signal v1.2.0
+ * @zakkster/lite-signal v1.2.1
  * --------------------
  * Hybrid Doubly-Linked-List Reactive Graph Engine — decoupled (Signal1_3) base
  * with the two 1.1.3 performance fixes ported in:
@@ -60,6 +60,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;
 
 /**
@@ -272,6 +277,20 @@ 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
@@ -338,10 +357,12 @@ 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;
@@ -391,6 +412,7 @@ export function createRegistry(config) {
     // ─── 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
@@ -556,6 +578,7 @@ export function createRegistry(config) {
             node.owner = null;
         }
 
+        if (mutationHook !== null) mutationHook(1, node.id, node.flags | 0);
         return node;
     }
 
@@ -763,6 +786,7 @@ export function createRegistry(config) {
         // 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 {
@@ -839,6 +863,7 @@ export function createRegistry(config) {
 
             // 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;
@@ -906,8 +931,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 +954,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 +984,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 +1025,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) {
@@ -1063,6 +1109,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;
@@ -1255,11 +1311,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,32 +1337,66 @@ 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};
 }
 
 // ─────────────────────────────────────────────────────────────────
@@ -1375,6 +1465,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);
 }

package/llms.txt

@@ -21,7 +21,7 @@ triggering write — no `queueMicrotask`, no promises, no scheduler ticks.
 - **Untrack**: `untrack(fn)` reads without subscribing.
 - **isTracking**: `isTracking()` returns true iff a read right now would record a dependency on this registry (for wrappers that lazily allocate signals).
 - **onCleanup**: registers teardown for the current computation; fires before each re-run and once on dispose. Works in effects and computeds.
-- **Observer-lifecycle introspection** (1.1.4; top-level + per-registry): `hasObservers(handle)` returns true iff a signal/computed has ≥1 live observer right now (O(1); a `peek` does not count). `observeObservers(handle, { onConnect?, onDisconnect? })` fires on the 0→1 and 1→0 observer transitions (after registration; transition-only) and returns an idempotent unobserve — the auto-pause hook for tickers (lite-time/lite-raf start a source only while it's watched). `forEachObserver(handle, fn)` / `forEachSource(handle, fn)` walk the live graph in either direction, passing a `{ kind, value }` descriptor (`kind` is `"signal" | "computed" | "effect"`) — for inspection (lite-devtools). The surface is gated by an internal counter: zero steady-state cost when nothing is observed. `hasObservers`/`forEach*` no-op on a non-handle; `observeObservers` throws `TypeError`. **Node identity (1.1.5):** `nodeId(handle)` returns the node's stable per-allocation id, `describe(handle)` returns the handle's own `{ id, kind, value }` descriptor, and `forEach*` descriptors now carry `id` too; a descriptor is **re-walkable** (pass it back into `forEachObserver`/`forEachSource`) — the recursion primitive lite-devtools uses to walk the full DAG.
+- **Observer-lifecycle introspection** (1.1.4; top-level + per-registry): `hasObservers(handle)` returns true iff a signal/computed has ≥1 live observer right now (O(1); a `peek` does not count). `observeObservers(handle, { onConnect?, onDisconnect? })` fires on the 0→1 and 1→0 observer transitions (after registration; transition-only) and returns an idempotent unobserve — the auto-pause hook for tickers (lite-time/lite-raf start a source only while it's watched). `forEachObserver(handle, fn)` / `forEachSource(handle, fn)` walk the live graph in either direction, passing a `{ kind, value }` descriptor (`kind` is `"signal" | "computed" | "effect"`) — for inspection (lite-devtools). The surface is gated by an internal counter: zero steady-state cost when nothing is observed. `hasObservers`/`forEach*` no-op on a non-handle; `observeObservers` throws `TypeError`. **Node identity (1.1.5):** `nodeId(handle)` returns the node's stable per-allocation id, `describe(handle)` returns the handle's own `{ id, kind, value }` descriptor, and `forEach*` descriptors now carry `id` too; a descriptor is **re-walkable** (pass it back into `forEachObserver`/`forEachSource`) — the recursion primitive lite-devtools uses to walk the full DAG. **Owner-tree introspection (1.2.1):** `forEachOwned(handle, fn)` walks a node's owned children (lifetime-binding edges from the 1.2 owner tree — invisible through dep/sub); `ownerOf(handle)` returns the owner's descriptor or `undefined` for top-level / stale handles. **Stale-handle guard (1.2.1):** the entire introspection surface plus `peek()`/`read()`/`set()` is now generation-checked. A handle held across the 1.2 owner-cascade auto-dispose used to resolve `NODE_PTR` ungated and silently report the recycled slot's NEW resident; 1.2.1 surfaces stale handles as `undefined` (or `TypeError`, for `observeObservers`) — same ABA discipline `dispose()` always had. Descriptors are gen-stamped so the re-walkable contract survives the guard. **Push-based mutation hook (1.2.1):** `onGraphMutation(fn)` registers a single nullable listener invoked synchronously at every mutation point with three integers `(opcode, intA, intB)` — opcodes `1` node-create / `2` node-dispose / `3` link-add / `4` link-remove / `5` recompute. Zero-cost gate when no listener is registered (one branch-predicted null check); allocation-free dispatch when registered. The connection point for push-based devtools/studio. Contract: observe only — never throw, never mutate.
 - **Registry**: `createRegistry({ maxNodes, maxLinks, onCapacityExceeded, maxFlushPasses })` creates an isolated reactive world with its own pools. Useful for tests, plugins, multi-tenant sandboxes. Top-level helpers use a default registry created at module load.
 - **CapacityError**: thrown when a fixed-size pool is exhausted under the `"throw"` policy, or when a `"grow"` policy hits the 16× starting-capacity ceiling on links.
 
@@ -50,7 +50,44 @@ triggering write — no `queueMicrotask`, no promises, no scheduler ticks.
 
 ## Version notes
 
-- **1.2.0** (current): structural refactor (three named layers: graph topology /
+- **1.2.1** (current): correctness-and-introspection patch. Drop-in over 1.2.0;
+  no public surface removed. **Stale-handle introspection (ABA fix):** the v1.2.0
+  owner tree made the engine recycle pool slots autonomously on owner re-run, so
+  holding a stale handle stopped being a user error and became a routine
+  occurrence. Pre-1.2.1, `nodeId`/`describe`/`forEachObserver`/`forEachSource`/
+  `hasObservers`/`observeObservers`/`peek()` would resolve `NODE_PTR` ungated
+  and happily report the recycled slot's NEW resident through an old handle
+  (wrong id, wrong value, wrong edges). All six entry points + `peek()` + `read()`
+  + `set()` now resolve through a generation check (the same ABA discipline
+  `dispose()` already had); stale handles read as `undefined` (or throw the
+  documented `TypeError`, for `observeObservers`). `describe()` descriptors are
+  gen-stamped alongside `NODE_PTR`, so the "descriptors are re-walkable handles"
+  contract survives the guard: a fresh descriptor walks, one held across a
+  recycle correctly goes stale. **Added — `onGraphMutation(fn)`:** registry-level
+  (and top-level) graph-mutation hook for push-based tooling. Single nullable
+  listener; every fire point is `if (mutationHook !== null) mutationHook(opcode, intA, intB)`
+  — zero-cost gate when absent, allocation-free dispatch when present. Opcodes:
+  `1` node-create `(id, flags)`, `2` node-dispose `(id, flags)` (cascades
+  included), `3` link-add `(source.id, target.id)`, `4` link-remove `(source.id, target.id)`,
+  `5` recompute `(id, 0)` before each effect re-run / computed re-eval.
+  Contract: observe only — never throw, never mutate the graph from inside.
+  This is the connection point lite-devtools 1.1 / lite-studio 1.1 use to go
+  push-based. **Added — `forEachOwned(handle, fn)` / `ownerOf(handle)`:** owner-
+  tree introspection. `forEachOwned` iterates a node's owned children as
+  re-walkable descriptors; `ownerOf` returns the owner's descriptor or
+  `undefined` (top-level or stale). Same descriptor conventions as
+  `forEachObserver`/`forEachSource`; garbage input is a no-op/`undefined`.
+  Also: `Object.is` hoisted to a module-level const (one IC entry instead of
+  per-call lookup in `signal()`/`computed()`). 404 tests, **100% line / 98.07%
+  branch coverage** on `Signal.js` + `Watch.js`. New
+  `test/21-perf-pins.test.mjs` (6 tests — construction-shape + ABA-guard pins),
+  `test/22-mutation-hook.test.mjs` (12 tests — `onGraphMutation` registration,
+  the 5 opcodes, payload shape, registry isolation), and
+  `test/23-owner-introspection.test.mjs` (14 tests — `forEachOwned`, `ownerOf`,
+  and gen-guarded behaviour across the introspection surface). Differential
+  fuzz vs the published 1.1.5: 0 disagreements over 30,000 writes.
+
+- **1.2.0**: structural refactor (three named layers: graph topology /
   ownership / propagation) plus four additive features built on top. Drop-in over
   1.1.5; no public surface removed. **Owner tree:** an effect or computed that
   creates nested observers (effect/computed) now owns them — when the owner
@@ -151,8 +188,13 @@ function observeObservers(
 ): () => void;                          // returns idempotent unobserve
 function forEachObserver(handle: Signal<any> | Computed<any>, fn: (d: NodeDescriptor) => void): void;
 function forEachSource(handle: Signal<any> | Computed<any>, fn: (d: NodeDescriptor) => void): void;
+function forEachOwned(handle: Signal<any> | Computed<any>, fn: (d: NodeDescriptor) => void): void;   // 1.2.1
+function ownerOf(handle: Signal<any> | Computed<any>): NodeDescriptor | undefined;                    // 1.2.1
 function nodeId(handle: Signal<any> | Computed<any>): number | undefined;            // 1.1.5
 function describe(handle: Signal<any> | Computed<any>): NodeDescriptor | undefined;   // 1.1.5
+function onGraphMutation(                                                              // 1.2.1
+  fn: ((opcode: 1|2|3|4|5, intA: number, intB: number) => void) | null
+): () => void;                                                                          // unsub restores prior listener
 function onCleanup(fn: () => void): void;
 function stats(): RegistryStats;
 
@@ -324,6 +366,31 @@ const sandbox = createRegistry({ maxNodes: 256, onCapacityExceeded: "throw" });
 plugin(sandbox.signal, sandbox.computed, sandbox.effect);
 // later:
 sandbox.destroy();   // entire reactive world reset
+
+// 1.2.1: push-based devtools via onGraphMutation
+// Single listener; opcodes 1=create, 2=dispose, 3=link-add, 4=link-remove, 5=recompute.
+// Allocation-free dispatch with just three integers.
+const unsubscribe = onGraphMutation((opcode, intA, intB) => {
+  switch (opcode) {
+    case 1: devtools.onNodeCreate(intA, intB);   break;   // intA=id, intB=flags
+    case 2: devtools.onNodeDispose(intA);        break;
+    case 3: devtools.onLinkAdd(intA, intB);      break;   // intA=source.id, intB=target.id
+    case 4: devtools.onLinkRemove(intA, intB);   break;
+    case 5: devtools.onRecompute(intA);          break;
+  }
+});
+// Stop listening — restores prior listener (or null), engine returns to zero-cost state.
+unsubscribe();
+
+// 1.2.1: walk the owner tree (cascade-disposal domains)
+//   forEachOwned + ownerOf complement forEachObserver + forEachSource:
+//   the dep/sub edges show DATA FLOW; the owner edges show LIFETIME BINDING.
+function dumpOwnerTree(handle, depth = 0) {
+  const d = describe(handle);
+  if (!d) return;
+  console.log(" ".repeat(depth * 2), d.kind, d.id);
+  forEachOwned(d, (child) => dumpOwnerTree(child, depth + 1));
+}
 ```
 
 ## File layout

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-signal",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Zero-GC reactive graph. Monomorphic object pool, versioned push-pull propagation, 32-bit modular versioning. Built for hot paths and long-running processes.",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
   "license": "MIT",
@@ -45,7 +45,10 @@
     "object-pool",
     "fine-grained",
     "twitch-extension",
-    "performance"
+    "performance",
+    "devtools",
+    "introspection",
+    "owner-tree"
   ],
   "homepage": "https://github.com/PeshoVurtoleta/lite-signal#readme",
   "repository": {