@zakkster/lite-signal 1.1.4 → 1.1.5

package/README.md

@@ -104,6 +104,9 @@ Full type definitions ship in [`Signal.d.ts`](./Signal.d.ts) and are referenced
 
 ## The case for object pooling
 
+<details>
+<summary>Why pre-allocate: the GC math, and the per-op zero-allocation table.</summary>
+
 A naive reactive library allocates one object per dependency edge, one per subscription, one per queued effect. With 1000 computeds × 1 update / frame × 60 fps, that's 60,000 short-lived objects per second. The major GC will catch up with you.
 
 `lite-signal` solves this by pre-allocating two pools at startup — **nodes** (one per signal/computed/effect) and **links** (one per dependency edge) — and reusing them indefinitely. After the warm-up frames, the hot path performs zero allocations:
@@ -118,10 +121,15 @@ A naive reactive library allocates one object per dependency edge, one per subsc
 
 The free lists are singly-linked through a `nextFree` field on each pool object — `O(1)` pop, `O(1)` push, no fragmentation.
 
+</details>
+
 ---
 
 ## Architecture in one diagram
 
+<details>
+<summary>Pools, the reactive graph, hot-path state, and the doubly-linked edge model.</summary>
+
 ```mermaid
 flowchart TB
   subgraph Pools[Pre-allocated object pools]
@@ -163,10 +171,15 @@ Every reactive entity is a `ReactiveNode` with bit flags (`COMPUTED`, `EFFECT`,
 
 Doubly-linked on both axes means `O(1)` unlink during the cursor-based reconciliation that happens at the end of every computed/effect re-run.
 
+</details>
+
 ---
 
 ## How a write propagates
 
+<details>
+<summary>The set → mark → flush sequence, and why computeds stay pull-based.</summary>
+
 ```mermaid
 sequenceDiagram
   participant U as User code
@@ -197,6 +210,8 @@ The flush phase uses **two queue buffers** (`effectQueueA` / `effectQueueB`) alt
 
 Computeds are **pull-based** — they're not in the effect queue. Reading a computed walks its dep list, recursively pulls upstream computeds, and only re-runs if any dep's version is greater than its own `evalVersion`. The version comparison uses 32-bit modular arithmetic: `((dep.version - evalVer) | 0) > 0`. This is the trick that makes the engine immune to integer overflow during long-running sessions.
 
+</details>
+
 ---
 
 ## API reference
@@ -315,11 +330,13 @@ forEachObserver(sum, d => console.log(d.kind, d.value));  // subscribers of `sum
 forEachSource(sum,   d => console.log(d.kind, d.value));  // dependencies of `sum`
 ```
 
-Four functions (top-level + per-registry), added in 1.1.4, for auto-pausing wrappers and graph inspection:
+Six functions (top-level + per-registry) — four in 1.1.4, two more in 1.1.5 — 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 `{ kind, value }` descriptor (`kind` ∈ `"signal" | "computed" | "effect"`). No-op 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.
 
 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**.
 
@@ -373,6 +390,9 @@ r.destroy();                     // reset all pools, invalidate generations
 
 ## Capacity, growth, and the link ceiling
 
+<details>
+<summary>Pool sizing, the grow policy, and why there is a 16× link ceiling.</summary>
+
 The engine has two pool sizes: **nodes** and **links**. Both are fixed at registry creation but can be configured to grow.
 
 ```mermaid
@@ -397,6 +417,8 @@ Default sizing for a Twitch-extension-style budget:
 
 `stats()` reports `signals`, `computeds`, `effects`, `activeLinks`, `pooledLinks`, `linkPoolCapacity`. Drop it on screen for live observability.
 
+</details>
+
 ---
 
 ## Watchers
@@ -532,6 +554,9 @@ All three primitives live in a separate module (`Watch.js`) and are re-exported
 
 ## Edge cases pinned down
 
+<details>
+<summary>Diamonds, self-feedback, NaN/±0, throwing bodies, 32-bit version wrap, deep-chain limits.</summary>
+
 These are the questions you'd ask in a code review, with the answers:
 
 - **Diamond dependency.** Glitch-free. The mark phase walks the graph once; computeds are pulled lazily on read, so each one re-runs at most once per propagation regardless of how many paths reach it.
@@ -545,25 +570,27 @@ These are the questions you'd ask in a code review, with the answers:
 - **Deep chain depth.** Computed resolution is recursive in the JS call stack. Chains beyond ~10,000 deep risk `RangeError: Maximum call stack size exceeded`. Effects use an iterative mark phase, so signal → effect fan-out has no depth limit other than memory.
 - **`destroy()` after dispose.** `destroy()` bumps every node's generation, so any in-flight scheduled trampolines from before destruction are silently dropped. Closures returned to user code from disposed effects guard with `if (node.flags === 0) return;` — calling `dispose()` again is a no-op.
 
+</details>
+
 ---
 
 ## Benchmarks
 
-Honest numbers, against the same workload, with anti-DCE sinks and verified effect execution. All measurements: Node 22, **2016-era Intel MacBook Pro (4 cores, ~10 yr old hardware)**, 20K iterations × 5 inner runs × 10 outer invocations (median reported). Newer/faster machines shift all libs up proportionally; the relative ordering between libs is what matters. Numbers below are lite-signal **@1.1.4** vs alien-signals on the same loop; the full five-framework comparison (incl. preact, vue-reactivity, solid across 34 reactive-suite tests) is in [`resultsReactive.txt`](./resultsReactive.txt).
+Honest numbers, against the same workload, with anti-DCE sinks and verified effect execution. All measurements: Node 22, **2016-era Intel MacBook Pro (4 cores, ~10 yr old hardware)**, 20K iterations × 5 inner runs × 11 outer invocations (median reported). Newer/faster machines shift all libs up proportionally; the relative ordering between libs is what matters. Numbers below are lite-signal **@1.1.5** vs alien-signals on the same loop; the full five-framework comparison (incl. preact, vue-reactivity, solid across 34 reactive-suite tests) is in [`resultsReactive.txt`](./resultsReactive.txt). *(Both halves are now @1.1.5 — this throughput table median-of-11, the cross-framework reactivity suite median-of-12 in [`resultsReactive.txt`](./resultsReactive.txt). 1.1.5 is additive over 1.1.4 (node-identity only), so the engine numbers are perf-neutral vs 1.1.4.)*
 
 | Scenario   | What it stresses                | lite-signal | alien-signals | lite vs alien |
 | ---------- | -------------------------------- | ----------- | ------------- | ------------- |
-| **MUX**    | 256 signals → 1 sum → 1 effect (fan-in) | **314K ops/s** | 194K       | **+62%**      |
-| **BROADCAST** | 1 signal → 1000 effects (fan-out)    | **26K**     | 22K           | **+22%**      |
-| **KAIROS**    | 1 signal → 1000 computeds → 1 effect | **14K**     | 12K           | **+12%**      |
-| **DEEP CHAIN** | 256-deep computed chain → 1 effect  | 53K         | **60K**       | −11%          |
-| **WIDE DENSE** | 5 layers × ~200 wide, dense fan-in  | **7K**      | 6K            | **+6%** ⬆     |
-| **Δheap MUX**  | transient alloc pressure, 20K iters | **0.3 KB**  | 3,907 KB      | —             |
+| **MUX**    | 256 signals → 1 sum → 1 effect (fan-in) | **314K ops/s** | 198K       | **+59%**      |
+| **BROADCAST** | 1 signal → 1000 effects (fan-out)    | **27K**     | 22K           | **+20%**      |
+| **KAIROS**    | 1 signal → 1000 computeds → 1 effect | **15K**     | 13K           | **+19%**      |
+| **DEEP CHAIN** | 256-deep computed chain → 1 effect  | 53K         | **60K**       | −12%          |
+| **WIDE DENSE** | 5 layers × ~200 wide, dense fan-in  | **7K**      | 7K            | **+6%** ⬆     |
+| **Δheap MUX**  | transient alloc pressure, 20K iters | **0.3 KB**  | 6,120 KB      | —             |
 | **Retained MUX** | state surviving forced GC         | **−7 KB** (none) | −1 KB    | —             |
 
-**Reading the table:** `lite-signal` wins **MUX** (fan-in aggregation) by **+62%**, **BROADCAST** (fan-out) by **+22%**, and **KAIROS** (one source feeding a wide layer of memos) by **+12%** — the patterns that dominate real UI workloads: dashboards, scoreboards, HUDs, leaderboards, and any view that aggregates many inputs into a single computed slice. The **WIDE DENSE** row (⬆) is the headline of 1.1.4: at 1.1.2 lite-signal *lost* this dense, high-fan-in shape by −16%; the 1.1.4 retracking rewrite flips it to **+6%**. `alien-signals` now retains only a **−11% lead on DEEP CHAIN** (256-deep computed pipelines), where a flatter internal representation pays off when the propagation path is long rather than wide.
+**Reading the table:** `lite-signal` wins **MUX** (fan-in aggregation) by **+59%**, **BROADCAST** (fan-out) by **+20%**, and **KAIROS** (one source feeding a wide layer of memos) by **+19%** — the patterns that dominate real UI workloads: dashboards, scoreboards, HUDs, leaderboards, and any view that aggregates many inputs into a single computed slice. The **WIDE DENSE** row (⬆) is the headline of 1.1.4: at 1.1.2 lite-signal *lost* this dense, high-fan-in shape by −16%; the 1.1.4 retracking rewrite flips it to **+6%**. `alien-signals` now retains only a **−12% lead on DEEP CHAIN** (256-deep computed pipelines), where a flatter internal representation pays off when the propagation path is long rather than wide.
 
-On allocation pressure, `lite-signal` is alone in the zero-Δheap band: ~0.3 KB of transient garbage on stable shapes across 20,000 iterations. The contrast is starkest on SMALL SELECTIVE — lite-signal 0.3 KB vs alien-signals **29 MB** in the same loop. preact runs ~230 KB per loop, solid runs into single-digit megabytes, and alien-signals — which earlier shared the zero-GC band with lite-signal — now allocates 0.9-3.9 MB per stable scenario in current published versions. Negative "retained" numbers mean V8 reclaimed memory below the pre-bench baseline during the post-run forced GC — no leaks anywhere.
+On allocation pressure, `lite-signal` is alone in the zero-Δheap band: ~0.3 KB of transient garbage on stable shapes across 20,000 iterations. The contrast is starkest on SMALL SELECTIVE — lite-signal 0.3 KB vs alien-signals **~15 MB** in the same loop. preact ranges from ~220 KB to low-single-digit MB per loop, solid runs into single-digit megabytes, and alien-signals — which earlier shared the zero-GC band with lite-signal — allocates from near-zero (BROADCAST) up to ~6 MB (MUX) per stable scenario in this run. Negative "retained" numbers mean V8 reclaimed memory below the pre-bench baseline during the post-run forced GC — no leaks anywhere.
 
 > Note on the +70.8 KB retained that lite-signal shows on KAIROS specifically: that's the pre-allocated pool sitting in memory holding the live graph (1002 nodes + ~2000 links). The pool *is* the working memory — see the [Case for object pooling](#case-for-object-pooling) section. On the other benches the graph is small enough that the same pool floats below baseline after GC.
 
@@ -590,19 +617,23 @@ Three tiers, all reproducible.
 
 `npm test` runs the suite in `test/`, covering:
 
-- **`01-core.test.mjs`** — signal/computed/effect basics, equality semantics, NaN/±0, subscribe/peek/update, untrack, batch, cleanup ordering, first-run error recovery, nested object reference-identity gotchas.
-- **`02-topology.test.mjs`** — diamond glitch-freedom, 256-deep and 1024-deep computed chains, wide fan-out (1000 effects from one signal), dynamic dependency switching, conditional fan-out, nested effects, cycle detection (`CycleError`).
-- **`03-pool.test.mjs`** — `CapacityError` under both `"throw"` and `"grow"` policies, the 16× link ceiling, stable pool reuse across thousands of create/dispose cycles, registry isolation.
-- **`05-scheduler.test.mjs`** — scheduler-deferred effects, dispose-during-schedule races, microtask integration, 32-bit version wrap (simulated), `setDefaultRegistry`, `onCleanup` inside computeds.
-- **`06-nested-objects.test.mjs`** — array mutation patterns (push/splice/spread), deep nested paths, Map/Set/Date inside signals, custom structural equality, computed memoisation cutoffs over object slices, signal-of-signals composition, high-frequency object updates, batched immutable updates.
-- **`07-dispose.test.mjs`** — unified `dispose(api)` across signals, computeds and effect handles, idempotency, cross-registry isolation (per-registry Symbol prevents pool corruption), foreign-value safety, top-level helper routing, 500-cycle balanced churn leaving pool and stats stable.
-- **`08-watch.test.mjs`** — Validates the user-land observer utilities (watch, when, whenAsync). Covers lifecycle teardown, old/new value tracking, and Promise-based asynchronous state resolution.
-- **`09-conformance.test.mjs`** — Industry-standard conformance tests. Validates the engine against extreme edge cases from the johnsoncodehk reactive test suite, ensuring strict zero-GC invariants, correct cleanup isolation, and re-entrant stability.
-- **`10-is-tracking.test.mjs`** — The `isTracking()` observer-context predicate. 11 tests across 5 describe blocks: true inside effect/computed bodies; false inside `untrack`, `subscribe` callbacks, `onCleanup` bodies, and `watch` callbacks (the untracked-window cases that catch an observer-only misimplementation); false outside any observer including at the call site of an unobserved computed read; state-restoration after a thrown body; per-registry isolation; top-level binding.
-- **`11-adopted-reactive.test.mjs`** — 24 engine-agnostic edge cases adopted from across the ecosystem: alien-signals' parent-child link-integrity regression (#226–228), equality-predicate corners (preact/solid/vue), `signal.update(fn)` functional setter (vue/solid), `peek()` non-subscription depth (preact/vue), and the `subscribe` behavioral contract (preact/mobx).
-- **`12-coverage.test.mjs`** — 18 targeted exercises for public surface and hot-path branches the behavioral suites don't incidentally hit: top-level routing to the default registry, the computed clean-read short-circuit (`markEpoch` O(1) skip), dependency-set shrink severing the stale tail, error/structural edge paths, and scheduler ABA across a recycled pool slot. The owner-tree block is capability-gated (runs on 1.2.0+, skipped on 1.1.x).
-- **`13-introspection.test.mjs`** — The observer-lifecycle surface (1.1.4). 10 tests across 3 describe blocks: `hasObservers` (live observation reflects; a peek doesn't count), `observeObservers` auto-pause lifecycle (start-on-first / stop-on-last, no extra connect for a 2nd observer, re-observe fires again, no churn on re-track, conditional reads toggle honestly, transition-only registration, works for computeds), and `forEachObserver`/`forEachSource` enumeration (both directions; descriptor carries kind + value).
-- **`14-lifecycle-teardown.test.mjs`** — Effect-teardown guards (1.1.4 fix). A stopped effect must not re-subscribe to a signal read later in the same run; self-dispose must leave no orphaned link; a throwing effect setup must leave no live subscription; normal and dynamic re-tracking stay unaffected.
+- **`01-core_test.mjs`** — signal/computed/effect basics, equality semantics, NaN/±0, subscribe/peek/update, untrack, batch, cleanup ordering, first-run error recovery, nested object reference-identity gotchas.
+- **`02-topology_test.mjs`** — diamond glitch-freedom, 256-deep and 1024-deep computed chains, wide fan-out (1000 effects from one signal), dynamic dependency switching, conditional fan-out, nested effects, cycle detection (`CycleError`).
+- **`03-pool_test.mjs`** — `CapacityError` under both `"throw"` and `"grow"` policies, the 16× link ceiling, stable pool reuse across thousands of create/dispose cycles, registry isolation.
+- **`05-scheduler_test.mjs`** — scheduler-deferred effects, dispose-during-schedule races, microtask integration, 32-bit version wrap (simulated), `setDefaultRegistry`, `onCleanup` inside computeds.
+- **`06-nested-objects_test.mjs`** — array mutation patterns (push/splice/spread), deep nested paths, Map/Set/Date inside signals, custom structural equality, computed memoisation cutoffs over object slices, signal-of-signals composition, high-frequency object updates, batched immutable updates.
+- **`07-dispose_test.mjs`** — unified `dispose(api)` across signals, computeds and effect handles, idempotency, cross-registry isolation (per-registry Symbol prevents pool corruption), foreign-value safety, top-level helper routing, 500-cycle balanced churn leaving pool and stats stable.
+- **`08-watch_test.mjs`** — Validates the user-land observer utilities (watch, when, whenAsync). Covers lifecycle teardown, old/new value tracking, and Promise-based asynchronous state resolution.
+- **`09-conformance_test.mjs`** — Industry-standard conformance tests. Validates the engine against extreme edge cases from the johnsoncodehk reactive test suite, ensuring strict zero-GC invariants, correct cleanup isolation, and re-entrant stability.
+- **`10-is-tracking_test.mjs`** — The `isTracking()` observer-context predicate. 11 tests across 5 describe blocks: true inside effect/computed bodies; false inside `untrack`, `subscribe` callbacks, `onCleanup` bodies, and `watch` callbacks (the untracked-window cases that catch an observer-only misimplementation); false outside any observer including at the call site of an unobserved computed read; state-restoration after a thrown body; per-registry isolation; top-level binding.
+- **`11-adopted-reactive_test.mjs`** — 24 engine-agnostic edge cases adopted from across the ecosystem: alien-signals' parent-child link-integrity regression (#226–228), equality-predicate corners (preact/solid/vue), `signal.update(fn)` functional setter (vue/solid), `peek()` non-subscription depth (preact/vue), and the `subscribe` behavioral contract (preact/mobx).
+- **`12-coverage_test.mjs`** — 18 targeted exercises for public surface and hot-path branches the behavioral suites don't incidentally hit: top-level routing to the default registry, the computed clean-read short-circuit (`markEpoch` O(1) skip), dependency-set shrink severing the stale tail, error/structural edge paths, and scheduler ABA across a recycled pool slot. The owner-tree block is capability-gated (runs on 1.2.0+, skipped on 1.1.x).
+- **`13-introspection_test.mjs`** — The observer-lifecycle surface (1.1.4). 10 tests across 3 describe blocks: `hasObservers` (live observation reflects; a peek doesn't count), `observeObservers` auto-pause lifecycle (start-on-first / stop-on-last, no extra connect for a 2nd observer, re-observe fires again, no churn on re-track, conditional reads toggle honestly, transition-only registration, works for computeds), and `forEachObserver`/`forEachSource` enumeration (both directions; descriptor carries kind + value).
+- **`14-lifecycle-teardown_test.mjs`** — Effect-teardown guards against the alien-signals@3.2.1 regressions (4 tests). A stopped effect must not re-subscribe to a signal read later in the same run; self-dispose must leave no orphaned link (clean `activeLinks`); a throwing setup must leave no live subscription; normal and dynamic re-tracking stay unaffected by the `allocateLink` eligibility gate.
+- **`15-owner-lazy-alloc_test.mjs`** — Owner-adoption contract for the 1.2.0 owner tree (4 tests, capability-gated — skipped on 1.1.x). A signal allocated lazily *inside* a computed/effect must **not** be owner-adopted (it survives the owner's re-run — the lite-store/lite-form lazy-field shape) and sibling lazy signals must not cross-wire, while observers *are* still auto-disposed. Runs on 1.2.0+.
+- **`16-alien-parity_test.mjs`** — Differential regression guards (3 tests) reproducing the *properties* behind alien-signals@3.2.0 fixed bugs: reads inside a cleanup create no spurious dependencies (the dispose-cleanup fix); an inner-effect write does not block later propagation through a computed chain (#112); a dynamic dependency-set change stays correct under dirty-check (#109/#110).
+- **`17-reactivity_test.mjs`** — Behavioral suite (≈30 tests across 11 groups) mirroring universal signal-system bug classes: subscription lifecycle, cleanup ordering, stale-dependency tracking, batching/timing (incl. set-then-revert), equality cutoff (NaN/±0/custom), nested invalidation + glitch-free diamond, memory/retained nodes, the synchronous async-boundary, scheduler & loops (self-write termination, self-reading computed), and differential-review additions (cached computed errors, mid-batch pull, self-disposing getter, pooled-slot return). SSR hydration is a documented N/A — lite has no DOM layer.
+- **`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).
 
 ```bash
 npm test
@@ -610,7 +641,7 @@ npm test
 
 ### Tier 2 — Memory (allocation-free verification)
 
-`npm run test:gc` runs `test/04-zero-gc.test.mjs` with `--expose-gc`:
+`npm run test:gc` runs `test/04-zero-gc_test.mjs` with `--expose-gc`:
 
 - 100,000 `set()` calls on a graph with effects retain **< 200 KB** of heap.
 - 1,000 create/dispose cycles retain **< 50 KB**.
@@ -641,6 +672,9 @@ npm run verify   # test + test:gc + a sanity bench
 
 ## Performance Trade-offs & Topology Scaling
 
+<details>
+<summary>Stable vs dynamic topologies; Andrii Volynets' matrix, the 1.1.4 result, and the roadmap.</summary>
+
 `lite-signal` was built with a strict mandate: **absolute zero garbage collection**. By packing the dependency graph into a flat, pre-allocated memory arena, we eliminate the Scavenger GC pauses that plague 120fps Canvas/WebGL loops.
 
 Through **v1.1.2**, that came with a mathematical trade-off: while memory allocation is $O(1)$, the cursor-based retracking degraded to $O(N)$ linear scans under chaotic, high-fan-in, batched read-after-write — the shape of large DOM-style apps with heavy branch switching. **v1.1.4 closed that gap.** A version-stamped $O(1)$ reconciliation plus a `markEpoch` clean-read short-circuit on the pull replaced the cursor degradation; stable read order is unchanged (still $O(1)$, still zero-alloc).
@@ -658,16 +692,18 @@ In stable environments (game engines, particle systems, visualizers), `lite-sign
 | **1000x5 (25 sources, wide/dense)** | 304ms | 303ms | 1746ms |
 | **64x6 (selective dynamic DAG)** | 181ms | 196ms | 559ms |
 
-*1.1.4 on the local harness (slow 2016 MacBook — compare within-column, lite vs alien; the approximating scenarios from `bench/benchmark.mjs`):*
-| Scenario | alien-signals | lite-signal (1.1.4) | result |
+*1.1.5 on the local harness (slow 2016 MacBook — compare within-column, lite vs alien; the approximating scenarios from `bench/benchmark.mjs`):*
+| Scenario | alien-signals | lite-signal (1.1.5) | result |
 | :--- | :--- | :--- | :--- |
-| **LARGE WEB APP** (≈ 1000x12) | 3026ms | 2736ms | **lite +11%** |
-| **WIDE DENSE** (≈ 1000x5) | 2960ms | 2802ms | **lite +6%** |
-| **SMALL SELECTIVE** (≈ 64x6) | 2985ms | 1868ms | **lite +60%** |
+| **LARGE WEB APP** (≈ 1000x12) | 2846ms | 2686ms | **lite +6%** |
+| **WIDE DENSE** (≈ 1000x5) | 2826ms | 2671ms | **lite +6%** |
+| **SMALL SELECTIVE** (≈ 64x6) | 2000ms | 1857ms | **lite +8%** |
 
-The cross-framework reactivity suite agrees independently: `dyn: large web app` and `dyn: wide dense` are now wins there too, and lite-signal is the fastest of five frameworks on both (see [`resultsReactive.txt`](./resultsReactive.txt)). The new retracking is verified correct by `retracking.difftest.mjs` — 20,000 direct + 10,000 batched writes, 0 disagreements. *(A fresh run of Andrii's exact matrix on 1.1.4 is the definitive external confirmation and is pending; the two local suites above are the current evidence.)*
+> **Honest note (1.1.5 run):** alien-signals is much faster on these three shapes than in the 1.1.4 run above (SMALL SELECTIVE 2985ms → 2000ms, LARGE WEB APP 3026ms → 2846ms) — a newer alien build and/or host conditions — so lite-signal's margins narrowed from +60%/+11%/+6% to **+8%/+6%/+6%**. Within this run lite still leads all three and remains the only zero-Δheap library (see [`results.txt`](./results.txt)).
 
-**The Takeaway:** as of 1.1.4 you no longer have to choose. `lite-signal` keeps the zero-GC, flat-arena profile for 120fps Canvas/WebGL **and** holds parity-or-ahead of alien-signals on dynamic, high-fan-in web-app topologies. The one shape where alien's flatter representation still leads is the 256-deep computed pipeline (DEEP CHAIN, −11%).
+The cross-framework reactivity suite agrees independently and was re-run on **1.1.5** (median-of-12): `dyn: large web app` **555ms** (+6% vs alien-signals' 590ms) and `dyn: wide dense` **870ms** (+7% vs 933ms) are wins there too — lite-signal is the fastest of five frameworks on both, with preact and vue ~7–30× slower (see [`resultsReactive.txt`](./resultsReactive.txt)). The retracking is verified correct by `retracking.difftest.mjs` — 20,000 direct + 10,000 batched writes, 0 disagreements. *(A fresh run of Andrii's exact matrix on 1.1.5 is the definitive external confirmation and is pending; the two local suites above are the current evidence.)*
+
+**The Takeaway:** as of 1.1.4 you no longer have to choose. `lite-signal` keeps the zero-GC, flat-arena profile for 120fps Canvas/WebGL **and** holds parity-or-ahead of alien-signals on dynamic, high-fan-in web-app topologies. The one shape where alien's flatter representation still leads is the 256-deep computed pipeline (DEEP CHAIN, −12%).
 
 ### Roadmap
 - **1.1.5** — additions in service of `lite-devtools` (node identity/traversability on the introspection walkers, for full auto-discovered graph rendering).
@@ -676,6 +712,8 @@ The cross-framework reactivity suite agrees independently: `dyn: large web app`
 
 > Note: the retracking rewrite that closes the dynamic-topology gap shipped in **1.1.4**, not a future release. The earlier roadmap that listed it under "v1.2" is superseded.
 
+</details>
+
 ---
 
 ## What this is not
@@ -712,6 +750,9 @@ A growing family of zero-GC, ESM-only, sub-2KB packages built on `lite-signal`.
 
 ## Browser and runtime support
 
+<details>
+<summary>Support matrix (Chrome / Firefox / Safari / Node / Bun / Deno / Workers).</summary>
+
 Pure ES2020 + `Object.is` + `Int32 | 0`. Runs anywhere that runs modern JavaScript.
 
 | Target                            | Supported |
@@ -727,10 +768,15 @@ Pure ES2020 + `Object.is` + `Int32 | 0`. Runs anywhere that runs modern JavaScri
 
 ESM-only. No CommonJS build — modern bundlers handle this; legacy consumers can use a wrapper.
 
+</details>
+
 ---
 
 ## Integration recipes
 
+<details>
+<summary>Game HUD (rAF), Twitch config sync, per-tenant sandboxing.</summary>
+
 ### Reactive game HUD with requestAnimationFrame
 
 ```js
@@ -791,10 +837,15 @@ function spawnPlugin(pluginCode) {
 }
 ```
 
+</details>
+
 ---
 
 ## Conformance
 
+<details>
+<summary>174/177 on the reactive-framework-test-suite; what lite-signal does and doesn't, by intent.</summary>
+
 lite-signal is evaluated against the
 [reactive-framework-test-suite](https://github.com/johnsoncodehk/reactive-framework-test-suite),
 the most comprehensive behavioral test battery for JavaScript reactive
@@ -860,10 +911,15 @@ The remaining open items, by intent.
 Per-test results, the runner adapter, and reproductions live in
 `/conformance/`.
 
+</details>
+
 ---
 
 ## FAQ
 
+<details>
+<summary>Microtasks, dual capacities, Object.is, destroy(), framework integration, dep-order stability.</summary>
+
 **Why no microtask scheduler?**
 Microtask schedulers solve a real problem (deduplicating multiple `set()`s into one effect run) but introduce a worse one: causal opacity. When `signal.set(x)` returns, you don't know whether your effect has run yet. `lite-signal` chooses synchronous flush + explicit `batch()` for the same deduplication outcome with predictable timing.
 
@@ -888,6 +944,8 @@ The cleanup runs *before* the next computeFn body, so the set's notification arr
 **Is the dep order stable across re-runs?**
 Yes, if your computeFn reads its deps in the same order each invocation. The `currentDep` cursor walks the existing dep list and tries to match; matches reuse the existing link (zero alloc), mismatches insert/remove. Stable order = stable performance.
 
+</details>
+
 ---
 
 ## npm scripts

package/Signal.d.ts

@@ -99,6 +99,9 @@ export type NodeKind = "signal" | "computed" | "effect";
 
 /** Non-perturbing snapshot of a graph neighbour yielded by the `forEach*` walkers. */
 export interface NodeDescriptor {
+    /** Stable per-allocation node id (1.1.5+). Dedupe key for graph traversal, and the
+     *  re-walk handle: a descriptor may be passed back into forEachObserver/forEachSource. */
+    id: number;
     kind: NodeKind;
     /** The node's current value (last stored/computed value; an effect's is its body return). */
     value: unknown;
@@ -174,6 +177,11 @@ 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. */
+    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. */
+    describe(handle: ReactiveHandle): NodeDescriptor | undefined;
     onCleanup(fn: () => void): void;
     stats(): RegistryStats;
     /** Reset everything: nodes, links, queues, global clock. Outstanding dispose
@@ -214,6 +222,10 @@ 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.nodeId}. */
+export function nodeId(handle: ReactiveHandle): number | undefined;
+/** Top-level binding of {@link Registry.describe}. */
+export function describe(handle: ReactiveHandle): NodeDescriptor | undefined;
 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.1.4
+ * @zakkster/lite-signal v1.1.5
  * --------------------
  * Zero-GC reactive graph.
  *
@@ -85,6 +85,8 @@ class ReactiveNode {
         this.markEpoch = 0;
         /** Recycle generation: bumped on dispose, used to invalidate stale scheduler closures. */
         this.gen = 0;
+        /** Stable per-allocation id for introspection/devtools (1.1.5). Reassigned on each allocate-from-pool. */
+        this.id = 0;
 
         /** Captured value at first .set() inside the current batch (revert detection). */
         this.preBatchValue = undefined;
@@ -194,6 +196,7 @@ export function createRegistry(config = {}) {
     for (let i = 0; i < currentLinkCapacity - 1; i++) linkPool[i].nextFree = linkPool[i + 1];
 
     let activeNodes = 0 | 0;
+    let nodeSeq = 1 | 0;            // monotonic node-id source for introspection (1.1.5+); wraps modular | 0
     let activeLinks = 0 | 0;
     let statSignals = 0 | 0;
     let statComputeds = 0 | 0;
@@ -239,7 +242,6 @@ export function createRegistry(config = {}) {
         const po = currentObserver, pt = isTrackingDeps;
         currentObserver = null;
         isTrackingDeps = false;
-
         try {
             e.onConnect();
         } finally {
@@ -256,7 +258,6 @@ export function createRegistry(config = {}) {
         const po = currentObserver, pt = isTrackingDeps;
         currentObserver = null;
         isTrackingDeps = false;
-
         try {
             e.onDisconnect();
         } finally {
@@ -281,12 +282,13 @@ export function createRegistry(config = {}) {
      * @private
      */
     function allocateLink(source, target) {
-        // Eligibility gate (lite's analogue of alien-signals' shouldTrack): if the observer was
-        // disposed mid-run — self-dispose, or an outer observer torn down while suspended — its
-        // flags are cleared to 0. Linking would splice a dead, pool-bound node back into `source`'s
-        // subscriber list: a phantom edge that mis-targets the instant the slot is recycled. Skip it.
-        // Cold path only (the inline cursor-hit fast path never reaches here) -> steady-state reads
-        // pay nothing. Legit tracking always passes a live observer (flags != 0).
+        // Eligibility gate (lite's analogue of alien-signals' shouldTrack): if the observer
+        // was disposed mid-run — self-dispose, or an outer observer torn down while suspended —
+        // its flags are cleared to 0. Linking would splice a dead, pool-bound node back into
+        // `source`'s subscriber list: a phantom edge that dangles into the pool and mis-targets
+        // the instant that slot is recycled (the next allocation). Skip it. This sits on the COLD
+        // path only — the inline cursor-hit fast path never reaches allocateLink — so steady-state
+        // tracked reads pay nothing. Legit tracking always passes a live observer (flags != 0).
         if (target.flags === 0) return null;
         let expected = activeObserverCurrentDep;
         // Dead on this build: the inline cursor fast-path inside every read
@@ -513,6 +515,8 @@ export function createRegistry(config = {}) {
         node.revertEpoch = 0;
         node.preBatchValue = undefined;
         node.preBatchVersion = 0;
+        node.id = nodeSeq;
+        nodeSeq = (nodeSeq + 1) | 0;   // fresh identity per allocation (1.1.5)
         return node;
     }
 
@@ -1306,7 +1310,22 @@ export function createRegistry(config = {}) {
     function describeNode(node) {
         const fl = node.flags;
         const kind = (fl & FLAG_EFFECT) !== 0 ? "effect" : (fl & FLAG_COMPUTED) !== 0 ? "computed" : "signal";
-        return {kind, value: node.value};
+        const d = {id: node.id, kind, value: node.value};
+        // Carry the node so the descriptor can be passed BACK into forEachObserver/forEachSource —
+        // this is what lets lite-devtools BFS the full graph. Non-enumerable so {id,kind,value}
+        // stays the visible shape (clean logs / JSON).
+        Object.defineProperty(d, NODE_PTR, {value: node, enumerable: false});
+        return d;
+    }
+
+    function nodeId(handle) {
+        const node = handle != null ? handle[NODE_PTR] : undefined;
+        return node !== undefined ? node.id : undefined;
+    }
+
+    function describe(handle) {
+        const node = handle != null ? handle[NODE_PTR] : undefined;
+        return node !== undefined ? describeNode(node) : undefined;
     }
 
     function forEachObserver(handle, fn) {
@@ -1345,7 +1364,9 @@ export function createRegistry(config = {}) {
         hasObservers,
         observeObservers,
         forEachObserver,
-        forEachSource
+        forEachSource,
+        nodeId,
+        describe
     };
 }
 
@@ -1419,6 +1440,14 @@ export function forEachSource(handle, fn) {
     return defaultRegistry.forEachSource(handle, fn);
 }
 
+export function nodeId(handle) {
+    return defaultRegistry.nodeId(handle);
+}
+
+export function describe(handle) {
+    return defaultRegistry.describe(handle);
+}
+
 /** @type {Registry["onCleanup"]} */
 export function onCleanup(fn) {
     return defaultRegistry.onCleanup(fn);

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`.
+- **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.
 - **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,15 @@ triggering write — no `queueMicrotask`, no promises, no scheduler ticks.
 
 ## Version notes
 
-- **1.1.4** (current): combined release — a retracking rewrite plus an observer-lifecycle
+- **1.1.5** (current): additive release in service of `@zakkster/lite-devtools` — stable
+  node identity on the introspection surface. `nodeId(handle)` -> the node's stable
+  per-allocation id (the dedupe key for graph walks); `describe(handle)` -> the handle's
+  own `{ id, kind, value }` descriptor, **re-walkable** (pass it back into
+  `forEachObserver`/`forEachSource` to walk the full DAG); `forEach*` descriptors now carry
+  `id`. One SMI write at allocation, node shape kept monomorphic — **zero steady-state
+  cost**. Drop-in over 1.1.4, no breaking changes. New `test/18-identity_test.mjs` (5 tests); plus `14-lifecycle-teardown`, `16-alien-parity`, and the `17-reactivity` behavioral suite.
+
+- **1.1.4**: combined release — a retracking rewrite plus an observer-lifecycle
   introspection surface. Drop-in over 1.1.3. **Retracking:** version-stamped O(1)
   reconciliation + a `markEpoch` clean-read short-circuit replace the cursor strategy's
   O(N)-per-dep degradation under chaotic high-fan-in batched read-after-write; stable read
@@ -111,6 +119,8 @@ 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 nodeId(handle: Signal<any> | Computed<any>): number | undefined;            // 1.1.5
+function describe(handle: Signal<any> | Computed<any>): NodeDescriptor | undefined;   // 1.1.5
 function onCleanup(fn: () => void): void;
 function stats(): RegistryStats;
 
@@ -134,7 +144,8 @@ interface Computed<T> {
 
 type Dispose = () => void;
 
-interface NodeDescriptor {           // yielded by forEachObserver / forEachSource
+interface NodeDescriptor {           // yielded by forEachObserver / forEachSource / describe
+  id: number;                        // stable per-allocation id (1.1.5); dedupe + re-walk key
   kind: "signal" | "computed" | "effect";
   value: unknown;                    // node's current value
 }
@@ -153,8 +164,8 @@ interface RegistryStats {
   activeLinks: number;
   pooledLinks: number;
   linkPoolCapacity: number;
-  nodePoolCapacity?: number;
-  activeNodes?: number;
+  nodePoolCapacity: number;
+  activeNodes: number;
 }
 
 class CapacityError extends Error {
@@ -235,9 +246,9 @@ path is long rather than wide.
 These four are the *stable* topologies (unchanged through 1.1.4). The chaotic,
 high-fan-in shapes that were lite-signal's documented weakness — `dyn: large web app`
 and `dyn: wide dense` in the cross-framework reactivity suite — were closed by the
-1.1.4 retracking rewrite and are now the fastest of five frameworks: 571ms / 912ms
-vs alien-signals' 623ms / 1001ms, with preact and vue 10–18× slower. See
-resultsReactive.txt for the full 34-test, 5-framework table.
+1.1.4 retracking rewrite and remain the fastest of five frameworks (re-confirmed on
+1.1.5, median-of-12): 555ms / 870ms vs alien-signals' 590ms / 933ms, with preact and
+vue ~7–30× slower. See resultsReactive.txt for the full 34-test, 5-framework table.
 
 On allocation pressure, lite-signal is alone in the zero-Δheap band: ~15 KB of
 transient garbage per 20,000-iteration loop, regardless of scenario. preact runs
@@ -287,20 +298,24 @@ sandbox.destroy();   // entire reactive world reset
 
 - `Signal.js`              — full implementation, single file.
 - `Signal.d.ts`          — TypeScript declarations for all public API.
-- `test/01-core.test.mjs`     — signal/computed/effect basics, equality, untrack.
-- `test/02-topology.test.mjs` — diamonds, chains, fan-out/in, cycle detection.
-- `test/03-pool.test.mjs`     — capacity errors, grow policy, pool reuse.
-- `test/04-zero-gc.test.mjs`  — heap retention (run with --expose-gc).
-- `test/05-scheduler.test.mjs` — scheduler races, dispose, gen counter, version wrap.
-- `test/06-nested-objects.test.mjs` — nested-object & reference-identity behaviours.
-- `test/07-dispose.test.mjs` — universal disposal: registry.dispose(api).
-- `test/08-watch.test.mjs` — new watch reactivity tests.
-- `test/09-conformance.test.mjs` — johnsoncodehk/reactive-framework-test-suite conformance fixes tests.
+- `test/01-core_test.mjs`     — signal/computed/effect basics, equality, untrack.
+- `test/02-topology_test.mjs` — diamonds, chains, fan-out/in, cycle detection.
+- `test/03-pool_test.mjs`     — capacity errors, grow policy, pool reuse.
+- `test/04-zero-gc_test.mjs`  — heap retention (run with --expose-gc).
+- `test/05-scheduler_test.mjs` — scheduler races, dispose, gen counter, version wrap.
+- `test/06-nested-objects_test.mjs` — nested-object & reference-identity behaviours.
+- `test/07-dispose_test.mjs` — universal disposal: registry.dispose(api).
+- `test/08-watch_test.mjs` — new watch reactivity tests.
+- `test/09-conformance_test.mjs` — johnsoncodehk/reactive-framework-test-suite conformance fixes tests.
 - `test/10-is-tracking_test.mjs` — `isTracking()` across observer bodies, untracked windows, and outside any observer.
 - `test/11-adopted-reactive_test.mjs` — engine-agnostic edge cases adopted from the wider ecosystem (alien-signals link-integrity #226–228, equality-predicate corners, `update()`/`peek()`/`subscribe` contracts).
 - `test/12-coverage_test.mjs` — targeted public-surface + hot-path branch coverage (top-level routing, clean-read short-circuit, tail severance, scheduler ABA); owner-tree block capability-gated.
 - `test/13-introspection_test.mjs` — observer-lifecycle surface: `hasObservers`, `observeObservers` auto-pause, `forEach*` enumeration (10 tests).
 - `test/14-lifecycle-teardown_test.mjs` — effect-teardown guards: stopped effect doesn't re-subscribe to a signal read later in the same run, self-dispose leaves no orphan link, throwing setup leaves no live subscription (4 tests).
+- `test/15-owner-lazy-alloc_test.mjs` — owner-adoption contract for the 1.2.0 owner tree (lazy signals never adopted; observers still auto-disposed); capability-gated, skipped on 1.1.x (4 tests).
+- `test/16-alien-parity_test.mjs` — differential guards vs alien-signals@3.2.0 fixed-bug classes: cleanup reads create no deps, inner write doesn't block computed-chain propagation, dynamic dep-set correct under dirty-check (3 tests).
+- `test/17-reactivity_test.mjs` — behavioral suite over universal signal-system bug classes (subscription lifecycle, cleanup ordering, stale-dep tracking, batching, equality, nested invalidation, memory, sync async-boundary, scheduler/loops, + differential-review additions); SSR is N/A (≈30 tests).
+- `test/18-identity_test.mjs` — node identity (1.1.5): `nodeId`/`describe`, descriptor `id`, re-walkable descriptors, non-perturbing (5 tests).
 - `bench/benchmark.mjs`       — anti-DCE throughput harness (ops/s; results.txt).
 - `bench/benchmarkReactive.mjs` — cross-framework reactivity suite vs alien-signals, preact, vue-reactivity, solid (resultsReactive.txt).
 - `demo/index.html`           — interactive visualization of the reactive graph.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-signal",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "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",