@zakkster/lite-signal 1.1.4 → 1.2.0

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.
 
@@ -32,7 +32,7 @@ triggering write — no `queueMicrotask`, no promises, no scheduler ticks.
 - **Cursor reconciliation**: at the start of each computed/effect run, `activeObserverCurrentDep` points at the head of the existing dep list. As the body reads deps, matching links advance the cursor (zero alloc); non-matching links insert before the cursor and the displaced tail is severed at the end of the run.
 - **Iterative mark phase**: `markDownstream` uses a pre-allocated `markStack` array for DFS — no recursion, no call stack growth on wide fan-out.
 - **Recursive computed pull**: `pullComputed` is call-stack recursive; deep chains beyond ~10,000 nodes will throw `RangeError`. Effects don't have this limit.
-- **Double-buffered effect queue**: `effectQueueA` / `effectQueueB` alternate each flush pass. An effect that writes during its own re-run gets re-queued into the alternate buffer.
+- **Double-buffered effect queue**: `effectQueueA` / `effectQueueB` alternate each flush pass — effects *scheduled by* the current pass (cross-effect cascades) drain in the next pass. A **self-write** (an effect writing a signal it reads) is the exception: `markDownstream`'s `FLAG_COMPUTING` guard does **not** re-queue the writing effect, so a self-cycle runs exactly once — while the write still propagates to the signal's other observers, and the effect stays responsive to later *external* writes (its `evalVersion` is bumped in the `executeEffect` finally). Mutual cross-effect write loops (A→B→A) are not self-cycles and trip `CycleError: flush passes exceeded` via `maxFlushPasses`.
 - **maxFlushPasses ceiling**: default 100. Exceeding this throws `CycleError`. Prevents runaway effect loops.
 - **32-bit modular versioning**: `globalVersion` and `node.version` are `(value + 1) | 0`, wrapping signed. Comparison via `((dep.version - evalVer) | 0) > 0` is wrap-safe and works in modular distance, not raw integer ordering. The engine never overflows.
 - **Generation counter**: each node has a `gen` field incremented on dispose and destroy. Scheduler trampolines capture the current gen and no-op if it changes — prevents stale callbacks from re-firing after dispose.
@@ -50,7 +50,47 @@ 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.2.0** (current): 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
+  re-runs or is disposed, the engine cascade-disposes those observers before
+  the new run. Plain signals are deliberately NOT owner-adopted so lazy-
+  allocation wrappers (lite-store keys, lite-form fields) continue to survive
+  re-runs of the computed that allocated them. **Pre-batch revert:** inside a
+  `batch(...)`, set X then set X back (under the signal's `equals`) reverts the
+  version bump — downstream effects/computeds do not fire. **AggregateError on
+  multi-throw:** two or more effects throwing in the same flush pass aggregate to
+  `AggregateError` at the trigger; single-throw is unchanged. **Scheduler thunk
+  caching:** the scheduler closure is cached on the node and gen-bound, so async
+  schedules that fire post-dispose against a recycled slot are guaranteed no-ops
+  (ABA safe). Internal split: `currentObserver` and `currentOwner` are now
+  distinct pointers (today they move together, no behavioural change). **Perf:**
+  shared `peek` (one closure per registry instead of per primitive) shaves
+  10–14% off signal/computed creation on the `S:create*` micros, no hot-path or
+  behavioural change. 363 tests, 100% line / 98.62% branch coverage on
+  `Signal.js` + `Watch.js`. Differential fuzz vs the published 1.1.5: 0
+  disagreements over 30,000 writes. New `test/19-v12-additions.test.mjs`
+  (24 tests) and `test/20-axis-stress.test.mjs` (23 tests — eight orthogonal
+  engine-invariant axes plus permanent conformance pins). **Conformance fixes
+  in 1.2.0**: #141 (dispose during execution then continue: no re-run), and
+  #238 / #241 / #243 (cleanup ordering on cascade: inner-before-outer,
+  deepest-first, and the inner-only-re-run regression). #141 was a latent
+  crash present in 1.1.5 too; the v1.2 owner tree exercised it more
+  aggressively. Fix is two-fold — nullify the tracking cursor in `disposeNode`
+  when the disposed node is the active observer (plus a `gen`-snapshot guard
+  in `executeEffect`/`pullComputed`); and swap `runCleanup` to cascade
+  children first, then own.
+
+- **1.1.5**: 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 +151,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 +176,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 +196,8 @@ interface RegistryStats {
   activeLinks: number;
   pooledLinks: number;
   linkPoolCapacity: number;
-  nodePoolCapacity?: number;
-  activeNodes?: number;
+  nodePoolCapacity: number;
+  activeNodes: number;
 }
 
 class CapacityError extends Error {
@@ -235,9 +278,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 +330,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.2.0",
   "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",
@@ -22,7 +22,8 @@
     "Watch.js",
     "README.md",
     "llms.txt",
-    "LICENSE.txt"
+    "LICENSE.txt",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "test": "node --test --test-reporter=spec",