@jarenjs/json 0.46.4 → 0.49.2

package/ARCHITECTURE.md

@@ -163,7 +163,7 @@ Grouping, `$distinct` and the `$orderby` machinery need a total, deterministic e
 
 ### The operator registry
 
-All 99 §8 operators live in one table in `operators.js` — the query-language analogue of `path.js`'s `FUNCTIONS` table. A test derives the count from the registry and asserts it against QUERY-FORMAT §8 *and* against every committed document that states a number — this file, the README twice, `site.md` and `@jarenjs/linq`'s architecture — so an operator cannot be added without moving all of them in the same change:
+All 104 §8 operators live in one table in `operators.js` — the query-language analogue of `path.js`'s `FUNCTIONS` table. A test derives the count from the registry and asserts it against QUERY-FORMAT §8 *and* against every committed document that states a number — this file, the README twice, `site.md` and `@jarenjs/linq`'s architecture — so an operator cannot be added without moving all of them in the same change:
 
 ```javascript
 '$substring': {

package/README.md

@@ -386,13 +386,13 @@ queryJson({
 }, [1, 2, 3, 4, 5]); // [2, 3, 4] — a 3-point moving average
 ```
 
-The operator library (99 operators: comparisons, IEEE-double arithmetic, logic, strings with I-Regexp `$match`/`$search`/`$replace`, aggregates, sequence tools like `$distinct`/`$subsequence`/`$range`, type predicates and casts, `$coalesce`, the RFC 3339 date family, the spatial family and `$similarity`) is cataloged in [QUERY-FORMAT.md §8](./docs/QUERY-FORMAT.md#8-operators).
+The operator library (104 operators: comparisons, IEEE-double arithmetic, logic, strings with I-Regexp `$match`/`$search`/`$replace`, aggregates, sequence tools like `$distinct`/`$subsequence`/`$range`, type predicates and casts, `$coalesce`, the RFC 3339 date family, the spatial family, `$similarity` and the time-series family) is cataloged in [QUERY-FORMAT.md §8](./docs/QUERY-FORMAT.md#8-operators).
 
-**Extending the vocabulary (host opt-in).** The 99 are closed, but a host can add more the way `@jarenjs/validate` gains formats from `@jarenjs/formats`: `createJsltRegistry().use(mathPack).use(financePack)` composes packs of pure `@jarenjs/core` functions into a compiler, so `{ "$sqrt": "$.variance" }` and `{ "$npv": ["$.rate", "$.cashflows[*]"] }` work in a stylesheet, a bare query, and `@jarenjs/linq` — while a document compiled *without* the registry still rejects them. Aggregators fold a `seq` operand to an array before the pure call. See [JSLT-FORMAT.md §13](./docs/JSLT-FORMAT.md#13-registered-operators-host-opt-in-non-normative).
+**Extending the vocabulary (host opt-in).** The 104 are closed, but a host can add more the way `@jarenjs/validate` gains formats from `@jarenjs/formats`: `createJsltRegistry().use(mathPack).use(financePack)` composes packs of pure `@jarenjs/core` functions into a compiler, so `{ "$sqrt": "$.variance" }` and `{ "$npv": ["$.rate", "$.cashflows[*]"] }` work in a stylesheet, a bare query, and `@jarenjs/linq` — while a document compiled *without* the registry still rejects them. Aggregators fold a `seq` operand to an array before the pure call. See [JSLT-FORMAT.md §13](./docs/JSLT-FORMAT.md#13-registered-operators-host-opt-in-non-normative).
 
 **Dates are RFC 3339 strings** ([§8.13](./docs/QUERY-FORMAT.md#813-dates-and-times)): `$is-date`/`$is-time`/`$is-datetime`/`$is-duration` test the lexical forms, `$year`…`$seconds` and `$offset` read components *lexically, in the value's own offset* (so "group by month" means what you expect), `$week`/`$week-year`/`$quarter`/`$weekday` add the derived calendar fields, and `$epoch`/`$datetime` convert to and from epoch milliseconds — the one place a value is shifted to UTC, and therefore the way to compare instants across offsets. There is deliberately no `current-dateTime`: a compiled query is cached by document identity and saved as a rule, so it must answer the same for the same input forever.
 
-Dates also *move*. `$date-add`/`$date-sub` shift by an ISO 8601 duration or by an amount and a unit, `$start-of`/`$end-of` truncate to a calendar unit, `$date-diff` counts whole units, and `$date-format` renders through a Unicode LDML pattern compiled once with the query. Two rules keep it predictable: the **lexical form is preserved** (a date stays a date, and a date-time keeps its own offset instead of being normalized to UTC), and **month arithmetic clamps**, so 31 January plus a month is 28 February — with `$date-diff` counting to match, so adding its answer back never overshoots.
+Dates also *move*. `$date-add`/`$date-sub` shift by an ISO 8601 duration or by an amount and a unit, `$start-of`/`$end-of` truncate to a calendar unit, `$date-diff` counts whole units, and `$date-format` renders through a Unicode LDML pattern compiled once with the query. Three rules keep it predictable: the **lexical form is preserved** (a date stays a date, and a date-time keeps its own offset instead of being normalized to UTC); **month arithmetic clamps**, so 31 January plus a month is 28 February — with `$date-diff` counting to match, so adding its answer back never overshoots; and **an operation needing a half the value has not got is refused**, so adding hours to a date, or asking a time for its end of month, is a `JQ2001` rather than an invented answer. Fractions apply where they convert exactly: `P1.5D` is thirty-six hours on a date-time, half a month is refused.
 
 ```js
 queryJson({
@@ -406,7 +406,7 @@ queryJson({
 
 Bucketing by week is the shape components alone cannot express, because a week boundary is arithmetic rather than a field. Patterns stay locale-independent — `MMMM` and `EEEE` are rejected rather than silently rendered in English — because localized text belongs to the presentation layer, not to a query.
 
-**Geography is GeoJSON** ([§8.14](./docs/QUERY-FORMAT.md#814-spatial)), for the same reason dates are RFC 3339 strings: it is what the document already holds. Thirteen of the 98 operators are spatial — eight measurements and predicates, five conversions — and JSLT and JTLT inherit every one. Operands are a bare `[longitude, latitude]` position, a geometry, a `Feature` or a `FeatureCollection`, and wrappers unwrap for you. `$distance`, `$area` and `$length` answer in metres on the WGS 84 sphere — never planar, because a Euclidean answer over raw degrees is wrong by two thirds over a kilometre at Dutch latitudes. `$within` tests containment, `$bbox`/`$centroid` measure, and `$bbox-intersects` is named for exactly what it tests, since an `$intersects` that compared only boxes would be a lie the first time two L-shapes shared one.
+**Geography is GeoJSON** ([§8.14](./docs/QUERY-FORMAT.md#814-spatial)), for the same reason dates are RFC 3339 strings: it is what the document already holds. Thirteen of the 104 operators are spatial — eight measurements and predicates, five conversions — and JSLT and JTLT inherit every one. Operands are a bare `[longitude, latitude]` position, a geometry, a `Feature` or a `FeatureCollection`, and wrappers unwrap for you. `$distance`, `$area` and `$length` answer in metres on the WGS 84 sphere — never planar, because a Euclidean answer over raw degrees is wrong by two thirds over a kilometre at Dutch latitudes. `$within` tests containment, `$bbox`/`$centroid` measure, and `$bbox-intersects` is named for exactly what it tests, since an `$intersects` that compared only boxes would be a lie the first time two L-shapes shared one.
 
 ```js
 queryJson({
@@ -481,6 +481,49 @@ breaks ties by identity, so the same document answers with the same rows every
 time it runs. `@jarenjs/linq` spells the whole chain fluently as
 `.orderByDescending(m => m.embedding.similarity(q), { empty: 'least' }).take(10)`.
 
+### Time series, in five operators
+
+A series is what a document already holds when something has been measured
+repeatedly — records with an instant and a reading — so five operators cover
+the questions a `$for` phrase can ask but cannot answer in one pass
+([§8.16](./docs/QUERY-FORMAT.md#816-time-series)):
+
+```javascript
+queryJson({ $resample: ['$.readings[*]',
+  { every: 'PT1H', aggregate: 'mean', fill: 'linear' }] }, data);
+// [{ at: 1767225600000, value: 4.5, count: 3600 }, …]
+```
+
+`$overlaps` tests two half-open `{start, end}` intervals (touching spans do
+*not* overlap), `$time-bucket` labels the bucket an instant falls in,
+`$resample` aggregates a series into buckets with an explicit fill policy,
+`$rolling` aggregates over a window measured in **time** rather than in rows,
+and `$asof` answers "what was current when this happened" for every left row.
+Each is a call into [`@jarenjs/core/series`](../core/README.md) and nothing
+else — the same kernel a chart and an indexed database read.
+
+The second operand is a **verbatim literal**, not an expression, and that is
+what makes it checkable: the width, the aggregate, the fill policy and the row
+selectors are read once when the query compiles, so an unknown member, a bad
+duration or a wildcard where a selector belongs is `JQ0003` with the near miss
+named. Only what the *data* decides — a row that is not a sample, an instant
+that names none — is `JQ2001`. A left row with no as-of match keeps
+`right: null` and **stays in the answer**: no match is data.
+
+```javascript
+queryJson({ $asof: ['$.trades[*]', '$.quotes[*]',
+  { by: '$.symbol', direction: 'backward', tolerance: 'PT1M' }] }, data);
+```
+
+Instants are epoch milliseconds on both sides; `$epoch` and `$datetime` are the
+conversions, and a row that spells its instant elsewhere is read with a
+selector (`{ at: '$.on' }`) rather than rewritten first. Calendar widths need a
+wall clock: UTC and `{ offset }` need nothing, and a **named zone needs an
+injected `zoneProvider`** — this suite bundles no time-zone database, and a
+document that asked for one without it is refused rather than quietly answered
+in UTC. Nothing here reads a clock: there is no `$now`, for the same reason
+§8.13 has no `current-dateTime`.
+
 ### External parameters
 
 A variable no phrase binds is an **external**: use is the declaration. The compiled query exposes the collected names and takes bindings at call time:

package/dist/types/query/operators.d.ts

@@ -694,6 +694,48 @@ export declare const OPERATORS: Readonly<{
         result: typeof resultEmptyPropagates;
         compile: (gets: any, args: any) => (f: any) => string | typeof EMPTY;
     };
+    $overlaps: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: (cards: any) => 1 | 2;
+        resultType: typeof RT_BOOLEAN;
+        compile: (gets: any, args: any) => (f: any) => boolean | typeof EMPTY;
+    };
+    '$time-bucket': {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: (cards: any) => 1 | 2;
+        resultType: typeof RT_INTEGER;
+        compile: (gets: any, args: any, docPath: any, node: any) => (f: any) => any;
+    };
+    $resample: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof RESULT_MANY;
+        compile: (gets: any, args: any, docPath: any, node: any) => (f: any) => any;
+    };
+    $rolling: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof RESULT_MANY;
+        compile: (gets: any, args: any, docPath: any, node: any) => (f: any) => any;
+    };
+    $asof: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof RESULT_MANY;
+        compile: (gets: any, args: any, docPath: any) => (f: any) => any;
+    };
 }>;
 declare function coalesceCard(cards: any): 0 | 1 | 2 | 3;
 declare function compileCoalesce(gets: any): any;

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

@@ -0,0 +1,164 @@
+import { JsonQueryRuntimeError } from './errors.js';
+/**
+ * The calendar context every clock-reading spec carries, and the one
+ * `$time-bucket` takes as its own literal. `zone` is an IANA name — only
+ * `'UTC'` resolves without a provider (D7: this suite bundles no tzdb) —
+ * `offset` is minutes east of UTC, and `disambiguation` says what a
+ * local time that happens twice, or never, resolves to.
+ */
+export declare const CLOCK_MEMBERS: readonly string[];
+/** `$resample`: the D5 bucket contract, plus where a row keeps its members. */
+export declare const RESAMPLE_MEMBERS: readonly string[];
+/** `$rolling`: a window measured in time, and how much of one counts. */
+export declare const ROLLING_MEMBERS: readonly string[];
+/**
+ * `$asof`: which way to look, how far, and what makes two rows
+ * comparable. The one list NOT read from the kernel: `asOfJoin` takes
+ * nested `left`/`right` selector records, and a spec that stays one
+ * flat literal is what makes "compiled once" true — so the document
+ * spells `by`, `leftAt` and `rightAt`, and `compileAsOfSpec` below is
+ * the single place that translation happens.
+ */
+export declare const ASOF_MEMBERS: readonly string[];
+/**
+ * One captured spec literal, confirmed to be an object naming only
+ * admitted members.
+ * @param {any} value - the raw node's frozen value
+ * @param {readonly string[]} allowed - the closed member list
+ * @param {string} operator - the operator's name, for the message
+ * @param {string} docPath - the spec argument's pointer
+ * @returns {any} the same object
+ * @throws {JsonQueryCompileError} JQ0003
+ */
+export declare function requireSpec(value: any, allowed: readonly string[], operator: string, docPath: string): any;
+/**
+ * A spec member that must be one of a closed set of names.
+ * @param {any} value
+ * @param {readonly string[]} allowed
+ * @param {string} member
+ * @param {string} docPath
+ * @returns {string}
+ */
+export declare function requireEnum(value: any, allowed: readonly string[], member: string, docPath: string): string;
+/**
+ * A spec member that must be a finite number.
+ * @param {any} value
+ * @param {string} member
+ * @param {string} docPath
+ * @returns {number}
+ */
+export declare function requireNumber(value: any, member: string, docPath: string): number;
+/**
+ * A spec member naming an instant: epoch milliseconds or an RFC 3339
+ * string. The kernel converts it; this only refuses what is not one of
+ * the two spellings, so the message names the member rather than a row.
+ * @param {any} value
+ * @param {string} member
+ * @param {string} docPath
+ * @returns {number | string}
+ */
+export declare function requireInstant(value: any, member: string, docPath: string): number | string;
+/**
+ * A spec member naming a span: a finite count of milliseconds or an ISO
+ * 8601 duration string. The kernel decides whether the duration is one
+ * it can walk; this refuses the shapes that are not spans at all.
+ * @param {any} value
+ * @param {string} member
+ * @param {string} docPath
+ * @returns {number | string}
+ */
+export declare function requireSpan(value: any, member: string, docPath: string): number | string;
+/**
+ * A **row selector**: the query language's singular-path spelling, with
+ * `$` reading as the ROW rather than as the document — `'$.on'`,
+ * `'$[\'recorded at\']'`, `'$.meta.at'`. Compiled once into a direct
+ * property walk (`compileSingularGetter`), so nothing is parsed per row.
+ *
+ * A bare member name is the common case, and it is handed to the kernel
+ * as a name rather than as a closure: `canonicalSeries`'s no-copy fast
+ * path is only available to a series already spelled `at`/`value`, and
+ * a closure would take it away from every caller who did not need one.
+ *
+ * @param {any} value - the raw spec member
+ * @param {string} member - its name, for the message
+ * @param {string} docPath - the spec argument's pointer
+ * @returns {string | ((item: any) => any)} a member name, or a reader
+ * @throws {JsonQueryCompileError} JQ0003 for a non-singular or invalid path
+ */
+export declare function compileSelector(value: any, member: string, docPath: string): string | ((item: any) => any);
+/**
+ * The wall clock a spec's calendar boundaries fall on, resolved once.
+ *
+ * UTC and a fixed offset need nothing. A named zone needs the tzdb this
+ * suite deliberately does not bundle (D7), and a JSON document cannot
+ * carry one — so the provider arrives through the compilation's
+ * `zoneProvider` option, and a named zone without one is a refusal
+ * naming the seam rather than a silent fall back to UTC that is right
+ * for eight months of the year.
+ *
+ * @param {any} spec - the captured spec (or calendar context)
+ * @param {any} provider - `options.zoneProvider`, or null
+ * @param {string} docPath
+ * @returns {{ zone?: string, offset?: number, provider?: any, disambiguation?: string }}
+ *   the clock options the kernel takes
+ * @throws {JsonQueryCompileError} JQ0003
+ */
+export declare function compileClock(spec: any, provider: any, docPath: string): {
+    zone?: string;
+    offset?: number;
+    provider?: any;
+    disambiguation?: string;
+};
+/** The seven aggregates D5 fixes, for both `$resample` and `$rolling`. */
+export declare const AGGREGATES: readonly string[];
+/** The five fill policies D5 fixes. */
+export declare const FILLS: readonly string[];
+/** Which way an as-of join looks for its match. */
+export declare const DIRECTIONS: readonly string[];
+/**
+ * Copy the members a spec authored into the shape the kernel takes,
+ * compiling each through its own rule. Members absent from the document
+ * stay absent, so the kernel's own defaults are the only defaults.
+ * @param {any} spec - the captured literal
+ * @param {any} provider - `options.zoneProvider`, or null
+ * @param {string} docPath
+ * @param {Record<string, (value: any, member: string, docPath: string) => any>} rules
+ * @returns {any} the kernel spec
+ */
+export declare function buildKernelSpec(spec: any, provider: any, docPath: string, rules: Record<string, (value: any, member: string, docPath: string) => any>): any;
+/**
+ * The rows a series operand carries.
+ *
+ * Both spellings a document actually has work, and neither is ambiguous
+ * because a sample is an object: a path that fans out (`$.rows[*]`)
+ * arrives as a sequence of rows, and a path that does not (`$.rows`)
+ * arrives as the one array item that holds them. The empty sequence is
+ * an empty series — no rows is data, not an error.
+ *
+ * @param {any} v - the evaluated operand
+ * @param {string} docPath
+ * @returns {any[]}
+ * @throws {JsonQueryRuntimeError} JQ2001 when it is not rows at all
+ */
+export declare function seriesArg(v: any, docPath: string): any[];
+/**
+ * One half-open interval operand: a record with a `start` and an `end`.
+ * The kernel decides whether the bounds name instants and whether the
+ * span is a span; this only refuses what is not a record.
+ * @param {any} v
+ * @param {string} docPath
+ * @returns {any}
+ * @throws {JsonQueryRuntimeError} JQ2001
+ */
+export declare function intervalArg(v: any, docPath: string): any;
+/**
+ * The kernel's refusals, in this language's vocabulary. Everything the
+ * temporal kernel throws is a `TypeError` about the DATA it was handed —
+ * a row that is not a sample, an instant that names none, a local time
+ * that never happened — which is exactly what `JQ2001` is for. A host
+ * failure that is not a `TypeError` is not laundered.
+ * @param {unknown} e
+ * @param {string} docPath
+ * @returns {JsonQueryRuntimeError}
+ */
+export declare function seriesRefusal(e: unknown, docPath: string): JsonQueryRuntimeError;

package/docs/QUERY-FORMAT.md

@@ -1233,7 +1233,7 @@ by an ISO 8601 duration (`[date, "P1M"]`) or by an amount and a unit
 `hour`, `minute`, `second`, `millisecond` — so an unknown one is `JQ2001`
 rather than a compile error.
 
-Two rules make these predictable:
+Three rules make these predictable:
 
 - **The lexical form is preserved.** A `full-date` shifted by a day is still
   a `full-date`, and a `date-time` keeps its own offset rather than being
@@ -1245,6 +1245,19 @@ Two rules make these predictable:
   because the alternative — overflowing into March — makes adding a month
   non-monotonic. `$date-diff` counts months to match, so adding its result
   back never overshoots: `2026-01-31` to `2026-02-28` is **one** month.
+- **An operation that needs a half the value has not got is refused.** A unit
+  names a half: `year` through `day` read the calendar, `hour` through
+  `millisecond` read the clock. Adding hours to a `full-date`, adding a day
+  to a `full-time`, or truncating either to the unit it does not carry is
+  `JQ2001` — there is no answer to give, and the alternative to refusing is
+  to invent one. `$start-of`/`$end-of` `day` is the boundary both forms have:
+  a `full-time` truncates to midnight and to `23:59:59.999`.
+
+A **fraction** is a quantity only where the unit converts exactly.
+`[date, 1.5, "day"]` and `[date, "P1.5D"]` are thirty-six hours, applied as
+whole milliseconds — so both need a value with a clock to land on. Half a
+month is not a length and is `JQ2001`; half a *year* is six months exactly,
+and applies.
 
 `$date-format` renders a value through a **Unicode LDML** pattern
 (`yyyy-MM-dd`, not moment's `YYYY-MM-DD`); a literal pattern compiles once
@@ -1264,9 +1277,9 @@ the presentation layer, not to a query.
 | `$quarter` `$weekday` | calendar quarter 1-4; ISO weekday 1 (Monday) to 7 (Sunday) |
 | `$epoch` | date or date-time → milliseconds since the epoch (UTC); a `full-time` → `JQ2001` |
 | `$datetime` | epoch milliseconds → canonical UTC `date-time`; out of RFC 3339 range → `JQ2001` |
-| `$date-add` `$date-sub` | `[date, duration]` or `[date, amount, unit]` → a value of the same lexical form |
-| `$start-of` `$end-of` | `[date, unit]` → the unit's first / last instant, in the same lexical form |
-| `$date-diff` | `[from, to, unit]` → whole units, negative when `to` precedes `from` |
+| `$date-add` `$date-sub` | `[date, duration]` or `[date, amount, unit]` → a value of the same lexical form; a fraction that has no exact conversion, or a unit the value has no half for, is `JQ2001` |
+| `$start-of` `$end-of` | `[date, unit]` → the unit's first / last instant, in the same lexical form; a sub-day unit on a `full-date`, or `week` and coarser on a `full-time`, is `JQ2001` |
+| `$date-diff` | `[from, to, unit]` → whole units, negative when `to` precedes `from`; a value with no date half is `JQ2001` for every unit |
 | `$date-format` | `[date, pattern]` → the value rendered through an LDML pattern |
 
 Every operator that *produces* a date produces it in the same canonical
@@ -1525,6 +1538,161 @@ A filter is the same key in a `$where`, and it composes with the ordering:
 threshold filter for free.
 
 
+### 8.16 Time series
+
+A time series is what a JSON document already holds when something has been
+measured repeatedly: **records with an instant and a reading**. There is no
+series type to construct and nothing to declare — `{"at": 1767225600000,
+"value": 4.5}` is a sample, and `{"start": …, "end": …}` is an interval.
+
+These five operators are the vocabulary for questions a `$for` phrase can ask
+but cannot answer in one pass: *do these two spans collide*, *which bucket
+does this instant fall in*, *what does an hour of this look like*, *what was
+the average over the last five minutes at every point*, and *what was the
+current value when this happened*. Each is a call into
+[`@jarenjs/core/series`](../../core/README.md) and nothing else — the same
+kernel a chart and an indexed database read — so a document, a fluent chain
+and a stored plan cannot answer the same question differently.
+
+| Operator | Definition |
+|---|---|
+| `$overlaps` | `[a, b]` → do two half-open `{start, end}` intervals share an instant; touching spans do **not** overlap |
+| `$time-bucket` | `[at, every, origin?, context?]` → the instant labelling the bucket `at` falls in |
+| `$resample` | `[series, spec]` → sorted `{at, value, count}` buckets, one per `every` |
+| `$rolling` | `[series, spec]` → one `{at, value, count}` per input instant, over a window measured in **time** |
+| `$asof` | `[left, right, spec?]` → one `{left, right, distance}` per left row: the right row that was current when it happened |
+
+**Instants are epoch milliseconds** on both sides of these operators — what an
+indexed column stores and what arithmetic wants. A source row may spell its
+instant as an RFC 3339 string and it is converted once, at the door; every
+`at` these operators *produce* is a number. `$epoch` and `$datetime` are the
+two conversions, and they already exist:
+`{"$datetime": {"$time-bucket": [{"$epoch": "$e.on"}, "PT1H"]}}`.
+
+**A series operand is either spelling.** A path that fans out (`$.rows[*]`)
+arrives as a sequence of rows; one that does not (`$.rows`) arrives as the
+array holding them. The empty sequence is an empty series — no rows is data.
+
+#### Specs are literals
+
+The second operand of `$resample`, `$rolling` and `$asof` — and the fourth of
+`$time-bucket` — is a **verbatim JSON literal**, not an expression. Nothing
+inside it is evaluated and nothing inside it can vary per row, which is what
+lets the width, the aggregate, the fill policy, the wall clock and the row
+selectors be read exactly once when the query compiles.
+
+Each spec is **closed**: it admits the members below and no others. An unknown
+member is `JQ0003` with the near miss named, because a `minPeriod` silently
+ignored is the bug that costs an afternoon. So is a bad duration, a bad
+aggregate, a bad path and a zone with no provider. Only what the *data*
+decides — a row that is not a sample, an instant that names none, a local time
+that never happened — is `JQ2001`, against the operand that carried it.
+
+| Spec | Members |
+|---|---|
+| `$resample` | `every` (required), `origin`, `start`, `end`, `aggregate`, `fill`, `at`, `value`, and the calendar context |
+| `$rolling` | `width` (required), `aggregate`, `minPeriods`, `at`, `value`, and the calendar context |
+| `$asof` | `direction`, `tolerance`, `by`, `leftAt`, `rightAt` |
+| calendar context | `zone`, `offset`, `disambiguation` |
+
+`every`, `width` and `tolerance` are an ISO 8601 duration (`"PT1H"`, `"P1M"`)
+or a count of milliseconds. `origin`, `start` and `end` are epoch milliseconds
+or an RFC 3339 string. `aggregate` is one of `sum`, `mean`, `min`, `max`,
+`first`, `last`, `count` (default `mean`); `fill` is one of `omit`, `null`,
+`zero`, `locf`, `linear` (default `omit`); `direction` is `backward` (default),
+`forward` or `nearest`.
+
+`at`, `value`, `by`, `leftAt` and `rightAt` are **row selectors**: a singular
+path where `$` reads as the *row* rather than as the document, so a series
+spelled `{"on": …, "reading": …}` is read with `{"at": "$.on", "value":
+"$.reading"}` and nothing has to be rewritten first. Wildcards, descendants
+and filters are refused (`JQ0003`) — a selector names one member.
+
+#### Buckets, fill and the count
+
+`$resample` labels every bucket at its **start** and reports `count`, the
+number of source rows that fell in it — duplicates and gaps included. The six
+value aggregates skip a `null` reading, so `value` is `null` exactly when
+there was nothing to measure and `count` says whether that was because nobody
+reported or everybody reported a gap. `aggregate: "count"` returns that same
+number as `value`.
+
+`fill` decides what an **empty** bucket says, and nothing else. `omit` leaves
+it out; `null` and `zero` emit it with that value; `locf` carries the last
+measured bucket forward; `linear` interpolates between its two neighbours.
+Neither `locf` nor `linear` extrapolates: with no measured bucket on the side
+it needs, the bucket stays `null`. A bucket that held rows and no numbers is a
+*measurement*, not an absence, and is never an anchor for either.
+
+```json
+{ "$resample": [ "$.readings[*]",
+                 { "every": "PT1H", "aggregate": "mean", "fill": "linear" } ] }
+```
+
+#### Windows measured in time
+
+`$rolling` answers one row per input instant, over the half-open window
+ending at it. `minPeriods` (default 1) withholds a value — `null`, with the
+real `count` — for a window that is short of that many readings, which is how
+a leading partial window stays visible instead of being quietly averaged.
+
+Rows sharing an instant share a window and share an answer: the window is a
+function of the instant it ends at, never of arrival order. That is the one
+place `$rolling` differs from `$for`'s `$window` (§6.4), which counts **rows**
+and is unchanged.
+
+```json
+{ "$rolling": [ "$.samples[*]", { "width": "PT5M", "aggregate": "mean", "minPeriods": 30 } ] }
+```
+
+#### As-of, and no-match as data
+
+`$asof` walks both sides once and answers `{left, right, distance}` per left
+row. `backward` takes the last right row at or before the left instant,
+`forward` the first at or after, `nearest` the closer of the two with ties
+going backward. At an equal instant the **last** right row wins, because "as
+of" means the later reading. `tolerance` is the furthest a match may be —
+beyond it there is no match, not a distant one — and `by` joins within groups.
+
+A left row with nothing to match is `{"left": …, "right": null, "distance":
+null}`. **It stays in the answer**: no match is data, and a join that dropped
+the row would be answering a question nobody asked.
+
+```json
+{ "$asof": [ "$.trades[*]", "$.quotes[*]",
+             { "by": "$.symbol", "direction": "backward", "tolerance": "PT1M" } ] }
+```
+
+#### Calendar boundaries and the zone seam
+
+A fixed width (`PT15M`, `P1D` on UTC or an offset) is integer arithmetic. A
+calendar width (`P1M`, `P1Y`, and a day on a *named* zone, where the day the
+clock changed is 23 or 25 hours long) walks a wall clock instead. A width
+mixing the two families (`P1MT1H`) is refused.
+
+UTC is the default and needs nothing. `{"offset": 120}` is a constant number
+of minutes east and is exact. A **named zone needs a time-zone database this
+suite deliberately does not bundle**, and a JSON document cannot carry one, so
+`{"zone": "Europe/Amsterdam"}` compiles only when the host injected
+`options.zoneProvider` — an object with `toParts(epoch, zone)` and
+`toEpoch(parts, zone, disambiguation)`. Without it the document is refused
+(`JQ0003`) naming the seam, rather than falling back to UTC and being right
+for eight months of the year.
+
+`disambiguation` says what a local time that happens twice, or never, resolves
+to: `reject` (the default — it is an error), `earlier` or `later`.
+
+```json
+{ "$resample": [ "$.readings[*]",
+                 { "every": "P1M", "zone": "Europe/Amsterdam", "aggregate": "sum" } ] }
+```
+
+**Nothing here reads a clock.** `$resample`'s window, when `start`/`end` are
+absent, derives from the data; there is no `$now`, for the same reason §8.13
+has no `current-dateTime`. A compiled query gives the same answer for the same
+document forever.
+
+
 ## 9. Variables, scoping, and external parameters
 
 1. Variables are introduced by `$for`, `$let`, `$at`, `$count`, `$groupby`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/json",
   "private": false,
-  "version": "0.46.4",
+  "version": "0.49.2",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -90,6 +90,6 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.46.4"
+    "@jarenjs/core": "^0.49.2"
   }
 }