pond-ts 0.27.0 → 0.29.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.27.0...HEAD
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.29.0...HEAD
+[0.29.0]: https://github.com/pjm17971/pond-ts/compare/v0.28.0...v0.29.0
+[0.28.0]: https://github.com/pjm17971/pond-ts/compare/v0.27.0...v0.28.0
 [0.27.0]: https://github.com/pjm17971/pond-ts/compare/v0.26.0...v0.27.0
 [0.26.0]: https://github.com/pjm17971/pond-ts/compare/v0.25.0...v0.26.0
 [0.25.0]: https://github.com/pjm17971/pond-ts/compare/v0.24.0...v0.25.0
@@ -21,7 +23,58 @@ type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
-## [0.27.0] — 2026-06-16
+## [0.29.0] — 2026-06-17
+
+### Added
+
+- **`byColumn({ edges, inclusive })`** — `inclusive: '(]'` makes edge bins
+  upper-inclusive (`(eᵢ, eᵢ₊₁]`), for Coggan power / HR zones where a sample on a
+  zone's top edge belongs to the lower zone (the first edge becomes an exclusive
+  floor). Defaults to `'[)'` (unchanged — lower-inclusive `[eᵢ, eᵢ₊₁)`). (estela
+  F-geo-2 zone inclusivity.)
+- **`'mean'` reducer alias for `'avg'`** — `'mean'` is now an accepted built-in
+  reducer name across `aggregate` / `rolling` / `byColumn` / `rollingByColumn` /
+  `reduce` (and the live equivalents), at **both runtime and the type level**: it
+  resolves to the `avg` kernel and classifies as numeric output
+  (`number | undefined`), exactly like `'avg'`. Matches the column API's
+  `Float64Column.mean()`. (estela F-reducer-naming.)
+
+### Fixed
+
+- **`RowForSchema` honors `required: false`** — a **value** column declared
+  `required: false` now accepts `undefined` in its tuple-row cell at the type
+  level (matching the runtime, which records it as missing), so optional cells no
+  longer need an `as never` cast. The **key (first) column stays required** even
+  if marked `required: false` (the constructor always requires it). `null` is
+  still not admitted for tuple rows (only the JSON object-row path takes `null`).
+  Correspondingly, **`.rows` / `toRows()` now type an optional cell as
+  `… | undefined`** (`NormalizedRowForSchema`), so reading a possibly-missing
+  cell is no longer unsoundly typed as present — a type tightening on output for
+  schemas that use `required: false`. (estela F-geo-row-optional; Codex-hardened.)
+
+## [0.28.0] — 2026-06-17
+
+### Added
+
+- **`TimeSeries.rollingByColumn(col, { radius }, mapping)` — windowed value-axis
+  aggregation.** The sliding-window sibling of `byColumn`: slides a centered
+  `±radius` window along a **non-decreasing** numeric column and reduces it at
+  every row, returning one record per row (positionally aligned with the
+  series). Where `byColumn` collapses rows into disjoint value-bins (the
+  value-axis analogue of `aggregate`), `rollingByColumn` is the value-axis
+  analogue of `rolling`. Built for windowed-percentile bands over a derived axis
+  (e.g. a spread band over cumulative distance). A missing/non-finite axis row is
+  excluded from every window and emits each reducer's empty value. O(n) two-pointer
+  sweep. See `docs/notes/rolling-by-column.md`.
+- **`TimeSeries.withColumn(name, values)` — attach a computed numeric column.**
+  Appends a `Float64Array` / `(number | undefined)[]` as a new `number` column
+  (the schema type widens to include it), so a derived array — cumulative
+  distance, speed, gradient — can re-enter the pond pipeline as a real column
+  that `aggregate` / `byColumn` / `rollingByColumn` / `column(name)` can
+  reference. Existing key + value columns are shared by reference (zero-copy);
+  only the new column is added. `values` must match `series.length`; defined
+  cells are validated against the numeric intake contract (**non-finite is
+  rejected** — pass `undefined` for a missing cell, not `NaN`).
 
 ### Added
 
@@ -52,7 +105,7 @@ type-level changes; patch bumps are strictly additive.
   - **Behavior note — `array` columns:** an identity-comparing reducer (`keep`,
     or a custom reducer using `===` on the cell) on an `array`-kind source
     column now compares the value stored in the column, not the original object
-    reference passed at construction. Two rows given the *same* array object
+    reference passed at construction. Two rows given the _same_ array object
     therefore read as distinct. Scalar columns (number / string / boolean) are
     unaffected. A non-finite or wrong-kind reducer result is still rejected with
     a `ValidationError`, exactly as the constructor's intake did.

package/dist/batch/by-column.d.ts

@@ -11,6 +11,7 @@ export type BinSpec = {
     origin?: number;
 } | {
     edges: readonly number[];
+    inclusive?: '[)' | '(]';
 };
 /** One value-bin's record: its `[start, end)` range plus the mapped aggregates. */
 export type BinRecord = {

package/dist/batch/by-column.js

@@ -45,21 +45,45 @@ export function computeByColumn(store, binColName, spec, columnSpecs) {
             }
         }
         const last = edges.length - 1;
-        binOf = (v) => {
-            if (v < edges[0] || v >= edges[last])
-                return NaN; // out of range → drop
-            // rightmost edge <= v, clamped to a valid bin [0, last)
-            let lo = 0;
-            let hi = last; // bins are [0, last)
-            while (lo < hi) {
-                const mid = (lo + hi + 1) >>> 1;
-                if (edges[mid] <= v)
-                    lo = mid;
-                else
-                    hi = mid - 1;
-            }
-            return lo;
-        };
+        // `inclusive` picks the bin a value exactly on an interior edge falls into.
+        // `'[)'` (default): bins are `[eᵢ, eᵢ₊₁)`, lower-inclusive — a boundary value
+        // goes to the bin ABOVE; range is `[e₀, eₙ)`. `'(]'`: bins are `(eᵢ, eᵢ₊₁]`,
+        // upper-inclusive (Coggan power/HR zones — a sample at exactly a zone's top
+        // edge is the LOWER zone) — a boundary value goes to the bin BELOW; range is
+        // `(e₀, eₙ]`, so the first edge is an exclusive floor (set it below your
+        // minimum to keep the minimum in bin 0).
+        binOf =
+            spec.inclusive === '(]'
+                ? (v) => {
+                    if (v <= edges[0] || v > edges[last])
+                        return NaN; // out of (e₀, eₙ]
+                    // rightmost edge STRICTLY less than v, clamped to a valid bin [0, last)
+                    let lo = 0;
+                    let hi = last;
+                    while (lo < hi) {
+                        const mid = (lo + hi + 1) >>> 1;
+                        if (edges[mid] < v)
+                            lo = mid;
+                        else
+                            hi = mid - 1;
+                    }
+                    return lo;
+                }
+                : (v) => {
+                    if (v < edges[0] || v >= edges[last])
+                        return NaN; // out of [e₀, eₙ)
+                    // rightmost edge <= v, clamped to a valid bin [0, last)
+                    let lo = 0;
+                    let hi = last;
+                    while (lo < hi) {
+                        const mid = (lo + hi + 1) >>> 1;
+                        if (edges[mid] <= v)
+                            lo = mid;
+                        else
+                            hi = mid - 1;
+                    }
+                    return lo;
+                };
         rangeOf = (i) => ({ start: edges[i], end: edges[i + 1] });
     }
     else {

package/dist/batch/operators/column-builders.d.ts

@@ -2,9 +2,12 @@ import { type Column } from '../../columnar/index.js';
 /**
  * Build a typed {@link Column} from a per-row value array, dispatching on the
  * column's `kind`. An `undefined` cell becomes missing (its validity bit is
- * left unset, so `read(i)` returns `undefined`). Numeric arrays reject
- * non-finite values at construction (`float64ColumnFromArray`) — packed
- * numeric columns stay NaN-free.
+ * left unset, so `read(i)` returns `undefined`). These builders do **not**
+ * enforce the intake contract: `float64ColumnFromArray` *stores* a non-finite
+ * number (flagging the column non-finite for the guarded reducer path) rather
+ * than rejecting it, and the `*FromArray` builders coerce a kind mismatch to a
+ * missing cell. A caller that must uphold intake (finite-or-missing, no NaN in
+ * a packed numeric column) calls {@link assertColumnValuesMatchKind} first.
  *
  * This is the shared form of the kind→builder dispatch that `fill`
  * (`buildFilledColumn`), `map` (its inline builder), and `collapse`

package/dist/batch/operators/column-builders.js

@@ -3,9 +3,12 @@ import { ValidationError } from '../../core/errors.js';
 /**
  * Build a typed {@link Column} from a per-row value array, dispatching on the
  * column's `kind`. An `undefined` cell becomes missing (its validity bit is
- * left unset, so `read(i)` returns `undefined`). Numeric arrays reject
- * non-finite values at construction (`float64ColumnFromArray`) — packed
- * numeric columns stay NaN-free.
+ * left unset, so `read(i)` returns `undefined`). These builders do **not**
+ * enforce the intake contract: `float64ColumnFromArray` *stores* a non-finite
+ * number (flagging the column non-finite for the guarded reducer path) rather
+ * than rejecting it, and the `*FromArray` builders coerce a kind mismatch to a
+ * missing cell. A caller that must uphold intake (finite-or-missing, no NaN in
+ * a packed numeric column) calls {@link assertColumnValuesMatchKind} first.
  *
  * This is the shared form of the kind→builder dispatch that `fill`
  * (`buildFilledColumn`), `map` (its inline builder), and `collapse`

package/dist/batch/rolling-by-column.d.ts

@@ -0,0 +1,36 @@
+import type { ColumnSchema, ColumnarStore } from '../columnar/index.js';
+import type { ColumnValue } from '../schema/index.js';
+import type { AggregateColumnSpec } from './aggregate-columns.js';
+/**
+ * Window spec for {@link TimeSeries.rollingByColumn}: a **centered** window of
+ * half-width `radius`, in the axis column's own units. The window for a row is
+ * every row whose axis value lies within `±radius` of it. See
+ * `docs/notes/rolling-by-column.md`.
+ */
+export type WindowSpec = {
+    radius: number;
+};
+/** One windowed record: the mapped aggregates over the window centered at a row. */
+export type WindowRecord = Record<string, ColumnValue | undefined>;
+/**
+ * Windowed value-axis aggregation runtime — the sliding-window sibling of
+ * {@link computeByColumn}. For each row, reduces (via `columnSpecs`) the rows
+ * whose `axisColName` value lies within `±spec.radius` of that row's value,
+ * returning one {@link WindowRecord} per row, **positionally aligned with the
+ * store** (`out[i]` is the window centered at row `i`).
+ *
+ * The axis column must be **non-decreasing** — that ordering is what makes a
+ * sliding window meaningful (vs `byColumn`'s order-free group-by) and is what
+ * lets the window advance as a single O(n) two-pointer rather than a per-row
+ * range scan. A row whose axis value is missing / non-finite can't be placed in
+ * the ordering: it is excluded from every window, and its own output slot gets
+ * each reducer's empty snapshot (so the result stays positionally aligned). The
+ * reducer non-finite policy still applies to the *source* columns.
+ *
+ * Reads straight off the columnar store (`Column.read(i)`, no event
+ * materialization). Uses `rollingStateFor` (add/remove/snapshot) rather than the
+ * append-only `bucketStateFor`, because the window is a moving multiset; the two
+ * pointers `add` rows entering the right edge and `remove` rows leaving the left.
+ */
+export declare function computeRollingByColumn(store: ColumnarStore<ColumnSchema>, axisColName: string, spec: WindowSpec, columnSpecs: ReadonlyArray<AggregateColumnSpec>): WindowRecord[];
+//# sourceMappingURL=rolling-by-column.d.ts.map

package/dist/batch/rolling-by-column.js

@@ -0,0 +1,102 @@
+import { rollingStateFor } from '../reducers/index.js';
+/**
+ * Windowed value-axis aggregation runtime — the sliding-window sibling of
+ * {@link computeByColumn}. For each row, reduces (via `columnSpecs`) the rows
+ * whose `axisColName` value lies within `±spec.radius` of that row's value,
+ * returning one {@link WindowRecord} per row, **positionally aligned with the
+ * store** (`out[i]` is the window centered at row `i`).
+ *
+ * The axis column must be **non-decreasing** — that ordering is what makes a
+ * sliding window meaningful (vs `byColumn`'s order-free group-by) and is what
+ * lets the window advance as a single O(n) two-pointer rather than a per-row
+ * range scan. A row whose axis value is missing / non-finite can't be placed in
+ * the ordering: it is excluded from every window, and its own output slot gets
+ * each reducer's empty snapshot (so the result stays positionally aligned). The
+ * reducer non-finite policy still applies to the *source* columns.
+ *
+ * Reads straight off the columnar store (`Column.read(i)`, no event
+ * materialization). Uses `rollingStateFor` (add/remove/snapshot) rather than the
+ * append-only `bucketStateFor`, because the window is a moving multiset; the two
+ * pointers `add` rows entering the right edge and `remove` rows leaving the left.
+ */
+export function computeRollingByColumn(store, axisColName, spec, columnSpecs) {
+    const axisCol = store.columns.get(axisColName);
+    if (axisCol === undefined) {
+        throw new RangeError(`rollingByColumn: unknown column '${axisColName}'`);
+    }
+    if (axisCol.kind !== 'number') {
+        throw new TypeError(`rollingByColumn: column '${axisColName}' must be a number column (got '${axisCol.kind}')`);
+    }
+    const { radius } = spec;
+    if (!Number.isFinite(radius) || radius <= 0) {
+        throw new RangeError('rollingByColumn: radius must be a positive finite number');
+    }
+    const sourceCols = columnSpecs.map((s) => store.columns.get(s.source));
+    const n = store.length;
+    // Compact the finite-axis rows in row order: `ax[k]` is the axis value, `idx[k]`
+    // the real row index. Validate non-decreasing — a sliding window over an
+    // unsorted axis is meaningless, and a descending step would break the
+    // monotonic two-pointer below (it only ever moves `lo`/`hi` to the right).
+    const ax = new Float64Array(n);
+    const idx = new Int32Array(n);
+    let m = 0;
+    for (let i = 0; i < n; i += 1) {
+        const av = axisCol.read(i);
+        if (typeof av !== 'number' || !Number.isFinite(av))
+            continue;
+        if (m > 0 && av < ax[m - 1]) {
+            throw new RangeError(`rollingByColumn: axis column '${axisColName}' must be non-decreasing; row ${i} (${av}) < previous (${ax[m - 1]})`);
+        }
+        ax[m] = av;
+        idx[m] = i;
+        m += 1;
+    }
+    // One shared rolling state per output column, maintained incrementally across
+    // the whole sweep — this is what makes it O(n) rather than O(n · window).
+    const states = columnSpecs.map((s) => rollingStateFor(s.reducer));
+    const specCount = columnSpecs.length;
+    const out = new Array(n);
+    let lo = 0;
+    let hi = 0; // the window currently holds compact positions [lo, hi)
+    for (let i = 0; i < n; i += 1) {
+        const av = axisCol.read(i);
+        if (typeof av !== 'number' || !Number.isFinite(av)) {
+            // No axis position → empty window. A FRESH empty snapshot per row (per
+            // spec), not a shared/cached value: an array-kind reducer would otherwise
+            // alias one `[]` across rows. Matches byColumn's empty-bin handling.
+            const rec = {};
+            for (let c = 0; c < specCount; c += 1) {
+                rec[columnSpecs[c].output] = rollingStateFor(columnSpecs[c].reducer).snapshot();
+            }
+            out[i] = rec;
+            continue;
+        }
+        const wlo = av - radius;
+        const whi = av + radius;
+        // Expand the right edge: add finite-axis rows with `ax ≤ center + radius`.
+        while (hi < m && ax[hi] <= whi) {
+            const r = idx[hi];
+            for (let c = 0; c < specCount; c += 1) {
+                states[c].add(r, sourceCols[c].read(r));
+            }
+            hi += 1;
+        }
+        // Contract the left edge: drop rows with `ax < center − radius`. The center
+        // row itself satisfies `wlo ≤ av ≤ whi`, so `lo` never passes it (`lo < hi`
+        // always holds here) and the window is non-empty.
+        while (lo < hi && ax[lo] < wlo) {
+            const r = idx[lo];
+            for (let c = 0; c < specCount; c += 1) {
+                states[c].remove(r, sourceCols[c].read(r));
+            }
+            lo += 1;
+        }
+        const rec = {};
+        for (let c = 0; c < specCount; c += 1) {
+            rec[columnSpecs[c].output] = states[c].snapshot();
+        }
+        out[i] = rec;
+    }
+    return out;
+}
+//# sourceMappingURL=rolling-by-column.js.map

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

@@ -1,6 +1,7 @@
-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 { AlignSchema, MaterializeSchema, ArrayAggregateAppendSchema, ArrayAggregateReplaceSchema, ArrayColumnNameForSchema, ArrayExplodeAppendSchema, ArrayExplodeReplaceSchema, BaselineSchema, AggregateReducer, AggregateSchema, AppendColumn, 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 { type BinSpec } from './by-column.js';
+import { type WindowSpec } from './rolling-by-column.js';
 import { BoundedSequence } from '../sequence/bounded-sequence.js';
 import { type TimeZoneOptions } from '../core/calendar.js';
 import { TimeRange } from '../core/time-range.js';
@@ -538,8 +539,11 @@ export declare class TimeSeries<S extends SeriesSchema> {
      *   source (cumulative distance / work) yields contiguous ranges (per-km
      *   splits, elevation-vs-distance profile); a non-monotonic source (power)
      *   yields a histogram (distribution).
-     * - `{ edges }` — explicit ascending edges `[e₀ … eₙ]` → `n` bins, bin `i` =
-     *   `[eᵢ, eᵢ₊₁)` (e.g. FTP / Coggan power zones). Always emits all `n` bins.
+     * - `{ edges, inclusive? }` — explicit ascending edges `[e₀ … eₙ]` → `n` bins.
+     *   `inclusive` defaults to `'[)'` (bin `i` = `[eᵢ, eᵢ₊₁)`, lower-inclusive);
+     *   pass `'(]'` for upper-inclusive bins (`(eᵢ, eᵢ₊₁]`) — Coggan power / HR
+     *   zones, where a sample exactly on a zone's top edge belongs to the lower
+     *   zone (the first edge becomes an exclusive floor). Always emits all `n` bins.
      *
      * A row whose bin value is missing / non-finite (or, for `edges`, outside
      * `[e₀, eₙ)`) contributes to no bin. The reducer non-finite policy still
@@ -551,6 +555,32 @@ export declare class TimeSeries<S extends SeriesSchema> {
         start: number;
         end: number;
     } & ReduceResult<S, Mapping>>;
+    /**
+     * Example:
+     * `series.rollingByColumn('cumDist', { radius: 120 }, { lo: { from: 'speed', using: 'p5' }, hi: { from: 'speed', using: 'p95' } })`.
+     *
+     * **Windowed value-axis aggregation — the sliding-window sibling of
+     * `byColumn`.** Where `byColumn` collapses rows into disjoint value-bins (the
+     * value-axis analogue of `aggregate`), `rollingByColumn` slides a **centered
+     * window** along a value axis and reduces the window at every row (the
+     * value-axis analogue of `rolling`). For each row it reduces the rows whose
+     * `col` value lies within `±radius` of that row's value, and returns **one
+     * record per row, positionally aligned with the series** (`out[i]` is the
+     * window centered at row `i`) — *not* a `TimeSeries`, and with no `start`/`end`
+     * range (the caller already has the axis column to zip against).
+     *
+     * `col` must be a **non-decreasing** numeric column — the ordering is what
+     * makes a sliding window meaningful (vs `byColumn`'s order-free group-by) and
+     * is enforced (a descending step throws). A row whose `col` value is missing /
+     * non-finite is excluded from every window and its own slot gets each
+     * reducer's empty snapshot, so the result stays positionally aligned. The
+     * reducer non-finite policy still applies to the *source* columns.
+     *
+     * The window is centered and inclusive (`col[i] − radius ≤ col[j] ≤ col[i] +
+     * radius`); a single O(n) two-pointer sweep maintains the window. See
+     * `docs/notes/rolling-by-column.md`.
+     */
+    rollingByColumn<const Mapping extends ValidatedAggregateMap<S, Mapping>>(col: NumericColumnNameForSchema<S>, spec: WindowSpec, mapping: Mapping): Array<ReduceResult<S, Mapping>>;
     /**
      * Example: `series.groupBy("host")`.
      * Partitions the series into groups keyed by the distinct values of a payload column.
@@ -1112,6 +1142,31 @@ export declare class TimeSeries<S extends SeriesSchema> {
     select<const Keys extends readonly (keyof EventDataForSchema<S>)[]>(...keys: Keys): TimeSeries<SelectSchema<S, Keys[number] & string>>;
     /** Example: `series.rename({ cpu: "usage" })`. Returns a new series with payload field names renamed according to the supplied mapping. */
     rename<const Mapping extends RenameMap<EventDataForSchema<S>>>(mapping: Mapping): TimeSeries<RenameSchema<S, Mapping>>;
+    /**
+     * Example:
+     * `series.withColumn('cumDist', cumulativeDistances)` (a `Float64Array`).
+     *
+     * **Attach a computed numeric column.** Returns a new series with `values`
+     * appended as a new `number` column named `name`, so downstream pond ops
+     * (`aggregate`, `byColumn`, `rollingByColumn`, `column(name)`) can reference
+     * it. The existing key + value columns are shared by reference (zero-copy);
+     * only the new column is added. This is the seam that lets a derived array
+     * (cumulative distance, speed, gradient) re-enter the pond pipeline as a real
+     * column instead of staying a side-channel.
+     *
+     * `values` is a `Float64Array` (dense) or a `(number | undefined)[]` (where
+     * `undefined` marks a missing cell), and must have exactly `series.length`
+     * entries. Defined values are validated against the numeric intake contract —
+     * **non-finite (`NaN` / `±Infinity`) is rejected** (a `ValidationError`,
+     * matching construction), so packed numeric columns stay NaN-free; pass
+     * `undefined` for a missing cell, never `NaN`. `name` must not collide with an
+     * existing column.
+     *
+     * This is the *validated* attach. A trusted bulk-construction path
+     * (`fromTrustedColumns`, skipping the finite scan) is a deferred sibling for
+     * when a perf-critical consumer earns it.
+     */
+    withColumn<const Name extends string>(name: Name, values: ReadonlyArray<number | undefined> | Float64Array): TimeSeries<AppendColumn<S, Name, 'number'>>;
     /** Example: `series.collapse(["in", "out"], "avg", fn)`. Collapses selected payload fields into a single derived field across each event in the series. */
     collapse<const Keys extends readonly (keyof EventDataForSchema<S>)[], Name extends string, R extends ScalarValue>(keys: Keys, output: Name, reducer: (values: Pick<EventDataForSchema<S>, Keys[number]>) => R): TimeSeries<CollapseSchema<S, Keys[number] & string, Name, R>>;
     collapse<const Keys extends readonly (keyof EventDataForSchema<S>)[], Name extends string, R extends ScalarValue>(keys: Keys, output: Name, reducer: (values: Pick<EventDataForSchema<S>, Keys[number]>) => R, options: {

package/dist/batch/time-series.js

@@ -7,6 +7,7 @@ import { shiftOp } from './operators/shift.js';
 import { collapseOp } from './operators/collapse.js';
 import { assertColumnValuesMatchKind, columnFromValuesByKind, } from './operators/column-builders.js';
 import { computeByColumn } from './by-column.js';
+import { computeRollingByColumn, } from './rolling-by-column.js';
 import { BoundedSequence } from '../sequence/bounded-sequence.js';
 import { Interval } from '../core/interval.js';
 import { Time } from '../core/time.js';
@@ -14,7 +15,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 { ColumnarStore, IntervalKeyColumn, TimeKeyColumn, TimeRangeKeyColumn, float64ColumnFromArray, stringColumnFromArray, withColumnsRenamed, withColumnsSelected, withKeyColumn, withRowRange, withRowSelection, } from '../columnar/index.js';
+import { ColumnarStore, IntervalKeyColumn, TimeKeyColumn, TimeRangeKeyColumn, float64ColumnFromArray, stringColumnFromArray, withColumnAppended, withColumnsRenamed, withColumnsSelected, withKeyColumn, withRowRange, withRowSelection, } from '../columnar/index.js';
 import { SeriesStore } from '../live/series-store.js';
 import { parseDuration } from '../core/duration.js';
 import { resolveReducer, bucketStateFor, rollingStateFor, } from '../reducers/index.js';
@@ -871,6 +872,10 @@ export class TimeSeries {
     }
     /** Example: `series.rows`. Returns the normalized row view of the series. */
     get rows() {
+        // `toRows` returns runtime-normalized rows (Time/Interval keys, `undefined`
+        // for missing cells); the double cast is the existing trust point — the
+        // `RowForSchema`→`NormalizedRowForSchema` conditional types no longer overlap
+        // structurally for a direct cast now that both honor `required: false`.
         return toRows(this.schema, this.events);
     }
     /** Example: `series.toRows()`. Returns normalized row arrays using `Time`/`TimeRange`/`Interval` keys and `undefined` for missing payload values. */
@@ -1390,8 +1395,11 @@ export class TimeSeries {
      *   source (cumulative distance / work) yields contiguous ranges (per-km
      *   splits, elevation-vs-distance profile); a non-monotonic source (power)
      *   yields a histogram (distribution).
-     * - `{ edges }` — explicit ascending edges `[e₀ … eₙ]` → `n` bins, bin `i` =
-     *   `[eᵢ, eᵢ₊₁)` (e.g. FTP / Coggan power zones). Always emits all `n` bins.
+     * - `{ edges, inclusive? }` — explicit ascending edges `[e₀ … eₙ]` → `n` bins.
+     *   `inclusive` defaults to `'[)'` (bin `i` = `[eᵢ, eᵢ₊₁)`, lower-inclusive);
+     *   pass `'(]'` for upper-inclusive bins (`(eᵢ, eᵢ₊₁]`) — Coggan power / HR
+     *   zones, where a sample exactly on a zone's top edge belongs to the lower
+     *   zone (the first edge becomes an exclusive floor). Always emits all `n` bins.
      *
      * A row whose bin value is missing / non-finite (or, for `edges`, outside
      * `[e₀, eₙ)`) contributes to no bin. The reducer non-finite policy still
@@ -1403,6 +1411,35 @@ export class TimeSeries {
         const columnSpecs = normalizeAggregateColumns(this.schema, mapping);
         return computeByColumn(this.#store.store, col, spec, columnSpecs);
     }
+    /**
+     * Example:
+     * `series.rollingByColumn('cumDist', { radius: 120 }, { lo: { from: 'speed', using: 'p5' }, hi: { from: 'speed', using: 'p95' } })`.
+     *
+     * **Windowed value-axis aggregation — the sliding-window sibling of
+     * `byColumn`.** Where `byColumn` collapses rows into disjoint value-bins (the
+     * value-axis analogue of `aggregate`), `rollingByColumn` slides a **centered
+     * window** along a value axis and reduces the window at every row (the
+     * value-axis analogue of `rolling`). For each row it reduces the rows whose
+     * `col` value lies within `±radius` of that row's value, and returns **one
+     * record per row, positionally aligned with the series** (`out[i]` is the
+     * window centered at row `i`) — *not* a `TimeSeries`, and with no `start`/`end`
+     * range (the caller already has the axis column to zip against).
+     *
+     * `col` must be a **non-decreasing** numeric column — the ordering is what
+     * makes a sliding window meaningful (vs `byColumn`'s order-free group-by) and
+     * is enforced (a descending step throws). A row whose `col` value is missing /
+     * non-finite is excluded from every window and its own slot gets each
+     * reducer's empty snapshot, so the result stays positionally aligned. The
+     * reducer non-finite policy still applies to the *source* columns.
+     *
+     * The window is centered and inclusive (`col[i] − radius ≤ col[j] ≤ col[i] +
+     * radius`); a single O(n) two-pointer sweep maintains the window. See
+     * `docs/notes/rolling-by-column.md`.
+     */
+    rollingByColumn(col, spec, mapping) {
+        const columnSpecs = normalizeAggregateColumns(this.schema, mapping);
+        return computeRollingByColumn(this.#store.store, col, spec, columnSpecs);
+    }
     groupBy(column, transform) {
         const buckets = new Map();
         for (const event of this.events) {
@@ -2720,6 +2757,47 @@ export class TimeSeries {
         const reshaped = withColumnsRenamed(this.#store.store, mapping);
         return TimeSeries.#fromTrustedStore(this.name, resultSchema, reshaped);
     }
+    /**
+     * Example:
+     * `series.withColumn('cumDist', cumulativeDistances)` (a `Float64Array`).
+     *
+     * **Attach a computed numeric column.** Returns a new series with `values`
+     * appended as a new `number` column named `name`, so downstream pond ops
+     * (`aggregate`, `byColumn`, `rollingByColumn`, `column(name)`) can reference
+     * it. The existing key + value columns are shared by reference (zero-copy);
+     * only the new column is added. This is the seam that lets a derived array
+     * (cumulative distance, speed, gradient) re-enter the pond pipeline as a real
+     * column instead of staying a side-channel.
+     *
+     * `values` is a `Float64Array` (dense) or a `(number | undefined)[]` (where
+     * `undefined` marks a missing cell), and must have exactly `series.length`
+     * entries. Defined values are validated against the numeric intake contract —
+     * **non-finite (`NaN` / `±Infinity`) is rejected** (a `ValidationError`,
+     * matching construction), so packed numeric columns stay NaN-free; pass
+     * `undefined` for a missing cell, never `NaN`. `name` must not collide with an
+     * existing column.
+     *
+     * This is the *validated* attach. A trusted bulk-construction path
+     * (`fromTrustedColumns`, skipping the finite scan) is a deferred sibling for
+     * when a perf-critical consumer earns it.
+     */
+    withColumn(name, values) {
+        if (values.length !== this.length) {
+            throw new RangeError(`withColumn: values length ${values.length} does not match series length ${this.length}`);
+        }
+        // Re-assert the numeric intake contract (finite-or-missing) — trusted
+        // construction below bypasses the constructor's strict intake, so a
+        // non-finite cell would otherwise pack into the column and break the
+        // reducer non-finite policy's NaN-free invariant.
+        assertColumnValuesMatchKind('number', values, `withColumn '${String(name)}'`);
+        const column = columnFromValuesByKind('number', values);
+        const reshaped = withColumnAppended(this.#store.store, name, column);
+        const resultSchema = Object.freeze([
+            ...this.schema,
+            { name, kind: 'number' },
+        ]);
+        return TimeSeries.#fromTrustedStore(this.name, resultSchema, reshaped);
+    }
     collapse(keys, output, reducer, options) {
         // Column-native (Step 4): the reducer runs over the keyed columns read
         // straight off the store in the extracted `collapseOp` — no

package/dist/reducers/index.js

@@ -33,6 +33,11 @@ export function resolveReducer(operation) {
     const r = registry[operation];
     if (r)
         return r;
+    // `'mean'` is an accepted alias for `'avg'` in aggregate/rolling mappings,
+    // matching the column API (`Float64Column.mean()` → the `'avg'` kernel). Keeps
+    // the registry free of a duplicate entry. (estela F-reducer-naming.)
+    if (operation === 'mean')
+        return avg;
     const q = parsePercentile(operation);
     if (q !== undefined)
         return percentileReducer(q);

package/dist/schema/aggregate.d.ts

@@ -1,5 +1,5 @@
 import type { AppendColumn, ArrayColumnNameForSchema, ColumnDef, ColumnValue, OptionalizeColumns, ReplaceColumnKind, ScalarKind, SeriesSchema, ValueColumn, ValueColumnsForSchema } from './series.js';
-export type AggregateFunction = 'sum' | 'avg' | 'min' | 'max' | 'count' | 'first' | 'last' | 'median' | 'stdev' | 'difference' | 'keep' | 'unique' | 'samples' | `p${number}` | `top${number}`;
+export type AggregateFunction = 'sum' | 'avg' | 'mean' | 'min' | 'max' | 'count' | 'first' | 'last' | 'median' | 'stdev' | 'difference' | 'keep' | 'unique' | 'samples' | `p${number}` | `top${number}`;
 /**
  * Custom aggregate reducers receive every value in a bucket (including
  * `undefined`) and return a single result. The return type is widened to
@@ -152,7 +152,7 @@ type UnifiedOutputKind<Columns extends readonly ValueColumn[], K extends string,
  * reducer function (or otherwise unrecognized) — the spec branch passes
  * `ScalarKind`, the shorthand branch passes the source column's kind.
  */
-type ReducerOutputKind<Columns extends readonly ValueColumn[], From extends string, Using, Fallback extends ScalarKind> = Using extends 'sum' | 'avg' | 'count' | 'min' | 'max' | 'median' | 'stdev' | 'difference' | `p${number}` ? 'number' : Using extends 'unique' | 'samples' | `top${number}` ? 'array' : Using extends 'first' | 'last' | 'keep' ? From extends Columns[number]['name'] ? ColumnKindByName<Columns, From> : ScalarKind : Fallback;
+type ReducerOutputKind<Columns extends readonly ValueColumn[], From extends string, Using, Fallback extends ScalarKind> = Using extends 'sum' | 'avg' | 'mean' | 'count' | 'min' | 'max' | 'median' | 'stdev' | 'difference' | `p${number}` ? 'number' : Using extends 'unique' | 'samples' | `top${number}` ? 'array' : Using extends 'first' | 'last' | 'keep' ? From extends Columns[number]['name'] ? ColumnKindByName<Columns, From> : ScalarKind : Fallback;
 /**
  * Union of typed `ColumnDef`s — one per **output key** in the mapping
  * (not per source column). Used as the `...Rest` of the schema tuple;
@@ -209,7 +209,7 @@ export type AggregateOutputMapResultSchema<S extends SeriesSchema, Mapping> = Ag
  * Aggregate functions that always produce a numeric result regardless of
  * source column kind. Matches the reducer registry's `outputKind: 'number'`.
  */
-type NumericAggregateFunction = 'sum' | 'avg' | 'count' | 'min' | 'max' | 'median' | 'stdev' | 'difference' | `p${number}`;
+type NumericAggregateFunction = 'sum' | 'avg' | 'mean' | 'count' | 'min' | 'max' | 'median' | 'stdev' | 'difference' | `p${number}`;
 /**
  * Output column kind for `arrayAggregate(col, reducer, { kind? })`.
  * Numeric reducers → `'number'`, `'unique'` → `'array'`, `'first'`/`'last'`/

package/dist/schema/events.d.ts

@@ -20,7 +20,9 @@ export type TimeSeriesInput<S extends SeriesSchema> = {
     sort?: boolean;
 };
 export type NormalizedRowForSchema<S extends readonly ColumnDef<string, string>[]> = {
-    [I in keyof S]: S[I] extends ColumnDef<any, infer K> ? NormalizedValueForKind<K> : never;
+    [I in keyof S]: S[I] extends ColumnDef<any, infer K> ? I extends '0' ? NormalizedValueForKind<K> : S[I] extends {
+        required: false;
+    } ? NormalizedValueForKind<K> | undefined : NormalizedValueForKind<K> : never;
 };
 type DataValueForColumn<C extends ColumnDef<string, string>> = C extends ColumnDef<any, infer K> ? C['required'] extends false ? NormalizedValueForKind<K> | undefined : NormalizedValueForKind<K> : never;
 type NormalizedDataValueForColumn<C extends ColumnDef<string, string>> = C extends ColumnDef<any, infer K> ? K extends FirstColKind ? EventKeyForKind<K> : C['required'] extends false ? NormalizedValueForKind<K> | undefined : NormalizedValueForKind<K> : never;

package/dist/schema/reduce.d.ts

@@ -73,7 +73,7 @@ export type ReduceResult<S extends SeriesSchema, Mapping> = {
  * and shorthand branches. `From` is the spec's `from` or the shorthand
  * key; `Using` is the reducer.
  */
-type ReduceValueForReducer<S extends SeriesSchema, From extends string, Using> = Using extends 'sum' | 'avg' | 'count' | 'min' | 'max' | 'median' | 'stdev' | 'difference' | `p${number}` ? number | undefined : Using extends 'unique' | 'samples' | `top${number}` ? From extends ValueColumnsForSchema<S>[number]['name'] ? ColumnByName<S, From>['kind'] extends 'number' ? ReadonlyArray<number> | undefined : ColumnByName<S, From>['kind'] extends 'string' ? ReadonlyArray<string> | undefined : ColumnByName<S, From>['kind'] extends 'boolean' ? ReadonlyArray<boolean> | undefined : ReadonlyArray<string | number | boolean> | undefined : ReadonlyArray<string | number | boolean> | undefined : Using extends 'first' | 'last' | 'keep' ? From extends ValueColumnsForSchema<S>[number]['name'] ? ColumnByName<S, From>['kind'] extends 'number' ? number | undefined : ColumnByName<S, From>['kind'] extends 'string' ? string | undefined : ColumnByName<S, From>['kind'] extends 'boolean' ? boolean | undefined : ColumnValue | undefined : ColumnValue | undefined : ColumnValue | undefined;
+type ReduceValueForReducer<S extends SeriesSchema, From extends string, Using> = Using extends 'sum' | 'avg' | 'mean' | 'count' | 'min' | 'max' | 'median' | 'stdev' | 'difference' | `p${number}` ? number | undefined : Using extends 'unique' | 'samples' | `top${number}` ? From extends ValueColumnsForSchema<S>[number]['name'] ? ColumnByName<S, From>['kind'] extends 'number' ? ReadonlyArray<number> | undefined : ColumnByName<S, From>['kind'] extends 'string' ? ReadonlyArray<string> | undefined : ColumnByName<S, From>['kind'] extends 'boolean' ? ReadonlyArray<boolean> | undefined : ReadonlyArray<string | number | boolean> | undefined : ReadonlyArray<string | number | boolean> | undefined : Using extends 'first' | 'last' | 'keep' ? From extends ValueColumnsForSchema<S>[number]['name'] ? ColumnByName<S, From>['kind'] extends 'number' ? number | undefined : ColumnByName<S, From>['kind'] extends 'string' ? string | undefined : ColumnByName<S, From>['kind'] extends 'boolean' ? boolean | undefined : ColumnValue | undefined : ColumnValue | undefined : ColumnValue | undefined;
 /**
  * Value type for an explicit `kind` on a reduce spec. Mirrors
  * `NormalizedValueForKind` but stays inline here for the same TS2394

package/dist/schema/rolling.d.ts

@@ -90,7 +90,7 @@ type FusedColumnKind<S extends SeriesSchema, Key extends string, Value> = Value
  * Reducer-string-to-output-kind dispatch, shared by both AggregateMap
  * and AggregateOutputMap entry shapes.
  */
-type FusedReducerKind<S extends SeriesSchema, From extends string, Using> = Using extends 'sum' | 'avg' | 'count' | 'min' | 'max' | 'median' | 'stdev' | 'difference' | `p${number}` ? 'number' : Using extends 'unique' | 'samples' | `top${number}` ? 'array' : Using extends 'first' | 'last' | 'keep' ? FromColumnKind<S, From> : ScalarKind;
+type FusedReducerKind<S extends SeriesSchema, From extends string, Using> = Using extends 'sum' | 'avg' | 'mean' | 'count' | 'min' | 'max' | 'median' | 'stdev' | 'difference' | `p${number}` ? 'number' : Using extends 'unique' | 'samples' | `top${number}` ? 'array' : Using extends 'first' | 'last' | 'keep' ? FromColumnKind<S, From> : ScalarKind;
 /**
  * Look up the kind of a value column by name. Used by source-
  * preserving reducers (`first` / `last` / `keep`) where the output

package/dist/schema/series.d.ts

@@ -22,6 +22,14 @@ export type ColumnDef<Name extends string, Kind extends string> = {
     kind: Kind;
     required?: boolean;
 };
+/**
+ * The key (first) column of a schema. Its **name must equal its kind** —
+ * `time` / `timeRange` / `interval`. So `{ name: 'time', kind: 'time' }` is the
+ * only valid time key; `{ name: 'at', kind: 'time' }` does **not** typecheck
+ * (the error surfaces as a name/literal-type mismatch, e.g. `'"at"' is not
+ * assignable to '"time"'` — read it as "the key column must be named for its
+ * kind", not as a value error). Value columns, by contrast, take any name.
+ */
 export type FirstColumn = ColumnDef<'time', 'time'> | ColumnDef<'interval', 'interval'> | ColumnDef<'timeRange', 'timeRange'>;
 export type ValueColumn<Name extends string = string> = ColumnDef<Name, ScalarKind>;
 export type SeriesSchema = readonly [FirstColumn, ...ValueColumn[]];
@@ -32,8 +40,18 @@ export type ValueColumnsForSchema<S extends SeriesSchema> = S extends readonly [
 export type ValueForKind<K extends string> = K extends 'time' ? TimestampInput | Time : K extends 'interval' ? IntervalInput | Interval : K extends 'timeRange' ? TimeRangeInput | TimeRange : K extends 'number' ? number : K extends 'string' ? string : K extends 'boolean' ? boolean : K extends 'array' ? ArrayValue : never;
 export type NormalizedValueForKind<K extends string> = K extends 'time' ? Time : K extends 'timeRange' ? TimeRange : K extends 'interval' ? Interval : K extends 'number' ? number : K extends 'string' ? string : K extends 'boolean' ? boolean : K extends 'array' ? ArrayValue : never;
 export type KindForValue<V extends ScalarValue> = V extends number ? 'number' : V extends string ? 'string' : 'boolean';
+/**
+ * Tuple-row input type for a schema. A column declared `required: false`
+ * accepts `undefined` in its cell (a missing value — the constructor records
+ * it in the validity bitmap), matching the runtime's intake. `null` is **not**
+ * admitted: the tuple-row constructor rejects it (only the JSON object-row path
+ * accepts `null`), so the type stays honest to what intake actually takes —
+ * pass `undefined` for a missing tuple cell. (estela F-geo-row-optional.)
+ */
 export type RowForSchema<S extends readonly ColumnDef<string, string>[]> = {
-    [I in keyof S]: S[I] extends ColumnDef<any, infer K> ? ValueForKind<K> : never;
+    [I in keyof S]: S[I] extends ColumnDef<any, infer K> ? I extends '0' ? ValueForKind<K> : S[I] extends {
+        required: false;
+    } ? ValueForKind<K> | undefined : ValueForKind<K> : never;
 };
 export type NumericColumnNameForSchema<S extends SeriesSchema> = Extract<ValueColumnsForSchema<S>[number], ColumnDef<string, 'number'>>['name'];
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pond-ts",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "TypeScript-first time series primitives",
   "license": "MIT",
   "repository": {