@stravica-ai/digital-operator-pa 0.1.64 → 0.1.65

package/dist/engineering-pa-library-cli/src/migrate/apply.mjs

@@ -0,0 +1,479 @@
+// apply.mjs: `library migrate-mounts --apply`, the verified batch engine for
+// the legacy-path migration (w-2026-10-16-dave-019, slice 3 Part B).
+//
+// One invocation moves one batch (or, with `--batches all`, batch after
+// batch) of ONE tier's legacy rows to the mounted path, through the ingest as
+// ordinary events, and proves every doc before the next step:
+//
+//   plan     re-plan the tier live (Part A's planner, with fetch); eligible
+//            rows in plan order are re-put, delete, take-legacy,
+//            take-mounted, and merge rows with a merged body on disk
+//   phase 1  compare-and-swap: fetch, re-read both blobs of every batch row;
+//            any change since the plan is `state-changed`
+//   phase 2  upserts (re-put, take-legacy: the legacy body; merge: the
+//            merged body) with deterministic event ids; an ack other than
+//            accepted or deduped is `rejected:<reason>`
+//   phase 3  wait until every target blob equals the posted body's blob
+//            (`not-applied` on timeout, `content-mismatch` on another blob)
+//   phase 4  deletes of the legacy path, only for rows whose mounted copy
+//            verified (phase 3, or phase 1 for delete and take-mounted)
+//   phase 5  wait until every deleted legacy path is absent
+//   phase 6  reader check: fast-forward the clone, then the real reader
+//            (`scanSourcesFor` over an empty home, `locateScannedFile`) must
+//            resolve the workspace id to `<clone>/<target>` with the body's
+//            sha256
+//
+// The first divergence stops the invocation: no further post of any kind,
+// and a legacy copy is never deleted unless its mounted copy verified. Docs
+// upserted but not yet deleted are safe (the reader's bridge serves the
+// newer mounted copy) and the next run re-plans them. Cross-tier rows are
+// never applied (Dave ruling 2026-10-19); they are listed for the relay.
+//
+// Seams (post, git, clock, sleep, hooks) are injected so tests drive a local
+// ingest double and temp repos.
+
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve, sep } from 'node:path';
+
+import { locateScannedFile, scanSourcesFor } from '../../../engineering-pa-core/src/knowledge/retrieval/links.mjs';
+import { gitRemoteOf } from '../../../engineering-pa-core/src/knowledge/retrieval/mounts.mjs';
+import { createMountMap } from '../../../engineering-pa-core/src/knowledge/retrieval/mount-map.mjs';
+
+import { parseIngestAck } from '../ack.mjs';
+import { buildEnvelope } from '../envelope.mjs';
+import {
+  CROSS_TIER_COLUMNS,
+  LEGACY_PREFIX,
+  PlanError,
+  crossTierRows,
+  defaultGitRunner,
+  gitBlobSha,
+  lsTreeBlobs,
+  planTier,
+  resolvePlanRef,
+  tierLabel,
+  toCsv,
+} from './plan.mjs';
+
+export const APPLY_ACTIONS = new Set(['re-put', 'delete', 'take-legacy', 'take-mounted', 'merge']);
+export const UPSERT_ACTIONS = new Set(['re-put', 'take-legacy', 'merge']);
+export const DEFAULT_BATCH_SIZE = 25;
+export const MAX_BATCH_SIZE = 100;
+export const DEFAULT_WAIT_MS = 300000;
+export const DEFAULT_POLL_MS = 10000;
+
+// RFC 4122 URL namespace; the name carries `migrate-mounts` and the row.
+const NAMESPACE_URL = '6ba7b811-9dad-11d1-80b4-00c04fd430c8';
+
+export const ROLLBACK_NOTE = 'No rollback mode. Every pre-state copy is `git show <tierShaBefore>:<path>` in the tier. '
+  + 'To restore a mounted copy, put that body at its workspace path with `library put`. Legacy copies are not '
+  + 'restored: the mounted copy carries the content and is what the reader reads.';
+
+/** A name-based (version 5, SHA-1) uuid, RFC 4122 layout, stdlib only. */
+export function uuidV5(name, namespace = NAMESPACE_URL) {
+  const ns = Buffer.from(namespace.replace(/-/g, ''), 'hex');
+  const bytes = Buffer.from(createHash('sha1').update(ns).update(Buffer.from(String(name), 'utf8')).digest().subarray(0, 16));
+  bytes[6] = (bytes[6] & 0x0f) | 0x50;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const h = bytes.toString('hex');
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}
+
+/**
+ * The deterministic event id for one migration event, over the tier, the
+ * event action (`upsert` or `delete`), the path, the body blob and `since`:
+ * the last commit that touched that path at the planned sha (empty when it
+ * never existed). A rerun after a crash, with the path untouched since,
+ * gives the same id and dedups at the ingest; once the path has changed
+ * (the worker wrote another body, a stale writer brought a legacy copy
+ * back), the corrective post gets a new id instead of being deduped
+ * forever.
+ */
+export function migrateEventId({ repoKey, action, path, blob, since = '' }) {
+  return uuidV5(['migrate-mounts', repoKey, action, path, blob, since].join('\n'));
+}
+
+/** The last commit touching `path` at `sha`, or '' when none did. */
+export function lastTouch(git, root, sha, path) {
+  return git(['log', '-1', '--format=%H', sha, '--', path], { cwd: root }).toString('utf8').trim();
+}
+
+const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
+
+/** Where a merge row's merged body lives: `<merged-dir>/<tier>/<R>`. */
+export function mergedBodyPath(mergedDir, tier, legacyPath) {
+  if (!mergedDir) return null;
+  const base = resolve(mergedDir);
+  const p = resolve(base, tier, ...legacyPath.slice(LEGACY_PREFIX.length).split('/'));
+  return p.startsWith(base + sep) ? p : null;
+}
+
+/** `YYYYMMDDTHHMMSSmmmZ` for batch ids and report names. */
+export function utcStamp(date) {
+  return date.toISOString().replace(/[-:]/g, '').replace('.', '');
+}
+
+class Divergence extends Error {
+  constructor(code, path, phase, detail = '') {
+    super(`${code} at ${path}`);
+    this.code = code;
+    this.path = path;
+    this.phase = phase;
+    this.detail = detail;
+  }
+}
+
+function assertCleanClone(git, root) {
+  const dirty = git(['status', '--porcelain'], { cwd: root }).toString('utf8').trim();
+  if (dirty) throw new PlanError(`clone ${root} has uncommitted changes; --apply refuses a dirty clone`);
+}
+
+/**
+ * Apply batches to one tier.
+ *
+ * @param {object} opts
+ * @param {string} opts.root the tier clone
+ * @param {string} opts.repoKey its registry key
+ * @param {object} opts.registry the registry (for the mount map)
+ * @param {string} opts.companyRoot the company clone (the reader's registry)
+ * @param {string} opts.out output dir (batch reports, divergence files)
+ * @param {string} opts.repoRoot operator repo root (provenance source path)
+ * @param {object} opts.producer envelope producer
+ * @param {(envelope: object) => Promise<{httpStatus: number, body: unknown}>} opts.post
+ * @param {string} [opts.mergedDir]
+ * @param {number} [opts.batchSize]
+ * @param {'1'|'all'} [opts.batches]
+ * @param {number} [opts.waitMs]
+ * @param {number} [opts.pollMs]
+ * @param {string} [opts.ref]
+ * @param {Function} [opts.git]
+ * @param {() => Date} [opts.clock]
+ * @param {(ms: number) => Promise<void>} [opts.sleep]
+ * @param {Function} [opts.remoteOf]
+ * @param {(repoKey: string) => object|null} [opts.targetTree] other tiers' trees (cross-tier rows)
+ * @param {object} [opts.hooks] test seam: `afterPlan({ batchIndex, plan })`
+ * @param {Function} [opts.log]
+ * @returns {Promise<{ exitCode: number, batches: object[] }>}
+ */
+export async function applyTier(opts) {
+  const {
+    root, repoKey, registry, git = defaultGitRunner, log = () => {},
+  } = opts;
+  const map = createMountMap(registry);
+  if (!map.mountsFor(repoKey).length) {
+    throw new PlanError(`${repoKey} has no knowledge mount in the registry; its legacy rows are owner decisions and --apply refuses the tier`);
+  }
+  assertCleanClone(git, root);
+  mkdirSync(resolve(opts.out, 'batches'), { recursive: true });
+  const batches = [];
+  for (let batchIndex = 1; ; batchIndex += 1) {
+    const report = await applyBatch({ ...opts, map, git, batchIndex });
+    batches.push(report);
+    log(batchSummaryLine(report));
+    if (report.crossTier.length) {
+      const merges = report.crossTier.filter((c) => c.crossKind === 'merge').length;
+      log(`${tierLabel(report.tier)} cross-tier: ${report.crossTier.length} row(s) not applied (${merges} merge), listed in ${report.crossTierCsv}`);
+    }
+    if (report.divergence) return { exitCode: 2, batches };
+    if (opts.batches !== 'all' || report.rows.length === 0) break;
+  }
+  return { exitCode: 0, batches };
+}
+
+/** `<tier> batch <id>: posted u upserts, d deletes; verified v of n; skipped s; divergence <none|code at path>` */
+export function batchSummaryLine(r) {
+  const u = r.rows.filter((x) => x.upsertPosted).length;
+  const d = r.rows.filter((x) => x.deletePosted).length;
+  const v = r.rows.filter((x) => x.verified.mounted && x.verified.legacyGone && x.verified.reader).length;
+  const div = r.divergence ? `${r.divergence.code} at ${r.divergence.path}` : 'none';
+  return `${tierLabel(r.tier)} batch ${r.batchId}: posted ${u} upserts, ${d} deletes; verified ${v} of ${r.rows.length}; skipped ${r.skipped.length}; divergence ${div}`;
+}
+
+async function applyBatch(ctx) {
+  const {
+    root, repoKey, map, git, out, repoRoot, producer, post, mergedDir, companyRoot,
+    batchSize = DEFAULT_BATCH_SIZE, waitMs = DEFAULT_WAIT_MS, pollMs = DEFAULT_POLL_MS,
+    ref, clock = () => new Date(), sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+    remoteOf = gitRemoteOf, targetTree = null, hooks = {}, batchIndex,
+  } = ctx;
+  const tier = tierLabel(repoKey);
+  const started = clock();
+  let batchId = `${repoKey}-${utcStamp(started)}`;
+  if (existsSync(resolve(out, 'batches', `${batchId}.json`))) batchId += `-${batchIndex}`;
+
+  // ---- plan (live) -----------------------------------------------------------
+  const at = resolvePlanRef(git, root, { ref, fetch: true });
+  const plan = planTier({ root, repoKey, map, at, git, targetTree });
+  if (hooks.afterPlan) await hooks.afterPlan({ batchIndex, plan });
+  const eligible = [];
+  const skipped = [];
+  for (const row of plan.rows) {
+    if (!APPLY_ACTIONS.has(row.action)) {
+      skipped.push({ action: row.action, legacyPath: row.current, reason: row.reason });
+      continue;
+    }
+    if (row.action === 'merge') {
+      const p = mergedBodyPath(mergedDir, tier, row.current);
+      if (!p || !existsSync(p)) {
+        skipped.push({ action: 'merge', legacyPath: row.current, reason: p ? `no merged body at ${p}` : 'no --merged-dir; a merge row needs a merged body' });
+        continue;
+      }
+      row.mergedBody = readFileSync(p);
+    }
+    eligible.push(row);
+  }
+  const batch = eligible.slice(0, batchSize);
+  const crossTier = crossTierRows([{ ...plan, sha: at.sha, rows: plan.rows }]);
+  const crossTierCsv = resolve(out, 'cross-tier.csv');
+
+  const rows = batch.map((row) => ({
+    action: row.action,
+    legacyPath: row.current,
+    mountedPath: row.correct,
+    workspaceId: row.workspaceId,
+    preLegacyBlob: row.legacyBlob,
+    preMountedBlob: row.mountedBlob || null,
+    postedBlob: null,
+    mergedBodySha256: row.mergedBody ? sha256(row.mergedBody) : null,
+    upsertEventId: null,
+    deleteEventId: null,
+    upsertPosted: false,
+    deletePosted: false,
+    verified: { mounted: false, legacyGone: false, reader: false },
+    divergence: null,
+  }));
+  // Body to post (upserts) or expect (delete, take-mounted).
+  const expectBody = new Map();
+  for (const [i, row] of batch.entries()) {
+    if (row.action === 'merge') expectBody.set(i, row.mergedBody);
+    else if (UPSERT_ACTIONS.has(row.action)) expectBody.set(i, plan.bodies.get(row.legacyBlob));
+    else expectBody.set(i, plan.bodies.get(row.mountedBlob));
+  }
+
+  const report = {
+    batchId,
+    tier: repoKey,
+    ref: at.ref,
+    tierShaBefore: at.sha,
+    tierShaAfter: null,
+    startedAt: started.toISOString(),
+    finishedAt: null,
+    remainingEligible: eligible.length - batch.length,
+    rows,
+    skipped,
+    crossTier,
+    crossTierCsv,
+    divergence: null,
+    rollback: {
+      note: ROLLBACK_NOTE,
+      tierShaBefore: at.sha,
+      copies: rows.map((r) => ({
+        legacyPath: r.legacyPath,
+        legacyBlob: r.preLegacyBlob,
+        mountedPath: r.mountedPath,
+        mountedBlob: r.preMountedBlob,
+        workspaceId: r.workspaceId,
+        show: `git show ${at.sha}:${r.preMountedBlob ? r.mountedPath : r.legacyPath}`,
+      })),
+    },
+  };
+
+  const fetchTree = () => {
+    const now = resolvePlanRef(git, root, { ref: at.ref, fetch: true });
+    return { sha: now.sha, tree: lsTreeBlobs(git, root, now.sha) };
+  };
+  const deadlineFrom = () => clock().getTime() + waitMs;
+
+  try {
+    if (!batch.length) {
+      report.tierShaAfter = at.sha;
+      return report;
+    }
+
+    // ---- phase 1: compare-and-swap ------------------------------------------------
+    const p1 = fetchTree();
+    for (const [i, row] of batch.entries()) {
+      const legacyNow = p1.tree.get(row.current) ?? '';
+      const mountedNow = p1.tree.get(row.correct) ?? '';
+      if (legacyNow !== row.legacyBlob || mountedNow !== (row.mountedBlob || '')) {
+        throw Object.assign(new Divergence('state-changed', row.current, 1,
+          `planned legacy ${row.legacyBlob} mounted ${row.mountedBlob || '(absent)'}; now legacy ${legacyNow || '(absent)'} mounted ${mountedNow || '(absent)'}`), { row: i });
+      }
+      if (!UPSERT_ACTIONS.has(row.action)) rows[i].verified.mounted = true;
+    }
+
+    // ---- phase 2: upserts -----------------------------------------------------------
+    for (const [i, row] of batch.entries()) {
+      if (!UPSERT_ACTIONS.has(row.action)) continue;
+      const raw = expectBody.get(i) ?? Buffer.alloc(0);
+      const content = raw.toString('utf8');
+      const posted = Buffer.from(content, 'utf8');
+      if (!posted.equals(raw)) {
+        throw Object.assign(new Divergence('body-not-utf8', row.current, 2, 'the body does not round-trip through UTF-8; posting it would change its bytes'), { row: i });
+      }
+      expectBody.set(i, posted);
+      const postedBlob = gitBlobSha(posted);
+      rows[i].postedBlob = postedBlob;
+      const clientEventId = migrateEventId({ repoKey, action: 'upsert', path: row.correct, blob: postedBlob, since: lastTouch(git, root, at.sha, row.correct) });
+      rows[i].upsertEventId = clientEventId;
+      const envelope = buildEnvelope({
+        repoRoot,
+        sourcePath: join(repoRoot, ...row.workspaceId.split('/')),
+        content,
+        producer,
+        kind: 'knowledge.doc.upsert',
+        tier: repoKey,
+        sourceKind: 'manual',
+        payloadPath: row.correct,
+        clientEventId,
+        clock,
+      });
+      await postOne(post, envelope, row.correct, 2, i);
+      rows[i].upsertPosted = true;
+    }
+
+    // ---- phase 3: wait for the mounted copies ------------------------------------------
+    const pendingUp = new Set(batch.map((r, i) => i).filter((i) => UPSERT_ACTIONS.has(batch[i].action)));
+    if (pendingUp.size) {
+      const deadline = deadlineFrom();
+      for (;;) {
+        const { tree } = fetchTree();
+        for (const i of [...pendingUp]) {
+          const blob = tree.get(batch[i].correct) ?? '';
+          if (blob === rows[i].postedBlob) { rows[i].verified.mounted = true; pendingUp.delete(i); continue; }
+          if (blob !== (batch[i].mountedBlob || '')) {
+            throw Object.assign(new Divergence('content-mismatch', batch[i].correct, 3,
+              `expected blob ${rows[i].postedBlob}, tier holds ${blob || '(absent)'}`), { row: i });
+          }
+        }
+        if (!pendingUp.size) break;
+        if (clock().getTime() >= deadline) {
+          const i = [...pendingUp][0];
+          throw Object.assign(new Divergence('not-applied', batch[i].correct, 3,
+            `blob ${rows[i].postedBlob} not at ${at.ref}:${batch[i].correct} within ${waitMs} ms`), { row: i });
+        }
+        await sleep(pollMs);
+      }
+    }
+
+    // ---- phase 4: deletes, only behind a verified mounted copy -------------------------
+    const deleted = [];
+    for (const [i, row] of batch.entries()) {
+      if (!rows[i].verified.mounted) continue; // never delete a legacy copy whose mounted copy did not verify
+      const clientEventId = migrateEventId({ repoKey, action: 'delete', path: row.current, blob: row.legacyBlob, since: lastTouch(git, root, at.sha, row.current) });
+      rows[i].deleteEventId = clientEventId;
+      const envelope = buildEnvelope({
+        repoRoot,
+        sourcePath: join(repoRoot, ...row.workspaceId.split('/')),
+        content: undefined,
+        producer,
+        kind: 'knowledge.doc.delete',
+        tier: repoKey,
+        sourceKind: 'manual',
+        payloadPath: row.current,
+        clientEventId,
+        clock,
+      });
+      await postOne(post, envelope, row.current, 4, i);
+      rows[i].deletePosted = true;
+      deleted.push(i);
+    }
+
+    // ---- phase 5: wait for the legacy paths to go --------------------------------------
+    const pendingDel = new Set(deleted);
+    if (pendingDel.size) {
+      const deadline = deadlineFrom();
+      for (;;) {
+        const { sha, tree } = fetchTree();
+        for (const i of [...pendingDel]) {
+          const blob = tree.get(batch[i].current) ?? '';
+          if (!blob) { rows[i].verified.legacyGone = true; pendingDel.delete(i); continue; }
+          if (blob !== batch[i].legacyBlob) {
+            throw Object.assign(new Divergence('state-changed', batch[i].current, 5,
+              `legacy path rewritten to ${blob} while its delete was pending`), { row: i });
+          }
+        }
+        report.tierShaAfter = sha;
+        if (!pendingDel.size) break;
+        if (clock().getTime() >= deadline) {
+          const i = [...pendingDel][0];
+          throw Object.assign(new Divergence('not-applied', batch[i].current, 5,
+            `legacy path still at ${at.ref} after ${waitMs} ms`), { row: i });
+        }
+        await sleep(pollMs);
+      }
+    }
+
+    // ---- phase 6: the real reader -------------------------------------------------------
+    readerCheck({ git, root, ref: at.ref, companyRoot, remoteOf, batch, rows, expectBody });
+    if (!report.tierShaAfter) report.tierShaAfter = fetchTree().sha;
+    return report;
+  } catch (e) {
+    if (!(e instanceof Divergence)) throw e;
+    report.divergence = { code: e.code, path: e.path, phase: e.phase, detail: e.detail };
+    if (typeof e.row === 'number') rows[e.row].divergence = report.divergence;
+    try { report.tierShaAfter = resolvePlanRef(git, root, { ref: at.ref, fetch: false }).sha; } catch { /* keep null */ }
+    writeFileSync(resolve(out, `divergence-${batchId}.json`), `${JSON.stringify({ batchId, tier: repoKey, ...report.divergence }, null, 2)}\n`);
+    return report;
+  } finally {
+    report.finishedAt = clock().toISOString();
+    writeFileSync(resolve(out, 'batches', `${batchId}.json`), `${JSON.stringify(report, null, 2)}\n`);
+    writeFileSync(crossTierCsv, crossTierCsvText(crossTier));
+  }
+}
+
+async function postOne(post, envelope, path, phase, row) {
+  let res;
+  try {
+    res = await post(envelope);
+  } catch (e) {
+    throw Object.assign(new Divergence(`rejected:unreachable`, path, phase, e.message ?? String(e)), { row });
+  }
+  const ack = parseIngestAck(res);
+  if (ack.kind !== 'accepted' && ack.kind !== 'deduped') {
+    throw Object.assign(new Divergence(`rejected:${ack.reason}`, path, phase, ack.reason), { row });
+  }
+}
+
+/**
+ * Phase 6: fast-forward the clone to the ref, then ask the reader, over an
+ * empty home (so no home copy masks the tier), which file backs each
+ * workspace id. It must be `<clone>/<target>` with the expected sha256.
+ */
+function readerCheck({ git, root, ref, companyRoot, remoteOf, batch, rows, expectBody }) {
+  const dirty = git(['status', '--porcelain'], { cwd: root }).toString('utf8').trim();
+  if (dirty) throw new Divergence('reader:dirty-clone', root, 6, 'the clone has uncommitted changes; it was not fast-forwarded');
+  if (ref !== 'HEAD') {
+    try {
+      git(['merge', '--ff-only', '--quiet', ref], { cwd: root });
+    } catch (e) {
+      throw new Divergence('reader:not-fast-forward', root, 6, e.message);
+    }
+  }
+  const home = mkdtempSync(join(tmpdir(), 'migrate-mounts-reader-'));
+  try {
+    const extraRoots = [...new Set([root, companyRoot].filter(Boolean))];
+    const scans = scanSourcesFor(home, { extraRoots, remoteOf });
+    for (const [i, row] of batch.entries()) {
+      const expected = join(root, ...row.correct.split('/'));
+      const found = locateScannedFile(scans, row.workspaceId);
+      if (found !== expected) {
+        throw Object.assign(new Divergence('reader-mismatch', row.workspaceId, 6, `reader resolves ${found ?? '(nothing)'}, expected ${expected}`), { row: i });
+      }
+      const want = sha256(expectBody.get(i) ?? Buffer.alloc(0));
+      const got = sha256(readFileSync(found));
+      if (got !== want) {
+        throw Object.assign(new Divergence('reader-mismatch', row.workspaceId, 6, `sha256 ${got} at ${found}, expected ${want}`), { row: i });
+      }
+      rows[i].verified.reader = true;
+    }
+  } finally {
+    rmdirSync(home); // created empty above and never written to
+  }
+}
+
+function crossTierCsvText(cross) {
+  return toCsv(cross, CROSS_TIER_COLUMNS);
+}

package/dist/engineering-pa-library-cli/src/migrate/kit.mjs

@@ -0,0 +1,108 @@
+// kit.mjs: the merge kit for the legacy-path migration (slice 3 Part A).
+//
+// For every row whose two copies differ (`merge`, `take-legacy`,
+// `take-mounted`) the kit holds both bodies, a unified diff from the
+// mounted copy (a/) to the legacy copy (b/), and the home copy when it
+// matches neither. A writer reads the kit and writes merged bodies to
+// `<merged-dir>/<tier>/<R>`; nothing here writes outside `<out>/merge/`.
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+
+import { KIT_ACTIONS, LEGACY_PREFIX } from './plan.mjs';
+
+/** Name the diff sides by path instead of blob id. */
+export function labelDiff(diff, { mountedBlob, legacyBlob, mountedPath, legacyPath }) {
+  return diff
+    .replace(`diff --git a/${mountedBlob} b/${legacyBlob}`, `diff --git a/${mountedPath} b/${legacyPath}`)
+    .replace(`--- a/${mountedBlob}`, `--- a/${mountedPath}`)
+    .replace(`+++ b/${legacyBlob}`, `+++ b/${legacyPath}`);
+}
+
+const README = (rows) => `# Merge kit: legacy-path migration (w-2026-10-16-dave-019, slice 3)
+
+Generated by \`library migrate-mounts --dry-run\`. One entry per row whose
+two copies differ, under \`<tier>/<R>\`, where R is the path after
+\`operator/knowledge/\`:
+
+- \`<R>.legacy\`: the tier's legacy copy at \`operator/knowledge/<R>\`.
+- \`<R>.mounted\`: the tier's copy at the mounted path (the plan's \`correct\`).
+- \`<R>.diff\`: unified diff from the mounted copy (a/) to the legacy copy (b/).
+- \`<R>.home\`: the home workspace copy, present only when it matches neither.
+
+## The rule
+
+Migrating a row is a merge of the two bodies, never a move or an overwrite,
+and commit recency never decides it (the library's merge rule,
+\`knowledge-memory/legacy-path-migration-merge.md\`).
+
+- \`merge\` rows: keep the Librarian additions from the legacy copy and the
+  newer operator edits from the mounted copy, resolve every conflicting
+  passage on purpose, and write the merged body to
+  \`<merged-dir>/<tier>/<R>\`. A \`merge\` row without a merged body is
+  skipped by the apply.
+- \`take-legacy\` rows: the mounted copy is an ancestor of the legacy copy, so
+  the legacy body is posted as is. Check the diff anyway.
+- \`take-mounted\` rows: the legacy copy is an ancestor of the mounted copy, so
+  nothing is posted and only the legacy copy is deleted. Check the diff
+  anyway.
+
+A \`.home\` file means the operator's local copy holds a third version; fold
+anything it alone carries into the merged body.
+
+## Cross-tier rows (Dave ruling 2026-10-19)
+
+A legacy row under \`operator/knowledge/wsd/\` is wsd-tier content: its
+target is the wsd tier at \`knowledge/R\`, R being the path after
+\`operator/knowledge/wsd/\`. In the wsd tier it is an ordinary row (its kit
+files, if any, are listed below with the other rows). In any other tier the
+plan marks it \`cross-tier\`, the apply never writes it, and
+\`cross-tier.csv\` (next to the plan CSVs) lists every such row with both
+blobs: \`move\` (no wsd copy yet), \`identical\`, or \`merge\` (a wsd copy
+that differs; the same merge rule applies, and the wsd tier owner writes and
+applies the merged body from a wsd host). This kit holds no files for them.
+
+## Rows (${rows.length})
+
+| tier | R | action | home |
+|---|---|---|---|
+${rows.map((r) => `| ${r.tier} | \`${r.current.slice(LEGACY_PREFIX.length)}\` | ${r.action} | ${r.home} |`).join('\n')}
+`;
+
+/**
+ * Write the kit for every planned tier under `<out>/merge/`.
+ *
+ * @param {object} opts
+ * @param {string} opts.out
+ * @param {{ root: string, tier: string, rows: object[], bodies: Map, homes: Map }[]} opts.plans
+ * @param {Function} opts.git the runner (for `git diff <blob> <blob>`)
+ * @returns {{ dir: string, count: number }}
+ */
+export function writeMergeKit({ out, plans, git }) {
+  const dir = resolve(out, 'merge');
+  mkdirSync(dir, { recursive: true });
+  const kitRows = [];
+  for (const plan of plans) {
+    for (const row of plan.rows) {
+      if (!KIT_ACTIONS.has(row.action)) continue;
+      const rest = row.current.slice(LEGACY_PREFIX.length);
+      const base = resolve(dir, plan.tier, ...rest.split('/'));
+      if (!base.startsWith(dir + sep)) continue; // never write outside the kit
+      mkdirSync(dirname(base), { recursive: true });
+      writeFileSync(`${base}.legacy`, plan.bodies.get(row.legacyBlob) ?? Buffer.alloc(0));
+      writeFileSync(`${base}.mounted`, plan.bodies.get(row.mountedBlob) ?? Buffer.alloc(0));
+      const diff = git(['diff', '--no-color', '--no-ext-diff', row.mountedBlob, row.legacyBlob], { cwd: plan.root }).toString('utf8');
+      writeFileSync(`${base}.diff`, labelDiff(diff, {
+        mountedBlob: row.mountedBlob,
+        legacyBlob: row.legacyBlob,
+        mountedPath: row.correct,
+        legacyPath: row.current,
+      }));
+      const home = plan.homes.get(row.current);
+      if (row.home === 'differs' && home) writeFileSync(`${base}.home`, home);
+      kitRows.push(row);
+    }
+  }
+  writeFileSync(join(dir, 'README.md'), README(kitRows));
+  return { dir, count: kitRows.length };
+}