create-walle 0.10.2 → 0.10.3

package/template/wall-e/http/sync-api.js

@@ -1,66 +1,91 @@
 'use strict';
 
-// WP-5 (multi-machine-login-resume-sync-2026-10-18 §6.6, R-10/R-11): the Wall-E
-// half of the brain sync pair.
-//
-//   GET  /api/walle/sync/outbox?after_seq=N&limit=M   -- this host's brain outbox
-//   POST /api/walle/sync/apply  { sourceInstanceId, entries:[...] }
-//   POST /api/walle/sync/prune  { throughSeq }   -- outbox retention (follow-up #17)
-//
-// The `/api/wall-e/...` spellings are accepted as aliases; the CTM worker calls
-// the doc's `/api/walle/...` form.
-//
-// AUTH: a bearer that matches the CTM peer token is required, and loopback alone
-// is NOT enough. The laptop pushes to the Spark through the ssh LocalForward
-// (`bin/spark-home-forward.sh`), so the request arrives on the Spark as a
-// loopback request — the same hole WP-4 F7 closed on CTM
-// (coding-task-manager/lib/auth-context.js `_syncCredentialPresented`). Both
-// spellings of the token env are read: CTM_SYNC_PEER_TOKEN (one peer) and
-// CTM_SYNC_PEER_TOKENS (the `peerId=token` / JSON map form the CTM side parses in
-// lib/hosted-sync-worker.js).
+// Wall-E's half of the brain sync pair — now the v2 version-vector feed only (WP-1). The
+// v1 outbox routes (`/api/walle/sync/{outbox,apply,prune}` + the `/api/wall-e/` aliases),
+// their env-token peer auth and the outbox storage were retired in WP-6 (migration 105).
 //
 // WRITES: brain row writes belong to the brain owner process. The route resolves
 // the owner worker client first (lib/brain-owner-worker-client) and only falls
 // back to the in-process brain module when no owner client exists (dev, tests, a
 // single-process host) or when the owner refuses the call as not whitelisted —
-// see _callLocalBrain. Everything a batch writes happens inside ONE
-// `db.transaction(...).immediate()` in applyBrainSyncEntries, with the
+// see callLocalBrain. Everything a v2 apply writes happens inside ONE
+// `db.transaction(...).immediate()` in brain-sync-v2.js, with the
 // connection-scoped TEMP TABLE `brain_sync_applying` present for its duration so
-// the capture triggers cannot re-enqueue what we just applied.
+// the capture triggers cannot re-stamp what we just applied.
 //
-// The DDL for the four sync tables and the eight triggers lives in the
-// runner-owned ladder: migration 89 in wall-e/brain/migrations.js, whose text is
-// brain/schema.js's BRAIN_SYNC_DDL (the sanctioned DDL module). This file owns NO
-// DDL — the apply-batch sentinel's CREATE/DROP TEMP TABLE text is
+// This file owns NO DDL — the apply-batch sentinel's CREATE/DROP TEMP TABLE text is
 // schema.createBrainSyncSentinel / dropBrainSyncSentinel.
 
-const { strFlag } = require('../lib/env-flags');
-const { createBrainSyncSentinel, dropBrainSyncSentinel } = require('../brain/schema');
-const brainSyncStore = require('../brain/brain-sync-store');
-
-const SYNC_PATHS = new Set([
-  '/api/walle/sync/outbox',
-  '/api/walle/sync/apply',
-  '/api/wall-e/sync/outbox',
-  '/api/wall-e/sync/apply',
-  '/api/walle/sync/prune',
-  '/api/wall-e/sync/prune',
-]);
-
-const REPLICATED_TABLES = brainSyncStore.REPLICATED_TABLES;
-const APPLY_SENTINEL_TABLE = 'brain_sync_applying';
-const DEFAULT_LIMIT = 100;
-const MAX_LIMIT = 1000;
-// Follow-up #17: one prune call deletes at most this many rows per table, so a backlog of a
-// few hundred thousand outbox rows drains over several ticks instead of one long write lock.
-const PRUNE_CHUNK = 5000;
-const APPLIED_RETENTION_DAYS = 7;
+const { strFlag, boolFlag } = require('../lib/env-flags');
+const { resolveCtmDataDir } = require('../lib/ctm-data-dir');
+const { requireBearer } = require('./auth');
+const { isLoopbackRequest } = require('../shared/request-provenance');
+
+// WP-1 (shared-memory-every-machine-2026-10-31.html §6.4, D-12): the v2 change feed. Loopback +
+// the LOCAL Wall-E token only — a peer never calls these directly (its CTM does, with the
+// pool credential), so a tunnel-forwarded request is refused even with a valid token. The
+// storage half lives in brain/brain-sync-v2.js and runs on the owner's connection.
+const V2_ROUTE_SPECS = Object.freeze({
+  vector: { method: 'GET', op: 'brainSyncV2Vector' },
+  changes: { method: 'POST', op: 'brainSyncV2Changes' },
+  apply: { method: 'POST', op: 'brainSyncV2Apply' },
+  'member-vector': { method: 'POST', op: 'brainSyncV2MemberVector' },
+  'prune-tombstones': { method: 'POST', op: 'brainSyncV2PruneTombstones' },
+  digest: { method: 'GET', op: 'brainSyncV2Digest' },
+  // WP-4 §6.7: the join trio. The home serves the snapshot; the member records the import and
+  // lets the brain-join-import job drive the pages. Same gate as every other v2 route.
+  'join/snapshot': { method: 'POST', op: 'brainSyncV2JoinSnapshot' },
+  'join/import': { method: 'POST', op: 'brainSyncV2JoinImport' },
+  'join/status': { method: 'GET', op: 'brainSyncV2JoinStatus' },
+});
+const V2_PATH_PREFIXES = Object.freeze(['/api/walle/sync/v2/', '/api/wall-e/sync/v2/']);
+// §6.4: JSON bodies are capped at 8 MiB and one apply carries at most 2000 entries.
+const V2_MAX_BODY_BYTES = 8 * 1024 * 1024;
+const V2_MAX_ENTRIES = 2000;
+// lib/env-flags.js's own falsy set — an injected env (tests) must parse exactly the same way
+// as boolFlag() does for a real run.
+const FALSY_TOKENS = new Set(['0', 'false', 'no', 'off']);
+
+function _v2Route(pathname) {
+  const prefix = V2_PATH_PREFIXES.find((candidate) => pathname.startsWith(candidate));
+  if (!prefix) return null;
+  const spec = V2_ROUTE_SPECS[pathname.slice(prefix.length)];
+  return spec ? { ...spec, pathname } : null;
+}
+
+// Kill switch (§6.4): the hub's memory tick and these routes are off together, through one
+// flag read. A real run goes through lib/env-flags.js; an injected env is parsed with the same
+// token set so the two can never disagree about what "off" means.
+function brainSyncEnabled(env) {
+  if (!env || env === process.env) return boolFlag('CTM_SYNC_BRAIN_ENABLED', true);
+  const raw = _flag('CTM_SYNC_BRAIN_ENABLED', '', env).trim();
+  return !raw || !FALSY_TOKENS.has(raw.toLowerCase());
+}
+
+// 403 when the request is not provably on-box (D-12: the CTM front is what crosses the wire),
+// 401/403 for the token, 503 when the host has no local token configured at all — an
+// unauthenticated route is never "open just because the token is empty".
+function authorizeV2Request(req, env) {
+  if (!isLoopbackRequest(req)) return { ok: false, status: 403, error: 'loopback_required' };
+  const token = _string(_flag('WALL_E_API_TOKEN', '', env), 1000).trim();
+  if (!token) return { ok: false, status: 503, error: 'walle_token_unconfigured' };
+  if (requireBearer(req, token)) return { ok: true };
+  return { ok: false, status: bearerToken(req) ? 403 : 401, error: bearerToken(req) ? 'wall_e_token_invalid' : 'wall_e_token_required' };
+}
 
 function _string(value, max = 4000) {
   if (typeof value === 'string') return value.slice(0, max);
   return value == null ? '' : String(value).slice(0, max);
 }
 
+// The presented bearer, or '' — the v2 gate distinguishes "forgot it" (401) from "wrong
+// token" (403) with this.
+function bearerToken(req) {
+  const header = _string(req?.headers?.authorization, 1200);
+  const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+  return match ? match[1].trim() : '';
+}
+
 // Real runs read through the canonical flag parser (lib/env-flags.js), which is
 // the only sanctioned place a CTM_*/WALLE_* name is read — an injected env (the
 // integration test constructs several) keeps its own object verbatim.
@@ -71,69 +96,6 @@ function _flag(name, fallback, env) {
   return String(raw);
 }
 
-// The `peerId=token,peer2=token2` (or JSON object) form CTM parses in
-// lib/hosted-sync-worker.js `_parsePeerTokenMap`; kept byte-compatible in spirit:
-// both spellings resolve to the same tokens on both sides.
-function parsePeerTokenMap(raw) {
-  const value = _string(raw, 20000).trim();
-  const map = new Map();
-  if (!value) return map;
-  if (value.startsWith('{')) {
-    try {
-      const parsed = JSON.parse(value);
-      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-        for (const [peerId, token] of Object.entries(parsed)) {
-          const id = _string(peerId, 160).trim();
-          const clean = _string(token, 1000).trim();
-          if (id && clean) map.set(id, clean);
-        }
-        return map;
-      }
-    } catch {
-      return map; // REPORT: a malformed JSON token map yields no peers — the route then refuses every request rather than authorizing one
-    }
-  }
-  for (const part of value.split(',')) {
-    const [peerId, ...rest] = part.split('=');
-    const id = _string(peerId, 160).trim();
-    const clean = _string(rest.join('='), 1000).trim();
-    if (id && clean) map.set(id, clean);
-  }
-  return map;
-}
-
-function peerTokens(env) {
-  const tokens = new Set();
-  const single = _string(_flag('CTM_SYNC_PEER_TOKEN', '', env), 1000).trim();
-  if (single) tokens.add(single);
-  for (const token of parsePeerTokenMap(_flag('CTM_SYNC_PEER_TOKENS', '', env)).values()) tokens.add(token);
-  return tokens;
-}
-
-// R-12 parity with CTM: sync is on iff peers are configured. Wall-E reads this to
-// report/behave consistently; the routes themselves are gated by the bearer, so a
-// host with no peers configured still ACCEPTS a push (it is a receiver).
-function syncEnabledByPeers(env) {
-  return _string(_flag('CTM_SYNC_PEERS', '', env), 20000).trim().length > 0;
-}
-
-function bearerToken(req) {
-  const header = _string(req?.headers?.authorization, 1200);
-  const match = /^Bearer\s+(.+)$/i.exec(header.trim());
-  return match ? match[1].trim() : '';
-}
-
-// 401 when nothing was presented, 403 when a bearer was presented but is not a
-// peer token: the caller must be able to tell "you forgot the token" from "that
-// token is not mine".
-function authorizePeerRequest(req, env) {
-  const presented = bearerToken(req);
-  if (!presented) return { ok: false, status: 401, error: 'peer_token_required' };
-  const tokens = peerTokens(env);
-  if (!tokens.size || !tokens.has(presented)) return { ok: false, status: 403, error: 'peer_token_invalid' };
-  return { ok: true, token: presented, tokens };
-}
-
 function _jsonResponse(res, body, status = 200) {
   const payload = JSON.stringify(body);
   res.writeHead(status, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
@@ -168,293 +130,6 @@ function _readBody(req, limitBytes = 32 * 1024 * 1024) {
   });
 }
 
-// ---------------------------------------------------------------------------
-// The sync core. Exported so the integration test can drive it against a real
-// temp brain without an HTTP listener.
-// ---------------------------------------------------------------------------
-
-function _tableColumns(db, table) {
-  try {
-    return db.prepare(`PRAGMA table_info("${table}")`).all().map((row) => row.name);
-  } catch {
-    return [];
-  }
-}
-
-// Payloads arrive from a peer: identifiers that reach SQL come only from the
-// LOCAL table's column list, values are always bound parameters.
-function _payloadFields(payload, allowedColumns) {
-  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return [];
-  const allowed = new Set(allowedColumns);
-  return Object.keys(payload).filter((key) => allowed.has(key));
-}
-
-function _parsePayload(raw) {
-  if (raw && typeof raw === 'object') return raw;
-  try {
-    const parsed = JSON.parse(String(raw || '{}'));
-    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
-  } catch {
-    return null; // REPORT: an unparseable payload from a peer is recorded as a conflict; the cursor stays behind it
-  }
-}
-
-function _parseSeq(value) {
-  const n = Number(value);
-  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
-}
-
-function listBrainOutbox(db, { afterSeq = 0, limit = DEFAULT_LIMIT } = {}) {
-  const after = Math.max(0, _parseSeq(afterSeq));
-  const bounded = Math.max(1, Math.min(MAX_LIMIT, Math.floor(Number(limit) || 0) || DEFAULT_LIMIT));
-  const localId = brainSyncStore.localBrainInstanceId(db);
-  const page = db.prepare(`
-    SELECT seq, operation_id, table_name, row_id, op, updated_at, origin_instance_id
-      FROM brain_outbox
-     WHERE seq > ?
-     ORDER BY seq ASC
-     LIMIT ?
-  `);
-  let rows = page.all(after, bounded);
-  // Follow-up #16: a short page means the live log is drained past `after` — top it up with the
-  // next slice of pre-capture history (never more than the room left in this page, AC-16d), then
-  // re-read so the new rows ship in this same response.
-  let backfill;
-  if (rows.length < bounded) {
-    const filled = brainSyncStore.enqueueBackfillPage(db, bounded - rows.length);
-    backfill = filled.backfill;
-    if (filled.enqueued) rows = page.all(after, bounded);
-  } else {
-    backfill = brainSyncStore.readBackfillState(db);
-  }
-  // The payload is the LIVE row at read time (the triggers record only the id and the clock):
-  // a row that is gone by now ships as a delete, which is what the peer should mirror.
-  const entries = rows.map((row) => {
-    const live = brainSyncStore.readReplicatedRow(db, row.table_name, row.row_id);
-    return {
-      seq: Number(row.seq) || 0,
-      operation_id: row.operation_id,
-      table_name: row.table_name,
-      row_id: row.row_id,
-      op: live ? 'upsert' : 'delete',
-      payload: JSON.stringify(live || { id: row.row_id }),
-      updated_at: row.updated_at,
-      origin_instance_id: row.origin_instance_id || localId,
-    };
-  });
-  return {
-    ok: true,
-    entries,
-    lastSeq: entries.reduce((max, entry) => Math.max(max, entry.seq), 0),
-    pending: Number(db.prepare('SELECT count(*) AS c FROM brain_outbox WHERE seq > ?').get(after)?.c || 0) || 0,
-    backfill,
-  };
-}
-
-// Follow-up #17: outbox retention. CTM calls this on the LOCAL Wall-E once every configured
-// peer's push cursor is past `throughSeq` (lib/hosted-sync-worker.js). Bounded: at most
-// PRUNE_CHUNK rows per table per call; `more` says whether outbox rows <= throughSeq remain.
-// brain_sync_applied rows older than APPLIED_RETENTION_DAYS go too: re-delivering a pruned
-// operation is already a no-op (memories INSERT OR IGNORE; the LWW compare skips an equal clock
-// from the same origin), so the applied set only has to cover the in-flight window.
-function pruneBrainOutbox(db, { throughSeq = 0, limit = PRUNE_CHUNK } = {}) {
-  const through = _parseSeq(throughSeq);
-  const chunk = Math.max(1, Math.min(PRUNE_CHUNK, Math.floor(Number(limit) || 0) || PRUNE_CHUNK));
-  return db.transaction(() => {
-    const pruned = through
-      ? db.prepare(`
-          DELETE FROM brain_outbox
-           WHERE seq IN (SELECT seq FROM brain_outbox WHERE seq <= ? ORDER BY seq ASC LIMIT ?)
-        `).run(through, chunk).changes
-      : 0;
-    const more = through
-      ? !!db.prepare('SELECT 1 AS hit FROM brain_outbox WHERE seq <= ? LIMIT 1').get(through)
-      : false;
-    const appliedPruned = db.prepare(`
-      DELETE FROM brain_sync_applied
-       WHERE rowid IN (SELECT rowid FROM brain_sync_applied WHERE applied_at < datetime('now', ?) LIMIT ?)
-    `).run(`-${APPLIED_RETENTION_DAYS} days`, chunk).changes;
-    return { ok: true, throughSeq: through, pruned, more, appliedPruned };
-  }).immediate();
-}
-
-function _lwwWins(db, table, rowId, updatedAt, originInstanceId, localId) {
-  const local = db.prepare(
-    'SELECT updated_at, origin_instance_id FROM brain_row_clock WHERE table_name = ? AND row_id = ?'
-  ).get(table, rowId);
-  if (!local) return true;
-  const localAt = _string(local.updated_at, 64);
-  const incomingAt = _string(updatedAt, 64);
-  if (incomingAt > localAt) return true;
-  if (incomingAt < localAt) return false;
-  // Deterministic tiebreak (R-10, P-6): equal clock → the lexicographically smaller
-  // origin_instance_id wins on BOTH hosts, so the two converge. '' in the local clock
-  // means "this host" (the triggers cannot stamp the id), so it compares as localId.
-  const localOrigin = _string(local.origin_instance_id, 160) || _string(localId, 160);
-  return _string(originInstanceId, 160) < localOrigin;
-}
-
-function _writeRow(db, table, fields, payload) {
-  const columns = fields.map((column) => `"${column}"`).join(', ');
-  const placeholders = fields.map(() => '?').join(', ');
-  const values = fields.map((column) => payload[column]);
-  if (table === 'memories') {
-    // R-10: memories replicate append-only by id — a re-sent (or locally edited)
-    // memory never overwrites the row that is already here.
-    return db.prepare(`INSERT OR IGNORE INTO "memories" (${columns}) VALUES (${placeholders})`).run(...values);
-  }
-  const updates = fields.filter((column) => column !== 'id').map((column) => `"${column}" = excluded."${column}"`).join(', ');
-  const conflict = updates ? `ON CONFLICT("id") DO UPDATE SET ${updates}` : 'ON CONFLICT("id") DO NOTHING';
-  return db.prepare(`INSERT INTO "${table}" (${columns}) VALUES (${placeholders}) ${conflict}`).run(...values);
-}
-
-function _stampClock(db, table, rowId, updatedAt, originInstanceId) {
-  db.prepare(`
-    INSERT INTO brain_row_clock (table_name, row_id, updated_at, origin_instance_id)
-    VALUES (?, ?, ?, ?)
-    ON CONFLICT(table_name, row_id) DO UPDATE SET
-      updated_at = excluded.updated_at, origin_instance_id = excluded.origin_instance_id
-  `).run(table, rowId, _string(updatedAt, 64), _string(originInstanceId, 160));
-}
-
-function _sortBySeq(entries) {
-  return entries
-    .map((entry, index) => ({ entry, index, seq: _parseSeq(entry?.seq) }))
-    .sort((a, b) => (a.seq - b.seq) || (a.index - b.index))
-    .map((wrapped) => wrapped.entry);
-}
-
-// Apply one batch from a peer, one transaction per batch.
-//
-// R-10 rules: memories → INSERT OR IGNORE by id; knowledge/entities/people →
-// upsert only when the incoming clock is newer, or equal with a smaller
-// origin_instance_id. knowledge.superseded_by whose target is not here gets the
-// same repair migration 88 applies to a dangling pointer (NULL) and is reported
-// as `brain_fk_dropped`: an outbox row is immutable, so "park and retry" could
-// only ever re-offer the identical row — a permanent stall of everything behind
-// it — and ordered paging means a target that DID travel always arrives first
-// (a lower seq). The same holds for a malformed row: it is recorded as a
-// conflict, marked applied so it is never re-litigated, and the cursor moves on.
-// Nothing in a batch can stop the cursor.
-function applyBrainSyncEntries(db, payload = {}) {
-  const sourceInstanceId = _string(payload.sourceInstanceId || payload.source_instance_id, 160).trim();
-  if (!sourceInstanceId) {
-    const error = new Error('brain_sync_source_instance_required');
-    error.code = 'BRAIN_SYNC_SOURCE_REQUIRED';
-    throw error;
-  }
-  const entries = _sortBySeq(Array.isArray(payload.entries) ? payload.entries : []);
-  const localId = brainSyncStore.localBrainInstanceId(db);
-
-  // The sentinel's CREATE TEMP TABLE text lives in brain/schema.js (the sanctioned
-  // DDL module) — this HTTP module owns no DDL (bin/ddl-outside-runner-lint.js).
-  createBrainSyncSentinel(db);
-  try {
-    return db.transaction(() => {
-      let applied = 0;
-      let skipped = 0;
-      let lastSeq = 0;
-      const conflicts = [];
-      // Idempotence is keyed by operation_id alone (a 128-bit random id, UNIQUE in
-      // the producer's outbox): the same row reaching this host twice — once pulled,
-      // once pushed, filed under two different source ids — is still one write.
-      const seen = db.prepare('SELECT 1 AS hit FROM brain_sync_applied WHERE operation_id = ?');
-      const record = db.prepare(
-        "INSERT OR IGNORE INTO brain_sync_applied (source_instance_id, operation_id, applied_at) VALUES (?, ?, datetime('now'))"
-      );
-      const settle = (seq, operationId) => {
-        if (operationId) record.run(sourceInstanceId, operationId);
-        lastSeq = Math.max(lastSeq, seq);
-      };
-      for (const entry of entries) {
-        const seq = _parseSeq(entry?.seq);
-        const operationId = _string(entry?.operation_id || entry?.operationId, 160).trim();
-        const table = _string(entry?.table_name || entry?.tableName, 40).trim();
-        const rowId = _string(entry?.row_id || entry?.rowId, 160).trim();
-        if (!operationId || !rowId || !REPLICATED_TABLES.includes(table)) {
-          conflicts.push({ seq, operation_id: operationId, reason: 'brain_entry_invalid' });
-          settle(seq, operationId);
-          continue;
-        }
-        if (seen.get(operationId)) {
-          // Idempotent consumer: the same operation_id twice is a skip, never a
-          // second write.
-          skipped += 1;
-          settle(seq, '');
-          continue;
-        }
-        const parsed = _parsePayload(entry.payload);
-        if (!parsed) {
-          conflicts.push({ seq, operation_id: operationId, reason: 'brain_payload_invalid' });
-          settle(seq, operationId);
-          continue;
-        }
-        const updatedAt = _string(entry.updated_at || entry.updatedAt, 64);
-        const originInstanceId = _string(entry.origin_instance_id || entry.originInstanceId, 160);
-        const op = _string(entry.op, 16).trim() || 'upsert';
-        const columns = _tableColumns(db, table);
-        if (!columns.length) {
-          conflicts.push({ seq, operation_id: operationId, reason: 'brain_table_unknown' });
-          settle(seq, operationId);
-          continue;
-        }
-        if (op === 'delete') {
-          if (table !== 'memories' && !_lwwWins(db, table, rowId, updatedAt, originInstanceId, localId)) {
-            skipped += 1;
-            settle(seq, operationId);
-            continue;
-          }
-          db.prepare(`DELETE FROM "${table}" WHERE id = ?`).run(rowId);
-          _stampClock(db, table, rowId, updatedAt, originInstanceId);
-          settle(seq, operationId);
-          applied += 1;
-          continue;
-        }
-        if (table !== 'memories' && !_lwwWins(db, table, rowId, updatedAt, originInstanceId, localId)) {
-          // Older (or tied-but-losing) write: silently dropped per R-10, but
-          // recorded as applied so the same batch is never re-litigated.
-          skipped += 1;
-          settle(seq, operationId);
-          continue;
-        }
-        const row = { ...parsed, id: parsed.id || rowId };
-        // Follow-up #19: a memory this host did not ingest is never extracted here — the origin
-        // host's extraction produced its knowledge rows, and those replicate on their own. The
-        // insert is INSERT OR IGNORE, so this only ever labels a row that apply itself creates.
-        if (table === 'memories') row.extraction_status = 'replicated';
-        if (table === 'knowledge') {
-          const target = _string(row.superseded_by, 160).trim();
-          if (target && !brainSyncStore.knowledgeRowExists(db, target)) {
-            conflicts.push({ seq, operation_id: operationId, reason: 'brain_fk_dropped', row_id: rowId, referenced_id: target });
-            row.superseded_by = null;
-          }
-        }
-        const fields = _payloadFields(row, columns);
-        if (!fields.includes('id')) fields.unshift('id');
-        _writeRow(db, table, fields, row);
-        if (table !== 'memories') _stampClock(db, table, rowId, updatedAt, originInstanceId);
-        settle(seq, operationId);
-        applied += 1;
-      }
-      db.prepare(`
-        INSERT INTO brain_sync_hwm (source_instance_id, last_seq, updated_at)
-        VALUES (?, ?, datetime('now'))
-        ON CONFLICT(source_instance_id) DO UPDATE SET
-          last_seq = MAX(brain_sync_hwm.last_seq, excluded.last_seq),
-          updated_at = excluded.updated_at
-      `).run(sourceInstanceId, lastSeq);
-      return { ok: true, applied, skipped, conflicts, lastSeq };
-    }).immediate();
-  } finally {
-    dropBrainSyncSentinel(db);
-  }
-}
-
-function getBrainSyncHwm(db, sourceInstanceId) {
-  const row = db.prepare('SELECT last_seq FROM brain_sync_hwm WHERE source_instance_id = ?').get(_string(sourceInstanceId, 160));
-  return Number(row?.last_seq || 0) || 0;
-}
-
 // ---------------------------------------------------------------------------
 // Local brain resolution (owner worker first, in-process module second).
 // ---------------------------------------------------------------------------
@@ -511,9 +186,21 @@ async function callLocalBrain(method, args = []) {
       // header: the two owner-call registrations are called out in the WP-5 report).
     }
   }
-  if (method === 'brainSyncOutbox') return _withDb(method, args, listBrainOutbox);
-  if (method === 'brainSyncApplyEntries') return _withDb(method, args, applyBrainSyncEntries);
-  if (method === 'brainSyncPrune') return _withDb(method, args, pruneBrainOutbox);
+  // WP-1: the v2 feed. Same shape as the v1 trio — the storage module is loaded lazily so the
+  // (brain → http) edge this file would otherwise create never exists at require time.
+  const v2 = () => require('../brain/brain-sync-v2');
+  if (method === 'brainSyncV2Vector') return _withDb(method, args, (db) => v2().readVector(db));
+  if (method === 'brainSyncV2Changes') return _withDb(method, args, (db, options) => v2().changesSince(db, options || {}));
+  if (method === 'brainSyncV2Apply') return _withDb(method, args, (db, payload) => v2().applyChanges(db, payload || {}));
+  if (method === 'brainSyncV2MemberVector') return _withDb(method, args, (db, payload) => v2().recordMemberVector(db, payload || {}));
+  if (method === 'brainSyncV2PruneTombstones') return _withDb(method, args, (db, options) => v2().pruneTombstones(db, options || {}));
+  if (method === 'brainSyncV2Digest') return _withDb(method, args, (db, options) => v2().digest(db, options || {}));
+  // WP-4 §6.7: the join trio. Same lazy-require shape as the feed above — brain/brain-join.js
+  // owns the snapshot/import/status storage half, and this file stays the thin route layer.
+  const join = () => require('../brain/brain-join');
+  if (method === 'brainSyncV2JoinSnapshot') return _withDb(method, args, (db, options) => join().createJoinSnapshot({ db, ...(options || {}) }));
+  if (method === 'brainSyncV2JoinImport') return _withDb(method, args, (db, options) => join().startJoinImport(db, options || {}));
+  if (method === 'brainSyncV2JoinStatus') return _withDb(method, args, (db) => join().joinStatus(db));
   throw new Error(`unknown brain sync method: ${method}`);
 }
 
@@ -522,89 +209,223 @@ async function callLocalBrain(method, args = []) {
 // ---------------------------------------------------------------------------
 
 function handlesSyncPath(pathname) {
-  return SYNC_PATHS.has(_string(pathname, 200));
+  return !!_v2Route(_string(pathname, 200));
 }
 
-async function _handleOutbox(req, res, url, env) {
-  const auth = authorizePeerRequest(req, env);
-  if (!auth.ok) return _jsonResponse(res, { ok: false, error: auth.error }, auth.status);
-  let result;
-  try {
-    result = await callLocalBrain('brainSyncOutbox', [{
-      afterSeq: url.searchParams.get('after_seq') || url.searchParams.get('afterSeq') || 0,
-      limit: url.searchParams.get('limit') || DEFAULT_LIMIT,
-    }]);
-  } catch (err) {
-    return _jsonResponse(res, { ok: false, error: err?.message || String(err) }, 500);
-  }
-  if (result == null) return _jsonResponse(res, { ok: false, error: 'brain_unavailable' }, 503);
-  return _jsonResponse(res, result);
-}
+// ---------------------------------------------------------------------------
+// v2 routes (WP-1 §6.4). Thin by design: kill switch → auth → bounded body → owner call.
+// ---------------------------------------------------------------------------
 
-async function _handleApply(req, res, env) {
-  const auth = authorizePeerRequest(req, env);
-  if (!auth.ok) return _jsonResponse(res, { ok: false, error: auth.error }, auth.status);
-  let body;
-  try {
-    body = await _readBody(req);
-  } catch (err) {
-    const status = err?.code === 'PAYLOAD_TOO_LARGE' ? 413 : 400;
-    return _jsonResponse(res, { ok: false, error: err?.code === 'PAYLOAD_TOO_LARGE' ? 'payload_too_large' : 'invalid_json' }, status);
+// 400/413 for the two business-rule refusals, 500 otherwise; the code, not the message text,
+// is what the route keys on.
+function _v2ErrorStatus(err) {
+  if (err?.code === 'BRAIN_SYNC_SOURCE_REQUIRED') return 400;
+  if (err?.code === 'BRAIN_SYNC_ENTRIES_TOO_LARGE') return 413;
+  if (err?.code === 'BRAIN_SYNC_TABLE_UNKNOWN') return 400;
+  if (err?.code === 'BRAIN_SYNC_MEMBER_REQUIRED') return 400;
+  // WP-4 §6.7: the join trio's business-rule refusals — a seed walk still running, a different
+  // join already in flight, a join file outside the inbox, a missing joinId.
+  if (err?.code === 'JOIN_CLOCK_SEED_PENDING') return 409;
+  if (err?.code === 'JOIN_IN_PROGRESS') return 409;
+  if (err?.code === 'JOIN_PATH_INVALID') return 400;
+  if (err?.code === 'JOIN_ID_REQUIRED') return 400;
+  return 500;
+}
+
+// Answers and returns null when the request must not proceed; true when it may.
+function _v2Gate(req, res, env) {
+  if (!brainSyncEnabled(env)) {
+    _jsonResponse(res, { ok: false, error: 'brain_sync_disabled' }, 503);
+    return null;
   }
-  // The source instance id is trusted only from a bearer-authenticated request.
-  if (!_string(body.sourceInstanceId || body.source_instance_id, 160).trim()) {
-    return _jsonResponse(res, { ok: false, error: 'sourceInstanceId_required' }, 400);
+  const auth = authorizeV2Request(req, env);
+  if (!auth.ok) {
+    _jsonResponse(res, { ok: false, error: auth.error }, auth.status);
+    return null;
   }
-  let result;
+  return true;
+}
+
+async function _v2Body(req, res, limitBytes) {
   try {
-    result = await callLocalBrain('brainSyncApplyEntries', [{ ...body, sourceInstanceId: _string(body.sourceInstanceId || body.source_instance_id, 160).trim() }]);
+    return await _readBody(req, limitBytes);
   } catch (err) {
-    const status = err?.code === 'BRAIN_SYNC_SOURCE_REQUIRED' ? 400 : 500;
-    return _jsonResponse(res, { ok: false, error: err?.message || String(err) }, status);
+    const tooLarge = err?.code === 'PAYLOAD_TOO_LARGE';
+    _jsonResponse(res, { ok: false, error: tooLarge ? 'payload_too_large' : 'invalid_json' }, tooLarge ? 413 : 400);
+    return null;
   }
-  if (result == null) return _jsonResponse(res, { ok: false, error: 'brain_unavailable' }, 503);
-  return _jsonResponse(res, result);
 }
 
-async function _handlePrune(req, res, env) {
-  const auth = authorizePeerRequest(req, env);
-  if (!auth.ok) return _jsonResponse(res, { ok: false, error: auth.error }, auth.status);
-  let body;
+// One call to the owner; a null result means no local writer exists (503), a throw maps through
+// _v2ErrorStatus. `res` is answered either way.
+async function _v2OwnerCall(res, op, args) {
   try {
-    body = await _readBody(req, 64 * 1024);
+    const result = await callLocalBrain(op, args);
+    if (result == null) {
+      _jsonResponse(res, { ok: false, error: 'brain_unavailable' }, 503);
+      return null;
+    }
+    return result;
   } catch (err) {
-    const status = err?.code === 'PAYLOAD_TOO_LARGE' ? 413 : 400;
-    return _jsonResponse(res, { ok: false, error: err?.code === 'PAYLOAD_TOO_LARGE' ? 'payload_too_large' : 'invalid_json' }, status);
+    _jsonResponse(res, { ok: false, error: err?.message || String(err) }, _v2ErrorStatus(err));
+    return null;
   }
-  const throughSeq = _parseSeq(body.throughSeq ?? body.through_seq);
+}
+
+async function _handleV2Vector(req, res, url, env) {
+  if (!_v2Gate(req, res, env)) return true;
+  const result = await _v2OwnerCall(res, 'brainSyncV2Vector', []);
+  if (result == null) return true;
+  return _jsonResponse(res, { ok: true, ...result });
+}
+
+async function _handleV2Changes(req, res, url, env) {
+  if (!_v2Gate(req, res, env)) return true;
+  const body = await _v2Body(req, res, V2_MAX_BODY_BYTES);
+  if (body == null) return true;
+  const since = body.since && typeof body.since === 'object' && !Array.isArray(body.since) ? body.since : {};
+  const result = await _v2OwnerCall(res, 'brainSyncV2Changes', [{ since, limit: body.limit }]);
+  if (result == null) return true;
+  // §6.4: a node whose WP-0 clock walk has not finished cannot answer a change feed — its
+  // clocks are incomplete, so anything it shipped would be a lie. The peer retries.
+  if (result.clockSeedDone === false) return _jsonResponse(res, { ok: false, error: 'clock_seed_pending' }, 409);
+  return _jsonResponse(res, { ok: true, entries: result.entries, more: result.more });
+}
+
+async function _handleV2Apply(req, res, url, env) {
+  if (!_v2Gate(req, res, env)) return true;
+  const body = await _v2Body(req, res, V2_MAX_BODY_BYTES);
+  if (body == null) return true;
+  const sourceInstanceId = _string(body.sourceInstanceId || body.source_instance_id, 160).trim();
+  if (!sourceInstanceId) return _jsonResponse(res, { ok: false, error: 'sourceInstanceId_required' }, 400);
+  const entries = Array.isArray(body.entries) ? body.entries : [];
+  if (entries.length > V2_MAX_ENTRIES) return _jsonResponse(res, { ok: false, error: 'too_many_entries' }, 413);
+  // D-5 membership marker: the hub's round (via the member's CTM front) names itself in this header;
+  // a Wall-E that has been synced BY a home is a member and stops running derived producers.
+  const memberOf = _string(req?.headers?.['x-ctm-memory-sync-home'], 160).trim();
+  const result = await _v2OwnerCall(res, 'brainSyncV2Apply', [{ sourceInstanceId, entries, ...(memberOf ? { memberOf } : {}) }]);
+  if (result == null) return true;
+  return _jsonResponse(res, { ok: true, ...result });
+}
+
+async function _handleV2MemberVector(req, res, url, env) {
+  if (!_v2Gate(req, res, env)) return true;
+  const body = await _v2Body(req, res, V2_MAX_BODY_BYTES);
+  if (body == null) return true;
+  const result = await _v2OwnerCall(res, 'brainSyncV2MemberVector', [{
+    memberInstanceId: _string(body.memberInstanceId || body.member_instance_id, 160).trim(),
+    vector: body.vector && typeof body.vector === 'object' && !Array.isArray(body.vector) ? body.vector : {},
+  }]);
+  if (result == null) return true;
+  return _jsonResponse(res, { ok: true, ...result });
+}
+
+async function _handleV2PruneTombstones(req, res, url, env) {
+  if (!_v2Gate(req, res, env)) return true;
+  const body = await _v2Body(req, res, V2_MAX_BODY_BYTES);
+  if (body == null) return true;
+  const result = await _v2OwnerCall(res, 'brainSyncV2PruneTombstones', [{ rejoinAfterDays: body.rejoinAfterDays }]);
+  if (result == null) return true;
+  return _jsonResponse(res, { ok: true, ...result });
+}
+
+async function _handleV2Digest(req, res, url, env) {
+  if (!_v2Gate(req, res, env)) return true;
+  const table = _string(url?.searchParams?.get('table') || 'memories', 40).trim();
+  const result = await _v2OwnerCall(res, 'brainSyncV2Digest', [{ table }]);
+  if (result == null) return true;
+  return _jsonResponse(res, { ok: true, ...result });
+}
+
+// WP-4 §6.7: the join trio. The home's snapshot runs where the backup API runs (the owner), and
+// the member's import is only RECORDED here — the brain-join-import job drives the pages.
+async function _handleV2JoinSnapshot(req, res, url, env) {
+  if (!_v2Gate(req, res, env)) return true;
+  // R-4/R-5 (§6.4): `{ fresh: true }` asks the home for a NEW snapshot instead of the one inside
+  // the 6 h reuse window — the member could not resume it. An empty body (a v1 caller, or a home
+  // that has nothing to retry) keeps today's reuse behavior.
+  const body = await _v2Body(req, res, V2_MAX_BODY_BYTES);
+  if (body == null) return true;
+  const result = await _v2OwnerCall(res, 'brainSyncV2JoinSnapshot', [{ fresh: body.fresh === true }]);
+  if (result == null) return true;
+  return _jsonResponse(res, { ok: true, ...result });
+}
+
+// R-6 (§5): the member's join file must sit in CTM's inbox, and ONLY this process knows where
+// that is — the owner worker's env is a whitelist that drops CTM_DATA_DIR (I-5). So the DAEMON
+// resolves CTM's data dir here and hands the root down as `dataDir`; the owner process env is
+// never widened, and the path check itself is unchanged.
+function _joinImportOptions(body, env) {
+  return {
+    joinId: _string(body.joinId || body.join_id, 200).trim(),
+    path: _string(body.path, 4096).trim(),
+    sha256: _string(body.sha256, 128).trim(),
+    homeInstanceId: _string(body.homeInstanceId || body.home_instance_id, 160).trim(),
+    dataDir: resolveCtmDataDir(env || process.env),
+  };
+}
+
+async function _handleV2JoinImport(req, res, url, env) {
+  if (!_v2Gate(req, res, env)) return true;
+  const body = await _v2Body(req, res, V2_MAX_BODY_BYTES);
+  if (body == null) return true;
   let result;
   try {
-    result = await callLocalBrain('brainSyncPrune', [{ throughSeq }]);
+    result = await callLocalBrain('brainSyncV2JoinImport', [_joinImportOptions(body, env)]);
   } catch (err) {
-    return _jsonResponse(res, { ok: false, error: err?.message || String(err) }, 500);
+    // §6.7: a different join already in flight answers 409 with the id that holds it.
+    if (err?.code === 'JOIN_IN_PROGRESS') {
+      return _jsonResponse(res, { ok: false, error: 'join_in_progress', joinId: _string(err.joinId, 200) || null }, 409);
+    }
+    return _jsonResponse(res, { ok: false, error: err?.message || String(err) }, _v2ErrorStatus(err));
   }
   if (result == null) return _jsonResponse(res, { ok: false, error: 'brain_unavailable' }, 503);
-  return _jsonResponse(res, result);
+  // 202: accepted and recorded, not yet imported (the job does the pages). R-4 (§6.4): a record
+  // this call RESUMED at its stored cursor reports `resumed: true`, so the hub knows it is
+  // continuing an existing import rather than starting a new one.
+  return _jsonResponse(res, { ok: true, state: result.state, ...(result.resumed ? { resumed: true } : {}) }, 202);
+}
+
+async function _handleV2JoinStatus(req, res, url, env) {
+  if (!_v2Gate(req, res, env)) return true;
+  const result = await _v2OwnerCall(res, 'brainSyncV2JoinStatus', []);
+  if (result == null) return true;
+  return _jsonResponse(res, { ok: true, ...result });
+}
+
+function _v2Handler(route) {
+  switch (route.op) {
+    case 'brainSyncV2Vector': return _handleV2Vector;
+    case 'brainSyncV2Changes': return _handleV2Changes;
+    case 'brainSyncV2Apply': return _handleV2Apply;
+    case 'brainSyncV2MemberVector': return _handleV2MemberVector;
+    case 'brainSyncV2PruneTombstones': return _handleV2PruneTombstones;
+    case 'brainSyncV2Digest': return _handleV2Digest;
+    case 'brainSyncV2JoinSnapshot': return _handleV2JoinSnapshot;
+    case 'brainSyncV2JoinImport': return _handleV2JoinImport;
+    case 'brainSyncV2JoinStatus': return _handleV2JoinStatus;
+    default: return null;
+  }
 }
 
 // Returns false when the path is not ours (api-walle's routeWalleApi uses that to
 // keep dispatching); returns true once it has written the response.
 function handleSyncApi(req, res, url, deps = {}) {
   const pathname = _string(url?.pathname, 200);
-  if (!handlesSyncPath(pathname)) return false;
+  const route = _v2Route(pathname);
+  // WP-6 (migration 105): only the v2 feed is routed here any more; anything else is not ours.
+  if (!route) return false;
   const env = deps.env || process.env;
-  const isOutbox = pathname.endsWith('/sync/outbox');
   const method = _string(req?.method, 10).toUpperCase();
-  if (isOutbox && method !== 'GET') return _jsonResponse(res, { ok: false, error: 'method_not_allowed' }, 405);
-  if (!isOutbox && method !== 'POST') return _jsonResponse(res, { ok: false, error: 'method_not_allowed' }, 405);
-  const isPrune = pathname.endsWith('/sync/prune');
-  const promise = isOutbox ? _handleOutbox(req, res, url, env) : (isPrune ? _handlePrune(req, res, env) : _handleApply(req, res, env));
+  if (method !== route.method) return _jsonResponse(res, { ok: false, error: 'method_not_allowed' }, 405);
+  const handler = _v2Handler(route);
+  const promise = handler(req, res, url, env);
   promise.catch((err) => {
-    // REPORT: the handler already tried to answer; a late rejection is logged, not
-    // swallowed, and must not take the daemon down.
+    // REPORT: the handler already answered; a late rejection is logged, not swallowed, and
+    // must not take the daemon down.
     try {
       if (!res.headersSent) _jsonResponse(res, { ok: false, error: err?.message || String(err) }, 500);
-      else console.warn(`[sync-api] late handler failure: ${err?.message || err}`);
+      else console.warn(`[sync-api] late v2 handler failure: ${err?.message || err}`);
     } catch {
       /* expected: the socket is already gone — there is nothing left to answer */
     }
@@ -613,20 +434,13 @@ function handleSyncApi(req, res, url, deps = {}) {
 }
 
 module.exports = {
-  SYNC_PATHS,
-  REPLICATED_TABLES,
-  APPLY_SENTINEL_TABLE,
+  V2_ROUTE_SPECS,
   handleSyncApi,
   handlesSyncPath,
-  authorizePeerRequest,
-  parsePeerTokenMap,
-  peerTokens,
-  syncEnabledByPeers,
-  listBrainOutbox,
-  applyBrainSyncEntries,
-  pruneBrainOutbox,
-  getBrainSyncHwm,
+  authorizeV2Request,
+  brainSyncEnabled,
   callLocalBrain,
   _setSyncBrainForTests,
   _setOwnerClientForTests,
+  _joinImportOptions,
 };