@jarenjs/db 0.46.5 → 0.49.2

package/ARCHITECTURE.md

@@ -153,6 +153,17 @@ member the schema types as an array or an object. Those are exact; the
 spatial predicates that only NARROW are rows in the residual table, and
 the implied-conjunct table below carries every proof.
 
+Plus one GROUPING a composite instant index makes exact: the
+fixed-width temporal bucket. A `$groupby` whose single key is
+`$time-bucket` over a schema-typed integer epoch path with a literal
+width and origin, projected to the group key plus `$count` of the
+binding and `$sum`/`$avg`/`$min`/`$max` over singular schema-typed
+numeric paths, becomes a `GROUP BY` over integer arithmetic. So does a
+`$resample` whose frozen spec asks for nothing that ladder cannot do —
+a fixed width, `fill: 'omit'`, and one of `sum|mean|min|max|count`.
+Everything else about time is a NAMED refinement ("The temporal plan"
+below).
+
 Plus one ORDERING a **`derive: 'vector'`** column makes cheap without
 making it native: the k-nearest composition — `$orderby` on a
 `$similarity` key, descending, `$empty: 'least'`, under a `$subsequence`
@@ -181,6 +192,7 @@ mode, `knn`, beside native, row and set.
 | the k-nearest ordering over a `derive: 'vector'` column | the column cuts the candidates; the engine orders them (mode `knn`, "The k-nearest plan" below) — engine work, so `strict: true` refuses it |
 | `$similarity` anywhere else — a threshold in `$where`, a score in `$return`, a second ordering key | no native spelling; runs in the residual over whatever the rest of the document pushed |
 | the k-nearest shape with no finite window, ascending, `$empty: 'greatest'`, a probe that is neither a literal vector nor an external, a literal probe of another width, or a selection not pushed whole (a residual conjunct, an implied one, a `$let` before the where) | nothing is proven; the whole document runs in the engine, and `explain()` names which precondition failed — a k-nearest query never falls to the full scan silently |
+| `$resample` with a fill policy other than `omit`, `$rolling`, `$asof`, `first`/`last`, a calendar width, a named zone, a `$time-bucket` whose width or origin is an EXPRESSION, or an instant the schema does not type as an integer | the index bounds the fetch and `@jarenjs/core/series` decides over what comes back; `explain().series.reasons` carries the CODE — `fill-policy`, `rolling-refinement`, `asof-refinement`, `unsupported-aggregate`, `calendar-width`, `named-zone`, `nonliteral-spec`, `instant-not-integer` — and `strict: true` refuses every one of them |
 
 ### The type truth table
 
@@ -418,6 +430,79 @@ engine's business. With `strict: true` the shape is `JD0010` naming the
 rank: the order is engine work, the same honesty as a spatial
 refinement.
 
+### The temporal plan (series)
+
+Time needs no storage kind here. The physical declaration is the
+composite JSONPath index a model already has —
+`{ "name": "by_series_at", "path": ["$.series", "$.at"] }` — over a
+numeric epoch member, and the whole of `src/series.js` is deciding
+which questions that index answers. There is no `derive: 'series'`, no
+column type, no host function and no extension.
+
+A B-tree seeks exactly as far as its leading columns are decided: a run
+of equalities, then at most one range. So the index that a temporal
+plan reports is the declared one with the longest leading run of
+columns an equality PINNED whose next column is the instant the query
+ranges over. Three shapes follow from that, and they are closed:
+
+| shape | the document | the plan |
+|---|---|---|
+| **range** | every leading column pinned, a half-open range on the instant, ordered by it | native — `SEARCH … (series=? AND at>? AND at<?)` |
+| **as-of** | the same prefix with ONE instant bound, ordered by the instant, under a finite window | native — the index read backwards, one row |
+| **bucket** | a `$groupby` over `$time-bucket`, or a `$resample` whose spec asks for nothing more | native — `GROUP BY` over `at - (((at - origin) % every + every) % every)` |
+
+The ladder is integer arithmetic all the way down, and the non-negative
+remainder is why: a truncating division puts an instant before 1970 in
+the bucket AFTER its own. The width and the anchor are read through the
+kernel's own `compileBuckets`, so `'PT1H'` and `3600000` are the same
+ladder and the default anchor is the kernel's rather than a second
+guess at it; an `{ offset }` calendar context folds into the anchor,
+because a constant number of minutes east is arithmetic. A named zone
+never does: its clock is host code the database does not have.
+
+Everything else is a **named refinement** — the implied-conjunct
+pattern again, applied to a whole operator. The planner narrows the
+fetch by whatever the frozen spec makes provable and the residual, which
+is the ENGINE running the caller's own document, decides:
+
+| operator | what bounds the fetch |
+|---|---|
+| `$resample` (fill, calendar, `first`/`last`) | the spec's own `start`/`end`, plus the operand's `$where` |
+| `$rolling` | the operand's `$where` alone — a window measured in time answers once per input instant |
+| `$asof` with the collection on the RIGHT | the probes' own span (`at <= max` backward, `at >= min` forward, both sides under a `tolerance`) and a membership test over the probes' `by` keys |
+| `$asof` with the collection on the LEFT | nothing — a join answers once per LEFT row, so every left row is needed |
+
+The as-of bound is one STATEMENT, whatever the probes number, which is
+what `test/db/statement-count.test.js` pins: the failure mode a batch
+exists to refuse is one seek per left row. Without a `tolerance` a
+backward join can only be bounded ABOVE, so that one statement can read
+most of a long history — `benchmark/series.js` publishes the candidate
+count beside the timing rather than netting it out.
+
+**A group with no instant.** A row whose instant member is missing or
+is not a number groups under SQL `NULL`; the kernel REFUSES such a row
+(`JQ2001`). SQL cannot refuse, so a native bucket that meets one hands
+the whole question back — the full-collection residual, where the engine
+answers what it answers everywhere — and the fallback is COUNTED as
+`collection.stats().series.diverted`, the same honesty the k-nearest
+divert has.
+
+**`explain().series`** is `null` unless the document asked a temporal
+question, which it does by naming a §8.16 operator or by being the
+closed range/as-of shape over a COMPOSITE instant index. (A singular
+index over an ordinary member cannot make a query temporal: nothing in
+a column says "instant", and inventing one would make every `age > 21`
+a temporal plan.) It carries `{ mode, operation, index, prefix, range,
+ladder, aggregates, refinement, reasons, counts }`. `mode` is
+`'native'` (the statement alone answers), `'hybrid'` (the database
+narrows and a kernel decides) or `'engine'` (the database narrowed
+nothing). `reasons` is `{ code, reason }` where the code is the first
+word of the sentence, so the machine-readable code and the sentence
+`strict: true` prints cannot drift apart. `counts` is the LAST ACTUAL
+execution's `{ statements, candidates, results }` and is `null` before
+the document has run once — an estimate mislabelled as a count is
+exactly what an honest explain may not print.
+
 ### The two residual modes
 
 - **Row residual** — only the projection is untranslated: predicates,
@@ -465,7 +550,9 @@ and this is where it says so (MODEL-FORMAT §4). Under `'rtree'` the
 names the virtual table. `rank` is `null` or the k-nearest stage —
 `{ column, dims, probe, limit, offset, margin, decides: 'engine' }` —
 what the fetch reads, the window the cut serves, the margin it keeps,
-and who decides the order (always the engine). `estimatedRows` is ABSENT on SQLite drivers — the capability slot
+and who decides the order (always the engine). `series` is `null` or
+the temporal record ("The temporal plan" above), whose `counts` are the
+last ACTUAL run's rather than an estimate. `estimatedRows` is ABSENT on SQLite drivers — the capability slot
 is empty and no number is fabricated. `residual` is `null` or
 `{ mode: 'row' | 'set' | 'knn', reasons: [{ construct, reason }] }` with
 reasons drawn from the deliberate-residual table. With
@@ -578,7 +665,7 @@ rollback truncates the journal buffer to its checkpoint. Overhead is
 measured and published: capture off ~6µs, journal ~17µs, session ~69µs
 per single-op commit, amortizing across a transaction.
 
-## Live queries (`src/live.js`, `src/window.js`)
+## Live queries (`src/live.js`, `src/live-time.js`, `src/window.js`)
 
 A live query classifies its document against the normative maintenance
 table by reading the COMPILED PLAN — translated filters, order terms
@@ -605,6 +692,23 @@ proven by a seeded oracle that holds the maintained result equal to a
 fresh re-query after every mutation. Incremental beats re-run 13× at
 1k rows, 51× at 10k.
 
+**Event time** (`src/live-time.js`) adds two more strategies for the
+one document shape whose answer is a function of instants rather than
+of rows: a `$resample` bucket state and a `$rolling` window state, both
+over a FIXED width. There is no clock under either — the watermark is a
+finite epoch the host supplies and `advance()` is the only way it moves
+— and both fold through `@jarenjs/core/series` itself rather than
+carrying a second aggregate, so a maintained answer cannot drift from
+what a fresh query gives. A write touches one bucket (two when it
+crosses a boundary) or the windows ending in `[t, t + width)`, and
+exactly those are recomputed. Everything a per-key state cannot place
+exactly re-runs with its member named: a calendar ladder, a named zone,
+a `locf`/`linear` fill, a `first`/`last` aggregate, a retention under
+`width + allowedLateness`. A reading behind the lateness boundary is
+never folded in silently — the view re-reads and the emission carries a
+`lateData` record — which is the one place this layer spends a full
+re-query to keep a promise rather than a number.
+
 ## Durable runs and the job queue (`src/jobs.js`, `src/dag-job.js`)
 
 The queue's whole correctness story is one guarded statement: the

package/README.md

@@ -113,6 +113,17 @@ shape binds at `store.collection<User>('users')`.
   decided or merely narrowed. The worked example, the geofence and the
   measured numbers are in [Spatial storage](#spatial-storage--the-model-the-plan-the-fence-the-numbers)
   below.
+- **A time series is a composite index, not a storage kind.** Declare
+  `{ "path": ["$.series", "$.at"] }` over a numeric epoch member and the
+  planner recognizes three shapes over it: a half-open range under a
+  series equality, an as-of lookup (the index read backwards, one row),
+  and a fixed-width bucket ladder — a `$groupby` over `$time-bucket`, or
+  a `$resample` whose spec asks for nothing a `GROUP BY` cannot do — as
+  integer arithmetic in SQL. A fill policy, a calendar width, a rolling
+  window and an as-of JOIN are **named refinements**: the index bounds
+  the fetch and `@jarenjs/core/series` decides, with `explain().series`
+  carrying the reason code and the last run's actual candidate and
+  result counts. See [Time series](#time-series--the-index-the-ladder-the-refinement).
 - **Migrations are documents.** `planMigration` diffs two models into
   rendered-DDL + JSLT-transform + assertion steps; a shadow database
   replays the whole chain before the real store is touched; a
@@ -445,6 +456,91 @@ and unindexed — and every entry must answer identically, including a
 deliberate one-binary32-ulp near-tie and the windows that reach past the
 scored rows into the tail the column cannot rank.
 
+## Time series — the index, the ladder, the refinement
+
+The physical declaration is one a model already has:
+
+```json
+{ "name": "by_series_at", "path": ["$.series", "$.at"] }
+```
+
+No `derive` kind, no column type, no host function, no extension. What
+the planner adds is the reading of that index — a B-tree seeks as far
+as its leading columns are decided, so a query that pins `series` with
+an equality and ranges over `at` is a SEARCH, and one that only bounds
+`at` is a scan the plan says so about.
+
+```js
+// native: SEARCH sample USING INDEX sample_by_series_at (gx_series=? AND gx_at>? AND gx_at<?)
+await sample.execute({
+  $for: { s: '$[*]' },
+  $where: { $and: [
+    { $eq: ['$s.series', 'sensor-a'] },
+    { $ge: ['$s.at', from] },
+    { $lt: ['$s.at', to] },
+  ] },
+  $orderby: [{ $key: '$s.at' }],
+  $return: '$s',
+});
+
+// native: the same index, GROUP BY over integer bucket arithmetic
+await sample.execute({ $resample: [
+  { $for: { s: '$[*]' }, $where: { $eq: ['$s.series', 'sensor-a'] }, $return: '$s' },
+  { every: 'PT1M', aggregate: 'mean' },
+] });
+
+// hybrid: the index bounds the fetch, rollingSeries decides
+await sample.execute({ $rolling: [
+  { $for: { s: '$[*]' }, $where: { $eq: ['$s.series', 'sensor-a'] }, $return: '$s' },
+  { width: 'PT1M', aggregate: 'mean', minPeriods: 30 },
+] });
+```
+
+**The numbers, the loss included.** `benchmark/series.js` answers the
+same range, the same buckets, the same rolling window and the same
+as-of join over one seeded corpus by plain references, by the temporal
+kernel, by a generic query document, by hand-written SQL and by the
+store — every route checked against the others before a timing is
+taken. At <!--bm:series.corpus-->100,000 samples at 1-second spacing, Node v24.19.0<!--/bm-->,
+the store is measured three ways at once — <!--bm:series.storeShapes-->the planned range costs 4.2× the hand-written statement and 1535.5× the resident cut, and the pushed bucket ladder 2.5× the hand-written GROUP BY, 1.6× FASTER than the generic query route, and 155.1× the one-pass loop<!--/bm-->.
+The range row is not the planner's price: the statement selects two
+COLUMNS where the store renders and parses a whole JSON document per
+row, which is what storing documents costs.
+
+And what a refinement costs, with the loss in it: <!--bm:series.storeRefinement-->A window measured in time is not pushed: the store answers it at 18.5× the kernel over an array already in memory, over 100,000 candidates the index bounded. The batched as-of join reads 99,129 rows in 1 statement and costs 1424.3× fifty-one separate index reads — a bound is what it buys, not a speed-up, and without a tolerance a backward join can only be bounded above.<!--/bm-->
+
+**A refinement is named, never quiet.** `explain().series` reports
+`mode` — `native`, `hybrid` or `engine` — the declared index the fetch
+seeks through, the instant bounds it used, which kernel finished the
+answer, and a reason code for every thing the database could not do:
+`fill-policy`, `calendar-width`, `named-zone`, `rolling-refinement`,
+`asof-refinement`, `unsupported-aggregate`, `nonliteral-spec`,
+`instant-not-integer`, `missing-series-prefix`. `strict: true` refuses
+every one of them before a statement runs, and the counts `explain()`
+prints are the LAST ACTUAL execution's — `null` until the document has
+run, because an estimate wearing a count's name is worse than no
+number.
+
+**The as-of join is bounded, and the bound is the claim.** `$asof` with
+the collection on the right reads the probes it was given, bounds the
+fetch by their own span and by a membership test over their `by` keys,
+and issues exactly ONE statement whatever the probes number — the
+failure mode a batch exists to refuse is one seek per left row, and
+`test/db/statement-count.test.js` pins it at 1, 10 and 200 probes.
+Without a `tolerance` a backward join can only be bounded ABOVE, so
+that one statement can read most of a long history: the benchmark
+publishes the candidate count beside the timing rather than netting it
+out, and at fifty-one probes over a hundred thousand rows the batch
+LOSES to fifty-one separate index reads. Few questions of a large
+series belong to a batch; a join of two series does.
+
+**One corpus, five executors, proven to agree.** The committed temporal
+corpus (`test/json/fixtures/series-corpus.json`) runs through the plain
+references, the query vocabulary, `node:sqlite`, a real wasm build and
+both drivers again with pushdown forced off — indexed and unindexed —
+and every case must answer identically, plan mode and reason codes
+included.
+
 ## What SQLite-only means, frankly
 
 SQLite is the supported backend — 3.45 or newer, on `node:sqlite`,
@@ -493,7 +589,7 @@ SQLite's own story (WAL plus a busy timeout, both set and visible on
   journal where it does not (`bun:sqlite`, the wasm build). One diff
   format runs store → patch → live query → O(k) render. Capture is
   opt-in; the overhead is published, not waved away.
-- **Live queries** (LIVE-FORMAT §§7–12): `collection.live(document)`
+- **Live queries** (LIVE-FORMAT §§7–13): `collection.live(document)`
   maintains a result as writes arrive and emits patches — incremental
   for `where`/`select`/`orderBy`+`limit`/aggregates/single-level
   `groupBy` and a spatial `where` over a derived index (the geofence;
@@ -501,6 +597,11 @@ SQLite's own story (WAL plus a busy timeout, both set and visible on
   **declared, never silent** (`live.mode` names the reason).
   Unaffected rows stay reference-identical; a seeded oracle holds the
   maintained result equal to a fresh re-query after every mutation.
+- **Event time** (LIVE-FORMAT §13): a `$resample` or `$rolling` view
+  over a fixed width maintains exact event-time buckets and windows
+  against a watermark the HOST supplies — never a clock — and a reading
+  behind the declared lateness re-reads and emits a `lateData` record
+  rather than being folded in as though it had arrived on time.
 - **Durable runs and the job queue** (JOBS-FORMAT, FLOW-FORMAT §7.6):
   a `@jarenjs/flow` DAG run checkpoints declared nodes and RESUMES
   after a crash; `store.jobs` leases work in one guarded statement
@@ -512,6 +613,35 @@ SQLite's own story (WAL plus a busy timeout, both set and visible on
   connection, others are clients. Proven in the `#/data` studio across
   Chromium, Firefox and WebKit.
 
+### What an event-time view costs
+
+`benchmark/live.js` maintains a 60 s bucket ladder and a 5 minute
+rolling window over a seeded series and rewrites one reading per commit,
+inside the lateness the view allows. The maintained rows are checked
+against `resampleSeries` / `rollingSeries` over the **whole** collection
+before a single timing is printed — a fast live view with the wrong
+answer is not a fast live view — and the run exits non-zero if they
+disagree.
+
+<!--bm:live.eventTimeTable-->
+| view | maintained | re-run | ratio |
+|---|---:|---:|---:|
+| bucket (60 s ladder, mean), 1000 rows | 119 µs | 1.09 ms | 9.2× |
+| rolling (5 min window, mean), 1000 rows | 407 µs | 3.86 ms | 9.5× |
+| bucket (60 s ladder, mean), 10000 rows | 136 µs | 10.9 ms | 80.2× |
+| rolling (5 min window, mean), 10000 rows | 13.7 ms | 62.7 ms | 4.6× |
+<!--/bm-->
+
+The gain is <!--bm:live.eventTimeBand-->80.2× for the bucket and 4.6× for the rolling at 10,000 readings<!--/bm-->. A bucket
+view is nearly flat in the series length, because a write folds one
+bucket again and the rest of the ladder is untouched. A rolling view is
+not, and the table says so: its answer is one row per reading, so the
+emitted diff walks every one of them whatever changed. A bucket view
+also holds one maintained entry per reading *plus* one per bucket, which
+is over §12's default `maxMaintained` at ten thousand readings — the
+bound errors rather than degrading, and raising it is a decision
+somebody makes.
+
 ## Sync-readiness — what exists and what does not
 
 The change stream is an ordered log of RFC 6902 patches with a
@@ -540,6 +670,10 @@ replication on these primitives is a roadmap item, not a hint.
   priority classes, no cron, no workflow compensation.
 - **Live-query maintenance is limited to the declared table** (§7);
   joins, entity queries and non-canonical shapes re-run, reported.
+- **`eventTime.retention` bounds repair work, not memory.** It is the
+  horizon a view claims and is checked against the window it maintains;
+  the maintained state is still bounded by `live.maxMaintained`, and no
+  version of this compacts a bucket's rows away.
 - **The wasm build journals** (its session extension is not yet
   adapted); OPFS needs a secure context, and where it is absent the
   store runs in memory with the durability difference stated.
@@ -554,7 +688,7 @@ profile §8, entities §9, relational translation §10, the unit of work
 §11), [docs/MIGRATION-FORMAT.md](docs/MIGRATION-FORMAT.md) (documents
 §§1–8, relational changes §§9–12),
 [docs/LIVE-FORMAT.md](docs/LIVE-FORMAT.md) (capture §§1–6, live queries
-§§7–12) and [docs/JOBS-FORMAT.md](docs/JOBS-FORMAT.md) (the durable
+§§7–12, event time §13) and [docs/JOBS-FORMAT.md](docs/JOBS-FORMAT.md) (the durable
 queue §§1–9); the seams, the pushdown contract and every engine are in
 [ARCHITECTURE.md](ARCHITECTURE.md); the benchmark methodology is in
 [benchmark/README.md](../../benchmark/README.md).

package/dist/types/algebra.d.ts

@@ -10,9 +10,10 @@
  * One plan shape covers this version: a guarded selection over ONE
  * collection with optional ordering, window, aggregate and a
  * whole-document projection — or, instead of an ordering and a window,
- * a k-nearest RANK the engine finishes over the rows the plan fetches.
- * Constructs beyond it are residuals by design (see ARCHITECTURE.md's
- * deliberate-residual table).
+ * a k-nearest RANK the engine finishes over the rows the plan fetches,
+ * or, instead of a projection, a fixed-width temporal BUCKET the plan
+ * groups and aggregates itself. Constructs beyond it are residuals by
+ * design (see ARCHITECTURE.md's deliberate-residual table).
  */
 /** The plan format version, carried on every plan. */
 export declare const PLAN_VERSION = 2;
@@ -85,6 +86,19 @@ export type PlanOrderTerm = {
     desc: boolean;
     emptyGreatest: boolean;
 };
+export type PlanBucket = {
+    ref: PlanRef;
+    every: number;
+    origin: number;
+    as: string;
+    order: 'asc' | 'desc' | 'first-seen';
+    aggregates: {
+        fn: 'rows' | 'sum' | 'avg' | 'min' | 'max';
+        ref: PlanRef | null;
+        as: string;
+        empty: 'null' | 'zero' | 'omit';
+    }[];
+};
 export type PlanRank = {
     column: string;
     dims: number;
@@ -108,6 +122,7 @@ export type Plan = {
         limit: number | null;
     } | null;
     rank: PlanRank | null;
+    bucket: PlanBucket | null;
     aggregate: {
         fn: 'count' | 'sum' | 'avg' | 'min' | 'max';
         ref: PlanRef | null;
@@ -152,6 +167,21 @@ export type Plan = {
  *
  * @typedef {{ ref: PlanRef, desc: boolean, emptyGreatest: boolean }} PlanOrderTerm
  *
+ * @typedef {{ ref: PlanRef, every: number, origin: number, as: string,
+ *   order: 'asc' | 'desc' | 'first-seen',
+ *   aggregates: { fn: 'rows' | 'sum' | 'avg' | 'min' | 'max',
+ *     ref: PlanRef | null, as: string,
+ *     empty: 'null' | 'zero' | 'omit' }[] }} PlanBucket
+ *   The fixed-width temporal GROUP BY: the instant column, the ladder's
+ *   width and anchor in epoch milliseconds, the name the bucket's start
+ *   is answered under, how the groups are ordered, and one aggregate
+ *   per answered member. `rows` is `COUNT(*)` — the D5 count of SOURCE
+ *   rows, duplicates and measured gaps included — and the four value
+ *   aggregates skip a `NULL` reading exactly as the kernel skips a
+ *   `null` one. `first-seen` order is the group's earliest row identity,
+ *   which is the engine's own "order of first appearance" (§6.5).
+ *   A plan carrying a bucket carries no `aggregate` and no `rank`.
+ *
  * @typedef {{ column: string, dims: number,
  *   probe: { lit: number[] } | { ext: string },
  *   offset: number, limit: number, margin: number }} PlanRank
@@ -174,6 +204,7 @@ export type Plan = {
  *   order: PlanOrderTerm[] | null,
  *   window: { offset: number, limit: number | null } | null,
  *   rank: PlanRank | null,
+ *   bucket: PlanBucket | null,
  *   aggregate: { fn: 'count' | 'sum' | 'avg' | 'min' | 'max',
  *     ref: PlanRef | null } | null,
  *   project: 'document',

package/dist/types/dialect.d.ts

@@ -60,6 +60,9 @@ export type JsonPathSegment = {
  *   strEndsWith: (valueSql: string, patternA: string, patternB: string, patternC: string) => string,
  *   strContains: (valueSql: string, patternSql: string) => string,
  *   orderNulls: (nullsFirst: boolean) => string,
+ *   timeBucket: (instantSql: string, originSql: string, everyA: string,
+ *     everyB: string, everyC: string) => string,
+ *   groupAggregate: (fn: string, valueSql: string | null) => string,
  *   rowIdentity: () => string,
  *   identityIn: (identitySql: string, paramSqls: string[]) => string,
  *   rtree?: { module: string, columns: readonly string[] },
@@ -114,6 +117,8 @@ export declare function createDialect(spec: {
     strEndsWith: (valueSql: string, patternA: string, patternB: string, patternC: string) => string;
     strContains: (valueSql: string, patternSql: string) => string;
     orderNulls: (nullsFirst: boolean) => string;
+    timeBucket: (instantSql: string, originSql: string, everyA: string, everyB: string, everyC: string) => string;
+    groupAggregate: (fn: string, valueSql: string | null) => string;
     rowIdentity: () => string;
     identityIn: (identitySql: string, paramSqls: string[]) => string;
     rtree?: {

package/dist/types/errors.d.ts

@@ -31,6 +31,7 @@ export declare const DB_CODES: Readonly<{
     JD0050: "live queries require change capture";
     JD0051: "the demanded live mode is unavailable";
     JD0052: "the live-query bound was reached";
+    JD0053: "the live event-time declaration is invalid";
     JD0020: "the migration's from-shape does not match the database";
     JD0021: "the migration is missing a required data transform";
     JD0022: "an applied migration disagrees with the history record";
@@ -90,6 +91,8 @@ export declare const DB_CODES: Readonly<{
  *    classifies as re-run; the reason names the forcing construct
  *  - `JD0052` — registering would exceed the store's `live.maxQueries`
  *    bound; the bound is printed, never silent
+ *  - `JD0053` — a live query's `eventTime` names a member it does not
+ *    admit, or a watermark/retention that is not a finite span
  *  - `JD0020` — a migration's `from` hash does not match the
  *    database's recorded shape; running it would corrupt
  *  - `JD0021` — a draft transform was not filled in, or a document no

package/dist/types/live-time.d.ts

@@ -0,0 +1,141 @@
+/**
+ * @file Event-time live views (LIVE-FORMAT §13): a `$resample` or
+ * `$rolling` document over a collection, maintained against an
+ * explicit watermark.
+ *
+ * There is no clock in this file, and there is none anywhere under it.
+ * A live view over time needs to know what "now" is — which bucket is
+ * still open, which reading counts as late — and the only honest
+ * source of that is the host, because the machine's clock is a
+ * different quantity from the instant a reading carries. So the
+ * watermark ARRIVES: it is a finite epoch supplied at registration and
+ * moved forward by `advance()`, it never goes backwards, and a test can
+ * put it wherever the story needs it without waiting for a timer.
+ *
+ * What the maintenance actually does:
+ *
+ *  - **A bucket view keeps its rows by bucket.** A write touches one
+ *   bucket (two, when it moves a reading across a boundary), and only
+ *   those are folded again — through `resampleSeries` itself, over that
+ *   bucket's own rows, so the aggregate is the kernel's and cannot
+ *   drift from what a fresh query would answer.
+ *  - **A rolling view keeps its rows in instant order.** A write at `t`
+ *   can only change the windows ending in `[t, t + width)`, so exactly
+ *   that stretch is recomputed — again by the kernel, over the slice
+ *   that stretch can see.
+ *
+ * And what it refuses. A calendar ladder walks a wall clock, a named
+ * zone needs host code, `locf`/`linear` couple every bucket to its
+ * neighbours, and `first`/`last` name a row by a position a maintained
+ * map does not preserve. Each of those re-runs with its own reason
+ * rather than being approximated. So does a reading older than the
+ * declared lateness: the view re-runs, the emission carries a
+ * `lateData` record naming the instant and the boundary, and the row is
+ * never quietly folded into a bucket its reader already believed
+ * closed.
+ *
+ * `retention` is the horizon this view claims to work over. It is
+ * checked, not assumed: it must cover a whole window plus the lateness
+ * the caller allows, which is the span a single repair can read. It is
+ * NOT a compaction policy — the maintained state is bounded by
+ * `live.maxMaintained` exactly as every other strategy's is, and this
+ * file drops nothing that an answer still depends on.
+ */
+/**
+ * Validate the `eventTime` option into the record the classifier and
+ * the strategies read, or `null` when the caller declared none.
+ * @param {any} options - the live options
+ * @param {string} collection - for the error's `collection` property
+ * @returns {null | { member: string, watermark: number,
+ *   allowedLateness: number, retention: number }}
+ * @throws {DbCompileError} `JD0053` for any member this does not admit
+ */
+export declare function normalizeEventTime(options: any, collection: string): null | {
+    member: string;
+    watermark: number;
+    allowedLateness: number;
+    retention: number;
+};
+/**
+ * Classify a document as an event-time view, or say why it is not one.
+ *
+ * Returns `null` when the document does not name `$resample` or
+ * `$rolling` over this collection at all — the caller then goes on to
+ * §7's ordinary table. Every other outcome is a decision: a maintained
+ * description, or `{ strategy: 'rerun', reason }`.
+ * @param {any} inner - the unwrapped document
+ * @param {boolean} windowed - whether a `$subsequence` wrapped it
+ * @param {boolean} keyed
+ * @param {null | { member: string, watermark: number,
+ *   allowedLateness: number, retention: number }} eventTime
+ * @returns {any}
+ */
+export declare function classifyEventTime(inner: any, windowed: boolean, keyed: boolean, eventTime: null | {
+    member: string;
+    watermark: number;
+    allowedLateness: number;
+    retention: number;
+}): any;
+/**
+ * `$resample` over a fixed ladder: one maintained fold per bucket.
+ * @param {any} description
+ * @param {any} context
+ */
+export declare function bucketStrategy(description: any, context: any): {
+    advance: (next: any) => void;
+    stats: () => {
+        lateData: number;
+        reruns: number;
+        recomputes: number;
+        watermark: any;
+    };
+    entries: () => number;
+    init: () => any;
+    apply(record: any): {
+        rebuild: boolean;
+        late: any;
+        rows?: undefined;
+    } | {
+        rebuild?: undefined;
+        late?: undefined;
+        rows: {
+            at: any;
+            value: number | null;
+            count: number;
+        }[] | ({
+            at: number;
+            value: number | null;
+            count: number;
+        } | undefined)[];
+    } | null;
+    /** A re-run rebuilds the whole state from the store — the only
+     * answer to a reading the maintained state cannot place. */
+    rebuild(): any;
+};
+/**
+ * `$rolling` over a fixed width: one output per input instant, with
+ * only the stretch a write can reach recomputed.
+ * @param {any} description
+ * @param {any} context
+ */
+export declare function rollingStrategy(description: any, context: any): {
+    advance: (next: any) => void;
+    stats: () => {
+        lateData: number;
+        reruns: number;
+        recomputes: number;
+        watermark: any;
+    };
+    entries: () => number;
+    init: () => any;
+    apply(record: any): {
+        rows?: undefined;
+        rebuild: boolean;
+        late: any;
+    } | {
+        rebuild?: undefined;
+        late?: undefined;
+        rows: any[];
+    } | null;
+    rebuild(): any;
+};

package/dist/types/live.d.ts

@@ -31,9 +31,11 @@ export declare const LIVE_DEFAULTS: Readonly<{
  *   columnByCanonical)
  * @param {boolean} keyed - whether documents carry their key (a
  *   declared key pointer); unkeyed rows cannot be tracked by key
+ * @param {any} [eventTime] - the normalized `eventTime` option
+ *   (`live-time.js`), or null when the caller declared none
  * @returns {any}
  */
-export declare function classifyLiveQuery(document: any, queryShape: any, keyed: boolean): any;
+export declare function classifyLiveQuery(document: any, queryShape: any, keyed: boolean, eventTime?: any): any;
 /**
  * Diff two row arrays into sequential add/remove/replace ops under
  * `/rows`, relying on REFERENCE identity for unchanged rows (the §9

package/dist/types/plan.d.ts

@@ -60,6 +60,7 @@ export declare function assertDecidedKind(node: any): void;
  *   udfs: string[],
  *   prefilters: { construct: string, via: 'columns' | 'rtree',
  *     columns: string[], exact: boolean }[],
+ *   series: any,
  * }}
  */
 export declare function planQuery(document: any, shape: any, options?: {
@@ -83,6 +84,7 @@ export declare function planQuery(document: any, shape: any, options?: {
         columns: string[];
         exact: boolean;
     }[];
+    series: any;
 };
 /**
  * Build the planner shape for one entity: canonical top-level paths

package/dist/types/query.d.ts

@@ -37,12 +37,13 @@
  * residual.
  * @param {number} [bound]
  * @param {{ functions?: any, extensions?: any } | null} [operators]
+ * @param {any} [zoneProvider] - D7's injected clock, or absent
  * @returns {any}
  */
 export declare function createQueryState(bound?: number, operators?: {
     functions?: any;
     extensions?: any;
-} | null): any;
+} | null, zoneProvider?: any): any;
 /**
  * The query engine for one collection.
  * @param {{ connection: any, state: any, collection: any,

package/dist/types/residual.d.ts

@@ -29,12 +29,14 @@
  * @param {any} [limits]
  * @param {{ functions?: any, extensions?: any } | null} [operators] -
  *   the store's registered operators, so the residual can evaluate them
+ * @param {any} [zoneProvider] - D7's injected clock, so a calendar
+ *   ladder on a named zone compiles rather than being refused
  * @returns {(candidates: any[], externals: any) => any}
  */
 export declare function compileSetResidual(document: any, limits?: any, operators?: {
     functions?: any;
     extensions?: any;
-} | null): (candidates: any[], externals: any) => any;
+} | null, zoneProvider?: any): (candidates: any[], externals: any) => any;
 /**
  * Compile the per-row projection for row-mode evaluation.
  * @param {any} rowDocument - The planner's complete one-row document
@@ -44,12 +46,13 @@ export declare function compileSetResidual(document: any, limits?: any, operator
  *   the only place that knows the name.
  * @param {any} [limits]
  * @param {{ functions?: any, extensions?: any } | null} [operators]
+ * @param {any} [zoneProvider] - D7's injected clock
  * @returns {(row: any, externals: any) => any[]} the row's items
  */
 export declare function compileRowResidual(rowDocument: any, limits?: any, operators?: {
     functions?: any;
     extensions?: any;
-} | null): (row: any, externals: any) => any[];
+} | null, zoneProvider?: any): (row: any, externals: any) => any[];
 /**
  * Map a flat item array onto the engine's result shape: an empty
  * sequence is `undefined`, a singleton is the item, anything longer is