@zakkster/lite-signal-decorators 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,131 @@ All notable changes to `@zakkster/lite-signal-decorators` are documented here.
 The format follows Keep a Changelog; this project adheres to Semantic
 Versioning.
 
+## [0.4.0] - 2026-08-26
+
+The introspection release: the surface grows 11 -> 16, every addition cold-path
+or opt-in, the hot accessor canon byte-identical to 0.3.0 (review-diffed
+against the published tarball). Stage gate, measured at closeout: 213/213
+tests on both lanes; torture 15 scenarios (13 pass + the two forward-compat
+scenarios legitimately skipping under the installed 1.5.0 peer) with 15/15
+sabotage controls breaking as required; the peer-preview lane SUITE-GREEN
+(15/15, forward scenarios RUNNING) against lite-signal 1.9.0-preview.6 AND
+1.9.0-canary.1; pack 7 files.
+
+### Added
+
+- `costOf(Factory)` -- the measured, settled per-instance cost on the class's
+  bound registry: `{ nodes, links, signals, deriveds, effects }`, frozen and
+  cached per class. Quiet-required, floor-verified, DOUBLE-probed with
+  identical-deltas-or-throw: an inconclusive probe (a derived whose read set
+  changes between runs, a polluted registry) throws a named error, never
+  guesses. `nodes` reproduces the 0002 Q3 grid exactly (P + D + E + 1);
+  `links` is the first-full-read count.
+- `capacityFor(inventory, { headroom }?)` -- sizes a ready `createRegistry`
+  config from `[Factory, count]` pairs: nodes exact, links x `headroom`
+  floored at the engine minimum, `prealloc: "eager"`,
+  `onCapacityExceeded: "throw"`; fail-closed inventory and options
+  validation. The link-headroom policy -- nodes exact; fixed-shape deriveds
+  provision exactly at first-full-read; branchy-read deriveds fail LOUD with
+  the `headroom` knob as the documented escape -- is recorded with its
+  measured evidence in `decisions/0007-capacity-policy.md`, closing 0002's
+  open question.
+- `enableLabels(on)` / `labelOf(idOrHandle, registry?)` -- opt-in devtools
+  identity (default OFF): per-registry `nodeId -> "Class.prop" /
+  "Class#method" / "Class@anchor"` maps, per-class shared label strings,
+  dispose unregisters, misses return `undefined`. A feature-detected
+  integration test walks lite-devtools `graph()`/`toTree` from `rootOf(vm)`
+  and resolves every walked node. The one-line devtools `labelResolver`
+  upstream proposal is recorded in `decisions/0008-introspection.md`.
+- `auditReactive(on)` -- opt-in leak auditor (default OFF): a lazily-created
+  `FinalizationRegistry` reports any instance collected without
+  `disposeReactive`, naming class and shape; it holds no instance references
+  itself, unregisters on dispose, and registers nothing while off (proven by
+  a child-process `--expose-gc` test).
+- Forward-compat torture: `scope-adoption` (floor 1.6.0) and `using-dispose`
+  (floor 1.9.0), written against the REAL probed future engine surfaces
+  (1.6.0's `createScope` adoption; 1.9.0's native `[Symbol.dispose]` on
+  handles) via a typeof-only feature probe (`test/shared/peer-probe.mjs` --
+  never version parsing). Their sabotage controls lie about the probe, so
+  they fail loudly even under the current peer. Plus `torture:peer-preview`:
+  a scratch-install lane that runs the whole suite against the peer's
+  `preview` and `canary` dist-tags and reports per-tag verdicts.
+- Tests: `12-accounting` (11), `13-labels-audit` (10, incl. the child-process
+  audit fixture), `14-qa-s4-boundary` (21 adversarial pins), and two
+  capacityFor round-trip lanes (node-bound and link-bound) in
+  capacity-torture. Suite 171 -> 213. Dev-only devDependency:
+  `@zakkster/lite-devtools` (integration walk).
+
+### Fixed
+
+- (Found in review) A registry passing the 11-method duck-check but lacking
+  `stats()` -- constructible from the public surface -- made `costOf` and
+  `capacityFor` die with a raw `TypeError` instead of a named error. Now a
+  named, ERR-prefixed throw explains that probing needs a `createRegistry()`
+  registry with its stats ledger. The falsified "no reachable raw path"
+  claim in 0008 is amended with the counterexample preserved, rejection-
+  history style.
+- (Found in QA) `capacityFor`'s options guard borrowed decorator-flavored
+  usage wording for a plain function call, and accepted an ARRAY as an
+  options bag; it now throws the call-form message
+  (`options must be a plain object like { headroom: 1.25 }`) for both.
+  `null` still means "omitted".
+- (Found writing tests) `capacityFor` on a signals-only inventory produced
+  `maxLinks: 0`, which `createRegistry` rejects; the returned links are now
+  floored at the engine minimum of 1 so every valid inventory yields a
+  constructible config.
+
+## [0.3.0] - 2026-08-26
+
+The class-reactivity benchmark release. Zero runtime changes: the 11-export
+surface ships logic-identical to 0.2.0 (version constants aside); what this
+release adds is the proof. Stage gate, all measured at closeout: 171/171
+tests on both lanes; torture 13 scenarios / 13 sabotage controls all
+green-and-breakable; the full benchmark matrix 42/42 lanes `sink=ok`, exit 0.
+
+### Added
+
+- `bench/` -- a private, never-shipped benchmark sub-package: six admitted
+  engines (`lsd` decorators, `lsd-define` buildless, the `lite-raw-boxes`
+  honesty baseline, MobX 7, signal-utils + signal-polyfill, a hand-rolled
+  alien-signals class) x seven class-shaped scenarios (vm-write, fleet-read
+  and fleet-tick over 10k instances, cascade 64/16+aggregate, deep-vm 64-deep,
+  churn as the headline, retention as gates). Ported lite-signal rig: anti-DCE
+  sink with analytic expected-sum oracles (skipped work rejects the lane),
+  median-of-5 + min, GC-fenced runs with real delta/retained heap columns,
+  machine provenance stamps with resolved adapter versions, a sabotaged-adapter
+  self-test proving the harness can fail, and machine-gated effect liveness on
+  lifecycle lanes. Candidates `classy-solid` and `@reactively/decorate` probed
+  and excluded with recorded one-line blockers (solid's stock-Node SSR
+  resolution; legacy-only decorators). Reproducible from a clean clone:
+  `cd bench && npm install && npm run bench`.
+- `fleet-soak` -- the 13th torture scenario (soak group): 2000 VMs (16000 pool
+  nodes exactly) under sustained ticks with partial churn rotations for a
+  wall-clock budget; per-sample F-0, flat retained heap, gcGate maxMajor 0;
+  its sabotage control leaks one VM per rotation and is caught at the first
+  sample.
+- `decisions/0006-kill-criteria.md` -- the formal verdicts. Criterion 1 (the
+  2.0x line vs the hand-written instance-field baseline) CLEARED WITH MARGIN:
+  vm-write 0.94x, fleet-read 1.10x (parity, per 0003's tied-layout finding).
+  Criterion 2 (churn cleanliness) CLEARED: 0 major and 0 minor collections
+  over 4096 lifecycle cycles on every lite lane, pools at floor (asserted
+  in-lane), retained settled at-or-below baseline -- and the decorated churn
+  loop emits ~12.6x less transient garbage than the hand-rolled equivalent.
+  Every competitor number published under the same stamp (AD-6 honesty
+  tiering); the wide-shape cascade/deep-vm gap vs raw boxes is recorded as an
+  S4 investigation item, not hidden.
+
+### Changed
+
+- README: the measured-numbers section now cites the cross-framework matrix
+  and the 0006 verdicts alongside the package's own committed probes; version
+  references bumped.
+- CHANGELOG release links now point at the package `repository`
+  (github.com/PeshoVurtoleta/lite-signal-decorators), matching the new
+  `repository`/`homepage`/`funding` fields in package.json.
+- `llms.txt` scope note: 0.3.0 adds only dev-side proof; the export surface
+  is unchanged and frozen for 0.x.
+
 ## [0.2.0] - 2026-08-26
 
 The adversarial-torture release: the 0.2 surface is frozen for 0.x, proven by
@@ -54,9 +179,8 @@ gc major=0 minor=0`.
 
 ## [0.2.0-preview.1] - 2026-08-26
 
-The full runtime surface. Exports grow from 8 to 11. Never published: the
-preview publish was pending npm authentication when 0.2.0 superseded it; the
-changes below first shipped with 0.2.0.
+The full runtime surface. Exports grow from 8 to 11. Published under the
+`preview` dist-tag on the same day 0.2.0 went to `latest`.
 
 ### Added
 
@@ -152,6 +276,8 @@ Initial release -- the decorator core.
 - Torture skeleton (`@zakkster/lite-leak` + `@zakkster/lite-gc-profiler`):
   retention, conservation, lifecycle, and zero-GC lanes.
 
-[0.2.0]: https://github.com/zakkster/lite-signal-decorators/releases/tag/v0.2.0
-[0.2.0-preview.1]: https://github.com/zakkster/lite-signal-decorators/releases/tag/v0.2.0-preview.1
-[0.1.0]: https://github.com/zakkster/lite-signal-decorators/releases/tag/v0.1.0
+[0.4.0]: https://github.com/PeshoVurtoleta/lite-signal-decorators/releases/tag/v0.4.0
+[0.3.0]: https://github.com/PeshoVurtoleta/lite-signal-decorators/releases/tag/v0.3.0
+[0.2.0]: https://github.com/PeshoVurtoleta/lite-signal-decorators/releases/tag/v0.2.0
+[0.2.0-preview.1]: https://github.com/PeshoVurtoleta/lite-signal-decorators/releases/tag/v0.2.0-preview.1
+[0.1.0]: https://github.com/PeshoVurtoleta/lite-signal-decorators/releases/tag/v0.1.0

package/README.md

@@ -240,12 +240,23 @@ Symbol keys work (`Reflect.ownKeys`). A spec key colliding with an own property
 | `boxOf` | `(vm, key) => SignalBox \| ComputedBox` | The live engine box behind a `@reactive`/`@derived` member -- `.peek()`, `.subscribe()`, raw interop. Unknown key: named throw with a did-you-mean. After dispose: `ReactiveDisposedError`. |
 | `rootOf` | `(vm) => NodeDescriptor` | The instance's anchor descriptor -- feeds `forEachOwned` and lite-devtools. Throws `ReactiveDisposedError` after dispose. |
 
+### Introspection & audit (0.4.0)
+
+| 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 + D + E + 1; `links` is the first-full-read link count. |
+| `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. |
+
+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).
+
 ### Errors & constants
 
 | Export | Value |
 |---|---|
 | `ReactiveDisposedError` | `extends Error`; `name: "ReactiveDisposedError"`; fields `className`, `key`. Thrown on ANY touch of a disposed instance's surface. |
-| `VERSION` | `"0.2.0"` |
+| `VERSION` | `"0.4.0"` |
 
 ### The rejection matrix
 
@@ -348,7 +359,7 @@ The gates that hold it (run on every change, all green at 0.2.0):
 - Torture: **12/12 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) -- plus **12/12 sabotage controls** proving each gate can actually fail.
 - `churn-soak`: sustained construct/use/dispose for a wall-clock budget; pools at floor and retained heap flat at every sample.
 
-The cross-framework churn benchmark (vs MobX-style layers and signal-utils, with the same anti-DCE rig) is the 0.3.0 milestone; the numbers above are the package's own committed probes.
+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 seven class-shaped scenarios, 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.
 
 </details>
 
@@ -473,7 +484,7 @@ Because an instance whose base-class boxes live in one pool and whose subclass b
 No, and the README says so with numbers: 22.12 ns/op vs 15.25 raw vs 11.67 unbatched on the reference rig -- a thunk + rest-array per call. Use it for actions; keep per-frame writes on plain accessors.
 
 **Where are `costOf`, labels, the audit hook, private members?**
-Not in 0.2.0 -- the runtime surface is complete and frozen for 0.x, and the introspection layer is roadmapped behind the 0.3.0 benchmark. The `llms.txt` scope note tracks exactly what is and isn't included.
+The first three landed in 0.4.0 -- `costOf`/`capacityFor` (measured capacity accounting), `enableLabels`/`labelOf` (devtools identity), and `auditReactive` (leak audit), all cold-path or opt-in with the hot canon untouched. Private-member support remains out. The `llms.txt` scope note tracks exactly what is and isn't included.
 
 ---
 

package/SignalDecorators.d.ts

@@ -11,6 +11,8 @@ import type {
     ComputedBox,
     NodeDescriptor,
     Registry,
+    RegistryConfig,
+    ReactiveHandle,
     EffectScheduler,
 } from "@zakkster/lite-signal";
 
@@ -256,6 +258,97 @@ export function boxOf<T = unknown>(vm: object, key: PropertyKey): SignalBox<T> |
  */
 export function rootOf(vm: object): NodeDescriptor;
 
+// --- Introspection & audit (S4) -----------------------------------------------
+
+/** The measured per-instance cost of a reactive class, returned by {@link costOf}. */
+export interface ReactiveCost {
+    /** Total nodes = `signals + deriveds + effects + 1` (the anchor). */
+    nodes: number;
+    /** Dependency links held after every `@derived` has been read once (0007). */
+    links: number;
+    /** Count of `@reactive` members. */
+    signals: number;
+    /** Count of `@derived` members. */
+    deriveds: number;
+    /** Count of `@reactiveEffect` members. */
+    effects: number;
+}
+
+/**
+ * Measure the settled per-instance cost of a reactive class on its bound
+ * registry. Constructs a probe instance (with NO arguments), reads every
+ * `@derived` once to force the lazy links, disposes, and verifies the registry
+ * floor -- twice, requiring identical deltas. The result is frozen and cached
+ * per class.
+ *
+ * @param Factory the class returned by `@reactiveHost` or `defineReactive`.
+ * @throws if `Factory` is not a reactive wrapper class, if the two probes
+ *   disagree (a data-dependent read or a polluted registry -- costOf never
+ *   guesses), or if dispose does not return the registry to its floor.
+ */
+export function costOf(Factory: new (...args: any[]) => any): Readonly<ReactiveCost>;
+
+/** A `[Factory, count]` pair for {@link capacityFor}. */
+export type InventoryEntry = [new (...args: any[]) => any, number];
+
+/** Options for {@link capacityFor}. */
+export interface CapacityForOptions {
+    /**
+     * Link-budget multiplier (`>= 1`, default `1` = exact). Applied to the link
+     * total for workloads with dynamic-dependency (branchy) deriveds whose active
+     * branch can read more members than the probe measured. See decisions/0007.
+     */
+    headroom?: number;
+}
+
+/**
+ * Size a `createRegistry` config for a stated inventory of `[Factory, count]`
+ * pairs. Nodes are exact; links are `sum(cost.links x count)` scaled by
+ * `headroom`. Returns a ready `RegistryConfig` with `prealloc: "eager"` and
+ * `onCapacityExceeded: "throw"`.
+ *
+ * @throws on an empty inventory, a non-factory entry, a non-positive/non-integer
+ *   count, or a bad `headroom`.
+ */
+export function capacityFor(
+    inventory: InventoryEntry[],
+    options?: CapacityForOptions,
+): RegistryConfig;
+
+/**
+ * Toggle devtools labels (default OFF). While ON, wiring registers a
+ * `nodeId -> label` for every node an instance creates (`"Class.prop"`,
+ * `"Class#method"`, `"Class@anchor"`) into a per-registry map, and
+ * `disposeReactive` unregisters them. OFF adds no hot-path cost.
+ *
+ * @throws if `on` is not a boolean.
+ */
+export function enableLabels(on: boolean): void;
+
+/**
+ * Resolve a node id (or a handle, via the registry's `nodeId`) to its label, or
+ * `undefined` if unlabeled/unknown -- an introspection miss is never an error.
+ * `registry` defaults to the default registry.
+ */
+export function labelOf(
+    idOrHandle: number | ReactiveHandle | NodeDescriptor,
+    registry?: Registry,
+): string | undefined;
+
+/**
+ * Toggle the leak auditor (default OFF). While ON, a lazily-created
+ * `FinalizationRegistry` reports (one `console.error`) any instance
+ * garbage-collected WITHOUT `disposeReactive`, naming the class + shape. OFF: no
+ * `FinalizationRegistry` exists and nothing is registered.
+ *
+ * Note: an instance pinned by its own undisposed derived/effect nodes on a
+ * long-lived registry is never collected, so audit cannot fire for it -- that
+ * retention is caught by leak torture instead (see decisions/0008).
+ *
+ * @throws if `on` is not a boolean.
+ */
+export function auditReactive(on: boolean): void;
+
 // --- Errors -------------------------------------------------------------------
 
 /**
@@ -273,4 +366,4 @@ export class ReactiveDisposedError extends Error {
 // --- Version ------------------------------------------------------------------
 
 /** Package version. Kept in lockstep with package.json and llms.txt. */
-export const VERSION: "0.2.0";
+export const VERSION: "0.4.0";

package/SignalDecorators.js

@@ -1,5 +1,5 @@
 /**
- * @zakkster/lite-signal-decorators v0.2.0
+ * @zakkster/lite-signal-decorators v0.4.0
  * --------------------
  * Stage-3 decorator layer over @zakkster/lite-signal. Turns a plain class into
  * a reactive view-model with measured per-instance cost and deterministic
@@ -44,6 +44,7 @@ import {
     isTracking,
     batch,
     untrack,
+    stats,
 } from "@zakkster/lite-signal";
 
 // --- Module state -------------------------------------------------------------
@@ -85,10 +86,40 @@ const SCRATCH = [];
 // Hoisted package prefix (PD-15): every cold error message begins with this.
 const ERR = "@zakkster/lite-signal-decorators: ";
 
+// --- Introspection state (S4; all opt-in, all cold/off by default) -----------
+
+// PD-23/PD-24: labels and audit are opt-in debug features. INTROSPECT_ON is the
+// single wiring/dispose gate (= LABELS_ON || AUDIT_ON), so the OFF path pays at
+// most one flag test at wiring and one at dispose -- the hot accessor canon is
+// never touched in either mode.
+let LABELS_ON = false;
+let AUDIT_ON = false;
+let INTROSPECT_ON = false;
+
+// PD-23: per-registry nodeId -> label. nodeIds are per-registry, so a
+// module-global Map would collide across registries; the key is the plan's reg
+// object (DEFAULT_REG facade or a custom Registry).
+const LABEL_MAPS = new WeakMap();       // reg -> Map<number, string>
+// Per-plan label strings, built once at first labeled wiring and shared by every
+// instance of the class.
+const LABEL_STRINGS = new WeakMap();    // plan -> { anchor, signals[], deriveds[], effects[] }
+// The instance's registered label ids, so disposeReactive can unregister exactly
+// them (effect handles are otherwise discarded). Only written while LABELS_ON.
+const LABEL_IDS = Symbol("lite-signal-decorators.labelIds");
+
+// PD-24: costOf result cache (per wrapper class; shape is frozen at decoration).
+const COST_CACHE = new WeakMap();       // Factory -> frozen cost object
+
+// PD-24: the audit FinalizationRegistry is created lazily on first enable and
+// never torn down (a FR holds no strong refs to its targets). Its held value is
+// a plain { className, shape } record -- it must NOT close over the instance.
+let AUDIT_FR = null;
+
 // Known option keys per decorator (unknown-key did-you-mean sets, PD-8/PD-11).
 const KNOWN_OPTION_KEYS = ["equals"];
 const EFFECT_OPTION_KEYS = ["scheduler"];
 const HOST_OPTION_KEYS = ["registry"];
+const CAP_OPTION_KEYS = ["headroom"];
 
 // --- DEFAULT_REG facade (PD-11) ----------------------------------------------
 
@@ -107,6 +138,10 @@ const DEFAULT_REG = Object.freeze({
     isTracking,
     batch,
     untrack,
+    // `stats` is not in REG_METHODS (the duck-check stays at the 11 methods the
+    // wiring/dispose paths use); costOf reads it here for the default registry,
+    // and every custom Registry from createRegistry() exposes it natively.
+    stats,
 });
 
 // The 11 method names a valid Registry must expose (duck-check set, PD-11).
@@ -864,11 +899,22 @@ function wireInstance(inst, plan) {
             }
             // Effects wire AFTER every derived (D-4a): the first synchronous run
             // sees every field and every derived. Dispose handles are DISCARDED --
-            // teardown is the anchor cascade.
+            // teardown is the anchor cascade. The ONE introspection flag test
+            // (S4, PD-23/24): the OFF branch is byte-identical to 0.3.0; the ON
+            // branch captures effect handles for labeling + registers audit.
             const effs = plan.effects;
-            for (let i = 0; i < effs.length; i++) {
-                const e = effs[i];
-                reg.effect(makeEffectBody(inst, e.fn), e.opts);
+            if (INTROSPECT_ON) {
+                const effHandles = LABELS_ON ? [] : null;
+                for (let i = 0; i < effs.length; i++) {
+                    const h = reg.effect(makeEffectBody(inst, effs[i].fn), effs[i].opts);
+                    if (effHandles !== null) effHandles.push(h);
+                }
+                introspectWire(inst, plan, reg, effHandles);
+            } else {
+                for (let i = 0; i < effs.length; i++) {
+                    const e = effs[i];
+                    reg.effect(makeEffectBody(inst, e.fn), e.opts);
+                }
             }
         });
     } catch (e) {
@@ -1258,6 +1304,10 @@ export function disposeReactive(vm) {
             }
         }
     }
+    // S4 introspection cleanup (one flag test on the OFF dispose path): drop this
+    // instance's label entries and unregister it from the audit FR so a proper
+    // dispose is never mistaken for a silent death.
+    if (INTROSPECT_ON) introspectDispose(vm, reg);
     disposeCore(vm, plan);
     return true;
 }
@@ -1295,7 +1345,320 @@ export function rootOf(vm) {
     return a;
 }
 
+// --- Introspection & audit (S4; all cold / opt-in) ----------------------------
+
+function throwCostFactory() {
+    throw new TypeError(
+        `${ERR}costOf(Factory) -- Factory must be a @reactiveHost / defineReactive wrapper class.`,
+    );
+}
+
+function throwCostNoPlan() {
+    throw new Error(
+        `${ERR}costOf(Factory) -- that class has no reactive plan; pass the class returned by @reactiveHost or defineReactive, not the undecorated inner class.`,
+    );
+}
+
+function throwCostNoStats(name) {
+    throw new TypeError(
+        `${ERR}costOf(${name}) -- the bound registry has no stats() ledger; costOf/capacityFor need a createRegistry() registry (which always carries the stats ledger). A hand-rolled 11-method registry facade cannot be probed.`,
+    );
+}
+
+function throwCostInconclusive(name, a, b) {
+    throw new Error(
+        `${ERR}costOf(${name}) -- inconclusive: two probes disagreed (nodes ${a.nodes}/${b.nodes}, links ${a.links}/${b.links}). A data-dependent derived read, or a registry mutated mid-probe, makes the cost non-deterministic; costOf fails closed rather than guess.`,
+    );
+}
+
+function throwCostNodeMismatch(name, got, want) {
+    throw new Error(
+        `${ERR}costOf(${name}) -- probed node count ${got} != P+D+E+1 (${want}); the bound registry was not quiet during the probe.`,
+    );
+}
+
+function throwCostFloor(name) {
+    throw new Error(
+        `${ERR}costOf(${name}) -- dispose did not return the bound registry to its pre-probe floor; the probe could not run against a quiet registry.`,
+    );
+}
+
+// costOf runs the probe twice and requires identical deltas: an inconclusive
+// probe is a fail-closed THROW, never a guessed number (PD-21).
+function probeCost(Factory, plan, reg) {
+    const before = reg.stats();
+    const inst = new Factory();
+    const ders = plan.deriveds;
+    for (let i = 0; i < ders.length; i++) void inst[ders[i].key];   // force lazy links
+    const mid = reg.stats();
+    const nodes = mid.activeNodes - before.activeNodes;
+    const links = mid.activeLinks - before.activeLinks;
+    disposeReactive(inst);
+    const after = reg.stats();
+    if (after.activeNodes !== before.activeNodes || after.activeLinks !== before.activeLinks) {
+        throwCostFloor(plan.ctorName);
+    }
+    return { nodes, links };
+}
+
+/**
+ * Measure the settled per-instance cost of a reactive class on its bound
+ * registry: construct, read every `@derived` once (forcing the lazy links),
+ * snapshot, dispose, verify the floor -- twice, requiring identical deltas.
+ * Returns a frozen `{ nodes, links, signals, deriveds, effects }`; `nodes`
+ * equals P+D+E+1. Cached per class. Throws (never guesses) on an inconclusive
+ * or polluted probe. Constructs the probe instance with no arguments.
+ */
+export function costOf(Factory) {
+    if (typeof Factory !== "function") throwCostFactory();
+    const cached = COST_CACHE.get(Factory);
+    if (cached !== undefined) return cached;
+    const plan = PLANS.get(Factory);
+    if (plan === undefined) throwCostNoPlan();
+    const reg = plan.reg;
+    // The 11-method REG_METHODS duck-check excludes stats (the wiring/dispose
+    // paths never need it), so a hand-rolled facade can be duck-valid yet lack
+    // stats -- guard here rather than let probeCost throw a raw TypeError.
+    if (typeof reg.stats !== "function") throwCostNoStats(plan.ctorName);
+    const first = probeCost(Factory, plan, reg);
+    const second = probeCost(Factory, plan, reg);
+    if (first.nodes !== second.nodes || first.links !== second.links) {
+        throwCostInconclusive(plan.ctorName, first, second);
+    }
+    const sig = plan.signals.length;
+    const der = plan.deriveds.length;
+    const eff = plan.effects.length;
+    const expected = sig + der + eff + 1;
+    if (first.nodes !== expected) throwCostNodeMismatch(plan.ctorName, first.nodes, expected);
+    const result = Object.freeze({
+        nodes: first.nodes,
+        links: first.links,
+        signals: sig,
+        deriveds: der,
+        effects: eff,
+    });
+    COST_CACHE.set(Factory, result);
+    return result;
+}
+
+function throwCapInventory() {
+    throw new TypeError(
+        `${ERR}capacityFor(inventory) -- inventory must be a non-empty array of [Factory, count] pairs.`,
+    );
+}
+
+function throwCapPair(i) {
+    throw new TypeError(
+        `${ERR}capacityFor -- inventory[${i}] must be a [Factory, count] pair.`,
+    );
+}
+
+function throwCapFactory(i) {
+    throw new TypeError(
+        `${ERR}capacityFor -- inventory[${i}][0] must be a @reactiveHost / defineReactive wrapper class.`,
+    );
+}
+
+function throwCapCount(i) {
+    throw new TypeError(
+        `${ERR}capacityFor -- inventory[${i}][1] must be a positive integer count.`,
+    );
+}
+
+function throwCapHeadroom() {
+    throw new TypeError(
+        `${ERR}capacityFor -- headroom must be a finite number >= 1.`,
+    );
+}
+
+function throwCapOptions(options) {
+    const got = Array.isArray(options) ? "an array" : typeof options;
+    throw new TypeError(
+        `${ERR}capacityFor(inventory, options?) -- options must be a plain object like { headroom: 1.25 }; got ${got}.`,
+    );
+}
+
+/**
+ * Size a `createRegistry` config for a stated inventory of `[Factory, count]`
+ * pairs. Nodes are exact (`sum(cost.nodes x count)`); links are
+ * `sum(cost.links x count)` scaled by `headroom` (default 1 -- exact; see
+ * decisions/0007). Returns
+ * `{ maxNodes, maxLinks, prealloc: "eager", onCapacityExceeded: "throw" }`.
+ * Fail-closed on a non-factory, a non-positive/non-integer count, an empty
+ * inventory, or a bad `headroom`.
+ */
+export function capacityFor(inventory, options) {
+    if (!Array.isArray(inventory) || inventory.length === 0) throwCapInventory();
+    let headroom = 1;
+    if (options !== undefined && options !== null) {   // null == omitted (preserved)
+        if (typeof options !== "object" || Array.isArray(options)) throwCapOptions(options);
+        const okeys = Object.keys(options);
+        for (let i = 0; i < okeys.length; i++) {
+            if (okeys[i] !== "headroom") throwUnknownOption("capacityFor", okeys[i], CAP_OPTION_KEYS);
+        }
+        if (options.headroom !== undefined) {
+            const h = options.headroom;
+            if (typeof h !== "number" || !isFinite(h) || h < 1) throwCapHeadroom();
+            headroom = h;
+        }
+    }
+    let totalNodes = 0;
+    let totalLinks = 0;
+    for (let i = 0; i < inventory.length; i++) {
+        const pair = inventory[i];
+        if (!Array.isArray(pair) || pair.length !== 2) throwCapPair(i);
+        const Factory = pair[0];
+        const count = pair[1];
+        if (typeof Factory !== "function") throwCapFactory(i);
+        if (typeof count !== "number" || !Number.isInteger(count) || count <= 0) throwCapCount(i);
+        const cost = costOf(Factory);
+        totalNodes += cost.nodes * count;
+        totalLinks += cost.links * count;
+    }
+    return {
+        maxNodes: totalNodes,                          // exact -- nodes are deterministic
+        // links x headroom, floored at the engine minimum of 1 (createRegistry
+        // rejects maxLinks: 0) so a signals-only inventory still yields a
+        // constructible config (0007). Floor is applied AFTER the multiplier.
+        maxLinks: Math.max(1, Math.ceil(totalLinks * headroom)),
+        prealloc: "eager",
+        onCapacityExceeded: "throw",
+    };
+}
+
+function throwFlagArg(what) {
+    throw new TypeError(`${ERR}${what}(on) -- on must be a boolean.`);
+}
+
+// Per-class label strings, built once and shared by every instance (PD-23).
+function labelStringsFor(plan) {
+    let s = LABEL_STRINGS.get(plan);
+    if (s !== undefined) return s;
+    const name = plan.ctorName;
+    const sig = [];
+    for (let i = 0; i < plan.signals.length; i++) sig.push(`${name}.${keyLabel(plan.signals[i].key)}`);
+    const der = [];
+    for (let i = 0; i < plan.deriveds.length; i++) der.push(`${name}.${keyLabel(plan.deriveds[i].key)}`);
+    const eff = [];
+    for (let i = 0; i < plan.effects.length; i++) eff.push(`${name}#${keyLabel(plan.effects[i].key)}`);
+    s = { anchor: `${name}@anchor`, signals: sig, deriveds: der, effects: eff };
+    LABEL_STRINGS.set(plan, s);
+    return s;
+}
+
+function registerLabels(inst, plan, reg, effHandles) {
+    let map = LABEL_MAPS.get(reg);
+    if (map === undefined) {
+        map = new Map();
+        LABEL_MAPS.set(reg, map);
+    }
+    const strings = labelStringsFor(plan);
+    const ids = [];
+    const anchorId = reg.nodeId(inst[ANCHOR]);
+    if (anchorId !== undefined) { map.set(anchorId, strings.anchor); ids.push(anchorId); }
+    const sigs = plan.signals;
+    for (let i = 0; i < sigs.length; i++) {
+        const id = reg.nodeId(inst[sigs[i].slot]);
+        if (id !== undefined) { map.set(id, strings.signals[i]); ids.push(id); }
+    }
+    const ders = plan.deriveds;
+    for (let i = 0; i < ders.length; i++) {
+        const id = reg.nodeId(inst[ders[i].slot]);
+        if (id !== undefined) { map.set(id, strings.deriveds[i]); ids.push(id); }
+    }
+    if (effHandles !== null) {
+        for (let i = 0; i < effHandles.length; i++) {
+            const id = reg.nodeId(effHandles[i]);
+            if (id !== undefined) { map.set(id, strings.effects[i]); ids.push(id); }
+        }
+    }
+    inst[LABEL_IDS] = ids;
+}
+
+function auditShape(plan) {
+    return `P=${plan.signals.length} D=${plan.deriveds.length} E=${plan.effects.length}`;
+}
+
+function auditFinalize(held) {
+    // held is a plain { className, shape } record -- it never references the
+    // (now-collected) instance, so the FR cannot itself retain what it watches.
+    console.error(
+        `${ERR}auditReactive: an instance of ${held.className} (${held.shape}) was garbage-collected without disposeReactive() -- its reactive graph was reclaimed by GC, not by you. Dispose at end of life: disposeReactive(vm), or a \`using\` block.`,
+    );
+}
+
+// Wiring-time introspection (S4): only reached when INTROSPECT_ON. Registers
+// per-node labels (while LABELS_ON) and the audit FR entry (while AUDIT_ON).
+function introspectWire(inst, plan, reg, effHandles) {
+    if (LABELS_ON) registerLabels(inst, plan, reg, effHandles);
+    if (AUDIT_ON && AUDIT_FR !== null) {
+        AUDIT_FR.register(inst, { className: plan.ctorName, shape: auditShape(plan) }, inst);
+    }
+}
+
+// Dispose-time introspection (S4): only reached when INTROSPECT_ON. Drops this
+// instance's label entries and unregisters it from the audit FR.
+function introspectDispose(vm, reg) {
+    const ids = vm[LABEL_IDS];
+    if (ids !== undefined) {
+        const map = LABEL_MAPS.get(reg);
+        if (map !== undefined) for (let i = 0; i < ids.length; i++) map.delete(ids[i]);
+        vm[LABEL_IDS] = undefined;
+    }
+    if (AUDIT_FR !== null) AUDIT_FR.unregister(vm);
+}
+
+/**
+ * Toggle devtools labels (default OFF). While ON, wiring registers a
+ * `nodeId -> "Class.prop" / "Class#method" / "Class@anchor"` label for every
+ * node an instance creates, into a per-registry map; `disposeReactive`
+ * unregisters them. OFF adds no hot-path cost (the accessor canon is untouched).
+ */
+export function enableLabels(on) {
+    if (typeof on !== "boolean") throwFlagArg("enableLabels");
+    LABELS_ON = on;
+    INTROSPECT_ON = LABELS_ON || AUDIT_ON;
+}
+
+/**
+ * Resolve a node id (or a handle, via the registry's `nodeId`) to its label, or
+ * `undefined` if unlabeled/unknown -- an introspection miss is never an error.
+ * `registry` defaults to the default registry; pass a custom `Registry` to look
+ * up nodes it owns.
+ */
+export function labelOf(idOrHandle, registry) {
+    const reg = registry === undefined || registry === null ? DEFAULT_REG : registry;
+    if (typeof reg !== "object" || reg === null) return undefined;
+    let id;
+    if (typeof idOrHandle === "number") {
+        id = idOrHandle;
+    } else if (idOrHandle !== null && typeof idOrHandle === "object" && typeof reg.nodeId === "function") {
+        id = reg.nodeId(idOrHandle);
+        if (id === undefined) return undefined;
+    } else {
+        return undefined;
+    }
+    const map = LABEL_MAPS.get(reg);
+    if (map === undefined) return undefined;
+    return map.get(id);
+}
+
+/**
+ * Toggle the leak auditor (default OFF). While ON, a lazily-created
+ * FinalizationRegistry reports (one `console.error`) any instance that is
+ * garbage-collected WITHOUT `disposeReactive` -- naming the class + shape. OFF:
+ * no FinalizationRegistry exists and nothing is registered.
+ */
+export function auditReactive(on) {
+    if (typeof on !== "boolean") throwFlagArg("auditReactive");
+    if (on && AUDIT_FR === null && typeof FinalizationRegistry === "function") {
+        AUDIT_FR = new FinalizationRegistry(auditFinalize);
+    }
+    AUDIT_ON = on;
+    INTROSPECT_ON = LABELS_ON || AUDIT_ON;
+}
+
 // --- Version ------------------------------------------------------------------
 
 /** Package version. Kept in lockstep with package.json and llms.txt. */
-export const VERSION = "0.2.0";
+export const VERSION = "0.4.0";

package/llms.txt

@@ -1,6 +1,6 @@
 # @zakkster/lite-signal-decorators
 
-VERSION 0.2.0
+VERSION 0.4.0
 
 > Stage-3 decorator layer over @zakkster/lite-signal. Turns a plain class into a
 > reactive view-model where each instance has a measured per-property cost, a
@@ -20,7 +20,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 (11)
+## Exports (16)
 
 - `reactive` -- `@reactive accessor x = v` (bare) or `@reactive({ equals })`
   (factory). Declares a per-instance signal.
@@ -53,9 +53,22 @@ 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.
+- `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
+  guesses. `nodes` = P+D+E+1; `links` = the first-full-read link count. 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.
+- `enableLabels(on)` / `labelOf(idOrHandle, registry?) -> string | undefined` --
+  opt-in devtools labels (default OFF); per-registry `nodeId -> "Class.prop" /
+  "Class#method" / "Class@anchor"`.
+- `auditReactive(on)` -- opt-in leak auditor (default OFF); a lazy
+  `FinalizationRegistry` reports any instance GC'd without `disposeReactive`.
 - `ReactiveDisposedError` -- `extends Error`, `name` `"ReactiveDisposedError"`,
   fields `className` and `key`.
-- `VERSION` -- `"0.2.0"`.
+- `VERSION` -- `"0.4.0"`.
 
 ## Registry law (one registry per host chain)
 
@@ -118,6 +131,45 @@ with the decorator path: values, deriveds, effect methods, disposal, poison, and
 capacity accounting are identical because both front doors call the SAME wiring
 core.
 
+## Introspection & audit (S4; all cold, all opt-in)
+
+`costOf(Factory)` measures a class's settled per-instance cost by a stats-delta
+probe on its bound registry: construct, read every `@derived` once (forcing the
+lazy links), snapshot, dispose, verify the floor -- run TWICE, requiring
+identical deltas. An inconclusive probe (a data-dependent derived read, or a
+registry mutated mid-probe) or a floor-verify failure THROWS a named error;
+costOf never returns a guess. `nodes` equals P+D+E+1 (the R-A law); `links` is
+the first-full-read count. The result is frozen and cached per class. costOf
+constructs the probe instance with NO constructor arguments.
+
+`capacityFor(inventory, { headroom } = {})` turns `[Factory, count]` pairs into a
+ready `createRegistry` config `{ maxNodes, maxLinks, prealloc: "eager",
+onCapacityExceeded: "throw" }`. Nodes are exact (`sum(cost.nodes x count)`);
+links are `sum(cost.links x count)` scaled by `headroom` (default 1 = exact),
+floored at the engine minimum of 1 so a signals-only inventory stays
+constructible.
+FIXED-shape deriveds provision exactly; a BRANCHY derived whose active branch
+reads more members than the probe measured under-provisions and the engine throws
+`CapacityError` at link formation (loud, named -- raise `headroom` for such
+workloads). See decisions/0007.
+
+Labels (`enableLabels(true)`, default OFF) register, at wiring, a per-registry
+`nodeId -> label` for every node an instance creates
+(`"Class.prop"` / `"Class#method"` / `"Class@anchor"`); `labelOf(idOrHandle,
+registry?)` resolves them (an unknown id returns `undefined` -- a miss is not an
+error); `disposeReactive` unregisters. Maps are per-registry (node ids are
+per-registry). OFF adds no hot-path cost -- the accessor canon is byte-identical
+to 0.3.0; labels feed a `graph()`/`toTree()` devtools walk from `rootOf(vm)`.
+
+Audit (`auditReactive(true)`, default OFF) lazily creates one
+`FinalizationRegistry` and reports (one `console.error`) any instance
+garbage-collected WITHOUT `disposeReactive`, naming the class + shape. OFF: no
+`FinalizationRegistry` exists, nothing is registered, wiring measures unchanged.
+Reach: an instance still pinned by its own undisposed derived/effect nodes on a
+long-lived registry is never collected, so audit cannot fire for it -- that
+retention is what the leak/retention torture catches; audit catches instances
+that reach GC without dispose (e.g. a per-scope registry dropped whole).
+
 ## Rejections (all named, all fail-closed, all at decoration/definition time)
 
 Legacy emit, wrong decorator kind, static members, private (#) members, unknown
@@ -137,7 +189,10 @@ routed per-registry via `createRegistry()`).
 
 ## Scope note
 
-0.2.0 ships the full runtime surface: the decorator core plus
-`@reactiveEffect`, `@batched`, `@reactiveHost({ registry })`, and
-`defineReactive`. Not yet included: cost introspection (`costOf`/`capacityFor`),
-labels, an audit hook, and private-member support.
+0.4.0 adds the S4 introspection surface -- 16 exports: the 11 runtime
+exports plus `costOf`, `capacityFor`, `enableLabels`, `labelOf`, and
+`auditReactive` (all cold / opt-in; the hot accessor canon is byte-identical to
+0.3.0). Also present since 0.3.0: the dev-side class-reactivity benchmark
+(`bench/`, private, never shipped) and the fleet-soak torture scenario; the
+formal kill-criteria verdicts live in decisions/0006-kill-criteria.md. Not yet
+included: private-member support.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-signal-decorators",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Stage-3 decorator layer over @zakkster/lite-signal. 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",
@@ -66,6 +66,7 @@
     "torture:semantic": "node test/torture/run.mjs --group semantic",
     "torture:soak": "node test/torture/run.mjs --group soak",
     "torture:controls": "node test/torture/run.mjs --controls",
+    "torture:peer-preview": "node test/torture/peer-preview.mjs",
     "spikes": "for f in spikes/*.mjs; do echo \"== $f ==\"; node --expose-gc \"$f\" || exit 1; done",
     "spike:emit": "node --expose-gc spikes/emit/probe.mjs",
     "spike:ownership": "node --expose-gc spikes/ownership.mjs",
@@ -82,6 +83,7 @@
     "@babel/core": "^7.25.0",
     "@babel/plugin-proposal-decorators": "^7.25.0",
     "@babel/preset-typescript": "^7.29.7",
+    "@zakkster/lite-devtools": "^1.4.0",
     "@zakkster/lite-gc-profiler": "^1.16.0",
     "@zakkster/lite-leak": "^1.10.0",
     "@zakkster/lite-signal": "1.5.0",