@zakkster/lite-signal-decorators 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -4,6 +4,116 @@ All notable changes to `@zakkster/lite-signal-decorators` are documented here.
 The format follows Keep a Changelog; this project adheres to Semantic
 Versioning.
 
+## [1.4.0] - 2026-08-30
+
+The measured-instance pillar -- decisions/0013 criterion (b). `costOf(Factory)`
+answers "what will an instance of this class cost" by probing with NO ctor args,
+so a ctor-arg-dependent shape needs a measurement-twin class to size it;
+decisions/0009 candidate 4 recorded that absence plainly (r9 and the fleet demo
+both paid it). `costOfInstance(vm)` closes it: it measures a LIVE, wired instance
+by walking its OWN graph -- no probe, no twin, no registry pollution. The demo is
+the NAMED consumer that admits it under the 0009 bar (a new export needs a named
+consumer, and a recipe is not one): the console's shape-drift wall now measures a
+real `Entity` and the HUD reports a live fleet member's cost per tick. The
+`EntityShape` twin is honestly retained -- its remaining job is `capacityFor`
+sizing only (the world must be sized before it exists). Surface 21 -> 22.
+
+### Added
+
+- **`costOfInstance(vm) -> { nodes, links, signals, locals, deriveds, effects }`**
+  (22nd export) -- the LIVE per-instance cost, walked from the instance's own
+  graph: `nodes = 1 (anchor) + plan.signals.length + plan.locals.length +
+  forEachOwned(rootOf(vm))` (the deriveds and user effects the anchor adopted --
+  signal/local boxes are built pre-anchor and unadopted, so they are never
+  owned); `links` is the un-deduped sum of `forEachSource` over the anchor, every
+  owned node, and every signal/local box (one edge per observer, matching
+  `costOf`'s activeLinks delta); kind counts are read from the plan arrays, never
+  walked. THE LIVE-VS-PROBE CONTRACT is the feature: `costOf` forces every derived
+  to the constructed CEILING, `costOfInstance` reports what THIS instance costs
+  right now -- an unforced lazy derived or an untaken dynamic branch shows FEWER
+  links until the graph is exercised (`nodes` matches regardless; read every
+  derived once and the two agree exactly). UNCACHED (PD-70) -- a live graph
+  mutates, so a cached number would lie. Needs no `stats()` ledger (PD-72), so it
+  measures instances on hand-rolled registries where `costOf` fails closed.
+  Allocates its frozen result by design (one object per call, cold like
+  `snapshotOf`; PD-69, no out-param variant). Fails closed on a disposed/parked
+  instance with a NAMED `ReactiveDisposedError` (PD-71 -- a parked vm holds ZERO
+  nodes and a silent `{ nodes: 0 }` is indistinguishable from a bug) and on
+  unwired/no-plan/prewired-member values.
+- **`test/19-cost-instance.test.mjs`** (22 cases) -- both emit lanes + buildless:
+  A1 parity-when-forced (=== `costOf`, nodes/links/every kind count), A2
+  delta-when-lazy (links strictly lower, then monotonic toward the forced
+  number), a `@localTo` member counted in locals contributing ZERO graph links,
+  the frozen `{nodes,links,signals,locals,deriveds,effects}` shape, A3
+  registry-untouched over 10000 calls, PD-72 bound-registry + stats-less-facade
+  measurement (where `costOf` fails closed), PD-70 uncached/live across a branch
+  flip, and the A6 fail-closed matrix (plain/unwired/parked/disposed each a NAMED
+  throw, never a `{nodes:0}` report).
+- **The `introspection-torture` lane extended** with two `costOfInstance`
+  blocks: A4 -- 1e4 calls at `maxMajor 0`, `maxPauseMs <= 4.0`, the per-call
+  frozen result the only allocation (REPORTED, never gated); A5 -- 1000
+  wire/measure/park/reinit/dispose cycles with `tracker.size()` 0, `activeNodes`
+  to exact baseline, pool growths 0.
+- **The demo consumer** (never cut -- the admission ground): the console's
+  shape-drift wall measures a real live `Entity` via `costOfInstance` (its node
+  count === the sizing twin's) and the HUD reports one live fleet member's
+  `costOfInstance` per HUD tick (never per frame), so the live-vs-forced delta is
+  visible on screen. Cold boot / HUD-tick paths only; zero frame-loop cost.
+
+### Changed
+
+- **The export surface: 21 -> 22** -- 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: `costOfInstance`
+  is cold and moves no accessor byte.
+- Version sync to 1.4.0 across FOUR sites now: `package.json`, the `VERSION`
+  const, `llms.txt` line 3, and the `SignalDecorators.d.ts` VERSION literal --
+  the last a NEW asserted sync site. The `.d.ts` literal had gone stale (it read
+  a prior version, escaping the three-place sweep since the d.ts VERSION line was
+  never gated); the owner caught it, so `test/15`'s VERSION-consistency test
+  gains a FOURTH leg that regexes the `.d.ts` literal and asserts it string-equals
+  `package.json`, killing that bug class.
+- `test/15` surface-freeze recount 21 -> 22 (all CB-A2 sites).
+
+### Measured (rig: Node v26.3.1, arm64 Apple M4 Pro, lite-signal 1.5.0)
+
+- A1 parity (forced): `costOfInstance(vm)` === `costOf(Factory)` for the same
+  shape once every derived is read once -- demo `Entity` nodes **7**, links
+  **3** (P2/L1/D2/E1), both paths identical; kind counts identical.
+- A2 delta (lazy): a fresh instance reads links **1 -> 2 -> 3** as its deriveds
+  are exercised, strictly below the forced number until the graph is exercised;
+  node counts equal throughout.
+- A standalone `@localTo` member contributes **ZERO** graph links (the upstream
+  compare is a plain per-instance slot, not an edge) -- measured, not assumed; it
+  counts in `locals` only.
+- 1e4 `costOfInstance` calls: **71.3 B/op** (the per-call frozen result), gc
+  major **0**, `maxPauseMs <= 4.0` -- REPORTED, never gated.
+- A3: 10000 calls leave the registry `stats()` snapshot byte-identical
+  (`activeNodes`/`activeLinks`/`totalDisposals` unchanged) -- the walk never
+  mutates the registry.
+- A5: 1000 wire/measure/park/reinit/dispose cycles -- `tracker.size()` 0,
+  `activeNodes` to exact baseline, pool growths 0.
+
+Records: decisions/0013 (strategic-admission track, criterion (b)),
+decisions/0009 (candidate 4, 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 -- 335 pass / 0 fail
+  test:gc               OK       exit 0 -- 335 pass / 0 fail
+  torture               OK       exit 0 -- 16 passed, 2 skipped, 0 warned, 0 failed in 34.3s
+  torture:controls      OK       exit 0 -- 18 passed, 0 skipped, 0 warned, 0 failed in 3.6s
+  torture:peer-preview  REPORTED NON-BLOCKING -- lane completed (exit 0) [preview 1.9.0-preview.6 SUITE-GREEN 18/0/0/0; canary 1.9.0-canary.1 SUITE-GREEN 18/0/0/0]
+  bench:selftest        OK       exit 0 -- ALL PASS -- 22 passed, 0 failed
+  cookbook              OK       exit 0/0 -- corpus 18/18 companions ok in 2.1s; controls 8/8 controls fail correctly in 5.1s
+  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.3.0] - 2026-08-30
 
 The introspection/migration rung of the decisions/0013 strategic-admission

package/README.md

@@ -147,6 +147,7 @@ const ReactivePlayer = defineReactive(Player, {
 - **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.
+- **Live per-instance cost (1.4.0)** -- `costOfInstance(vm)` walks one wired instance's own graph and reports what it costs RIGHT NOW: `costOf(Factory)` answers "what will an instance of this class cost" (it forces every derived to the constructed ceiling), `costOfInstance` answers "what does THIS instance cost" -- an unforced lazy derived or an untaken branch shows fewer links until the graph is exercised, and reading every derived once makes the two agree exactly. Twin-free: it needs no stats() ledger, so it measures instances on hand-rolled registries where `costOf` fails closed.
 
 ---
 
@@ -270,10 +271,20 @@ Symbol keys work (`Reflect.ownKeys`). A spec key colliding with an own property
 | Export | Signature | Behavior |
 |---|---|---|
 | `costOf` | `(Factory) => { nodes, links, signals, deriveds, effects }` | The measured, settled per-instance cost, probed on the class's bound registry (frozen result, cached per class). Double-probed: an inconclusive or polluted probe THROWS -- never a guess. `nodes` is exactly P + L + D + E + 1; `links` is the first-full-read link count. |
+| `costOfInstance` (1.4.0) | `(vm) => { nodes, links, signals, locals, deriveds, effects }` | The LIVE cost of one wired instance right now, walked from its own graph -- no probe, no ctor args, no registry pollution. The delta from `costOf` IS the feature: `costOf` forces every derived to the constructed CEILING ("what will an instance of this class cost"), `costOfInstance` reports "what does THIS instance cost right now" -- an unforced lazy derived or an untaken branch has formed no links, so `links` reads BELOW `costOf` until the graph is exercised (`nodes` matches regardless; read every derived once and the two agree exactly). UNCACHED -- a live graph mutates, so a cached number would lie. Needs no stats() ledger, so it measures instances on hand-rolled registries where `costOf` fails closed. Allocates its frozen result by design (one object per call, ~71 B/op -- reported, never gated). Fails closed on a disposed/parked instance with a NAMED throw (a parked vm holds zero nodes; a silent `{ nodes: 0 }` is indistinguishable from a bug) and on unwired/no-plan/prewired values. |
 | `capacityFor` | `(inventory, { headroom }?) => RegistryConfig` | Sizes a `createRegistry` config from `[Factory, count]` pairs: nodes exact, links x `headroom` (floored at the engine minimum of 1), `prealloc: "eager"`, `onCapacityExceeded: "throw"`. Fail-closed inventory and options validation. Link policy + caveats: [decisions/0007](decisions/0007-capacity-policy.md). |
 | `enableLabels` / `labelOf` | `(on)` / `(idOrHandle, registry?) => string \| undefined` | Opt-in devtools identity (default OFF): while on, wiring registers per-registry `nodeId -> "Class.prop"` / `"Class#method"` / `"Class@anchor"`; dispose unregisters. `labelOf` misses return `undefined`, never throw. |
 | `auditReactive` | `(on)` | Opt-in leak auditor (default OFF): a lazily-created `FinalizationRegistry` reports any instance collected WITHOUT `disposeReactive`, naming class and shape. Holds no instance references itself; zero cost and zero registrations while off. |
 
+The `costOf`/`costOfInstance` split reads as a class-vs-instance pair:
+
+```js
+const cls = costOf(Enemy);            // ceiling: every derived forced
+const fresh = costOfInstance(inst);   // fresh.links < cls.links (a lazy derived unread)
+inst.threat; inst.range;              // exercise the deriveds, then re-measure
+costOfInstance(inst).links === cls.links;  // now exact
+```
+
 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)
@@ -288,7 +299,7 @@ With labels and audit off, the zero-GC budgets are byte-identical to 0.3.0 -- th
 | Export | Value |
 |---|---|
 | `ReactiveDisposedError` | `extends Error`; `name: "ReactiveDisposedError"`; fields `className`, `key`. Thrown on ANY touch of a disposed instance's surface. |
-| `VERSION` | `"1.3.0"` |
+| `VERSION` | `"1.4.0"` |
 
 ### The rejection matrix
 
@@ -408,10 +419,11 @@ The ~7 ns over raw batch is the guarded thunk + rest-array the decorator allocat
 | `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 |
+| `costOfInstance(vm)` | 1 frozen object | **by design** -- the per-call frozen result allocates (**71.3 B/op measured**, 1e4 calls); the measurement itself is `gc.major === 0` over those 1e4 calls -- REPORTED, never gated. The graph walk *under* it allocates nothing (module-slot visitors, no per-call closure); cold, off any frame path |
 
-The gates that hold it (run on every change, all green at 1.3.0):
+The gates that hold it (run on every change, all green at 1.4.0):
 
-- `npm test` / `npm run test:gc` -- **313/313** on both lanes.
+- `npm test` / `npm run test:gc` -- **335/335** 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: **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.
@@ -445,12 +457,12 @@ Full rationale lives in [`decisions/`](decisions/) -- each is a numbered, dated
 ## Testing (for clients & QA)
 
 ```bash
-npm test            # node --test, 313 tests
-npm run test:gc     # the same 313 with --expose-gc (enables the allocation assertions)
+npm test            # node --test, 335 tests
+npm run test:gc     # the same 335 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
 ```
 
-**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.
+**335 tests** across nineteen files, all green at 1.4.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 |
 |---|---:|---|
@@ -468,10 +480,11 @@ 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 21 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 22 exports), citation allowlist, link law, static-cost probe, and the four-place VERSION sync (module const === package.json === llms.txt === `SignalDecorators.d.ts` literal) |
 | `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 |
+| `19-cost-instance` | 22 | `costOfInstance` on both emit lanes + buildless: A1 parity-when-forced (=== `costOf`, nodes/links/every kind count), A2 delta-when-lazy (links strictly lower, then monotonic toward the forced number), `@localTo` counted in locals with zero graph links, the frozen `{nodes,links,signals,locals,deriveds,effects}` shape, A3 registry-untouched over 10000 calls, PD-72 bound-registry + stats-less-facade measurement (where `costOf` fails closed), PD-70 uncached/live across a branch flip, and the A6 fail-closed matrix (plain/unwired/parked/disposed each a NAMED throw, never a `{nodes:0}` report) |
 
 ### Emit-support matrix
 
@@ -528,6 +541,8 @@ npm run demo:gc             # headless GC-budget lane over the fleet core (maxMa
 npm run demo:storm          # headless dispose-storm retention lane (lite-leak, size 0)
 ```
 
+Since 1.4.0 the console is the named consumer of `costOfInstance`: its shape-drift wall measures a real live `Entity` (its node count === the `EntityShape` sizing twin's) and the HUD reports one live fleet member's `costOfInstance` per HUD tick, so the live-vs-`costOf` delta -- a forced ceiling against the lazy live cost -- is visible on screen. The `EntityShape` twin stays for `capacityFor` sizing only (the world must be sized before it exists).
+
 The `demo/` directory is dev-only -- it never enters `package.json` `files[]` and never ships to consumers.
 
 ---
@@ -602,7 +617,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 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).
+[`COOKBOOK.md`](https://github.com/PeshoVurtoleta/lite-signal-decorators/blob/main/COOKBOOK.md) collects eighteen composition recipes over the frozen 22-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

@@ -425,6 +425,34 @@ export interface ReactiveCost {
  */
 export function costOf(Factory: new (...args: any[]) => any): Readonly<ReactiveCost>;
 
+/**
+ * Measure the cost of ONE live, wired instance right now -- no probe, no
+ * construction, no ctor args, no registry pollution. Returns a per-call frozen
+ * `ReactiveCost` in costOf's exact shape, WALKED from the live graph:
+ * `nodes = 1 + signals + locals + forEachOwned(rootOf(vm))` (the deriveds and
+ * user effects the anchor adopted), and `links` is the un-deduped sum of
+ * forEachSource over the anchor, every owned node, and every signal/local box.
+ *
+ * THE LIVE-VS-PROBE CONTRACT. This number is the truth NOW. costOf forces every
+ * derived to report the constructed CEILING; costOfInstance reports what THIS
+ * instance costs at this moment, so an unforced lazy derived or an untaken
+ * dynamic branch shows FEWER links than costOf for the same shape until the graph
+ * is exercised. `nodes` matches regardless. Read every derived once and the two
+ * agree exactly. The delta is the feature, not a bug.
+ *
+ * The frozen result allocates by design, one object per call (UNCACHED -- a live
+ * graph mutates, so a cached number would lie). The walk needs no stats() ledger,
+ * so costOfInstance measures instances on registries where costOf fails closed.
+ *
+ * @param vm a live, wired reactive instance.
+ * @throws {ReactiveDisposedError} if `vm` was disposed or parked (a parked vm
+ *   holds zero nodes; a silent `{ nodes: 0 }` would be indistinguishable from a
+ *   bug, so both fail closed).
+ * @throws if `vm` is not wired yet, has no reactive plan, or exposes a prewired
+ *   member slot.
+ */
+export function costOfInstance(vm: object): Readonly<ReactiveCost>;
+
 /** A `[Factory, count]` pair for {@link capacityFor}. */
 export type InventoryEntry = [new (...args: any[]) => any, number];
 
@@ -503,4 +531,4 @@ export class ReactiveDisposedError extends Error {
 // --- Version ------------------------------------------------------------------
 
 /** Package version. Kept in lockstep with package.json and llms.txt. */
-export const VERSION: "1.0.0";
+export const VERSION: "1.4.0";

package/SignalDecorators.js

@@ -1,5 +1,5 @@
 /**
- * @zakkster/lite-signal-decorators v1.3.0
+ * @zakkster/lite-signal-decorators v1.4.0
  * --------------------
  * Standard-decorators layer over @zakkster/lite-signal. Turns a plain class into
  * a reactive view-model with measured per-instance cost and deterministic
@@ -45,6 +45,8 @@ import {
     batch,
     untrack,
     stats,
+    forEachOwned,
+    forEachSource,
 } from "@zakkster/lite-signal";
 
 // --- Module state -------------------------------------------------------------
@@ -172,6 +174,14 @@ const DEFAULT_REG = Object.freeze({
     // wiring/dispose paths use); costOf reads it here for the default registry,
     // and every custom Registry from createRegistry() exposes it natively.
     stats,
+    // `forEachOwned`/`forEachSource` join the facade the same way (S10): each
+    // registry owns its NODE_PTR symbol, so a handle is walkable ONLY by the
+    // registry that minted it. costOfInstance routes its walk through a plan's
+    // own `reg`, so the default-registry path needs these two here; a custom
+    // Registry from createRegistry() carries them natively. Not in REG_METHODS
+    // (the wiring/dispose paths never walk).
+    forEachOwned,
+    forEachSource,
 });
 
 // The 11 method names a valid Registry must expose (duck-check set, PD-11).
@@ -2132,6 +2142,122 @@ export function costOf(Factory) {
     return result;
 }
 
+// Module-level walk accumulators for costOfInstance. forEachOwned/forEachSource
+// call fn(descriptor) with NO carrier arg, so the visitor cannot thread state
+// through a parameter the way forEachReactive's `arg` does. Reusing three module
+// slots (never a per-call closure) keeps the frozen result the ONLY allocation
+// (PD-69). Non-reentrant by construction: a cost walk never re-enters
+// costOfInstance, so the single-threaded ESM model makes the shared slots safe.
+let COST_INSTANCE_REG = null;
+let COST_INSTANCE_OWNED = 0;
+let COST_INSTANCE_LINKS = 0;
+
+// Tally one source edge (called per forEachSource visit across anchor, owned
+// nodes, and signal/local boxes).
+function costInstanceLinkVisit(node) {
+    COST_INSTANCE_LINKS++;
+}
+
+// Tally one owned node (a derived or user effect adopted by the anchor) and fold
+// its source edges into the link total in the same pass.
+function costInstanceOwnedVisit(node) {
+    COST_INSTANCE_OWNED++;
+    COST_INSTANCE_REG.forEachSource(node, costInstanceLinkVisit);
+}
+
+/**
+ * Measure the cost of ONE live, wired instance right now -- no probe, no
+ * construction, no ctor args, no registry pollution. Returns a per-call frozen
+ * `{ nodes, links, signals, locals, deriveds, effects }` in costOf's exact shape.
+ * `nodes` is WALKED: 1 (the anchor) + plan.signals.length + plan.locals.length +
+ * every child forEachOwned(rootOf(vm)) yields (the deriveds and user effects the
+ * anchor adopted -- signal/local boxes are built pre-anchor and unadopted, so
+ * they are never owned). `links` is the sum of forEachSource over the anchor,
+ * every owned node, and every signal/local box, WITHOUT dedupe -- one edge per
+ * observer, matching costOf's activeLinks delta. Kind counts are read from the
+ * plan arrays, never walked.
+ *
+ * THE LIVE-VS-PROBE CONTRACT. This number is the truth NOW. costOf constructs a
+ * throwaway probe and FORCES every derived (:2079) to report the constructed
+ * CEILING -- "what will an instance of this class cost". costOfInstance reports
+ * what THIS instance costs at this moment: an unforced lazy derived and an
+ * untaken dynamic branch have formed no links yet, so `links` reads BELOW
+ * costOf's for the same shape until the graph is exercised. `nodes` matches
+ * regardless (owned children exist whether or not their links have formed). Read
+ * every derived once and the two agree exactly (A1 parity). The delta is the
+ * feature, not a bug -- fewer links means the instance has not paid for a branch
+ * it has not taken.
+ *
+ * ALLOCATION HONESTY. The frozen result allocates by design, one object per call,
+ * exactly like snapshotOf -- this is a cold introspection call, never a gated hot
+ * path (PD-69). There is no out-param variant; no consumer needs one. The walk
+ * itself allocates nothing (module-slot visitors, no per-call closure).
+ *
+ * UNCACHED (PD-70). costOf caches per class because a class shape is frozen at
+ * decoration; a live instance graph MUTATES (a derived forces, a branch flips),
+ * so a cached number would lie. Every call re-walks.
+ *
+ * WORKS WHERE costOf CANNOT (PD-72). The walk needs no stats() ledger, so
+ * costOfInstance measures an instance on a hand-rolled registry that carries the
+ * introspection walkers but not stats -- exactly the case costOf fails closed on
+ * (:2049).
+ *
+ * @throws {ReactiveDisposedError} if the instance was disposed or parked -- a
+ *   parked vm holds ZERO nodes, and a silent `{ nodes: 0 }` is indistinguishable
+ *   from a bug, so both states fail closed (PD-71).
+ * @throws if `vm` is not wired yet, has no reactive plan, or exposes a prewired
+ *   member slot.
+ */
+export function costOfInstance(vm) {
+    const plan = planOf(vm);
+    if (plan === undefined) throwNoPlan("costOfInstance");
+    const a = vm[ANCHOR];
+    if (a === undefined) throwNotWired("costOfInstance");
+    if (a === DISPOSED) throw new ReactiveDisposedError(plan.ctorName, "<root>");
+    if (a === PARKED) throw new ReactiveDisposedError(plan.ctorName, "<root>", true);
+    const reg = plan.reg;
+    COST_INSTANCE_REG = reg;
+    COST_INSTANCE_OWNED = 0;
+    COST_INSTANCE_LINKS = 0;
+    // Owned nodes = deriveds + user effects the anchor adopted; each contributes
+    // its source edges to the link tally as it is visited. Signals/locals are
+    // built pre-anchor (unadopted), so forEachOwned never yields them (:1234-1248).
+    reg.forEachOwned(a, costInstanceOwnedVisit);
+    // The anchor's own source edges.
+    reg.forEachSource(a, costInstanceLinkVisit);
+    // Signal + local boxes are not owned -- read each from its slot (the walker
+    // idiom from forEachReactive) and fold its source edges in. A prewired slot
+    // is impossible past the wired guard above, but the check fails closed if a
+    // partially-built instance is ever measured.
+    const sigs = plan.signals;
+    for (let i = 0; i < sigs.length; i++) {
+        const h = vm[sigs[i].slot];
+        if (h !== undefined && h[NONLIVE] === "prewired") throwPrewiredMember(plan.ctorName, sigs[i].key);
+        reg.forEachSource(h, costInstanceLinkVisit);
+    }
+    const locs = plan.locals;
+    for (let i = 0; i < locs.length; i++) {
+        const h = vm[locs[i].slot];
+        if (h !== undefined && h[NONLIVE] === "prewired") throwPrewiredMember(plan.ctorName, locs[i].key);
+        reg.forEachSource(h, costInstanceLinkVisit);
+    }
+    const sig = sigs.length;
+    const loc = locs.length;
+    const der = plan.deriveds.length;
+    const eff = plan.effects.length;
+    const nodes = 1 + sig + loc + COST_INSTANCE_OWNED;
+    const links = COST_INSTANCE_LINKS;
+    COST_INSTANCE_REG = null;                    // drop the registry ref (cold)
+    return Object.freeze({
+        nodes: nodes,
+        links: links,
+        signals: sig,
+        locals: loc,
+        deriveds: der,
+        effects: eff,
+    });
+}
+
 function throwCapInventory() {
     throw new TypeError(
         `${ERR}capacityFor(inventory) -- inventory must be a non-empty array of [Factory, count] pairs.`,
@@ -2359,4 +2485,4 @@ export function auditReactive(on) {
 // --- Version ------------------------------------------------------------------
 
 /** Package version. Kept in lockstep with package.json and llms.txt. */
-export const VERSION = "1.3.0";
+export const VERSION = "1.4.0";

package/llms.txt

@@ -1,6 +1,6 @@
 # @zakkster/lite-signal-decorators
 
-VERSION 1.3.0
+VERSION 1.4.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 (21)
+## Exports (22)
 
 - `reactive` -- `@reactive accessor x = v` (bare) or `@reactive({ equals })`
   (factory). Declares a per-instance signal.
@@ -116,6 +116,22 @@ slot for a poison handle, so any later read/write throws a named
   cached). Double-probed: an inconclusive or polluted probe throws, never
   guesses. `nodes` = P+L+D+E+1; `links` = the first-full-read link count. See
   "Introspection & audit".
+- `costOfInstance(vm) -> { nodes, links, signals, locals, deriveds, effects }` --
+  the LIVE measured cost of one wired instance right now, walked from its own
+  graph. The delta from `costOf` IS the feature: `costOf` answers "what will an
+  instance of this class cost" (it forces every derived to the constructed
+  ceiling), `costOfInstance` answers "what does THIS instance cost right now" --
+  an unforced lazy derived or an untaken dynamic branch has formed no links yet,
+  so `links` reads BELOW `costOf` for the same shape until the graph is
+  exercised; `nodes` matches regardless. Read every derived once and the two
+  agree exactly (forced parity === costOf). UNCACHED by design -- a live graph
+  mutates, so a cached number would lie; every call re-walks. Allocates its
+  frozen result by design (one object per call, ~71 B/op, cold like snapshotOf --
+  reported, never gated). Needs no stats() ledger, so it measures instances on
+  hand-rolled registries where `costOf` fails closed. Fails closed on a
+  disposed/parked instance with a NAMED throw -- a parked vm holds zero nodes and
+  a silent `{ nodes: 0 }` is indistinguishable from a bug -- and on unwired,
+  no-plan, or prewired-member values. See "Introspection & audit".
 - `capacityFor(inventory, { headroom }?) -> RegistryConfig` -- size a
   `createRegistry` config from `[Factory, count]` pairs. Nodes exact, links x
   `headroom` (default 1). Fail-closed inventory validation.
@@ -126,7 +142,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.3.0"`.
+- `VERSION` -- `"1.4.0"`.
 
 ## Registry law (one registry per host chain)
 
@@ -270,7 +286,9 @@ an additive MINOR -> 19 exports; the 1.0.0 canon (`makeGet`/`makeSet`/
 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
+the 1.0.0 canon stays byte-identical. 1.4.0 adds `costOfInstance` (decisions/0013
+criterion (b); the demo is the named consumer) as an additive MINOR -> 22
+exports; 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.3.0",
+  "version": "1.4.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",