@zakkster/lite-signal-decorators 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -4,6 +4,97 @@ All notable changes to `@zakkster/lite-signal-decorators` are documented here.
 The format follows Keep a Changelog; this project adheres to Semantic
 Versioning.
 
+## [1.3.0] - 2026-08-30
+
+The introspection/migration rung of the decisions/0013 strategic-admission
+ladder, and the release that proves criterion (c): `snapshotOf` ships as the
+MobX-`toJS`-parity export nobody could reach cleanly by composition, and it is
+the REAL, NAMED in-package consumer that finally admits `forEachReactive` under
+the ORIGINAL 0009 bar (a new export needs a named consumer, and a recipe is not
+one). decisions/0009 recorded both as candidates 2 and 3 with the absence
+stated plainly; this release admits them together -- `forEachReactive` because
+`snapshotOf` is built ON it, `snapshotOf` because it is the MobX-`toJS` parity a
+recipe cannot honestly serve. The recorded absence in 0009 is preserved as
+pre-admission history, not rewritten. Surface 19 -> 21.
+
+### Added
+
+- **`forEachReactive(vm, fn, arg) -> count`** (20th export) -- a cold walk over
+  every value-bearing member. Calls `fn(key, box, kind, arg)` once per member
+  and returns the visit count. `kind` is `"signal" | "local" | "derived"`;
+  `@reactiveEffect`/`@batched` are EXCLUDED (non-value-bearing -- `boxOf`
+  refuses them). Order is PLAN order: signals, then locals, then deriveds, each
+  declaration-ordered and ancestor-first (never `Reflect.ownKeys`, so it is
+  stable across reinit). Four scalar args, no descriptor object, and the `arg`
+  pass-through kills the caller's closure -- a gated zero-alloc walk. Symbol
+  keys are visited. Fails closed on non-reactive/unwired/parked/disposed with the
+  same named errors as `rootOf`.
+- **`snapshotOf(vm) -> object`** (21st export) -- a shallow plain-object copy of
+  every value-bearing member, keyed by member key, built ON `forEachReactive`.
+  Values are read through the ACCESSOR `vm[key]`, NOT `box.get`, so a `@localTo`
+  compare-on-read resets honestly and a `@derived` computes on read (PD-62). The
+  whole walk runs under ONE `untrack` when the caller is tracking, so a
+  `snapshotOf` inside an effect subscribes to nothing (PD-63). SHALLOW by design
+  (PD-64): a nested VM is copied by reference, recursion deferred to a named
+  consumer. Symbol keys included (`Reflect.ownKeys` law). Fails closed on
+  parked/disposed (`ReactiveDisposedError`, parked vs disposed flavor) and
+  non-reactive values. It ALLOCATES the returned object by design -- reported,
+  never gated; the walk under it stays zero-alloc.
+- **`test/18-introspection.test.mjs`** (22 cases) -- both emit lanes + buildless:
+  plan-order walk, symbol keys, kind tags, effect/batched exclusion, count
+  return + `arg` pass-through, the untracked-read law (a `snapshotOf` inside an
+  effect fires ONCE, then never as every member is written), r7
+  `{name,hp,mp,alive}` parity, the PD-62 accessor-read reset honesty, and the
+  fail-closed non-reactive/unwired/parked/disposed matrix.
+- **The `introspection-torture` lane** (scenario 18 of 18) with its own
+  `TORTURE_BREAK` sabotage control: 1e6 hoisted-callback `forEachReactive` walks
+  at `maxMajor 0` with control-relative minors, plus 1e5 `snapshotOf` cycles
+  whose bytes/op are REPORTED in the summary line, never gated -- the snapshot
+  allocates by design and the harness says so out loud.
+
+### Changed
+
+- **The export surface: 19 -> 21** -- an additive MINOR under the 1.0.0 semver
+  promise (new exports are minors). The 1.0.0 hot canon
+  (`makeGet`/`makeSet`/`makeDerivedGet`) stays byte-identical: both new exports
+  are cold and neither moves an accessor byte.
+- Three-place version sync to 1.3.0 (`package.json`, the `VERSION` const,
+  `llms.txt`); the `test/15` surface-freeze recount 19 -> 21.
+- `throwNoBox` message widened to name `@localTo`: `boxOf` serves `@reactive`,
+  `@localTo`, and `@derived` members only (locals pass `boxOf`; the message had
+  listed only `@reactive`/`@derived`).
+
+### Measured (rig: Node v26.3.1, arm64 Apple M4 Pro, lite-signal 1.5.0)
+
+- 1e6 hoisted-callback `forEachReactive` walks: **0.002 B/walk** (vs the 0.000
+  B/op zero-alloc control, within a +2-byte limit), gc major **0**,
+  `maxPauseMs <= 4.0`.
+- 1e5 `snapshotOf` cycles: **95.8 B/op** -- the returned object, reported as
+  "allocates by design", never gated.
+- 1e5 construct -> snapshot -> dispose cycles: `tracker.size()` 0, findings 0,
+  warnings 0, `activeNodes`/`nodes` back to exact pre-loop baseline; snapshots
+  hold no box reference.
+
+Records: decisions/0013 (strategic-admission track, criterion (c)),
+decisions/0009 (candidates 2 + 3, now stamped ADMITTED with the pre-admission
+absence preserved).
+
+### Gate output (section-10 chain, archived verbatim)
+
+```
+  fixtures              OK       exit 0 -- emit fixtures regenerated
+  test                  OK       exit 0 -- 313 pass / 0 fail
+  test:gc               OK       exit 0 -- 313 pass / 0 fail
+  torture               OK       exit 0 -- 16 passed, 2 skipped, 0 warned, 0 failed in 34.9s
+  torture:controls      OK       exit 0 -- 18 passed, 0 skipped, 0 warned, 0 failed in 3.7s
+  torture:peer-preview  REPORTED NON-BLOCKING -- lane completed (exit 0)
+  bench:selftest        OK       exit 0 -- ALL PASS -- 22 passed, 0 failed
+  cookbook              OK       exit 0/0 -- corpus 18/18 companions ok; controls 8/8 fail correctly
+  pack                  OK       exit 0 -- 7/7 files, exact 7-name set, no demo/ no Publications/
+----------------------------------------------------------------------
+  GATE PASS -- 8 blocking steps + 1 non-blocking (peer-preview)
+```
+
 ## [1.2.0] - 2026-08-30
 
 The flagship of the decisions/0013 strategic-admission track: a story-grade,

package/README.md

@@ -146,6 +146,7 @@ const ReactivePlayer = defineReactive(Player, {
 - **One deterministic teardown** -- `disposeReactive(vm)` (or a `using` block): anchor cascade, box disposal, poison swap, idempotent, allocation-free on the success path.
 - **Fail-closed everything** -- statics, private `#` members, unknown options, duplicate keys, orphaned members, invalid registries, half-valid specs: all named throws at decoration time, with a nearest-key did-you-mean where a typo is likely.
 - **Interop that stays raw** -- `boxOf(vm, key)` hands you the live engine box; `rootOf(vm)` hands the anchor descriptor to `forEachOwned` / lite-devtools. Decorated and hand-written signals share one graph.
+- **Introspection & migration (1.3.0)** -- `forEachReactive(vm, fn, arg)` walks every value-bearing member in plan order (`signal`/`local`/`derived`, effects excluded) with a zero-alloc `fn(key, box, kind, arg)` callback; `snapshotOf(vm)` returns a shallow plain-object copy read through the accessors under one `untrack` -- the native `toJS` this package now ships, safe to call inside an effect.
 
 ---
 
@@ -275,12 +276,19 @@ Symbol keys work (`Reflect.ownKeys`). A spec key colliding with an own property
 
 With labels and audit off, the zero-GC budgets are byte-identical to 0.3.0 -- the hot accessor canon is untouched by all four (review-diffed against the published 0.3.0 tarball).
 
+### Introspection walk & snapshot (1.3.0)
+
+| Export | Signature | Behavior |
+|---|---|---|
+| `forEachReactive` | `(vm, fn, arg) => count` | Cold value-member walk. Calls `fn(key, box, kind, arg)` once per value-bearing member and returns the visit count. `kind` is `"signal" \| "local" \| "derived"`; `@reactiveEffect`/`@batched` are EXCLUDED (non-value-bearing). Order is PLAN order -- signals, then locals, then deriveds, each declaration-ordered and ancestor-first (never `Reflect.ownKeys`, so it is stable across reinit). Four scalar args, zero descriptor object, and the `arg` pass-through kills the caller's closure: the walk is a gated zero-alloc body. Symbol keys are visited. Fails closed on a non-reactive, unwired, parked, or disposed value with the same named errors as `rootOf`. |
+| `snapshotOf` | `(vm) => object` | A shallow plain-object copy of every value-bearing member, keyed by member key. Values are read through the ACCESSOR `vm[key]`, NOT `box.get`, so a `@localTo` compare-on-read resets honestly and a `@derived` computes on read (PD-62: reading the box directly would show a stale local after an untracked upstream move -- the accessor is the documented read). The whole walk runs under ONE `untrack` when the caller is tracking, so `snapshotOf` inside an effect subscribes to nothing. SHALLOW by design: a nested VM is copied by reference, not recursed. Symbol keys included. Fails closed on parked/disposed (`ReactiveDisposedError`, parked vs disposed flavor) and non-reactive values. This export ALLOCATES the returned object by design (~96 B/op measured) -- reported, never gated; the walk under it stays zero-alloc. |
+
 ### Errors & constants
 
 | Export | Value |
 |---|---|
 | `ReactiveDisposedError` | `extends Error`; `name: "ReactiveDisposedError"`; fields `className`, `key`. Thrown on ANY touch of a disposed instance's surface. |
-| `VERSION` | `"1.2.0"` |
+| `VERSION` | `"1.3.0"` |
 
 ### The rejection matrix
 
@@ -398,12 +406,14 @@ The ~7 ns over raw batch is the guarded thunk + rest-array the decorator allocat
 | `new Host()` | P + L + D + E + 1 pool nodes | plus the instance itself; nodes recycle on dispose (F-0 conservation) |
 | `disposeReactive(vm)` | none | allocation-free success path; poison handles are prebuilt per member at decoration time |
 | `boxOf` / `rootOf` / any throw | cold path | introspection and failure paths may allocate; never on the hot path |
+| `forEachReactive` walk | none | gated: 1e6 hoisted-callback walks measure **0.002 B/walk** (vs the 0.000 B/op zero-alloc control -- within a +2-byte limit), `gc.major === 0`; the 4-scalar `fn(key, box, kind, arg)` carries no descriptor object and the `arg` pass-through kills the caller's closure |
+| `snapshotOf(vm)` | 1 plain object | **by design** -- the returned copy allocates (**95.8 B/op measured**, 1e5 cycles); REPORTED in the torture summary line, never gated. The walk *under* it stays zero-alloc; cold, off any frame path |
 
-The gates that hold it (run on every change, all green at 1.2.0):
+The gates that hold it (run on every change, all green at 1.3.0):
 
-- `npm test` / `npm run test:gc` -- **291/291** on both lanes.
+- `npm test` / `npm run test:gc` -- **313/313** on both lanes.
 - Suite gate (lite-leak + lite-gc-profiler): `leak=size 0/0 findings=0 warnings=0 | gc major=0 minor=0 maxMs=0.00 | ok`.
-- Torture: **17 scenarios** (zero-GC read/write lanes at `maxMajor 0, maxPauseMs 4`; 4096-cycle leak gate at 0 live / 0 findings / 0 warnings; capacity atomicity at every overflow point; a 300-seed x 20k-op oracle with zero divergences; the `reinit-torture` acquire/release gate; the `localto-torture` zero-alloc read/write storm + ABA-stale interleave lattice + pooled park/reinit) -- **15 run + 2 that skip correctly below their peer floors** (`scope-adoption` needs 1.6.0, `using-dispose` needs 1.9.0; the installed peer is 1.5.0). A skip *below* a floor is the forward-compat design working; a skip *at or above* it is a FAIL (run.mjs enforces floor-escalation). Every scenario carries a `TORTURE_BREAK` sabotage control that must exit non-zero -- **17/17 controls** prove each gate can actually fail.
+- Torture: **18 scenarios** (zero-GC read/write lanes at `maxMajor 0, maxPauseMs 4`; 4096-cycle leak gate at 0 live / 0 findings / 0 warnings; capacity atomicity at every overflow point; a 300-seed x 20k-op oracle with zero divergences; the `reinit-torture` acquire/release gate; the `localto-torture` zero-alloc read/write storm + ABA-stale interleave lattice + pooled park/reinit; the `introspection-torture` 1e6 hoisted-callback `forEachReactive` walk at `maxMajor 0` with the snapshot-allocates figure reported, never gated) -- **16 run + 2 that skip correctly below their peer floors** (`scope-adoption` needs 1.6.0, `using-dispose` needs 1.9.0; the installed peer is 1.5.0). A skip *below* a floor is the forward-compat design working; a skip *at or above* it is a FAIL (run.mjs enforces floor-escalation). Every scenario carries a `TORTURE_BREAK` sabotage control that must exit non-zero -- **18/18 controls** prove each gate can actually fail.
 - `churn-soak` + `fleet-soak`: sustained construct/use/dispose and a 10s 2k-VM fleet tick; pools at floor and retained heap flat at every sample.
 
 The cross-framework matrix lives in `bench/` (private, never shipped): six engines -- both our tiers, the hand-written `lite-raw-boxes` baseline, MobX 7, signal-utils/signal-polyfill, and a hand-rolled alien-signals class -- across eight class-shaped scenarios (including the `churn-reuse` acquire/release lane, where the lite tiers pool with zero retained growth and MobX/signal-utils/alien-class are structurally `unsupported` -- no disposable instance lifecycle to pool), checksum-verified for identical work, stamped into `bench/results.txt`. The formal verdicts are in [`decisions/0006-kill-criteria.md`](decisions/0006-kill-criteria.md): the decorated path measured **0.94x** the hand-written baseline on vm-write and **1.10x** on a 10k-instance fleet read (the 2.0x kill line cleared with margin), and **0 major + 0 minor GC over 4096 construct/use/dispose cycles** with pools at floor -- while emitting ~12.6x less transient garbage per churn run than the hand-rolled class it replaces.
@@ -435,12 +445,12 @@ Full rationale lives in [`decisions/`](decisions/) -- each is a numbered, dated
 ## Testing (for clients & QA)
 
 ```bash
-npm test            # node --test, 291 tests
-npm run test:gc     # the same 291 with --expose-gc (enables the allocation assertions)
+npm test            # node --test, 313 tests
+npm run test:gc     # the same 313 with --expose-gc (enables the allocation assertions)
 npm run gate        # the full pre-publish chain (section 10): fixtures -> test -> test:gc -> torture -> controls -> peer-preview (non-blocking) -> bench selftest -> cookbook -> pack
 ```
 
-**291 tests** across seventeen files, all green at 1.2.0. The decorator protocol is tested three times over: against a mock standard-decorators emitter *and* against committed real TypeScript 5 and Babel `2023-11` emits, so both toolchains' codegen is pinned, not assumed.
+**313 tests** across eighteen files, all green at 1.3.0. The decorator protocol is tested three times over: against a mock standard-decorators emitter *and* against committed real TypeScript 5 and Babel `2023-11` emits, so both toolchains' codegen is pinned, not assumed.
 
 | File | Tests | Covers |
 |---|---:|---|
@@ -458,9 +468,10 @@ npm run gate        # the full pre-publish chain (section 10): fixtures -> test
 | `12-accounting` | 11 | `costOf` node/link/shape grid (double-probe, frozen + cached, fail-closed) + `capacityFor` budget sizing |
 | `13-labels-audit` | 10 | `enableLabels`/`labelOf` per-registry identity + `auditReactive` leak reporting, both opt-in and default-OFF |
 | `14-qa-s4-boundary` | 21 | S4 adversarial edges: stats-less facade closure, signals-only capacity floor, label/audit boundary matrix |
-| `15-cookbook` | 14 | [`COOKBOOK.md`](https://github.com/PeshoVurtoleta/lite-signal-decorators/blob/main/COOKBOOK.md) drift/parity: each fenced block byte-compared against its tagged companion `#region` (both directions + both-way coverage), surface freeze (exactly 19 exports), citation allowlist, link law, static-cost probe |
+| `15-cookbook` | 14 | [`COOKBOOK.md`](https://github.com/PeshoVurtoleta/lite-signal-decorators/blob/main/COOKBOOK.md) drift/parity: each fenced block byte-compared against its tagged companion `#region` (both directions + both-way coverage), surface freeze (exactly 21 exports), citation allowlist, link law, static-cost probe |
 | `16-reinit` | 29 | Pooled-reinit lattice on both emit lanes: park/reinit/dispose transitions, the five `reinitReactive` fail-closed states, parked-touch throws by name, `initials` boundary matrix (0..N+1 keys, null/undefined, NaN/-0 verbatim), `Symbol.dispose` on a parked instance, accessor descriptors byte-identical across reinit, self-release re-entrancy, ledger conservation |
 | `17-localto` | 34 | `@localTo` on both emit lanes + buildless `locals`: the read/write/upstream-reset lattice, both initial flavors (follow-from-wiring vs reset-from-initial), the ABA stale-local contract, `equals` override survival, park/reinit box+seen reset, `costOf` = P+L+D+E+1, source-throw fail-closed, and the fail-closed option/source matrix |
+| `18-introspection` | 22 | `forEachReactive`/`snapshotOf` on both emit lanes + buildless: plan-order walk (signals, locals, deriveds; ancestor-first), symbol keys, the `signal`/`local`/`derived` kind tags, effect/batched exclusion, count return + `arg` pass-through, the untracked-read law (snapshotOf inside an effect fires once), r7 `{name,hp,mp,alive}` parity, the PD-62 accessor-read reset honesty, and the fail-closed non-reactive/unwired/parked/disposed matrix |
 
 ### Emit-support matrix
 
@@ -486,13 +497,13 @@ Source hashes: `fixture.src.ts` `339c40148a70`, `static.src.ts` `81fb649965e6`,
 Process-isolated stress scenarios built on `@zakkster/lite-leak` + `@zakkster/lite-gc-profiler`:
 
 ```bash
-npm run torture             # all 17 scenarios (15 run + 2 floor-gated skips)
+npm run torture             # all 18 scenarios (16 run + 2 floor-gated skips)
 npm run torture:semantic    # the correctness lane (CI)
 npm run torture:soak        # the wall-clock churn + fleet soaks
 npm run torture:controls    # sabotage self-test: every scenario must FAIL when broken
 ```
 
-Seventeen scenarios: emit-matrix, ordering, lifecycle, pool-conservation, zero-GC lanes, capacity atomicity (every overflow point x both construction paths), the full disposed-poison surface + resurrection storms, a 4096-cycle lite-leak gate, a **300-seed x 20k-op oracle fuzzer** (decorated vs hand-wired raw twin in lockstep: every derived value, every effect fire count, every graph opcode tally), raw/decorated interop + cross-registry + `registry.destroy()` contracts, batch/untrack semantics, the `reinit-torture` acquire/release gate (4096 pooled cycles: `maxMajor 0`, retained delta-heap at/below the in-process zero-alloc control, exact pool conservation), the `localto-torture` gate (zero-alloc `@localTo` read/write storm at `maxMajor 0`, the ABA-stale write/reset interleave asserted AS the shipped contract, pooled park/reinit box+seen reset, tracking-edge and pure-compute-read pins), the wall-clock churn soak, and a 10s 2k-VM fleet soak -- plus two forward-compat scenarios (`scope-adoption`, `using-dispose`) that **skip correctly** while the installed peer sits below their per-feature floors (1.6.0 `createScope`, 1.9.0 `Symbol.dispose`). A skip below a floor is the design working; a skip at or above it is a FAIL. On the installed 1.5.0 peer: 15 pass, 2 skip. Every scenario carries a `TORTURE_BREAK` sabotage control that must exit non-zero -- a gate that cannot fail is not a gate. Seeded lanes replay exactly via `TORTURE_SEED`.
+Eighteen scenarios: emit-matrix, ordering, lifecycle, pool-conservation, zero-GC lanes, capacity atomicity (every overflow point x both construction paths), the full disposed-poison surface + resurrection storms, a 4096-cycle lite-leak gate, a **300-seed x 20k-op oracle fuzzer** (decorated vs hand-wired raw twin in lockstep: every derived value, every effect fire count, every graph opcode tally), raw/decorated interop + cross-registry + `registry.destroy()` contracts, batch/untrack semantics, the `reinit-torture` acquire/release gate (4096 pooled cycles: `maxMajor 0`, retained delta-heap at/below the in-process zero-alloc control, exact pool conservation), the `localto-torture` gate (zero-alloc `@localTo` read/write storm at `maxMajor 0`, the ABA-stale write/reset interleave asserted AS the shipped contract, pooled park/reinit box+seen reset, tracking-edge and pure-compute-read pins), the `introspection-torture` gate (1e6 hoisted-callback `forEachReactive` walks at `maxMajor 0` with control-relative minors, plus 1e5 `snapshotOf` cycles whose bytes/op are REPORTED in the summary line, never gated -- the snapshot allocates by design), the wall-clock churn soak, and a 10s 2k-VM fleet soak -- plus two forward-compat scenarios (`scope-adoption`, `using-dispose`) that **skip correctly** while the installed peer sits below their per-feature floors (1.6.0 `createScope`, 1.9.0 `Symbol.dispose`). A skip below a floor is the design working; a skip at or above it is a FAIL. On the installed 1.5.0 peer: 16 pass, 2 skip. Every scenario carries a `TORTURE_BREAK` sabotage control that must exit non-zero -- a gate that cannot fail is not a gate. Seeded lanes replay exactly via `TORTURE_SEED`.
 
 ### The cookbook lane (dev-side, never shipped)
 
@@ -547,6 +558,7 @@ The decorator vocabulary maps almost one-to-one; what changes is the lifetime st
 | `@action m()` | `@batched m()` |
 | `makeObservable(this, {...})` | `@reactiveHost` -- one wiring site, no mirror object to keep in sync |
 | `reaction(...)` / `autorun(...)` | `@reactiveEffect m()` |
+| `toJS(obj)` | `snapshotOf(vm)` -- a shallow plain-object copy of every member, read through the accessors under one `untrack` (safe inside an effect); nested VMs stay by reference (1.3.0) |
 | reaction disposers only; the instance itself is never disposable | **`disposeReactive(vm)` -- one call, idempotent, node-exact, and every later touch throws by name. MobX has no equivalent; its per-instance graph ends when the collector decides.** |
 
 ### From signal-utils
@@ -590,7 +602,7 @@ The cross-framework numbers behind this table are stamped in [`decisions/0006-ki
 
 ### The cookbook
 
-[`COOKBOOK.md`](https://github.com/PeshoVurtoleta/lite-signal-decorators/blob/main/COOKBOOK.md) collects eighteen composition recipes over the frozen 19-export surface -- how to build the things this package deliberately does not ship a decorator for, by composing the ones it does. Its headline is the **MobX-parity-by-composition matrix**, mapping each remaining MobX construct (`observable.array`, `observable.map`, `observable.deep`, `toJS`, `when`, `runInAction`, `observe`/`intercept`) to a decorator, a suite member, or a recipe -- extending the migration tables above to the rest of MobX with the honest note per row. It walks the **two-plane fleet** (a sim plane of arena columns written raw per frame beside a reactive plane of a handful of committed members), the reactive-collection-without-a-node-per-element pattern, and the **lite-store boundary** where document state meets class state -- stated plainly as the one path that is *not* zero-GC, and why. Every code block is byte-verified against a runnable, GC-gated companion in `cookbook/` (`npm run cookbook`), so a quoted recipe cannot drift from working code. It is delivered GitHub-only -- the installed tarball stays the lean 7-file runtime surface (decisions/0009).
+[`COOKBOOK.md`](https://github.com/PeshoVurtoleta/lite-signal-decorators/blob/main/COOKBOOK.md) collects eighteen composition recipes over the frozen 21-export surface -- how to build the things this package deliberately does not ship a decorator for, by composing the ones it does. Its headline is the **MobX-parity-by-composition matrix**, mapping each remaining MobX construct (`observable.array`, `observable.map`, `observable.deep`, `toJS`, `when`, `runInAction`, `observe`/`intercept`) to a decorator, a suite member, or a recipe -- extending the migration tables above to the rest of MobX with the honest note per row. It walks the **two-plane fleet** (a sim plane of arena columns written raw per frame beside a reactive plane of a handful of committed members), the reactive-collection-without-a-node-per-element pattern, and the **lite-store boundary** where document state meets class state -- stated plainly as the one path that is *not* zero-GC, and why. Every code block is byte-verified against a runnable, GC-gated companion in `cookbook/` (`npm run cookbook`), so a quoted recipe cannot drift from working code. It is delivered GitHub-only -- the installed tarball stays the lean 7-file runtime surface (decisions/0009).
 
 ---
 

package/SignalDecorators.d.ts

@@ -342,6 +342,57 @@ export function boxOf<T = unknown>(vm: object, key: PropertyKey): SignalBox<T> |
  */
 export function rootOf(vm: object): NodeDescriptor;
 
+// --- Reactive walk & snapshot (S9) --------------------------------------------
+
+/**
+ * The literal kind tag {@link forEachReactive} passes for each visited member: a
+ * `@reactive` signal, a `@localTo` local, or a `@derived` computed. Effects and
+ * batched actions are non-value-bearing and never appear.
+ */
+export type ReactiveKind = "signal" | "local" | "derived";
+
+/**
+ * Visit every value-bearing reactive member of `vm` in PLAN order -- all signals,
+ * then all `@localTo` locals, then all deriveds; within each group declaration-
+ * ordered and ancestor-first (a subclass's own members follow its ancestors').
+ * `@reactiveEffect` and `@batched` members are EXCLUDED -- they back no box.
+ * `fn` receives the member key (symbol keys included), the live {@link SignalBox}
+ * / {@link ComputedBox} (exactly what {@link boxOf} returns), the
+ * {@link ReactiveKind} literal, and the pass-through `arg` -- which threads caller
+ * state without a closure, so the walk is zero-allocation per call and per visit.
+ * Returns the number of members visited.
+ *
+ * @throws {TypeError} if `fn` is not a function.
+ * @throws {ReactiveDisposedError} if the instance was disposed or parked.
+ * @throws if `vm` is not wired yet, or is not a reactive instance.
+ */
+export function forEachReactive<A = unknown>(
+    vm: object,
+    fn: (
+        key: PropertyKey,
+        box: SignalBox<unknown> | ComputedBox<unknown>,
+        kind: ReactiveKind,
+        arg: A,
+    ) => void,
+    arg?: A,
+): number;
+
+/**
+ * Return a plain object snapshot of every value-bearing reactive member of `vm`
+ * -- signals, `@localTo` locals, and deriveds -- keyed by member key (symbol keys
+ * included). Each value is read through the ACCESSOR `vm[key]`, NOT the raw box,
+ * so `@localTo` compare-on-read and derived compute stay honest. SHALLOW by
+ * design: a nested reactive VM is copied by reference, never recursed. The whole
+ * read pass runs under one untracked scope when a tracking context is active, so
+ * calling this inside an effect does NOT subscribe that effect to every member.
+ * The returned object allocates by design -- this is a cold introspection call,
+ * never a gated hot path.
+ *
+ * @throws {ReactiveDisposedError} if the instance was disposed or parked.
+ * @throws if `vm` is not wired yet, or is not a reactive instance.
+ */
+export function snapshotOf(vm: object): Record<PropertyKey, unknown>;
+
 // --- Introspection & audit (S4) -----------------------------------------------
 
 /** The measured per-instance cost of a reactive class, returned by {@link costOf}. */

package/SignalDecorators.js

@@ -1,5 +1,5 @@
 /**
- * @zakkster/lite-signal-decorators v1.2.0
+ * @zakkster/lite-signal-decorators v1.3.0
  * --------------------
  * Standard-decorators layer over @zakkster/lite-signal. Turns a plain class into
  * a reactive view-model with measured per-instance cost and deterministic
@@ -447,7 +447,7 @@ function throwReinitInitialsKey(ctorName, key, plan) {
 function throwNoBox(ctorName, key, kind) {
     const what = kind === "effect" ? "@reactiveEffect" : "@batched";
     throw new Error(
-        `${ERR}boxOf(${ctorName}, ${keyLabel(key)}) -- ${keyLabel(key)} is a ${what} member and has no backing box; boxOf serves @reactive and @derived members only.`,
+        `${ERR}boxOf(${ctorName}, ${keyLabel(key)}) -- ${keyLabel(key)} is a ${what} member and has no backing box; boxOf serves @reactive, @localTo, and @derived members only.`,
     );
 }
 
@@ -1927,6 +1927,111 @@ export function rootOf(vm) {
     return a;
 }
 
+// --- Reactive walk & snapshot (S9; cold / opt-in) -----------------------------
+
+// Hoisted kind literals -- passed by forEachReactive so a walk carries zero
+// per-visit bytes beyond its four scalar args (no per-member string allocation).
+const KIND_SIGNAL = "signal";
+const KIND_LOCAL = "local";
+const KIND_DERIVED = "derived";
+
+function throwForEachFn() {
+    throw new TypeError(
+        `${ERR}forEachReactive(vm, fn) -- fn must be a function; it is called fn(key, box, kind, arg) once per reactive member.`,
+    );
+}
+
+/**
+ * Visit every value-bearing reactive member of `vm` in PLAN order -- all signals,
+ * then all @localTo locals, then all deriveds; each group declaration-ordered and
+ * ancestor-first -- invoking `fn(key, box, kind, arg)` per member and returning
+ * the visit count. `box` is the live SignalBox/ComputedBox (exactly what boxOf
+ * returns); `kind` is the literal "signal" | "local" | "derived". @reactiveEffect
+ * and @batched members are EXCLUDED (non-value-bearing; boxOf refuses them). The
+ * `arg` pass-through threads caller state without a closure, so the walk is
+ * zero-allocation per call and per visit.
+ *
+ * @throws {TypeError} if `fn` is not a function.
+ * @throws {ReactiveDisposedError} if the instance was disposed or parked.
+ * @throws if `vm` is not wired yet, or is not a reactive instance.
+ */
+export function forEachReactive(vm, fn, arg) {
+    if (typeof fn !== "function") throwForEachFn();
+    const plan = planOf(vm);
+    if (plan === undefined) throwNoPlan("forEachReactive");
+    const a = vm[ANCHOR];
+    if (a === undefined) throwNotWired("forEachReactive");
+    if (a === DISPOSED) throw new ReactiveDisposedError(plan.ctorName, "<root>");
+    if (a === PARKED) throw new ReactiveDisposedError(plan.ctorName, "<root>", true);
+    let n = 0;
+    const sigs = plan.signals;
+    for (let i = 0; i < sigs.length; i++) {
+        const r = sigs[i];
+        const h = vm[r.slot];
+        if (h !== undefined && h[NONLIVE] === "prewired") throwPrewiredMember(plan.ctorName, r.key);
+        fn(r.key, h, KIND_SIGNAL, arg);
+        n++;
+    }
+    const locs = plan.locals;
+    for (let i = 0; i < locs.length; i++) {
+        const r = locs[i];
+        const h = vm[r.slot];
+        if (h !== undefined && h[NONLIVE] === "prewired") throwPrewiredMember(plan.ctorName, r.key);
+        fn(r.key, h, KIND_LOCAL, arg);
+        n++;
+    }
+    const ders = plan.deriveds;
+    for (let i = 0; i < ders.length; i++) {
+        const r = ders[i];
+        const h = vm[r.slot];
+        if (h !== undefined && h[NONLIVE] === "prewired") throwPrewiredMember(plan.ctorName, r.key);
+        fn(r.key, h, KIND_DERIVED, arg);
+        n++;
+    }
+    return n;
+}
+
+// snapshotOf's per-member visitor -- the forEachReactive walk contract
+// (key, box, kind, arg). snapshotOf IS forEachReactive's named in-package
+// consumer: the fill is ROUTED through the walk (0009 candidate 2 / 0013 (c)
+// admission ground), not a private duplicate. The carrier `arg` threads both the
+// instance and the output object so the visitor stays a hoisted, closure-free
+// function. The read is the ACCESSOR vm[key] (PD-62), NOT box.get -- so @localTo
+// compare-on-read and derived compute stay honest; `box`/`kind` are unused here,
+// which the walk contract permits (a consumer reads only the fields it needs).
+function snapshotVisit(key, box, kind, arg) {
+    arg.out[key] = arg.vm[key];
+}
+
+/**
+ * Return a plain `{}` snapshot of every value-bearing reactive member of `vm` --
+ * signals, @localTo locals, and deriveds -- keyed by member key (symbol keys
+ * included), each value read through the ACCESSOR `vm[key]` (so @localTo
+ * compare-on-read and derived compute stay honest). SHALLOW by design: a nested
+ * reactive VM is copied by reference, never recursed. The whole read pass runs
+ * under ONE untrack thunk when a tracking scope is active (the makeLocalSet
+ * idiom), so calling snapshotOf inside an effect does NOT subscribe the effect to
+ * every member. The returned object allocates by design -- this is a cold
+ * introspection call, never a gated hot path.
+ *
+ * @throws {ReactiveDisposedError} if the instance was disposed or parked.
+ * @throws if `vm` is not wired yet, or is not a reactive instance.
+ */
+export function snapshotOf(vm) {
+    const plan = planOf(vm);
+    if (plan === undefined) throwNoPlan("snapshotOf");
+    const a = vm[ANCHOR];
+    if (a === undefined) throwNotWired("snapshotOf");
+    if (a === DISPOSED) throw new ReactiveDisposedError(plan.ctorName, "<root>");
+    if (a === PARKED) throw new ReactiveDisposedError(plan.ctorName, "<root>", true);
+    const out = {};
+    const carrier = { vm, out };                 // allocates by design (cold call)
+    const reg = plan.reg;
+    if (reg.isTracking()) reg.untrack(() => forEachReactive(vm, snapshotVisit, carrier));
+    else forEachReactive(vm, snapshotVisit, carrier);
+    return out;
+}
+
 // --- Introspection & audit (S4; all cold / opt-in) ----------------------------
 
 function throwCostFactory() {
@@ -2254,4 +2359,4 @@ export function auditReactive(on) {
 // --- Version ------------------------------------------------------------------
 
 /** Package version. Kept in lockstep with package.json and llms.txt. */
-export const VERSION = "1.2.0";
+export const VERSION = "1.3.0";

package/llms.txt

@@ -1,6 +1,6 @@
 # @zakkster/lite-signal-decorators
 
-VERSION 1.2.0
+VERSION 1.3.0
 
 > Standard-decorators layer over @zakkster/lite-signal, built on the TC39
 > decorators proposal (Stage 2.7 since 2026-05; TS 5.x / Babel 2023-11 emit
@@ -22,7 +22,7 @@ zero decorator syntax, sharing the SAME core by function identity.
 slot for a poison handle, so any later read/write throws a named
 `ReactiveDisposedError`.
 
-## Exports (19)
+## Exports (21)
 
 - `reactive` -- `@reactive accessor x = v` (bare) or `@reactive({ equals })`
   (factory). Declares a per-instance signal.
@@ -89,6 +89,28 @@ slot for a poison handle, so any later read/write throws a named
   dispose.
 - `rootOf(vm) -> NodeDescriptor` -- the instance's anchor descriptor; feeds
   `forEachOwned` / lite-devtools. Throws `ReactiveDisposedError` after dispose.
+- `forEachReactive(vm, fn, arg) -> count` -- cold value-member walk. Calls
+  `fn(key, box, kind, arg)` once per value-bearing member and returns the visit
+  count. `kind` is `"signal" | "local" | "derived"`; `@reactiveEffect` and
+  `@batched` are EXCLUDED (non-value-bearing -- `boxOf` refuses them). Order is
+  PLAN order: signals, then locals, then deriveds, each declaration-ordered and
+  ancestor-first (never `Reflect.ownKeys`, so it is stable across reinit). Four
+  scalar args, zero descriptor object, and the `arg` pass-through kills the
+  caller's closure -- the walk is a gated zero-alloc body. Symbol-keyed members
+  are visited (`byKey` is a Map). Fails closed on a non-reactive, unwired,
+  parked, or disposed value with the same named errors as `rootOf`.
+- `snapshotOf(vm) -> plain object` -- a shallow plain-object copy of every
+  value-bearing member (signals + locals + deriveds), keyed by member key.
+  Values are read through the ACCESSOR `vm[key]` (NOT `box.get`), so a `@localTo`
+  compare-on-read resets honestly and a `@derived` computes on read. The whole
+  walk runs under ONE `reg.untrack` thunk when `reg.isTracking()`, so calling it
+  inside an effect subscribes to NOTHING. SHALLOW by design: a nested VM is
+  copied by reference, not recursed (recursion needs a seen-set + cycle law,
+  deferred to a named consumer). Symbol keys are included
+  (`Reflect.ownKeys` law). Fails closed on parked/disposed (named
+  `ReactiveDisposedError`) and non-reactive values. This export ALLOCATES by
+  design (the returned object; ~96 B/op measured) and is reported, never gated --
+  the walk under it stays zero-alloc.
 - `costOf(Factory) -> { nodes, links, signals, deriveds, effects }` -- the
   measured settled per-instance cost on the class's bound registry (frozen,
   cached). Double-probed: an inconclusive or polluted probe throws, never
@@ -104,7 +126,7 @@ slot for a poison handle, so any later read/write throws a named
   `FinalizationRegistry` reports any instance GC'd without `disposeReactive`.
 - `ReactiveDisposedError` -- `extends Error`, `name` `"ReactiveDisposedError"`,
   fields `className` and `key`.
-- `VERSION` -- `"1.2.0"`.
+- `VERSION` -- `"1.3.0"`.
 
 ## Registry law (one registry per host chain)
 
@@ -245,7 +267,10 @@ runtime exports plus `costOf`, `capacityFor`, `enableLabels`, `labelOf`, and
 0.3.0). 1.2.0 adds `localTo` (decisions/0013 strategic track, 0014 contract) as
 an additive MINOR -> 19 exports; the 1.0.0 canon (`makeGet`/`makeSet`/
 `makeDerivedGet`) stays byte-identical -- @localTo ships its own accessor bodies
-and pays its own measured cost. The semver promise from here: any change to an existing export's
+and pays its own measured cost. 1.3.0 adds `forEachReactive` + `snapshotOf`
+(decisions/0013 ladder) as an additive MINOR -> 21 exports; `snapshotOf` is the
+named in-package consumer that admits `forEachReactive` under the 0009 bar, and
+the 1.0.0 canon stays byte-identical. The semver promise from here: any change to an existing export's
 signature or behavior is a MAJOR, recorded in a decision file; new exports are
 minors; the hot accessor canon (`makeGet`/`makeSet`) does not move without a
 major. Also present since

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-signal-decorators",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Standard-decorators layer over @zakkster/lite-signal (TC39 decorators proposal, Stage 2.7 since 2026-05; TS 5.x / Babel 2023-11 emit unchanged). The reactive class layer where an instance has a measured cost, deterministic teardown, and a churn benchmark.",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
   "license": "MIT",