pond-ts 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -7,7 +7,8 @@ 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.22.0...HEAD
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.23.0...HEAD
+[0.23.0]: https://github.com/pjm17971/pond-ts/compare/v0.22.0...v0.23.0
 [0.22.0]: https://github.com/pjm17971/pond-ts/compare/v0.21.0...v0.22.0
 [0.21.0]: https://github.com/pjm17971/pond-ts/compare/v0.20.0...v0.21.0
 [0.20.0]: https://github.com/pjm17971/pond-ts/compare/v0.19.0...v0.20.0
@@ -16,6 +17,81 @@ type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.23.0] — 2026-06-13
+
+### Added
+
+- **`new TimeSeries({ …, sort: true })` (and `TimeSeries.fromJSON`) sort rows by
+  key on construction.** Pond requires rows in non-decreasing key order and
+  throws otherwise; `sort: true` accepts unsorted input (messy CSVs, merged
+  sources) and sorts it for you instead of forcing a manual pre-sort. The sort
+  is **stable** — rows with equal keys keep their input order — matching what
+  `TimeSeries.fromEvents` already does. The out-of-order error now names the
+  option. (Audit v2 §5 F3.)
+
+### Changed
+
+- **CommonJS consumers now get a clear error instead of
+  `ERR_PACKAGE_PATH_NOT_EXPORTED`.** Both `pond-ts` and `@pond-ts/react`
+  add a `require` condition to their `exports["."]` map pointing at a tiny
+  shipped CJS stub that throws an ESM-only message naming `import` as the
+  fix. The packages remain ES-module-only; this only improves the error a
+  `require('pond-ts')` caller sees. (Audit v2 §5 F6/F7/F9/F10/F11)
+- **Published tarballs no longer ship `*.js.map` / `*.d.ts.map` source
+  maps.** The maps referenced a `../src` tree that was never included in
+  the tarball (`files: ["dist", …]`), so they were dead weight (~⅓ of the
+  unpacked size). A `prepack` step now strips them from the published
+  artifact for both packages; local `npm run build` still emits them, so
+  in-repo debugging is unaffected. (Audit v2 §5 F6/F7/F9/F10/F11)
+
+### Fixed
+
+- **Shipped `.d.ts` now type-check under `skipLibCheck: false`.** The internal
+  `EMITS_EVICT` marker symbol was `@internal` (stripped from the emitted
+  `series.d.ts`) but still referenced by un-stripped public declarations — a
+  by-name re-export in `schema/index.d.ts` and the `[EMITS_EVICT]` brand members
+  on `LiveSeries` / `LiveView` — leaving dangling references that broke strict
+  consumer builds with **TS2305**. Those references are now `@internal` too, so
+  the symbol is fully stripped from the published types; runtime behavior is
+  unchanged. (Audit v2 §5 F2.)
+- **`TimeSeries.at(-1)` counts from the end**, matching `LiveSeries.at` and
+  `Array.prototype.at` (it previously returned `undefined` for any negative
+  index). Deep underflow (e.g. `at(-100)` on a 3-event series) still returns
+  `undefined`, and the non-integer / `NaN` guard is unchanged. (Audit v2 §5 F8.)
+- **Docs: corrected `Time.asString()` (does not exist), the missing
+  `aggregate`/`materialize` → `pivotByGroup` rekey pointer, and an
+  inaccurate `rolling().value()` return-type example.** The getting-started
+  example now calls `event.key().toDate().toISOString()`; the aggregation
+  and reshape pages note that interval-keyed output must be rekeyed with
+  `.asTime({ at: 'begin' })` before a time-keyed transform like
+  `pivotByGroup` (whose runtime error now says so too); the rolling page
+  documents `value()` as `Record<string, ColumnValue | undefined>`.
+  (Audit v2 §5 F6/F7/F9/F10/F11)
+- **Mixed shorthand + `{ from, using }` mappings now keep every output
+  column in the result type (Audit v2 §5 F1).** Calling
+  `aggregate` / `rolling` / `reduce` with a mapping that mixes the
+  shorthand form (`cpu: 'avg'`) and the spec form
+  (`cpu_p95: { from: 'cpu', using: 'p95' }`) in one call — the
+  docs-blessed pattern — previously resolved to the shorthand overload
+  and **silently dropped every spec-keyed output column from the result
+  type** (`event.get('cpu_p95')` failed to compile with `TS2345`), even
+  though the runtime emitted the column. The two overloads
+  (`AggregateMap` shorthand + `AggregateOutputMap` spec) are now
+  collapsed into one unified mapping shape whose result schema dispatches
+  per output key, so all columns survive and each narrows to its
+  reducer's output kind. Runtime behavior is unchanged — this is a
+  types-only fix plus the tests that should have caught it.
+- **The unified mapping keeps the shorthand compile-time guards.** A
+  shorthand reducer is still kind-checked against its source column
+  (`host: 'avg'` on a `string` column stays a compile error), and a bare
+  reducer on a key that is not a source column (`ghost: 'avg'` — a typo
+  the runtime rejects with "unknown source column") is now a compile
+  error too. Spec keys (`{ from, using }`) remain free output names.
+  Inline mapping literals get full validation; values pre-widened to
+  `AggregateMap<S>` and broad-schema (`TimeSeries<SeriesSchema>`)
+  callers keep the permissive shape. `AggregateOutputMap` is retained
+  as a back-compat alias of `AggregateMap`.
+
 ## [0.22.0] — 2026-06-12
 
 ### Changed

package/dist/batch/partitioned-time-series.d.ts

@@ -4,8 +4,7 @@ import { Sequence } from '../sequence/sequence.js';
 import type { DurationInput } from '../core/duration.js';
 import type { TemporalLike } from '../core/temporal.js';
 import type { BatchSampleStrategy } from '../sequence/sample.js';
-import type { AggregateMap, AggregateOutputMap, AggregateSchema, AlignSchema, BaselineSchema, DedupeKeep, DiffSchema, EventDataForSchema, FillMapping, FillStrategy, MaterializeSchema, NumericColumnNameForSchema, RollingAlignment, RollingSchema, SeriesSchema, SmoothAppendSchema, SmoothMethod, SmoothSchema } from '../schema/index.js';
-import type { AggregateOutputMapResultSchema, RollingOutputMapSchema } from '../schema/index.js';
+import type { AggregateSchema, AlignSchema, BaselineSchema, DedupeKeep, DiffSchema, EventDataForSchema, FillMapping, FillStrategy, MaterializeSchema, NumericColumnNameForSchema, RollingAlignment, RollingSchema, SeriesSchema, SmoothAppendSchema, SmoothMethod, SmoothSchema, ValidatedAggregateMap } from '../schema/index.js';
 type SequenceLike = Sequence | BoundedSequence;
 type AlignMethod = 'hold' | 'linear';
 type AlignSample = 'begin' | 'center' | 'end';
@@ -247,26 +246,16 @@ export declare class PartitionedTimeSeries<S extends SeriesSchema, K extends str
         range?: TemporalLike;
     }): PartitionedTimeSeries<MaterializeSchema<S>, K>;
     /** Per-partition `rolling`. See {@link TimeSeries.rolling}. */
-    rolling<const Mapping extends AggregateMap<S>>(window: DurationInput, mapping: Mapping, options?: {
+    rolling<const Mapping extends ValidatedAggregateMap<S, Mapping>>(window: DurationInput, mapping: Mapping, options?: {
         alignment?: RollingAlignment;
         minSamples?: number;
     }): PartitionedTimeSeries<RollingSchema<S, Mapping>, K>;
-    rolling<const Mapping extends AggregateOutputMap<S>>(window: DurationInput, mapping: Mapping, options?: {
-        alignment?: RollingAlignment;
-        minSamples?: number;
-    }): PartitionedTimeSeries<RollingOutputMapSchema<S, Mapping>, K>;
-    rolling<const Mapping extends AggregateMap<S>>(sequence: SequenceLike, window: DurationInput, mapping: Mapping, options?: {
+    rolling<const Mapping extends ValidatedAggregateMap<S, Mapping>>(sequence: SequenceLike, window: DurationInput, mapping: Mapping, options?: {
         alignment?: RollingAlignment;
         sample?: AlignSample;
         range?: TemporalLike;
         minSamples?: number;
     }): PartitionedTimeSeries<AggregateSchema<S, Mapping>, K>;
-    rolling<const Mapping extends AggregateOutputMap<S>>(sequence: SequenceLike, window: DurationInput, mapping: Mapping, options?: {
-        alignment?: RollingAlignment;
-        sample?: AlignSample;
-        range?: TemporalLike;
-        minSamples?: number;
-    }): PartitionedTimeSeries<AggregateOutputMapResultSchema<S, Mapping>, K>;
     /** Per-partition `smooth`. See {@link TimeSeries.smooth}. */
     smooth<const Target extends NumericColumnNameForSchema<S>, const Output extends string | undefined = undefined>(column: Target, method: SmoothMethod, options: {
         alpha: number;
@@ -319,12 +308,9 @@ export declare class PartitionedTimeSeries<S extends SeriesSchema, K extends str
     /** Per-partition `shift`. See {@link TimeSeries.shift}. */
     shift<const Target extends NumericColumnNameForSchema<S>>(columns: Target | readonly Target[], n: number): PartitionedTimeSeries<DiffSchema<S, Target>, K>;
     /** Per-partition `aggregate`. See {@link TimeSeries.aggregate}. */
-    aggregate<const Mapping extends AggregateMap<S>>(sequence: SequenceLike, mapping: Mapping, options?: {
+    aggregate<const Mapping extends ValidatedAggregateMap<S, Mapping>>(sequence: SequenceLike, mapping: Mapping, options?: {
         range?: TemporalLike;
     }): PartitionedTimeSeries<AggregateSchema<S, Mapping>, K>;
-    aggregate<const Mapping extends AggregateOutputMap<S>>(sequence: SequenceLike, mapping: Mapping, options?: {
-        range?: TemporalLike;
-    }): PartitionedTimeSeries<AggregateOutputMapResultSchema<S, Mapping>, K>;
 }
 export {};
 //# sourceMappingURL=partitioned-time-series.d.ts.map

package/dist/batch/time-series.d.ts

@@ -1,5 +1,4 @@
-import type { AlignSchema, MaterializeSchema, ArrayAggregateAppendSchema, ArrayAggregateReplaceSchema, ArrayColumnNameForSchema, ArrayExplodeAppendSchema, ArrayExplodeReplaceSchema, BaselineSchema, AggregateReducer, AggregateOutputMap, AggregateMap, AggregateSchema, CollapseSchema, EventDataForSchema, EventForSchema, FirstColKind, IntervalKeyedSchema, JsonRowFormat, JoinManySchema, JoinSchema, JoinType, NumericColumnNameForSchema, NormalizedObjectRow, NormalizedRowForSchema, PivotByGroupSchema, PointRowForSchema, PrefixedJoinManySchema, PrefixedJoinSchema, ReduceResult, RenameMap } from '../schema/index.js';
-import type { AggregateOutputMapResultSchema, RollingOutputMapSchema } from '../schema/index.js';
+import type { AlignSchema, MaterializeSchema, ArrayAggregateAppendSchema, ArrayAggregateReplaceSchema, ArrayColumnNameForSchema, ArrayExplodeAppendSchema, ArrayExplodeReplaceSchema, BaselineSchema, AggregateReducer, AggregateSchema, CollapseSchema, EventDataForSchema, EventForSchema, FirstColKind, IntervalKeyedSchema, JsonRowFormat, JoinManySchema, JoinSchema, JoinType, NumericColumnNameForSchema, NormalizedObjectRow, NormalizedRowForSchema, PivotByGroupSchema, PointRowForSchema, PrefixedJoinManySchema, PrefixedJoinSchema, ReduceResult, RenameMap, ValidatedAggregateMap } from '../schema/index.js';
 import type { RenameSchema, RollingAlignment, RollingSchema, ColumnValue, DedupeKeep, DiffSchema, FillMapping, FillStrategy, ScalarKind, ScalarValue, SmoothMethod, SmoothAppendSchema, SmoothSchema, SelectSchema, SeriesSchema, TimeKeyedSchema, TimeSeriesJsonInput, TimeSeriesInput, TimeRangeKeyedSchema, ValueColumnKindForName, ValueColumnNameForSchema, ValueColumnsForSchema } from '../schema/index.js';
 import { BoundedSequence } from '../sequence/bounded-sequence.js';
 import { type TimeZoneOptions } from '../core/calendar.js';
@@ -77,6 +76,12 @@ export declare class TimeSeries<S extends SeriesSchema> {
      */
     static fromJSON<S extends SeriesSchema>(input: TimeSeriesJsonInput<S> & {
         parse?: TimeZoneOptions;
+        /**
+         * Sort rows by key before construction (off by default; see
+         * `TimeSeriesInput.sort`). Useful when reviving a wire payload whose
+         * rows aren't guaranteed sorted — avoids a manual pre-sort.
+         */
+        sort?: boolean;
     }): TimeSeries<S>;
     /**
      * Example: `TimeSeries.fromEvents(events, { schema, name })`.
@@ -497,12 +502,9 @@ export declare class TimeSeries<S extends SeriesSchema> {
      * `series.partitionBy(col).aggregate(seq, mapping).collect()` to
      * aggregate per entity. See {@link TimeSeries.partitionBy}.
      */
-    aggregate<const Mapping extends AggregateMap<S>>(sequence: SequenceLike, mapping: Mapping, options?: {
+    aggregate<const Mapping extends ValidatedAggregateMap<S, Mapping>>(sequence: SequenceLike, mapping: Mapping, options?: {
         range?: TemporalLike;
     }): TimeSeries<AggregateSchema<S, Mapping>>;
-    aggregate<const Mapping extends AggregateOutputMap<S>>(sequence: SequenceLike, mapping: Mapping, options?: {
-        range?: TemporalLike;
-    }): TimeSeries<AggregateOutputMapResultSchema<S, Mapping>>;
     /**
      * Example: `series.reduce("value", "avg")`.
      * Collapses the entire series to a single scalar value using the specified reducer.
@@ -516,8 +518,7 @@ export declare class TimeSeries<S extends SeriesSchema> {
      * a plain value or record.
      */
     reduce(column: ValueColumnsForSchema<S>[number]['name'], reducer: AggregateReducer): ColumnValue | undefined;
-    reduce<const Mapping extends AggregateMap<S>>(mapping: Mapping): ReduceResult<S, Mapping>;
-    reduce<const Mapping extends AggregateOutputMap<S>>(mapping: Mapping): ReduceResult<S, Mapping>;
+    reduce<const Mapping extends ValidatedAggregateMap<S, Mapping>>(mapping: Mapping): ReduceResult<S, Mapping>;
     /**
      * Example: `series.groupBy("host")`.
      * Partitions the series into groups keyed by the distinct values of a payload column.
@@ -900,26 +901,16 @@ export declare class TimeSeries<S extends SeriesSchema> {
      * `series.partitionBy(col).rolling(...).collect()` to scope per
      * entity. See {@link TimeSeries.partitionBy}.
      */
-    rolling<const Mapping extends AggregateMap<S>>(window: DurationInput, mapping: Mapping, options?: {
+    rolling<const Mapping extends ValidatedAggregateMap<S, Mapping>>(window: DurationInput, mapping: Mapping, options?: {
         alignment?: RollingAlignment;
         minSamples?: number;
     }): TimeSeries<RollingSchema<S, Mapping>>;
-    rolling<const Mapping extends AggregateOutputMap<S>>(window: DurationInput, mapping: Mapping, options?: {
-        alignment?: RollingAlignment;
-        minSamples?: number;
-    }): TimeSeries<RollingOutputMapSchema<S, Mapping>>;
-    rolling<const Mapping extends AggregateMap<S>>(sequence: SequenceLike, window: DurationInput, mapping: Mapping, options?: {
+    rolling<const Mapping extends ValidatedAggregateMap<S, Mapping>>(sequence: SequenceLike, window: DurationInput, mapping: Mapping, options?: {
         alignment?: RollingAlignment;
         sample?: AlignSample;
         range?: TemporalLike;
         minSamples?: number;
     }): TimeSeries<AggregateSchema<S, Mapping>>;
-    rolling<const Mapping extends AggregateOutputMap<S>>(sequence: SequenceLike, window: DurationInput, mapping: Mapping, options?: {
-        alignment?: RollingAlignment;
-        sample?: AlignSample;
-        range?: TemporalLike;
-        minSamples?: number;
-    }): TimeSeries<AggregateOutputMapResultSchema<S, Mapping>>;
     /**
      * Example: `series.smooth("value", "ema", { alpha: 0.2 })`.
      * Applies a smoothing transform to one numeric payload column while preserving the original key

package/dist/batch/time-series.js

@@ -468,6 +468,7 @@ export class TimeSeries {
             name: input.name,
             schema: input.schema,
             rows: parseJsonRows(input.schema, input.rows, input.parse),
+            sort: input.sort ?? false,
         });
     }
     /**
@@ -587,13 +588,21 @@ export class TimeSeries {
         }
         else {
             this.schema = Object.freeze(input.schema.slice());
+            // `{ sort: true }` sorts unsorted input by key before intake (otherwise
+            // the intake's non-decreasing-order check throws). Stable, so rows with
+            // equal keys keep their input order; same key comparator as
+            // `fromEvents` / `concat`. Copies the array — the caller's `rows` is not
+            // mutated.
+            const rows = input.sort
+                ? [...input.rows].sort((a, b) => compareEventKeys(toKey(a[0]), toKey(b[0])))
+                : input.rows;
             // `SeriesStore.fromValidatedRows` runs the column-native
             // intake (`validateAndNormalizeColumnar`) — same validation
             // rules as the pre-2a row-shape `validateAndNormalize` but
             // writes directly into columnar buffers without allocating
             // Event objects + frozen data dicts. Events lazy-materialize
             // on first `eventAt(i)` access via the store's per-row cache.
-            this.#store = SeriesStore.fromValidatedRows(this.schema, input.rows);
+            this.#store = SeriesStore.fromValidatedRows(this.schema, rows);
         }
         Object.freeze(this);
     }
@@ -782,14 +791,18 @@ export class TimeSeries {
      * series.events[i]` holds whenever both are accessed.
      */
     at(index) {
-        // Match pre-2a array-indexing semantics: non-integer or NaN
-        // inputs return undefined rather than throwing downstream from
-        // `#store.eventAt`. `this.events[NaN]` returned undefined per
-        // JS array semantics (key coercion + miss); the direct route
-        // to `#store.eventAt(NaN)` would proceed past the bounds check
-        // and attempt key materialization at the invalid row. Closed
-        // Codex round 4's medium finding on PR #150.
-        if (!Number.isInteger(index) || index < 0 || index >= this.#store.length) {
+        // Non-integer / NaN inputs return undefined rather than throwing
+        // downstream from `#store.eventAt` (`this.events[NaN]` returned undefined
+        // per JS array semantics; the direct route to `#store.eventAt(NaN)` would
+        // proceed past the bounds check and materialize a key at an invalid row).
+        // Closed Codex round 4's medium finding on PR #150.
+        if (!Number.isInteger(index))
+            return undefined;
+        // Negative indices count from the end — parity with `LiveSeries.at` and
+        // `Array.prototype.at` (`at(-1)` is the last event).
+        if (index < 0)
+            index += this.#store.length;
+        if (index < 0 || index >= this.#store.length) {
             return undefined;
         }
         return this.#store.eventAt(index);
@@ -1292,7 +1305,8 @@ export class TimeSeries {
     }
     pivotByGroup(groupCol, valueCol, options = {}) {
         if (this.schema[0].kind !== 'time') {
-            throw new TypeError(`pivotByGroup requires a time-keyed series; got ${this.schema[0].kind}`);
+            throw new TypeError(`pivotByGroup requires a time-keyed series; got ${this.schema[0].kind}` +
+                ` — piping from aggregate/materialize? call .asTime({ at: 'begin' }) first`);
         }
         const valueColumnDef = this.schema.find((c) => c.name === valueCol);
         if (!valueColumnDef) {
@@ -2826,6 +2840,12 @@ export class TimeSeries {
             rollingOptions.alignment = alignment;
         if (minSamples !== undefined)
             rollingOptions.minSamples = minSamples;
+        // Trust boundary: a generic mapping can't prove it satisfies the
+        // public overload's ValidatedAggregateMap constraint (S is
+        // unresolved here), so route through the broad-schema escape hatch
+        // — for concrete SeriesSchema the constraint degrades to the
+        // permissive AggregateMap by design. The computed spec keys are
+        // collision-checked above.
         const rolling = this.rolling(window, {
             [avgName]: { from: col, using: 'avg' },
             [sdName]: { from: col, using: 'stdev' },
@@ -2920,6 +2940,8 @@ export class TimeSeries {
             rollingOptions.alignment = alignment;
         if (minSamples !== undefined)
             rollingOptions.minSamples = minSamples;
+        // Trust boundary: see baseline() above — generic mapping routed
+        // through the broad-schema escape hatch of ValidatedAggregateMap.
         const rolling = this.rolling(window, rollingMapping, rollingOptions);
         const kept = [];
         for (let i = 0; i < this.events.length; i += 1) {

package/dist/batch/validate.js

@@ -376,11 +376,11 @@ export function validateAndNormalizeColumnar(input) {
         const prevBegin = beginBuf[i - 1];
         const curBegin = beginBuf[i];
         if (prevBegin > curBegin) {
-            throw new ValidationError(`row ${i} is out of order`);
+            throw new ValidationError(`row ${i} is out of order — keys must be non-decreasing; pass { sort: true } to sort rows on construction, or pre-sort them`);
         }
         if (prevBegin === curBegin && endBuf !== beginBuf) {
             if (endBuf[i - 1] > endBuf[i]) {
-                throw new ValidationError(`row ${i} is out of order`);
+                throw new ValidationError(`row ${i} is out of order — keys must be non-decreasing; pass { sort: true } to sort rows on construction, or pre-sort them`);
             }
         }
     }

package/dist/cjs-fallback.cjs

@@ -0,0 +1,15 @@
+'use strict';
+
+// pond-ts ships as ES modules only. This stub is the `require` target in the
+// package's `exports` map so that CommonJS consumers get a clear, actionable
+// error instead of Node's cryptic `ERR_PACKAGE_PATH_NOT_EXPORTED`.
+//
+// It is copied verbatim into `dist/` during `prepack` (see package.json) so it
+// rides along in the published tarball; the source of truth lives at the
+// package root and is never touched by `tsc`.
+
+throw new Error(
+  'pond-ts is an ES module package and cannot be loaded with require(). ' +
+    "Use `import { TimeSeries } from 'pond-ts'` instead, or a dynamic " +
+    "`await import('pond-ts')` from CommonJS. See https://nodejs.org/api/esm.html.",
+);

package/dist/index.d.ts

@@ -29,7 +29,7 @@ export { ArrayColumn } from './columnar/array-column.js';
 export { ChunkedArrayColumn, ChunkedBooleanColumn, ChunkedFloat64Column, ChunkedStringColumn, } from './columnar/chunked-column.js';
 export { type IntervalLabelKind, type KeyColumn, IntervalKeyColumn, TimeKeyColumn, TimeRangeKeyColumn, } from './columnar/key-column.js';
 export { type ValidityBitmap } from './columnar/validity.js';
-export type { AlignSchema, ArrayColumnNameForSchema, BaselineSchema, AggregateFunction, AggregateReducer, AggregateOutputMap, AggregateOutputSpec, AggregateMap, AggregateSchema, ColumnDef, CollapseData, ArrayAggregateAppendSchema, ArrayAggregateKind, ArrayAggregateReplaceSchema, ArrayExplodeAppendSchema, ArrayExplodeReplaceSchema, CollapseSchema, DedupeKeep, EventDataForSchema, EventForSchema, EventKeyForKind, FillMapping, FillStrategy, MaterializeSchema, EventKeyForSchema, FirstColKind, FirstColumn, IntervalKeyedSchema, JsonIntervalInput, JsonObjectRowForSchema, JsonRowFormat, JsonRowForSchema, JsonTimeRangeInput, JsonTimestampInput, JsonValueForKind, RollingAlignment, RollingSchema, JoinConflictMode, JoinManySchema, PrefixedJoinManySchema, PrefixedJoinSchema, LiveSource, JoinType, JoinSchema, NormalizedRowForSchema, NormalizedObjectRowForSchema, NormalizedObjectRow, NormalizedValueForKind, ReduceResult, RenameData, RenameMap, RenameSchema, RekeySchema, RowForSchema, ArrayValue, ColumnValue, ScalarKind, ScalarValue, CustomAggregateReducer, DiffSchema, NumericColumnNameForSchema, SmoothMethod, SmoothAppendSchema, SmoothSchema, SelectData, SelectSchema, SeriesSchema, TimeKeyedSchema, TimeSeriesInput, TimeSeriesJsonInput, TimeRangeKeyedSchema, ValueColumnsForSchema, ValueColumn, ValueForKind, } from './schema/index.js';
+export type { AlignSchema, ArrayColumnNameForSchema, BaselineSchema, AggregateFunction, AggregateReducer, AggregateOutputMap, AggregateOutputSpec, AggregateMap, AggregateSchema, ValidatedAggregateMap, ColumnDef, CollapseData, ArrayAggregateAppendSchema, ArrayAggregateKind, ArrayAggregateReplaceSchema, ArrayExplodeAppendSchema, ArrayExplodeReplaceSchema, CollapseSchema, DedupeKeep, EventDataForSchema, EventForSchema, EventKeyForKind, FillMapping, FillStrategy, MaterializeSchema, EventKeyForSchema, FirstColKind, FirstColumn, IntervalKeyedSchema, JsonIntervalInput, JsonObjectRowForSchema, JsonRowFormat, JsonRowForSchema, JsonTimeRangeInput, JsonTimestampInput, JsonValueForKind, RollingAlignment, RollingSchema, JoinConflictMode, JoinManySchema, PrefixedJoinManySchema, PrefixedJoinSchema, LiveSource, JoinType, JoinSchema, NormalizedRowForSchema, NormalizedObjectRowForSchema, NormalizedObjectRow, NormalizedValueForKind, ReduceResult, RenameData, RenameMap, RenameSchema, RekeySchema, RowForSchema, ArrayValue, ColumnValue, ScalarKind, ScalarValue, CustomAggregateReducer, DiffSchema, NumericColumnNameForSchema, SmoothMethod, SmoothAppendSchema, SmoothSchema, SelectData, SelectSchema, SeriesSchema, TimeKeyedSchema, TimeSeriesInput, TimeSeriesJsonInput, TimeRangeKeyedSchema, ValueColumnsForSchema, ValueColumn, ValueForKind, } from './schema/index.js';
 export type { CalendarOptions, CalendarUnit, TimeZoneOptions, } from './core/calendar.js';
 export type { EventKey, IntervalInput, IntervalValue, TemporalLike, TimeRangeInput, TimestampInput, } from './core/temporal.js';
 export type { DurationInput } from './core/duration.js';

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

@@ -4,7 +4,7 @@ import { LiveView, type LiveFillMapping, type LiveFillStrategy } from './live-vi
 import { LiveRollingAggregation, type LiveRollingOptions, type RollingWindow } from './live-rolling-aggregation.js';
 import { TimeSeries } from '../batch/time-series.js';
 import type { Sequence } from '../sequence/sequence.js';
-import type { AggregateMap, AggregateOutputMap, DiffSchema, EventDataForSchema, EventForSchema, LiveSource, NumericColumnNameForSchema, ColumnValue, RollingSchema, SelectSchema, SeriesSchema } from '../schema/index.js';
+import type { AggregateMap, AggregateOutputMap, DiffSchema, EventDataForSchema, EventForSchema, LiveSource, NumericColumnNameForSchema, ColumnValue, RollingSchema, SelectSchema, SeriesSchema, ValidatedAggregateMap } from '../schema/index.js';
 import type { RollingOutputMapSchema } from '../schema/index.js';
 import type { DurationInput } from '../core/duration.js';
 type ClosedEvent = Event<Interval, Record<string, ColumnValue | undefined>>;
@@ -48,7 +48,7 @@ export declare class LiveAggregation<S extends SeriesSchema, Out extends SeriesS
     cumulative<const Targets extends NumericColumnNameForSchema<Out>>(spec: {
         [K in Targets]: 'sum' | 'max' | 'min' | 'count' | ((acc: number, value: number) => number);
     }): LiveView<DiffSchema<Out, Targets>>;
-    rolling<const M extends AggregateMap<Out>>(windowSize: RollingWindow, mapping: M, options?: LiveRollingOptions): LiveRollingAggregation<Out, RollingSchema<Out, M>>;
+    rolling<const M extends ValidatedAggregateMap<Out, M>>(windowSize: RollingWindow, mapping: M, options?: LiveRollingOptions): LiveRollingAggregation<Out, RollingSchema<Out, M>>;
     rolling<const M extends AggregateOutputMap<Out>>(windowSize: RollingWindow, mapping: M, options?: LiveRollingOptions): LiveRollingAggregation<Out, RollingOutputMapSchema<Out, M>>;
     /**
      * Pipeline stats snapshot — cumulative counters since

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

@@ -4,9 +4,8 @@ import { LivePartitionedFusedRolling } from './live-partitioned-fused-rolling.js
 import type { SampleStrategy } from '../sequence/sample.js';
 import { type LiveFillMapping, type LiveFillStrategy } from './live-view.js';
 import type { Trigger } from './triggers.js';
-import { type AggregateMap, type AggregateOutputMap, type DiffSchema, type EventDataForSchema, type LiveSource, type NumericColumnNameForSchema, type RollingSchema, type SeriesSchema } from '../schema/index.js';
-import type { RollingOutputMapSchema } from '../schema/index.js';
-import type { FusedMapping, FusedMappingValid, FusedPartitionedRollingSchema } from '../schema/index.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 { LiveRollingOptions, RollingWindow } from './live-rolling-aggregation.js';
 /**
@@ -252,28 +251,17 @@ export declare class LivePartitionedSeries<S extends SeriesSchema, K extends str
      * );
      * ```
      */
-    rolling<const M extends AggregateMap<S>>(window: RollingWindow, mapping: M, options?: LiveRollingOptions & {
+    rolling<const M extends ValidatedAggregateMap<S, M>>(window: RollingWindow, mapping: M, options?: LiveRollingOptions & {
         trigger?: {
             kind: 'event' | 'count';
         };
     }): LivePartitionedView<S, RollingSchema<S, M>, K, ByCol>;
-    rolling<const M extends AggregateOutputMap<S>>(window: RollingWindow, mapping: M, options?: LiveRollingOptions & {
-        trigger?: {
-            kind: 'event' | 'count';
-        };
-    }): LivePartitionedView<S, RollingOutputMapSchema<S, M>, K, ByCol>;
-    rolling<const M extends AggregateMap<S>>(window: RollingWindow, mapping: M, options: LiveRollingOptions & {
-        trigger: {
-            kind: 'clock';
-        } & Trigger;
-    }): LivePartitionedSyncRolling<S, K, SeriesSchema>;
-    rolling<const M extends AggregateOutputMap<S>>(window: RollingWindow, mapping: M, options: LiveRollingOptions & {
+    rolling<const M extends ValidatedAggregateMap<S, M>>(window: RollingWindow, mapping: M, options: LiveRollingOptions & {
         trigger: {
             kind: 'clock';
         } & Trigger;
     }): LivePartitionedSyncRolling<S, K, SeriesSchema>;
-    rolling<const M extends AggregateMap<S>>(window: RollingWindow, mapping: M, options: LiveRollingOptions): LivePartitionedView<S, RollingSchema<S, M>, K, ByCol> | LivePartitionedSyncRolling<S, K, SeriesSchema>;
-    rolling<const M extends AggregateOutputMap<S>>(window: RollingWindow, mapping: M, options: LiveRollingOptions): LivePartitionedView<S, RollingOutputMapSchema<S, M>, K, ByCol> | LivePartitionedSyncRolling<S, K, SeriesSchema>;
+    rolling<const M extends ValidatedAggregateMap<S, M>>(window: RollingWindow, mapping: M, options: LiveRollingOptions): LivePartitionedView<S, RollingSchema<S, M>, K, ByCol> | LivePartitionedSyncRolling<S, K, SeriesSchema>;
     /**
      * Keyed-form fused multi-window partitioned rolling. Maintains N
      * windows per partition in a single ingest pass over a single
@@ -437,28 +425,17 @@ export declare class LivePartitionedView<SBase extends SeriesSchema, R extends S
      * partition column with a passthrough reducer (e.g.
      * `host: 'last'`) to keep it visible in the unified output.
      */
-    rolling<const M extends AggregateMap<R>>(window: RollingWindow, mapping: M, options?: LiveRollingOptions & {
+    rolling<const M extends ValidatedAggregateMap<R, M>>(window: RollingWindow, mapping: M, options?: LiveRollingOptions & {
         trigger?: {
             kind: 'event' | 'count';
         };
     }): LivePartitionedView<SBase, RollingSchema<R, M>, K, ByCol>;
-    rolling<const M extends AggregateOutputMap<R>>(window: RollingWindow, mapping: M, options?: LiveRollingOptions & {
-        trigger?: {
-            kind: 'event' | 'count';
-        };
-    }): LivePartitionedView<SBase, RollingOutputMapSchema<R, M>, K, ByCol>;
-    rolling<const M extends AggregateMap<R>>(window: RollingWindow, mapping: M, options: LiveRollingOptions & {
-        trigger: {
-            kind: 'clock';
-        } & Trigger;
-    }): LivePartitionedSyncRolling<R, K, SeriesSchema>;
-    rolling<const M extends AggregateOutputMap<R>>(window: RollingWindow, mapping: M, options: LiveRollingOptions & {
+    rolling<const M extends ValidatedAggregateMap<R, M>>(window: RollingWindow, mapping: M, options: LiveRollingOptions & {
         trigger: {
             kind: 'clock';
         } & Trigger;
     }): LivePartitionedSyncRolling<R, K, SeriesSchema>;
-    rolling<const M extends AggregateMap<R>>(window: RollingWindow, mapping: M, options: LiveRollingOptions): LivePartitionedView<SBase, RollingSchema<R, M>, K, ByCol> | LivePartitionedSyncRolling<R, K, SeriesSchema>;
-    rolling<const M extends AggregateOutputMap<R>>(window: RollingWindow, mapping: M, options: LiveRollingOptions): LivePartitionedView<SBase, RollingOutputMapSchema<R, M>, K, ByCol> | LivePartitionedSyncRolling<R, K, SeriesSchema>;
+    rolling<const M extends ValidatedAggregateMap<R, M>>(window: RollingWindow, mapping: M, options: LiveRollingOptions): LivePartitionedView<SBase, RollingSchema<R, M>, K, ByCol> | LivePartitionedSyncRolling<R, K, SeriesSchema>;
     /**
      * Keyed-form fused multi-window rolling on a chained
      * `LivePartitionedView`. Same shape as the root variant — each

package/dist/live/live-rolling-aggregation.d.ts

@@ -2,7 +2,7 @@ import { LiveAggregation } from './live-aggregation.js';
 import { LiveView, type LiveFillMapping, type LiveFillStrategy } from './live-view.js';
 import type { Sequence } from '../sequence/sequence.js';
 import { type Trigger } from './triggers.js';
-import type { AggregateMap, AggregateOutputMap, AggregateSchema, DiffSchema, EventDataForSchema, EventForSchema, LiveSource, NumericColumnNameForSchema, SelectSchema, SeriesSchema, ColumnValue } from '../schema/index.js';
+import type { AggregateMap, AggregateOutputMap, AggregateSchema, DiffSchema, EventDataForSchema, EventForSchema, LiveSource, NumericColumnNameForSchema, SelectSchema, SeriesSchema, ColumnValue, ValidatedAggregateMap } from '../schema/index.js';
 import type { AggregateOutputMapResultSchema } from '../schema/index.js';
 import type { DurationInput } from '../core/duration.js';
 import type { RetentionPolicy } from './live-series.js';
@@ -107,7 +107,7 @@ export declare class LiveRollingAggregation<S extends SeriesSchema, Out extends
     cumulative<const Targets extends NumericColumnNameForSchema<Out>>(spec: {
         [K in Targets]: 'sum' | 'max' | 'min' | 'count' | ((acc: number, value: number) => number);
     }): LiveView<DiffSchema<Out, Targets>>;
-    aggregate<const M extends AggregateMap<Out>>(sequence: Sequence, mapping: M): LiveAggregation<Out, AggregateSchema<Out, M>>;
+    aggregate<const M extends ValidatedAggregateMap<Out, M>>(sequence: Sequence, mapping: M): LiveAggregation<Out, AggregateSchema<Out, M>>;
     aggregate<const M extends AggregateOutputMap<Out>>(sequence: Sequence, mapping: M): LiveAggregation<Out, AggregateOutputMapResultSchema<Out, M>>;
     /**
      * Pipeline stats snapshot — cumulative counters since

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

@@ -5,12 +5,11 @@ import { LiveRollingAggregation, type LiveRollingOptions, type RollingWindow } f
 import { TimeSeries, type KeyLike } from '../batch/time-series.js';
 import type { TimeZoneOptions } from '../core/calendar.js';
 import type { Sequence } from '../sequence/sequence.js';
-import { EMITS_EVICT, type AggregateMap, type AggregateOutputMap, type AggregateSchema, type DiffSchema, type EventDataForSchema, type EventForSchema, type JsonObjectRowForSchema, type JsonRowForSchema, type NormalizedObjectRow, type NormalizedRowForSchema, type NumericColumnNameForSchema, type RollingSchema, type RowForSchema, type SelectSchema, type SeriesSchema, type TimeSeriesJsonInput, type TimeSeriesJsonOutputArray, type TimeSeriesJsonOutputObject } from '../schema/index.js';
-import type { AggregateOutputMapResultSchema, RollingOutputMapSchema } from '../schema/index.js';
+import { type AggregateSchema, type DiffSchema, type EventDataForSchema, type EventForSchema, type JsonObjectRowForSchema, type JsonRowForSchema, type NormalizedObjectRow, type NormalizedRowForSchema, type NumericColumnNameForSchema, type RollingSchema, type RowForSchema, type SelectSchema, type SeriesSchema, type TimeSeriesJsonInput, type TimeSeriesJsonOutputArray, type TimeSeriesJsonOutputObject } from '../schema/index.js';
 import { LiveFusedRolling } from './live-fused-rolling.js';
 import { LiveReduce } from './live-reduce.js';
 import type { SampleStrategy } from '../sequence/sample.js';
-import type { FusedMapping, FusedMappingValid, FusedRollingSchema } from '../schema/index.js';
+import type { FusedMapping, FusedMappingValid, FusedRollingSchema, ValidatedAggregateMap } from '../schema/index.js';
 import type { DurationInput } from '../core/duration.js';
 export type OrderingMode = 'strict' | 'drop' | 'reorder';
 export type RetentionPolicy = {
@@ -44,7 +43,6 @@ type BatchListener<S extends SeriesSchema> = (events: ReadonlyArray<EventForSche
 type EvictListener<S extends SeriesSchema> = (events: ReadonlyArray<EventForSchema<S>>) => void;
 export declare class LiveSeries<S extends SeriesSchema> {
     #private;
-    readonly [EMITS_EVICT]: true;
     readonly name: string;
     readonly schema: S;
     constructor(options: LiveSeriesOptions<S>);
@@ -239,10 +237,8 @@ export declare class LiveSeries<S extends SeriesSchema> {
     sample(strategy: SampleStrategy): LiveView<S>;
     select<const Keys extends readonly (keyof EventDataForSchema<S>)[]>(...keys: Keys): LiveView<SelectSchema<S, Keys[number] & string>>;
     window(size: RollingWindow): LiveView<S>;
-    aggregate<const M extends AggregateMap<S>>(sequence: Sequence, mapping: M): LiveAggregation<S, AggregateSchema<S, M>>;
-    aggregate<const M extends AggregateOutputMap<S>>(sequence: Sequence, mapping: M): LiveAggregation<S, AggregateOutputMapResultSchema<S, M>>;
-    rolling<const M extends AggregateMap<S>>(window: RollingWindow, mapping: M, options?: LiveRollingOptions): LiveRollingAggregation<S, RollingSchema<S, M>>;
-    rolling<const M extends AggregateOutputMap<S>>(window: RollingWindow, mapping: M, options?: LiveRollingOptions): LiveRollingAggregation<S, RollingOutputMapSchema<S, M>>;
+    aggregate<const M extends ValidatedAggregateMap<S, M>>(sequence: Sequence, mapping: M): LiveAggregation<S, AggregateSchema<S, M>>;
+    rolling<const M extends ValidatedAggregateMap<S, M>>(window: RollingWindow, mapping: M, options?: LiveRollingOptions): LiveRollingAggregation<S, RollingSchema<S, M>>;
     /**
      * Keyed-form fused multi-window rolling. Maintains N windows in
      * one ingest pass over a single shared deque; emits one merged
@@ -278,8 +274,7 @@ export declare class LiveSeries<S extends SeriesSchema> {
      * `[time, ...mappingColumns]`. Composes with the rest of the
      * live operator surface.
      */
-    reduce<const M extends AggregateMap<S>>(mapping: M, options?: LiveRollingOptions): LiveReduce<S, RollingSchema<S, M>>;
-    reduce<const M extends AggregateOutputMap<S>>(mapping: M, options?: LiveRollingOptions): LiveReduce<S, RollingOutputMapSchema<S, M>>;
+    reduce<const M extends ValidatedAggregateMap<S, M>>(mapping: M, options?: LiveRollingOptions): LiveReduce<S, RollingSchema<S, M>>;
     /**
      * Time span of the current buffer — `last.begin() - first.begin()`
      * in milliseconds. Returns `0` if the buffer is empty or holds a

package/dist/live/live-series.js

@@ -87,6 +87,7 @@ function assertCellKind(kind, value, name) {
 }
 // ── LiveSeries ──────────────────────────────────────────────────
 export class LiveSeries {
+    /** @internal */
     [EMITS_EVICT] = true;
     name;
     schema;
@@ -373,7 +374,7 @@ export class LiveSeries {
             rows,
         });
         // INTRA-batch order is enforced by `validateAndNormalizeColumnar`
-        // above (it throws `ValidationError("row N is out of order")`). The
+        // above (it throws a `ValidationError` naming the out-of-order row). The
         // cross-batch boundary check + commit/fan-out live in `#commitChunk`.
         const store = ColumnarStore.fromTrustedStore(this.schema, keys, columns);
         this.#commitChunk(store);

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

@@ -7,9 +7,8 @@ import { TimeSeries, type KeyLike } from '../batch/time-series.js';
 import type { Sequence } from '../sequence/sequence.js';
 import { TimeKeyColumn } from '../columnar/key-column.js';
 import type { PublicColumnForKind, KeyColumnForSchema } from '../column.js';
-import { EMITS_EVICT, type AggregateMap, type AggregateOutputMap, type AggregateSchema, type DiffSchema, type EventDataForSchema, type EventForSchema, type LiveSource, type NumericColumnNameForSchema, type ValueColumnNameForSchema, type RollingSchema, type ScalarValue, type SelectSchema, type SeriesSchema, type ValueColumnsForSchema } from '../schema/index.js';
-import type { AggregateOutputMapResultSchema, RollingOutputMapSchema } from '../schema/index.js';
-import type { FusedMapping, FusedMappingValid, FusedRollingSchema } from '../schema/index.js';
+import { type AggregateSchema, type DiffSchema, type EventDataForSchema, type EventForSchema, type LiveSource, type NumericColumnNameForSchema, type ValueColumnNameForSchema, type RollingSchema, type ScalarValue, type SelectSchema, type SeriesSchema, type ValueColumnsForSchema } from '../schema/index.js';
+import type { FusedMapping, FusedMappingValid, FusedRollingSchema, ValidatedAggregateMap } from '../schema/index.js';
 export type LiveFillStrategy = 'hold' | 'zero';
 export type LiveFillMapping<S extends SeriesSchema> = {
     [K in ValueColumnsForSchema<S>[number]['name']]?: LiveFillStrategy | ScalarValue;
@@ -40,7 +39,6 @@ type ViewOptions<S extends SeriesSchema> = {
 type TimeKeyOnly<S extends SeriesSchema> = KeyColumnForSchema<S> extends TimeKeyColumn ? KeyColumnForSchema<S> : 'LiveView.keyColumn() supports time-keyed views only — use toTimeSeries() for other key kinds';
 export declare class LiveView<S extends SeriesSchema> implements LiveSource<S> {
     #private;
-    readonly [EMITS_EVICT]: true;
     readonly name: string;
     readonly schema: S;
     constructor(source: LiveSource<any>, process: (event: any) => EventForSchema<S> | undefined, options?: ViewOptions<S>);
@@ -122,10 +120,8 @@ export declare class LiveView<S extends SeriesSchema> implements LiveSource<S> {
      * is per-event derivative of the named columns.
      */
     eventRate(): number;
-    aggregate<const M extends AggregateMap<S>>(sequence: Sequence, mapping: M): LiveAggregation<S, AggregateSchema<S, M>>;
-    aggregate<const M extends AggregateOutputMap<S>>(sequence: Sequence, mapping: M): LiveAggregation<S, AggregateOutputMapResultSchema<S, M>>;
-    rolling<const M extends AggregateMap<S>>(window: RollingWindow, mapping: M, options?: LiveRollingOptions): LiveRollingAggregation<S, RollingSchema<S, M>>;
-    rolling<const M extends AggregateOutputMap<S>>(window: RollingWindow, mapping: M, options?: LiveRollingOptions): LiveRollingAggregation<S, RollingOutputMapSchema<S, M>>;
+    aggregate<const M extends ValidatedAggregateMap<S, M>>(sequence: Sequence, mapping: M): LiveAggregation<S, AggregateSchema<S, M>>;
+    rolling<const M extends ValidatedAggregateMap<S, M>>(window: RollingWindow, mapping: M, options?: LiveRollingOptions): LiveRollingAggregation<S, RollingSchema<S, M>>;
     /**
      * Keyed-form fused multi-window rolling on a `LiveView`. See
      * {@link LiveSeries.rolling} for the full surface — chained-from-
@@ -137,8 +133,7 @@ export declare class LiveView<S extends SeriesSchema> implements LiveSource<S> {
      * Streaming reduce over the view's current buffer. See
      * {@link LiveSeries.reduce} for the full surface.
      */
-    reduce<const M extends AggregateMap<S>>(mapping: M, options?: LiveRollingOptions): LiveReduce<S, RollingSchema<S, M>>;
-    reduce<const M extends AggregateOutputMap<S>>(mapping: M, options?: LiveRollingOptions): LiveReduce<S, RollingOutputMapSchema<S, M>>;
+    reduce<const M extends ValidatedAggregateMap<S, M>>(mapping: M, options?: LiveRollingOptions): LiveReduce<S, RollingSchema<S, M>>;
     diff<const Target extends NumericColumnNameForSchema<S>>(columns: Target | readonly Target[], options?: {
         drop?: boolean;
     }): LiveView<DiffSchema<S, Target>>;

package/dist/live/live-view.js

@@ -11,6 +11,7 @@ import { TimeKeyColumn } from '../columnar/key-column.js';
 import { EMITS_EVICT, } from '../schema/index.js';
 import { parseDuration } from '../core/duration.js';
 export class LiveView {
+    /** @internal */
     [EMITS_EVICT] = true;
     name;
     schema;