slidemind 0.3.20 → 0.4.0

package/src/install-channel.mjs

@@ -17,6 +17,7 @@
 // cannot put a bin on PATH), so a Codex-plugin session always runs the npm CLI
 // and the npm remediation is already correct there.
 
+import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -50,12 +51,68 @@ export function isClaudePluginInstall(root = PACKAGE_ROOT) {
   return false;
 }
 
+// Which sandbox is confining this process, if any? Codex exports CODEX_SANDBOX
+// (`seatbelt` on macOS, `landlock` on Linux) for every command it runs under
+// the sandbox, and leaves it unset for a full-access run — so its presence is
+// a reliable "my writes are confined to the workspace" signal. Returned as the
+// name so a caller can word a message, not just a boolean.
+export function sandboxName() {
+  const s = process.env.CODEX_SANDBOX;
+  return s && s !== "none" ? s : null;
+}
+
+// Can a global `npm install -g slidemind@latest` launched from THIS process
+// actually replace the running binary? npm renames the package directory in
+// place, so the node_modules that holds slidemind must be writable. Two things
+// break that, and the fix for each is the same escalation:
+//   "sandbox"    — a Codex sandbox confines writes to the workspace (and the
+//                  config dir too, so the "we already tried" record can never
+//                  persist and a doomed install would respawn every command)
+//   "permission" — a root-owned global prefix
+// Returns the reason, or null when the install would work. `root` is overridable
+// for tests, mirroring isClaudePluginInstall(root).
+export function globalInstallBlock(root = PACKAGE_ROOT) {
+  const dir = path.dirname(path.resolve(root));
+  const probe = path.join(
+    dir,
+    `.slidemind-wp-${process.pid}-${Math.random().toString(36).slice(2)}`,
+  );
+  try {
+    fs.writeFileSync(probe, "");
+    fs.rmSync(probe, { force: true });
+    return null;
+  } catch {
+    return sandboxName() ? "sandbox" : "permission";
+  }
+}
+
 // The one sentence every version-floor / too-old-CLI message ends with, so the
-// remediation always names the updater that actually replaces THIS binary.
-export function updateCliInstruction() {
-  return isClaudePluginInstall()
-    ? "This CLI came from the slidemind Claude Code plugin, so update it there: " +
-        "`/plugin` → slidemind → update (a global `npm install -g slidemind@latest` " +
-        "installs a separate copy and will NOT change the `slidemind` this session runs)."
-    : "Run `slidemind update` (or `npm install -g slidemind@latest`), then retry.";
+// remediation always names the updater that actually replaces THIS binary —
+// and asks for escalated rights when the running process cannot write the
+// global install itself (a Codex sandbox, or a root-owned prefix).
+// `block` lets a caller that already resolved globalInstallBlock() pass it in
+// (so the message matches the decision exactly); omitted, it self-detects — the
+// shape the hard-block callers (connection.mjs, transport.mjs) use.
+export function updateCliInstruction(block = globalInstallBlock()) {
+  if (isClaudePluginInstall()) {
+    return (
+      "This CLI came from the slidemind Claude Code plugin, so update it there: " +
+      "`/plugin` → slidemind → update (a global `npm install -g slidemind@latest` " +
+      "installs a separate copy and will NOT change the `slidemind` this session runs)."
+    );
+  }
+  if (block === "sandbox") {
+    return (
+      "This session is sandboxed and cannot replace the global install itself — " +
+      "run `slidemind update` with escalated permissions (approve running it " +
+      "outside the sandbox) to update the CLI, then retry."
+    );
+  }
+  if (block === "permission") {
+    return (
+      "The global install is not writable from here — run `slidemind update` " +
+      "with escalated permissions (e.g. `sudo`) to update the CLI, then retry."
+    );
+  }
+  return "Run `slidemind update` (or `npm install -g slidemind@latest`), then retry.";
 }

package/src/lib/adopt.mjs

@@ -1,3 +1,4 @@
+import { stageWorkspace } from './workspace-transaction.mjs';
 // `slidemind adopt <file.pptx>` — reconstruct a local deck workspace from a
 // presentation's deck-embedded source tags (intern-slidemind
 // docs/deck-embedded-source-spec.md §6.2) and, where the add-in offers it,
@@ -26,11 +27,21 @@ import path from "node:path";
 
 import { unzip } from "../pptx/zip.mjs";
 import { slideOrderPaths } from "../pptx/ooxml.mjs";
-import { decodeSourceTags, mintSlideGuid, readSlideTags } from "../pptx/tags.mjs";
+import {
+  TAG_GUID,
+  computeProjection,
+  decodeSourceTags,
+  mintSlideGuid,
+  readSlideTags,
+  withoutChartHashes,
+} from "../pptx/tags.mjs";
 import { foldPickedSlides } from "../pptx/slide-swap.mjs";
 import { readDeckBundleRef, writeDeckBundleRef } from "../bridge/bundle.mjs";
+import { IMAGE_INTENT_META_KEY, restoreImageIntentFromTags } from "./image-intent-tags.mjs";
+import { PRESERVATION_META_KEY, restorePreservationFromTags } from "./preservation-tags.mjs";
 import { loadSlideGuids, saveSlideGuids, slideGuidEntry } from "./slide-guids.mjs";
 import { writeConversionRecord } from "./conversions.mjs";
+import { deckSlug } from "./deck-paths.mjs";
 
 // Converted JSX needs a fresh baseline against the imported PPTX. Source tags
 // alone cannot recover the original conversion evidence or preserved natives.
@@ -39,6 +50,52 @@ export function needsConversion(decoded) {
     /^\s*\/\/\s*SLIDEMIND_DIALECT:\s*converted\b/m.test(decoded.jsx);
 }
 
+/**
+ * May the embedded JSX be written back verbatim?
+ *
+ * `decodeSourceTags` proves the PAYLOAD is intact. That is a different question
+ * from whether it still describes the slide: a normal PowerPoint text, geometry
+ * or style edit leaves the payload perfectly valid and perfectly stale. The
+ * second half of the proof is the drift baseline the bake stored alongside it —
+ * the structural projection as it stood when the slide was written. Recompute
+ * that projection over the slide as it is NOW and the two must agree.
+ *
+ * A slide with no baseline cannot be proved either way, so it is not reused.
+ * Chart hashes drop from both sides for the reason stated in tags.mjs: this repo
+ * projects `chart: null`, and comparing that against a real hash would send
+ * every chart-bearing slide through the converter forever.
+ */
+export function sourceMatchesSlide(files, slidePath, decoded) {
+  if (!decoded?.baseline) return false;
+  return (
+    JSON.stringify(withoutChartHashes(computeProjection(files, slidePath))) ===
+    JSON.stringify(withoutChartHashes(decoded.baseline))
+  );
+}
+
+/**
+ * What each slide of a package becomes, decided from the PACKAGE rather than
+ * from the source decoder alone:
+ *
+ *   "source"  the embedded JSX is intact AND proved to still describe the slide
+ *   "convert" hydrate from the CURRENT content through the add-in's converter
+ *   "native"  keep the slide verbatim as a lossless one-slide .pptx
+ *
+ * `slides` (1-based play-order numbers) narrows what is HYDRATED — everything
+ * outside it stays native. Restoring a proved-current source costs no backend
+ * call, so it happens whether or not the slide was requested.
+ */
+export function hydrationRoutes({ files, order, decodedByIndex }, { slides = null } = {}) {
+  const wanted = slides && slides !== "all" ? new Set(slides.map(Number)) : null;
+  return decodedByIndex.map((decoded, i) => {
+    if (decoded && !needsConversion(decoded) && sourceMatchesSlide(files, order[i], decoded)) {
+      return "source";
+    }
+    if (!wanted || wanted.has(i + 1)) return "convert";
+    return "native";
+  });
+}
+
 export const LIVE_DECK_UNSUPPORTED =
   "conversion of live presentations requires the add-in path in v1 — " +
   "`slidemind adopt` takes a .pptx FILE. Save the open deck to disk and adopt " +
@@ -163,8 +220,25 @@ function convertedByNumber(converted) {
   return map;
 }
 
-export function adoptDeckFromPptx({ pptxPath, deckDir, converted = null, source = null }) {
-  const { buffer, order, decodedByIndex } = source ?? readSourceDeck(pptxPath);
+export function adoptDeckFromPptx({
+  pptxPath,
+  deckDir,
+  converted = null,
+  source = null,
+  slides = null,
+  only = null,
+  // 1-based play order -> file stem, for a slide that must keep the name it
+  // already has in the deck (a folded reused slide converted in place).
+  stems = null,
+}) {
+  const deck = source ?? readSourceDeck(pptxPath);
+  const { buffer, order, decodedByIndex } = deck;
+  const routes = hydrationRoutes(deck, { slides });
+  // `only` materializes a SUBSET of the package into the workspace and leaves
+  // every other slide file exactly where it is — the later-hydration path, where
+  // one slide is being brought forward while another carries pending edits.
+  const materialize = only ? new Set([...only].map(Number)) : null;
+  const wanted = (index) => !materialize || materialize.has(index + 1);
   const convertedSlides = convertedByNumber(converted);
 
   const slidesDir = path.join(deckDir, "slides");
@@ -179,15 +253,19 @@ export function adoptDeckFromPptx({ pptxPath, deckDir, converted = null, source
   const adopted = [];
   const convertedFiles = [];
   const native = [];
+  // Which workspace file materializes each slide of the package, by 1-based play
+  // order. The revision record keys its per-slide evidence on this — without it
+  // a rebase cannot tell which local file a remote change belongs to.
+  const fileByIndex = new Map();
   let bundle = null;
 
-  // Fold every converted slide in one pass. The package supplies preserved
-  // natives AND the original envelope (layouts, passive third-party tags,
-  // relationships). Tagged converted JSX alone cannot restore either safely.
+  // Fold every slide that is NOT restored from a proved-current source in one
+  // pass. The package supplies preserved natives AND the original envelope
+  // (layouts, passive third-party tags, relationships). Tagged converted JSX
+  // alone cannot restore either safely, and an unhydrated slide IS its package.
   const picks = [];
-  decodedByIndex.forEach((decoded, index) => {
-    if (!needsConversion(decoded)) return;
-    picks.push(index + 1);
+  routes.forEach((route, index) => {
+    if (route !== "source" && wanted(index)) picks.push(index + 1);
   });
   const foldByPick = new Map(
     (picks.length
@@ -220,6 +298,14 @@ export function adoptDeckFromPptx({ pptxPath, deckDir, converted = null, source
   // crops) land BEFORE the slide loop so a collision-renamed asset can be
   // rewritten in the converted jsx. Names arrive from an UNTRUSTED package,
   // so they pass the same escape guard as tag-embedded assets.
+  // Slides whose embedded source carried image obligations, restored in one
+  // pass after the loop so the deck ends with one registry write, not one per
+  // slide (src/lib/image-intent-tags.mjs).
+  const intentEntries = [];
+  // …and the obligations they carried (src/lib/preservation-tags.mjs), keyed by
+  // the identity THIS deck gave the slide — a duplicate gets a fresh GUID below,
+  // and its record has to follow that, not the one baked into the file.
+  const preservationEntries = [];
   const convAssetRenames = new Map();
   for (const [name, b64] of Object.entries(converted?.assets ?? {})) {
     const bytes = Buffer.from(String(b64), "base64");
@@ -228,12 +314,17 @@ export function adoptDeckFromPptx({ pptxPath, deckDir, converted = null, source
   }
 
   decodedByIndex.forEach((decoded, index) => {
-    if (decoded && !needsConversion(decoded)) {
-      const stem = stemFor(decoded.meta.name, index, taken);
+    if (!wanted(index)) return;
+    if (routes[index] === "source") {
+      const stem = stems?.get(index + 1) ?? stemFor(decoded.meta.name, index, taken);
       let jsx = decoded.jsx;
+      const renames = new Map();
       for (const asset of decoded.assets) {
         const placed = placeAsset(deckDir, asset.name, asset.bytes, asset.sha256);
-        if (placed && placed !== asset.name) jsx = jsx.split(asset.name).join(placed);
+        if (placed && placed !== asset.name) {
+          renames.set(asset.name, placed);
+          jsx = jsx.split(asset.name).join(placed);
+        }
       }
       fs.writeFileSync(path.join(slidesDir, `${stem}.jsx`), jsx, "utf8");
       const owns = ownerIndexByGuid.get(decoded.guid)?.index === index;
@@ -241,8 +332,26 @@ export function adoptDeckFromPptx({ pptxPath, deckDir, converted = null, source
         owns && !seenGuids.has(decoded.guid) ? decoded.guid : mintSlideGuid();
       seenGuids.add(guid);
       guids[`slides/${stem}.jsx`] = slideGuidEntry(guid, jsx);
+      // The slide's image obligations, if it recorded any. Only this route
+      // restores them: its embedded source was proved to still describe the
+      // slide, so the picture it names is the picture that is there.
+      if (decoded.meta[IMAGE_INTENT_META_KEY]) {
+        intentEntries.push({
+          slideId: guid,
+          intent: decoded.meta[IMAGE_INTENT_META_KEY],
+          restoreUses: true,
+          renames,
+        });
+      }
+      // Its preservation record, on the same terms and for the same reason:
+      // this route, and only this route, proved the payload still describes the
+      // slide, so the elements it requires are the elements that are there.
+      if (decoded.meta[PRESERVATION_META_KEY]) {
+        preservationEntries.push({ slideKey: guid, entry: decoded.meta[PRESERVATION_META_KEY] });
+      }
       bundle ??= decoded.meta.bundle ?? null;
       adopted.push(`${stem}.jsx`);
+      fileByIndex.set(index + 1, { file: `${stem}.jsx`, guid, route: "source" });
       return;
     }
     const fold = foldByPick.get(index + 1);
@@ -250,11 +359,16 @@ export function adoptDeckFromPptx({ pptxPath, deckDir, converted = null, source
     if (conv) {
       // Deterministically converted: editable jsx in the converted dialect,
       // plus the identity/evidence record push threads back to the server.
-      const stem = stemFor(decoded?.meta.name ?? conv.name ?? `${pad2(index + 1)}-converted`, index, taken);
+      const stem =
+        stems?.get(index + 1) ??
+        stemFor(decoded?.meta.name ?? conv.name ?? `${pad2(index + 1)}-converted`, index, taken);
       let jsx = conv.jsx;
       for (const [from, to] of convAssetRenames) jsx = jsx.split(from).join(to);
       fs.writeFileSync(path.join(slidesDir, `${stem}.jsx`), jsx, "utf8");
-      const candidateGuid = decoded?.guid ?? conv.guid;
+      // The route sends no guid; a slide whose package carries one (a native
+      // slide that was already pushed) keeps it, as the native branch does.
+      const candidateGuid =
+        decoded?.guid ?? conv.guid ?? readSlideTags(deck.files, order[index])[TAG_GUID] ?? null;
       const owns = !decoded || ownerIndexByGuid.get(decoded.guid)?.index === index;
       const guid = owns && candidateGuid && !seenGuids.has(candidateGuid)
         ? candidateGuid : mintSlideGuid();
@@ -281,18 +395,34 @@ export function adoptDeckFromPptx({ pptxPath, deckDir, converted = null, source
       );
       bundle ??= decoded?.meta.bundle ?? null;
       convertedFiles.push(`${stem}.jsx`);
+      fileByIndex.set(index + 1, { file: `${stem}.jsx`, guid, route: "convert" });
       return;
     }
-    // No decodable source and no conversion → keep the slide verbatim as a
-    // native one-slide .pptx, spliced back by filename order on every future
-    // render.
+    // Nothing hydrated this slide — either it was outside `--slides` or the
+    // converter declined it. It stays verbatim as a lossless one-slide .pptx,
+    // spliced back by filename order on every future render, carrying its own
+    // notes, comments, animations and embeddings.
     if (!fold) return;
     const stem = stemFor(`${pad2(index + 1)}-reused-adopted`, index, taken);
     fs.writeFileSync(path.join(slidesDir, `${stem}.pptx`), fold.bytes);
     native.push(`${stem}.pptx`);
+    // A native slide keeps the identity the PACKAGE gives it — read straight
+    // off the GUID tag, never through the source decoder, so a slide whose
+    // source tags were stripped still has one.
+    const guid = decoded?.guid ?? readSlideTags(deck.files, order[index])[TAG_GUID] ?? null;
+    fileByIndex.set(index + 1, { file: `${stem}.pptx`, guid, route: "native" });
   });
 
   if (Object.keys(guids).length > 0) saveSlideGuids(deckDir, guids);
+  // Image identity, after the GUIDs are persisted: an override is keyed by the
+  // slide's durable ID, so the ID has to exist first. A file that recorded none
+  // — a plain imported .pptx, or one rendered before this contract — reaches
+  // this with nothing to restore and gains no obligation (A27).
+  const intentNotes = restoreImageIntentFromTags(deckDir, intentEntries).notes;
+  // Same ordering rule, same additive contract: an entry already on disk stays,
+  // so a repeated or resumed adoption restores nothing a second time and an
+  // older file cannot resurrect a requirement this deck superseded.
+  intentNotes.push(...restorePreservationFromTags(deckDir, preservationEntries).notes);
   // A wholly foreign deck names no bundle in any tag, but conversion ran
   // against a design — bind to that one so the next push renders pane-free
   // (the etag self-heals on the first render).
@@ -313,7 +443,7 @@ export function adoptDeckFromPptx({ pptxPath, deckDir, converted = null, source
   if (!fs.existsSync(planPath)) {
     fs.writeFileSync(
       planPath,
-      `---\nskill: create-slides\n---\n\n# ${path.basename(deckDir)}\n\nAdopted from ${path.basename(pptxPath)}.\n`,
+      `---\nskill: create-slides\n---\n\n# ${deckSlug(deckDir)}\n\nAdopted from ${path.basename(pptxPath)}.\n`,
       "utf8",
     );
   }
@@ -324,10 +454,17 @@ export function adoptDeckFromPptx({ pptxPath, deckDir, converted = null, source
     converted: convertedFiles,
     native,
     bundle,
+    routes,
+    // 1-based play order -> { file, guid, route }: which workspace file carries
+    // each slide of the adopted package.
+    slideFiles: fileByIndex,
     // Why a slide the server was asked to convert stayed native (addinOwned,
     // nativeOnlyEnvelope, a parse failure) — the agent has to be able to say so.
     skipped: Array.isArray(converted?.skipped) ? converted.skipped : [],
-    warnings: Array.isArray(converted?.warnings) ? converted.warnings : [],
+    warnings: [
+      ...(Array.isArray(converted?.warnings) ? converted.warnings : []),
+      ...intentNotes,
+    ],
   };
 }
 
@@ -351,19 +488,23 @@ export async function convertUntaggedSlides({
   brandId = null,
   note = () => {},
   source = null,
+  slides: requested = null,
 }) {
-  const { buffer, decodedByIndex } = source ?? readSourceDeck(pptxPath);
-  const slides = [];
-  decodedByIndex.forEach((decoded, i) => {
-    if (needsConversion(decoded)) slides.push(i + 1);
-  });
+  const deck = source ?? readSourceDeck(pptxPath);
+  const { buffer } = deck;
+  // Ask for exactly the slides that will be hydrated — no more. A slide whose
+  // embedded source is proved current needs no conversion, and one outside
+  // `--slides` is staying native, so uploading either wastes a round trip and
+  // (on a big deck) minutes of wall time.
+  const routes = hydrationRoutes(deck, { slides: requested });
+  const slides = routes.flatMap((route, i) => (route === "convert" ? [i + 1] : []));
   if (slides.length === 0) return null;
 
   const client = await import("../bridge/client.mjs");
   const brand =
     brandId ??
     readDeckBundleRef(deckDir)?.presFP ??
-    decodedByIndex.find((d) => d?.meta?.bundle?.presFP)?.meta.bundle.presFP ??
+    deck.decodedByIndex.find((d) => d?.meta?.bundle?.presFP)?.meta.bundle.presFP ??
     null;
   let resolved = brand && brand !== "unknown" ? brand : null;
   let backendURL = null;
@@ -415,3 +556,183 @@ export async function convertUntaggedSlides({
     return null;
   }
 }
+
+// ---------------------------------------------------------------------------
+// update mode — adoption that can be run twice
+// ---------------------------------------------------------------------------
+
+/**
+ * Adopt a .pptx into a workspace, or bring an already-adopted workspace up to
+ * that file. One entry point, because the difference between the two is a
+ * question about state the caller should not have to answer.
+ *
+ * Five outcomes:
+ *
+ *   "adopted"    first adoption — slides materialized and the accepted base
+ *                recorded, the whole thing journaled so a crash resolves to a
+ *                complete generation rather than a half-built deck;
+ *   "hydrated"   the same file, but slides that were native are now requested as
+ *                editable JSX. Only those are re-materialized; every other
+ *                slide file — including one with pending local edits — is left
+ *                exactly as it is, and the new material joins the BASELINE
+ *                rather than reading as an edit;
+ *   "unchanged"  the same file, nothing new asked for. Nothing is written: not
+ *                the slides, not the assets, not the GUIDs, not the adoption
+ *                time;
+ *   "rebased"    a different file over a clean workspace — the remote changes
+ *                apply and the accepted base advances;
+ *   needs_reconcile (thrown) — a different file over a workspace with
+ *                unpublished edits. The incoming snapshot is STAGED and nothing
+ *                local is touched; `slidemind rebase` decides what happens.
+ */
+export async function adoptWorkspace({
+  pptxPath,
+  deckDir,
+  brandId = null,
+  slides = null,
+  convert = true,
+  note = () => {},
+  owner = null,
+}) {
+  const revisionLib = await import("./revision.mjs");
+  if (!owner) {
+    const held = revisionLib.acquireOwner(deckDir, { command: 'adopt' });
+    try { return await adoptWorkspace({ pptxPath, deckDir, brandId, slides, convert, note, owner: held.token }); }
+    finally { held.release(); }
+  }
+  const source = readSourceDeck(pptxPath);
+  const incoming = revisionLib.inventoryPackage(source.buffer);
+  const revision = revisionLib.readRevision(deckDir);
+
+  const runConvert = async (only) =>
+    convert
+      ? await convertUntaggedSlides({
+          pptxPath,
+          deckDir,
+          brandId,
+          note,
+          source,
+          slides: only,
+        })
+      : null;
+
+  // --- already adopted from THIS file ------------------------------------
+  if (revision && revision.base?.sha256 === incoming.sha256) {
+    const byIndex = new Map(
+      (revision.base.slides ?? []).map((s) => [s.index, s]),
+    );
+    const requested = slides === "all" ? [...byIndex.keys()] : slides ? slides.map(Number) : [];
+    const toHydrate = requested.filter((n) => {
+      const entry = byIndex.get(n);
+      return entry && (!entry.file || entry.file.endsWith(".pptx"));
+    });
+    if (toHydrate.length === 0) {
+      return { mode: "unchanged", revision, slideCount: incoming.slideCount };
+    }
+
+    // Withdraw the native materialization of exactly those slides, then build
+    // their JSX in its place. Nothing else in slides/ is read or written.
+    const dirty = revisionLib.computeDirty(deckDir, revision);
+    if (toHydrate.some((n) => dirty.dirtySlides.includes(byIndex.get(n)?.file))) {
+      const error = new Error("Cannot hydrate an edited native slide; preserve or reconcile its changes first.");
+      error.code = "local_dirty";
+      throw error;
+    }
+    const activeDir = deckDir;
+    const tx = stageWorkspace(activeDir);
+    try {
+      const deckDir = tx.workspace;
+      const converted = convert ? await convertUntaggedSlides({ pptxPath, deckDir, brandId, note, source, slides: toHydrate }) : null;
+      const replaced = [];
+      for (const n of toHydrate) {
+        const entry = byIndex.get(n);
+        if (!entry?.file) continue;
+        fs.rmSync(path.join(deckDir, "slides", entry.file), { force: true });
+        replaced.push(entry.file);
+      }
+      const result = adoptDeckFromPptx({
+        pptxPath,
+        deckDir,
+        converted,
+        source,
+        slides: toHydrate,
+        only: toHydrate,
+      });
+      const slideFiles = new Map(
+        (revision.base.slides ?? [])
+          .filter((s) => s.file)
+          .map((s) => [s.index, { file: s.file, guid: s.guid }]),
+      );
+      for (const [index, entry] of result.slideFiles) slideFiles.set(index, entry);
+      revisionLib.writeRevision(deckDir, {
+        ...revision,
+        base: {
+          ...revision.base,
+          slides: (revision.base.slides ?? []).map((s) => ({
+            ...s,
+            file: slideFiles.get(s.index)?.file ?? s.file ?? null,
+          })),
+        },
+      });
+      const hydrated = [...result.adopted, ...result.converted];
+      revisionLib.noteHydration(deckDir, hydrated, replaced);
+      tx.activate({ checkpoint: () => revisionLib.assertCheckpoint(activeDir, { owner, generation: revision.generation, digest: dirty.inputDigest }) });
+      return { mode: "hydrated", result, hydrated, revision: revisionLib.readRevision(activeDir) };
+    } finally { tx.dispose(); }
+  }
+
+  // --- a DIFFERENT file over an adopted workspace ------------------------
+  if (revision) {
+    const staged = revisionLib.stageIncoming(deckDir, {
+      bytes: source.buffer,
+      source: { kind: "file", path: path.resolve(pptxPath), name: path.basename(pptxPath) },
+    });
+    const dirty = revisionLib.computeDirty(deckDir, revision);
+    if (dirty.localDirty) {
+      const err = new Error(
+        `${deckSlug(deckDir)} has unpublished local changes (${dirty.dirtySlides.length} slide(s)), ` +
+          `so adopting a newer file would overwrite them. The incoming file is kept as ` +
+          `revision ${staged.revisionId}; nothing local was touched.\n` +
+          `Reconcile it: \`slidemind rebase ${deckSlug(deckDir)} --incoming ${staged.revisionId}\``,
+      );
+      err.code = "needs_reconcile";
+      err.revisionId = staged.revisionId;
+      err.dirtySlides = dirty.dirtySlides;
+      throw err;
+    }
+    const { applyRebase } = await import("./rebase.mjs");
+    const rebase = applyRebase(deckDir, staged.revisionId, { owner });
+    return { mode: "rebased", rebase, revisionId: staged.revisionId };
+  }
+
+  // --- first adoption ----------------------------------------------------
+  const journal = revisionLib.journalBegin(deckDir, {
+    op: "adopt",
+    detail: { file: path.basename(pptxPath), sha256: incoming.sha256 },
+  });
+  const converted = await runConvert(slides);
+  revisionLib.journalStep(deckDir, journal, "materialize");
+  const result = adoptDeckFromPptx({ pptxPath, deckDir, converted, source, slides });
+  revisionLib.journalStep(deckDir, journal, "record-base");
+  revisionLib.recordAcceptedBase(deckDir, {
+    bytes: source.buffer,
+    origin: { kind: "adopted", file: path.basename(pptxPath), path: path.resolve(pptxPath) },
+  });
+  // The per-slide file mapping: which workspace file carries which slide of the
+  // accepted package. A rebase without it cannot tell whose edit a remote
+  // change collides with.
+  const recorded = revisionLib.readRevision(deckDir);
+  revisionLib.writeRevision(deckDir, {
+    ...recorded,
+    base: {
+      ...recorded.base,
+      slides: recorded.base.slides.map((s) => ({
+        ...s,
+        file: result.slideFiles.get(s.index)?.file ?? null,
+        hydrated: result.routes[s.index - 1] !== "native",
+      })),
+    },
+  });
+  revisionLib.journalComplete(deckDir);
+  return { mode: "adopted", result, revision: revisionLib.readRevision(deckDir) };
+}

package/src/lib/concept-spec-binding.mjs

@@ -0,0 +1,96 @@
+// A concept spec is the reader's inventory of ONE mockup: the bytes it was read
+// from, not "slide N". `concepts` records their SHA-256 in the spec
+// (`imageSha256`), and every consumer here takes a spec only while the mockup
+// on disk still hashes to it.
+//
+// x112 GTM: a run that found 3 of 4 mockups on disk regenerated all four, then
+// reused the three specs already on disk because their slide numbers and image
+// intent matched. Slides 1–3 were transcribed from pictures that no longer
+// existed, and the deck's concepts disagreed with its JSX (forms 0.55). Bound to
+// the bytes, a replaced mockup has no spec until it is read again, and a spec
+// with no binding (written before this contract) is simply read again.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { listSpecSlides, readSpec } from "../builders/concept-spec.mjs";
+
+const pad = (n) => String(n).padStart(2, "0");
+
+export function mockupFileFor(deckDir, slideNumber) {
+  return path.join(deckDir, "concepts", `concept-slide-${pad(slideNumber)}.png`);
+}
+
+/** SHA-256 (hex) of a mockup's bytes, or null when there is no mockup. */
+export function imageDigest(bytesOrFile) {
+  let bytes = bytesOrFile;
+  if (typeof bytesOrFile === "string") {
+    try {
+      bytes = fs.readFileSync(bytesOrFile);
+    } catch {
+      return null;
+    }
+  }
+  return crypto.createHash("sha256").update(bytes).digest("hex");
+}
+
+/**
+ * Where slide N's spec stands against its mockup on disk:
+ * `current` (read from exactly these bytes), `stale` (read from other bytes),
+ * `unbound` (no binding recorded), `no-mockup` (a spec with no picture beside
+ * it) or `absent` (no spec).
+ */
+export function specState(deckDir, slideNumber) {
+  const spec = readSpec(deckDir, slideNumber);
+  if (!spec) return { status: "absent", spec: null };
+  const digest = imageDigest(mockupFileFor(deckDir, slideNumber));
+  if (!digest) return { status: "no-mockup", spec };
+  if (typeof spec.imageSha256 !== "string" || !spec.imageSha256) return { status: "unbound", spec };
+  return { status: spec.imageSha256 === digest ? "current" : "stale", spec };
+}
+
+/** Slide N's spec while it describes the mockup on disk, else null. */
+export function currentSpec(deckDir, slideNumber) {
+  const { status, spec } = specState(deckDir, slideNumber);
+  return status === "current" ? spec : null;
+}
+
+/** The slides whose spec is current, and those whose spec on disk is not. */
+export function specSlidesByState(deckDir) {
+  const current = [];
+  const outdated = [];
+  for (const n of listSpecSlides(deckDir)) {
+    (specState(deckDir, n).status === "current" ? current : outdated).push(n);
+  }
+  return { current, outdated };
+}
+
+/**
+ * Remove slide N's spec — the mapped one, the reader's raw one and the legacy
+ * file next to the PNG. Called in the same step a mockup is replaced, so no
+ * reader of the deck can pair the new picture with the old inventory.
+ */
+export function dropSpec(deckDir, slideNumber) {
+  const n = pad(slideNumber);
+  for (const f of [
+    path.join(deckDir, "state", "concept-specs", `concept-slide-${n}.json`),
+    path.join(deckDir, "state", "reader-specs", `concept-slide-${n}.json`),
+    path.join(deckDir, "concepts", `concept-slide-${n}.spec.json`),
+  ]) {
+    fs.rmSync(f, { force: true });
+  }
+}
+
+/**
+ * Replace slide N's mockup atomically (temp file + rename in the same
+ * directory) and drop its spec in the same step.
+ */
+export function replaceMockup(deckDir, slideNumber, bytes) {
+  const file = mockupFileFor(deckDir, slideNumber);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, bytes);
+  dropSpec(deckDir, slideNumber);
+  fs.renameSync(tmp, file);
+  return file;
+}