memhouse 0.18.12 → 0.20.1

package/memhouse/house/convert-v3.js

@@ -0,0 +1,742 @@
+// Legacy -> v3 conversion (docs/design/source-identity.md draft 5, §7 step 4).
+//
+// Reads the member's legacy rooms, renamed into the archive database:
+//
+//   <db>_archive.<m>_messages_pre_v3, <m>_tool_calls_pre_v3, <m>_sessions_pre_v3
+//
+// and writes the conversation layer:
+//
+//   <db>.<m>_turns, <m>_calls, <m>_sessions
+//
+// Everything runs SERVER-SIDE as INSERT … SELECT, one hash bucket of sessions at a time
+// (sized by rows and by text bytes — see bucketCount). Nothing is read into this process but
+// counts.
+//
+// THE MAPPING (each line is a decision; docs/design/source-identity-build.md lists them too)
+//
+//   harness, session_id   split from the old '<source>:<native id>'. Only when the prefix IS
+//                         the row's `source` (every shipped row, by construction); an id that
+//                         does not carry its own source keeps the whole id and harness = source,
+//                         and is counted as `unprefixed` in the report.
+//   message_id            'legacy:<origin>:<epoch>:<seq>'  — the full old key, so a converted
+//   call_id               'legacy:<origin>:<epoch>:<idx>'    row can never collide with a
+//                                                             shipped one, and an import never
+//                                                             with a ship row
+//   part_id '0' · part_ord 0 · incarnation '' · removed 0 · state '' · parent_id '' ·
+//   response_id '' · effort '' · reasoning_tokens 0 · harness_version ''
+//   ord                   the legacy seq — dense for the main conversation, a fixed block per
+//                         sub-agent; the display tie-break within equal ts
+//   rev                   0 — the lowest value there is. Every row the capture layer writes
+//                         (fgen·2^40 + upto ≥ 1) and every tombstone of a legacy key wins
+//                         against it, and a re-run of this conversion can never resurrect a
+//                         tombstoned legacy row.
+//   ts, role, model, tokens, text, folder, project, host, origin   carried as they are, but:
+//   input_tokens          for Gemini CLI, input minus cache reads (floor 0) — legacyInput().
+//                         0.18 stored Gemini's promptTokenCount, which already counts the
+//                         cached tokens it also stored as cache_read; the house split keeps
+//                         them apart, as the 0.20 normaliser does (input_includes_cache).
+//                         0.18 never stored Gemini's thought tokens: they cannot be added
+//   text_len              lengthUTF8(text), characters
+//   agent_id              extra.agent.id of the legacy message ('' = main conversation); a
+//                         call takes it, and its model, from the message it belongs to
+//   kind                  best effort from the legacy text markers — legacyKind() below, the
+//                         SQL in kindSQL() is the same rule
+//   harness_path          the harness's data folder, from the legacy session's transcript path
+//                         (pathFromPath): the part before /projects/ (Claude Code) or before
+//                         /sessions/, /archived_sessions/ (Codex); for any other harness, or a
+//                         path without that marker, the path's home plus the harness's default
+//                         folder (editors/harness-paths.js) — what the 0.20 bridge keys it by.
+//                         Not symlink-resolved: the server cannot, so a session under a
+//                         symlinked folder keeps its legacy rows undeduped.
+//   extra                 the legacy extra, as a JSON string (agent id/type/description/turn)
+//   adapter_ver           0
+//   user_id, ingested_at  PRESERVED — insert_allow_materialized_columns = 1, as migrate.js
+//
+//   sessions              rebuilt from the converted turns and calls (totals, usage per hour ×
+//                         model, tools, agents, days) plus the legacy session's metadata;
+//                         usage_basis 'per_record', rev 0
+//
+// The legacy rows are read with FINAL and restricted to the CURRENT parse (house.js
+// currentParse: every non-ship row, and ship rows of the newest epoch per session — tool
+// calls take their epoch from messages). The restored rooms are already compacted to that,
+// so the filter is a no-op there; it keeps the conversion right on a room that is not.
+//
+// RESUMABLE. The tables are the truth: per bucket, the distinct v3 keys the legacy side
+// yields are compared with the distinct `legacy:` keys already in turns/calls (counted
+// physically, tombstoned ones included). A complete bucket is skipped; an incomplete one is
+// re-inserted whole — ReplacingMergeTree collapses what was already there, and rev 0 cannot
+// beat a tombstone. Sessions are rebuilt for every bucket whose turns or calls moved, and for
+// any bucket whose sessions are incomplete.
+//
+// Transport-free (`q`, like migrate.js). Pure helpers are exported for the unit gate.
+
+const { v3Names } = require('./schema-v3');
+const { defaultFolder } = require('../../editors/harness-paths');
+
+// ── pure: the rules, in JavaScript ───────────────────────────────────────────────────
+
+const SUBAGENT_TAG = '[subagent] ';
+const MARKERS = { thinking: '[thinking] ', tool_call: '[tool-call: ', tool_result: '[tool-result: ' };
+const PLAYBOOKS_DIR = '/.claude-playbooks/';
+
+/** Harnesses whose 0.18 input_tokens counted the cache reads stored beside them. */
+const INPUT_INCLUDES_CACHE = ['gemini-cli'];
+/** A legacy row's input tokens as the house stores them: without the cache reads it also
+ * stored, for a harness in INPUT_INCLUDES_CACHE (floor 0); otherwise as stored. */
+function legacyInput(harness, input, cacheRead) {
+  const i = Number(input) || 0; const c = Number(cacheRead) || 0;
+  return INPUT_INCLUDES_CACHE.includes(harness) ? Math.max(i - c, 0) : i;
+}
+
+/** '<source>:<native>' -> { harness, session_id, prefixed }. */
+function splitLegacySessionId(id, source) {
+  const sid = String(id ?? '');
+  const src = String(source ?? '');
+  if (src && sid.startsWith(`${src}:`)) return { harness: src, session_id: sid.slice(src.length + 1), prefixed: true };
+  if (!src && sid.includes(':')) {
+    const i = sid.indexOf(':');
+    return { harness: sid.slice(0, i), session_id: sid.slice(i + 1), prefixed: true };
+  }
+  return { harness: src, session_id: sid, prefixed: false };
+}
+
+function legacyMessageId(origin, epoch, seq) { return `legacy:${origin}:${epoch}:${seq}`; }
+function legacyCallId(origin, epoch, idx) { return `legacy:${origin}:${epoch}:${idx}`; }
+
+/** The logical install a transcript path belongs to. */
+function rootFromPath(p) {
+  const s = String(p ?? '');
+  const i = s.indexOf(PLAYBOOKS_DIR);
+  if (i >= 0) return s.slice(i + PLAYBOOKS_DIR.length).split('/')[0];
+  return s ? 'default' : '';
+}
+
+// The home a transcript path lies in, and a harness's default data folder relative to it.
+const HOME_RE = '^(/Users/[^/]+|/home/[^/]+|/root)(/|$)';
+const PATH_HARNESSES = ['claude-code', 'codex', 'gemini-cli', 'opencode', 'goose', 'zed', 'cursor', 'cursor-agent', 'vscode',
+  'copilot-cli', 'copilot-jetbrains', 'kiro', 'devin', 'antigravity', 'agy', 'commandcode', 'droid'];
+const OPENCODE_CHANNEL_DB = /\/opencode-[A-Za-z0-9._-]+\.db$/;
+function relFolder(harness, mac) {
+  // Never the converting process's own environment (XDG_*, APPDATA): the rule is about the machine
+  // that wrote the 0.18 row, and must give the same answer on any server.
+  return defaultFolder(harness, { home: '/', platform: mac ? 'darwin' : 'linux', env: {} }) || '';
+}
+
+/** The harness_path (data folder) a legacy transcript path belongs to: what capture keys its session by. */
+function pathFromPath(harness, p) {
+  const s = String(p ?? '');
+  if (!s) return '';
+  let m;
+  if (harness === 'claude-code' && (m = /^(.*)\/projects\//.exec(s))) return m[1];
+  if (harness === 'codex' && (m = /^(.*)\/(archived_)?sessions\//.exec(s))) return m[1];
+  // OpenCode is keyed by its DB file (sessions-model §1): a path naming a channel DB is that store;
+  // anything else is the default DB, the only one the 0.18 reader read.
+  if (harness === 'opencode' && OPENCODE_CHANNEL_DB.test(s)) return s;
+  const home = (new RegExp(HOME_RE).exec(s) || [])[1] || '';
+  const rel = relFolder(harness, s.startsWith('/Users/'));
+  if (harness === 'opencode') return home && rel ? `${home}${rel}/opencode.db` : '';
+  return home && rel ? home + rel : '';
+}
+
+function isMarkerLine(l) {
+  return l.startsWith(MARKERS.thinking) || l.startsWith(MARKERS.tool_call) || l.startsWith(MARKERS.tool_result);
+}
+
+/**
+ * The v3 `kind` of a legacy row — best effort, because a legacy row is a JOIN of parts:
+ * Claude Code wrote one row per record (almost always one content block), Codex one row per
+ * turn (reasoning summaries, tool calls, tool results and the answer, '\n'-joined).
+ *
+ *   1. not an assistant row                              text
+ *   2. exactly '[assistant activity]' (Codex: tokens, no text)   usage
+ *   3. starts '[thinking] ' and the harness is not codex  thinking   (a Claude thinking block
+ *                                                                     is its own record; its
+ *                                                                     body may span lines)
+ *   4. every line starts with a marker                    the first line's marker kind
+ *   5. starts '[tool-result: '                            tool_result (a multi-line result)
+ *   6. otherwise                                          text       (a Codex turn with an
+ *                                                                     answer in it)
+ *
+ * A leading '[subagent] ' tag is ignored. kindSQL() is the same rule in ClickHouse SQL; the
+ * conversion matrix holds the two against each other on every fixture row.
+ */
+function legacyKind(role, text, harness) {
+  if (role !== 'assistant') return 'text';
+  let t = String(text ?? '');
+  if (t.startsWith(SUBAGENT_TAG)) t = t.slice(SUBAGENT_TAG.length);
+  if (t === '[assistant activity]') return 'usage';
+  if (harness !== 'codex' && t.startsWith(MARKERS.thinking)) return 'thinking';
+  if (t.split('\n').every(isMarkerLine)) {
+    if (t.startsWith(MARKERS.thinking)) return 'thinking';
+    if (t.startsWith(MARKERS.tool_call)) return 'tool_call';
+    return 'tool_result';
+  }
+  if (t.startsWith(MARKERS.tool_result)) return 'tool_result';
+  return 'text';
+}
+
+/**
+ * How many hash buckets a conversion is split into: enough that no bucket holds more than
+ * `batchRows` rows or `batchBytes` bytes of message text. Bytes matter more than rows — the
+ * insert's memory is the text indexes being built over the bucket's text (measured on lab
+ * 26.7.4.58: ~1.4 GiB for one 175k-row bucket of ~230 MB text with default insert blocks,
+ * ~0.6 GiB with INSERT_BLOCKS below).
+ */
+const BATCH_ROWS = 250000;
+const BATCH_BYTES = 64 * 1024 * 1024;
+function bucketCount(rows, batchRows = BATCH_ROWS, bytes = 0, batchBytes = BATCH_BYTES) {
+  const r = Math.max(1, Math.floor(Number(batchRows) || BATCH_ROWS));
+  const y = Math.max(1, Math.floor(Number(batchBytes) || BATCH_BYTES));
+  return Math.max(1, Math.ceil((Number(rows) || 0) / r), Math.ceil((Number(bytes) || 0) / y));
+}
+
+// ── SQL: the same rules, server-side ──────────────────────────────────────────────────
+
+/** A ClickHouse string literal. */
+function lit(v) { return `'${String(v).replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`; }
+
+const PREFIXED = (a) => `(${a}.source != '' AND startsWith(${a}.session_id, concat(${a}.source, ':')))`;
+const BARE_PREFIX = (a) => `(${a}.source = '' AND position(${a}.session_id, ':') > 0)`;
+
+function harnessSQL(a) {
+  return `multiIf(${PREFIXED(a)}, toString(${a}.source), ${BARE_PREFIX(a)}, substringIndex(${a}.session_id, ':', 1), toString(${a}.source))`;
+}
+function sessionSQL(a) {
+  return `multiIf(${PREFIXED(a)}, substring(${a}.session_id, length(${a}.source) + 2), `
+    + `${BARE_PREFIX(a)}, substring(${a}.session_id, position(${a}.session_id, ':') + 1), ${a}.session_id)`;
+}
+function prefixedSQL(a) { return `(${PREFIXED(a)} OR ${BARE_PREFIX(a)})`; }
+
+function rootSQL(p) {
+  return `if(position(${p}, '${PLAYBOOKS_DIR}') > 0, `
+    + `splitByChar('/', substring(${p}, position(${p}, '${PLAYBOOKS_DIR}') + ${PLAYBOOKS_DIR.length}))[1], `
+    + `if(${p} != '', 'default', ''))`;
+}
+
+/** pathFromPath in SQL: `h` the v3 harness expression, `p` the legacy path. */
+function pathSQL(h, p) {
+  const H = `[${PATH_HARNESSES.map(lit).join(', ')}]`;
+  const rels = (mac) => `[${PATH_HARNESSES.map((x) => lit(relFolder(x, mac))).join(', ')}]`;
+  const home = `extract(${p}, ${lit(HOME_RE)})`;
+  const rel = `if(startsWith(${p}, '/Users/'), transform(${h}, ${H}, ${rels(true)}, ''), transform(${h}, ${H}, ${rels(false)}, ''))`;
+  return `multiIf(${p} = '', '',
+      ${h} = 'opencode' AND match(${p}, '/opencode-[A-Za-z0-9._-]+\\.db$'), ${p},
+      ${h} = 'opencode' AND ${home} != '' AND ${rel} != '', concat(${home}, ${rel}, '/opencode.db'),
+      ${h} = 'claude-code' AND match(${p}, '/projects/'), extract(${p}, '^(.*)/projects/'),
+      ${h} = 'codex' AND match(${p}, '/(archived_)?sessions/'), extract(${p}, '^(.*)/(archived_)?sessions/'),
+      ${home} != '' AND ${rel} != '', concat(${home}, ${rel}), '')`;
+}
+
+function kindSQL(role, text, harness) {
+  const t = `if(startsWith(${text}, '${SUBAGENT_TAG}'), substring(${text}, ${SUBAGENT_TAG.length + 1}), ${text})`;
+  const marker = (x) => `(startsWith(${x}, '${MARKERS.thinking}') OR startsWith(${x}, '${MARKERS.tool_call}') OR startsWith(${x}, '${MARKERS.tool_result}'))`;
+  return `multiIf(${role} != 'assistant', 'text',
+      ${t} = '[assistant activity]', 'usage',
+      ${harness} != 'codex' AND startsWith(${t}, '${MARKERS.thinking}'), 'thinking',
+      arrayAll(l -> ${marker('l')}, splitByChar('\\n', ${t})),
+        multiIf(startsWith(${t}, '${MARKERS.thinking}'), 'thinking', startsWith(${t}, '${MARKERS.tool_call}'), 'tool_call', 'tool_result'),
+      startsWith(${t}, '${MARKERS.tool_result}'), 'tool_result',
+      'text')`;
+}
+
+function bucketSQL(h, s, n, b) {
+  return n > 1 ? `cityHash64(toString(${h}), toString(${s})) % ${n} = ${b}` : '1';
+}
+
+/**
+ * House.js currentParse as a predicate on alias `a`; tool calls take the epoch from messages.
+ *
+ * With `member`, a session that has rows under the member's own user_id takes ONLY those: rows
+ * of the same session under another user_id are older copies (a pre-member `default` shipper),
+ * and v3's key has no user_id, so keeping both would merge two parses row by row. Measured on
+ * a development copy (2026-10-14): hundreds of sessions existed under both the member and
+ * `default`; the `default` copy was never longer (about nine in ten equal, the rest shorter) and
+ * its newest message predated the member.
+ */
+function currentParseSQL(a, messagesTable, member = null) {
+  const own = member == null ? '' : ` AND (${a}.user_id = ${lit(member)} OR ${a}.session_id NOT IN (
+      SELECT DISTINCT session_id FROM ${messagesTable} WHERE user_id = ${lit(member)}))`;
+  return `((${a}.origin != 'ship' OR (${a}.session_id, ${a}.user_id, ${a}.epoch) IN (
+      SELECT session_id, user_id, max(epoch) FROM ${messagesTable} WHERE origin = 'ship' GROUP BY session_id, user_id))${own})`;
+}
+
+/**
+ * Which legacy row wins when two land on ONE v3 key (same split session, origin, epoch, seq —
+ * or idx — and ts): two user_ids on one row, or a prefixed and an unprefixed id of one
+ * session. The winner is the member's own row, then the newest ingested_at, then the greatest
+ * (user_id, legacy session id) — deterministic, so a re-run and a resumed run write the same
+ * row. The losers are counted as `collisions` in the report.
+ *
+ * Computed as an exclusion set from key columns only — a GROUP BY over ids and times, never a
+ * sort of whole rows with their text (ORDER BY … LIMIT 1 BY would hold a bucket's text in
+ * memory to find, in practice, nothing).
+ */
+function losersSQL(N, table, idOf, n, b) {
+  const a = 'x';
+  return `SELECT kh, ks, kid, kt, c.1 AS ku, c.2 AS kl FROM (
+      SELECT kh, ks, kid, kt, groupArray((ku, kl)) AS cand,
+             argMax((ku, kl), (ku = ${lit(N.member)}, king, ku, kl)) AS win
+      FROM (
+        SELECT ${harnessSQL(a)} AS kh, ${sessionSQL(a)} AS ks, ${idOf(a)} AS kid, ${a}.ts AS kt,
+               ${a}.user_id AS ku, ${a}.session_id AS kl, ${a}.ingested_at AS king
+        FROM ${table} AS ${a} FINAL
+        WHERE ${currentParseSQL(a, N.legacy.messages, N.member)} AND ${bucketSQL('kh', 'ks', n, b)}
+      )
+      GROUP BY kh, ks, kid, kt HAVING count() > 1
+    ) ARRAY JOIN cand AS c WHERE c != win`;
+}
+/** legacyInput() in SQL: `h` is the row's harness expression. UInt64 like the column: the difference is
+ * taken signed and floored at 0, since a UInt64 minus a UInt64 is Int64 in ClickHouse. */
+const legacyInputSQL = (a, h) => `if(${h} IN (${INPUT_INCLUDES_CACHE.map(lit).join(', ')}), `
+  + `toUInt64(greatest(toInt64(${a}.input_tokens) - toInt64(${a}.cache_read_tokens), 0)), ${a}.input_tokens)`;
+const MESSAGE_ID = (a) => `concat('legacy:', toString(${a}.origin), ':', toString(${a}.epoch), ':', toString(${a}.seq))`;
+const CALL_ID = (a) => `concat('legacy:', toString(${a}.origin), ':', toString(${a}.epoch), ':', toString(${a}.idx))`;
+
+/** The converted legacy messages of one bucket, with v3 names prefixed `v_`. */
+function legacyMessagesSQL(N, n, b, { onePerKey = true } = {}) {
+  const L = N.legacy;
+  return `SELECT
+      ${harnessSQL('m')} AS v_harness,
+      ${sessionSQL('m')} AS v_session,
+      ${prefixedSQL('m')} AS v_prefixed,
+      m.session_id AS l_session,
+      toJSONString(m.extra) AS v_extra,
+      JSONExtractString(v_extra, 'agent', 'id') AS v_agent,
+      ${MESSAGE_ID('m')} AS v_message_id,
+      m.ts AS v_ts,
+      toUInt64(m.seq) AS v_ord,
+      toString(m.role) AS v_role,
+      ${kindSQL('m.role', 'm.text', 'v_harness')} AS v_kind,
+      toString(m.model) AS v_model,
+      ${legacyInputSQL('m', 'v_harness')} AS v_in, m.input_tokens AS l_in, m.output_tokens AS v_out,
+      m.cache_read_tokens AS v_cr, m.cache_write_tokens AS v_cw,
+      m.text AS v_text,
+      toUInt32(lengthUTF8(m.text)) AS v_text_len,
+      m.folder AS v_folder, m.project AS v_project, toString(m.host) AS v_host,
+      toString(m.origin) AS v_origin,
+      m.user_id AS v_user, m.ingested_at AS v_ingested
+    FROM ${L.messages} AS m FINAL
+    WHERE ${currentParseSQL('m', L.messages, N.member)} AND ${bucketSQL('v_harness', 'v_session', n, b)}${onePerKey ? `
+      AND (v_harness, v_session, v_message_id, v_ts, v_user, l_session) NOT IN (${losersSQL(N, L.messages, MESSAGE_ID, n, b)})` : ''}`;
+}
+
+function legacyCallsSQL(N, n, b, { onePerKey = true } = {}) {
+  const L = N.legacy;
+  return `SELECT
+      ${harnessSQL('t')} AS v_harness,
+      ${sessionSQL('t')} AS v_session,
+      t.session_id AS l_session, t.user_id AS v_user, toString(t.origin) AS v_origin,
+      t.epoch AS l_epoch, t.seq AS l_seq,
+      concat('legacy:', v_origin, ':', toString(t.epoch), ':', toString(t.idx)) AS v_call_id,
+      concat('legacy:', v_origin, ':', toString(t.epoch), ':', toString(t.seq)) AS v_message_id,
+      t.ts AS v_ts, toString(t.tool_name) AS v_tool, t.args AS v_args,
+      t.folder AS v_folder, t.project AS v_project, toString(t.host) AS v_host,
+      t.ingested_at AS v_ingested
+    FROM ${L.tool_calls} AS t FINAL
+    WHERE ${currentParseSQL('t', L.messages, N.member)} AND ${bucketSQL('v_harness', 'v_session', n, b)}${onePerKey ? `
+      AND (v_harness, v_session, v_call_id, v_ts, v_user, l_session) NOT IN (${losersSQL(N, L.tool_calls, CALL_ID, n, b)})` : ''}`;
+}
+
+function legacySessionsSQL(N, n, b) {
+  return `SELECT
+      ${harnessSQL('z')} AS v_harness,
+      ${sessionSQL('z')} AS v_session,
+      z.session_id AS l_session, toString(z.host) AS l_host, z.name AS l_name, toString(z.mode) AS l_mode,
+      z.folder AS l_folder, z.project AS l_project, z.git_branch AS l_branch,
+      z.created_at AS l_created, z.last_updated_at AS l_updated, toString(z.origin) AS l_origin,
+      z.user_id AS l_user, z.ingested_at AS l_ing, ${pathSQL(harnessSQL('z'), 'z.path')} AS l_path
+    FROM ${N.legacy.sessions} AS z FINAL
+    WHERE ${bucketSQL('v_harness', 'v_session', n, b)}`;
+}
+
+const TURN_COLUMNS = [
+  'harness', 'harness_version', 'harness_path', 'session_id', 'incarnation', 'agent_id', 'message_id', 'part_id', 'part_ord',
+  'parent_id', 'response_id', 'ts', 'ord', 'rev', 'is_deleted', 'removed', 'state', 'role', 'kind', 'model', 'effort',
+  'input_tokens', 'output_tokens', 'cache_read_tokens', 'cache_write_tokens', 'reasoning_tokens',
+  'text', 'text_len', 'folder', 'project', 'host', 'origin', 'extra', 'adapter_ver', 'user_id', 'ingested_at',
+];
+
+function turnsInsertSQL(N, n, b) {
+  return `INSERT INTO ${N.turns} (${TURN_COLUMNS.join(', ')})
+    SELECT c.v_harness, '', ifNull(r.l_path, ''), c.v_session, '', c.v_agent, c.v_message_id, '0', 0, '', '',
+           c.v_ts, c.v_ord, 0, 0, 0, '', c.v_role, c.v_kind, c.v_model, '',
+           c.v_in, c.v_out, c.v_cr, c.v_cw, 0,
+           c.v_text, c.v_text_len, c.v_folder, c.v_project, c.v_host, c.v_origin, c.v_extra, 0, c.v_user, c.v_ingested
+    FROM (${legacyMessagesSQL(N, n, b)}) AS c
+    LEFT JOIN (${legacyPathsSQL(N)}) AS r ON r.l_session = c.l_session`;
+}
+
+/** Each legacy session's harness_path, from its newest legacy sessions row. */
+function legacyPathsSQL(N) {
+  return `SELECT z.session_id AS l_session, argMax(${pathSQL(harnessSQL('z'), 'z.path')}, z.ingested_at) AS l_path
+      FROM ${N.legacy.sessions} AS z FINAL GROUP BY z.session_id`;
+}
+
+const CALL_COLUMNS = [
+  'harness', 'harness_path', 'session_id', 'incarnation', 'agent_id', 'call_id', 'message_id', 'ts', 'rev', 'is_deleted', 'removed', 'tool_name',
+  'args', 'result_ts', 'is_error', 'result_len', 'model', 'folder', 'project', 'host', 'adapter_ver',
+  'user_id', 'ingested_at',
+];
+
+function callsInsertSQL(N, n, b) {
+  const L = N.legacy;
+  return `INSERT INTO ${N.calls} (${CALL_COLUMNS.join(', ')})
+    SELECT c.v_harness, ifNull(r.l_path, ''), c.v_session, '', ifNull(j.j_agent, ''), c.v_call_id, c.v_message_id, c.v_ts, 0, 0, 0,
+           c.v_tool, c.v_args, NULL, false, 0, ifNull(j.j_model, ''), c.v_folder, c.v_project, c.v_host, 0,
+           c.v_user, c.v_ingested
+    FROM (${legacyCallsSQL(N, n, b)}) AS c
+    LEFT JOIN (
+      SELECT m.session_id AS j_session, m.user_id AS j_user, toString(m.origin) AS j_origin,
+             m.epoch AS j_epoch, m.seq AS j_seq,
+             JSONExtractString(toJSONString(m.extra), 'agent', 'id') AS j_agent, toString(m.model) AS j_model
+      FROM ${L.messages} AS m FINAL
+      WHERE ${bucketSQL(harnessSQL('m'), sessionSQL('m'), n, b)}
+    ) AS j ON j.j_session = c.l_session AND j.j_user = c.v_user AND j.j_origin = c.v_origin
+          AND j.j_epoch = c.l_epoch AND j.j_seq = c.l_seq
+    LEFT JOIN (${legacyPathsSQL(N)}) AS r ON r.l_session = c.l_session`;
+}
+
+const SESSION_COLUMNS = [
+  'harness', 'session_id', 'incarnation', 'harness_version', 'harness_path', 'host', 'name', 'mode', 'folder', 'project',
+  'git_branch', 'created_at', 'updated_at', 'started', 'ended', 'messages', 'user_messages',
+  'assistant_messages', 'agent_messages', 'tool_calls', 'input_tokens', 'output_tokens',
+  'cache_read_tokens', 'cache_write_tokens', 'reasoning_tokens', 'user_chars', 'assistant_chars',
+  'first_prompt', 'models', 'dominant_model', 'days',
+  '`usage.hour`', '`usage.model`', '`usage.messages`', '`usage.input`', '`usage.output`',
+  '`usage.cache_read`', '`usage.cache_write`', '`usage.reasoning`',
+  '`tools.name`', '`tools.calls`', '`tools.errors`',
+  '`agents.agent_id`', '`agents.type`', '`agents.description`', '`agents.workflow`', '`agents.messages`', '`agents.first_ts`',
+  '`links.kind`', '`links.origin`', '`links.origin_store`', '`links.evidence`', '`links.at`', '`links.through`',
+  'usage_basis', 'origin', 'rev', 'is_deleted', 'removed', 'user_id', 'ingested_at',
+];
+
+/** The converted turns of one bucket — read with FINAL, tombstones dropped. */
+function convertedTurnsSQL(N, n, b) {
+  // Short aliases, none of them a column name or a table alias of sessionsInsertSQL — an alias
+  // that shadows a column inside its own aggregate is a cyclic-alias error in ClickHouse.
+  return `SELECT toString(harness) AS h, session_id AS s, agent_id AS aid, ts AS t, ord AS o,
+           toString(role) AS rl, toString(kind) AS kd, toString(model) AS md,
+           input_tokens AS ti, output_tokens AS tout, cache_read_tokens AS tcr, cache_write_tokens AS tcw,
+           reasoning_tokens AS trs, text AS tx, text_len AS tlen, folder AS fo, project AS pr,
+           toString(host) AS ho, toString(harness_path) AS ro, toString(origin) AS og, extra AS ex,
+           user_id AS uid, ingested_at AS ing
+    FROM ${N.turns} FINAL
+    WHERE is_deleted = 0 AND removed = 0 AND startsWith(message_id, 'legacy:') AND ${bucketSQL('harness', 'session_id', n, b)}`;
+}
+
+function sessionsInsertSQL(N, n, b) {
+  const T = convertedTurnsSQL(N, n, b);
+  return `INSERT INTO ${N.sessions} (${SESSION_COLUMNS.join(', ')})
+    SELECT
+      k.kh, k.ks, '', '',
+      if(ls.ls_path != '', ls.ls_path, a.a_root),
+      if(ls.ls_host != '', ls.ls_host, a.a_host),
+      ls.ls_name, ls.ls_mode,
+      if(ls.ls_folder != '', ls.ls_folder, a.a_folder),
+      if(ls.ls_project != '', ls.ls_project, a.a_project),
+      ls.ls_branch, ls.ls_created, ls.ls_updated,
+      if(a.a_n > 0, a.a_started, coalesce(ls.ls_created, ls.ls_updated, ls.ls_ing)),
+      if(a.a_n > 0, a.a_ended, coalesce(ls.ls_updated, ls.ls_created, ls.ls_ing)),
+      a.a_messages, a.a_user_messages, a.a_assistant_messages, a.a_agent_messages,
+      toUInt32(tl.tl_calls),
+      a.a_in, a.a_out, a.a_cr, a.a_cw, a.a_rs, a.a_user_chars, a.a_assistant_chars,
+      a.a_first_prompt, a.a_models, dm.dm_model,
+      arraySort(arrayDistinct(arrayConcat(a.a_days, tl.tl_days))),
+      arrayMap(x -> x.1, u.u_arr), arrayMap(x -> x.2, u.u_arr), arrayMap(x -> x.3, u.u_arr),
+      arrayMap(x -> x.4, u.u_arr), arrayMap(x -> x.5, u.u_arr), arrayMap(x -> x.6, u.u_arr),
+      arrayMap(x -> x.7, u.u_arr), arrayMap(x -> x.8, u.u_arr),
+      arrayMap(x -> x.1, tl.tl_arr), arrayMap(x -> x.2, tl.tl_arr), arrayMap(x -> x.3, tl.tl_arr),
+      arrayMap(x -> x.1, ag.ag_arr), arrayMap(x -> x.2, ag.ag_arr), arrayMap(x -> x.3, ag.ag_arr),
+      arrayMap(x -> x.4, ag.ag_arr), arrayMap(x -> x.5, ag.ag_arr), arrayMap(x -> x.6, ag.ag_arr),
+      [], [], [], [], [], [],
+      'per_record',
+      if(ls.ls_present = 1, ls.ls_origin, if(a.a_ship > 0, 'ship', a.a_origin)),
+      0, 0, 0,
+      if(ls.ls_present = 1, ls.ls_user, a.a_user),
+      if(ls.ls_present = 1, ls.ls_ing, a.a_ing)
+    FROM (
+      SELECT DISTINCT kh, ks FROM (
+        SELECT h AS kh, s AS ks FROM (${T})
+        UNION ALL
+        SELECT v_harness AS kh, v_session AS ks FROM (${legacySessionsSQL(N, n, b)})
+      )
+    ) AS k
+    LEFT JOIN (
+      SELECT h, s, count() AS a_n, min(t) AS a_started, max(t) AS a_ended,
+             toUInt32(countIf(kd = 'text')) AS a_messages,
+             toUInt32(countIf(kd = 'text' AND rl = 'user')) AS a_user_messages,
+             toUInt32(countIf(kd = 'text' AND rl = 'assistant')) AS a_assistant_messages,
+             toUInt32(countIf(kd = 'text' AND aid != '')) AS a_agent_messages,
+             sum(ti) AS a_in, sum(tout) AS a_out, sum(tcr) AS a_cr, sum(tcw) AS a_cw, sum(trs) AS a_rs,
+             sumIf(toUInt64(tlen), rl = 'user') AS a_user_chars, sumIf(toUInt64(tlen), rl = 'assistant') AS a_assistant_chars,
+             substringUTF8(argMinIf(tx, (t, o), rl = 'user' AND aid = '' AND kd = 'text' AND tx != ''), 1, 200) AS a_first_prompt,
+             arraySort(groupUniqArrayIf(md, md NOT IN ('', '<synthetic>'))) AS a_models,
+             arraySort(groupUniqArray(toDate(t))) AS a_days,
+             argMin(ro, (t, o)) AS a_root, argMin(ho, (t, o)) AS a_host,
+             argMin(fo, (t, o)) AS a_folder, argMin(pr, (t, o)) AS a_project,
+             countIf(og = 'ship') AS a_ship, argMin(og, (t, o)) AS a_origin,
+             argMin(uid, (t, o)) AS a_user, max(ing) AS a_ing
+      FROM (${T}) GROUP BY h, s
+    ) AS a ON a.h = k.kh AND a.s = k.ks
+    LEFT JOIN (
+      SELECT h, s, arraySort(x -> (x.1, x.2), groupArray((hr, md, um, ui, uo, ucr, ucw, urs))) AS u_arr
+      FROM (
+        SELECT h, s, toStartOfHour(toDateTime(t, 'UTC')) AS hr, md, toUInt32(countIf(kd = 'text')) AS um,
+               sum(ti) AS ui, sum(tout) AS uo, sum(tcr) AS ucr, sum(tcw) AS ucw, sum(trs) AS urs
+        FROM (${T}) GROUP BY h, s, hr, md
+      ) GROUP BY h, s
+    ) AS u ON u.h = k.kh AND u.s = k.ks
+    LEFT JOIN (
+      SELECT h, s, arraySort(x -> x.1, groupArray((tn, tc, te))) AS tl_arr, sum(tc) AS tl_calls,
+             arraySort(arrayDistinct(groupArrayArray(td))) AS tl_days
+      FROM (
+        SELECT toString(harness) AS h, session_id AS s, toString(tool_name) AS tn,
+               toUInt32(count()) AS tc, toUInt32(countIf(is_error)) AS te, groupUniqArray(toDate(ts)) AS td
+        FROM ${N.calls} FINAL
+        WHERE is_deleted = 0 AND startsWith(call_id, 'legacy:') AND ${bucketSQL('harness', 'session_id', n, b)}
+        GROUP BY h, s, tn
+      ) GROUP BY h, s
+    ) AS tl ON tl.h = k.kh AND tl.s = k.ks
+    LEFT JOIN (
+      SELECT h, s, arraySort(x -> (x.6, x.1), groupArray((aid, g_type, g_desc, g_wf, g_msgs, g_first))) AS ag_arr
+      FROM (
+        SELECT h, s, aid,
+               argMin(JSONExtractString(ex, 'agent', 'type'), (t, o)) AS g_type,
+               argMin(JSONExtractString(ex, 'agent', 'description'), (t, o)) AS g_desc,
+               argMin(JSONExtractString(ex, 'agent', 'workflow'), (t, o)) AS g_wf,
+               toUInt32(countIf(kd = 'text')) AS g_msgs, min(t) AS g_first
+        FROM (${T}) WHERE aid != '' GROUP BY h, s, aid
+      ) GROUP BY h, s
+    ) AS ag ON ag.h = k.kh AND ag.s = k.ks
+    LEFT JOIN (
+      SELECT h, s, argMax(md, (c, md)) AS dm_model
+      FROM (SELECT h, s, md, count() AS c FROM (${T}) WHERE md NOT IN ('', '<synthetic>') GROUP BY h, s, md)
+      GROUP BY h, s
+    ) AS dm ON dm.h = k.kh AND dm.s = k.ks
+    LEFT JOIN (
+      SELECT v_harness, v_session, 1 AS ls_present,
+             argMax(l_host, l_ing) AS ls_host, argMax(l_name, l_ing) AS ls_name, argMax(l_mode, l_ing) AS ls_mode,
+             argMax(l_folder, l_ing) AS ls_folder, argMax(l_project, l_ing) AS ls_project,
+             argMax(l_branch, l_ing) AS ls_branch,
+             argMax(l_created, l_ing) AS ls_created, argMax(l_updated, l_ing) AS ls_updated,
+             argMax(l_origin, l_ing) AS ls_origin, argMax(l_user, l_ing) AS ls_user, max(l_ing) AS ls_ing,
+             argMax(l_path, l_ing) AS ls_path
+      FROM (${legacySessionsSQL(N, n, b)})
+      GROUP BY v_harness, v_session
+    ) AS ls ON ls.v_harness = k.kh AND ls.v_session = k.ks`;
+}
+
+// ── counting: what the legacy side yields, what is already converted ─────────────────
+
+function legacyTurnCountsSQL(N, n) {
+  return `SELECT ${n > 1 ? `cityHash64(toString(v_harness), toString(v_session)) % ${n}` : '0'} AS b,
+           count() AS rows, uniqExact(v_harness, v_session, v_message_id, v_ts) AS keys,
+           uniqExactIf(l_session, NOT v_prefixed) AS unprefixed
+    FROM (${legacyMessagesSQL(N, 1, 0, { onePerKey: false })}) GROUP BY b`;
+}
+/** The Gemini CLI rows whose input loses its cache reads, and the tokens it loses: over the rows the
+ * insert writes (current parse, one per v3 key), so a dry run counts what the conversion takes out. */
+function legacyInputAdjustSQL(N) {
+  return `SELECT countIf(l_in != v_in) AS rows, sum(l_in - v_in) AS tokens
+    FROM (${legacyMessagesSQL(N, 1, 0)}) WHERE v_harness IN (${INPUT_INCLUDES_CACHE.map(lit).join(', ')})`;
+}
+function convertedTurnCountsSQL(N, n) {
+  return `SELECT ${n > 1 ? `cityHash64(toString(harness), toString(session_id)) % ${n}` : '0'} AS b,
+           uniqExact(toString(harness), session_id, message_id, ts) AS keys
+    FROM ${N.turns} WHERE startsWith(message_id, 'legacy:') GROUP BY b`;
+}
+function legacyCallCountsSQL(N, n) {
+  return `SELECT ${n > 1 ? `cityHash64(toString(v_harness), toString(v_session)) % ${n}` : '0'} AS b,
+           count() AS rows, uniqExact(v_harness, v_session, v_call_id, v_ts) AS keys
+    FROM (${legacyCallsSQL(N, 1, 0, { onePerKey: false })}) GROUP BY b`;
+}
+function convertedCallCountsSQL(N, n) {
+  return `SELECT ${n > 1 ? `cityHash64(toString(harness), toString(session_id)) % ${n}` : '0'} AS b,
+           uniqExact(toString(harness), session_id, call_id, ts) AS keys
+    FROM ${N.calls} WHERE startsWith(call_id, 'legacy:') GROUP BY b`;
+}
+function legacySessionCountsSQL(N, n) {
+  return `SELECT ${n > 1 ? `cityHash64(toString(kh), toString(ks)) % ${n}` : '0'} AS b, uniqExact(kh, ks) AS keys
+    FROM (
+      SELECT v_harness AS kh, v_session AS ks FROM (${legacyMessagesSQL(N, 1, 0, { onePerKey: false })})
+      UNION ALL
+      SELECT v_harness AS kh, v_session AS ks FROM (${legacySessionsSQL(N, 1, 0)})
+    ) GROUP BY b`;
+}
+function convertedSessionCountsSQL(N, n) {
+  // Rows this conversion wrote: rev 0 and the legacy usage basis. The capture layer's rows
+  // (rev ≥ 1, per_response) are not counted, whether or not they have replaced these.
+  return `SELECT ${n > 1 ? `cityHash64(toString(harness), toString(session_id)) % ${n}` : '0'} AS b,
+           uniqExact(toString(harness), session_id) AS keys
+    FROM ${N.sessions} WHERE rev = 0 AND usage_basis = 'per_record' GROUP BY b`;
+}
+
+/**
+ * Every query's settings, explicitly — never the CLI's session-wide final=1 / join_use_nulls=1:
+ * FINAL is written where it is meant, join misses read as defaults, user_id is carried rather
+ * than restamped, and toJSONString keeps integers as numbers.
+ */
+const CONVERT_SETTINGS = {
+  final: 0, join_use_nulls: 0, async_insert: 0, insert_allow_materialized_columns: 1,
+  output_format_json_quote_64bit_integers: 0,
+};
+/** Smaller insert blocks: parts of ≤16k rows / 16 MiB, so no text index is built over a whole bucket at once. */
+const INSERT_BLOCKS = {
+  max_insert_block_size: 16384, min_insert_block_size_rows: 16384, min_insert_block_size_bytes: 16 * 1024 * 1024,
+};
+const INSERT_SETTINGS = { ...CONVERT_SETTINGS, ...INSERT_BLOCKS };
+
+function byBucket(rows, field) {
+  const m = new Map();
+  for (const r of rows) m.set(Number(r.b), Number(r[field]) || 0);
+  return m;
+}
+const sumMap = (m) => [...m.values()].reduce((a, x) => a + x, 0);
+
+async function rowsOrEmpty(q, sql) {
+  try { return await q.rows(sql, CONVERT_SETTINGS); }
+  catch (e) {
+    if (/UNKNOWN_TABLE|Unknown table|doesn't exist|does not exist/i.test(String(e && e.message))) return [];
+    throw e;
+  }
+}
+
+/**
+ * What sizes the buckets: the legacy rows and the bytes of message text — under FINAL, so a
+ * background merge between two runs cannot change the bucket count (and with it every
+ * bucket's membership).
+ */
+async function legacySize(q, N) {
+  const r = await q.rows(`SELECT (SELECT count() FROM ${N.legacy.messages} FINAL) AS m,
+      (SELECT sum(length(text)) FROM ${N.legacy.messages} FINAL) AS bytes,
+      (SELECT count() FROM ${N.legacy.tool_calls} FINAL) AS t`, CONVERT_SETTINGS);
+  return { rows: Math.max(Number(r[0]?.m) || 0, Number(r[0]?.t) || 0), bytes: Number(r[0]?.bytes) || 0 };
+}
+
+/** Per-bucket legacy and converted counts for all three tables. */
+async function plan(q, N, n) {
+  const [lt, ct, lc, cc, ls, cs] = await Promise.all([
+    q.rows(legacyTurnCountsSQL(N, n), CONVERT_SETTINGS),
+    rowsOrEmpty(q, convertedTurnCountsSQL(N, n)),
+    q.rows(legacyCallCountsSQL(N, n), CONVERT_SETTINGS),
+    rowsOrEmpty(q, convertedCallCountsSQL(N, n)),
+    q.rows(legacySessionCountsSQL(N, n), CONVERT_SETTINGS),
+    rowsOrEmpty(q, convertedSessionCountsSQL(N, n)),
+  ]);
+  return {
+    turns: { rows: byBucket(lt, 'rows'), want: byBucket(lt, 'keys'), have: byBucket(ct, 'keys'), unprefixed: sumMap(byBucket(lt, 'unprefixed')) },
+    calls: { rows: byBucket(lc, 'rows'), want: byBucket(lc, 'keys'), have: byBucket(cc, 'keys') },
+    sessions: { want: byBucket(ls, 'keys'), have: byBucket(cs, 'keys') },
+  };
+}
+
+function complete(p, b) { return (p.want.get(b) || 0) === (p.have.get(b) || 0); }
+
+function summarize(p, inserted, skipped) {
+  const out = {
+    legacy_keys: sumMap(p.want), converted_keys: sumMap(p.have),
+    buckets_inserted: inserted, buckets_skipped: skipped,
+  };
+  if (p.rows) {
+    out.legacy_rows = sumMap(p.rows);
+    // Two legacy rows that land on ONE v3 key: same split session, origin, epoch, seq and ts,
+    // different user_id (or a prefixed and an unprefixed id of one session). Reported, never hidden.
+    out.collisions = out.legacy_rows - out.legacy_keys;
+  }
+  return out;
+}
+
+/**
+ * Convert one member. `ctx`: { db, member, ledger?, host? }. `opts`: { batchRows, dryRun }.
+ * @returns the report: per-table counts, buckets, collisions, unprefixed ids, ok.
+ */
+async function convert(q, ctx, { batchRows = BATCH_ROWS, batchBytes = BATCH_BYTES, dryRun = false } = {}, ui = null) {
+  const N = v3Names(ctx.db, ctx.member);
+  const say = (m) => ui && ui.ok && ui.ok(m);
+  // A conversion resumes by comparing the legacy keys a bucket yields with the `legacy:` keys
+  // already in turns/calls. Once the capture has deduped converted rows (a 'legacy' files row), a
+  // tombstone cleanup may have dropped those rows and their tombstones together; a re-run would then
+  // find the bucket incomplete and write the duplicates back. So: never after dedupe, unless forced.
+  const deduped = await rowsOrEmpty(q, `SELECT count() AS n FROM ${N.files} FINAL WHERE role = 'legacy' AND is_deleted = 0`);
+  const dedupedSessions = Number((deduped[0] || {}).n) || 0;
+  if (dedupedSessions && !ctx.forceAfterDedupe) {
+    return { member: ctx.member, ok: false, deduped_sessions: dedupedSessions, refused: `${dedupedSessions} session(s) of ${ctx.member} are already deduped against their capture; `
+      + 're-converting could bring back rows the dedupe removed (and a cleanup may have dropped). Refusing.' };
+  }
+  const started = Date.now();
+  const size = await legacySize(q, N);
+  const n = bucketCount(size.rows, batchRows, size.bytes, batchBytes);
+  const before = await plan(q, N, n);
+  const adj = (await q.rows(legacyInputAdjustSQL(N), CONVERT_SETTINGS))[0] || {};
+  const report = {
+    member: ctx.member, source: N.legacy, target: { turns: N.turns, calls: N.calls, sessions: N.sessions },
+    buckets: n, legacy_text_bytes: size.bytes, dry_run: Boolean(dryRun), unprefixed_sessions: before.turns.unprefixed,
+    // Gemini CLI input without its cache reads (legacyInput): what the conversion takes out.
+    input_without_cache: { harnesses: INPUT_INCLUDES_CACHE, rows: Number(adj.rows) || 0, tokens: Number(adj.tokens) || 0 },
+  };
+  if (dryRun) {
+    report.turns = summarize(before.turns, 0, 0);
+    report.calls = summarize(before.calls, 0, 0);
+    report.sessions = summarize(before.sessions, 0, 0);
+    report.pending_buckets = [...Array(n).keys()].filter((b) =>
+      !complete(before.turns, b) || !complete(before.calls, b) || !complete(before.sessions, b));
+    report.ok = report.pending_buckets.length === 0;
+    return report;
+  }
+
+  const ledger = ctx.ledger || null;
+  const event = async (e) => { if (ledger) { try { await ledger.event(e); } catch { /* best effort */ } } };
+  await event({ kind: 'migration', id: '0200-v3-convert', status: 'pending', host: ctx.host || '',
+    detail: `convert ${ctx.member}: ${n} bucket(s)` });
+
+  const done = { turns: [0, 0], calls: [0, 0], sessions: [0, 0] };
+  try {
+    for (let b = 0; b < n; b++) {
+      let moved = false;
+      for (const [t, build] of [['turns', turnsInsertSQL], ['calls', callsInsertSQL]]) {
+        if (complete(before[t], b)) { done[t][1]++; continue; }
+        await q.sql(build(N, n, b), INSERT_SETTINGS);
+        done[t][0]++; moved = true;
+        say(`${t}: bucket ${b + 1}/${n} converted`);
+      }
+      if (moved || !complete(before.sessions, b)) {
+        await q.sql(sessionsInsertSQL(N, n, b), INSERT_SETTINGS);
+        done.sessions[0]++;
+        say(`sessions: bucket ${b + 1}/${n} built`);
+      } else done.sessions[1]++;
+    }
+  } catch (e) {
+    await event({ kind: 'migration', id: '0200-v3-convert', status: 'failed', host: ctx.host || '',
+      detail: `convert ${ctx.member}: ${String(e && e.message).split('\n')[0]}` });
+    throw e;
+  }
+
+  const after = await plan(q, N, n);
+  for (const t of ['turns', 'calls', 'sessions']) {
+    report[t] = summarize(after[t], done[t][0], done[t][1]);
+    report[t].converted_before = sumMap(before[t].have);
+  }
+  report.ok = ['turns', 'calls', 'sessions'].every((t) => [...Array(n).keys()].every((b) => complete(after[t], b)));
+  report.seconds = Math.round((Date.now() - started) / 100) / 10;
+  await event({ kind: 'migration', id: '0200-v3-convert', status: report.ok ? 'applied' : 'failed', host: ctx.host || '',
+    rows_before: report.turns.legacy_rows, rows_after: report.turns.converted_keys,
+    detail: `convert ${ctx.member}: turns ${report.turns.converted_keys}/${report.turns.legacy_keys}, `
+      + `calls ${report.calls.converted_keys}/${report.calls.legacy_keys}, `
+      + `sessions ${report.sessions.converted_keys}/${report.sessions.legacy_keys}`
+      + `${report.turns.collisions ? `, ${report.turns.collisions} turn collision(s)` : ''}` });
+  return report;
+}
+
+module.exports = {
+  // pure
+  splitLegacySessionId, legacyMessageId, legacyCallId, rootFromPath, pathFromPath, legacyKind, legacyInput, bucketCount, lit,
+  INPUT_INCLUDES_CACHE,
+  BATCH_ROWS, BATCH_BYTES,
+  // SQL builders (exported for the matrix and the unit gate)
+  harnessSQL, sessionSQL, rootSQL, pathSQL, kindSQL, bucketSQL, currentParseSQL, legacyInputSQL, legacyInputAdjustSQL, MESSAGE_ID,
+  legacyMessagesSQL, legacyCallsSQL, legacySessionsSQL,
+  turnsInsertSQL, callsInsertSQL, sessionsInsertSQL,
+  TURN_COLUMNS, CALL_COLUMNS, SESSION_COLUMNS, CONVERT_SETTINGS, INSERT_SETTINGS,
+  // running
+  legacySize, plan, convert,
+};