slidemind 0.3.20 → 0.4.0

package/src/lib/preservation-verdict.mjs

@@ -0,0 +1,1342 @@
+// Did the slide keep its promises? — the two comparisons behind the verdict.
+//
+// Contract from `openspec/changes/safeguard-slide-editing/implementation-guide.md`
+// section 5 ("Preservation and render verification"), task 5.3. Mirrored
+// byte-for-byte into the add-in (`scripts/sync-transcription-runtime.mjs`,
+// group `edit-contracts`), because a preservation check that runs in only one
+// client is not a safeguard — it is a local opinion.
+//
+// Two complementary comparisons, exactly as the guide asks:
+//
+//   1. compareSlideSource()      — source/IR. What the edit INTENDED: which
+//                                  elements were added, removed or had a
+//                                  property changed, plus every construct the
+//                                  reader could not statically resolve. This is
+//                                  the half that can prove a property was NOT
+//                                  touched, where text layout has normal
+//                                  rendering variability.
+//   2. compareRenderEvidence()   — rendered IR. Did the object actually SURVIVE
+//      comparePackageEvidence()    rendering and splicing? "Visible nonzero
+//                                  bounds and endpoints matter; an element in
+//                                  source but absent in output is not success."
+//
+// Three rules the shape of this module exists to keep:
+//
+//   • **Three outcomes, never two.** Every check answers `passed`, `failed`,
+//     `unknown` or `unsupported` (`EVIDENCE_STATUSES`). Missing evidence is
+//     `unknown` and rolls the verdict up to `unknown`; it never reads as a pass.
+//     An element the render says nothing about is not an element that survived.
+//   • **No ZIP byte streams.** Package timestamps, relationship ids and part
+//     ordering legitimately change on every save. What is compared here is the
+//     NORMALIZED projection of a slide (`computeProjection`, src/pptx/tags.mjs)
+//     and the RESOLVED targets of its relationships — never bytes of the
+//     container. Native binary payloads are the exception that proves it: their
+//     digests must hold, because nothing but the user editing that object in
+//     PowerPoint may change them.
+//   • **The verdict carries its binding context.** sourceHash, liveRevision,
+//     operationId and requirementSetHash travel with it, so a later phase can
+//     say "this verdict was about a slide that no longer exists" instead of
+//     trusting it (`verdictIsStale`).
+//
+// Everything here is pure: no disk, no network, no mutation of an argument and
+// no throw. The caller computes the projections (the CLI through
+// `src/pptx/tags.mjs`, the add-in through its own reader) and hands them in —
+// that dependency injection is what lets one comparison serve both clients
+// without this file importing either client's package machinery.
+
+import { createHash } from "node:crypto";
+
+import { PROPERTY_SCOPES } from "./edit-operations.mjs";
+import { EVIDENCE_STATUSES } from "./slide-preservation.mjs";
+import { isDurableId } from "./durable-ids.mjs";
+import { inlineComponents } from "./inline-components.mjs";
+
+/** Schema version of the verdict this module returns. */
+export const PRESERVATION_VERDICT_VERSION = 1;
+
+// ---------------------------------------------------------------------------
+// Numeric tolerances
+// ---------------------------------------------------------------------------
+//
+// Named, exported and justified — a magic number inline is a tolerance nobody
+// can argue with later. The guide's rule: reuse the renderer's own units and
+// rounding where they exist, and otherwise allow at most one OOXML EMU of
+// quantization for an exact transform.
+
+/**
+ * The quantization the structural projection ALREADY applies to every EMU
+ * coordinate (`roundEmu` in src/pptx/tags.mjs and its TypeScript twin:
+ * `Math.round(n / 100) * 100`). It is the renderer's own rounding, so it is
+ * reused rather than re-derived — which is why the tolerance ON TOP of it is
+ * zero. Worst-case error of the pair is therefore one quantum, 100 EMU
+ * ≈ 0.0079 pt ≈ 1/9600 inch: far below anything a PowerPoint user can nudge.
+ */
+export const PROJECTION_QUANTUM_EMU = 100;
+
+/**
+ * Slack allowed on an already-quantized EMU coordinate: none. Two renders of an
+ * untouched transform land in the same 100-EMU bucket, so any difference at all
+ * is a real move — and accepting "one bucket either way" would silently permit
+ * a 200 EMU drift per pass, which accumulates across the repair budget's three
+ * passes.
+ */
+export const TRANSFORM_TOLERANCE_EMU = 0;
+
+/**
+ * Slack on a RENDERED rect, in slot px. Both clients measure with the same
+ * pinned Chrome (AGENTS.md: identical Chromium ⇒ identical text measurement),
+ * so this absorbs `getBoundingClientRect`'s double-precision noise, not layout
+ * differences. Half a CSS px is under one device pixel at 1x — smaller than
+ * anything that can paint differently.
+ */
+export const RENDER_GEOMETRY_TOLERANCE_PX = 0.5;
+
+/**
+ * The smallest rendered extent that can still paint, in slot px. Below it the
+ * element is hidden however present it is in the source. Chosen at half a CSS
+ * px for the same reason as above: a genuine hairline rule (1px) stays above
+ * it, a collapsed box (0px) does not.
+ */
+export const RENDER_MIN_VISIBLE_PX = 0.5;
+
+/**
+ * The smallest opacity that still reads as visible. 1% is below the JPEG-noise
+ * floor of any capture; a value beneath it is an element that was hidden, not
+ * an element that was faint.
+ */
+export const RENDER_MIN_VISIBLE_OPACITY = 0.01;
+
+/**
+ * How far past the canvas edge a rect may sit before it counts as off-canvas,
+ * in slot px. One px: a shape flush with the edge rounds outwards, a shape
+ * parked outside the slide does not.
+ */
+export const OFF_CANVAS_SLACK_PX = 1;
+
+// ---------------------------------------------------------------------------
+// Small shared helpers
+// ---------------------------------------------------------------------------
+
+const isPlainObject = (v) => Boolean(v) && typeof v === "object" && !Array.isArray(v);
+const isNonEmptyString = (v) => typeof v === "string" && v.trim().length > 0;
+const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : null);
+
+/** Stable JSON: object keys sorted at every depth, so a hash is order-free. */
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (isPlainObject(value)) {
+    return `{${Object.keys(value)
+      .sort()
+      .map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value ?? null);
+}
+
+const sha256 = (s) => createHash("sha256").update(s).digest("hex");
+
+// ---------------------------------------------------------------------------
+// 1. Source / IR comparison
+// ---------------------------------------------------------------------------
+//
+// A very small JSX reader. Both dialects the product writes are regular:
+// transcribed helpers (`<B id="…" x={44} …>`) and the converted dialect
+// (`<div data-sm-source-id={10} style={{…}}>`). This reads the tag tree, buckets
+// each element's attributes into the SAME property scopes the operation and
+// preservation records speak (`PROPERTY_SCOPES`), and refuses to guess about
+// anything it cannot resolve statically.
+//
+// ponytail: this scanner is a near-twin of the unexported one in
+// src/lib/lint-converted.mjs. It is copied rather than imported because this
+// module is byte-mirrored into the add-in and may only import its own group;
+// lift lint-converted's reader onto this file once that module is free to
+// depend on a mirrored one.
+
+/**
+ * Where the string, template literal or comment opening at `i` ends (the index
+ * of its last character), or `i` itself when none opens there. Comments and
+ * template literals exist only inside an expression (`inExpr`, i.e. within
+ * `{…}`); at depth 0 a quote is an attribute string.
+ *
+ * A quote that never closes is not a string — a valid file has none — so it is
+ * a stray one the reader failed to see past (an apostrophe in a construct this
+ * reader does not model) and reads as one character. Read as a string instead,
+ * it swallows the rest of the file and every later element reads as removed.
+ */
+function literalEnd(src, i, inExpr) {
+  const c = src[i];
+  if (inExpr && c === "/" && src[i + 1] === "/") {
+    const nl = src.indexOf("\n", i);
+    return nl < 0 ? src.length - 1 : nl;
+  }
+  if (inExpr && c === "/" && src[i + 1] === "*") {
+    const close = src.indexOf("*/", i + 2);
+    return close < 0 ? i : close + 1;
+  }
+  if (c === '"' || c === "'" || (inExpr && c === "`")) {
+    for (let k = i + 1; k < src.length; k++) {
+      if (inExpr && src[k] === "\\") k++;
+      else if (src[k] === c) return k;
+    }
+  }
+  return i;
+}
+
+function* scanTags(src) {
+  for (let i = 0; i < src.length; i++) {
+    if (src[i] !== "<") continue;
+    const head = /^<(\/?)([A-Za-z][\w.:-]*)/.exec(src.slice(i, i + 64));
+    if (!head) continue;
+    let j = i + head[0].length;
+    let depth = 0;
+    for (; j < src.length; j++) {
+      const c = src[j];
+      const end = literalEnd(src, j, depth > 0);
+      if (end !== j) {
+        j = end;
+        continue;
+      }
+      if (c === "{") depth++;
+      else if (c === "}") depth--;
+      else if (c === ">" && depth === 0) break;
+    }
+    const raw = src.slice(i, j + 1);
+    yield { close: head[1] === "/", name: head[2], raw, selfClose: raw.endsWith("/>"), start: i, end: j + 1 };
+    i = j;
+  }
+}
+
+/** Tag tree. Each node keeps its open tag, its content span and its children. */
+function parseJsx(src) {
+  const root = { name: "#root", raw: "", start: 0, contentStart: 0, contentEnd: src.length, end: src.length, children: [] };
+  const stack = [root];
+  for (const t of scanTags(src)) {
+    if (t.close) {
+      if (stack.length > 1) {
+        const node = stack.pop();
+        node.contentEnd = t.start;
+        node.end = t.end;
+      }
+      continue;
+    }
+    const node = {
+      name: t.name,
+      raw: t.raw,
+      start: t.start,
+      contentStart: t.end,
+      contentEnd: t.end,
+      end: t.end,
+      children: [],
+    };
+    stack[stack.length - 1].children.push(node);
+    if (!t.selfClose) stack.push(node);
+  }
+  // An unclosed tag runs to the end of the file; the reader reports it rather
+  // than silently re-parenting what follows.
+  while (stack.length > 1) {
+    const node = stack.pop();
+    node.contentEnd = src.length;
+    node.end = src.length;
+    node.unclosed = true;
+  }
+  return root;
+}
+
+/**
+ * Attributes of one open tag: `{ name: "quoted string" | { expr } | true }`.
+ * Brace values are read depth-aware, so `style={{ a: "b" }}` is one value.
+ */
+function attrsOf(raw) {
+  const out = {};
+  const body = raw.replace(/^<[A-Za-z][\w.:-]*/, "").replace(/\/?>$/, "");
+  let i = 0;
+  while (i < body.length) {
+    while (i < body.length && /\s/.test(body[i])) i++;
+    const name = /^[A-Za-z_][\w:.-]*/.exec(body.slice(i))?.[0];
+    if (!name) {
+      i += 1;
+      continue;
+    }
+    i += name.length;
+    let j = i;
+    while (j < body.length && /\s/.test(body[j])) j++;
+    if (body[j] !== "=") {
+      out[name] = true; // valueless flag: `nowrap`, `data-connector`
+      i = j;
+      continue;
+    }
+    j += 1;
+    while (j < body.length && /\s/.test(body[j])) j++;
+    const opener = body[j];
+    if (opener === '"' || opener === "'") {
+      const end = body.indexOf(opener, j + 1);
+      out[name] = end < 0 ? body.slice(j + 1) : body.slice(j + 1, end);
+      i = end < 0 ? body.length : end + 1;
+    } else if (opener === "{") {
+      let depth = 0;
+      let k = j;
+      for (; k < body.length; k++) {
+        const c = body[k];
+        const end = literalEnd(body, k, depth > 0);
+        if (end !== k) {
+          k = end;
+          continue;
+        }
+        if (c === "{") depth += 1;
+        else if (c === "}") {
+          depth -= 1;
+          if (depth === 0) break;
+        }
+      }
+      out[name] = { expr: body.slice(j + 1, k).trim() };
+      i = k + 1;
+    } else {
+      i = j; // `name=` with nothing after it — malformed, skipped
+    }
+  }
+  return out;
+}
+
+/**
+ * An expression this reader will not pretend to understand: a call, a template
+ * literal, a spread, an arrow, a ternary or a boolean operator. The add-in's
+ * own gate says the same thing about computed style values — unreadable is a
+ * reported state, not an error and not a pass.
+ */
+const UNREADABLE_EXPR = /[(`]|\.\.\.|=>|\?|&&|\|\|/;
+
+/**
+ * String literals (a template literal without `${` is one) and comments. They
+ * are stripped BEFORE `UNREADABLE_EXPR` is tested: a `(` inside
+ * `"var(--x)"` or `"polygon(…)"` is part of a value, not a call.
+ */
+const LITERAL_OR_COMMENT =
+  /"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`(?:[^`\\$]|\\.|\$(?!\{))*`|\/\/[^\n]*|\/\*[\s\S]*?\*\//g;
+
+/** Words that ARE their own value, as opposed to naming one somewhere else. */
+const LITERAL_WORDS = new Set(["true", "false", "null", "undefined"]);
+
+/**
+ * An expression is readable when every word in it is a literal or an object
+ * key. A bare identifier (`x={col * 96}`, `src={m}`) names a value this reader
+ * has no access to — it is reported, never resolved and never assumed equal.
+ */
+function exprIsUnreadable(expr) {
+  const stripped = String(expr ?? "").replace(LITERAL_OR_COMMENT, (m) => (m[0] === "/" ? " " : '""'));
+  if (UNREADABLE_EXPR.test(stripped)) return true;
+  for (const m of stripped.matchAll(/[A-Za-z_$][\w$]*/g)) {
+    if (LITERAL_WORDS.has(m[0])) continue;
+    if (/^\s*:/.test(stripped.slice(m.index + m[0].length))) continue;
+    return true;
+  }
+  return false;
+}
+
+const isUnreadable = (value) => isPlainObject(value) && exprIsUnreadable(value.expr);
+
+const attrText = (value) => {
+  if (value === true) return "true";
+  if (isPlainObject(value)) return `{${value.expr}}`;
+  return String(value ?? "");
+};
+
+const ENTITIES = { "&lt;": "<", "&gt;": ">", "&quot;": '"', "&apos;": "'", "&nbsp;": " ", "&amp;": "&" };
+
+/**
+ * Readable text of a source fragment: JSX string expressions become their
+ * value, every other expression contributes nothing (it is reported as
+ * unreadable elsewhere), entities are decoded once and whitespace collapses.
+ */
+function cleanText(raw) {
+  return String(raw ?? "")
+    .replace(/\{\s*"((?:[^"\\]|\\.)*)"\s*\}/g, (_, q) => {
+      try {
+        return JSON.parse(`"${q}"`);
+      } catch {
+        return q;
+      }
+    })
+    .replace(/\{[^{}]*\}/g, "")
+    .replace(/&(?:lt|gt|quot|apos|nbsp|amp);/g, (m) => ENTITIES[m])
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * The element's OWN text: its direct text plus that of inline children which
+ * carry no identity of their own (`<b>`, `<span>`). A child element with an id
+ * is a separate obligation and its text belongs to it, not to its parent.
+ */
+function ownText(node, src) {
+  let out = "";
+  let cursor = node.contentStart;
+  for (const child of node.children) {
+    out += src.slice(cursor, child.start);
+    if (!elementIdOf(child)) out += ownText(child, src);
+    cursor = child.end;
+  }
+  return cleanText(out + src.slice(cursor, node.contentEnd));
+}
+
+/**
+ * Attribute → property scope. The scope vocabulary is the operation record's
+ * (`PROPERTY_SCOPES`), which is itself the structural projection's own field
+ * set — so a scope always names something the render evidence can compare.
+ * Anything absent from both tables lands in `other`, and a change there is
+ * reported as `unknown` rather than ignored.
+ */
+const ATTR_SCOPE = {
+  x: "geom", y: "geom", w: "geom", h: "geom", rot: "geom", transform: "geom",
+  fill: "fill", bg: "fill",
+  stroke: "line", head: "line",
+  // A native line directive's own geometry and ends (nativeLinesV1).
+  "data-prst": "line", "data-adj": "line", "data-rot": "line", "data-flip": "line",
+  "data-from-site": "line", "data-to-site": "line", "data-cap-start": "line", "data-cap-end": "line",
+  "data-dash": "line", "data-linecap": "line",
+  src: "media", fit: "media", imgFit: "media", "data-asset-use": "media", "data-sm-src-crop": "media",
+  "data-sm-chart": "chart",
+  "data-sm-native-object": "native", "data-sm-preserved": "native",
+  px: "text", role: "text", align: "text", nowrap: "text", bold: "text",
+};
+
+const STYLE_SCOPE = {
+  left: "geom", top: "geom", width: "geom", height: "geom", position: "geom",
+  transform: "geom", clipPath: "geom", "clip-path": "geom",
+  background: "fill", backgroundColor: "fill", backgroundImage: "fill", opacity: "fill",
+  border: "line", borderTop: "line", borderRight: "line", borderBottom: "line", borderLeft: "line",
+  borderWidth: "line", borderStyle: "line", borderColor: "line", fill: "fill",
+  outline: "line", borderRadius: "line", boxShadow: "line",
+  color: "text", fontSize: "text", fontWeight: "text", fontFamily: "text",
+  fontStyle: "text", lineHeight: "text", textAlign: "text", letterSpacing: "text",
+};
+
+/**
+ * Ids that name a slide element, in the two dialects the product writes. An id
+ * bound to a name (`<div id={id}>`) is a helper's template, stamped with a real
+ * id at each call site: it names no element of its own.
+ */
+function elementIdOf(node) {
+  const attrs = node.attrs ?? (node.attrs = attrsOf(node.raw));
+  const id = attrs.id;
+  if (typeof id === "string" && id.trim()) return id.trim();
+  const literal = isPlainObject(id) && /^(?:(["'`])([\w.:-]+)\1|(\d+))$/.exec(id.expr);
+  if (literal) return literal[2] ?? literal[3];
+  // The converted dialect's handle on a source shape. Normalized to the bare
+  // number string, which is exactly the `p:cNvPr/@id` the package carries — so
+  // a requirement, the source and the projection all spell it one way.
+  const src = attrs["data-sm-source-id"];
+  const raw = isPlainObject(src) ? src.expr : src;
+  if (typeof raw === "string" && /^["']?\d+["']?$/.test(raw.trim())) return raw.trim().replace(/["']/g, "");
+  return null;
+}
+
+/** `#node-a` → `node-a`; a bare id stays as it is. */
+const refTarget = (value) => String(attrText(value)).replace(/^\{?["']?#?/, "").replace(/["']?\}?$/, "").trim();
+
+/**
+ * Read one slide's source into an element inventory.
+ *
+ * @param {string} jsx
+ * @returns {{
+ *   elements: Array<object>,
+ *   byId: Map<string, object>,
+ *   unsupported: Array<{elementId: string|null, line: number, construct: string, reason: string}>,
+ *   ambiguous: Array<{elementId: string|null, line: number, reason: string}>,
+ * }}
+ */
+export function readSlideElements(jsx) {
+  // A set component's members are read where they are drawn: each call site
+  // inlined with its literal props, on its own lines (inline-components.mjs).
+  const inlined = inlineComponents(String(jsx ?? ""));
+  const src = inlined.src;
+  const root = parseJsx(src);
+  const lineAt = (offset) => src.slice(0, offset).split("\n").length;
+  const elements = [];
+  const byId = new Map();
+  const unsupported = inlined.unreadable.map((u) => ({
+    elementId: null,
+    line: u.line,
+    construct: `<${u.component}>`,
+    reason: "unreadable_component",
+  }));
+  const ambiguous = [];
+
+  // `wrapperFrame`: the text frame that follows an id-less wrapper around one
+  // identified child (see `textFrameAfter`), handed down to that child.
+  const visit = (node, insideIdentified, wrapperFrame = null) => {
+    node.children.forEach((child, i) => {
+      if (child.unclosed) {
+        unsupported.push({
+          elementId: elementIdOf(child),
+          line: lineAt(child.start),
+          construct: `<${child.name}>`,
+          reason: "unclosed_element",
+        });
+      }
+      const elementId = elementIdOf(child);
+      const attrs = child.attrs ?? (child.attrs = attrsOf(child.raw));
+      if (elementId) {
+        const frame = textFrameAfter(node.children[i + 1]) ?? wrapperFrame;
+        const entry = describeElement(child, elementId, attrs, src, lineAt, frame);
+        for (const note of entry.unreadable) {
+          unsupported.push({ elementId, line: entry.line, construct: note, reason: "unreadable_expression" });
+        }
+        if (byId.has(elementId)) {
+          ambiguous.push({ elementId, line: entry.line, reason: "duplicate_element_id" });
+        } else {
+          byId.set(elementId, entry);
+        }
+        elements.push(entry);
+      } else if (isSlideElement(child, attrs) && !insideIdentified) {
+        // An element that paints but names nothing, and sits under nothing that
+        // names it either, cannot carry an obligation. Surfaced, never matched
+        // by shape — the guide asks for ambiguity to be reported rather than
+        // resolved with a confident guess. (A `<Chart>` inside `<B id="…">` is
+        // not ambiguous: the JSX itself says whose chart it is, and
+        // `describeElement` folds its attributes into that parent.)
+        ambiguous.push({ elementId: null, line: lineAt(child.start), reason: `unidentified_${child.name}` });
+      }
+      const wraps = !elementId && child.children.length === 1 && elementIdOf(child.children[0]);
+      visit(child, insideIdentified || Boolean(elementId), wraps ? textFrameAfter(node.children[i + 1]) : null);
+    });
+  };
+  visit(root, false);
+
+  // List rendering multiplies one source element into many rendered ones, so a
+  // per-element source comparison cannot speak about what is inside it.
+  for (const m of src.matchAll(/\.map\s*\(/g)) {
+    unsupported.push({ elementId: null, line: lineAt(m.index), construct: ".map(", reason: "list_rendering" });
+  }
+
+  return { elements, byId, unsupported, ambiguous };
+}
+
+/**
+ * Bind concept requirements to the ids the transcriber actually writes. One
+ * spec element becomes several when it is drawn as a multi-trace line or a
+ * mark's dots — `<id>-1`, `<id>-2`, … (src/builders/transcribe.mjs,
+ * concept-lines.mjs) — so a requirement seeded on the spec id names an element
+ * the source never has, and fails `removed_from_source` on untouched output.
+ * Such a requirement is replaced by one per piece, owing the same.
+ *
+ * Unchanged: a requirement whose own id is in the source, one with no pieces
+ * there, and any piece id that already has a requirement of its own.
+ */
+export function bindSplitIds(requirements, jsx) {
+  const present = [...readSlideElements(jsx).byId.keys()];
+  const owned = new Set(requirements.map((r) => r?.elementId));
+  const out = [];
+  for (const req of requirements) {
+    const id = req?.elementId;
+    const pieces =
+      req?.kind === "element" && typeof id === "string" && !present.includes(id)
+        ? present.filter((p) => p.startsWith(`${id}-`) && /^\d+$/.test(p.slice(id.length + 1)) && !owned.has(p))
+        : [];
+    if (pieces.length === 0) {
+      out.push(req);
+      continue;
+    }
+    for (const piece of pieces) {
+      out.push({ ...req, requirementId: `${req.requirementId}${piece.slice(id.length)}`, elementId: piece });
+    }
+  }
+  return out;
+}
+
+/**
+ * The converted dialect writes a filled shape as TWO siblings: its paint
+ * element carries `data-sm-source-id`, its text frame (`data-sm-text-frame`)
+ * does not — exactly one of them declares the id (reverse/codegen.ts,
+ * `sourceIdAttr`). That frame's text is the shape's text. A non-rect shape's
+ * paint is an `<svg>` inside an id-less wrapper `<div>`, and the frame follows
+ * the WRAPPER (reverse/codegen-svg.ts), so `readSlideElements` hands a
+ * wrapper's frame down to the one identified child it wraps.
+ */
+function textFrameAfter(next) {
+  if (!next || elementIdOf(next)) return null;
+  return next.attrs["data-sm-text-frame"] !== undefined ? next : null;
+}
+
+/** Does this tag paint something on the slide (as opposed to being a wrapper)? */
+function isSlideElement(node, attrs) {
+  if (/^(B|T|I|R|L|Chart|img|table)$/.test(node.name)) return true;
+  return attrs["data-connector"] !== undefined || attrs["data-sm-native-object"] !== undefined;
+}
+
+/** One element's per-scope fingerprints, relationships and unreadable parts. */
+function describeElement(node, elementId, attrs, src, lineAt, frame = null) {
+  const buckets = Object.fromEntries([...PROPERTY_SCOPES, "other"].map((s) => [s, []]));
+  const relationships = [];
+  const unreadable = [];
+  let kind = node.name;
+
+  // The element's own attributes, plus those of every descendant that carries
+  // no identity of its own — an unnamed `<Chart>` or `<b>` is part of THIS
+  // obligation, not a second one.
+  const absorb = (n, own) => {
+    const a = n.attrs ?? (n.attrs = attrsOf(n.raw));
+    const prefix = own ? "" : `${n.name}.`;
+    for (const [name, value] of Object.entries(a)) {
+      if (name === "id" || name === "data-sm-source-id" || name === "key") continue;
+      if (name === "data-from" || name === "data-to") {
+        relationships.push({ role: name === "data-from" ? "start" : "end", target: refTarget(value) });
+        continue;
+      }
+      if (isUnreadable(value)) unreadable.push(`${prefix}${name}={${value.expr}}`);
+      if (name === "style") {
+        // The style object is split per property, so a geometry change and a
+        // colour change in the same attribute do not read as one opaque diff.
+        for (const [prop, raw] of styleEntries(value)) {
+          (buckets[STYLE_SCOPE[prop]] ?? buckets.other).push(`${prefix}style.${prop}=${raw}`);
+        }
+        continue;
+      }
+      // `type`/`data` mean a chart only on a chart element; elsewhere they are
+      // ordinary attributes and must not be mistaken for chart evidence.
+      const scope = n.name === "Chart" && (name === "type" || name === "data") ? "chart" : ATTR_SCOPE[name];
+      (buckets[scope] ?? buckets.other).push(`${prefix}${name}=${attrText(value)}`);
+    }
+    if (n.name === "Chart" || a["data-sm-chart"] !== undefined) kind = "chart";
+    for (const child of n.children) if (!elementIdOf(child)) absorb(child, false);
+  };
+  absorb(node, true);
+
+  const text = [ownText(node, src), frame ? ownText(frame, src) : ""].filter(Boolean).join(" ");
+  if (text) buckets.text.push(`#text=${text}`);
+
+  const scopes = {};
+  for (const scope of [...PROPERTY_SCOPES, "other"]) {
+    scopes[scope] = buckets[scope].length ? buckets[scope].sort().join("\u001f") : null;
+  }
+
+  return {
+    elementId,
+    tag: node.name,
+    line: lineAt(node.start),
+    kind,
+    scopes,
+    text,
+    relationships,
+    unreadable,
+  };
+}
+
+/** `{{ left: "66px", top: "36px" }}` → [["left", '"66px"'], …]. */
+function* styleEntries(value) {
+  const expr = isPlainObject(value) ? value.expr : String(value ?? "");
+  const inner = expr.replace(/^\{/, "").replace(/\}$/, "");
+  for (const m of inner.matchAll(/([A-Za-z-][\w-]*)\s*:\s*("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|[^,}]+)/g)) {
+    yield [m[1], m[2].trim()];
+  }
+}
+
+/**
+ * Compare two versions of one slide's source.
+ *
+ * `changes` is what the edit INTENDED, keyed to the operation record's own
+ * property scopes. `unknown` holds elements whose only difference is in an
+ * attribute this reader does not model — seen, unattributable, and therefore
+ * never a silent pass. `unsupported` and `ambiguous` carry everything the
+ * reader refused to resolve.
+ *
+ * @param {string} before
+ * @param {string} after
+ */
+export function compareSlideSource(before, after) {
+  const a = readSlideElements(before);
+  const b = readSlideElements(after);
+  const changes = [];
+  const unknown = [];
+
+  const ids = new Set([...a.byId.keys(), ...b.byId.keys()]);
+  for (const elementId of ids) {
+    const prev = a.byId.get(elementId);
+    const next = b.byId.get(elementId);
+    if (!prev) {
+      changes.push({
+        elementId,
+        action: "add",
+        properties: PROPERTY_SCOPES.filter((s) => next.scopes[s] != null),
+        relationships: next.relationships,
+      });
+      continue;
+    }
+    if (!next) {
+      changes.push({
+        elementId,
+        action: "remove",
+        properties: PROPERTY_SCOPES.filter((s) => prev.scopes[s] != null),
+        relationships: prev.relationships,
+      });
+      continue;
+    }
+    const properties = PROPERTY_SCOPES.filter((s) => prev.scopes[s] !== next.scopes[s]);
+    const relationshipsChanged = canonical(prev.relationships) !== canonical(next.relationships);
+    if (prev.scopes.other !== next.scopes.other) {
+      unknown.push({
+        elementId,
+        reason: "unmodelled_attribute_change",
+        detail: "an attribute outside the property-scope vocabulary changed; the scope of this edit cannot be named",
+      });
+    }
+    if (properties.length || relationshipsChanged) {
+      changes.push({
+        elementId,
+        action: "update",
+        properties,
+        ...(relationshipsChanged ? { relationships: { before: prev.relationships, after: next.relationships } } : {}),
+      });
+    }
+  }
+
+  changes.sort((x, y) => String(x.elementId).localeCompare(String(y.elementId)));
+  return {
+    changes,
+    unknown,
+    unsupported: [...a.unsupported, ...b.unsupported],
+    ambiguous: [...a.ambiguous, ...b.ambiguous],
+    before: a,
+    after: b,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 2a. Rendered-IR comparison — did the object actually paint?
+// ---------------------------------------------------------------------------
+
+/** Reasons an element is present in the render tree but cannot be seen. */
+export const HIDDEN_REASONS = [
+  "hidden:display-none",
+  "hidden:zero-size",
+  "hidden:zero-opacity",
+  "hidden:clipped",
+  "hidden:off-canvas",
+];
+
+/**
+ * Is this clip-path empty? Returns true (clips everything), false (leaves area)
+ * or null (this reader cannot tell — the caller reports `unsupported`, never a
+ * pass). `polygon()` is resolved by area rather than refused, because the
+ * transcriber writes chevrons and trapezoids that way on ordinary slides.
+ */
+function clipHidesEverything(clipPath) {
+  const value = String(clipPath ?? "").trim();
+  if (!value || value === "none") return false;
+  const inset = /^inset\(\s*([^)]*?)\s*(?:round[^)]*)?\)$/.exec(value);
+  if (inset) {
+    const parts = inset[1].trim().split(/\s+/).map((p) => percent(p));
+    if (parts.some((p) => p === null)) return null;
+    const [t, r = t, b = t, l = r] = parts;
+    return t + b >= 100 || l + r >= 100;
+  }
+  const circle = /^circle\(\s*([^\s)]+)/.exec(value);
+  if (circle) {
+    const radius = percent(circle[1]) ?? num(Number.parseFloat(circle[1]));
+    return radius === null ? null : radius <= 0;
+  }
+  const polygon = /^polygon\(\s*([^)]*)\)$/.exec(value);
+  if (polygon) {
+    const points = [];
+    for (const pair of polygon[1].split(",")) {
+      const [px, py] = pair.trim().split(/\s+/).map((p) => percent(p));
+      if (px === null || py === null) return null;
+      points.push([px, py]);
+    }
+    if (points.length < 3) return true;
+    // Shoelace: a polygon with no area paints nothing.
+    let twiceArea = 0;
+    for (let i = 0; i < points.length; i++) {
+      const [x1, y1] = points[i];
+      const [x2, y2] = points[(i + 1) % points.length];
+      twiceArea += x1 * y2 - x2 * y1;
+    }
+    return Math.abs(twiceArea) / 2 < 1e-6;
+  }
+  return null;
+}
+
+/** "50%" → 50, "0" → 0, "12px" → null (no basis to compare against). */
+function percent(token) {
+  const t = String(token ?? "").trim();
+  if (/^-?\d+(\.\d+)?%$/.test(t)) return Number.parseFloat(t);
+  if (/^-?0(\.0+)?$/.test(t)) return 0;
+  return null;
+}
+
+/** Which sides of a rect moved past the rendered-px tolerance. */
+function rectDrift(want, got) {
+  if (!isPlainObject(want) || !isPlainObject(got)) return null;
+  return ["x", "y", "w", "h"].filter((k) => {
+    const a = num(want[k]);
+    const b = num(got[k]);
+    return a !== null && b !== null && Math.abs(b - a) > RENDER_GEOMETRY_TOLERANCE_PX;
+  });
+}
+
+/** Index a captured box tree by element identity, carrying inherited hiding. */
+function indexRender(boxes, canvas) {
+  const byId = new Map();
+  let seen = 0;
+  const walk = (box, inherited) => {
+    if (!isPlainObject(box)) return;
+    seen += 1;
+    const local = boxHidden(box, canvas);
+    const state = inherited ?? local;
+    const id = isNonEmptyString(box.elementId)
+      ? box.elementId
+      : box.smSourceId != null
+        ? String(box.smSourceId)
+        : null;
+    if (id && !byId.has(id)) byId.set(id, { box, hidden: state });
+    for (const child of box.children ?? []) walk(child, state);
+  };
+  for (const box of Array.isArray(boxes) ? boxes : []) walk(box, null);
+  return { byId, seen };
+}
+
+/**
+ * Why this box cannot be seen, or null. `{ unsupported: "…" }` when the reader
+ * will not decide — a clip it cannot resolve is not a clip that passed.
+ */
+function boxHidden(box, canvas) {
+  const style = isPlainObject(box.style) ? box.style : {};
+  if (style.display === "none") return { reason: "hidden:display-none" };
+
+  const rect = isPlainObject(box.rect) ? box.rect : null;
+  // A connector is measured from its endpoints, not from its own rect: the
+  // native `<p:cxnSp>` for a horizontal link legitimately has zero height.
+  const measuredByEndpoints = Boolean(box.connector);
+  if (rect && !measuredByEndpoints) {
+    const w = num(rect.w);
+    const h = num(rect.h);
+    if (w === null || h === null) return { unsupported: "rect_unreadable" };
+    if (w < RENDER_MIN_VISIBLE_PX || h < RENDER_MIN_VISIBLE_PX) return { reason: "hidden:zero-size" };
+  } else if (!rect && !measuredByEndpoints) {
+    return { unsupported: "rect_missing" };
+  }
+
+  const opacity = num(style.opacity);
+  if (opacity !== null && opacity < RENDER_MIN_VISIBLE_OPACITY) return { reason: "hidden:zero-opacity" };
+
+  const clipped = clipHidesEverything(style.clipPath);
+  if (clipped === null) return { unsupported: "clip_path_unreadable" };
+  if (clipped) return { reason: "hidden:clipped" };
+
+  // A connector's rect is degenerate by construction (see above), so the
+  // off-canvas test cannot read it either: a zero-width link at x=0 has
+  // `right <= OFF_CANVAS_SLACK_PX` and would report hidden:off-canvas — a
+  // false deletion on a slide nobody touched.
+  if (canvas && rect && !measuredByEndpoints) {
+    const w = num(canvas.w);
+    const h = num(canvas.h);
+    if (w !== null && h !== null) {
+      const right = num(rect.x) + num(rect.w);
+      const bottom = num(rect.y) + num(rect.h);
+      const outside =
+        right <= OFF_CANVAS_SLACK_PX ||
+        bottom <= OFF_CANVAS_SLACK_PX ||
+        num(rect.x) >= w - OFF_CANVAS_SLACK_PX ||
+        num(rect.y) >= h - OFF_CANVAS_SLACK_PX;
+      if (outside) return { reason: "hidden:off-canvas" };
+    }
+  }
+  return null;
+}
+
+/**
+ * Prove each element survived the render.
+ *
+ * `render` is one captured slide (`{ boxes: [...] }` — the CapturedDeck slide
+ * both clients already produce). `elementIds` are the identities being asked
+ * about; each gets one of:
+ *
+ *   passed      — a box with that identity paints something visible
+ *   failed      — the render HAS evidence and the element is absent from it,
+ *                 or is present and hidden (zero-size, zero-opacity,
+ *                 display:none, fully clipped, off-canvas)
+ *   unknown     — there is no render evidence at all to speak from
+ *   unsupported — the box is there but this reader cannot decide (an
+ *                 unresolvable clip-path, a missing rect)
+ *
+ * The failed case is the point of this function: an element present in the JSX
+ * and missing or hidden in the render must never read as preserved.
+ *
+ * `expectRects`, when given, additionally holds each element to the rect it
+ * occupied in an earlier capture, within `RENDER_GEOMETRY_TOLERANCE_PX`. That
+ * is the only place a rendered-px tolerance applies: EMU geometry is the
+ * package comparison's business, at its own quantization.
+ *
+ * @param {{boxes?: Array<object>}} render
+ * @param {{
+ *   canvas?: {w:number,h:number}|null,
+ *   elementIds?: Array<string>,
+ *   expectRects?: Record<string, {x:number,y:number,w:number,h:number}>|null,
+ * }} [opts]
+ */
+export function compareRenderEvidence(render, { canvas = null, elementIds = [], expectRects = null } = {}) {
+  const boxes = isPlainObject(render) ? render.boxes : null;
+  const { byId, seen } = indexRender(boxes, canvas);
+  const hasEvidence = seen > 0;
+  const byIdOut = {};
+
+  for (const elementId of elementIds) {
+    if (!hasEvidence) {
+      byIdOut[elementId] = {
+        status: "unknown",
+        reason: "no_render_evidence",
+        detail: "the slide was not captured, so nothing can be said about what survived",
+      };
+      continue;
+    }
+    const found = byId.get(elementId);
+    if (!found) {
+      byIdOut[elementId] = {
+        status: "failed",
+        reason: "absent_from_render",
+        detail: "the source declares this element and the render does not contain it",
+      };
+      continue;
+    }
+    const hidden = found.hidden;
+    if (hidden?.unsupported) {
+      byIdOut[elementId] = { status: "unsupported", reason: hidden.unsupported, rect: found.box.rect ?? null };
+      continue;
+    }
+    if (hidden?.reason) {
+      byIdOut[elementId] = {
+        status: "failed",
+        reason: hidden.reason,
+        detail: "the element is in the render but paints nothing a viewer can see",
+        rect: found.box.rect ?? null,
+      };
+      continue;
+    }
+    const want = expectRects?.[elementId];
+    const drift = want ? rectDrift(want, found.box.rect) : null;
+    if (drift?.length) {
+      byIdOut[elementId] = {
+        status: "failed",
+        reason: "geometry_moved",
+        detail: `past ${RENDER_GEOMETRY_TOLERANCE_PX}px on: ${drift.join(", ")}`,
+        rect: found.box.rect ?? null,
+      };
+      continue;
+    }
+    byIdOut[elementId] = { status: "passed", rect: found.box.rect ?? null };
+  }
+
+  return { byId: byIdOut, evidence: hasEvidence ? "present" : "absent", indexed: [...byId.keys()] };
+}
+
+// ---------------------------------------------------------------------------
+// 2b. Final-package comparison — did it survive the splice, unchanged?
+// ---------------------------------------------------------------------------
+
+/**
+ * Compare two NORMALIZED projections of one slide, keyed by element identity.
+ *
+ * Both arguments are `{ [elementId]: shape }`, where `shape` is a structural
+ * projection entry (`computeProjection`, src/pptx/tags.mjs, or the add-in's
+ * twin): `{ geom, text, fill, line, mediaSha256, chart }`. The caller supplies
+ * the keying, because only the caller knows how its package spells identity —
+ * an identity this module invented would be a confident guess, which the guide
+ * forbids. A `native` field may be attached per shape (`{ parts: { path: sha } }`)
+ * to carry an opaque object's dependency closure.
+ *
+ * ZIP bytes are deliberately NOT compared: timestamps, relationship ids and
+ * part ordering legitimately change on a save that changed nothing.
+ *
+ * @param {Record<string, object>} before
+ * @param {Record<string, object>} after
+ * @param {{resolvedTargets?: Array<string>|Set<string>|null}} [opts]
+ */
+export function comparePackageEvidence(before, after, { resolvedTargets = null } = {}) {
+  const a = isPlainObject(before) ? before : {};
+  const b = isPlainObject(after) ? after : {};
+  const targets = resolvedTargets == null ? null : new Set(resolvedTargets);
+  const byId = {};
+
+  for (const elementId of new Set([...Object.keys(a), ...Object.keys(b)])) {
+    const prev = a[elementId];
+    const next = b[elementId];
+    if (!isPlainObject(next)) {
+      byId[elementId] = {
+        status: "failed",
+        reason: "absent_from_package",
+        detail: "the element is not in the delivered package",
+        scopes: {},
+      };
+      continue;
+    }
+    if (!isPlainObject(prev)) {
+      byId[elementId] = {
+        status: "unknown",
+        reason: "no_package_baseline",
+        detail: "nothing to compare the delivered element against",
+        scopes: {},
+      };
+      continue;
+    }
+    const scopes = {
+      geom: compareGeom(prev.geom, next.geom),
+      text: sameOrChanged(canonical(prev.text ?? null), canonical(next.text ?? null)),
+      fill: sameOrChanged(prev.fill ?? null, next.fill ?? null),
+      line: sameOrChanged(prev.line ?? null, next.line ?? null),
+      media: compareDigest(prev.mediaSha256, next.mediaSha256, "media_digest_unavailable"),
+      // The CLI's projection cannot produce a chart hash (src/pptx/tags.mjs
+      // documents why: it would need the add-in's whole chart reader). Both
+      // sides null is therefore `unsupported`, never a pass.
+      chart: compareDigest(prev.chart, next.chart, "chart_hash_unavailable"),
+      native: compareNative(prev.native, next.native),
+    };
+    // The element-level status rolls up only the scopes the projection always
+    // models, plus the three payload scopes that are actually present on one
+    // side or the other. A text shape has no chart, so "no chart hash here" is
+    // not an unsupported CHECK — it is the absence of a thing to check. Where a
+    // payload really does exist and its digest is unavailable (the CLI's chart
+    // hash), the `unsupported` stays in `scopes` and reaches the verdict
+    // through the requirement that protects it.
+    const carried = [
+      ...["geom", "text", "fill", "line"],
+      ...(prev.mediaSha256 != null || next.mediaSha256 != null ? ["media"] : []),
+      ...(prev.chart != null || next.chart != null ? ["chart"] : []),
+      ...(isPlainObject(prev.native) || isPlainObject(next.native) ? ["native"] : []),
+    ];
+    byId[elementId] = { status: rollUp(carried.map((s) => scopes[s].status)), scopes };
+  }
+
+  if (targets) {
+    byId["#relationships"] = { status: "passed", resolved: [...targets] };
+  }
+  return { byId, resolvedTargets: targets };
+}
+
+function compareGeom(prev, next) {
+  if (!isPlainObject(prev) || !isPlainObject(next)) {
+    return { status: "unknown", reason: "geometry_unavailable" };
+  }
+  const moved = ["x", "y", "w", "h", "rot"].filter((k) => {
+    const dp = num(prev[k]);
+    const dn = num(next[k]);
+    if (dp === null || dn === null) return false;
+    return Math.abs(dn - dp) > TRANSFORM_TOLERANCE_EMU;
+  });
+  return moved.length
+    ? { status: "failed", reason: "geometry_changed", detail: `changed: ${moved.join(", ")}`, tolerance: { quantumEmu: PROJECTION_QUANTUM_EMU, slackEmu: TRANSFORM_TOLERANCE_EMU } }
+    : { status: "passed" };
+}
+
+const sameOrChanged = (prev, next) =>
+  prev === next ? { status: "passed" } : { status: "failed", reason: "property_changed" };
+
+function compareDigest(prev, next, missingReason) {
+  if (prev == null && next == null) return { status: "unsupported", reason: missingReason };
+  if (prev == null || next == null) return { status: "failed", reason: "digest_appeared_or_vanished" };
+  return prev === next
+    ? { status: "passed" }
+    : { status: "failed", reason: "digest_changed", detail: "a binary payload changed without the user editing it" };
+}
+
+function compareNative(prev, next) {
+  const prevParts = isPlainObject(prev?.parts) ? prev.parts : null;
+  const nextParts = isPlainObject(next?.parts) ? next.parts : null;
+  if (!prevParts && !nextParts) return { status: "unsupported", reason: "native_closure_not_supplied" };
+  if (!prevParts || !nextParts) return { status: "unknown", reason: "native_closure_partial" };
+  const missing = Object.keys(prevParts).filter((p) => nextParts[p] === undefined);
+  if (missing.length) {
+    return { status: "failed", reason: "native_part_missing", detail: `dropped: ${missing.join(", ")}` };
+  }
+  const rehashed = Object.keys(prevParts).filter((p) => nextParts[p] !== prevParts[p]);
+  if (rehashed.length) {
+    return { status: "failed", reason: "native_part_changed", detail: `rewritten: ${rehashed.join(", ")}` };
+  }
+  return { status: "passed" };
+}
+
+/** failed beats unsupported beats unknown beats passed. */
+function rollUp(statuses) {
+  if (statuses.includes("failed")) return "failed";
+  if (statuses.includes("unsupported")) return "unsupported";
+  if (statuses.includes("unknown")) return "unknown";
+  return statuses.length ? "passed" : "unknown";
+}
+
+// ---------------------------------------------------------------------------
+// The verdict
+// ---------------------------------------------------------------------------
+
+/**
+ * Hash of the obligations a verdict was about. Covers the active requirements'
+ * identity, kind, protected scopes and relationships — not the baseline hash,
+ * because source changes on every edit while the promises do not. A later
+ * phase compares this against the record on disk to know the verdict is stale.
+ */
+export function requirementSetHash(entry) {
+  const active = Array.isArray(entry?.active) ? entry.active : [];
+  const shape = active
+    .filter(isPlainObject)
+    .map((r) => ({
+      requirementId: r.requirementId ?? null,
+      elementId: r.elementId ?? null,
+      kind: r.kind ?? null,
+      properties: [...(Array.isArray(r.properties) ? r.properties : [])].sort(),
+      relationships: [...(Array.isArray(r.relationships) ? r.relationships : [])]
+        .filter(isPlainObject)
+        .map((rel) => ({ role: rel.role ?? null, target: rel.target ?? null }))
+        .sort((x, y) => canonical(x).localeCompare(canonical(y))),
+      useId: r.useId ?? null,
+    }))
+    .sort((x, y) => String(x.requirementId).localeCompare(String(y.requirementId)));
+  return sha256(canonical(shape));
+}
+
+/** What a restyle may change on any element: how it looks, not what it says. */
+const LOOK_SCOPES = ["geom", "fill", "line"];
+const CONTENT_SCOPES = new Set(["text", "media", "chart", "native"]);
+
+/**
+ * Only an IMPORT's decoration may be restyled away. Its seed claims a content
+ * scope exactly where the shape HAS that content (its own text, a picture
+ * fill), so a requirement without one owes only a look. Elsewhere the absence
+ * proves nothing: a concept's drawn marks (a bar, a sparkline, a rule) carry
+ * data with no text, and `legacy-current` claims only media/native for every
+ * element.
+ */
+const WAIVABLE_ORIGIN = "converted";
+
+/**
+ * What this operation declared it may change on the requirement's element.
+ *
+ * Two sources: the target's explicit `changes`, and the operation's KIND. A
+ * redesign is the user asking for a new look, so on a slide it targets the look
+ * scopes are declared by the kind itself, and an imported element that carried
+ * none of the slide's content may go. Content — text, pictures, charts, native objects,
+ * connections — stays owed: a restyle must keep the user's words and images,
+ * which is what keeps a real loss refusable.
+ */
+function declaredFor(operation, slideKey, req, origin) {
+  const out = { scopes: new Set(), removable: false, declared: false };
+  for (const target of Array.isArray(operation?.targets) ? operation.targets : []) {
+    if (!isPlainObject(target)) continue;
+    if (slideKey != null && target.slideKey !== slideKey) continue;
+    if (operation.kind === "redesign") {
+      out.declared = true;
+      for (const scope of LOOK_SCOPES) out.scopes.add(scope);
+      const properties = Array.isArray(req.properties) ? req.properties : [];
+      if (req.kind === "element" && origin === WAIVABLE_ORIGIN && !properties.some((s) => CONTENT_SCOPES.has(s))) {
+        out.removable = true;
+      }
+    }
+    for (const change of Array.isArray(target.changes) ? target.changes : []) {
+      if (!isPlainObject(change) || change.elementId !== req.elementId) continue;
+      out.declared = true;
+      if (change.action === "remove") out.removable = true;
+      for (const scope of Array.isArray(change.properties) ? change.properties : []) out.scopes.add(scope);
+    }
+  }
+  return out;
+}
+
+/** A declared removal the evidence confirms: the element is simply gone. */
+const declaredRemoval = (at) => ({ ...at, scope: null, status: "passed", reason: "declared_removal" });
+
+/**
+ * Compose the two comparisons into one verdict about one slide.
+ *
+ * `entry` is the slide's preservation record (its `active` requirements),
+ * `operation` the record authorizing this run, and `source` / `render` /
+ * `packageEvidence` are the results of the three comparisons above — each
+ * optional, because a draft has no package and an offline check has no render.
+ * Whatever is absent produces `unknown` checks, never passes.
+ *
+ * @param {{
+ *   entry?: object|null,
+ *   operation?: object|null,
+ *   slideKey?: string|null,
+ *   source?: object|null,
+ *   render?: object|null,
+ *   packageEvidence?: object|null,
+ *   binding?: {sourceHash?: string, liveRevision?: string, operationId?: string},
+ * }} [input]
+ */
+export function preservationVerdict({
+  entry = null,
+  operation = null,
+  slideKey = null,
+  source = null,
+  render = null,
+  packageEvidence = null,
+  binding = {},
+} = {}) {
+  const active = Array.isArray(entry?.active) ? entry.active.filter(isPlainObject) : [];
+  const key = slideKey ?? (isDurableId(entry?.slideKey) ? entry.slideKey : null);
+  const checks = [];
+
+  for (const req of active) {
+    const elementId = req.elementId;
+    const at = { requirementId: req.requirementId ?? null, elementId: elementId ?? null, kind: req.kind ?? null };
+    const allowed = declaredFor(operation, key, req, entry?.origin ?? null);
+
+    // --- source: is the obligation still in the file the agent wrote?
+    if (source) {
+      const unsupported = source.unsupported?.find((u) => u.elementId === elementId);
+      const unknown = source.unknown?.find((u) => u.elementId === elementId);
+      const ambiguous = source.ambiguous?.find((u) => u.elementId === elementId);
+      const change = source.changes?.find((c) => c.elementId === elementId);
+      if (unsupported) {
+        checks.push({ ...at, scope: null, status: "unsupported", reason: unsupported.reason });
+      } else if (ambiguous) {
+        checks.push({ ...at, scope: null, status: "unknown", reason: ambiguous.reason });
+      } else if (change?.action === "remove" && !allowed.removable) {
+        checks.push({
+          ...at,
+          scope: null,
+          status: "failed",
+          reason: "removed_from_source",
+          detail: "the element is gone from the source and this operation did not declare its removal",
+        });
+      } else if (unknown) {
+        checks.push({ ...at, scope: null, status: "unknown", reason: unknown.reason });
+      }
+    }
+
+    // --- render: did it paint?
+    if (render && elementId != null) {
+      const seen = render.byId?.[elementId];
+      if (seen?.reason === "absent_from_render" && allowed.removable) {
+        checks.push(declaredRemoval(at));
+      } else if (seen) {
+        checks.push({
+          ...at,
+          scope: null,
+          status: seen.status,
+          reason: seen.reason ?? null,
+          ...(seen.detail ? { detail: seen.detail } : {}),
+        });
+      } else {
+        checks.push({ ...at, scope: null, status: "unknown", reason: "not_checked_in_render" });
+      }
+    }
+
+    // --- package: did the protected properties survive the splice?
+    if (packageEvidence && elementId != null) {
+      const seen = packageEvidence.byId?.[elementId];
+      if (!seen) {
+        checks.push({ ...at, scope: null, status: "unknown", reason: "not_checked_in_package" });
+      } else if (seen.status === "failed" && seen.reason === "absent_from_package") {
+        checks.push(
+          allowed.removable
+            ? declaredRemoval(at)
+            : { ...at, scope: null, status: "failed", reason: seen.reason, detail: seen.detail },
+        );
+      } else {
+        const protectedScopes = Array.isArray(req.properties) && req.properties.length
+          ? req.properties
+          : PROPERTY_SCOPES;
+        for (const scope of protectedScopes) {
+          const result = seen.scopes?.[scope];
+          if (!result) {
+            checks.push({ ...at, scope, status: "unknown", reason: "scope_not_compared" });
+            continue;
+          }
+          // A property the operation declared changeable is allowed to differ;
+          // it is still reported, so the verdict says what it let through.
+          if (result.status === "failed" && allowed.scopes.has(scope)) {
+            checks.push({ ...at, scope, status: "passed", reason: "declared_change" });
+            continue;
+          }
+          checks.push({
+            ...at,
+            scope,
+            status: result.status,
+            reason: result.reason ?? null,
+            ...(result.detail ? { detail: result.detail } : {}),
+          });
+        }
+      }
+    }
+
+    // --- relationships: an endpoint or package part that no longer resolves.
+    const targets = packageEvidence?.resolvedTargets ?? null;
+    for (const rel of Array.isArray(req.relationships) ? req.relationships : []) {
+      if (!isPlainObject(rel)) continue;
+      const scope = req.kind === "native-object" ? "native" : "geom";
+      if (!targets) {
+        checks.push({ ...at, scope, status: "unknown", reason: "relationships_not_resolved", detail: rel.role });
+        continue;
+      }
+      checks.push(
+        targets.has(rel.target)
+          ? { ...at, scope, status: "passed", reason: `relationship:${rel.role}` }
+          : {
+              ...at,
+              scope,
+              status: "failed",
+              reason: "relationship_broken",
+              detail: `${rel.role} → ${rel.target} no longer resolves`,
+            },
+      );
+    }
+
+    if (!checks.some((c) => c.requirementId === at.requirementId)) {
+      checks.push({ ...at, scope: null, status: "unknown", reason: "no_evidence_supplied" });
+    }
+  }
+
+  // A construct the reader could not resolve that belongs to no single element
+  // — list rendering, an unclosed tag — makes the source comparison unable to
+  // speak for the WHOLE slide, so it is a check of its own rather than a note
+  // nobody reads.
+  for (const u of source?.unsupported ?? []) {
+    if (u.elementId != null) continue;
+    checks.push({ requirementId: null, elementId: null, kind: null, scope: null, status: "unsupported", reason: u.reason });
+  }
+
+  const counts = Object.fromEntries(EVIDENCE_STATUSES.map((s) => [s, 0]));
+  for (const c of checks) counts[c.status] = (counts[c.status] ?? 0) + 1;
+
+  // `unsupported` is not a pass: it rolls the verdict to `unknown`, which is
+  // what a final delivery refuses on.
+  const status = checks.length === 0 && active.length === 0
+    ? "unknown"
+    : rollUp(checks.map((c) => c.status)) === "unsupported"
+      ? "unknown"
+      : rollUp(checks.map((c) => c.status));
+
+  return {
+    version: PRESERVATION_VERDICT_VERSION,
+    status,
+    slideKey: key,
+    binding: {
+      sourceHash: binding.sourceHash ?? null,
+      liveRevision: binding.liveRevision ?? null,
+      operationId: isPlainObject(operation) ? (operation.operationId ?? null) : (binding.operationId ?? null),
+      requirementSetHash: requirementSetHash(entry),
+    },
+    checks,
+    counts,
+    unsupported: [
+      ...(source?.unsupported ?? []),
+      ...checks.filter((c) => c.status === "unsupported").map((c) => ({
+        elementId: c.elementId,
+        reason: c.reason,
+        construct: c.scope ? `scope:${c.scope}` : "element",
+      })),
+    ],
+  };
+}
+
+/**
+ * Has anything the verdict was bound to moved since? Any difference in the
+ * source hash, the live revision, the operation or the requirement set
+ * invalidates it — a verdict is about one exact state of one exact slide.
+ */
+export function verdictIsStale(verdict, current = {}) {
+  if (!isPlainObject(verdict) || verdict.version !== PRESERVATION_VERDICT_VERSION) return true;
+  const bound = isPlainObject(verdict.binding) ? verdict.binding : {};
+  for (const field of ["sourceHash", "liveRevision", "operationId", "requirementSetHash"]) {
+    if (current[field] === undefined) continue;
+    if (bound[field] !== current[field]) return true;
+  }
+  return false;
+}