slidemind 0.3.20 → 0.4.1

package/src/lib/slide-guids.mjs

@@ -12,8 +12,9 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { statePath, writeStateFile } from "./deck-paths.mjs";
 
-const SIDECAR = ".slide-guids.json";
+const SIDECAR = "slide-guids.json";
 
 const sha256Hex = (data) => createHash("sha256").update(data).digest("hex");
 
@@ -28,7 +29,7 @@ export function slideGuidEntry(guid, jsx) {
 function readSidecar(deckDir) {
   let parsed;
   try {
-    parsed = JSON.parse(fs.readFileSync(path.join(deckDir, SIDECAR), "utf8"));
+    parsed = JSON.parse(fs.readFileSync(statePath(deckDir, SIDECAR), "utf8"));
   } catch {
     return {};
   }
@@ -44,10 +45,7 @@ function readSidecar(deckDir) {
 }
 
 function writeSidecar(deckDir, entries) {
-  fs.writeFileSync(
-    path.join(deckDir, SIDECAR),
-    `${JSON.stringify(entries, null, 2)}\n`,
-  );
+  writeStateFile(deckDir, SIDECAR, `${JSON.stringify(entries, null, 2)}\n`);
 }
 
 /** { [path]: guid } — the wire shape the render routes take. */

package/src/lib/slide-preservation.mjs

@@ -0,0 +1,423 @@
+// What a slide must still contain after an edit — the preservation record.
+//
+// Contract from `openspec/changes/safeguard-slide-editing/implementation-guide.md`
+// section 1. Persisted at `<deck>/.slidemind/state/slide-preservation.json`,
+// indexed by slideKey, and mirrored byte-for-byte into the add-in
+// (`scripts/sync-transcription-runtime.mjs`) so both clients enforce one set of
+// obligations.
+//
+// The rule this file exists to make unrepresentable: **a changed source hash
+// never clears these records.** An agent that rewrites a slide has changed the
+// bytes, not the promises. Dropping a requirement is only legal as an explicit,
+// operation-scoped supersession — which is why the transition below compares
+// two versions of the file rather than just validating one. "Clear all
+// requirements" has no encoding.
+//
+// Pure: no disk, no mutation, no throw.
+
+import { EDIT_OPERATION_VERSION, PROPERTY_SCOPES, operationSlideKeys } from "./edit-operations.mjs";
+import { isDurableId } from "./durable-ids.mjs";
+
+/** Sidecar name under the workspace's `state/`. */
+export const SLIDE_PRESERVATION_FILE = "slide-preservation.json";
+
+/** Same version line as the operation record; the two are written together. */
+export const SLIDE_PRESERVATION_VERSION = EDIT_OPERATION_VERSION;
+
+/**
+ * Where the obligations came from:
+ *   concept        — a transcribed slide; requirement ids are concept-spec element ids
+ *   converted      — an imported slide; ids are the converter's source-shape ids
+ *   legacy-current — a deck that predates this record; seeded from CURRENT
+ *                    evidence, never from an old plan's obligations
+ */
+export const PRESERVATION_ORIGINS = ["concept", "converted", "legacy-current"];
+
+/**
+ * Requirement flavours. `element` covers an ordinary shape/text/picture;
+ * `connection` and `native-object` are defined by what they point AT, so both
+ * must carry relationships; `image-use` delegates byte/framing verification to
+ * the image-intent validator and only stores the canonical use id.
+ */
+export const REQUIREMENT_KINDS = ["element", "connection", "native-object", "image-use"];
+
+/**
+ * Evidence is tri-state on purpose: missing evidence is `unknown`, which is NOT
+ * `passed`. A record that cannot say what it verified must say so, so a final
+ * replacement can refuse rather than assume.
+ */
+export const EVIDENCE_STATUSES = ["unknown", "passed", "failed", "unsupported"];
+
+const SHA256_RE = /^[0-9a-f]{64}$/;
+
+const err = (out, path, code, message) => out.push({ path, code, message });
+const isPlainObject = (v) => Boolean(v) && typeof v === "object" && !Array.isArray(v);
+const isNonEmptyString = (v) => typeof v === "string" && v.trim().length > 0;
+
+function checkVersion(record, path, out) {
+  if (record.version === SLIDE_PRESERVATION_VERSION) return true;
+  err(
+    out,
+    `${path}.version`,
+    "unsupported_version",
+    `schema version ${JSON.stringify(record.version ?? null)} is not supported; ` +
+      `this build reads version ${SLIDE_PRESERVATION_VERSION}. Preserve the record as it is ` +
+      `and upgrade slidemind (\`slidemind update\`) before editing this deck.`,
+  );
+  return false;
+}
+
+function checkEnum(value, allowed, path, code, out) {
+  if (allowed.includes(value)) return true;
+  err(out, path, code, `${JSON.stringify(value ?? null)} is not one of ${allowed.join(" | ")}`);
+  return false;
+}
+
+function validateRequirement(req, path, seenIds, seenIdentities, out) {
+  if (!isPlainObject(req)) {
+    err(out, path, "invalid_record", "a requirement must be an object");
+    return;
+  }
+  if (!isDurableId(req.requirementId)) {
+    err(out, `${path}.requirementId`, "missing_field", "requirementId must be a durable identity");
+  } else if (seenIds.has(req.requirementId)) {
+    err(out, `${path}.requirementId`, "duplicate_requirement_id", `requirementId ${req.requirementId} appears twice`);
+  } else {
+    seenIds.add(req.requirementId);
+  }
+
+  if (!isDurableId(req.elementId)) {
+    err(out, `${path}.elementId`, "missing_field", "elementId must be a durable element identity");
+  }
+  const kindOk = checkEnum(req.kind, REQUIREMENT_KINDS, `${path}.kind`, "invalid_value", out);
+
+  // One element gets one requirement per kind. Two of the same is an ambiguous
+  // obligation: a verdict could satisfy one and violate the other.
+  if (isDurableId(req.elementId) && kindOk) {
+    const identity = `${req.kind}:${req.elementId}`;
+    if (seenIdentities.has(identity)) {
+      err(
+        out,
+        `${path}.elementId`,
+        "duplicate_element_id",
+        `element ${req.elementId} already has a ${req.kind} requirement on this slide`,
+      );
+    } else {
+      seenIdentities.add(identity);
+    }
+  }
+
+  if (!Array.isArray(req.properties)) {
+    err(out, `${path}.properties`, "missing_field", "properties must be an array of protected property scopes");
+  } else {
+    req.properties.forEach((scope, i) => {
+      if (!PROPERTY_SCOPES.includes(scope)) {
+        err(
+          out,
+          `${path}.properties[${i}]`,
+          "invalid_property_scope",
+          `${JSON.stringify(scope ?? null)} is not a known property scope (${PROPERTY_SCOPES.join(", ")})`,
+        );
+      }
+    });
+  }
+
+  const relationships = req.relationships;
+  if (relationships != null && !Array.isArray(relationships)) {
+    err(out, `${path}.relationships`, "invalid_value", "relationships must be an array");
+  } else if (Array.isArray(relationships)) {
+    relationships.forEach((rel, i) => {
+      const at = `${path}.relationships[${i}]`;
+      if (!isPlainObject(rel)) {
+        err(out, at, "invalid_record", "a relationship must be an object");
+        return;
+      }
+      if (!isNonEmptyString(rel.role)) err(out, `${at}.role`, "missing_field", "role is required (e.g. start, end, package-part)");
+      if (!isDurableId(rel.target)) {
+        err(out, `${at}.target`, "missing_field", "target must name the element id or package part it depends on");
+      }
+    });
+  }
+
+  // A connector without its endpoints and a native object without its package
+  // closure are not obligations at all — they are the exact holes E11 and E17
+  // walk through (same element count, different endpoint; native object whose
+  // dependency was repointed).
+  if ((req.kind === "connection" || req.kind === "native-object") && !(relationships?.length > 0)) {
+    err(
+      out,
+      `${path}.relationships`,
+      "missing_field",
+      `a ${req.kind} requirement must record what it is bound to; without it the obligation cannot be checked`,
+    );
+  }
+  if (req.kind === "image-use" && !isDurableId(req.useId)) {
+    err(
+      out,
+      `${path}.useId`,
+      "missing_field",
+      "an image-use requirement must name the canonical image-intent use id it delegates verification to",
+    );
+  }
+}
+
+/** Validate one slide's entry. `slideKey` is the map key it was stored under. */
+export function validateSlidePreservation(entry, { slideKey = null, path = "preservation" } = {}) {
+  const errors = [];
+  if (!isPlainObject(entry)) {
+    err(errors, path, "invalid_record", "a preservation entry must be an object");
+    return { ok: false, errors };
+  }
+  if (!checkVersion(entry, path, errors)) return { ok: false, errors };
+
+  if (!isDurableId(entry.slideKey)) {
+    err(errors, `${path}.slideKey`, "missing_field", "slideKey must be a durable slide identity, never a position");
+  } else if (slideKey != null && entry.slideKey !== slideKey) {
+    err(
+      errors,
+      `${path}.slideKey`,
+      "slide_key_mismatch",
+      `entry is stored under ${slideKey} but claims ${entry.slideKey}; the index and the record must agree`,
+    );
+  }
+
+  checkEnum(entry.origin, PRESERVATION_ORIGINS, `${path}.origin`, "invalid_value", errors);
+  checkEnum(entry.evidence, EVIDENCE_STATUSES, `${path}.evidence`, "missing_field", errors);
+
+  if (!isPlainObject(entry.baseline)) {
+    err(errors, `${path}.baseline`, "missing_base_revision", "baseline { revision, sourceHash } is required");
+  } else {
+    if (!SHA256_RE.test(String(entry.baseline.sourceHash ?? ""))) {
+      err(
+        errors,
+        `${path}.baseline.sourceHash`,
+        "missing_base_revision",
+        "baseline.sourceHash (sha256 of the source these requirements were taken from) is required",
+      );
+    }
+    if (entry.baseline.revision != null && !isNonEmptyString(entry.baseline.revision)) {
+      err(errors, `${path}.baseline.revision`, "invalid_value", "baseline.revision, when present, must be a string");
+    }
+  }
+
+  if (!Array.isArray(entry.active)) {
+    err(errors, `${path}.active`, "missing_field", "active must be an array of requirements");
+  } else {
+    const seenIds = new Set();
+    const seenIdentities = new Set();
+    entry.active.forEach((req, i) =>
+      validateRequirement(req, `${path}.active[${i}]`, seenIds, seenIdentities, errors),
+    );
+
+    if (!Array.isArray(entry.superseded)) {
+      err(errors, `${path}.superseded`, "missing_field", "superseded must be an array (empty is allowed)");
+    } else {
+      const seenSuperseded = new Set();
+      entry.superseded.forEach((s, i) => {
+        const at = `${path}.superseded[${i}]`;
+        if (!isPlainObject(s)) {
+          err(errors, at, "invalid_record", "a supersession must be an object");
+          return;
+        }
+        if (!isDurableId(s.requirementId)) {
+          err(errors, `${at}.requirementId`, "missing_field", "requirementId is required");
+        } else if (seenSuperseded.has(s.requirementId)) {
+          err(errors, `${at}.requirementId`, "duplicate_requirement_id", `${s.requirementId} is superseded twice`);
+        } else {
+          seenSuperseded.add(s.requirementId);
+        }
+        if (!isNonEmptyString(s.operationId)) {
+          err(
+            errors,
+            `${at}.operationId`,
+            "missing_field",
+            "a supersession names the operation the user authorized it in",
+          );
+        }
+        if (!isNonEmptyString(s.reason)) {
+          err(errors, `${at}.reason`, "missing_field", "a supersession states why the obligation ended");
+        }
+        if (seenIds.has(s.requirementId)) {
+          err(
+            errors,
+            `${at}.requirementId`,
+            "superseded_still_active",
+            `${s.requirementId} is listed as both active and superseded`,
+          );
+        }
+      });
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+/** Validate the whole sidecar: `{ version, slides: { [slideKey]: entry } }`. */
+export function validateSlidePreservationFile(doc, { path = "slide-preservation" } = {}) {
+  const errors = [];
+  if (!isPlainObject(doc)) {
+    err(errors, path, "invalid_record", "the preservation file must be an object");
+    return { ok: false, errors };
+  }
+  if (!checkVersion(doc, path, errors)) return { ok: false, errors };
+  if (!isPlainObject(doc.slides)) {
+    err(errors, `${path}.slides`, "missing_field", "slides must be an object indexed by slideKey");
+    return { ok: false, errors };
+  }
+  for (const [slideKey, entry] of Object.entries(doc.slides)) {
+    errors.push(...validateSlidePreservation(entry, { slideKey, path: `${path}.slides[${slideKey}]` }).errors);
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * The transition rule: what `next` is allowed to have dropped relative to
+ * `previous`.
+ *
+ * `next` must validate on its own, AND every obligation `previous` held must
+ * still be there — unless `next` explicitly supersedes it, naming the operation
+ * that authorized it, and unless that operation is actually scoped to the
+ * slide. A changed `baseline.sourceHash` is expressly NOT a reason: source
+ * changes on every edit, which is why "the file was rewritten" can never be the
+ * argument for dropping a promise.
+ *
+ * @param {unknown} previous the file as it is on disk (null/absent is allowed)
+ * @param {unknown} next     the file the caller wants to write
+ * @param {{ operation?: object }} [opts] the operation authorizing the write
+ */
+export function validatePreservationUpdate(previous, next, { operation = null, path = "slide-preservation" } = {}) {
+  const errors = [...validateSlidePreservationFile(next, { path }).errors];
+  const before = isPlainObject(previous) && isPlainObject(previous.slides) ? previous.slides : {};
+  const after = isPlainObject(next) && isPlainObject(next.slides) ? next.slides : {};
+  const scope = operation ? new Set(operationSlideKeys(operation)) : null;
+  const operationId = isPlainObject(operation) ? operation.operationId : null;
+
+  for (const [slideKey, prevEntry] of Object.entries(before)) {
+    const nextEntry = after[slideKey];
+    if (!isPlainObject(nextEntry)) {
+      err(
+        errors,
+        `${path}.slides[${slideKey}]`,
+        "entry_dropped",
+        `the preservation record for ${slideKey} disappeared; requirements outlive the source they were taken from`,
+      );
+      continue;
+    }
+    const activeNow = new Set(
+      (Array.isArray(nextEntry.active) ? nextEntry.active : []).map((r) => (isPlainObject(r) ? r.requirementId : null)),
+    );
+    const supersededNow = new Map(
+      (Array.isArray(nextEntry.superseded) ? nextEntry.superseded : [])
+        .filter(isPlainObject)
+        .map((s) => [s.requirementId, s]),
+    );
+    const supersededBefore = new Set(
+      (Array.isArray(prevEntry.superseded) ? prevEntry.superseded : [])
+        .filter(isPlainObject)
+        .map((s) => s.requirementId),
+    );
+
+    for (const req of Array.isArray(prevEntry.active) ? prevEntry.active : []) {
+      if (!isPlainObject(req) || !isDurableId(req.requirementId)) continue;
+      if (activeNow.has(req.requirementId)) continue;
+      const supersession = supersededNow.get(req.requirementId);
+      if (!supersession) {
+        err(
+          errors,
+          `${path}.slides[${slideKey}].active`,
+          "requirement_dropped",
+          `requirement ${req.requirementId} was removed without being superseded; ` +
+            `a rewritten slide does not clear its obligations — supersede it in an operation the user asked for`,
+        );
+        continue;
+      }
+      if (operationId && supersession.operationId !== operationId) {
+        err(
+          errors,
+          `${path}.slides[${slideKey}].superseded`,
+          "supersede_unscoped",
+          `requirement ${req.requirementId} claims operation ${supersession.operationId}, ` +
+            `but this write is operation ${operationId}`,
+        );
+      }
+      if (scope && !scope.has(slideKey)) {
+        err(
+          errors,
+          `${path}.slides[${slideKey}].superseded`,
+          "supersede_unscoped",
+          `slide ${slideKey} is not a target of this operation, so its requirements cannot be superseded by it`,
+        );
+      }
+    }
+
+    // A supersession must point at something that was actually owed.
+    for (const [requirementId] of supersededNow) {
+      const wasActive = (Array.isArray(prevEntry.active) ? prevEntry.active : []).some(
+        (r) => isPlainObject(r) && r.requirementId === requirementId,
+      );
+      if (!wasActive && !supersededBefore.has(requirementId)) {
+        err(
+          errors,
+          `${path}.slides[${slideKey}].superseded`,
+          "supersede_unknown",
+          `requirement ${requirementId} was never active on ${slideKey}`,
+        );
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * One target's requirement amendment — the only legal way an obligation leaves
+ * or a requested addition arrives (guide 5.2), shared so both clients retire a
+ * declared removal the same way. Pure: returns the next entry plus what moved.
+ *
+ *   remove  supersede every requirement on that element, naming the operation
+ *           and the base it was declared against
+ *   add     the requested element becomes a requirement in its own right; a
+ *           re-add gets a NEW id (superseded ids are append-only)
+ *   update  nothing here — a permission, read by the verdict, never a narrowing
+ *
+ * Idempotent: a removal already retired and an addition already owed are
+ * skipped, so applying it again (every render, in the add-in) changes nothing.
+ */
+export function amendForOperation(entry, target, operation, { at = new Date().toISOString() } = {}) {
+  const changes = (Array.isArray(target?.changes) ? target.changes : []).filter((c) => isDurableId(c?.elementId));
+  let active = [...(entry?.active ?? [])];
+  const superseded = [...(entry?.superseded ?? [])];
+  const moved = { superseded: [], added: [] };
+  for (const change of changes) {
+    if (change.action === "remove") {
+      for (const req of active.filter((r) => r.elementId === change.elementId)) {
+        superseded.push({
+          requirementId: req.requirementId,
+          operationId: operation.operationId,
+          reason: `removed on request: ${operation.requestSummary}`,
+          baseSourceHash: target.baseSourceHash ?? null,
+          amendedAt: at,
+        });
+        moved.superseded.push(req.requirementId);
+      }
+      active = active.filter((r) => r.elementId !== change.elementId);
+    } else if (change.action === "add") {
+      if (active.some((r) => r.elementId === change.elementId)) continue;
+      const retired = new Set(superseded.map((s) => s.requirementId));
+      let requirementId = `req-element-${change.elementId}`;
+      if (retired.has(requirementId)) requirementId = `${requirementId}@${operation.operationId}`;
+      // Added once per operation: a second pass finds it active and skips it.
+      if (retired.has(requirementId)) continue;
+      active.push({
+        requirementId,
+        elementId: change.elementId,
+        kind: "element",
+        properties: [...(change.properties ?? [])],
+        requestedBy: operation.operationId,
+      });
+      moved.added.push(requirementId);
+    }
+  }
+  if (moved.superseded.length === 0 && moved.added.length === 0) return { entry, ...moved };
+  return { entry: { ...entry, active, superseded }, ...moved };
+}

package/src/lib/slide-selection.mjs

@@ -0,0 +1,9 @@
+// A resolved --only selection is an allowlist, never permission to fall back
+// to the entire deck. Preserve deck order and reject typos before any writes.
+export function selectSlideFiles(files, only = null) {
+  if (only == null) return files;
+  if (!Array.isArray(only) || !only.length) throw new Error("--only requires at least one slide file");
+  const missing = only.filter((name) => !files.includes(name));
+  if (missing.length) throw new Error(`--only: unknown slide file(s): ${missing.join(", ")}`);
+  return files.filter((name) => only.includes(name));
+}

package/src/lib/workspace-transaction.mjs

@@ -0,0 +1,117 @@
+// Stage a complete generation, then activate with a durable undo log. Readers
+// refuse an unfinished activation; the next owner rolls it back before reading.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+const hash = b => createHash('sha256').update(b).digest('hex');
+const durableWrite = (file, bytes) => { const fd = fs.openSync(file, 'w'); try { fs.writeFileSync(fd, bytes); fs.fsyncSync(fd); } finally { fs.closeSync(fd); } };
+const marker = ws => path.join(ws, 'state', 'activation.json');
+const excluded = rel => /^(?:state\/(?:busy\.json|activation\.json|activations(?:\/|$)|staged(?:\/|$)|candidates(?:\/|$)))/.test(rel);
+function files(root, prefix = '', out = new Map()) {
+  if (!fs.existsSync(root)) return out;
+  for (const e of fs.readdirSync(root, { withFileTypes: true })) {
+    const rel = prefix ? `${prefix}/${e.name}` : e.name;
+    if (excluded(rel)) continue;
+    if (e.isSymbolicLink()) throw new Error(`Cannot stage symbolic link ${rel}`);
+    if (e.isDirectory()) files(path.join(root, e.name), rel, out);
+    else out.set(rel, fs.readFileSync(path.join(root, e.name)));
+  }
+  return out;
+}
+export function assertNoActivation(ws) {
+  if (fs.existsSync(marker(ws))) throw Object.assign(new Error('An interrupted workspace activation needs recovery by the next deck owner.'), { code: 'activation_incomplete' });
+}
+export function recoverActivation(ws) {
+  if (!fs.existsSync(marker(ws))) return false;
+  const record = JSON.parse(fs.readFileSync(marker(ws), 'utf8'));
+  if (!/^[0-9a-f-]{36}$/.test(record.id) || !Array.isArray(record.entries)) throw new Error('Invalid activation journal');
+  for (const entry of record.entries) {
+    if (!entry || typeof entry.rel !== 'string' || (!/^\.\.\/(?:[^/\\]+\.xlsx|plan\.html)$/i.test(entry.rel) && (path.isAbsolute(entry.rel) || entry.rel.split(/[\\/]/).includes('..') || excluded(entry.rel))) || !/^\d+$/.test(entry.backup)) throw new Error('Unsafe activation journal path');
+    const backup = path.join(ws, 'state', 'activations', record.id, entry.backup);
+    if (entry.existed && hash(fs.readFileSync(backup)) !== entry.beforeHash) throw new Error('Activation backup is corrupt; recovery refused');
+    const target = path.resolve(ws, entry.rel);
+    const currentHash = fs.existsSync(target) ? hash(fs.readFileSync(target)) : null;
+    if (currentHash !== entry.beforeHash && currentHash !== entry.afterHash) throw new Error('A file changed after the interrupted activation; recovery needs reconciliation');
+    for (let parent = path.dirname(target); parent !== path.dirname(ws); parent = path.dirname(parent)) {
+      if (fs.existsSync(parent) && fs.lstatSync(parent).isSymbolicLink()) throw new Error('Activation recovery refuses a symbolic link');
+      if (parent === path.dirname(parent)) throw new Error('Activation target escapes the deck');
+    }
+  }
+  for (const entry of record.entries) {
+    const target = path.resolve(ws, entry.rel);
+    if (entry.existed) {
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.copyFileSync(path.join(ws, 'state', 'activations', record.id, entry.backup), target);
+    } else fs.rmSync(target, { force: true });
+  }
+  fs.rmSync(marker(ws));
+  return true;
+}
+export function stageWorkspace(ws) {
+  assertNoActivation(ws);
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'slidemind-generation-'));
+  const staged = path.join(root, '.slidemind');
+  fs.mkdirSync(staged, { recursive: true });
+  const original = files(ws);
+  // Workbook artifacts may live exactly one directory above the workspace.
+  if (path.basename(ws) === '.slidemind') {
+    for (const e of fs.readdirSync(path.dirname(ws), { withFileTypes: true })) {
+      if (e.isFile() && (/\.xlsx$/i.test(e.name) || e.name === 'plan.html')) original.set(`../${e.name}`, fs.readFileSync(path.join(ws, '..', e.name)));
+    }
+  }
+  for (const [rel, bytes] of original) {
+    const target = path.resolve(staged, rel);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, bytes);
+  }
+  return {
+    workspace: staged,
+    copySnapshot(revisionId) {
+      if (!/^in-[a-zA-Z0-9-]+$/.test(revisionId)) throw new Error('Invalid staged snapshot id');
+      fs.cpSync(path.join(ws, 'state', 'staged', revisionId), path.join(staged, 'state', 'staged', revisionId), { recursive: true });
+      const busy = path.join(ws, 'state', 'busy.json');
+      if (fs.existsSync(busy)) fs.copyFileSync(busy, path.join(staged, 'state', 'busy.json'));
+    },
+    dispose: () => fs.rmSync(root, { recursive: true, force: true }),
+    activate({ checkpoint = () => {}, fault = () => {} } = {}) {
+      checkpoint();
+      const current = files(ws);
+      for (const [rel] of original) if (rel.startsWith('../') && fs.existsSync(path.resolve(ws, rel))) current.set(rel, fs.readFileSync(path.resolve(ws, rel)));
+      if (current.size !== original.size || [...original].some(([rel, bytes]) => !current.has(rel) || hash(current.get(rel)) !== hash(bytes))) {
+        throw Object.assign(new Error('Workspace changed while staging; nothing activated.'), { code: 'generation_moved' });
+      }
+      const ownerPath = path.join(staged, 'state', 'plan-owner.json');
+      if (fs.existsSync(ownerPath)) {
+        const owner = JSON.parse(fs.readFileSync(ownerPath, 'utf8'));
+        if (typeof owner.reviewCommand === 'string') owner.reviewCommand = owner.reviewCommand.replace(root, path.dirname(ws));
+        fs.writeFileSync(ownerPath, JSON.stringify(owner, null, 2) + '\n');
+      }
+      const next = files(staged);
+      for (const e of fs.readdirSync(root, { withFileTypes: true })) if (e.isFile() && (/\.xlsx$/i.test(e.name) || e.name === 'plan.html')) next.set(`../${e.name}`, fs.readFileSync(path.join(root, e.name)));
+      const changes = [...new Set([...original.keys(), ...next.keys()])].filter(rel => !original.has(rel) || !next.has(rel) || hash(original.get(rel)) !== hash(next.get(rel)));
+      const id = randomUUID();
+      const backupDir = path.join(ws, 'state', 'activations', id);
+      fs.mkdirSync(backupDir, { recursive: true });
+      const entries = changes.map((rel, i) => {
+        const existed = original.has(rel);
+        if (existed) durableWrite(path.join(backupDir, String(i)), original.get(rel));
+        return { rel, existed, backup: String(i), beforeHash: existed ? hash(original.get(rel)) : null, afterHash: next.has(rel) ? hash(next.get(rel)) : null };
+      });
+      durableWrite(`${marker(ws)}.tmp`, JSON.stringify({ id, entries }));
+      fs.renameSync(`${marker(ws)}.tmp`, marker(ws));
+      try {
+        for (const entry of entries) {
+          const target = path.resolve(ws, entry.rel);
+          if (next.has(entry.rel)) {
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            durableWrite(`${target}.activation-tmp`, next.get(entry.rel));
+            fs.renameSync(`${target}.activation-tmp`, target);
+          } else fs.rmSync(target, { force: true });
+          fault(entry.rel);
+        }
+        fs.rmSync(marker(ws));
+      } catch (err) { recoverActivation(ws); throw err; }
+    },
+  };
+}