@zakkster/lite-signal-decorators 0.3.0 → 1.0.0

package/CHANGELOG.md

@@ -4,6 +4,162 @@ All notable changes to `@zakkster/lite-signal-decorators` are documented here.
 The format follows Keep a Changelog; this project adheres to Semantic
 Versioning.
 
+## [1.0.0] - 2026-08-29
+
+The 1.0 release: docs freeze, the fleet playground, and the standing pre-publish
+gate. Zero runtime changes -- the 16-export surface ships byte-identical to
+0.4.0 (the hot accessor canon is review-diffed to a zero-line diff), and this
+release freezes that surface under semver: any later signature change is a major
+recorded in a decision file. Dist-tag `latest`. Stage gate, measured at
+closeout by the full section-10 chain (archived verbatim below): 214/214 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 per tag
+(15/15, forward scenarios RUNNING) against lite-signal 1.9.0-preview.6 AND
+1.9.0-canary.1; the bench sink self-test catching its sabotaged adapter; pack 7
+files, no `demo/` or `Publications/`.
+
+### Added
+
+- The fleet-playground demo (`demo/`, dev-only, never in `files[]`): a
+  single-file instrument console over a two-plane architecture -- Plane A a
+  decorated entity-VM fleet in a `capacityFor`-sized custom registry with
+  enforced ceilings, Plane B the telemetry signals in the default registry
+  driving five `@zakkster/lite-watch-ex` watchers (`watchUntil`,
+  `pausableWatch`, `watchChanged`, `watchMany`, `watchPrevious`). The DOM-free
+  core runs headless under the same GC-budget and dispose-storm gates the
+  library uses; the PD-29 registry wall is proven by a stats-delta (no watcher
+  ever forms an edge into the custom-registry fleet), not by assertion.
+- README migration section: MobX 7 and signal-utils translation tables,
+  including the closing row MobX cannot write -- `disposeReactive(vm)` is one
+  idempotent, node-exact call after which every later touch throws by name.
+- README emit-support matrix, generated from `test/fixtures/hashes.json` (9
+  entries) under drift-proof `EMIT-MATRIX` markers; `04-fixture-freshness`
+  asserts the README block equals the generator, so a re-emit that changes a
+  byte is loud, not silent.
+- `llms.txt` per-feature forward floors documented alongside the peer range:
+  1.6.0 for `createScope`, 1.9.0 for `Symbol.dispose`; the peer range floor
+  stays `>=1.5.0 <2.0.0`.
+- `gate` script (`test/gate.mjs`): the section-10 pre-publish chain as captured
+  child processes -- fixtures, test, test:gc, torture (semantic + soak),
+  the TORTURE_BREAK control sweep, the non-blocking peer-preview lane,
+  the bench sink self-test, and `npm pack --dry-run` asserting exactly 7 files.
+  Every blocking step exits 0 or the gate exits non-zero; peer-preview is
+  reported, never gated.
+- `Publications/` (dev-only, never shipped): per-channel release drafts and the
+  GitHub release notes, centered on the class-reactivity benchmark methodology
+  with an explicit invitation for competitor adapter PRs.
+
+### Changed
+
+- Docs re-stamped to reality: Testing sections now read 214 tests across
+  fourteen files and 15 torture scenarios (13 run + 2 floor-gated skips), and
+  every numeric claim traces to a live stamp (`bench/results.txt`,
+  `decisions/0006`, or a gate tail). Version references across README and
+  llms.txt move to 1.0.0.
+- The 16-export surface is frozen under semver at 1.0.0. The 0.x "frozen for
+  0.x" note is retired in favor of the semver promise.
+
+### Fixed
+
+- (Found in review, pass 1 charge C4) An inline-style violation in the demo
+  HTML -- a non-custom-property `style=` attribute against the demo CSS law --
+  was hoisted into the stylesheet. Custom-property `style="--var: value"` hooks
+  remain, per the law.
+- (Found in the planner audit) The Testing and gates sections carried
+  0.2.0-era numbers (171 tests, "12/12 scenarios", an 11-row file table) two
+  stages stale, in violation of the no-claim-without-a-stamp rule. Re-stamped
+  against the 1.0.0 tree.
+
+### Gate output (section-10 chain, archived verbatim)
+
+```
+  fixtures              OK       exit 0 -- emit fixtures regenerated
+  test                  OK       exit 0 -- 214 pass / 0 fail
+  test:gc               OK       exit 0 -- 214 pass / 0 fail
+  torture               OK       exit 0 -- 13 passed, 2 skipped, 0 warned, 0 failed in 32.7s
+  torture:controls      OK       exit 0 -- 15 passed, 0 skipped, 0 warned, 0 failed in 1.9s
+  torture:peer-preview  REPORTED NON-BLOCKING -- lane completed (exit 0) [preview 1.9.0-preview.6 SUITE-GREEN 15 passed, 0 skipped, 0 warned, 0 failed; canary 1.9.0-canary.1 SUITE-GREEN 15 passed, 0 skipped, 0 warned, 0 failed]
+  bench:selftest        OK       exit 0 -- ALL PASS -- 22 passed, 0 failed
+  pack                  OK       exit 0 -- 7/7 files, no demo/ no Publications/
+----------------------------------------------------------------------
+  GATE PASS -- 7 blocking steps + 1 non-blocking (peer-preview)
+```
+
+## [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
@@ -202,6 +358,8 @@ Initial release -- the decorator core.
 - Torture skeleton (`@zakkster/lite-leak` + `@zakkster/lite-gc-profiler`):
   retention, conservation, lifecycle, and zero-GC lanes.
 
+[1.0.0]: https://github.com/PeshoVurtoleta/lite-signal-decorators/releases/tag/v1.0.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

package/README.md

@@ -49,6 +49,7 @@ No base class to extend. No `makeObservable(this, {...})` mirror object to keep
 - [Design decisions worth knowing](#design-decisions-worth-knowing)
 - [Testing (for clients & QA)](#testing-for-clients--qa)
 - [Compatibility](#compatibility)
+- [Migrating from MobX 7 & signal-utils](#migrating-from-mobx-7--signal-utils)
 - [What this is not](#what-this-is-not)
 - [Ecosystem](#ecosystem)
 - [FAQ](#faq) - [License](#license)
@@ -240,12 +241,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 (1.0.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.3.0"` |
+| `VERSION` | `"1.0.0"` |
 
 ### The rejection matrix
 
@@ -294,6 +306,27 @@ console.log(world.stats().activeNodes); // 0 -- every node returned to the pool
 
 The default registry never notices any of it: bound-registry churn leaves outside `stats()` frozen (torture-pinned). And because `boxOf` returns the *engine's* box, everything lite-signal composes with -- subscriptions, `peek`, batch, untrack, lite-raf frame effects -- composes with decorated members too.
 
+### Predicate-gated watchers (`@zakkster/lite-watch-ex`)
+
+`lite-watch-ex` adds one-shot, pausable, and change-gated watchers over the same engine. Its sources are plain **thunks** (`() => vm.hp`, never a box handle), and every watcher creates its effect node in the **default registry** -- so wire one only to a **default-registry** instance (one with no `host.registry`), never across a custom-registry fleet, where the edge would cross a boundary the engine's default `dispose` cannot see:
+
+```js
+import { watchUntil } from "@zakkster/lite-watch-ex";
+import { defineReactive } from "@zakkster/lite-signal-decorators";
+
+// Default-registry instance -- no host.registry, so it lives in the default graph.
+const ReactivePlayer = defineReactive(class Player {}, { signals: { hp: 100 } });
+const vm = new ReactivePlayer();
+
+// Fires ONCE when hp crosses the threshold, then self-disposes:
+watchUntil(() => vm.hp, (h) => h <= 25, (h) => console.log("low hp:", h));
+
+vm.hp = 40;  // predicate false -> no fire
+vm.hp = 20;  // predicate true  -> "low hp: 20", watcher disposes itself
+```
+
+The [`fleet-playground` demo](demo/fleet-playground.html) shows the safe split at scale: decorated entity VMs in an enforced custom registry, all watchers on a separate default-registry telemetry plane.
+
 ---
 
 ## The numbers
@@ -341,12 +374,12 @@ The ~7 ns over raw batch is the guarded thunk + rest-array the decorator allocat
 | `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 |
 
-The gates that hold it (run on every change, all green at 0.2.0):
+The gates that hold it (run on every change, all green at 1.0.0):
 
-- `npm test` / `npm run test:gc` -- **171/171** on both lanes.
+- `npm test` / `npm run test:gc` -- **214/214** 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: **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.
+- Torture: **15 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) -- **13 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 -- **15/15 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 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.
 
@@ -371,18 +404,19 @@ Full rationale lives in [`decisions/`](decisions/) -- each is a numbered, dated
 ## Testing (for clients & QA)
 
 ```bash
-npm test            # node --test, 171 tests
-npm run test:gc     # the same 171 with --expose-gc (enables the allocation assertions)
+npm test            # node --test, 214 tests
+npm run test:gc     # the same 214 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 -> pack
 ```
 
-**171 tests** across eleven files, all green at 0.2.0. The decorator protocol is tested three times over: against a mock Stage-3 emitter *and* against committed real TypeScript 5 and Babel `2023-11` emits, so both toolchains' codegen is pinned, not assumed.
+**214 tests** across fourteen files, all green at 1.0.0. The decorator protocol is tested three times over: against a mock Stage-3 emitter *and* against committed real TypeScript 5 and Babel `2023-11` emits, so both toolchains' codegen is pinned, not assumed.
 
 | File | Tests | Covers |
 |---|---:|---|
 | `01-protocol-mock` | 30 | Decorator protocol on the mock Stage-3 emitter: wiring, values, options, rejection matrix |
 | `02-fixtures-ts` | 19 | The same laws on real TypeScript 5 emit (committed fixtures) |
 | `03-fixtures-babel` | 19 | The same laws on real Babel `2023-11` emit |
-| `04-fixture-freshness` | 1 | Fixture hashes match the sources (stale-emit guard) |
+| `04-fixture-freshness` | 2 | Fixture hashes match the sources (stale-emit guard) + the README emit-matrix block matches its generator |
 | `05-wiring` | 5 | Anchor creation, wiring order, leaf-wires-once |
 | `06-dispose` | 6 | Cascade, idempotency, poison, `using` |
 | `07-qa-boundary` | 13 | S1 adversarial boundary pins |
@@ -390,19 +424,54 @@ npm run test:gc     # the same 171 with --expose-gc (enables the allocation asse
 | `09-buildless` | 16 | `defineReactive` parity + the spec rejection matrix |
 | `10-qa-s2a-boundary` | 34 | Adversarial pins: identity guard, frozen dispose, registry heterogeneity, stacking |
 | `11-qa-s2b-boundary` | 8 | Construction-throw boundaries: init-phase drain, chain-base throws, overflow storms |
+| `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 |
+
+### Emit-support matrix
+
+Three fixture sources, two Stage-3 emitters, both emit lanes -- every cell below is a committed, hash-pinned fixture (the `04-fixture-freshness` guard above). The table is generated from the fixture manifest, so a re-emit that changes a byte is loud, not silent:
+
+<!-- EMIT-MATRIX:START -->
+Generated by `node test/fixtures/emit-matrix.mjs` from `test/fixtures/hashes.json` -- do not hand-edit. Toolchain pinned by the committed fixtures: **TypeScript 5.9.3**, **@babel/core 7.29.7** + **@babel/plugin-proposal-decorators 7.29.7** (`version: 2023-11`). Each `sha256` is the first 12 hex of the committed emit; `npm run fixtures` regenerates and `test/04-fixture-freshness` fails loudly on any drift.
+
+| Source | Emitter | Emit lane | Compiled output | sha256 | At decoration time |
+|---|---|---|---|---|---|
+| `fixture.src.ts` | TypeScript 5 | standard 2023-11 | `ts-out/fixture.src.js` | `1a3fc0f943bf` | accepted -- full decorator surface wired + pinned green |
+| `fixture.src.ts` | Babel | standard 2023-11 | `babel-out/fixture.src.js` | `eb9dfb5939b1` | accepted -- full decorator surface wired + pinned green |
+| `static.src.ts` | TypeScript 5 | standard 2023-11 | `ts-out/static.src.js` | `d2a03e3d5f70` | rejected -- static member is a named throw at decoration time |
+| `static.src.ts` | Babel | standard 2023-11 | `babel-out/static.src.js` | `dc936c5aa235` | rejected -- static member is a named throw at decoration time |
+| `legacy.src.ts` | TypeScript 5 | legacy (experimental) | `ts-legacy-out/legacy.src.js` | `c1059b1d37b1` | rejected -- legacy emit -> named rejection at decoration time |
+| `legacy.src.ts` | Babel | legacy (experimental) | `babel-legacy-out/legacy.src.js` | `1d35a02c57ce` | rejected -- legacy emit -> named rejection at decoration time |
+
+Source hashes: `fixture.src.ts` `fb492a396340`, `static.src.ts` `81fb649965e6`, `legacy.src.ts` `30ac3dabaf7c`.
+<!-- EMIT-MATRIX:END -->
 
 ### The torture suite (dev-side, never shipped)
 
 Process-isolated stress scenarios built on `@zakkster/lite-leak` + `@zakkster/lite-gc-profiler`:
 
 ```bash
-npm run torture             # all 12 scenarios
+npm run torture             # all 15 scenarios (13 run + 2 floor-gated skips)
 npm run torture:semantic    # the correctness lane (CI)
-npm run torture:soak        # the wall-clock churn soak
+npm run torture:soak        # the wall-clock churn + fleet soaks
 npm run torture:controls    # sabotage self-test: every scenario must FAIL when broken
 ```
 
-Twelve 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, and the churn soak. 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`.
+Fifteen 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 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: 13 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 fleet demo (dev-side, never shipped)
+
+A single-file instrument console -- [`demo/fleet-playground.html`](demo/fleet-playground.html) -- drives a two-plane capacity fleet: decorated entity VMs in an enforced custom registry, telemetry watchers in the default registry. Its DOM-free core runs headless under the same gates the library uses:
+
+```bash
+npm run demo:build          # esbuild bundle -> demo/bundle.js + rewrite demo/bundle.sha256
+npm run demo:check          # verify the committed bundle matches its recorded hash
+npm run demo:gc             # headless GC-budget lane over the fleet core (maxMajor 0)
+npm run demo:storm          # headless dispose-storm retention lane (lite-leak, size 0)
+```
+
+The `demo/` directory is dev-only -- it never enters `package.json` `files[]` and never ships to consumers.
 
 ---
 
@@ -419,12 +488,45 @@ Native (untranspiled) `@` decorators in engines: not shipped anywhere yet -- unt
 
 ---
 
+## Migrating from MobX 7 & signal-utils
+
+The decorator vocabulary maps almost one-to-one; what changes is the lifetime story. Both libraries below leave teardown to the garbage collector -- this package makes it a single deterministic call.
+
+### From MobX 7
+
+| MobX 7 | lite-signal-decorators |
+|---|---|
+| `@observable accessor x` | `@reactive accessor x` |
+| `@computed get y()` | `@derived get y()` |
+| `@action m()` | `@batched m()` |
+| `makeObservable(this, {...})` | `@reactiveHost` -- one wiring site, no mirror object to keep in sync |
+| `reaction(...)` / `autorun(...)` | `@reactiveEffect m()` |
+| 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
+
+Verified against the installed `signal-utils@0.21.1`: `@signal` (on accessors or getters) and `@cached` (on getters) are the two decorators in its surface.
+
+| signal-utils 0.21 | lite-signal-decorators |
+|---|---|
+| `@signal accessor x` (or `@signal get x`) | `@reactive accessor x` |
+| `@cached get y()` | `@derived get y()` |
+| no disposal API at all | `disposeReactive(vm)` -- **and it disposes**: cascade teardown, poison swap, node-exact conservation |
+| Stage-3 build required | `defineReactive(Class, spec)` -- the buildless door signal-utils has no equivalent for |
+
+The cross-framework numbers behind this table are stamped in [`decisions/0006-kill-criteria.md`](decisions/0006-kill-criteria.md) (both engines measured through their documented class APIs at checksum-identical work).
+
+---
+
 ## What this is not
 
 - **Not a home for module-level or global signals.** That is raw `lite-signal` territory; `static` members are rejected by design.
+- **Not a deep/proxy observation layer.** No `observable.deep`, no wrapped Arrays/Maps/Sets, no proxy magic -- the reactive unit is a declared member, not a traversed object graph. Collections are `@zakkster/lite-project` territory.
 - **Not a per-frame action system.** `@batched` costs a measured thunk per call -- fine for "one call per user intent", wrong inside a render loop. Per-frame hot lanes stay on plain accessor writes (and frame *scheduling* belongs to `lite-raf`).
 - **Not a framework, renderer, or component model.** It ends at the reactive view-model; DOM binding is `lite-signal-dom`'s job.
-- **Not a MobX API shim.** No `makeObservable`, no administration objects, no proxy magic -- and no GC-based cleanup: disposal is explicit, deterministic, and verified, because "the collector will get it eventually" is not a lifecycle.
+- **Not a general meta-programming kit.** Five decorators, one wiring law -- not an open decorator toolbox. It does one thing: turn a class into a reactive view-model with a provable lifetime.
+- **Not a MobX API shim.** No `makeObservable`, no administration objects -- and no GC-based cleanup: disposal is explicit, deterministic, and verified, because "the collector will get it eventually" is not a lifecycle.
+- **Not a legacy-decorators consumer.** TypeScript `experimentalDecorators` emit is detected by call shape at decoration time and rejected with a named error -- never "works differently under legacy".
 - **Not usable as `@` syntax without a toolchain** -- that is exactly what `defineReactive` exists for.
 
 ---
@@ -437,6 +539,7 @@ Native (untranspiled) `@` decorators in engines: not shipped anywhere yet -- unt
 | `@zakkster/lite-signal-dom` | DOM bindings for the same engine -- where a view-model meets actual elements. |
 | `@zakkster/lite-raf` | Frame-rate scheduling for the same graph; the frame-coalescing pattern the `scheduler` option on `@reactiveEffect` exists to plug into. |
 | `@zakkster/lite-devtools` | Graph inspection; `rootOf(vm)` + `forEachOwned` is the hook it walks. |
+| [`@zakkster/lite-watch-ex`](https://www.npmjs.com/package/@zakkster/lite-watch-ex) | One-shot / predicate-gated / pausable watchers over the same engine; thunk sources, default-registry effects -- see the [registry note](#composability) before pointing one at a decorated member. |
 | `@zakkster/lite-leak` + `@zakkster/lite-gc-profiler` | The dev-side harness that proves every retention and allocation claim in this README. Never shipped to consumers. |
 
 ---
@@ -473,7 +576,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.3.0 -- the runtime surface froze for 0.x at 0.2.0, and the introspection layer (capacity accounting, devtools identity) is the 0.4.0 milestone. The `llms.txt` scope note tracks exactly what is and isn't included.
+All three are part of the frozen 1.0.0 surface -- `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.3.0";
+export const VERSION: "1.0.0";

package/SignalDecorators.js

@@ -1,5 +1,5 @@
 /**
- * @zakkster/lite-signal-decorators v0.3.0
+ * @zakkster/lite-signal-decorators v1.0.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.3.0";
+export const VERSION = "1.0.0";

package/llms.txt

@@ -1,6 +1,6 @@
 # @zakkster/lite-signal-decorators
 
-VERSION 0.3.0
+VERSION 1.0.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.3.0"`.
+- `VERSION` -- `"1.0.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
@@ -133,12 +185,26 @@ throw a named error.
 Requires `@zakkster/lite-signal` `>=1.5.0 <2.0.0` (peer dependency). Uses
 `signalBox`, `computedBox`, `effect`, `createRoot`, `getOwner`, `runWithOwner`,
 `dispose`, `nodeId`, `isTracking`, `batch`, and `untrack` from it (all 11 also
-routed per-registry via `createRegistry()`).
+routed per-registry via `createRegistry()`). The RANGE floor is 1.5.0 and stays
+1.5.0 -- everything the runtime surface needs shipped in 1.5.0 stable. Two
+forward-compat torture scenarios are feature-detected above that floor and SKIP
+below it (a skip below the floor is correct; at or above it is a failure): the
+`createScope` adoption scenario needs peer 1.6.0, and the engine
+`[Symbol.dispose]`/`using` interop scenario needs peer 1.9.0. Neither is a
+runtime requirement -- the shipped surface runs on 1.5.0.
 
 ## Scope note
 
-0.3.0 = the 0.2.0 runtime surface (unchanged -- the same 11 exports, frozen for
-0.x) plus the dev-side class-reactivity benchmark (`bench/`, private, never
+1.0.0 FREEZES the export 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). 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
+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: cost introspection
-(`costOf`/`capacityFor`), labels, an audit hook, and private-member support.
+live in decisions/0006-kill-criteria.md. Still OUT of the 1.0 surface (each a
+deliberate, documented exclusion, not an oversight): private (`#`) members,
+static members, module/global signals (raw lite-signal territory), and any
+instance reinitialization / pooling API -- an instance is single-lifetime,
+disposed once, never revived.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-signal-decorators",
-  "version": "0.3.0",
+  "version": "1.0.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,8 @@
     "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",
+    "gate": "node test/gate.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",
@@ -73,7 +75,11 @@
     "spike:manual": "node --expose-gc spikes/manual-call.mjs",
     "spike:poison": "node --expose-gc spikes/poison.mjs",
     "spike:buildless": "node --expose-gc spikes/buildless.mjs",
-    "fixtures:regen": "node spikes/emit/regen.mjs"
+    "fixtures:regen": "node spikes/emit/regen.mjs",
+    "demo:build": "node demo/build.mjs",
+    "demo:check": "node demo/build.mjs --check",
+    "demo:gc": "node --expose-gc demo/gc-lane.mjs",
+    "demo:storm": "node --expose-gc demo/storm-lane.mjs"
   },
   "peerDependencies": {
     "@zakkster/lite-signal": ">=1.5.0 <2.0.0"
@@ -82,9 +88,12 @@
     "@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",
+    "@zakkster/lite-watch-ex": "^1.1.0",
+    "esbuild": "0.28.2",
     "typescript": "^5.6.0"
   }
 }