@zakkster/lite-signal 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -4,14 +4,277 @@ 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
+## [1.2.2] -- 2026-06-16
+
+A code-deletion ship: a `createNode` audit removes ten redundant field-writes
+that defended against a state the engine cannot produce on a clean free-list.
+No public surface change, no semantic change, no new tests required for new
+behavior (because there is none) -- only an added invariant suite that pins
+the cleanliness claim the audit relies on. Drop-in over 1.2.1.
+
+**Version lineage note.** This is the engine previously labeled `1.2.3` in dev.
+Renumbered to `1.2.2` to keep semver tidy: the deletion is small, isolated, and
+intentionally non-behavioral; bumping the patch rather than the minor reflects
+that. The upcoming `1.3.0` (lazy/chunked pool with `prealloc:"eager"` default
+and intrusive mark stack) carries the next minor bump.
+
+### Changed -- clean free-list invariant audit in `createNode`
+
+Two clusters of redundant writes removed. Both rely on a single invariant:
+**every node leaving the pool has the listed fields at their fresh-construct
+default values** because `disposeNode` and `runCleanup` already null them and
+the `ReactiveNode` constructor initializes them to the same values on
+fresh-pool-growth allocation.
+
+- **Seven graph/batch fields** no longer rewritten on every allocate:
+  `headDep`, `tailDep`, `headSub`, `tailSub`, `revertEpoch`, `preBatchValue`,
+  `preBatchVersion`. Paired-checked: `disposeNode` clears all seven on the
+  recycle path; the `ReactiveNode` constructor inits all seven to the same
+  values on the fresh-allocation path used by pool growth.
+- **Three owner-tree fields** in the non-adoption path no longer rewritten:
+  the `firstOwned = null`, the adoption-path `prevOwned = null`, and the
+  else-branch `owner = null`. The `disposeNode` direct path nulls
+  `owner / prevOwned / nextOwned`; the `runCleanup` cascade path nulls them
+  on every disposed child and sets the parent's `firstOwned = null` at exit.
+  The constructor inits all four owner-tree fields to `null` on
+  fresh-allocation.
+
+What `createNode` still writes are the *lifetime* writes for the new resident:
+`value`, `flags`, `id`, and the three fields `disposeNode` does NOT touch
+(`version`, `evalVersion`, `markEpoch` -- propagation state that must reset for
+the new lifetime), plus the conditional owner-adoption splice
+(`owner`, `nextOwned`, parent chain link).
+
+### Added -- `test/10-free-list-invariant_test.mjs`
+
+A three-test invariant suite that asserts the audit's claim by inspecting
+freshly-allocated nodes' underlying field state (via the documented
+`describe()` -> `NODE_PTR` surface, the same protocol devtools uses). Tests:
+
+- Recycled slot reports null `headDep/tailDep/headSub/tailSub` and zero
+  `revertEpoch/preBatchVersion`, undefined `preBatchValue`, after disposing
+  a real signal->computed->effect graph.
+- Recycled slot reports null `owner/prevOwned/nextOwned/firstOwned` after an
+  owner-cascade tears down a nested observer tree.
+- Mixed-pattern churn (simple, batched-write, error-flush) leaves no dirty
+  state on the free list across 32 follow-up allocations.
+
+If any future change reintroduces a write to a clean-state field on the
+dispose path or removes a write that turns out NOT to be redundant, this
+suite catches it.
+
+### Added -- `test/11-devtools-contract_test.mjs`
+
+A 12-test smoke probe of the introspection surface that lite-devtools 1.1 /
+lite-studio 1.1 consume. Verifies handle resolution + walkers, owner-tree
+walkers, the `onGraphMutation` push hook, the `observeObservers` ghost
+contract (zero added nodes under heavy introspection), and pins the
+authoritative 1.2.x `stats()` shape (exactly 8 keys: `signals`, `computeds`,
+`effects`, `activeNodes`, `activeLinks`, `pooledLinks`, `nodePoolCapacity`,
+`linkPoolCapacity`). Also pins the absence of `totalAllocations` /
+`totalDisposals` / `poolGrowths` on 1.2.x -- those are reserved for 1.4.0 and
+the test fails if they appear early.
+
+### Verified
+
+- **408 tests total: 398 pass, 10 skip, 0 fail** across the 23 active
+  suites (01-09 baseline + 11-23 introspection/ownership/perf-pin + my new
+  25 devtools-real-boot + 26 free-list-invariant). The 10 skips are 9
+  signalBox-staged-for-1.5.0 in `24-signalbox` and 1 architecturally-N/A
+  SSR case in `17-reactivity`.
+- **Coverage on `Signal.js`: 100% statements, 98.43% branches, 100%
+  functions, 100% lines.** `Watch.js`: 100% across all four. (c8@11,
+  Node 22.) Better branch coverage than the 1.2.1 baseline documented in
+  `llms.txt` (was 98.07%); the engine path that closed the gap was a
+  targeted test of the swallow-on-self-dispose-then-throw branch in
+  `pullComputed`. The remaining ~5 unreached branches are exactly the
+  unreachable-by-construction cases already catalogued as `/* c8 ignore */`
+  candidates in `COVERAGE-NOTES.md` (cursor fast path, batch wraparound
+  sentinel, etc.).
+- **Devtools 1.1.0 + Studio 1.1.0 contract: green.** Test
+  `25-devtools-real-boot` boots the actual `Devtools.js` against the
+  1.2.2 engine and exercises all 19 exports + the 10 symbols Studio
+  imports from Devtools. The ghost contract holds (heavy introspection
+  adds zero nodes). One real test-rig finding surfaced during this work:
+  if the engine is developed in a repo whose own `package.json` declares
+  `name: "@zakkster/lite-signal"`, importing the package by name from the
+  project root can resolve to a different module instance than imports
+  from inside a sibling `node_modules/@zakkster/lite-devtools/`,
+  fragmenting the `defaultRegistry`. This is purely a dev-loop / test-rig
+  matter (not an engine, devtools, or studio bug) -- in a real consumer
+  installation both packages live in `node_modules` and resolve once.
+
+### Not changed
+
+- Public API: no additions, no removals, no signature changes.
+- Type surface: `Signal.d.ts` unchanged.
+- Behavior: every existing test case in 01-09 passes unmodified.
+
+### Honest notes
+
+- **Perf**: no microbench numbers cited. Ten removed field writes per
+  `createNode` is a real saving on creation-heavy workloads, but creation
+  cost is dominated by the owner-adoption splice and the optional mutation
+  hook, not by these writes. Any "X% faster on creation" claim would need
+  to come from a per-run lite-vs-alien measurement on the project's
+  standard benchmark harness; this ship does not include one because the
+  audit is justified by correctness (clean invariant beats defensive
+  writes) rather than measured speedup.
+- **Differential testing**: the retracking difftest harness expects two
+  engine builds (REF = prior shipped, CANDIDATE = under review). This ship
+  was validated against itself (30,000 writes, 0 disagreements), which
+  proves determinism but not 1.2.2-vs-1.2.1 behavioral equivalence --
+  equivalence is argued instead from the audit being a code-deletion of
+  writes provably-redundant under the existing pre/post-invariants, and
+  from the full 01-09 suite passing unmodified.
+
+### Benchmarks
+
+The audit ship does not move the curve on any benchmark -- by design;
+the steady-state hot paths are byte-identical to 1.2.1. The bench
+results were re-measured against 1.2.2 on the project's reference host
+(2016 MacBook Pro, Intel, Node 22) and are published as the baseline
+for the next version. See [`bench/results.txt`](./bench/results.txt)
+(in-house anti-DCE harness, median-of-3 cold-process runs from
+`bench/run-all.sh`), [`bench/resultsReactive.txt`](./bench/resultsReactive.txt)
+(community reactive suite, 10 raw runs), and the third-party
+[js-reactivity-benchmark](https://github.com/volynetstyle/js-reactivity-benchmark)
+results (16 frameworks). Position on the third-party suite: **#4 of 16
+by geomean** (2.05× vs alien-signals 1.00×), behind alien-signals,
+reflex, and @reactively; ahead of Preact Signals (2.09×), uSignal,
+$mol_wire, and 9 others. Outright wins on `manyEffectsFromOneSource`
+and `manySourcesIntoOneComputedEffectWithDirect`; top-3 finishes on
+18 of 47 tests. The version dependencies used for these numbers are
+pinned in [`bench/package.json`](./bench/package.json) at
+`lite-signal-bench@2.2.0`.
+
+## [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
 (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.
+that split. No behavioural changes for existing code -- drop-in over 1.1.5.
 
-### Added — auto-disposal of nested observers (owner tree)
+### 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.
@@ -25,7 +288,7 @@ that split. No behavioural changes for existing code — drop-in over 1.1.5.
   `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)
+### 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
@@ -33,15 +296,15 @@ that split. No behavioural changes for existing code — drop-in over 1.1.5.
   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`
+### 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
+  unchanged -- a flush exceeding `maxFlushPasses` (default 100) throws an
   `Error` prefixed `"CycleError:"`.
 
-### Added — scheduler thunk caching with gen-bound ABA guard
+### 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
@@ -49,14 +312,14 @@ that split. No behavioural changes for existing code — drop-in over 1.1.5.
   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
+### 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
+    - **L1 Graph topology** -- `allocateLink` / `freeLink` / `severTail`. Pure
       edge mechanics. Never touches `owner` / `firstOwned`.
-    - **L2 Ownership/lifecycle** — `createNode` / `disposeNode` / `runCleanup`.
+    - **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
+    - **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
@@ -65,31 +328,31 @@ that split. No behavioural changes for existing code — drop-in over 1.1.5.
 - **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
+  ~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
+### 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
+- `allocateLink` retains the **O(1) `tailSub` dedup** -- divergent re-tracking
+  remains O(N), not O(N^2). 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
+### 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
+  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.
+  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:
@@ -104,18 +367,18 @@ that split. No behavioural changes for existing code — drop-in over 1.1.5.
 - 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
+  detection, batchEpoch wraparound after 2^3^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
+- 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
+  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`).
@@ -130,76 +393,76 @@ that split. No behavioural changes for existing code — drop-in over 1.1.5.
 - 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
+## [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)
+### 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` -- 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`
+- 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
+## [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
+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)
+### 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.
+  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)
+    - `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)
+### 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
+- **`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
+- **`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
+- **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 —
+- 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
@@ -211,14 +474,14 @@ All accept a public `Signal`/`Computed` handle.
 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
+## [1.1.3] -- 2026-05-28
 
-Patch release: one new export, no behavior changes, no engine changes — drop-in
+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
+  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
@@ -236,14 +499,14 @@ 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
+  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.
+  Roughly 1-2 ns per call.
 
 ### Test suite
-- Added `test/10-is-tracking_test.mjs`: 11 tests across 5 describe blocks —
+- 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
@@ -252,19 +515,19 @@ allocation on whether the read will actually subscribe anything.
 ### Migration from 1.1.2
 None required. Drop-in upgrade. No existing surface or behavior changed.
 
-## [1.1.2] — 2026-05-26
+## [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.
+the creation path. No behavior changes, no API changes -- drop-in over 1.1.1.
 
-### Changed — performance (no semantic change)
+### 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
+  `= {}` 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
@@ -274,11 +537,11 @@ the creation path. No behavior changes, no API changes — drop-in over 1.1.1.
   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
+### 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
+  instance -- eliminating any chance of a duplicate-module-instance split that
   would silently break cross-module dependency tracking.
 
 ### Test suite
@@ -297,7 +560,7 @@ the creation path. No behavior changes, no API changes — drop-in over 1.1.1.
 ### Migration from 1.1.x
 None required. Drop-in upgrade.
 
-## [1.1.1] — 2026-05-22
+## [1.1.1] -- 2026-05-22
 
 Patch release: cleanup-semantics adapter integration, conformance fixes from
 the `johnsoncodehk/reactive-framework-test-suite`, and one targeted
@@ -311,7 +574,7 @@ correctness bug in flush error reporting.
 - `tailSub` field on `ReactiveNode`. Symmetric with the existing `tailDep`;
   enables O(1) tail insertion into the subscriber list.
 
-### Changed — conformance fixes
+### 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
@@ -320,8 +583,8 @@ correctness bug in flush error reporting.
 
 - **#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
+  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
@@ -354,7 +617,7 @@ correctness bug in flush error reporting.
 
 ### Performance
 - No regressions observed in MUX, BROADCAST, DEEP CHAIN, KAIROS, or
-  SELECTIVE DAG benchmarks. MUX moved from 156K to 226K ops/s — V8 appears
+  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`).
@@ -373,22 +636,22 @@ correctness bug in flush error reporting.
   (sibling-effect propagation under no-re-run, cycle precedence over
   buffered errors, custom-equals revert, etc.).
 
-## [1.1.0] — 2026-05-20
+## [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.
+- `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).
+- `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`.
+- `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
@@ -404,12 +667,12 @@ correctness bug in flush error reporting.
 - 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).
+- 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
+## [1.0.0] -- 2026-05-12
 Initial public release.