slidemind 0.3.20 → 0.4.1

package/src/lib/rebase.mjs

@@ -0,0 +1,945 @@
+import { readRemote, writeRemote } from './remote.mjs';
+import { readPresentationContext } from './presentation-context.mjs';
+import { runDeclared, materializeArtifact } from './extensions.mjs';
+import { unzip, zip } from '../pptx/zip.mjs';
+import { slideOrderPaths } from '../pptx/ooxml.mjs';
+import { TAG_GUID, mintSlideGuid, updateSlideTag } from '../pptx/tags.mjs';
+import { stageWorkspace } from './workspace-transaction.mjs';
+import { loadSlideGuids, saveSlideGuids } from './slide-guids.mjs';
+import { designDigest, slideContentDigests } from '../pptx/content-digest.mjs';
+// Three-way rebase: the accepted base, the working inputs, and an incoming
+// snapshot of the same deck saved somewhere else.
+//
+// The rule: a conflict is BOTH SIDES CHANGING THE SAME SLIDE — editing it
+// twice, or one side deleting it while the other edited it. Everything else
+// merges, the way co-authoring in PowerPoint merges it:
+//
+//   • a slide only one side changed takes that side's version;
+//   • slides either side added or deleted land where that side put them;
+//   • both sides' reorders combine — a slide both sides moved keeps THEIR
+//     position, and says so;
+//   • a change to the shared design (theme, masters, layouts) is theirs to
+//     make — nothing local edits it — so it is taken, and reported.
+//
+// "Changed" is read by MEANING (src/pptx/content-digest.mjs), never by bytes:
+// one PowerPoint save re-serializes, renumbers and re-localizes almost every
+// part of a file nobody edited, and a byte comparison reported all of that as
+// somebody's edit. A conflict activates NOTHING. The base, the incoming file
+// and the local inputs all survive a conflicted rebase intact, because the
+// point of the exercise is that nobody loses work.
+//
+// A remote-only slide change applies by taking the slide back to its package
+// form: the incoming slide is folded in as a native one-slide .pptx and any
+// stale local hydration of it is dropped. That is honest (the bytes are exactly
+// what the other side saved) and it needs no converter — `slidemind adopt
+// <file> --slides N` re-hydrates it to editable JSX when the user wants that.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  acceptedBasePath,
+  clearConflicts,
+  computeDirty,
+  inputDigest,
+  journalBegin,
+  journalComplete,
+  journalStep,
+  materializedInputs,
+  readRevision,
+  readStaged,
+  slideFileOrder,
+  stagedBytes,
+  stagedDir,
+  writeConflicts,
+  writeRevision,
+  inventoryPackage,
+  assertCheckpoint,
+} from "./revision.mjs";
+import { foldPickedSlides } from "../pptx/slide-swap.mjs";
+import { removeConversionRecord } from "./conversions.mjs";
+
+const nowIso = () => new Date().toISOString();
+
+// Every conflict class the design enumerates. The `kind` is the contract the
+// resolution file and the downstream consumers key on. All four are one thing
+// underneath — both sides changed the same slide — named by how:
+export const CONFLICT_KINDS = [
+  "both-edited", // edited on both sides
+  "incoming-deleted", // edited here, deleted there
+  "local-deleted", // deleted here, edited there
+  "ambiguous-identity", // edited here, and their file no longer says which slide it is
+];
+
+// How one slide is identified across two saves of the same deck, in the order
+// the evidence is trustworthy:
+//
+//   1. a SLIDEMIND GUID — survives reorders, renames and source-tag removal;
+//   2. the package's own slide id (`p:sldId/@id`) — PowerPoint keeps it across
+//      an ordinary save. It is what tells PowerPoint's Duplicate Slide apart
+//      from the original: the copy carries the original's tags, GUID included,
+//      under a NEW slide id. It also matches a slide whose GUID a host dropped.
+//
+// Position is never identity: two saves with the same slide count prove nothing
+// about which slide is which once someone has reordered them.
+
+/** Each slide with a key unique within its own package, or `key: null`. */
+function keyed(slides) {
+  const perGuid = new Map();
+  for (const s of slides ?? []) if (s.guid) perGuid.set(s.guid, (perGuid.get(s.guid) ?? 0) + 1);
+  return (slides ?? []).map((slide) => {
+    let key = null;
+    if (slide.guid && perGuid.get(slide.guid) === 1) key = `guid:${slide.guid}`;
+    else if (slide.guid && slide.sldId) key = `guid:${slide.guid}@${slide.sldId}`;
+    else if (!slide.guid && slide.sldId) key = `sldid:${slide.sldId}`;
+    return { ...slide, key };
+  });
+}
+
+/**
+ * Pair the accepted base's slides with the incoming file's.
+ *
+ * `sameContent(base, incoming)` breaks the one tie identity cannot: a duplicated
+ * slide whose original also lost its slide id. Returns the pairs, the slides
+ * only one side has, the slides no key can name, and the base slides whose
+ * GUID survives only in copies none of which can be told to be it.
+ */
+function matchSlides(base, incoming, sameContent) {
+  const pairs = [];
+  const unnamed = [];
+  const usedBase = new Set();
+  const usedIncoming = new Set();
+  const pair = (b, i) => {
+    pairs.push({ base: b, incoming: i });
+    usedBase.add(b);
+    usedIncoming.add(i);
+  };
+
+  // A slide carrying neither a GUID nor a slide id, or a key two slides share
+  // (a duplicated slide id is a broken package), is matched to nothing.
+  for (const [list, label, used] of [
+    [base, "accepted", usedBase],
+    [incoming, "incoming", usedIncoming],
+  ]) {
+    const holders = new Map();
+    for (const s of list) if (s.key) holders.set(s.key, [...(holders.get(s.key) ?? []), s]);
+    for (const s of list) {
+      if (!s.key) {
+        unnamed.push({ slide: s, why: `this slide of the ${label} file carries neither a GUID nor a slide id, so it cannot be matched` });
+      } else if (holders.get(s.key).length > 1) {
+        unnamed.push({ slide: s, why: `${s.key} names ${holders.get(s.key).length} slides of the ${label} file` });
+      } else {
+        continue;
+      }
+      used.add(s);
+    }
+  }
+
+  const byGuid = (list, used) => {
+    const map = new Map();
+    for (const s of list) if (!used.has(s) && s.guid) map.set(s.guid, [...(map.get(s.guid) ?? []), s]);
+    return map;
+  };
+  const incomingByGuid = byGuid(incoming, usedIncoming);
+  const unclaimedLineage = new Set();
+  for (const [guid, bs] of byGuid(base, usedBase)) {
+    const is = incomingByGuid.get(guid);
+    if (!is) continue;
+    // One on each side: the same slide, wherever it moved.
+    if (bs.length === 1 && is.length === 1) {
+      pair(bs[0], is[0]);
+      continue;
+    }
+    // A duplicated slide: the original kept its slide id, every copy has a new one.
+    for (const b of bs) {
+      const i = is.find((x) => !usedIncoming.has(x) && x.sldId && x.sldId === b.sldId);
+      if (i) pair(b, i);
+    }
+    const restBase = bs.filter((b) => !usedBase.has(b));
+    const restIncoming = is.filter((i) => !usedIncoming.has(i));
+    if (restBase.length === 1 && restIncoming.length) {
+      const same = restIncoming.filter((i) => sameContent(restBase[0], i));
+      if (restIncoming.length === 1) pair(restBase[0], restIncoming[0]);
+      else if (same.length === 1) pair(restBase[0], same[0]);
+    }
+    // Whatever is left cannot be told apart. Read as "removed there, copies
+    // added there", their file lands exactly as saved; only a LOCAL edit to
+    // such a slide has nowhere certain to go (classifyRebase).
+    for (const b of bs) if (!usedBase.has(b) && restIncoming.some((i) => !usedIncoming.has(i))) unclaimedLineage.add(b);
+  }
+
+  // A GUID one side lost: the same slide id is the same slide. Two DIFFERENT
+  // GUIDs on one slide id are two slides, however the id came to be reused.
+  for (const b of base) {
+    if (usedBase.has(b) || !b.sldId) continue;
+    const hits = incoming.filter((i) => !usedIncoming.has(i) && i.sldId === b.sldId && (!i.guid || !b.guid));
+    if (hits.length === 1) pair(b, hits[0]);
+  }
+
+  return {
+    pairs,
+    unnamed,
+    unclaimedLineage,
+    baseOnly: base.filter((b) => !usedBase.has(b)),
+    incomingOnly: incoming.filter((i) => !usedIncoming.has(i)),
+  };
+}
+
+// The items of `side` that side MOVED relative to `base`: everything outside
+// one longest common subsequence of the two orders (over the items both hold).
+// Which of two swapped slides counts as "the" mover is arbitrary, and either
+// answer reproduces the same order once the movers are placed.
+function moved(base, side) {
+  const inSide = new Set(side);
+  const inBase = new Set(base);
+  const a = base.filter((x) => inSide.has(x));
+  const b = side.filter((x) => inBase.has(x));
+  const n = a.length;
+  const m = b.length;
+  const lcs = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+    }
+  }
+  const kept = new Set();
+  for (let i = 0, j = 0; i < n && j < m; ) {
+    if (a[i] === b[j]) {
+      kept.add(a[i]);
+      i++;
+      j++;
+    } else if (lcs[i + 1][j] >= lcs[i][j + 1]) i++;
+    else j++;
+  }
+  return new Set(b.filter((x) => !kept.has(x)));
+}
+
+/**
+ * Three-way merge of slide order. Their order is the starting point (it
+ * already carries their adds, deletes and moves); every slide only the local
+ * side moved or added is then placed after the slide it follows locally. A
+ * slide both sides moved keeps their position and is reported — a move is not
+ * worth stopping anyone for.
+ *
+ * @param {string[]} base     merge ids in the accepted base's order
+ * @param {string[]} incoming merge ids in their order
+ * @param {string[]} local    merge ids in the working files' order (`local:` = added here)
+ */
+export function mergeOrder(base, incoming, local) {
+  const theirMoves = moved(base, incoming);
+  const ourMoves = moved(base, local);
+  const present = new Set(incoming);
+  const place = new Set(local.filter((x) => (ourMoves.has(x) && !theirMoves.has(x)) || x.startsWith("local:")));
+  const order = [...incoming];
+  for (let p = 0; p < local.length; p++) {
+    const x = local[p];
+    if (!place.has(x) || (!present.has(x) && !x.startsWith("local:"))) continue;
+    const at = order.indexOf(x);
+    if (at >= 0) order.splice(at, 1);
+    // The neighbour it follows here — preferring one THEY did not move, since
+    // a slide they moved no longer marks the place we meant.
+    let to = -1;
+    for (const anchored of [(y) => !theirMoves.has(y), () => true]) {
+      for (let q = p - 1; q >= 0 && to < 0; q--) {
+        const k = order.indexOf(local[q]);
+        if (k >= 0 && anchored(local[q])) to = k + 1;
+      }
+      for (let q = p + 1; q < local.length && to < 0; q++) {
+        const k = order.indexOf(local[q]);
+        if (k >= 0 && anchored(local[q])) to = k;
+      }
+    }
+    order.splice(to < 0 ? order.length : to, 0, x);
+  }
+  return { order, bothMoved: [...ourMoves].filter((x) => theirMoves.has(x) && present.has(x)) };
+}
+
+/**
+ * Slide files that hold, byte for byte, what another base slide file held:
+ * old file -> new file.
+ *
+ * The NN- prefix IS the play order, so a local reorder renames files — to new
+ * names, or, when slides share a stem, onto each other's names (a swap). The
+ * dirty tracker is keyed by path and reads either as edits. For a merge that is
+ * the wrong reading: the slide is the same one in a new place, and a
+ * colleague's edit to it is not a delete/edit conflict.
+ *
+ * Only a unique byte-identical match counts. A slide moved onto a path whose
+ * own slide did not move away (it was edited or deleted there) cannot be told
+ * from an edit of that slide, so that one move is not claimed at all.
+ */
+function localRenames(revision, now) {
+  const baseline = revision.baseline?.inputs ?? {};
+  const bySlideHash = (inputs) => {
+    const map = new Map();
+    for (const [rel, hash] of Object.entries(inputs)) {
+      if (rel.startsWith("slides/") && /\.(jsx|pptx)$/.test(rel)) map.set(hash, [...(map.get(hash) ?? []), rel]);
+    }
+    return map;
+  };
+  const was = bySlideHash(baseline);
+  const is = bySlideHash(now);
+  const renames = {};
+  for (const [hash, olds] of was) {
+    const news = is.get(hash);
+    if (olds.length === 1 && news?.length === 1 && olds[0] !== news[0]) {
+      renames[olds[0].slice("slides/".length)] = news[0].slice("slides/".length);
+    }
+  }
+  for (let settled = false; !settled; ) {
+    settled = true;
+    for (const [from, to] of Object.entries(renames)) {
+      if (baseline[`slides/${to}`] !== undefined && renames[to] === undefined) {
+        delete renames[from];
+        settled = false;
+      }
+    }
+  }
+  return renames;
+}
+
+// Digests of a package, by its sha256. A pull classifies, then applies (which
+// classifies again inside its transaction), and a refused rebase classifies a
+// third time to write the resolution file — the package is the same bytes each
+// time, and on a large deck reading it is the expensive part.
+const digestCache = new Map();
+function packageDigests(sha256, read) {
+  const cached = sha256 ? digestCache.get(sha256) : null;
+  if (cached) return cached;
+  const files = unzip(read());
+  const digests = { slides: slideContentDigests(files), design: designDigest(files) };
+  if (sha256) {
+    digestCache.set(sha256, digests);
+    if (digestCache.size > 4) digestCache.delete(digestCache.keys().next().value);
+  }
+  return digests;
+}
+
+/**
+ * Compare base, working inputs and a staged incoming snapshot.
+ *
+ * Returns `{ revisionId, remoteOnly, localOnly, unchanged, conflicts, orderPlan,
+ * identity, sharedChanged, notes }`. `remoteOnly` entries are what `applyRebase`
+ * will refresh, add or remove; `conflicts` is the manifest body; `orderPlan` is
+ * the merged slide order in merge ids; `identity` maps each incoming slide's key
+ * to its merge id.
+ */
+export function classifyRebase(workspaceDir, revisionId) {
+  const revision = readRevision(workspaceDir);
+  if (!revision) {
+    const e = new Error("this deck has no accepted base — adopt it before rebasing.");
+    e.code = "no_base";
+    throw e;
+  }
+  const incoming = readStaged(workspaceDir, revisionId);
+  const missing = (code, message) => Object.assign(new Error(message), { code });
+  if (!incoming) throw missing("no_such_revision", `no staged snapshot ${revisionId}`);
+  const theirsDigests = packageDigests(incoming.sha256, () => {
+    const bytes = stagedBytes(workspaceDir, revisionId);
+    if (!bytes) throw missing("no_such_revision", `no staged snapshot ${revisionId}`);
+    return bytes;
+  });
+  const baseDigests = packageDigests(revision.base?.sha256, () => {
+    try {
+      return fs.readFileSync(acceptedBasePath(workspaceDir));
+    } catch {
+      throw missing("no_base", "this deck's accepted base file is missing — adopt it again before rebasing.");
+    }
+  });
+  const baseContent = baseDigests.slides;
+  const incomingContent = theirsDigests.slides;
+  const sharedChanged = baseDigests.design !== theirsDigests.design;
+
+  const materialized = materializedInputs(workspaceDir);
+  const dirty = computeDirty(workspaceDir, revision, materialized);
+  const dirtyFiles = new Set(dirty.dirtySlides);
+  const localRemoved = new Set(dirty.removed);
+  const renames = localRenames(revision, materialized.inputs);
+  // Each base slide under the name its file has NOW.
+  const base = keyed(revision.base?.slides).map((b) => (b.file && renames[b.file] ? { ...b, file: renames[b.file], renamed: true } : b));
+  const theirs = keyed(incoming.slides);
+  const match = matchSlides(base, theirs, (b, i) => baseContent.get(b.part) === incomingContent.get(i.part));
+
+  const nameOf = (slide) => slide.guid ?? slide.key ?? slide.part;
+  const mine = (b) => Boolean(b.file && !b.renamed && dirtyFiles.has(b.file));
+  // A slide the user deleted locally. `computeDirty` reports it as dirty like
+  // any other change, so without this it would be labelled `both-edited` — true
+  // in spirit, wrong in the one word the user reads to decide what to do.
+  const locallyDeleted = (b) => Boolean(b.file && !b.renamed && localRemoved.has(b.file));
+
+  const conflicts = [];
+  const remoteOnly = [];
+  const localOnly = [];
+  const unchanged = [];
+  const conflict = (kind, b, i, detail, extra = {}) =>
+    conflicts.push({
+      id: `c${conflicts.length + 1}`,
+      kind,
+      guid: b ? nameOf(b) : i ? nameOf(i) : null,
+      key: b?.key ?? i?.key ?? null,
+      file: b?.file ?? null,
+      baseSha256: b?.package ?? null,
+      incomingSha256: i?.package ?? null,
+      inputSha256: dirty.inputDigest,
+      detail,
+      ...extra,
+    });
+
+  // Only a broken package gets here (a valid one gives every slide an id), and
+  // nothing about a broken package is guessed into place.
+  for (const { slide, why } of match.unnamed) {
+    const isBase = base.includes(slide);
+    conflict("ambiguous-identity", isBase ? slide : null, isBase ? null : slide, why, { part: slide.part });
+  }
+
+  for (const { base: b, incoming: i } of match.pairs) {
+    const changedThere = baseContent.get(b.part) !== incomingContent.get(i.part);
+    if (changedThere && locallyDeleted(b)) {
+      conflict(
+        "local-deleted",
+        b,
+        i,
+        "this slide was deleted locally, and the incoming file changed it — " +
+          "reinstating their version and dropping it are both defensible, so neither is chosen",
+      );
+    } else if (changedThere && mine(b)) {
+      conflict("both-edited", b, i, "this slide changed on both sides");
+    } else if (changedThere) {
+      remoteOnly.push({ id: b.key, key: b.key, guid: nameOf(b), action: "refresh", file: b.file ?? null, index: i.index });
+    } else if (mine(b)) {
+      localOnly.push({ key: b.key, guid: nameOf(b), file: b.file ?? null });
+    } else {
+      unchanged.push(nameOf(b));
+    }
+  }
+
+  for (const b of match.baseOnly) {
+    if (!mine(b) || locallyDeleted(b)) {
+      remoteOnly.push({ id: b.key, key: b.key, guid: nameOf(b), action: "delete", file: b.file ?? null });
+    } else if (match.unclaimedLineage.has(b)) {
+      conflict(
+        "ambiguous-identity",
+        b,
+        null,
+        "their file holds several copies of this slide and none of them can be told to be it, " +
+          "so there is no certain place for your edit",
+      );
+    } else {
+      conflict("incoming-deleted", b, null, "the incoming file no longer has this slide, but it has unpublished local edits");
+    }
+  }
+
+  const identity = {};
+  for (const { base: b, incoming: i } of match.pairs) identity[i.key] = b.key;
+  for (const i of match.incomingOnly) {
+    if (!i.key) continue;
+    identity[i.key] = `in:${i.key}`;
+    // A copy PowerPoint's Duplicate Slide made carries its original's GUID.
+    const copy = Boolean(i.guid && theirs.some((s) => s !== i && s.guid === i.guid));
+    remoteOnly.push({ id: `in:${i.key}`, key: null, guid: nameOf(i), action: "add", file: null, index: i.index, copy });
+  }
+
+  // Order. Their order, plus every move and addition only this side made.
+  const fileFor = new Map(base.filter((b) => b.key && b.file).map((b) => [b.file, b.key]));
+  const { order: orderPlan, bothMoved } = mergeOrder(
+    base.map((b) => b.key).filter(Boolean),
+    theirs.map((i) => identity[i.key]).filter(Boolean),
+    slideFileOrder(workspaceDir).map((file) => fileFor.get(file) ?? `local:${file}`),
+  );
+
+  const notes = [];
+  if (sharedChanged) {
+    notes.push(
+      "their save changed the shared design (theme, masters or layouts); it is taken as saved, and " +
+        "slides you edited will render onto it — check them in the next preview",
+    );
+  }
+  for (const id of bothMoved) {
+    const b = base.find((s) => s.key === id);
+    notes.push(`${b?.file ?? nameOf(b ?? { key: id })} was moved on both sides — it keeps their position`);
+  }
+
+  return {
+    revisionId,
+    baseSha256: revision.base?.sha256 ?? null,
+    incomingSha256: incoming.sha256,
+    remoteOnly,
+    localOnly,
+    unchanged,
+    conflicts,
+    orderPlan,
+    identity,
+    renames,
+    sharedChanged,
+    notes,
+    generation: revision.generation,
+    inputDigest: dirty.inputDigest,
+  };
+}
+
+/**
+ * Write the diagnostic conflict manifest and the complete recovery evidence:
+ * the accepted base, the whole incoming file, and a snapshot of the local
+ * inputs as they stood. A per-slide preview is an extra, never the only copy.
+ */
+export function recordConflicts(workspaceDir, classified) {
+  const dir = stagedDir(workspaceDir, classified.revisionId);
+  const localDir = path.join(dir, "local-snapshot");
+  fs.mkdirSync(localDir, { recursive: true });
+  for (const sub of ["slides", "assets", "conversions"]) {
+    const from = path.join(workspaceDir, sub);
+    if (fs.existsSync(from)) fs.cpSync(from, path.join(localDir, sub), { recursive: true });
+  }
+  writeConflicts(workspaceDir, {
+    revisionId: classified.revisionId,
+    baseSha256: classified.baseSha256,
+    incomingSha256: classified.incomingSha256,
+    generation: classified.generation,
+    inputDigest: classified.inputDigest,
+    detectedAt: nowIso(),
+    conflicts: classified.conflicts,
+    recovery: {
+      base: "state/base.pptx",
+      incoming: `state/staged/${classified.revisionId}/incoming.pptx`,
+      local: `state/staged/${classified.revisionId}/local-snapshot/`,
+    },
+    resolveWith: `slidemind rebase <deck> --resolve <resolution.json>`,
+  });
+  return classified.conflicts;
+}
+
+// Two-phase in-memory rename avoids filename swaps clobbering each other.
+function applyOrder(ws, order, fileByKey) {
+  const all = slideFileOrder(ws);
+  const ordered = [...order.map(key => fileByKey.get(key)).filter(file => file && all.includes(file))];
+  ordered.push(...all.filter(file => !ordered.includes(file)));
+  const renames = new Map(ordered.map((file, i) => [file, `${String(i + 1).padStart(2, '0')}-${file.replace(/^\d+-/, '')}`]));
+  const pending = [];
+  const guids = loadSlideGuids(ws), nextGuids = {};
+  for (const [from, to] of renames) {
+    const a = from.replace(/\.(jsx|pptx)$/, ''), b = to.replace(/\.(jsx|pptx)$/, '');
+    for (const [oldRel, newRel] of [[`slides/${from}`, `slides/${to}`], [`slides/${a}.brief.md`, `slides/${b}.brief.md`], [`conversions/${a}.json`, `conversions/${b}.json`], [`conversions/${a}.slide.pptx`, `conversions/${b}.slide.pptx`]]) {
+      if (!fs.existsSync(path.join(ws, oldRel))) continue;
+      let bytes = fs.readFileSync(path.join(ws, oldRel));
+      if (oldRel.startsWith('conversions/') && oldRel.endsWith('.json')) {
+        const record = JSON.parse(bytes); record.slide = `slides/${to}`;
+        if (record.source?.package) record.source.package = `${b}.slide.pptx`;
+        bytes = Buffer.from(JSON.stringify(record, null, 2));
+      }
+      pending.push({ oldRel, newRel, bytes });
+    }
+    if (guids[`slides/${from}`]) nextGuids[`slides/${to}`] = guids[`slides/${from}`];
+  }
+  for (const entry of pending) fs.rmSync(path.join(ws, entry.oldRel), { force: true });
+  for (const entry of pending) fs.writeFileSync(path.join(ws, entry.newRel), entry.bytes);
+  fs.writeFileSync(path.join(ws, 'state', 'slide-guids.json'), JSON.stringify(Object.fromEntries(Object.entries(nextGuids).map(([file, guid]) => [file, { guid, sha256: null }]))));
+  for (const [key, file] of fileByKey) fileByKey.set(key, renames.get(file) ?? file);
+  return renames;
+}
+
+// An explicit `rebase --incoming` must not bypass the checks pull performs.
+// Remote artifacts were downloaded by pull and are read from its immutable
+// staging directory; this path has no network or publication authority.
+function assessStagedBusiness(ws, revisionId) {
+  const decoded = readPresentationContext(unzip(stagedBytes(ws, revisionId)));
+  const remembered = readRemote(ws)?.extensions ?? [];
+  const declarations = decoded?.context?.extensions ?? [];
+  const blocked = message => { throw Object.assign(new Error(message), { code: 'validation_required' }); };
+  if (decoded?.corrupt || remembered.some(e => e.required !== false && !declarations.some(d => d.id === e.id && d.required !== false))) blocked('The staged remote generation is missing its required business context. Pull its exact artifacts before rebasing.');
+  if (!declarations.length) return;
+  const dependencies = declarations.flatMap(e => e.refs ?? []);
+  const request = { dependencies, context: decoded.context };
+  const hydrate = runDeclared(ws, declarations, 'hydrate', request);
+  for (const result of hydrate.results) {
+    for (const artifact of result.response.artifacts ?? []) {
+      const ref = (result.declaration.refs ?? []).find(r => r.artifactId === artifact.artifactId);
+      if (!ref?.sha256) { if (artifact.required !== false) blocked(`No exact ref for ${artifact.artifactId}`); else continue; }
+      const file = path.join(stagedDir(ws, revisionId), 'context', `${ref.sha256}-${ref.artifactId}`.replace(/[^A-Za-z0-9._-]/g, '-'));
+      if (!fs.existsSync(file)) { if (artifact.required !== false) blocked(`The exact ${artifact.artifactId} is not staged; pull before rebasing.`); else continue; }
+      const placement = materializeArtifact(ws, { ...artifact, extensionId: result.id, sha256: ref.sha256 }, fs.readFileSync(file));
+      if (placement.isolated) blocked(`Unsafe artifact placement for ${artifact.artifactId}`);
+      const registryPath = path.join(ws, 'state', 'artifact-materializations.json');
+      let registry = { artifacts: [] };
+      try { registry = JSON.parse(fs.readFileSync(registryPath, 'utf8')); } catch {}
+      registry.artifacts = (registry.artifacts ?? []).filter(a => a.extensionId !== result.id || a.artifactId !== ref.artifactId);
+      registry.artifacts.push({ extensionId: result.id, artifactId: ref.artifactId, localPath: path.relative(ws, placement.path), sha256: ref.sha256 });
+      fs.writeFileSync(registryPath, JSON.stringify(registry));
+    }
+  }
+  const restored = runDeclared(ws, declarations, 'hydrate', request);
+  const assessed = runDeclared(ws, declarations, 'assess', request);
+  const blockers = [...restored.blockers, ...assessed.blockers];
+  if (blockers.length) blocked(blockers.map(b => b.message).join('\n'));
+}
+
+// Take one slide of the incoming package back to its package form on disk. The
+// local hydration of that slide (JSX plus its conversion record) is removed:
+// keeping it would be keeping a projection of content that no longer exists.
+// The one-slide package with its GUID tag rewritten in place.
+function withSlideGuid(bytes, guid) {
+  const files = unzip(Buffer.from(bytes));
+  const part = slideOrderPaths(files)[0];
+  return part && updateSlideTag(files, part, TAG_GUID, guid) ? zip(files) : bytes;
+}
+
+function refreshSlideFromIncoming(workspaceDir, incomingBuf, entry, folds, ownGuid = null) {
+  const slidesDir = path.join(workspaceDir, "slides");
+  fs.mkdirSync(slidesDir, { recursive: true });
+  const fold = folds.get(entry.index);
+  if (!fold) return null;
+  const stem = entry.file
+    ? entry.file.replace(/\.(jsx|pptx)$/, "")
+    : `${String(entry.index).padStart(2, "0")}-incoming-${String(entry.guid ?? entry.key).replace(/[^a-z0-9]/gi, "").slice(0, 8)}`;
+  if (entry.file) {
+    fs.rmSync(path.join(slidesDir, entry.file), { force: true });
+    if (entry.file.endsWith(".jsx")) removeConversionRecord(workspaceDir, entry.file);
+  }
+  const file = `${stem}.pptx`;
+  fs.writeFileSync(path.join(slidesDir, file), Buffer.from(ownGuid ? withSlideGuid(fold.bytes, ownGuid) : fold.bytes));
+  return file;
+}
+
+/**
+ * Apply a classified rebase. Remote-only changes land, local-only edits stay
+ * dirty against the NEW accepted base, and a conflict activates nothing.
+ *
+ * `resolutions` (from `rebase --resolve <file>`) is validated against the exact
+ * base/incoming/input hashes recorded when the conflict was detected — a stale
+ * resolution is refused with everything intact. There is no generic force.
+ */
+export function applyRebase(workspaceDir, revisionId, { owner, resolutions = null, staged = false } = {}) {
+  if (!staged) {
+    const classified = classifyRebase(workspaceDir, revisionId);
+    // Preserve the normal conflict manifest on the real workspace.
+    if (classified.conflicts.length && !resolutions) {
+      recordConflicts(workspaceDir, classified);
+      throw Object.assign(new Error(`${classified.conflicts.length} conflict(s) need a decision; nothing activated.`), { code: 'rebase_conflicts', conflicts: classified.conflicts });
+    }
+    const tx = stageWorkspace(workspaceDir);
+    try {
+      tx.copySnapshot(revisionId);
+      const result = applyRebase(tx.workspace, revisionId, { owner, resolutions, staged: true });
+      if (readStaged(workspaceDir, revisionId)?.source?.kind === 'remote') assessStagedBusiness(tx.workspace, revisionId);
+      tx.activate({ checkpoint: () => assertCheckpoint(workspaceDir, { owner, generation: classified.generation, digest: classified.inputDigest }) });
+      return result;
+    } finally { tx.dispose(); }
+  }
+  const classified = classifyRebase(workspaceDir, revisionId);
+  const revision = readRevision(workspaceDir);
+  const incoming = readStaged(workspaceDir, revisionId);
+  const incomingBuf = stagedBytes(workspaceDir, revisionId);
+  if (!incomingBuf) {
+    const e = new Error(`staged snapshot ${revisionId} has no bytes`);
+    e.code = "no_such_revision";
+    throw e;
+  }
+
+  let outstanding = classified.conflicts;
+  let chosen = new Map();
+  if (resolutions) {
+    const { applied, rejected } = matchResolutions(classified, resolutions);
+    if (rejected.length > 0) {
+      const e = new Error(
+        `these resolutions no longer match the state they were written against:\n  ` +
+          rejected.map((r) => `${r.id}: ${r.why}`).join("\n  ") +
+          `\nNothing was activated. Re-read the conflict manifest and resolve again.`,
+      );
+      e.code = "resolution_stale";
+      e.rejected = rejected;
+      throw e;
+    }
+    chosen = applied;
+    outstanding = classified.conflicts.filter((c) => !chosen.has(c.id));
+  }
+
+  if (outstanding.length > 0) {
+    recordConflicts(workspaceDir, { ...classified, conflicts: outstanding });
+    const e = new Error(
+      `${outstanding.length} conflict(s) need a decision — nothing was changed. ` +
+        `The base, the incoming file and a snapshot of your local slides are all kept under ` +
+        `state/staged/${revisionId}/. Resolve with \`--resolve <file>\`.`,
+    );
+    e.code = "rebase_conflicts";
+    e.conflicts = outstanding;
+    throw e;
+  }
+
+  // Everything that will touch the working tree, worked out BEFORE anything is
+  // written, so a failure halfway through has a journal to resume from.
+  const refresh = classified.remoteOnly.filter((r) => r.action !== "delete");
+  const removals = classified.remoteOnly.filter((r) => r.action === "delete");
+  const incomingKeys = keyed(incoming.slides);
+  for (const [id, choice] of chosen) {
+    const conflict = classified.conflicts.find((c) => c.id === id);
+    if (!conflict?.key) continue;
+    if (choice.choice === "incoming") {
+      const inc = incomingKeys.find((s) => s.key && classified.identity[s.key] === conflict.key);
+      if (inc) {
+        refresh.push({
+          id: conflict.key,
+          key: conflict.key,
+          guid: conflict.guid,
+          action: "refresh",
+          file: conflict.file,
+          index: inc.index,
+        });
+      } else {
+        removals.push({ id: conflict.key, key: conflict.key, guid: conflict.guid, action: "delete", file: conflict.file });
+      }
+    }
+    // "local" keeps the working file exactly as it is; it simply stays dirty
+    // against the new base. "merged" means the user already wrote the file.
+  }
+
+  const journal = journalBegin(workspaceDir, {
+    op: "rebase",
+    stagingDir: `state/staged/${revisionId}`,
+    detail: {
+      revisionId,
+      from: revision.base?.sha256 ?? null,
+      to: incoming.sha256,
+      refresh: refresh.map((r) => r.guid),
+      remove: removals.map((r) => r.guid),
+    },
+  });
+  assertCheckpoint(workspaceDir, {
+    owner,
+    generation: classified.generation,
+    digest: classified.inputDigest,
+  });
+
+  const picks = [...new Set(refresh.map((r) => r.index).filter(Boolean))];
+  const folds = new Map(
+    (picks.length ? foldPickedSlides(incomingBuf, picks, { sourceName: "incoming" }) : []).map(
+      (f) => [f.selection, f],
+    ),
+  );
+
+  journalStep(workspaceDir, journal, "materialize-incoming");
+  // Merge id -> working file: a base slide by its key, a slide added here by
+  // its file, a slide arriving from their file by the id `classifyRebase` gave it.
+  const fileByKey = new Map();
+  for (const slide of keyed(revision.base?.slides)) {
+    if (slide.key && slide.file) fileByKey.set(slide.key, classified.renames[slide.file] ?? slide.file);
+  }
+  for (const id of classified.orderPlan) {
+    if (id.startsWith("local:")) fileByKey.set(id, id.slice("local:".length));
+  }
+  for (const entry of refresh) {
+    // Two working files never claim one identity: a duplicated slide's copy gets
+    // its own GUID, in the slide it brings and in the sidecar — the way adopt
+    // re-mints a duplicate.
+    const ownGuid = entry.copy ? mintSlideGuid() : null;
+    const file = refreshSlideFromIncoming(workspaceDir, incomingBuf, entry, folds, ownGuid);
+    if (file) {
+      fileByKey.set(entry.id, file);
+      const previousGuid = entry.file ? loadSlideGuids(workspaceDir)[`slides/${entry.file}`] : null;
+      const guid = ownGuid ?? (incoming.slides ?? []).find((s) => s.index === entry.index)?.guid ?? previousGuid;
+      if (guid) saveSlideGuids(workspaceDir, { [`slides/${file}`]: guid });
+    }
+  }
+  for (const entry of removals) {
+    fileByKey.delete(entry.id);
+    if (!entry.file) continue;
+    fs.rmSync(path.join(workspaceDir, "slides", entry.file), { force: true });
+    if (entry.file.endsWith(".jsx")) removeConversionRecord(workspaceDir, entry.file);
+  }
+
+  const beforeOrder = materializedInputs(workspaceDir);
+  const renamed = applyOrder(workspaceDir, classified.orderPlan, fileByKey);
+  journalStep(workspaceDir, journal, "advance-base");
+  fs.writeFileSync(acceptedBasePath(workspaceDir), incomingBuf);
+  const inventory = inventoryPackage(incomingBuf);
+  const materialized = materializedInputs(workspaceDir);
+
+  // The new baseline records what the incoming side contributed. Local edits are
+  // deliberately NOT folded in: they stay dirty against the new base, which is
+  // what "unpublished local work" means.
+  const renamedKey = key => {
+    for (const [from, to] of renamed) {
+      const a = from.replace(/\.(jsx|pptx)$/, ''), b = to.replace(/\.(jsx|pptx)$/, '');
+      if (key === `slides/${from}`) return `slides/${to}`;
+      if (key === `slides/${a}.brief.md`) return `slides/${b}.brief.md`;
+      if (key.startsWith(`conversions/${a}.`)) return key.replace(`conversions/${a}.`, `conversions/${b}.`);
+    }
+    return key;
+  };
+  // A file renamed here carries its accepted bytes under its new name: it is
+  // the same slide, moved, and must not read as deleted-plus-added afterwards.
+  // Built fresh, not moved key by key: in a swap each name is the other's target.
+  const priorInputs = {};
+  for (const [rel, hash] of Object.entries(revision.baseline?.inputs ?? {})) {
+    const to = rel.startsWith("slides/") ? classified.renames[rel.slice("slides/".length)] : undefined;
+    priorInputs[to ? `slides/${to}` : rel] = hash;
+  }
+  const baseline = {};
+  for (const [key, hash] of Object.entries(priorInputs)) {
+    const moved = renamedKey(key);
+    baseline[moved] = key.startsWith('conversions/') && key.endsWith('.json') && beforeOrder.inputs[key] === hash ? materialized.inputs[moved] : hash;
+  }
+  for (const entry of [...refresh, ...removals]) {
+    if (entry.file) {
+      delete baseline[renamedKey(`slides/${entry.file}`)];
+      const stem = entry.file.replace(/\.(jsx|pptx)$/, '');
+      delete baseline[renamedKey(`conversions/${stem}.json`)];
+      delete baseline[renamedKey(`conversions/${stem}.slide.pptx`)];
+    }
+    const landed = fileByKey.get(entry.id);
+    if (landed && materialized.inputs[`slides/${landed}`]) baseline[`slides/${landed}`] = materialized.inputs[`slides/${landed}`];
+  }
+
+  // Their order, in this deck's file names: what the new base IS. Where the
+  // merged order differs (a move or an addition made here), the deck stays
+  // dirty on order until the next publish carries it.
+  const fileOfIncoming = (slide) => (slide.key ? fileByKey.get(classified.identity[slide.key]) ?? null : null);
+  const incomingInventory = keyed(inventory.slides);
+  const baseOrder = incomingInventory
+    .map(fileOfIncoming)
+    .filter((file) => file && baseline[`slides/${file}`] !== undefined);
+
+  journalStep(workspaceDir, journal, "write-revision");
+  const next = writeRevision(workspaceDir, {
+    ...revision,
+    generation: revision.generation + 1,
+    base: {
+      sha256: inventory.sha256,
+      acceptedAt: nowIso(),
+      slideCount: inventory.slideCount,
+      packageSha256: inventory.packageSha256,
+      order: inventory.order,
+      slides: inventory.slides.map((s, i) => ({
+        ...s,
+        file: fileOfIncoming(incomingInventory[i]),
+      })),
+    },
+    baseline: {
+      ...revision.baseline,
+      inputs: baseline,
+      order: baseOrder,
+      shared: materialized.shared,
+      at: nowIso(),
+    },
+    candidate: null, // every candidate was built against the old base
+    conflicts: null,
+    rebasedFrom: { revisionId, at: nowIso(), incomingSha256: incoming.sha256 },
+  });
+  clearConflicts(workspaceDir);
+  journalComplete(workspaceDir);
+
+  // A rebase onto a save pulled from the bound item moves the accepted remote
+  // revision with the base. Without this the next publish compares the item's
+  // eTag against the one before that save and stages the same save again as
+  // "somebody else saved first", forever.
+  const remote = readRemote(workspaceDir);
+  if (remote && incoming.source?.kind === "remote" && incoming.source.itemId === remote.itemId) {
+    writeRemote(workspaceDir, {
+      ...remote,
+      acceptedETag: incoming.source.eTag ?? remote.acceptedETag,
+      acceptedCTag: incoming.source.cTag ?? remote.acceptedCTag,
+      acceptedSha256: incoming.sha256,
+    });
+  }
+
+  const after = computeDirty(workspaceDir, next);
+  return {
+    revisionId,
+    applied: refresh.length + removals.length,
+    refreshed: refresh.map((r) => r.guid),
+    removed: removals.map((r) => r.guid),
+    localOnly: classified.localOnly,
+    notes: classified.notes,
+    stillDirty: after.dirtySlides,
+    generation: next.generation,
+  };
+}
+
+/**
+ * Bind each resolution to the exact hashes the conflict was detected against.
+ * A choice written before an input moved is REFUSED — the user resolved a
+ * different situation, and applying it anyway would silently discard whatever
+ * changed since. There is deliberately no generic force flag.
+ */
+export function matchResolutions(classified, resolutions) {
+  const applied = new Map();
+  const rejected = [];
+  const byId = new Map(classified.conflicts.map((c) => [c.id, c]));
+
+  if (resolutions.revisionId && resolutions.revisionId !== classified.revisionId) {
+    rejected.push({
+      id: "(file)",
+      why: `it resolves ${resolutions.revisionId}, but this rebase is ${classified.revisionId}`,
+    });
+    return { applied, rejected };
+  }
+  if (resolutions.baseSha256 && resolutions.baseSha256 !== classified.baseSha256) {
+    rejected.push({ id: "(file)", why: "the accepted base moved since it was written" });
+    return { applied, rejected };
+  }
+
+  for (const entry of resolutions.resolutions ?? []) {
+    const conflict = byId.get(entry.id);
+    if (!conflict) {
+      rejected.push({ id: entry.id, why: "there is no conflict with that id in this rebase" });
+      continue;
+    }
+    if (!["local", "incoming", "merged"].includes(entry.choice)) {
+      rejected.push({ id: entry.id, why: `choice must be local, incoming or merged (got ${entry.choice})` });
+      continue;
+    }
+    for (const field of ["baseSha256", "incomingSha256", "inputSha256"]) {
+      if (entry[field] && entry[field] !== conflict[field]) {
+        rejected.push({ id: entry.id, why: `${field} no longer matches — the deck moved since you resolved it` });
+      }
+    }
+    if (entry.choice === "merged" && !entry.mergedFile) {
+      rejected.push({ id: entry.id, why: "a merged choice must name the file you wrote" });
+      continue;
+    }
+    if (rejected.some((r) => r.id === entry.id)) continue;
+    applied.set(entry.id, entry);
+  }
+
+  for (const conflict of classified.conflicts) {
+    if (!applied.has(conflict.id)) {
+      rejected.push({ id: conflict.id, why: "this conflict has no resolution in the file" });
+    }
+  }
+  return { applied, rejected };
+}
+
+/** The skeleton a user fills in — every hash already bound. */
+export function resolutionTemplate(classified) {
+  return {
+    schemaVersion: 1,
+    revisionId: classified.revisionId,
+    baseSha256: classified.baseSha256,
+    incomingSha256: classified.incomingSha256,
+    resolutions: classified.conflicts.map((c) => ({
+      id: c.id,
+      kind: c.kind,
+      guid: c.guid,
+      key: c.key,
+      file: c.file,
+      detail: c.detail,
+      choice: "local | incoming | merged",
+      mergedFile: null,
+      baseSha256: c.baseSha256,
+      incomingSha256: c.incomingSha256,
+      inputSha256: c.inputSha256,
+    })),
+  };
+}
+
+/** Recover an interrupted rebase: the journal names the generation to finish. */
+export function resumeRebase(workspaceDir, journal, { owner } = {}) {
+  if (journal?.op !== "rebase") return null;
+  const revisionId = journal.detail?.revisionId;
+  if (!revisionId) {
+    journalComplete(workspaceDir);
+    return { resumed: false, reason: "the journal names no snapshot — cleared" };
+  }
+  // Re-running from the staged bytes is idempotent: classification reads the
+  // CURRENT base, so a rebase that already advanced simply finds nothing to do.
+  const result = applyRebase(workspaceDir, revisionId, { owner });
+  return { resumed: true, ...result };
+}