pond-ts 0.22.0 → 0.24.0

package/CHANGELOG.md

@@ -7,7 +7,9 @@ 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.24.0...HEAD
+[0.24.0]: https://github.com/pjm17971/pond-ts/compare/v0.23.0...v0.24.0
+[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 +18,128 @@ type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.24.0] — 2026-06-14
+
+### Changed
+
+- **`TimeSeries.timeRange()` is now a columnar key-axis read instead of a
+  reduce over materialized events.** Behavior is unchanged, but the old
+  implementation materialized every `Event` on its first call — and because
+  `aggregate()` defaults its `range` to `series.timeRange()`, a one-shot
+  `aggregate()` paid full event materialization before the columnar fast
+  path could run, erasing the win. The new path reads the key column's
+  begin/end axis directly: O(1) for time-keyed series, a typed-array scan
+  for range/interval-keyed series, with no event materialization. Measured
+  on 1M rows: `timeRange()` itself ~407 ms → ~0.002 ms (time-keyed); cold
+  `aggregate()` with a defaulted range ~387 ms → ~6 ms (~63×). Every
+  `timeRange()` / `overlaps` / `contains` / `intersection` caller benefits.
+  (Audit v2 §3.3.)
+- **`aggregate()` now takes the columnar fast path when a mapping mixes
+  numeric reducers with `first` / `last`.** Previously a single `first` or
+  `last` column (they have no numeric `reduceColumn`) bailed the entire call
+  to the row path. They now qualify via a boundary scan — the first/last
+  _defined_ cell, on any column kind. Behavior is unchanged. The big
+  beneficiary is **partitioned `aggregate`**, which auto-injects a `'first'`
+  reducer for the partition column and so was excluded from the fast path on
+  every call (audit v2 §3.2/§3.3). Measured on 1M rows, flat
+  `{ cpu: 'avg', host: 'first' }`: ~37.7 ms → ~4.8 ms (~7.8×); the
+  pure-numeric path is unchanged. (The remaining `partitionBy` materialization
+  cost is addressed separately by the columnar `partitionBy` split.)
+- **`partitionBy(...)` now splits the columnar store directly instead of
+  materializing events.** `collect()` / the per-partition sugar methods
+  (`fill` / `diff` / `rolling` / …) and `toMap()` previously walked
+  `this.events` to bucket rows, then rebuilt each partition via `fromEvents`
+  (re-validating + re-packing) — silently re-paying the event-materialization
+  tax the columnar wave removed, and making `partitionBy(host).fill().collect()`
+  the #1 batch hotspot. They now group row indices off the store and gather
+  each partition via a zero-materialization columnar selection. Behavior is
+  unchanged (partition order, the `' undefined'` missing-key bucket, composite
+  keys, and declared `groups` all preserved). Measured on 100k rows / 64
+  partitions: `toMap()` ~389 → ~25 ns/row (~15×, no event materialization at
+  all); `diff().collect()` ~2×; `fill(hold).collect()` ~1.7× (the residual is
+  `TimeSeries.concat` still materializing to re-sort — a separate follow-up).
+  Declared-`groups` membership is validated by the same columnar scan, so that
+  path is materialization-free too (~331 → ~33 ns/row). **Behavior note:**
+  per-partition sub-series from `toMap()` / `apply()` now lazily materialize
+  their own `Event` objects rather than reusing the source's instances — cell
+  values are identical; only object identity differs (`collect()`, which
+  returns the source unchanged, is unaffected). (Audit v2 §3.2.)
+
+## [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/README.md

@@ -152,20 +152,24 @@ const points = series.sample({ reservoir: { size: 500 } }).toRows();
 
 ## Performance
 
-pond-ts is **7.6x faster** than pondjs on average across all comparable
-operations, with no regressions. The advantage grows with data size.
-
-| Category          | Speedup (N=16k) | Notes                                         |
-| ----------------- | --------------- | --------------------------------------------- |
-| **Aggregation**   | 25–32x          | O(N+B) bucketing vs O(N×B) Pipeline           |
-| **Alignment**     | 32x             | Forward cursor vs repeated binary search      |
-| **Rate/diff**     | 18x             | Direct array walk vs Pipeline materialization |
-| **Fill**          | 10–11x          | Single-pass vs Pipeline per strategy          |
-| **Transforms**    | 3–16x           | Pre-validated constructor skips re-validation |
-| **Construction**  | 7x              | Plain objects vs ImmutableJS wrapping         |
-| **Statistics**    | 7–9x            | Direct computation vs ImmutableJS iteration   |
-| **Serialization** | 4x              | Simpler internal representation               |
-| **Event access**  | 23x             | Array indexing vs ImmutableJS `get()`         |
+pond-ts is faster on **every** comparable operation, with no regressions —
+a **~17x** geometric-mean speedup across the measurable ops, plus a handful
+of transforms (`select` / `rename`) that are **effectively instant** (O(1)
+column rebinds, below the timer's resolution). The advantage grows with data
+size.
+
+| Category          | Speedup (N=16k)                                      | Notes                                         |
+| ----------------- | ---------------------------------------------------- | --------------------------------------------- |
+| **Rate**          | ~120x                                                | Single columnar walk vs Pipeline              |
+| **Fill**          | 77–87x                                               | Single columnar pass vs Pipeline per strategy |
+| **Aggregation**   | 57–82x                                               | O(N+B) bucketing vs O(N×B) Pipeline           |
+| **Statistics**    | 18–80x                                               | Typed-array reduce vs ImmutableJS iteration   |
+| **Alignment**     | 42x                                                  | Forward cursor vs repeated binary search      |
+| **Construction**  | 13x                                                  | Columnar intake vs ImmutableJS wrapping       |
+| **Chained**       | 8x                                                   | Derived constructors vs per-step Pipeline     |
+| **Transforms**    | `select`/`rename` instant; `collapse` 30x; `map` ~4x | Column reshapes vs Pipeline                   |
+| **Event access**  | 6x                                                   | Array indexing vs ImmutableJS `get()`         |
+| **Serialization** | 4x                                                   | Lightweight columnar representation           |
 
 See the [full benchmark results](website/docs/reference/benchmarks.mdx)
 for detailed numbers. Run locally:

package/dist/batch/aggregate-columns.d.ts

@@ -34,30 +34,6 @@ export type AggregateColumnSpec = {
  * same `mapping` shape produces the same schema.
  */
 export declare function normalizeAggregateColumns<S extends SeriesSchema>(schema: S, mapping: AggregateMap<S> | AggregateOutputMap<S>): AggregateColumnSpec[];
-/**
- * **Phase 4.7 step 3B — columnar fast path for time-keyed `aggregate()`.**
- * On sorted time-keyed data each bucket is a contiguous index range, so
- * when every mapped column is a built-in numeric reducer with a
- * `reduceColumn` fast path over a **packed `Float64Column`** source, each
- * bucket reduces straight off the typed-array slice — skipping the
- * `series.events` materialization and the per-cell `state.add` walk the
- * row path pays. Reuses the shipped step-3A `reduceColumn` kernels
- * (sum/min/max/avg 59–73×, stdev 35×, median/p95 3.4×) per bucket.
- *
- * Returns `null` — caller takes the unchanged row path — when any column
- * doesn't qualify: a custom-function reducer, a reducer with no
- * `reduceColumn` (`first` / `last` / `unique` / `top` / `samples`), or a
- * non-numeric / chunked / missing source column. All-or-nothing per call
- * keeps the bucket walk single-pass; mixed mappings fall back wholesale.
- *
- * `begins` is the key column's begin axis (sorted, identical row order to
- * the value columns — both read straight off the store). Bucketing
- * replicates the row path exactly: `cursor` carries across buckets, and a
- * bucket owns `[start, scan)` where `begins[i] ∈ [bucket.begin,
- * bucket.end)`. Empty buckets reduce an empty slice — the reducer's
- * empty-input result (the step-3A parity contract guarantees this matches
- * a zero-`add` bucket snapshot).
- */
 export declare function tryAggregateColumnarTimeKeyed<B extends {
     begin(): number;
     end(): number;

package/dist/batch/aggregate-columns.js

@@ -73,45 +73,34 @@ export function normalizeAggregateColumns(schema, mapping) {
     }
     return normalized;
 }
-/**
- * **Phase 4.7 step 3B — columnar fast path for time-keyed `aggregate()`.**
- * On sorted time-keyed data each bucket is a contiguous index range, so
- * when every mapped column is a built-in numeric reducer with a
- * `reduceColumn` fast path over a **packed `Float64Column`** source, each
- * bucket reduces straight off the typed-array slice — skipping the
- * `series.events` materialization and the per-cell `state.add` walk the
- * row path pays. Reuses the shipped step-3A `reduceColumn` kernels
- * (sum/min/max/avg 59–73×, stdev 35×, median/p95 3.4×) per bucket.
- *
- * Returns `null` — caller takes the unchanged row path — when any column
- * doesn't qualify: a custom-function reducer, a reducer with no
- * `reduceColumn` (`first` / `last` / `unique` / `top` / `samples`), or a
- * non-numeric / chunked / missing source column. All-or-nothing per call
- * keeps the bucket walk single-pass; mixed mappings fall back wholesale.
- *
- * `begins` is the key column's begin axis (sorted, identical row order to
- * the value columns — both read straight off the store). Bucketing
- * replicates the row path exactly: `cursor` carries across buckets, and a
- * bucket owns `[start, scan)` where `begins[i] ∈ [bucket.begin,
- * bucket.end)`. Empty buckets reduce an empty slice — the reducer's
- * empty-input result (the step-3A parity contract guarantees this matches
- * a zero-`add` bucket snapshot).
- */
 export function tryAggregateColumnarTimeKeyed(begins, getColumn, buckets, columns) {
     const plans = [];
     for (const spec of columns) {
         if (typeof spec.reducer !== 'string')
             return null; // custom function
         const def = resolveReducer(spec.reducer);
-        if (def.reduceColumn === undefined)
-            return null; // first/last/unique/...
         const source = getColumn(spec.source);
-        if (source === undefined ||
-            source.kind !== 'number' ||
-            source.storage !== 'packed') {
-            return null; // non-numeric / chunked / missing source
+        if (source === undefined)
+            return null; // missing source
+        if (def.definedBoundary !== undefined) {
+            // `first` / `last`: pick the first/last *defined* cell in the bucket
+            // via a boundary scan over any column kind / storage (`col.read(i)`).
+            // This is what lets a partitioned `aggregate` — whose auto-injected
+            // partition-column reducer is `'first'` — take the fast path instead
+            // of bailing the whole call for lack of a numeric `reduceColumn`.
+            plans.push({
+                kind: 'boundary',
+                column: source,
+                which: def.definedBoundary,
+            });
+            continue;
         }
-        plans.push({ column: source, reduce: def.reduceColumn });
+        if (def.reduceColumn === undefined)
+            return null; // unique / top / samples / keep
+        if (source.kind !== 'number' || source.storage !== 'packed') {
+            return null; // non-numeric / chunked numeric source
+        }
+        plans.push({ kind: 'reduce', column: source, reduce: def.reduceColumn });
     }
     const n = begins.length;
     let cursor = 0;
@@ -130,7 +119,33 @@ export function tryAggregateColumnarTimeKeyed(begins, getColumn, buckets, column
         const reduced = new Array(plans.length);
         for (let p = 0; p < plans.length; p += 1) {
             const plan = plans[p];
-            reduced[p] = plan.reduce(plan.column.sliceByRange(start, scan));
+            if (plan.kind === 'reduce') {
+                reduced[p] = plan.reduce(plan.column.sliceByRange(start, scan));
+            }
+            else if (plan.which === 'first') {
+                // First defined cell in [start, scan); scans past missing cells.
+                let value;
+                for (let i = start; i < scan; i += 1) {
+                    const cell = plan.column.read(i);
+                    if (cell !== undefined) {
+                        value = cell;
+                        break;
+                    }
+                }
+                reduced[p] = value;
+            }
+            else {
+                // Last defined cell in [start, scan); scans backward past missing.
+                let value;
+                for (let i = scan - 1; i >= start; i -= 1) {
+                    const cell = plan.column.read(i);
+                    if (cell !== undefined) {
+                        value = cell;
+                        break;
+                    }
+                }
+                reduced[p] = value;
+            }
         }
         rows[b] = Object.freeze([bucket, ...reduced]);
     }

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';
@@ -197,8 +196,6 @@ export declare class PartitionedTimeSeries<S extends SeriesSchema, K extends str
     toMap(): Map<K, TimeSeries<S>>;
     toMap<R extends SeriesSchema>(transform: (group: TimeSeries<S>) => TimeSeries<R>): Map<K, TimeSeries<R>>;
     toMap<R>(transform: (group: TimeSeries<S>) => R): Map<K, R>;
-    private static partitionKeyOf;
-    private static bucketByPartition;
     private static applyToSource;
     private rewrap;
     /**
@@ -247,26 +244,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 +306,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/partitioned-time-series.js

@@ -88,17 +88,17 @@ export class PartitionedTimeSeries {
             this.validateGroupMembership();
         }
     }
-    // Validate that every event's partition value appears in the
-    // declared groups. Mirrors the partition encoder so the comparison
-    // accepts the same string forms toMap will produce as keys.
+    // Validate that every partition value appears in the declared groups.
+    // Scans the partition column columnar-natively via `_distinctPartitionKeys`
+    // (no event materialization — same encoding `toMap` produces), so the
+    // declared-`groups` path is materialization-free like the rest of the
+    // split.
     validateGroupMembership() {
         if (!this.groups)
             return;
         const col = this.by[0];
         const declared = new Set(this.groups);
-        const keyOf = PartitionedTimeSeries.partitionKeyOf(this.by);
-        for (const event of this.source.events) {
-            const key = keyOf(event);
+        for (const key of this.source._distinctPartitionKeys(this.by)) {
             if (!declared.has(key)) {
                 // Decode the encoder's leading-space sentinel so the message
                 // shows the user-facing concept, not the internal encoding.
@@ -205,96 +205,54 @@ export class PartitionedTimeSeries {
     }
     toMap(transform) {
         const result = new Map();
-        const buckets = this.source.events.length === 0
+        // Columnar partition split — each sub-series is gathered straight off
+        // the store, no event materialization (the old path rebuilt every
+        // partition via `fromEvents`). Map order = first-encountered partition.
+        const partitions = this.source.length === 0
             ? new Map()
-            : PartitionedTimeSeries.bucketByPartition(this.source, this.by);
+            : this.source._partitionByColumns(this.by);
         if (this.groups) {
             // Declared-order iteration. Empty groups produce empty
             // TimeSeries entries (consistent with pivotByGroup's typed
             // groups behavior, which emits a column for every declared
             // value even when no events match).
             for (const g of this.groups) {
-                const events = buckets.get(g) ?? [];
-                const sub = TimeSeries.fromEvents(events, {
-                    schema: this.source.schema,
-                    name: this.source.name,
-                });
+                const sub = partitions.get(g) ??
+                    TimeSeries.fromEvents([], {
+                        schema: this.source.schema,
+                        name: this.source.name,
+                    });
                 result.set(g, transform ? transform(sub) : sub);
             }
             return result;
         }
         // Insertion-order iteration (matches the order each partition was
         // first encountered in the source events).
-        for (const [key, events] of buckets) {
-            const sub = TimeSeries.fromEvents(events, {
-                schema: this.source.schema,
-                name: this.source.name,
-            });
+        for (const [key, sub] of partitions) {
             result.set(key, transform ? transform(sub) : sub);
         }
         return result;
     }
-    // Build the encoder that produces a string key for an event given
-    // the partition columns. Single-column case avoids the JSON encoding
-    // overhead. Multi-column uses JSON.stringify to guarantee no key
-    // collisions on values containing separators (e.g. region names with
-    // spaces) — a naive `parts.join('|')` would collide. `undefined` in a
-    // single-column key becomes the literal `' undefined'` (with the
-    // leading space ensuring it can never collide with a string column
-    // whose value is the literal `'undefined'`).
-    static partitionKeyOf(by) {
-        if (by.length === 1) {
-            const col = by[0];
-            return (event) => {
-                const v = event.data()[col];
-                return v === undefined ? ' undefined' : `${String(v)}`;
-            };
-        }
-        return (event) => {
-            const data = event.data();
-            const parts = new Array(by.length);
-            for (let i = 0; i < by.length; i += 1) {
-                parts[i] = data[by[i]] ?? null;
-            }
-            return JSON.stringify(parts);
-        };
-    }
-    // Group source events into buckets keyed by partition value. Returned
-    // Map iteration order = insertion order, which matches the order
-    // partitions were first seen in the source events array.
-    static bucketByPartition(source, by) {
-        const keyOf = PartitionedTimeSeries.partitionKeyOf(by);
-        const buckets = new Map();
-        for (const event of source.events) {
-            const key = keyOf(event);
-            let bucket = buckets.get(key);
-            if (!bucket) {
-                bucket = [];
-                buckets.set(key, bucket);
-            }
-            bucket.push(event);
-        }
-        return buckets;
-    }
     // Internal helper used by both `apply` (terminal) and the sugar
     // methods (which re-wrap the result back into a partitioned view).
     static applyToSource(source, by, fn) {
         // Empty source: apply fn to an empty group so the output schema
         // and name come from fn, not from inferring R structurally.
-        if (source.events.length === 0) {
+        if (source.length === 0) {
             const empty = TimeSeries.fromEvents([], {
                 schema: source.schema,
                 name: source.name,
             });
             return fn(empty);
         }
-        const buckets = PartitionedTimeSeries.bucketByPartition(source, by);
+        // Columnar partition split — no event materialization. The old path
+        // walked `source.events` to bucket, then rebuilt each partition via
+        // `fromEvents` (re-validating + re-packing), silently re-paying the
+        // 495 ns/row tax the columnar wave removed. `_partitionByColumns`
+        // gathers each partition straight off the store (audit v2 §3.2).
+        const partitions = source._partitionByColumns(by);
         const transformed = [];
-        for (const events of buckets.values()) {
-            const sub = TimeSeries.fromEvents(events, {
-                schema: source.schema,
-                name: source.name,
-            });
+        for (const sub of partitions.values()) {
             transformed.push(fn(sub));
         }
         return TimeSeries.concat(transformed);

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