slidemind 0.3.20 → 0.4.1

package/src/lib/conversions.mjs

@@ -83,6 +83,28 @@ export function writeConversionRecord(
   return full;
 }
 
+/**
+ * Drop one slide's record AND its preserve package. Used when a slide's local
+ * hydration is withdrawn — a rebase took it back to its package form, or an
+ * update replaced it — because a record left behind names a slide that is not
+ * there any more, which `conversionIntegrityErrors` correctly refuses to build.
+ * Returns the names it removed.
+ */
+export function removeConversionRecord(deckDir, slideFileName) {
+  // Callers name the slide FILE, which may already have been replaced by its
+  // native form — so both extensions are stripped, not just `.jsx`.
+  const stem = path.basename(String(slideFileName)).replace(/\.(jsx|pptx)$/i, "");
+  const dir = conversionsDir(deckDir);
+  const removed = [];
+  for (const name of [`${stem}.json`, `${stem}.slide.pptx`]) {
+    const file = path.join(dir, name);
+    if (!fs.existsSync(file)) continue;
+    fs.rmSync(file, { force: true });
+    removed.push(name);
+  }
+  return removed;
+}
+
 /**
  * Every conversion record of a deck, keyed by slide file name, in the shape the
  * render request carries: identity + evidence + the base64 preserve source.
@@ -90,8 +112,17 @@ export function writeConversionRecord(
  * A record whose `slides/<stem>.jsx` no longer exists is skipped — the slide was
  * deleted or renamed, and shipping its baseline would bind conversion identity
  * to a slide that is no longer in the deck. Unreadable/corrupt records are
- * skipped too: a converted slide then renders as ordinary jsx (its preserved
- * natives are lost, which the caller warns about) rather than failing the push.
+ * skipped too — and a skipped record is INDISTINGUISHABLE here from one that
+ * was never written. Nobody warns about it either: every warning path
+ * (`conversionIntegrityErrors`, `conversionsMissingPreserveSource`) iterates
+ * this same map, so the slide they would name is already gone from it.
+ *
+ * That is fine for a renderer — the slide previews as ordinary jsx — and wrong
+ * for anything that REWRITES source or DELIVERS a deck, where absence reads as
+ * "not converted" and the answer is really "nobody could tell". Those callers
+ * ask {@link conversionProvenance} per slide instead, which distinguishes the
+ * two; `build-and-push` does, and refuses rather than shipping a slide whose
+ * preserved natives (SmartArt, OLE, an unmodeled chart) would silently be gone.
  *
  * `includeSource: false` skips reading the preserve packages — for callers that
  * only need to know WHICH slides are converted (they can be megabytes).
@@ -108,6 +139,11 @@ export function loadConversions(deckDir, { includeSource = true } = {}) {
     try {
       record = JSON.parse(fs.readFileSync(path.join(dir, name), "utf8"));
     } catch {
+      // Deliberate, and ONLY safe for the render path: a slide missing from
+      // this map renders as ordinary jsx. It is not safe for anything that
+      // decides whether a slide may be REWRITTEN, because absence here reads
+      // as "not converted" when the truth is "nobody could tell". Those
+      // callers ask `conversionProvenance` below, which does not skip.
       continue;
     }
     const entry = {
@@ -135,6 +171,34 @@ export function loadConversions(deckDir, { includeSource = true } = {}) {
   return out;
 }
 
+/**
+ * Is ONE slide converted? Three answers, and the third is the whole point:
+ *
+ *   the record   a `conversions/<stem>.json` that parsed: converted, and this
+ *                is what it says
+ *   null         looked, there is no record file: not converted
+ *   undefined    a record file IS there and could not be read, so the question
+ *                is unanswered
+ *
+ * The third is what {@link loadConversions} cannot express — a map has no way
+ * to say "something was here and I could not read it", so a corrupt record
+ * arrives at its callers as absence. For a renderer that is a degraded slide;
+ * for anything that rewrites source it is the difference between refusing and
+ * quietly rewriting a converted slide whose pragma someone removed (E15). The
+ * three states line up with `validateSettleTarget`'s own contract
+ * (src/builders/settle.mjs): undefined refuses as `provenance_unknown`, a
+ * record refuses as `converted_provenance`, null proceeds.
+ */
+export function conversionProvenance(deckDir, slideFileName) {
+  const file = path.join(conversionsDir(deckDir), `${stemOf(slideFileName)}.json`);
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Follow the deck's reconciled GUIDs: move every conversion record whose slide
  * file was renamed (a reorder renames every slide — the NN- prefix IS the play
@@ -237,9 +301,9 @@ export function applyConversionGates(deckDir, conversions, gates) {
         reasons,
         note:
           `${file}: this converted slide was NOT confirmed for replacement ` +
-          `(${gate.route}: ${reasons.join(", ")}) — it is in the rendered deck, but pushing ` +
-          `it over the original is unreviewed. Compare it with the source slide, then set ` +
-          `"state": "verified" in ${CONVERSIONS_DIR}/${stemOf(file)}.json once it is right.`,
+          `(${gate.route}: ${reasons.join(", ")}) — it is in the rendered deck, but nobody ` +
+          `has reviewed it over the original: replacing the original (\`push --replace\`) ` +
+          `waits for the user's go-ahead (\`--accept-conversions\`).`,
       });
     }
     stampFirstReplace(deckDir, file, gate);
@@ -377,7 +441,7 @@ export function conversionIntegrityErrors(deckDir, conversions) {
       errors.push(
         `${file}: its conversion record still claims "slide": "${record.slide}" — the file was renamed ` +
           `by hand. Rename it back, or re-run 'slidemind adopt' (a plan-driven reorder belongs to ` +
-          `'proposal-plan renumber', which moves the jsx, the brief, the record and the GUID together).`,
+          `the pack's own renumber command, which moves the jsx, the brief, the record and the GUID together).`,
       );
     }
   }

package/src/lib/convert-folded.mjs

@@ -0,0 +1,107 @@
+// Convert ONE folded slide of a deck — `slides/NN-*.pptx`, written by
+// `slidemind add-slide` (or kept native by an adoption) — into editable jsx IN
+// PLACE, when the user asks to change it (workflow/search.md: a reused slide
+// stays native until then, and is then edited like any other deck slide).
+//
+// Same machinery as adoption: the add-in's convert-pptx route for a slide with
+// no current embedded source, a verbatim restore for one whose source is proved
+// current, and `adoptDeckFromPptx` to materialize either. The jsx keeps the
+// .pptx's file stem, so play order does not move, and replaces it — the deck
+// never carries the slide twice. A slide that cannot be converted leaves the
+// deck untouched and says why.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { adoptDeckFromPptx, convertUntaggedSlides, hydrationRoutes, readSourceDeck } from "./adopt.mjs";
+import { stageWorkspace } from "./workspace-transaction.mjs";
+
+function refuse(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+// Only a deck's own folded slide: any folder on disk can be called `slides`.
+// The CLI asks this before it takes the deck's lock, so a refusal writes nothing.
+export function notFoldedReason(pptxPath) {
+  const file = path.basename(pptxPath);
+  return path.basename(path.dirname(pptxPath)) === "slides" && /^\d{1,3}-.+\.pptx$/i.test(file)
+    ? null
+    : `${file} is not a deck's folded slide (<deck>/slides/<NN-name>.pptx); nothing was changed.`;
+}
+
+export async function convertFoldedSlide({ pptxPath, deckDir, brandId = null, note = () => {}, owner = null }) {
+  const file = path.basename(pptxPath);
+  const notFolded = notFoldedReason(pptxPath);
+  if (notFolded) throw refuse("not_folded", notFolded);
+  const stem = file.replace(/\.pptx$/i, "");
+  const source = readSourceDeck(pptxPath);
+  if (source.order.length !== 1) {
+    throw refuse("not_one_slide", `${file} holds ${source.order.length} slides; a folded slide file holds exactly one.`);
+  }
+
+  const revisionLib = await import("./revision.mjs");
+  const revision = revisionLib.readRevision(deckDir);
+  const dirty = revision ? revisionLib.computeDirty(deckDir, revision) : null;
+  // In the accepted baseline: the conversion is hydration, not an edit, so the
+  // jsx joins the baseline in the .pptx's place. Added since: it stays an added
+  // slide, just editable. Edited since: converting would drop that edit.
+  const inBaseline = revision?.baseline?.inputs?.[`slides/${file}`] !== undefined;
+  if (inBaseline && dirty.dirtySlides.includes(file)) {
+    throw refuse("local_dirty", `${file} has unpublished changes; publish or reconcile them before converting it.`);
+  }
+
+  const heard = [];
+  const [route] = hydrationRoutes(source, { slides: [1] });
+  const converted =
+    route === "convert"
+      ? await convertUntaggedSlides({
+          pptxPath,
+          deckDir,
+          brandId,
+          source,
+          slides: [1],
+          note: (line) => {
+            heard.push(line);
+            note(line);
+          },
+        })
+      : null;
+  if (route === "convert" && !converted?.slides?.some((s) => Number(s?.index) === 1)) {
+    const why = converted?.skipped?.find((s) => Number(s?.index) === 1)?.reason ?? heard.at(-1) ?? "the add-in returned no jsx for it";
+    throw refuse("not_converted", `${file} was not converted (${why}); it stays native and nothing was changed.`);
+  }
+
+  const tx = stageWorkspace(deckDir);
+  try {
+    const ws = tx.workspace;
+    fs.rmSync(path.join(ws, "slides", file), { force: true });
+    const result = adoptDeckFromPptx({
+      pptxPath,
+      deckDir: ws,
+      converted,
+      source,
+      slides: [1],
+      only: [1],
+      stems: new Map([[1, stem]]),
+    });
+    const jsx = `${stem}.jsx`;
+    if (inBaseline) {
+      revisionLib.writeRevision(ws, {
+        ...revision,
+        base: {
+          ...revision.base,
+          slides: (revision.base?.slides ?? []).map((s) => (s.file === file ? { ...s, file: jsx, hydrated: true } : s)),
+        },
+      });
+      revisionLib.noteHydration(ws, [jsx], [file]);
+    }
+    tx.activate({
+      checkpoint: () =>
+        revision &&
+        revisionLib.assertCheckpoint(deckDir, { owner, generation: revision.generation, digest: dirty.inputDigest }),
+    });
+    return { file: jsx, replaced: file, route, joinedBaseline: inBaseline, warnings: result.warnings, skipped: result.skipped };
+  } finally {
+    tx.dispose();
+  }
+}

package/src/lib/deck-paths.mjs

@@ -0,0 +1,418 @@
+// Where a deck keeps its two halves.
+//
+//   decks/<slug>/                 the DELIVERABLE root — only what the user asked for
+//     <slug>.pptx                 the built presentation
+//     plan.html                   the persisted plan page
+//     .slidemind/                 the WORKSPACE — everything the CLI works with
+//       slides/ assets/ conversions/   the render contract (unchanged, and named
+//                                      by the add-in's bundle-shipped workflow docs)
+//       concepts/ plan.md              authoring inputs
+//       state/*.json                   the eight sidecars
+//       preview/                       presentation.html, fonts/, draft/, build/
+//
+// `.slidemind/` holds the deck contract that used to sit at the root, so the
+// CLI needs ONE resolver rather than a path hunt: every command runs on the
+// workspace, and a deck without `.slidemind/` (decks predating this layout, the
+// designer's scratch deck) is its own workspace and keeps working unchanged.
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const WORKSPACE_DIRNAME = ".slidemind";
+
+// `plan.json` / `<something>-plan.json` — a plan record the core does not own.
+// Both the deck test and the page-ownership test key off it.
+function planRecordIn(dir) {
+  try {
+    return fs.readdirSync(dir).find((n) => /^(.+-)?plan\.json$/i.test(n)) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function isDir(p) {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+// Does this directory stand on its own as a deck? An extension pack applies the
+// same test, so both sides answer "is `.slidemind/scratch` a deck or part of its
+// host?" identically. A plan record alone counts: a planned-but-never-authored
+// deck has nothing else yet.
+export function isDeckDir(dir) {
+  if (isDir(path.join(dir, WORKSPACE_DIRNAME))) return true;
+  if (isDir(path.join(dir, "slides")) || isDir(path.join(dir, "conversions"))) return true;
+  if (fs.existsSync(path.join(dir, "plan.md"))) return true;
+  return Boolean(planRecordIn(dir));
+}
+
+// ---------------------------------------------------------------------------
+// layout generation
+// ---------------------------------------------------------------------------
+
+// The layout before `.slidemind/` existed kept everything at the deck root:
+// slides/, assets/, concepts/, plan.md, the sidecars as dotfiles or bare JSON,
+// `.draft-preview/` and `presentation.html`. This CLI no longer reads those —
+// `resolveWorkspace` treats such a root as its own workspace and looks for the
+// sidecars under `state/`, so an old deck silently loses its binding, its plan
+// and review sign-offs and its reconcile ack. `migrateLegacyDeck` moves such a
+// deck into the current layout; the workspace runs it on every registration.
+export const LEGACY_MARKERS = [
+  ".bundle-ref.json",
+  "plan-review.json",
+  "review.json",
+  "draft-check.json",
+  "reconcile-ack.json",
+  "slide-guids.json",
+  ".draft-preview",
+  "presentation.html",
+  "asset-plan.md",
+  "plan.md",
+  "slides",
+  "assets",
+  "concepts",
+  "conversions",
+];
+
+/**
+ * `current` (a `.slidemind/` workspace), `legacy` (the pre-workspace flat
+ * layout: any LEGACY_MARKERS entry at the root) or `unknown` (no layout
+ * evidence — e.g. a plan-only record). One stat for a current deck.
+ */
+export function deckFormat(root) {
+  if (isDir(path.join(root, WORKSPACE_DIRNAME))) return "current";
+  if (LEGACY_MARKERS.some((n) => fs.existsSync(path.join(root, n)))) return "legacy";
+  return "unknown";
+}
+
+// Where each root entry of the flat layout lives in a `.slidemind/` workspace.
+// Every sign-off survives the move: the review hash is workspace-relative path +
+// bytes (`slides/01-x.jsx` is the same string in both layouts), the plan hash is
+// plan.md's bytes, the draft check hashes per slide file — nothing stores an
+// absolute path. The two stylesheet copies are the bundle's, nothing reads them.
+const LEGACY_MOVES = [
+  ["slides", "slides"],
+  ["assets", "assets"],
+  ["concepts", "concepts"],
+  ["conversions", "conversions"],
+  ["plan.md", "plan.md"],
+  ["asset-plan.md", "asset-plan.md"],
+  [".bundle-ref.json", "state/bundle-ref.json"],
+  ["plan-review.json", "state/plan-review.json"],
+  ["review.json", "state/review.json"],
+  ["draft-check.json", "state/draft-check.json"],
+  ["reconcile-ack.json", "state/reconcile-ack.json"],
+  ["slide-guids.json", "state/slide-guids.json"],
+  ["presentation.html", "preview/presentation.html"],
+  [".draft-preview", "preview/draft"],
+  [".draft-preview/draft-check.json", "state/draft-check.json"],
+];
+
+function mtime(p) {
+  try {
+    return fs.statSync(p).mtimeMs;
+  } catch {
+    return -1;
+  }
+}
+
+/**
+ * Move a flat pre-workspace deck into `<root>/.slidemind/`. Idempotent: a deck
+ * that already has a workspace, or carries no legacy marker, is left alone
+ * (returns null). A root `state/` — written by this CLI when it ran on the flat
+ * deck as its own workspace — merges into the new `state/`, newer file wins.
+ * Returns the workspace-relative paths that were written.
+ */
+export function migrateLegacyDeck(root, { bundleDirFor = null } = {}) {
+  // A workspace dir itself looks flat from the inside; never nest one in it.
+  if (path.basename(path.resolve(root)) === WORKSPACE_DIRNAME) return null;
+  if (deckFormat(root) !== "legacy") return null;
+  const ws = path.join(root, WORKSPACE_DIRNAME);
+  const moved = [];
+  const move = (from, to) => {
+    if (!fs.existsSync(from)) return;
+    if (to === null) return fs.rmSync(from, { force: true });
+    if (fs.existsSync(to)) {
+      // Both layouts wrote this sidecar: keep the newer, drop the other.
+      if (mtime(from) <= mtime(to)) return fs.rmSync(from, { force: true, recursive: true });
+      fs.rmSync(to, { force: true, recursive: true });
+    }
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    fs.renameSync(from, to);
+    moved.push(path.relative(ws, to).split(path.sep).join("/"));
+  };
+  fs.mkdirSync(path.join(ws, "state"), { recursive: true });
+  for (const [from, to] of LEGACY_MOVES) {
+    // `.draft-preview/draft-check.json` moves after the dir itself did.
+    const src = from.startsWith(".draft-preview/") ? path.join(ws, "preview/draft", path.basename(from)) : path.join(root, from);
+    move(src, to === null ? null : path.join(ws, to));
+  }
+  const rootState = path.join(root, "state");
+  if (isDir(rootState)) {
+    for (const n of fs.readdirSync(rootState)) move(path.join(rootState, n), path.join(ws, "state", n));
+    fs.rmSync(rootState, { recursive: true, force: true });
+  }
+  // The two stylesheets the flat layout kept at the root are the bundle's, and a
+  // deck no longer carries them — but ownership here is the same rule as
+  // everywhere else: MATCHING BYTES, never the filename. A copy the user edited
+  // is theirs and stays. Runs last, so the bundle ref has already moved into
+  // `state/` and `bundleDirFor` can resolve it; without a resolver nothing is
+  // deleted, because an unprovable delete is the one outcome worth avoiding.
+  const bundleDir = bundleDirFor ? bundleDirFor(ws) : null;
+  if (bundleDir) {
+    for (const [deckRel, bundleRel] of BUNDLE_SOURCES) {
+      const at = path.join(root, deckRel);
+      if (sameBytes(at, path.join(bundleDir, ...bundleRel))) fs.rmSync(at, { force: true });
+    }
+  }
+  return moved;
+}
+
+// The workspace a path lies inside, up to and including its last `.slidemind`
+// segment — null when the path is not inside one.
+function hostWorkspace(p) {
+  const parts = p.split(path.sep);
+  const i = parts.lastIndexOf(WORKSPACE_DIRNAME);
+  return i === -1 ? null : parts.slice(0, i + 1).join(path.sep);
+}
+
+/**
+ * `<deck>/.slidemind` when it exists, else `<deck>` (a flat deck is its own
+ * workspace). A path INSIDE someone else's workspace is either a deck of its own
+ * — the designer's scratch deck at `.slidemind/scratch` — or part of its host, so
+ * `.slidemind/slides` and `.slidemind/plan/` resolve to the workspace that owns them.
+ */
+export function resolveWorkspace(deckDir) {
+  if (!deckDir) return deckDir;
+  const nested = path.join(deckDir, WORKSPACE_DIRNAME);
+  if (isDir(nested)) return nested;
+  const host = hostWorkspace(deckDir);
+  if (host && host !== deckDir && !isDeckDir(deckDir)) return host;
+  return deckDir;
+}
+
+/** The deliverable root of a workspace — one level up from `.slidemind`, else itself. */
+export function deckRoot(workspaceDir) {
+  if (!workspaceDir) return workspaceDir;
+  if (path.basename(workspaceDir) === WORKSPACE_DIRNAME) return path.dirname(workspaceDir);
+  const host = hostWorkspace(workspaceDir);
+  // Inside a workspace and not a deck itself: the deck is the one that owns it.
+  if (host && !isDeckDir(workspaceDir)) return path.dirname(host);
+  return workspaceDir;
+}
+
+/** The deck's name, from the ROOT — `path.basename(workspaceDir)` would say ".slidemind". */
+export function deckSlug(workspaceDir) {
+  return path.basename(path.resolve(deckRoot(workspaceDir)));
+}
+
+/** The built presentation, at the deck root: `<deck>/<slug>.pptx`. */
+export function deckPptxPath(workspaceDir) {
+  return path.join(deckRoot(workspaceDir), `${deckSlug(workspaceDir)}.pptx`);
+}
+
+/** The persisted plan page, at the deck root. */
+export function planPagePath(workspaceDir) {
+  return path.join(deckRoot(workspaceDir), "plan.html");
+}
+
+// The eight sidecars, grouped under `state/`.
+export const STATE_FILES = [
+  "slide-guids.json",
+  "bundle-ref.json",
+  "plan-review.json",
+  "review.json",
+  "draft-check.json",
+  "reconcile-ack.json",
+  "layout-context.json",
+  // The deck's image registry (src/lib/image-assets.mjs): immutable {assetId,
+  // sha256, …} entries for the bytes under `assets/local/`.
+  "image-assets.json",
+  // Image uses a TARGETED EDIT recorded outside a plan stage
+  // (src/lib/image-use-overrides.mjs), keyed by durable slide GUID. Folded back
+  // into the plan by the next approved revision.
+  "image-use-overrides.json",
+  // The intent fingerprint each concept mockup was generated under
+  // (src/builders/concept-intent.mjs) — what makes a stale mockup visible
+  // instead of silently reused.
+  "concept-intent.json",
+];
+
+/** `<workspace>/state/<name>`. */
+export function statePath(workspaceDir, name) {
+  return path.join(workspaceDir, "state", name);
+}
+
+/** Write a sidecar, creating `state/` on the way. */
+export function writeStateFile(workspaceDir, name, contents) {
+  const file = statePath(workspaceDir, name);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, contents);
+  return file;
+}
+
+/** `<workspace>/preview[/draft|/build]` — the one class of output nothing reads back. */
+export function previewPath(workspaceDir, ...sub) {
+  return path.join(workspaceDir, "preview", ...sub);
+}
+
+// ---------------------------------------------------------------------------
+// bundle ownership
+// ---------------------------------------------------------------------------
+
+// Which files in a deck are COPIES of the design bundle's own. Some decks carry
+// the two stylesheets and the chrome/master images; nothing reads them any more,
+// so they are never uploaded and never hashed into a review approval.
+//
+// Ownership is the materialized bundle (the manifest of what the design owns)
+// PLUS byte identity — never the filename. A user's own `assets/master-data.png`,
+// and a same-named file whose bytes differ from the bundle's, stay deck-owned and
+// keep their place in the preview, the upload and the review hash. With no bundle
+// on hand nothing is bundle-owned, which is the safe direction: a deck file is
+// only ever set aside on positive evidence.
+//
+// Returns workspace-relative POSIX paths.
+//
+// ponytail: byte compare after a size check, no content index — an assets dir is
+// tens of files. Hash them if a deck ever carries hundreds.
+const BUNDLE_SOURCES = [
+  ["corporate-design.css", ["corporate-design.css"]],
+  ["layouts.css", ["layouts", "layouts.css"]],
+];
+
+function sameBytes(a, b) {
+  try {
+    if (fs.statSync(a).size !== fs.statSync(b).size) return false;
+    return fs.readFileSync(a).equals(fs.readFileSync(b));
+  } catch {
+    return false;
+  }
+}
+
+export function bundleOwnedFiles(workspaceDir, bundleDir) {
+  const owned = new Set();
+  if (!workspaceDir || !bundleDir) return owned;
+  for (const [deckRel, bundleRel] of BUNDLE_SOURCES) {
+    if (sameBytes(path.join(workspaceDir, deckRel), path.join(bundleDir, ...bundleRel))) {
+      owned.add(deckRel);
+    }
+  }
+  let entries = [];
+  try {
+    entries = fs.readdirSync(path.join(workspaceDir, "assets"), { withFileTypes: true });
+  } catch {
+    return owned;
+  }
+  for (const e of entries) {
+    if (!e.isFile()) continue;
+    const deckFile = path.join(workspaceDir, "assets", e.name);
+    if (sameBytes(deckFile, path.join(bundleDir, "assets", e.name))) {
+      owned.add(`assets/${e.name}`);
+    }
+  }
+  return owned;
+}
+
+// ---------------------------------------------------------------------------
+// who owns plan.html
+// ---------------------------------------------------------------------------
+
+// One deck root, one plan page, one writer. The core CLI renders it from
+// `plan.md`; an extension (a pack) renders its own from its own
+// record. Whoever owns it says so in `state/plan-owner.json`:
+//
+//   { version: 1, owner: "core" | "<extension id>", reviewCommand: "<what a human runs>",
+//     recordPath: "<workspace-relative record>", updatedAt: "<ISO>" }
+//
+// Generic gates never overwrite a page they do not own — they name the owner's
+// review command instead. This is a protocol, not a list: the CLI knows nothing
+// about any particular extension.
+export const PLAN_OWNER_FILE = "plan-owner.json";
+
+/** In the <head> of every page the CORE renderer wrote — an unmarked page is someone else's. */
+export const PLAN_PAGE_MARKER = '<meta name="slidemind-plan-owner" content="core">';
+
+export function readPlanOwner(workspaceDir) {
+  try {
+    const data = JSON.parse(fs.readFileSync(statePath(workspaceDir, PLAN_OWNER_FILE), "utf8"));
+    return data && typeof data.owner === "string" ? data : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writePlanOwner(workspaceDir, { owner, reviewCommand, recordPath }) {
+  return writeStateFile(
+    workspaceDir,
+    PLAN_OWNER_FILE,
+    JSON.stringify(
+      { version: 1, owner, reviewCommand, recordPath, updatedAt: new Date().toISOString() },
+      null,
+      2,
+    ) + "\n",
+  );
+}
+
+// First `bytes` of a file as text, or null — the marker sits in the <head>, and
+// a rendered plan page is a few hundred KB of inlined modules.
+function headOf(file, bytes = 4096) {
+  let fd;
+  try {
+    fd = fs.openSync(file, "r");
+  } catch {
+    return null;
+  }
+  try {
+    const buf = Buffer.alloc(bytes);
+    const n = fs.readSync(fd, buf, 0, bytes, 0);
+    return buf.subarray(0, n).toString("utf8");
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+// A plan record the core does not own: `plan.json` or `<something>-plan.json`,
+// in the workspace or at the deck root. Decks written before the ownership file
+// existed carry one of these and no declaration, so the evidence stands in for it.
+function foreignPlanRecord(workspaceDir) {
+  for (const dir of new Set([workspaceDir, deckRoot(workspaceDir)])) {
+    const hit = planRecordIn(dir);
+    if (hit) return path.relative(workspaceDir, path.join(dir, hit)).split(path.sep).join("/");
+  }
+  return null;
+}
+
+/**
+ * Who may write `<root>/plan.html`: the declaration when there is one, else the
+ * evidence on disk (an unmarked page, or a plan record the core does not own),
+ * else core. `declared` is false when the owner was inferred.
+ */
+export function planPageOwner(workspaceDir) {
+  const declared = readPlanOwner(workspaceDir);
+  if (declared) return { ...declared, declared: true };
+
+  // Transition: decks written before the declaration existed. A record the core
+  // does not own, or a page the core renderer did not write, is an extension's.
+  const extension = (recordPath) => ({
+    version: 1,
+    owner: "extension",
+    reviewCommand: null,
+    recordPath,
+    declared: false,
+  });
+  const record = foreignPlanRecord(workspaceDir);
+  if (record) return extension(record);
+  const head = headOf(planPagePath(workspaceDir));
+  if (head !== null && !head.includes(PLAN_PAGE_MARKER)) return extension(null);
+
+  return {
+    version: 1,
+    owner: "core",
+    reviewCommand: `slidemind plan ${deckSlug(workspaceDir)}`,
+    recordPath: "plan.md",
+    declared: false,
+  };
+}