pond-ts 0.65.0 → 0.67.0

package/dist/live/listener-set.d.ts

@@ -0,0 +1,18 @@
+/**
+ * [PND-LIVFIX] A listener set whose iteration snapshot is cached: `add` /
+ * `delete` invalidate it, `snapshot()` rebuilds it lazily. Dispatch
+ * iterates the snapshot, so a listener that subscribes or unsubscribes
+ * mid-fan-out neither disturbs the others nor fires for the event it was
+ * added during — without allocating an array per event on the hot path
+ * (subscriptions change rarely; events arrive at kHz).
+ */
+export declare class ListenerSet<F extends (...args: never[]) => void> {
+    #private;
+    get size(): number;
+    add(fn: F): void;
+    delete(fn: F): void;
+    clear(): void;
+    snapshot(): readonly F[];
+    [Symbol.iterator](): Iterator<F>;
+}
+//# sourceMappingURL=listener-set.d.ts.map

package/dist/live/listener-set.js

@@ -0,0 +1,34 @@
+/**
+ * [PND-LIVFIX] A listener set whose iteration snapshot is cached: `add` /
+ * `delete` invalidate it, `snapshot()` rebuilds it lazily. Dispatch
+ * iterates the snapshot, so a listener that subscribes or unsubscribes
+ * mid-fan-out neither disturbs the others nor fires for the event it was
+ * added during — without allocating an array per event on the hot path
+ * (subscriptions change rarely; events arrive at kHz).
+ */
+export class ListenerSet {
+    #set = new Set();
+    #snapshot = null;
+    get size() {
+        return this.#set.size;
+    }
+    add(fn) {
+        this.#set.add(fn);
+        this.#snapshot = null;
+    }
+    delete(fn) {
+        if (this.#set.delete(fn))
+            this.#snapshot = null;
+    }
+    clear() {
+        this.#set.clear();
+        this.#snapshot = null;
+    }
+    snapshot() {
+        return (this.#snapshot ??= Array.from(this.#set));
+    }
+    [Symbol.iterator]() {
+        return this.snapshot()[Symbol.iterator]();
+    }
+}
+//# sourceMappingURL=listener-set.js.map

package/dist/live/live-partitioned-series.d.ts

@@ -6,7 +6,7 @@ import { type LiveFillMapping, type LiveFillStrategy } from './live-view.js';
 import type { Trigger } from './triggers.js';
 import { type DiffSchema, type EventDataForSchema, type LiveSource, type NumericColumnNameForSchema, type RollingSchema, type SeriesSchema } from '../schema/index.js';
 import type { FusedMapping, FusedMappingValid, FusedPartitionedRollingSchema, ValidatedAggregateMap } from '../schema/index.js';
-import type { DurationInput } from '../core/duration.js';
+import { type DurationInput } from '../core/duration.js';
 import type { LiveRollingOptions, RollingWindow } from './live-rolling-aggregation.js';
 /**
  * Per-partition retention and grace settings for a partitioned live

package/dist/live/live-partitioned-series.js

@@ -3,6 +3,14 @@ import { LiveRollingAggregation } from './live-rolling-aggregation.js';
 import { LivePartitionedSyncRolling } from './live-partitioned-sync-rolling.js';
 import { LivePartitionedFusedRolling } from './live-partitioned-fused-rolling.js';
 import { makeCumulativeView, makeDiffView, makeFillView, makeStrideSampleView, } from './live-view.js';
+import { parseDuration } from '../core/duration.js';
+/** [PND-LIVFIX] The option keys `partitionBy` accepts; anything else throws. */
+const PARTITION_OPTION_KEYS = new Set([
+    'groups',
+    'retention',
+    'graceWindow',
+    'ordering',
+]);
 /** Encoder for partition values → keys. Mirrors the batch single-column case. */
 function partitionKey(event, col) {
     const v = event.data()[col];
@@ -92,10 +100,33 @@ export class LivePartitionedSeries {
     // Pipeline counters for {@link LivePartitionedSeries.stats}.
     // Cumulative since construction; never reset.
     #statsEventsRouted = 0;
+    /**
+     * [PND-LIVFIX] Quiet-partition age sweep. Per-partition `maxAge` used
+     * to run only when a partition received a push, so a partition that
+     * went quiet never evicted (audit 2026-06 §4.3). The router now tracks
+     * the source watermark (newest key routed) and, when it has advanced
+     * by at least `#sweepEveryMs` since the last sweep, asks EVERY
+     * partition to age out against it (`LiveSeries._sweepAge`). The
+     * throttle keeps the hot path O(1) per event on high-cardinality
+     * sources — a sweep is O(partitions) — while bounding how long a quiet
+     * partition can overstay `maxAge` to `maxAge / 8`. `Infinity` when the
+     * partition retention has no `maxAge` (nothing to sweep).
+     */
+    #sweepEveryMs;
+    #watermarkMs = -Infinity;
+    #lastSweepMs = -Infinity;
     constructor(source, by, options = {}) {
         this.name = source.name;
         this.schema = source.schema;
         this.by = by;
+        // [PND-LIVFIX] Unknown options used to be silently ignored, so a JS
+        // caller passing e.g. `maxPartitions` got no signal (audit §4.3).
+        for (const key of Object.keys(options)) {
+            if (!PARTITION_OPTION_KEYS.has(key)) {
+                throw new TypeError(`LivePartitionedSeries: unknown option "${key}". Known options: ` +
+                    `${[...PARTITION_OPTION_KEYS].join(', ')}.`);
+            }
+        }
         if (!source.schema.some((c) => c.name === by)) {
             throw new TypeError(`LivePartitionedSeries: column "${String(by)}" not in schema`);
         }
@@ -120,6 +151,11 @@ export class LivePartitionedSeries {
         };
         this.#onSpawn = new Set();
         this.#disposers = new Set();
+        const maxAge = options.retention?.maxAge;
+        this.#sweepEveryMs =
+            maxAge === undefined
+                ? Infinity
+                : Math.max(1, Math.floor(parseDuration(maxAge) / 8));
         // Column-native routing path: when the source is a chunked-backed
         // LiveSeries (top-level strict time-keyed), route its appended chunks
         // through `scatterByPartition`-style bucketing into per-partition
@@ -698,6 +734,32 @@ export class LivePartitionedSeries {
         // instead of round-tripping `Event → row → Event` (which would
         // re-validate and re-allocate per event).
         part._pushTrustedEvents([event]);
+        this.#advanceWatermark(event.begin());
+    }
+    /** [PND-LIVFIX] Track the newest routed key and sweep quiet partitions. */
+    #advanceWatermark(beginMs) {
+        if (this.#sweepEveryMs === Infinity)
+            return;
+        if (beginMs > this.#watermarkMs)
+            this.#watermarkMs = beginMs;
+        if (this.#watermarkMs - this.#lastSweepMs < this.#sweepEveryMs)
+            return;
+        this.#lastSweepMs = this.#watermarkMs;
+        // A partition's `'evict'` listener may throw; the sweep must still
+        // reach every other partition (else a quiet partition waits another
+        // throttle window on someone else's bug). Isolate per partition and
+        // surface the first error after the loop, like a push does.
+        let first;
+        for (const part of this.#partitions.values()) {
+            try {
+                part._sweepAge(this.#watermarkMs);
+            }
+            catch (error) {
+                first ??= { error };
+            }
+        }
+        if (first)
+            throw first.error;
     }
     /**
      * Column-native routing: bucket a source chunk's rows by partition and
@@ -733,6 +795,8 @@ export class LivePartitionedSeries {
             one[0] = i;
             part._stageRows(store, one);
         }
+        if (n > 0)
+            this.#advanceWatermark(store.beginAt(n - 1));
     }
     /**
      * One-time replay of a chunked source's existing buffer at

package/dist/live/live-reduce.d.ts

@@ -65,20 +65,20 @@ type EventListener = (event: any) => void;
  * snapshot to a `TimeSeries` first via
  * `live.toTimeSeries().reduce(...)`.
  *
- * **Caveat — `reorder` + retention specifically.** The windowed
- * reducers `min` / `max` / `first` / `last` / `samples` maintain
- * forward-sliding-window state (a monotone deque, or head-removal
- * ordered entries) that assumes eviction removes the OLDEST-arrived
- * event first. That holds for `strict` / `drop` (append-only) and
- * the chunked backing, but NOT for `reorder` + retention, where the
- * source evicts the sorted-prefix — which may be a later arrival. On
- * that combination those five reducers can report stale or
- * `undefined` snapshots. The value-based reducers (`avg`, `count`,
- * `sum`, `stdev`, `median`, `percentile`, `unique`) remove by value
- * and stay correct. This is a long-standing limitation (it predates
- * the chunked backing); for reliable windowed extrema on a reorder
- * source, snapshot to a `TimeSeries` and `reduce` there. Tracked in
- * PLAN.md "Deferred".
+ * **`reorder` + retention** ([PND-LIVFIX]). The windowed reducers
+ * `min` / `max` / `first` / `last` normally keep forward-sliding-window
+ * state (a monotone deque, head-removal ordered entries) that assumes
+ * eviction removes the oldest-arrived event first — true for `strict` /
+ * `drop` and the chunked backing. A `reorder` source evicts its sorted
+ * prefix, which may be a later arrival, and those states used to go
+ * stale or `undefined` there. Over a `reorder` source this class now
+ * selects removal-by-any-index structures for those four reducers (a
+ * sorted array for the extrema, an index-keyed map for `first` / `last`)
+ * — exact in any eviction order, at O(n) per update instead of O(1),
+ * and only on that source shape. `first` / `last` still follow
+ * ARRIVAL order (the caveat above), never a value the source has
+ * evicted. `samples` and the value-based reducers were already
+ * order-independent.
  *
  * **Source contract — `EMITS_EVICT` is load-bearing.** This
  * class's reducer state stays in sync with the source's current

package/dist/live/live-reduce.js

@@ -68,20 +68,20 @@ import { EMITS_EVICT, } from '../schema/index.js';
  * snapshot to a `TimeSeries` first via
  * `live.toTimeSeries().reduce(...)`.
  *
- * **Caveat — `reorder` + retention specifically.** The windowed
- * reducers `min` / `max` / `first` / `last` / `samples` maintain
- * forward-sliding-window state (a monotone deque, or head-removal
- * ordered entries) that assumes eviction removes the OLDEST-arrived
- * event first. That holds for `strict` / `drop` (append-only) and
- * the chunked backing, but NOT for `reorder` + retention, where the
- * source evicts the sorted-prefix — which may be a later arrival. On
- * that combination those five reducers can report stale or
- * `undefined` snapshots. The value-based reducers (`avg`, `count`,
- * `sum`, `stdev`, `median`, `percentile`, `unique`) remove by value
- * and stay correct. This is a long-standing limitation (it predates
- * the chunked backing); for reliable windowed extrema on a reorder
- * source, snapshot to a `TimeSeries` and `reduce` there. Tracked in
- * PLAN.md "Deferred".
+ * **`reorder` + retention** ([PND-LIVFIX]). The windowed reducers
+ * `min` / `max` / `first` / `last` normally keep forward-sliding-window
+ * state (a monotone deque, head-removal ordered entries) that assumes
+ * eviction removes the oldest-arrived event first — true for `strict` /
+ * `drop` and the chunked backing. A `reorder` source evicts its sorted
+ * prefix, which may be a later arrival, and those states used to go
+ * stale or `undefined` there. Over a `reorder` source this class now
+ * selects removal-by-any-index structures for those four reducers (a
+ * sorted array for the extrema, an index-keyed map for `first` / `last`)
+ * — exact in any eviction order, at O(n) per update instead of O(1),
+ * and only on that source shape. `first` / `last` still follow
+ * ARRIVAL order (the caveat above), never a value the source has
+ * evicted. `samples` and the value-based reducers were already
+ * order-independent.
  *
  * **Source contract — `EMITS_EVICT` is load-bearing.** This
  * class's reducer state stays in sync with the source's current
@@ -182,7 +182,14 @@ export class LiveReduce {
         // the live aggregation surface; keeps `LiveReduce`'s reducer
         // semantics identical to `aggregate` / `rolling`.
         this.#columns = normalizeAggregateColumns(source.schema, mapping);
-        this.#states = this.#columns.map((c) => rollingStateFor(c.reducer));
+        // [PND-LIVFIX] A `reorder` source evicts its sorted prefix, which can
+        // be a later arrival than the FIFO frontier; the windowed states for
+        // `min` / `max` / `first` / `last` must then accept removal of any
+        // index. Ask the source (internal getter on `LiveSeries`); anything
+        // else is append-only.
+        const evictionOrder = source._evictionOrder ??
+            'arrival';
+        this.#states = this.#columns.map((c) => rollingStateFor(c.reducer, evictionOrder));
         // Output schema: source's first (time/keyed) column + each
         // reducer's output column. Matches LiveRollingAggregation's
         // schema shape for consistency.

package/dist/live/live-series.d.ts

@@ -41,14 +41,6 @@ export type LiveSeriesOptions<S extends SeriesSchema> = {
 type EventListener<S extends SeriesSchema> = (event: EventForSchema<S>) => void;
 type BatchListener<S extends SeriesSchema> = (events: ReadonlyArray<EventForSchema<S>>) => void;
 type EvictListener<S extends SeriesSchema> = (events: ReadonlyArray<EventForSchema<S>>) => void;
-/**
- * A mutable, append-optimized event buffer for live ingestion — the entry
- * point to the live layer. `push` validates rows against the same schema
- * as `TimeSeries`, retention (`maxEvents` / `maxAge`) bounds the buffer,
- * and subscribers react on the `'event'`, `'batch'`, and `'evict'`
- * channels; snapshot to the batch layer at any time with `toTimeSeries()`.
- * Example: `new LiveSeries({ name, schema, retention: { maxEvents: 10_000 } })`.
- */
 export declare class LiveSeries<S extends SeriesSchema> {
     #private;
     readonly name: string;
@@ -100,19 +92,24 @@ export declare class LiveSeries<S extends SeriesSchema> {
      * **Commit granularity differs by backing.** On the `Event[]`
      * backing each row is appended then its `'event'` fires, so a
      * handler observes `length` grow row-by-row (`1, 2, …`) within one
-     * `pushMany`, and a handler that throws mid-batch leaves only the
-     * rows up to the throw committed. On the chunked columnar backing
-     * (top-level `strict` time-keyed series) the whole batch is appended
-     * as one chunk *before* any `'event'` fires — so a handler sees the
-     * full post-batch `length` for every event of the batch, and a
-     * handler that throws mid-fan-out leaves the *entire* batch committed
-     * (the chunk is already appended). Both leave `length` and `ingested`
-     * mutually consistent after a throw; they differ only in how much of
-     * the batch is committed. This is intrinsic to all-or-nothing
-     * columnar append — per-row commit would reintroduce the per-row
-     * `Event` cost the chunked backing exists to avoid. The cross-backing
-     * contract callers can rely on: every successfully-ingested row fires
-     * exactly one `'event'`, in order, before `'batch'`/`'evict'`.
+     * `pushMany`. On the chunked columnar backing (top-level `strict`
+     * time-keyed series) the whole batch is appended as one chunk
+     * *before* any `'event'` fires, so a handler sees the full post-batch
+     * `length` for every event of the batch. This is intrinsic to
+     * all-or-nothing columnar append — per-row commit would reintroduce
+     * the per-row `Event` cost the chunked backing exists to avoid. The
+     * cross-backing contract callers can rely on: every
+     * successfully-ingested row fires exactly one `'event'`, in order,
+     * before `'batch'`/`'evict'`.
+     *
+     * **Listener errors are isolated** ([PND-LIVFIX]). A listener that
+     * throws does not stop the push: every row is still committed, the
+     * remaining listeners still run, retention still runs, and `'batch'` /
+     * `'evict'` still fire. The first error is rethrown to the caller once
+     * the push has completed, so `length`, `ingested` and every subscriber
+     * (a derived `filter()` view included) agree afterwards. A push made
+     * from inside a listener is queued and runs after the current push,
+     * in arrival order, so emission stays monotonic.
      */
     pushMany(rows: ReadonlyArray<RowForSchema<S>>): void;
     /**