slidemind 0.3.20 → 0.4.1

package/src/lib/revision.mjs

@@ -0,0 +1,1210 @@
+import { assertNoActivation, recoverActivation, stageWorkspace } from './workspace-transaction.mjs';
+// The local revision protocol: what the deck was ACCEPTED from, what is on disk
+// RIGHT NOW, and the immutable candidates a build produced in between.
+//
+// Three states, deliberately separate (design `add-pptx-first-adoption` §1):
+//
+//   state/base.pptx            the accepted snapshot, byte-identical to the file
+//                              adoption took delivery of. Immutable.
+//   slides/ assets/ …          the WORKING inputs. Edited freely; never cleared
+//                              by a build, never advanced by one.
+//   state/candidates/<id>/     an immutable rendered candidate + the evidence
+//                              (base sha, generation, input digest, order,
+//                              dependencies, output sha) it was built from.
+//
+// A build writes a candidate. It does NOT advance the base and does NOT clear
+// localDirty — edit → build → build keeps the first edit, which is the whole
+// point. Only an explicit `revision accept --candidate <id>` (local-only) or a
+// confirmed remote receipt (the next change) moves the accepted base.
+//
+// Everything here is SYNC and filesystem-only. This module is the contract the
+// SharePoint pull/publish change and the pack read, so the schemas are
+// exported as constants and pinned by fixtures under test/fixtures/revision/.
+
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { statePath, writeStateFile } from "./deck-paths.mjs";
+import { EDIT_OPERATIONS_FILE } from "./edit-operations.mjs";
+import { SLIDE_PRESERVATION_FILE } from "./slide-preservation.mjs";
+import { resolveBundleDirForDeck, readDeckBundleRef } from "../bridge/bundle.mjs";
+import { bundleOwnedFiles } from "./deck-paths.mjs";
+import { unzip, readText } from "../pptx/zip.mjs";
+import { relsFor, resolvePartPath, slideOrderPaths } from "../pptx/ooxml.mjs";
+import {
+  TAG_GUID,
+  computeProjection,
+  readSlideTags,
+  referencedAssets,
+  withoutChartHashes,
+} from "../pptx/tags.mjs";
+
+export const SCHEMA_VERSION = 1;
+
+// Every file this protocol owns, relative to `<workspace>/state/`. `clean` must
+// keep all of them (they are the only record of what was accepted).
+export const REVISION_FILE = "revision.json";
+export const BUSY_FILE = "busy.json";
+export const JOURNAL_FILE = "journal.json";
+export const CONFLICTS_FILE = "conflicts.json";
+export const BASE_PPTX = "base.pptx";
+export const CANDIDATES_DIR = "candidates";
+export const STAGED_DIR = "staged";
+export const CANDIDATE_FILE = "candidate.json";
+export const CANDIDATE_PPTX = "deck.pptx";
+export const INCOMING_FILE = "incoming.json";
+export const INCOMING_PPTX = "incoming.pptx";
+// The remote half (src/lib/remote.mjs) keeps its records in the same directory
+// and under the same rule: they are the only copy of what was published and of
+// what an interrupted write may have done.
+export const REMOTE_FILE = "remote.json";
+export const OPERATIONS_DIR = "operations";
+export const RECEIPTS_DIR = "receipts";
+
+/** Everything under `<workspace>/state/` this protocol owns — `clean` skips these. */
+export const PROTECTED_STATE = [
+  REVISION_FILE,
+  BUSY_FILE,
+  JOURNAL_FILE,
+  CONFLICTS_FILE,
+  BASE_PPTX,
+  CANDIDATES_DIR,
+  STAGED_DIR,
+  REMOTE_FILE,
+  OPERATIONS_DIR,
+  RECEIPTS_DIR,
+  // What an edit was allowed to change, and what the slide still owes
+  // afterwards (src/lib/edit-state.mjs). Requirements outlive the source they
+  // were taken from, so neither is ever a build artifact.
+  EDIT_OPERATIONS_FILE,
+  SLIDE_PRESERVATION_FILE,
+];
+
+const sha256 = (data) =>
+  createHash("sha256")
+    .update(typeof data === "string" ? Buffer.from(data, "utf8") : Buffer.from(data))
+    .digest("hex");
+
+const nowIso = () => new Date().toISOString();
+
+function stateDir(workspaceDir, ...sub) {
+  return path.join(workspaceDir, "state", ...sub);
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  // Write-then-rename: a kill mid-write must not leave half a JSON record where
+  // the accepted base is supposed to be.
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n");
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+/**
+ * Atomic sidecar write for any `<workspace>/state/<name>.json`: the same
+ * write-then-rename `revision.json` gets, so a kill mid-write can never leave
+ * half a record where an obligation is supposed to be. The edit-safeguard
+ * sidecars (src/lib/edit-state.mjs) ride on this rather than on a second
+ * persistence layer.
+ */
+export function writeStateJson(workspaceDir, name, data) {
+  return writeJson(statePath(workspaceDir, name), data);
+}
+
+// ---------------------------------------------------------------------------
+// package inventory — read the package, NOT the source decoder
+// ---------------------------------------------------------------------------
+
+// Whether a slide reaches a chart part. `computeProjection` here emits
+// `chart: null` unconditionally (the documented parity divergence in tags.mjs),
+// so a chart-bearing slide can never be proved unchanged from its projection
+// alone — it is reported `unverified` rather than silently "same".
+function slideIsChartBlind(files, part) {
+  for (const rel of relsFor(files, part)) {
+    if ((rel.type ?? "").endsWith("/chart") || (rel.type ?? "").endsWith("/chartEx")) return true;
+  }
+  return false;
+}
+
+// Every part a slide reaches, hashed together with the slide itself: the
+// evidence a projection cannot carry (native objects, embeddings, animation,
+// notes, comments). Slides are never traversed into — a slide is a root.
+function slideClosureSha(files, part) {
+  const seen = new Set();
+  const queue = [part];
+  const hashes = [];
+  while (queue.length) {
+    const p = queue.shift();
+    if (!p || files[p] === undefined || seen.has(p)) continue;
+    seen.add(p);
+    hashes.push(`${p}:${sha256(files[p])}`);
+    const relsPath = `${p.slice(0, p.lastIndexOf("/"))}/_rels/${p.slice(p.lastIndexOf("/") + 1)}.rels`;
+    if (files[relsPath] !== undefined && !seen.has(relsPath)) {
+      seen.add(relsPath);
+      hashes.push(`${relsPath}:${sha256(files[relsPath])}`);
+    }
+    const dir = p.includes("/") ? p.slice(0, p.lastIndexOf("/")) : "";
+    for (const rel of relsFor(files, p)) {
+      if (rel.targetMode === "External") continue;
+      const target = resolvePartPath(dir, rel.target);
+      // Masters and layouts are SHARED: hashing them into every slide would make
+      // one theme tweak dirty the whole deck. They ride the package hash instead.
+      if (/^ppt\/slide(Masters|Layouts)\//.test(target)) continue;
+      if (/^ppt\/slides\/slide\d+\.xml$/.test(target)) continue; // links, not content
+      queue.push(target);
+    }
+  }
+  return sha256(hashes.sort().join("\n"));
+}
+
+/**
+ * What a .pptx actually contains, read from the package and independent of any
+ * source tag payload. `decodeSourceTags` proves a payload is INTACT, never that
+ * it agrees with the slide — so nothing here consults it.
+ *
+ * Returns `{ sha256, slideCount, packageSha256, order: [guid…], slides: [{…}], parts }`.
+ */
+export function inventoryPackage(bytes) {
+  const buf = Buffer.from(bytes);
+  const files = unzip(buf);
+  const order = slideOrderPaths(files);
+  const slides = order.map((part, i) => {
+    const tags = readSlideTags(files, part);
+    const sldId = sldIdForPart(files, part);
+    return {
+      // A GUID tag survives source-tag removal, so it is read on its own.
+      guid: tags[TAG_GUID] ?? null,
+      part,
+      sldId,
+      index: i + 1,
+      projection: sha256(
+        JSON.stringify(withoutChartHashes(computeProjection(files, part))),
+      ),
+      package: slideClosureSha(files, part),
+      chartBlind: slideIsChartBlind(files, part),
+      tagged: Boolean(tags[TAG_GUID]),
+    };
+  });
+  return {
+    sha256: sha256(buf),
+    slideCount: order.length,
+    // Every part except the slides themselves — masters, layouts, themes,
+    // presProps, the section list. A theme edit lands here and nowhere else.
+    packageSha256: sha256(
+      Object.keys(files)
+        .filter((p) => !/^ppt\/slides\//.test(p))
+        .sort()
+        .map((p) => `${p}:${sha256(files[p])}`)
+        .join("\n"),
+    ),
+    order: slides.map((s) => s.guid),
+    slides,
+    parts: Object.keys(files).sort(),
+  };
+}
+
+function sldIdForPart(files, part) {
+  const pres = readText(files, "ppt/presentation.xml");
+  if (!pres) return null;
+  const rels = {};
+  for (const rel of relsFor(files, "ppt/presentation.xml")) {
+    if (rel.id) rels[rel.id] = resolvePartPath("ppt", rel.target);
+  }
+  const list = /<(?:[\w.-]+:)?sldIdLst[\s\S]*?<\/(?:[\w.-]+:)?sldIdLst>/.exec(pres);
+  if (!list) return null;
+  const re = /<(?:[\w.-]+:)?sldId\b([^>]*)>/g;
+  let m;
+  while ((m = re.exec(list[0])) !== null) {
+    const rId = /\b[\w.-]+:id\s*=\s*"([^"]+)"/.exec(m[1])?.[1];
+    if (rId && rels[rId] === part) return /\bid\s*=\s*"([^"]+)"/.exec(m[1])?.[1] ?? null;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// working inputs — what is on disk right now
+// ---------------------------------------------------------------------------
+
+function walkFiles(dir, prefix, out, skip) {
+  let entries = [];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+    const abs = path.join(dir, e.name);
+    const rel = prefix ? `${prefix}/${e.name}` : e.name;
+    if (e.isDirectory()) walkFiles(abs, rel, out, skip);
+    else if (e.isFile() && !skip.has(rel)) {
+      try {
+        out[rel] = sha256(fs.readFileSync(abs));
+      } catch {
+        /* unreadable — it simply carries no baseline this round */
+      }
+    }
+  }
+}
+
+/** The slide files in play order (filename order — jsx and native .pptx share it). */
+export function slideFileOrder(workspaceDir) {
+  try {
+    return fs
+      .readdirSync(path.join(workspaceDir, "slides"))
+      .filter((f) => f.endsWith(".jsx") || f.endsWith(".pptx"))
+      .sort((a, b) => a.localeCompare(b, "en", { numeric: true }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Everything a render reads, hashed by BYTES: slide sources, deck-owned assets
+ * and the conversion records (which carry the preserved native packages). Plus
+ * the effective shared dependency — the design the deck is bound to — because a
+ * corporate design that moved changes every slide's output without touching a
+ * single deck file.
+ *
+ * Copies of the design bundle a pre-workspace deck still carries are skipped,
+ * exactly as `hashDeckContent` skips them, so re-materializing an unchanged
+ * design cannot flip a deck dirty.
+ */
+export function materializedInputs(workspaceDir) {
+  const skip = bundleOwnedFiles(workspaceDir, resolveBundleDirForDeck(workspaceDir));
+  const inputs = {};
+  for (const sub of ["slides", "assets", "conversions"]) {
+    walkFiles(path.join(workspaceDir, sub), sub, inputs, skip);
+  }
+  const ref = readDeckBundleRef(workspaceDir);
+  return {
+    inputs,
+    order: slideFileOrder(workspaceDir),
+    shared: { design: ref?.presFP ? `${ref.presFP}@${ref.etag ?? ""}` : null },
+  };
+}
+
+/** One hash over a materialized-input set — the value a candidate binds to. */
+export function inputDigest(materialized) {
+  const { inputs, order, shared } = materialized;
+  return sha256(
+    JSON.stringify({
+      inputs: Object.keys(inputs)
+        .sort()
+        .map((k) => [k, inputs[k]]),
+      order,
+      shared,
+    }),
+  );
+}
+
+// slide file -> the assets its jsx references, so a changed image dirties every
+// slide that draws it (an image-only edit must not read as "nothing changed").
+function assetDependents(workspaceDir, order) {
+  const assetsDir = path.join(workspaceDir, "assets");
+  const map = new Map();
+  for (const file of order) {
+    if (!file.endsWith(".jsx")) continue;
+    let jsx;
+    try {
+      jsx = fs.readFileSync(path.join(workspaceDir, "slides", file), "utf8");
+    } catch {
+      continue;
+    }
+    for (const asset of referencedAssets(jsx, assetsDir)) {
+      const list = map.get(asset.name) ?? [];
+      list.push(file);
+      map.set(asset.name, list);
+    }
+  }
+  return map;
+}
+
+/**
+ * Local differences against the accepted working-input baseline. Content,
+ * structure and dependencies all count: changed/added/removed slide files, a
+ * changed referenced asset, a changed conversion record (the preserved native
+ * bytes live there), slide ORDER, and the effective design.
+ *
+ * Hydration is not an edit: it records a new baseline materialization against
+ * the same accepted package, which `noteHydration` folds into the baseline.
+ */
+export function computeDirty(
+  workspaceDir,
+  revision = readRevision(workspaceDir),
+  materialized = materializedInputs(workspaceDir),
+) {
+  const empty = {
+    localDirty: false,
+    dirtySlides: [],
+    added: [],
+    removed: [],
+    orderChanged: false,
+    sharedChanged: false,
+    unverified: [],
+    inputDigest: inputDigest(materialized),
+  };
+  if (!revision?.baseline) return { ...empty, localDirty: Object.keys(materialized.inputs).length > 0 };
+
+  const baseline = revision.baseline.inputs ?? {};
+  const now = materialized.inputs;
+  const dirty = new Set();
+  const added = [];
+  const removed = [];
+
+  const dependents = assetDependents(workspaceDir, materialized.order);
+  const touch = (rel) => {
+    if (rel.startsWith("slides/")) {
+      dirty.add(rel.slice("slides/".length));
+      return;
+    }
+    if (rel.startsWith("conversions/")) {
+      // conversions/<stem>.json and conversions/<stem>.slide.pptx both belong to
+      // slides/<stem>.jsx.
+      const stem = path.basename(rel).replace(/\.slide\.pptx$/, "").replace(/\.json$/, "");
+      dirty.add(`${stem}.jsx`);
+      return;
+    }
+    for (const file of dependents.get(rel) ?? []) dirty.add(file);
+  };
+
+  for (const [rel, hash] of Object.entries(now)) {
+    if (baseline[rel] === undefined) {
+      if (rel.startsWith("slides/")) added.push(rel.slice("slides/".length));
+      touch(rel);
+    } else if (baseline[rel] !== hash) {
+      touch(rel);
+    }
+  }
+  for (const rel of Object.keys(baseline)) {
+    if (now[rel] !== undefined) continue;
+    if (rel.startsWith("slides/")) removed.push(rel.slice("slides/".length));
+    touch(rel);
+  }
+
+  const orderChanged =
+    JSON.stringify(materialized.order) !== JSON.stringify(revision.baseline.order ?? []);
+  // A design that moved changes every slide's render without touching a file —
+  // but it is NOT a local edit, so it never joins `dirtySlides` (every consumer
+  // of that list means "unpublished edits": rebase conflicts, adopt/pull
+  // refusals, the build's render set). It is reported on its own; build-pptx
+  // re-renders the untouched slides only with --refresh-design.
+  const sharedChanged =
+    JSON.stringify(materialized.shared) !== JSON.stringify(revision.baseline.shared ?? {});
+
+  // Slides whose evidence is known-incomplete here: a chart's data lives in a
+  // spec hash this repo cannot produce (see the CHART HASH note in tags.mjs), so
+  // "no input changed" is not proof for them. Reported, never silently clean.
+  const unverified = (revision.base?.slides ?? [])
+    .filter((s) => s.chartBlind)
+    .map((s) => s.guid ?? s.part);
+
+  const dirtySlides = [...dirty].sort((a, b) => a.localeCompare(b, "en", { numeric: true }));
+  return {
+    localDirty:
+      dirtySlides.length > 0 || added.length > 0 || removed.length > 0 || orderChanged,
+    dirtySlides,
+    added: added.sort(),
+    removed: removed.sort(),
+    orderChanged,
+    sharedChanged,
+    unverified,
+    inputDigest: inputDigest(materialized),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// revision.json
+// ---------------------------------------------------------------------------
+
+export function revisionPath(workspaceDir) {
+  return statePath(workspaceDir, REVISION_FILE);
+}
+
+export function readRevision(workspaceDir) {
+  assertNoActivation(workspaceDir);
+  const data = readJson(revisionPath(workspaceDir));
+  return data?.schemaVersion === SCHEMA_VERSION ? data : null;
+}
+
+/** Persist and return the RECORD — callers read the generation back off it. */
+export function writeRevision(workspaceDir, revision) {
+  const record = { ...revision, schemaVersion: SCHEMA_VERSION };
+  writeJson(revisionPath(workspaceDir), record);
+  return record;
+}
+
+export function acceptedBasePath(workspaceDir) {
+  return stateDir(workspaceDir, BASE_PPTX);
+}
+
+export function readAcceptedBase(workspaceDir) {
+  assertNoActivation(workspaceDir);
+  try {
+    return fs.readFileSync(acceptedBasePath(workspaceDir));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Record a fresh accepted base: the exact bytes adoption took delivery of, the
+ * package evidence read out of them, and the materialized working inputs that
+ * correspond to that package. Generation starts at 1 and only ever advances.
+ */
+export function recordAcceptedBase(workspaceDir, { bytes, origin }) {
+  const inventory = inventoryPackage(bytes);
+  const previous = readRevision(workspaceDir);
+  fs.mkdirSync(stateDir(workspaceDir), { recursive: true });
+  fs.writeFileSync(acceptedBasePath(workspaceDir), Buffer.from(bytes));
+  const materialized = materializedInputs(workspaceDir);
+  return writeRevision(workspaceDir, {
+    schemaVersion: SCHEMA_VERSION,
+    generation: (previous?.generation ?? 0) + 1,
+    origin: { ...origin, at: nowIso() },
+    base: {
+      sha256: inventory.sha256,
+      acceptedAt: nowIso(),
+      slideCount: inventory.slideCount,
+      packageSha256: inventory.packageSha256,
+      order: inventory.order,
+      slides: inventory.slides,
+    },
+    baseline: {
+      inputs: materialized.inputs,
+      order: materialized.order,
+      shared: materialized.shared,
+      at: nowIso(),
+    },
+    candidate: null,
+    staged: previous?.staged ?? [],
+    conflicts: null,
+  });
+}
+
+// Every baseline key one slide file owns: the slide itself plus its conversion
+// record and preserved package.
+function baselineKeysFor(file) {
+  const stem = file.replace(/\.(jsx|pptx)$/, "");
+  return [`slides/${file}`, `conversions/${stem}.json`, `conversions/${stem}.slide.pptx`];
+}
+
+/**
+ * Hydration added working inputs for slides of the SAME accepted package. It is
+ * not an edit: the new files join the baseline, so they do not read as dirty —
+ * but every other slide's pending edit stays exactly where it was.
+ *
+ * `replaced` names the files the hydration WITHDREW (the native form a slide had
+ * before it became editable jsx). They leave the baseline with it; without that
+ * the vanished native file reads as a local deletion, which is the one thing
+ * hydration must not look like. Only the named files are dropped — a slide the
+ * user actually deleted is still a local change and stays dirty.
+ */
+export function noteHydration(workspaceDir, hydratedFiles, replaced = []) {
+  const revision = readRevision(workspaceDir);
+  if (!revision) return null;
+  const materialized = materializedInputs(workspaceDir);
+  const baseline = { ...(revision.baseline?.inputs ?? {}) };
+  for (const file of replaced) {
+    for (const key of baselineKeysFor(file)) delete baseline[key];
+  }
+  const claim = new Set();
+  for (const file of hydratedFiles) {
+    for (const key of baselineKeysFor(file)) claim.add(key);
+  }
+  for (const rel of Object.keys(materialized.inputs)) {
+    // Assets a freshly hydrated slide brought with it join the baseline too —
+    // they came out of the accepted package, so they are not a local edit.
+    if (claim.has(rel) || (rel.startsWith("assets/") && baseline[rel] === undefined)) {
+      baseline[rel] = materialized.inputs[rel];
+    }
+  }
+  return writeRevision(workspaceDir, {
+    ...revision,
+    generation: revision.generation + 1,
+    baseline: {
+      ...revision.baseline,
+      inputs: baseline,
+      order: materialized.order,
+      shared: materialized.shared,
+      at: nowIso(),
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// ownership — an exclusive create, not a read/check/write
+// ---------------------------------------------------------------------------
+
+// Seconds since boot at which THIS process started. A recycled pid carries a
+// different value, so the pair (pid, processStart) identifies a process without
+// a platform-specific /proc read.
+// ponytail: whole-second resolution and a reboot resets the clock — both only
+// ever make a stale owner look MORE stale, never a live one look dead.
+// os.uptime() throws EPERM inside some agent sandboxes (codex exec seatbelt,
+// observed 2026-09-18: every build-pptx died with "uv_uptime returned EPERM"
+// and left a zero-byte busy.json behind). Fall back to epoch seconds; the two
+// call sites below share the basis, so a mark compared within one process
+// stays consistent.
+// ponytail: a sandboxed and an unsandboxed process judging the same lock use
+// different bases and read each other as recycled pids — only ever releases a
+// lock, never wedges one; fine until two harnesses share one deck live.
+function uptimeSeconds() {
+  try {
+    return os.uptime();
+  } catch {
+    return Date.now() / 1000;
+  }
+}
+
+function processStartMark() {
+  return Math.max(0, Math.round(uptimeSeconds() - process.uptime()));
+}
+
+// Is this pid a live process? EPERM means it exists but belongs to someone
+// else — another user, or another harness sandbox (Codex seatbelt answers
+// EPERM across instances), so treating any throw as dead made every lock
+// under a sandbox look free. Only ESRCH (and garbage) is dead.
+export function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err?.code === "EPERM";
+  }
+}
+
+// Is this record still someone's?
+//
+// A SESSION marker (`revision begin`) deliberately outlives the process that
+// created it: the whole point is to protect an edit session made of many
+// commands and raw file writes, and the command that minted the token exited a
+// second later. It is released by `revision finish`, by its own token, or by an
+// explicit --force when the human says the session is gone — never by a pid
+// check, which would make every session token stale the instant it was issued.
+//
+// A COMMAND marker is pid-bound, so a crashed build releases its own lock.
+function alive(busy) {
+  if (!busy) return false;
+  if (busy.kind === "session") return true;
+  if (!busy.pid) return false;
+  if (busy.host && busy.host !== os.hostname()) return true; // not ours to judge
+  try {
+    process.kill(busy.pid, 0);
+  } catch (err) {
+    return err?.code === "EPERM"; // exists but is someone else's
+  }
+  if (busy.pid === process.pid) return true;
+  // A live pid whose recorded start time is far from any plausible current one
+  // is a recycled pid, not the original owner.
+  return Math.abs(processStartMark() - (busy.processStart ?? 0)) <= uptimeSeconds();
+}
+
+export function readBusy(workspaceDir) {
+  return readJson(stateDir(workspaceDir, BUSY_FILE));
+}
+
+/**
+ * Take local ownership of a deck. Exclusive: the record is created with `wx`, so
+ * two processes racing can never both win. A nested call under the SAME owner
+ * token (env `SLIDEMIND_OWNER`, or an explicit `owner`) re-enters instead of
+ * deadlocking.
+ *
+ * Returns `{ token, generation, nested, release() }`. `release()` on a nested
+ * acquisition is a no-op — the outermost holder owns the lifetime.
+ */
+export function acquireOwner(
+  workspaceDir,
+  { command = "unknown", owner = null, session = false } = {},
+) {
+  const file = stateDir(workspaceDir, BUSY_FILE);
+  const wanted = owner ?? process.env.SLIDEMIND_OWNER ?? null;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+
+  for (let attempt = 0; attempt < 2; attempt++) {
+    let fd;
+    try {
+      fd = fs.openSync(file, "wx");
+    } catch (err) {
+      if (err?.code !== "EEXIST") throw err;
+      const busy = readBusy(workspaceDir);
+      if (busy && wanted && busy.owner === wanted) {
+        // Same session, nested command: re-enter under the existing token.
+        writeJson(file, { ...busy, depth: (busy.depth ?? 1) + 1 });
+        return {
+          token: busy.owner,
+          generation: busy.generation,
+          nested: true,
+          release: () => {
+            const cur = readBusy(workspaceDir);
+            if (cur?.owner === busy.owner) {
+              writeJson(file, { ...cur, depth: Math.max(1, (cur.depth ?? 1) - 1) });
+            }
+          },
+        };
+      }
+      if (!busy || alive(busy)) {
+        const e = new Error(
+          !busy ? "deck ownership is being initialized or its lock is unreadable; retry or inspect busy.json before forcing release." : busy.kind === "session"
+            ? `deck is held by an edit session (\`${busy.command}\`, started ${busy.startedAt}). ` +
+              `Run every command under its token (export SLIDEMIND_OWNER), or end it with ` +
+              `\`slidemind revision finish <deck>\`.`
+            : `deck is in use by ${busy.command ?? "another command"} (pid ${busy.pid}, since ${busy.startedAt}). ` +
+              `Wait for it, or run \`slidemind revision finish <deck> --force\` if that process is gone.`,
+        );
+        e.code = "deck_busy";
+        e.busy = busy;
+        throw e;
+      }
+      // A dead owner: release ONLY the ownership. Dirty files and any journaled
+      // operation survive untouched — a crash is not a reason to lose work.
+      // Serialize stale removers. A second remover must inspect the current
+      // lock again, not unlink a replacement using its earlier observation.
+      const guard = `${file}.reap`;
+      try { fs.mkdirSync(guard); }
+      catch (error) {
+        if (error.code !== "EEXIST") throw error;
+        throw Object.assign(new Error("deck ownership recovery is in progress"), { code: "deck_busy" });
+      }
+      try {
+        const current = readBusy(workspaceDir);
+        if (current?.owner === busy.owner && !alive(current)) fs.rmSync(file, { force: true });
+      } finally { fs.rmdirSync(guard); }
+      continue;
+    }
+    let revision;
+    try { recoverActivation(workspaceDir); revision = readRevision(workspaceDir); }
+    catch (error) { fs.closeSync(fd); fs.rmSync(file, { force: true }); throw error; }
+    const record = {
+      schemaVersion: SCHEMA_VERSION,
+      owner: `own-${randomUUID()}`,
+      // "session" outlives its process (see alive); "command" is pid-bound.
+      kind: session ? "session" : "command",
+      pid: process.pid,
+      processStart: processStartMark(),
+      host: os.hostname(),
+      command,
+      generation: revision?.generation ?? 0,
+      startedAt: nowIso(),
+      depth: 1,
+    };
+    fs.writeSync(fd, JSON.stringify(record, null, 2) + "\n");
+    fs.closeSync(fd);
+    // `fail()` ends the process with process.exit(), which skips every
+    // `finally` — so a command that dies that way used to leave its marker
+    // behind and the next one waited on a lock nobody held. It self-healed
+    // (the pid is dead, so `alive()` reaps it), but an operation lease reads a
+    // leaked marker as a live claim, so the release happens here instead of at
+    // each of the ten call sites. Fully synchronous, as an exit handler must be.
+    //
+    // A SESSION marker is deliberately excluded: `revision begin` prints a
+    // token precisely so the marker outlives the process that minted it.
+    const onExit = session
+      ? null
+      : () => {
+          const cur = readBusy(workspaceDir);
+          // Only ever this process's own command marker — never a replacement
+          // somebody else acquired after we let go.
+          if (cur?.owner === record.owner && cur.kind === "command" && cur.pid === process.pid) {
+            fs.rmSync(file, { force: true });
+          }
+        };
+    if (onExit) process.on("exit", onExit);
+    return {
+      token: record.owner,
+      generation: record.generation,
+      nested: false,
+      release: () => {
+        // Idempotent: a normal release retires the hook, so exiting afterwards
+        // is a no-op even if the marker has since been re-acquired.
+        if (onExit) process.off("exit", onExit);
+        const cur = readBusy(workspaceDir);
+        if (!cur || cur.owner !== record.owner) return;
+        if ((cur.depth ?? 1) > 1) {
+          writeJson(file, { ...cur, depth: cur.depth - 1 });
+          return;
+        }
+        fs.rmSync(file, { force: true });
+      },
+    };
+  }
+  throw new Error("could not acquire deck ownership");
+}
+
+/**
+ * Drop a stale owner record. Returns what was released, or null when the owner
+ * is alive (the caller must not steal it) or there was none. NEVER touches
+ * working files or journals.
+ */
+export function releaseStaleOwner(workspaceDir, { owner = null, force = false } = {}) {
+  const busy = readBusy(workspaceDir);
+  if (!busy) return null;
+  if (owner && busy.owner !== owner) return null;
+  if (!force && !owner && alive(busy)) return null;
+  fs.rmSync(stateDir(workspaceDir, BUSY_FILE), { force: true });
+  return busy;
+}
+
+/**
+ * The safe checkpoint every activation passes: ownership still ours, and the
+ * generation + working inputs unchanged since they were captured. Throws
+ * `generation_moved` otherwise, so a snapshot whose inputs changed mid-capture
+ * is never certified.
+ */
+export function assertCheckpoint(workspaceDir, { owner, generation, digest }) {
+  const busy = readBusy(workspaceDir);
+  if (!busy || busy.owner !== owner) {
+    const e = new Error("lost deck ownership while the operation was running");
+    e.code = "ownership_lost";
+    throw e;
+  }
+  const revision = readRevision(workspaceDir);
+  const current = computeDirty(workspaceDir, revision);
+  if ((revision?.generation ?? 0) !== generation || current.inputDigest !== digest) {
+    const e = new Error(
+      "the deck changed while this operation ran — nothing was activated. Re-run it.",
+    );
+    e.code = "generation_moved";
+    throw e;
+  }
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// journal — a half-applied activation must be recoverable, never valid
+// ---------------------------------------------------------------------------
+
+export function readJournal(workspaceDir) {
+  const data = readJson(stateDir(workspaceDir, JOURNAL_FILE));
+  return data?.schemaVersion === SCHEMA_VERSION ? data : null;
+}
+
+export function journalBegin(workspaceDir, { op, stagingDir = null, detail = null }) {
+  const journal = {
+    schemaVersion: SCHEMA_VERSION,
+    id: `jr-${randomUUID()}`,
+    op,
+    status: "staged",
+    startedAt: nowIso(),
+    stagingDir,
+    detail,
+    steps: [],
+  };
+  writeJson(stateDir(workspaceDir, JOURNAL_FILE), journal);
+  return journal;
+}
+
+export function journalStep(workspaceDir, journal, step) {
+  const next = { ...journal, status: "activating", steps: [...journal.steps, { step, at: nowIso() }] };
+  writeJson(stateDir(workspaceDir, JOURNAL_FILE), next);
+  return next;
+}
+
+export function journalComplete(workspaceDir) {
+  fs.rmSync(stateDir(workspaceDir, JOURNAL_FILE), { force: true });
+}
+
+/** An unfinished activation, or null. Only the absence of a journal means done. */
+export function journalIncomplete(workspaceDir) {
+  const journal = readJournal(workspaceDir);
+  return journal && journal.status !== "complete" ? journal : null;
+}
+
+// ---------------------------------------------------------------------------
+// candidates — immutable rendered output plus the evidence it came from
+// ---------------------------------------------------------------------------
+
+export function candidateDir(workspaceDir, candidateId) {
+  return stateDir(workspaceDir, CANDIDATES_DIR, candidateId);
+}
+
+/**
+ * Persist a rendered deck as an immutable candidate. Does NOT advance the base
+ * and does NOT clear dirty — building twice keeps both edits, and neither build
+ * counts as acceptance.
+ *
+ * An identical candidate (same base, generation, inputs and output bytes) is
+ * reused rather than duplicated.
+ */
+export function saveCandidate(workspaceDir, { bytes, validation = null, review = null, renderedAll = true }) {
+  let revision = readRevision(workspaceDir);
+  const materialized = materializedInputs(workspaceDir);
+  const digest = inputDigest(materialized);
+  const inventory = inventoryPackage(bytes);
+  if (!revision) revision = writeRevision(workspaceDir, { generation: 0, origin: { kind: 'authored' }, base: null, baseline: null, candidate: null, conflicts: null });
+  const evidence = {
+    baseSha256: revision?.base?.sha256 ?? null,
+    generation: revision?.generation ?? 0,
+    inputDigest: digest,
+    outputSha256: inventory.sha256,
+  };
+
+  for (const existing of listCandidates(workspaceDir)) {
+    if (
+      existing.baseSha256 === evidence.baseSha256 &&
+      existing.generation === evidence.generation &&
+      existing.inputDigest === evidence.inputDigest &&
+      existing.outputSha256 === evidence.outputSha256
+    ) {
+      return existing;
+    }
+  }
+
+  const candidateId = `cand-${randomUUID().replace(/-/g, "").slice(0, 16)}`;
+  const dir = candidateDir(workspaceDir, candidateId);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, CANDIDATE_PPTX), Buffer.from(bytes));
+  const record = {
+    schemaVersion: SCHEMA_VERSION,
+    candidateId,
+    createdAt: nowIso(),
+    ...evidence,
+    outputBytes: Buffer.byteLength(Buffer.from(bytes)),
+    slideCount: inventory.slideCount,
+    order: inventory.order,
+    inputs: materialized.inputs,
+    // A build that left untouched slides on the design they were last rendered
+    // with must not claim the current design for them: the accepted base then
+    // keeps the old `shared`, so `sharedChanged` stays true and the next
+    // --refresh-design still knows those slides are behind.
+    dependencies: renderedAll ? materialized.shared : (revision.baseline?.shared ?? materialized.shared),
+    validation,
+    review,
+  };
+  writeJson(path.join(dir, CANDIDATE_FILE), record);
+  if (revision) writeRevision(workspaceDir, { ...revision, candidate: candidateId });
+  return record;
+}
+
+export function readCandidate(workspaceDir, candidateId) {
+  const data = readJson(path.join(candidateDir(workspaceDir, candidateId), CANDIDATE_FILE));
+  return data?.schemaVersion === SCHEMA_VERSION ? data : null;
+}
+
+export function candidateBytes(workspaceDir, candidateId) {
+  try {
+    return fs.readFileSync(path.join(candidateDir(workspaceDir, candidateId), CANDIDATE_PPTX));
+  } catch {
+    return null;
+  }
+}
+
+export function listCandidates(workspaceDir) {
+  let names = [];
+  try {
+    names = fs.readdirSync(stateDir(workspaceDir, CANDIDATES_DIR));
+  } catch {
+    return [];
+  }
+  return names
+    .map((id) => readCandidate(workspaceDir, id))
+    .filter(Boolean)
+    .sort((a, b) => (a.createdAt < b.createdAt ? 1 : -1));
+}
+
+/** Why a candidate is no longer a valid thing to accept, or null. */
+export function candidateStale(workspaceDir, candidate, revision = readRevision(workspaceDir)) {
+  if (!candidate) return "no such candidate";
+  if (!revision) return "the deck has no accepted base";
+  if (candidate.baseSha256 !== (revision.base?.sha256 ?? null)) {
+    return "it was built against a different accepted base";
+  }
+  if (candidate.generation !== revision.generation) {
+    return "the deck's accepted state moved since it was built";
+  }
+  const digest = inputDigest(materializedInputs(workspaceDir));
+  if (candidate.inputDigest !== digest) {
+    return "the deck's inputs changed since it was built";
+  }
+  const bytes = candidateBytes(workspaceDir, candidate.candidateId);
+  if (!bytes || sha256(bytes) !== candidate.outputSha256) {
+    return "its recorded output bytes are missing or no longer match";
+  }
+  return null;
+}
+
+/**
+ * Accept a validated LOCAL-ONLY candidate: its bytes become the accepted base
+ * and its inputs become the baseline, journaled so a crash resolves to one
+ * complete generation. Refuses a remote-bound deck (only a confirmed publish
+ * receipt may advance THAT base), a stale candidate, an unresolved conflict and
+ * a candidate whose required gates did not pass.
+ */
+export function acceptCandidate(workspaceDir, candidateId, { owner }) {
+  const revision = readRevision(workspaceDir);
+  if (revision?.remote || readJson(path.join(workspaceDir, "state", "remote.json"))) {
+    const e = new Error(
+      "this deck is bound to a remote copy — acceptance there comes from a confirmed publish receipt, not from `revision accept`.",
+    );
+    e.code = "remote_bound";
+    throw e;
+  }
+  if (readConflicts(workspaceDir)) {
+    const e = new Error(
+      "unresolved rebase conflicts — resolve them (`slidemind rebase <deck> --resolve <file>`) before accepting.",
+    );
+    e.code = "conflicted";
+    throw e;
+  }
+  const candidate = readCandidate(workspaceDir, candidateId);
+  const why = candidateStale(workspaceDir, candidate, revision);
+  if (why) {
+    const e = new Error(`candidate ${candidateId} cannot be accepted: ${why}.`);
+    e.code = "candidate_stale";
+    throw e;
+  }
+  if (candidate.validation?.ok !== true) {
+    const e = new Error(
+      `candidate ${candidateId} did not pass validation: ${(candidate.validation?.errors ?? ["validation evidence is missing"]).join("; ")}`,
+    );
+    e.code = "candidate_invalid";
+    throw e;
+  }
+
+  return advanceBaseToCandidate(workspaceDir, candidate, { owner, origin: "local", revision });
+}
+
+/**
+ * Move the accepted base onto a candidate's bytes and its inputs onto the
+ * baseline, journaled so a crash resolves to one complete generation.
+ *
+ * Shared by the two acceptance doors — `revision accept` locally and a CONFIRMED
+ * publish receipt remotely. The guards differ (that is the whole point of having
+ * two doors); what happens once a caller has earned the right is identical, and
+ * a second copy of it would be a second chance to get the baseline wrong.
+ */
+function advanceBaseToCandidate(workspaceDir, candidate, { owner, origin, revision, receipt = null }) {
+  const candidateId = candidate.candidateId;
+  const bytes = candidateBytes(workspaceDir, candidateId);
+  assertCheckpoint(workspaceDir, {
+    owner,
+    generation: revision.generation,
+    digest: candidate.inputDigest,
+  });
+  const inventory = inventoryPackage(bytes);
+  const tx = stageWorkspace(workspaceDir);
+  try {
+    fs.writeFileSync(acceptedBasePath(tx.workspace), bytes);
+    const next = writeRevision(tx.workspace, {
+      ...revision,
+      generation: revision.generation + 1,
+      base: {
+        sha256: inventory.sha256,
+        acceptedAt: nowIso(),
+        slideCount: inventory.slideCount,
+        packageSha256: inventory.packageSha256,
+        order: inventory.order,
+        // The per-slide file map is what a later rebase matches a colleague's
+        // change against; rebuilding it from the candidate would lose it.
+        slides: inventory.slides.map((s, i) => ({
+          ...s,
+          file: slideFileOrder(workspaceDir)[i] ?? null,
+        })),
+      },
+      baseline: {
+        inputs: candidate.inputs,
+        order: slideFileOrder(workspaceDir),
+        shared: candidate.dependencies,
+        at: nowIso(),
+      },
+      candidate: null,
+      acceptedCandidate: {
+        candidateId,
+        at: nowIso(),
+        origin,
+        ...(receipt ? { receipt: { operationId: receipt.operationId, versionId: receipt.version?.versionId ?? null } } : {}),
+      },
+    });
+    tx.activate({ checkpoint: () => assertCheckpoint(workspaceDir, {
+      owner, generation: revision.generation, digest: candidate.inputDigest,
+    }) });
+    return next;
+  } finally { tx.dispose(); }
+}
+
+/**
+ * The REMOTE acceptance door: a confirmed publish receipt, and nothing else,
+ * moves a remote-bound deck's accepted base.
+ *
+ * `acceptCandidate` refuses these decks deliberately — a local decision cannot
+ * certify that a server stored anything. This is the same operation with the
+ * opposite precondition: the receipt must name the candidate whose bytes the
+ * server confirmed, so the base can only ever advance to what is actually there.
+ */
+export function acceptCandidateFromReceipt(workspaceDir, candidateId, { owner, receipt }) {
+  const revision = readRevision(workspaceDir);
+  const candidate = readCandidate(workspaceDir, candidateId);
+  if (!candidate) {
+    const e = new Error(`no such candidate: ${candidateId}`);
+    e.code = "candidate_stale";
+    throw e;
+  }
+  if (!receipt?.candidateSha256 || receipt.candidateSha256 !== candidate.outputSha256) {
+    const e = new Error(
+      "the receipt does not name this candidate's bytes — the base is not advanced on evidence about a different build.",
+    );
+    e.code = "receipt_mismatch";
+    throw e;
+  }
+  return advanceBaseToCandidate(workspaceDir, candidate, {
+    owner,
+    origin: "remote",
+    revision,
+    receipt,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// staged incoming snapshots + the conflict manifest
+// ---------------------------------------------------------------------------
+
+export function stagedDir(workspaceDir, revisionId) {
+  return stateDir(workspaceDir, STAGED_DIR, revisionId);
+}
+
+/**
+ * Put incoming bytes somewhere IMMUTABLE and revision-specific. Staging never
+ * touches working inputs, so a pull that lands mid-edit cannot disturb the edit.
+ */
+export function stageIncoming(workspaceDir, { bytes, source }) {
+  const inventory = inventoryPackage(bytes);
+  // The same bytes staged twice (a pull after a publish that already staged
+  // them) are one incoming revision, not two to reconcile.
+  for (const id of readRevision(workspaceDir)?.staged ?? []) {
+    const existing = readStaged(workspaceDir, id);
+    if (existing?.sha256 === inventory.sha256) return existing;
+  }
+  const revisionId = `in-${randomUUID().replace(/-/g, "").slice(0, 16)}`;
+  const dir = stagedDir(workspaceDir, revisionId);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, INCOMING_PPTX), Buffer.from(bytes));
+  const record = {
+    schemaVersion: SCHEMA_VERSION,
+    revisionId,
+    stagedAt: nowIso(),
+    source,
+    sha256: inventory.sha256,
+    slideCount: inventory.slideCount,
+    packageSha256: inventory.packageSha256,
+    order: inventory.order,
+    slides: inventory.slides,
+  };
+  writeJson(path.join(dir, INCOMING_FILE), record);
+  const revision = readRevision(workspaceDir);
+  if (revision) {
+    writeRevision(workspaceDir, {
+      ...revision,
+      staged: [...new Set([...(revision.staged ?? []), revisionId])],
+    });
+  }
+  return record;
+}
+
+export function readStaged(workspaceDir, revisionId) {
+  const data = readJson(path.join(stagedDir(workspaceDir, revisionId), INCOMING_FILE));
+  return data?.schemaVersion === SCHEMA_VERSION ? data : null;
+}
+
+export function stagedBytes(workspaceDir, revisionId) {
+  try {
+    return fs.readFileSync(path.join(stagedDir(workspaceDir, revisionId), INCOMING_PPTX));
+  } catch {
+    return null;
+  }
+}
+
+export function listStaged(workspaceDir) {
+  try {
+    return fs
+      .readdirSync(stateDir(workspaceDir, STAGED_DIR))
+      .map((id) => readStaged(workspaceDir, id))
+      .filter(Boolean)
+      .sort((a, b) => (a.stagedAt < b.stagedAt ? 1 : -1));
+  } catch {
+    return [];
+  }
+}
+
+export function readConflicts(workspaceDir) {
+  const data = readJson(stateDir(workspaceDir, CONFLICTS_FILE));
+  return data?.schemaVersion === SCHEMA_VERSION ? data : null;
+}
+
+export function writeConflicts(workspaceDir, manifest) {
+  const file = writeJson(stateDir(workspaceDir, CONFLICTS_FILE), {
+    ...manifest,
+    schemaVersion: SCHEMA_VERSION,
+  });
+  const revision = readRevision(workspaceDir);
+  if (revision) writeRevision(workspaceDir, { ...revision, conflicts: manifest.revisionId });
+  return file;
+}
+
+export function clearConflicts(workspaceDir) {
+  fs.rmSync(stateDir(workspaceDir, CONFLICTS_FILE), { force: true });
+  const revision = readRevision(workspaceDir);
+  if (revision) writeRevision(workspaceDir, { ...revision, conflicts: null });
+}
+
+// ---------------------------------------------------------------------------
+// the one shape ready/status report
+// ---------------------------------------------------------------------------
+
+/** Everything `ready --json` and `revision status` expose, read from disk. */
+export function revisionStatus(workspaceDir) {
+  const revision = readRevision(workspaceDir);
+  const dirty = computeDirty(workspaceDir, revision);
+  const busy = readBusy(workspaceDir);
+  const candidateId = revision?.candidate ?? null;
+  const candidate = candidateId ? readCandidate(workspaceDir, candidateId) : null;
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    adopted: Boolean(revision),
+    origin: revision?.origin ?? null,
+    generation: revision?.generation ?? 0,
+    base: revision?.base
+      ? {
+          sha256: revision.base.sha256,
+          acceptedAt: revision.base.acceptedAt,
+          slideCount: revision.base.slideCount,
+        }
+      : null,
+    localDirty: dirty.localDirty,
+    dirtySlides: dirty.dirtySlides,
+    added: dirty.added,
+    removed: dirty.removed,
+    orderChanged: dirty.orderChanged,
+    designMoved: dirty.sharedChanged,
+    unverified: dirty.unverified,
+    inputDigest: dirty.inputDigest,
+    candidate: candidate
+      ? {
+          candidateId: candidate.candidateId,
+          createdAt: candidate.createdAt,
+          outputSha256: candidate.outputSha256,
+          stale: candidateStale(workspaceDir, candidate, revision),
+        }
+      : null,
+    candidates: listCandidates(workspaceDir).map((c) => c.candidateId),
+    staged: listStaged(workspaceDir).map((s) => ({
+      revisionId: s.revisionId,
+      stagedAt: s.stagedAt,
+      sha256: s.sha256,
+    })),
+    conflicts: readConflicts(workspaceDir)?.conflicts?.length ?? 0,
+    owner: busy
+      ? { kind: busy.kind ?? "command", command: busy.command, pid: busy.pid, startedAt: busy.startedAt }
+      : null,
+    journal: journalIncomplete(workspaceDir)?.op ?? null,
+  };
+}