static-fire 0.0.0-stage → 0.54.1

package/src/core/db.ts

@@ -0,0 +1,608 @@
+// The record store: one SQLite file (runs/static-fire.db) holds every batch, trial, grading and verdict.
+// It is the only copy of the records (authored files stay YAML). Plain SQL, no ORM.
+//
+// Several CLI processes can write at once: WAL mode, a 5000 ms busy timeout, and every write in a
+// BEGIN IMMEDIATE transaction (a deferred one that reads and then writes can fail at once in WAL mode).
+// The record rules live in the schema as triggers, so they hold for every writer:
+//   - a trial row never changes after the trial has ended (status done, failed or invalid);
+//   - a grading is never overwritten: once done or invalid, its row and its verdicts are read-only.
+// Regrading adds a new grading row; currentGrading() returns the latest finished one.
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { projectPaths, projectRoot } from "./project";
+import type { Vote } from "./types";
+
+/** The schema version, kept in PRAGMA user_version. */
+export const SCHEMA_VERSION = 4;
+
+const BUSY_TIMEOUT_MS = 5000;
+
+const ENDED = "('done', 'failed', 'invalid')";
+
+/**
+ * MIGRATIONS[i] takes the schema from version i to version i + 1. Never edit a released step: add one.
+ * Every step runs with foreign keys off, in one write transaction with the others, and a foreign key check must
+ * be clean before it commits (migrate()). Exported for the upgrade tests, which build older stores with them.
+ */
+export const MIGRATIONS: readonly string[] = [
+  `
+  CREATE TABLE task_versions (
+    hash        TEXT PRIMARY KEY,
+    task_id     TEXT NOT NULL,
+    label       INTEGER NOT NULL,
+    snapshot    TEXT NOT NULL,
+    first_seen  TEXT NOT NULL
+  );
+  CREATE TABLE grading_setups (
+    hash          TEXT PRIMARY KEY,
+    task_id       TEXT NOT NULL,
+    task_hash     TEXT NOT NULL REFERENCES task_versions(hash),
+    judge_harness TEXT NOT NULL,
+    judge_model   TEXT NOT NULL,
+    judge_effort  TEXT,
+    judge_label   TEXT NOT NULL,
+    grader_rev    INTEGER NOT NULL,
+    snapshot      TEXT NOT NULL,
+    first_seen    TEXT NOT NULL
+  );
+  CREATE TABLE user_setups (
+    hash   TEXT PRIMARY KEY,
+    files  TEXT NOT NULL
+  );
+  CREATE TABLE batches (
+    id                TEXT PRIMARY KEY,
+    started_at        TEXT NOT NULL,
+    ended_at          TEXT,
+    request           TEXT NOT NULL,
+    harness_versions  TEXT NOT NULL
+  );
+  CREATE TABLE trials (
+    id                  TEXT PRIMARY KEY,
+    batch_id            TEXT NOT NULL REFERENCES batches(id),
+    task_id             TEXT NOT NULL,
+    task_hash           TEXT NOT NULL REFERENCES task_versions(hash),
+    config_key          TEXT NOT NULL,
+    config_id           TEXT NOT NULL,
+    harness             TEXT NOT NULL,
+    model               TEXT NOT NULL,
+    effort              TEXT,
+    profile             TEXT,
+    provider            TEXT,
+    family              TEXT,
+    n                   INTEGER NOT NULL,
+    status              TEXT NOT NULL CHECK (status IN ('queued', 'running', 'done', 'failed', 'invalid')),
+    started_at          TEXT,
+    ended_at            TEXT,
+    duration_ms         INTEGER,
+    input_tokens        INTEGER,
+    output_tokens       INTEGER,
+    cache_read_tokens   INTEGER,
+    cache_write_tokens  INTEGER,
+    cost_usd            REAL,
+    cost_source         TEXT,
+    turns               INTEGER,
+    setup_hash          TEXT REFERENCES user_setups(hash),
+    profile_hash        TEXT,
+    blocked_tools       TEXT,
+    harness_version     TEXT,
+    copied_share        REAL,
+    error               TEXT,
+    dir                 TEXT NOT NULL
+  );
+  CREATE TABLE gradings (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    trial_id        TEXT NOT NULL REFERENCES trials(id),
+    grading_hash    TEXT NOT NULL REFERENCES grading_setups(hash),
+    votes           INTEGER NOT NULL,
+    graded_at       TEXT NOT NULL,
+    status          TEXT NOT NULL CHECK (status IN ('grading', 'done', 'invalid')),
+    score           REAL,
+    gates_passed    INTEGER,
+    measures        TEXT,
+    judge_cost_usd  REAL,
+    error           TEXT
+  );
+  CREATE TABLE verdicts (
+    grading_id    INTEGER NOT NULL REFERENCES gradings(id),
+    criterion_id  TEXT NOT NULL,
+    score         REAL,
+    error         TEXT,
+    votes         TEXT NOT NULL,
+    PRIMARY KEY (grading_id, criterion_id)
+  );
+
+  CREATE INDEX trials_task_config ON trials(task_id, task_hash, config_key);
+  CREATE INDEX gradings_trial_hash_time ON gradings(trial_id, grading_hash, graded_at);
+  CREATE INDEX verdicts_grading ON verdicts(grading_id);
+
+  CREATE TRIGGER trials_ended_no_update BEFORE UPDATE ON trials WHEN OLD.status IN ${ENDED}
+  BEGIN SELECT RAISE(ABORT, 'trial row is read-only: the trial has ended (status done, failed or invalid)'); END;
+  CREATE TRIGGER trials_ended_no_delete BEFORE DELETE ON trials WHEN OLD.status IN ${ENDED}
+  BEGIN SELECT RAISE(ABORT, 'trial row cannot be deleted: the trial has ended (status done, failed or invalid)'); END;
+  -- INSERT OR REPLACE deletes the old row without firing the DELETE trigger (recursive_triggers is off by
+  -- default), so an insert over an existing read-only row is refused here.
+  CREATE TRIGGER trials_ended_no_replace BEFORE INSERT ON trials
+  WHEN EXISTS (SELECT 1 FROM trials WHERE id = NEW.id AND status IN ${ENDED})
+  BEGIN SELECT RAISE(ABORT, 'trial row is read-only: the trial has ended (status done, failed or invalid)'); END;
+
+  CREATE TRIGGER gradings_finished_no_update BEFORE UPDATE ON gradings WHEN OLD.status <> 'grading'
+  BEGIN SELECT RAISE(ABORT, 'grading row is read-only: the grading has finished (status done or invalid); regrade to add a new grading'); END;
+  CREATE TRIGGER gradings_finished_no_delete BEFORE DELETE ON gradings WHEN OLD.status <> 'grading'
+  BEGIN SELECT RAISE(ABORT, 'grading row cannot be deleted: the grading has finished (status done or invalid)'); END;
+  CREATE TRIGGER gradings_finished_no_replace BEFORE INSERT ON gradings
+  WHEN EXISTS (SELECT 1 FROM gradings WHERE id = NEW.id AND status <> 'grading')
+  BEGIN SELECT RAISE(ABORT, 'grading row is read-only: the grading has finished (status done or invalid); regrade to add a new grading'); END;
+
+  CREATE TRIGGER verdicts_no_update BEFORE UPDATE ON verdicts
+  BEGIN SELECT RAISE(ABORT, 'verdict row is read-only: verdicts never change once written'); END;
+  CREATE TRIGGER verdicts_no_delete BEFORE DELETE ON verdicts
+  BEGIN SELECT RAISE(ABORT, 'verdict row cannot be deleted: verdicts never change once written'); END;
+  CREATE TRIGGER verdicts_finished_no_insert BEFORE INSERT ON verdicts
+  WHEN (SELECT status FROM gradings WHERE id = NEW.grading_id) <> 'grading'
+  BEGIN SELECT RAISE(ABORT, 'cannot add a verdict: its grading has finished (status done or invalid)'); END;
+  CREATE TRIGGER verdicts_no_replace BEFORE INSERT ON verdicts
+  WHEN EXISTS (SELECT 1 FROM verdicts WHERE grading_id = NEW.grading_id AND criterion_id = NEW.criterion_id)
+  BEGIN SELECT RAISE(ABORT, 'verdict row is read-only: verdicts never change once written'); END;
+  `,
+  // How many runs of a batch (its `run`, and each `rerun`) are still working: running trials or grading them.
+  // Bookkeeping for the batch's end time only, so it is not part of BatchRecord.
+  `ALTER TABLE batches ADD COLUMN runs_in_flight INTEGER NOT NULL DEFAULT 0;`,
+  // The grader revision was one number per grading version. The engine revision is a set of parts that the
+  // stored snapshot holds (identity.ts, engineOf), so the column has nothing left to say. Snapshots are not touched.
+  `ALTER TABLE grading_setups DROP COLUMN grader_rev;`,
+  // A task file's `version` is optional, so a task version can have no label. SQLite cannot drop NOT NULL in
+  // place: the table is built again with the same columns in the same order, and every row (rowid included) is
+  // copied. grading_setups and trials reference task_versions by name, so their foreign keys hold after the rename.
+  `
+  CREATE TABLE task_versions_new (
+    hash        TEXT PRIMARY KEY,
+    task_id     TEXT NOT NULL,
+    label       INTEGER,
+    snapshot    TEXT NOT NULL,
+    first_seen  TEXT NOT NULL
+  );
+  INSERT INTO task_versions_new (rowid, hash, task_id, label, snapshot, first_seen)
+    SELECT rowid, hash, task_id, label, snapshot, first_seen FROM task_versions ORDER BY rowid;
+  DROP TABLE task_versions;
+  ALTER TABLE task_versions_new RENAME TO task_versions;
+  `,
+];
+
+/** Where the store is: STATIC_FIRE_DB when set, else runs/static-fire.db in the project found from the current folder. */
+export function defaultDbPath(): string {
+  return process.env.STATIC_FIRE_DB || projectPaths(projectRoot()).dbPath;
+}
+
+/**
+ * A trial's artifact folder: `<folder of the database>/trials/<trial-id>`. The `dir` column holds the relative
+ * `trials/<trial-id>`, so the records and artifacts survive a moved checkout.
+ */
+export function trialDir(dbPath: string, trialId: string): string {
+  return join(dirname(resolve(dbPath)), "trials", trialId);
+}
+
+// ---- Records -------------------------------------------------------------------------------------
+// Fields are camelCase; each maps to the snake_case column of the same name. Absent values are null.
+
+type JsonObject = Record<string, unknown>;
+
+/** One task hash: what the agent was given. */
+export interface TaskVersionRecord {
+  hash: string; taskId: string;
+  label: number | null;          // the task file's `version`, a readable label only; null when the file has none
+  snapshot: JsonObject;          // prompt, output, file hashes
+  firstSeen: string;
+}
+
+/** One grading hash: how an output was graded. */
+export interface GradingSetupRecord {
+  hash: string; taskId: string; taskHash: string;
+  judgeHarness: string; judgeModel: string; judgeEffort: string | null; judgeLabel: string;
+  snapshot: JsonObject;          // gates, measures, context, file hashes, and the engine revision (identity.ts, engineOf)
+  firstSeen: string;
+}
+
+/** One user setup: path → content hash of each file. */
+export interface UserSetupRecord { hash: string; files: Record<string, string> }
+
+/** One `run` invocation. */
+export interface BatchRecord {
+  id: string; startedAt: string; endedAt: string | null;
+  request: JsonObject;                       // what was asked for
+  harnessVersions: Record<string, string | null>;   // harness → CLI version, read once per batch (null: could not be read)
+}
+
+export type TrialRecordStatus = "queued" | "running" | "done" | "failed" | "invalid";
+
+/** One agent run. Read-only once its status is done, failed or invalid. */
+export interface TrialRecord {
+  id: string; batchId: string; taskId: string; taskHash: string;
+  configKey: string; configId: string;
+  harness: string; model: string; effort: string | null; profile: string | null; provider: string | null; family: string | null;
+  n: number;
+  status: TrialRecordStatus;
+  startedAt: string | null; endedAt: string | null; durationMs: number | null;
+  inputTokens: number | null; outputTokens: number | null; cacheReadTokens: number | null; cacheWriteTokens: number | null;
+  costUsd: number | null; costSource: string | null; turns: number | null;
+  setupHash: string | null; profileHash: string | null; blockedTools: string[] | null; harnessVersion: string | null;
+  copiedShare: number | null;
+  error: string | null;
+  dir: string;                   // the trial's artifact folder
+}
+
+export type GradingStatus = "grading" | "done" | "invalid";
+
+/** One grading of one trial under one grading hash. Read-only once done or invalid. */
+export interface GradingRecord {
+  id: number; trialId: string; gradingHash: string; votes: number; gradedAt: string;
+  status: GradingStatus;
+  score: number | null; gatesPassed: boolean | null; measures: Record<string, number> | null;
+  judgeCostUsd: number | null; error: string | null;
+}
+
+/** One criterion in one grading. */
+export interface VerdictRecord {
+  gradingId: number; criterionId: string;
+  score: number | null; error: string | null;
+  votes: Vote[];
+}
+
+export interface NewGrading { trialId: string; gradingHash: string; votes: number; gradedAt: string }
+
+/** How a grading ended, with its verdicts. */
+export interface GradingResult {
+  status: "done" | "invalid";
+  score: number | null; gatesPassed: boolean | null; measures: Record<string, number> | null;
+  judgeCostUsd: number | null; error: string | null;
+  verdicts: Omit<VerdictRecord, "gradingId">[];
+}
+
+export interface TrialFilter { batchId?: string; taskId?: string; taskHash?: string; configKey?: string }
+
+/** Every record, for backup (`static-fire export`). Tables in an order a restore could insert them. */
+export interface ExportDoc {
+  format: "static-fire-export";
+  schemaVersion: number;
+  exportedAt: string;
+  tables: {
+    task_versions: TaskVersionRecord[]; grading_setups: GradingSetupRecord[]; user_setups: UserSetupRecord[];
+    batches: BatchRecord[]; trials: TrialRecord[]; gradings: GradingRecord[]; verdicts: VerdictRecord[];
+  };
+}
+
+export interface Store {
+  /** Stored once per hash: a hash that exists keeps its first record, which is returned. */
+  putTaskVersion(r: TaskVersionRecord): TaskVersionRecord;
+  putGradingSetup(r: GradingSetupRecord): GradingSetupRecord;
+  putUserSetup(r: UserSetupRecord): UserSetupRecord;
+  getTaskVersion(hash: string): TaskVersionRecord | null;
+  getGradingSetup(hash: string): GradingSetupRecord | null;
+  getUserSetup(hash: string): UserSetupRecord | null;
+  /**
+   * Every grading setup, oldest first by first_seen, then hash. With a task id: the setups of that task, which
+   * are the ones recorded for it and the ones a grading of its trials used (two tasks with the same content
+   * share one row, stored with the first task's id).
+   */
+  listGradingSetups(taskId?: string): GradingSetupRecord[];
+  /** The tasks a grading setup belongs to: the task it was recorded for and the tasks of the trials graded under it. */
+  gradingSetupTaskIds(hash: string): string[];
+
+  createBatch(r: BatchRecord): void;
+  endBatch(id: string, endedAt: string): void;
+  /** A run of the batch starts (its `run` or a `rerun`): counts it as in flight and clears the batch's end time. */
+  startBatchRun(id: string): void;
+  /** A run of the batch has finished its trials and their gradings: stops counting it. Returns the runs still in flight. */
+  finishBatchRun(id: string): number;
+  getBatch(id: string): BatchRecord | null;
+  /** Newest first. */
+  listBatches(): BatchRecord[];
+
+  /** Inserts a trial in any status (an import inserts ended trials). */
+  insertTrial(r: TrialRecord): void;
+  /** Changes a trial that has not ended. Throws once its status is done, failed or invalid. */
+  updateTrial(id: string, patch: Partial<Omit<TrialRecord, "id">>): void;
+  getTrial(id: string): TrialRecord | null;
+  /** In id order. */
+  listTrials(filter?: TrialFilter): TrialRecord[];
+
+  /** Adds a grading row in status `grading` and returns its id. A regrade adds a row; none is overwritten. */
+  startGrading(g: NewGrading): number;
+  /** Ends a grading with its verdicts, in one transaction. Throws when the grading has already finished. */
+  finishGrading(id: number, r: GradingResult): void;
+  /** Every grading of a trial (optionally under one grading hash), oldest first, finished or not. */
+  listGradings(trialId: string, gradingHash?: string): GradingRecord[];
+  /** The grading that counts: the latest finished (done or invalid) one under that hash, by graded_at, then id. */
+  currentGrading(trialId: string, gradingHash: string): GradingRecord | null;
+  listVerdicts(gradingId: number): VerdictRecord[];
+
+  /** Runs `fn` in one write transaction (BEGIN IMMEDIATE), for several writes that must land together. */
+  transaction<T>(fn: () => T): T;
+  /** Every record, read in one transaction so the copy is consistent. */
+  exportAll(): ExportDoc;
+  /** Reads one PRAGMA of this connection, for example "busy_timeout". */
+  pragma(name: string): unknown;
+  close(): void;
+}
+
+/**
+ * Opens the store at `path`, creating the folder and the database when missing and bringing an older
+ * schema up to SCHEMA_VERSION. Opening a current database writes nothing.
+ */
+export function openStore(path: string): Store {
+  mkdirSync(dirname(path), { recursive: true });
+  const db = new Database(path, { create: true, strict: true });
+  try {
+    db.run(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);   // first, so the statements below wait for other writers too
+    useWal(db, path);
+    db.run("PRAGMA foreign_keys = ON");
+    migrate(db, path);
+  } catch (e) {
+    db.close();
+    throw e;
+  }
+  return storeOn(db);
+}
+
+/** A new, empty store in memory, with no file: what a plan reads when the project has no record store yet. */
+export function emptyStore(): Store {
+  const db = new Database(":memory:", { strict: true });
+  db.run("PRAGMA foreign_keys = ON");
+  migrate(db, ":memory:");
+  return storeOn(db);
+}
+
+/**
+ * A copy in memory of the store at `path`, for a plan, which must write nothing (#74). The file is opened read-only
+ * and read in one go; an older schema is brought up to SCHEMA_VERSION in the copy only, so the file keeps its
+ * schema, its journal mode and its content. Writes to the copy are lost when it is closed.
+ */
+export function snapshotStore(path: string): Store {
+  const file = new Database(path, { readonly: true, strict: true });
+  let bytes: Uint8Array;
+  try {
+    file.run(`PRAGMA busy_timeout = ${BUSY_TIMEOUT_MS}`);
+    bytes = file.serialize();
+  } finally {
+    file.close();
+  }
+  // Bytes 18 and 19 of the header say WAL mode; an image in memory cannot use WAL, so mark it as a rollback journal.
+  bytes[18] = 1;
+  bytes[19] = 1;
+  const db = Database.deserialize(bytes, { strict: true });
+  try {
+    db.run("PRAGMA foreign_keys = ON");
+    migrate(db, path);
+  } catch (e) {
+    db.close();
+    throw e;
+  }
+  return storeOn(db);
+}
+
+/**
+ * Switches a new database to WAL mode (the mode is kept in the file, so later opens only read it).
+ * SQLite does not apply the busy timeout to this switch: when another process is creating the same file
+ * it fails at once with SQLITE_BUSY. So it is retried for up to the busy timeout.
+ */
+function useWal(db: Database, path: string) {
+  const mode = () => (db.query("PRAGMA journal_mode").get() as { journal_mode: string }).journal_mode;
+  const until = Date.now() + BUSY_TIMEOUT_MS;
+  for (let wait = 5; mode() !== "wal"; wait = Math.min(wait * 2, 100)) {
+    try {
+      db.run("PRAGMA journal_mode = WAL");
+    } catch (e) {
+      if ((e as { code?: string }).code !== "SQLITE_BUSY" || Date.now() > until) throw e;
+      Bun.sleepSync(wait);
+      continue;
+    }
+    if (mode() !== "wal") throw new Error(`could not switch ${path} to WAL mode (it is in ${mode()} mode)`);
+  }
+}
+
+const userVersion = (db: Database) => (db.query("PRAGMA user_version").get() as { user_version: number }).user_version;
+
+function migrate(db: Database, path: string) {
+  const tooNew = (v: number) =>
+    new Error(`${path} has schema version ${v}, newer than this Static Fire (${SCHEMA_VERSION}); update Static Fire to use it`);
+  const seen = userVersion(db);
+  if (seen > SCHEMA_VERSION) throw tooNew(seen);
+  if (seen === SCHEMA_VERSION) return;
+  // A step that builds a table again drops the old one, which foreign keys on would refuse. The setting cannot
+  // change inside a transaction, so it is off for the whole upgrade and checked by hand before the commit.
+  db.run("PRAGMA foreign_keys = OFF");
+  try {
+    // Read the version again inside the write lock: another process may have migrated since.
+    db.transaction(() => {
+      const from = userVersion(db);
+      if (from > SCHEMA_VERSION) throw tooNew(from);
+      if (from === SCHEMA_VERSION) return;
+      for (let v = from; v < SCHEMA_VERSION; v++) db.run(MIGRATIONS[v]!);
+      const broken = db.query("PRAGMA foreign_key_check").all() as { table: string; rowid: number; parent: string }[];
+      if (broken.length) {
+        const where = [...new Set(broken.map((b) => `${b.table} → ${b.parent}`))].join(", ");
+        throw new Error(`${path}: the upgrade to schema version ${SCHEMA_VERSION} would leave ${broken.length} foreign key reference(s) broken (${where}); the store was left as it was`);
+      }
+      db.run(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+    }).immediate();
+  } finally {
+    db.run("PRAGMA foreign_keys = ON");
+  }
+}
+
+// ---- Row mapping ---------------------------------------------------------------------------------
+
+type Kind = "plain" | "json" | "bool";
+interface Table { name: string; order: string; fields: [field: string, column: string, kind: Kind][] }
+
+const snake = (field: string) => field.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+
+/** `spec` lists the fields, camelCase, with ":json" or ":bool" for columns that need converting. */
+const table = (name: string, order: string, spec: string): Table => ({
+  name, order,
+  fields: spec.trim().split(/\s+/).map((f) => {
+    const [field, kind = "plain"] = f.split(":") as [string, Kind?];
+    return [field, snake(field), kind];
+  }),
+});
+
+const T = {
+  task_versions: table("task_versions", "hash", "hash taskId label snapshot:json firstSeen"),
+  grading_setups: table("grading_setups", "hash",
+    "hash taskId taskHash judgeHarness judgeModel judgeEffort judgeLabel snapshot:json firstSeen"),
+  user_setups: table("user_setups", "hash", "hash files:json"),
+  batches: table("batches", "id", "id startedAt endedAt request:json harnessVersions:json"),
+  trials: table("trials", "id", `
+    id batchId taskId taskHash configKey configId harness model effort profile provider family n status
+    startedAt endedAt durationMs inputTokens outputTokens cacheReadTokens cacheWriteTokens costUsd costSource turns
+    setupHash profileHash blockedTools:json harnessVersion copiedShare error dir`),
+  gradings: table("gradings", "id",
+    "id trialId gradingHash votes gradedAt status score gatesPassed:bool measures:json judgeCostUsd error"),
+  verdicts: table("verdicts", "grading_id, criterion_id", "gradingId criterionId score error votes:json"),
+} as const;
+
+/** Record → named parameters (column → value). Only the fields present in `r` are included. */
+function encode(t: Table, r: Record<string, unknown>): Record<string, unknown> {
+  const known = new Set(t.fields.map(([f]) => f));
+  for (const k of Object.keys(r)) if (!known.has(k)) throw new Error(`${t.name} has no field ${k}`);
+  const out: Record<string, unknown> = {};
+  for (const [field, column, kind] of t.fields) {
+    if (!(field in r)) continue;
+    const v = r[field] ?? null;
+    out[column] = v === null ? null : kind === "json" ? JSON.stringify(v) : kind === "bool" ? (v ? 1 : 0) : v;
+  }
+  return out;
+}
+
+function decode<R>(t: Table, row: Record<string, unknown> | null): R | null {
+  if (!row) return null;
+  const out: Record<string, unknown> = {};
+  for (const [field, column, kind] of t.fields) {
+    const v = row[column] ?? null;
+    out[field] = v === null ? null : kind === "json" ? JSON.parse(v as string) : kind === "bool" ? v === 1 : v;
+  }
+  return out as R;
+}
+
+const ENDED_TRIAL = new Set<string>(["done", "failed", "invalid"]);
+/** The grading hashes the gradings of one task's trials ($taskId) used. */
+const GRADING_HASHES_OF_TASK = "SELECT g.grading_hash FROM gradings g JOIN trials t ON t.id = g.trial_id WHERE t.task_id = $taskId";
+
+function storeOn(db: Database): Store {
+  const write = <X>(fn: () => X): X => db.transaction(fn).immediate();
+  const insert = (t: Table, r: object, verb = "INSERT") => {
+    const p = encode(t, r as Record<string, unknown>);
+    const cols = Object.keys(p);
+    return db.query(`${verb} INTO ${t.name} (${cols.join(", ")}) VALUES (${cols.map((c) => `$${c}`).join(", ")})`).run(p as any);
+  };
+  const one = <R>(t: Table, where: string, params: Record<string, unknown>) =>
+    decode<R>(t, db.query(`SELECT * FROM ${t.name} WHERE ${where}`).get(params as any) as Record<string, unknown> | null);
+  const many = <R>(t: Table, where: string, params: Record<string, unknown>, order = t.order) =>
+    (db.query(`SELECT * FROM ${t.name} ${where ? `WHERE ${where}` : ""} ORDER BY ${order}`).all(params as any) as Record<string, unknown>[])
+      .map((row) => decode<R>(t, row)!);
+  /** INSERT OR IGNORE, then the stored row: the first record for a hash stays. */
+  const putOnce = <R extends { hash: string }>(t: Table, r: R): R => write(() => {
+    insert(t, r, "INSERT OR IGNORE");
+    return one<R>(t, "hash = $hash", { hash: r.hash })!;
+  });
+  const getGrading = (id: number) => one<GradingRecord>(T.gradings, "id = $id", { id });
+
+  const store: Store = {
+    putTaskVersion: (r) => putOnce(T.task_versions, r),
+    putGradingSetup: (r) => putOnce(T.grading_setups, r),
+    putUserSetup: (r) => putOnce(T.user_setups, r),
+    getTaskVersion: (hash) => one(T.task_versions, "hash = $hash", { hash }),
+    getGradingSetup: (hash) => one(T.grading_setups, "hash = $hash", { hash }),
+    getUserSetup: (hash) => one(T.user_setups, "hash = $hash", { hash }),
+    listGradingSetups: (taskId) => taskId === undefined
+      ? many(T.grading_setups, "", {}, "first_seen, hash")
+      : many(T.grading_setups, `task_id = $taskId OR hash IN (${GRADING_HASHES_OF_TASK})`, { taskId }, "first_seen, hash"),
+    gradingSetupTaskIds: (hash) => (db.query(`SELECT task_id FROM grading_setups WHERE hash = $hash
+      UNION SELECT t.task_id FROM gradings g JOIN trials t ON t.id = g.trial_id WHERE g.grading_hash = $hash ORDER BY 1`)
+      .all({ hash }) as { task_id: string }[]).map((r) => r.task_id),
+
+    createBatch: (r) => { write(() => insert(T.batches, r)); },
+    endBatch(id, endedAt) {
+      const { changes } = write(() => db.query("UPDATE batches SET ended_at = $endedAt WHERE id = $id").run({ id, endedAt }));
+      if (!changes) throw new Error(`no batch ${id}`);
+    },
+    startBatchRun(id) {
+      const { changes } = write(() => db.query("UPDATE batches SET ended_at = NULL, runs_in_flight = runs_in_flight + 1 WHERE id = $id").run({ id }));
+      if (!changes) throw new Error(`no batch ${id}`);
+    },
+    finishBatchRun: (id) => write(() => {
+      const row = db.query("UPDATE batches SET runs_in_flight = MAX(runs_in_flight - 1, 0) WHERE id = $id RETURNING runs_in_flight").get({ id }) as { runs_in_flight: number } | null;
+      if (!row) throw new Error(`no batch ${id}`);
+      return row.runs_in_flight;
+    }),
+    getBatch: (id) => one(T.batches, "id = $id", { id }),
+    listBatches: () => many(T.batches, "", {}, "started_at DESC, id DESC"),
+
+    insertTrial: (r) => { write(() => insert(T.trials, r)); },
+    updateTrial(id, patch) {
+      if ("id" in patch) throw new Error(`a trial's id cannot change (trial ${id})`);
+      const p = encode(T.trials, patch);
+      const cols = Object.keys(p);
+      if (!cols.length) return;
+      write(() => {
+        const cur = one<TrialRecord>(T.trials, "id = $id", { id });
+        if (!cur) throw new Error(`no trial ${id}`);
+        if (ENDED_TRIAL.has(cur.status)) throw new Error(`trial ${id} has ended (status ${cur.status}); its row cannot change`);
+        db.query(`UPDATE trials SET ${cols.map((c) => `${c} = $${c}`).join(", ")} WHERE id = $__id`).run({ ...p, __id: id } as any);
+      });
+    },
+    getTrial: (id) => one(T.trials, "id = $id", { id }),
+    listTrials(f = {}) {
+      const where = (["batchId", "taskId", "taskHash", "configKey"] as const)
+        .filter((k) => f[k] !== undefined)
+        .map((k) => `${snake(k)} = $${k}`);
+      const params = Object.fromEntries(Object.entries(f).filter(([, v]) => v !== undefined));
+      return many(T.trials, where.join(" AND "), params);
+    },
+
+    startGrading(g) {
+      const { lastInsertRowid } = write(() => insert(T.gradings, { ...g, status: "grading" }));
+      return Number(lastInsertRowid);
+    },
+    finishGrading(id, r) {
+      if (r.status !== "done" && r.status !== "invalid") throw new Error(`a grading ends as done or invalid, not ${r.status}`);
+      write(() => {
+        const cur = getGrading(id);
+        if (!cur) throw new Error(`no grading ${id}`);
+        if (cur.status !== "grading") {
+          throw new Error(`grading ${id} has finished (status ${cur.status}); a grading is never overwritten: start a new grading to regrade`);
+        }
+        for (const v of r.verdicts) insert(T.verdicts, { ...v, gradingId: id });   // before the status changes: verdicts of a finished grading are refused
+        const { verdicts, ...rest } = r;
+        const p = encode(T.gradings, rest);
+        db.query(`UPDATE gradings SET ${Object.keys(p).map((c) => `${c} = $${c}`).join(", ")} WHERE id = $__id`).run({ ...p, __id: id } as any);
+      });
+    },
+    listGradings: (trialId, gradingHash) => gradingHash === undefined
+      ? many(T.gradings, "trial_id = $trialId", { trialId }, "graded_at, id")
+      : many(T.gradings, "trial_id = $trialId AND grading_hash = $gradingHash", { trialId, gradingHash }, "graded_at, id"),
+    currentGrading: (trialId, gradingHash) => many<GradingRecord>(T.gradings,
+      "trial_id = $trialId AND grading_hash = $gradingHash AND status IN ('done', 'invalid')", { trialId, gradingHash },
+      "graded_at DESC, id DESC LIMIT 1")[0] ?? null,
+    listVerdicts: (gradingId) => many(T.verdicts, "grading_id = $gradingId", { gradingId }, "criterion_id"),
+
+    transaction: (fn) => write(fn),
+    exportAll: () => db.transaction((): ExportDoc => ({
+      format: "static-fire-export",
+      schemaVersion: SCHEMA_VERSION,
+      exportedAt: new Date().toISOString(),
+      tables: {
+        task_versions: many(T.task_versions, "", {}), grading_setups: many(T.grading_setups, "", {}),
+        user_setups: many(T.user_setups, "", {}), batches: many(T.batches, "", {}), trials: many(T.trials, "", {}),
+        gradings: many(T.gradings, "", {}), verdicts: many(T.verdicts, "", {}),
+      },
+    }))(),
+    pragma(name) {
+      if (!/^[a-z_]+$/.test(name)) throw new Error(`not a pragma name: ${name}`);
+      const row = db.query(`PRAGMA ${name}`).get() as Record<string, unknown> | null;
+      return row ? Object.values(row)[0] : null;
+    },
+    close: () => db.close(),
+  };
+  return store;
+}