pond-ts 0.30.0 → 0.31.1

package/CHANGELOG.md

@@ -3,11 +3,14 @@
 All notable changes to this project are documented here.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
-`pond-ts` and `@pond-ts/react` release together under a single `v*` tag, so this
-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.30.0...HEAD
+The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`, and
+`@pond-ts/fit` — release together under a single `v*` tag, so this file covers
+them all. 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.31.1...HEAD
+[0.31.1]: https://github.com/pjm17971/pond-ts/compare/v0.30.0...v0.31.1
+[0.31.0]: https://github.com/pjm17971/pond-ts/compare/v0.30.0...3c4e8bd
 [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
@@ -22,6 +25,73 @@ 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
 
+## [0.31.1] — 2026-06-28
+
+### Fixed
+
+- **`@pond-ts/charts` and `@pond-ts/fit` now ship their own README** on npm.
+  0.31.0 inadvertently published the `pond-ts` core README on every package
+  (each `prepack` copied the repo-root README); charts and fit now carry their
+  own. No code or API changes.
+
+## [0.31.0] — 2026-06-28
+
+First published release of **`@pond-ts/charts`** and **`@pond-ts/fit`** (both were
+previously `private`). All four packages — `pond-ts`, `@pond-ts/react`,
+`@pond-ts/charts`, `@pond-ts/fit` — now release together, lock-step, under one
+`v*` tag.
+
+### Added — `pond-ts` (core)
+
+- **`ValueSeries` + `TimeSeries.byValue(axis)` — the value axis as a closed
+  type.** `byValue` re-keys a series onto a monotonic non-time **value axis**
+  (distance, cumulative work, …), returning a `ValueSeries` — the value-keyed
+  counterpart of `TimeSeries`. It carries the ordering-based operators
+  (`axisValues`, `axisAt`, `column`, `nearestIndex`, `sliceByValue`); the
+  calendar/clock operators are deliberately absent — a value axis has no
+  wall-clock semantics, and the disjoint `ValueSeriesSchema` makes them
+  type-impossible. The axis must be **defined, finite, and non-decreasing at
+  every row** (it becomes the index); it is dropped from the value columns (it
+  is now the key) and the rest reshare zero-copy. Substrate: a new `'value'`
+  `KeyKind` + `ValueKeyColumn`. Projection is O(N + C); `nearestIndex` is
+  O(log N); `sliceByValue` is O(log N + C) zero-copy. (value-axis RFC Phase 1.)
+- **`scan(source, step, init, options?)` — typed-accumulator running fold.** The
+  general form of `cumulative` (the classic `mapAccumL`): the accumulator `A`
+  (any value, seeded from `init`) is **decoupled** from the numeric `output` and
+  the output column. `step(acc, value, i)` returns `[nextAcc, output]`. With no
+  `options.output` the source column is **replaced** in place (as `cumulative`
+  does); with `options.output` a **new** column is appended and the source is
+  left intact. Missing-cell carry, stored-`NaN`, and multi-entity semantics are
+  inherited from `cumulative` (scope per entity with
+  `partitionBy(col).scan(...).collect()`). Column-native, O(N + C), no event
+  materialization. Enables `split = scan + byColumn` — materialize cross-bin
+  state (e.g. hysteresis elevation gain) into a column, then segment it with
+  `byColumn`'s pure, order-free reducers. (estela F-geo-2-splits; value-axis
+  RFC wave lead.)
+
+### Added — `@pond-ts/charts` (initial release)
+
+- **First public release.** A React charting layer over pond-ts — a canvas data
+  plane with SVG interactive overlays. `ChartContainer` / `ChartRow` / `Layers`
+  composition; `LineChart`, `AreaChart`, `BarChart`, `Scatter`, `BoxPlot`;
+  `TimeAxis` / `YAxis` / `XAxis` (time **and** value x-axes); the cursor system
+  (staffed flag, per-row cursor modes); shared gap-rendering modes; and the
+  estela theme. Peer-depends on `pond-ts`, `@pond-ts/react`, and React 18/19.
+
+### Added — `@pond-ts/fit` (initial release)
+
+- **First public release.** A fitness / activity domain library over pond-ts — the
+  `Activity` / `Section` façade, unit-safe quantities (`Distance` / `Speed` /
+  `Power` / … with `.format()`), geo / power / zones analytics, `Profile` +
+  `usingProfile()` → `ProfiledActivity` / `ProfiledSection`, and the `Track`
+  value object. Façade-first: one curated flat barrel, with the functional
+  operator surface kept internal. Peer-depends on `pond-ts`.
+
+### Changed
+
+- **All `@pond-ts/*` peer / dependency ranges widened to `^0.31.0`** for the
+  lock-step release.
+
 ## [0.30.0] — 2026-06-17
 
 ### Added

package/dist/batch/operators/by-value.d.ts

@@ -0,0 +1,19 @@
+import { ColumnarStore, type ColumnSchema } from '../../columnar/index.js';
+/**
+ * **Column-native `byValue`** — the raw `TimeSeries → ValueSeries` projection
+ * (RFC `value-axis.md` §6). Re-keys the store onto the monotonic `axis` column
+ * (a no-op reindex: the rows already sit in axis order, since the axis is
+ * non-decreasing in storage order) and **drops `axis` from the value columns**
+ * — it is now the key, and `fromTrustedStore` rejects the duplicate name
+ * otherwise. The non-axis value columns + their buffers are shared by reference
+ * (zero-copy); only the key column is newly allocated.
+ *
+ * Returns the reshaped store + the value-keyed output schema. The schema cast
+ * is the trust boundary; `TimeSeries.byValue` wraps the store in a
+ * `ValueSeries` with the precise `ValueKeyedSchema<S, Axis>` type.
+ */
+export declare function byValueOp(store: ColumnarStore<ColumnSchema>, schema: ColumnSchema, axis: string): {
+    store: ColumnarStore<ColumnSchema>;
+    schema: ColumnSchema;
+};
+//# sourceMappingURL=by-value.d.ts.map

package/dist/batch/operators/by-value.js

@@ -0,0 +1,91 @@
+import { ColumnarStore, Float64Column, ValueKeyColumn, } from '../../columnar/index.js';
+/**
+ * Validates that the `axis` column is a usable value axis — **every cell
+ * defined + finite + non-decreasing** — and returns the `Float64Array` to key
+ * on. Throws otherwise.
+ *
+ * This is the monotonicity contract for `byValue`: it lives on the *projection*,
+ * not on `ValueKeyColumn` or `byColumn` (Codex review #1). An order-free
+ * value-bin aggregation has no monotonic precondition, but promoting a column to
+ * the *index* of a series does — and a missing/non-finite cell can't be placed
+ * in the ordering, so (unlike a value column, where a gap is fine) the axis must
+ * be dense.
+ *
+ * **Zero-copy fast path (Lever 1).** A packed {@link Float64Column} (every batch
+ * value column is one) already holds a contiguous backing buffer. Once the scan
+ * has proven `[0, n)` is dense + finite, that buffer *is* the key data, so we
+ * hand back a `subarray(0, n)` view rather than allocating and copying a fresh
+ * array — the source axis column and the new key then share it read-only (the
+ * same zero-copy contract as a slice). `_values.length` can exceed the logical
+ * length (capacity-grown columns), hence the `subarray`. A chunked column has no
+ * single contiguous buffer, so it falls back to materializing one.
+ *
+ * Trade-off of the reuse: the returned `subarray` view retains the source
+ * column's whole `ArrayBuffer` (including any capacity slack on a grown
+ * column), where the old copy released it. Negligible for batch (`_values`
+ * is sized to the column) and for a single live projection; only worth
+ * revisiting if a path holds many such views at once.
+ *
+ * The validation read-loop is unavoidable here (it enforces dense + finite +
+ * sorted). A future `{ assumeSorted }` fast path could skip it for a
+ * caller-guaranteed axis (e.g. a `scan`-produced cumulative distance); that's a
+ * trusted-construction seam, deferred until a re-projection hot path earns it.
+ */
+function assertMonotonicAxis(store, axis) {
+    const col = store.columns.get(axis);
+    if (col === undefined) {
+        throw new RangeError(`byValue: unknown column '${axis}'`);
+    }
+    const n = store.length;
+    let prev = -Infinity;
+    for (let i = 0; i < n; i += 1) {
+        const v = col.read(i);
+        if (typeof v !== 'number' || !Number.isFinite(v)) {
+            throw new RangeError(`byValue: axis '${axis}' must be defined and finite at every row to be the index; ` +
+                `row ${i} is ${v === undefined ? 'missing' : String(v)}`);
+        }
+        if (v < prev) {
+            throw new RangeError(`byValue: axis '${axis}' must be non-decreasing; row ${i} (${v}) < previous (${prev})`);
+        }
+        prev = v;
+    }
+    // Validation passed → `[0, n)` is dense + finite. Reuse the packed backing
+    // buffer zero-copy; materialize only for a (rare) chunked axis column.
+    if (col instanceof Float64Column) {
+        return col._values.subarray(0, n);
+    }
+    const out = new Float64Array(n);
+    for (let i = 0; i < n; i += 1) {
+        out[i] = col.read(i);
+    }
+    return out;
+}
+/**
+ * **Column-native `byValue`** — the raw `TimeSeries → ValueSeries` projection
+ * (RFC `value-axis.md` §6). Re-keys the store onto the monotonic `axis` column
+ * (a no-op reindex: the rows already sit in axis order, since the axis is
+ * non-decreasing in storage order) and **drops `axis` from the value columns**
+ * — it is now the key, and `fromTrustedStore` rejects the duplicate name
+ * otherwise. The non-axis value columns + their buffers are shared by reference
+ * (zero-copy); only the key column is newly allocated.
+ *
+ * Returns the reshaped store + the value-keyed output schema. The schema cast
+ * is the trust boundary; `TimeSeries.byValue` wraps the store in a
+ * `ValueSeries` with the precise `ValueKeyedSchema<S, Axis>` type.
+ */
+export function byValueOp(store, schema, axis) {
+    const values = assertMonotonicAxis(store, axis);
+    // `fromValidatedSubarray`, not `new ValueKeyColumn` — `assertMonotonicAxis`
+    // already proved finiteness, so skip the constructor's redundant finite scan.
+    const keyCol = ValueKeyColumn.fromValidatedSubarray(values, store.length);
+    // Drop the axis column from the value columns (it becomes the key).
+    const newColumns = new Map(store.columns);
+    newColumns.delete(axis);
+    const newSchema = [
+        { name: axis, kind: 'value' },
+        ...schema.slice(1).filter((c) => c.name !== axis),
+    ];
+    const newStore = ColumnarStore.fromTrustedStore(newSchema, keyCol, newColumns);
+    return { store: newStore, schema: newSchema };
+}
+//# sourceMappingURL=by-value.js.map

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

@@ -0,0 +1,47 @@
+import { type ColumnarStore } from '../../columnar/index.js';
+import type { SeriesSchema } from '../../schema/index.js';
+/**
+ * The step function for {@link TimeSeries.scan} — the classic `mapAccumL`:
+ * given the carried accumulator, the current (defined) source value, and the
+ * row index, return the next accumulator and this row's numeric output. The
+ * accumulator type `A` is **decoupled** from the numeric output, which is what
+ * `cumulative` — where the accumulator *is* the output *is* a `number` — cannot
+ * express (e.g. hysteresis elevation gain carries `(ref, gain)` but emits only
+ * `gain`).
+ */
+export type ScanStep<A> = (acc: A, value: number, index: number) => readonly [next: A, output: number];
+/**
+ * **Column-native `scan`** — a typed-accumulator running fold, the
+ * generalization of `cumulativeOp`. Threads `acc: A` (any value, seeded from
+ * `init`) across the source column's defined cells, emits one numeric `output`
+ * per row, and either **replaces** the source column (`output === undefined`,
+ * `cumulative`'s convention) or **appends** a new column (`output` named,
+ * `withColumn`'s convention; the source stays intact). Reads straight off
+ * `Column.read(i)` — no event materialization, one pass, **O(n)**.
+ *
+ * Semantics are inherited from `cumulativeOp` so `scan` is consistent, not a
+ * new dialect:
+ * - A **defined numeric cell** calls `step(acc, value, i)`; the accumulator and
+ *   the last-emitted output both advance.
+ * - A **missing / undefined cell** does *not* call `step`: the accumulator is
+ *   carried unchanged and the row re-emits the last output, so the output holds
+ *   flat across a gap (exactly as `cumulative`'s accumulator holds). The output
+ *   is `undefined` only until the first defined value produces one
+ *   (`float64ColumnFromArray` derives validity from the `undefined`s).
+ * - A **stored `NaN`** is a defined number — `step` is called with it, and a
+ *   computed non-finite output lands as a defined cell. This is the
+ *   *trusted-compute* path (matching `cumulative`), not the validated
+ *   `withColumn` intake; the step author owns output finiteness.
+ *
+ * Returns the reshaped store + the output schema. The result-schema cast is the
+ * single trust boundary; `TimeSeries.scan` wraps the store via
+ * `#fromTrustedStore`. A non-numeric source is unreachable through the typed
+ * surface (`scan<Source extends NumericColumnNameForSchema<S>>`); on the
+ * replace path it fails fast (`withColumnReplaced`'s kind guard), matching
+ * `cumulative`.
+ */
+export declare function scanOp<S extends SeriesSchema, OutSchema extends SeriesSchema, A>(store: ColumnarStore<S>, schema: S, source: string, step: ScanStep<A>, init: A, output: string | undefined): {
+    store: ColumnarStore<OutSchema>;
+    schema: OutSchema;
+};
+//# sourceMappingURL=scan.d.ts.map

package/dist/batch/operators/scan.js

@@ -0,0 +1,81 @@
+import { float64ColumnFromArray, withColumnAppended, withColumnReplaced, } from '../../columnar/index.js';
+/**
+ * **Column-native `scan`** — a typed-accumulator running fold, the
+ * generalization of `cumulativeOp`. Threads `acc: A` (any value, seeded from
+ * `init`) across the source column's defined cells, emits one numeric `output`
+ * per row, and either **replaces** the source column (`output === undefined`,
+ * `cumulative`'s convention) or **appends** a new column (`output` named,
+ * `withColumn`'s convention; the source stays intact). Reads straight off
+ * `Column.read(i)` — no event materialization, one pass, **O(n)**.
+ *
+ * Semantics are inherited from `cumulativeOp` so `scan` is consistent, not a
+ * new dialect:
+ * - A **defined numeric cell** calls `step(acc, value, i)`; the accumulator and
+ *   the last-emitted output both advance.
+ * - A **missing / undefined cell** does *not* call `step`: the accumulator is
+ *   carried unchanged and the row re-emits the last output, so the output holds
+ *   flat across a gap (exactly as `cumulative`'s accumulator holds). The output
+ *   is `undefined` only until the first defined value produces one
+ *   (`float64ColumnFromArray` derives validity from the `undefined`s).
+ * - A **stored `NaN`** is a defined number — `step` is called with it, and a
+ *   computed non-finite output lands as a defined cell. This is the
+ *   *trusted-compute* path (matching `cumulative`), not the validated
+ *   `withColumn` intake; the step author owns output finiteness.
+ *
+ * Returns the reshaped store + the output schema. The result-schema cast is the
+ * single trust boundary; `TimeSeries.scan` wraps the store via
+ * `#fromTrustedStore`. A non-numeric source is unreachable through the typed
+ * surface (`scan<Source extends NumericColumnNameForSchema<S>>`); on the
+ * replace path it fails fast (`withColumnReplaced`'s kind guard), matching
+ * `cumulative`.
+ */
+export function scanOp(store, schema, source, step, init, output) {
+    const col = store.columns.get(source);
+    if (col === undefined) {
+        throw new RangeError(`scan: unknown column '${source}'`);
+    }
+    const n = store.length;
+    const out = new Array(n);
+    let acc = init;
+    let last;
+    for (let i = 0; i < n; i += 1) {
+        const raw = col.read(i);
+        if (typeof raw === 'number') {
+            const r = step(acc, raw, i);
+            acc = r[0];
+            last = r[1];
+        }
+        out[i] = last;
+    }
+    const column = float64ColumnFromArray(out);
+    const base = store;
+    // Output omitted ⇒ replace the source column in place (cumulative's
+    // convention; the source is widened to optional `number`).
+    if (output === undefined) {
+        const result = withColumnReplaced(base, source, column);
+        const outSchema = Object.freeze(schema.map((c, i) => i === 0 || c.name !== source
+            ? c
+            : { ...c, kind: 'number', required: false }));
+        return {
+            store: result,
+            schema: outSchema,
+        };
+    }
+    // Output named ⇒ append a new column, leaving the source intact. The name
+    // must not collide with the key or an existing value column (the schema
+    // includes the key at index 0). `withColumnAppended` re-checks, but the
+    // explicit guard gives a scan-specific message pointing at the replace path.
+    if (schema.some((c) => c.name === output)) {
+        throw new RangeError(`scan: output column '${output}' already exists; omit options.output to replace the source column`);
+    }
+    const result = withColumnAppended(base, output, column);
+    const outSchema = Object.freeze([
+        ...schema,
+        { name: output, kind: 'number' },
+    ]);
+    return {
+        store: result,
+        schema: outSchema,
+    };
+}
+//# sourceMappingURL=scan.js.map

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

@@ -4,7 +4,8 @@ import { Sequence } from '../sequence/sequence.js';
 import type { DurationInput } from '../core/duration.js';
 import type { TemporalLike } from '../core/temporal.js';
 import type { BatchSampleStrategy } from '../sequence/sample.js';
-import type { AggregateSchema, AlignSchema, BaselineSchema, DedupeKeep, DiffSchema, EventDataForSchema, FillMapping, FillStrategy, MaterializeSchema, NumericColumnNameForSchema, RollingAlignment, RollingSchema, SeriesSchema, SmoothAppendSchema, SmoothMethod, SmoothSchema, ValidatedAggregateMap } from '../schema/index.js';
+import type { AggregateSchema, AlignSchema, AppendColumn, BaselineSchema, DedupeKeep, DiffSchema, EventDataForSchema, FillMapping, FillStrategy, MaterializeSchema, NumericColumnNameForSchema, RollingAlignment, RollingSchema, SeriesSchema, SmoothAppendSchema, SmoothMethod, SmoothSchema, ValidatedAggregateMap } from '../schema/index.js';
+import type { ScanStep } from './operators/scan.js';
 type SequenceLike = Sequence | BoundedSequence;
 type AlignMethod = 'hold' | 'linear';
 type AlignSample = 'begin' | 'center' | 'end';
@@ -303,6 +304,11 @@ export declare class PartitionedTimeSeries<S extends SeriesSchema, K extends str
     cumulative<const Targets extends NumericColumnNameForSchema<S>>(spec: {
         [K in Targets]: 'sum' | 'max' | 'min' | 'count' | ((acc: number, value: number) => number);
     }): PartitionedTimeSeries<DiffSchema<S, Targets>, K>;
+    /** Per-partition `scan`. See {@link TimeSeries.scan}. */
+    scan<const Source extends NumericColumnNameForSchema<S>, A>(source: Source, step: ScanStep<A>, init: A): PartitionedTimeSeries<DiffSchema<S, Source>, K>;
+    scan<const Source extends NumericColumnNameForSchema<S>, const Name extends string, A>(source: Source, step: ScanStep<A>, init: A, options: {
+        output: Name;
+    }): PartitionedTimeSeries<AppendColumn<S, Name, 'number'>, K>;
     /** Per-partition `shift`. See {@link TimeSeries.shift}. */
     shift<const Target extends NumericColumnNameForSchema<S>>(columns: Target | readonly Target[], n: number): PartitionedTimeSeries<DiffSchema<S, Target>, K>;
     /** Per-partition `aggregate`. See {@link TimeSeries.aggregate}. */

package/dist/batch/partitioned-time-series.js

@@ -419,6 +419,9 @@ export class PartitionedTimeSeries {
     cumulative(spec) {
         return this.rewrap(PartitionedTimeSeries.applyToSource(this.source, this.by, (g) => g.cumulative(spec)));
     }
+    scan(source, step, init, options) {
+        return this.rewrap(PartitionedTimeSeries.applyToSource(this.source, this.by, (g) => g.scan(source, step, init, options)));
+    }
     /** Per-partition `shift`. See {@link TimeSeries.shift}. */
     shift(columns, n) {
         return this.rewrap(PartitionedTimeSeries.applyToSource(this.source, this.by, (g) => g.shift(columns, n)));

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' } })`.
@@ -792,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).
@@ -1089,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' } })`.
@@ -1680,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).
@@ -2603,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`.

package/dist/columnar/key-column.js

@@ -150,6 +150,81 @@ export class TimeKeyColumn {
     }
 }
 /* -------------------------------------------------------------------------- */
+/* ValueKeyColumn — single-buffer point key on a non-time value axis.         */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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 class ValueKeyColumn {
+    kind = 'value';
+    length;
+    begin;
+    /** For a point value key, `end === begin` (same buffer) — a zero-width axis position. */
+    end;
+    constructor(begin, length) {
+        validateColumnLength(length, 'ValueKeyColumn');
+        if (length > begin.length) {
+            throw new RangeError(`ValueKeyColumn buffer underflow: length ${length} exceeds begin.length ${begin.length}`);
+        }
+        assertFiniteTimestamps(begin, length, 'ValueKeyColumn', 'begin');
+        this.length = length;
+        this.begin = begin;
+        this.end = begin;
+    }
+    beginAt(i) {
+        if (i < 0 || i >= this.length) {
+            throw new RangeError(`ValueKeyColumn.beginAt out of range: ${i} not in [0, ${this.length})`);
+        }
+        return this.begin[i];
+    }
+    endAt(i) {
+        return this.beginAt(i);
+    }
+    /** Zero-copy index-range view. Mirrors {@link TimeKeyColumn.sliceByRange}. */
+    sliceByRange(start, end) {
+        const lo = Math.max(0, start);
+        const hi = Math.min(this.length, end);
+        if (hi <= lo) {
+            return ValueKeyColumn.fromValidatedSubarray(new Float64Array(0), 0);
+        }
+        return ValueKeyColumn.fromValidatedSubarray(this.begin.subarray(lo, hi), hi - lo);
+    }
+    /**
+     * @internal Trusted-buffer factory for slice paths; skips the per-row
+     * finiteness scan. Mirrors {@link TimeKeyColumn.fromValidatedSubarray}.
+     */
+    static fromValidatedSubarray(begin, length) {
+        validateColumnLength(length, 'ValueKeyColumn.fromValidatedSubarray');
+        if (length > begin.length) {
+            throw new RangeError(`ValueKeyColumn.fromValidatedSubarray buffer underflow: length ${length} exceeds begin.length ${begin.length}`);
+        }
+        const c = Object.create(ValueKeyColumn.prototype);
+        Object.assign(c, { kind: 'value', length, begin, end: begin });
+        return c;
+    }
+    /** Gathers rows by index. See {@link TimeKeyColumn.sliceByIndices}. */
+    sliceByIndices(indices) {
+        const outLength = indices.length;
+        const out = new Float64Array(outLength);
+        for (let i = 0; i < outLength; i += 1) {
+            const idx = indices[i];
+            out[i] = idx >= 0 && idx < this.length ? this.begin[idx] : 0;
+        }
+        return new ValueKeyColumn(out, outLength);
+    }
+}
+/* -------------------------------------------------------------------------- */
 /* TimeRangeKeyColumn — begin + end buffers.                                  */
 /* -------------------------------------------------------------------------- */
 export class TimeRangeKeyColumn {
@@ -455,6 +530,20 @@ export function timeKeyColumnFromArray(timestamps) {
     }
     return new TimeKeyColumn(begin, length);
 }
+/**
+ * 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 function valueKeyColumnFromArray(values) {
+    const length = values.length;
+    validateColumnLength(length, 'ValueKeyColumn');
+    const begin = new Float64Array(length);
+    for (let i = 0; i < length; i += 1) {
+        begin[i] = values[i];
+    }
+    return new ValueKeyColumn(begin, length);
+}
 /**
  * Builds a `TimeRangeKeyColumn` from `[begin, end]` pairs. Each pair
  * must satisfy `begin <= end`.

package/dist/columnar/types.d.ts

@@ -12,8 +12,14 @@
  */
 /** Value-column kinds — the four scalar storage shapes. */
 export type ColumnKind = 'number' | 'boolean' | 'string' | 'array';
-/** Key-column kinds — the three temporal axis shapes. */
-export type KeyKind = 'time' | 'timeRange' | 'interval';
+/**
+ * Key-column kinds. `'time'` / `'timeRange'` / `'interval'` are the temporal
+ * axis shapes; `'value'` is a non-time **value axis** (distance, cumulative
+ * work, …) — the substrate of a `ValueSeries`. The value tag is what gates the
+ * calendar/clock operators (`Sequence.every`, tz formatting) off a value-keyed
+ * series; the underlying buffer is the same finite `Float64Array`.
+ */
+export type KeyKind = 'time' | 'timeRange' | 'interval' | 'value';
 /**
  * Any column kind — value or key. `ColumnDef`'s `kind` field is
  * widened to this so a single tuple type can describe both the

package/dist/columnar/view.js

@@ -24,7 +24,7 @@
  * Framework-internal; not exported from `packages/core/src/index.ts`.
  */
 import { materializeChunkedArray, materializeChunkedBoolean, materializeChunkedFloat64, materializeChunkedString, } from './chunked-column.js';
-import { IntervalKeyColumn, TimeKeyColumn, TimeRangeKeyColumn, } from './key-column.js';
+import { IntervalKeyColumn, TimeKeyColumn, TimeRangeKeyColumn, ValueKeyColumn, } from './key-column.js';
 import { ColumnarStore } from './store.js';
 /**
  * Returns a new `ColumnarStore` whose rows are
@@ -361,6 +361,9 @@ function sliceKeyColumnByIndices(keys, indices) {
     if (keys instanceof IntervalKeyColumn) {
         return keys.sliceByIndices(indices);
     }
+    if (keys instanceof ValueKeyColumn) {
+        return keys.sliceByIndices(indices);
+    }
     // Defensive fallback — exhaustiveness check.
     throw new TypeError(`withRowSelection: unrecognized KeyColumn kind '${keys.kind}'`);
 }
@@ -382,6 +385,9 @@ function sliceKeyColumnByRange(keys, start, end) {
     if (keys instanceof IntervalKeyColumn) {
         return keys.sliceByRange(start, end);
     }
+    if (keys instanceof ValueKeyColumn) {
+        return keys.sliceByRange(start, end);
+    }
     // Defensive fallback — exhaustiveness check.
     throw new TypeError(`withRowRange: unrecognized KeyColumn kind '${keys.kind}'`);
 }

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export { Time } from './core/time.js';
 export { TimeRange, toTimeRange } from './core/time-range.js';
 export { Sequence } from './sequence/sequence.js';
 export { TimeSeries, type KeyLike } from './batch/time-series.js';
+export { ValueSeries } from './batch/value-series.js';
 export { top } from './reducers/index.js';
 export { ValidationError } from './core/errors.js';
 import './column.js';
@@ -27,9 +28,9 @@ export { type Column, type ColumnKind, type ColumnStorage, type ScanOptions, Boo
 export { StringColumn } from './columnar/string-column.js';
 export { ArrayColumn } from './columnar/array-column.js';
 export { ChunkedArrayColumn, ChunkedBooleanColumn, ChunkedFloat64Column, ChunkedStringColumn, } from './columnar/chunked-column.js';
-export { type IntervalLabelKind, type KeyColumn, IntervalKeyColumn, TimeKeyColumn, TimeRangeKeyColumn, } from './columnar/key-column.js';
+export { type IntervalLabelKind, type KeyColumn, IntervalKeyColumn, TimeKeyColumn, TimeRangeKeyColumn, ValueKeyColumn, } from './columnar/key-column.js';
 export { type ValidityBitmap } from './columnar/validity.js';
-export type { AlignSchema, ArrayColumnNameForSchema, BaselineSchema, AggregateFunction, AggregateReducer, AggregateOutputMap, AggregateOutputSpec, AggregateMap, AggregateSchema, ValidatedAggregateMap, ColumnDef, CollapseData, ArrayAggregateAppendSchema, ArrayAggregateKind, ArrayAggregateReplaceSchema, ArrayExplodeAppendSchema, ArrayExplodeReplaceSchema, CollapseSchema, DedupeKeep, EventDataForSchema, EventForSchema, EventKeyForKind, FillMapping, FillStrategy, MaterializeSchema, EventKeyForSchema, FirstColKind, FirstColumn, IntervalKeyedSchema, JsonIntervalInput, JsonObjectRowForSchema, JsonRowFormat, JsonRowForSchema, JsonTimeRangeInput, JsonTimestampInput, JsonValueForKind, RollingAlignment, RollingSchema, JoinConflictMode, JoinManySchema, PrefixedJoinManySchema, PrefixedJoinSchema, LiveSource, JoinType, JoinSchema, NormalizedRowForSchema, NormalizedObjectRowForSchema, NormalizedObjectRow, NormalizedValueForKind, ReduceResult, RenameData, RenameMap, RenameSchema, RekeySchema, RowForSchema, ArrayValue, ColumnValue, ScalarKind, ScalarValue, CustomAggregateReducer, DiffSchema, NumericColumnNameForSchema, SmoothMethod, SmoothAppendSchema, SmoothSchema, SelectData, SelectSchema, SeriesSchema, TimeKeyedSchema, TimeSeriesInput, TimeSeriesJsonInput, TimeRangeKeyedSchema, ValueColumnsForSchema, ValueColumn, ValueForKind, } from './schema/index.js';
+export type { AlignSchema, ArrayColumnNameForSchema, BaselineSchema, AggregateFunction, AggregateReducer, AggregateOutputMap, AggregateOutputSpec, AggregateMap, AggregateSchema, ValidatedAggregateMap, ColumnDef, CollapseData, ArrayAggregateAppendSchema, ArrayAggregateKind, ArrayAggregateReplaceSchema, ArrayExplodeAppendSchema, ArrayExplodeReplaceSchema, CollapseSchema, DedupeKeep, EventDataForSchema, EventForSchema, EventKeyForKind, FillMapping, FillStrategy, MaterializeSchema, EventKeyForSchema, FirstColKind, FirstColumn, IntervalKeyedSchema, JsonIntervalInput, JsonObjectRowForSchema, JsonRowFormat, JsonRowForSchema, JsonTimeRangeInput, JsonTimestampInput, JsonValueForKind, RollingAlignment, RollingSchema, JoinConflictMode, JoinManySchema, PrefixedJoinManySchema, PrefixedJoinSchema, LiveSource, JoinType, JoinSchema, NormalizedRowForSchema, NormalizedObjectRowForSchema, NormalizedObjectRow, NormalizedValueForKind, ReduceResult, RenameData, RenameMap, RenameSchema, RekeySchema, RowForSchema, ArrayValue, ColumnValue, ScalarKind, ScalarValue, CustomAggregateReducer, DiffSchema, NumericColumnNameForSchema, SmoothMethod, SmoothAppendSchema, SmoothSchema, SelectData, SelectSchema, SeriesSchema, TimeKeyedSchema, TimeSeriesInput, TimeSeriesJsonInput, TimeRangeKeyedSchema, ValueColumnsForSchema, ValueColumn, ValueForKind, ValueFirstColumn, ValueKeyedSchema, ValueSeriesColumnName, ValueSeriesSchema, ValueSeriesValueColumns, } from './schema/index.js';
 export type { CalendarOptions, CalendarUnit, TimeZoneOptions, } from './core/calendar.js';
 export type { EventKey, IntervalInput, IntervalValue, TemporalLike, TimeRangeInput, TimestampInput, } from './core/temporal.js';
 export type { DurationInput } from './core/duration.js';

package/dist/index.js

@@ -15,6 +15,7 @@ export { Time } from './core/time.js';
 export { TimeRange, toTimeRange } from './core/time-range.js';
 export { Sequence } from './sequence/sequence.js';
 export { TimeSeries } from './batch/time-series.js';
+export { ValueSeries } from './batch/value-series.js';
 export { top } from './reducers/index.js';
 export { ValidationError } from './core/errors.js';
 // ─── Column-centric public API (Phase 4.7 steps 8a + 8b) ────────
@@ -53,5 +54,5 @@ export { BooleanColumn, Float64Column, } from './columnar/column.js';
 export { StringColumn } from './columnar/string-column.js';
 export { ArrayColumn } from './columnar/array-column.js';
 export { ChunkedArrayColumn, ChunkedBooleanColumn, ChunkedFloat64Column, ChunkedStringColumn, } from './columnar/chunked-column.js';
-export { IntervalKeyColumn, TimeKeyColumn, TimeRangeKeyColumn, } from './columnar/key-column.js';
+export { IntervalKeyColumn, TimeKeyColumn, TimeRangeKeyColumn, ValueKeyColumn, } from './columnar/key-column.js';
 //# sourceMappingURL=index.js.map

package/dist/live/series-store.js

@@ -296,17 +296,25 @@ function materializeKey(keys, i) {
     if (keys.kind === 'timeRange') {
         return new TimeRange({ start: keys.beginAt(i), end: keys.endAt(i) });
     }
-    // interval
-    const ikeys = keys;
-    const label = ikeys.labelAt(i);
-    if (label === undefined) {
-        throw new Error(`SeriesStore.keyAt: row ${i} has no interval label (this should have been caught at IntervalKeyColumn construction)`);
-    }
-    return new Interval({
-        value: label,
-        start: keys.beginAt(i),
-        end: keys.endAt(i),
-    });
+    if (keys.kind === 'interval') {
+        const ikeys = keys;
+        const label = ikeys.labelAt(i);
+        if (label === undefined) {
+            throw new Error(`SeriesStore.keyAt: row ${i} has no interval label (this should have been caught at IntervalKeyColumn construction)`);
+        }
+        return new Interval({
+            value: label,
+            start: keys.beginAt(i),
+            end: keys.endAt(i),
+        });
+    }
+    // A `'value'` key (ValueSeries) has no EventKey representation — a ValueSeries
+    // wraps the ColumnarStore directly and never routes through SeriesStore. Fail
+    // loudly rather than silently mistreat a value key as an interval (which would
+    // call the non-existent `labelAt`). Unreachable today; a guard against a
+    // future path that wraps a value-keyed store in a SeriesStore.
+    throw new TypeError(`SeriesStore.keyAt: key kind '${keys.kind}' has no EventKey representation ` +
+        `(value-keyed stores are accessed via ValueSeries, not SeriesStore)`);
 }
 function buildRowData(store, i) {
     const data = {};

package/dist/schema/index.d.ts

@@ -1,4 +1,4 @@
-export type { AppendColumn, ArrayColumnNameForSchema, ArrayValue, ColumnDef, ColumnValue, FirstColKind, FirstColumn, IntervalKeyedSchema, KindForValue, NormalizedValueForKind, NumericColumnNameForSchema, OptionalNumberColumn, OptionalizeColumn, OptionalizeColumns, RekeySchema, ReplaceColumnKind, RowForSchema, ScalarKind, ScalarValue, SeriesSchema, TimeKeyedSchema, TimeRangeKeyedSchema, ValueColumn, ValueColumnKindForName, ValueColumnNameForSchema, ValueColumnsForSchema, ValueForKind, } from './series.js';
+export type { AppendColumn, ArrayColumnNameForSchema, ArrayValue, ColumnDef, ColumnValue, ExcludeColumnByName, FirstColKind, FirstColumn, IntervalKeyedSchema, KindForValue, NormalizedValueForKind, NumericColumnNameForSchema, OptionalNumberColumn, OptionalizeColumn, OptionalizeColumns, RekeySchema, ReplaceColumnKind, RowForSchema, ScalarKind, ScalarValue, SeriesSchema, TimeKeyedSchema, TimeRangeKeyedSchema, ValueColumn, ValueColumnKindForName, ValueColumnNameForSchema, ValueColumnsForSchema, ValueFirstColumn, ValueForKind, ValueKeyedSchema, ValueSeriesColumnName, ValueSeriesSchema, ValueSeriesValueColumns, } from './series.js';
 export type { EventDataForSchema, EventForSchema, EventKeyForKind, EventKeyForSchema, LiveSource, NormalizedObjectRow, NormalizedObjectRowForSchema, NormalizedRowForSchema, PointRowForSchema, TimeSeriesInput, } from './events.js';
 export type { JsonIntervalInput, JsonObjectRowForSchema, JsonRowForSchema, JsonRowFormat, JsonTimeRangeInput, JsonTimestampInput, JsonValueForKind, TimeSeriesJsonInput, TimeSeriesJsonOutputArray, TimeSeriesJsonOutputObject, } from './json.js';
 export type { AggregateColumns, AggregateFunction, AggregateMap, AggregateOutputMap, AggregateOutputMapResultSchema, AggregateOutputSpec, AggregateReducer, AggregateSchema, AlignSchema, ValidatedAggregateMap, ArrayAggregateAppendSchema, ArrayAggregateKind, ArrayAggregateReplaceSchema, ArrayExplodeAppendSchema, ArrayExplodeReplaceSchema, CustomAggregateReducer, MaterializeSchema, RollingOutputMapSchema, } from './aggregate.js';

package/dist/schema/series.d.ts

@@ -92,4 +92,23 @@ export type RekeySchema<S extends SeriesSchema, First extends FirstColumn> = rea
 export type TimeKeyedSchema<S extends SeriesSchema> = RekeySchema<S, ColumnDef<'time', 'time'>>;
 export type TimeRangeKeyedSchema<S extends SeriesSchema> = RekeySchema<S, ColumnDef<'timeRange', 'timeRange'>>;
 export type IntervalKeyedSchema<S extends SeriesSchema> = RekeySchema<S, ColumnDef<'interval', 'interval'>>;
+/** The first column of a `ValueSeries` — a `'value'` key with an arbitrary axis name. */
+export type ValueFirstColumn = ColumnDef<string, 'value'>;
+/** A value-axis-keyed schema: a `'value'` key (arbitrary name) + value columns. */
+export type ValueSeriesSchema = readonly [ValueFirstColumn, ...ValueColumn[]];
+/** Drops the column named `Target` from a value-column tuple. Mirrors {@link ReplaceColumnKind}. */
+export type ExcludeColumnByName<Columns extends readonly ValueColumn[], Target extends string> = Columns extends readonly [infer Head, ...infer Tail] ? Head extends ValueColumn ? Tail extends readonly ValueColumn[] ? Head['name'] extends Target ? ExcludeColumnByName<Tail, Target> : [Head, ...ExcludeColumnByName<Tail, Target>] : [] : [] : [];
+/**
+ * The schema produced by `TimeSeries.byValue(Axis)`: the named axis column
+ * becomes the `'value'` key, and is removed from the value columns (the key
+ * takes its name, so leaving it as a value column would duplicate the name).
+ */
+export type ValueKeyedSchema<S extends SeriesSchema, Axis extends string> = readonly [
+    ColumnDef<Axis, 'value'>,
+    ...ExcludeColumnByName<ValueColumnsForSchema<S>, Axis>
+];
+/** The value columns of a `ValueSeriesSchema` (everything after the axis key). */
+export type ValueSeriesValueColumns<VS extends ValueSeriesSchema> = VS extends readonly [ValueFirstColumn, ...infer Rest] ? Rest extends readonly ValueColumn[] ? Rest : never : never;
+/** Union of value-column names on a `ValueSeriesSchema` (for `ValueSeries.column`). */
+export type ValueSeriesColumnName<VS extends ValueSeriesSchema> = ValueSeriesValueColumns<VS>[number]['name'];
 //# sourceMappingURL=series.d.ts.map

package/package.json

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