slidemind 0.3.20 → 0.4.1

package/src/lib/presentation-context.mjs

@@ -0,0 +1,531 @@
+// `SLIDEMIND_CONTEXT_V1` — the portable context a .pptx carries about itself.
+//
+// A colleague opens a link on a machine that has never seen this deck. Nothing
+// local can tell them what it is, which design it was built on, which business
+// rules apply to it, or which external documents its content was approved
+// against. The presentation-level tag is the only thing that travels WITH the
+// file, so that is where those four facts live:
+//
+//   { v, deckId, documentInstance, brand, intent, extensions, operationId }
+//
+//   deckId            LOGICAL identity — survives a copy, and is REMINTED when a
+//                     copy becomes its own document (see the fork rule below).
+//   documentInstance  PHYSICAL identity — provider:tenant:driveId:itemId of the
+//                     item these bytes were published to. A cold open compares
+//                     it with the item the user's own link resolved to; a
+//                     mismatch means this is a copy, and a copy may not mutate
+//                     the original's context.
+//   brand             { presFP, etag } — which corporate design to materialize.
+//   intent            bounded, human-scale purpose for an ORDINARY deck.
+//   extensions        [{ id, protocolVersion, dataVersion, required, refs }] —
+//                     which installed extension owns this deck's business rules
+//                     and which exact artifacts its content was approved against.
+//   operationId       the publish that wrote these bytes, so an unknown outcome
+//                     can be resolved by reading the file back.
+//
+// Three rules this module enforces rather than documents:
+//
+//   1. **A ref is portable or it is not a ref.** Storage identity plus a content
+//      hash, never a local path and never a command. A deck that could name an
+//      executable would be a deck that could run one.
+//   2. **A mutable ref pins an exact version or it is not paired.** An eTag is a
+//      precondition value, not a content address — it says "unchanged since",
+//      never "this content". A mutable artifact without a retrievable versionId
+//      needs an immutable snapshot ref beside it.
+//   3. **Overflow is explicit.** The payload is capped; a deck that needs more
+//      context points at an immutable context ARTIFACT instead of being
+//      truncated into something that parses but means less than it says.
+
+import { createHash } from "node:crypto";
+
+import { readText } from "../pptx/zip.mjs";
+import { relsFor, relsPathFor, resolvePartPath, decodeXmlEntities, TAG_ELEMENT, tagAttr, tagElements } from "../pptx/ooxml.mjs";
+
+export const CONTEXT_VERSION = 1;
+export const TAG_CONTEXT_META = "SLIDEMIND_CONTEXT_V1";
+export const TAG_CONTEXT_CHUNK = "SLIDEMIND_CONTEXT_";
+
+// What actually rides in the tag values, so this is the number PowerPoint sees.
+// A deck past it publishes an immutable context artifact and points at it.
+export const CONTEXT_MAX_ENCODED_BYTES = 32 * 1024;
+
+// One tag value stays well under any host's attribute limit; the same size the
+// source-tag encoder uses, for the same reason.
+const CHUNK_BYTES = 12288;
+
+const TAGS_REL_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/tags";
+const TAGS_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.presentationml.tags+xml";
+const TAG_XML_NS =
+  'xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" ' +
+  'xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" ' +
+  'xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main"';
+
+const PRESENTATION_PART = "ppt/presentation.xml";
+const enc = (s) => new TextEncoder().encode(s);
+const sha256 = (data) =>
+  createHash("sha256")
+    .update(typeof data === "string" ? Buffer.from(data, "utf8") : Buffer.from(data))
+    .digest("hex");
+
+function xmlEsc(s) {
+  return String(s).replace(/[<>&"']/g, (c) =>
+    c === "<" ? "&lt;" : c === ">" ? "&gt;" : c === "&" ? "&amp;" : c === '"' ? "&quot;" : "&apos;",
+  );
+}
+
+// ---------------------------------------------------------------------------
+// portable refs
+// ---------------------------------------------------------------------------
+
+export const MUTABILITY = ["immutable", "mutable"];
+
+// Nothing outside this set may appear on a ref. The list is a WHITELIST rather
+// than a blacklist of dangerous keys on purpose: the next dangerous key is the
+// one nobody thought to ban.
+const REF_KEYS = new Set([
+  "artifactId",
+  "purpose",
+  "required",
+  "mutability",
+  "provider",
+  "tenant",
+  "host",
+  "driveId",
+  "itemId",
+  "versionId",
+  "sha256",
+  "bytes",
+  "contentType",
+  "snapshotOf",
+]);
+
+/**
+ * Why a ref cannot travel, or null.
+ *
+ * The three refusals that matter: a local path (it means nothing on the machine
+ * that opens the file), an executable/command key (a deck must never be able to
+ * say what to run), and a mutable ref with no exact version and no immutable
+ * snapshot beside it (it would pair the deck with "whatever that file says
+ * today", which is not what anyone approved).
+ */
+export function refProblem(ref, { snapshots = new Set() } = {}) {
+  if (!ref || typeof ref !== "object") return "a ref must be an object";
+  for (const key of Object.keys(ref)) {
+    if (!REF_KEYS.has(key)) return `\`${key}\` is not a portable ref field`;
+  }
+  for (const required of ["artifactId", "purpose", "mutability", "sha256"]) {
+    if (!ref[required]) return `a ref needs ${required}`;
+  }
+  if (!MUTABILITY.includes(ref.mutability)) {
+    return `mutability must be immutable or mutable (got ${ref.mutability})`;
+  }
+  if (!/^[0-9a-f]{64}$/.test(String(ref.sha256))) return "sha256 must be a hex digest";
+  for (const key of ["provider", "tenant", "host", "driveId", "itemId", "versionId"]) {
+    const value = ref[key];
+    if (value === undefined || value === null) continue;
+    if (typeof value !== "string") return `${key} must be a string`;
+    // A Windows drive letter, a POSIX absolute path, a relative walk, or a
+    // file: URL — every shape a local path arrives in.
+    if (/^[a-zA-Z]:[\\/]/.test(value) || value.startsWith("/") || value.startsWith("\\")) {
+      return `${key} looks like a local path; portable refs carry storage identity only`;
+    }
+    if (value.includes("..")) return `${key} must not contain a path traversal`;
+    if (/^file:/i.test(value)) return `${key} must not be a file: URL`;
+  }
+  if (ref.mutability === "mutable" && !ref.versionId && !snapshots.has(ref.artifactId)) {
+    return (
+      "a mutable ref must pin an exact versionId, or be paired with an immutable " +
+      "snapshot ref whose snapshotOf names it"
+    );
+  }
+  return null;
+}
+
+/** Validate a whole ref list together — snapshots are resolved across it. */
+export function validateRefs(refs) {
+  const list = Array.isArray(refs) ? refs : [];
+  const snapshots = new Set(
+    list.filter((r) => r?.mutability === "immutable" && r?.snapshotOf).map((r) => r.snapshotOf),
+  );
+  const errors = [];
+  const seen = new Set();
+  for (const ref of list) {
+    const why = refProblem(ref, { snapshots });
+    if (why) errors.push(`${ref?.artifactId ?? "(unnamed)"}: ${why}`);
+    if (ref?.artifactId) {
+      if (seen.has(ref.artifactId)) errors.push(`${ref.artifactId}: declared twice`);
+      seen.add(ref.artifactId);
+    }
+  }
+  return errors;
+}
+
+// ---------------------------------------------------------------------------
+// the context record
+// ---------------------------------------------------------------------------
+
+// Ordinary-deck intent is BOUNDED: it is a handful of human sentences about who
+// the deck is for and what it has to do, not a place to park a plan. The caps
+// are what keep the tag inside its budget without truncating anything silently —
+// over the cap is an error the caller resolves, never a quiet trim.
+const INTENT_FIELDS = {
+  audience: { max: 400 },
+  objective: { max: 400 },
+  constraints: { max: 1200, list: true },
+  decisions: { max: 1200, list: true },
+  roles: { max: 400, list: true },
+};
+
+export function intentProblems(intent) {
+  if (intent === null || intent === undefined) return [];
+  if (typeof intent !== "object" || Array.isArray(intent)) return ["intent must be an object"];
+  const errors = [];
+  for (const [key, value] of Object.entries(intent)) {
+    const spec = INTENT_FIELDS[key];
+    if (!spec) {
+      errors.push(`\`${key}\` is not a bounded intent field (${Object.keys(INTENT_FIELDS).join(", ")})`);
+      continue;
+    }
+    const text = spec.list
+      ? (Array.isArray(value) ? value : [value]).join("\n")
+      : String(value ?? "");
+    if (spec.list && !Array.isArray(value)) errors.push(`${key} must be an array`);
+    if (Buffer.byteLength(text, "utf8") > spec.max) {
+      errors.push(`${key} is longer than ${spec.max} bytes — put it in a context artifact instead`);
+    }
+  }
+  return errors;
+}
+
+/**
+ * Check a whole context record. Returns the list of problems; empty means it may
+ * be encoded. Nothing here mutates or trims — a context that does not fit is a
+ * decision for the caller (publish an overflow artifact), not a silent edit.
+ */
+export function contextProblems(context) {
+  const errors = [];
+  if (!context || typeof context !== "object") return ["context must be an object"];
+  if (context.v !== CONTEXT_VERSION) errors.push(`v must be ${CONTEXT_VERSION}`);
+  if (!context.deckId) errors.push("deckId is required");
+  errors.push(...intentProblems(context.intent));
+  for (const ext of context.extensions ?? []) {
+    if (!ext?.id) {
+      errors.push("an extension declaration needs an id");
+      continue;
+    }
+    if (ext.protocolVersion !== 1) {
+      errors.push(`${ext.id}: protocolVersion must be 1 in this schema`);
+    }
+    if (ext.command || ext.exec || ext.path) {
+      // The one rule a deck must never be able to bend: metadata SELECTS an
+      // installed extension by id, it never supplies what to run.
+      errors.push(`${ext.id}: a context may name an extension, never a command to run`);
+    }
+    errors.push(...validateRefs(ext.refs).map((e) => `${ext.id}: ${e}`));
+  }
+  if (context.overflowRef) {
+    errors.push(...validateRefs([context.overflowRef]).map((e) => `overflowRef: ${e}`));
+  }
+  return errors;
+}
+
+/** The canonical JSON a digest is taken over — key order must not change a digest. */
+export function canonicalContext(context) {
+  const sortKeys = (value) => {
+    if (Array.isArray(value)) return value.map(sortKeys);
+    if (value && typeof value === "object") {
+      return Object.fromEntries(
+        Object.keys(value)
+          .sort()
+          .map((k) => [k, sortKeys(value[k])]),
+      );
+    }
+    return value;
+  };
+  return JSON.stringify(sortKeys(context));
+}
+
+/** The digest an extension's evidence binds to. */
+export function contextDigest(context) {
+  return sha256(canonicalContext(context));
+}
+
+/**
+ * Encode a context into its tag map, or throw with the reason.
+ *
+ * `context_too_large` is thrown rather than truncated: the caller's answer is an
+ * immutable context artifact plus an `overflowRef`, and a half-written intent
+ * that still parses is exactly the silent loss this whole change exists to stop.
+ */
+export function encodeContextTags(context) {
+  const problems = contextProblems(context);
+  if (problems.length) {
+    const e = new Error(`this presentation context cannot be written:\n  ${problems.join("\n  ")}`);
+    e.code = "context_invalid";
+    e.problems = problems;
+    throw e;
+  }
+  const json = canonicalContext(context);
+  const payload = Buffer.from(json, "utf8").toString("base64");
+  if (Buffer.byteLength(payload, "utf8") > CONTEXT_MAX_ENCODED_BYTES) {
+    const e = new Error(
+      `this presentation context encodes to ${Buffer.byteLength(payload, "utf8")} bytes, over the ` +
+        `${CONTEXT_MAX_ENCODED_BYTES}-byte tag budget. Publish the detail as an immutable context ` +
+        `artifact and point at it with overflowRef.`,
+    );
+    e.code = "context_too_large";
+    e.encodedBytes = Buffer.byteLength(payload, "utf8");
+    throw e;
+  }
+  const chunks = [];
+  for (let i = 0; i < payload.length; i += CHUNK_BYTES) {
+    chunks.push(payload.slice(i, i + CHUNK_BYTES));
+  }
+  const tags = {
+    [TAG_CONTEXT_META]: JSON.stringify({
+      v: CONTEXT_VERSION,
+      chunks: chunks.length,
+      sha256: sha256(json),
+      bytes: Buffer.byteLength(json, "utf8"),
+    }),
+  };
+  chunks.forEach((c, i) => {
+    tags[`${TAG_CONTEXT_CHUNK}${i}`] = c;
+  });
+  return tags;
+}
+
+/**
+ * Decode a context out of a tag map.
+ *
+ * Returns `{ context, digest }`, or null when there is no context at all, or
+ * `{ corrupt: <why> }` when there is one and it does not hold together. The
+ * three answers are deliberately distinct: "no context" is a normal ordinary
+ * deck, "corrupt context" is a deck whose business gates cannot be assumed gone.
+ */
+export function decodeContextTags(tags) {
+  const raw = tags?.[TAG_CONTEXT_META];
+  if (!raw) return null;
+  let meta;
+  try {
+    meta = JSON.parse(raw);
+  } catch {
+    return { corrupt: "the context header is not readable JSON" };
+  }
+  if (meta?.v !== CONTEXT_VERSION) {
+    return { corrupt: `context schema v${meta?.v} is not readable by this CLI (expected v${CONTEXT_VERSION})` };
+  }
+  const parts = [];
+  for (let i = 0; i < Number(meta.chunks ?? 0); i++) {
+    const part = tags[`${TAG_CONTEXT_CHUNK}${i}`];
+    if (part === undefined) return { corrupt: `context chunk ${i} is missing` };
+    parts.push(part);
+  }
+  let json;
+  try {
+    json = Buffer.from(parts.join(""), "base64").toString("utf8");
+  } catch {
+    return { corrupt: "the context payload is not decodable" };
+  }
+  if (sha256(json) !== meta.sha256) {
+    return { corrupt: "the context payload does not match its recorded digest" };
+  }
+  let context;
+  try {
+    context = JSON.parse(json);
+  } catch {
+    return { corrupt: "the context payload is not readable JSON" };
+  }
+  const problems = contextProblems(context);
+  if (problems.length) return { corrupt: problems.join("; "), context };
+  return { context, digest: sha256(json) };
+}
+
+// ---------------------------------------------------------------------------
+// package side
+// ---------------------------------------------------------------------------
+
+/** Every tag reachable from `ppt/presentation.xml`'s own custDataLst. */
+export function readPresentationTags(files) {
+  const xml = readText(files, PRESENTATION_PART);
+  if (!xml) return {};
+  const tagRels = {};
+  for (const rel of relsFor(files, PRESENTATION_PART)) {
+    if (rel.id && rel.type === TAGS_REL_TYPE) {
+      tagRels[rel.id] = resolvePartPath("ppt", rel.target);
+    }
+  }
+  const out = {};
+  for (const cust of xml.matchAll(/<p:custDataLst\b[\s\S]*?<\/p:custDataLst>/g)) {
+    for (const ref of cust[0].matchAll(/<p:tags\b[^>]*\br:id="([^"]+)"/g)) {
+      const partPath = tagRels[ref[1]];
+      const tagXml = partPath ? readText(files, partPath) : null;
+      if (!tagXml) continue;
+      for (const t of tagElements(tagXml)) {
+        const name = tagAttr(t[1], "name");
+        const val = tagAttr(t[1], "val");
+        if (name) out[decodeXmlEntities(name)] = decodeXmlEntities(val ?? "");
+      }
+    }
+  }
+  return out;
+}
+
+/** The context a package carries, in the three-answer shape of {@link decodeContextTags}. */
+export function readPresentationContext(files) {
+  return decodeContextTags(readPresentationTags(files));
+}
+
+function nextTagIndex(files) {
+  let max = 0;
+  for (const name of Object.keys(files)) {
+    const m = name.match(/^ppt\/tags\/tag(\d+)\.xml$/);
+    if (m) max = Math.max(max, Number(m[1]));
+  }
+  return max + 1;
+}
+
+function nextRid(relsXml) {
+  let max = 0;
+  for (const m of relsXml.matchAll(/\bId="rId(\d+)"/g)) max = Math.max(max, Number(m[1]));
+  return max + 1;
+}
+
+// Drop the tag part this module previously wrote, with its relationship, its
+// content-type override and its custDataLst reference. Republishing without
+// this would stack a second context on every save, and the reader would join
+// two headers into one unreadable payload.
+function removeExistingContext(files) {
+  const xml = readText(files, PRESENTATION_PART);
+  if (!xml) return { xml: null, changed: false };
+  const relsPath = relsPathFor(PRESENTATION_PART);
+  let relsXml = readText(files, relsPath);
+  if (!relsXml) return { xml, changed: false };
+  let nextXml = xml;
+  let changed = false;
+  for (const rel of relsFor(files, PRESENTATION_PART)) {
+    if (rel.type !== TAGS_REL_TYPE || !rel.id) continue;
+    const partPath = resolvePartPath("ppt", rel.target);
+    const tagXml = readText(files, partPath);
+    if (!tagXml || ![...tagElements(tagXml)].some((t) => tagAttr(t[1], "name") === TAG_CONTEXT_META)) continue;
+    // A part that also holds another add-in's tags is shared: strip only ours
+    // and keep the part, its relationship and its reference in place.
+    const withoutOurs = tagXml.replace(new RegExp(TAG_ELEMENT, "g"), (tag) => (/\bname=["']SLIDEMIND_CONTEXT/.test(tag) ? "" : tag));
+    if (/<p:tag\b/.test(withoutOurs)) {
+      files[partPath] = enc(withoutOurs);
+      changed = true;
+      continue;
+    }
+    delete files[partPath];
+    relsXml = relsXml.replace(
+      new RegExp(`<Relationship\\b[^>]*\\bId="${rel.id}"[^>]*/>`, "g"),
+      "",
+    );
+    nextXml = nextXml.replace(
+      new RegExp(`<p:tags\\b[^>]*\\br:id="${rel.id}"\\s*/>`, "g"),
+      "",
+    );
+    const ct = readText(files, "[Content_Types].xml");
+    if (ct) {
+      files["[Content_Types].xml"] = enc(
+        ct.replace(new RegExp(`<Override\\b[^>]*PartName="/${partPath}"[^>]*/>`, "g"), ""),
+      );
+    }
+    changed = true;
+  }
+  if (changed) {
+    // An emptied list is removed rather than left behind: PowerPoint accepts an
+    // empty p:custDataLst, but leaving one on every save is litter nobody reads.
+    nextXml = nextXml.replace(/<p:custDataLst>\s*<\/p:custDataLst>/g, "");
+    files[relsPath] = enc(relsXml);
+  }
+  return { xml: nextXml, changed };
+}
+
+// CT_Presentation fixes the child order, and PowerPoint repairs a file that
+// breaks it. custDataLst sits after photoAlbum and before kinsoku — so the
+// insertion point is the first of the four elements that may follow it.
+const AFTER_CUST_DATA = ["p:kinsoku", "p:defaultTextStyle", "p:modifyVerifier", "p:extLst"];
+
+/**
+ * Write a context into a package IN PLACE, replacing any context this module
+ * wrote before. Additive to everything else: another add-in's presentation tags,
+ * the slide-level source tags and every other part are untouched.
+ */
+export function bakePresentationContext(files, context) {
+  const tags = encodeContextTags(context);
+  const { xml: stripped } = removeExistingContext(files);
+  const xml = stripped ?? readText(files, PRESENTATION_PART);
+  if (!xml) return false;
+
+  // CT_CustomerDataList allows ONE p:tags. A presentation that already carries
+  // one (a pack's master may bring think-cell's) gets our tags merged into
+  // that part; a second p:tags element is a PowerPoint repair prompt
+  // (observed 2026-09-17: PowerPoint kept the other add-in's and dropped ours).
+  const shared = xml.match(/<p:custDataLst\b[^>]*>[\s\S]*?<p:tags\b[^>]*\br:id="([^"]+)"/);
+  if (shared) {
+    const rel = relsFor(files, PRESENTATION_PART).find((r) => r.id === shared[1] && r.type === TAGS_REL_TYPE);
+    const partPath = rel ? resolvePartPath("ppt", rel.target) : null;
+    const tagXml = partPath ? readText(files, partPath) : null;
+    if (tagXml && tagXml.includes("</p:tagLst>")) {
+      const ours = Object.entries(tags)
+        .map(([name, val]) => `<p:tag name="${xmlEsc(name)}" val="${xmlEsc(val)}"/>`)
+        .join("");
+      files[partPath] = enc(tagXml.replace("</p:tagLst>", `${ours}</p:tagLst>`));
+      files[PRESENTATION_PART] = enc(xml);
+      return true;
+    }
+  }
+
+  const tagIndex = nextTagIndex(files);
+  const partName = `ppt/tags/tag${tagIndex}.xml`;
+  files[partName] = enc(
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\r\n<p:tagLst ${TAG_XML_NS}>` +
+      Object.entries(tags)
+        .map(([name, val]) => `<p:tag name="${xmlEsc(name)}" val="${xmlEsc(val)}"/>`)
+        .join("") +
+      `</p:tagLst>`,
+  );
+
+  const contentTypes = readText(files, "[Content_Types].xml") ?? "";
+  if (contentTypes && !contentTypes.includes(`PartName="/${partName}"`)) {
+    files["[Content_Types].xml"] = enc(
+      contentTypes.replace(
+        "</Types>",
+        `<Override PartName="/${partName}" ContentType="${TAGS_CONTENT_TYPE}"/></Types>`,
+      ),
+    );
+  }
+
+  const relsPath = relsPathFor(PRESENTATION_PART);
+  const relsXml =
+    readText(files, relsPath) ??
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\r\n<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"></Relationships>`;
+  const rId = `rId${nextRid(relsXml)}`;
+  files[relsPath] = enc(
+    relsXml.replace(
+      "</Relationships>",
+      `<Relationship Id="${rId}" Type="${TAGS_REL_TYPE}" Target="tags/tag${tagIndex}.xml"/></Relationships>`,
+    ),
+  );
+
+  const existing = xml.match(/<p:custDataLst\b[^>]*?(\/?)>/);
+  let nextXml;
+  if (existing && existing[1] === "/") {
+    nextXml = xml.replace(
+      existing[0],
+      `${existing[0].replace(/\/>$/, ">")}<p:tags r:id="${rId}"/></p:custDataLst>`,
+    );
+  } else if (existing) {
+    nextXml = xml.replace(existing[0], `${existing[0]}<p:tags r:id="${rId}"/>`);
+  } else {
+    const block = `<p:custDataLst><p:tags r:id="${rId}"/></p:custDataLst>`;
+    const anchor = AFTER_CUST_DATA.map((tag) => xml.indexOf(`<${tag}`)).filter((i) => i >= 0);
+    const at = anchor.length ? Math.min(...anchor) : xml.lastIndexOf("</p:presentation>");
+    nextXml = at >= 0 ? xml.slice(0, at) + block + xml.slice(at) : xml;
+  }
+  files[PRESENTATION_PART] = enc(nextXml);
+  return true;
+}

package/src/lib/preservation-tags.mjs

@@ -0,0 +1,157 @@
+// Preservation provenance through the deck-embedded source tags — what a slide
+// must still contain, baked into the .pptx it was rendered into and read back
+// out when that file is adopted again (openspec `safeguard-slide-editing`,
+// task 5.7 / E19–E20).
+//
+// Why it rides the slide's own tags rather than only `state/`: the .pptx is the
+// only thing that travels. A rendered deck is mailed, opened, saved and handed
+// back, and `slidemind adopt` rebuilds a workspace from it alone. The slide's
+// jsx, assets, identity, drift baseline and image obligations all survive that
+// round trip already (src/lib/image-intent-tags.mjs is the same shape, one
+// contract over). An obligation that did not would come back as a slide nobody
+// could prove had kept its connector, its native object or its chart.
+//
+// Two halves, both narrow:
+//
+//   BAKE    `preservationTagMeta` returns the slide's entry out of
+//           `state/slide-preservation.json`, keyed by the slide's own GUID.
+//   RESTORE `restorePreservationFromTags` puts entries back for the slides
+//           adopt restored from their own proved-current source.
+//
+// Four rules the restore exists to keep — the deletion ones are the subtle
+// half, and they run in both directions:
+//
+//   * **A file with no `preservation` carries no obligations.** A plain
+//     imported .pptx, or one rendered before this contract, is legacy and stays
+//     legacy; `migrateEditState` seeds it from CURRENT evidence instead. An
+//     obligation is never manufactured from a shape that happens to be there.
+//   * **Only a slide restored from its own proved-current source restores.**
+//     A slide that had to be re-converted is rebuilt content — adopt itself
+//     judged the embedded payload stale (`sourceMatchesSlide`) — so the element
+//     the record names may be the one the user just deleted in PowerPoint.
+//     A stale-but-valid payload never wins over current truth, here as
+//     everywhere else in adoption.
+//   * **An entry already on disk is never overwritten.** The workspace's record
+//     is the current statement of what is owed; the file's is history. That is
+//     what stops an OLDER .pptx from resurrecting a requirement this deck
+//     superseded — and what makes the restore idempotent, so a resumed or
+//     repeated adopt re-seeds nothing.
+//   * **`superseded` travels with `active`.** An intentional deletion is part
+//     of the record, so a deck re-adopted into a FRESH workspace comes back
+//     with the obligation still ended rather than silently owed again.
+//
+// Evidence is deliberately NOT carried across: a re-adoption is a new base, and
+// a workspace that has verified nothing must say `unknown` rather than inherit
+// someone else's `passed` (guide §5 — missing evidence is distinct from a
+// passed check, and any intervening change invalidates a verdict).
+
+import {
+  SLIDE_PRESERVATION_VERSION,
+  validateSlidePreservation,
+} from "./slide-preservation.mjs";
+import { readSlidePreservation, writeSlidePreservation } from "./edit-state.mjs";
+
+export const PRESERVATION_META_KEY = "preservation";
+
+// ponytail: a flat size cap, not a chunked channel. SRC_META is one tag value
+// and already carries the asset list; the source and the drift baseline get
+// their own chunk streams (CHUNK_BYTES = 12288) precisely because they can be
+// large. An entry is a few hundred bytes per requirement, so this only bites on
+// a slide with ~50 of them — and the upgrade path is the same chunking the
+// baseline uses (TAG_BASELINE_CHUNK), not a bigger number here.
+const META_BUDGET = 8192;
+
+/**
+ * The deck's preservation document for a whole bake, or null when it cannot be
+ * read. Read once and handed to {@link preservationTagMeta} per slide: the bake
+ * already avoids re-reading per-slide state, and an unreadable or future-schema
+ * record must not be the thing that fails a render — the commands that actually
+ * need it refuse on their own.
+ */
+export function preservationDocForBake(deckDir) {
+  try {
+    return readSlidePreservation(deckDir);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The `SRC_META.preservation` payload for one slide, or null when the slide has
+ * no record — which keeps its tags byte-identical to what they were before this
+ * contract existed.
+ *
+ * @param {string} deckDir   the deck workspace
+ * @param {string} slideKey  the slide's durable identity (its GUID)
+ * @param {{ preservation?: object }} [opts] a pre-read document, so a whole-deck
+ *   bake reads `state/slide-preservation.json` once instead of once per slide
+ */
+export function preservationTagMeta(deckDir, slideKey, { preservation = null } = {}) {
+  if (!slideKey) return null;
+  const doc = preservation ?? preservationDocForBake(deckDir);
+  const entry = doc?.slides?.[slideKey];
+  if (!entry) return null;
+  if (JSON.stringify(entry).length > META_BUDGET) return null;
+  return entry;
+}
+
+/**
+ * Restore the obligations a set of adopted slides carried.
+ *
+ * @param {string} deckDir the deck being adopted into
+ * @param {Array<{slideKey: string|null, entry: object|null}>} entries one per
+ *   slide adopted from its own proved-current source. `slideKey` is the GUID
+ *   this adoption assigned, which is NOT the embedded one when the slide turned
+ *   out to be a duplicate — the record follows the identity the slide has here.
+ * @returns {{slides: number, notes: string[]}}
+ */
+export function restorePreservationFromTags(deckDir, entries) {
+  const notes = [];
+  const wanted = (entries ?? []).filter((e) => e?.entry && e.slideKey);
+  if (!wanted.length) return { slides: 0, notes };
+
+  let previous;
+  try {
+    previous = readSlidePreservation(deckDir);
+  } catch (err) {
+    notes.push(`recorded obligations were not restored: ${err?.message ?? err}`);
+    return { slides: 0, notes };
+  }
+
+  const slides = { ...previous.slides };
+  let restored = 0;
+  for (const { slideKey, entry } of wanted) {
+    if (slides[slideKey]) continue; // never overwrite a live record with history
+    if (entry.version !== SLIDE_PRESERVATION_VERSION) {
+      notes.push(
+        `a slide records preservation version ${JSON.stringify(entry.version ?? null)} — ` +
+          `this CLI reads version ${SLIDE_PRESERVATION_VERSION}; its obligations were not restored`,
+      );
+      continue;
+    }
+    // Bound to the identity this deck gave the slide, and to no verdict: the
+    // requirements come back, the claim that they were met does not.
+    const rebound = { ...entry, slideKey, evidence: "unknown" };
+    // The payload came out of an untrusted file — shape-check before it becomes
+    // this deck's statement of what is owed.
+    const { ok, errors } = validateSlidePreservation(rebound, { slideKey });
+    if (!ok) {
+      notes.push(
+        `slide ${slideKey}: its recorded obligations are not a valid preservation record ` +
+          `(${errors[0]?.path}: ${errors[0]?.message}) — they were not restored`,
+      );
+      continue;
+    }
+    slides[slideKey] = rebound;
+    restored += 1;
+  }
+  if (restored === 0) return { slides: 0, notes };
+
+  try {
+    writeSlidePreservation(deckDir, { version: SLIDE_PRESERVATION_VERSION, slides });
+  } catch (err) {
+    notes.push(`recorded obligations were not restored: ${err?.message ?? err}`);
+    return { slides: 0, notes };
+  }
+  return { slides: restored, notes };
+}