botversion-sdk 2.2.3 → 2.3.0

package/undo/lib/capture-mssql.js

@@ -0,0 +1,901 @@
+// lib/capture-mssql.js
+"use strict";
+// SQL SERVER CAPTURE (Phase 6): saves before/after rows of tagged UPDATE, INSERT and DELETE statements on the host's own connection.
+// DELETE also saves the rows the database removes or changes through foreign keys.
+// Works on the "tedious" driver (the mssql package, Knex and Sequelize all run on it).
+// tedious runs one request at a time per connection, so the host's request is held back, our reads run first, then the host's
+// request runs, then our after-reads run, and only then is the host told its request finished.
+// Never throws into the host. Logs: table names, counts and reasons only.
+
+const log = require("./log");
+const tagger = require("./tagger");
+const store = require("./snapshot-store");
+const guard = require("./capture-guard");
+const gate = require("./gate");
+const { makeRun } = require("./mssql-run");
+const { classifyMssql, stripOutputClause } = require("./sql-classify-mssql");
+
+const DIALECT = "sqlserver";
+const OPTS = { database: "TransactSQL" };
+
+// Statements that start with one of these words are writes (or may hide one), even when the parser cannot read them.
+const WRITE_WORDS = new Set([
+  "INSERT",
+  "UPDATE",
+  "DELETE",
+  "MERGE",
+  "TRUNCATE",
+  "DROP",
+  "ALTER",
+  "EXEC",
+  "EXECUTE",
+  "BULK",
+  "WITH",
+  "WRITETEXT",
+  "UPDATETEXT",
+]);
+
+let parser = null;
+try {
+  const { Parser } = require("node-sql-parser");
+  parser = new Parser();
+} catch (_) {
+  /* parser missing: nothing is capturable */
+}
+
+class Skip extends Error {}
+
+const mask = (s) =>
+  String(s)
+    .replace(/'(?:[^']|'')*'/g, "'?'")
+    .slice(0, 300);
+
+const txState = new WeakMap(); // connection -> did the host's own statements open a transaction?
+const pkCache = new Map();
+let template = null;
+
+const q = (s) => "[" + String(s).replace(/\]/g, "]]") + "]";
+const parts = (t) => [t.schema, t.table].filter(Boolean);
+const tableSql = (t) => parts(t).map(q).join(".");
+const labelOf = (t) => parts(t).join(".");
+const keyOf = (row, cols) =>
+  cols
+    .map((c) => {
+      const v = row[c];
+      if (v instanceof Date) return v.toISOString();
+      if (Buffer.isBuffer(v)) return v.toString("hex");
+      return String(v);
+    })
+    .join("\u0001");
+const pickPk = (row, cols) => {
+  const o = {};
+  for (const c of cols) o[c] = row[c];
+  return o;
+};
+
+// Primary key columns of a table, and whether it is a single IDENTITY column.
+const PK_SQL =
+  "SELECT c.name AS name, c.is_identity AS is_identity FROM sys.indexes i " +
+  "JOIN sys.index_columns ic ON ic.object_id = i.object_id AND ic.index_id = i.index_id " +
+  "JOIN sys.columns c ON c.object_id = ic.object_id AND c.column_id = ic.column_id " +
+  "WHERE i.is_primary_key = 1 AND i.object_id = OBJECT_ID(@P1) ORDER BY ic.key_ordinal";
+
+// Is the host inside a transaction on this connection? tedious knows; the text tracking is a second opinion.
+function inTransactionOf(conn) {
+  return conn.inTransaction === true || txState.get(conn) === true;
+}
+
+function trackTransaction(conn, text) {
+  if (/^\s*BEGIN\s+TRAN/i.test(text)) txState.set(conn, true);
+  else if (
+    /^\s*(COMMIT|ROLLBACK)\b/i.test(text) &&
+    !/^\s*ROLLBACK\s+TRAN(SACTION)?\s+\w/i.test(text)
+  )
+    txState.set(conn, false);
+}
+
+function parseOne(sql) {
+  if (!parser) return null;
+  try {
+    const a = parser.astify(stripOutputClause(sql), OPTS);
+    const list = Array.isArray(a) ? a : [a];
+    return list.length === 1 ? list[0] : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+// A SELECT built from a parsed template, so the shape always matches the installed parser version.
+function selectTemplate() {
+  if (template) return template;
+  const a = parseOne(
+    "SELECT TOP " + (store.ROW_LIMIT + 1) + " * FROM botversion_t",
+  );
+  if (!a || a.type !== "select") return null;
+  template = a;
+  return a;
+}
+
+function tableRef(stmt) {
+  // An UPDATE / INSERT keeps its table in `table`; a DELETE keeps it in `from`.
+  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");
+  // The parser copies the FROM table into `table` (tagged addition); only a different entry means a multi-table delete.
+  if (
+    stmt.type === "delete" &&
+    Array.isArray(stmt.table) &&
+    stmt.table.some(
+      (x) =>
+        !(x && x.addition === true && t.some((f) => f && f.table === x.table)),
+    )
+  )
+    throw new Skip("multi-table delete cannot be saved");
+  if (stmt.type === "update" && Array.isArray(stmt.from) && stmt.from.length)
+    throw new Skip("update with a FROM clause cannot be saved");
+  if (stmt.top || stmt.limit) throw new Skip("TOP cannot be saved");
+  const n = t[0];
+  // The parser keeps the schema name in `db`. A name with a database part is not read from this database's catalog.
+  if (n.schema || n.catalog || (typeof n.db === "string" && n.db.includes(".")))
+    throw new Skip("a table in another database cannot be saved");
+  return { schema: n.db || null, table: n.table, node: n };
+}
+
+// SQL that reads the rows an UPDATE / DELETE will touch (same WHERE). Reading too many rows is safe, too few is not.
+// The host's own parameters (@name) are sent along with it.
+function readSql(stmt, ref, hostParams) {
+  const t = selectTemplate();
+  if (!t) throw new Skip("statement reader not available");
+  const sel = JSON.parse(JSON.stringify(t));
+  sel.from = [JSON.parse(JSON.stringify(ref.node))];
+  sel.where = stmt.where || null;
+  // The parser writes a @parameter back out as a quoted column name ([@p3]); put it back as a parameter. Text inside quotes is left alone.
+  const sql = parser
+    .sqlify(sel, OPTS)
+    .replace(/'(?:[^']|'')*'|\[(@[A-Za-z_][A-Za-z0-9_]*)\]/g, (m, name) =>
+      name ? name : m,
+    );
+  // Every @name in the generated SQL must be one of the host's parameters, otherwise the read could be wrong.
+  const known = new Set(hostParams.map((p) => String(p.name).toLowerCase()));
+  for (const m of sql.match(/@[A-Za-z_][A-Za-z0-9_]*/g) || [])
+    if (!known.has(m.slice(1).toLowerCase()))
+      throw new Skip("statement values cannot be read");
+  return sql;
+}
+
+async function primaryKeyOf(conn, run, ref, inTx) {
+  const key =
+    ((conn.config && conn.config.options && conn.config.options.database) ||
+      "") +
+    "|" +
+    labelOf(ref);
+  if (pkCache.has(key)) return pkCache.get(key);
+  const res = await store.guarded(run, inTx, () =>
+    run(PK_SQL, [tableSql(ref)]),
+  );
+  const cols = res.rows.map((r) => r.name);
+  const auto =
+    cols.length === 1 &&
+    (res.rows[0].is_identity === true || res.rows[0].is_identity === 1);
+  const info = { cols, auto };
+  if (cols.length) pkCache.set(key, info);
+  return info;
+}
+
+// Rows whose key columns match any of the given value sets. SQL Server has no (a, b) IN (...) form, and allows about 2100
+// parameters per statement, so the sets are sent in chunks.
+async function readMatching(run, ref, keyCols, valueSets, inTx) {
+  if (!valueSets.length) return [];
+  const per = Math.max(1, Math.floor(1800 / keyCols.length));
+  const out = [];
+  for (let i = 0; i < valueSets.length; i += per) {
+    const params = [];
+    const ors = valueSets.slice(i, i + per).map(
+      (vals) =>
+        "(" +
+        keyCols
+          .map((c, j) => {
+            params.push(vals[j]);
+            return `${q(c)} = @P${params.length}`;
+          })
+          .join(" AND ") +
+        ")",
+    );
+    const sql = `SELECT TOP ${store.ROW_LIMIT + 1} * FROM ${tableSql(ref)} WHERE ${ors.join(" OR ")}`;
+    const rows = (await store.guarded(run, inTx, () => run(sql, params))).rows;
+    for (const r of rows) out.push(r);
+  }
+  return out;
+}
+
+const pkValues = (obj, cols) => cols.map((c) => obj[c]);
+
+async function beforeUpdate(
+  run,
+  stmt,
+  ref,
+  pk,
+  st,
+  inTx,
+  notSaved,
+  hostParams,
+) {
+  let c = store.checkCapturable({ rowCount: 0, primaryKeyColumns: pk.cols });
+  if (!c.ok) {
+    notSaved(c.reason);
+    return null;
+  }
+  const sql = readSql(stmt, ref, hostParams);
+  const rows = (await store.guarded(run, inTx, () => run(sql, [], hostParams)))
+    .rows;
+  c = store.checkCapturable({
+    rowCount: rows.length,
+    primaryKeyColumns: pk.cols,
+  });
+  if (!c.ok) {
+    notSaved(c.reason);
+    return null;
+  }
+  const saved = [];
+  for (const row of rows) {
+    const r = await store.saveSnapshot(
+      run,
+      st,
+      {
+        table: labelOf(ref),
+        operation: "update",
+        primaryKey: pickPk(row, pk.cols),
+        before: row,
+        after: null,
+        isLinked: false,
+      },
+      { inTransaction: inTx, dialect: DIALECT },
+    );
+    if (!r.ok) {
+      notSaved(r.reason);
+      break;
+    }
+    saved.push({
+      id: r.id,
+      key: keyOf(row, pk.cols),
+      pkObj: pickPk(row, pk.cols),
+    });
+  }
+  return { saved };
+}
+
+async function afterUpdate(run, ref, pk, before, st, inTx) {
+  const rows = await readMatching(
+    run,
+    ref,
+    pk.cols,
+    before.saved.map((s) => pkValues(s.pkObj, pk.cols)),
+    inTx,
+  );
+  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, pk.cols));
+    if (!s) continue;
+    const r = await store.saveAfter(run, s.id, row, {
+      inTransaction: inTx,
+      dialect: DIALECT,
+    });
+    if (r.ok) n++;
+  }
+}
+
+// ---- DELETE: the rows the host deletes, plus rows the database removes or changes through foreign keys ----
+
+const MAX_DEPTH = 5; // how many levels of linked rows a delete may reach
+
+// Foreign keys that point AT a table. rule 1 = CASCADE, 2 = SET NULL, 3 = SET DEFAULT (the database changes the child rows);
+// 0 = NO ACTION (the database refuses the delete).
+const FK_SQL =
+  "SELECT fk.name AS cname, OBJECT_SCHEMA_NAME(fk.parent_object_id) AS child_schema, OBJECT_NAME(fk.parent_object_id) AS child_table, " +
+  "fk.delete_referential_action AS delete_rule, cp.name AS child_col, cr.name AS parent_col " +
+  "FROM sys.foreign_keys fk " +
+  "JOIN sys.foreign_key_columns fkc ON fkc.constraint_object_id = fk.object_id " +
+  "JOIN sys.columns cp ON cp.object_id = fkc.parent_object_id AND cp.column_id = fkc.parent_column_id " +
+  "JOIN sys.columns cr ON cr.object_id = fkc.referenced_object_id AND cr.column_id = fkc.referenced_column_id " +
+  "WHERE fk.referenced_object_id = OBJECT_ID(@P1) " +
+  "ORDER BY fk.name, fkc.constraint_column_id";
+
+// One entry per foreign key (a key can use several columns).
+async function readLinks(run, schema, table, inTx) {
+  const rows = (
+    await store.guarded(run, inTx, () =>
+      run(FK_SQL, [tableSql({ schema, table })]),
+    )
+  ).rows;
+  const byName = new Map();
+  for (const r of rows) {
+    const k = r.child_schema + "\u0002" + r.child_table + "\u0002" + r.cname;
+    if (!byName.has(k))
+      byName.set(k, {
+        childSchema: r.child_schema,
+        childTable: r.child_table,
+        rule: Number(r.delete_rule),
+        childCols: [],
+        parentCols: [],
+      });
+    const l = byName.get(k);
+    l.childCols.push(r.child_col);
+    l.parentCols.push(r.parent_col);
+  }
+  return [...byName.values()];
+}
+
+const tagOf = (schema, table, row, pk) =>
+  schema + "." + table + "\u0002" + keyOf(row, pk);
+
+// Works out every row a DELETE will remove or change (through foreign keys). Saves nothing. Throws Skip when unsafe.
+async function planDelete(conn, run, stmt, ref, rootPk, inTx, hostParams) {
+  let rootSchema = ref.schema;
+  if (!rootSchema) {
+    const cur = await store.guarded(run, inTx, () =>
+      run("SELECT OBJECT_SCHEMA_NAME(OBJECT_ID(@P1)) AS s", [tableSql(ref)]),
+    );
+    rootSchema = cur.rows[0] && cur.rows[0].s;
+  }
+  if (!rootSchema) throw new Skip("table not found");
+  let c = store.checkCapturable({
+    rowCount: 0,
+    primaryKeyColumns: rootPk.cols,
+  });
+  if (!c.ok) throw new Skip(c.reason);
+
+  // 1. The rows the host is deleting.
+  const sql = readSql(stmt, ref, hostParams);
+  const rootRows = (
+    await store.guarded(run, inTx, () => run(sql, [], hostParams))
+  ).rows;
+  c = store.checkCapturable({
+    rowCount: rootRows.length,
+    primaryKeyColumns: rootPk.cols,
+  });
+  if (!c.ok) throw new Skip(c.reason);
+
+  // 2. Rows reached through foreign keys, level by level.
+  //    kind "delete" = removed by the database (CASCADE); kind "update" = link cleared (SET NULL / SET DEFAULT).
+  const rootTable = { schema: rootSchema, table: ref.table };
+  const groups = [
+    {
+      table: rootTable,
+      schema: rootSchema,
+      pk: rootPk.cols,
+      rows: rootRows,
+      depth: 0,
+      kind: "delete",
+    },
+  ];
+  const deletedAt = new Map(); // row -> level it is deleted at
+  const cleared = new Set();
+  for (const r of rootRows)
+    deletedAt.set(tagOf(rootSchema, ref.table, r, rootPk.cols), 0);
+  let frontier = rootRows.length ? [groups[0]] : [];
+  let total = rootRows.length;
+  for (let depth = 1; frontier.length; depth++) {
+    const next = [];
+    for (const parent of frontier) {
+      const links = await readLinks(
+        run,
+        parent.schema,
+        parent.table.table,
+        inTx,
+      );
+      for (const link of links) {
+        const cascades = link.rule === 1;
+        if (!cascades && link.rule !== 2 && link.rule !== 3) continue; // NO ACTION: the database refuses the delete itself
+        const childRef = { schema: link.childSchema, table: link.childTable };
+        const found = await readMatching(
+          run,
+          childRef,
+          link.childCols,
+          parent.rows.map((r) => link.parentCols.map((col) => r[col])),
+          inTx,
+        );
+        if (!found.length) continue;
+        if (depth > MAX_DEPTH) throw new Skip("links go too deep");
+        const childPk = await primaryKeyOf(conn, run, childRef, inTx);
+        const cc = store.checkCapturable({
+          rowCount: found.length,
+          primaryKeyColumns: childPk.cols,
+        });
+        if (!cc.ok) throw new Skip(cc.reason);
+        const fresh = [];
+        for (const r of found) {
+          const k = tagOf(link.childSchema, link.childTable, r, childPk.cols);
+          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,
+          schema: link.childSchema,
+          pk: childPk.cols,
+          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.schema, g.table.table, r, g.pk)),
+      );
+  }
+  return groups.filter((g) => g.rows.length);
+}
+
+async function deleteSaved(run, inTx, ids) {
+  if (!ids.length) return;
+  try {
+    const d = store.deleteByIds(ids, DIALECT);
+    await store.guarded(run, inTx, () => run(d.sql, d.params));
+  } catch (_) {
+    /* ignore */
+  }
+}
+
+// Saves the rows a DELETE will remove or change. Deepest rows first, deleted rows last (Undo goes last to first).
+async function beforeDelete(
+  conn,
+  run,
+  stmt,
+  ref,
+  pk,
+  st,
+  inTx,
+  notSaved,
+  hostParams,
+) {
+  let groups;
+  try {
+    groups = await planDelete(conn, run, stmt, ref, pk, inTx, hostParams);
+  } 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 = await store.saveSnapshot(
+        run,
+        st,
+        {
+          table: labelOf(g.table),
+          operation: g.kind,
+          primaryKey: pickPk(row, g.pk),
+          before: row,
+          after: null,
+          isLinked: g.depth > 0,
+        },
+        { inTransaction: inTx, dialect: DIALECT },
+      );
+      if (!r.ok) {
+        // Do not keep a half-saved set: it could restore only part of the data.
+        await deleteSaved(
+          run,
+          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).
+async function afterDelete(run, before, st, inTx, name) {
+  for (const { g, ids } of before.fills) {
+    const rows = await readMatching(
+      run,
+      g.table,
+      g.pk,
+      g.rows.map((r) => pkValues(r, g.pk)),
+      inTx,
+    );
+    for (const row of rows) {
+      const id = ids.get(keyOf(row, g.pk));
+      if (!id) continue;
+      await store.saveAfter(run, id, row, {
+        inTransaction: inTx,
+        dialect: DIALECT,
+      });
+    }
+  }
+}
+
+// ---- 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;
+}
+
+// A key written in the statement itself: a plain number or string, or a @parameter holding one.
+function literalOf(e, auto, hostParams) {
+  const bad = () =>
+    new Skip("the new row key is not a plain value in the statement");
+  let v;
+  if (e && (e.type === "var" || e.type === "param")) {
+    const name = String(e.name !== undefined ? e.name : e.value)
+      .replace(/^@/, "")
+      .toLowerCase();
+    const p = hostParams.find((x) => String(x.name).toLowerCase() === name);
+    if (!p) throw bad();
+    v = p.value;
+  } else if (e && e.type === "number") v = e.value;
+  else if (e && typeof e.type === "string" && /string/.test(e.type))
+    v = e.value;
+  else throw bad();
+  if (typeof v === "number" && Number.isSafeInteger(v) && !(auto && v === 0))
+    return v;
+  if (typeof v === "string") return v;
+  throw bad();
+}
+
+// Decides BEFORE the insert runs whether its new row can be found again afterwards. Throws Skip when not.
+function planInsert(stmt, pk, hostParams) {
+  if (!pk.cols.length) throw new Skip("no-primary-key");
+  const cols = Array.isArray(stmt.columns) ? stmt.columns.map(colName) : null;
+  if (!cols || !cols.length || cols.some((c) => !c))
+    throw new Skip("insert without a column list 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 = pk.cols.map((c) => lower.indexOf(c.toLowerCase()));
+  if (idx.every((i) => i === -1)) {
+    if (pk.auto) return { mode: "auto" };
+    throw new Skip(
+      "new row key is not an identity column and not in the insert",
+    );
+  }
+  if (idx.some((i) => i === -1))
+    throw new Skip("part of the primary key is not in the insert");
+  const key = {};
+  pk.cols.forEach((c, n) => {
+    key[c] = literalOf(exprs[idx[n]], pk.auto, hostParams);
+  });
+  return { mode: "explicit", key };
+}
+
+async function afterInsert(run, ref, pk, plan, rowCount, st, inTx, notSaved) {
+  if (rowCount === 0) {
+    return;
+  }
+  let keyObj = plan.key;
+  if (plan.mode === "auto") {
+    // @@IDENTITY is per connection, and the connection is ours for this statement. IDENT_CURRENT must agree,
+    // otherwise a trigger or another session produced the number and the row cannot be identified safely.
+    const r = await store.guarded(run, inTx, () =>
+      run("SELECT @@IDENTITY AS id, IDENT_CURRENT(@P1) AS cur", [
+        tableSql(ref),
+      ]),
+    );
+    const row = r.rows[0] || {};
+    if (row.id == null || Number(row.id) !== Number(row.cur))
+      return notSaved("new row id could not be confirmed");
+    keyObj = { [pk.cols[0]]: Number(row.id) };
+  }
+  const full = await readMatching(
+    run,
+    ref,
+    pk.cols,
+    [pkValues(keyObj, pk.cols)],
+    inTx,
+  );
+  if (!full.length) return notSaved("new row could not be read back");
+  const r = await store.saveSnapshot(
+    run,
+    st,
+    {
+      table: labelOf(ref),
+      operation: "insert",
+      primaryKey: pickPk(full[0], pk.cols),
+      before: null,
+      after: full[0],
+      isLinked: false,
+    },
+    { inTransaction: inTx, dialect: DIALECT },
+  );
+  if (!r.ok) return notSaved(r.reason);
+}
+
+// The whole job for one tagged UPDATE / INSERT / DELETE. execHost() runs the host's own request and gives back its answer.
+async function runCapture(
+  conn,
+  run,
+  stmt,
+  ref,
+  kind,
+  st,
+  hostParams,
+  execHost,
+) {
+  const inTx = inTransactionOf(conn);
+  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 pk = null;
+  let before = null;
+  let plan = null;
+  try {
+    pk = await primaryKeyOf(conn, run, ref, inTx);
+    if (kind === "update")
+      before = await beforeUpdate(
+        run,
+        stmt,
+        ref,
+        pk,
+        st,
+        inTx,
+        notSaved,
+        hostParams,
+      );
+    else if (kind === "delete")
+      before = await beforeDelete(
+        conn,
+        run,
+        stmt,
+        ref,
+        pk,
+        st,
+        inTx,
+        notSaved,
+        hostParams,
+      );
+    else {
+      const c = store.checkCapturable({
+        rowCount: 0,
+        primaryKeyColumns: pk.cols,
+      });
+      if (!c.ok) notSaved(c.reason);
+      else plan = planInsert(stmt, pk, hostParams);
+    }
+  } catch (e) {
+    notSaved(
+      e instanceof Skip
+        ? e.message
+        : "capture error " + ((e && (e.code || e.number)) || "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) {
+    await deleteSaved(
+      run,
+      inTx,
+      before && before.saved ? before.saved.map((s) => s.id) : [],
+    );
+    if (!st.confirmed) await gate.block(st, name, failedWhy);
+  }
+
+  phase = "after";
+  const r = await 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)
+      await deleteSaved(
+        run,
+        inTx,
+        before.saved.map((s) => s.id),
+      );
+    return r;
+  }
+  try {
+    if (kind === "update" && before && before.saved.length)
+      await afterUpdate(run, ref, pk, before, st, inTx);
+    if (kind === "delete" && before && before.saved.length)
+      await afterDelete(run, before, st, inTx, name);
+    if (kind === "insert" && plan)
+      await afterInsert(run, ref, pk, plan, r.rowCount, st, inTx, notSaved);
+  } catch (e) {
+    notSaved("capture error " + ((e && (e.code || e.number)) || "unknown"));
+  }
+  return r;
+}
+
+// Runs `job` instead of the host's request. tedious calls request.callback when a request finishes, so that callback is held
+// back until the job is done, then the host gets its own answer (or the block error) exactly as tedious would give it.
+// job(execHost): execHost() runs the host's real request and resolves with { err, rowCount, rows }.
+function takeOver(conn, request, original, job) {
+  const hostCb = request.callback;
+  const execHost = () =>
+    new Promise((resolve) => {
+      request.callback = function (err, rowCount, rows) {
+        resolve({ err, rowCount, rows });
+      };
+      try {
+        original.call(conn, request);
+      } catch (e) {
+        resolve({ err: e });
+      }
+    });
+  const settle = (r) => {
+    request.callback = hostCb;
+    process.nextTick(() => hostCb.call(request, r.err, r.rowCount, r.rows));
+  };
+  Promise.resolve()
+    .then(() => job(execHost))
+    .then(settle, (e) => settle({ err: e }));
+}
+
+// For execSql / execSqlBatch. Returns true when capture took over (it runs the host's request itself, or blocks it).
+// copy = the loaded copy of tedious ({ exp, fns }); original = the method the host called.
+function maybeCapture(conn, request, original, copy) {
+  const st = tagger.getCurrent();
+  if (!st || guard.isUnhooked() || !parser) return false;
+  if (!request || typeof request.callback !== "function") return false;
+  const text = request.sqlTextOrProcedure;
+  if (typeof text !== "string") return false;
+  trackTransaction(conn, text);
+
+  // A write that cannot be saved: blocked until the user confirms (or runs unsaved if they already did).
+  const refuse = (table, why) => {
+    if (st.confirmed) st.unsaved = true; // runs without a saved snapshot, so Undo will not cover it
+    if (st.confirmed) return false;
+    takeOver(conn, request, original, async () => {
+      await gate.block(st, table, why);
+    });
+    return true;
+  };
+
+  const c = classifyMssql(text);
+  if (c.parseFailed)
+    return WRITE_WORDS.has(c.firstWord)
+      ? refuse("?", "statement could not be read")
+      : false;
+  if (c.writes.length === 0) {
+    // fails safe: an unreadable multi-command write must be blocked, not passed through as a read
+    const first = ((/^\s*([A-Za-z]+)/.exec(text) || [])[1] || "").toUpperCase();
+    if (c.multi && WRITE_WORDS.has(first))
+      return refuse("?", "statement could not be read");
+    return false; // a read
+  }
+  const tbl = c.writes[0].tables.filter(Boolean)[0] || "?";
+  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) =>
+    [
+      "has-subquery",
+      "insert-from-select",
+      "multi-table",
+      "merge",
+      "stored-procedure",
+    ].includes(n),
+  );
+  if (bad) return refuse(tbl, bad + " cannot be saved");
+  const stmt = parseOne(text);
+  if (!stmt || stmt.type !== w.kind)
+    return refuse(tbl, "this statement shape cannot be saved");
+  let ref;
+  try {
+    ref = tableRef(stmt);
+  } catch (e) {
+    return refuse(
+      tbl,
+      e instanceof Skip ? e.message : "this statement shape cannot be saved",
+    );
+  }
+
+  const hostParams = (
+    Array.isArray(request.parameters) ? request.parameters : []
+  ).filter((p) => p && !p.output);
+  const run = makeRun(conn, copy);
+  takeOver(conn, request, original, (execHost) =>
+    runCapture(conn, run, stmt, ref, w.kind, st, hostParams, execHost),
+  );
+  return true;
+}
+
+// For stored procedures (kind "procedure") and prepared statements (kind "prepared"): their writes cannot be saved,
+// so a tagged write is blocked until the user confirms. Returns true when it blocked the request.
+function maybeRefuse(conn, request, original, kind) {
+  const st = tagger.getCurrent();
+  if (!st || guard.isUnhooked()) return false;
+  if (!request || typeof request.callback !== "function") return false;
+  let table = "?";
+  let why;
+  if (kind === "procedure") {
+    why = "stored procedure cannot be saved";
+  } else {
+    const text = request.sqlTextOrProcedure;
+    if (typeof text !== "string" || !parser) return false;
+    const c = classifyMssql(text);
+    if (c.parseFailed) {
+      if (!WRITE_WORDS.has(c.firstWord)) return false;
+      why = "statement could not be read";
+    } else if (c.writes.length === 0) {
+      // fails safe: an unreadable multi-command write must be blocked, not passed through as a read
+      const first = (
+        (/^\s*([A-Za-z]+)/.exec(text) || [])[1] || ""
+      ).toUpperCase();
+      if (!(c.multi && WRITE_WORDS.has(first))) return false;
+      why = "statement could not be read";
+    } else {
+      table = c.writes[0].tables.filter(Boolean)[0] || "?";
+      why = "prepared statements cannot be saved";
+    }
+  }
+  if (st.confirmed) {
+    st.unsaved = true; // runs without a saved snapshot, so Undo will not cover it
+    return false;
+  }
+  takeOver(conn, request, original, async () => {
+    await gate.block(st, table, why);
+  });
+  return true;
+}
+
+// For bulk loads: always a write that cannot be saved. Returns true when it blocked the load.
+function refuseBulk(bulk) {
+  const st = tagger.getCurrent();
+  if (!st || guard.isUnhooked()) return false;
+  const table = (bulk && typeof bulk.table === "string" && bulk.table) || "?";
+  const cb = bulk && bulk.callback;
+  if (st.confirmed || typeof cb !== "function") {
+    st.unsaved = true; // a bulk load runs without a saved snapshot
+    return false;
+  }
+  Promise.resolve()
+    .then(() => gate.block(st, table, "bulk load cannot be saved"))
+    .catch((e) => process.nextTick(() => cb(e)));
+  return true;
+}
+
+module.exports = { maybeCapture, maybeRefuse, refuseBulk };