pond-ts 0.14.2 → 0.15.0

package/CHANGELOG.md

@@ -7,10 +7,239 @@ 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.15.0...HEAD
 
 ## [Unreleased]
 
+## [0.15.0] — 2026-05-05
+
+The "fused multi-window rolling" release. Shipping the primitive
+that closes the gRPC experiment's V6→V7 architectural cliff: a
+keyed-form overload on `live.rolling()` that maintains N windows
+in one ingest pass over a single shared deque, emits one merged
+event per trigger boundary, and (on the partitioned variant) eats
+the doubled `#routeEvent` / `#evictPartition` / `_pushTrustedEvents`
+hops V7 surfaced.
+
+Two independent signals motivated this: the gRPC profile-diff
+(PR #19 in `pond-grpc-experiment`) and the buffer-as-window
+persona's metric-agent call site
+(`series.rolling(RETENTION, mapping, ...)` as workaround). Both
+point at one primitive; both shipped together. RFC #20 in
+`pond-grpc-experiment` is the design record.
+
+### Added
+
+- **Keyed-form fused rolling on `LiveSeries.rolling`,
+  `LiveView.rolling`, and `LivePartitionedSeries.rolling`.** Pass
+  a record of `{ duration: mapping }` instead of `(window, mapping)`
+  to declare multiple windows; the rolling maintains them all in
+  one ingest pass:
+
+  ```ts
+  const fused = byHost.rolling(
+    {
+      '1m': {
+        cpu_avg: { from: 'cpu', using: 'avg' },
+        cpu_sd: { from: 'cpu', using: 'stdev' },
+      },
+      '200ms': { cpu_samples: { from: 'cpu', using: 'samples' } },
+    },
+    { trigger: Trigger.every('200ms') },
+  );
+  // fused emits one merged event per boundary with all four
+  // columns; one ingest pass per source event.
+  ```
+
+  - **Output: one merged stream.** All declared windows' columns
+    concatenated into one record per trigger fire — not N
+    accumulators or N streams. User code collapses to one event
+    handler (the V7 → V8 migration in the gRPC experiment drops
+    ~30 lines of `pendingByTs` / `partsFor` / `tryEmit` join
+    machinery).
+  - **Constraints.** Time-based windows only (object keys are
+    duration strings); single trigger across all windows by
+    design (per-window cadence falls back to two `rolling()`
+    calls, paying the V7 cost). On partitioned series, clock
+    trigger is required.
+  - **Per-window options.** Use the elaborated value form
+    (`{ mapping, minSamples }`) when one window needs different
+    options from the rest; bare-mapping value stays clean for
+    the common case.
+  - **Duplicate output column names** across windows are rejected
+    at construction with a clear error. Partition column auto-
+    injection is unified across all windows.
+  - **Single-window equivalence pin.**
+    `live.rolling('1m', mapping, opts)` and
+    `live.rolling({ '1m': mapping }, opts)` produce identical
+    output (locked down by tests).
+
+- **`LiveFusedRolling<S, Out>`** — non-partitioned class, exposed
+  on the public surface via `live.rolling({...}, opts)`.
+- **`LivePartitionedFusedRolling<S, K, Out>`** — synchronised-cross-
+  partition class, exposed via `byHost.rolling({...}, { trigger })`.
+- **Type-level surface:** `FusedMapping<S>`, `FusedMappingValue<S>`,
+  `FusedMappingElaborated<S>`, `FusedRollingSchema<S, FM>`,
+  `FusedPartitionedRollingSchema<S, ByCol, FM>`, and
+  `DurationString` — all exported from `pond-ts`. Output column
+  kinds narrow correctly through `event.get('cpu_avg')` to
+  `number | undefined`.
+
+### Performance
+
+`packages/core/scripts/perf-fused-rolling.mjs` — bench against
+gRPC RFC #20 acceptance criteria. Headline numbers (median of 3
+runs, `node --expose-gc`):
+
+```
+Partitioned, 100k events × 100 hosts (the gRPC use case):
+                                     wall (ms)    heap (MB)
+  single rolling baseline                95.20       74.33
+  two separate rollings (V7 shape)      141.12      101.71
+  fused two-window (V8 shape)           112.36       68.46
+
+Fused vs V7 shape:    -20.4% wall,  -32.7% heap
+Fused vs baseline:    +18.0% wall,   -7.9% heap
+
+Partitioned, 100k events × 1000 hosts (saturation):
+                                     wall (ms)    heap (MB)
+  two separate rollings (V7 shape)      700.35      556.56
+  fused two-window (V8 shape)           446.21      309.25
+
+Fused vs V7 shape:    -36.3% wall,  -44.4% heap
+```
+
+**Scaling beyond two windows — the architectural argument
+verified.** Every per-event pond hop runs ONCE in fused vs N times
+in N separate rollings. The bench scales N from 2 to 5 windows
+over the same 100k-events × 100-hosts source:
+
+```
+                Separate (ms)   Fused (ms)   Wall delta
+  N = 2            152.91         102.91       -32.7%
+  N = 3            186.63          79.89       -57.2%
+  N = 4            245.42         107.51       -56.2%
+  N = 5            279.79         118.90       -57.5%
+
+                Separate (MB)   Fused (MB)   Heap delta
+  N = 2            108.13          72.20       -33.2%
+  N = 3             93.30          43.08       -53.8%
+  N = 4            113.69          47.19       -58.5%
+  N = 5            137.17          47.12       -65.6%
+```
+
+Fused stays roughly constant (~100ms) across N=2..5; separate
+scales linearly. At N=5: **2.4× faster wall, 34% of the heap.**
+
+The architectural cliff is closed and the win compounds with N.
+Fused rolling's per-event cost is O(1) in the number of windows
+for pipeline overhead — only O(N) for the unavoidable per-window
+reducer-state updates (which separate also pays). Heap is
+dominated by the saved per-rolling deque + per-partition state.
+
+### Notes on what this does NOT include
+
+- **`live.reduce(mapping)` sugar.** Designed in PLAN as
+  `live.rolling({ buffer: mapping }, { history: false })`; the
+  `'buffer'` sentinel is reserved at the type level but throws at
+  runtime for now. Lands with the buffer-as-window Tier 1 PR.
+- **`TimeSeries.rolling` snapshot-side parity.** The keyed-form
+  overload is live-side only in v0.15.0; batch-side comes in a
+  follow-up.
+- **Path A (share `LiveSeries` buffer).** Currently Path B (own
+  deque) — fused rolling subscribes via `'event'` and maintains
+  its own per-partition deque. Path A is a transparent perf
+  follow-up; same API.
+- **Compile-time uniqueness check on output columns.** Runtime
+  check is in place; the type-level `CheckUniqueOutputs` helper
+  is parked as a follow-up. Same with tightening `DurationString`
+  to reject `'1min'`-style typos at the type level (today's
+  template-literal type is permissive; runtime `parseDuration`
+  catches malformed durations).
+
+### Migration
+
+Existing `live.rolling(window, mapping, opts)` calls are
+unchanged. The keyed form is opt-in and additive. Two-rolling
+patterns can migrate by collapsing to one fused call:
+
+```ts
+// Before:
+const baseline = byHost.rolling('1m', m1, { trigger });
+const slice = byHost.rolling('200ms', m2, { trigger });
+// Then a per-(ts, host) join over both event streams …
+
+// After:
+const fused = byHost.rolling({ '1m': m1, '200ms': m2 }, { trigger });
+fused.on('event', (e) => {
+  // All columns from both windows on one event.
+});
+```
+
+[0.15.0]: https://github.com/pjm17971/pond-ts/compare/v0.14.3...v0.15.0
+
+## [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 +320,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 +350,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 +368,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 +408,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 +657,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 +691,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/LiveFusedRolling.d.ts

@@ -0,0 +1,55 @@
+import type { ColumnValue, EventForSchema, LiveSource, SeriesSchema } from './types.js';
+import type { FusedMapping } from './types-fused-rolling.js';
+import type { LiveRollingOptions } from './LiveRollingAggregation.js';
+type EventListener = (event: any) => void;
+/**
+ * Multi-window rolling that maintains N windows in one ingest pass
+ * over a single shared deque. Replaces the workaround of multiple
+ * separate `LiveRollingAggregation`s sharing the same source — the
+ * gRPC experiment's V6→V7 profile-diff (PR #19) showed every per-
+ * event pond hop roughly doubled when running two rollings.
+ *
+ * Each declared window has:
+ *  - Its own resolved duration (clipped to retention; see PLAN.md)
+ *  - Its own column-spec list and reducer states
+ *  - Its own head cursor into the shared deque
+ *
+ * Output is ONE merged stream: one event per trigger boundary, with
+ * all windows' columns concatenated into one record. Duplicate
+ * output column names across windows are rejected at construction
+ * with a clear error (compile-time detection is queued as a
+ * follow-up).
+ *
+ * **Single trigger.** All windows share the configured trigger.
+ * Per-window cadence is explicitly NOT supported — that's what
+ * fusion saves. Users who need per-window cadence fall back to two
+ * separate `rolling()` calls and pay the V7 cost.
+ *
+ * **Time-based windows only.** Object keys are duration strings.
+ * Count-based windows stay on the existing single-window
+ * `LiveRollingAggregation`. This constraint keeps the
+ * window-clip-to-retention rule and boundary-detection logic clean.
+ *
+ * Public API: constructed via the `live.rolling(fusedMapping, opts)`
+ * keyed-form overload on `LiveSeries` / `LiveView`. User code
+ * doesn't import this class directly.
+ */
+export declare class LiveFusedRolling<S extends SeriesSchema, Out extends SeriesSchema = SeriesSchema> implements LiveSource<Out> {
+    #private;
+    readonly name: string;
+    readonly schema: Out;
+    constructor(source: LiveSource<S>, fusedMapping: FusedMapping<S>, options?: LiveRollingOptions);
+    get length(): number;
+    at(index: number): EventForSchema<Out> | undefined;
+    /**
+     * Read the current merged snapshot — every window's reducer
+     * outputs concatenated into one record. Useful for live-display
+     * patterns where the consumer wants the latest values without
+     * waiting for the next trigger fire.
+     */
+    value(): Record<string, ColumnValue | undefined>;
+    on(type: 'event', fn: EventListener): () => void;
+    dispose(): void;
+}
+export {};
+//# sourceMappingURL=LiveFusedRolling.d.ts.map

package/dist/LiveFusedRolling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LiveFusedRolling.d.ts","sourceRoot":"","sources":["../src/LiveFusedRolling.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAGV,WAAW,EACX,cAAc,EACd,UAAU,EACV,YAAY,EACb,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,YAAY,EAAqB,MAAM,0BAA0B,CAAC;AAChF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAwCtE,KAAK,aAAa,GAAG,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,gBAAgB,CAC3B,CAAC,SAAS,YAAY,EACtB,GAAG,SAAS,YAAY,GAAG,YAAY,CACvC,YAAW,UAAU,CAAC,GAAG,CAAC;;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC;gBAoCnB,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,EACrB,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC,EAC7B,OAAO,GAAE,kBAAuB;IAyGlC,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,GAAG,SAAS;IAKlD;;;;;OAKG;IACH,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IAahD,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,aAAa,GAAG,MAAM,IAAI;IAYhD,OAAO,IAAI,IAAI;CA0IhB"}