slidemind 0.3.20 → 0.4.0

package/src/builders/draft-check.mjs

@@ -4,285 +4,52 @@
 // live in the add-in and reach the CLI as the capture engine's `draftChecks`
 // export (`capture.mjs` → `loadDraftChecks`), so in-app see_draft and
 // view-draft run one rule set with one wording. What stays CLI-side is what
-// only exists in the CLI's world: the asset-plan.md inventory form, the
-// .draft-preview record and the gates it arms, and the 422 translate parser.
+// only exists in the CLI's world: the .draft-preview record and the gates it
+// arms, and the 422 translate parser.
 // Images are never overlaid: a magenta proportion grid on the concept and the
 // render dominated both and hid whether the slide was built well.
 
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { deckPptxPath, deckSlug, statePath } from "../lib/deck-paths.mjs";
 
-export const ASSET_PLAN_FILE = "asset-plan.md";
-export const DRAFT_CHECK_FILE = path.join(".draft-preview", "draft-check.json");
-
-// ---------------------------------------------------------------------------
-// Inventory — asset-plan.md as a form the build reads (port of inventory.ts).
-// ---------------------------------------------------------------------------
-
-const SLIDE_HEADING_RE = /^## Slide (\d+)\b/;
-const SLIDE_FILE_NUMBER_RE = /^(\d{1,3})[-_.]/;
-const SECTION_RE = /^(regions|organisms|connectors|icons):/;
-const FETCHED_ASSET_RE = /^(engine|gen)-/;
-// "none", "(none)", "n/a", "no connectors …", "none authorable …" — an
-// explicit empty row, never a listed organism/connector.
-const NONE_RE = /^\(?\s*(none|n\/a|no\b)/i;
-
-const pad2 = (n) => String(n).padStart(2, "0");
-
-// Route kind per connector row / directive — part of the mockup contract: a
-// loop the concept draws as curves that lands as elbows is a different figure,
-// and the count alone (5 = 5) never fires. Port of inventory.ts (gotcha 84).
-const ROUTE_KINDS = ["straight", "elbow", "curved"];
-const emptyRoutes = () => ({ straight: 0, elbow: 0, curved: 0 });
-function routeKindOf(text) {
-  for (const token of text.split(",")) {
-    const t = token.trim().toLowerCase();
-    if (ROUTE_KINDS.includes(t)) return t;
-  }
-  return null;
-}
-const describeRoutes = (r) => ROUTE_KINDS.map((k) => `${r[k]} ${k}`).join(", ");
-
-/** Seed the inventory form once (never overwrites a filled one). `images`: [{slideNumber,label}]. */
-export function seedAssetPlan(deckDir, images) {
-  const file = path.join(deckDir, ASSET_PLAN_FILE);
-  if (!images?.length || fs.existsSync(file)) return false;
-  const slides = [...images]
-    .sort((a, b) => a.slideNumber - b.slideNumber)
-    .map((img) =>
-      img.frame
-        ? [
-            `## Slide ${pad2(img.slideNumber)} — ${img.label ?? `Slide ${img.slideNumber}`}`,
-            `jsx: slides/${pad2(img.slideNumber)}-<name>.jsx`,
-            `(frame slide — ${img.frame}: chrome slots only, authored from the plan as the layout's props; no inventory, no mockup, no verdict)`,
-            "",
-          ].join("\n")
-        : [
-        `## Slide ${pad2(img.slideNumber)} — ${img.label ?? `Slide ${img.slideNumber}`}`,
-        `jsx: slides/${pad2(img.slideNumber)}-<name>.jsx`,
-        "regions:",
-        "- ",
-        "organisms:",
-        "- ",
-        "connectors:",
-        "- ",
-        "icons:",
-        "- ",
-        "",
-      ].join("\n"),
-    );
-  fs.writeFileSync(
-    file,
-    [
-      "# Asset plan — concept inventory",
-      "",
-      "Fill this BEFORE writing any slide, from `concepts/concept-slide-NN.png` (the BODY region only —",
-      "chrome goes through layout props). One bullet per line; the",
-      "draft check counts `connectors:` against the JSX and every fetched asset against the slides.",
-      "",
-      "- regions: split of the content slot in percentages of its width/height, e.g. `hero left x0–60 y0–100`, `rail right x65–100`, `callout bottom y85–100`.",
-      "- organisms: every card, figure, badge, chip row, callout, loop, satellite — region, share, alignment.",
-      "- connectors: `from → to, straight|elbow|curved, arrow end|both|none, solid|dashed` — one per arrow/line in the mockup.",
-      "- icons: subject, prominence, engine query; append the fetched `assets/<file>` when sourced, or `(no result)`.",
-      "",
-      "After `slidemind view-draft`, under each slide add `draft-check:` followed by ONE tick line per",
-      "organism row: `- [x] <organism>` when it is in the render at the concept's position and share,",
-      "`- [ ] <organism> — <what differs>` when it is not. `review` refuses to open while a slide has",
-      "fewer ticks than organisms or any `[ ]` left — fix the miss in the JSX, re-render, re-tick.",
-      "",
-      ...slides,
-    ].join("\n"),
-  );
-  return true;
-}
-
-function parseAssetPlan(text) {
-  const out = new Map();
-  let current = null;
-  let section = "";
-  for (const raw of text.split("\n")) {
-    const line = raw.trim();
-    const heading = SLIDE_HEADING_RE.exec(line);
-    if (heading) {
-      current = { filled: false, connectors: 0, routes: emptyRoutes(), organisms: 0, icons: 0, iconsResolved: 0, verdict: null, ticked: 0, unticked: 0 };
-      out.set(Number(heading[1]), current);
-      section = "";
-      continue;
-    }
-    if (!current) continue;
-    if (/^draft-check:/i.test(line)) {
-      current.verdict = line.slice("draft-check:".length).trim();
-      section = "draft-check";
-      continue;
-    }
-    if (section === "draft-check") {
-      const tick = /^-\s*\[( |x|X)\]/.exec(line);
-      if (tick) {
-        if (tick[1] === " ") current.unticked += 1;
-        else current.ticked += 1;
-        continue;
-      }
-    }
-    const sec = SECTION_RE.exec(line);
-    if (sec) {
-      section = sec[1];
-      // Inline form (`connectors: a -> b, …; c -> d, …`) counts like bullets —
-      // agents write both shapes; only the seeded form uses bullets.
-      const inline = line.slice(sec[0].length).trim();
-      if (inline && !NONE_RE.test(inline)) {
-        if (section === "organisms" || section === "regions") current.filled = true;
-        if (section === "connectors") {
-          for (const row of inline.split(";")) {
-            if (!row.trim()) continue;
-            current.connectors += 1;
-            const kind = routeKindOf(row);
-            if (kind) current.routes[kind] += 1;
-          }
-        }
-      }
-      continue;
-    }
-    if (!line.startsWith("-")) continue;
-    const body = line.slice(1).trim();
-    if (!body || NONE_RE.test(body)) continue;
-    if (section === "organisms" || section === "regions") current.filled = true;
-    if (section === "organisms") current.organisms += 1;
-    if (section === "connectors") {
-      current.connectors += 1;
-      const kind = routeKindOf(body);
-      if (kind) current.routes[kind] += 1;
-    }
-    if (section === "icons") {
-      current.icons += 1;
-      // Resolved = a fetched file appended, or an explicit "(no result)".
-      if (/assets\/|\(no result\)/i.test(body)) current.iconsResolved += 1;
-    }
-  }
-  return out;
-}
+// Which draft lines hold the gate is the shared table's (draft-lines.mjs,
+// mirrored into the add-in): `view-draft` records every line it does not
+// class as advisory, and that record is what `review` and delivery refuse on.
+import {
+  draftLineTier,
+  preservationFailureLines,
+  preservationUnreadableLine,
+} from "./draft-lines.mjs";
+export { draftLineTier };
 
 /**
- * The asset plan as stage facts: per slide whether the inventory is filled,
- * how many icon rows exist and how many are resolved. null without a plan.
+ * A build's package lines (build-pptx, push), split by the same table: a
+ * defect means the file is not ready for the user; a line outside the table is
+ * a note; the advisories the draft check already printed are not repeated.
  */
-export function assetPlanSummary(deckDir) {
-  const planFile = path.join(deckDir, ASSET_PLAN_FILE);
-  if (!fs.existsSync(planFile)) return null;
-  let plan;
-  try {
-    plan = parseAssetPlan(fs.readFileSync(planFile, "utf8"));
-  } catch {
-    return null;
-  }
-  const out = { slides: plan.size, unfilled: 0, icons: 0, iconsResolved: 0 };
-  for (const inv of plan.values()) {
-    if (!inv.filled) out.unfilled += 1;
-    out.icons += inv.icons;
-    out.iconsResolved += inv.iconsResolved;
-  }
-  return out;
-}
-
-function countConnectors(jsx) {
-  const attached = (jsx.match(/data-connector\b/g) ?? []).length;
-  const markers = (jsx.match(/marker-(?:end|start)\s*=/g) ?? []).length;
-  return attached + markers;
+export function splitPackageLines(warnings) {
+  const lines = (warnings ?? []).map((w) => String(w).trim());
+  return {
+    defects: lines.filter((l) => draftLineTier(l) === "defect"),
+    notes: lines.filter((l) => draftLineTier(l) === null),
+  };
 }
 
-// Route kind per `data-connector` directive; a missing data-route is straight.
-// Imported native connectors carry their own preset and are not authored
-// against the mockup, so they are left out of the kind tally.
-function countRoutes(jsx) {
-  const routes = emptyRoutes();
-  for (const tag of jsx.match(/<[^<>]*\bdata-connector\b[^<>]*>/g) ?? []) {
-    if (/\bdata-native-connector\b/.test(tag)) continue;
-    const kind = /\bdata-route\s*=\s*["']([a-z]+)["']/.exec(tag)?.[1] ?? "straight";
-    if (ROUTE_KINDS.includes(kind)) routes[kind] += 1;
-  }
-  return routes;
+/** The `PACKAGE DEFECTS:` block both delivering commands print. */
+export function packageDefectsText(defects, deckName) {
+  return (
+    `PACKAGE DEFECTS: ${defects.length} measured defect${defects.length === 1 ? "" : "s"} in the built file — not ready for the user. ` +
+    `Fix each in the JSX, run \`slidemind view-draft ${deckName} --only <slide>\`, then deliver again:\n` +
+    defects.map((l) => `  ${l}\n`).join("")
+  );
 }
 
-/**
- * `[inventory:warn]` lines for the deck: per authored slide (inventory empty,
- * connectors listed > drawn) plus fetched assets no slide references. Empty
- * when the deck has no asset-plan.md.
- */
-export function inventoryWarnings(deckDir, jsxFiles = null) {
-  const planFile = path.join(deckDir, ASSET_PLAN_FILE);
-  if (!fs.existsSync(planFile)) return [];
-  let plan;
-  try {
-    plan = parseAssetPlan(fs.readFileSync(planFile, "utf8"));
-  } catch {
-    return [];
-  }
-  if (plan.size === 0) return [];
-  const slidesDir = path.join(deckDir, "slides");
-  const allJsx = fs.existsSync(slidesDir)
-    ? fs.readdirSync(slidesDir).filter((f) => f.endsWith(".jsx")).sort()
-    : [];
-  const files = jsxFiles ?? allJsx;
-  const lines = [];
-  for (const file of files) {
-    const num = SLIDE_FILE_NUMBER_RE.exec(file);
-    if (!num) continue;
-    const inv = plan.get(Number(num[1]));
-    if (!inv) continue;
-    const jsxPath = `slides/${file}`;
-    if (!inv.filled) {
-      lines.push(
-        `[inventory:warn] ${jsxPath} — asset-plan.md has no regions/organisms rows for this slide. Inventory its concept mockup (every organism, its region and share) and rebuild from that list, not from memory.`,
-      );
-      continue;
-    }
-    let jsx = "";
-    try {
-      jsx = fs.readFileSync(path.join(slidesDir, file), "utf8");
-    } catch {
-      continue;
-    }
-    const drawn = countConnectors(jsx);
-    if (inv.connectors > drawn) {
-      lines.push(
-        `[inventory:warn] ${jsxPath} — asset-plan.md lists ${inv.connectors} connector${inv.connectors === 1 ? "" : "s"} for this slide, the JSX draws ${drawn} (data-connector / marker-end). Draw the missing ones per workflow/authoring.md → Arrow contract; a mockup connector is never dropped.`,
-      );
-    }
-    const drawnRoutes = countRoutes(jsx);
-    for (const kind of ROUTE_KINDS) {
-      if (inv.routes[kind] > drawnRoutes[kind]) {
-        lines.push(
-          `[inventory:warn] ${jsxPath} — asset-plan.md lists ${inv.routes[kind]} ${kind} connector${inv.routes[kind] === 1 ? "" : "s"} for this slide, the JSX draws ${drawnRoutes[kind]} (${describeRoutes(drawnRoutes)}). The mockup's route shape is the contract: keep data-route="${kind}" and fix the endpoint sides or node positions instead of changing the route kind.`,
-        );
-      }
-    }
-  }
-  // Fetched assets nobody references: the mockup staged them, the deck lost them.
-  const referenced = allJsx
-    .map((f) => {
-      try {
-        return fs.readFileSync(path.join(slidesDir, f), "utf8");
-      } catch {
-        return "";
-      }
-    })
-    .join("\n");
-  const assetsDir = path.join(deckDir, "assets");
-  const assets = fs.existsSync(assetsDir) ? fs.readdirSync(assetsDir).sort() : [];
-  const planText = fs.readFileSync(planFile, "utf8");
-  for (const file of assets) {
-    if (!FETCHED_ASSET_RE.test(file)) continue;
-    if (referenced.includes(file)) continue;
-    if (new RegExp(`${file.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[^\\n]*\\(unused\\)`).test(planText)) continue;
-    lines.push(
-      `[inventory:warn] assets/${file} was fetched for this deck but no slide references it — place it where the mockup stages that icon (\`<img src="./assets/${file}">\`), or mark it \`(unused)\` in asset-plan.md.`,
-    );
-  }
-  return lines;
-}
+export const DRAFT_CHECK_FILE = "draft-check.json";
 
 // ---------------------------------------------------------------------------
-// The draft-check record — what `review` refuses on.
+// The draft-check record — what `review`, `build-pptx` and `push` refuse on.
 // ---------------------------------------------------------------------------
 
 export function hashFile(file) {
@@ -291,7 +58,7 @@ export function hashFile(file) {
 
 /** Persist the measured defects per slide, keyed by the jsx content hash. */
 export function saveDraftCheck(deckDir, slides) {
-  const file = path.join(deckDir, DRAFT_CHECK_FILE);
+  const file = statePath(deckDir, DRAFT_CHECK_FILE);
   fs.mkdirSync(path.dirname(file), { recursive: true });
   const record = { version: 1, at: new Date().toISOString(), slides: {} };
   for (const s of slides) record.slides[s.fileName] = { hash: s.hash, defects: s.defects };
@@ -301,117 +68,97 @@ export function saveDraftCheck(deckDir, slides) {
 
 export function loadDraftCheck(deckDir) {
   try {
-    return JSON.parse(fs.readFileSync(path.join(deckDir, DRAFT_CHECK_FILE), "utf8"));
+    return JSON.parse(fs.readFileSync(statePath(deckDir, DRAFT_CHECK_FILE), "utf8"));
   } catch {
     return null;
   }
 }
 
 /**
- * Standing measured defects: the last view-draft flagged them and the jsx has
- * not changed since. null when nothing stands (no record, all fixed, or the
- * slide was edited after the check — the next view-draft re-measures it).
+ * Why these slides may not reach the user yet, or null. Every slide file
+ * delivered (default: every authored `.jsx` under slides/) needs a draft check
+ * of its current bytes that left no defect standing. A slide never checked, or
+ * edited after its check, holds like a defect: only a new view-draft clears a
+ * check, and editing is not evidence that a defect was fixed.
  */
-export function draftCheckBlocker(deckDir) {
-  const record = loadDraftCheck(deckDir);
-  if (!record?.slides) return null;
+export function draftCheckBlocker(deckDir, { files = null } = {}) {
+  const slidesDir = path.join(deckDir, "slides");
+  let shipped = files;
+  if (!shipped) {
+    try {
+      shipped = fs.readdirSync(slidesDir).filter((f) => f.endsWith(".jsx"));
+    } catch {
+      shipped = [];
+    }
+  }
+  const slides = loadDraftCheck(deckDir)?.slides ?? {};
   const standing = [];
-  for (const [fileName, entry] of Object.entries(record.slides)) {
-    if (!entry?.defects?.length) continue;
-    const file = path.join(deckDir, "slides", fileName);
+  for (const fileName of [...new Set(shipped)].filter((f) => f.endsWith(".jsx")).sort((a, b) => a.localeCompare(b, "en", { numeric: true }))) {
+    const file = path.join(slidesDir, fileName);
     if (!fs.existsSync(file)) continue;
-    if (hashFile(file) !== entry.hash) continue;
-    standing.push(...entry.defects);
+    const entry = slides[fileName];
+    if (!entry) {
+      standing.push(`[draft:unchecked] ${fileName} has no draft check. Run view-draft --only ${fileName} and inspect the new image.`);
+      continue;
+    }
+    if (hashFile(file) !== entry.hash) {
+      standing.push(`[draft:stale] ${fileName} changed after its preview. Re-run view-draft --only ${fileName} and inspect the new image.`);
+      continue;
+    }
+    standing.push(...(entry.defects ?? []));
   }
   if (standing.length === 0) return null;
   return (
-    `the last draft check measured ${standing.length} defect${standing.length === 1 ? "" : "s"} that still stand ` +
-    `(the slide files are unchanged since). Fix them in the JSX, re-run \`slidemind view-draft\`, then \`review\`:\n` +
+    `the draft check has ${standing.length} unresolved defect${standing.length === 1 ? "" : "s"} or unchecked slide${standing.length === 1 ? "" : "s"}. ` +
+    `Fix the defects, re-run \`slidemind view-draft\`, then retry:\n` +
     standing.map((l) => `  ${l}`).join("\n")
   );
 }
 
-
-// ---------------------------------------------------------------------------
-// The self-check verdict — an inventory, not an opinion.
-//
-// Every `draft-check:` verdict on disk across 181 judged sessions reads
-// "matches" (15 of 15), including slides the judge scored 0.71 with eight
-// organisms missing. A verdict is free; a tick per organism is not — the
-// agent has to find each one in the render or say what differs.
-// ---------------------------------------------------------------------------
-
-/**
- * Concept-seeded slides whose asset-plan.md section lists organisms but whose
- * `draft-check:` is missing, ticks fewer organisms than listed, or leaves a
- * `[ ]` standing. null when every such slide is fully ticked.
- */
-export function verdictBlocker(deckDir) {
-  const planFile = path.join(deckDir, ASSET_PLAN_FILE);
-  if (!fs.existsSync(planFile)) return null;
-  let plan;
-  try {
-    plan = parseAssetPlan(fs.readFileSync(planFile, "utf8"));
-  } catch {
-    return null;
-  }
-  const slidesDir = path.join(deckDir, "slides");
-  const conceptsDir = path.join(deckDir, "concepts");
-  const files = fs.existsSync(slidesDir)
-    ? fs.readdirSync(slidesDir).filter((f) => f.endsWith(".jsx")).sort()
-    : [];
-  const problems = [];
-  for (const file of files) {
-    const num = SLIDE_FILE_NUMBER_RE.exec(file);
-    if (!num) continue;
-    const n = Number(num[1]);
-    const inv = plan.get(n);
-    if (!inv || inv.organisms === 0) continue;
-    if (!fs.existsSync(path.join(conceptsDir, `concept-slide-${pad2(n)}.png`))) continue;
-    const ticks = inv.ticked + inv.unticked;
-    if (inv.verdict === null) {
-      problems.push(`slides/${file}: no draft-check verdict — asset-plan.md lists ${inv.organisms} organisms; open the concept and the render together and tick each one`);
-    } else if (inv.unticked > 0) {
-      problems.push(`slides/${file}: ${inv.unticked} organism${inv.unticked === 1 ? "" : "s"} ticked [ ] (differs) — fix in the JSX, re-run view-draft, re-tick`);
-    } else if (ticks < inv.organisms) {
-      problems.push(`slides/${file}: asset-plan.md lists ${inv.organisms} organisms, the verdict ticks ${ticks} — one \`- [x]\`/\`- [ ]\` line per organism`);
-    }
-  }
-  if (problems.length === 0) return null;
-  return (
-    "the self-check is incomplete — a verdict is one tick per organism, not one word:\n" +
-    problems.map((l) => `  ${l}`).join("\n")
-  );
-}
-
 // ---------------------------------------------------------------------------
-// Translate-gate errors — the server's slot-fit / diagram-geometry /
-// connector-endpoints verdicts, folded into the draft check so a builder
+// Translate-gate errors — the server's slot-fit / diagram-geometry / escape
+// verdicts (older add-ins also sent connector-endpoints), folded into the draft check so a builder
 // learns them on ITS slide before the deck-wide export, not five build-pptx
 // rounds later (x18: 17 of 39 minutes were that loop).
 // ---------------------------------------------------------------------------
 
 /**
- * Split a translate 422 message into per-slide lines. The server writes
- * `<file>.jsx: <rule>: <summary>` headers followed by `  [<rule>:error] <stem> — …`
- * lines; both are kept, keyed by the jsx file name. Unattributed lines land
- * under "" so nothing is lost.
+ * Split a translate 422 message into per-slide lines. The server prefixes each
+ * failing slide's error with `<file>.jsx: `, and that prefix makes it the
+ * current slide whatever follows: a `<rule>: <summary>` gate header (kept as
+ * `[<rule>:error] <file> — <summary>`), a tagged `[<tag>:error] <stem> — …`
+ * line (chrome), or plain text (a degraded render). Gate headers are followed
+ * by `  [<rule>:error] <stem> — …` lines; a slide that fails several measured
+ * gates reports each further gate as a bare `<rule>: <summary>` header under
+ * the same file. A chrome verdict quotes the slide's text, and a line break
+ * in that text splits it: the next unmatched line completes the chrome line
+ * just added, wherever it was filed. Unattributed lines land under "" so
+ * nothing is lost.
  */
 export function parseTranslateErrors(message) {
   const out = new Map();
+  let open = null; // the file whose last line is a chrome verdict cut inside its quote
   const add = (file, line) => {
     if (!out.has(file)) out.set(file, []);
     out.get(file).push(line);
+    open = /^\[chrome:error\]/.test(line) && (line.match(/"/g) ?? []).length % 2 ? file : null;
   };
   const text = String(message ?? "").replace(/^[^\n]*\/translate:\s*/, "");
   let current = "";
   for (const raw of text.split("\n")) {
     const line = raw.trimEnd();
     if (!line.trim()) continue;
-    const head = /^\s*(\S+\.jsx):\s+([a-z-]+):\s+(.*)$/.exec(line);
+    const head = /^\s*(\S+\.jsx):\s+(.*)$/.exec(line);
     if (head) {
       current = head[1];
-      add(current, `[${head[2]}:error] ${head[1]} — ${head[3]}`);
+      const rule = /^([a-z-]+):\s+(.*)$/.exec(head[2]);
+      if (rule) add(current, `[${rule[1]}:error] ${current} — ${rule[2]}`);
+      else add(current, head[2].startsWith("[") ? head[2] : line.trim());
+      continue;
+    }
+    const bare = current ? /^(slot-fit|svg-overlay|connector-endpoints|diagram-geometry|escape):\s+(.*)$/.exec(line) : null;
+    if (bare) {
+      add(current, `[${bare[1]}:error] ${current} — ${bare[2]}`);
       continue;
     }
     const tagged = /^\s*\[([a-z-]+):error\]\s+(\S+)\s+—/.exec(line);
@@ -421,7 +168,472 @@ export function parseTranslateErrors(message) {
       add(file, line.trim());
       continue;
     }
-    add(current, line.trim());
+    if (open) {
+      const file = open;
+      add(file, `${out.get(file).pop()} ${line.trim()}`);
+    } else add(current, line.trim());
   }
   return out;
 }
+
+// ---------------------------------------------------------------------------
+// Preservation — what a slide still OWES, checked by element identity.
+// ---------------------------------------------------------------------------
+//
+// This replaces the old `ownership()` gate, which switched the concept-spec
+// count check OFF the moment a slide's bytes stopped matching
+// `state/transcribed.json`. That is exactly backwards: a hand edit is when a
+// slide is most likely to lose something, and "the hash changed" was read as
+// "nothing is owed any more" (E09 — a title edit that drops an arrow).
+//
+// What is owed now lives in `state/slide-preservation.json` (src/lib/edit-state.mjs),
+// one requirement per element identity, and it survives any rewrite. Two
+// evidence channels answer it, because neither can answer alone:
+//
+//   source — the only place a connector can be checked. Its id is DERIVED from
+//            the pair it joins (`conn-a-b`) and never reaches the DOM, so the
+//            render literally cannot see one.
+//   render — the only place "present in the JSX but paints nothing" shows up.
+//
+// The modules are imported lazily: `edit-state` pulls in revision + bundle
+// resolution, and `draft-check` is loaded eagerly by `status` and `concepts`.
+
+/**
+ * The two packages a slide's obligations can be proved against: the import it
+ * came FROM, and the deck as last DELIVERED. Both or nothing — comparing a
+ * package with itself proves only that it exists, which is the "manufacture a
+ * package to satisfy the gate" move. A slide with no import baseline (anything
+ * authored rather than converted) therefore has no package evidence and stays
+ * `unknown`; see `packageEvidenceReachable`.
+ */
+function packagePair(deckDir, fileName) {
+  const stem = fileName.replace(/\.[^.]+$/, "");
+  const base = path.join(deckDir, "conversions", `${stem}.slide.pptx`);
+  const delivered = deckPptxPath(deckDir);
+  if (!fs.existsSync(base) || !fs.existsSync(delivered)) return null;
+  return { base, delivered };
+}
+
+/** Can this slide's obligations be proved from packages at all? */
+export function packageEvidenceReachable(deckDir, fileName) {
+  return packagePair(deckDir, fileName) !== null;
+}
+
+/**
+ * One slide's package evidence: its import compared against the bytes the deck
+ * last delivered, keyed by the element identity both packages carry.
+ *
+ * The delivered slide is found by its GUID in the baked source tags, never by
+ * position — a native slide spliced in ahead of it would shift every index.
+ * Null whenever anything cannot be established; nothing here guesses.
+ */
+function workspaceResolvedTargets(deckDir, fileName, entry) {
+  // A requirement's relationship targets are minted in THREE namespaces and
+  // only one of them is an OOXML part path:
+  //
+  //   start / end    an element id on the same slide  → the package resolves it
+  //   package-part   a WORKSPACE path                 → the filesystem does
+  //   native-slot    an index into the conversion      → that record does
+  //                  record's `preserved[]`
+  //
+  // `composeSlideEvidence().resolvedTargets` only speaks the first. Passing it
+  // alone makes every native-object requirement fail `relationship_broken`
+  // against a file that is sitting right there — a FALSE DELETION, which is
+  // worse than the `unknown` it replaces. So each target is resolved in the
+  // namespace it was minted in, and anything that does not resolve stays
+  // unresolved and still fails.
+  const resolved = [];
+  let preserved = 0;
+  try {
+    const stem = fileName.replace(/\.[^.]+$/, "");
+    const record = JSON.parse(fs.readFileSync(path.join(deckDir, "conversions", `${stem}.json`), "utf8"));
+    preserved = Array.isArray(record?.preserved) ? record.preserved.length : 0;
+  } catch {}
+  for (const req of entry?.active ?? []) {
+    for (const rel of req.relationships ?? []) {
+      if (rel.role === "package-part") {
+        if (fs.existsSync(path.join(deckDir, String(rel.target)))) resolved.push(rel.target);
+      } else if (rel.role === "native-slot") {
+        const slot = Number(rel.target);
+        if (Number.isInteger(slot) && slot >= 0 && slot < preserved) resolved.push(rel.target);
+      }
+    }
+  }
+  return resolved;
+}
+
+async function packageEvidenceFor(deckDir, fileName, slideKey, entry) {
+  const pair = packagePair(deckDir, fileName);
+  if (!pair) return null;
+  try {
+    const [{ unzip }, { slideOrderPaths }, tags, { composeSlideEvidence }, verdictMod] = await Promise.all([
+      import("../pptx/zip.mjs"),
+      import("../pptx/ooxml.mjs"),
+      import("../pptx/tags.mjs"),
+      import("../pptx/package-evidence.mjs"),
+      import("../lib/preservation-verdict.mjs"),
+    ]);
+    const beforeFiles = unzip(fs.readFileSync(pair.base));
+    const afterFiles = unzip(fs.readFileSync(pair.delivered));
+    const part = slideOrderPaths(afterFiles).find((candidate) => {
+      try {
+        return tags.decodeSourceTags(tags.readSlideTags(afterFiles, candidate))?.guid === slideKey;
+      } catch {
+        return false;
+      }
+    });
+    if (!part) return null; // the delivered deck does not carry this slide
+    const before = composeSlideEvidence(beforeFiles);
+    const after = composeSlideEvidence(afterFiles, { slidePart: part });
+    if (!before.slidePart || !after.slidePart) return null;
+    return verdictMod.comparePackageEvidence(before.shapes, after.shapes, {
+      resolvedTargets: [
+        ...after.resolvedTargets,
+        ...workspaceResolvedTargets(deckDir, fileName, entry),
+      ],
+    });
+  } catch {
+    // Evidence that cannot be composed is absent evidence, never a pass.
+    return null;
+  }
+}
+
+async function preservationModules() {
+  const [state, verdict, guids] = await Promise.all([
+    import("../lib/edit-state.mjs"),
+    import("../lib/preservation-verdict.mjs"),
+    import("../lib/slide-guids.mjs"),
+  ]);
+  return { state, verdict, guids };
+}
+
+// failed > unsupported > unknown > passed. `unsupported` rolls up as `unknown`
+// downstream — the verdict module already does that for its own status, and
+// missing evidence is never a pass.
+const EVIDENCE_ORDER = ["failed", "unsupported", "unknown", "passed"];
+const worstOf = (statuses) => EVIDENCE_ORDER.find((s) => statuses.includes(s)) ?? "passed";
+
+// The CLI's way to declare an intended removal, named in every [preserve:warn].
+const supersedeHint = (deckDir) =>
+  `supersede the obligation explicitly (\`slidemind revision begin ${deckSlug(deckDir)} --operation targeted-edit\`)`;
+
+/**
+ * The preservation diagnostics for one captured deck, per slide file.
+ *
+ * `slides` is `[{ fileName, render }]` straight off the capture. Returns
+ * `{ byFile, covered }` — `covered` names every slide that HAS a record,
+ * which is what stands the spec-count check down (each of its elements is
+ * checked by id instead, which is strictly stronger than counting them).
+ *
+ * Draft diagnostics never block: they name the element and the repair. What
+ * blocks is {@link preservationBlocker} at delivery.
+ */
+export async function preservationDiagnostics(deckDir, slides, { persist = true } = {}) {
+  const empty = { byFile: {}, covered: new Set() };
+  let mods;
+  try {
+    mods = await preservationModules();
+  } catch {
+    return empty;
+  }
+  const { readSlidePreservation, writeSlidePreservation, openOperations, sourceHash } = mods.state;
+  const { requirementEvidenceFromSource, checkRequirements, evidenceStatus } = mods.state;
+  const { compareRenderEvidence, preservationVerdict, readSlideElements } = mods.verdict;
+
+  let doc;
+  try {
+    doc = readSlidePreservation(deckDir);
+  } catch (err) {
+    // Delivery refuses an unreadable record (preservationBlocker), so the draft
+    // names it as a defect, on the first slide, as the add-in's render does.
+    const first = (slides ?? []).find((s) => /\.jsx$/i.test(s.fileName ?? ""));
+    if (!first) return empty;
+    return {
+      ...empty,
+      byFile: { [first.fileName]: [preservationUnreadableLine({ fileName: first.fileName, detail: err.message })] },
+    };
+  }
+  if (Object.keys(doc.slides ?? {}).length === 0) return empty;
+
+  const guids = mods.guids.loadSlideGuids(deckDir);
+  let operations = [];
+  try {
+    operations = openOperations(deckDir);
+  } catch {}
+
+  const byFile = {};
+  const covered = new Set();
+  const next = { ...doc, slides: { ...doc.slides } };
+  let changed = false;
+
+  for (const { fileName, render } of slides ?? []) {
+    if (!/\.jsx$/i.test(fileName)) continue;
+    const jsxPath = `slides/${fileName}`;
+    const slideKey = guids[jsxPath];
+    const entry = slideKey ? doc.slides[slideKey] : null;
+    if (!entry) continue;
+    let jsx;
+    try {
+      jsx = fs.readFileSync(path.join(deckDir, jsxPath), "utf8");
+    } catch {
+      continue;
+    }
+    covered.add(fileName);
+    const operation =
+      operations.find((o) => (o.targets ?? []).some((t) => t?.slideKey === slideKey)) ?? null;
+
+    // Ask the render only about ids the source actually declares as a DOM id.
+    // Everything else (connectors above all) is the source check's business —
+    // asking the render would read "absent" for every arrow ever drawn.
+    const declared = readSlideElements(jsx).byId;
+    const ids = (entry.active ?? []).map((r) => r.elementId).filter((id) => declared.has(id));
+    let renderEvidence = compareRenderEvidence(render ?? null, {
+      canvas: render?.canvas ?? null,
+      elementIds: ids,
+    });
+    if (ids.length > 0 && renderEvidence.indexed.length === 0) {
+      // Boxes, but not one carries an identity: this capture proved nothing
+      // about any element. Silence is `unknown`, never absence.
+      renderEvidence = {
+        ...renderEvidence,
+        evidence: "absent",
+        byId: Object.fromEntries(
+          ids.map((id) => [id, { status: "unknown", reason: "no_identified_boxes" }]),
+        ),
+      };
+    }
+    // The third channel. Present only for a slide whose import AND delivered
+    // bytes are both on disk; a draft has neither, and gets none.
+    const packageEvidence = await packageEvidenceFor(deckDir, fileName, slideKey, entry);
+    const verdict = preservationVerdict({
+      entry,
+      operation,
+      slideKey,
+      render: renderEvidence,
+      packageEvidence,
+      binding: { sourceHash: sourceHash(deckDir, jsxPath) },
+    });
+    const source = checkRequirements(
+      entry,
+      requirementEvidenceFromSource(jsx, { origin: entry.origin }),
+      { operation },
+    );
+
+    // One verdict, both channels. The source violations become checks of the
+    // verdict's own shape so that everything downstream — the lines here, the
+    // refusal at delivery — reads ONE list and names the same elements.
+    const checks = [
+      ...verdict.checks,
+      ...source.violations.map((v) => ({
+        requirementId: v.requirementId ?? null,
+        elementId: v.elementId ?? null,
+        kind: null,
+        scope: null,
+        status: "failed",
+        reason: v.code,
+        detail: v.detail,
+      })),
+    ];
+    // `checkRequirements` reports every non-`media` scope UNVERIFIED, because
+    // source bytes cannot prove a text, fill or geometry is unchanged. That is
+    // "source cannot say", not "nobody can" — so once the package HAS spoken,
+    // its silence must not veto the answer. Its VIOLATIONS always count: a
+    // missing element, a repointed connector or a swapped asset is a fact about
+    // the source, which no package evidence makes untrue.
+    const sourceStatus = packageEvidence
+      ? source.violations.length > 0
+        ? "failed"
+        : "passed"
+      : evidenceStatus(source);
+    const status = worstOf([verdict.status, sourceStatus]);
+    const counts = Object.fromEntries(EVIDENCE_ORDER.map((s) => [s, 0]));
+    for (const c of checks) counts[c.status] = (counts[c.status] ?? 0) + 1;
+    const merged = { ...verdict, status, checks, counts };
+
+    // One wording on both clients (draft-lines.mjs).
+    const lines = preservationFailureLines({
+      fileName,
+      checks,
+      active: entry.active,
+      supersede: supersedeHint(deckDir),
+    });
+    if (lines.length > 0) byFile[fileName] = lines;
+
+    if (entry.evidence !== status || entry.verdict?.binding?.sourceHash !== merged.binding.sourceHash) {
+      next.slides[slideKey] = { ...entry, evidence: status, verdict: merged };
+      changed = true;
+    }
+  }
+
+  if (persist && changed) {
+    // Obligations are never dropped here — only the verdict and the evidence
+    // status move — so the transition rule has nothing to refuse. A refusal is
+    // still swallowed: a draft preview must not die over its own bookkeeping.
+    try {
+      writeSlidePreservation(deckDir, next);
+    } catch {}
+  }
+  return { byFile, covered };
+}
+
+/**
+ * Why a FINAL replacement cannot go ahead, or null.
+ *
+ * Scope is REPLACEMENT, and a preservation record is what marks it — not
+ * session bookkeeping. Three things seed one, and all three mean "this slide
+ * existed before this build": `revision begin` (migrated from current
+ * evidence), `adopt` (restored from the package's embedded tags,
+ * src/lib/preservation-tags.mjs), and `transcribe --repair`. A deck authored
+ * from scratch acquires none of them, so ordinary authoring is never gated —
+ * this change safeguards replacement, it does not add a precondition to
+ * creating slides.
+ *
+ * Deliberately NOT keyed on an open operation. An operation is how a user
+ * DECLARES an edit and what permits a removal (`permittedChanges`, honoured in
+ * the draft verdict); it is not how a replacement is detected. Keying on it
+ * would have left the commonest replacement there is — `build-pptx` on an
+ * adopted deck, whose records `adopt` restored — entirely ungated, so E09's
+ * protection would have existed only for users who happened to open a scope by
+ * hand. Build-time inference (`inferBuildOperations`) would answer the same
+ * question one indirection later and has no production caller today.
+ *
+ * ponytail: draft evidence alone rarely reaches `passed` (a connector's
+ * endpoints and a native's package closure are only resolvable against the
+ * final package, which is task 5.5/5.6's channel). Until that lands, the way
+ * past it is to fix what the draft names, not to remove the record.
+ */
+export async function preservationBlocker(deckDir) {
+  const clear = { blocker: null, note: null };
+  let mods;
+  try {
+    mods = await preservationModules();
+  } catch {
+    return clear;
+  }
+  const { readSlidePreservation, finalEvidenceBlockers, sourceHash } = mods.state;
+  const { verdictIsStale, requirementSetHash } = mods.verdict;
+
+  let doc;
+  try {
+    doc = readSlidePreservation(deckDir);
+  } catch (err) {
+    return { blocker: err.message, note: null };
+  }
+  // The sidecar remembers a slide's identity after the file is gone; only what
+  // is still IN the deck can be replaced by this build, so only that is gated.
+  const fileOf = new Map(
+    Object.entries(mods.guids.loadSlideGuids(deckDir))
+      .filter(([jsxPath]) => fs.existsSync(path.join(deckDir, jsxPath)))
+      .map(([jsxPath, key]) => [key, jsxPath]),
+  );
+  const keys = Object.keys(doc.slides ?? {}).filter((slideKey) => fileOf.has(slideKey));
+  if (keys.length === 0) return { blocker: null, note: null };
+
+  // Is the recorded verdict about the bytes we are shipping?
+  const current = (slideKey) =>
+    !verdictIsStale(doc.slides[slideKey]?.verdict, {
+      sourceHash: sourceHash(deckDir, fileOf.get(slideKey)),
+      requirementSetHash: requirementSetHash(doc.slides[slideKey]),
+    });
+  const failedOf = (slideKey) =>
+    (doc.slides[slideKey]?.verdict?.checks ?? []).filter((c) => c.status === "failed" && c.elementId != null);
+
+  // `finalEvidenceBlockers` is the authority on EVIDENCE state, and it yields
+  // nothing for a `passed` entry. Freshness is a dimension it does not model,
+  // so every slide is walked — otherwise a verdict that passed once would keep
+  // certifying bytes it never saw.
+  const byKey = new Map(finalEvidenceBlockers(deckDir, keys).map((b) => [b.slideKey, b]));
+  const unproven = [];
+  const problems = [];
+  for (const slideKey of keys) {
+    const blocker = byKey.get(slideKey) ?? {
+      slideKey,
+      code: "evidence_passed",
+      reason: "preservation evidence is 'passed'",
+    };
+    // A record with a VIOLATED obligation refuses, always — that is E09.
+    if (blocker.code === "evidence_failed" || failedOf(blocker.slideKey).length > 0) {
+      problems.push(blocker);
+      continue;
+    }
+    // Anything else is "not proven", and there are two very different reasons.
+    // Nobody has checked THESE bytes: one command fixes that, so refuse and
+    // name it. Checking is what catches an edit made after the last draft.
+    if (!current(slideKey)) {
+      problems.push({
+        ...blocker,
+        code: "evidence_stale",
+        reason: "these exact bytes have not been checked (no verdict, or one bound to earlier source)",
+      });
+      continue;
+    }
+    if (!byKey.has(slideKey)) continue; // checked, current, and evidence passed
+    // Checked, nothing violated, and something still unproven. Which of two
+    // things that is decides whether it refuses.
+    //
+    // The package channel now exists (`src/pptx/package-evidence.mjs`), so a
+    // slide whose import and delivered bytes are both on disk CAN reach
+    // `passed` — and one that did not is a genuine failure to prove, which
+    // refuses. That is the guide's rung, restored.
+    //
+    // A slide with no import baseline has no package to be proved against at
+    // all; refusing it would block authored decks for evidence that cannot
+    // exist, which is the outage this compromise was opened to avoid. It ships
+    // with the limitation named, and is still never recorded as a pass.
+    if (packageEvidenceReachable(deckDir, path.basename(fileOf.get(slideKey)))) {
+      problems.push({
+        ...blocker,
+        code: "evidence_unproven",
+        reason:
+          "this slide can be proved against its imported and delivered packages, and this render did not prove it",
+      });
+      continue;
+    }
+    unproven.push(blocker);
+  }
+
+  // The note NAMES what went unproven, per slide and per element. A generic
+  // caveat would let a later reader mistake a shipped-with-note slide for a
+  // verified one, which is the only thing that would make this compromise
+  // unacceptable. The record still says `unknown`; nothing here writes a pass.
+  const WHY = {
+    relationships_not_resolved: "what it is bound to could not be resolved",
+    not_checked_in_render: "absent from this render's evidence",
+    not_checked_in_package: "no final-package evidence",
+    no_evidence_supplied: "no evidence at all",
+    scope_not_compared: "its protected properties were not compared",
+    no_identified_boxes: "the capture carried no element identities",
+  };
+  const note = unproven.length
+    ? `preservation: ${unproven.length} slide${unproven.length === 1 ? "" : "s"} shipped with obligations this build ` +
+      `could not prove — nothing was violated, nothing was certified either:\n` +
+      unproven
+        .map((b) => {
+          const owed = new Map();
+          for (const c of doc.slides[b.slideKey]?.verdict?.checks ?? []) {
+            if (c.status !== "unknown" && c.status !== "unsupported") continue;
+            const id = c.elementId ?? "(slide)";
+            if (!owed.has(id)) owed.set(id, new Set());
+            owed.get(id).add(WHY[c.reason] ?? c.reason ?? "unproven");
+          }
+          const items = [...owed].map(([id, why]) => `${id} (${[...why].join("; ")})`);
+          return `    ${fileOf.get(b.slideKey) ?? b.slideKey} — ${items.join(", ") || b.reason}`;
+        })
+        .join("\n")
+    : null;
+  if (problems.length === 0) return { blocker: null, note };
+
+  const slug = deckSlug(deckDir);
+  const detail = problems.map((p) => {
+    const file = fileOf.get(p.slideKey) ?? p.slideKey;
+    const failed = failedOf(p.slideKey).map((c) => c.elementId);
+    const owed = failed.length > 0 ? ` — unmet: ${[...new Set(failed)].join(", ")}` : "";
+    return `  ${file} — ${p.reason}${owed}`;
+  });
+  return { note, blocker: (
+    `${problems.length} slide${problems.length === 1 ? "" : "s"} cannot be replaced: ` +
+    `${problems.length === 1 ? "its" : "their"} preservation obligations are not established.\n${detail.join("\n")}\n` +
+    `Fix the [preserve:warn] lines and re-run \`slidemind view-draft ${slug}\` to re-establish the verdict. ` +
+    `An intentional removal is superseded explicitly: \`slidemind revision begin ${slug} --operation targeted-edit --slides <sel>\`.`
+  ) };
+}