pond-ts 0.28.0 → 0.30.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.28.0...HEAD
+[Unreleased]: https://github.com/pjm17971/pond-ts/compare/v0.30.0...HEAD
+[0.30.0]: https://github.com/pjm17971/pond-ts/compare/v0.29.0...v0.30.0
+[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
@@ -20,7 +22,65 @@ type-level changes; patch bumps are strictly additive.
 [0.19.0]: https://github.com/pjm17971/pond-ts/compare/v0.18.0...v0.19.0
 [0.18.0]: https://github.com/pjm17971/pond-ts/compare/v0.17.1...v0.18.0
 
-## [Unreleased]
+## [0.30.0] — 2026-06-17
+
+### Added
+
+- **`rollingByColumn(col, { radius, at }, mapping)` — evaluate at explicit
+  centers.** `at` takes a **non-decreasing** array of center values (e.g. a chart's
+  coarse display grid) and returns **one record per center**, instead of the
+  default one-per-row. A center with no rows within `±radius` yields each
+  reducer's empty value. Same O(n + centers) two-pointer. Closes the
+  evaluate-at-grid gap surfaced adopting `rollingByColumn` for a chart variance
+  band. (estela F-rolling-by-row.)
+- **`smooth(col, 'movingAverage' | 'loess', { …, missing: 'skip' })` —
+  validity-respecting smoothing.** By default (`missing: 'bridge'`) a cell whose
+  own value is missing is still assigned a smoothed value from its present
+  neighbours — the line is drawn _across_ the hole. `missing: 'skip'` keeps a
+  missing cell **missing** in the output, so a sustained dropout (a coast, a
+  sensor gap) is preserved as a break rather than fabricated through. Present
+  cells smooth over only the present values in their window either way. `ema`
+  takes no `missing` option (it is causal and never fabricates across a gap). A
+  `maxGap` hard segment boundary is a deferred follow-on. (estela
+  F-smooth-interactive.)
+
+### Changed
+
+- **`byColumn(…, { inclusive: '(]' })` floor edge is now inclusive.** Under
+  `'(]'`, interior bins stay upper-inclusive (`(eᵢ, eᵢ₊₁]`) but the **floor `e₀`
+  is inclusive** (bin 0 is `[e₀, e₁]`), so a value at exactly the minimum edge —
+  e.g. a `0` W coast/stop sample at a zone floor of 0 — lands in bin 0 instead of
+  being dropped (the `include_lowest` convention). Previously the floor was
+  exclusive. (estela F-inclusive-floor.)
+
+## [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
 

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,49 @@ 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ₙ)`. `'(]'`: interior 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. The **floor `e₀` is inclusive** (bin 0 is `[e₀, e₁]`), so a value at
+        // exactly the minimum edge — e.g. a `0` W coast/stop sample — lands in bin 0
+        // rather than being dropped (the `include_lowest` convention; estela
+        // F-inclusive-floor). Range is `[e₀, eₙ]`.
+        binOf =
+            spec.inclusive === '(]'
+                ? (v) => {
+                    if (v < edges[0] || v > edges[last])
+                        return NaN; // out of [e₀, eₙ]
+                    // rightmost edge STRICTLY less than v (so an interior edge goes to
+                    // the bin below), clamped to [0, last); v === e₀ → bin 0 (floor
+                    // inclusive).
+                    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/rolling-by-column.d.ts

@@ -3,12 +3,19 @@ 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
+ * half-width `radius`, in the axis column's own units.
+ *
+ * By default a window is evaluated at **every input row** (one record per row).
+ * Pass `at` — a **non-decreasing** array of explicit center values (e.g. a chart's
+ * coarse display grid) — to evaluate at those centers instead, returning one
+ * record per center. Each center's window is the rows whose axis value lies
+ * within `±radius` of it; a center need not coincide with any row, and a center
+ * with no rows in range yields each reducer's empty value. See
  * `docs/notes/rolling-by-column.md`.
  */
 export type WindowSpec = {
     radius: number;
+    at?: readonly number[];
 };
 /** One windowed record: the mapped aggregates over the window centered at a row. */
 export type WindowRecord = Record<string, ColumnValue | undefined>;

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

@@ -55,6 +55,50 @@ export function computeRollingByColumn(store, axisColName, spec, columnSpecs) {
     // 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;
+    // `at` mode (estela F-rolling-by-row): evaluate at explicit ascending centers
+    // (e.g. a chart's display grid) rather than at every input row. One record per
+    // center; the two-pointer sweeps the same shared states across the centers, so
+    // it stays O(n + at.length). A center with no rows in `±radius` empties the
+    // window and yields each reducer's empty value.
+    if (spec.at !== undefined) {
+        const at = spec.at;
+        for (let k = 0; k < at.length; k += 1) {
+            if (!Number.isFinite(at[k])) {
+                throw new RangeError(`rollingByColumn: at[${k}] is not finite`);
+            }
+            if (k > 0 && at[k] < at[k - 1]) {
+                throw new RangeError('rollingByColumn: at centers must be non-decreasing');
+            }
+        }
+        const atOut = new Array(at.length);
+        let alo = 0;
+        let ahi = 0; // window holds compact positions [alo, ahi)
+        for (let k = 0; k < at.length; k += 1) {
+            const c = at[k];
+            const wlo = c - radius;
+            const whi = c + radius;
+            while (ahi < m && ax[ahi] <= whi) {
+                const r = idx[ahi];
+                for (let cc = 0; cc < specCount; cc += 1) {
+                    states[cc].add(r, sourceCols[cc].read(r));
+                }
+                ahi += 1;
+            }
+            while (alo < ahi && ax[alo] < wlo) {
+                const r = idx[alo];
+                for (let cc = 0; cc < specCount; cc += 1) {
+                    states[cc].remove(r, sourceCols[cc].read(r));
+                }
+                alo += 1;
+            }
+            const rec = {};
+            for (let cc = 0; cc < specCount; cc += 1) {
+                rec[columnSpecs[cc].output] = states[cc].snapshot();
+            }
+            atOut[k] = rec;
+        }
+        return atOut;
+    }
     const out = new Array(n);
     let lo = 0;
     let hi = 0; // the window currently holds compact positions [lo, hi)

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

@@ -539,8 +539,13 @@ 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 interior bins (`(eᵢ, eᵢ₊₁]`) — Coggan power
+     *   / HR zones, where a sample exactly on a zone's top edge belongs to the
+     *   lower zone. The floor `e₀` stays **inclusive** (bin 0 is `[e₀, e₁]`), so a
+     *   minimum-edge value (e.g. a `0` W coast sample) lands in bin 0 rather than
+     *   being dropped. 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
@@ -574,7 +579,12 @@ export declare class TimeSeries<S extends SeriesSchema> {
      * 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
+     * radius`); a single O(n) two-pointer sweep maintains the window.
+     *
+     * Pass `{ radius, at }` — a **non-decreasing** array of explicit center values
+     * (e.g. a chart's coarse display grid) — to evaluate at those centers instead
+     * of at every row, returning **one record per center** (a center with no rows
+     * in range yields each reducer's empty value). 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>>;
@@ -995,6 +1005,17 @@ export declare class TimeSeries<S extends SeriesSchema> {
      * When `output` is omitted, the smoothed values replace the target column. When `output` is
      * supplied, the smoothed values are appended as a new optional numeric column.
      *
+     * **Missing cells** (`movingAverage` / `loess`): by default (`missing:
+     * 'bridge'`) a cell whose own value is missing is still assigned a smoothed
+     * value computed from its present neighbours — i.e. the line is drawn *across*
+     * the hole. Pass `missing: 'skip'` to keep a missing cell **missing** in the
+     * output, so a sustained dropout (a coast, a sensor gap) is preserved as a
+     * break rather than fabricated through. Present cells already smooth over only
+     * the present values in their window either way. `ema` is causal and never
+     * fabricates across a gap, so it takes no `missing` option. (estela
+     * F-smooth-interactive; a `maxGap` hard segment boundary is a deferred
+     * follow-on.)
+     *
      * **Multi-entity series:** the smoothing window pulls values from
      * every entity into each smoothed point — `host-A`'s smoothed value
      * is blended with `host-B`'s and `host-C`'s. On a series carrying
@@ -1010,9 +1031,11 @@ export declare class TimeSeries<S extends SeriesSchema> {
         window: DurationInput;
         alignment?: RollingAlignment;
         output?: Output;
+        missing?: 'skip' | 'bridge';
     } | {
         span: number;
         output?: Output;
+        missing?: 'skip' | 'bridge';
     }): TimeSeries<Output extends string ? SmoothAppendSchema<S, Output> : SmoothSchema<S, Target>>;
     /** Example: `series.slice(0, 10)`. Returns a positional half-open slice of the series. */
     slice(beginIndex?: number, endIndex?: number): TimeSeries<S>;

package/dist/batch/time-series.js

@@ -872,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. */
@@ -1391,8 +1395,13 @@ 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 interior bins (`(eᵢ, eᵢ₊₁]`) — Coggan power
+     *   / HR zones, where a sample exactly on a zone's top edge belongs to the
+     *   lower zone. The floor `e₀` stays **inclusive** (bin 0 is `[e₀, e₁]`), so a
+     *   minimum-edge value (e.g. a `0` W coast sample) lands in bin 0 rather than
+     *   being dropped. 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
@@ -1426,7 +1435,12 @@ export class TimeSeries {
      * 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
+     * radius`); a single O(n) two-pointer sweep maintains the window.
+     *
+     * Pass `{ radius, at }` — a **non-decreasing** array of explicit center values
+     * (e.g. a chart's coarse display grid) — to evaluate at those centers instead
+     * of at every row, returning **one record per center** (a center with no rows
+     * in range yields each reducer's empty value). See
      * `docs/notes/rolling-by-column.md`.
      */
     rollingByColumn(col, spec, mapping) {
@@ -2204,6 +2218,17 @@ export class TimeSeries {
      * When `output` is omitted, the smoothed values replace the target column. When `output` is
      * supplied, the smoothed values are appended as a new optional numeric column.
      *
+     * **Missing cells** (`movingAverage` / `loess`): by default (`missing:
+     * 'bridge'`) a cell whose own value is missing is still assigned a smoothed
+     * value computed from its present neighbours — i.e. the line is drawn *across*
+     * the hole. Pass `missing: 'skip'` to keep a missing cell **missing** in the
+     * output, so a sustained dropout (a coast, a sensor gap) is preserved as a
+     * break rather than fabricated through. Present cells already smooth over only
+     * the present values in their window either way. `ema` is causal and never
+     * fabricates across a gap, so it takes no `missing` option. (estela
+     * F-smooth-interactive; a `maxGap` hard segment boundary is a deferred
+     * follow-on.)
+     *
      * **Multi-entity series:** the smoothing window pulls values from
      * every entity into each smoothed point — `host-A`'s smoothed value
      * is blended with `host-B`'s and `host-C`'s. On a series carrying
@@ -2290,8 +2315,14 @@ export class TimeSeries {
                     loessValues.push(value);
                 }
             }
+            // `missing: 'skip'` — a cell whose own value is missing stays missing
+            // (don't fit a fabricated value across the hole from its present
+            // neighbours). Default `'bridge'` is the prior behaviour (fit everywhere).
+            const skipMissing = options.missing === 'skip';
             const resultRows = this.events.map((event, index) => {
-                const smoothed = loessAt(anchors[index], loessAnchors, loessValues, span);
+                const smoothed = skipMissing && sourceValues[index] === undefined
+                    ? undefined
+                    : loessAt(anchors[index], loessAnchors, loessValues, span);
                 const nextEvent = output === undefined
                     ? event.set(column, smoothed)
                     : event.merge({ [output]: smoothed });
@@ -2314,6 +2345,7 @@ export class TimeSeries {
         const window = options.window;
         const windowMs = parseDuration(window);
         const alignment = options.alignment ?? 'trailing';
+        const skipMissing = options.missing === 'skip';
         const resultValues = new Array(this.events.length);
         let windowStart = 0;
         let windowEnd = 0;
@@ -2380,7 +2412,12 @@ export class TimeSeries {
             }
             const smoothed = snapshot();
             for (let index = groupStart; index < groupEnd; index++) {
-                resultValues[index] = smoothed;
+                // `missing: 'skip'` — a cell whose own value is missing stays missing
+                // (don't fabricate it from the window average). Default `'bridge'` fills.
+                resultValues[index] =
+                    skipMissing && sourceValues[index] === undefined
+                        ? undefined
+                        : smoothed;
             }
             groupStart = groupEnd;
         }

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.28.0",
+  "version": "0.30.0",
   "description": "TypeScript-first time series primitives",
   "license": "MIT",
   "repository": {