slidemind 0.2.3 → 0.3.0

package/src/lib/overwrite-guard.mjs

@@ -0,0 +1,91 @@
+// Overwrite guard: never silently clobber manual PowerPoint edits.
+//
+// `slidemind build-pptx` (and push's fallback save) writes its output file
+// wholesale. If the user opened the last build in desktop PowerPoint and moved
+// a shape, retyped a line, or recoloured a box, that work lives ONLY in that
+// file — the deck's jsx knows nothing about it — and a rebuild would erase it
+// with no warning. This module answers the one question that stands between a
+// rebuild and that loss: has anything in the file changed since we wrote it?
+//
+// The answer needs no server and no diff engine (the CLI ships none, by
+// design — intern-slidemind PLAN_CLI_RECONCILE.md §3): a slidemind-authored
+// slide carries its own drift BASELINE in its tags, the structural projection
+// P(slide) as it stood at bake time. Recomputing P over the file on disk and
+// comparing the two IS the detection. What to do about a difference — fold the
+// text edits back into the jsx, report the rest — is Phase B's server round
+// trip; here an edited slide only means "refuse, and say which slide".
+
+import fs from "node:fs";
+
+import { slideOrderPaths } from "../pptx/ooxml.mjs";
+import {
+  TAG_GUID,
+  computeProjection,
+  decodeSourceTags,
+  readSlideTags,
+} from "../pptx/tags.mjs";
+import { unzip } from "../pptx/zip.mjs";
+
+/**
+ * Slides of the .pptx at `outPath` that were edited since the CLI last wrote
+ * it. `[]` means the file is safe to overwrite — it is missing, it is not a
+ * package we can read, or every slide we can vouch for still matches its
+ * baseline. Entries are `{ slideIndex, slidePath, guid, baseline, current }`
+ * with `slideIndex` 1-based in PLAY order (the number PowerPoint shows the
+ * user). The two projections ride along because the server-side reconcile
+ * (Phase B) diffs exactly them — computing them twice would mean unzipping and
+ * re-parsing the whole package twice.
+ */
+export function detectManualEdits(outPath) {
+  if (!outPath || !fs.existsSync(outPath)) return [];
+
+  let files;
+  try {
+    files = unzip(fs.readFileSync(outPath));
+  } catch {
+    // Not a readable OPC package — nothing slidemind ever baked is in there to
+    // protect, and refusing here would block a build over any stray --out file.
+    return [];
+  }
+
+  const edited = [];
+  slideOrderPaths(files).forEach((slidePath, i) => {
+    const tags = readSlideTags(files, slidePath);
+    const decoded = decodeSourceTags(tags);
+    // No decodable source (foreign or native-reused slide) or no baked
+    // baseline (pre-baseline bake): nothing to compare against. Skipping is
+    // the honest answer — an unverifiable slide is not evidence of an edit.
+    if (!decoded?.baseline) return;
+    // Both sides are produced by the SAME emitter, so key order matches and a
+    // string compare is a stable structural compare.
+    const current = computeProjection(files, slidePath);
+    if (JSON.stringify(current) === JSON.stringify(decoded.baseline)) return;
+    edited.push({
+      slideIndex: i + 1,
+      slidePath,
+      guid: tags[TAG_GUID] ?? null,
+      baseline: decoded.baseline,
+      current,
+    });
+  });
+  return edited;
+}
+
+// The refusal a manually-edited output file earns when nothing can be done for
+// it here: the user's PowerPoint edits exist in that file ALONE, so the build
+// stops and names the slides rather than overwriting them. Reachable only for
+// slides the deck cannot address — one carrying no jsx of ours to fold into.
+// Everything else goes through the server-side reconcile (Phase B).
+export function manualEditsError(outFile, edited) {
+  const numbers = edited.map((e) => e.slideIndex).join(", ");
+  const err = new Error(
+    `${outFile} was edited in PowerPoint since the CLI last wrote it — ` +
+      `slide ${numbers} (${edited.length} of them) no longer match the source ` +
+      `this deck would render.\n` +
+      `Rebuilding would discard those edits: re-run with --force to discard ` +
+      `these manual edits, or use --out <other file> to keep them.`,
+  );
+  err.code = "manual_edits";
+  err.manualEdits = edited;
+  return err;
+}

package/src/lib/reconcile-ack.mjs

@@ -0,0 +1,46 @@
+// Deck-local sidecar recording the last ACKNOWLEDGED drift hash per slide file
+// (`{ "01-cover.jsx": "<nowHash>" }`), keyed exactly like the render request's
+// `slides` and `reconcile` maps. File handling mirrors slide-guids.mjs.
+//
+// The ack is what keeps the reconcile loop finite. When the server reports a
+// manual PowerPoint edit it cannot fold on its own (a moved shape), the build
+// refuses and the hash of that slide's CURRENT state is stored here. The user
+// folds the change into the jsx and re-runs: the output file has not changed,
+// so the hash still matches, the server short-circuits its diff, and the build
+// proceeds. Any NEW manual edit changes the hash and re-arms the report.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const SIDECAR = ".reconcile-ack.json";
+
+/** { [fileName]: nowHash } — `{}` when the deck has no sidecar (or a broken one). */
+export function loadReconcileAcks(deckDir) {
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(path.join(deckDir, SIDECAR), "utf8"));
+  } catch {
+    return {};
+  }
+  if (!parsed || typeof parsed !== "object") return {};
+  const out = {};
+  for (const [file, hash] of Object.entries(parsed)) {
+    // basename: the key is a slide FILE NAME, never a path — a crafted one can
+    // then never travel out of this map into a write.
+    if (typeof hash === "string" && hash) out[path.basename(file)] = hash;
+  }
+  return out;
+}
+
+/** Merge acks into the sidecar (last write wins per file). No-op when empty. */
+export function saveReconcileAcks(deckDir, acks) {
+  if (!acks || Object.keys(acks).length === 0) return;
+  const merged = loadReconcileAcks(deckDir);
+  for (const [file, hash] of Object.entries(acks)) {
+    if (typeof hash === "string" && hash) merged[path.basename(file)] = hash;
+  }
+  fs.writeFileSync(
+    path.join(deckDir, SIDECAR),
+    `${JSON.stringify(merged, null, 2)}\n`,
+  );
+}

package/src/lib/reconcile.mjs

@@ -0,0 +1,306 @@
+// Manual-edit reconcile, CLI half (intern-slidemind PLAN_CLI_RECONCILE.md,
+// Phase B2). Two functions around ONE server round trip:
+//
+//   collectReconcileInputs  — what the render request carries: for every slide
+//                             the user edited in PowerPoint since the last
+//                             build, its baked baseline projection and its
+//                             current one, keyed by jsx file name. Reads the
+//                             deck's previous OUTPUT FILE (`build-pptx`).
+//   collectLiveReconcileInputs — the same field, read from the LIVE deck via
+//                             the pane's export op. What `push --replace` must
+//                             use: it wipes what is on screen, not a file.
+//   applyReconcileResponse  — what comes back: text edits already folded into
+//                             the jsx (write them down), a hash to acknowledge,
+//                             and the edits that need human judgment (refuse).
+//
+// The CLI ships NO diff and NO fold logic — same rule as lint and the exporter
+// ("served on the wire", plan §3). It supplies projections and applies results;
+// the server decides what changed and what that means.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { computeProjection, decodeSourceTags } from "../pptx/tags.mjs";
+import { unzip } from "../pptx/zip.mjs";
+import { loadConversions } from "./conversions.mjs";
+import { detectManualEdits, manualEditsError } from "./overwrite-guard.mjs";
+import { loadReconcileAcks, saveReconcileAcks } from "./reconcile-ack.mjs";
+import { reconcileSlideGuids } from "./slide-guids.mjs";
+
+/**
+ * The render request's `reconcile` field for `deckDir`'s previous output at
+ * `outFile`, or null when there is nothing to reconcile. Throws the Phase A
+ * `manual_edits` refusal for an edited slide this deck cannot address.
+ */
+export function collectReconcileInputs({ deckDir, outFile, force = false }) {
+  // `--force` is the explicit "discard my edits" — no scan, no field, exactly
+  // the blind build the CLI did before any of this existed.
+  if (force) return null;
+  const edits = detectManualEdits(outFile);
+  if (edits.length === 0) return null;
+
+  // GUID → slide file name. reconcileSlideGuids, not loadSlideGuids: a reorder
+  // renames every file, so the raw sidecar can still be keyed by the old names
+  // — and the reconcile map must key by the names `slides` uses. It is
+  // idempotent, so the render's own call right after finds nothing to do.
+  const fileByGuid = new Map();
+  for (const [slidePath, guid] of Object.entries(reconcileSlideGuids(deckDir))) {
+    fileByGuid.set(guid, path.basename(slidePath));
+  }
+  // B3 exclusion — CONVERTED slides (`slidemind adopt`). Their drift protection
+  // is the conversion-gate machinery, which already holds a baseline of the
+  // ORIGINAL slide; driving a second reconcile from the render bake's baseline
+  // would have two mechanisms arguing over one slide. Matched by GUID, not file
+  // name, so a reorder cannot smuggle one back in before the records rehome.
+  const convertedGuids = new Set(
+    Object.values(loadConversions(deckDir, { includeSource: false }))
+      .map((record) => record.guid)
+      .filter(Boolean),
+  );
+
+  const acks = loadReconcileAcks(deckDir);
+  const reconcile = {};
+  const refusals = [];
+  for (const edit of edits) {
+    if (edit.guid && convertedGuids.has(edit.guid)) continue;
+    const fileName = edit.guid ? fileByGuid.get(edit.guid) : null;
+    // B3 exclusion — a slide with no jsx of ours behind it: a native reused
+    // .pptx, or a slide pushed by another deck. There is nothing to fold an
+    // edit INTO, so Phase A's refusal still governs it.
+    if (!fileName) {
+      refusals.push(edit);
+      continue;
+    }
+    reconcile[fileName] = {
+      baseline: edit.baseline,
+      current: edit.current,
+      ...(acks[fileName] ? { ack: acks[fileName] } : {}),
+    };
+  }
+  if (refusals.length > 0) throw manualEditsError(outFile, refusals);
+  return Object.keys(reconcile).length > 0 ? reconcile : null;
+}
+
+// ---------------------------------------------------------------------------
+// Live deck (push --replace) — plan Phase C2
+// ---------------------------------------------------------------------------
+
+// One export round trip, with the two failure shapes that mean "this live deck
+// cannot be inspected at all" mapped to a fail-closed refusal: a 404 (backend
+// predates the route) and UNSUPPORTED_API (the pane's Office build cannot
+// export). A --replace push must never proceed on faith — it deletes slides.
+// Everything else (unknown presentation, wrong presentation, transport) stays
+// its own error: the push aborts and nothing on screen is touched either way.
+async function exportRound(exportSlides, guids) {
+  try {
+    return await exportSlides(guids);
+  } catch (err) {
+    const reason =
+      err?.status === 404 && err?.code !== "unknown_presentation"
+        ? "this add-in backend does not support export-slides"
+        : err?.code === "UNSUPPORTED_API"
+          ? "this PowerPoint build cannot export slides"
+          : null;
+    if (!reason) throw err;
+    const failClosed = new Error(
+      `the live deck could not be inspected for manual PowerPoint edits ` +
+        `(${reason}) — update the slidemind add-in, or re-run with --force to ` +
+        `push anyway and discard any manual edits`,
+    );
+    failClosed.code = "reconcile_unsupported";
+    throw failClosed;
+  }
+}
+
+// A whole-deck replace deletes every live slide it does not re-push. Slides the
+// deck does not own — added by hand, by another tool, or a manual DUPLICATE of
+// one of ours (same GUID twice: the copy lands here) — would go with them.
+// v1 policy is to refuse and let the user decide (plan C2 step 4).
+function liveDeckExtraSlidesError(unmatched) {
+  const numbers = unmatched
+    .map((s) => (Number.isFinite(s?.index) ? s.index + 1 : "?"))
+    .join(", ");
+  const err = new Error(
+    `the live deck contains ${unmatched.length} slide(s) not in this deck ` +
+      `(added manually or by another tool) — pass --force to discard them.\n` +
+      `Slide ${numbers} (live deck numbering) would be deleted by a whole-deck ` +
+      `replace; push without --replace to insert instead.`,
+  );
+  err.code = "live_deck_extra_slides";
+  err.unmatched = unmatched;
+  return err;
+}
+
+/**
+ * The render request's `reconcile` field built from the LIVE presentation:
+ * export the deck's slides through the pane, decode each one's baked baseline
+ * from its TAGS and project its exported BYTES for the current state.
+ * `guids` selects a subset (a `--slides` push); null means the whole deck.
+ * `exportSlides(guids)` is the pane ack producer — injected so this stays free
+ * of the bridge client (and testable without a relay).
+ */
+export async function collectLiveReconcileInputs({
+  deckDir,
+  exportSlides,
+  guids = null,
+}) {
+  const fileByGuid = new Map();
+  for (const [slidePath, guid] of Object.entries(reconcileSlideGuids(deckDir))) {
+    fileByGuid.set(guid, path.basename(slidePath));
+  }
+  const deckGuids = [...fileByGuid.keys()];
+  const requested = (guids ?? deckGuids).filter((guid) => fileByGuid.has(guid));
+  if (requested.length === 0) return null;
+
+  // `truncated` names slides that matched but did not fit the relay frame —
+  // re-request them until every one has landed. Dropping them would silently
+  // leave those slides unprotected, which is the whole failure mode here.
+  const exported = {};
+  let deck = null;
+  let pending = requested;
+  while (pending.length > 0) {
+    const before = Object.keys(exported).length;
+    const ack = await exportRound(exportSlides, pending);
+    deck ??= ack?.deck ?? null;
+    for (const [guid, slide] of Object.entries(ack?.slides ?? {})) {
+      if (slide?.base64 && slide?.tags) exported[guid] = slide;
+    }
+    const next = (Array.isArray(ack?.truncated) ? ack.truncated : []).filter(
+      (guid) => !exported[guid] && requested.includes(guid),
+    );
+    if (next.length > 0 && Object.keys(exported).length === before) {
+      const err = new Error(
+        `the pane could not export ${next.length} live slide(s) — they are too ` +
+          `large for the relay frame, so their manual edits cannot be checked. ` +
+          `Re-run with --force to push anyway and discard any manual edits.`,
+      );
+      err.code = "export_incomplete";
+      throw err;
+    }
+    pending = next;
+  }
+
+  // Only meaningful for a WHOLE-deck request: a subset replace deletes nothing
+  // outside the subset, so slides beyond it are none of its business.
+  const unmatched =
+    requested.length === deckGuids.length ? (deck?.unmatched ?? []) : [];
+  if (unmatched.length > 0) throw liveDeckExtraSlidesError(unmatched);
+
+  const acks = loadReconcileAcks(deckDir);
+  const reconcile = {};
+  for (const [guid, slide] of Object.entries(exported)) {
+    const fileName = fileByGuid.get(guid);
+    if (!fileName) continue;
+    // Same honesty rule as the file guard: a slide whose tags carry no baseline
+    // (pushed before baselines existed) cannot be compared, so it is skipped —
+    // an unverifiable slide is not evidence of an edit.
+    const baseline = decodeSourceTags(slide.tags)?.baseline ?? null;
+    if (!baseline) continue;
+    // The BYTES carry the current state; the TAGS carry the baseline. Never the
+    // other way round — exportAsBase64 strips tags (office-js #6104).
+    const current = computeProjection(unzip(Buffer.from(slide.base64, "base64")));
+    if (JSON.stringify(current) === JSON.stringify(baseline)) continue;
+    reconcile[fileName] = {
+      baseline,
+      current,
+      ...(acks[fileName] ? { ack: acks[fileName] } : {}),
+    };
+  }
+  return Object.keys(reconcile).length > 0 ? reconcile : null;
+}
+
+/**
+ * The reconcile payload carried by a REFUSED render: the backend answers HTTP
+ * 409 when EVERY jsx slide of the request blocked (the common single-slide
+ * deck), because there is then no deck to return — the echo travels on the
+ * error body instead of the result. Both surfaces land here: the sync route's
+ * 409 (bridgeFetch attaches the parsed body) and a render job that failed with
+ * the same payload (jobFailureError rebuilds it from the job's error extra).
+ * Null for every other error, which stays a plain transport failure.
+ */
+export function reconcileErrorPayload(err) {
+  const echo = err?.body?.reconcile;
+  // A NON-EMPTY echo is the whole signal. An error carrying none (or an empty
+  // one) is a plain failure and must surface as itself — mapping it onto the
+  // fail-closed "backend does not support reconcile" message would blame the
+  // wrong thing for whatever actually went wrong.
+  if (!echo || typeof echo !== "object" || Object.keys(echo).length === 0) {
+    return null;
+  }
+  return err.body;
+}
+
+/**
+ * Apply the render response's `reconcile` echo: fold text edits into the deck's
+ * jsx, store the acknowledged hashes, and refuse the build when a slide's edit
+ * needs human judgment. Returns normally only when the caller may write/push.
+ * `sent` is what {@link collectReconcileInputs} produced (null ⇒ nothing to do).
+ */
+export function applyReconcileResponse({ deckDir, sent, result }) {
+  if (!sent) return;
+  const echo = result?.reconcile;
+  const sentFiles = Object.keys(sent);
+  // FAIL CLOSED (plan §3). The echo IS the capability signal: a backend that
+  // understood the field answers for every key. Anything less and we do not
+  // know whether the user's edits were considered — so nothing gets written.
+  const answered = echo && typeof echo === "object" ? echo : {};
+  if (sentFiles.some((file) => !answered[file])) {
+    const err = new Error(
+      "backend does not support manual-edit reconcile — update the add-in " +
+        "backend, or re-run with --force to discard the manual edits",
+    );
+    err.code = "reconcile_unsupported";
+    throw err;
+  }
+
+  const acks = {};
+  const reports = [];
+  // Only the files we ASKED about: the response may not steer a write to a path
+  // of its choosing.
+  for (const fileName of sentFiles) {
+    const entry = answered[fileName];
+    const safeName = path.basename(fileName);
+    if (typeof entry.nowHash === "string" && entry.nowHash) {
+      acks[safeName] = entry.nowHash;
+    }
+    if (typeof entry.foldedJsx === "string") {
+      // The fold is now the source of truth — the render already used it. It
+      // is written for a BLOCKING slide too (the backend echoes it either
+      // way): the text half of the edit is then already safe on disk while the
+      // agent folds the geometry half by hand.
+      fs.writeFileSync(
+        path.join(deckDir, "slides", safeName),
+        entry.foldedJsx,
+        "utf8",
+      );
+      process.stderr.write(
+        `note: folded ${entry.appliedTextEdits ?? 0} manual text edit(s) from ` +
+          `PowerPoint into slides/${safeName}\n`,
+      );
+    }
+    if (entry.blocking) {
+      // The response also lists these in `skippedSlides` as
+      // `{ stem, reason: "reconcile" }`. Nothing to do with that: this throws,
+      // so the caller never gets far enough to print the skip lines — the
+      // report says it better and says it once.
+      reports.push(entry.report ?? `${safeName}: manual edit needs folding`);
+    }
+  }
+  // BEFORE the refusal below: the ack is what lets the re-run through once the
+  // user has folded the change into the jsx. Without it the same report fires
+  // forever (the output file, and therefore its hash, never changed).
+  saveReconcileAcks(deckDir, acks);
+
+  if (reports.length > 0) {
+    const err = new Error(
+      `${reports.length} slide(s) were edited in PowerPoint in ways that cannot ` +
+        `be folded automatically — nothing was written or pushed.\n\n` +
+        `${reports.join("\n\n")}\n\n` +
+        `Fold each change into the slide's jsx as layout intent (never literal ` +
+        `offsets) and re-run, or re-run with --force to discard these manual edits.`,
+    );
+    err.code = "reconcile_required";
+    err.reports = reports;
+    throw err;
+  }
+}

package/src/lib/slide-guids.mjs

@@ -0,0 +1,143 @@
+// Deck-local sidecar persisting each slide's durable GUID (`sm-<uuid>`) for
+// the deck-embedded source tags, keyed by workspace jsx path
+// ("slides/01-cover.jsx"). Each entry also records the sha256 of the jsx it
+// was last saved for: the NN- filename prefix IS the play order, so reordering
+// a deck renames every file — the content hash is what lets a renamed file
+// keep its identity (reconcileSlideGuids below).
+//
+// Keeps a slide's identity stable across re-renders: the compose path sends
+// these to the server render (which mints for new slides and reports back),
+// the fill-template path bakes them locally.
+
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+const SIDECAR = ".slide-guids.json";
+
+const sha256Hex = (data) => createHash("sha256").update(data).digest("hex");
+
+/** Sidecar entry for a slide: its GUID plus the hash of the jsx it maps to. */
+export function slideGuidEntry(guid, jsx) {
+  return { guid, sha256: sha256Hex(Buffer.from(String(jsx), "utf8")) };
+}
+
+// Raw sidecar, normalized to { [path]: { guid, sha256|null } }. A v1 sidecar
+// stored bare guid strings — read them (identity must survive the format
+// change) but never write them back.
+function readSidecar(deckDir) {
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(path.join(deckDir, SIDECAR), "utf8"));
+  } catch {
+    return {};
+  }
+  if (!parsed || typeof parsed !== "object") return {};
+  const out = {};
+  for (const [p, v] of Object.entries(parsed)) {
+    if (typeof v === "string") out[p] = { guid: v, sha256: null };
+    else if (v && typeof v.guid === "string") {
+      out[p] = { guid: v.guid, sha256: typeof v.sha256 === "string" ? v.sha256 : null };
+    }
+  }
+  return out;
+}
+
+function writeSidecar(deckDir, entries) {
+  fs.writeFileSync(
+    path.join(deckDir, SIDECAR),
+    `${JSON.stringify(entries, null, 2)}\n`,
+  );
+}
+
+/** { [path]: guid } — the wire shape the render routes take. */
+export function loadSlideGuids(deckDir) {
+  const out = {};
+  for (const [p, entry] of Object.entries(readSidecar(deckDir))) {
+    out[p] = entry.guid;
+  }
+  return out;
+}
+
+/**
+ * Merge entries into the sidecar. Values are either a bare guid string
+ * (content hash unknown — reconcile refreshes it on the next run) or a
+ * {@link slideGuidEntry}.
+ */
+export function saveSlideGuids(deckDir, guids) {
+  if (!guids || Object.keys(guids).length === 0) return;
+  const merged = readSidecar(deckDir);
+  for (const [p, v] of Object.entries(guids)) {
+    if (typeof v === "string") {
+      merged[p] = { guid: v, sha256: merged[p]?.guid === v ? (merged[p].sha256 ?? null) : null };
+    } else if (v && typeof v.guid === "string") {
+      merged[p] = { guid: v.guid, sha256: v.sha256 ?? null };
+    }
+  }
+  writeSidecar(deckDir, merged);
+}
+
+/**
+ * Reconcile the sidecar with the slide files actually on disk and return the
+ * resulting { [path]: guid } map. Run this before every bake/render — it is
+ * what makes identity survive the single most common deck edit (reordering,
+ * which renames every file):
+ *
+ *   • a file with a sidecar entry keeps its GUID (and gets its hash refreshed);
+ *   • a file WITHOUT an entry inherits the GUID of a vanished entry whose
+ *     recorded hash matches its content — a pure rename;
+ *   • entries whose file is gone and whose content matched nothing are DROPPED,
+ *     so a later file reusing the name can never resurrect a dead slide's
+ *     identity.
+ *
+ * Files still unmapped after this are genuinely new; the caller (or the server
+ * render) mints for them.
+ */
+export function reconcileSlideGuids(deckDir) {
+  const sidecar = readSidecar(deckDir);
+  const slidesDir = path.join(deckDir, "slides");
+  const present = new Map(); // path -> sha256 of current content
+  let files = [];
+  try {
+    files = fs.readdirSync(slidesDir).filter((f) => f.endsWith(".jsx"));
+  } catch {
+    files = [];
+  }
+  for (const f of files.sort()) {
+    try {
+      present.set(`slides/${f}`, sha256Hex(fs.readFileSync(path.join(slidesDir, f))));
+    } catch {
+      /* unreadable slide — it simply keeps no identity this round */
+    }
+  }
+
+  const next = {};
+  const orphansBySha = new Map(); // sha256 -> [guid, …] whose file is gone
+  for (const [p, entry] of Object.entries(sidecar)) {
+    if (present.has(p)) {
+      next[p] = { guid: entry.guid, sha256: present.get(p) };
+    } else if (entry.sha256) {
+      const list = orphansBySha.get(entry.sha256) ?? [];
+      list.push(entry.guid);
+      orphansBySha.set(entry.sha256, list);
+    }
+  }
+  const claimed = new Set(Object.values(next).map((e) => e.guid));
+  for (const [p, sha] of present) {
+    if (next[p]) continue;
+    const guids = orphansBySha.get(sha);
+    while (guids?.length) {
+      const guid = guids.shift();
+      if (!claimed.has(guid)) {
+        next[p] = { guid, sha256: sha };
+        claimed.add(guid);
+        break;
+      }
+    }
+  }
+
+  if (JSON.stringify(next) !== JSON.stringify(sidecar)) writeSidecar(deckDir, next);
+  const out = {};
+  for (const [p, entry] of Object.entries(next)) out[p] = entry.guid;
+  return out;
+}