@jarenjs/core 0.49.2 → 0.66.1

package/ARCHITECTURE.md

@@ -161,6 +161,19 @@ flowchart TB
 
         subgraph FunctionModule["Function Utilities"]
             FunctionUtil["function.js<br/>trueThat, falseThat"]
+            AsyncUtil["async.js<br/>Bounded ordered asynchronous map, awaited sink"]
+        end
+
+        subgraph RandomModule["Randomness"]
+            RandomUtil["random.js<br/>Seeded generator, integer draw, shuffle, distinct draw"]
+        end
+
+        subgraph RuntimeModule["Host runtime"]
+            RuntimeRecord["runtime.js<br/>The runtime record: clock, identifiers, randomness, zone provider"]
+        end
+
+        subgraph StatsModule["Statistics"]
+            StatsUtil["stats.js<br/>Mean, sample variance, median, named quantile"]
         end
 
         subgraph StringModules["String &amp; Scanning"]
@@ -628,9 +641,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×** |
@@ -638,7 +651,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
@@ -677,7 +690,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,
@@ -685,7 +698,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×** |
@@ -700,11 +713,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
@@ -713,7 +726,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.
 
@@ -825,6 +838,36 @@ findSlots(shifts, { duration: 'PT30M' }).length; // 16
 createIntervalIndex(shifts).at(4 * 3600_000);   // the second shift only: [start, end)
 ```
 
+### 5e. Runtime record (`runtime.js`)
+
+The one record a host hands to every subsystem that needs a host fact:
+`createRuntime({ now, uuid, random, zoneProvider })`, frozen, defaulting
+member for member to the platform's own (`Date.now`, `crypto.randomUUID`,
+`Math.random`, and no zone provider — a named zone stays a refusal). The
+store (query deadlines included), the job engine, the migration runner, the
+contract bindings and the contract memory ledger take it as `runtime`; a
+subsystem's own explicit option wins over the record's member,
+which wins over the built-in default, so adopting the record changes nothing
+observable and a deterministic run — a fixed clock, a seeded generator, a
+counting identifier — is configured once. It is a type plus a freeze: this
+module reads no clock and draws no number of its own, and it reaches hosts,
+never query compilation, because a compiled query is cached by document
+identity and there is no `now` in the kernel for it to feed.
+
+```javascript
+import { createRuntime } from '@jarenjs/core/runtime';
+import { mulberry32 } from '@jarenjs/core/random';
+
+let n = 0;
+const runtime = createRuntime({
+  now: () => 1_700_000_000_000,
+  uuid: () => `id-${++n}`,
+  random: mulberry32(2026),
+});
+runtime.zoneProvider;                       // null — the one member left at its default
+createRuntime({ clock: Date.now });          // TypeError: a runtime record has 'now', 'uuid', 'random', 'zoneProvider', not 'clock'
+```
+
 ### 6. Text Module (`text/`)
 
 Comprehensive string format validation organized by domain.

package/README.md

@@ -13,6 +13,10 @@ 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/runtime` | the runtime record — `createRuntime({ now, uuid, random, zoneProvider })`, frozen, defaulting member for member to the platform's own (`Date.now`, `crypto.randomUUID`, `Math.random`, no zone provider) — that the store (its query deadlines included), the jobs engine, the migration runner, every contract binding and the contract memory ledger take as `runtime`, so a deterministic run is configured once; a subsystem's own explicit option wins over the record, and the record reaches hosts, never query compilation |
+| `@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; and `createAwaitedSink(sink)` — the suite's one write serializer: every `write` waits for the previous one to settle (a sink may answer a promise — a socket waiting for `drain`, a stream waiting for the consumer's pull), `end` waits for every write, `abort` rejects what is still queued at once, one failure stops everything behind it, and a synchronous sink stays on a no-promise fast path |
 | `@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 |
@@ -98,7 +102,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).
 
@@ -187,6 +191,110 @@ t({ comparison: '>=', limit: 18 });   // 'must be >= 18'
 
 The JSON addressing and query standards — JSON validation helpers, JSON Pointer (RFC 6901), the compiling JSONPath engine (RFC 9535), and the Jaren JSON Query language with its XQuery front-end — live in [`@jarenjs/json`](../json). This package supplies their foundations: the char-code scanner (`@jarenjs/core/scan`), `equalsJson` deep equality, code-point ordering, and the I-Regexp (RFC 9485) toolbox.
 
+## Exports
+
+Every subpath a consumer can import, derived from the manifest by
+`npm run docs:derive` (`npm run docs:check` fails when the two drift):
+
+<!--fact:exports.core-->
+| Import | Kind | Declarations |
+|---|---|---|
+| `@jarenjs/core` | JavaScript | declared |
+| `@jarenjs/core/array` | JavaScript | declared |
+| `@jarenjs/core/async` | JavaScript | declared |
+| `@jarenjs/core/bigint` | JavaScript | declared |
+| `@jarenjs/core/cache` | JavaScript | declared |
+| `@jarenjs/core/chunk` | JavaScript | declared |
+| `@jarenjs/core/color` | JavaScript | declared |
+| `@jarenjs/core/dates` | JavaScript | declared |
+| `@jarenjs/core/errors` | JavaScript | declared |
+| `@jarenjs/core/dates/civil` | JavaScript | declared |
+| `@jarenjs/core/dates/duration` | JavaScript | declared |
+| `@jarenjs/core/dates/format` | JavaScript | declared |
+| `@jarenjs/core/dates/index` | JavaScript | declared |
+| `@jarenjs/core/dates/parse` | JavaScript | declared |
+| `@jarenjs/core/dates/rfc3339` | JavaScript | declared |
+| `@jarenjs/core/dates/ticks` | JavaScript | declared |
+| `@jarenjs/core/float` | JavaScript | declared |
+| `@jarenjs/core/geo` | JavaScript | declared |
+| `@jarenjs/core/geo/angle` | JavaScript | declared |
+| `@jarenjs/core/geo/bbox` | JavaScript | declared |
+| `@jarenjs/core/geo/distance` | JavaScript | declared |
+| `@jarenjs/core/geo/geohash` | JavaScript | declared |
+| `@jarenjs/core/geo/geojson` | JavaScript | declared |
+| `@jarenjs/core/geo/index` | JavaScript | declared |
+| `@jarenjs/core/geo/index-tree` | JavaScript | declared |
+| `@jarenjs/core/geo/mercator` | JavaScript | declared |
+| `@jarenjs/core/geo/predicates` | JavaScript | declared |
+| `@jarenjs/core/geo/ring` | JavaScript | declared |
+| `@jarenjs/core/geo/simplify` | JavaScript | declared |
+| `@jarenjs/core/geo/valid` | JavaScript | declared |
+| `@jarenjs/core/geo/wkt` | JavaScript | declared |
+| `@jarenjs/core/vector` | JavaScript | declared |
+| `@jarenjs/core/function` | JavaScript | declared |
+| `@jarenjs/core/integer` | JavaScript | declared |
+| `@jarenjs/core/message` | JavaScript | declared |
+| `@jarenjs/core/number` | JavaScript | declared |
+| `@jarenjs/core/object` | JavaScript | declared |
+| `@jarenjs/core/random` | JavaScript | declared |
+| `@jarenjs/core/runtime` | JavaScript | declared |
+| `@jarenjs/core/scan` | JavaScript | declared |
+| `@jarenjs/core/schema` | JavaScript | declared |
+| `@jarenjs/core/series` | JavaScript | declared |
+| `@jarenjs/core/series/asof` | JavaScript | declared |
+| `@jarenjs/core/series/bucket` | JavaScript | declared |
+| `@jarenjs/core/series/downsample` | JavaScript | declared |
+| `@jarenjs/core/series/index` | JavaScript | declared |
+| `@jarenjs/core/series/interval` | JavaScript | declared |
+| `@jarenjs/core/series/interval-index` | JavaScript | declared |
+| `@jarenjs/core/series/normalize` | JavaScript | declared |
+| `@jarenjs/core/series/rolling` | JavaScript | declared |
+| `@jarenjs/core/series/selector` | JavaScript | declared |
+| `@jarenjs/core/series/zone` | JavaScript | declared |
+| `@jarenjs/core/stats` | JavaScript | declared |
+| `@jarenjs/core/string` | JavaScript | declared |
+| `@jarenjs/core/text` | JavaScript | declared |
+| `@jarenjs/core/text/base64` | JavaScript | declared |
+| `@jarenjs/core/text/basic` | JavaScript | declared |
+| `@jarenjs/core/text/email` | JavaScript | declared |
+| `@jarenjs/core/text/host` | JavaScript | declared |
+| `@jarenjs/core/text/i18n` | JavaScript | declared |
+| `@jarenjs/core/text/identifiers` | JavaScript | declared |
+| `@jarenjs/core/text/index` | JavaScript | declared |
+| `@jarenjs/core/text/iregexp` | JavaScript | declared |
+| `@jarenjs/core/text/misc` | JavaScript | declared |
+| `@jarenjs/core/text/punycode` | JavaScript | declared |
+| `@jarenjs/core/text/sse` | JavaScript | declared |
+| `@jarenjs/core/math` | JavaScript | declared |
+| `@jarenjs/core/math/float64` | JavaScript | declared |
+| `@jarenjs/core/math/format` | JavaScript | declared |
+| `@jarenjs/core/math/index` | JavaScript | declared |
+| `@jarenjs/core/math/int32` | JavaScript | declared |
+| `@jarenjs/core/math/mat4` | JavaScript | declared |
+| `@jarenjs/core/math/project` | JavaScript | declared |
+| `@jarenjs/core/math/solve` | JavaScript | declared |
+| `@jarenjs/core/math/vec2f64` | JavaScript | declared |
+| `@jarenjs/core/math/vec2i32` | JavaScript | declared |
+| `@jarenjs/core/math/vec3f64` | JavaScript | declared |
+| `@jarenjs/core/math/word` | JavaScript | declared |
+| `@jarenjs/core/finance` | JavaScript | declared |
+| `@jarenjs/core/finance/amortization` | JavaScript | declared |
+| `@jarenjs/core/finance/bond` | JavaScript | declared |
+| `@jarenjs/core/finance/cashflow` | JavaScript | declared |
+| `@jarenjs/core/finance/depreciation` | JavaScript | declared |
+| `@jarenjs/core/finance/index` | JavaScript | declared |
+| `@jarenjs/core/finance/indicators` | JavaScript | declared |
+| `@jarenjs/core/finance/interest` | JavaScript | declared |
+| `@jarenjs/core/finance/returns` | JavaScript | declared |
+| `@jarenjs/core/finance/tvm` | JavaScript | declared |
+| `@jarenjs/core/convert` | JavaScript | declared |
+| `@jarenjs/core/convert/convert` | JavaScript | declared |
+| `@jarenjs/core/convert/currency` | JavaScript | declared |
+| `@jarenjs/core/convert/index` | JavaScript | declared |
+| `@jarenjs/core/convert/registry` | JavaScript | declared |
+| `@jarenjs/core/package.json` | metadata | — |
+<!--/fact-->
+
 ## Development
 
 Unit tests live in `test/core/` at the repository root (`npm run test:core`). This package's internals are described in its own [ARCHITECTURE](./ARCHITECTURE.md) document, with per-module references under [docs/](./docs/) (`MATH`, `CONVERT`, `FINANCE`, `DATES`, `GEO`); see the repository [README](../../README.md) and [ARCHITECTURE](../../docs/ARCHITECTURE.md) for the monorepo picture, and the [ROADMAP](../../docs/ROADMAP.md) for planned work.

package/dist/types/async.d.ts

@@ -0,0 +1,142 @@
+/**
+ * @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[]>;
+export type SinkLike<T> = {
+    write: (chunk: T) => unknown;
+    end?: () => unknown;
+    abort?: (reason: unknown) => unknown;
+};
+export type AwaitedSink<T> = {
+    /**
+     * - queue one
+     * chunk behind every earlier write; `undefined` when the underlying
+     * write answered synchronously with nothing pending (the fast path),
+     * else a promise that settles when the underlying write did
+     */
+    write: (chunk: T) => Promise<void> | undefined;
+    /**
+     * - queue the underlying `end` once
+     * after every write; repeated calls answer the same promise
+     */
+    end: () => Promise<void>;
+    /**
+     * - stop accepting
+     * writes, reject the writes still queued, and call the underlying
+     * `abort` once, immediately; repeated calls answer the same promise
+     */
+    abort: (reason?: unknown) => Promise<void>;
+    /**
+     * - whether a write rejected or an abort
+     * happened; nothing reaches the underlying sink after that
+     */
+    failed: () => boolean;
+    /**
+     * - whether `end` or `abort` was called
+     */
+    closed: () => boolean;
+};
+/**
+ * The underlying sink an awaited sink serializes: `write` answers a
+ * value (the chunk is written) or a promise (the chunk is written when
+ * it settles — a socket waiting for `drain`, a stream waiting for the
+ * consumer's next pull); `end` and `abort` are optional and may answer
+ * either way too.
+ * @template T
+ * @typedef {Object} SinkLike
+ * @property {(chunk: T) => unknown} write
+ * @property {() => unknown} [end]
+ * @property {(reason: unknown) => unknown} [abort]
+ */
+/**
+ * The serialized, awaited view of a sink.
+ * @template T
+ * @typedef {Object} AwaitedSink
+ * @property {(chunk: T) => Promise<void> | undefined} write - queue one
+ *   chunk behind every earlier write; `undefined` when the underlying
+ *   write answered synchronously with nothing pending (the fast path),
+ *   else a promise that settles when the underlying write did
+ * @property {() => Promise<void>} end - queue the underlying `end` once
+ *   after every write; repeated calls answer the same promise
+ * @property {(reason?: unknown) => Promise<void>} abort - stop accepting
+ *   writes, reject the writes still queued, and call the underlying
+ *   `abort` once, immediately; repeated calls answer the same promise
+ * @property {() => boolean} failed - whether a write rejected or an abort
+ *   happened; nothing reaches the underlying sink after that
+ * @property {() => boolean} closed - whether `end` or `abort` was called
+ */
+/**
+ * Serialize a sink: every write waits for the previous one, `end` waits
+ * for every write, and one failure stops everything after it. This is
+ * the one place the suite decides what "the next chunk" means for a
+ * sink that may answer a promise — a Node response whose `write()` said
+ * `false` (wait for `drain`), a Web `ReadableStream` bridge that waits
+ * for the consumer's pull, a stream runner whose carrier hooks may be
+ * asynchronous — so backpressure is a property of the sink, never of
+ * the code writing into it.
+ *
+ * The contract, in full:
+ *
+ *  - writes reach the underlying sink in call order and never overlap:
+ *    the next underlying write begins only after the previous one
+ *    settled;
+ *  - a synchronous sink stays on a no-extra-promise fast path: while
+ *    nothing is pending and the underlying write answers a non-thenable,
+ *    `write` answers `undefined`; the first thenable answer opens the
+ *    queue, and an idle queue returns to the fast path;
+ *  - `end()` runs the underlying `end` once, after every write queued
+ *    before it; `abort(reason)` runs the underlying `abort` once, at once
+ *    (an abort is urgent — the pending underlying write is not waited
+ *    for), and every write still queued rejects with the reason;
+ *  - a write that throws or rejects (including a throwing `then` getter
+ *    on its answer) fails the sink: its own promise
+ *    rejects, every write queued behind it rejects with the same reason
+ *    without reaching the underlying sink, later writes reject at once,
+ *    and `end()` rejects too — the stream did not end cleanly;
+ *  - `end` and `abort` are mutually terminal: the first one decides, the
+ *    other one (and every repeat) answers the first one's promise; a
+ *    write after either rejects;
+ *  - `write` never throws — a refusal is a rejected promise, so a caller
+ *    handles one shape.
+ *
+ * @template T
+ * @param {SinkLike<T>} sink
+ * @returns {AwaitedSink<T>}
+ * @throws {TypeError} when `sink` has no `write` function
+ */
+export declare function createAwaitedSink<T>(sink: SinkLike<T>): AwaitedSink<T>;

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

@@ -45,7 +45,8 @@ export declare function compileDateFormat(pattern: string, names?: DateNames): (
  * `full-time`, and the offset is the record's own rather than UTC.
  *
  * The round trip preserves the *value*, not necessarily the spelling: a
- * fractional second is emitted only when non-zero and without trailing
+ * fractional second keeps the parser's six-digit precision and is emitted
+ * only when non-zero and without trailing
  * zeros, so `…:05.250Z` comes back `…:05.25Z`. The parts record holds
  * the fraction as a number, so the original digit count is not
  * recoverable — a consumer that must reproduce the input byte for byte

package/dist/types/object.d.ts

@@ -2,8 +2,9 @@
  * Deep equality comparison for arbitrary values.
  *
  * Generic JavaScript equality: understands Maps, Sets, RegExps,
- * functions, typed arrays and class instances (constructors must
- * match). Not the same as `equalsJson`, which compares JSON values
+ * functions, typed arrays and class instances (prototype constructors
+ * must match; an own `constructor` member is data). Not the same as
+ * `equalsJson`, which compares JSON values
  * only and is the hot-path variant — keep both.
  * @param {any} target
  * @param {any} source
@@ -111,7 +112,7 @@ export declare function contentKey(value: any): string;
  * functions, symbols, cycles, and non-plain objects (a `Date`, `Map`,
  * `RegExp` or class instance, all of which serialize to `{}`), plus the
  * two members a serialization cannot show — a symbol key, and an own
- * array property past the last element. A caller that may hold such a
+ * array property that is not an element index. A caller that may hold such a
  * value must treat the refusal as "not cacheable" and compute afresh —
  * never as "reuse whatever shares the key".
  *

package/dist/types/random.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @file The suite's one seeded generator, and the three draws built on
+ * it. Every seeded corpus, oracle and property test in this repository
+ * needs the same thing: a stream of numbers that is identical on every
+ * host for a given seed, so that a benchmark can state a delta and a
+ * failing property test can be replayed. Before this file that stream
+ * was written ten times; a generator that exists once is one whose
+ * sequence can be pinned once.
+ *
+ * The algorithm is mulberry32 — a 32-bit state, one multiply-xorshift
+ * round per draw, a period of 2^32. It is named by its algorithm rather
+ * than by its role because the SEQUENCE is the contract: a corpus
+ * generated from seed 20260825 must regenerate byte-for-byte, and a
+ * "better" generator under the same name would silently change every
+ * fixture that trusts it. A second algorithm gets a second name.
+ *
+ * Nothing here is cryptographic, and nothing here reads `Math.random`.
+ */
+/**
+ * A seeded generator: uniform in `[0, 1)`, identical on every host for
+ * the same seed.
+ *
+ * The seed is taken as an unsigned 32-bit integer (`seed >>> 0`, the
+ * ToUint32 conversion): `1.5` seeds as `1`, `-1` as `4294967295`,
+ * `2^32 + 5` as `5`, and `NaN` as `0`. Two seeds that agree modulo 2^32
+ * are one stream — say so wherever a seed is published.
+ * @param {number} seed
+ * @returns {() => number} the stream; each call is the next draw
+ */
+export declare function mulberry32(seed: number): () => number;
+/**
+ * One integer draw over the half-open range `[min, max)`: `min +
+ * floor(random() * (max - min))`.
+ *
+ * This is the floor draw and deliberately so. Every committed corpus in
+ * the suite was generated with exactly this arithmetic, and a generator
+ * whose integer draw changed would regenerate every one of them
+ * differently. It is uniform up to a bias bounded by `(max - min) /
+ * 2^32` — under one part in a million for a span of four thousand, and
+ * far below anything a benchmark row can resolve. A draw that rejects
+ * to remove even that bias would be a different function under a
+ * different name, not a change to this one.
+ * @param {() => number} random - the stream, from {@link mulberry32}
+ * @param {number} min - inclusive integer lower bound
+ * @param {number} max - exclusive integer upper bound; must exceed `min`
+ * @returns {number} an integer in `[min, max)`
+ * @throws {RangeError} when a bound is not an integer or `max <= min`
+ */
+export declare function randomInt(random: () => number, min: number, max: number): number;
+/**
+ * Fisher–Yates, in place, from the given stream: for `i` from the last
+ * index down to 1, swap `i` with a uniform `j` in `[0, i]`. Returns the
+ * same array. An empty or one-element list draws nothing.
+ *
+ * The descending form is the one the seeded corpora were generated
+ * with; the ascending form is a different permutation of the same
+ * stream and must not be substituted.
+ * @template T
+ * @param {() => number} random - the stream, from {@link mulberry32}
+ * @param {T[]} list - reordered in place
+ * @returns {T[]} `list`
+ */
+export declare function shuffle<T>(random: () => number, list: T[]): T[];
+/**
+ * `k` distinct indices from `[0, n)`, uniformly, as a partial forward
+ * Fisher–Yates over a fresh index pool: the first `k` positions of a
+ * shuffle, without paying for the rest. Asked for more than `n` it
+ * answers `n` — a draw cannot invent a member the population does not
+ * hold; asked for nothing, or from nothing, it answers `[]`.
+ *
+ * The stream is the caller's, so one stream can serve many draws
+ * (a policy that draws per question from one seeded closure stays
+ * reproducible across the whole run).
+ * @param {() => number} random - the stream, from {@link mulberry32}
+ * @param {number} n - the population size (a non-negative integer)
+ * @param {number} k - how many to draw (a non-negative integer)
+ * @returns {number[]} `min(k, n)` distinct indices, in draw order
+ * @throws {RangeError} when `n` or `k` is not a non-negative integer
+ */
+export declare function drawDistinct(random: () => number, n: number, k: number): number[];

package/dist/types/runtime.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @file The runtime record: the host facts every subsystem that needs
+ * one used to take separately — the clock, secure identifiers,
+ * randomness and the zone provider — as one frozen record a host builds
+ * once and hands to the store, the jobs engine, the migration runner and
+ * the http binding. Nothing here IS a clock, a random source or a zone
+ * database: the defaults are the platform's own (`Date.now`,
+ * `crypto.randomUUID`, `Math.random`, and no zone provider, which keeps
+ * a named zone the refusal it always was), so adopting the record changes
+ * nothing a consumer can observe. What it buys is that a deterministic
+ * run — a fixed clock, a seeded generator, a counting identifier — is
+ * configured in one place, and that four subsystems can no longer
+ * disagree about what time it is.
+ *
+ * Precedence is fixed: a subsystem's own explicit option wins over the
+ * record's member, which wins over the built-in default. The options are
+ * published surface, and a record that silently overrode them would be a
+ * breaking change dressed as an ergonomic.
+ *
+ * The record reaches hosts, never query compilation. A compiled query is
+ * cached by document identity and saved as a rule, so the current instant
+ * enters it as data — an external — and there is no `now` operator for
+ * this record to feed.
+ */
+export type Runtime = {
+    /**
+     * - the clock, in epoch milliseconds
+     */
+    now: () => number;
+    /**
+     * - a fresh identifier; secure by default
+     */
+    uuid: () => string;
+    /**
+     * - uniform in `[0, 1)`
+     */
+    random: () => number;
+    /**
+     *   - the tzdb a named zone is read through, or `null`: a named zone is
+     *   then a refusal, never a quiet UTC
+     */
+    zoneProvider: import('./series/zone.js').ZoneProvider | null;
+};
+/**
+ * The record every host-facing subsystem takes as `runtime`.
+ * @typedef {Object} Runtime
+ * @property {() => number} now - the clock, in epoch milliseconds
+ * @property {() => string} uuid - a fresh identifier; secure by default
+ * @property {() => number} random - uniform in `[0, 1)`
+ * @property {import('./series/zone.js').ZoneProvider | null} zoneProvider
+ *   - the tzdb a named zone is read through, or `null`: a named zone is
+ *   then a refusal, never a quiet UTC
+ */
+/**
+ * The four members a runtime record carries, so a subsystem, a test and
+ * a document all spell the host facts the same way.
+ */
+export declare const RUNTIME_MEMBERS: readonly string[];
+/**
+ * Build a runtime record: the platform defaults, with any member
+ * overridden. The result is frozen, so a subsystem that was handed one
+ * can hand it on without a copy.
+ *
+ * The record is closed: a member it does not have is a refusal naming
+ * the four it does, because `clock` for `now` quietly ignored would be a
+ * deterministic run that is not.
+ *
+ * @param {Partial<Runtime>} [overrides]
+ * @returns {Readonly<Runtime>}
+ * @throws {TypeError} for a member that is not a function, a
+ *   `zoneProvider` that is neither `null` nor a provider, or a member
+ *   the record does not have
+ * @example
+ * createRuntime();                                  // the platform's own
+ * createRuntime({ now: () => 1_700_000_000_000 });  // a fixed clock, the rest default
+ * createRuntime({ uuid: () => `id-${++n}`, random: mulberry32(1), zoneProvider });
+ */
+export declare function createRuntime(overrides?: Partial<Runtime>): Readonly<Runtime>;
+/**
+ * The record a subsystem reads its `runtime` option through: nothing
+ * given is the platform default, and anything given is validated and
+ * frozen — so every member a subsystem reads is a function, and a
+ * malformed record is refused where it was passed rather than where it
+ * was first called.
+ * @param {Partial<Runtime> | undefined | null} [candidate] - a subsystem's `options.runtime`
+ * @returns {Readonly<Runtime>}
+ * @throws {TypeError} as `createRuntime` does
+ */
+export declare function resolveRuntime(candidate?: Partial<Runtime> | undefined | null): Readonly<Runtime>;

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

@@ -2,6 +2,13 @@ export { toEpoch, normalizeSeries, canonicalSeries, normalizeIntervals, lowerBou
 export { containsInstant, overlapsInterval, intersectInterval, mergeIntervals, subtractIntervals, gapsWithin, coverageOf, findSlots, MERGE_MEMBERS, SLOTS_MEMBERS, } from './interval.js';
 export { createIntervalIndex } from './interval-index.js';
 export { resolveClock, CLOCK_MEMBERS } from './zone.js';
+export type ZoneProvider = import('./zone.js').ZoneProvider;
+/**
+ * The wall clock a caller supplies for a named zone - the shape a host
+ * passes as `provider`, named here so it can be spelled where the seam
+ * is crossed.
+ * @typedef {import('./zone.js').ZoneProvider} ZoneProvider
+ */
 export { compileBuckets, resampleSeries, RESAMPLE_MEMBERS } from './bucket.js';
 export { rollingSeries, ROLLING_MEMBERS } from './rolling.js';
 export { asOfJoin, ASOF_MEMBERS } from './asof.js';