@pond-ts/react 0.14.1 → 0.14.3

package/CHANGELOG.md

@@ -7,10 +7,123 @@ 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.1...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
+`'samples'` reducer that the v0.14.1 Layer 2 review caught
+post-merge. The runtime worked, but TypeScript didn't know about
+`'samples'`: passing it through `series.aggregate({ col: 'samples' })`
+or `live.rolling(window, { col: 'samples' })` produced
+`Type '"samples"' is not assignable to type 'AggregateReducer'`,
+and `series.reduce({ col: 'samples' }).col` fell through to
+`ColumnValue | undefined` instead of the narrowed array type.
+
+### Fixed
+
+- **`'samples'` is now in the type system everywhere.** Added to
+  `AggregateFunction` union, both branches of
+  `AggregateFunctionsForKind` (numeric and array/string/boolean),
+  `AggregateKindForColumn` (so output columns get
+  `kind: 'array'`), `ArrayAggregateKind`, and the array branch of
+  `ReduceResult` in `types-reduce.ts`.
+
+  ```ts
+  // Pre-v0.14.2: TS error, but ran correctly.
+  // Post-v0.14.2: typechecks and narrows the same way `unique` and
+  // `top${N}` do — `ReadonlyArray<T>` for source kind T.
+  series.reduce({ vals: 'samples' }).vals; // ReadonlyArray<number> | undefined
+
+  series.aggregate(Sequence.every('5s'), { vals: 'samples' });
+  // Output column: { name: 'vals', kind: 'array' }
+  ```
+
+- **`reducer-reference.mdx`** updated: "14 built-in reducers" → 15.
+
+### Added
+
+- `test-d/types.test-d.ts` block pinning `'samples'` narrowing
+  parity with `'unique'` / `'top${N}'`. Closes the regression hole
+  the v0.14.1 review surfaced.
+
+### Known follow-up
+
+The v0.14.1 review also flagged that `npm run verify`'s
+`test:type` step uses `tsconfig.types.json` (covers `src` +
+`test-d/`), not `tsconfig.vitest.json` (covers `test/`) — that's
+why the missing `'samples'` narrowing didn't fail CI even though
+`packages/core/test/samples-reducer.test.ts` had ~30 type errors.
+Captured in DOCPLAN.md / PLAN.md as a future safety-net widening;
+not in scope for v0.14.2 because pre-existing test files have
+their own type drift that would need cleanup first.
+
+[0.14.2]: https://github.com/pjm17971/pond-ts/compare/v0.14.1...v0.14.2
+
 ## [0.14.1] — 2026-05-03
 
 The "samples reducer + lifted custom-fn guard" release. Surfaced by
@@ -40,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') },
   );
@@ -70,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`,
@@ -89,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
@@ -129,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
@@ -378,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 —
@@ -412,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pond-ts/react",
-  "version": "0.14.1",
+  "version": "0.14.3",
   "description": "React hooks for pond-ts live time series",
   "license": "MIT",
   "repository": {