@zakkster/lite-signal 1.1.5 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,415 @@
+# Changelog
+
+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.0] — 2026-06-11
+
+A structural refactor that internally splits the engine into three named layers
+(graph topology / ownership-lifecycle / propagation-execution) with a strict
+dependency direction, plus a small set of additive features built on top of
+that split. No behavioural changes for existing code — drop-in over 1.1.5.
+
+### Added — auto-disposal of nested observers (owner tree)
+- An effect or computed that creates **observers** (nested `effect`/`computed`)
+  now owns them via an internal owner tree. When the owner re-runs or is
+  disposed, all owned observers are cascade-disposed before the new run starts.
+  This is what closes the long-standing "nested effects leak on re-run" hazard
+  that other engines fix with `createRoot` wrappers.
+- **Plain signals are deliberately NOT owner-adopted.** Lazy-allocation
+  wrappers (`lite-store` allocates a key's signal on first read, `lite-form`
+  allocates lazy fields the same way) depend on a lazily-created signal
+  surviving its allocating computed's re-runs. The rule is:
+  *observers cascade with the owner; signals do not.* Locked in by 5 tests in
+  `test/15-owner-lazy-alloc.test.mjs` (the lite-store cross-wire shape) and
+  the new `test/19-v12-additions.test.mjs`.
+
+### Added — pre-batch revert (the "set X, set X back" optimisation)
+- Inside a `batch(...)`, if a signal is set and then set back to its
+  pre-batch value (under the signal's own `equals`), the version bump is
+  reverted and downstream effects/computeds do **not** fire. Eliminates a
+  whole class of "spurious re-run from a temporary mutation" patterns common
+  in form state and undo/redo. Verified end-to-end (signal, computed, effect)
+  in `test/19-v12-additions.test.mjs`.
+
+### Added — multi-effect throws aggregate to `AggregateError`
+- When two or more effects throw in the **same flush pass**, the engine
+  collects all errors and rethrows a native `AggregateError` at the
+  triggering `set()` / batch boundary. A single thrown error is rethrown
+  unwrapped (no change). Effects that don't throw still run. Cycle detection
+  unchanged — a flush exceeding `maxFlushPasses` (default 100) throws an
+  `Error` prefixed `"CycleError:"`.
+
+### Added — scheduler thunk caching with gen-bound ABA guard
+- `effect(fn, { scheduler })` now caches the scheduler thunk on the node
+  itself (`node.schedulerThunk`) so repeated re-schedules reuse the same
+  closure (no allocation per re-schedule). The thunk holds a generation snapshot
+  taken at effect creation: after `dispose()` the engine bumps the node's
+  generation, so a stale thunk fired by an async scheduler against a recycled
+  pool slot is a guaranteed no-op (ABA safe).
+
+### Changed — internal refactor, no behavioural difference
+- The engine is reorganised into three explicit layers with documented
+  invariants (see the file header in `Signal.js`):
+    - **L1 Graph topology** — `allocateLink` / `freeLink` / `severTail`. Pure
+      edge mechanics. Never touches `owner` / `firstOwned`.
+    - **L2 Ownership/lifecycle** — `createNode` / `disposeNode` / `runCleanup`.
+      Owns the owner tree and user cleanup. Never touches the tracking cursor.
+    - **L3 Propagation/execution** — `markDownstream` (cursor-free), and the
+      orchestrators `executeEffect` / `pullComputed` that drive the cursor
+      (L1) and call `runCleanup` (L2) before a re-run.
+- `currentObserver` and `currentOwner` are now distinct pointers. Today they
+  move together (no behavioural change), but the split paves the way for
+  future `runWithOwner`/`createRoot` without coupling tracking and lifecycle.
+- **Shared `peek` (perf).** `signal()` and `computed()` now reuse a single
+  `peek` function per registry instead of allocating a fresh closure per
+  primitive. Equivalent across registries (each registry has its own pair).
+  ~10–14% faster signal/computed creation on the `S:create*` micros, no
+  hot-path or behavioural change. Verified by 5 dedicated tests + the full
+  309-strong existing suite + 30,000-write differential retracking fuzz vs
+  the published 1.1.5.
+
+### Changed — port-forward of the 1.1.3/1.1.4 perf fixes
+- `pullComputed` retains the **`markEpoch` clean short-circuit** — re-reading
+  a computed after an unrelated source changed is O(1).
+- `allocateLink` retains the **O(1) `tailSub` dedup** — divergent re-tracking
+  remains O(N), not O(N²). The same documented edge note applies: a nested
+  re-read of the same source after an intervening observer can retain one
+  duplicate link per intervening edge, bounded by the loop count and
+  dispose-reclaimed.
+
+### Fixed — conformance regressions surfaced during release prep
+- **#141 (`dispose during execution then continue: no re-run`)**: an effect that
+  called its own dispose handle mid-run and then continued to read another
+  signal would corrupt the link-list bookkeeping in `severTail` (latent crash
+  present in 1.1.5 too — the v1.2 owner tree exercised the path more
+  aggressively and made it visible). Fixed by nulling the tracking cursor in
+  `disposeNode` when the disposed node is the active observer, plus a
+  gen-snapshot guard in `executeEffect` / `pullComputed` so a post-body
+  `severTail` on a recycled slot is skipped.
+- **#238 / #241 / #243 (cleanup ordering)**: nested effect cleanups must fire
+  inside-out on owner-tree disposal — grandchild before child before outer.
+  The previous `runCleanup` ran the node's OWN cleanup before cascading, which
+  surfaced on cascade-dispose, on owner re-run, AND on the regression path
+  where an inner-only re-run had fired first. Fixed by swapping the order:
+  cascade children first, then own. Matches React / Solid (children may rely
+  on parent state being live at cleanup time; never the reverse).
+- Permanent regression guards for all four landed in
+  `test/20-axis-stress.test.mjs` under "Conformance pins" (7 new tests across
+  two suites; includes a BONUS test for the re-run cascade path which has the
+  same invariant).
+
+### Test suite (released numbers)
+- 363 tests / 133 suites total, all passing under `node --expose-gc --test`.
+- **100% line coverage** and **98.62% branch coverage** on `Signal.js`
+  + `Watch.js` (the few uncovered branches are defensive guards: cycle
+  detection, batchEpoch wraparound after 2³² batches, and the self-dispose
+  `gen` branches added by the conformance fixes — unreachable from
+  conformance + existing user code).
+- New file `test/19-v12-additions.test.mjs` (24 tests) locks in shared peek,
+  owner adoption rule, pre-batch revert, AggregateError aggregation,
+  CycleError detection, the `maxLinks` config branch, the disposed-signal
+  read/set behaviour, and the stop-fn ABA guard.
+- New file `test/20-axis-stress.test.mjs` (23 tests) — eight orthogonal
+  engine-invariant "axes" plus the permanent conformance pins for #141,
+  #238, #241, #243.
+- Existing `test/15-owner-lazy-alloc.test.mjs` skips ("scheduler-thunk
+  caching lands in v1.2.0") are removed — the owner tree exists, the
+  tests pass.
+- Differential retracking fuzz against the published 1.1.5: 30,000 writes,
+  **0 disagreements** (`bench/retracking.difftest.mjs`).
+
+### Notes for users
+- **Drop-in.** No public surface removed. Behaviour identical to 1.1.5 except
+  for: (i) the owner-cascade auto-dispose of nested observers (was: leaked),
+  (ii) the pre-batch revert (was: always fired even if reverted), and
+  (iii) multi-throw aggregation. (i) and (ii) are silent wins; if you
+  previously caught the first thrown effect in a flush, you now get an
+  `AggregateError` whose `.errors[0]` is what you used to get.
+- The "scheduler-thunk caching" hint that referenced an older internal
+  staging name (Signal-1.3.0-rc) is gone; the file is the public 1.2.0.
+
+## [1.1.5] — 2026-06-04
+
+Additive release in service of `@zakkster/lite-devtools`: stable node identity on the
+introspection surface, so a tool can dedupe and traverse the full reactive DAG. Drop-in
+over 1.1.4, no breaking changes.
+
+### Added — node identity (top-level + per-registry)
+- `nodeId(handle)` -> the node's stable per-allocation id (`number`), or `undefined` for a
+  non-handle. The dedupe key for graph walks.
+- `describe(handle)` -> the handle's own `{ id, kind, value }` descriptor, or `undefined`
+  for a non-handle. **Re-walkable**: the descriptor may be passed back into
+  `forEachObserver`/`forEachSource` — the recursion primitive for full DAG discovery.
+- `forEachObserver`/`forEachSource` descriptors now carry `id` (`{ id, kind, value }`).
+- Every node gains a stable `id` assigned at allocation: one SMI write at creation, node
+  shape kept uniform (monomorphic). **Zero steady-state cost.**
+
+### Test suite
+- Added `test/15-identity_test.mjs`: 5 tests — ids unique + stable, `nodeId`/`describe`
+  undefined on non-handles, descriptor shape `{ id, kind, value }`, descriptors re-walkable,
+  identity walks non-perturbing.
+
+## [1.1.4] — 2026-05-31
+
+Combined release: a retracking rewrite that closes the two documented chaotic
+read-order limitations, plus an observer-lifecycle introspection surface. No
+breaking changes, no public-API removals — drop-in over 1.1.3. (This release
+folds in the work that was internally staged as 1.1.4 and 1.1.5; it ships as a
+single 1.1.4.)
+
+### Changed — performance (retracking, no semantic change)
+- **Version-stamped O(1) reconciliation + clean-read short-circuit.** The cursor
+  reconciliation now stamps each source per evaluation and a `markEpoch` guard
+  short-circuits the pull when a subtree is already clean. This replaces the
+  prior strategy's O(N)-per-dep degradation under chaotic, high-fan-in, batched
+  read-after-write (every read re-validating its dependency subtree). Stable
+  read order is unchanged — still O(1) per dep via cursor reuse, still zero-alloc.
+- **Result.** The two rows that were the documented v1.1.x limitation flipped from
+  multiples-behind to ahead of `alien-signals`, and are now the fastest of the five
+  benchmarked frameworks:
+    - `dyn: large web app`  6194ms → **571ms** (~10.9× faster; +9% vs alien)
+    - `dyn: wide dense`     5115ms → **912ms** (~5.6× faster; +10% vs alien)
+  No regressions on the other rows (steady-state update, propagation, and creation
+  paths are within noise of 1.1.2). See `resultsReactive.txt`.
+- **Correctness.** The new retracking is validated by `retracking.difftest.mjs`
+  against a reference reconciler: 20,000 direct writes and 10,000 batched writes,
+  **0 disagreements**.
+
+### Added — observer-lifecycle introspection (top-level + per-registry)
+A small, zero-cost-when-unused surface for auto-pausing wrappers and devtools.
+All accept a public `Signal`/`Computed` handle.
+- **`hasObservers(handle)` → `boolean`.** O(1) (`node.headSub !== null`). The
+  auto-pause predicate: is anything subscribed to this source right now? A `peek`
+  does not count.
+- **`observeObservers(handle, { onConnect?, onDisconnect? })` → `unobserve`.**
+  Fires `onConnect` on the 0→1 observer transition and `onDisconnect` on 1→0,
+  *after* registration (transition-only — no immediate fire if the handle is
+  already observed). Re-tracking a persistently-read source does **not** churn
+  connect/disconnect. This is the hook `lite-time` / `lite-raf` use to start a
+  ticker only while a derived value is being watched.
+- **`forEachObserver(handle, fn)` / `forEachSource(handle, fn)`.** Walk the live
+  graph in either direction; `fn` receives a `{ kind, value }` descriptor where
+  `kind` is `"signal" | "computed" | "effect"`. For graph inspection (lite-devtools).
+- **Cost.** The hooks sit behind an internal lifecycle counter — when no handle is
+  being observed, the hot path adds a single branch-predicted `count !== 0` check
+  inside link alloc/free and nothing else. Zero steady-state cost when unused.
+- **Error contract.** `hasObservers` / `forEachObserver` / `forEachSource` no-op
+  on a non-handle argument; `observeObservers` throws `TypeError`.
+
+### Test suite
+- Added `test/13-introspection_test.mjs`: 10 tests across 3 describe blocks —
+  `hasObservers` (live observation reflects, 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).
+
+### Migration from 1.1.3
+None required. Drop-in upgrade. No existing surface or behavior changed; the
+introspection functions are purely additive and the retracking change is internal.
+
+## [1.1.3] — 2026-05-28
+
+Patch release: one new export, no behavior changes, no engine changes — drop-in
+over 1.1.2.
+
+### Added
+- **`isTracking()`** (top-level + per-registry). Returns `true` iff a read RIGHT
+  NOW would record a dependency on this registry — an observer body is on the
+  stack AND tracking is enabled. Returns `false` inside `untrack()`, inside the
+  callback of `signal.subscribe` (which inlines the same untracked-notify), inside
+  `onCleanup` bodies, inside the `watch` / `when` callback path, and outside any
+  observer. The predicate mirrors the engine's own read-trap check
+  (`isTrackingDeps && currentObserver !== null`) so callers stay in lockstep with
+  what the engine actually does on a read, not just whether an observer is on the
+  stack.
+
+### Why
+Wrapper libraries (lite-store, lite-query, lite-form) need to allocate reactive
+primitives lazily on property reads to preserve the zero-GC contract. Without a
+predicate they must either always allocate (defeats the point) or inspect engine
+internals (fragile coupling). `isTracking()` is the first-class way to gate
+allocation on whether the read will actually subscribe anything.
+
+### API notes
+- **Per-registry.** A wrapper operating against a non-default registry MUST call
+  THAT registry's `isTracking()`, not the top-level one — each registry has its
+  own tracking state. The top-level helper delegates to the default registry,
+  matching the existing pattern for `signal`/`computed`/`effect`/`untrack`.
+- **Cost.** Two closure-variable loads, one AND, one return; V8 inlines it.
+  Roughly 1–2 ns per call.
+
+### Test suite
+- Added `test/10-is-tracking_test.mjs`: 11 tests across 5 describe blocks —
+  observer-bodies (effect + computed), untracked windows (`untrack`, `subscribe`
+  callback, `onCleanup`, `watch` callback), outside-observer (module scope,
+  call-site of unobserved computed read), robustness (state restored after
+  observer body throws, per-registry isolation), and the top-level binding.
+
+### Migration from 1.1.2
+None required. Drop-in upgrade. No existing surface or behavior changed.
+
+## [1.1.2] — 2026-05-26
+
+Patch release: hot-path micro-optimizations and a zero-allocation cleanup of
+the creation path. No behavior changes, no API changes — drop-in over 1.1.1.
+
+### Changed — performance (no semantic change)
+- **Inlined cursor fast-path in `signal()`/`computed()` reads.** On stable read
+  order the cursor match is now handled inline; only a cursor *miss* falls
+  through into the (large, non-inlinable) `allocateLink` frame. Removes a
+  function call from the steady-state read hot path.
+- **Allocation-free creation.** `signal`/`computed`/`effect` now read their
+  `opts` argument defensively instead of defaulting the parameter to `{}`. The
+  `= {}` default allocated a throwaway object on every no-opts call — the common
+  path when mounting many cells. Creation is now zero-allocation on that path.
+- **Single-closure `subscribe`.** The tracked read + untracked notify is inlined
+  (one closure instead of two), dropping a per-subscription closure and an
+  `untrack` wrapper call on every fire.
+- **`markDownstream` micro-cleanup.** Combined `(FLAG_QUEUED | FLAG_COMPUTING)`
+  test and tightened stack/queue index arithmetic. The `flags` read stays inside
+  the `markEpoch` dedup guard on purpose (hoisting it would add work on the
+  already-marked revisit path that the guard exists to keep cheap).
+
+### Changed — packaging
+- Canonical single-engine layout: the implementation is `Signal.js` and the
+  watcher utilities are `Watch.js`, which imports `effect`/`untrack` from
+  `./Signal.js`. Both the public entry and `Watch.js` resolve to one engine
+  instance — eliminating any chance of a duplicate-module-instance split that
+  would silently break cross-module dependency tracking.
+
+### Test suite
+- `tests/09-conformance.test.mjs`: the owner-tree conformance items **#209** and
+  **#210** (three-level cascading disposal; inner-effect cleanup on outer re-run)
+  are marked skipped with a v1.2 pointer. The baseline engine maintains no owner
+  tree; these are validated against the v1.2 ownership hybrid. All other
+  conformance items pass.
+
+### Performance
+- Steady-state hot path remains **0 allocations** (`signal.set`, `peek`, computed
+  read, effect re-run, dispose). Creation path now also 0-allocation on the
+  no-opts common case. Re-run `npm run bench` on your target host for current
+  ops/s; the 1.1.1 numbers stand as a floor.
+
+### Migration from 1.1.x
+None required. Drop-in upgrade.
+
+## [1.1.1] — 2026-05-22
+
+Patch release: cleanup-semantics adapter integration, conformance fixes from
+the `johnsoncodehk/reactive-framework-test-suite`, and one targeted
+correctness bug in flush error reporting.
+
+### Added
+- Top-level `destroy()` export. Wipes the default registry; intended for
+  test-suite isolation only. Previously the function existed but was not
+  re-exported from the package entrypoint, breaking any adapter that
+  destructure-imports it.
+- `tailSub` field on `ReactiveNode`. Symmetric with the existing `tailDep`;
+  enables O(1) tail insertion into the subscriber list.
+
+### Changed — conformance fixes
+
+- **#216** Effects now fire in **creation order** on a shared signal.
+  Subscriber list insertion is tail-first instead of head-first; traversal
+  order in `markDownstream` is unchanged. Brings lite-signal in line with
+  every other library in the suite except solid-js and pota.
+
+- **#178** `runCleanup` invokes registered cleanups in an **untracked
+  context** (`currentObserver = null`, `isTrackingDeps = false`). Reads
+  inside a cleanup body — including reads triggered by a synchronous
+  `dispose()` from a containing effect — no longer leak into the parent
+  observer's dep set.
+
+- **#111** `executeEffect` bails cleanly when a node is disposed by its own
+  cleanup. Previously the post-cleanup body invocation hit `undefined()` on
+  the cleared `computeFn`.
+
+- **#123 / #132 / #147** **Revert detection in batches.** A signal whose
+  in-batch write sequence ends at the pre-batch value (per its `equals`
+  predicate) restores its `version` and skips propagation. Captures are
+  scoped per top-level batch via a `revertEpoch` counter; the `0` sentinel
+  is preserved through SMI wraparound by skipping it on increment.
+
+- **#121** **Throw isolation in flush.** Effects that throw during
+  `flushEffects` no longer halt the flush. Errors are collected in a
+  reused per-registry buffer; on flush completion, a single thrown error
+  re-raises as-is, multiple throws raise as `AggregateError`. `isFlushing`
+  is now cleared in a `try/finally`, eliminating the registry-deadlock
+  that the prior throw-out path would leave behind.
+
+- **#180 / #213** **No-re-run semantics for self-cycles.** An effect that
+  is currently executing on the call stack is no longer re-queued by
+  `markDownstream` when its own body's writes propagate back through a
+  computed chain. Matches S.js / pre-2.0 Solid. Sibling effects on the
+  same chain continue to fire normally.
+
+### Fixed
+- Flush error buffer no longer leaks across calls when a `CycleError`
+  escapes the flush loop. Buffered effect errors are cleared in the
+  outer `finally` if the flush is exiting abnormally.
+
+### Performance
+- No regressions observed in MUX, BROADCAST, DEEP CHAIN, KAIROS, or
+  SELECTIVE DAG benchmarks. MUX moved from 156K to 226K ops/s — V8 appears
+  to optimise the flush loop more aggressively now that the per-iteration
+  `try/catch` shape is stable. Out-of-batch `signal.set` is unchanged
+  (revert-detection guards short-circuit on `batchDepth === 0`).
+
+### Conformance score
+- Before 1.1.1: 145 / 156 (with v1.1.0 adapter pre-fix), 164 / 177
+  (corrected adapter, no library fixes).
+- After 1.1.1: TBD pending full conformance re-run. Expected: all
+  Tier 1 + Tier 2 items closed (#216, #178, #111, #123, #132, #147, #121,
+  #180, #213, #235), leaving `#179`, `#209`, `#210` deferred to v1.2
+  (owner-tree / computed-self-write).
+
+### Internal test suite
+- Added `tests/09-conformance.test.mjs` collecting the upstream test IDs
+  by number, with companion tests pinning the design decisions
+  (sibling-effect propagation under no-re-run, cycle precedence over
+  buffered errors, custom-equals revert, etc.).
+
+## [1.1.0] — 2026-05-20
+
+### Added
+- `markDownstream` iterative DFS marker backed by preallocated `markStack` — propagation no longer grows the JS call stack regardless of graph depth.
+- Double-buffered effect queue (`effectQueueA` / `effectQueueB`) — effects scheduled mid-flush land in the next pass, no recursive flush.
+- Generation counter (`gen`) per node — stale handles after dispose+recycle silently no-op instead of corrupting the pool.
+- `CapacityError` with `kind` (`"nodes"` | `"links"`) and `capacity` fields, thrown when the `"throw"` policy is set and a pool is exhausted.
+- `createRegistry({ onCapacityExceeded: "grow" })` — opt-in unbounded pool growth, bounded by `maxLinks * 16` ceiling.
+- `createRegistry({ maxFlushPasses })` — configurable cycle-protection limit (default `100`).
+- `destroy()` — full registry reset; all prior handles silently no-op afterward.
+- `watch(source, callback, { immediate? })`, `when(predicate, callback)`, `whenAsync(predicate)` — re-exported from `Watch.js`. Zero-allocation hot paths in `watch` and `when`; `whenAsync` allocates one Promise per call (documented; not for per-frame use).
+
+### Changed
+- 32-bit modular epoch arithmetic across `globalVersion`, `evalVersion`, `markEpoch`. Engine survives indefinite uptime without integer-overflow risk.
+- `dispose(api)` is now universal across signals, computeds, effect handles, and `.subscribe()` return values. Cross-registry calls are silent no-ops. Foreign reactive primitives are duck-typed (on `.peek`) and not invoked.
+- `untrack(fn)` restores prior tracking state via `try / finally` — safe under thrown errors inside `fn`.
+- `onCleanup(fn)` now accepts multiple registrations per scope and works in computeds, not just effects. Stored as a single function or upgraded to an array.
+
+### Fixed
+- Diamond dependency reads no longer over-fire effects (versioned pull resolves convergence cleanly in one pass).
+- Effect re-runs no longer leak link slots when the dep set shrinks (tail-link severance in `severTail`).
+- Disposed-then-recycled slots no longer mis-dispose under stale handles (generation guard in `dispose`).
+- Cleanup functions registered inside computeds now fire (previously effect-only).
+
+### Performance
+- Steady-state hot path: **0 allocations** across `signal.set`, `signal.peek`, computed read, effect re-run, dispose.
+- **249K ops/s** on MUX fan-in (Node 22, 2016 MacBook Pro). +20% vs alien-signals on identical workload.
+- **15 KB** transient heap across 20,000 iterations.
+- Full methodology and reproducibility recipe in [`bench/README.md`](./bench/README.md).
+
+### Known limitations
+- Dependency reconciliation is O(1) per read on stable read order; degrades to O(N) under chaotic read order. v1.2 (in benchmark validation) replaces the cursor-based retracking with per-source version-stamped reconciliation — see [RFC #N1](https://github.com/PeshoVurtoleta/lite-signal/issues/1).
+- Computed resolution is recursive on the JS call stack; bounded by the engine stack limit (~10,000 frames).
+- `whenAsync` allocates one Promise per call. Use `when` (callback form) for per-frame paths.
+
+### Migration from 1.0.x
+None required. Drop-in upgrade.
+
+## [1.0.0] — 2026-05-12
+Initial public release.