create-walle 0.10.2 → 0.10.3

package/template/wall-e/brain/brain-sync-membership.js

@@ -0,0 +1,20 @@
+'use strict';
+
+// shared-memory D-5 (wall-e/docs/shared-memory-every-machine-2026-10-31.html): the READ side of the
+// durable "this node is a member" marker. Kept apart from brain/brain-sync-v2.js (which writes it) so
+// that placement checks inside scheduler worker jobs (lib/derivation-home.js) never pull write code
+// into the worker-job module set (tests/worker-job-direct-write-gate.test.js). Host-local kv, never
+// replicated.
+const MEMBERSHIP_KEY = 'brain_sync.membership';
+
+function readMembership(db) {
+  const row = db.prepare('SELECT value FROM kv_store WHERE key = ?').get(MEMBERSHIP_KEY);
+  if (!row || !row.value) return null;
+  try {
+    return JSON.parse(row.value);
+  } catch {
+    return null; // HANDLE: a corrupt marker reads as "no marker"; the next home round rewrites it
+  }
+}
+
+module.exports = { MEMBERSHIP_KEY, readMembership };

package/template/wall-e/brain/brain-sync-store.js

@@ -1,8 +1,9 @@
 'use strict';
 
-// multi-machine WP-5: the storage-layer half of the brain outbox (no DDL here — that is
-// brain/schema.js ensureBrainSyncSchema). The capture triggers record only (table, id, clock);
-// everything that reads a replicated ROW lives in this module so that raw SQL against the
+// multi-machine WP-5: the storage-layer half of brain sync (no DDL here — that is
+// brain/schema.js / brain/brain-sync-v2-schema.js). The v1 outbox transport is retired
+// (WP-6); what remains is the replicated-row reader and the v2 clock host-local helpers.
+// Everything that reads a replicated ROW lives in this module so that raw SQL against the
 // replicated tables stays in the storage layer (tests/knowledge-read-bounds.test.js).
 
 const REPLICATED_TABLES = Object.freeze(['memories', 'knowledge', 'entities', 'people']);
@@ -22,8 +23,8 @@ function knowledgeRowExists(db, id) {
   return !!db.prepare('SELECT 1 AS hit FROM knowledge WHERE id = ?').get(id);
 }
 
-// This brain's own instance id — the value the triggers could not stamp cheaply ('' in
-// brain_row_clock / brain_outbox means "this host"). Same precedence as
+// This brain's own instance id — the value the capture trigger cannot stamp cheaply ('' in
+// brain_row_clock means "this host"). Same precedence as
 // lib/brain-host-identity.js: the kv identity record, then the owner table.
 function localBrainInstanceId(db) {
   try {
@@ -40,110 +41,163 @@ function localBrainInstanceId(db) {
   }
 }
 
-// Follow-up #16: history backfill. Rows that predate the capture triggers (migration 89) never
-// had an outbox row; the outbox READ enqueues them a bounded page at a time (sync-api.js
-// listBrainOutbox), so there is no scheduler job, no boot work and no migration. The per-table
-// rowid cursor is host-local state in kv_store (no capture trigger exists on kv_store).
-//
-// Order: entities, people, knowledge, memories. knowledge walks rowid DESCENDING — every
-// superseded_by target has a higher rowid than the row pointing at it (measured on the live
-// brain), so a target always travels first and the receiver never drops the pointer
-// (brain_fk_dropped). `after` is the last rowid enqueued (for knowledge: the rows still to go
-// are BELOW it; null = not started).
-const BACKFILL_KEY = 'brain_sync.backfill';
-const BACKFILL_ORDER = Object.freeze(['entities', 'people', 'knowledge', 'memories']);
-const BACKFILL_DESCENDING = new Set(['knowledge']);
-// History loses to any real captured edit (LWW compares the clock first); two backfills of the
-// same id on two hosts tiebreak deterministically by origin id.
+// WP-0 (§5 D-3/D-4/D-8, §6.3): the CLOCK seed walk — the v2 replacement for v1's history
+// backfill (WP-6 deletes that walk). It exists because a row whose clock row is missing
+// (written before the v2 triggers, or before this host knew its own instance id) is not
+// ADDRESSABLE — a peer asks "everything from origin X after seq N" and never learns it exists.
+// One clock row per replicated row, bounded page per call, host-local cursor in kv_store, one
+// transaction per call. Nothing here fires a capture trigger — brain_row_clock,
+// brain_local_seq, brain_vv and kv_store carry none — so the sentinel is not needed either.
+const CLOCK_SEED_KEY = 'brain_sync.clock_seed';
+// History loses to any real captured edit (LWW compares the clock first); two seeds of the
+// same id on two hosts tiebreak deterministically by origin id. Shared with the seed walk.
 const BACKFILL_CLOCK = '1970-01-01T00:00:00.000Z';
+// entities, people, knowledge, memories; knowledge walks rowid DESCENDING, because every
+// superseded_by target has a higher rowid than the row pointing at it.
+const CLOCK_SEED_ORDER = Object.freeze(['entities', 'people', 'knowledge', 'memories']);
+const CLOCK_SEED_DESCENDING = new Set(['knowledge']);
 
-function readBackfillState(db) {
+// Read side for WP-1 (and the job's own no-op check): where the walk is, and whether it is over.
+function clockSeedState(db) {
+  const row = db.prepare('SELECT value FROM kv_store WHERE key = ?').get(CLOCK_SEED_KEY);
   let parsed = {};
-  const row = db.prepare('SELECT value FROM kv_store WHERE key = ?').get(BACKFILL_KEY);
   if (row && row.value) {
     try {
       parsed = JSON.parse(row.value) || {};
     } catch {
-      parsed = {}; // HANDLE: a corrupt cursor restarts the walk from the top — a re-send is idempotent on the receiver
+      parsed = {}; // HANDLE: a corrupt cursor restarts the walk from the top — every re-seed is idempotent (ON CONFLICT DO NOTHING)
     }
   }
-  const state = {};
-  for (const table of BACKFILL_ORDER) {
-    const entry = parsed[table] && typeof parsed[table] === 'object' ? parsed[table] : {};
-    state[table] = { after: Number.isInteger(entry.after) ? entry.after : null, done: entry.done === true };
-  }
-  return state;
+  return {
+    done: parsed.done === true,
+    table: CLOCK_SEED_ORDER.includes(parsed.table) ? parsed.table : CLOCK_SEED_ORDER[0],
+    after: Number.isInteger(parsed.after) ? parsed.after : null,
+  };
 }
 
-function _writeBackfillState(db, state) {
+function _writeClockSeedState(db, state) {
   db.prepare(`
     INSERT INTO kv_store (key, value, updated_at) VALUES (?, ?, datetime('now'))
     ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at
-  `).run(BACKFILL_KEY, JSON.stringify(state));
+  `).run(CLOCK_SEED_KEY, JSON.stringify(state));
+}
+
+// The same self-initialising counter the capture triggers use, so a seed and a live write can
+// never mint the same seq for two different rows.
+function _nextLocalSeq(db) {
+  db.prepare(`
+    INSERT INTO brain_local_seq (id, next_seq) VALUES (1, 1)
+    ON CONFLICT(id) DO UPDATE SET next_seq = next_seq + 1
+  `).run();
+  return Number(db.prepare('SELECT next_seq FROM brain_local_seq WHERE id = 1').get().next_seq);
+}
+
+function _bumpLocalVv(db, originInstanceId, seq) {
+  if (!(seq > 0)) return;
+  db.prepare(`
+    INSERT INTO brain_vv (origin_instance_id, max_seq) VALUES (?, ?)
+    ON CONFLICT(origin_instance_id) DO UPDATE SET max_seq = MAX(max_seq, excluded.max_seq)
+  `).run(originInstanceId, seq);
 }
 
-function _backfillRows(db, table, after, limit) {
-  if (BACKFILL_DESCENDING.has(table)) {
-    if (after == null) return db.prepare(`SELECT rowid AS rid, id FROM "${table}" ORDER BY rowid DESC LIMIT ?`).all(limit);
-    return db.prepare(`SELECT rowid AS rid, id FROM "${table}" WHERE rowid < ? ORDER BY rowid DESC LIMIT ?`).all(after, limit);
+// Up to `limit` rows of one replicated table that have NO clock row, in walk order.
+function _clockSeedRows(db, table, after, limit) {
+  const missing = `NOT EXISTS (SELECT 1 FROM brain_row_clock c WHERE c.table_name = '${table}' AND c.row_id = t.id)`;
+  if (CLOCK_SEED_DESCENDING.has(table)) {
+    return db.prepare(`SELECT t.rowid AS rid, t.id AS id FROM "${table}" t WHERE ${missing} AND t.rowid < ? ORDER BY t.rowid DESC LIMIT ?`)
+      .all(after == null ? Number.MAX_SAFE_INTEGER : after, limit);
   }
-  return db.prepare(`SELECT rowid AS rid, id FROM "${table}" WHERE rowid > ? ORDER BY rowid ASC LIMIT ?`).all(after == null ? 0 : after, limit);
+  return db.prepare(`SELECT t.rowid AS rid, t.id AS id FROM "${table}" t WHERE ${missing} AND t.rowid > ? ORDER BY t.rowid ASC LIMIT ?`)
+    .all(after == null ? 0 : after, limit);
 }
 
-// Enqueue at most `budget` historical rows into brain_outbox, in one transaction with the cursor.
-// A row with no brain_row_clock is stamped with the sentinel clock and origin '' (this host); a row
-// that already has a clock keeps it. Rows already captured live may be enqueued a second time —
-// the receiver's apply is idempotent, so there is deliberately no dedup scan. The writes here
-// touch only brain_outbox / brain_row_clock / kv_store, none of which carries a capture trigger.
-function enqueueBackfillPage(db, budget) {
-  let remaining = Math.max(0, Math.floor(Number(budget) || 0));
-  const state = readBackfillState(db);
-  if (!remaining || BACKFILL_ORDER.every((table) => state[table].done)) return { enqueued: 0, backfill: state };
-  let enqueued = 0;
+// The v1 clock rows still carry '' ("this host") and often seq 0. Adopt them: once the origin is
+// the local id the row is addressable, and the ones that already have a seq keep it (only a 0
+// gets a fresh one). Bounded by the caller's budget, and resumable for free — an adopted row no
+// longer matches `origin_instance_id = ''`, so the next call continues where this one stopped.
+function _adoptUnknownOriginPage(db, localId, budget) {
+  const select = db.prepare(`
+    SELECT row_id AS rowId, origin_seq AS originSeq FROM brain_row_clock
+    WHERE table_name = ? AND origin_instance_id = '' ORDER BY rowid ASC LIMIT ?
+  `);
+  const adopt = db.prepare('UPDATE brain_row_clock SET origin_instance_id = ?, origin_seq = ? WHERE table_name = ? AND row_id = ?');
+  let adopted = 0;
+  let maxSeq = 0;
+  for (const table of REPLICATED_TABLES) {
+    if (adopted >= budget) break;
+    for (const row of select.all(table, budget - adopted)) {
+      const seq = Number(row.originSeq) > 0 ? Number(row.originSeq) : _nextLocalSeq(db);
+      adopt.run(localId, seq, table, row.rowId);
+      maxSeq = Math.max(maxSeq, seq);
+      adopted += 1;
+    }
+  }
+  _bumpLocalVv(db, localId, maxSeq);
+  return adopted;
+}
+
+// One bounded, resumable page of the clock seed walk. `limit` is the row budget for the WHOLE
+// call (adoptions and seeds together), so a caller can bound the work it is about to do —
+// job-driven, never boot-driven.
+function seedClockPage(db, { limit = 2000 } = {}) {
+  const budget = Math.max(0, Math.floor(Number(limit) || 0));
+  const state = clockSeedState(db);
+  const localId = localBrainInstanceId(db);
+  // No identity yet: nothing can be addressed, and guessing one would fork this host's seq
+  // space. The job stays pending (done: false) until the boot write lands.
+  if (!localId) {
+    return { seeded: 0, rewritten: 0, done: false, table: state.table, reason: 'identity_unknown' };
+  }
+  if (state.done || budget === 0) return { seeded: 0, rewritten: 0, done: state.done, table: state.table };
+
+  const stamp = db.prepare(`
+    INSERT INTO brain_row_clock (table_name, row_id, updated_at, origin_instance_id, origin_seq, deleted)
+    VALUES (?, ?, ?, ?, ?, 0)
+    ON CONFLICT(table_name, row_id) DO NOTHING
+  `);
+  let seeded = 0;
+  let rewritten = 0;
+  let table = state.table;
+  let after = state.after;
+  let done = false;
   db.transaction(() => {
-    const clockOf = db.prepare('SELECT updated_at, origin_instance_id FROM brain_row_clock WHERE table_name = ? AND row_id = ?');
-    const stamp = db.prepare(`
-      INSERT INTO brain_row_clock (table_name, row_id, updated_at, origin_instance_id) VALUES (?, ?, ?, '')
-      ON CONFLICT(table_name, row_id) DO NOTHING
-    `);
-    const enqueue = db.prepare(`
-      INSERT INTO brain_outbox (operation_id, table_name, row_id, op, updated_at, origin_instance_id)
-      VALUES (lower(hex(randomblob(16))), ?, ?, 'upsert', ?, ?)
-    `);
-    for (const table of BACKFILL_ORDER) {
-      if (!remaining) break;
-      const cursor = state[table];
-      if (cursor.done) continue;
+    rewritten = _adoptUnknownOriginPage(db, localId, budget);
+    let remaining = budget - rewritten;
+    let index = Math.max(0, CLOCK_SEED_ORDER.indexOf(table));
+    let maxSeq = 0;
+    while (remaining > 0 && index < CLOCK_SEED_ORDER.length) {
+      table = CLOCK_SEED_ORDER[index];
       const requested = remaining;
-      const rows = _backfillRows(db, table, cursor.after, requested);
+      const rows = _clockSeedRows(db, table, after, requested);
       for (const row of rows) {
-        cursor.after = Number(row.rid);
+        after = Number(row.rid);
         remaining -= 1;
-        if (row.id == null || row.id === '') continue;
-        const id = String(row.id);
-        let clock = clockOf.get(table, id);
-        if (!clock) {
-          stamp.run(table, id, BACKFILL_CLOCK);
-          clock = { updated_at: BACKFILL_CLOCK, origin_instance_id: '' };
-        }
-        enqueue.run(table, id, String(clock.updated_at || BACKFILL_CLOCK), String(clock.origin_instance_id || ''));
-        enqueued += 1;
+        if (row.id == null || row.id === '') continue; // a rowid with no id is unreachable by a peer; the cursor still moves past it
+        const seq = _nextLocalSeq(db);
+        stamp.run(table, String(row.id), BACKFILL_CLOCK, localId, seq);
+        maxSeq = Math.max(maxSeq, seq);
+        seeded += 1;
+      }
+      if (rows.length < requested) {
+        index += 1;
+        after = null;
       }
-      if (rows.length < requested) cursor.done = true;
     }
-    _writeBackfillState(db, state);
+    done = index >= CLOCK_SEED_ORDER.length;
+    _bumpLocalVv(db, localId, maxSeq);
+    _writeClockSeedState(db, { table, after: done ? null : after, done });
   }).immediate();
-  return { enqueued, backfill: state };
+  return { seeded, rewritten, done, table };
 }
 
 module.exports = {
   REPLICATED_TABLES,
-  BACKFILL_KEY,
-  BACKFILL_ORDER,
   BACKFILL_CLOCK,
+  CLOCK_SEED_KEY,
+  CLOCK_SEED_ORDER,
   readReplicatedRow,
   knowledgeRowExists,
   localBrainInstanceId,
-  readBackfillState,
-  enqueueBackfillPage,
+  clockSeedState,
+  seedClockPage,
 };

package/template/wall-e/brain/brain-sync-v2-schema.js

@@ -0,0 +1,203 @@
+'use strict';
+
+// Sanctioned DDL module (lint/ddl-outside-runner.config.json): the WP-0 v2 brain-sync clock.
+// Invoked only through brain/schema.js ensureBrainSyncSchemaV2 (createTables() and MIGRATIONS[104]).
+// It never requires schema.js (schema.js -> this file is the only edge).
+
+// --- WP-0 (shared-memory-every-machine-2026-10-31.html §5 D-3/D-4/D-8, §6.1) ------
+// The v2 clock. v1's brain_row_clock held only (updated_at, origin_instance_id) —
+// enough to decide WHO wins, not enough to ADDRESS a change: a peer asks "everything
+// from origin X after seq N" (D-3). v2 adds origin_seq + deleted, so the clock row IS
+// the compacted change log (one row per replicated row, latest state only) and a delete
+// leaves a tombstone instead of vanishing (D-8: pruned only once every member's reported
+// vector has passed it). The trigger also maintains brain_local_seq (this node's origin
+// counter) and brain_vv (what this node holds, per origin).
+//
+// Idempotent BY INSPECTION, because createTables() runs it on EVERY boot (fresh and
+// existing alike): the column adds are probed, and the triggers are dropped/recreated
+// only while the installed SQL is still a v1 body (`brain_local_seq` absent). The
+// statements below are shared verbatim by the fresh path (createTables) and migration
+// 104, which is what tests-integration/migration-baseline-parity.test.js compares.
+const BRAIN_SYNC_V2_COLUMNS = Object.freeze([
+  ['origin_seq', 'ALTER TABLE brain_row_clock ADD COLUMN origin_seq INTEGER NOT NULL DEFAULT 0'],
+  // No CHECK on `deleted`: a CHECK would have to be spelled identically on both paths
+  // (ALTER-added here, CREATE TABLE on a future rebuild) to keep the parity test green,
+  // and the only writer is this file's own trigger.
+  ['deleted', 'ALTER TABLE brain_row_clock ADD COLUMN deleted INTEGER NOT NULL DEFAULT 0'],
+]);
+
+// Host-local tables (D-7): never replicated, never taken from a join snapshot. brain_vv
+// is the node's own vector; brain_member_vv is the hub's record of what each member last
+// reported (empty on a member); brain_sync_conflicts is the WP-1 conflict ledger.
+const BRAIN_SYNC_V2_TABLES = `
+    CREATE INDEX IF NOT EXISTS idx_brain_row_clock_origin ON brain_row_clock(origin_instance_id, origin_seq);
+    CREATE TABLE IF NOT EXISTS brain_local_identity (
+      id INTEGER PRIMARY KEY CHECK (id = 1),
+      instance_id TEXT NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS brain_local_seq (
+      id INTEGER PRIMARY KEY CHECK (id = 1),
+      next_seq INTEGER NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS brain_vv (
+      origin_instance_id TEXT PRIMARY KEY,
+      max_seq INTEGER NOT NULL
+    );
+    CREATE TABLE IF NOT EXISTS brain_member_vv (
+      member_instance_id TEXT NOT NULL,
+      origin_instance_id TEXT NOT NULL,
+      max_seq INTEGER NOT NULL,
+      reported_at TEXT NOT NULL,
+      PRIMARY KEY (member_instance_id, origin_instance_id)
+    );
+    CREATE TABLE IF NOT EXISTS brain_sync_conflicts (
+      id INTEGER PRIMARY KEY,
+      at TEXT NOT NULL,
+      reason TEXT NOT NULL CHECK (reason IN ('lww_lost','memory_identity_conflict','brain_fk_dropped','brain_table_unknown')),
+      table_name TEXT NOT NULL,
+      row_id TEXT NOT NULL,
+      origin_instance_id TEXT NOT NULL,
+      origin_seq INTEGER NOT NULL,
+      detail TEXT NOT NULL DEFAULT ''
+    );
+  `;
+
+// The 12 capture triggers (ai / au / ad per replicated table), replacing v1's 8: same
+// names, same WHEN sentinel, same watch columns for _au (a column a migration added is
+// never named — ALTER TABLE DROP COLUMN dies while a trigger names it), plus the body
+// that stamps the clock, bumps the sequence and maintains the vector. WP-6 (migration
+// 105) removed the v1 outbox INSERT the ai/au bodies used to append.
+//
+// A trigger must never make a user write fail. The self-initialising `INSERT ... VALUES
+// (1, 1) ON CONFLICT DO UPDATE SET next_seq = next_seq + 1` and the COALESCE to '' make
+// every body legal even on a brain whose brain_local_identity row does not exist yet
+// ('' keeps meaning "this host" — the v1 convention — until migration 104's boot write
+// lands).
+// The columns whose change is a replication event (the _au WATCH list). Also the columns the
+// WP-1 digest compares: unwatched columns (read stamps, local classifier output) legitimately
+// differ between machines and never replicate after the insert.
+const BRAIN_SYNC_WATCH_COLUMNS = Object.freeze({
+  memories: Object.freeze(['content', 'content_raw', 'subject', 'metadata', 'importance', 'archived_at']),
+  knowledge: Object.freeze(['category', 'subject', 'predicate', 'object', 'confidence', 'source_memory_ids', 'status', 'superseded_by', 'valid_from', 'valid_to', 'last_confirmed', 'times_confirmed']),
+  entities: Object.freeze(['canonical_name', 'entity_type', 'aliases', 'properties', 'updated_at']),
+  people: Object.freeze(['name', 'aliases', 'identities', 'relationship', 'trust_level', 'trust_reason', 'interaction_freq', 'last_interaction', 'notes']),
+});
+
+function buildBrainSyncV2Triggers() {
+  const skipWhen = "NOT EXISTS (SELECT 1 FROM pragma_table_list WHERE name = 'brain_sync_applying')";
+  const watchColumns = BRAIN_SYNC_WATCH_COLUMNS;
+  let sql = '';
+  for (const table of Object.keys(watchColumns)) {
+    const watch = watchColumns[table].map((column) => `"${column}"`).join(', ');
+    const body = (row, deleted) => `
+      INSERT INTO brain_local_seq (id, next_seq) VALUES (1, 1)
+      ON CONFLICT(id) DO UPDATE SET next_seq = next_seq + 1;
+      INSERT INTO brain_row_clock (table_name, row_id, updated_at, origin_instance_id, origin_seq, deleted)
+      VALUES ('${table}', ${row}, strftime('%Y-%m-%dT%H:%M:%fZ', 'now'),
+              COALESCE((SELECT instance_id FROM brain_local_identity WHERE id = 1), ''),
+              (SELECT next_seq FROM brain_local_seq WHERE id = 1), ${deleted})
+      ON CONFLICT(table_name, row_id) DO UPDATE SET
+        updated_at = excluded.updated_at,
+        origin_instance_id = excluded.origin_instance_id,
+        origin_seq = excluded.origin_seq,
+        deleted = excluded.deleted;
+      INSERT INTO brain_vv (origin_instance_id, max_seq)
+      VALUES (COALESCE((SELECT instance_id FROM brain_local_identity WHERE id = 1), ''),
+              (SELECT next_seq FROM brain_local_seq WHERE id = 1))
+      ON CONFLICT(origin_instance_id) DO UPDATE SET max_seq = MAX(max_seq, excluded.max_seq);`;
+    // WP-6 (migration 105): the ai/au bodies stamp only the clock/seq/vv — the v1 outbox
+    // INSERT they used to append is gone, and so is the table it wrote to.
+    const live = body('new.id', '0');
+    sql += `
+      DROP TRIGGER IF EXISTS brain_outbox_${table}_ai;
+      CREATE TRIGGER IF NOT EXISTS brain_outbox_${table}_ai AFTER INSERT ON ${table}
+      WHEN ${skipWhen}
+      BEGIN${live}
+      END;
+      DROP TRIGGER IF EXISTS brain_outbox_${table}_au;
+      CREATE TRIGGER IF NOT EXISTS brain_outbox_${table}_au AFTER UPDATE OF ${watch} ON ${table}
+      WHEN ${skipWhen}
+      BEGIN${live}
+      END;
+      DROP TRIGGER IF EXISTS brain_outbox_${table}_ad;
+      CREATE TRIGGER IF NOT EXISTS brain_outbox_${table}_ad AFTER DELETE ON ${table}
+      WHEN ${skipWhen}
+      BEGIN${body('old.id', '1')}
+      END;
+    `;
+  }
+  return sql;
+}
+
+const BRAIN_SYNC_V2_TRIGGERS = buildBrainSyncV2Triggers();
+// The one string a v1 trigger body does NOT contain — the installed-SQL probe below.
+const BRAIN_SYNC_V2_MARKER = 'brain_local_seq';
+
+// What the installed schema already has: the brain_row_clock columns and the capture
+// trigger bodies. Asked through better-sqlite3's own APIs (pragma(), sqlite_master) —
+// the same probe brain.js's `_columnExists` makes.
+//
+// The fallback matters: tests/brain-schema-module.test.js drives createTables() with a
+// recording stub that implements only exec()/prepare(), so the probe throws there instead
+// of answering, and "the v1 shape is installed" (columns missing, no triggers) is the
+// right answer — the module then executes the fresh-install statements, each of which is
+// IF NOT EXISTS / DROP IF EXISTS, and the DDL it records is the DDL a fresh install gets.
+function _readBrainSyncInstalledSchema(d) {
+  try {
+    const columns = new Set((d.pragma('table_info(brain_row_clock)') || []).map((row) => row.name));
+    const triggers = d.prepare("SELECT sql FROM sqlite_master WHERE type = 'trigger' AND name LIKE 'brain_outbox_%'")
+      .all().map((row) => String(row.sql || '')).join('\n');
+    return { columns, triggers };
+  } catch {
+    return { columns: null, triggers: '' }; // HANDLE: a handle that cannot answer queries — treat as an un-upgraded schema
+  }
+}
+
+// The v2 half of migration 104's body (schema.js ensureBrainSyncSchemaV2 runs the v1 DDL
+// first, then this). createTables() runs it on every boot, so it must be a no-op on a
+// database that already has the columns and the v2 triggers.
+function applyBrainSyncSchemaV2(d) {
+  const installed = _readBrainSyncInstalledSchema(d);
+  for (const [column, sql] of BRAIN_SYNC_V2_COLUMNS) {
+    if (!installed.columns || !installed.columns.has(column)) d.exec(sql);
+  }
+  d.exec(BRAIN_SYNC_V2_TABLES);
+  if (!installed.triggers.includes(BRAIN_SYNC_V2_MARKER)) d.exec(BRAIN_SYNC_V2_TRIGGERS);
+}
+
+// --- WP-6 (migration 105): retire the v1 outbox transport -------------------------
+// v1's outbox was the delivery mechanism until WP-1's version-vector feed replaced it;
+// nothing drained it any more (observed 2026-10-31: hub 16,556 rows, box 35,526), and it
+// was the only reason every brain write carried a second INSERT. Migration 105 deletes it
+// completely: the three tables and the outbox INSERT the ai/au capture bodies used to
+// append. v2 behaviour (clock/seq/vv) is untouched — the ai/au bodies are otherwise
+// byte-identical.
+//
+// The one statement a v1/pre-105 trigger body has and the v2 body does not — the probe below.
+const BRAIN_SYNC_OUTBOX_INSERT = 'INSERT INTO brain_outbox';
+// DROP order matters only for readability; IF EXISTS makes a re-run (and a fresh install,
+// where none of the three ever existed) a no-op.
+const BRAIN_SYNC_V1_DROP_SQL = `
+    DROP TABLE IF EXISTS brain_outbox;
+    DROP TABLE IF EXISTS brain_sync_hwm;
+    DROP TABLE IF EXISTS brain_sync_applied;
+  `;
+
+// Migration 105's body. createTables() runs it on every boot, so it must be a no-op on a
+// database that already has outbox-free triggers and no v1 tables.
+function applyBrainSyncSchemaV3(d) {
+  // Recreate the 8 ai/au triggers only while the installed SQL still carries the outbox
+  // INSERT. Dropping the tables first would leave a body that references a missing table
+  // (legal in SQLite until it fires, but a landmine), so the recreate comes first.
+  const installed = _readBrainSyncInstalledSchema(d);
+  if (installed.triggers.includes(BRAIN_SYNC_OUTBOX_INSERT)) d.exec(BRAIN_SYNC_V2_TRIGGERS);
+  d.exec(BRAIN_SYNC_V1_DROP_SQL);
+}
+
+module.exports = {
+  applyBrainSyncSchemaV2,
+  applyBrainSyncSchemaV3,
+  BRAIN_SYNC_V2_TRIGGERS,
+  BRAIN_SYNC_V2_MARKER,
+  BRAIN_SYNC_WATCH_COLUMNS,
+};