pond-ts 0.54.0 → 0.55.0

package/CHANGELOG.md

@@ -8,7 +8,8 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`,
 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/pond-ts/pond/compare/v0.54.0...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.55.0...HEAD
+[0.55.0]: https://github.com/pond-ts/pond/compare/v0.54.0...v0.55.0
 [0.54.0]: https://github.com/pond-ts/pond/compare/v0.53.1...v0.54.0
 [0.53.1]: https://github.com/pond-ts/pond/compare/v0.53.0...v0.53.1
 [0.53.0]: https://github.com/pond-ts/pond/compare/v0.52.0...v0.53.0
@@ -55,8 +56,318 @@ include new features and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.55.0] — 2026-08-04
+
+### Added
+
+- **process:** **`@pond-ts/process` publishes for the first time —
+  experimental, pre-1.0.** Computations as data over pond-ts: a processing
+  graph authored fluently in application code (or composed as JSON by a saved
+  view or a tool-calling model) resolves against a declared op vocabulary and
+  runs over a bound `TimeSeries`, with content-addressed caching, provenance,
+  and per-node timings on every response. Two entry points: the plan layer at
+  `.` and the Node worker pool at `./pool`. The docs section
+  ([pond-ts.org/docs/process](https://pond-ts.org/docs/process/)) is listed on
+  the site with a TypeDoc API reference; the publication follows the 2026-08
+  external audit hardening (all P1 findings fixed and regression-pinned). The
+  API is expected to move as friction reports land — pin an exact version.
+
+- **charts:** **`<BarChart categories>` now works horizontally** ([PND-HCAT],
+  the 2026-08 API review's #3 item) — the funnel / ranking / comparison shape.
+  `orientation="horizontal"` puts the categories on the **y** axis as unit
+  slots with the value on x, and a `<YAxis>` with no explicit `ticks` **derives
+  one label per category by itself**, so the chart no longer needs a
+  hand-built `i + 0.5` tick list. It previously threw ("horizontal category
+  axes are not yet supported"), which forced consumers to convert their
+  categories into ordinal `bins` records _and_ hand-place the labels — the
+  workaround the gallery funnel documents.
+
+  Explicit `<YAxis ticks>` still wins, and vertical categorical charts are
+  untouched (categories stay on the container's ordinal x band scale). A new
+  internal `RowLayer.binCategories()` channel carries the names to whichever
+  axis they land on.
+
+- **charts:** **the list family's series door** — `<BarList series={splits}
+label={…}>` / `<BoxList series>` take a `TimeSeries` / `ValueSeries`
+  directly (one row per event; exactly-one-of with `rows`), closing the
+  "required adapter" gap the 2026-08 API review named: starting from a pond
+  series there is no shaping step. The `listRowsFrom*` readers remain for
+  record rows. Docs across the charts hub, cheat sheet, and type pages now
+  present the series as the whole data contract, with the exported `from*`
+  builders re-documented as **interop escape hatches for non-pond data**.
+
+- **charts:** **`<BarList>` + `<BoxList>` — standalone ranked row lists** (the
+  react-timeseries-charts `HorizontalBarChart` shape, rebuilt as what it
+  always was: a table). One DOM row per _entity_ — an interface, a split, a
+  symbol — with a label cell (any node, links included), one glyph line per
+  configured column on **one shared value scale**, optional data cells
+  before/after the glyphs, `sortBy`/`sortDirection` or a full custom
+  comparator (missing values sort last either direction), an optional per-row
+  expander (`renderExpanded`, keyed on row identity so it survives a re-sort),
+  and consumer-owned row selection with an accent edge in the marks register.
+  A vertical **baseline rule** at the scale origin anchors the rows to one
+  reference (on by default for `<BoxList>`, whose lines float at their lower
+  quantile; opt-in for `<BarList>`, whose tracks already show zero), and
+  reference **`markers`** (`{ value, label? }`) draw a labelled dotted rule
+  through every row in the annotation register — an SLA / capacity line —
+  with marker values joining the auto domain fit.
+  `<BarList>` draws proportional value bars; its sister `<BoxList>` draws a
+  five-number distribution per line — range band, `q1`→`q3` body, median line
+  — plus an optional **current-value tick** with a formatted inline label (the
+  esnet traffic-by-interface look), using the same quantile vocabulary as the
+  canvas `<BoxPlot>` (`lower`/`q1`/`median`/`q3`/`upper`, both-or-neither
+  body, quantiles computed upstream — `reduce` facts — never by the chart).
+  Styling stays on the one channel: bars resolve `theme.bar[as]`, boxes
+  `theme.box[as]`; both built-in themes gain a `box.secondary` role for the
+  paired-direction case. Readers `listRowsFromTimeSeries` /
+  `listRowsFromValueSeries` build one row per event / axis key. The in-plot
+  histogram remains `<BarChart orientation="horizontal">` — the lists are for
+  the table-shaped cases it can't be (link labels, cells, expanders, custom
+  sort).
+
+- **charts:** **`BarStyle.hover` — a distinct hover colour for bars**
+  ([#577](https://github.com/pond-ts/pond/issues/577)). A theme may now give
+  bars a three-step emphasis — `fill` at rest → `hover` under the pointer →
+  `highlight` (plus the outline) when selected. Previously one `highlight`
+  served both live states, so hover and select differed only by the presence of
+  an outline; `ScatterStyle` has carried distinct rest / selected treatments
+  (`outline` vs `selectedOutline`) all along, making bars the less expressive
+  layer for the same two-state interaction.
+
+  **Optional, with a `highlight` fallback**, so no existing theme changes
+  meaning or rendering — a theme that wants the distinction adds one colour.
+  Selection outranks hover on a bar that is both. Single-series only: a stacked
+  or per-bin-coloured bar has no separate highlight colour to replace (it pops
+  its _own_ fill, so a red/green volume bar keeps its meaning while live), and
+  that convention is unchanged.
+
+### Changed
+
+- **charts:** **a bar's capabilities now follow the mark it draws, not the
+  prop that fed it** ([PND-BARSEM], the 2026-08 API review's #2 item). A
+  **one-column vertical** histogram (`bins` + a single `column`) and a
+  one-entry `columns` draw exactly the mark a `series` + `column` chart
+  draws, but they used to route through the stacked path purely because of
+  which prop supplied them — and so silently lost whole-slot hit-testing
+  (#584), the `BarStyle.hover` colour, the cursor readout, stable per-bar
+  identity and per-bar decimation. They now take the single-series path, so
+  visually identical bars behave identically.
+
+  **What this changes in practice:** on a one-column histogram, hover and
+  click now hit the bar's **whole slot** rather than only the drawn
+  rectangle (so the space above a short bar is live, and slots tile the
+  axis); the layer gains a cursor readout; and `theme.bar.hover` applies.
+  A genuine multi-group stack, `categories`, and horizontal charts are
+  unchanged — their segments share a bin's x-range, so only y distinguishes
+  them. New reader `barsFromBins` backs the normalized path.
+
+  **Not a pure widening, in one respect:** dense-bar envelope decimation is
+  now live on a one-column histogram (it was single-series-only). It engages
+  only once bars fall under ~1px, where it is visually lossless, but at that
+  density the per-bar `gap` and highlight give way to envelope rects — pass
+  `decimate={false}` to keep every bar drawn. The `colors` map, the
+  `theme.bar[<column>]` role and `SelectInfo.label` are all preserved across
+  the reroute (each was a silent regression caught in review).
+
+  This shrinks `BarStyle.hover`'s scope warning from a list of five
+  path-accidents to the two real exclusions (a multi-group stack has no
+  hover channel on `StackStyle`; `binColors` keeps each bar's own colour by
+  design) — which was the acceptance test the task set itself.
+
+- **charts:** **column names and source modes are now checked at compile
+  time** ([PND-CHARTAPI], the 2026-08 API review's #1 item). Every draw
+  layer's column props are derived from the series' schema, so
+  `<LineChart series={cpu} column="cpuu" />` — and a numeric prop pointed at
+  a string column, where the schema has some other numeric column — fail to
+  **compile** instead of throwing at render; the
+  same holds for `readout`, the band edges, the box quantiles, and the OHLC
+  prices. `<BarChart>`'s props became a **union of its legal source modes**,
+  so mixing sources (`series` + `bins`) or column forms (`column` +
+  `columns`), or passing `categories` a `column`, are compile errors too.
+  `<BarList>` / `<BoxList>` get the same treatment for `rows` XOR `series`,
+  which additionally closes the row-type hole #590 documented (annotating a
+  callback with a custom row type while passing `series` claimed a shape the
+  series door cannot produce).
+
+  **This narrows what compiles — deliberately.** Code carrying a typo, an
+  illegal mode mix, or a lying row annotation stops building; that is the
+  point, and each case was already a runtime failure. Two compatibility
+  behaviours are preserved on purpose: a **loosely-typed** series
+  (`TimeSeries<SeriesSchema>`, e.g. from a helper that doesn't narrow) still
+  accepts any column name, because an unparameterized schema leaves the name
+  union open and nothing can be checked against it; and `bins` column names
+  stay `string`, since they name aggregate fields of a bin record rather than
+  schema columns. Note the deliberate distinction: a schema that _does_ name
+  its columns but has **no numeric one** rejects every name — there is nothing
+  numeric to plot — which is not the same as the loose case.
+
+  **One new limitation.** Because a layer's props are a union _per series
+  kind_, a value typed as _either_ kind (`TimeSeries<A> | ValueSeries<B>` — a
+  wrapper that forwards whatever it is given) matches no single member and
+  must be narrowed or cast at the boundary. `DurationAxis.stories.tsx` is the
+  worked example. The alternative design (one generic over the series type)
+  handles that case but changes every props type's public generic parameters;
+  the trade is recorded in `spikes/charts-type-seam/REPORT.md`.
+
+- **charts:** **a bar's hover / click target is now its whole slot**, not the
+  rectangle it draws. A bar _is_ the full width of its interval; the `gap` that
+  separates adjacent columns is a display affordance. Hit-testing the drawn
+  rect made that affordance interactive — the gap was a dead channel you could
+  point at and select nothing, and so was the empty plot space above a short
+  bar, even though the x-scrub cursor at that same x reported the bar quite
+  happily. `barAt` now tests the bar's full interval width and the full plot
+  height, so hover, click and the cursor readout all agree on which bar you are
+  on, and slots tile the axis.
+
+  **Widening, with one exception.** Points that previously selected _nothing_
+  now select the bar whose slot they fall in. The exception: a bar whose value
+  exceeds an explicit `<YAxis max>` used to draw — and be clickable — above the
+  plot top, in the strip a `'top'` axis title reserves; the slot stops at the
+  axis domain, so that sliver no longer hits. Everything inside the plot that
+  hit before still hits.
+
+  **It reaches across the full plot height, so it can shadow layers beneath
+  it.** The topmost hit wins, so a `<BarChart>` declared _after_ a
+  `<ScatterChart>` / `<BoxPlot>` / another `<BarChart>` in the same row now
+  claims every hit in its x-range at any y. Declare a bar layer **below** the
+  marks that should stay clickable.
+
+  **Single-series vertical only** — a stacked, `bins`, `categories` or
+  horizontal chart still hit-tests the drawn segment, because a stack's
+  segments share a bin's x-range and only y tells them apart.
+
+  Unchanged: a genuine hole between non-contiguous intervals still misses (the
+  change makes the drawing gap hittable, it doesn't invent coverage the data
+  lacks), a gap (`NaN`) bar owns no slot, and a shared edge goes to the left
+  bar — the rule `barIndexAtTime` already documented, so the two now agree by
+  construction.
+
+### Fixed
+
+- **process:** **audit hardening — five wrong-answer / silent-acceptance paths
+  in the plan layer closed** (external Codex audit, 2026-08; all reproduced,
+  all regression-pinned). Unit validation of a **picked output** read
+  `outputs[0]` instead of the selected output, so a picked `variance` was
+  refused where variance was demanded and — worse, silently — accepted where
+  price was. `Registry.define()` now rejects duplicate input roles and
+  duplicate output ids (both used to _collapse_ at run time rather than fail:
+  inputs resolved to the last role, outputs dropped the earlier column),
+  invalid param defaults, and `dependsOn` naming unknown params. An op result
+  whose length does not match the bound series is refused at the producer —
+  it used to ride out unchecked whenever `assemble: false` skipped the only
+  length check. The column-selection loop now honours `onError` (an operator
+  exception escaped `'collect'`), and a selector naming a nonexistent output
+  is a `skipped` entry instead of silently surfacing nothing. Fact provenance
+  (`id`, `name`, `op`, `unit`) now wins over a custom fold body's fields, and
+  `columnBytes` sums a chunked column's chunks instead of reporting 0 — which
+  a byte budget would read as "free".
+
+  Also: the derived fold slots in both builders now key by **params** —
+  `shape({points: 100})` after `shape({points: 20})` silently returned the
+  20-point node — and `shape` itself uses a `ceil` stride, so 200 points
+  asked of 399 rows returns ≤200 rather than all 399. The nested JSON Schema
+  projection can now express the `PickedOutput` input form, `Host` accepts
+  `budgetBytes` (the [PND-PROCCACHE] cap was unreachable from the long-lived
+  host shape) and grows `remove(id)`, and CI's package-content check covers
+  `@pond-ts/process`. Package remains **unpublished** (`private: true`).
+
+  A second audit round tightened the same seams. `columnBytes` now counts
+  what is actually retained: the **backing buffer's capacity** rather than
+  the column's logical length (core documents `_values` as possibly
+  oversized, so a one-row column viewing a 1000-slot buffer retains 8,000
+  bytes, not 8 — an undercount that defeats the budget), the chunk-offset
+  index and the bitmap's real bytes on chunked columns. The
+  **request-driven half of a `Host`'s footprint is now boundable**:
+  `runAsync` binds a graph per distinct caller-supplied `SourceRef`, so
+  `maxSources` caps registry-loaded sources LRU (author-added datasets are
+  never evicted), and a `remove()` racing an in-flight load now wins — the
+  landing load discards its result instead of resurrecting the dataset.
+  And an omitted param now unifies with its explicit default in the fluent
+  layer's derived fold slots (`shape()` ≡ `shape({points: 40})`, the same
+  rule `specId` applies), while the response labels a computation with the
+  **first** slot that named it rather than whichever was declared last.
+
+- **charts:** **a hovered or selected single-series bar now pops to full
+  opacity** ([#576](https://github.com/pond-ts/pond/issues/576)). `drawBars`
+  set `globalAlpha` once to the resting `style.opacity` and never lifted it for
+  the highlight **fill** on the single-series path — only for the selected
+  bar's outline. The per-bar-`binColors` branch in the same function and
+  `drawStacks` both already popped to 1, and `drawBars`' own docstring claimed
+  it did too. So on a theme with `opacity < 1` a **hovered** bar (which has no
+  outline) barely changed, and a **selected** one read only by its outline.
+  All three paths now treat the highlight fill identically.
+
+  **This changes pixels** on any single-series `<BarChart>` with an alpha'd
+  theme: highlighted bars are brighter. A theme that raised its base `opacity`
+  to compensate may now want it back down.
+
+  **It also flattens select against hover**, which is worth knowing before you
+  upgrade. The selected bar's outline strokes in `highlight` — previously that
+  read as a brighter ring over an alpha'd fill, and it was the main thing
+  separating a selected bar from a hovered one. Now the fill underneath is the
+  same colour at the same alpha, so only the half of the stroke falling
+  outside the rect distinguishes them. Hover is no longer nearly invisible,
+  but the two live states are closer together. A theme that needs them clearly
+  apart should set the new `BarStyle.hover`.
+
 ## [0.54.0] — 2026-08-02
 
+### Fixed
+
+- **core:** **`fromArrow` now reads a field's declared Arrow type instead of
+  guessing from the runtime shape of `toArray()`** — closing a
+  silent-corruption class. The reader worked out what a column held from what
+  `toArray()` handed back, which is correct for the types it supports and
+  quietly wrong outside them, because Arrow's physical layouts do not all store
+  one machine word per logical value. Measured, before the fix: **`Float16`
+  ingested `1.5` as `15872`** (its half-float bit pattern — the length matched,
+  so nothing caught it), and a **`Decimal128` column with a single null
+  ingested `123.45` as `12345`** (the per-element path produced exactly `rows`
+  values, so the length check never fired). A dense `Decimal` merely threw the
+  wrong error, blaming a length mismatch.
+
+  The readable set is now an explicit allowlist — `Int` (any width),
+  `Float32`/`Float64`, `Date32`/`Date64`, `Time32`/`Time64`, `Timestamp`,
+  `Utf8`/`LargeUtf8`/`Utf8View`, `Null` (an all-missing value column), and a
+  `Dictionary` of any of those (the encoding is transparent; readability
+  follows the value type) — checked per field, on the key and value columns of every
+  Arrow door (`TimeSeries.fromArrow`, `ValueSeries.fromArrow`, and the
+  flattened key edges). Anything else is refused **by name**, with the cast
+  that would fix it: `Decimal` names the float64 precision trade-off, `Float16`
+  says to cast, `Bool` names the real reason (the columnar ingest engine
+  carries `number` and `string` value columns only). A duck-typed stand-in
+  carrying no `typeId` keeps working — the `ArrowTableLike` contract is
+  deliberately structural — and gains a width check that catches the Decimal
+  shape anyway.
+
+  Behavioural change worth noting: a `Utf8` **key** now throws on its declared
+  type rather than on its shape, so the message names the type and points at
+  passing it as a value column instead.
+
+### Changed
+
+- **A fold no longer builds a `TimeSeries`** ([PND-PROCTERM]). Every node's
+  `compute` widened the source with `appendColumn` for each nested input, so
+  an op could call the corpus normally — the studies take
+  `(series, { column })`. For a fold that was waste twice over: the column it
+  reads is already in its inputs, and it was being packed into a series only
+  to be read straight back out.
+
+  The cost was not incidental. `appendColumn` **boxes a gapped column** on
+  the way in, because core's `withColumn` takes values rather than a column —
+  22.4 ms per column at 1M rows. Every rolling study is gapped, so the
+  expensive path was the ordinary one.
+
+  20 folds × 500k rows, on top of the columnar fold context below:
+  **383 → 129 ms** (2.96×), rss 173 → 113 MB. Against the boxed, assembling
+  baseline the two changes together are **606 → 129 ms**.
+
+  A facts-only request now returns no `series` at all, and the upstream
+  column still resolves through the node graph rather than the terminal's
+  `needed` set — so the failure the plan warned about, a fact silently
+  coming back with no value because its column was never selected, cannot
+  happen.
+
 ### Added
 
 - **`ctx.out` — prepared output buffers for a ranged recompute**

package/package.json

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