pond-ts 0.29.0 → 0.31.0

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

@@ -1,5 +1,7 @@
 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 { RenameSchema, RollingAlignment, RollingSchema, ColumnValue, DedupeKeep, DiffSchema, FillMapping, FillStrategy, ScalarKind, ScalarValue, SmoothMethod, SmoothAppendSchema, SmoothSchema, SelectSchema, SeriesSchema, TimeKeyedSchema, TimeSeriesJsonInput, TimeSeriesInput, TimeRangeKeyedSchema, ValueColumnKindForName, ValueColumnNameForSchema, ValueColumnsForSchema, ValueKeyedSchema } from '../schema/index.js';
+import { type ScanStep } from './operators/scan.js';
+import { ValueSeries } from './value-series.js';
 import { type BinSpec } from './by-column.js';
 import { type WindowSpec } from './rolling-by-column.js';
 import { BoundedSequence } from '../sequence/bounded-sequence.js';
@@ -521,6 +523,29 @@ export declare class TimeSeries<S extends SeriesSchema> {
      */
     reduce(column: ValueColumnsForSchema<S>[number]['name'], reducer: AggregateReducer): ColumnValue | undefined;
     reduce<const Mapping extends ValidatedAggregateMap<S, Mapping>>(mapping: Mapping): ReduceResult<S, Mapping>;
+    /**
+     * Example: `track.byValue('cumDist')`.
+     *
+     * **The raw `TimeSeries → ValueSeries` projection** (RFC `value-axis.md` §6):
+     * re-key the series onto a monotonic numeric **value axis** (distance,
+     * cumulative work, …), returning a {@link ValueSeries} that carries the
+     * ordering-based operators (axis read, nearest-by-value, slice-by-value) over
+     * that axis instead of time.
+     *
+     * `axis` must be **defined, finite, and non-decreasing at every row** — it
+     * becomes the index, so (unlike a value column) it cannot have gaps; an
+     * `assertMonotonicAxis` check throws otherwise. This monotonicity contract
+     * lives on the *projection*, not on {@link TimeSeries.byColumn} (whose
+     * order-free binning has no such precondition). The re-key is a no-op reindex
+     * (the rows already sit in axis order) and the axis column is **dropped from
+     * the value columns** (it is now the key); the other columns are shared
+     * zero-copy.
+     *
+     * `byValue` is the projection; `byColumn` is value-axis *aggregation* — pair
+     * them via {@link TimeSeries.scan} for stateful splits
+     * (`split = scan + byColumn`).
+     */
+    byValue<const Axis extends NumericColumnNameForSchema<S>>(axis: Axis): Axis extends Axis ? ValueSeries<ValueKeyedSchema<S, Axis>> : never;
     /**
      * Example:
      * `series.byColumn('cumDist', { width: 1000 }, { gain: { from: 'ele', using: 'sum' } })`.
@@ -541,9 +566,11 @@ export declare class TimeSeries<S extends SeriesSchema> {
      *   yields a histogram (distribution).
      * - `{ 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.
+     *   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
@@ -577,7 +604,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>>;
@@ -785,6 +817,56 @@ export declare class TimeSeries<S extends SeriesSchema> {
     cumulative<const Targets extends NumericColumnNameForSchema<S>>(spec: {
         [K in Targets]: 'sum' | 'max' | 'min' | 'count' | ((acc: number, value: number) => number);
     }): TimeSeries<DiffSchema<S, Targets>>;
+    /**
+     * Example:
+     * ```ts
+     * // running sum — the cumulative special case, replacing in place:
+     * series.scan('work', (acc, v) => [acc + v, acc + v], 0);
+     *
+     * // typed accumulator into a NEW column (hysteresis elevation gain):
+     * track.scan<'cumGain', { ref: number | null; gain: number }>(
+     *   'ele',
+     *   (acc, ele) => {
+     *     if (acc.ref === null) return [{ ref: ele, gain: 0 }, 0];
+     *     const d = ele - acc.ref;
+     *     if (d >= 3) return [{ ref: ele, gain: acc.gain + d }, acc.gain + d];
+     *     if (d <= -3) return [{ ref: ele, gain: acc.gain }, acc.gain];
+     *     return [acc, acc.gain]; // within deadband — carry
+     *   },
+     *   { ref: null, gain: 0 },
+     *   { output: 'cumGain' },
+     * );
+     * ```
+     *
+     * **Typed-accumulator running fold** (the classic `mapAccumL`) over a numeric
+     * column. `step(acc, value, i)` returns `[nextAcc, output]`; the accumulator
+     * `A` (inferred from `init`) is **decoupled** from the numeric `output` — the
+     * generalization {@link TimeSeries.cumulative} can't express, since there the
+     * accumulator *is* the output *is* a `number`. `cumulative` is the scalar
+     * special case: `series.cumulative({ x: 'sum' })` is
+     * `series.scan('x', (a, v) => [a + v, a + v], 0)`.
+     *
+     * With no `options.output` the source column is **replaced** in place (widened
+     * to optional `number`, as `cumulative` does). With `options.output` a **new**
+     * column of that name is appended and the source is left intact (as
+     * {@link TimeSeries.withColumn} does); the name must not already exist.
+     *
+     * **Missing cells carry:** a missing / undefined source cell does not call
+     * `step` — the accumulator is held and the row re-emits the last output (so it
+     * holds flat across a gap), `undefined` only until the first defined value. A
+     * stored `NaN` is a defined number and is passed to `step`; the step author
+     * owns output finiteness (this is the trusted-compute path, not the validated
+     * `withColumn` intake).
+     *
+     * **Multi-entity series:** the accumulator threads across all rows in storage
+     * order, so it interleaves across entities — `host-A`'s next row folds on top
+     * of `host-B`'s. Use `series.partitionBy(col).scan(...).collect()` to scope
+     * per entity. See {@link TimeSeries.partitionBy}.
+     */
+    scan<const Source extends NumericColumnNameForSchema<S>, A>(source: Source, step: ScanStep<A>, init: A): TimeSeries<DiffSchema<S, Source>>;
+    scan<const Source extends NumericColumnNameForSchema<S>, const Name extends string, A>(source: Source, step: ScanStep<A>, init: A, options: {
+        output: Name;
+    }): TimeSeries<AppendColumn<S, Name, 'number'>>;
     /**
      * Example: `series.shift("value", 1)`.
      * Lags column values by N events (positive N) or leads them (negative N).
@@ -998,6 +1080,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
@@ -1013,9 +1106,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>;
@@ -1069,6 +1164,20 @@ export declare class TimeSeries<S extends SeriesSchema> {
     atOrBefore(key: KeyLike): EventForSchema<S> | undefined;
     /** Example: `series.atOrAfter(new Time(Date.now()))`. Returns the event with the exact key or the nearest later event, if any. */
     atOrAfter(key: KeyLike): EventForSchema<S> | undefined;
+    /**
+     * Example: `series.nearest(new Time(Date.now()))`. Returns the event whose key
+     * is **closest** to `key` by `begin()` distance, or `undefined` only when the
+     * series is empty.
+     *
+     * Where `atOrBefore` / `atOrAfter` bound to one side, this rounds to the nearer
+     * neighbour (ties go to the earlier event). A key outside the series resolves
+     * to the first or last event — the nearest that exists — so callers that want
+     * "no match past the data" should range-check against {@link timeRange}.
+     *
+     * O(log N) via `bisect`; the columnar key buffer is probed by `begin()`, with
+     * no Event allocation beyond the single result.
+     */
+    nearest(key: KeyLike): EventForSchema<S> | undefined;
     /** Example: `series.timeRange()`. Returns the overall temporal extent of the series, if the series is not empty. */
     timeRange(): TimeRange | undefined;
     /** Example: `series.overlaps(range)`. Returns `true` when the overall series extent overlaps the supplied temporal value. */

package/dist/batch/time-series.js

@@ -1,5 +1,8 @@
 import { isAggregateOutputSpec, normalizeAggregateColumns, tryAggregateColumnarTimeKeyed, } from './aggregate-columns.js';
 import { cumulativeOp, } from './operators/cumulative.js';
+import { scanOp } from './operators/scan.js';
+import { byValueOp } from './operators/by-value.js';
+import { ValueSeries } from './value-series.js';
 import { diffRateOp } from './operators/diff-rate.js';
 import { fillOp } from './operators/fill.js';
 import { mapOp } from './operators/map.js';
@@ -1377,6 +1380,39 @@ export class TimeSeries {
         }
         return result;
     }
+    /**
+     * Example: `track.byValue('cumDist')`.
+     *
+     * **The raw `TimeSeries → ValueSeries` projection** (RFC `value-axis.md` §6):
+     * re-key the series onto a monotonic numeric **value axis** (distance,
+     * cumulative work, …), returning a {@link ValueSeries} that carries the
+     * ordering-based operators (axis read, nearest-by-value, slice-by-value) over
+     * that axis instead of time.
+     *
+     * `axis` must be **defined, finite, and non-decreasing at every row** — it
+     * becomes the index, so (unlike a value column) it cannot have gaps; an
+     * `assertMonotonicAxis` check throws otherwise. This monotonicity contract
+     * lives on the *projection*, not on {@link TimeSeries.byColumn} (whose
+     * order-free binning has no such precondition). The re-key is a no-op reindex
+     * (the rows already sit in axis order) and the axis column is **dropped from
+     * the value columns** (it is now the key); the other columns are shared
+     * zero-copy.
+     *
+     * `byValue` is the projection; `byColumn` is value-axis *aggregation* — pair
+     * them via {@link TimeSeries.scan} for stateful splits
+     * (`split = scan + byColumn`).
+     */
+    byValue(axis) {
+        // The return type is **distributive** over `Axis` (`Axis extends Axis ?`):
+        // for a literal axis it is just `ValueSeries<ValueKeyedSchema<S, Axis>>`,
+        // but for a union axis (e.g. a generic wrapper's `'cumDist' | 'hr'`) it
+        // becomes the discriminated union `ValueSeries<…cumDist> | ValueSeries<…hr>`
+        // — each branch drops only its own axis, so narrowing on `axisName` recovers
+        // the right `column()` names. Without distribution, `ValueKeyedSchema` would
+        // drop *every* union member from the value columns.
+        const { store, schema } = byValueOp(this.#store.store, this.schema, axis);
+        return ValueSeries.fromTrustedStore(this.name, schema, store);
+    }
     /**
      * Example:
      * `series.byColumn('cumDist', { width: 1000 }, { gain: { from: 'ele', using: 'sum' } })`.
@@ -1397,9 +1433,11 @@ export class TimeSeries {
      *   yields a histogram (distribution).
      * - `{ 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.
+     *   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
@@ -1433,7 +1471,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) {
@@ -1673,6 +1716,13 @@ export class TimeSeries {
         const { store, schema } = cumulativeOp(this.#store.store, this.schema, spec);
         return TimeSeries.#fromTrustedStore(this.name, schema, store);
     }
+    scan(source, step, init, options) {
+        // Column-native: the typed-accumulator fold runs straight off the store's
+        // source column in the extracted `scanOp` — no `this.events`
+        // materialization. The method is a thin delegate.
+        const { store, schema } = scanOp(this.#store.store, this.schema, source, step, init, options?.output);
+        return TimeSeries.#fromTrustedStore(this.name, schema, store);
+    }
     /**
      * Example: `series.shift("value", 1)`.
      * Lags column values by N events (positive N) or leads them (negative N).
@@ -2211,6 +2261,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
@@ -2297,8 +2358,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 });
@@ -2321,6 +2388,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;
@@ -2387,7 +2455,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;
         }
@@ -2573,6 +2646,34 @@ export class TimeSeries {
     atOrAfter(key) {
         return this.at(this.bisect(key));
     }
+    /**
+     * Example: `series.nearest(new Time(Date.now()))`. Returns the event whose key
+     * is **closest** to `key` by `begin()` distance, or `undefined` only when the
+     * series is empty.
+     *
+     * Where `atOrBefore` / `atOrAfter` bound to one side, this rounds to the nearer
+     * neighbour (ties go to the earlier event). A key outside the series resolves
+     * to the first or last event — the nearest that exists — so callers that want
+     * "no match past the data" should range-check against {@link timeRange}.
+     *
+     * O(log N) via `bisect`; the columnar key buffer is probed by `begin()`, with
+     * no Event allocation beyond the single result.
+     */
+    nearest(key) {
+        const n = this.#store.length;
+        if (n === 0)
+            return undefined;
+        const normalizedKey = toKey(key);
+        const index = this.bisect(normalizedKey); // first index with keyAt(i) >= key
+        if (index <= 0)
+            return this.at(0);
+        if (index >= n)
+            return this.at(n - 1);
+        const target = normalizedKey.begin();
+        const before = this.#store.keyAt(index - 1).begin();
+        const after = this.#store.keyAt(index).begin();
+        return this.at(target - before <= after - target ? index - 1 : index);
+    }
     /** Example: `series.timeRange()`. Returns the overall temporal extent of the series, if the series is not empty. */
     timeRange() {
         // Columnar key-axis read. The old implementation reduced over

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

@@ -0,0 +1,53 @@
+import { type Column as ColumnarColumn } from '../columnar/index.js';
+import type { ValueSeriesColumnName, ValueSeriesSchema } from '../schema/index.js';
+/**
+ * A **value-keyed series** — the closed value-axis counterpart of
+ * `TimeSeries`. Its key is a monotonic non-time axis (distance, cumulative
+ * work, …) rather than time, produced by `TimeSeries.byValue(axis)`.
+ *
+ * `ValueSeries` carries the **ordering-based** operators (read the axis, read
+ * value columns, nearest-by-value, slice-by-value) — the part of the series
+ * algebra that was never really about time (RFC `value-axis.md` §5). The
+ * calendar/clock operators (`Sequence.every`, tz formatting) are deliberately
+ * absent: a value axis has no wall-clock semantics, and the disjoint
+ * `ValueSeriesSchema` makes them type-impossible here.
+ *
+ * Minimal by design (RFC §7: adopt the type early, grow the algebra as a second
+ * value-axis consumer earns it). Wraps the columnar store directly — a value
+ * row is an `(axis, …values)` tuple, not a `Time`-keyed `Event`, so it does not
+ * go through the time-only `SeriesStore` / EventKey layer.
+ */
+export declare class ValueSeries<VS extends ValueSeriesSchema> {
+    #private;
+    readonly name: string;
+    readonly schema: VS;
+    private constructor();
+    /** Number of rows. */
+    get length(): number;
+    /** The axis (key) column's name — e.g. `'cumDist'`. */
+    get axisName(): VS[0]['name'];
+    /**
+     * The axis values (the x of every row), in axis order. **Zero-copy** — the
+     * returned `Float64Array` is the live key buffer; treat it as read-only.
+     */
+    axisValues(): Float64Array;
+    /** The axis value at row `i`. Throws if out of range. */
+    axisAt(i: number): number;
+    /** A value column by name, for direct columnar reads (`.read(i)`, `.values()`). */
+    column(name: ValueSeriesColumnName<VS>): ColumnarColumn | undefined;
+    /**
+     * Index of the row whose axis value is **closest** to `value` — the
+     * value-axis cursor primitive. The axis is non-decreasing, so this is a
+     * binary search. Returns `-1` for an empty series; clamps to the first / last
+     * row when `value` is outside the axis extent.
+     */
+    nearestIndex(value: number): number;
+    /**
+     * The contiguous sub-series whose axis value lies in `[lo, hi)` — the
+     * value-axis cull (pan / zoom on a value x). Binary-searches the bounds and
+     * zero-copy slices the store. `lo >= hi` (or a range outside the extent)
+     * yields an empty series.
+     */
+    sliceByValue(lo: number, hi: number): ValueSeries<VS>;
+}
+//# sourceMappingURL=value-series.d.ts.map

package/dist/batch/value-series.js

@@ -0,0 +1,105 @@
+import { withRowRange, } from '../columnar/index.js';
+/**
+ * A **value-keyed series** — the closed value-axis counterpart of
+ * `TimeSeries`. Its key is a monotonic non-time axis (distance, cumulative
+ * work, …) rather than time, produced by `TimeSeries.byValue(axis)`.
+ *
+ * `ValueSeries` carries the **ordering-based** operators (read the axis, read
+ * value columns, nearest-by-value, slice-by-value) — the part of the series
+ * algebra that was never really about time (RFC `value-axis.md` §5). The
+ * calendar/clock operators (`Sequence.every`, tz formatting) are deliberately
+ * absent: a value axis has no wall-clock semantics, and the disjoint
+ * `ValueSeriesSchema` makes them type-impossible here.
+ *
+ * Minimal by design (RFC §7: adopt the type early, grow the algebra as a second
+ * value-axis consumer earns it). Wraps the columnar store directly — a value
+ * row is an `(axis, …values)` tuple, not a `Time`-keyed `Event`, so it does not
+ * go through the time-only `SeriesStore` / EventKey layer.
+ */
+export class ValueSeries {
+    name;
+    schema;
+    #store;
+    /**
+     * @internal Trusted construction — `store` must be value-keyed and structurally
+     * match `schema` (the invariant `TimeSeries.byValue` / `byValueOp` establish).
+     * Not for general use; construct a `ValueSeries` via `TimeSeries.byValue`.
+     */
+    static fromTrustedStore(name, schema, store) {
+        return new ValueSeries(name, schema, store);
+    }
+    constructor(name, schema, store) {
+        this.name = name;
+        this.schema = Object.freeze(schema.slice());
+        this.#store = store;
+    }
+    /** Number of rows. */
+    get length() {
+        return this.#store.length;
+    }
+    /** The axis (key) column's name — e.g. `'cumDist'`. */
+    get axisName() {
+        return this.schema[0].name;
+    }
+    /**
+     * The axis values (the x of every row), in axis order. **Zero-copy** — the
+     * returned `Float64Array` is the live key buffer; treat it as read-only.
+     */
+    axisValues() {
+        return this.#store.keys.begin;
+    }
+    /** The axis value at row `i`. Throws if out of range. */
+    axisAt(i) {
+        return this.#store.keys.beginAt(i);
+    }
+    /** A value column by name, for direct columnar reads (`.read(i)`, `.values()`). */
+    column(name) {
+        return this.#store.columns.get(name);
+    }
+    /**
+     * Index of the row whose axis value is **closest** to `value` — the
+     * value-axis cursor primitive. The axis is non-decreasing, so this is a
+     * binary search. Returns `-1` for an empty series; clamps to the first / last
+     * row when `value` is outside the axis extent.
+     */
+    nearestIndex(value) {
+        const n = this.length;
+        if (n === 0)
+            return -1;
+        const ax = this.axisValues();
+        const lo = lowerBound(ax, n, value);
+        if (lo === 0)
+            return 0;
+        if (lo === n)
+            return n - 1;
+        return value - ax[lo - 1] <= ax[lo] - value ? lo - 1 : lo;
+    }
+    /**
+     * The contiguous sub-series whose axis value lies in `[lo, hi)` — the
+     * value-axis cull (pan / zoom on a value x). Binary-searches the bounds and
+     * zero-copy slices the store. `lo >= hi` (or a range outside the extent)
+     * yields an empty series.
+     */
+    sliceByValue(lo, hi) {
+        const ax = this.axisValues();
+        const n = this.length;
+        const loIdx = lowerBound(ax, n, lo);
+        const hiIdx = lowerBound(ax, n, hi);
+        const sliced = withRowRange(this.#store, loIdx, hiIdx);
+        return ValueSeries.fromTrustedStore(this.name, this.schema, sliced);
+    }
+}
+/** First index `i` in `ax[0..n)` with `ax[i] >= target` (lower bound). */
+function lowerBound(ax, n, target) {
+    let lo = 0;
+    let hi = n;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (ax[mid] < target)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+//# sourceMappingURL=value-series.js.map

package/dist/columnar/index.d.ts

@@ -33,7 +33,7 @@ export { type ColumnarRingBufferOptions, ColumnarRingBuffer, } from './ring-buff
 export { type OnUndefinedPartition, type ScatterByPartitionOptions, scatterByPartition, } from './scatter.js';
 export { DICT_ENCODE_MIN_LENGTH, DICT_ENCODE_RATIO, StringColumn, buildDictionaryIndex, estimateDictionaryBytes, remapColumnToDictionary, remapIndicesToDictionary, stringColumnDictEncoded, stringColumnFallback, stringColumnFromArray, } from './string-column.js';
 export { ArrayColumn, EMPTY_ARRAY_SENTINEL, arrayColumnFromArray, } from './array-column.js';
-export { type IntervalLabelKind, type KeyColumn, IntervalKeyColumn, TimeKeyColumn, TimeRangeKeyColumn, timeKeyColumnFromArray, timeRangeKeyColumnFromPairs, } from './key-column.js';
+export { type IntervalLabelKind, type KeyColumn, IntervalKeyColumn, TimeKeyColumn, TimeRangeKeyColumn, ValueKeyColumn, timeKeyColumnFromArray, timeRangeKeyColumnFromPairs, valueKeyColumnFromArray, } from './key-column.js';
 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';

package/dist/columnar/index.js

@@ -33,7 +33,7 @@ export { ColumnarRingBuffer, } from './ring-buffer.js';
 export { scatterByPartition, } from './scatter.js';
 export { DICT_ENCODE_MIN_LENGTH, DICT_ENCODE_RATIO, StringColumn, buildDictionaryIndex, estimateDictionaryBytes, remapColumnToDictionary, remapIndicesToDictionary, stringColumnDictEncoded, stringColumnFallback, stringColumnFromArray, } from './string-column.js';
 export { ArrayColumn, EMPTY_ARRAY_SENTINEL, arrayColumnFromArray, } from './array-column.js';
-export { IntervalKeyColumn, TimeKeyColumn, TimeRangeKeyColumn, timeKeyColumnFromArray, timeRangeKeyColumnFromPairs, } from './key-column.js';
+export { IntervalKeyColumn, TimeKeyColumn, TimeRangeKeyColumn, ValueKeyColumn, timeKeyColumnFromArray, timeRangeKeyColumnFromPairs, valueKeyColumnFromArray, } from './key-column.js';
 export { ColumnarStore } from './store.js';
 export { ArrayColumnBuilder, BooleanColumnBuilder, Float64ColumnBuilder, StringColumnBuilder, columnBuilderForKind, } from './builder.js';
 export { materialize, withColumnAppended, withColumnReplaced, withColumnsRenamed, withColumnsSelected, withKeyColumn, withRowRange, withRowSelection, } from './view.js';

package/dist/columnar/key-column.d.ts

@@ -33,13 +33,13 @@
 import { Float64Column } from './column.js';
 import { StringColumn } from './string-column.js';
 /** The framework's key-column discriminated union. */
-export type KeyColumn = TimeKeyColumn | TimeRangeKeyColumn | IntervalKeyColumn;
+export type KeyColumn = TimeKeyColumn | TimeRangeKeyColumn | IntervalKeyColumn | ValueKeyColumn;
 /**
  * Shared interface implemented by every key-column class. Pure
  * indexed buffer access; the framework knows nothing about
  * `EventKey` / `Time` / `TimeRange` / `Interval`.
  */
-interface KeyColumnBase<K extends 'time' | 'timeRange' | 'interval'> {
+interface KeyColumnBase<K extends 'time' | 'timeRange' | 'interval' | 'value'> {
     readonly kind: K;
     /** Row count. */
     readonly length: number;
@@ -97,6 +97,34 @@ export declare class TimeKeyColumn implements KeyColumnBase<'time'> {
      */
     sliceByIndices(indices: Int32Array): TimeKeyColumn;
 }
+/**
+ * Point key on a **value axis** (distance, cumulative work, …) rather than
+ * time — the substrate of a `ValueSeries`. Structurally identical to
+ * {@link TimeKeyColumn} (single `Float64Array`, `end === begin`); only the
+ * `kind` tag differs, which is what gates the calendar/clock operators
+ * (`Sequence.every`, tz tick formatting) off a value-keyed series.
+ *
+ * The buffer carries finite axis values, not epoch milliseconds. **Ordering
+ * (non-decreasing) is NOT enforced here** — the monotonicity contract lives on
+ * the `byValue` projection (`assertMonotonicAxis`), so the column stays a dumb
+ * indexed buffer (matching how the time columns don't self-validate sort
+ * order). Finiteness *is* enforced: a `NaN` / `Infinity` axis value would break
+ * bisection and range logic.
+ */
+export declare class ValueKeyColumn implements KeyColumnBase<'value'> {
+    readonly kind: "value";
+    readonly length: number;
+    readonly begin: Float64Array;
+    /** For a point value key, `end === begin` (same buffer) — a zero-width axis position. */
+    readonly end: Float64Array;
+    constructor(begin: Float64Array, length: number);
+    beginAt(i: number): number;
+    endAt(i: number): number;
+    /** Zero-copy index-range view. Mirrors {@link TimeKeyColumn.sliceByRange}. */
+    sliceByRange(start: number, end: number): ValueKeyColumn;
+    /** Gathers rows by index. See {@link TimeKeyColumn.sliceByIndices}. */
+    sliceByIndices(indices: Int32Array): ValueKeyColumn;
+}
 export declare class TimeRangeKeyColumn implements KeyColumnBase<'timeRange'> {
     readonly kind: "timeRange";
     readonly length: number;
@@ -181,6 +209,12 @@ export declare class IntervalKeyColumn implements KeyColumnBase<'interval'> {
  * value columns.
  */
 export declare function timeKeyColumnFromArray(timestamps: ReadonlyArray<number>): TimeKeyColumn;
+/**
+ * Builds a {@link ValueKeyColumn} from an array of axis values. The values
+ * must be finite; ordering (non-decreasing) is the `byValue` projection's
+ * contract, not this factory's.
+ */
+export declare function valueKeyColumnFromArray(values: ReadonlyArray<number>): ValueKeyColumn;
 /**
  * Builds a `TimeRangeKeyColumn` from `[begin, end]` pairs. Each pair
  * must satisfy `begin <= end`.