@jarenjs/db 0.46.5 → 0.49.2

package/dist/types/series.d.ts

@@ -0,0 +1,227 @@
+/**
+ * @file The temporal recognizer: which documents ask a §8.16 question,
+ * which of those a declared `(series, at)` index can answer, and what
+ * the honest reason is when it cannot.
+ *
+ * No SQL and no storage kind live here. The physical feature is the
+ * composite JSONPath index a model already declares
+ * (`{ "name": "by_series_at", "path": ["$.series", "$.at"] }`); this
+ * module only decides which of the three CLOSED shapes a planned
+ * selection is in:
+ *
+ *  1. **range** — an equality on every leading column of an instant
+ *     index plus a half-open range on the instant column, ordered by
+ *     the instant. The index seeks; nothing is left over.
+ *  2. **as-of** — the same prefix with ONE instant bound, ordered by
+ *     the instant and cut to a finite window. One index seek per probe.
+ *  3. **bucket** — a fixed-width ladder over the instant column with
+ *     the exact `sum|mean|min|max|count` aggregates, which is a
+ *     `GROUP BY` over integer arithmetic.
+ *
+ * Everything else — a calendar ladder, a fill policy, a rolling window,
+ * an as-of JOIN, `first`/`last` — is a named core refinement: the
+ * database narrows through the index and `@jarenjs/core/series` (via
+ * the residual, which is the ENGINE running the caller's own document)
+ * decides. The narrowing is the contribution; the answer is always the
+ * engine's, which is what makes a refinement idempotent.
+ *
+ * Every refusal here has a CODE, and the code is the first word of the
+ * sentence the plan carries, so `explain().series.reasons[].code` and
+ * `explain().residual.reasons[].reason` cannot drift apart.
+ */
+/** The three §8.16 operators a whole document can BE. */
+export declare const SERIES_ROOT_OPS: readonly string[];
+/** Every §8.16 operator: naming one makes a document temporal. */
+export declare const SERIES_OPS: readonly string[];
+/**
+ * The D5 aggregates a `GROUP BY` reproduces exactly, and the plan's
+ * name for each. `count` is `rows` because it counts SOURCE ROWS —
+ * duplicates and measured gaps included — which is `COUNT(*)` and not
+ * `COUNT(value)`; the six value aggregates skip a `null` reading,
+ * which is what SQL's aggregates already do with SQL `NULL`.
+ *
+ * `first` and `last` are deliberately absent: they name a row by its
+ * position in the series, and a group's order is not the series' order.
+ */
+export declare const NATIVE_AGGREGATES: Readonly<{
+    mean: "avg";
+    sum: "sum";
+    min: "min";
+    max: "max";
+    count: "rows";
+}>;
+/**
+ * The closed reason table. A reason is a CODE and a sentence; the plan
+ * carries `"<code>: <sentence>"` so one string serves strict mode's
+ * refusal, `explain().residual.reasons` and the machine-readable
+ * `explain().series.reasons[].code` at once.
+ */
+export declare const SERIES_REASONS: Readonly<{
+    'missing-series-prefix': string;
+    'calendar-width': string;
+    'named-zone': string;
+    'fill-policy': string;
+    'rolling-refinement': string;
+    'asof-refinement': "an as-of join walks both sides once, so the index bounds the fetch and the kernel joins";
+    'nonliteral-spec': string;
+    'unsupported-aggregate': string;
+    'row-selector': string;
+    'instant-not-integer': string;
+    'value-not-numeric': string;
+    'nonnative-grouping': "the grouping key or the projection is not the closed bucket shape";
+    'invalid-spec': string;
+}>;
+/**
+ * One reason, in both spellings at once.
+ * @param {keyof SERIES_REASONS | string} code
+ * @param {string} construct - the operator or clause that forced it
+ * @returns {{ code: string, construct: string, reason: string }}
+ */
+export declare function seriesReason(code: keyof SERIES_REASONS | string, construct: string): {
+    code: string;
+    construct: string;
+    reason: string;
+};
+/**
+ * Every declared index whose LAST covered column is `column`, with the
+ * columns before it as the prefix that must be pinned.
+ *
+ * `minColumns` is what keeps an ordinary query ordinary. A collection
+ * that declares `(age)` and is asked for `age > 21` is not asking a
+ * temporal question, and nothing in a column can say otherwise — so
+ * the shape D9 actually names, a COMPOSITE index whose last column is
+ * the instant, is what makes a plain selection temporal. A document
+ * that named a §8.16 operator has already said so itself, and reads
+ * the singular index too.
+ * @param {any} shape - { indexes?: { name, columns }[] }
+ * @param {string} column
+ * @param {number} [minColumns]
+ * @returns {{ name: string, prefix: string[], column: string }[]}
+ */
+export declare function instantIndexesOver(shape: any, column: string, minColumns?: number): {
+    name: string;
+    prefix: string[];
+    column: string;
+}[];
+/**
+ * The index a fetch actually SEEKS through, or `null` when none does.
+ *
+ * A B-tree is seekable exactly as far as its leading columns are
+ * decided: a run of equalities, and then at most one range. So the
+ * index that wins is the one with the longest leading run of PINNED
+ * columns whose next column is the instant the query ranges over —
+ * which is `(series, at)` under an equality on the series, and is
+ * nothing at all under a bare instant bound, because a range on a
+ * trailing column reads every row of the index.
+ *
+ * With no instant column of its own (an as-of join reading an instant
+ * the model does not index) a pinned prefix alone still seeks, and is
+ * reported as what it is.
+ * @param {any} shape
+ * @param {string | null} column - the instant column, or `null`
+ * @param {{ pinned: Set<string>, bounds: Map<string, any> }} facts
+ * @param {number} [minColumns] - see {@link instantIndexesOver}
+ * @returns {{ name: string, prefix: string[], column: string | null } | null}
+ */
+export declare function seekingIndexFor(shape: any, column: string | null, facts: {
+    pinned: Set<string>;
+    bounds: Map<string, any>;
+}, minColumns?: number): {
+    name: string;
+    prefix: string[];
+    column: string | null;
+} | null;
+/**
+ * Walk a pushed filter and report, per column, what it decided: which
+ * columns an equality pinned and what instant bounds a range put on
+ * one. Only a top-level conjunction counts — a disjunction or a
+ * negation decides nothing about a seek.
+ * @param {import('./algebra.js').PlanPredicate | null} filter
+ * @returns {{ pinned: Set<string>,
+ *   bounds: Map<string, { from: any, fromOp: string | null,
+ *     to: any, toOp: string | null }> }}
+ */
+export declare function filterFacts(filter: import('./algebra.js').PlanPredicate | null): {
+    pinned: Set<string>;
+    bounds: Map<string, {
+        from: any;
+        fromOp: string | null;
+        to: any;
+        toOp: string | null;
+    }>;
+};
+/**
+ * The fixed ladder a `$time-bucket`/`$resample` spec asks for, or the
+ * reason it is not one. `origin` is folded to an epoch here — a
+ * `{ offset }` context moves the ladder's default anchor off UTC's
+ * midnight, which is arithmetic, while a named zone is not.
+ *
+ * The width is read through the temporal kernel's OWN compiler, so
+ * `'PT1H'`, `3600000` and `'PT60M'` are the same ladder, the default
+ * anchor is the kernel's rather than a second guess at it, and a width
+ * mixing the two families was already refused when the query compiled.
+ * @param {{ every: any, origin?: any, zone?: any, offset?: any }} spec
+ * @param {(spec: any, options: any) => any} compileBuckets - the kernel's
+ * @returns {{ every: number, origin: number } | { code: string }}
+ */
+export declare function fixedLadder(spec: {
+    every: any;
+    origin?: any;
+    zone?: any;
+    offset?: any;
+}, compileBuckets: (spec: any, options: any) => any): {
+    every: number;
+    origin: number;
+} | {
+    code: string;
+};
+/**
+ * Whether a `PlanRef` can carry a native bucket ladder: the instant
+ * must be a declared whole epoch, because the boundary arithmetic in
+ * SQL is integer arithmetic and a truncating division over a real
+ * would put an instant before 1970 in the bucket after its own.
+ * @param {import('./algebra.js').PlanRef | null} ref
+ * @returns {string | null} the reason code, or `null` when it can
+ */
+export declare function instantRefusal(ref: import('./algebra.js').PlanRef | null): string | null;
+/**
+ * Whether a `PlanRef` can carry a native VALUE aggregate.
+ * @param {import('./algebra.js').PlanRef | null} ref
+ * @returns {string | null}
+ */
+export declare function valueRefusal(ref: import('./algebra.js').PlanRef | null): string | null;
+/**
+ * The one member name a `'$.on'`-style row selector reads, or `null`
+ * for anything a declared column cannot stand in for. The language's
+ * own reader (`compileSelector`) folds a single-segment path to a bare
+ * name; this reads the same two spellings out of the FROZEN literal a
+ * planner sees, and refuses everything else rather than guessing.
+ * @param {any} text
+ * @returns {string | null}
+ */
+export declare function singularSelector(text: any): string | null;
+/**
+ * The explain record for one temporal document. Counts are the LAST
+ * ACTUAL execution's — never an estimate — and are `null` until the
+ * document has run once.
+ * @param {{ mode: 'native' | 'hybrid' | 'engine', operation: string,
+ *   index?: string | null, prefix?: string[], range?: any,
+ *   ladder?: any, aggregates?: string[], refinement?: string | null,
+ *   reasons?: { code: string, construct: string, reason: string }[] }} facts
+ * @returns {any}
+ */
+export declare function seriesRecord(facts: {
+    mode: 'native' | 'hybrid' | 'engine';
+    operation: string;
+    index?: string | null;
+    prefix?: string[];
+    range?: any;
+    ladder?: any;
+    aggregates?: string[];
+    refinement?: string | null;
+    reasons?: {
+        code: string;
+        construct: string;
+        reason: string;
+    }[];
+}): any;

package/dist/types/store.d.ts

@@ -33,8 +33,14 @@ export declare function normalizeModel(model: any): Map<string, any>;
  * @param {{ driver: any, path?: string, compileSchema?: Function,
  *   busyTimeout?: number, queueTimeout?: number, journalMode?: string,
  *   statementCacheBound?: number, profile?: any, operators?: any,
- *   functions?: any, extensions?: any,
+ *   functions?: any, extensions?: any, zoneProvider?: any,
  *   readOnly?: boolean }} options
+ *   `zoneProvider` is D7's injected clock: a named zone in a temporal
+ *   spec (`{ "every": "P1M", "zone": "Europe/Amsterdam" }`) is host code
+ *   the database cannot have, so a store that never received one refuses
+ *   such a document (`JQ0003`) rather than answering it in UTC. It
+ *   reaches every residual compilation, which is where the calendar
+ *   ladder actually walks.
  * @returns {Promise<any>}
  */
 export declare function openStore(model: any, options: {
@@ -49,5 +55,6 @@ export declare function openStore(model: any, options: {
     operators?: any;
     functions?: any;
     extensions?: any;
+    zoneProvider?: any;
     readOnly?: boolean;
 }): Promise<any>;

package/docs/LIVE-FORMAT.md

@@ -148,6 +148,7 @@ against its own result document (§9). Registration:
 const live = await store.collection('users').live(document, {
   externals: {},          // fixed at registration (§8)
   mode: 'auto',           // 'auto' | 'incremental' | 'rerun'
+  eventTime: undefined,   // a temporal view's watermark (§13)
 });
 live.result;              // the maintained result document
 live.mode;                // { strategy, mode: 'incremental'|'rerun', reason }
@@ -177,6 +178,8 @@ what the pushdown planner already means by it.
 | `orderBy` beside a refined spatial predicate — over `$distance` (not a path) or over a member (the set residual drops the planner's order terms) | **re-run on invalidation**, the ordering named as the reason | the previous result, for diffing |
 | a whole-query aggregate or a `groupBy` whose `where` is a refined spatial predicate | **re-run on invalidation** — the accumulator needs a fully translated selection and a refinement is not one; the reason says so | the previous result, for diffing |
 | a spatial predicate the planner **refused** (no `derive` index on the member, an untyped member, an unbounded probe) | **re-run on invalidation**, the refusal named — it never translated, so nothing narrows the fetch | the previous result, for diffing |
+| a `$resample` or `$rolling` document over the collection, with an explicit `eventTime` and a fixed width (§13) | **event-time bucket / rolling state**: rows kept by bucket, or in instant order; only what a write can reach is folded again, through `@jarenjs/core/series` itself | the contributing rows, plus one fold per bucket |
+| the same document with no `eventTime`, a calendar width, a named zone, a `locf`/`linear` fill, a `first`/`last` aggregate, or a retention that does not cover the window | **re-run on invalidation**, the member that stopped it named (§13.2) | the previous result, for diffing |
 | joins, multi-entity roots, graph loads, every entity query | **re-run on invalidation — declared, not attempted** in this version | the previous result, for diffing |
 | anything else: non-translatable predicates, `limit` without `orderBy`, `offset` > 0, windowed aggregates, `@jarenjs/linq`'s nested two-level `groupBy` emission, non-canonical group returns | **re-run on invalidation**, the reason named | the previous result, for diffing |
 
@@ -376,3 +379,103 @@ the signal), no maintenance over asynchronous connections in this
 version (every current driver is synchronous; the browser driver's
 order owns that story), no replication, and no ordering guarantee for
 unordered queries beyond §9's determinism.
+
+## 13. Event time
+
+A live view over time needs to know what "now" is — which reading counts
+as late — and the machine's clock is a different quantity from the
+instant a reading carries. So there is no clock in this layer and none
+under it: the **watermark arrives**.
+
+```js
+const live = await store.collection('readings').live(
+  [{ $resample: ['$[*]', { every: 60_000, aggregate: 'mean' }] }],
+  { eventTime: {
+      path: '$.at',              // the instant member, as a row selector
+      watermark: 1767225600000,  // a finite epoch the HOST supplies
+      allowedLateness: 300_000,  // how late a reading may still be
+      retention: 900_000,        // the horizon this view claims
+  } });
+
+live.advance(1767225660000);     // the only way a watermark moves
+live.stats().watermark;          // what it is now
+```
+
+`eventTime` is a **closed** member set: `path`, `watermark`,
+`allowedLateness` (default 0) and `retention`. Anything else — a
+misspelling, a non-finite epoch, a negative lateness, a `path` that is
+not a singular row selector — is `JD0053` at registration, not a member
+quietly ignored. `advance()` refuses a value that is not finite or that
+goes backwards (a `TypeError`), and it is absent on every view
+registered without an `eventTime`. An entity document has no collection
+to place rows in and re-runs, so an `eventTime` on `store.live` is
+`JD0053` too.
+
+### 13.1 What is maintained
+
+Two documents, and only these two shapes: `$resample` and `$rolling`
+whose series operand is the collection (`"$[*]"`, or a FLWOR over it
+whose `$where` narrows and whose `$return` is the bare binding).
+
+- **A bucket view keeps its rows by bucket.** A write touches one bucket
+  — two, when it moves a reading across a boundary — and exactly those
+  are folded again by calling `resampleSeries` over that bucket's own
+  rows. The aggregate is therefore 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 those
+  windows can see.
+
+`retention` is the horizon the view claims, and it is checked rather
+than assumed: it must cover the width plus `allowedLateness`, which is
+the span a single repair can read. A shorter one is a re-run with the
+numbers printed. It is **not** a compaction policy — the maintained
+state is bounded by `live.maxMaintained` exactly as every other
+strategy's is (§12), and nothing an answer still depends on is dropped.
+That is the honest statement of what this version buys: bounded repair
+work and a visible lateness contract, not a smaller heap.
+
+### 13.2 What re-runs, and why
+
+| Refused | Because |
+|---|---|
+| no `eventTime` | a temporal view maintains event time, and a hidden clock is the one source this suite will not use |
+| a calendar `every`/`width` (`P1M`, `P1D` on a zone) | a calendar ladder walks a wall clock and a month has no width, so its boundaries move with the data rather than with arithmetic |
+| a named `zone` | it resolves through the injected provider, which maintenance would have to consult per boundary |
+| `fill: 'locf'` / `'linear'` | they fill an empty bucket from its neighbours, so one late reading moves buckets it never belonged to |
+| `aggregate: 'first'` / `'last'` | they name a row by its position in the series, which a per-key state does not preserve — the same refusal the pushdown planner makes |
+| a `retention` under `width + allowedLateness` | a repair could read outside the horizon the view claims |
+| a `$subsequence` window, a projecting operand, a collection with no document key | there is no row a key can be tracked through |
+| a spec whose `at` selector is not `eventTime.path` | the state would place a row by one instant and aggregate it by another |
+
+Each of those is `live.mode.reason`, and `mode: 'incremental'` still
+refuses them at registration with `JD0051`.
+
+### 13.3 Late data is visible, never lost
+
+A reading is **late** when its instant — before the write, after it, or
+both — is behind `watermark - allowedLateness`. Late readings are not
+dropped and not quietly folded in. The view **re-reads** from the store,
+so the answer still equals what a fresh query would give, and the
+emission carries the reason:
+
+```js
+live.subscribe(({ patch, seq, lateData }) => {
+  if (lateData !== undefined) {
+    // { reason: 'late-data', at, key, watermark, allowedLateness, boundary }
+  }
+});
+```
+
+`stats().lateData` counts them and `stats().reruns` counts the re-reads
+they forced. A reading outside the view's own `start`/`end` window is
+not late data: it belongs to no bucket this view maintains, so there is
+nothing to be late for.
+
+The maintained answer is **equal to a full recomputation after every
+mutation** — not approximately, and not eventually. `test/db/live-time.test.js`
+holds a shuffled stream of inserts, in-place updates, instant moves and
+deletes against `resampleSeries` / `rollingSeries` over the whole
+collection after each one, which is the only oracle that cannot drift
+with the implementation.

package/docs/MODEL-FORMAT.md

@@ -71,6 +71,24 @@ The store runs over SQLite — on Node (`@jarenjs/db/node`), on Bun
 An invalid model document is `JD0005` with a `docPath` pointing at the
 offending member. Model checking happens before any database work.
 
+**A time series needs no new declaration.** A composite index whose
+LAST path is a finite numeric epoch member is the whole physical
+feature a temporal plan reads:
+
+```json
+{ "indexes": [{ "name": "by_series_at", "path": ["$.series", "$.at"] }] }
+```
+
+There is no `derive` kind for it, no column type and no host function.
+The columns before the instant are the prefix an equality has to pin
+for the index to seek, exactly as for any other composite index, and
+the schema is the type source as always: type the instant `integer` and
+a bucket ladder is pushed as integer arithmetic; type it `number` and
+the ladder stays a core refinement, because a truncating division over
+a real would put an instant in the wrong bucket. Which shapes are
+pushed, and the reason each refinement is one, are in ARCHITECTURE.md's
+"The temporal plan".
+
 ### 2.1 Derived indexes (spatial and vector storage)
 
 A generated column must be a scalar (§3), and a GeoJSON position is an
@@ -713,6 +731,7 @@ error.
 | `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 |
 | `JD2001` | insert found the key already present |
 | `JD2002` | a usable key could not be resolved for the write |
 | `JD2003` | the write failed schema validation |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/db",
   "private": false,
-  "version": "0.46.5",
+  "version": "0.49.2",
   "type": "module",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
@@ -71,9 +71,9 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.46.5",
-    "@jarenjs/json": "^0.46.5",
-    "@jarenjs/validate": "^0.46.5"
+    "@jarenjs/core": "^0.49.2",
+    "@jarenjs/json": "^0.49.2",
+    "@jarenjs/validate": "^0.49.2"
   },
   "bin": {
     "jaren-db": "./src/cli.js"

package/src/algebra.js

@@ -11,9 +11,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. */
@@ -57,6 +58,21 @@ export const PLAN_VERSION = 2;
  *
  * @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
@@ -79,6 +95,7 @@ export const PLAN_VERSION = 2;
  *   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',
@@ -99,6 +116,7 @@ export function selectPlan(collection) {
     order: null,
     window: null,
     rank: null,
+    bucket: null,
     aggregate: null,
     project: 'document',
   };
@@ -123,6 +141,7 @@ export function conjoin(filter, predicate) {
 const SQL_TOKENS = [
   'SELECT', 'WHERE', 'ORDER BY', 'LIMIT ', 'INSERT', 'FROM ',
   'jsonb_extract', 'json_type', 'substr(', 'instr(', '"doc"', '@p1', ' AS ',
+  'GROUP BY', 'COUNT(',
 ];
 
 /**

package/src/dialect.js

@@ -58,6 +58,9 @@
  *   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[] },
@@ -473,6 +476,16 @@ export function createDialect(spec) {
     strEndsWith: spec.strEndsWith,
     strContains: spec.strContains,
     orderNulls: spec.orderNulls,
+    /**
+     * The instant a fixed-width bucket ladder labels one row with:
+     * `origin + floor((at - origin) / every) * every`, which reduces to
+     * `at` less the non-negative remainder. The parameters appear in
+     * TEXT order — the origin once, the width three times — because a
+     * positional dialect numbers them by where they are written.
+     */
+    timeBucket: spec.timeBucket,
+    /** One grouped aggregate; `null` counts ROWS rather than values. */
+    groupAggregate: spec.groupAggregate,
     rowIdentity: spec.rowIdentity,
     /**
      * The R\*Tree spelling: the module name and the virtual table's own

package/src/dialects/sqlite.js

@@ -82,6 +82,9 @@ export const sqliteDialect = createDialect({
     upsert: true,
     savepoints: true,
     alterTableFull: false,
+    // a GROUP BY / ORDER BY term may name a result alias, so a bucket
+    // ladder is written once rather than three times
+    groupByAlias: true,
   },
   tableSuffix: ' STRICT',
   // RFC 3339 text → epoch milliseconds, in SQL: the migration planner
@@ -152,6 +155,22 @@ export const sqliteDialect = createDialect({
     `(length(${patternA}) = 0 OR substr(${valueSql}, -length(${patternB})) = ${patternC})`,
   strContains: (valueSql, patternSql) => `instr(${valueSql}, ${patternSql}) > 0`,
   orderNulls: (nullsFirst) => (nullsFirst ? ' NULLS FIRST' : ' NULLS LAST'),
+  // the fixed bucket ladder, in integer arithmetic all the way down.
+  // `origin + floor((at - origin) / every) * every` is `at` less the
+  // NON-NEGATIVE remainder, and `((x % m) + m) % m` is how a language
+  // whose `%` truncates towards zero (C's, and SQLite's) spells one —
+  // which is the whole of why an instant before 1970 lands in its own
+  // bucket rather than the one after it. The column is declared
+  // INTEGER, so nothing here converts and nothing rounds.
+  timeBucket: (instantSql, originSql, everyA, everyB, everyC) =>
+    `(${instantSql} - (((${instantSql} - ${originSql}) % ${everyA} + ${everyB}) % ${everyC}))`,
+  // `rows` is COUNT(*) — the D5 count of SOURCE rows, which is not
+  // COUNT(value): a measured gap is a row that reported nothing, and
+  // the difference between "nobody reported" and "everybody reported a
+  // gap" is exactly what the count is for
+  groupAggregate: (fn, valueSql) => (valueSql === null
+    ? 'COUNT(*)'
+    : `${{ sum: 'SUM', avg: 'AVG', min: 'MIN', max: 'MAX' }[fn]}(${valueSql})`),
   rowIdentity: () => '"rowid"',
   // membership of the row identity in a bound list — the fetch of a
   // k-nearest plan's candidates. `IN` over the rowid is a primary-key

package/src/emit.js

@@ -273,6 +273,17 @@ export function emitPlan(plan, dialect, physical) {
     }
   };
 
+  // The temporal bucket's ladder, written ONCE and named: the SELECT
+  // list carries it, and the grouping and the ordering name the alias.
+  // Writing it three times would triple its parameters, and a bucket
+  // start is exactly the kind of value the caller wants to read back.
+  const bucketSql = plan.bucket === null ? null
+    : dialect.timeBucket(valueOf(plan.bucket.ref),
+      param({ literal: plan.bucket.origin }),
+      param({ literal: plan.bucket.every }),
+      param({ literal: plan.bucket.every }),
+      param({ literal: plan.bucket.every }));
+
   const selection = plan.rank !== null
     // the k-nearest fetch: the row identity and the packed column
     // under the pushed WHERE, and nothing that orders or limits — the
@@ -280,15 +291,30 @@ export function emitPlan(plan, dialect, physical) {
     // the rank loses to fetching the column and ranking in the engine,
     // and none of them runs where no function can be registered)
     ? `${dialect.rowIdentity()} AS ${q('rid')}, ${q(plan.rank.column)} AS ${q('vec')}`
-    : plan.aggregate === null
-      ? `${dialect.jsonText(docColumn)} AS ${q('doc')}`
-      : plan.aggregate.fn === 'count'
-        ? `COUNT(*) AS ${q('value')}`
-        : `${plan.aggregate.fn.toUpperCase()}(${valueOf(plan.aggregate.ref)}) AS ${q('value')}`;
+    : plan.bucket !== null
+      ? [`${bucketSql} AS ${q(plan.bucket.as)}`,
+        ...plan.bucket.aggregates.map((entry) =>
+          `${dialect.groupAggregate(entry.fn,
+            entry.ref === null ? null : valueOf(entry.ref))} AS ${q(entry.as)}`)].join(', ')
+      : plan.aggregate === null
+        ? `${dialect.jsonText(docColumn)} AS ${q('doc')}`
+        : plan.aggregate.fn === 'count'
+          ? `COUNT(*) AS ${q('value')}`
+          : `${plan.aggregate.fn.toUpperCase()}(${valueOf(plan.aggregate.ref)}) AS ${q('value')}`;
 
   let sql = `SELECT ${selection} FROM ${q(physical.table)}`;
   if (plan.filter !== null) sql += ` WHERE ${emitPred(plan.filter)}`;
-  if (plan.aggregate === null && plan.rank === null) {
+  if (plan.bucket !== null) {
+    // `first-seen` is the engine's own group order (§6.5, first
+    // appearance), which over a collection is the group's earliest row
+    // identity — the same tiebreaker the ungrouped fetch appends
+    const alias = q(plan.bucket.as);
+    const order = plan.bucket.order === 'first-seen'
+      ? dialect.groupAggregate('min', dialect.rowIdentity())
+      : `${alias} ${plan.bucket.order === 'desc' ? 'DESC' : 'ASC'}`;
+    sql += ` GROUP BY ${alias} ORDER BY ${order}`;
+  }
+  if (plan.aggregate === null && plan.rank === null && plan.bucket === null) {
     const terms = (plan.order ?? []).map((term) => {
       // Jaren's default sorts an empty key least: NULLS FIRST when
       // ascending, NULLS LAST when descending — and mirrored for

package/src/errors.js

@@ -34,6 +34,7 @@ export const DB_CODES = Object.freeze({
   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',
@@ -94,6 +95,8 @@ export const DB_CODES = Object.freeze({
  *    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