pond-ts 0.21.0 → 0.23.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.21.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
 [0.19.0]: https://github.com/pjm17971/pond-ts/compare/v0.18.0...v0.19.0
@@ -15,6 +17,136 @@ 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
+
+- **`asTime` / `asTimeRange` / `asInterval` are now column-native.** They
+  reinterpret the key's kind (a "rekey") straight off the existing key's
+  `begin` / `end` buffers instead of materializing events — value columns pass
+  through by reference. `asTimeRange` and `asTime` with `begin` / `end` reuse
+  the key buffer zero-copy (≈ **9×** faster on a build → rekey → read pipeline);
+  `asTime({ at: 'center' })` adds one midpoint pass; `asInterval` builds the
+  label column (string → `StringColumn`, number → `Float64Column`, inferred
+  from the first label and required consistent across rows). `asTime` with
+  `center` / `end` throws if anchoring a source with overlapping extents would
+  produce a non-monotonic time axis (preserving the prior validation — `begin`
+  is always sorted and is exempt).
+- **Breaking: `asInterval`'s label function now receives the interval's
+  `TimeRange` (its `[begin, end]` extent) and index — not the whole `Event`.**
+  The canonical form is unchanged: `series.asInterval(range => range.begin())`
+  works exactly as before (both `Event` and `TimeRange` expose `begin()` /
+  `end()`). Only a label fn that read a _value column_ off the event (e.g.
+  `event => event.get('label')`) needs rewriting — compute the label before
+  `asInterval`, or derive it from the extent. The constant form
+  (`asInterval('bucket')` / `asInterval(42)`) is unaffected. (Pre-1.0 minor;
+  this is the change that lets the function form stay on the columnar path.)
+
+### Fixed
+
+- **`mapColumns` rejects a non-finite numeric result at write.** A mapper on a
+  `number` column that returns `NaN` or `±Infinity` now throws a `RangeError`,
+  consistent with construction intake (which already rejects non-finite
+  numbers). Previously the value was packed into the column, where the reduce
+  fast path and the row path could disagree on the same bucket (e.g.
+  `aggregate('min')` returning a different result depending on which path ran).
+  A stored `NaN` is still a defined value the mapper sees — map it to a finite
+  number, or to `undefined` (missing), to clean it. (Closes a hole introduced
+  alongside `mapColumns` in 0.21.0.)
+- **`aggregate('stdev')` is now numerically stable and path-independent.** The
+  bucketed row path (`bucketState`) used a one-pass `sq/n − mean²` accumulator
+  that cancels catastrophically on near-equal large-magnitude values —
+  returning `0` (e.g. `[1e10, 1e10+1, 1e10+2, 1e10+3]` → `0` instead of
+  `≈1.118`), or a negative variance whose `sqrt` is `NaN` that the validating
+  constructor then rejected with a throw. Because the columnar fast path is
+  all-or-nothing, an unrelated mapping (e.g. a `count` over a string column)
+  could silently flip the _same_ series' stdev. All three batch paths (`reduce`,
+  `reduceColumn`, `bucketState`) now share **one Welford recurrence** — O(1) per
+  element, no buffer (so the live aggregation path that shares `bucketState`
+  stays O(1)), `m2 ≥ 0` by construction — so they agree regardless of magnitude.
+  (Even the prior two-pass `Σv/n`-then-deviations drifted ~8.7% from the true
+  value at `2^52`, where the summed mean rounds — so unifying on Welford, not
+  two-pass, was necessary.) **Correction:** 0.21.0's columnar `aggregate()` fast
+  path (#186) was described as "signature + semantics unchanged", but it did
+  change released `stdev` output for fast-path-qualifying aggregates; this fix
+  makes every path agree. (`rolling`/`smooth` stdev keep the one-pass form for
+  now — a separate, deferred item.)
+
 ## [0.21.0] — 2026-06-11
 
 ### Added

package/dist/batch/operators/map.d.ts

@@ -19,8 +19,17 @@ export type ColumnMapper = (value: unknown) => unknown;
  * Semantics:
  * - **Missing cells carry.** The mapper is called only on defined
  *   values; a missing (`undefined`) cell stays missing (the mapper is
- *   not invoked). A stored `NaN` is a defined number, so the mapper
- *   *is* called on it (matching `typeof raw === 'number'`).
+ *   not invoked).
+ * - **Numeric results must be finite.** For a `number` column, a mapper
+ *   result of `NaN` or `±Infinity` throws a `RangeError` at write —
+ *   matching construction intake (`assertCellKind`), which rejects
+ *   non-finite numbers. This keeps packed numeric columns NaN-free, so
+ *   the columnar fast-path and the row-path reducers can never diverge
+ *   on the same bucket (the bug audit v2 §1.3 reproduced). A stored
+ *   `NaN` *is* a defined value, so the mapper is still invoked on it —
+ *   use that to clean it (map `NaN` to a finite number, or to
+ *   `undefined` for a missing cell). (Array columns are not
+ *   element-checked here; they don't feed the numeric reducers.)
  * - **Same kind, schema-stable.** The mapper returns the column's own
  *   kind (the method's type enforces `(value: T) => T`), so the output
  *   column keeps its kind and the schema is unchanged. The result is
@@ -36,6 +45,9 @@ export type ColumnMapper = (value: unknown) => unknown;
  * same-kind builder can't store: `columnFromValuesByKind` coerces it
  * to missing, so the cell reads back as a gap the declared schema may
  * not advertise. Both are type-illegal inputs, not handled specially.
+ * (A non-finite *number* from a numeric mapper is the one same-kind
+ * case that throws rather than coerces — it would corrupt the packed
+ * column, not read back as a gap.)
  */
 export declare function mapOp<S extends SeriesSchema>(store: ColumnarStore<S>, schema: S, spec: ReadonlyMap<string, ColumnMapper>): {
     store: ColumnarStore<S>;

package/dist/batch/operators/map.js

@@ -32,8 +32,17 @@ function columnFromValuesByKind(kind, values) {
  * Semantics:
  * - **Missing cells carry.** The mapper is called only on defined
  *   values; a missing (`undefined`) cell stays missing (the mapper is
- *   not invoked). A stored `NaN` is a defined number, so the mapper
- *   *is* called on it (matching `typeof raw === 'number'`).
+ *   not invoked).
+ * - **Numeric results must be finite.** For a `number` column, a mapper
+ *   result of `NaN` or `±Infinity` throws a `RangeError` at write —
+ *   matching construction intake (`assertCellKind`), which rejects
+ *   non-finite numbers. This keeps packed numeric columns NaN-free, so
+ *   the columnar fast-path and the row-path reducers can never diverge
+ *   on the same bucket (the bug audit v2 §1.3 reproduced). A stored
+ *   `NaN` *is* a defined value, so the mapper is still invoked on it —
+ *   use that to clean it (map `NaN` to a finite number, or to
+ *   `undefined` for a missing cell). (Array columns are not
+ *   element-checked here; they don't feed the numeric reducers.)
  * - **Same kind, schema-stable.** The mapper returns the column's own
  *   kind (the method's type enforces `(value: T) => T`), so the output
  *   column keeps its kind and the schema is unchanged. The result is
@@ -49,6 +58,9 @@ function columnFromValuesByKind(kind, values) {
  * same-kind builder can't store: `columnFromValuesByKind` coerces it
  * to missing, so the cell reads back as a gap the declared schema may
  * not advertise. Both are type-illegal inputs, not handled specially.
+ * (A non-finite *number* from a numeric mapper is the one same-kind
+ * case that throws rather than coerces — it would corrupt the packed
+ * column, not read back as a gap.)
  */
 export function mapOp(store, schema, spec) {
     const n = store.length;
@@ -65,10 +77,30 @@ export function mapOp(store, schema, spec) {
         if (col === undefined)
             continue;
         const kind = colKind.get(name);
+        // Numeric columns reject a non-finite (NaN / ±Infinity) mapper result at
+        // write, matching construction intake (assertCellKind). A packed NaN would
+        // otherwise be unreachable-by-assumption for the reduce kernels and diverge
+        // the fast path from the row path (audit v2 §1.3). Hoisted out of the loop
+        // so non-numeric columns pay nothing.
+        const rejectNonFinite = kind === 'number';
         const out = new Array(n);
         for (let i = 0; i < n; i += 1) {
             const v = col.read(i);
-            out[i] = v === undefined ? undefined : fn(v);
+            if (v === undefined) {
+                out[i] = undefined;
+                continue;
+            }
+            const mapped = fn(v);
+            if (rejectNonFinite &&
+                typeof mapped === 'number' &&
+                !Number.isFinite(mapped)) {
+                throw new RangeError(`mapColumns: the mapper for column '${name}' returned a non-finite ` +
+                    `number (${mapped}) at row ${i}. Numeric columns reject NaN and ` +
+                    `±Infinity at write, consistent with intake — a packed NaN would ` +
+                    `diverge the fast-path and row-path reducers on the same data. ` +
+                    `Map to a finite number, or to undefined for a missing cell.`);
+            }
+            out[i] = mapped;
         }
         result = withColumnReplaced(result, name, columnFromValuesByKind(kind, out));
     }

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 })`.
@@ -337,9 +342,9 @@ export declare class TimeSeries<S extends SeriesSchema> {
     }): TimeSeries<TimeKeyedSchema<S>>;
     /** Example: `series.asTimeRange()`. Converts the series key type to `"timeRange"` while preserving each event extent. */
     asTimeRange(): TimeSeries<TimeRangeKeyedSchema<S>>;
-    /** Example: `series.asInterval(event => event.begin())`. Converts the series key type to `"interval"` while preserving each event extent and supplying interval labels. */
+    /** Example: `series.asInterval(range => range.begin())`. Converts the series key type to `"interval"` while preserving each event extent and supplying interval labels. */
     asInterval(value: IntervalValue): TimeSeries<IntervalKeyedSchema<S>>;
-    asInterval(value: (event: EventForSchema<S>, index: number) => IntervalValue): TimeSeries<IntervalKeyedSchema<S>>;
+    asInterval(value: (range: TimeRange, index: number) => IntervalValue): TimeSeries<IntervalKeyedSchema<S>>;
     /**
      * Example: `left.join(right, { type: "left" })`.
      * Performs an exact-key join of two series with the same key kind.
@@ -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

@@ -12,7 +12,7 @@ import { TimeRange } from '../core/time-range.js';
 import { compareEventKeys } from '../core/temporal.js';
 import { PartitionedTimeSeries } from './partitioned-time-series.js';
 import { Sequence } from '../sequence/sequence.js';
-import { withColumnsRenamed, withColumnsSelected, withRowRange, } from '../columnar/index.js';
+import { IntervalKeyColumn, TimeKeyColumn, TimeRangeKeyColumn, float64ColumnFromArray, stringColumnFromArray, withColumnsRenamed, withColumnsSelected, withKeyColumn, withRowRange, } from '../columnar/index.js';
 import { SeriesStore } from '../live/series-store.js';
 import { parseDuration } from '../core/duration.js';
 import { resolveReducer, } from '../reducers/index.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);
@@ -847,40 +860,95 @@ export class TimeSeries {
     }
     /** Example: `series.asTime({ at: "center" })`. Converts the series key type to `"time"` using the supplied anchor within each event extent. */
     asTime(options = {}) {
+        // Column-native rekey: reinterpret the key as `time` straight off the
+        // existing key's begin/end buffers — no `this.events`. `begin`/`end`
+        // reuse the source buffer zero-copy; `center` computes midpoints.
         const schema = Object.freeze([
             { name: 'time', kind: 'time' },
             ...this.schema.slice(1),
         ]);
-        const resultEvents = this.events.map((event) => event.asTime(options));
-        if ((options.at ?? 'begin') === 'begin') {
-            return TimeSeries.#fromTrustedEvents(this.name, schema, resultEvents);
+        const keys = this.#store.store.keys;
+        const at = options.at ?? 'begin';
+        const n = keys.length;
+        let beginBuf;
+        if (at === 'center') {
+            beginBuf = new Float64Array(n);
+            for (let i = 0; i < n; i += 1) {
+                beginBuf[i] = (keys.begin[i] + keys.end[i]) / 2;
+            }
         }
-        return new TimeSeries({
-            name: this.name,
-            schema,
-            rows: toRows(schema, resultEvents),
-        });
+        else {
+            beginBuf = at === 'end' ? keys.end : keys.begin;
+        }
+        // The source is ordered by `begin`, so `begin` stays monotonic — but for a
+        // ranged source with overlapping extents, anchoring at `end` / `center`
+        // can REORDER rows, producing a non-monotonic time axis. The pre-#200 path
+        // routed these anchors through the validating constructor, which threw on
+        // an unsorted result; `withKeyColumn` → `#fromTrustedStore` trusts the key
+        // and would silently accept it (breaking `bisect` / `timeRange` / key-range
+        // ops). Restore the throw with an O(n) scan. (`begin` can't reorder, so it
+        // is exempt — and `withKeyColumn` documents the monotonic-key precondition.)
+        if (at !== 'begin') {
+            for (let i = 1; i < n; i += 1) {
+                if (beginBuf[i] < beginBuf[i - 1]) {
+                    throw new Error(`asTime({ at: '${at}' }) produced a non-monotonic time axis at ` +
+                        `row ${i} (${beginBuf[i]} < ${beginBuf[i - 1]}): the source ` +
+                        `extents overlap, so anchoring at '${at}' reorders rows. Anchor ` +
+                        `at 'begin', or re-sort after converting.`);
+                }
+            }
+        }
+        const store = withKeyColumn(this.#store.store, schema[0], new TimeKeyColumn(beginBuf, keys.length));
+        return TimeSeries.#fromTrustedStore(this.name, schema, store);
     }
     /** Example: `series.asTimeRange()`. Converts the series key type to `"timeRange"` while preserving each event extent. */
     asTimeRange() {
+        // Column-native rekey: the timeRange covers each row's existing extent —
+        // reuse the key's begin/end buffers zero-copy, no events.
         const schema = Object.freeze([
             { name: 'timeRange', kind: 'timeRange' },
             ...this.schema.slice(1),
         ]);
-        const resultEvents = this.events.map((event) => event.asTimeRange());
-        return TimeSeries.#fromTrustedEvents(this.name, schema, resultEvents);
+        const keys = this.#store.store.keys;
+        const store = withKeyColumn(this.#store.store, schema[0], new TimeRangeKeyColumn(keys.begin, keys.end, keys.length));
+        return TimeSeries.#fromTrustedStore(this.name, schema, store);
     }
     asInterval(value) {
+        // Column-native rekey: build the interval labels straight off the key's
+        // begin/end buffers — no events. The label fn receives the interval's
+        // TimeRange (its [begin, end] extent) + index, NOT the whole event
+        // (breaking — see CHANGELOG [Unreleased]). Label kind is inferred from the
+        // first label — the two `IntervalValue` kinds, string → StringColumn /
+        // number → Float64Column — and must be consistent across rows (a mix
+        // throws, as at event intake). A type-defeated non-string/number label
+        // (e.g. a boolean via `as any`) is rejected here rather than coerced the
+        // way intake would (`true → 1`); throwing on the nonsense input is safer.
         const schema = Object.freeze([
             { name: 'interval', kind: 'interval' },
             ...this.schema.slice(1),
         ]);
-        const nextEvents = this.events.map((event, index) => {
-            return typeof value === 'function'
-                ? event.asInterval(() => value(event, index))
-                : event.asInterval(value);
-        });
-        return TimeSeries.#fromTrustedEvents(this.name, schema, nextEvents);
+        const keys = this.#store.store.keys;
+        const n = keys.length;
+        const labels = new Array(n);
+        if (typeof value === 'function') {
+            for (let i = 0; i < n; i += 1) {
+                labels[i] = value(new TimeRange([keys.begin[i], keys.end[i]]), i);
+            }
+        }
+        else {
+            labels.fill(value);
+        }
+        const labelKind = n > 0 ? typeof labels[0] : 'string';
+        for (let i = 1; i < n; i += 1) {
+            if (typeof labels[i] !== labelKind) {
+                throw new Error(`asInterval: interval label at row ${i} is ${typeof labels[i]} but earlier rows were ${labelKind} — interval labels must be one type throughout`);
+            }
+        }
+        const labelCol = labelKind === 'number'
+            ? float64ColumnFromArray(labels)
+            : stringColumnFromArray(labels);
+        const store = withKeyColumn(this.#store.store, schema[0], new IntervalKeyColumn(keys.begin, keys.end, labelCol, n));
+        return TimeSeries.#fromTrustedStore(this.name, schema, store);
     }
     join(other, options = {}) {
         const [left, right] = prepareSeriesForJoin([
@@ -1237,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) {
@@ -2771,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' },
@@ -2865,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/columnar/index.d.ts

@@ -37,5 +37,5 @@ export { type IntervalLabelKind, type KeyColumn, IntervalKeyColumn, TimeKeyColum
 export { type FromTrustedStoreOptions, ColumnarStore } from './store.js';
 export { type ColumnBuilder, ArrayColumnBuilder, BooleanColumnBuilder, Float64ColumnBuilder, StringColumnBuilder, columnBuilderForKind, } from './builder.js';
 export { type AnyColumnKind, type ArrayValue, type ColumnDef, type ColumnSchema, type KeyKind, type ScalarValue, } from './types.js';
-export { materialize, withColumnAppended, withColumnReplaced, withColumnsRenamed, withColumnsSelected, withRowRange, withRowSelection, } from './view.js';
+export { materialize, withColumnAppended, withColumnReplaced, withColumnsRenamed, withColumnsSelected, withKeyColumn, withRowRange, withRowSelection, } from './view.js';
 //# sourceMappingURL=index.d.ts.map