@jarenjs/core 0.46.5 → 0.56.0

package/ARCHITECTURE.md

@@ -109,7 +109,9 @@ flowchart TB
             DatesRfc["rfc3339.js<br/>RFC 3339 / ISO 8601"]
             DatesCivil["civil.js<br/>Gregorian day-number math"]
             DatesFormat["format.js<br/>LDML pattern compiler"]
+            DatesParse["parse.js<br/>LDML pattern parser"]
             DatesDuration["duration.js<br/>ISO 8601 durations"]
+            DatesTicks["ticks.js<br/>Time-axis step ladder"]
         end
 
         subgraph GeoModule["Spatial"]
@@ -130,6 +132,14 @@ flowchart TB
             VectorIndex["vector/index.js<br/>Similarity kernels, normalization, packed form"]
         end
 
+        subgraph SeriesModule["Temporal"]
+            SeriesIndex["series/index.js"]
+            SeriesSelector["selector.js<br/>Where a member lives in a row"]
+            SeriesNormalize["normalize.js<br/>Instants, stable sort, binary bounds"]
+            SeriesInterval["interval.js<br/>Half-open set algebra"]
+            SeriesTree["interval-index.js<br/>Prefix-max-end interval index"]
+        end
+
         subgraph MathModules["Mathematics"]
             MathIndex["math/index.js"]
             Int32Math["int32.js<br/>Fixed-point math"]
@@ -151,6 +161,15 @@ flowchart TB
 
         subgraph FunctionModule["Function Utilities"]
             FunctionUtil["function.js<br/>trueThat, falseThat"]
+            AsyncUtil["async.js<br/>Bounded ordered asynchronous map"]
+        end
+
+        subgraph RandomModule["Randomness"]
+            RandomUtil["random.js<br/>Seeded generator, integer draw, shuffle, distinct draw"]
+        end
+
+        subgraph StatsModule["Statistics"]
+            StatsUtil["stats.js<br/>Mean, sample variance, median, named quantile"]
         end
 
         subgraph StringModules["String &amp; Scanning"]
@@ -191,6 +210,7 @@ flowchart TB
     DatesIndex --> DatesCivil
     DatesIndex --> DatesFormat
     DatesIndex --> DatesDuration
+    DatesIndex --> DatesTicks
 
     GeoIndex --> GeoPred
     GeoIndex --> GeoDist
@@ -462,7 +482,9 @@ intermediate and is plain data, never an opaque handle.
 | `rfc3339.js` | validation, lexical decomposition, epoch conversion |
 | `civil.js` | proleptic Gregorian arithmetic over integers |
 | `format.js` | LDML pattern → compiled formatter |
+| `parse.js` | LDML pattern → compiled strict parser (the formatter's inverse) |
 | `duration.js` | ISO 8601 duration decomposition and date arithmetic |
+| `ticks.js` | the time-axis step ladder and its calendar boundaries |
 
 Calendar math goes through day numbers (`daysFromCivil`/`civilFromDays`),
 never through `Date`: the conversions are ~10 integer operations and allocate
@@ -475,6 +497,23 @@ allocates nothing per value. Formatting is the two-stage compiler again — a
 pattern is scanned once into a chain of appenders, which measured ~4.5×
 against re-scanning it per call.
 
+Parsing is the same compiler run backwards. `compileDateParser` scans a
+pattern once into a chain of readers and returns a function from text to the
+same parts record `parseRFC3339Parts` produces, so every calendar function
+takes its output unchanged. It is strict in three ways that a permissive
+reader is not: trailing input fails, an impossible civil date (31 February,
+hour 24) fails rather than rolling forward into the next month, and a
+fixed-width token reads exactly its width. Failure is `null` — malformed
+*text* is data — while a malformed *pattern* throws at compile time. The
+tokens that only ever format, because they are derived from a date rather
+than fields of one (`EEEE`, `DDD`, `ww`, `Q`), are compile errors with a
+message saying which and why, rather than tokens that quietly read nothing.
+A consumer whose patterns are not LDML — Mermaid's Gantt `dateFormat` is
+moment's grammar and its `axisFormat` is strftime — adapts its own tokens
+onto this vocabulary rather than handing its spelling to this compiler:
+LDML's `YYYY` is the week-numbering year, so `YYYY-MM-DD` read as LDML
+answers 2019 for 2018-12-31.
+
 Locale-dependent presentation (month and weekday names, meridiem, relative
 phrasing) is deliberately **not** here, so this package stays zero-dependency
 and free of data that drifts per language: `compileDateFormat` takes a names
@@ -532,11 +571,31 @@ import {
 const parts = parseRFC3339Parts('2026-01-31');
 addToParts(parts, 1, 'month');          // 2026-02-28 — month math clamps
 startOfParts(parts, 'week');            // the Monday of that week (ISO 8601)
+addToParts(parts, 3, 'hour');           // TypeError — a full-date has no clock
 
 const fmt = compileDateFormat("yyyy-'W'ww");  // compile once…
 fmt(parts);                             // …call many: '2026-W05'
+
+const read = compileDateParser('dd-MM-yyyy');
+read('06-01-2014');                     // { year: 2014, month: 1, day: 6, … }
+read('06-01-2014x');                    // null — trailing input
+read('31-02-2014');                     // null — February has no 31st
+```
+
+**Ticks a caller chose, or ticks this module chose:**
+
+```javascript
+import { axisTicksTime, timeTicksEvery } from '@jarenjs/core/dates';
+
+axisTicksTime(from, to, 4);                  // the ladder picks the step
+timeTicksEvery(from, to, 'week', 1, { weekStart: 7 });  // Sundays
 ```
 
+`axisTicksTime` is the chart axis's planner; `timeTicksEvery` is the same
+boundary rule with the step supplied, which is what a document declaring its
+own interval (Mermaid's `tickInterval 1week`) needs. One ladder, so a chart
+and a timeline cannot disagree about where a tick falls.
+
 ### 5b. Geo Module (`geo/`)
 
 The spatial kernel. As with dates, **there is no geometry type**: the
@@ -578,9 +637,9 @@ direction is *not* claimed, because WKT whitespace, the `M` measure and number
 spelling are normalized on the way through.
 
 Against [`wellknown`](https://www.npmjs.com/package/wellknown), the established
-WKT↔GeoJSON converter (`npm run benchmark:geo`, Node <!--bm:geo.node-->v24.19.0<!--/bm-->):
+WKT↔GeoJSON converter (`npm run benchmark:geo`, Node <!--fact:geo.node-->v24.19.0<!--/fact-->):
 
-<!--bm:geo.wktTable-->
+<!--fact:geo.wktTable-->
 | scenario | Jaren | rival | ratio |
 |---|---|---|---|
 | wkt parse (POINT) | 431.1 ns | 1.31 µs (wellknown) | **3.1×** |
@@ -588,7 +647,7 @@ WKT↔GeoJSON converter (`npm run benchmark:geo`, Node <!--bm:geo.node-->v24.19.
 | wkt stringify (2000-vertex polygon) | 163.40 µs | 229.70 µs (wellknown) | **1.4×** |
 | wkt validate (POINT) | 242.7 ns | 1.28 µs (wellknown) | **5.3×** |
 | wkt validate (2000-vertex polygon) | 496.00 µs | 1.90 ms (wellknown) | **3.8×** |
-<!--/bm-->
+<!--/fact-->
 
 The last two rows are the ones the sink exists for: `wellknown` has no
 predicate, so validating means parsing and throwing the geometry away. And the
@@ -627,7 +686,7 @@ RFC 7946 removed coordinate-reference-system support and mandates WGS 84, so
 there is no SRID table and no reprojection: conformance removes the need rather
 than an omission hiding it.
 
-**Measured against the field** (`npm run benchmark:geo`, Node <!--bm:geo.node-->v24.19.0<!--/bm-->). Every
+**Measured against the field** (`npm run benchmark:geo`, Node <!--fact:geo.node-->v24.19.0<!--/fact-->). Every
 scenario asserts result equivalence before any timing, and the harness refuses
 to print a table if the engines disagree: distance, area, length and bounding
 box come out *bit-identical* to Turf, containment agrees on a 400-point sweep,
@@ -635,7 +694,7 @@ and the index returns exactly Flatbush's answer on 200 queries. Ratios are the
 rival's time over this kernel's, so above 1 means Jaren is faster; the rows
 below derive from the committed measurement and are refreshed with it.
 
-<!--bm:geo.table-->
+<!--fact:geo.table-->
 | scenario | Jaren | rival | ratio |
 |---|---|---|---|
 | distance (two positions) | 28.3 ns | 111.0 ns (turf) | **3.9×** |
@@ -650,11 +709,11 @@ below derive from the committed measurement and are refreshed with it.
 | index build (100k boxes) | 12.70 ms | 10.62 ms (flatbush) | 0.8× |
 | index probe (100k boxes) | 602.3 ns | 668.9 ns (flatbush) | **1.1×** |
 | linear scan (100k boxes, no index) | 141.50 µs | — | — |
-<!--/bm-->
+<!--/fact-->
 
-The losses are kept, and named by the same measurement: on the committed run <!--bm:geo.losses-->three rows lose to a rival: point in polygon (2000-vertex) at 0.5× (turf), bounding box (2000-vertex) at 0.9× (turf), index build (100k boxes) at 0.8× (flatbush)<!--/bm-->.
+The losses are kept, and named by the same measurement: on the committed run <!--fact:geo.losses-->three rows lose to a rival: point in polygon (2000-vertex) at 0.5× (turf), bounding box (2000-vertex) at 0.9× (turf), index build (100k boxes) at 0.8× (flatbush)<!--/fact-->.
 **Point-in-polygon on a large ring runs at about half Turf's speed**
-(<!--bm:geo.pip2000-->0.5×<!--/bm--> at 2000 vertices) because every edge that could
+(<!--fact:geo.pip2000-->0.5×<!--/fact--> at 2000 vertices) because every edge that could
 matter goes through the exact orientation predicate, where Turf uses naive
 floating-point arithmetic. That is the trade this module exists to make — it
 is the difference between a containment test that is right on near-collinear
@@ -663,7 +722,7 @@ predicate on edges that cannot affect the answer, which took this from 0.2×
 to about 0.5×; the rest is the predicate itself, and the campaign that made
 geography reachable across the suite never traded it away. The bounding box
 of the same ring and the index build against Flatbush sit within a few tenths
-of level (<!--bm:geo.bbox2000-->0.9×<!--/bm--> and <!--bm:geo.indexBuild-->0.8×<!--/bm-->) and move
+of level (<!--fact:geo.bbox2000-->0.9×<!--/fact--> and <!--fact:geo.indexBuild-->0.8×<!--/fact-->) and move
 between runs and Node versions; they are published as measured rather than
 rounded to a win.
 
@@ -721,6 +780,60 @@ their reason to exist; they guarantee a finite answer. The fixed-arity vector
 classes in `math/` (`Vec2f64`, `Vec3f64`) are 2D/3D geometry with a
 different convention and a different job, and they stay where they are.
 
+### 5d. Series Module (`series/`)
+
+The temporal kernel: one meaning for an instant, one for a sorted series of
+readings, one for an interval, and the set algebra over them. As with dates,
+**there is no type** — an instant is epoch milliseconds or an RFC 3339 string,
+a sample is `{ at, value }`, an interval is `{ start, end }` — and, as with
+dates, **there is no `now`**: every bound is data, so every answer here is
+reproducible and cacheable.
+
+| File | Owns |
+|---|---|
+| `selector.js` | where a member lives in a caller's row — a property name or a function, so `on`/`recorded_at`/`from`/`to` are read where they are |
+| `normalize.js` | `toEpoch`, `normalizeSeries`, `normalizeIntervals` and the `lowerBoundTime`/`upperBoundTime` cuts a sorted array is read through |
+| `interval.js` | `containsInstant`, `overlapsInterval`, `intersectInterval`, `mergeIntervals`, `subtractIntervals`, `gapsWithin`, `coverageOf`, `findSlots` |
+| `interval-index.js` | `createIntervalIndex` — build once, query many, by point or by range |
+
+Four decisions carry it. **Half-open `[start, end)`**: an interval holds its
+start and not its end, so touching intervals neither overlap nor double-count
+and a boundary instant belongs to exactly one of them — while `mergeIntervals`
+*joins* touching spans by default, because availability means continuous cover,
+with `{ adjacent: false }` as the explicit other answer. **Nothing is dropped**:
+a member that names no instant, or an interval that is empty, reversed or
+non-finite, is a refusal naming the row rather than a silently shorter result,
+and the sort is stable so duplicate instants keep their order and both count.
+**No clock**: `gapsWithin` and `coverageOf` derive their window from the input's
+own hull when given none, because the only other default would be "now".
+
+And **the index cuts on both ends**. Sorting by start alone is the bug: a span
+that began long before a query sits far to the left of the query's own
+neighbourhood and still overlaps it, so a binary search around the query loses
+it while looking plausible. `createIntervalIndex` therefore carries a prefix
+maximum end beside the starts — non-decreasing by construction, hence
+binary-searchable — and the first position where it passes the query's start is
+the first position where anything can still be live. A query is two binary cuts
+and a walk between them, O(log n + k), returning the caller's own rows in a
+fresh array. Like the packed-Hilbert box index it is **static**: bounds are
+copied into flat typed arrays at build time, so a query reads no source object
+and a row mutated afterwards cannot change what the index answers.
+
+Buckets, resampling, rolling windows and as-of joins are the layer above this
+one; named zones, recurrence grammars and scheduling solvers are outside it.
+`findSlots` enumerates where a fixed-width span fits — choosing among the
+answers is a solver's job, deliberately not this kernel's.
+
+```javascript
+import { createIntervalIndex, mergeIntervals, findSlots } from '@jarenjs/core/series';
+
+const shifts = [{ start: 0, end: 4 * 3600_000 }, { start: 4 * 3600_000, end: 8 * 3600_000 }];
+mergeIntervals(shifts);                         // one span — touching IS continuous cover
+mergeIntervals(shifts, { adjacent: false });    // two — a handover is two shifts
+findSlots(shifts, { duration: 'PT30M' }).length; // 16
+createIntervalIndex(shifts).at(4 * 3600_000);   // the second shift only: [start, end)
+```
+
 ### 6. Text Module (`text/`)
 
 Comprehensive string format validation organized by domain.

package/README.md

@@ -1,6 +1,6 @@
 # @jarenjs/core
 
-The zero-dependency foundation of [Jaren](https://github.com/jklarenbeek/jarenjs). Everything the rest of the suite is built on lives here — type guards, Unicode-aware string handling, a large text-validation toolbox, number range helpers, fixed-point and vector math, the calendar kernel, the spatial kernel, the vector kernel, the message-catalog compiler, unit/currency conversion and a finance library.
+The zero-dependency foundation of [Jaren](https://github.com/jklarenbeek/jarenjs). Everything the rest of the suite is built on lives here — type guards, Unicode-aware string handling, a large text-validation toolbox, number range helpers, fixed-point and vector math, the calendar kernel, the spatial kernel, the vector kernel, the interval kernel, the message-catalog compiler, unit/currency conversion and a finance library.
 
 None of it depends on JSON Schema: every module can be used standalone in any JavaScript project.
 
@@ -13,6 +13,9 @@ None of it depends on JSON Schema: every module can be used standalone in any Ja
 | `@jarenjs/core/object` | deep equality (`equalsDeep`, JSON-only `equalsJson`), the `isJsonObject` and deep `isJsonValue` predicates, `__proto__`-safe `setObjectMember`, `deepFreeze`, map/set merging |
 | `@jarenjs/core/string` | Unicode string helpers (`countCodePoints`, `compareCodePoints`, ...), cached regex compilation, the suite's one content hash (`fnv1a` and the `hashContent` fingerprint over it) and `kebabCase` |
 | `@jarenjs/core/cache` | the bounded LRU (`createBoundedCache`), the reference-keyed `createWeakCache`, and `createSemanticCache` — keyed by what a value IS, for caches whose entries decide a result |
+| `@jarenjs/core/random` | the suite's one seeded generator (`mulberry32`, pinned sequence, ToUint32 seed) and the draws built on it: `randomInt` over a half-open range, in-place Fisher–Yates `shuffle`, and `drawDistinct` — `k` distinct indices from one stream |
+| `@jarenjs/core/stats` | descriptive statistics over a sample: `mean`, sample `variance`/`stddev`, the midpoint `median`, and `quantile(values, p, { method })` — `p` on 0..1 under a NAMED rule, `'nearest-rank'` or `'linear'`, because a default would decide silently; an empty sample answers `undefined`, never `0` |
+| `@jarenjs/core/async` | `mapConcurrent(items, limit, worker, { signal })` — the bounded ordered asynchronous map: never more than `limit` workers in flight, results in input order, a rejection or an abort stops dispatch and drains the lanes before the map rejects, so nothing is still running when it settles |
 | `@jarenjs/core/chunk` | cutting a value down to size: `sizeOf` (the suite's one size rule — a string is its length, anything else its JSON), `excerpt`, `truncate`, and `chunkText` by size, line or separator with offsets that locate a piece in its source |
 | `@jarenjs/core/scan` | char-code constants and predicates for recursive-descent parsers |
 | `@jarenjs/core/message` | the message template/catalog compiler shared by the validator and the form layer |
@@ -24,6 +27,7 @@ None of it depends on JSON Schema: every module can be used standalone in any Ja
 | `@jarenjs/core/dates` | RFC 3339 / ISO 8601 validation, plus the calendar kernel: integer date arithmetic, compiled formatting, durations |
 | `@jarenjs/core/geo` | the spatial kernel over GeoJSON: robust orientation, great-circle measurement, rings, bounding boxes, geohash, GeoJSON/WKT validity, a packed-Hilbert box index, Web Mercator and Douglas-Peucker simplification |
 | `@jarenjs/core/vector` | the vector kernel over plain arrays: dot, cosine and Euclidean similarity (higher-is-better; a malformed pair scores 0), l2 normalization, the packed little-endian Float32 form and the one shape guard (`isVector`) |
+| `@jarenjs/core/series` | the temporal kernel over plain records: instant/sample/interval normalization with a stable sort, half-open `[start, end)` set algebra (overlap, merge, subtract, gaps, coverage, slot enumeration), a static interval index, and the series operations built on them — fixed and calendar buckets with five fill policies, time-width rolling aggregates, as-of joins and gap-aware downsampling, on an injected zone seam |
 | `@jarenjs/core/text` | text validators: emails, hostnames, IPs, URIs/IRIs, UUIDs, punycode, ... |
 | `@jarenjs/core/math` | int32/float64 math and 2D/3D vector classes; the linear `remap` and unit-interval `clamp01` |
 | `@jarenjs/core/finance` | zero-dependency finance/trading formulas: TVM, cash flow, amortization, interest, depreciation, bonds, technical indicators, returns/risk |
@@ -65,7 +69,7 @@ Grouped by file: `email` (RFC 5321 + internationalized addresses), `host` (hostn
 
 ## Dates, numbers and math
 
-- `dates` — RFC 3339 date/time/date-time validation and parsing (leap years and month lengths included), the more lenient ISO date-time forms, and the suite's calendar kernel: proleptic Gregorian arithmetic over integer day numbers (`addToParts`, `startOfParts`, `endOfParts` — month math clamps, so 31 Jan plus a month is 28 Feb), ISO 8601 duration decomposition, and `compileDateFormat`, which turns an LDML pattern into a formatter once instead of re-scanning it per call. Dates stay JSON: an RFC 3339 string or epoch milliseconds, never a wrapper object. Locale names live in `@jarenjs/locales`, so a pattern needing `MMMM` takes a names provider. The full module reference is [docs/DATES.md](./docs/DATES.md).
+- `dates` — RFC 3339 date/time/date-time validation and parsing (leap years and month lengths included), the more lenient ISO date-time forms, and the suite's calendar kernel: proleptic Gregorian arithmetic over integer day numbers (`addToParts`, `startOfParts`, `endOfParts` — month math clamps, so 31 Jan plus a month is 28 Feb, and an operation reading a half the value has not got is refused rather than guessed), ISO 8601 duration decomposition, the locale-free time-axis step ladder (`niceTimeStep`, `axisTicksTime`, and `timeTicksEvery` for a step the caller declares) a chart and a timeline both read, and the two-stage pattern compilers `compileDateFormat` and its strict inverse `compileDateParser`, which turn an LDML pattern into a formatter or a parser once instead of re-scanning it per call — the parser refuses trailing input, an impossible civil date, and the tokens that only format because they are derived from a date rather than fields of one. Dates stay JSON: an RFC 3339 string or epoch milliseconds, never a wrapper object. Locale names live in `@jarenjs/locales`, so a pattern needing `MMMM` takes a names provider. The full module reference is [docs/DATES.md](./docs/DATES.md); the interval algebra built on top of it is [`series`](#intervals-and-series).
 - `integer`/`float`/`bigint` — range constants and validators for every fixed-width type from `int8` to `uint64` and `float16` to `float64`, including float increment/decrement in representable steps.
 - `math` — asm.js-style typed math (`Int32`, `Float64`) and vector classes (`Vec2i32`, `Vec2f64`, `Vec3f64`) with a fast integer sine approximation; reference in [docs/MATH.md](./docs/MATH.md).
 
@@ -97,7 +101,7 @@ Four design decisions carry the module:
 - **Orientation is computed exactly** (Shewchuk's adaptive predicates): a naive floating-point determinant returns the *wrong sign* on near-collinear input, which makes containment contradict itself. Every ring winding and point-in-polygon answer rests on this sign, and the deliberate cost is on the [benchmark page](https://jklarenbeek.github.io/jarenjs/#/benchmarks?suite=geo).
 - **Measurement is spherical, drawing is projected, and the two never mix.** A Euclidean norm on raw degrees is 64% wrong over 1 km at Dutch latitudes, so `haversineDistance`/`sphericalRingArea` work on the sphere (`equirectDistance` is the cheap screening form for rejecting candidates first), while `projectMercator`/`fitMercator` and `simplifyLine`/`simplifyRing` exist for renderers — never measure on a projected coordinate.
 - **Validity is a separate concern from traversal, and a box is refused rather than made too small.** `eachPosition`, `bboxOf`, `centroidOf` and friends measure without judging (a ring is read as closed whether or not it is); a box over any non-finite coordinate is `null`, never a plausible box that misses its input; and boxes never cross the antimeridian — cut the geometry at ±180° as RFC 7946 §3.1.9 asks, and every containment test and index probe is right. `isValidGeoJson` (structure plus the ring closure a JSON Schema provably cannot express), `isValidWkt` and `isValidGeohash` are the one-call judgments that back the `geoFormats` group in [`@jarenjs/formats`](../formats), next to the full GeoJSON meta-schema artifacts in [`@jarenjs/json`](../json).
-- **WKT is one grammar walk with two entry points.** `isValidWkt` and `wktToGeoJson` run the *same* scan, parameterized by a sink that is absent for the predicate and present for the parser — so the `wkt` format tester (which runs per value in the validator and per keystroke in the form layer) allocates nothing, and the two cannot drift apart. A committed corpus asserts `isValidWkt(s) === (wktToGeoJson(s) !== null)` for all 181 entries, malformed half included. `geoJsonToWkt` writes the string back, and `wktToGeoJson(geoJsonToWkt(g))` returns `g`; the text direction is *not* claimed, because whitespace, the `M` measure and number spelling are normalized. Against [`wellknown`](https://www.npmjs.com/package/wellknown) the parse is <!--bm:geo.wktParsePoint-->3.1×<!--/bm--> faster on a `POINT` and the yes-or-no answer <!--bm:geo.wktValidatePoint-->5.3×<!--/bm--> — and wellknown *validates less* while being slower, which is the honest framing; the table and every language difference are in [ARCHITECTURE](./ARCHITECTURE.md). The kernel's own losses are published there too, derived from the same run: <!--bm:geo.losses-->three rows lose to a rival: point in polygon (2000-vertex) at 0.5× (turf), bounding box (2000-vertex) at 0.9× (turf), index build (100k boxes) at 0.8× (flatbush)<!--/bm-->.
+- **WKT is one grammar walk with two entry points.** `isValidWkt` and `wktToGeoJson` run the *same* scan, parameterized by a sink that is absent for the predicate and present for the parser — so the `wkt` format tester (which runs per value in the validator and per keystroke in the form layer) allocates nothing, and the two cannot drift apart. A committed corpus asserts `isValidWkt(s) === (wktToGeoJson(s) !== null)` for all 181 entries, malformed half included. `geoJsonToWkt` writes the string back, and `wktToGeoJson(geoJsonToWkt(g))` returns `g`; the text direction is *not* claimed, because whitespace, the `M` measure and number spelling are normalized. Against [`wellknown`](https://www.npmjs.com/package/wellknown) the parse is <!--fact:geo.wktParsePoint-->3.1×<!--/fact--> faster on a `POINT` and the yes-or-no answer <!--fact:geo.wktValidatePoint-->5.3×<!--/fact--> — and wellknown *validates less* while being slower, which is the honest framing; the table and every language difference are in [ARCHITECTURE](./ARCHITECTURE.md). The kernel's own losses are published there too, derived from the same run: <!--fact:geo.losses-->three rows lose to a rival: point in polygon (2000-vertex) at 0.5× (turf), bounding box (2000-vertex) at 0.9× (turf), index build (100k boxes) at 0.8× (flatbush)<!--/fact-->.
 
 The spatial query operators (`$distance`, `$within`, `$geohash`, spatial joins over the box index) live in the query engine in [`@jarenjs/json`](../json); the streaming map chart that draws a FeatureCollection with bounded memory lives in [`@jarenjs/charts`](../../components/charts). The full module reference is [docs/GEO.md](./docs/GEO.md).
 
@@ -123,6 +127,49 @@ Three rules, kept by every function so that no caller has to check them again:
 
 The packed form is `4·d` bytes of little-endian binary32 — the value a database column stores; components round to `Math.fround` and come back exactly. Unpacking aligned bytes on a little-endian host is a *view*, not a copy, which is what a sweep over ten thousand fetched rows is paid for by; misaligned bytes (a pooled `Buffer`, an odd offset into a record) and big-endian hosts take the copy path to the same values. The client that produces embeddings — and a deterministic reference embedder for tests — lives in [`@jarenjs/ai`](../ai/README.md#embeddings).
 
+## Intervals and series
+
+`@jarenjs/core/series` is the suite's temporal kernel: one meaning for an interval, one meaning for a sorted series of timestamped readings, the set algebra over them, and the five operations every consumer of a timeline otherwise rebuilds by hand — bucket, fill, roll, join as-of, downsample. As with dates, there is no type — an instant is epoch milliseconds or an RFC 3339 string, a sample is `{ at, value }`, an interval is `{ start, end }` — so every value stays a plain JSON item, and nothing here reads a clock.
+
+```javascript
+import { createIntervalIndex, mergeIntervals, gapsWithin, findSlots } from '@jarenjs/core/series';
+
+const shifts = [
+  { from: '2026-03-02T09:00:00Z', to: '2026-03-02T13:00:00Z', who: 'ada' },
+  { from: '2026-03-02T13:00:00Z', to: '2026-03-02T17:00:00Z', who: 'grace' },
+];
+const index = createIntervalIndex(shifts, { start: 'from', end: 'to' });
+index.at('2026-03-02T13:00:00Z');        // [grace] — half-open, so the handover belongs to one shift
+
+const cover = shifts.map((s) => ({ start: s.from, end: s.to }));
+mergeIntervals(cover);                    // one span, 09:00–17:00 — touching IS continuous cover
+findSlots(cover, { duration: 'PT30M' });  // sixteen half-hour slots, one straddling the handover
+```
+
+```javascript
+import { resampleSeries, rollingSeries, asOfJoin, downsampleSeries } from '@jarenjs/core/series';
+
+resampleSeries(readings, { every: 'PT1H', aggregate: 'mean', fill: 'linear' });
+resampleSeries(readings, { every: 'P1M', zone: 'Europe/Amsterdam', provider });
+rollingSeries(readings, { width: 'PT5M', aggregate: 'max', minPeriods: 3 });
+asOfJoin(trades, quotes, { direction: 'nearest', tolerance: 'PT1S', key: 'symbol' });
+downsampleSeries(readings, { target: 2000 });   // → { points, sourceCount, renderedCount, method }
+```
+
+Seven decisions carry the module:
+
+- **Half-open, everywhere.** `[start, end)` holds its start and not its end, so a day ends exactly where the next begins, a boundary instant belongs to exactly one of two touching intervals, and nothing is counted twice. Touching intervals therefore do *not* overlap — back-to-back bookings are not a double booking — while `mergeIntervals` joins them by default, because availability asks whether there is continuous cover. `{ adjacent: false }` is the other answer, spelled out rather than guessed.
+- **A row is never dropped, and a duplicate is never merged away.** A member that cannot become a finite instant is a refusal naming the row, not a silently shorter result; an empty (`[t, t)`), reversed or non-finite interval is refused at the point it was written. The sort is stable, so two readings in the same millisecond keep their input order and both count.
+- **Nothing reads a clock.** `gapsWithin` and `coverageOf` derive their window from the input's own hull when given none, because the only other default would be "now" — and an operation that read the clock could not be cached, reproduced or run in a test twice.
+- **The index cuts on both ends, and cannot lose a long span.** Sorting by start alone is the bug: a conference week that began before an hourly meeting sits far to the left of that meeting's neighbourhood and still overlaps it. `createIntervalIndex` carries a prefix maximum end beside the starts — non-decreasing, so binary-searchable — and a query becomes two binary cuts and a walk between them, O(log n + k), returning the caller's own rows. It is static: bounds are copied at build time, so a query reads no source object and a row mutated afterwards changes nothing.
+
+- **Bucketing is arithmetic; filling is a policy.** An average over an empty hour is not zero, and it is not yesterday's average, and it is not nothing — it is whichever of `omit | null | zero | locf | linear` the caller asked for, and the aggregate had no opinion. `count` reports source rows (duplicates and measured gaps included) beside every value, so `null` and "nobody reported" are distinguishable. Neither `locf` nor `linear` invents a value at the leading edge.
+- **A rolling window is a duration, not a row count.** Sixty rows of a sensor reporting every second is a minute; sixty rows of a sensor that dropped half its readings is two minutes. The window is `(at − width, at]`, so two readings in the same millisecond share it and therefore share an answer. `sum`/`mean`/`count` carry a running total, `min`/`max` use a monotone deque, `first`/`last` are forward-only pointers — the complexity is structural, and the tests count the reads rather than the milliseconds.
+- **Time zones are injected, never bundled.** UTC and fixed offsets work with no setup; a named zone takes the caller's own `provider`, because a bundled tzdb is megabytes that go stale on a government's timetable. A local time that never happened, or happened twice, is a refusal unless `disambiguation` says `earlier` or `later`. A sampler never bridges a gap, never moves an end, and refuses a target too small to hold both rather than drawing a prettier line.
+- **A specification is closed.** Every kernel that takes one publishes the members it admits, and anything else is a refusal naming the near miss — because `minPeriod` for `minPeriods` quietly ignored is a window with no minimum and a plausible number to show for it, and `timezone` for `zone` is precisely the silent fall back to UTC the injected clock exists to prevent. The query language reads the same lists, minus the `provider`, which is a pair of functions and therefore not something a document can carry.
+
+The kernel is measured against one-pass loops written for one question and against the query vocabulary a consumer had instead, and both ratios are published: it costs about twice a hand-written loop and answers about a hundred times faster than the generic route. Named time zones' data, recurrence grammars and scheduling solvers are deliberately outside it. The full module reference is [docs/SERIES.md](./docs/SERIES.md).
+
 ## Messages
 
 `@jarenjs/core/message` is the template/catalog compiler behind the validator's uniform error messages and the form layer's labels — msgid plus parameters in, rendered text out, so every message is translatable by swapping a catalog ([`@jarenjs/locales`](../locales) ships eleven language packs over it):

package/dist/types/async.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @file The bounded ordered asynchronous map: run a worker over a list
+ * with never more than `limit` calls in flight, and answer the results
+ * in the list's order. Before this file the same twelve lines lived in
+ * the AI package's program runner and in the benchmark harness, and a
+ * downstream consumer had written them a third time; a pool that exists
+ * once is one whose edge behavior can be pinned once.
+ *
+ * The contract, in full:
+ *
+ *  - results are in INPUT order, whatever order the workers finish in;
+ *  - never more than `limit` workers are in flight; `limit` must be a
+ *    number of at least 1 (`Infinity` is allowed and means unbounded) —
+ *    anything else is a `TypeError`, never a silent clamp, because a
+ *    limit of 0 is a bug in the caller and "sequential" is spelled 1;
+ *  - a worker rejection stops dispatch: no item starts after it, the
+ *    workers already in flight are awaited, and only then does the map
+ *    reject with that first rejection. A worker that throws
+ *    synchronously is a rejection;
+ *  - an abort does the same, rejecting with the signal's reason; a signal
+ *    that is already aborted rejects before any worker runs;
+ *  - so when the returned promise settles, NO worker is still running —
+ *    the caller can close whatever the workers were using.
+ *
+ * The map does not retry, rate-limit, delay per origin or know anything
+ * about what the worker does; those are the caller's policies around it.
+ */
+/**
+ * @template T, R
+ * @param {readonly T[]} items
+ * @param {number} limit - workers in flight at once; a number >= 1, `Infinity` for unbounded
+ * @param {(item: T, index: number) => Promise<R> | R} worker
+ * @param {{ signal?: AbortSignal }} [options]
+ * @returns {Promise<R[]>} the results, in input order
+ * @throws {TypeError} (as a rejection) when `limit` is not a number >= 1
+ */
+export declare function mapConcurrent<T, R>(items: readonly T[], limit: number, worker: (item: T, index: number) => Promise<R> | R, options?: {
+    signal?: AbortSignal;
+}): Promise<R[]>;

package/dist/types/dates/civil.d.ts

@@ -111,36 +111,55 @@ export declare function fixedUnitMs(unit: string): number;
 /**
  * Add a signed amount of calendar units to a parts record, returning a
  * new one. The input is never mutated and its lexical shape is kept: a
- * full-date stays a full-date, and a value keeps its own UTC offset
- * rather than being normalized.
+ * full-date stays a full-date, a full-time stays a full-time, and a
+ * value keeps its own UTC offset rather than being normalized.
  *
  * Month and year arithmetic **clamps** to the end of the target month —
  * 2026-01-31 plus one month is 2026-02-28 — which is the rule every
  * mainstream date library uses, because the alternative (overflowing
  * into March) makes `add(1, 'month')` non-monotonic.
  *
+ * A fraction is a quantity only where the unit has an exact conversion.
+ * A fixed-width fraction becomes whole milliseconds, so `1.5 day` is
+ * thirty-six hours; a calendar fraction is refused unless it lands on a
+ * whole month, because half of January is not a length. The clock those
+ * milliseconds land on has to exist: a full-date can be moved by whole
+ * days but not by half of one.
+ *
  * @param {object} parts - a parts record from `parseRFC3339Parts`
- * @param {number} amount - signed count, may be fractional only for
- *   fixed-width units (a fractional month has no meaning)
+ * @param {number} amount - signed count, fractional only where the unit
+ *   converts exactly and the value has the half to carry it
  * @param {string} unit - a {@link DATE_UNITS} member
  * @returns {object} a new parts record
+ * @throws {TypeError} for an unknown unit, a fraction with no exact
+ *   conversion, or a value missing a half the operation reads
  */
 export declare function addToParts(parts: object, amount: number, unit: string): object;
 /**
  * Truncate a parts record to the start of a calendar unit, returning a
  * new one. `week` starts on Monday (ISO 8601).
+ *
+ * `day` and coarser name a boundary the calendar has, so the start of
+ * the day of a full-time is midnight. A sub-day unit names a boundary
+ * inside a day, which a value with no clock does not have, and is
+ * refused rather than answered from a clock that is not there.
+ *
  * @param {object} parts - a parts record
  * @param {string} unit - a {@link DATE_UNITS} member
  * @returns {object} a new parts record
+ * @throws {TypeError} for an unknown unit, or a value missing a half
+ *   the truncation reads
  */
 export declare function startOfParts(parts: object, unit: string): object;
 /**
  * The last representable instant inside a calendar unit: the start of
  * the next unit less one millisecond. A value with no time half is
  * truncated to the unit's last *day* instead, so a full-date stays a
- * full-date.
+ * full-date, and it refuses the same sub-day units `startOfParts` does.
  * @param {object} parts - a parts record
  * @param {string} unit - a {@link DATE_UNITS} member
  * @returns {object} a new parts record
+ * @throws {TypeError} for an unknown unit, or a value missing a half
+ *   the truncation reads
  */
 export declare function endOfParts(parts: object, unit: string): object;

package/dist/types/dates/index.d.ts

@@ -1,4 +1,6 @@
 export * from './rfc3339.js';
 export * from './civil.js';
 export * from './format.js';
+export * from './parse.js';
 export * from './duration.js';
+export * from './ticks.js';

package/dist/types/dates/parse.d.ts

@@ -0,0 +1,47 @@
+export type Reader = (text: string, i: number, out: any) => number;
+/**
+ * Compile an LDML date pattern into a strict parser.
+ *
+ * The returned function takes a string and returns a parts record in
+ * exactly the shape `parseRFC3339Parts` produces — so
+ * `epochOfRFC3339Parts`, `formatRFC3339Parts`, `addToParts` and every
+ * other calendar function accept it unchanged — or `null` when the text
+ * does not match. Failure is `null`, never a throw and never a partial
+ * record: a malformed *pattern* is the programmer's error and throws at
+ * compile time; malformed *text* is data and is reported as no match.
+ *
+ * Strict means three things:
+ *
+ * 1. **Full consumption.** Trailing text fails; `yyyy-MM-dd` does not
+ *    read `2026-01-02T03:04`.
+ * 2. **Impossible civil dates fail.** 31 February and hour 24 are not
+ *    silently rolled forward into March and the next day.
+ * 3. **Fixed-width tokens are fixed width.** `MM` reads exactly two
+ *    digits, `M` one or two, and neither reads three.
+ *
+ * The lexical family of the result follows the pattern: a pattern with
+ * only date tokens yields a full-date (`hours`/`minutes`/`seconds` are
+ * the contract's `-1`), one with only time tokens a full-time
+ * (`year`/`month`/`day` are `-1`), and one with both a date-time. A
+ * pattern with no field token at all is a compile error — it could only
+ * ever return the same empty record.
+ *
+ * Two tokens are not strict inverses of an arbitrary value and are
+ * documented rather than refused: `yy` reads 00–68 as 2000–2068 and
+ * 69–99 as 1969–1999 (the POSIX pivot moment uses), and `h`/`hh`
+ * without an `a` in the same pattern read as the morning, so 12 is
+ * midnight. Both round-trip their own spelling exactly.
+ *
+ * @param {string} pattern - an LDML pattern, e.g. `'yyyy-MM-dd'`
+ * @param {import('./format.js').DateNames} [names] - locale names, required only if the
+ *   pattern uses `MMM`/`MMMM`/`a`
+ * @returns {(text: string) => object | null} the compiled parser
+ * @throws {TypeError} on an unterminated quote, a derived token, a name
+ *   token with no provider, or a pattern that reads no field
+ * @example
+ * const read = compileDateParser('dd-MM-yyyy');
+ * read('06-01-2014');  // { year: 2014, month: 1, day: 6, hours: -1, … }
+ * read('06-01-2014x'); // null — trailing input
+ * read('31-02-2014');  // null — February has no 31st
+ */
+export declare function compileDateParser(pattern: string, names?: import('./format.js').DateNames): (text: string) => object | null;

package/dist/types/dates/ticks.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Choose the calendar step closest to covering `span` in `count` ticks.
+ *
+ * A year is the coarsest unit a calendar has, so above one year the
+ * ladder continues as whole years on the same 1/2/5×10^k steps — 2, 5,
+ * 10, 50, 1000 years. Without that continuation a millennial domain
+ * asks for one tick per year and runs out of axis long before it runs
+ * out of domain.
+ *
+ * @param {number} span - Domain width in milliseconds
+ * @param {number} count - Desired tick count
+ * @returns {[string, number]} a [unit, amount] pair
+ */
+export declare function niceTimeStep(span: number, count: number): [string, number];
+/**
+ * Time ticks on calendar boundaries: the first tick is the start of a
+ * `[unit, amount]` step at or after `min`, and each following one is a
+ * whole step later. A multi-unit step lands on a multiple of its own
+ * amount — months on 1, 4, 7, 10 and years on 1900, 1950, 2000 — so an
+ * axis reads as a calendar rather than as offsets from wherever the
+ * data happened to start.
+ *
+ * @param {number} min - Domain minimum, epoch milliseconds
+ * @param {number} max - Domain maximum, epoch milliseconds
+ * @param {number} [count] - Desired tick count (approximate)
+ * @returns {number[]} tick values in epoch milliseconds
+ */
+export declare function axisTicksTime(min: number, max: number, count?: number): number[];
+/**
+ * Time ticks on a step the CALLER chose, rather than one this module
+ * picked for a target count: the first tick is the start of the
+ * `amount`-wide `unit` at or after `min`, and each following one is a
+ * whole step later. This is the boundary rule {@link axisTicksTime}
+ * uses once it has decided a step, exposed on its own because a
+ * consumer whose document declares its own interval — Mermaid's Gantt
+ * `tickInterval 1week` is the one in this repo — needs the same
+ * boundaries without the ladder choosing for it.
+ *
+ * A multi-unit step lands on a multiple of its own amount, so months
+ * fall on 1, 4, 7, 10 and years on 1900, 1950, 2000. A `week` step
+ * starts on Monday unless `weekStart` names another ISO weekday, which
+ * is what a document that says "weeks begin on Sunday" means.
+ *
+ * @param {number} min - Domain minimum, epoch milliseconds
+ * @param {number} max - Domain maximum, epoch milliseconds
+ * @param {string} unit - a `DATE_UNITS` member (`'day'`, `'week'`, …)
+ * @param {number} [amount] - whole steps per tick, at least 1
+ * @param {{ weekStart?: number, limit?: number }} [options] -
+ *   `weekStart` is an ISO weekday, 1 (Monday) to 7 (Sunday);
+ *   `limit` caps the tick count (default 1000)
+ * @returns {number[]} tick values in epoch milliseconds
+ * @example
+ * timeTicksEvery(Date.UTC(2024, 0, 3), Date.UTC(2024, 0, 20), 'week', 1);
+ * // the Mondays of 2024-01-08 and 2024-01-15
+ */
+export declare function timeTicksEvery(min: number, max: number, unit: string, amount?: number, options?: {
+    weekStart?: number;
+    limit?: number;
+}): number[];

package/dist/types/math/float64.d.ts

@@ -222,6 +222,19 @@ export declare function remap(v: number, smin: number, smax: number, dmin: numbe
  * @returns {number}
  */
 export declare function niceStep(span: number, count?: number): number;
+/**
+ * Ticks on the {@link niceStep} ladder inside `[min, max]`: every whole
+ * multiple of the step the domain contains, rounded to the step's own
+ * precision so an axis never shows `0.30000000000000004`. A degenerate
+ * domain yields a single tick, a reversed one reads the same as its
+ * forward twin, and a non-finite bound yields nothing.
+ *
+ * @param {number} min - Domain minimum
+ * @param {number} max - Domain maximum
+ * @param {number} [count] - Desired tick count (approximate)
+ * @returns {number[]}
+ */
+export declare function axisTicksLinear(min: number, max: number, count?: number): number[];
 /**
  * Clamp a value into the unit interval `[0, 1]` — the fraction every
  * unit-space geometry stage emits. `NaN` passes through as `NaN` rather