@jarenjs/db 0.46.5 → 0.56.0

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/capture.js

@@ -32,8 +32,8 @@
 import { createJSONPatch } from '@jarenjs/json/patch';
 import { encodeJSONPointerSegment, decodeJSONPointerSegment } from '@jarenjs/json/pointer';
 
-import { DbRuntimeError } from './errors.js';
-import { chain } from './driver.js';
+import { DbCompileError, DbRuntimeError } from './errors.js';
+import { chain, attempt } from './driver.js';
 
 /** The persisted change log (LIVE-FORMAT §5). */
 export const CHANGES_TABLE = '_jaren_changes';
@@ -323,6 +323,11 @@ export function createCaptureEngine(options) {
   const { connection, shapes, mode } = options;
   const dialect = connection.dialect;
   const q = dialect.quoteIdentifier;
+  if (options.log && !(Number.isInteger(options.retention) && options.retention >= 1)) {
+    // a retention of 0 pruned every record the moment it was written,
+    // with the log reported as enabled
+    throw new TypeError('capture.log.retention must be a positive integer (records kept)');
+  }
 
   /** @type {Set<Function>} */
   const observers = new Set();
@@ -345,9 +350,15 @@ export function createCaptureEngine(options) {
         { name: 'patch', type: dialect.typeFor('string', 'key') },
       ],
     }),
+    // the sequence is allocated by the STATEMENT, inside the write's
+    // own transaction: a counter seeded once at open collided with
+    // another store's writes to the same file and rolled the user's
+    // write back with a raw UNIQUE failure
     insert: `INSERT INTO ${q(CHANGES_TABLE)} `
       + `(${['seq', 'at', 'source', 'patch'].map(q).join(', ')}) `
-      + `VALUES (${[1, 2, 3, 4].map((i) => dialect.parameterRef(i, 'v')).join(', ')})`,
+      + `VALUES ((SELECT COALESCE(MAX(${q('seq')}), 0) + 1 FROM ${q(CHANGES_TABLE)}), `
+      + `${[1, 2, 3].map((i) => dialect.parameterRef(i, 'v')).join(', ')}) `
+      + `RETURNING ${q('seq')} AS ${q('seq')}`,
     prune: `DELETE FROM ${q(CHANGES_TABLE)} WHERE ${q('seq')} <= ${dialect.parameterRef(1, 'v')}`,
     highest: `SELECT MAX(${q('seq')}) AS ${q('n')} FROM ${q(CHANGES_TABLE)}`,
     read: `SELECT ${['seq', 'at', 'source', 'patch'].map(q).join(', ')} `
@@ -357,7 +368,10 @@ export function createCaptureEngine(options) {
 
   const ready = logStatements === null
     ? null
-    : chain(connection.exec(logStatements.create), () =>
+    : chain(attempt(() => connection.exec(logStatements.create), (error) => new DbCompileError('JD0002',
+      `the change log table could not be created (${error?.message ?? String(error)}) — `
+      + 'a read-only store creates nothing; open it read-write once, or without capture.log',
+      '/capture', error)), () =>
       chain(connection.prepare(logStatements.highest), (statement) =>
         chain(statement.get([]), (row) => {
           seq = Number(row?.n ?? 0) || 0;
@@ -443,28 +457,45 @@ export function createCaptureEngine(options) {
 
   const persist = (patch, at) => {
     if (logStatements === null || patch.length === 0) return null;
-    seq += 1;
-    const mySeq = seq;
     return chain(connection.prepare(logStatements.insert), (insert) =>
-      chain(insert.run([mySeq, at, mode, JSON.stringify(patch)]), () =>
-        chain(connection.prepare(logStatements.prune), (prune) =>
-          chain(prune.run([mySeq - options.retention]), () => null))));
+      chain(insert.get([at, mode, JSON.stringify(patch)]), (row) => {
+        seq = Number(row.seq);
+        return chain(connection.prepare(logStatements.prune), (prune) =>
+          chain(prune.run([seq - options.retention]), () => null));
+      }));
   };
 
+  /** The collections a patch touches, in first-seen order. */
+  const collectionsOf = (patch) => [...new Set(patch.map(
+    (op) => decodeJSONPointerSegment(op.path.split('/')[1])))];
+
+  let delivering = false;
   const deliver = () => {
-    while (pendingDeliveries.length > 0) {
-      const delivery = pendingDeliveries.shift();
-      for (const observer of [...observers]) {
-        // error isolation: a throwing observer must never affect the
-        // write (the app.observe discipline)
-        try {
-          observer(delivery);
-        }
-        catch {
-          // deliberately swallowed; the write already committed
+    // never re-entered: an observer that WRITES commits a further record
+    // from inside this loop, and delivering that record here handed it to
+    // every sibling before the older one — commit order inverted for
+    // them, and a maintained view kept a stale row for good. The nested
+    // call queues its record; this loop drains it after the current one.
+    if (delivering) return;
+    delivering = true;
+    try {
+      while (pendingDeliveries.length > 0) {
+        const delivery = pendingDeliveries.shift();
+        for (const observer of [...observers]) {
+          // error isolation: a throwing observer must never affect the
+          // write (the app.observe discipline)
+          try {
+            observer(delivery);
+          }
+          catch {
+            // deliberately swallowed; the write already committed
+          }
         }
       }
     }
+    finally {
+      delivering = false;
+    }
   };
 
   /**
@@ -498,9 +529,7 @@ export function createCaptureEngine(options) {
                 seq: logStatements === null ? (seq += 1) : seq,
                 at,
                 source: mode,
-                collections: [...new Set(patch.map(
-                  (op) => decodeJSONPointerSegment(op.path.split('/')[1]))),
-                ],
+                collections: collectionsOf(patch),
                 patch,
               },
             }));
@@ -570,13 +599,22 @@ export function createCaptureEngine(options) {
         throw new DbRuntimeError('JD2051',
           'the change log is not enabled — open the store with capture.log');
       }
+      if (typeof after !== 'number' || !Number.isFinite(after)) {
+        throw new TypeError(`changesSince(after) takes the last seq seen as a number, got ${
+          after === undefined ? 'undefined' : JSON.stringify(after)}`);
+      }
       return chain(connection.prepare(logStatements.read), (statement) =>
-        chain(statement.all([after]), (rows) => rows.map((row) => ({
-          seq: Number(row.seq),
-          at: Number(row.at),
-          source: String(row.source),
-          patch: JSON.parse(row.patch),
-        }))));
+        chain(statement.all([after]), (rows) => rows.map((row) => {
+          const patch = JSON.parse(row.patch);
+          // the same record shape observers receive: `collections` too
+          return {
+            seq: Number(row.seq),
+            at: Number(row.at),
+            source: String(row.source),
+            collections: collectionsOf(patch),
+            patch,
+          };
+        })));
     },
   };
 }

package/src/cli.js

@@ -2,39 +2,61 @@
 //#region the jaren-db command
 // Migrations nobody drives by API stay undrifted by nobody: the CLI is
 // what puts `check` in CI and a reviewable migration document in the
-// repository. Five commands (MIGRATION-FORMAT §11): plan, status,
-// apply, check, shape.
+// repository. Six commands (MIGRATION-FORMAT §11): plan, snapshot,
+// status, apply, check, shape. A model or a migration is a JSON file or
+// a MODULE — the model pen's document, the migration pen's builder —
+// loaded twice, because a module that emits a different document on its
+// second load is one whose migration can never match its own history.
 
 import * as fs from 'fs';
 import * as path from 'path';
 import * as readline from 'readline';
+import { pathToFileURL } from 'url';
+
+import { canonicalizeJson } from '@jarenjs/json/canonical';
 
 import {
-  planModelMigration, migrate, migrationStatus, shapeHash,
+  planModelMigration, migrate, migrationStatus, shapeHash, compareShapeToModel,
   sqliteDialect, normalizeModel, normalizeEntities, explainMapping,
-  planCollection, planEntity, planJoinTable, HISTORY_TABLE,
+  planCollection, planEntity, planJoinTable, HISTORY_TABLE, entityEmitModel,
 } from './index.js';
 import { nodeDriver } from './drivers/node.js';
 
 const USAGE = `jaren-db — model-driven SQLite migrations
 
 Usage:
-  jaren-db plan   --from <model> --to <model> [--store <db>] [--id <name>] [--out <file>]
-  jaren-db status --model <model> --store <db> --baseline <model> [--migrations <dir>]
-  jaren-db apply  --store <db> --baseline <model> --migrations <dir> [--model <m>] [--dry-run] [--yes]
-  jaren-db check  --model <model> --store <db> --baseline <model> [--migrations <dir>]
-  jaren-db shape  --model <model>
+  jaren-db plan     --from <model> --to <model> [--store <db>] [--id <name>] [--out <file>]
+  jaren-db plan     --model <model> [--snapshot <file>] [--store <db>] [--id <name>] --out <file>
+  jaren-db snapshot --model <model> [--snapshot <file>] [--types <file>]
+  jaren-db status   --model <model> --store <db> --baseline <model> [--migrations <dir>] [--snapshot <file>]
+  jaren-db apply    --store <db> --baseline <model> --migrations <dir> [--model <m>] [--dry-run] [--yes]
+  jaren-db check    --model <model> --store <db> --baseline <model> [--migrations <dir>] [--snapshot <file>]
+  jaren-db shape    --model <model>
+
+A <model> or a migration is a .json file, or a MODULE (.js, .mjs, .cjs —
+or .ts where Node strips types) whose default export, or its 'model' /
+'migration' export, is the document or a pen builder that emits one. A
+module is loaded twice and refused when its two emissions differ: no
+clock, no env, no randomness. --migrations reads .json files and
+modules, sorted by file name.
 
-plan    Diff two model FILES into a migration document (a database
-        stores shape hashes, not models — the from-model is the
-        previous model file). With --store, first verify the
-        from-model matches the database's recorded shape.
-status  Applied, pending, and drift (a hand-modified database).
-apply   Print every statement, then apply. Destructive steps (drop
-        table/column, rebuild) require --yes or an interactive
-        confirmation naming what is lost. --dry-run only prints.
-check   The CI command: exit 1 on pending migrations or drift.
-shape   Print the physical mapping a model produces.
+plan      Diff two model FILES into a migration document (a database
+          stores shape hashes, not models — the from-model is the
+          previous model file), or diff the committed SNAPSHOT (default
+          model.snapshot.json beside the model) against the model: with
+          --out the migration is written and the snapshot advanced; a
+          model matching its snapshot plans nothing. With --store, first
+          verify the from-model matches the database's recorded shape.
+snapshot  Write the model's snapshot; with --types, emit's TypeScript
+          declaration for it (needs @jarenjs/emit beside @jarenjs/db).
+status    Applied, pending, drift (a hand-modified database) and — with
+          a snapshot — an unplanned model change.
+apply     Print every statement, then apply. Destructive steps (drop
+          table/column, rebuild) require --yes or an interactive
+          confirmation naming what is lost. --dry-run only prints.
+check     The CI command: exit 1 on an unplanned model change, pending
+          migrations or drift.
+shape     Print the physical mapping a model produces.
 `;
 
 function fail(message) {
@@ -46,6 +68,7 @@ function parseArgs(argv) {
   const options = {
     command: argv[2], from: null, to: null, model: null, store: null,
     baseline: null, migrations: null, id: null, out: null,
+    snapshot: null, types: null,
     dryRun: false, yes: false, help: false,
   };
   for (let i = 3; i < argv.length; i++) {
@@ -58,6 +81,8 @@ function parseArgs(argv) {
       case '--migrations': options.migrations = argv[++i]; break;
       case '--id': options.id = argv[++i]; break;
       case '--out': options.out = argv[++i]; break;
+      case '--snapshot': options.snapshot = argv[++i]; break;
+      case '--types': options.types = argv[++i]; break;
       case '--dry-run': options.dryRun = true; break;
       case '--yes': options.yes = true; break;
       case '--help': case '-h': options.help = true; break;
@@ -76,13 +101,82 @@ const readJson = (file, what) => {
   }
 };
 
-/** The migrations directory, sorted — the full ordered chain. */
-const readMigrationsDir = (dir) => {
+const MODULE_EXT = /\.(?:m?js|cjs|m?ts|cts)$/;
+const TS_EXT = /\.[mc]?ts$/;
+let loads = 0;
+
+/** The document a module exports — `default`, or the named export — as
+ * its JSON emission (a pen builder's `toJSON()`), or a named failure. */
+const emissionOf = (mod, exportName, file) => {
+  const value = mod.default !== undefined ? mod.default : mod[exportName];
+  if (value === null || typeof value !== 'object') {
+    return fail(`module '${file}' exports neither a default nor a '${exportName}' document`);
+  }
+  let doc;
+  try {
+    doc = JSON.parse(JSON.stringify(value));
+  }
+  catch (error) {
+    return fail(`module '${file}': the ${exportName} emission is not JSON (${error.message})`);
+  }
+  if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) {
+    return fail(`module '${file}': the ${exportName} emission is not a document`);
+  }
+  return doc;
+};
+
+/**
+ * A model or migration document: a `.json` file, or a module loaded
+ * TWICE — an emission that changes between loads is not pure (a clock,
+ * the environment, randomness), and a migration that hashes differently
+ * per load can never match its own history.
+ */
+async function loadDocument(file, what, exportName) {
+  if (file.endsWith('.json')) return readJson(file, what);
+  if (!MODULE_EXT.test(file)) {
+    return fail(`cannot read ${what} '${file}': neither a .json file nor a module `
+      + '(.js, .mjs, .cjs — or .ts where Node strips types)');
+  }
+  const url = pathToFileURL(path.resolve(file)).href;
+  const load = async () => {
+    try {
+      return await import(`${url}?jaren-db-load=${++loads}`);
+    }
+    catch (error) {
+      return fail(`cannot load ${what} module '${file}': ${error.message}`
+        + (TS_EXT.test(file)
+          ? ' — a .ts module loads only where Node strips types (Node >= 24 does by default; --no-strip-types turns it off)'
+          : ''));
+    }
+  };
+  const first = emissionOf(await load(), exportName, file);
+  const second = emissionOf(await load(), exportName, file);
+  if (canonicalizeJson(first) !== canonicalizeJson(second)) {
+    return fail(`the ${what} module '${file}' is not pure — two loads emitted different documents; `
+      + 'no clock, no env, no randomness in a model or migration module');
+  }
+  return first;
+}
+
+/** The migrations directory, sorted by file name — the full ordered chain. */
+const loadMigrationsDir = async (dir) => {
   if (dir === null) return [];
-  return fs.readdirSync(dir)
-    .filter((file) => file.endsWith('.json'))
-    .sort()
-    .map((file) => readJson(path.join(dir, file), 'migration'));
+  const files = fs.readdirSync(dir)
+    .filter((file) => (file.endsWith('.json') || MODULE_EXT.test(file)) && !file.endsWith('.d.ts'))
+    .sort();
+  const migrations = [];
+  for (const file of files) migrations.push(await loadDocument(path.join(dir, file), 'migration', 'migration'));
+  return migrations;
+};
+
+/** The committed snapshot beside a model, unless one is named. */
+const defaultSnapshotOf = (modelFile) => path.join(path.dirname(modelFile), 'model.snapshot.json');
+
+/** Write a file only when its text changed — two runs on one input change nothing. */
+const writeIfChanged = (file, text) => {
+  const same = fs.existsSync(file) && fs.readFileSync(file, 'utf8') === text;
+  if (!same) fs.writeFileSync(file, text);
+  return same;
 };
 
 /** What a migration will destroy, by note — the confirmation names it. */
@@ -105,17 +199,42 @@ const renderSteps = (migration) => {
 };
 
 async function commandPlan(options) {
-  if (options.from === null || options.to === null)
-    fail('plan needs --from and --to model files');
-  const fromModel = readJson(options.from, 'from-model');
-  const toModel = readJson(options.to, 'to-model');
+  let fromModel;
+  let toModel;
+  let snapshotFile = null;
+  if (options.model !== null) {
+    if (options.from !== null || options.to !== null)
+      fail('plan takes either --from and --to model files, or --model with its --snapshot — not both');
+    snapshotFile = options.snapshot ?? defaultSnapshotOf(options.model);
+    if (!fs.existsSync(snapshotFile)) {
+      fail(`no snapshot at '${snapshotFile}' — write one from the model the store was created with: `
+        + `jaren-db snapshot --model <baseline> --snapshot '${snapshotFile}'`);
+    }
+    fromModel = readJson(snapshotFile, 'snapshot');
+    toModel = await loadDocument(options.model, 'model', 'model');
+    if (shapeHash(fromModel) === shapeHash(toModel)) {
+      console.log(`no change — the model matches its snapshot (${snapshotFile}); nothing to plan`);
+      return;
+    }
+  }
+  else {
+    if (options.from === null || options.to === null)
+      fail('plan needs --from and --to model files, or --model with a committed --snapshot');
+    fromModel = await loadDocument(options.from, 'from-model', 'model');
+    toModel = await loadDocument(options.to, 'to-model', 'model');
+  }
   if (options.store !== null) {
-    const status = await migrationStatus(
-      { driver: nodeDriver(), path: options.store }, [], {
-        baseline: fromModel, model: fromModel,
-      }).catch((error) => fail(error.message));
-    if (status.drift !== null) {
-      fail(`the store does not match the from-model (${status.drift}) — `
+    // the from-model is compared with the database's SHAPE directly:
+    // asking the history with an empty chain refused every database
+    // that had applied a migration (JD0022), which is every database
+    // one plans a second migration for
+    const driver = nodeDriver();
+    const connection = await driver.open(options.store, {}).catch((error) => fail(error.message));
+    const drift = await Promise.resolve(compareShapeToModel(driver, connection, fromModel, undefined))
+      .catch((error) => fail(error.message));
+    await connection.close();
+    if (drift !== null) {
+      fail(`the store does not match the from-model (${drift}) — `
         + 'is this really the previous model?');
     }
   }
@@ -136,14 +255,39 @@ async function commandPlan(options) {
       + 'fill them in before applying');
   }
   if (report.destructive) console.error('NOTE: this migration is DESTRUCTIVE');
+  if (snapshotFile !== null) {
+    if (options.out === null) {
+      console.error(`NOTE: the snapshot was not advanced — plan with --out to write the migration and move ${snapshotFile}`);
+    }
+    else {
+      writeIfChanged(snapshotFile, JSON.stringify(toModel, null, 2) + '\n');
+      console.log(`advanced ${snapshotFile} (shape ${shapeHash(toModel)})`);
+    }
+  }
 }
 
 async function commandStatus(options, { asCheck }) {
   if (options.store === null || options.baseline === null)
     fail(`${asCheck ? 'check' : 'status'} needs --store and --baseline`);
-  const baseline = readJson(options.baseline, 'baseline model');
-  const model = options.model !== null ? readJson(options.model, 'model') : undefined;
-  const migrations = readMigrationsDir(options.migrations);
+  // `check` without the model verified nothing and printed "in sync"
+  if (asCheck && options.model === null)
+    fail('check needs --model — drift is measured against the model the code carries');
+  const baseline = await loadDocument(options.baseline, 'baseline model', 'model');
+  const model = options.model !== null ? await loadDocument(options.model, 'model', 'model') : undefined;
+  const migrations = await loadMigrationsDir(options.migrations);
+  // the snapshot discipline, when it is in use: a model that moved
+  // without a plan is named as such, never as the database's drift
+  const snapshotFile = options.snapshot ?? (options.model !== null ? defaultSnapshotOf(options.model) : null);
+  let unplanned = null;
+  const snapshotInUse = snapshotFile !== null && (options.snapshot !== null || fs.existsSync(snapshotFile));
+  if (snapshotInUse) {
+    if (!fs.existsSync(snapshotFile)) fail(`no snapshot at '${snapshotFile}'`);
+    const recorded = shapeHash(readJson(snapshotFile, 'snapshot'));
+    const current = shapeHash(model);
+    if (recorded !== current) {
+      unplanned = `${snapshotFile} records shape ${recorded}, the model is ${current} — run jaren-db plan`;
+    }
+  }
   let status;
   try {
     status = await migrationStatus({ driver: nodeDriver(), path: options.store },
@@ -157,7 +301,12 @@ async function commandStatus(options, { asCheck }) {
   if (model !== undefined && status.pending.length === 0) {
     console.log(`drift:    ${status.drift === null ? 'none — in sync' : status.drift}`);
   }
+  if (snapshotInUse) {
+    console.log(`model:    ${unplanned === null ? 'planned — matches its snapshot' : `UNPLANNED change — ${unplanned}`}`);
+  }
   if (asCheck) {
+    if (unplanned !== null)
+      fail(`unplanned model change: ${unplanned}`);
     if (status.pending.length > 0)
       fail(`${status.pending.length} pending migration(s) — run jaren-db apply`);
     if (status.drift !== null)
@@ -177,9 +326,9 @@ const confirm = (question) => new Promise((resolve) => {
 async function commandApply(options) {
   if (options.store === null || options.baseline === null || options.migrations === null)
     fail('apply needs --store, --baseline and --migrations');
-  const baseline = readJson(options.baseline, 'baseline model');
-  const model = options.model !== null ? readJson(options.model, 'model') : undefined;
-  const migrations = readMigrationsDir(options.migrations);
+  const baseline = await loadDocument(options.baseline, 'baseline model', 'model');
+  const model = options.model !== null ? await loadDocument(options.model, 'model', 'model') : undefined;
+  const migrations = await loadMigrationsDir(options.migrations);
   const target = { driver: nodeDriver(), path: options.store };
 
   const status = await migrationStatus(target, migrations, { baseline })
@@ -206,7 +355,10 @@ async function commandApply(options) {
     const answer = await confirm('Apply anyway? [y/N] ');
     if (!answer) fail('aborted — nothing was applied');
   }
-  else if (!options.yes && process.stdin.isTTY) {
+  else if (!options.yes) {
+    // "default is dry-run + ask" (MIGRATION-FORMAT §11): where nobody
+    // can be asked, the statements above are the dry run and nothing runs
+    if (!process.stdin.isTTY) fail('apply needs --yes (no interactive terminal to ask) — nothing was applied');
     const answer = await confirm('Apply? [y/N] ');
     if (!answer) fail('aborted — nothing was applied');
   }
@@ -220,9 +372,37 @@ async function commandApply(options) {
   }
 }
 
-function commandShape(options) {
+async function commandSnapshot(options) {
+  if (options.model === null) fail('snapshot needs --model');
+  const model = await loadDocument(options.model, 'model', 'model');
+  const snapshotFile = options.snapshot ?? defaultSnapshotOf(options.model);
+  const same = writeIfChanged(snapshotFile, JSON.stringify(model, null, 2) + '\n');
+  console.log(`${same ? 'unchanged' : 'wrote'} ${snapshotFile} (shape ${shapeHash(model)})`);
+  if (options.types === null) return;
+  // emit is loaded lazily, and only here: db does not depend on it, so a
+  // host without it is told exactly what --types needs
+  let emit;
+  let typescript;
+  try {
+    emit = await import('@jarenjs/emit');
+    typescript = await import('@jarenjs/emit/typescript');
+  }
+  catch (error) {
+    if (error.code === 'ERR_MODULE_NOT_FOUND' || error.code === 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
+      return fail(`--types needs @jarenjs/emit beside @jarenjs/db, and it does not resolve `
+        + `(${error.message}) — install it: npm install @jarenjs/emit`);
+    }
+    throw error;
+  }
+  const declaration = typescript.renderTypeScript(
+    entityEmitModel(model, { compile: emit.compileEmitModel, source: options.model }), {});
+  const sameTypes = writeIfChanged(options.types, declaration);
+  console.log(`${sameTypes ? 'unchanged' : 'wrote'} ${options.types}`);
+}
+
+async function commandShape(options) {
   if (options.model === null) fail('shape needs --model');
-  const model = readJson(options.model, 'model');
+  const model = await loadDocument(options.model, 'model', 'model');
   console.log(`shape hash: ${shapeHash(model)}`);
   for (const collection of normalizeModel(model).values()) {
     for (const sql of planCollection(collection.name, collection, sqliteDialect).createSql)
@@ -251,6 +431,7 @@ async function main() {
   }
   switch (options.command) {
     case 'plan': return commandPlan(options);
+    case 'snapshot': return commandSnapshot(options);
     case 'status': return commandStatus(options, { asCheck: false });
     case 'check': return commandStatus(options, { asCheck: true });
     case 'apply': return commandApply(options);

package/src/ddl.js

@@ -70,12 +70,32 @@ export function compileIndexPath(expression, docPath) {
       `the index path '${expression}' selects the whole document — index a member`,
       docPath);
   }
-  const canonical = segments
-    .map((s) => ('name' in s ? `.${s.name}` : `[${s.index}]`))
+  return { segments, canonical: canonicalOf(segments) };
+}
+
+/**
+ * The canonical spelling of a member path — the key every generated
+ * column and every promoted reference is matched by. INJECTIVE: a
+ * member literally named `a.b` and the nested path `a` → `b` used to
+ * spell the same `.a.b`, so an index over one silently served the
+ * other and a filter on the flat member answered from the nested
+ * value. Names are JSON-quoted, so no two paths share a spelling; the
+ * generated column STEM strips the quotes and keeps its old form.
+ * @param {import('./dialect.js').JsonPathSegment[]} segments
+ * @returns {string}
+ */
+export function canonicalOf(segments) {
+  return segments
+    .map((s) => ('name' in s
+      ? (IDENTIFIER.test(s.name) ? `.${s.name}` : `.${JSON.stringify(s.name)}`)
+      : `[${s.index}]`))
     .join('');
-  return { segments, canonical };
 }
 
+/** A member name that spells itself: anything else is JSON-quoted in
+ * the canonical, so `.a.b` (nested) and `."a.b"` (one member) differ. */
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
 /**
  * The schema subschema at a segment path, walked structurally through
  * `properties` / `items` / `prefixItems`. The collection's schema is

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