pond-ts 0.14.2 → 0.14.3

package/CHANGELOG.md

@@ -7,10 +7,72 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 file covers both packages. Pre-1.0: minor bumps may include new features and
 type-level changes; patch bumps are strictly additive.
 
-[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.14.2...HEAD
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.14.3...HEAD
 
 ## [Unreleased]
 
+## [0.14.3] — 2026-05-04
+
+A targeted allocation fix in the `'samples'` reducer's rolling-state
+implementation. Motivated by gRPC experiment V7 numbers — at the
+ceiling regime (1k partitions × 1k events/s, 1M target) the all-
+pond pipeline using `samples()` regressed throughput ~19% vs V6's
+hybrid pond-rolling + manual-deque pattern, with +17% heap at
+moderate loads. Per-event cost analysis pointed at a 1-element
+`ScalarValue[]` allocation per scalar `add()` — one wasted
+allocation per event compounding under sustained kHz × N-partition
+load.
+
+### Changed
+
+- **`samples.rollingState()` skips array wrap for scalar source
+  columns.** Scalar values (the common case at saturation) now
+  store directly into the keyed map; only array-kind sources
+  build a sub-array (because `remove(index)` needs to drop a
+  single event's contributions together). Snapshot branches on
+  `Array.isArray` to flatten the mixed map.
+
+  ```
+  Focused micro-bench (5M scalar add+remove cycles):
+                       median (ms)   min (ms)   max (ms)
+  baseline (v0.14.2)      239.85      236.62     244.58
+  v0.14.3                 209.09      207.42     215.26
+  delta                   −12.8%      −12.3%     −12.0%
+
+  Integration bench (100k events × N hosts, full pipeline):
+  Tight wall-clock parity within run-to-run noise across all
+  scenarios (samples 1m/5s, scalar/array). Allocation pressure
+  isn't the dominant cost at this scale; the optimization
+  compounds only at saturation regimes where GC pressure stacks.
+  ```
+
+  Behavior is preserved bit-for-bit — every existing
+  `samples-reducer.test.ts` assertion passes without modification.
+
+### Added
+
+- `packages/core/scripts/perf-samples-reducer.mjs` — benchmark
+  covering the focused micro-bench + four integration scenarios
+  (scalar moderate / scalar high-cardinality / scalar high-churn
+  / array source) with a comparison anchor against `'avg'` on
+  the same shape. Run with `node --expose-gc` for heap numbers.
+
+### Note on saturation regimes
+
+V7's regression isn't fully closed by this fix. The remaining gap
+is architectural — V7 routes events through two full
+`LiveRollingAggregation` pipelines (Map ops + reducer state +
+trigger dispatch + subscriber fan-out per pipeline), where V6's
+hybrid had one pond rolling for stats plus a passive
+`array.push` listener for raw values. At the kHz × 1k-partition
+saturation regime, the manual-deque pattern is genuinely the
+right shape; pond's `samples` is for typical loads where per-
+event overhead is invisible. A shared-buffer primitive (parked
+as `tap()` in PLAN.md) would close the saturation gap; out of
+scope for v0.14.3.
+
+[0.14.3]: https://github.com/pjm17971/pond-ts/compare/v0.14.2...v0.14.3
+
 ## [0.14.2] — 2026-05-03
 
 Hotfix over v0.14.1 — closes a type-narrowing gap on the new
@@ -91,7 +153,7 @@ either). Two related changes ship together to close both gaps.
     '1m',
     {
       mean: { from: 'cpu', using: 'avg' },
-      sd:   { from: 'cpu', using: 'stdev' },
+      sd: { from: 'cpu', using: 'stdev' },
     },
     { trigger: Trigger.every('30s') },
   );
@@ -121,7 +183,6 @@ either). Two related changes ship together to close both gaps.
   function-typed reducers. New `bucketStateFor` and `rollingStateFor`
   helpers in `reducers/index.ts` route built-ins to their dedicated
   O(1) machinery and wrap custom functions in a generic adapter:
-
   - **Bucket adapter** (`LiveAggregation`): buffers values, calls
     the function once at `snapshot()` time. O(N) per snapshot.
   - **Rolling adapter** (`LiveRollingAggregation`,
@@ -140,7 +201,7 @@ either). Two related changes ship together to close both gaps.
 
   Pre-v0.14.1, calling `live.rolling(...)` with a custom-function
   reducer threw `TypeError: live rolling reducer for output 'X' must
-  be a built-in name; ...`. Post-v0.14.1, the same call constructs
+be a built-in name; ...`. Post-v0.14.1, the same call constructs
   successfully and runs.
 
 ### Tests
@@ -180,13 +241,13 @@ re-allocations). Both root-caused, both fixed.
 Benchmark deltas on `scripts/perf-live-partitioned.mjs`
 (100k events, median ms):
 
-| Scenario                              | Before | After  | Δ       |
-| ------------------------------------- | -----: | -----: | ------: |
-| bare `LiveSeries.push`                |  41.11 |  30.08 | **−27%** |
-| `partitionBy('host')` routing (10)    |  83.14 |  39.10 | **−53%** |
-| `partitionBy + collect()`             | 124.82 |  49.96 | **−60%** |
-| `partitionBy + apply(fill)`           | 120.53 |  49.64 | **−59%** |
-| `partitionBy('host')` routing (1000)  | 105.92 |  43.23 | **−59%** |
+| Scenario                             | Before | After |        Δ |
+| ------------------------------------ | -----: | ----: | -------: |
+| bare `LiveSeries.push`               |  41.11 | 30.08 | **−27%** |
+| `partitionBy('host')` routing (10)   |  83.14 | 39.10 | **−53%** |
+| `partitionBy + collect()`            | 124.82 | 49.96 | **−60%** |
+| `partitionBy + apply(fill)`          | 120.53 | 49.64 | **−59%** |
+| `partitionBy('host')` routing (1000) | 105.92 | 43.23 | **−59%** |
 
 The bare-push delta is from the byte-estimate removal; the
 partition-routing deltas are from the trusted-pipeline path that
@@ -429,7 +490,7 @@ the live surface.
 - **Better error message when a custom-function reducer is passed to
   live aggregation.** `LiveAggregation` already failed at construction
   via `resolveReducer(reducer)` (with a generic `unsupported aggregate
-  reducer` message); now the eager built-in-name check runs first and
+reducer` message); now the eager built-in-name check runs first and
   emits a targeted error pointing at the `AggregateOutputMap` alias
   workaround. Same eager behavior on `LivePartitionedSyncRolling`,
   which previously failed lazily when the first partition spawned —
@@ -463,8 +524,8 @@ the live surface.
   required TS to see the `trigger` field's discriminator at the call
   site — so a caller writing
   `const opts: LiveRollingOptions = { trigger: Trigger.event() };
-  partitioned.rolling(window, mapping, opts);` got `TS2769 No
-  overload matches this call`. Pre-existing hole on the partitioned
+partitioned.rolling(window, mapping, opts);` got `TS2769 No
+overload matches this call`. Pre-existing hole on the partitioned
   surface; surfaced by the v0.13.0 Codex adversarial pass. Closed by
   adding catch-all overloads that accept the broader
   `LiveRollingOptions` and return the union of both trigger

package/dist/reducers/samples.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"samples.d.ts","sourceRoot":"","sources":["../../src/reducers/samples.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAoB7C;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,OAAO,EAAE,UAwCrB,CAAC"}
+{"version":3,"file":"samples.d.ts","sourceRoot":"","sources":["../../src/reducers/samples.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAoB7C;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,OAAO,EAAE,UA2DrB,CAAC"}

package/dist/reducers/samples.js

@@ -55,11 +55,28 @@ export const samples = {
     rollingState() {
         // Map keyed by event index so `remove` is O(1). `Array.from(map.values())`
         // returns insertion order, which matches arrival order.
+        //
+        // Stored value is `ScalarValue | ScalarValue[]`: scalar source columns
+        // (the common case at kHz × N-partition load) skip wrapping each event
+        // in a 1-element array, dropping one allocation per `add`. Only
+        // array-kind sources need a sub-array (so a single event's contributions
+        // can be dropped together on `remove(index)`).
         const items = new Map();
         return {
             add(index, v) {
+                if (v === undefined)
+                    return;
+                if (isScalar(v)) {
+                    items.set(index, v);
+                    return;
+                }
+                // Array-kind source: flatten one level, store the sub-array so
+                // remove(index) drops every contribution from this event.
                 const collected = [];
-                collectInto(collected, v);
+                for (const element of v) {
+                    if (isScalar(element))
+                        collected.push(element);
+                }
                 if (collected.length > 0)
                     items.set(index, collected);
             },
@@ -68,9 +85,14 @@ export const samples = {
             },
             snapshot() {
                 const out = [];
-                for (const arr of items.values()) {
-                    for (const v of arr)
+                for (const v of items.values()) {
+                    if (Array.isArray(v)) {
+                        for (const x of v)
+                            out.push(x);
+                    }
+                    else {
                         out.push(v);
+                    }
                 }
                 return out;
             },

package/dist/reducers/samples.js.map

@@ -1 +1 @@
-{"version":3,"file":"samples.js","sourceRoot":"","sources":["../../src/reducers/samples.ts"],"names":[],"mappings":"AAGA,SAAS,QAAQ,CAAC,CAA0B;IAC1C,OAAO,CACL,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,SAAS,CACzE,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,SAAS,WAAW,CAAC,GAAkB,EAAE,CAA0B;IACjE,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO;IAC5B,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QAChB,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACZ,OAAO;IACT,CAAC;IACD,KAAK,MAAM,OAAO,IAAI,CAAC,EAAE,CAAC;QACxB,IAAI,QAAQ,CAAC,OAAO,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3C,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,OAAO,GAAe;IACjC,UAAU,EAAE,OAAO;IACnB,MAAM,CAAC,OAAO;QACZ,MAAM,GAAG,GAAkB,EAAE,CAAC;QAC9B,KAAK,MAAM,CAAC,IAAI,OAAO;YAAE,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAC7C,OAAO,GAAG,CAAC;IACb,CAAC;IACD,WAAW;QACT,MAAM,KAAK,GAAkB,EAAE,CAAC;QAChC,OAAO;YACL,GAAG,CAAC,CAAC;gBACH,WAAW,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YACxB,CAAC;YACD,QAAQ;gBACN,OAAO,KAAK,CAAC,KAAK,EAAE,CAAC;YACvB,CAAC;SACF,CAAC;IACJ,CAAC;IACD,YAAY;QACV,2EAA2E;QAC3E,wDAAwD;QACxD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAyB,CAAC;QAC/C,OAAO;YACL,GAAG,CAAC,KAAK,EAAE,CAAC;gBACV,MAAM,SAAS,GAAkB,EAAE,CAAC;gBACpC,WAAW,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;gBAC1B,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;oBAAE,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;YACxD,CAAC;YACD,MAAM,CAAC,KAAK,EAAE,EAAE;gBACd,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;YACD,QAAQ;gBACN,MAAM,GAAG,GAAkB,EAAE,CAAC;gBAC9B,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;oBACjC,KAAK,MAAM,CAAC,IAAI,GAAG;wBAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBACnC,CAAC;gBACD,OAAO,GAAG,CAAC;YACb,CAAC;SACF,CAAC;IACJ,CAAC;CACF,CAAC"}
+{"version":3,"file":"samples.js","sourceRoot":"","sources":["../../src/reducers/samples.ts"],"names":[],"mappings":"AAGA,SAAS,QAAQ,CAAC,CAA0B;IAC1C,OAAO,CACL,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,SAAS,CACzE,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,SAAS,WAAW,CAAC,GAAkB,EAAE,CAA0B;IACjE,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO;IAC5B,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QAChB,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACZ,OAAO;IACT,CAAC;IACD,KAAK,MAAM,OAAO,IAAI,CAAC,EAAE,CAAC;QACxB,IAAI,QAAQ,CAAC,OAAO,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3C,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,OAAO,GAAe;IACjC,UAAU,EAAE,OAAO;IACnB,MAAM,CAAC,OAAO;QACZ,MAAM,GAAG,GAAkB,EAAE,CAAC;QAC9B,KAAK,MAAM,CAAC,IAAI,OAAO;YAAE,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAC7C,OAAO,GAAG,CAAC;IACb,CAAC;IACD,WAAW;QACT,MAAM,KAAK,GAAkB,EAAE,CAAC;QAChC,OAAO;YACL,GAAG,CAAC,CAAC;gBACH,WAAW,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YACxB,CAAC;YACD,QAAQ;gBACN,OAAO,KAAK,CAAC,KAAK,EAAE,CAAC;YACvB,CAAC;SACF,CAAC;IACJ,CAAC;IACD,YAAY;QACV,2EAA2E;QAC3E,wDAAwD;QACxD,EAAE;QACF,uEAAuE;QACvE,uEAAuE;QACvE,gEAAgE;QAChE,yEAAyE;QACzE,+CAA+C;QAC/C,MAAM,KAAK,GAAG,IAAI,GAAG,EAAuC,CAAC;QAC7D,OAAO;YACL,GAAG,CAAC,KAAK,EAAE,CAAC;gBACV,IAAI,CAAC,KAAK,SAAS;oBAAE,OAAO;gBAC5B,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;oBAChB,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;oBACpB,OAAO;gBACT,CAAC;gBACD,+DAA+D;gBAC/D,0DAA0D;gBAC1D,MAAM,SAAS,GAAkB,EAAE,CAAC;gBACpC,KAAK,MAAM,OAAO,IAAI,CAAC,EAAE,CAAC;oBACxB,IAAI,QAAQ,CAAC,OAAO,CAAC;wBAAE,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACjD,CAAC;gBACD,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;oBAAE,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;YACxD,CAAC;YACD,MAAM,CAAC,KAAK,EAAE,EAAE;gBACd,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;YACD,QAAQ;gBACN,MAAM,GAAG,GAAkB,EAAE,CAAC;gBAC9B,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;oBAC/B,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;wBACrB,KAAK,MAAM,CAAC,IAAI,CAAC;4BAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;oBACjC,CAAC;yBAAM,CAAC;wBACN,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;oBACd,CAAC;gBACH,CAAC;gBACD,OAAO,GAAG,CAAC;YACb,CAAC;SACF,CAAC;IACJ,CAAC;CACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pond-ts",
-  "version": "0.14.2",
+  "version": "0.14.3",
   "description": "TypeScript-first time series primitives",
   "license": "MIT",
   "repository": {