@zakkster/lite-signal-decorators 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -4,6 +4,117 @@ All notable changes to `@zakkster/lite-signal-decorators` are documented here.
 The format follows Keep a Changelog; this project adheres to Semantic
 Versioning.
 
+## [1.5.0] - 2026-08-30
+
+The gamedev release -- decisions/0013 criterion (d), and the LADDER CLOSES. The
+package already shipped the fleet primitives (`capacityFor` sizes a registry;
+`createRegistry` builds it; `releaseReactive`/`reinitReactive` park and revive an
+instance with zero engine nodes held while parked), and the demo hand-rolled a
+pool over them. `createFleet(inventory, bind, opts?)` is that pool, extracted:
+the flagship-audience helper that composes the shipped primitives into one
+fixed-capacity fleet handle. The demo is the NAMED consumer (criterion (d): serve
+the flagship audience on a shipped primitive with the demo as a live consumer
+landing in the same release) -- its hand-rolled pool was DELETED for the helper,
+and that diff went NET-NEGATIVE. Surface 22 -> 23, and the decisions/0013
+strategic-admission ladder is closed at four rungs.
+
+### Added
+
+- **`createFleet(inventory, bind, opts?) -> Fleet`** (23rd export) -- a
+  fixed-capacity pool of reactive instances over the shipped primitives. COLD
+  construction: `capacityFor(inventory, opts)` sizes a registry, `createRegistry`
+  builds it, `bind(registry)` binds the caller's decorated class to that registry
+  and returns it (PD-76 -- the helper never wraps or redefines the class; the demo
+  keeps its real `@reactiveHost` cycle), then one member per inventory unit is
+  EAGER-constructed and PARKED (PD-75 -- `acquire` never constructs). The handle
+  is `{ registry, Class, capacity, acquire(initials?), release(vm), at(i),
+  size(), stats(), dispose() }`. HOT: `acquire` pops an `Int32Array` free-list and
+  `reinitReactive`s a parked member (`initials` override the reset values);
+  `release` validates a per-fleet symbol slot stamp (a plain symbol-keyed integer
+  field, NOT a WeakMap -- PD-77's forcing condition, resolved) and
+  `releaseReactive`s the member back to the pool. Both hot bodies allocate ZERO.
+  SIX named fail-closed misuses: `FleetExhaustedError` (acquire at capacity;
+  pre-checked, the registry's own `CapacityError` is unreachable because all N are
+  prealloc'd), `FleetForeignMemberError` (release of a vm this fleet never handed
+  out -- the slot stamp is the check), `FleetDoubleReleaseError` (release of an
+  already-parked vm -- `releaseReactive` returning false is the check),
+  `FleetDisposedError` (any call after `dispose()`), a `RangeError` (`at(i)`
+  outside `[0, capacity)`), and a `TypeError` (a `bind` that is not a function or
+  does not return a constructor). These six are internal by design -- ONE exported
+  error class remains the surface law (`ReactiveDisposedError`); the fleet names
+  are message/name-level and pinned by test/20. Construction is ATOMIC: any
+  mid-prefill throw disposes the already-built members and destroys the registry
+  before rethrowing. `dispose()` disposes every member LIVE AND PARKED (park ->
+  dispose lands DISPOSED) then destroys the fleet-owned registry -- parked members
+  are disposed too, never leaked.
+- **`test/20-fleet.test.mjs`** (37 cases) -- the API surface + the six fail-closed
+  laws + both emit lanes where meaningful + a buildless (`defineReactive`) class +
+  `initials` pass-through, and the 22 -> 23 export-count assertion.
+- **`test/torture/fleet-torture.mjs`** (a NEW lane, 19 scenarios / 19 controls) --
+  proves the HELPER's bookkeeping (the primitive pooled-cycle proof stays in
+  `reinit-torture`): A1 4096 acquire/release cycles at zero-alloc budgets with a
+  `TORTURE_BREAK` control that catches a deliberately leaky variant; A2 1000
+  fleet lifecycles at N=512 returning `activeNodes` to exact baseline with
+  `poolGrowths` 0.
+- **The demo consumer** (never cut -- the admission ground): `loop.ts`'s
+  hand-rolled pool (the `EntityShape` wall plumbing, slots/count, spawn/kill,
+  dispose-storm bodies) is DELETED in favor of one `createFleet` call;
+  `step`/`readPositions` use `at(i)`; the drift wall + HUD keep working. The
+  `EntityShape` twin is kept ONLY for pre-existence `capacityFor` sizing.
+
+### Changed
+
+- **The export surface: 22 -> 23** -- an additive MINOR under the 1.0.0 semver
+  promise (new exports are minors). The 1.0.0 hot canon
+  (`makeGet`/`makeSet`/`makeDerivedGet`) stays byte-identical: `createFleet` is
+  cold construction over the shipped primitives and moves no accessor byte.
+- Version sync to 1.5.0 across the FOUR sites: `package.json`, the `VERSION`
+  const, `llms.txt` line 3, and the `SignalDecorators.d.ts` VERSION literal.
+- `test/15` surface-freeze recount 22 -> 23 (the CB-A2 sites); its four-place
+  VERSION leg reads live values and needed no edit.
+- The demo's boot cost rises by ~7ms one-time for the 4096 eager constructions
+  (the eager prefill moves cost to load -- the honest number, reported not hidden;
+  it buys a zero-alloc steady state).
+
+### Measured (rig: Node v26.3.1, arm64 Apple M4 Pro, lite-signal 1.5.0)
+
+- A1 acquire/release, 4096 cycles at 8N: **1.649 B/cyc** vs the in-process
+  zero-alloc control **0.234 B/cyc** (+2 limit); `gc.major` **0**; minors **2**
+  vs a limit of 129; `maxPauseMs` **0.36**. The `TORTURE_BREAK` leaky variant is
+  caught at **42.881 B/cyc**.
+- A2 1000 lifecycles x N=512 return `activeNodes` to the exact baseline;
+  `poolGrowths` delta **0**.
+- Release frees exactly `-(P+L+D+E+1)` nodes -- on the demo `Entity` shape that
+  is **-8** node-delta per release.
+
+### Records
+
+- decisions/0009 (the fifth admission candidate) and decisions/0011 (the
+  fleet-helpers section) each gain an ADMITTED stamp.
+- decisions/0013 gains its COMPLETION ADDENDUM: the strategic-admission ladder is
+  CLOSED -- four rungs shipped same-day (v1.2.0 `@localTo` (a); v1.3.0
+  `snapshotOf` + `forEachReactive` (c); v1.4.0 `costOfInstance` (b); v1.5.0
+  `createFleet` (d)). Surface 18 -> 23 across the ladder; candidates 1 (`bump`)
+  and 7 (`onObserved` sugar) remain deferred behind the original real-consumer
+  bar, which resumes as the only track for anything new. The planned
+  decisions/0015 was CUT -- its fleet-contract facts fold into the 0013 addendum.
+
+### Gate output (section-10 chain, archived verbatim)
+
+```
+  fixtures              OK       exit 0 -- emit fixtures regenerated
+  test                  OK       exit 0 -- 377 pass / 0 fail
+  test:gc               OK       exit 0 -- 377 pass / 0 fail
+  torture               OK       exit 0 -- 17 passed, 2 skipped, 0 warned, 0 failed in 35.5s
+  torture:controls      OK       exit 0 -- 19 passed, 0 skipped, 0 warned, 0 failed in 3.7s
+  torture:peer-preview  REPORTED NON-BLOCKING -- lane completed (exit 0) [preview 1.9.0-preview.6 SUITE-GREEN 19/0/0/0; canary 1.9.0-canary.1 SUITE-GREEN 19/0/0/0]
+  bench:selftest        OK       exit 0 -- ALL PASS -- 22 passed, 0 failed
+  cookbook              OK       exit 0/0 -- corpus 18/18 companions ok in 2.0s; controls 8/8 controls fail correctly in 4.9s
+  pack                  OK       exit 0 -- 7/7 files, exact 7-name set, no demo/ no Publications/
+----------------------------------------------------------------------
+  GATE PASS -- 8 blocking steps + 1 non-blocking (peer-preview)
+```
+
 ## [1.4.0] - 2026-08-30
 
 The measured-instance pillar -- decisions/0013 criterion (b). `costOf(Factory)`

package/README.md

@@ -148,6 +148,7 @@ const ReactivePlayer = defineReactive(Player, {
 - **Interop that stays raw** -- `boxOf(vm, key)` hands you the live engine box; `rootOf(vm)` hands the anchor descriptor to `forEachOwned` / lite-devtools. Decorated and hand-written signals share one graph.
 - **Introspection & migration (1.3.0)** -- `forEachReactive(vm, fn, arg)` walks every value-bearing member in plan order (`signal`/`local`/`derived`, effects excluded) with a zero-alloc `fn(key, box, kind, arg)` callback; `snapshotOf(vm)` returns a shallow plain-object copy read through the accessors under one `untrack` -- the native `toJS` this package now ships, safe to call inside an effect.
 - **Live per-instance cost (1.4.0)** -- `costOfInstance(vm)` walks one wired instance's own graph and reports what it costs RIGHT NOW: `costOf(Factory)` answers "what will an instance of this class cost" (it forces every derived to the constructed ceiling), `costOfInstance` answers "what does THIS instance cost" -- an unforced lazy derived or an untaken branch shows fewer links until the graph is exercised, and reading every derived once makes the two agree exactly. Twin-free: it needs no stats() ledger, so it measures instances on hand-rolled registries where `costOf` fails closed.
+- **One-call pooled fleets (1.5.0)** -- `createFleet(inventory, bind, opts?)` composes the shipped primitives (`capacityFor` sizes the registry, `createRegistry` builds it, `releaseReactive`/`reinitReactive` park and revive) into one fixed-capacity fleet handle `{ registry, Class, capacity, acquire, release, at, size, stats, dispose }`. It EAGER-prefills and parks every member at construction, so `acquire(initials?)` never constructs -- it pops an `Int32Array` free-list and revives a parked member with ZERO allocation, and `release(vm)` parks it back after a per-fleet slot-stamp check. Six named fail-closed misuses (exhausted, foreign vm, double release, use-after-dispose, out-of-range `at`, bad `bind`); `dispose()` tears every member LIVE and PARKED plus the fleet-owned registry. The gamedev release: spawn/kill worlds and respawn-heavy scenes on a zero-GC steady state (decisions/0013 criterion (d) -- the demo's hand-rolled pool was deleted for it).
 
 ---
 
@@ -294,6 +295,28 @@ With labels and audit off, the zero-GC budgets are byte-identical to 0.3.0 -- th
 | `forEachReactive` | `(vm, fn, arg) => count` | Cold value-member walk. Calls `fn(key, box, kind, arg)` once per value-bearing member and returns the visit count. `kind` is `"signal" \| "local" \| "derived"`; `@reactiveEffect`/`@batched` are EXCLUDED (non-value-bearing). Order is PLAN order -- signals, then locals, then deriveds, each declaration-ordered and ancestor-first (never `Reflect.ownKeys`, so it is stable across reinit). Four scalar args, zero descriptor object, and the `arg` pass-through kills the caller's closure: the walk is a gated zero-alloc body. Symbol keys are visited. Fails closed on a non-reactive, unwired, parked, or disposed value with the same named errors as `rootOf`. |
 | `snapshotOf` | `(vm) => object` | A shallow plain-object copy of every value-bearing member, keyed by member key. Values are read through the ACCESSOR `vm[key]`, NOT `box.get`, so a `@localTo` compare-on-read resets honestly and a `@derived` computes on read (PD-62: reading the box directly would show a stale local after an untracked upstream move -- the accessor is the documented read). The whole walk runs under ONE `untrack` when the caller is tracking, so `snapshotOf` inside an effect subscribes to nothing. SHALLOW by design: a nested VM is copied by reference, not recursed. Symbol keys included. Fails closed on parked/disposed (`ReactiveDisposedError`, parked vs disposed flavor) and non-reactive values. This export ALLOCATES the returned object by design (~96 B/op measured) -- reported, never gated; the walk under it stays zero-alloc. |
 
+### Fleet (1.5.0)
+
+| Export | Signature | Behavior |
+|---|---|---|
+| `createFleet` | `(inventory, bind, opts?) => Fleet` | A fixed-capacity pool of reactive instances over the shipped primitives. COLD construction: `capacityFor(inventory, opts)` sizes a registry, `createRegistry` builds it, `bind(registry)` binds the caller's decorated class to it and returns it (the helper never wraps or redefines the class), then one member per inventory unit is EAGER-constructed and PARKED. The handle is `{ registry, Class, capacity, acquire(initials?), release(vm), at(i), size(), stats(), dispose() }`. HOT: `acquire` pops an `Int32Array` free-list and revives a parked member (`initials` override the reset values); `release` validates a per-fleet symbol slot stamp (a plain symbol-keyed integer field, NOT a WeakMap) and parks the member back. Both hot bodies allocate ZERO. Six named fail-closed misuses: `FleetExhaustedError` (acquire at capacity, pre-checked), `FleetForeignMemberError` (release of a vm this fleet never handed out), `FleetDoubleReleaseError` (release of an already-parked vm), `FleetDisposedError` (any call after `dispose()`), a `RangeError` (`at(i)` out of `[0, capacity)`), and a `TypeError` (a `bind` that is not a function or does not return a constructor). Construction is ATOMIC (a mid-prefill throw disposes what was built + destroys the registry). `dispose()` disposes every member LIVE and PARKED then destroys the fleet-owned registry. |
+
+The fleet is the demo's pool, extracted -- one call for a spawn/kill world:
+
+```js
+const fleet = createFleet([[Entity, 4096]], (reg) => {
+  @reactiveHost({ registry: reg })
+  class Bound extends Entity {}
+  return Bound;
+});
+const e = fleet.acquire({ x: 10, y: 20 });   // revive a parked member, zero alloc
+fleet.at(0);                                  // slot read (bounds-checked)
+fleet.release(e);                             // park it back; nodes return to the pool
+fleet.dispose();                              // every member + the registry torn down
+```
+
+`acquire` never constructs: all `capacity` members are built and parked at construction, so the steady state is allocation-free. That moves the construction cost to load (the demo pays ~7ms one-time to prefill 4096 members) in exchange for a zero-GC spawn/kill loop.
+
 ### Errors & constants
 
 | Export | Value |
@@ -404,6 +427,8 @@ The ~7 ns over raw batch is the guarded thunk + rest-array the decorator allocat
 
 `P + L + D + E + 1` pool nodes -- one per signal, per local, per derived, per effect, plus the anchor. All of them return to the pool on dispose: conservation is node-exact (`activeNodes` to baseline, zero pool growths, allocations minus disposals reconciled) over 4096-cycle churn and a wall-clock soak.
 
+**`createFleet` acquire/release (1.5.0).** The fleet's hot loop measures **1.649 B/cyc** at 8N against a **0.234 B/cyc** in-process zero-alloc control (a +2 limit); `gc.major 0`, 2 minors against a limit of 129, `maxPauseMs 0.36`. A `release(vm)` frees exactly `P + L + D + E + 1` nodes -- on the demo `Entity` shape that is a **-8** `activeNodes` delta per release. 1000 fleet lifecycles at N=512 return `activeNodes` to the exact baseline with `poolGrowths` 0, and the lane's `TORTURE_BREAK` control catches a leaky variant at 42.881 B/cyc.
+
 <details>
 <summary><strong>Zero-GC design notes: the allocation table + the gates</strong></summary>
 
@@ -420,12 +445,13 @@ The ~7 ns over raw batch is the guarded thunk + rest-array the decorator allocat
 | `forEachReactive` walk | none | gated: 1e6 hoisted-callback walks measure **0.002 B/walk** (vs the 0.000 B/op zero-alloc control -- within a +2-byte limit), `gc.major === 0`; the 4-scalar `fn(key, box, kind, arg)` carries no descriptor object and the `arg` pass-through kills the caller's closure |
 | `snapshotOf(vm)` | 1 plain object | **by design** -- the returned copy allocates (**95.8 B/op measured**, 1e5 cycles); REPORTED in the torture summary line, never gated. The walk *under* it stays zero-alloc; cold, off any frame path |
 | `costOfInstance(vm)` | 1 frozen object | **by design** -- the per-call frozen result allocates (**71.3 B/op measured**, 1e4 calls); the measurement itself is `gc.major === 0` over those 1e4 calls -- REPORTED, never gated. The graph walk *under* it allocates nothing (module-slot visitors, no per-call closure); cold, off any frame path |
+| `fleet.acquire` / `fleet.release` | none | gated: the fleet's hot loop measures **1.649 B/cyc** at 8N (vs a 0.234 B/cyc zero-alloc control, +2 limit), `gc.major 0`, `maxPauseMs 0.36`; `acquire` pops an `Int32Array` free-list + revives a parked member, `release` parks it after a symbol-slot-stamp check -- no WeakMap, no per-call closure |
 
-The gates that hold it (run on every change, all green at 1.4.0):
+The gates that hold it (run on every change, all green at 1.5.0):
 
-- `npm test` / `npm run test:gc` -- **335/335** on both lanes.
+- `npm test` / `npm run test:gc` -- **372/372** on both lanes.
 - Suite gate (lite-leak + lite-gc-profiler): `leak=size 0/0 findings=0 warnings=0 | gc major=0 minor=0 maxMs=0.00 | ok`.
-- Torture: **18 scenarios** (zero-GC read/write lanes at `maxMajor 0, maxPauseMs 4`; 4096-cycle leak gate at 0 live / 0 findings / 0 warnings; capacity atomicity at every overflow point; a 300-seed x 20k-op oracle with zero divergences; the `reinit-torture` acquire/release gate; the `localto-torture` zero-alloc read/write storm + ABA-stale interleave lattice + pooled park/reinit; the `introspection-torture` 1e6 hoisted-callback `forEachReactive` walk at `maxMajor 0` with the snapshot-allocates figure reported, never gated) -- **16 run + 2 that skip correctly below their peer floors** (`scope-adoption` needs 1.6.0, `using-dispose` needs 1.9.0; the installed peer is 1.5.0). A skip *below* a floor is the forward-compat design working; a skip *at or above* it is a FAIL (run.mjs enforces floor-escalation). Every scenario carries a `TORTURE_BREAK` sabotage control that must exit non-zero -- **18/18 controls** prove each gate can actually fail.
+- Torture: **19 scenarios** (zero-GC read/write lanes at `maxMajor 0, maxPauseMs 4`; 4096-cycle leak gate at 0 live / 0 findings / 0 warnings; capacity atomicity at every overflow point; a 300-seed x 20k-op oracle with zero divergences; the `reinit-torture` acquire/release gate; the `localto-torture` zero-alloc read/write storm + ABA-stale interleave lattice + pooled park/reinit; the `introspection-torture` 1e6 hoisted-callback `forEachReactive` walk at `maxMajor 0` with the snapshot-allocates figure reported, never gated; the `fleet-torture` 4096 acquire/release cycles at zero-alloc budgets + 1000 lifecycles to exact baseline) -- **17 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 -- **19/19 controls** prove each gate can actually fail.
 - `churn-soak` + `fleet-soak`: sustained construct/use/dispose and a 10s 2k-VM fleet tick; pools at floor and retained heap flat at every sample.
 
 The cross-framework matrix lives in `bench/` (private, never shipped): six engines -- both our tiers, the hand-written `lite-raw-boxes` baseline, MobX 7, signal-utils/signal-polyfill, and a hand-rolled alien-signals class -- across eight class-shaped scenarios (including the `churn-reuse` acquire/release lane, where the lite tiers pool with zero retained growth and MobX/signal-utils/alien-class are structurally `unsupported` -- no disposable instance lifecycle to pool), checksum-verified for identical work, stamped into `bench/results.txt`. The formal verdicts are in [`decisions/0006-kill-criteria.md`](decisions/0006-kill-criteria.md): the decorated path measured **0.94x** the hand-written baseline on vm-write and **1.10x** on a 10k-instance fleet read (the 2.0x kill line cleared with margin), and **0 major + 0 minor GC over 4096 construct/use/dispose cycles** with pools at floor -- while emitting ~12.6x less transient garbage per churn run than the hand-rolled class it replaces.
@@ -457,12 +483,12 @@ Full rationale lives in [`decisions/`](decisions/) -- each is a numbered, dated
 ## Testing (for clients & QA)
 
 ```bash
-npm test            # node --test, 335 tests
-npm run test:gc     # the same 335 with --expose-gc (enables the allocation assertions)
+npm test            # node --test, 372 tests
+npm run test:gc     # the same 372 with --expose-gc (enables the allocation assertions)
 npm run gate        # the full pre-publish chain (section 10): fixtures -> test -> test:gc -> torture -> controls -> peer-preview (non-blocking) -> bench selftest -> cookbook -> pack
 ```
 
-**335 tests** across nineteen files, all green at 1.4.0. The decorator protocol is tested three times over: against a mock standard-decorators emitter *and* against committed real TypeScript 5 and Babel `2023-11` emits, so both toolchains' codegen is pinned, not assumed.
+**372 tests** across twenty files, all green at 1.5.0. The decorator protocol is tested three times over: against a mock standard-decorators emitter *and* against committed real TypeScript 5 and Babel `2023-11` emits, so both toolchains' codegen is pinned, not assumed.
 
 | File | Tests | Covers |
 |---|---:|---|
@@ -480,11 +506,12 @@ npm run gate        # the full pre-publish chain (section 10): fixtures -> test
 | `12-accounting` | 11 | `costOf` node/link/shape grid (double-probe, frozen + cached, fail-closed) + `capacityFor` budget sizing |
 | `13-labels-audit` | 10 | `enableLabels`/`labelOf` per-registry identity + `auditReactive` leak reporting, both opt-in and default-OFF |
 | `14-qa-s4-boundary` | 21 | S4 adversarial edges: stats-less facade closure, signals-only capacity floor, label/audit boundary matrix |
-| `15-cookbook` | 14 | [`COOKBOOK.md`](https://github.com/PeshoVurtoleta/lite-signal-decorators/blob/main/COOKBOOK.md) drift/parity: each fenced block byte-compared against its tagged companion `#region` (both directions + both-way coverage), surface freeze (exactly 22 exports), citation allowlist, link law, static-cost probe, and the four-place VERSION sync (module const === package.json === llms.txt === `SignalDecorators.d.ts` literal) |
+| `15-cookbook` | 14 | [`COOKBOOK.md`](https://github.com/PeshoVurtoleta/lite-signal-decorators/blob/main/COOKBOOK.md) drift/parity: each fenced block byte-compared against its tagged companion `#region` (both directions + both-way coverage), surface freeze (exactly 23 exports), citation allowlist, link law, static-cost probe, and the four-place VERSION sync (module const === package.json === llms.txt === `SignalDecorators.d.ts` literal) |
 | `16-reinit` | 29 | Pooled-reinit lattice on both emit lanes: park/reinit/dispose transitions, the five `reinitReactive` fail-closed states, parked-touch throws by name, `initials` boundary matrix (0..N+1 keys, null/undefined, NaN/-0 verbatim), `Symbol.dispose` on a parked instance, accessor descriptors byte-identical across reinit, self-release re-entrancy, ledger conservation |
 | `17-localto` | 34 | `@localTo` on both emit lanes + buildless `locals`: the read/write/upstream-reset lattice, both initial flavors (follow-from-wiring vs reset-from-initial), the ABA stale-local contract, `equals` override survival, park/reinit box+seen reset, `costOf` = P+L+D+E+1, source-throw fail-closed, and the fail-closed option/source matrix |
 | `18-introspection` | 22 | `forEachReactive`/`snapshotOf` on both emit lanes + buildless: plan-order walk (signals, locals, deriveds; ancestor-first), symbol keys, the `signal`/`local`/`derived` kind tags, effect/batched exclusion, count return + `arg` pass-through, the untracked-read law (snapshotOf inside an effect fires once), r7 `{name,hp,mp,alive}` parity, the PD-62 accessor-read reset honesty, and the fail-closed non-reactive/unwired/parked/disposed matrix |
 | `19-cost-instance` | 22 | `costOfInstance` on both emit lanes + buildless: A1 parity-when-forced (=== `costOf`, nodes/links/every kind count), A2 delta-when-lazy (links strictly lower, then monotonic toward the forced number), `@localTo` counted in locals with zero graph links, the frozen `{nodes,links,signals,locals,deriveds,effects}` shape, A3 registry-untouched over 10000 calls, PD-72 bound-registry + stats-less-facade measurement (where `costOf` fails closed), PD-70 uncached/live across a branch flip, and the A6 fail-closed matrix (plain/unwired/parked/disposed each a NAMED throw, never a `{nodes:0}` report) |
+| `20-fleet` | 37 | `createFleet` on both emit lanes + a buildless class: the `{registry,Class,capacity,acquire,release,at,size,stats,dispose}` handle surface, eager-prefill (all members parked at construction, `acquire` never constructs), `initials` pass-through, the six fail-closed misuses (exhausted/foreign/double-release/use-after-dispose/`at` out-of-range/bad `bind`), atomic mid-prefill cleanup, `dispose()` tearing live AND parked members plus the registry, and the 22 -> 23 export-count freeze |
 
 ### Emit-support matrix
 
@@ -543,6 +570,8 @@ npm run demo:storm          # headless dispose-storm retention lane (lite-leak,
 
 Since 1.4.0 the console is the named consumer of `costOfInstance`: its shape-drift wall measures a real live `Entity` (its node count === the `EntityShape` sizing twin's) and the HUD reports one live fleet member's `costOfInstance` per HUD tick, so the live-vs-`costOf` delta -- a forced ceiling against the lazy live cost -- is visible on screen. The `EntityShape` twin stays for `capacityFor` sizing only (the world must be sized before it exists).
 
+Since 1.5.0 the demo's hand-rolled pool IS `createFleet`: the spawn/kill plumbing (the slot array, free-list, count, and dispose-storm bodies) was DELETED in favor of one fleet handle, and `step`/`readPositions` read members through `fleet.at(i)`. The diff went net-negative -- the demo is the named consumer that admitted the helper (decisions/0013 criterion (d)). The eager prefill moves construction to load (~7ms one-time for 4096 members), the honest cost of a zero-alloc steady state.
+
 The `demo/` directory is dev-only -- it never enters `package.json` `files[]` and never ships to consumers.
 
 ---

package/SignalDecorators.d.ts

@@ -12,6 +12,7 @@ import type {
     NodeDescriptor,
     Registry,
     RegistryConfig,
+    RegistryStats,
     ReactiveHandle,
     EffectScheduler,
 } from "@zakkster/lite-signal";
@@ -480,6 +481,70 @@ export function capacityFor(
     options?: CapacityForOptions,
 ): RegistryConfig;
 
+// --- createFleet --------------------------------------------------------------
+
+/** Options for {@link createFleet}. Forwarded to {@link capacityFor}. */
+export interface CreateFleetOptions {
+    /** Link-budget multiplier (`>= 1`, default `1` = exact). See {@link CapacityForOptions.headroom}. */
+    headroom?: number;
+}
+
+/**
+ * A fixed-capacity pool of reactive instances built by {@link createFleet}. Owns
+ * its registry; `dispose()` tears both members and registry down.
+ */
+export interface Fleet<T extends object = object> {
+    /** The fleet-owned `Registry` the members are bound to. */
+    readonly registry: Registry;
+    /** The bound class `bind(registry)` returned; every member is an instance of it. */
+    readonly Class: new (...args: any[]) => T;
+    /** The fixed member ceiling (sum of the inventory counts), sized eagerly at construction. */
+    readonly capacity: number;
+    /**
+     * Revive a parked member and return it. `initials` overrides its reset values
+     * (undefined = the plan's initials). Zero allocation.
+     * @throws a named `FleetExhaustedError` when all `capacity` members are live.
+     * @throws a named `FleetDisposedError` after `dispose()`.
+     */
+    acquire(initials?: Record<PropertyKey, unknown>): T;
+    /**
+     * Park a member back into the pool. Zero allocation.
+     * @throws a named `FleetForeignMemberError` if `vm` was not acquired from this fleet.
+     * @throws a named `FleetDoubleReleaseError` if `vm` is already parked.
+     * @throws a named `FleetDisposedError` after `dispose()`.
+     */
+    release(vm: T): T;
+    /**
+     * The member in slot `i` (live or parked).
+     * @throws a `RangeError` if `i` is out of `[0, capacity)`.
+     * @throws a named `FleetDisposedError` after `dispose()`.
+     */
+    at(i: number): T;
+    /** The live member count (`capacity` minus parked). */
+    size(): number;
+    /** The fleet-owned registry's stats ledger, passed through. */
+    stats(): RegistryStats;
+    /** Dispose every member (live and parked) and destroy the registry. Idempotent. */
+    dispose(): void;
+}
+
+/**
+ * Build a fixed-capacity {@link Fleet} of reactive instances over the shipped
+ * primitives: `capacityFor(inventory, opts)` sizes a registry, `createRegistry`
+ * builds it, `bind(registry)` binds the caller's decorated class to it and returns
+ * it, then one member per inventory unit is EAGER-constructed and parked (acquire
+ * never constructs). The returned handle acquires/releases members with zero
+ * allocation and fails closed (named throws) on every misuse.
+ *
+ * @throws {TypeError} if `bind` is not a function or does not return a constructor.
+ * @throws if `inventory`/`opts` are invalid (via {@link capacityFor}).
+ */
+export function createFleet<T extends object = object>(
+    inventory: InventoryEntry[],
+    bind: (registry: Registry) => new (...args: any[]) => T,
+    opts?: CreateFleetOptions,
+): Fleet<T>;
+
 /**
  * Toggle devtools labels (default OFF). While ON, wiring registers a
  * `nodeId -> label` for every node an instance creates (`"Class.prop"`,
@@ -531,4 +596,4 @@ export class ReactiveDisposedError extends Error {
 // --- Version ------------------------------------------------------------------
 
 /** Package version. Kept in lockstep with package.json and llms.txt. */
-export const VERSION: "1.4.0";
+export const VERSION: "1.5.0";

package/SignalDecorators.js

@@ -1,5 +1,5 @@
 /**
- * @zakkster/lite-signal-decorators v1.4.0
+ * @zakkster/lite-signal-decorators v1.5.0
  * --------------------
  * Standard-decorators layer over @zakkster/lite-signal. Turns a plain class into
  * a reactive view-model with measured per-instance cost and deterministic
@@ -47,6 +47,7 @@ import {
     stats,
     forEachOwned,
     forEachSource,
+    createRegistry,
 } from "@zakkster/lite-signal";
 
 // --- Module state -------------------------------------------------------------
@@ -2343,6 +2344,222 @@ export function capacityFor(inventory, options) {
     };
 }
 
+// --- createFleet (S11; the fleet helper over the shipped primitives) ----------
+//
+// The flagship-audience helper (0013 (d)): capacityFor -> createRegistry -> bind
+// -> EAGER-prefill N parked members over a slot array + an Int32Array free-list.
+// The demo's hand-rolled pool (loop.ts) is the extracted spec, so acquire/release
+// are the extracted spawn/kill: reinitReactive/releaseReactive with zero-alloc
+// bookkeeping. Cold construction; the hot acquire/release/at bodies are prebuilt
+// closures over the fleet's arrays (zero allocation, fail-closed guards only).
+//
+// SLOT STAMP (PD-77 forcing condition resolved): ownership is proven by a
+// per-fleet Symbol stamped onto each vm at prefill carrying its slot index -- a
+// plain (symbol-keyed) integer field, NOT a WeakMap. A field read is one property
+// load (zero allocation, monomorphic); a WeakMap.get is a slower hash probe AND
+// retains a parallel table for the fleet's lifetime. The stamp is minted per
+// fleet, so a foreign vm (no stamp, or another fleet's stamp) reads `undefined`
+// for THIS fleet's symbol and fails closed. slots[i] === vm re-confirms identity;
+// releaseReactive() returning false (already parked) is the double-release check.
+
+function throwFleetBind() {
+    throw new TypeError(
+        `${ERR}createFleet(inventory, bind, opts?) -- bind must be a function (registry) -> BoundClass.`,
+    );
+}
+
+function throwFleetBindReturn() {
+    throw new TypeError(
+        `${ERR}createFleet -- bind(registry) must return the bound class (a constructor); the fleet constructs its members from it.`,
+    );
+}
+
+function throwFleetExhausted(ctorName, capacity) {
+    // Named so a caller can catch the capacity ceiling distinctly. The registry's
+    // own CapacityError is unreachable (all N are prealloc'd), so this pre-check
+    // is the ONLY exhaustion signal.
+    const e = new Error(
+        `${ERR}fleet<${ctorName}> is exhausted -- all ${capacity} members are live. release() one before acquire(), or size the fleet larger; capacity is fixed at construction (eager prefill).`,
+    );
+    e.name = "FleetExhaustedError";
+    throw e;
+}
+
+function throwFleetForeign(ctorName) {
+    const e = new Error(
+        `${ERR}release(vm) -- vm was not acquired from this fleet<${ctorName}> (no matching slot stamp). Release only members this fleet handed out.`,
+    );
+    e.name = "FleetForeignMemberError";
+    throw e;
+}
+
+function throwFleetDoubleRelease(ctorName) {
+    const e = new Error(
+        `${ERR}release(vm) -- vm is already parked in fleet<${ctorName}> (double release). Each acquire() pairs with exactly one release().`,
+    );
+    e.name = "FleetDoubleReleaseError";
+    throw e;
+}
+
+function throwFleetDead(ctorName, op) {
+    const e = new Error(
+        `${ERR}${op}() -- fleet<${ctorName}> was disposed; its members are torn down and its registry is destroyed. Construct a new fleet.`,
+    );
+    e.name = "FleetDisposedError";
+    throw e;
+}
+
+function throwFleetRange(ctorName, i, capacity) {
+    throw new RangeError(
+        `${ERR}at(${String(i)}) -- index out of bounds for fleet<${ctorName}> [0, ${capacity}).`,
+    );
+}
+
+/**
+ * Build a fixed-capacity fleet of reactive instances over the shipped primitives.
+ * COLD construction sizes a registry from `inventory` (capacityFor), builds it
+ * (createRegistry), hands it to `bind(registry)` so the caller binds its decorated
+ * class to that registry and returns it, then EAGER-constructs and PARKS one
+ * member per inventory unit (PD-75: acquire never constructs). Returns a Fleet
+ * handle `{ registry, Class, capacity, acquire, release, at, size, stats,
+ * dispose }`.
+ *
+ * HOT: `acquire(initials?)` pops the free-list and reinitReactive()s a parked
+ * member (throws `FleetExhaustedError` at capacity); `release(vm)` validates the
+ * slot stamp, releaseReactive()s the member back to the pool (throws on a foreign
+ * vm or a double release), and pushes its slot. `at(i)` is a bounds-checked
+ * slot read; `size()` is the live count; `stats()` passes the registry ledger
+ * through. Both hot bodies allocate nothing.
+ *
+ * `dispose()` disposes every member (live AND parked -> DISPOSED), destroys the
+ * fleet-owned registry, and marks the fleet dead; every later call fails closed
+ * with a named throw. Construction is atomic: any mid-prefill throw disposes the
+ * already-built members and destroys the registry before rethrowing (fail closed).
+ *
+ * @throws {TypeError} if `bind` is not a function or does not return a constructor.
+ * @throws if `inventory`/`opts` are invalid (via capacityFor's fail-closed checks).
+ */
+export function createFleet(inventory, bind, opts) {
+    if (typeof bind !== "function") throwFleetBind();
+    // capacityFor validates inventory + opts (unknown-key did-you-mean, headroom)
+    // and returns the eager/throw config; reuse its fail-closed checks wholesale.
+    const config = capacityFor(inventory, opts);
+    // Total prefill count = the sum of the inventory units (each pair[1] is a
+    // validated positive integer by the time capacityFor returned).
+    let capacity = 0;
+    for (let i = 0; i < inventory.length; i++) capacity += inventory[i][1];
+
+    // The fleet OWNS this registry (dispose() destroys it). Any throw from here
+    // on routes through the atomic-cleanup catch below.
+    const registry = createRegistry(config);
+    const STAMP = Symbol("lite-signal-decorators.fleet");
+    const slots = new Array(capacity);
+    const free = new Int32Array(capacity);      // free-list: free[0..freeTop) = idle slots
+    let Class;
+    let ctorName;
+    let built = 0;
+    try {
+        Class = bind(registry);
+        if (typeof Class !== "function") throwFleetBindReturn();
+        ctorName = Class.name || "fleet";
+        for (let i = 0; i < capacity; i++) {
+            const vm = new Class();             // eager construct on the fleet's registry
+            vm[STAMP] = i;                      // slot stamp: ownership + slot index
+            releaseReactive(vm);                // park it (PD-75); nodes return to pool
+            slots[i] = vm;
+            free[i] = i;
+            built = i + 1;
+        }
+    } catch (e) {
+        for (let j = 0; j < built; j++) disposeReactive(slots[j]);
+        registry.destroy();                     // tear the fleet-owned registry down
+        throw e;                                // atomic: nothing half-built survives
+    }
+
+    let freeTop = capacity;                     // all slots idle (all parked)
+    let dead = false;
+
+    // HOT: revive the head parked slot. reinitReactive resets its boxes to
+    // `initials` (undefined = the plan's reset values) with zero closure alloc.
+    // ORDERING (mirrors fleetRelease): PEEK the candidate via free[freeTop-1],
+    // run the FALLIBLE reinit FIRST, and decrement freeTop only AFTER it succeeds.
+    // reinit throws named on bad initials (e.g. acquire({typo:1})) and on an
+    // out-of-band-disposed member; decrementing before it would strand the popped
+    // slot above freeTop -- lost capacity, over-reported size(). Fail closed:
+    // freeTop moves only on success, so a rejected acquire leaves the slot
+    // acquirable. (a) The disposed case: a member disposed out of band via at()
+    // wedges at the free-list head -- every acquire rethrows reinit's named
+    // "disposed (terminal)" error, refusing loudly rather than eroding capacity
+    // silently. Left as (a) not (b): reinit's disposed and bad-initials throws are
+    // both plain Errors with no distinct code/class, so dropping only the disposed
+    // slot would need brittle message-matching -- a fail-open hazard worse than an
+    // honest, named refusal.
+    function fleetAcquire(initials) {
+        if (dead) throwFleetDead(ctorName, "acquire");
+        if (freeTop === 0) throwFleetExhausted(ctorName, capacity);
+        const i = free[freeTop - 1];
+        const vm = slots[i];
+        reinitReactive(vm, initials);
+        freeTop = freeTop - 1;
+        return vm;
+    }
+
+    // HOT: validate ownership by the slot stamp, then park. `vm[STAMP]` is
+    // `undefined` for a foreign or non-object vm (fail closed); slots[i] === vm
+    // re-confirms identity; releaseReactive() false is the double-release signal.
+    function fleetRelease(vm) {
+        if (dead) throwFleetDead(ctorName, "release");
+        const i = vm !== null && typeof vm === "object" ? vm[STAMP] : undefined;
+        if (i === undefined || slots[i] !== vm) throwFleetForeign(ctorName);
+        if (!releaseReactive(vm)) throwFleetDoubleRelease(ctorName);
+        free[freeTop] = i;
+        freeTop = freeTop + 1;
+        return vm;
+    }
+
+    // HOT: bounds-checked slot read (live OR parked). `i >>> 0` folds negative and
+    // out-of-range into one unsigned compare.
+    function fleetAt(i) {
+        if (dead) throwFleetDead(ctorName, "at");
+        if ((i >>> 0) >= capacity) throwFleetRange(ctorName, i, capacity);
+        return slots[i];
+    }
+
+    function fleetSize() {
+        if (dead) throwFleetDead(ctorName, "size");
+        return capacity - freeTop;              // live = capacity - idle
+    }
+
+    // The fleet-owned registry always comes from createRegistry(), which always
+    // carries the stats ledger, so this is a straight pass-through.
+    function fleetStats() {
+        if (dead) throwFleetDead(ctorName, "stats");
+        return registry.stats();
+    }
+
+    // Dispose every member (live AND parked; disposeReactive on a parked member
+    // lands it DISPOSED), then destroy the registry. Idempotent: a second call
+    // no-ops. After dispose, every hot method fails closed via the `dead` guard.
+    function fleetDispose() {
+        if (dead) return;
+        dead = true;
+        for (let i = 0; i < capacity; i++) disposeReactive(slots[i]);
+        registry.destroy();
+    }
+
+    return {
+        registry,
+        Class,
+        capacity,
+        acquire: fleetAcquire,
+        release: fleetRelease,
+        at: fleetAt,
+        size: fleetSize,
+        stats: fleetStats,
+        dispose: fleetDispose,
+    };
+}
+
 function throwFlagArg(what) {
     throw new TypeError(`${ERR}${what}(on) -- on must be a boolean.`);
 }
@@ -2485,4 +2702,4 @@ export function auditReactive(on) {
 // --- Version ------------------------------------------------------------------
 
 /** Package version. Kept in lockstep with package.json and llms.txt. */
-export const VERSION = "1.4.0";
+export const VERSION = "1.5.0";

package/llms.txt

@@ -1,6 +1,6 @@
 # @zakkster/lite-signal-decorators
 
-VERSION 1.4.0
+VERSION 1.5.0
 
 > Standard-decorators layer over @zakkster/lite-signal, built on the TC39
 > decorators proposal (Stage 2.7 since 2026-05; TS 5.x / Babel 2023-11 emit
@@ -22,7 +22,7 @@ zero decorator syntax, sharing the SAME core by function identity.
 slot for a poison handle, so any later read/write throws a named
 `ReactiveDisposedError`.
 
-## Exports (22)
+## Exports (23)
 
 - `reactive` -- `@reactive accessor x = v` (bare) or `@reactive({ equals })`
   (factory). Declares a per-instance signal.
@@ -135,6 +135,33 @@ slot for a poison handle, so any later read/write throws a named
 - `capacityFor(inventory, { headroom }?) -> RegistryConfig` -- size a
   `createRegistry` config from `[Factory, count]` pairs. Nodes exact, links x
   `headroom` (default 1). Fail-closed inventory validation.
+- `createFleet(inventory, bind, opts?) -> Fleet` -- the flagship-audience fleet
+  helper over the shipped primitives (`capacityFor` + `createRegistry` +
+  park/reinit; decisions/0013 criterion (d)). COLD construction sizes a registry
+  from `inventory`, builds it, hands it to `bind(registry)` (the caller binds its
+  decorated class to that registry and returns it -- the helper never wraps or
+  redefines the class), then EAGER-constructs and PARKS one member per inventory
+  unit. Returns a handle `{ registry, Class, capacity, acquire(initials?),
+  release(vm), at(i), size(), stats(), dispose() }`. Import in the exports block:
+  `import { createFleet } from "@zakkster/lite-signal-decorators"`. LAWS: eager
+  prefill is done at construction -- `acquire` never constructs, it pops a
+  free-list and `reinitReactive`s a parked member (`initials` override the reset
+  values); `release` validates a per-fleet slot stamp and `releaseReactive`s the
+  member back to the pool. Both hot bodies allocate ZERO (a slot array + an
+  `Int32Array` free-list + a per-vm symbol slot stamp -- never a WeakMap). SIX
+  named fail-closed misuses: `acquire` at capacity throws `FleetExhaustedError`
+  (pre-checked; the registry's own `CapacityError` is unreachable, all N are
+  prealloc'd); `release` of a foreign vm throws `FleetForeignMemberError` (the
+  slot stamp is the check); a double release throws `FleetDoubleReleaseError`;
+  any call after `dispose()` throws `FleetDisposedError`; `at(i)` out of
+  `[0, capacity)` throws a `RangeError`; a `bind` that is not a function or does
+  not return a constructor throws a `TypeError`. Construction is ATOMIC: any
+  mid-prefill throw disposes the already-built members and destroys the registry
+  before rethrowing. `dispose()` disposes every member LIVE AND PARKED (park ->
+  dispose lands DISPOSED), then destroys the fleet-owned registry -- parked
+  members are disposed too, not leaked. `null` is not zero at any gate. The demo's
+  hand-rolled pool is the extracted spec (its diff went net-negative when the
+  helper replaced it).
 - `enableLabels(on)` / `labelOf(idOrHandle, registry?) -> string | undefined` --
   opt-in devtools labels (default OFF); per-registry `nodeId -> "Class.prop" /
   "Class#method" / "Class@anchor"`.
@@ -142,7 +169,7 @@ slot for a poison handle, so any later read/write throws a named
   `FinalizationRegistry` reports any instance GC'd without `disposeReactive`.
 - `ReactiveDisposedError` -- `extends Error`, `name` `"ReactiveDisposedError"`,
   fields `className` and `key`.
-- `VERSION` -- `"1.4.0"`.
+- `VERSION` -- `"1.5.0"`.
 
 ## Registry law (one registry per host chain)
 
@@ -288,7 +315,10 @@ and pays its own measured cost. 1.3.0 adds `forEachReactive` + `snapshotOf`
 named in-package consumer that admits `forEachReactive` under the 0009 bar, and
 the 1.0.0 canon stays byte-identical. 1.4.0 adds `costOfInstance` (decisions/0013
 criterion (b); the demo is the named consumer) as an additive MINOR -> 22
-exports; the 1.0.0 canon stays byte-identical. The semver promise from here: any change to an existing export's
+exports; the 1.0.0 canon stays byte-identical. 1.5.0 adds `createFleet`
+(decisions/0013 criterion (d); the demo fleet is the named consumer, its
+hand-rolled pool DELETED for the helper) as an additive MINOR -> 23 exports --
+the 0013 ladder CLOSES at 23; the 1.0.0 canon stays byte-identical. The semver promise from here: any change to an existing export's
 signature or behavior is a MAJOR, recorded in a decision file; new exports are
 minors; the hot accessor canon (`makeGet`/`makeSet`) does not move without a
 major. Also present since

package/package.json

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