pond-ts 0.14.3 → 0.15.1

package/CHANGELOG.md

@@ -7,10 +7,247 @@ 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.3...HEAD
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.15.1...HEAD
 
 ## [Unreleased]
 
+## [0.15.1] — 2026-05-05
+
+Type-narrowing follow-up to v0.15.0. The fused partitioned-rolling
+typing chain exposed a pre-existing pond limitation where
+`partitionBy('host')` widened the partition-column type instead of
+narrowing it to the literal `'host'`. The gRPC experiment's V8
+migration ([pond-grpc-experiment#22](https://github.com/pjm17971/pond-grpc-experiment/pull/22))
+worked around it as `partitionBy<'host'>('host')` — clobbering the
+value-type parameter `K` to fill the column-name slot. v0.15.1
+captures the column literal directly so the workaround can drop.
+
+### Fixed
+
+- **`partitionBy` narrows the partition column literal.** The
+  `by` argument's literal type now flows into a new `ByCol`
+  generic on `LivePartitionedSeries<S, K, ByCol>` and
+  `LivePartitionedView<SBase, R, K, ByCol>`. Threaded through every
+  per-partition method (`fill`, `diff`, `rate`, `pctChange`,
+  `cumulative`, `apply`, the rolling overloads). The fused
+  partitioned-rolling overload's
+  `FusedPartitionedRollingSchema<S, ByCol, FM>` now resolves
+  correctly without the `<'host'>` workaround:
+
+  ```ts
+  // Before v0.15.1: needed the explicit type arg to narrow
+  // host through the fused-rolling schema chain.
+  live.partitionBy<'host'>('host').rolling({ ... }, { trigger });
+
+  // v0.15.1+: the literal 'host' is captured automatically.
+  live.partitionBy('host').rolling({ ... }, { trigger });
+  // Output schema includes `host` narrowed to its column kind;
+  // event.get('host') resolves correctly.
+  ```
+
+  Existing V8 callers using the `partitionBy<'host'>('host')`
+  workaround continue to narrow correctly. Type-parameter order
+  on `partitionBy` is `<ByCol, K>` (column name first, value type
+  second) so the explicit `<'host'>` binds the literal to `ByCol`
+  — exactly what the workaround intended pre-v0.15.1. The
+  workaround can now drop because automatic inference does the
+  same job, but it doesn't have to.
+
+### Type system
+
+- `LivePartitionedSeries<S, K, ByCol>` — third generic added with
+  default `keyof EventDataForSchema<S> & string`. Backwards-
+  compatible: existing references to `LivePartitionedSeries<S, K>`
+  and `LivePartitionedSeries<S>` resolve to the upper-bound default.
+- `LivePartitionedView<SBase, R, K, ByCol>` — same shape; `ByCol`
+  threaded through every chain hop so partition-column literals
+  survive `partitionBy('host').fill(...).rolling({...}, opts)`.
+
+### Test surface
+
+`test-d/fused-rolling.test-d.ts` extended to pin the narrowing at
+both the root and chained levels:
+
+```ts
+const fC = live.partitionBy('host').rolling({ ... }, { trigger });
+sampleEvent.get('host'); // narrows to string | undefined
+
+const chained = live.partitionBy('host').fill({ cpu: 'hold' })
+  .rolling({ '1m': { cpu_avg: ... } }, { trigger });
+chainedSample.get('host'); // narrows correctly through the chain
+```
+
+All 1115 + 55 runtime tests still pass; type-d clean.
+
+[0.15.1]: https://github.com/pjm17971/pond-ts/compare/v0.15.0...v0.15.1
+
+## [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

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"}