@jarenjs/core 0.56.0 → 0.67.0

package/ARCHITECTURE.md

@@ -161,13 +161,17 @@ flowchart TB
 
         subgraph FunctionModule["Function Utilities"]
             FunctionUtil["function.js<br/>trueThat, falseThat"]
-            AsyncUtil["async.js<br/>Bounded ordered asynchronous map"]
+            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
@@ -834,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

@@ -14,8 +14,9 @@ None of it depends on JSON Schema: every module can be used standalone in any Ja
 | `@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 |
+| `@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 |
@@ -190,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

@@ -37,3 +37,106 @@
 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/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';

package/dist/types/string.d.ts

@@ -54,6 +54,19 @@ export declare function getStringLength(str: string, useGrapheme?: boolean): num
  * @returns {number} Number of occurrences in [start, end)
  */
 export declare function countCharCode(str: string, code: number, start?: number, end?: number): number;
+/**
+ * The UTF-8 byte length of a slice of a string — the one measure every
+ * byte bound in the suite counts (a body limit, a page, a change
+ * record, a parser's record or token limit) — computed without encoding
+ * a copy: one byte below U+0080, two below U+0800, four for a surrogate
+ * pair (one code point), three otherwise; a lone surrogate counts three,
+ * as its replacement would.
+ * @param {string} str
+ * @param {number} [start] - Inclusive start offset (defaults to 0)
+ * @param {number} [end] - Exclusive end offset (defaults to full length)
+ * @returns {number} The UTF-8 bytes of `str[start, end)`
+ */
+export declare function utf8ByteLength(str: string, start?: number, end?: number): number;
 /**
  * Count the Unicode code points of a string (surrogate-pair aware;
  * a lone surrogate counts as one code point).

package/docs/DATES.md

@@ -21,7 +21,9 @@ Parsing: `parseRFC3339Parts(str)` → a flat **parts** record
 `{year, month, day, hours, minutes, seconds, offset}`. Absent fields are
 `-1` sentinels; `offset` is minutes east of UTC, `0` for `Z` and `null`
 when the string carried none. The inverse is `formatRFC3339Parts(parts)`
-(round-trips the offset). `epochOfRFC3339Parts(parts)` → epoch ms: a
+(round-trips the offset and up to six fractional-second digits, dropping
+trailing zeros). The `SSS` formatting token writes the first three fraction
+digits. `epochOfRFC3339Parts(parts)` → epoch ms: a
 date-only reads as UTC midnight, an offset shifts to its instant, and a
 time-only has **no** instant — it returns `NaN` rather than inventing a
 day. `getDateTypeOf*` variants produce a `Date` for callers that want

package/docs/SERIES.md

@@ -177,6 +177,20 @@ with no provider is a refusal, never a quiet fall back to UTC — which is
 right for Amsterdam for none of the year and *looks* right for eight
 months of it.
 
+The seam is crossed, not closed. `@jarenjs/locales/intl-zones` ships
+`createIntlZoneProvider()`, a provider over the host's own ICU data —
+the one copy of the tzdb that is already installed and already
+maintained — that a caller passes as `provider`. It is opt-in and on
+its own subpath, because ICU output moves between hosts and may not be
+anyone's default; it never reads the host's own zone, because every
+call names its zone and there is no default that asks the process
+where it is; and it answers a gap and a fold exactly, proved by a
+transition corpus rather than by examples. Nothing about the seam
+moves: this kernel still bundles no zone data and reaches for no
+`Intl`, a named zone with no provider is still a refusal, and a host
+with a tzdb of its own still passes that instead. The provider's own
+document is [`@jarenjs/locales`' README](../../locales/README.md).
+
 ## Buckets, resampling and fill — `bucket.js`
 
 Two questions that are always asked together and are not the same
@@ -317,26 +331,27 @@ unless the kernel answered the identical rows the references did.
 
 The kernel is not the ceiling and does not claim to be. A one-pass loop
 written for one question validates nothing, normalizes nothing and
-returns a bare pair. Against those loops the kernel costs <!--fact:series.kernelVsCeiling-->3.4× the one-pass bucket loop and 6.2× the one-pass ring sum<!--/fact-->,
-and against the vocabulary a consumer had instead it is <!--fact:series.kernelVsQuery-->73.6× faster than the generic query bucket and 81.2× faster than the labelled count window<!--/fact-->.
+returns a bare pair. Against those loops the kernel costs <!--fact:series.kernelVsCeiling-->3.3× the one-pass bucket loop and 6.0× the one-pass ring sum<!--/fact-->,
+and against the vocabulary a consumer had instead it is <!--fact:series.kernelVsQuery-->76.7× faster than the generic query bucket and 78.5× faster than the labelled count window<!--/fact-->.
 
 <!--fact:series.kernelTable-->
 | operation | median | rows | against | what that is | ratio |
 |---|---:|---:|---:|---|---:|
-| `resampleSeries`, 60 s buckets | 1.5 ms | 1,667 | 0.45 ms | one-pass loop | 3.4× |
-| `resampleSeries`, + linear fill | 1.1 ms | 1,657 | 1 ms | the same buckets, omitting | 1.0× |
-| `rollingSeries`, 60 s window | 7.2 ms | 100,000 | 1.2 ms | one-pass ring sum | 6.2× |
-| `asOfJoin`, one left row per 100 | 1.7 ms | 1,000 | 2.2 ms | one index read per row | 0.8× |
-| `downsampleSeries`, lttb, gap corpus | 1.6 ms | 2,000 | 1.8 ms | the same line with no holes in it | 0.9× |
+| `resampleSeries`, 60 s buckets | 1.6 ms | 1,667 | 0.47 ms | one-pass loop | 3.3× |
+| `resampleSeries`, + linear fill | 1.1 ms | 1,657 | 1 ms | the same buckets, omitting | 1.1× |
+| `rollingSeries`, 60 s window | 7.6 ms | 100,000 | 1.3 ms | one-pass ring sum | 6.0× |
+| `asOfJoin`, one left row per 100 | 1.7 ms | 1,000 | 1.7 ms | one index read per row | 1.0× |
+| `downsampleSeries`, lttb, gap corpus | 1.7 ms | 2,000 | 1.9 ms | the same line with no holes in it | 0.9× |
 <!--/fact-->
 
-A row that loses stays in, and the two shapes of the same join are published side by side rather than the flattering one alone. <!--fact:series.asofShape-->The as-of join costs 14.7× a handful of index reads, and beats them by 1.3× once there is one left row per hundred right ones. The reason is the shape rather than the engine: a b-tree pays per probe, and a sorted walk pays for the whole right side whether it was asked one question or a thousand.<!--/fact-->
+A row that loses stays in, and the two shapes of the same join are published side by side rather than the flattering one alone. <!--fact:series.asofShape-->The as-of join costs 19.7× a handful of index reads, and narrows to 1.0× the same join once there is one left row per hundred right ones — still the statement's win, published as one. The reason is the shape rather than the engine: a b-tree pays per probe, and a sorted walk pays for the whole right side whether it was asked one question or a thousand.<!--/fact-->
 
-And the seam has a price that this corpus cannot charge it. <!--fact:series.zoneCost-->Walking every boundary through an injected zone provider costs 1.0× the integer ladder over an identical answer — near parity because it is near nothing, since the benchmark corpus spans 28 hours and holds two daily boundaries. What the suite gates instead is that the provider is consulted per boundary rather than per sample.<!--/fact-->
+And the seam has a price that this corpus cannot charge it. <!--fact:series.zoneCost-->Walking every boundary through the shipped Intl zone provider costs 1.1× the integer ladder over an identical answer — a handful of ICU reads against the whole ladder, since the benchmark corpus spans 28 hours and holds two daily boundaries. What the suite gates is that the provider is consulted per boundary rather than per sample.<!--/fact-->
 
 ## Not here
 
-Named time zones are injected, never bundled; recurrence grammars
+Named time zones are injected, never bundled — the provider over host
+ICU lives opt-in in `@jarenjs/locales`, not here; recurrence grammars
 (RRULE, iCalendar) and any kind of scheduling solver are somebody else's
 layer. This module supplies the algebra those are built from, and
 nothing that needs a clock, a locale or a zone database to be correct.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/core",
   "private": false,
-  "version": "0.56.0",
+  "version": "0.67.0",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -112,6 +112,10 @@
       "types": "./dist/types/random.d.ts",
       "default": "./src/random.js"
     },
+    "./runtime": {
+      "types": "./dist/types/runtime.d.ts",
+      "default": "./src/runtime.js"
+    },
     "./scan": {
       "types": "./dist/types/scan.d.ts",
       "default": "./src/scan.js"

package/src/async.js

@@ -27,6 +27,8 @@
  * about what the worker does; those are the caller's policies around it.
  */
 
+import { isThenable } from './function.js';
+
 /**
  * @template T, R
  * @param {readonly T[]} items
@@ -76,3 +78,208 @@ export async function mapConcurrent(items, limit, worker, options = {}) {
   if (stop.length > 0) throw stop[0];
   return results;
 }
+
+/**
+ * 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 function createAwaitedSink(sink) {
+  if (sink === null || typeof sink !== 'object' || typeof sink.write !== 'function') {
+    throw new TypeError('createAwaitedSink needs a sink with a write function');
+  }
+  /** whether an underlying operation is in flight (it answered a thenable) */
+  let running = false;
+  /**
+   * The operations waiting for the one in flight, in call order.
+   * @type {{ op: () => unknown, resolve: () => void, reject: (reason: unknown) => void }[]}
+   */
+  const queued = [];
+  let failed = false;
+  /** @type {unknown} */
+  let failure;
+  let closed = false;
+  /** @type {Promise<void> | null} the first end()/abort() settlement */
+  let terminal = null;
+
+  /** @param {unknown} reason */
+  const fail = (reason) => {
+    if (failed) return;
+    failed = true;
+    failure = reason;
+  };
+
+  /** Run what is queued, one at a time, until one answers a thenable. */
+  const next = () => {
+    while (!running && queued.length > 0) {
+      const item = /** @type {NonNullable<typeof queued[0]>} */ (queued.shift());
+      if (failed) {
+        item.reject(failure);
+        continue;
+      }
+      let answer;
+      try {
+        answer = item.op();
+        if (!isThenable(answer)) {
+          item.resolve();
+          continue;
+        }
+      }
+      catch (err) {
+        fail(err);
+        item.reject(err);
+        continue;
+      }
+      running = true;
+      Promise.resolve(answer).then(() => {
+        running = false;
+        item.resolve();
+        next();
+      }, (err) => {
+        running = false;
+        fail(err);
+        item.reject(err);
+        next();
+      });
+    }
+  };
+
+  /**
+   * Run one operation behind the queue.
+   * @param {() => unknown} op
+   * @returns {Promise<void> | undefined}
+   */
+  const run = (op) => {
+    if (running || queued.length > 0) {
+      return new Promise((resolve, reject) => { queued.push({ op, resolve, reject }); });
+    }
+    let answer;
+    try {
+      answer = op();
+      if (!isThenable(answer)) return undefined;
+    }
+    catch (err) {
+      fail(err);
+      return Promise.reject(err);
+    }
+    running = true;
+    return new Promise((resolve, reject) => {
+      Promise.resolve(answer).then(() => {
+        running = false;
+        resolve();
+        next();
+      }, (err) => {
+        running = false;
+        fail(err);
+        reject(err);
+        next();
+      });
+    });
+  };
+
+  return {
+    write(chunk) {
+      if (failed) return Promise.reject(failure);
+      if (closed) return Promise.reject(new Error('createAwaitedSink: write after end'));
+      return run(() => sink.write(chunk));
+    },
+    end() {
+      if (terminal !== null) return terminal;
+      closed = true;
+      if (failed) {
+        terminal = Promise.reject(failure);
+        return terminal;
+      }
+      const answer = run(() => (typeof sink.end === 'function' ? sink.end() : undefined));
+      terminal = answer === undefined ? Promise.resolve() : answer;
+      return terminal;
+    },
+    abort(reason) {
+      if (terminal !== null) return terminal;
+      closed = true;
+      const why = reason === undefined ? new Error('createAwaitedSink: aborted') : reason;
+      fail(why);
+      // what is still queued rejects now — an abort does not wait for
+      // the operation in flight, whose late settlement is then ignored
+      const waiting = queued.splice(0, queued.length);
+      for (let i = 0; i < waiting.length; i++) waiting[i].reject(why);
+      let answer;
+      try {
+        answer = typeof sink.abort === 'function' ? sink.abort(why) : undefined;
+      }
+      catch (err) {
+        terminal = Promise.reject(err);
+        return terminal;
+      }
+      terminal = Promise.resolve(answer).then(() => undefined);
+      return terminal;
+    },
+    failed: () => failed,
+    closed: () => closed,
+  };
+}

package/src/dates/format.js

@@ -40,6 +40,13 @@ import {
 const D2 = (n) => (n < 10 ? '0' + n : '' + n);
 const D3 = (n) => (n < 10 ? '00' + n : n < 100 ? '0' + n : '' + n);
 
+// The parser retains up to six fractional digits. Round the whole seconds
+// before extracting them, so subtraction does not expose binary noise.
+/** @param {number} seconds */
+function fractionDigits(seconds) {
+  return seconds.toFixed(6).slice(-6);
+}
+
 function pad(n, width) {
   const s = '' + n;
   return s.length >= width ? s : '0'.repeat(width - s.length) + s;
@@ -86,8 +93,8 @@ const TOKENS = {
   m: (p) => '' + p.minutes,
   ss: (p) => D2(Math.trunc(p.seconds)),
   s: (p) => '' + Math.trunc(p.seconds),
-  SSS: (p) => D3(Math.round((p.seconds - Math.trunc(p.seconds)) * 1000)),
-  S: (p) => '' + Math.trunc((p.seconds - Math.trunc(p.seconds)) * 10),
+  SSS: (p) => fractionDigits(p.seconds).slice(0, 3),
+  S: (p) => fractionDigits(p.seconds).slice(0, 1),
   a: (p, n) => n.meridiem[p.hours < 12 ? 0 : 1],
   XXX: (p) => offsetText(p.offset, true, true),
   XX: (p) => offsetText(p.offset, false, true),
@@ -203,7 +210,8 @@ const FORMAT_TIME = compileDateFormat('HH:mm:ssXXX');
  * `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
@@ -222,9 +230,11 @@ export function formatRFC3339Parts(parts) {
   if (fraction === 0)
     return base;
   // splice the fraction in after the seconds, before the offset
-  const digits = fraction.toFixed(3).slice(1).replace(/0+$/, '');
+  const digits = fractionDigits(parts.seconds).replace(/0+$/, '');
+  if (digits.length === 0)
+    return base;
   const cut = base.length - (FORMAT_OFFSET_LEN(parts));
-  return base.slice(0, cut) + digits + base.slice(cut);
+  return base.slice(0, cut) + '.' + digits + base.slice(cut);
 }
 
 // how many characters the rendered offset takes, so the fraction can be

package/src/dates/rfc3339.js

@@ -5,7 +5,7 @@ import {
   isObjectOfClass,
 } from '../index.js';
 // the calendar rules live in civil.js, which owns the day tables
-import { isLeapYear, daysInMonth } from './civil.js';
+import { isLeapYear, daysInMonth, daysFromCivil } from './civil.js';
 
 export { isLeapYear };
 
@@ -365,18 +365,16 @@ export function epochOfRFC3339Parts(parts) {
     return NaN;
   const seconds = parts.seconds < 0 ? 0 : parts.seconds;
   const whole = Math.floor(seconds);
+  // Civil day numbers preserve year zero's leap day and carries across
+  // year 99; Date.UTC's 1900-based interpretation of 0-99 cannot.
   const ms = Date.UTC(
-    parts.year, parts.month - 1, parts.day,
+    1970, 0, 1 + daysFromCivil(parts.year, parts.month, parts.day),
     parts.hours < 0 ? 0 : parts.hours,
     parts.minutes < 0 ? 0 : parts.minutes,
     whole, Math.round((seconds - whole) * 1000));
   if (ms !== ms)
     return NaN;
-  // Date.UTC maps years 0-99 into the 1900s; restore the real year
-  const utc = new Date(ms);
-  if (parts.year >= 0 && parts.year < 100)
-    utc.setUTCFullYear(parts.year);
-  return utc.getTime() - (parts.offset === null ? 0 : parts.offset) * 60000;
+  return ms - (parts.offset === null ? 0 : parts.offset) * 60000;
 }
 //#endregion
 

package/src/object.js

@@ -14,8 +14,9 @@ const hasOwn = Object.hasOwn;
  * 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
@@ -34,23 +35,24 @@ export function equalsDeep(target, source) {
   if (isScalarType(target))
     return false;
 
-  if (target.constructor !== source.constructor)
+  const constructor = Object.getPrototypeOf(target)?.constructor;
+  if (constructor !== Object.getPrototypeOf(source)?.constructor)
     return false;
 
-  if (target.constructor === Object) {
+  if (constructor === Object) {
     const tks = Object.keys(target);
     const sks = Object.keys(source);
     if (tks.length !== sks.length)
       return false;
     for (let i = 0; i < tks.length; ++i) {
       const key = tks[i];
-      if (!equalsDeep(target[key], source[key]))
+      if (!hasOwn(source, key) || !equalsDeep(target[key], source[key]))
         return false;
     }
     return true;
   }
 
-  if (target.constructor === Map) {
+  if (constructor === Map) {
     if (target.size !== source.size)
       return false;
     for (const [key, value] of target) {
@@ -62,7 +64,7 @@ export function equalsDeep(target, source) {
     return true;
   }
 
-  if (target.constructor === Array) {
+  if (constructor === Array) {
     if (target.length !== source.length)
       return false;
     for (let i = 0; i < target.length; ++i) {
@@ -72,7 +74,7 @@ export function equalsDeep(target, source) {
     return true;
   }
 
-  if (target.constructor === Set) {
+  if (constructor === Set) {
     if (target.size !== source.size)
       return false;
     for (const value of target) {
@@ -82,7 +84,7 @@ export function equalsDeep(target, source) {
     return true;
   }
 
-  if (target.constructor === RegExp) {
+  if (constructor === RegExp) {
     return target.toString() === source.toString();
   }
 
@@ -104,7 +106,7 @@ export function equalsDeep(target, source) {
   if (tkeys.length === 0) return true;
   for (let i = 0; i < tkeys.length; ++i) {
     const key = tkeys[i];
-    if (!equalsDeep(target[key], source[key]))
+    if (!hasOwn(source, key) || !equalsDeep(target[key], source[key]))
       return false;
   }
   return true;
@@ -375,7 +377,7 @@ function semanticToken(value, path, open) {
     // an own property beyond the elements would vanish positionally
     for (const key of Object.keys(items)) {
       const index = Number(key);
-      if (!Number.isInteger(index) || index < 0 || index >= items.length)
+      if (!Number.isInteger(index) || index < 0 || index >= items.length || String(index) !== key)
         refuse(`the extra array property ${JSON.stringify(key)}`);
     }
     out = '[';
@@ -422,7 +424,7 @@ function semanticToken(value, path, open) {
  * 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".
  *
@@ -634,4 +636,4 @@ export function mergeSet(set, ...iterables) {
       set.add(item);
     }
   }
-}
+}

package/src/runtime.js

@@ -0,0 +1,130 @@
+//@ts-check
+/**
+ * @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.
+ */
+
+/**
+ * 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 const RUNTIME_MEMBERS = Object.freeze(['now', 'uuid', 'random', 'zoneProvider']);
+
+/**
+ * The platform's own answers — exactly what every subsystem fell back
+ * to before the record existed, member for member, so a run that never
+ * builds a record behaves as it always did.
+ * @type {Readonly<Runtime>}
+ */
+const DEFAULT_RUNTIME = Object.freeze({
+  now: Date.now,
+  // `randomUUID` is a method of the platform's Crypto object and refuses
+  // to run unbound, so the default is a call rather than a reference
+  uuid: () => globalThis.crypto.randomUUID(),
+  random: Math.random,
+  zoneProvider: null,
+});
+
+/**
+ * Whether a value is the pair of functions the temporal kernel's clock
+ * seam takes for a named zone.
+ * @param {any} value
+ * @returns {boolean}
+ */
+function isZoneProvider(value) {
+  return value !== null && typeof value === 'object'
+    && typeof value.toParts === 'function' && typeof value.toEpoch === 'function';
+}
+
+/**
+ * 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 function createRuntime(overrides = undefined) {
+  if (overrides === undefined || overrides === null)
+    return DEFAULT_RUNTIME;
+  if (typeof overrides !== 'object')
+    throw new TypeError('a runtime record is an object');
+  /** @type {any} */
+  const record = { ...DEFAULT_RUNTIME };
+  for (const key of Object.keys(overrides)) {
+    if (!RUNTIME_MEMBERS.includes(key)) {
+      throw new TypeError(`a runtime record has ${
+        RUNTIME_MEMBERS.map((m) => `'${m}'`).join(', ')}, not '${key}'`);
+    }
+    const value = /** @type {any} */ (overrides)[key];
+    if (value === undefined)
+      continue;
+    if (key === 'zoneProvider') {
+      if (value !== null && !isZoneProvider(value)) {
+        throw new TypeError('runtime.zoneProvider is null or a provider with'
+          + ' toParts(epoch, zone) and toEpoch(parts, zone, disambiguation)');
+      }
+    }
+    else if (typeof value !== 'function') {
+      throw new TypeError(`runtime.${key} is a function`);
+    }
+    record[key] = value;
+  }
+  return Object.freeze(record);
+}
+
+/**
+ * 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 function resolveRuntime(candidate = undefined) {
+  return candidate === DEFAULT_RUNTIME ? DEFAULT_RUNTIME : createRuntime(candidate);
+}

package/src/series/index.js

@@ -75,6 +75,13 @@ export { createIntervalIndex } from './interval-index.js';
 
 export { resolveClock, CLOCK_MEMBERS } from './zone.js';
 
+/**
+ * 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';

package/src/string.js

@@ -166,6 +166,37 @@ export function countCharCode(str, code, start = 0, end = str.length) {
   return n;
 }
 
+/**
+ * The UTF-8 byte length of a slice of a string — the one measure every
+ * byte bound in the suite counts (a body limit, a page, a change
+ * record, a parser's record or token limit) — computed without encoding
+ * a copy: one byte below U+0080, two below U+0800, four for a surrogate
+ * pair (one code point), three otherwise; a lone surrogate counts three,
+ * as its replacement would.
+ * @param {string} str
+ * @param {number} [start] - Inclusive start offset (defaults to 0)
+ * @param {number} [end] - Exclusive end offset (defaults to full length)
+ * @returns {number} The UTF-8 bytes of `str[start, end)`
+ */
+export function utf8ByteLength(str, start = 0, end = str.length) {
+  let bytes = 0;
+  for (let i = start; i < end; i++) {
+    const code = str.charCodeAt(i);
+    if (code < 0x80) bytes += 1;
+    else if (code < 0x800) bytes += 2;
+    else if (code >= 0xD800 && code <= 0xDBFF && i + 1 < end) {
+      const next = str.charCodeAt(i + 1);
+      if (next >= 0xDC00 && next <= 0xDFFF) {
+        bytes += 4;
+        i++;
+      }
+      else bytes += 3;
+    }
+    else bytes += 3;
+  }
+  return bytes;
+}
+
 /**
  * Count the Unicode code points of a string (surrogate-pair aware;
  * a lone surrogate counts as one code point).