memhouse 0.8.0 → 0.11.0

package/memhouse/house/house.js

@@ -33,6 +33,100 @@
 
 const ROOM_TYPES = ['sessions', 'messages', 'tool_calls'];
 
+/**
+ * The house's own record of itself — not rooms. Nothing about a conversation lives in
+ * them, the shipper's guards do not require them, and a member who cannot create them
+ * still ships normally.
+ */
+const META_TYPES = ['house_meta', 'house_events'];
+
+/**
+ * What generation of the schema a house is at. Bumped only when existing rooms have to be
+ * REBUILT to keep working — a new column is not a version, because ensureSchema rolls one
+ * out in place.
+ *
+ *   1  0.4.x–0.9.x  shared rooms, origin in the transcript keys
+ *   2  0.10.0       epoch in the transcript keys; the shipper became insert-only
+ *
+ * A house at 1 is not broken, it is un-migrated: its rooms cannot hold two parses of a
+ * session, so the shipper refuses to write rather than overwrite. `memhouse migrate-rooms`
+ * moves it to 2.
+ */
+const SCHEMA_VERSION = 2;
+const MIGRATIONS = {
+  2: '0100-epoch-key',
+};
+
+/**
+ * Which schema generations THIS release may write. The degenerate compatibility matrix:
+ * a release supports exactly its own generation, and the array exists for the rare
+ * release that is wire-compatible across two (write both, migrate at leisure).
+ *
+ * The check that reads this (ship.js assertWriterSupported) is the forward half of the
+ * mixed-fleet story: every release from 0.10.0 on REFUSES a house whose recorded schema
+ * it does not support, in both directions — a house too new says "update memhouse", a
+ * house too old says "memhouse migrate". The backward half cannot be code: releases
+ * already on the registry read none of this, so for them the enforcement is the pilot's
+ * GRANTs (revoke the mutation privileges after migrating, and a pre-0.10 shipper's
+ * delete fails loudly instead of destroying retained parses). `memhouse migrate` prints
+ * that advice.
+ */
+const SUPPORTED_SCHEMAS = [2];
+
+/**
+ * The floor a house may set under its writers, recorded by `memhouse migrate` in
+ * house_meta['min_writer_schema']. Today it equals SCHEMA_VERSION; a future
+ * back-compatible generation can hold it one step lower for a grace window.
+ */
+const MIN_WRITER_SCHEMA = 2;
+
+/**
+ * The sorting key each room MUST have, as the column list ClickHouse reports in
+ * `system.tables.sorting_key`. Canonical here because three places check it — the shipper
+ * before every pass, `doctor`, and the room rebuild — and they disagreed once already: the
+ * shipper's guard lived only in `--ensure-schema`, so 137 sessions shipped straight past
+ * it into a stale-key house.
+ *
+ * Two of the five columns are the whole data-safety story, and both were bought with
+ * measured losses:
+ *
+ *   origin — an imported row and a shipped row at the same seq must be TWO rows.
+ *            Without it RMT collapses them and the import loses; 27,948 messages went
+ *            that way on a real house.
+ *   epoch  — a superseded parse and its replacement must be TWO rows, so a re-parse that
+ *            shrinks or diverges can be written WITHOUT deleting what it replaces. This is
+ *            what removed the shipper's DELETE.
+ *
+ * `sessions` is deliberately keyed on neither: it holds exactly one metadata row per
+ * session, and a second one makes sessions_v join messages twice and over-report (measured
+ * on a real house — one duplicate row inflated the totals by 1,764 messages and 655M
+ * tokens).
+ */
+const ROOM_KEYS = {
+  sessions: ['session_id', 'user_id'],
+  messages: ['session_id', 'user_id', 'origin', 'epoch', 'seq'],
+  tool_calls: ['session_id', 'user_id', 'origin', 'epoch', 'idx'],
+};
+
+/**
+ * What is wrong with a room's sorting key, or null when nothing is. `sortingKey` is the
+ * raw `system.tables.sorting_key` value; pass '' for a table that reports none.
+ *
+ * An EXISTING room reporting no sorting key at all is not a MergeTree — a Merge, a View, a
+ * Log engine standing where a room belongs. Skipping that case let a ship pass sail past
+ * its own guard and die later on `DELETE query is not supported for table …`, and let
+ * doctor print "✓ sorting keys carry origin correctly (2/3 rooms)" over a broken house.
+ */
+function keyProblem(type, sortingKey) {
+  const want = ROOM_KEYS[type];
+  if (!want) return `'${type}' is not a room type`;
+  const key = String(sortingKey || '').trim();
+  if (!key) return 'not a MergeTree, so it cannot be shipped to';
+  const have = key.split(',').map((s) => s.trim()).filter(Boolean);
+  if (have.length === want.length && have.every((c, i) => c === want[i])) return null;
+  return `(${key}) — expected (${want.join(', ')})`;
+}
+
 // The one server-side setting a member carries, applied directly on the user with
 // ADD SETTING (bare `ALTER USER … SETTINGS` REPLACES the user's whole list — measured, it
 // wiped an operator-set ceiling; ADD SETTING merges and upserts). There is no settings
@@ -50,14 +144,19 @@ const MEMBER_PIN = 'async_insert = 0 CONST';
 /**
  * The global-install command that will actually work HERE.
  *
- * Every site that printed `npm install -g memhouse --allow-scripts=better-sqlite3` printed
- * a line that fails with EACCES on any distro-packaged Node, because the global prefix is
- * root-owned — measured on a clean Ubuntu machine, exit 243. `sudo` is right for exactly
- * one of the two causes and makes the other worse, and what tells them apart is who owns
- * the prefix — so look, rather than guess.
+ * The flag half of this is gone: the command carried `--allow-scripts=better-sqlite3`
+ * for as long as SQLite was a native module, and omitting it silently cost five
+ * adapters. `node:sqlite` needs no install script, so the base command is now the plain
+ * one everybody already types.
+ *
+ * The `sudo` half stays, because it was never about the flag. A bare install fails with
+ * EACCES on any distro-packaged Node, because the global prefix is root-owned — measured
+ * on a clean Ubuntu machine, exit 243. `sudo` is right for exactly one of the two causes
+ * and makes the other worse, and what tells them apart is who owns the prefix — so look,
+ * rather than guess.
  */
 function installCommand() {
-  const base = 'npm install -g memhouse --allow-scripts=better-sqlite3';
+  const base = 'npm install -g memhouse';
   try {
     const { execFileSync } = require('child_process');
     const prefix = execFileSync('npm', ['prefix', '-g'], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
@@ -83,6 +182,71 @@ function assertUsableName(name, what = 'name') {
   }
 }
 
+/**
+ * One table's CREATE statement, lifted verbatim out of the schema template and renamed.
+ *
+ * Used by the room rebuild, which cannot construct the DDL from a column list: the
+ * sorting key IS the thing being changed, and the text indexes on `messages` carry a
+ * syntax (`TYPE text(tokenizer = ngrams(3))`) that no column-level reconstruction would
+ * reproduce. Taking the statement whole means a migrated room is byte-for-byte the room a
+ * fresh install would create.
+ */
+function createStatement(tpl, table, asName) {
+  // `(?:--[^\n]*\n\s*)*` between the column list and ENGINE: the template comments the
+  // engine choice on some tables, and a pattern demanding `) ENGINE` silently matched
+  // nothing for those — which reads as "the template has no such table".
+  const m = tpl.match(new RegExp(
+    `CREATE TABLE IF NOT EXISTS ${table}\\s*\\([\\s\\S]*?\\n\\)\\s*(?:--[^\\n]*\\n\\s*)*ENGINE[\\s\\S]*?;`, 'm'));
+  if (!m) throw new Error(`the schema template declares no table '${table}'`);
+  return m[0].replace(`CREATE TABLE IF NOT EXISTS ${table}`, `CREATE TABLE ${asName || table}`);
+}
+
+/**
+ * A transcript room restricted to the CURRENT parse of each session — SQL text, usable
+ * wherever the table name would go.
+ *
+ * The shipper keeps superseded parses (see the epoch column in schema.sql.tpl), so the
+ * physical room can hold a session twice: five messages at epoch 0, three at epoch 1.
+ * Reading that raw does not merely show stale rows, it makes every aggregate wrong —
+ * `total_msgs`, token sums, cost, model counts — which is a worse failure than the stale
+ * tail the epoch replaced. The filter is therefore not optional, and it is not left to
+ * each query to remember: `roomNames()` hands out THIS for `messages` / `tool_calls`, and
+ * the bare table only under `messages_raw` / `tool_calls_raw`. A read path nobody thought
+ * to update is correct; a write path nobody updated fails loudly on an insert into a
+ * subquery.
+ *
+ * `origin != 'ship'` first, and it carries the weight: epochs belong to the shipper, and
+ * an imported row sits at epoch 0 forever. Filtering it against the shipper's current
+ * epoch would hide the entire import behind any session that had been compacted once —
+ * the same class of loss as the delete this design removed, arriving as a read that
+ * silently returns less.
+ *
+ * The projection is deliberate: `*` omits MATERIALIZED columns, and the ones this schema
+ * has are all load-bearing. `user_id` is what every consumer scopes by (the rollup JOINs
+ * on it) and `text_ngram` / `text_word` are what `memhouse search` matches against — a
+ * bare `SELECT *` drops all three, and the search fails with `Unknown identifier`.
+ * Listing them costs nothing where they are unused: ClickHouse prunes unread columns out
+ * of a subquery.
+ */
+const ROOM_MATERIALIZED = {
+  messages: ['user_id', 'text_ngram', 'text_word'],
+  tool_calls: ['user_id'],
+};
+
+function currentParse(table, epochSource = table) {
+  const extra = (ROOM_MATERIALIZED[table] || ['user_id']).join(', ');
+  return `(
+    SELECT *, ${extra}
+    FROM ${table} FINAL
+    WHERE origin != 'ship'
+       OR (session_id, user_id, epoch) IN (
+            SELECT session_id, user_id, max(epoch)
+            FROM ${epochSource}
+            WHERE origin = 'ship'
+            GROUP BY session_id, user_id)
+  )`;
+}
+
 /**
  * The session rollup as SQL text, usable in the same `FROM ... AS c` position a view name
  * would occupy. Groups by (session_id, user_id): two housemates' rows never merge, even
@@ -118,7 +282,7 @@ function sessionsRollup({ sessions, messages }) {
         coalesce(sumIf(length(m.text), m.role = 'assistant'), 0) AS assistant_chars,
         coalesce(substring(argMinIf(m.text, m.seq, m.role = 'user' AND m.text != ''), 1, 200), '') AS first_prompt
     FROM ${sessions} AS s FINAL
-    LEFT JOIN ${messages} AS m FINAL ON m.session_id = s.session_id AND m.user_id = s.user_id
+    LEFT JOIN ${messages} AS m ON m.session_id = s.session_id AND m.user_id = s.user_id
     GROUP BY s.session_id, s.user_id
     SETTINGS join_use_nulls = 1
   )`;
@@ -140,7 +304,22 @@ const READ_SETTINGS = { final: 1, join_use_nulls: 1 };
  */
 function roomNames(user) {
   const out = { member: user, user };
-  for (const t of ROOM_TYPES) out[t] = t;
+  // The raw table names — for INSERT, for DDL, and for the shipper's own bookkeeping
+  // reads, which have to see every epoch to decide which one to write next.
+  for (const t of ROOM_TYPES) out[`${t}_raw`] = t;
+  // What everything else gets. `sessions` is unfiltered: it is one metadata row per
+  // session by construction, latest-wins, and carries no epoch anyone may read.
+  out.sessions = 'sessions';
+  out.messages = currentParse('messages');
+  // tool_calls takes its epoch from MESSAGES, not from itself. A parse that produces
+  // messages but NO tool calls is ordinary — a compaction can remove every assistant turn
+  // that called something — and it writes zero rows into this room at the new epoch. Asked
+  // for its own max(epoch), the room would answer with the SUPERSEDED epoch and serve the
+  // old parse's tool calls beside the new parse's messages. Both rooms are written by the
+  // same pass at the same epoch, so messages is the authority for both.
+  out.tool_calls = currentParse('tool_calls', 'messages');
+  // The house's own record of itself — plain names, nothing to filter.
+  for (const t of META_TYPES) { out[t] = t; out[`${t}_raw`] = t; }
   out.sessions_v = sessionsRollup(out);
   return out;
 }
@@ -159,7 +338,9 @@ async function resolveRooms(client) {
 }
 
 module.exports = {
-  ROOM_TYPES, READ_SETTINGS, MEMBER_PIN,
+  ROOM_TYPES, META_TYPES, SCHEMA_VERSION, SUPPORTED_SCHEMAS, MIN_WRITER_SCHEMA,
+  MIGRATIONS, ROOM_KEYS, keyProblem,
+  READ_SETTINGS, MEMBER_PIN,
   installCommand, assertUsableName,
-  sessionsRollup, roomNames, currentUser, resolveRooms,
+  sessionsRollup, currentParse, createStatement, roomNames, currentUser, resolveRooms,
 };

package/memhouse/house/migrate.js

@@ -0,0 +1,277 @@
+// The migration runner — the machinery `memhouse migrate` drives.
+//
+// A schema generation change (SCHEMA_VERSION in house.js) is the one kind of change
+// ensureSchema's column healer cannot roll out in place: sorting keys, engines, and
+// anything else ClickHouse refuses to ALTER. Those are REBUILDS, and a rebuild has a
+// middle, an actor, and an outcome — so each one is a registered migration in
+// ./migrations/<id>.js, and this module runs whichever of them a house still needs.
+//
+// The runner is deliberately transport-free: every entry point takes `q`, an object with
+// `sql(text, settings) -> string` and `rows(text, settings) -> object[]`, injected by the
+// caller (the CLI speaks raw HTTP; a test can speak @clickhouse/client). It never
+// constructs a connection and never reads config.
+//
+// What is a migration and what is not:
+//
+//   additive change (new column, new table, new index)  -> ensureSchema, NOT a migration
+//   rebuild (sorting key, engine, column type)          -> a migration, class 'rebuildRoom'
+//   data transform (backfill, rewrite)                  -> a migration, class 'sql'
+//
+// SCHEMA_VERSION bumps only for the last two.
+//
+// Invariants every migration inherits from the executors here — these were bought with
+// measured losses and are not per-migration choices:
+//
+//   NOTHING IS DELETED. A replaced object is renamed to `<name>_pre_<suffix>` and left
+//   for the pilot to drop. A leftover `__migrating` table from an interrupted run is
+//   never cleared automatically — it may hold the only copy of mid-flight rows.
+//
+//   PROVENANCE IS COPIED, NOT RESTAMPED. `user_id` is MATERIALIZED currentUser(), so a
+//   plain INSERT SELECT would stamp every copied row of a shared house with whoever ran
+//   the migration. The copy lists columns explicitly under
+//   insert_allow_materialized_columns=1, and drops only the derived text_ngram/text_word
+//   (recomputed on insert).
+//
+//   THE SWAP IS ONE STATEMENT. `RENAME TABLE a TO a_pre_x, tmp TO a` is atomic; the
+//   table never stops existing.
+//
+//   WRITES DURING THE COPY SURVIVE. A shipper running through the migration writes into
+//   the old table until the rename; a late-writes pass copies anything newer than the
+//   snapshot, and ReplacingMergeTree makes that idempotent.
+//
+//   EVERYTHING IS RECORDED. One house_events pending row before work, applied/failed
+//   after, per object; schema_version in house_meta only after a migration completes.
+
+const fs = require('fs');
+const path = require('path');
+const { ROOM_TYPES, keyProblem, createStatement } = require('./house');
+
+/**
+ * Every registered migration, in the order they must run. The id's numeric prefix is the
+ * order; the registry refuses duplicates and out-of-order versions at load time rather
+ * than at 2am on someone's house.
+ *
+ * A migration file exports:
+ *   id         '0100-epoch-key' — numeric prefix orders it, the rest names it
+ *   component  which part of memhouse it migrates ('rooms' today; 'daemon', 'config', …
+ *              later). `memhouse migrate` runs all components; `memhouse migrate-rooms`
+ *              filters to 'rooms'.
+ *   toVersion  the SCHEMA_VERSION a house is at once this has run
+ *   detect(q, ctx)        -> what still needs doing (any truthy non-empty value), or
+ *                            null/[] when the house is already past this migration.
+ *                            THE ROOMS ARE THE TRUTH, never house_meta: a hand-migrated
+ *                            house has no record, and a restored backup can carry a
+ *                            record newer than its tables.
+ *   plan(found)           -> lines of human text for the confirm prompt
+ *   steps(found, ctx)     -> [{op: 'rebuildRoom'|'healColumns'|'sql', ...args}]
+ */
+function listMigrations() {
+  const dir = path.join(__dirname, 'migrations');
+  const files = fs.readdirSync(dir).filter((f) => /^\d{4}-.*\.js$/.test(f)).sort();
+  // An EMPTY registry is a broken install, never a current house. Measured: an npm
+  // extraction dropped the one registry file, and `memhouse migrate` on an un-migrated
+  // house then said "nothing to migrate — the house is at schema 2" — the most dangerous
+  // possible reading of a missing file. The registry has carried at least 0100-epoch-key
+  // since it existed; zero entries means the files are gone, not the work.
+  if (!files.length) {
+    throw new Error(`the migration registry at ${dir} is empty — this install is broken.\n`
+      + '  Reinstall memhouse (npm install -g memhouse), then retry.');
+  }
+  const out = files.map((f) => require(path.join(dir, f)));
+  const seen = new Set();
+  let lastVersion = 0;
+  for (const m of out) {
+    // The id is spliced into SQL (house_events predicates) and into kept-table suffixes.
+    // It is repo-controlled, but "repo-controlled" is one compromised dependency away
+    // from "attacker-controlled" — validate like any other identifier.
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(m.id)) throw new Error(`migration id '${m.id}' must match [a-z0-9-]+`);
+    if (seen.has(m.id)) throw new Error(`duplicate migration id '${m.id}'`);
+    seen.add(m.id);
+    if (!(m.toVersion > lastVersion)) {
+      throw new Error(`migration '${m.id}' has toVersion ${m.toVersion}, not above ${lastVersion} — order is the numeric prefix`);
+    }
+    lastVersion = m.toVersion;
+    for (const k of ['component', 'detect', 'plan', 'steps']) {
+      if (!m[k]) throw new Error(`migration '${m.id}' is missing '${k}'`);
+    }
+  }
+  return out;
+}
+
+/**
+ * Which migrations this house still needs, in run order.
+ * @returns [{ migration, found }] — empty when the house is current.
+ */
+async function detectPending(q, ctx, { component = null } = {}) {
+  const pending = [];
+  for (const m of listMigrations()) {
+    if (component && m.component !== component) continue;
+    const found = await m.detect(q, ctx);
+    if (found && (!Array.isArray(found) || found.length)) pending.push({ migration: m, found });
+  }
+  return pending;
+}
+
+/**
+ * Refuse when another actor's run is unfinished. An `applied` newer than the last
+ * `pending` means done; a dangling `pending` means someone is (or was) mid-copy, and two
+ * concurrent rebuilds of one room end with one of them renaming the other's work.
+ * Best-effort: a house without house_events cannot answer, and that is not a reason to
+ * block the migration that will create it.
+ */
+async function unfinishedBy(q, ctx, migrationId) {
+  try {
+    const rows = await q.rows(
+      `SELECT argMax(status, event_at) AS status, argMax(actor, event_at) AS actor,
+              formatDateTime(max(event_at), '%Y-%m-%d %H:%i') AS at
+       FROM house_events WHERE kind = 'migration' AND id = '${migrationId}'`);
+    const r = rows[0];
+    if (r && r.status === 'pending' && r.actor && r.actor !== ctx.member) return r;
+  } catch { /* no events table yet */ }
+  return null;
+}
+
+// ── executors ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Copy a room into one built from the current template, swap atomically, keep the old
+ * one as `<name>_pre_<suffix>`. See the invariants at the top of this file.
+ */
+async function rebuildRoom(q, ctx, { type, name, keepSuffix }, ui) {
+  const tmp = `${name}__migrating`;
+  const kept = `${name}_pre_${keepSuffix}`;
+  for (const clash of [tmp, kept]) {
+    const exists = await q.rows(`SELECT name FROM system.tables WHERE database = '${ctx.db}' AND name = '${clash}'`);
+    if (exists.length) {
+      throw new Error(`${clash} already exists — an earlier migration did not finish.\n`
+        + `  inspect it, then rename or drop it yourself: DROP TABLE ${ctx.db}.${clash}`);
+    }
+  }
+  const before = Number((await q.rows(`SELECT count() AS c FROM ${name} FINAL`))[0]?.c || 0);
+
+  const oldCols = (await q.rows(`SELECT name FROM system.columns WHERE database = '${ctx.db}' AND table = '${name}'`)).map((c) => c.name);
+  await q.sql(createStatement(ctx.tpl, type, tmp), { allow_experimental_full_text_index: 1 });
+  const newCols = (await q.rows(`SELECT name FROM system.columns WHERE database = '${ctx.db}' AND table = '${tmp}'`)).map((c) => c.name);
+  const carried = newCols.filter((c) => oldCols.includes(c) && !['text_ngram', 'text_word'].includes(c));
+  const list = carried.join(', ');
+  const copySettings = { insert_allow_materialized_columns: 1, allow_experimental_full_text_index: 1 };
+  // The snapshot the late-writes pass filters against — taken with a MARGIN. An insert
+  // that began before this timestamp can commit after the big copy has read its parts,
+  // carrying an ingested_at OLDER than the snapshot: filtered at exactly `started`, such
+  // a row is missed by the copy AND the late pass, and dropping the kept table would
+  // then lose it. Five minutes covers any realistic insert-in-flight window, and the
+  // overlap costs nothing — ReplacingMergeTree dedupes re-copied rows.
+  const started = (await q.rows("SELECT toString(now64(3, 'UTC') - INTERVAL 300 SECOND) AS t"))[0].t;
+
+  await q.sql(`INSERT INTO ${tmp} (${list}) SELECT ${list} FROM ${name} FINAL`, copySettings);
+  const copied = Number((await q.rows(`SELECT count() AS c FROM ${tmp}`))[0]?.c || 0);
+  if (copied < before) throw new Error(`copied ${copied} of ${before} rows — refusing to swap`);
+
+  await q.sql(`RENAME TABLE ${name} TO ${kept}, ${tmp} TO ${name}`);
+  let late = false;
+  if (carried.includes('ingested_at')) {
+    try {
+      await q.sql(`INSERT INTO ${name} (${list}) SELECT ${list} FROM ${kept} FINAL WHERE ingested_at >= toDateTime64('${started}', 3, 'UTC')`, copySettings);
+      late = true;
+    } catch (e) {
+      // Best-effort must not mean SILENT. The rows are not lost — they sit in the kept
+      // table — but a shipper that wrote during the copy has its newest rows stranded
+      // there until someone re-runs this insert, and nobody re-runs what nobody was told
+      // about.
+      ui.warn(`${name}: the late-writes pass failed (${e.message.split('\n')[0]})`);
+      ui.warn(`  rows written during the copy are still in ${kept}; recover them with:`);
+      ui.warn(`  INSERT INTO ${name} (${list}) SELECT ${list} FROM ${kept} FINAL WHERE ingested_at >= toDateTime64('${started}', 3, 'UTC')`);
+    }
+  }
+  const after = Number((await q.rows(`SELECT count() AS c FROM ${name} FINAL`))[0]?.c || 0);
+  ui.ok(`${name}: ${after} rows, old room kept as ${kept}`);
+  return { before, after, kept, late };
+}
+
+/**
+ * ADD COLUMN anything the template declares that the live table lacks — for objects a
+ * migration does NOT rebuild. `sessions` keeps its key across schema 2 but still gains
+ * `epoch`; without this, the very next ship opens with a "fields are being DISCARDED"
+ * warning and sends the pilot to a second command.
+ */
+async function healColumns(q, ctx, { type, name }, ui) {
+  const { templateColumns } = require('../shipper/ship');
+  const want = templateColumns(ctx.tpl);
+  const have = new Set((await q.rows(`SELECT name FROM system.columns WHERE database = '${ctx.db}' AND table = '${name}'`)).map((c) => c.name));
+  if (!have.size) return;
+  for (const col of (want[type] || [])) {
+    if (have.has(col.name)) continue;
+    await q.sql(`ALTER TABLE ${name} ADD COLUMN IF NOT EXISTS ${col.name} ${col.type}`,
+      { allow_experimental_full_text_index: 1 });
+    ui.ok(`${name}: added missing column ${col.name}`);
+  }
+}
+
+const EXECUTORS = { rebuildRoom, healColumns, sql: async (q, ctx, { statement }, ui) => { await q.sql(statement); } };
+
+/**
+ * Run one pending migration: ledger pending -> steps -> ledger applied (or failed and
+ * rethrow). `ledger` is injected ({ event(fields), meta(key, value) }, both best-effort)
+ * because the record must never be the reason a rebuild fails.
+ */
+async function runMigration(q, ctx, { migration, found }, { ledger, ui }) {
+  // One migration-level pending marker FIRST, before any step. The per-step pair below
+  // records progress; this one exists for the OTHER migrator — unfinishedBy() reads it,
+  // and without it two `memhouse update`s sitting at their confirm prompts both saw a
+  // clean ledger and both proceeded on yes. (The room-level clash checks still make the
+  // race non-destructive — the loser fails on __migrating/CREATE — but failing cleanly
+  // beats failing confusingly.)
+  await ledger.event({
+    kind: 'migration', id: migration.id, status: 'pending', host: ctx.host,
+    to_version: String(migration.toVersion), detail: 'migration started',
+  });
+  const steps = migration.steps(found, ctx);
+  for (const step of steps) {
+    const exec = EXECUTORS[step.op];
+    if (!exec) throw new Error(`migration '${migration.id}' names unknown op '${step.op}'`);
+    const label = step.name || step.op;
+    // One event pair per step that MOVES data; heal/sql steps ride on the migration's own.
+    const record = step.op === 'rebuildRoom';
+    if (record) {
+      await ledger.event({
+        kind: 'migration', id: migration.id, status: 'pending', host: ctx.host,
+        to_version: String(migration.toVersion), detail: `${label}`,
+      });
+    }
+    try {
+      const r = await exec(q, ctx, step, ui);
+      if (record) {
+        await ledger.event({
+          kind: 'migration', id: migration.id, status: 'applied', host: ctx.host,
+          to_version: String(migration.toVersion),
+          rows_before: r?.before || 0, rows_after: r?.after || 0,
+          detail: `${label}: old room kept as ${r?.kept}${r?.late ? '; late writes copied' : ''}`,
+        });
+      }
+    } catch (e) {
+      if (record) {
+        await ledger.event({
+          kind: 'migration', id: migration.id, status: 'failed', host: ctx.host,
+          to_version: String(migration.toVersion), detail: `${label}: ${e.message}`,
+        });
+      }
+      // The MIGRATION-LEVEL failed row, always — the pending marker written before the
+      // steps is what unfinishedBy() reads, and left dangling it locked every OTHER
+      // member out of `memhouse migrate` forever, with advice (clean the __migrating
+      // leftovers) that did not touch the actual lock. argMax(status) = 'failed'
+      // unblocks; the next run re-detects and retries.
+      await ledger.event({
+        kind: 'migration', id: migration.id, status: 'failed', host: ctx.host,
+        to_version: String(migration.toVersion), detail: `migration failed at ${label}: ${e.message}`,
+      });
+      throw e;
+    }
+  }
+  await ledger.event({
+    kind: 'migration', id: migration.id, status: 'applied', host: ctx.host,
+    to_version: String(migration.toVersion), detail: 'migration completed',
+  });
+  await ledger.meta('schema_version', String(migration.toVersion));
+}
+
+module.exports = { listMigrations, detectPending, unfinishedBy, runMigration, EXECUTORS };

package/memhouse/house/migrations/0100-epoch-key.js

@@ -0,0 +1,68 @@
+// Schema 1 -> 2: `epoch` joins the transcript rooms' sorting keys.
+//
+// The shipper became insert-only in 0.10.0 — a re-parse that shrinks or diverges is
+// written under a new epoch instead of over the stored parse — and ReplacingMergeTree
+// collapses on the sorting key, so the epoch must BE in the key or the new parse and the
+// old one are the same rows and the old one loses through the merge. ORDER BY cannot be
+// altered in place; hence this rebuild.
+//
+// `sessions` keeps its key (one metadata row per session, deliberately) but gains the
+// `epoch` column, so it is healed rather than rebuilt.
+
+const { ROOM_TYPES, keyProblem } = require('../house');
+
+module.exports = {
+  id: '0100-epoch-key',
+  component: 'rooms',
+  toVersion: 2,
+
+  async detect(q, ctx) {
+    const found = [];
+    for (const t of ROOM_TYPES) {
+      const name = ctx.rooms[`${t}_raw`];
+      const rows = await q.rows(`SELECT sorting_key AS k FROM system.tables WHERE database = '${ctx.db}' AND name = '${name}'`);
+      // A missing room is install's problem, not a migration's — there is nothing to carry.
+      if (!rows.length) continue;
+      const problem = keyProblem(t, rows[0].k);
+      if (problem) { found.push({ t, name, key: rows[0].k, rebuild: true }); continue; }
+      // A correct key is not the whole generation: `sessions` keeps its key and gains
+      // `epoch` by ALTER. Detect keyed on keys alone went blind to a failed heal — a run
+      // that died between the last rebuild and the column heal re-detected as "nothing
+      // pending", stamped schema 2, and the missing column stayed missing while the
+      // failure text promised that re-running was enough.
+      const cols = await q.rows(`SELECT name FROM system.columns WHERE database = '${ctx.db}' AND table = '${name}' AND name = 'epoch'`);
+      if (!cols.length) found.push({ t, name, healOnly: true });
+    }
+    return found;
+  },
+
+  plan(found) {
+    const rebuilds = found.filter((x) => x.rebuild);
+    const heals = found.filter((x) => x.healOnly);
+    return [
+      ...(rebuilds.length ? [
+        `These rooms predate schema ${this.toVersion} and the shipper refuses to write into them:`,
+        '',
+        ...rebuilds.map((x) => `  ${x.name}  (${x.key})`),
+        '',
+        'Each is copied into a room with the current key, swapped in atomically, and the',
+        'old one kept as <room>_pre_epoch. Nothing is deleted — you drop those when ready.',
+      ] : []),
+      ...(heals.length ? [
+        `These rooms keep their key but are missing this generation's columns (added in place):`,
+        ...heals.map((x) => `  ${x.name}`),
+      ] : []),
+    ];
+  },
+
+  steps(found, ctx) {
+    const rebuilds = found.filter((x) => x.rebuild);
+    return [
+      ...rebuilds.map((x) => ({ op: 'rebuildRoom', type: x.t, name: x.name, keepSuffix: 'epoch' })),
+      // Heal EVERY room the rebuild does not touch — the detected healOnly ones and the
+      // already-correct rest alike; ADD COLUMN IF NOT EXISTS makes the latter free.
+      ...ROOM_TYPES.filter((t) => !rebuilds.some((x) => x.t === t))
+        .map((t) => ({ op: 'healColumns', type: t, name: ctx.rooms[`${t}_raw`] })),
+    ];
+  },
+};