botversion-sdk 2.2.3 → 2.3.0

package/undo/lib/capture-sqlite.js

@@ -0,0 +1,933 @@
+// lib/capture-sqlite.js
+"use strict";
+
+//capture-sqlite.js
+// SQLITE CAPTURE (Phase 6): saves before/after rows of tagged UPDATE, INSERT and DELETE statements.
+// DELETE also saves the rows the database removes or changes through foreign keys (when foreign keys are switched on).
+// One set of steps (generators) serves both drivers:
+//   better-sqlite3 answers at once  -> steps run in one go (captureBetter)
+//   sqlite3 answers through callbacks -> steps run step by step (captureNode)
+// Never throws into the host except: the host's own error, or Blocked (the confirm gate). Logs: names, counts, reasons only.
+
+const log = require("./log");
+const tagger = require("./tagger");
+const guard = require("./capture-guard");
+const gate = require("./gate");
+const store = require("./snapshot-store");
+const ss = require("./snapshot-store-sqlite");
+const S = require("./sqlite-sql");
+
+const { Skip, q, tableSql } = S;
+
+const MAX_DEPTH = 5; // how many levels of linked rows a delete may reach
+const WRITE_WORDS = new Set([
+  "INSERT",
+  "UPDATE",
+  "DELETE",
+  "REPLACE",
+  "DROP",
+  "ALTER",
+]);
+const WRITE_IN_WITH = /\b(INSERT|UPDATE|DELETE|REPLACE)\b/i;
+const BAD_NOTES = [
+  "has-subquery",
+  "upsert",
+  "insert-from-select",
+  "multi-table",
+  "replace",
+  "or-conflict",
+];
+
+const infoCache = new WeakMap(); // database object -> Map of table info
+
+const labelOf = (t) => (t.db ? t.db + "." : "") + t.table;
+const keyOf = (row, cols) =>
+  cols
+    .map((c) => {
+      const v = row[c];
+      return v instanceof Date ? v.toISOString() : String(v);
+    })
+    .join("\u0001");
+const pickPk = (row, cols) => {
+  const o = {};
+  for (const c of cols) o[c] = row[c];
+  return o;
+};
+const tagOf = (table, row, pk) =>
+  String(table).toLowerCase() + "\u0002" + keyOf(row, pk);
+
+// ---- reading the table's structure from the database itself ----
+
+// Primary key columns (and whether it is a single INTEGER PRIMARY KEY, which SQLite fills in by itself).
+function* tableInfo(io, ref) {
+  let cache = infoCache.get(io.key);
+  if (!cache) {
+    cache = new Map();
+    infoCache.set(io.key, cache);
+  }
+  const key = (ref.db || "") + "|" + ref.table.toLowerCase();
+  if (cache.has(key)) return cache.get(key);
+  const schema = ref.db ? q(ref.db) + "." : "";
+  let rows;
+  try {
+    rows = (yield io.run(`PRAGMA ${schema}table_xinfo(${q(ref.table)})`, []))
+      .rows;
+  } catch (_) {
+    rows = (yield io.run(`PRAGMA ${schema}table_info(${q(ref.table)})`, []))
+      .rows;
+  }
+  const pkRows = rows
+    .filter((r) => Number(r.pk) > 0)
+    .sort((a, b) => Number(a.pk) - Number(b.pk));
+  const info = {
+    cols: rows.map((r) => r.name),
+    pk: pkRows.map((r) => r.name),
+    auto:
+      pkRows.length === 1 &&
+      /^integer$/i.test(String(pkRows[0].type || "").trim()),
+    generated: rows.some((r) => Number(r.hidden) >= 2), // generated columns cannot be written back
+  };
+  if (rows.length) cache.set(key, info);
+  return info;
+}
+
+// Rows of a table with the given key values. (OR of ANDs: SQLite has no list of row values in IN.)
+function* readWhere(io, ref, cols, valueRows, limit) {
+  if (!valueRows.length) return [];
+  const params = [];
+  const terms = valueRows.map(
+    (o) =>
+      "(" +
+      cols
+        .map((c) => {
+          params.push(o[c]);
+          return q(c) + " = ?";
+        })
+        .join(" AND ") +
+      ")",
+  );
+  const sql =
+    `SELECT * FROM ${tableSql(labelOf(ref))} WHERE ${terms.join(" OR ")}` +
+    (limit ? ` LIMIT ${limit}` : "");
+  return (yield io.run(sql, params)).rows;
+}
+
+function* readByPk(io, ref, pk, pkObjs) {
+  return yield* readWhere(io, ref, pk, pkObjs, 0);
+}
+
+// ---- reading the statement ----
+
+let template = null;
+function selectTemplate() {
+  if (template) return template;
+  const a = S.parseOne(
+    'SELECT * FROM "botversion_t" LIMIT ' + (store.ROW_LIMIT + 1),
+  );
+  if (!a || a.type !== "select") return null;
+  template = a;
+  return a;
+}
+
+function tableRef(stmt) {
+  const src = stmt.type === "delete" ? stmt.from : stmt.table;
+  const t = Array.isArray(src) ? src : src ? [src] : [];
+  if (t.length !== 1 || !t[0] || typeof t[0].table !== "string")
+    throw new Skip("this statement shape cannot be saved");
+  return { db: t[0].db || null, table: t[0].table, as: t[0].as || null };
+}
+
+// SQL that reads the rows an UPDATE / DELETE will touch (same WHERE / ORDER BY / LIMIT). Reading too many rows is safe, too few is not.
+function readSql(stmt, ref) {
+  const t = selectTemplate();
+  if (!t) throw new Skip("statement reader not available");
+  const sel = JSON.parse(JSON.stringify(t));
+  sel.from = [{ db: ref.db, table: ref.table, as: ref.as }];
+  sel.where = stmt.where || null;
+  if (stmt.orderby) sel.orderby = stmt.orderby;
+  if (stmt.limit) {
+    const v = stmt.limit.value;
+    if (
+      !Array.isArray(v) ||
+      v.length !== 1 ||
+      typeof v[0].value !== "number" ||
+      v[0].value > store.ROW_LIMIT
+    )
+      throw new Skip("too-many-rows");
+    sel.limit.value[0].value = v[0].value;
+  }
+  return S.sqlify(sel);
+}
+
+// Decides what to do with one statement. Returns
+//   { action: "pass" }                                  not a write: leave it alone
+//   { action: "refuse", table, why }                    a write that cannot be saved
+//   { action: "capture", stmt, ref, kind, name }        a write that can be saved
+function analyse(text, binds) {
+  const PASS = { action: "pass" };
+  const sc = S.scan(text);
+  const withWrite = sc.first === "WITH" && WRITE_IN_WITH.test(sc.masked);
+  const writeish = WRITE_WORDS.has(sc.first) || withWrite;
+  const refuse = (table, why) => ({ action: "refuse", table, why });
+  if (!S.hasParser())
+    return writeish ? refuse("?", "the SQL reader is not installed") : PASS;
+
+  let sql;
+  try {
+    sql = S.inlineParams(text, sc, binds);
+  } catch (e) {
+    return writeish
+      ? refuse(
+          "?",
+          e instanceof Skip ? e.message : "statement values could not be read",
+        )
+      : PASS;
+  }
+  if (withWrite) return refuse("?", "a write inside WITH cannot be saved");
+  if (/^\s*(INSERT|UPDATE)\s+OR\b/i.test(sc.masked))
+    return refuse("?", "or-conflict cannot be saved");
+
+  const c = S.classify(sql);
+  if (c.parseFailed)
+    return writeish ? refuse("?", "statement could not be read") : PASS;
+  if (c.writes.length === 0) return PASS; // a read
+  const tbl = c.writes[0].tables.filter(Boolean)[0] || "?";
+  if (store.isOwnTable(tbl)) return PASS;
+  if (c.multi || c.writes.length !== 1)
+    return refuse(tbl, "several writes in one statement");
+  const w = c.writes[0];
+  if (w.kind !== "update" && w.kind !== "insert" && w.kind !== "delete")
+    return refuse(tbl, w.kind + " cannot be saved");
+  const bad = w.notes.find((n) => BAD_NOTES.includes(n));
+  if (bad) return refuse(tbl, bad + " cannot be saved");
+  const stmt = S.parseOne(sql);
+  if (!stmt || stmt.type !== w.kind)
+    return refuse(tbl, "this statement shape cannot be saved");
+  if (stmt.type === "update" && stmt.from)
+    return refuse(tbl, "this statement shape cannot be saved");
+  let ref;
+  try {
+    ref = tableRef(stmt);
+  } catch (_) {
+    return refuse(tbl, "this statement shape cannot be saved");
+  }
+  return { action: "capture", stmt, ref, kind: w.kind, name: labelOf(ref) };
+}
+
+// ---- UPDATE ----
+
+function* beforeUpdate(io, job, info, notSaved) {
+  const { stmt, ref, st } = job;
+  const rows = (yield io.run(readSql(stmt, ref), [])).rows;
+  const c = store.checkCapturable({
+    rowCount: rows.length,
+    primaryKeyColumns: info.pk,
+  });
+  if (!c.ok) {
+    notSaved(c.reason);
+    return null;
+  }
+  const saved = [];
+  for (const row of rows) {
+    const r = yield* ss.saveSnapshot(
+      io,
+      st,
+      {
+        table: labelOf(ref),
+        operation: "update",
+        primaryKey: pickPk(row, info.pk),
+        before: row,
+        after: null,
+        isLinked: false,
+      },
+      io.inTx,
+    );
+    if (!r.ok) {
+      notSaved(r.reason);
+      break;
+    }
+    saved.push({
+      id: r.id,
+      key: keyOf(row, info.pk),
+      pkObj: pickPk(row, info.pk),
+    });
+  }
+  return { saved };
+}
+
+function* afterUpdate(io, job, info, before) {
+  const { ref, st } = job;
+  const rows = yield* readByPk(
+    io,
+    ref,
+    info.pk,
+    before.saved.map((s) => s.pkObj),
+  );
+  const byKey = new Map(before.saved.map((s) => [s.key, s]));
+  let n = 0;
+  for (const row of rows) {
+    const s = byKey.get(keyOf(row, info.pk));
+    if (!s) continue;
+    const r = yield* ss.saveAfter(io, s.id, row, io.inTx);
+    if (r.ok) n++;
+  }
+}
+
+// ---- DELETE ----
+
+// Foreign keys that point AT a table: one entry per key (a key can use several columns).
+function* readLinks(io, schemaName, parent) {
+  const sch = q(schemaName);
+  const tables = (yield io.run(
+    `SELECT name FROM ${sch}.sqlite_master WHERE type = 'table'`,
+    [],
+  )).rows;
+  const out = [];
+  for (const t of tables) {
+    const fk = (yield io.run(
+      `PRAGMA ${sch}.foreign_key_list(${q(t.name)})`,
+      [],
+    )).rows;
+    const byId = new Map();
+    for (const r of fk) {
+      if (String(r.table).toLowerCase() !== parent.name.toLowerCase()) continue;
+      if (!byId.has(r.id))
+        byId.set(r.id, {
+          childTable: t.name,
+          rule: String(r.on_delete || "").toUpperCase(),
+          pairs: [],
+        });
+      byId.get(r.id).pairs.push({ seq: Number(r.seq), from: r.from, to: r.to });
+    }
+    for (const l of byId.values()) {
+      l.pairs.sort((a, b) => a.seq - b.seq);
+      l.childCols = l.pairs.map((p) => p.from);
+      l.parentCols = l.pairs.map((p, i) => p.to || parent.pk[i]); // no target written = the parent's primary key
+      if (l.parentCols.some((c) => !c))
+        throw new Skip("foreign-key target columns could not be read");
+      out.push(l);
+    }
+  }
+  return out;
+}
+
+// Works out every row a DELETE will remove or change (through foreign keys). Saves nothing. Throws Skip when unsafe.
+function* planDelete(io, job, info) {
+  const { stmt, ref } = job;
+  const rootSchema = ref.db || "main";
+  let c = store.checkCapturable({ rowCount: 0, primaryKeyColumns: info.pk });
+  if (!c.ok) throw new Skip(c.reason);
+
+  // 1. The rows the host is deleting.
+  const rootRows = (yield io.run(readSql(stmt, ref), [])).rows;
+  c = store.checkCapturable({
+    rowCount: rootRows.length,
+    primaryKeyColumns: info.pk,
+  });
+  if (!c.ok) throw new Skip(c.reason);
+
+  // 2. Rows reached through foreign keys, level by level. SQLite follows foreign keys only when they are switched on.
+  //    kind "delete" = removed by the database (CASCADE); kind "update" = link cleared (SET NULL / SET DEFAULT).
+  const rootTable = { db: ref.db, table: ref.table };
+  const groups = [
+    { table: rootTable, pk: info.pk, rows: rootRows, depth: 0, kind: "delete" },
+  ];
+  const deletedAt = new Map();
+  const cleared = new Set();
+  for (const r of rootRows) deletedAt.set(tagOf(ref.table, r, info.pk), 0);
+  let fkOn = false;
+  if (rootRows.length) {
+    const f = (yield io.run("PRAGMA foreign_keys", [])).rows;
+    fkOn = !!(f[0] && Number(f[0].foreign_keys) === 1);
+  }
+  let frontier = rootRows.length && fkOn ? [groups[0]] : [];
+  let total = rootRows.length;
+  for (let depth = 1; frontier.length; depth++) {
+    const next = [];
+    for (const parent of frontier) {
+      const links = yield* readLinks(io, rootSchema, {
+        name: parent.table.table,
+        pk: parent.pk,
+      });
+      for (const link of links) {
+        const cascades = link.rule === "CASCADE";
+        if (
+          !cascades &&
+          link.rule !== "SET NULL" &&
+          link.rule !== "SET DEFAULT"
+        )
+          continue; // RESTRICT / NO ACTION: the database refuses the delete itself
+        const childRef = { db: ref.db, table: link.childTable };
+        const parentVals = parent.rows.map((r) => {
+          const o = {};
+          link.parentCols.forEach((pc, i) => {
+            o[link.childCols[i]] = r[pc];
+          });
+          return o;
+        });
+        const found = yield* readWhere(
+          io,
+          childRef,
+          link.childCols,
+          parentVals,
+          store.ROW_LIMIT + 1,
+        );
+        if (!found.length) continue;
+        if (depth > MAX_DEPTH) throw new Skip("links go too deep");
+        const childInfo = yield* tableInfo(io, childRef);
+        if (childInfo.generated)
+          throw new Skip("tables with generated columns cannot be saved");
+        const cc = store.checkCapturable({
+          rowCount: found.length,
+          primaryKeyColumns: childInfo.pk,
+        });
+        if (!cc.ok) throw new Skip(cc.reason);
+        const fresh = [];
+        for (const r of found) {
+          const k = tagOf(link.childTable, r, childInfo.pk);
+          if (cascades) {
+            if (deletedAt.has(k)) {
+              // Same row reached at another level would be restored in the wrong order: do not guess.
+              if (deletedAt.get(k) !== depth)
+                throw new Skip(
+                  "a row is reached through links of different depth",
+                );
+              continue;
+            }
+            deletedAt.set(k, depth);
+          } else {
+            if (cleared.has(k)) continue;
+            cleared.add(k);
+          }
+          fresh.push(r);
+        }
+        total += fresh.length;
+        if (total > store.ROW_LIMIT) throw new Skip("too-many-rows");
+        if (!fresh.length) continue;
+        const grp = {
+          table: childRef,
+          pk: childInfo.pk,
+          rows: fresh,
+          depth,
+          kind: cascades ? "delete" : "update",
+        };
+        groups.push(grp);
+        if (cascades) next.push(grp);
+      }
+    }
+    frontier = next;
+  }
+  // A row that is deleted does not also need its link cleared.
+  for (const g of groups) {
+    if (g.kind === "update")
+      g.rows = g.rows.filter(
+        (r) => !deletedAt.has(tagOf(g.table.table, r, g.pk)),
+      );
+  }
+  return groups.filter((g) => g.rows.length);
+}
+
+// Saves the rows a DELETE will remove or change. Deepest rows first, deleted rows last (Undo goes last to first).
+function* beforeDelete(io, job, info, notSaved) {
+  const { st } = job;
+  let groups;
+  try {
+    groups = yield* planDelete(io, job, info);
+  } catch (e) {
+    if (e instanceof Skip) {
+      notSaved(e.message);
+      return null;
+    }
+    throw e;
+  }
+  const ordered = groups.slice().sort((a, b) => b.depth - a.depth);
+  const saved = [];
+  const fills = [];
+  for (const g of ordered) {
+    const ids = new Map();
+    for (const row of g.rows) {
+      const r = yield* ss.saveSnapshot(
+        io,
+        st,
+        {
+          table: labelOf(g.table),
+          operation: g.kind,
+          primaryKey: pickPk(row, g.pk),
+          before: row,
+          after: null,
+          isLinked: g.depth > 0,
+        },
+        io.inTx,
+      );
+      if (!r.ok) {
+        // Do not keep a half-saved set: it could restore only part of the data.
+        yield* ss.deleteByIds(
+          io,
+          io.inTx,
+          saved.map((s) => s.id),
+        );
+        notSaved(r.reason);
+        return null;
+      }
+      saved.push({ id: r.id });
+      ids.set(keyOf(row, g.pk), r.id);
+    }
+    if (g.kind === "update") fills.push({ g, ids });
+  }
+  return { saved, fills };
+}
+
+// Rows whose link was cleared: save how they look now (needed for the safety check in Undo).
+function* afterDelete(io, job, before) {
+  const { st, ref } = job;
+  for (const { g, ids } of before.fills) {
+    const rows = yield* readByPk(
+      io,
+      g.table,
+      g.pk,
+      g.rows.map((r) => pickPk(r, g.pk)),
+    );
+    for (const row of rows) {
+      const id = ids.get(keyOf(row, g.pk));
+      if (!id) continue;
+      yield* ss.saveAfter(io, id, row, io.inTx);
+    }
+  }
+}
+
+// ---- INSERT ----
+
+function colName(c) {
+  if (typeof c === "string") return c;
+  if (c && typeof c.column === "string") return c.column;
+  if (c && c.column && c.column.expr && typeof c.column.expr.value === "string")
+    return c.column.expr.value;
+  return null;
+}
+
+// Only plain numbers and plain text are accepted as a key written in the statement itself.
+function literalOf(e) {
+  if (
+    e &&
+    e.type === "number" &&
+    typeof e.value === "number" &&
+    Number.isSafeInteger(e.value)
+  )
+    return e.value;
+  if (
+    e &&
+    typeof e.type === "string" &&
+    /string/.test(e.type) &&
+    typeof e.value === "string" &&
+    !e.value.includes("\\") &&
+    !e.value.includes("'")
+  )
+    return e.value;
+  throw new Skip("the new row key is not a plain value in the statement");
+}
+
+// Decides BEFORE the insert runs whether its new row can be found again afterwards. Throws Skip when not.
+function planInsert(stmt, info) {
+  if (!info.pk.length) throw new Skip("no-primary-key");
+  let cols = Array.isArray(stmt.columns) ? stmt.columns.map(colName) : null;
+  if (!cols || !cols.length) cols = info.cols.slice(); // no column list: the table's own column order
+  if (cols.some((c) => !c)) throw new Skip("this insert shape cannot be saved");
+  const v = stmt.values;
+  const rows = Array.isArray(v)
+    ? v
+    : v && Array.isArray(v.values)
+      ? v.values
+      : null;
+  if (!rows || rows.length !== 1)
+    throw new Skip("only single-row inserts can be saved");
+  const exprs = rows[0] && Array.isArray(rows[0].value) ? rows[0].value : null;
+  if (!exprs || exprs.length !== cols.length)
+    throw new Skip("this insert shape cannot be saved");
+  const lower = cols.map((c) => c.toLowerCase());
+  const idx = info.pk.map((c) => lower.indexOf(c.toLowerCase()));
+  if (idx.every((i) => i === -1)) {
+    if (info.auto) return { mode: "auto" };
+    throw new Skip(
+      "new row key is not an automatic INTEGER PRIMARY KEY and not in the insert",
+    );
+  }
+  if (idx.some((i) => i === -1))
+    throw new Skip("part of the primary key is not in the insert");
+  if (info.auto && exprs[idx[0]] && exprs[idx[0]].type === "null")
+    return { mode: "auto" }; // NULL = "give me the next number"
+  const key = {};
+  info.pk.forEach((c, n) => {
+    key[c] = literalOf(exprs[idx[n]]);
+  });
+  return { mode: "explicit", key };
+}
+
+function* afterInsert(io, job, info, plan, r, notSaved) {
+  const { ref, st } = job;
+  if (r.changes === 0) {
+    return;
+  }
+  if (r.changes !== undefined && r.changes !== 1)
+    return notSaved("unexpected row count");
+  let keyObj = plan.key;
+  if (plan.mode === "auto") {
+    if (!r.insertId) return notSaved("new row id not returned by the database");
+    keyObj = { [info.pk[0]]: r.insertId };
+  }
+  const full = yield* readByPk(io, ref, info.pk, [keyObj]);
+  if (!full.length) return notSaved("new row could not be read back");
+  const s = yield* ss.saveSnapshot(
+    io,
+    st,
+    {
+      table: labelOf(ref),
+      operation: "insert",
+      primaryKey: pickPk(full[0], info.pk),
+      before: null,
+      after: full[0],
+      isLinked: false,
+    },
+    io.inTx,
+  );
+  if (!s.ok) return notSaved(s.reason);
+}
+
+// ---- the whole job for one tagged write ----
+// io = { key, inTx, run(sql, params), execHost() -> { err, res, insertId, changes }, block(st, where, why) }
+function* runCapture(io, job) {
+  const { stmt, ref, kind, st } = job;
+  const inTx = io.inTx;
+  const name = labelOf(ref);
+  let phase = "before"; // "before" = the write has not run yet, so it can still be blocked
+  let failedWhy = null;
+  const notSaved = (why) => {
+    if (phase === "before") failedWhy = failedWhy || why;
+    if (phase !== "before" || st.confirmed) st.unsaved = true; // the write runs (or already ran) without a saved snapshot
+  };
+
+  let info = null;
+  let before = null;
+  let plan = null;
+  try {
+    info = yield* tableInfo(io, ref);
+    const c = store.checkCapturable({
+      rowCount: 0,
+      primaryKeyColumns: info.pk,
+    });
+    if (!c.ok) notSaved(c.reason);
+    else if (info.generated)
+      notSaved("tables with generated columns cannot be saved");
+    else if (kind === "update")
+      before = yield* beforeUpdate(io, job, info, notSaved);
+    else if (kind === "delete")
+      before = yield* beforeDelete(io, job, info, notSaved);
+    else plan = planInsert(stmt, info);
+  } catch (e) {
+    notSaved(
+      e instanceof Skip
+        ? e.message
+        : "capture error " + ((e && e.code) || "unknown"),
+    );
+  }
+
+  // Cannot be saved: remove what was saved so far (a half-saved set could restore only part of the data), then block unless confirmed.
+  if (failedWhy) {
+    yield* ss.deleteByIds(
+      io,
+      inTx,
+      before && before.saved ? before.saved.map((s) => s.id) : [],
+    );
+    before = null;
+    plan = null;
+    if (!st.confirmed) yield io.block(st, name, failedWhy);
+  }
+
+  phase = "after";
+  const r = yield io.execHost();
+  if (r.err) {
+    // The host's write failed: remove the snapshots saved for it (inside a transaction they roll back by themselves).
+    if (!inTx && before && before.saved && before.saved.length)
+      yield* ss.deleteByIds(
+        io,
+        inTx,
+        before.saved.map((s) => s.id),
+      );
+    return r;
+  }
+  try {
+    if (kind === "update" && before && before.saved.length)
+      yield* afterUpdate(io, job, info, before);
+    if (kind === "delete" && before && before.saved.length)
+      yield* afterDelete(io, job, before);
+    if (kind === "insert" && plan)
+      yield* afterInsert(io, job, info, plan, r, notSaved);
+  } catch (e) {
+    notSaved("capture error " + ((e && e.code) || "unknown"));
+  }
+  return r;
+}
+
+// ---- hook entry points ----
+
+function noteWrite(st, a, method) {
+  st.writes++;
+}
+
+function noteStop(st, table, why) {
+  if (st.confirmed) st.unsaved = true; // runs without a saved snapshot, so Undo will not cover it
+}
+
+// better-sqlite3: run / get / all of a prepared statement. Returns { value } when capture took over, otherwise null.
+// ctx = { opsFor(db), boundOf(statement) }
+function captureBetter(self, method, args, original, ctx) {
+  const st = tagger.getCurrent();
+  if (!st || guard.isUnhooked() || !S.hasParser()) return null;
+  let a;
+  let db;
+  try {
+    const text = self.source;
+    if (typeof text !== "string") return null;
+    const given = args.length
+      ? Array.prototype.slice.call(args)
+      : ctx.boundOf(self) || [];
+    a = analyse(text, S.collectBinds(given));
+    db = self.database;
+  } catch (_) {
+    return null;
+  }
+  if (a.action === "pass") return null;
+  noteWrite(st, a, method);
+
+  const stop = (table, why) => {
+    noteStop(st, table, why);
+    if (st.confirmed) return null;
+    return gate.blockSync(st, table, why); // always throws
+  };
+  if (a.action === "refuse") return stop(a.table, a.why);
+
+  let io;
+  let outcome = null;
+  try {
+    if (!db || typeof db.prepare !== "function")
+      return stop(a.name, "database object not reachable");
+    const ops = ctx.opsFor(db);
+    io = {
+      key: db,
+      inTx: !!db.inTransaction,
+      run: (sql, params) => ops.query(sql, params),
+      block: (s, w, y) => gate.blockSync(s, w, y),
+      execHost: () => {
+        let res;
+        let err;
+        try {
+          res = original.apply(self, args);
+        } catch (e) {
+          err = e;
+        }
+        outcome = { err, res };
+        if (err) return outcome;
+        const r = { err: undefined, res };
+        if (
+          res &&
+          typeof res === "object" &&
+          !Array.isArray(res) &&
+          "lastInsertRowid" in res
+        ) {
+          r.insertId = res.lastInsertRowid;
+          r.changes = res.changes;
+        } else {
+          r.changes = Array.isArray(res)
+            ? res.length
+            : res === undefined
+              ? 0
+              : 1;
+          if (a.kind === "insert") {
+            try {
+              r.insertId = ops.query(
+                "SELECT last_insert_rowid() AS id",
+                [],
+              ).rows[0].id;
+            } catch (_) {
+              /* the key is then reported as not returned */
+            }
+          }
+        }
+        return r;
+      },
+    };
+  } catch (e) {
+    if (e instanceof gate.Blocked) throw e;
+    return null;
+  }
+
+  let r;
+  try {
+    r = S.driveSync(
+      runCapture(io, { stmt: a.stmt, ref: a.ref, kind: a.kind, st }),
+    );
+  } catch (e) {
+    if (e instanceof gate.Blocked) throw e;
+    // A problem of ours: if the host's write already ran, hand back its own answer; otherwise let the host run it normally.
+    if (outcome) {
+      if (outcome.err) throw outcome.err;
+      return { value: outcome.res };
+    }
+    return null;
+  }
+  if (r.err) throw r.err;
+  return { value: r.res };
+}
+
+// better-sqlite3: exec() / iterate(): writes that go this way cannot be saved, so they are blocked until the user confirms.
+function refuseWriteBetter(self, label, text, binds, ctx) {
+  const st = tagger.getCurrent();
+  if (!st || guard.isUnhooked() || !S.hasParser()) return;
+  let a;
+  try {
+    if (typeof text !== "string") return;
+    a = analyse(text, S.collectBinds(binds));
+  } catch (_) {
+    return;
+  }
+  if (a.action === "pass") return;
+  noteWrite(st, a, label);
+  const table = a.action === "refuse" ? a.table : a.name;
+  const why = a.action === "refuse" ? a.why : label + " cannot be saved";
+  noteStop(st, table, why);
+  if (st.confirmed) return;
+  gate.blockSync(st, table, why);
+}
+
+// sqlite3: a call on a Database or a prepared Statement.
+// c = { target, db, method, sql, offset, args, original, ops, preBound, getTx }
+// Returns { value } when capture took over (it runs the host's call itself, or blocks it), otherwise null.
+function captureNode(c) {
+  const st = tagger.getCurrent();
+  if (!st || guard.isUnhooked() || !S.hasParser()) return null;
+  let a;
+  let cb = null;
+  let cbIdx = -1;
+  try {
+    const rest = c.args.slice(c.offset);
+    if (rest.length && typeof rest[rest.length - 1] === "function") {
+      cbIdx = c.offset + rest.length - 1;
+      cb = c.args[cbIdx];
+    }
+    let binds = cbIdx >= 0 ? rest.slice(0, -1) : rest;
+    if (!binds.length && c.preBound) binds = c.preBound;
+    a = analyse(c.sql, S.collectBinds(binds));
+  } catch (_) {
+    return null;
+  }
+  if (a.action === "pass") return null;
+  noteWrite(st, a, c.method);
+
+  const fail = (e) => {
+    if (cb) process.nextTick(cb, e);
+    else if (typeof c.target.emit === "function")
+      process.nextTick(() => c.target.emit("error", e));
+  };
+  const stop = (table, why) => {
+    noteStop(st, table, why);
+    if (st.confirmed) return null;
+    gate.block(st, table, why).then(null, fail);
+    return { value: c.target };
+  };
+  if (a.action === "refuse") return stop(a.table, a.why);
+  if (c.method !== "run" && c.method !== "all" && c.method !== "get")
+    return stop(a.name, "this way of calling sqlite3 cannot be saved");
+
+  let outcome = null;
+  const hostArgs = c.args.slice();
+  const io = {
+    key: c.db,
+    inTx: !!c.getTx(),
+    run: (sql, params) => c.ops.query(sql, params),
+    block: (s, w, y) => gate.block(s, w, y),
+    execHost: () =>
+      new Promise((resolve) => {
+        const done = function (err, res) {
+          // sqlite3 reports lastID / changes on "this" of the callback (only for run)
+          const r = {
+            err,
+            res,
+            ctx: this,
+            insertId: this && this.lastID,
+            changes: this && this.changes,
+          };
+          outcome = r;
+          resolve(r);
+        };
+        if (cbIdx >= 0) hostArgs[cbIdx] = done;
+        else hostArgs.push(done);
+        try {
+          guard.runUnhooked(() => c.original.apply(c.target, hostArgs));
+        } catch (e) {
+          done.call(undefined, e);
+        }
+      }),
+  };
+
+  const settle = (r) => {
+    if (cb)
+      process.nextTick(() =>
+        cb.apply(r.ctx || c.target, r.err ? [r.err] : [null, r.res]),
+      );
+    else if (r.err) fail(r.err);
+  };
+  S.driveAsync(
+    runCapture(io, { stmt: a.stmt, ref: a.ref, kind: a.kind, st }),
+  ).then(settle, (e) => {
+    if (e instanceof gate.Blocked) return fail(e);
+    if (outcome) return settle(outcome);
+    // A problem of ours before the host's call ran: run it as if we were not here.
+    try {
+      guard.runUnhooked(() => c.original.apply(c.target, c.args));
+    } catch (e2) {
+      fail(e2);
+    }
+  });
+  return { value: c.target };
+}
+
+// sqlite3: exec() / each(): writes that go this way cannot be saved, so they are blocked until the user confirms.
+function refuseWriteNode(c) {
+  const st = tagger.getCurrent();
+  if (!st || guard.isUnhooked() || !S.hasParser()) return null;
+  let a;
+  let cb = null;
+  try {
+    const rest = c.args.slice(c.offset);
+    const firstFn = rest.findIndex((x) => typeof x === "function");
+    cb =
+      rest.length && typeof rest[rest.length - 1] === "function"
+        ? rest[rest.length - 1]
+        : null;
+    const binds = firstFn >= 0 ? rest.slice(0, firstFn) : rest;
+    a = analyse(c.sql, S.collectBinds(binds));
+  } catch (_) {
+    return null;
+  }
+  if (a.action === "pass") return null;
+  noteWrite(st, a, c.method);
+  const table = a.action === "refuse" ? a.table : a.name;
+  const why = a.action === "refuse" ? a.why : c.method + " cannot be saved";
+  noteStop(st, table, why);
+  if (st.confirmed) return null;
+  const fail = (e) => {
+    if (cb) process.nextTick(cb, e);
+    else if (typeof c.target.emit === "function")
+      process.nextTick(() => c.target.emit("error", e));
+  };
+  gate.block(st, table, why).then(null, fail);
+  return { value: c.target };
+}
+
+module.exports = {
+  analyse,
+  runCapture,
+  captureBetter,
+  refuseWriteBetter,
+  captureNode,
+  refuseWriteNode,
+};