slidemind 0.3.20 → 0.4.0

package/src/lib/publish.mjs

@@ -0,0 +1,1557 @@
+import { stageWorkspace } from './workspace-transaction.mjs';
+// Pull and publish: the protocol between a deck's local revision state and the
+// item it was opened from.
+//
+// The provider is INJECTED (`provider` — src/bridge/sharepoint.mjs in
+// production, a mock in the suite) so every branch that matters can be driven
+// offline: a 412 mid-publish, a context upload that lands before a deck write
+// that does not, a process death between the two, an equal-size download race, a
+// colleague's save arriving while local work is dirty.
+//
+// The order of operations is the specification, and it is not negotiable:
+//
+//   own → recover → pull → rebase → assess → manifest → artifacts → finalize
+//   → validate → recheck → conditional replace → receipt → advance → callback
+//
+// Four rules the code exists to enforce rather than describe:
+//
+//   1. **Journal before the effect, receipt after the confirmation.** Everything
+//      between those two is `unknown_outcome`, which is inspected, never retried.
+//   2. **Pending refs are not committed refs.** An uploaded context is paired
+//      with nothing until the deck version that names it is the stored one.
+//   3. **Only a confirmed receipt advances the base.** Not a 200 we half-read,
+//      not a later save by someone else, not an optimistic local decision.
+//   4. **Evidence is bound to hashes.** A rebase during the run invalidates the
+//      validation that ran before it; the run re-validates or it stops.
+
+import fs from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+
+import {
+  CANDIDATE_PPTX,
+  acceptCandidateFromReceipt,
+  assertCheckpoint,
+  candidateBytes,
+  candidateDir,
+  candidateStale,
+  computeDirty,
+  readCandidate,
+  readRevision,
+  writeRevision,
+  saveCandidate,
+  stageIncoming,
+  stagedDir,
+} from "./revision.mjs";
+import { applyRebase, classifyRebase, recordConflicts } from "./rebase.mjs";
+import {
+  abandonOperation,
+  bindRemote,
+  acceptReceipt,
+  beginOperation,
+  computeMode,
+  documentInstance,
+  noteObservation,
+  operationOutcome,
+  pendingOperations,
+  readRemote,
+  savedDestination,
+  stepOperation,
+  writeReceipt,
+  writeRemote,
+} from "./remote.mjs";
+import { collectManifest, materializeArtifact, runDeclared } from "./extensions.mjs";
+import {
+  bakePresentationContext,
+  contextDigest,
+  readPresentationContext,
+} from "./presentation-context.mjs";
+import { unzip, zip } from "../pptx/zip.mjs";
+
+export { savedDestination };
+
+const nowIso = () => new Date().toISOString();
+
+// ---------------------------------------------------------------------------
+// shared reads
+// ---------------------------------------------------------------------------
+
+function itemRef(remote) {
+  return { driveId: remote.driveId, itemId: remote.itemId };
+}
+
+/**
+ * Fold the provider's route answers together with this deck's access
+ * evidence and local gates.
+ *
+ * The three inputs stay three inputs all the way down: deployment policy, the
+ * user's grant, and whether this item is writable (usually `unknown`, and that
+ * is fine — the publish itself resolves it).
+ */
+export function decideMode({ provider, client, remote, gates = {}, policy = {} }) {
+  return computeMode({
+    capabilities: provider.capabilities(client.host).routes,
+    access: { read: remote?.access?.read ?? "unknown", write: remote?.access?.write ?? "unknown" },
+    policy,
+    gates,
+  });
+}
+
+/** The context these accepted bytes carry, in the three-answer decode shape. */
+export function contextOfBytes(bytes) {
+  try {
+    return readPresentationContext(unzip(Buffer.from(bytes)));
+  } catch {
+    return { corrupt: "the package could not be read" };
+  }
+}
+
+/**
+ * The extension declarations that apply to this deck.
+ *
+ * A WARM deck keeps the requirements its binding recorded even when the file
+ * came back with its tags stripped — an Office save that drops a custom tag part
+ * must not be able to turn a gated deck into an ordinary deck. A COLD deck
+ * with no binding and no context has nothing to fall back on, which is reported
+ * as unknown origin rather than resolved to "ordinary".
+ */
+export function declaredExtensions(workspaceDir, context) {
+  const remote = readRemote(workspaceDir);
+  const fromContext = context?.context?.extensions ?? null;
+  let owner = null;
+  try { owner = JSON.parse(fs.readFileSync(path.join(workspaceDir, 'state', 'plan-owner.json'), 'utf8'))?.owner; } catch {}
+  const local = typeof owner === 'string' && owner && owner !== 'core' ? [{ id: owner, protocolVersion: 1, required: true }] : [];
+  const remembered = [...(remote?.extensions ?? []), ...local];
+  const declarations = new Map();
+  for (const declaration of [...(fromContext ?? []), ...remembered]) {
+    const existing = declarations.get(declaration.id);
+    declarations.set(declaration.id, existing ? { ...declaration, ...existing, required: existing.required !== false || declaration.required !== false } : declaration);
+  }
+  return {
+    declarations: [...declarations.values()],
+    source: fromContext ? 'context' : remembered.length ? (local.length ? 'owner' : 'binding') : readRevision(workspaceDir)?.origin?.classification === 'ordinary' ? 'classification' : remote && !remote.originUnknown ? 'binding' : 'none',
+  };
+}
+
+/** The dependency refs currently paired with the accepted deck. */
+export function pairedRefs(workspaceDir, context) {
+  const fromContext = (context?.context?.extensions ?? []).flatMap((e) => e.refs ?? []);
+  if (fromContext.length) return fromContext;
+  return readRemote(workspaceDir)?.committedRefs ?? [];
+}
+
+function revisionSummary(workspaceDir) {
+  const revision = readRevision(workspaceDir);
+  const dirty = computeDirty(workspaceDir, revision);
+  return {
+    generation: revision?.generation ?? 0,
+    baseSha256: revision?.base?.sha256 ?? null,
+    inputDigest: dirty.inputDigest,
+    localDirty: dirty.localDirty,
+    dirtySlides: dirty.dirtySlides,
+    unverified: dirty.unverified,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// recovery — always first, before anything new leaves this machine
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve every operation a previous run left open.
+ *
+ * The three outcomes, and why none of them is "try again":
+ *   - a receipt already exists → the commit landed; only local finalization is
+ *     pending, so finish THAT.
+ *   - the phase could have left an effect → ask the provider whether our exact
+ *     bytes are in the item's history. A later save by someone else proves
+ *     nothing about ours.
+ *   - nothing can have happened yet → close the record and move on.
+ */
+// The byte length that pairs with a journalled candidate's sha256 — `saveCandidate`
+// records both from the same buffer, so they cannot disagree. Used only to let a
+// version-history scan skip versions that cannot possibly hash to ours.
+function candidateSize(workspaceDir, operation) {
+  const id = operation?.evidence?.candidateId;
+  const size = id ? readCandidate(workspaceDir, id)?.outputBytes : null;
+  return typeof size === "number" ? size : null;
+}
+
+export async function recoverOperations(workspaceDir, { provider, client, owner, note = () => {} }) {
+  const resolved = [];
+  for (const operation of pendingOperations(workspaceDir)) {
+    const outcome = operationOutcome(workspaceDir, operation);
+    if (outcome.action === "discard") {
+      abandonOperation(workspaceDir, operation.operationId, "nothing had left this machine");
+      resolved.push({ operationId: operation.operationId, action: "discarded" });
+      continue;
+    }
+    if (outcome.action === "resolved") {
+      const finished = await finalizeCommitted(workspaceDir, {
+        operation,
+        receipt: outcome.receipt,
+        owner,
+        note,
+      });
+      resolved.push({ operationId: operation.operationId, action: "finalized", ...finished });
+      continue;
+    }
+    // `inspect`: the only honest question is whether our bytes are there.
+    const remote = readRemote(workspaceDir);
+    if (operation.kind === "rename") {
+      const current = remote ? await provider.getItem(client, itemRef(remote)).catch(() => null) : null;
+      if (current?.name === operation.evidence?.to) {
+        const receipt = writeReceipt(workspaceDir, operation.operationId, { item: current, refs: remote.committedRefs ?? [], route: "rename-recovered" });
+        const finished = await finalizeCommitted(workspaceDir, { operation, receipt, owner, note });
+        resolved.push({ operationId: operation.operationId, action: "recovered", ...finished });
+      } else resolved.push({ operationId: operation.operationId, action: "unresolved", why: "rename outcome is not yet confirmed" });
+      continue;
+    }
+    if (operation.phase === "artifacts") {
+      // Artifact writes cannot be adjudicated by inspecting the presentation.
+      // Keep older/incomplete journals blocked rather than wrongly clearing them.
+      const pending = operation.artifactWrite;
+      if (!pending) {
+        if (["artifacts-done", "validation-blocked", "finalize-candidate"].includes(operation.steps?.at(-1)?.step)) {
+          abandonOperation(workspaceDir, operation.operationId, "all artifact receipts are recorded; presentation write never started");
+          resolved.push({ operationId: operation.operationId, action: "discarded", pendingRefs: operation.pendingRefs ?? [] });
+          continue;
+        }
+        resolved.push({ operationId: operation.operationId, action: "unresolved", why: "artifact outcome lacks target evidence" });
+        continue;
+      }
+      let target = pending.target;
+      if (!target?.itemId) target = await provider.getItemByPath(client, pending.folder, pending.name).catch(() => null);
+      if (!target?.itemId) {
+        resolved.push({ operationId: operation.operationId, action: "unresolved", why: "artifact creation outcome is not confirmed" });
+        continue;
+      }
+      const inspected = await provider.inspectWriteOutcome(client, { driveId: target.driveId, itemId: target.itemId }, { expectedSha256: pending.sha256 });
+      // An IMMUTABLE artifact's name is content-addressed by its own bytes, so the
+      // journal reserved this exact name in this deck's own folder and an item sits
+      // under it: that is the write, whatever the server did to the bytes on the way
+      // in. A MUTABLE one (an owned workbook) keeps a stable name that already
+      // existed before the replace, so the name proves nothing — only the hash does.
+      // Pinning the newest version regardless would pin the version our write was
+      // meant to REPLACE, or a colleague's later save, and report it as ours.
+      if (pending.mutable && !(inspected.landed === true && inspected.superseded !== true)) {
+        const why = inspected.landed === true
+          ? "the artifact's bytes landed but have already been superseded, so no version is honestly ours"
+          : inspected.landed === false
+            ? "the artifact replacement never landed"
+            : `the artifact's outcome could not be read (${inspected.why ?? "unknown"})`;
+        resolved.push({ operationId: operation.operationId, action: "unresolved", why });
+        continue;
+      }
+      // `written` is what arms pinAfterWrite's eTag-moved guard. For a mutable
+      // artifact that is the item we just confirmed holds our bytes, so a save
+      // landing between the check and the pin refuses instead of pinning theirs.
+      const pinned = await pinAfterWrite(provider, client, { driveId: target.driveId, itemId: target.itemId }, pending.mutable ? (inspected.current ?? null) : null);
+      if (pinned.error) {
+        resolved.push({ operationId: operation.operationId, action: "unresolved", why: `artifact found by name but ${pinned.error}` });
+        continue;
+      }
+      const recoveredRef = refFor(client, pending.artifact, target, { versionId: pending.mutable ? pinned.versionId : (inspected.version?.versionId ?? null), mutability: pending.mutable ? "mutable" : "immutable", storedSha256: pinned.storedSha256 });
+      stepOperation(workspaceDir, operation.operationId, { pendingRefs: [...(operation.pendingRefs ?? []), recoveredRef], artifactWrite: null });
+      abandonOperation(workspaceDir, operation.operationId, "artifact outcome recovered; presentation was never written");
+      resolved.push({ operationId: operation.operationId, action: "artifact-recovered", pendingRef: recoveredRef });
+      continue;
+    }
+    const expected = operation.evidence?.candidateSha256;
+    if (!remote && operation.kind === 'create' && operation.destination) {
+      const target = await provider.getItemByPath(client, operation.destination, operation.destination.name).catch(() => null);
+      if (target?.itemId) {
+        const inspected = await provider.inspectWriteOutcome(client, { driveId: target.driveId, itemId: target.itemId }, { expectedSha256: expected, expectedBytes: candidateSize(workspaceDir, operation) });
+        if (inspected.landed === true) {
+          const candidateContext = contextOfBytes(candidateBytes(workspaceDir, operation.evidence.candidateId));
+          bindRemote(workspaceDir, { identity: { provider: 'sharepoint', tenant: new URL(client.host).hostname, driveId: target.driveId, itemId: target.itemId }, labels: { name: target.name, parentId: target.parentId, webUrl: target.webUrl }, extensions: candidateContext?.context?.extensions ?? [] });
+          const receipt = writeReceipt(workspaceDir, operation.operationId, { item: target, version: inspected.version, candidateId: operation.evidence.candidateId, candidateSha256: expected, refs: operation.pendingRefs ?? [], route: 'create-recovered' });
+          const finished = await finalizeCommitted(workspaceDir, { operation, receipt, owner, note });
+          resolved.push({ operationId: operation.operationId, action: 'recovered', receipt, ...finished });
+          continue;
+        }
+      }
+    }
+    if (!remote || !expected) {
+      note(
+        `operation ${operation.operationId} cannot be resolved (no binding or no candidate hash on record) — ` +
+          `it is left open and blocks publishing.`,
+      );
+      resolved.push({ operationId: operation.operationId, action: "unresolved" });
+      continue;
+    }
+    const inspection = await provider.inspectWriteOutcome(client, itemRef(remote), {
+      expectedSha256: expected,
+      expectedBytes: candidateSize(workspaceDir, operation),
+    });
+    if (inspection.landed === true) {
+      const receipt = writeReceipt(workspaceDir, operation.operationId, {
+        item: inspection.current ?? null,
+        version: inspection.version ?? null,
+        candidateId: operation.evidence?.candidateId ?? null,
+        candidateSha256: expected,
+        refs: operation.pendingRefs ?? [],
+        route: operation.evidence?.route ?? "recovered",
+        supersededByNewerRevision: Boolean(inspection.superseded),
+      });
+      const finished = await finalizeCommitted(workspaceDir, { operation, receipt, owner, note });
+      note(
+        inspection.superseded
+          ? `the interrupted publish DID land; a newer revision has since replaced it, and that newer ` +
+              `revision is staged for you to reconcile.`
+          : `the interrupted publish had already landed — nothing was uploaded again.`,
+      );
+      resolved.push({ operationId: operation.operationId, action: "recovered", receipt, ...finished });
+      continue;
+    }
+    if (inspection.landed === false) {
+      abandonOperation(
+        workspaceDir,
+        operation.operationId,
+        "inspection found our bytes in no stored version",
+      );
+      note(`the interrupted publish never landed — the candidate is intact and can be published again.`);
+      resolved.push({ operationId: operation.operationId, action: "never-landed" });
+      continue;
+    }
+    note(
+      `the outcome of operation ${operation.operationId} could not be determined (${inspection.why}). ` +
+        `Nothing will be re-uploaded until it is.`,
+    );
+    resolved.push({ operationId: operation.operationId, action: "unknown", why: inspection.why });
+  }
+  return resolved;
+}
+
+/**
+ * Everything that happens locally AFTER the server confirmed: the base advances
+ * to the bytes that were stored, committed refs replace pending refs, and the
+ * extensions are told. The callback is idempotent and its failure never causes a
+ * re-upload — "saved remotely, local finalization pending" is a real state and
+ * says so.
+ */
+export async function finalizeCommitted(workspaceDir, { operation, receipt, owner, note = () => {} }) {
+  const candidateId = receipt.candidateId ?? operation?.evidence?.candidateId ?? null;
+  let advanced = null;
+  const revision = readRevision(workspaceDir);
+  if (candidateId && revision?.acceptedCandidate?.candidateId !== candidateId) {
+    try {
+      advanced = acceptCandidateFromReceipt(workspaceDir, candidateId, { owner, receipt });
+    } catch (err) {
+      // The remote copy IS saved. Failing to move the local base is a local
+      // problem with a local remedy, and saying "publish failed" here would send
+      // the user to re-upload bytes that are already there.
+      note(
+        `saved remotely, but the local accepted base could not be advanced (${err?.message ?? err}). ` +
+          `The receipt is on disk; re-run publish to finish the local half.`,
+      );
+      return { advanced: false, callbackFailed: true, finalizationPending: true };
+    }
+  }
+  acceptReceipt(workspaceDir, receipt);
+  const context = contextOfBytes(candidateId ? candidateBytes(workspaceDir, candidateId) ?? [] : []);
+  const { declarations } = declaredExtensions(workspaceDir, context);
+  const callback = runDeclared(workspaceDir, declarations, "committed", {
+    operationId: operation?.operationId ?? receipt.operationId,
+    revision: revisionSummary(workspaceDir),
+    receipt,
+    context: context?.context ?? null,
+  });
+  const callbackFailed = callback.blockers.length > 0;
+  stepOperation(workspaceDir, receipt.operationId, {
+    phase: callbackFailed ? "committed" : "finalized",
+    step: callbackFailed ? "callback-failed" : "finalized",
+    committedRefs: receipt.refs ?? [],
+    pendingRefs: [],
+  });
+  if (callbackFailed) {
+    note(
+      `saved remotely; the extension callback did not complete (${callback.blockers[0]?.message}). ` +
+        `It is idempotent — re-running publish retries the callback, not the upload.`,
+    );
+  }
+  return { advanced: Boolean(advanced), callbackFailed };
+}
+
+// ---------------------------------------------------------------------------
+// pull
+// ---------------------------------------------------------------------------
+
+/**
+ * Has anything changed remotely?
+ *
+ * Deliberately metadata-only. Ten unchanged pulls of an ordinary deck make ten
+ * metadata calls and download nothing — no content request, no conversion, no
+ * derived context version, no remote write of any kind.
+ *
+ * A rename is detected separately from a content change: same content identity,
+ * different name. It updates labels and nothing else, because re-hydrating a
+ * deck because somebody retitled the file is pure waste.
+ */
+export async function checkFreshness(workspaceDir, { provider, client }) {
+  const remote = readRemote(workspaceDir);
+  if (!remote) {
+    const e = new Error("this deck is not bound to a remote copy");
+    e.code = "identity_unresolved";
+    throw e;
+  }
+  let item;
+  try {
+    item = await provider.getItem(client, itemRef(remote));
+  } catch (err) {
+    // A failed observation NEVER refreshes lastPulledAt: a timestamp that says
+    // "checked just now" when the check failed is worse than a stale one.
+    noteObservation(workspaceDir, { failure: { code: err?.code ?? "offline", message: err?.message } });
+    throw err;
+  }
+  const contentSame = remote.acceptedCTag
+    ? item.cTag === remote.acceptedCTag
+    : item.eTag === remote.acceptedETag;
+  const renamed = item.name !== remote.name;
+  const dependencies = await checkDependencies(workspaceDir, { provider, client });
+  noteObservation(workspaceDir, {
+    revision: {
+      eTag: item.eTag,
+      cTag: item.cTag,
+      size: item.size,
+      lastModifiedDateTime: item.lastModifiedDateTime,
+    },
+    labels: renamed && contentSame ? { name: item.name, webUrl: item.webUrl } : {},
+  });
+  return {
+    item,
+    changed: !contentSame,
+    renameOnly: contentSame && renamed,
+    dependencies,
+    dependencyChanges: dependencies.filter((d) => d.changed),
+  };
+}
+
+/**
+ * Independently mutable inputs are checked EVEN WHEN the deck's own eTag is
+ * unchanged. A workbook someone edited this morning is an incoming business
+ * change; the deck bytes that reference it did not move, and a check that only
+ * looked at the deck would report "current" about content that no longer is.
+ *
+ * The pinned version stays pinned. What this produces is an OBSERVATION of the
+ * latest version, never a replacement of the approved one.
+ */
+export async function checkDependencies(workspaceDir, { provider, client, refs: pendingRefs = null }) {
+  const remote = readRemote(workspaceDir);
+  const refs = (pendingRefs ?? remote?.committedRefs ?? []).filter((r) => r.mutability === "mutable");
+  const out = [];
+  for (const ref of refs) {
+    if (!ref.driveId || !ref.itemId) continue;
+    let item = null;
+    try {
+      item = await provider.getItem(client, { driveId: ref.driveId, itemId: ref.itemId });
+    } catch (err) {
+      out.push({ ref, error: err?.code ?? "offline", changed: false, unreadable: true });
+      continue;
+    }
+    const latest = { eTag: item.eTag, cTag: item.cTag, size: item.size, name: item.name };
+    // Changed against the stored bytes this deck paired with (the ref's sha256
+    // is the server's hash, not the local upload's — see refFor).
+    let contentChanged = true;
+    if (ref.sha256) {
+      try {
+        const snapshot = await provider.downloadSnapshot(client, { driveId: ref.driveId, itemId: ref.itemId });
+        contentChanged = snapshot.sha256 !== ref.sha256;
+      } catch (err) {
+        out.push({ ref, error: err?.code ?? "offline", changed: true, unreadable: true });
+        continue;
+      }
+    }
+    out.push({
+      ref,
+      latest,
+      // Changed against the version this deck is PAIRED with, not against the
+      // last thing we happened to see.
+      changed: contentChanged,
+      pinnedVersionId: ref.versionId ?? null,
+    });
+  }
+  if (out.length && readRemote(workspaceDir)) {
+    const remoteNow = readRemote(workspaceDir);
+    // Only ever ANNOTATE an existing binding. `{...null}` would write a record
+    // carrying nothing but observations; bindRemote then reads that stub as "bound
+    // to a different item" and throws rebind_required, so a first publish that
+    // happens to carry a mutable dependency could never write its receipt and the
+    // next attempt would 404 on the stub and re-create into a name_conflict.
+    writeRemote(workspaceDir, {
+      ...remoteNow,
+      dependencyObservations: Object.fromEntries(
+        out.filter((d) => d.latest).map((d) => [d.ref.artifactId, { ...d.latest, at: nowIso() }]),
+      ),
+    });
+  }
+  return out;
+}
+
+/**
+ * Pull: check, stage, and merge at an owned checkpoint.
+ *
+ * Staging is unconditional and harmless — immutable bytes under a
+ * revision-specific path, never a working file. Activation is the part that
+ * needs everything to line up: no slide changed on both sides, nothing
+ * half-written, ownership still ours, and the business side content with what
+ * arrived. Unpublished local edits are merged AROUND, never touched.
+ */
+export async function pullDeck(workspaceDir, { provider, client, owner, note = () => {} }) {
+  const freshness = await checkFreshness(workspaceDir, { provider, client });
+  if (!freshness.changed) {
+    return {
+      status: freshness.renameOnly ? "renamed" : "current",
+      ...freshness,
+      activated: false,
+    };
+  }
+
+  const snapshot = await provider.downloadSnapshot(client, itemRef(readRemote(workspaceDir)));
+  const staged = stageIncoming(workspaceDir, {
+    bytes: snapshot.bytes,
+    source: {
+      kind: "remote",
+      provider: readRemote(workspaceDir)?.provider ?? "sharepoint",
+      itemId: readRemote(workspaceDir)?.itemId ?? null,
+      eTag: snapshot.revision?.eTag ?? null,
+      cTag: snapshot.revision?.cTag ?? null,
+      versionId: snapshot.revision?.versionId ?? null,
+      at: nowIso(),
+    },
+  });
+  // The incoming PPTX names its own exact context. It is fetched and staged with
+  // the bytes, as ONE candidate incoming set — pairing the new deck with the old
+  // deck's approved context would be a quieter version of the same loss this
+  // whole change exists to stop.
+  const incomingContext = contextOfBytes(snapshot.bytes);
+  const stagedContext = await stageIncomingContext(workspaceDir, staged.revisionId, incomingContext, {
+    provider,
+    client,
+    note,
+  });
+
+  const requiredErrors = stagedContext.filter(a => a.error);
+  if (requiredErrors.length || incomingContext?.corrupt || ((readRemote(workspaceDir)?.extensions ?? []).some(e => e.required !== false && !(incomingContext?.context?.extensions ?? []).some(i => i.id === e.id && i.required !== false)))) {
+    return { status: 'staged', ...freshness, staged, stagedContext, activated: false, reason: 'artifact_missing' };
+  }
+  const summary = revisionSummary(workspaceDir);
+  if (summary.localDirty) {
+    // Unpublished work here does not hold a merge up; a slide BOTH sides
+    // changed does. The rebase below never touches a local edit — it takes
+    // their slides around it and leaves every local change unpublished.
+    const classified = classifyRebase(workspaceDir, staged.revisionId);
+    if (classified.conflicts.length) {
+      recordConflicts(workspaceDir, classified);
+      note(
+        `${classified.conflicts.length} slide(s) changed on both sides, so the incoming save was staged ` +
+          `as ${staged.revisionId} and nothing local was touched.`,
+      );
+      return {
+        status: "staged",
+        ...freshness,
+        staged,
+        stagedContext,
+        conflicts: classified.conflicts,
+        activated: false,
+        reason: "needs_reconcile",
+      };
+    }
+  }
+
+  assertCheckpoint(workspaceDir, {
+    owner,
+    generation: summary.generation,
+    digest: summary.inputDigest,
+  });
+  const tx = stageWorkspace(workspaceDir);
+  try {
+    tx.copySnapshot(staged.revisionId);
+    const rebase = applyRebase(tx.workspace, staged.revisionId, { owner, staged: true });
+    const remote = readRemote(workspaceDir);
+    writeRemote(tx.workspace, {
+      ...remote,
+      acceptedETag: snapshot.revision?.eTag ?? remote.acceptedETag,
+      acceptedCTag: snapshot.revision?.cTag ?? remote.acceptedCTag,
+      acceptedSha256: snapshot.sha256,
+      name: freshness.item.name, webUrl: freshness.item.webUrl, lastPulledAt: nowIso(),
+      extensions: incomingContext?.context?.extensions ?? remote.extensions ?? [],
+      committedRefs: incomingContext?.context?.extensions?.flatMap(e => e.refs ?? []) ?? remote.committedRefs ?? [],
+    });
+    const { declarations } = declaredExtensions(tx.workspace, incomingContext);
+    // Resolve artifacts from the exact pinned snapshots already verified above.
+    const pinnedProvider = { ...provider,
+      downloadVersion: async (_client, ref, version) => {
+        const pin = declarations.flatMap(e => e.refs ?? []).find(r => r.driveId === ref.driveId && r.itemId === ref.itemId && r.versionId === version);
+        const artifact = stagedContext.find(a => a.artifactId === pin?.artifactId && a.sha256 === pin?.sha256);
+        if (!artifact?.file) throw new Error('Required pinned artifact is not staged');
+        return fs.readFileSync(artifact.file);
+      },
+    };
+    const hydrated = await hydrateContext(tx.workspace, { provider: pinnedProvider, client, context: incomingContext, note, staged: true });
+    if (hydrated.blockers?.length) return { status: 'staged', ...freshness, staged, stagedContext, activated: false, reason: 'validation_required', blockers: hydrated.blockers };
+    const assessment = runDeclared(tx.workspace, declarations, 'assess', {
+      revision: revisionSummary(tx.workspace), dependencies: pairedRefs(tx.workspace, incomingContext),
+      context: incomingContext?.context ?? null, incoming: { revisionId: staged.revisionId, sha256: snapshot.sha256 },
+    });
+    if (assessment.blockers.length) return { status: 'staged', ...freshness, staged, stagedContext, assessment, activated: false, reason: 'validation_required' };
+    tx.activate({ checkpoint: () => assertCheckpoint(workspaceDir, { owner, generation: summary.generation, digest: summary.inputDigest }) });
+    return { status: 'activated', ...freshness, staged, stagedContext, rebase, assessment, activated: true };
+  } finally { tx.dispose(); }
+
+}
+
+/** Fetch and stage the exact artifacts an incoming deck's context pins. */
+async function stageIncomingContext(workspaceDir, revisionId, context, { provider, client, note }) {
+  const refs = (context?.context?.extensions ?? []).flatMap((e) => e.refs ?? []);
+  if (!refs.length) return [];
+  const dir = path.join(stagedDir(workspaceDir, revisionId), "context");
+  fs.mkdirSync(dir, { recursive: true });
+  const out = [];
+  for (const ref of refs) {
+    if (!ref.driveId || !ref.itemId) {
+      out.push({ artifactId: ref.artifactId, error: 'artifact_missing' });
+      continue;
+    }
+    try {
+      const bytes = ref.versionId
+        ? await provider.downloadVersion(client, { driveId: ref.driveId, itemId: ref.itemId }, ref.versionId)
+        : (await provider.downloadSnapshot(client, { driveId: ref.driveId, itemId: ref.itemId })).bytes;
+      const file = path.join(dir, `${ref.sha256}-${ref.artifactId}`.replace(/[^A-Za-z0-9._-]/g, "-"));
+      if (!ref.sha256 || createHash("sha256").update(bytes).digest("hex") !== ref.sha256) {
+        throw Object.assign(new Error("pinned artifact hash mismatch"), { code: "artifact_hash_mismatch" });
+      }
+      fs.writeFileSync(file, bytes);
+      out.push({ artifactId: ref.artifactId, sha256: ref.sha256, file, bytes: bytes.length });
+    } catch (err) {
+      // An unreadable or deleted pinned version BLOCKS the dependent edit rather
+      // than substituting the latest — substituting is how a deck quietly starts
+      // citing numbers nobody approved.
+      note(
+        `the exact version of '${ref.artifactId}' this save was approved against could not be read ` +
+          `(${err?.message ?? err}); work depending on it is blocked rather than paired with the latest.`,
+      );
+      out.push({ artifactId: ref.artifactId, error: err?.code ?? "unreadable" });
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// publish
+// ---------------------------------------------------------------------------
+
+/**
+ * Publish a validated candidate back to the bound item.
+ *
+ * Returns a discriminated result rather than throwing for the expected outcomes,
+ * because every one of them is a state the user needs told about precisely:
+ * `committed`, `needs_reconcile`, `blocked`, `manual`, `unknown`.
+ */
+export async function publishDeck(
+  workspaceDir,
+  {
+    provider,
+    client,
+    owner,
+    candidateId = null,
+    manual = false,
+    destination = null,
+    sharedWorkbookAuthority = false,
+    note = () => {},
+    onProgress = null,
+  },
+) {
+  const binding = readRemote(workspaceDir);
+  if (binding && destination) throw new Error('A bound deck cannot use --folder/--name; explicitly rebind it first.');
+  // First publish without --folder/--name: the folder the workspace saved
+  // (contracts §2 destination.json) stands in for the flags. Explicit flags
+  // win; a bound deck never consults it; every gate below runs unchanged.
+  let destinationSource = destination ? 'explicit' : null;
+  if (!binding && !destination) {
+    const saved = savedDestination(workspaceDir);
+    if (saved) {
+      destination = { driveId: saved.driveId, parentId: saved.parentId, name: saved.name };
+      destinationSource = 'saved';
+    }
+  }
+  const remote = binding ?? (destination ? { provider: 'sharepoint', tenant: new URL(client.host).hostname, driveId: destination.driveId, parentId: destination.parentId, name: destination.name, deckId: `deck-${randomUUID()}`, documentInstance: null, extensions: [], committedRefs: [] } : null);
+  // The deck that CREATES its workbook owns it: authority is recorded in the
+  // binding on the first create and inherited by every later publish, so the
+  // workbook is one SharePoint item with native version history, like the
+  // deck. A cold copy of the deck gets a fork binding that records no
+  // authority and keeps forking — the case the default exists to protect.
+  const workbookAuthority = Boolean(destination) || sharedWorkbookAuthority || Boolean(binding?.sharedWorkbookAuthority);
+  if (!remote) {
+    const e = new Error("this deck is not bound to a remote copy — `slidemind open <link>` binds one.");
+    e.code = "identity_unresolved";
+    throw e;
+  }
+
+  // 1. Recover anything a previous run left open. A deck with an unresolved
+  //    outcome does not get to start a second write.
+  const recovered = await recoverOperations(workspaceDir, { provider, client, owner, note });
+  const unresolved = recovered.filter((r) => r.action === "unknown" || r.action === "unresolved");
+  if (unresolved.length) {
+    return { status: "blocked", reason: "unknown_outcome", recovered, blockers: [] };
+  }
+
+  if (!binding && readRemote(workspaceDir)) {
+    const committed = recovered.find(r => r.receipt);
+    if (committed) return { status: 'committed', receipt: committed.receipt, recovered };
+    return { status: 'blocked', reason: 'unknown_outcome', recovered };
+  }
+
+  // 2. Pull and reconcile FIRST. Publishing onto a base somebody else has moved
+  //    is the overwrite this protocol exists to make impossible.
+  const pull = destination ? { status: "current", item: {} } : await pullDeck(workspaceDir, { provider, client, owner, note });
+  const dependencies = await checkDependencies(workspaceDir, { provider, client });
+  if (dependencies.some((d) => d.changed || d.unreadable)) {
+    return { status: "needs_reconcile", reason: "needs_reconcile", dependencies };
+  }
+  if (pull.status === "staged") {
+    // `staged` rides at the top level so the renderer can name the rebase.
+    return { status: "needs_reconcile", reason: "needs_reconcile", pull, staged: pull.staged ?? null };
+  }
+  if (pull.status === "activated") {
+    // Their save is merged in, so every candidate was built on a base that is
+    // no longer current. Publish never renders: the next build does.
+    return { status: "needs_reconcile", reason: "merged", pull };
+  }
+
+  // 3. The candidate. `build-pptx` produces it; publish never renders, so there
+  //    is exactly one place a deck's bytes come from.
+  const revision = readRevision(workspaceDir);
+  const chosen = candidateId ?? revision?.candidate ?? null;
+  const candidate = chosen ? readCandidate(workspaceDir, chosen) : null;
+  const why = candidateStale(workspaceDir, candidate, revision);
+  if (why) {
+    return {
+      status: "blocked",
+      reason: "validation_required",
+      message: candidate
+        ? `candidate ${chosen} cannot be published: ${why}. Re-run \`slidemind build-pptx\`.`
+        : `this deck has no candidate to publish — run \`slidemind build-pptx\` first.`,
+    };
+  }
+
+  // 4. Mode. Policy, grant, route proof and item access are four separate
+  //    questions and this is where they meet.
+  const bytes = candidateBytes(workspaceDir, candidate.candidateId);
+  const sizing = provider.routeForSize(client.host, bytes.length);
+  const context = contextOfBytes(bytes);
+  const { declarations, source: contextSource } = declaredExtensions(workspaceDir, context);
+
+  // 5. The required gates, on the CURRENT content. A generic publish cannot
+  //    walk past an extension's release checks, and there is no headless flag
+  //    that skips them.
+  const manifest = runDeclared(workspaceDir, declarations, "manifest", {
+    revision: revisionSummary(workspaceDir),
+    dependencies: pairedRefs(workspaceDir, context),
+    context: context?.context ?? null,
+  });
+  const gates = {
+    extensionMissing: manifest.missing.some((m) => m.required && m.blocker?.code === "extension_missing"),
+    extensionIncompatible: manifest.blockers.some((b) => b.code === "extension_incompatible"),
+    contextMissing:
+      Boolean(context?.corrupt) || (contextSource === "none" && (revision?.origin?.kind ?? "") !== "authored"),
+  };
+  let decision = decideMode({ provider, client, remote, gates,
+    policy: manual ? { remoteSavingDisabled: true } : {} });
+  if (destination && !manual && !gates.contextMissing && !manifest.blockers.length) decision = { ...decision, mode: 'automatic', canPublish: true, reason: null };
+  if (decision.mode === "blocked" || manifest.blockers.length || gates.contextMissing) {
+    return {
+      status: "blocked",
+      reason: decision.reason ?? "extension_missing",
+      decision,
+      blockers: manifest.blockers,
+    };
+  }
+  const collected = collectManifest(workspaceDir, mergeArtifacts(manifest), { extensionId: null });
+  if (collected.problems.length) {
+    return { status: "blocked", reason: "validation_required", blockers: collected.problems };
+  }
+  if (decision.mode !== "automatic") {
+    const unresolved = collected.artifacts.filter(a => a.uploadable).map(a => ({ artifactId: a.artifactId, purpose: a.purpose ?? 'attachment', required: a.required !== false, mutability: 'immutable', sha256: a.sha256, bytes: a.bytes }));
+    const manualContext = finalizeContext({ context, remote, refs: unresolved, owners: new Map(collected.artifacts.map(a => [a.artifactId, a.extensionId])), declarations, operationId: context?.context?.operationId ?? `manual-${candidate.candidateId}` });
+    const manualCandidate = saveCandidate(workspaceDir, { bytes: withContext(bytes, manualContext), validation: candidate.validation, review: candidate.review });
+    const validation = runDeclared(workspaceDir, declarations, "validate", {
+      revision: revisionSummary(workspaceDir),
+      dependencies: pairedRefs(workspaceDir, context),
+      context: context?.context ?? null,
+      candidate: { candidateId: manualCandidate.candidateId, sha256: manualCandidate.outputSha256,
+        bytes: manualCandidate.outputBytes, path: path.join(candidateDir(workspaceDir, manualCandidate.candidateId), CANDIDATE_PPTX) },
+    });
+    if (validation.blockers.length) return { status: "blocked", reason: "validation_required", blockers: validation.blockers };
+    const handoff = await prepareManualHandoff(workspaceDir, {
+      candidate: manualCandidate,
+      manifest,
+      context: { context: manualContext },
+      decision,
+      note,
+    });
+    return { status: "manual", reason: decision.reason, decision, handoff };
+  }
+
+  // 6. What will be uploaded, decided before anything leaves. The allowlist is
+  //    exactly the declared artifacts — never a glob, never the workspace.
+  const changed = collected.artifacts.filter(
+    (a) => a.uploadable && !alreadyCommitted(remote, a),
+  );
+
+  const operation = beginOperation(workspaceDir, {
+    kind: destination ? "create" : "publish",
+    destination,
+    deck: {
+      provider: remote.provider,
+      driveId: remote.driveId,
+      itemId: remote.itemId,
+      expectedETag: pull.item.eTag,
+    },
+    evidence: {
+      candidateId: candidate.candidateId,
+      candidateSha256: candidate.outputSha256,
+      baseSha256: candidate.baseSha256,
+      inputDigest: candidate.inputDigest,
+      generation: candidate.generation,
+      route: destination ? "create" : sizing.large ? "conditionalLarge" : "conditionalSmall",
+    },
+    plannedArtifacts: changed.map((a) => ({
+      artifactId: a.artifactId,
+      purpose: a.purpose,
+      mutability: a.mutability,
+      sha256: a.sha256,
+      bytes: a.bytes,
+    })),
+  });
+
+  // 7. Artifacts, before the deck. A context that exists without a deck naming
+  //    it is harmless; a deck naming a context that does not exist is not.
+  stepOperation(workspaceDir, operation.operationId, { phase: "artifacts", step: "artifacts" });
+  const uploaded = await uploadArtifacts(workspaceDir, {
+    provider,
+    client,
+    remote,
+    artifacts: changed,
+    sharedWorkbookAuthority: workbookAuthority,
+    operationId: operation.operationId,
+    note,
+  });
+  if (uploaded.failed.length) {
+    stepOperation(workspaceDir, operation.operationId, {
+      step: "artifacts-failed",
+      pendingRefs: uploaded.refs,
+    });
+    return {
+      status: "blocked",
+      reason: uploaded.failed[0].reason ?? "target_access_denied",
+      message: `an artifact could not be written: ${uploaded.failed[0].why}`,
+      operation,
+      partial: uploaded,
+    };
+  }
+  stepOperation(workspaceDir, operation.operationId, { pendingRefs: uploaded.refs, step: "artifacts-done" });
+
+  // 8. Finalize the tag against the refs that actually resolved, in a NEW
+  //    immutable candidate — the bytes that are validated are the bytes that
+  //    are uploaded.
+  const movedInputs = candidateStale(workspaceDir, candidate);
+  if (movedInputs) {
+    abandonOperation(workspaceDir, operation.operationId, "candidate inputs changed during artifact preparation");
+    return { status: "blocked", reason: "validation_required", message: movedInputs, pendingRefs: uploaded.refs };
+  }
+  const finalContext = finalizeContext({
+    context,
+    remote,
+    refs: uploaded.refs,
+    owners: uploaded.owners,
+    declarations,
+    operationId: operation.operationId,
+  });
+  const finalBytes = withContext(bytes, finalContext);
+  // Same reason the journal restates the hash below: the ROUTE has to be judged
+  // on the bytes that go on the wire. Baking the finalized context grows the
+  // package, so a candidate sitting just under the single-PUT ceiling crosses it
+  // here — and the small route answers an oversized PUT with a 413, which is an
+  // `unknown` outcome that blocks publishing and repeats on every retry.
+  const finalSizing = provider.routeForSize(client.host, finalBytes.length);
+  const finalCandidate = saveCandidate(workspaceDir, {
+    bytes: finalBytes,
+    validation: candidate.validation,
+    review: candidate.review,
+  });
+  // The journal must name the bytes that will actually be UPLOADED. Baking the
+  // finalized context changed them, so leaving the pre-finalization hash here
+  // would send crash recovery looking for a package that was never sent — and it
+  // would answer "never landed" about a write that did.
+  stepOperation(workspaceDir, operation.operationId, {
+    step: "finalize-candidate",
+    pendingRefs: finalContext.extensions.flatMap((e) => e.refs ?? []),
+    evidence: {
+      ...operation.evidence,
+      candidateId: finalCandidate.candidateId,
+      candidateSha256: finalCandidate.outputSha256,
+      contextDigest: contextDigest(finalContext),
+      route: destination ? "create" : finalSizing.large ? "conditionalLarge" : "conditionalSmall",
+    },
+  });
+
+  // 9. Required release checks on the FINAL bytes and the FINAL dependencies.
+  //    Evidence from before the refs resolved describes different content.
+  const validation = runDeclared(workspaceDir, declarations, "validate", {
+    operationId: operation.operationId,
+    revision: revisionSummary(workspaceDir),
+    dependencies: finalContext.extensions.flatMap((e) => e.refs ?? []),
+    context: finalContext,
+    candidate: {
+      candidateId: finalCandidate.candidateId,
+      sha256: finalCandidate.outputSha256,
+      bytes: finalBytes.length,
+      path: path.join(candidateDir(workspaceDir, finalCandidate.candidateId), CANDIDATE_PPTX),
+    },
+  });
+  if (validation.blockers.length) {
+    stepOperation(workspaceDir, operation.operationId, { step: "validation-blocked" });
+    return {
+      status: "blocked",
+      reason: "validation_required",
+      blockers: validation.blockers,
+      operation,
+      pendingRefs: uploaded.refs,
+    };
+  }
+
+  // 10. Recheck immediately before the write. The If-Match is the eTag observed
+  //     NOW — never one silently carried from step 2.
+  const fresh = destination ? {} : await provider.getItem(client, itemRef(remote));
+  const finalDependencies = await checkDependencies(workspaceDir, { provider, client, refs: finalContext.extensions.flatMap((e) => e.refs ?? []) });
+  if (finalDependencies.some((d) => d.changed || d.unreadable)) {
+    abandonOperation(workspaceDir, operation.operationId, "a paired dependency changed before the write");
+    return { status: "needs_reconcile", reason: "needs_reconcile", dependencies: finalDependencies, pendingRefs: uploaded.refs };
+  }
+  if (fresh.eTag !== pull.item.eTag || fresh.cTag !== pull.item.cTag) {
+    note("the item changed while this publish was preparing — nothing was written.");
+    abandonOperation(workspaceDir, operation.operationId, "the item moved before the write");
+    return { status: "needs_reconcile", reason: "needs_reconcile", observed: fresh, pendingRefs: uploaded.refs };
+  }
+
+  stepOperation(workspaceDir, operation.operationId, { phase: "deck-write", step: "replace" });
+  const changedCandidate = candidateStale(workspaceDir, finalCandidate);
+  if (changedCandidate) {
+    abandonOperation(workspaceDir, operation.operationId, "candidate inputs changed before replacement");
+    return { status: "blocked", reason: "validation_required", message: changedCandidate, pendingRefs: uploaded.refs };
+  }
+  const write = destination ? await provider.createConflictFail(client, destination, destination.name, finalBytes) : finalSizing.large
+    ? await provider.replaceLarge(client, itemRef(remote), finalBytes, {
+        ifMatch: fresh.eTag,
+        onProgress,
+      })
+    : await provider.replaceSmall(client, itemRef(remote), finalBytes, { ifMatch: fresh.eTag });
+
+  if (write.outcome === "unknown") {
+    // The one state that must never resolve itself optimistically. The record
+    // stays at `deck-write`; the next run inspects.
+    stepOperation(workspaceDir, operation.operationId, { step: "unknown-outcome", why: write.why });
+    return { status: "unknown", reason: "unknown_outcome", why: write.why, operation, pendingRefs: uploaded.refs };
+  }
+  if (write.outcome === "refused") {
+    if (write.reason === "needs_reconcile") {
+      // A 412 is this mechanism working. Candidate and accepted base are kept;
+      // the newer save is staged for reconciliation.
+      const snapshot = await provider.downloadSnapshot(client, itemRef(remote));
+      const staged = stageIncoming(workspaceDir, {
+        bytes: snapshot.bytes,
+        source: { kind: "remote", reason: "412", at: nowIso(), eTag: snapshot.revision?.eTag ?? null },
+      });
+      abandonOperation(workspaceDir, operation.operationId, "the expected revision no longer matched");
+      return {
+        status: "needs_reconcile",
+        reason: "needs_reconcile",
+        staged,
+        pendingRefs: uploaded.refs,
+      };
+    }
+    abandonOperation(workspaceDir, operation.operationId, `refused: ${write.reason}`);
+    return { status: "blocked", reason: write.reason, operation, pendingRefs: uploaded.refs };
+  }
+
+  // 11. Confirmed. Identity is checked before anything advances — a 200 that
+  //     describes a different item is not our commit.
+  if (!destination && write.item?.itemId && write.item.itemId !== remote.itemId) {
+    return {
+      status: "unknown",
+      reason: "unknown_outcome",
+      why: `the write was confirmed against item ${write.item.itemId}, not the bound ${remote.itemId}`,
+      operation,
+    };
+  }
+  if (destination) {
+    if (!write.item?.itemId) return { status: 'unknown', reason: 'unknown_outcome', operation };
+    // Same evidence `open` records: the create just proved read AND write on
+    // this item, and `ready` reports the mode from disk, so a binding without
+    // capabilities would read as "manual" until the next open.
+    bindRemote(workspaceDir, {
+      identity: { provider: 'sharepoint', tenant: remote.tenant, driveId: write.item.driveId, itemId: write.item.itemId },
+      labels: { name: write.item.name, parentId: write.item.parentId, webUrl: write.item.webUrl },
+      deckId: remote.deckId,
+      extensions: finalContext.extensions,
+      access: { read: 'allowed', write: 'allowed' },
+      capabilities: provider.capabilities(client.host).routes,
+      // This deck created its shared inputs, so it owns them from here on.
+      sharedWorkbookAuthority: true,
+    });
+  }
+  const receipt = writeReceipt(workspaceDir, operation.operationId, {
+    item: write.item,
+    version: write.version,
+    candidateId: finalCandidate.candidateId,
+    candidateSha256: finalCandidate.outputSha256,
+    refs: finalContext.extensions.flatMap((e) => e.refs ?? []),
+    route: write.route,
+  });
+  const finished = await finalizeCommitted(workspaceDir, { operation, receipt, owner, note });
+  // `--shared-workbook` on a binding that lacked authority grants it for good:
+  // the workbook this publish replaced or created is now this deck's to keep
+  // replacing, without the flag on every later run.
+  if (workbookAuthority && !readRemote(workspaceDir)?.sharedWorkbookAuthority) {
+    writeRemote(workspaceDir, { ...readRemote(workspaceDir), sharedWorkbookAuthority: true });
+  }
+  return { status: "committed", receipt, operation, destination: destinationSource, ...finished };
+}
+
+// Every extension's artifacts, in one list the collector can walk — each tagged
+// with the extension that declared it, so the finalized context puts each ref
+// back under its own owner rather than under whoever happened to be first.
+function mergeArtifacts(manifest) {
+  return {
+    artifacts: manifest.results.flatMap((r) =>
+      (r.response.artifacts ?? []).map((a) => ({ ...a, extensionId: r.id })),
+    ),
+  };
+}
+
+// An artifact whose exact bytes are already committed needs no upload. Local
+// timestamps and dirty flags deliberately play no part: they change on every
+// build, and letting them cause a context version would republish a deck's
+// approved plan because someone opened it.
+function alreadyCommitted(remote, artifact) {
+  return (remote?.committedRefs ?? []).some(
+    (ref) => ref.artifactId === artifact.artifactId && ref.sha256 === artifact.sha256 && ref.driveId && ref.itemId && (ref.mutability !== "mutable" || ref.versionId),
+  );
+}
+
+/**
+ * Write the changed durable artifacts and return the portable refs that pair
+ * with them.
+ *
+ * Immutable artifacts are content-addressed and created with conflict-fail: an
+ * existing object with the SAME bytes is reused, and one with different bytes is
+ * never overwritten — a published immutable context is somebody's evidence.
+ *
+ * A mutable artifact (the shared workbook) is replaced only with explicit
+ * authority, and only when the exact version it becomes can be pinned. The
+ * default is fork-on-change, because silently editing the origin's workbook from
+ * a copy of the deck is the worst outcome in this whole protocol.
+ */
+export async function uploadArtifacts(
+  workspaceDir,
+  { provider, client, remote, artifacts, sharedWorkbookAuthority, operationId, note },
+) {
+  const refs = [];
+  const failed = [];
+  // Which extension owns each ref. Kept BESIDE the refs rather than on them:
+  // a portable ref carries storage identity and nothing else, and adding a
+  // convenience field to it would fail the whitelist that keeps it portable.
+  const owners = new Map();
+  const folder = { driveId: remote.driveId, parentId: remote.parentId };
+  for (const artifact of artifacts) {
+    owners.set(artifact.artifactId, artifact.extensionId ?? null);
+    const bytes = fs.readFileSync(artifact.file);
+    if (createHash("sha256").update(bytes).digest("hex") !== artifact.sha256) {
+      failed.push({ artifactId: artifact.artifactId, why: "artifact changed after manifest validation", reason: "validation_required" });
+      break;
+    }
+    const owned = artifact.mutability === "mutable" && sharedWorkbookAuthority;
+    const bound = owned ? (remote.committedRefs ?? []).find((r) => r.artifactId === artifact.artifactId) : null;
+    const name = artifactName(remote, artifact, owned ? "owned" : artifact.mutability === "mutable" ? "fork" : "immutable");
+    stepOperation(workspaceDir, operationId, { artifactWrite: {
+      artifact: { artifactId: artifact.artifactId, purpose: artifact.purpose, required: artifact.required, sha256: artifact.sha256, bytes: artifact.bytes },
+      sha256: artifact.sha256, mutable: owned, folder, name,
+      target: bound ?? null,
+    }, pendingRefs: refs });
+    if (artifact.mutability === "mutable") {
+      if (!owned) {
+        note(
+          `'${artifact.artifactId}' is a shared mutable input and this deck has no declared authority ` +
+            `over it, so it is forked rather than overwritten. Pass --shared-workbook to change that.`,
+        );
+      }
+      // Owned: the first publish creates the item under its stable name, every
+      // later one replaces that same item under If-Match. Not owned: a
+      // content-addressed fork, reused when the bytes did not change.
+      const result = owned
+        ? bound
+          ? await replaceMutable(provider, client, remote, artifact, bytes)
+          : await createMutable(provider, client, folder, artifact, bytes, name)
+        : await createImmutable(provider, client, folder, artifact, bytes, name);
+      if (result.error) {
+        failed.push({ artifactId: artifact.artifactId, why: result.error, reason: result.reason });
+        break;
+      }
+      refs.push(result.ref);
+      stepOperation(workspaceDir, operationId, { pendingRefs: refs, artifactWrite: null });
+      continue;
+    }
+    const result = await createImmutable(provider, client, folder, artifact, bytes, name);
+    if (result.error) {
+      failed.push({ artifactId: artifact.artifactId, why: result.error, reason: result.reason });
+      break;
+    }
+    refs.push(result.ref);
+    stepOperation(workspaceDir, operationId, { pendingRefs: refs, artifactWrite: null });
+  }
+  return { refs, failed, owners };
+}
+
+/**
+ * What an artifact is called next to the deck. The deck's own file stem leads,
+ * so a folder reads as one deck rather than a pile of hashes:
+ *
+ *   owned      <deck>-calculation-workbook.xlsx          one item, versioned in place
+ *   immutable  <deck>-<artifact>-1a2b3c4d.json     content-addressed, reused on equal bytes
+ *   fork       <deck>-calculation-workbook-fork-1a2b3c4d.xlsx   ditto — a republish of unchanged
+ *                                                          bytes must not add a file
+ */
+export function artifactName(remote, artifact, kind) {
+  const deck = String(remote?.name ?? "deck").replace(/\.pptx$/i, "").replace(/[^A-Za-z0-9._-]/g, "-");
+  const id = String(artifact.artifactId).replace(/[^A-Za-z0-9._-]/g, "-");
+  const ext = path.extname(artifact.file || "") || "";
+  const hash = artifact.sha256.slice(0, 8);
+  if (kind === "owned") return `${deck}-${id}${ext}`;
+  if (kind === "fork") return `${deck}-${id}-fork-${hash}${ext}`;
+  return `${deck}-${id}-${hash}${ext}`;
+}
+
+// The exact version an item holds these bytes under — the only honest pairing
+// for a mutable artifact, since an eTag says "unchanged since" and is not a
+// content address.
+// A ref's `sha256` is the hash of what the SERVER stores, read back after the
+// write. SharePoint rewrites an Office package on upload (observed live
+// 2026-09-17: a workbook came back 1.9 KB larger, with `[trash]/*.dat` parts and
+// custom XML added), so the bytes we sent are not a usable identity for any
+// artifact of any type — and a cold machine, which only has the ref, must be
+// able to verify what it downloads against it. The extension keeps its own
+// local hash; the `committed` callback hands it the stored one.
+async function storedIdentity(provider, client, target) {
+  const stored = await provider.downloadSnapshot(client, target).catch(() => null);
+  return stored?.sha256 ?? null;
+}
+
+async function pinAfterWrite(provider, client, target, written, { attempts = 5, delayMs = 1500 } = {}) {
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    const current = await provider.getItem(client, target).catch(() => null);
+    if (current && written?.eTag && current.eTag !== written.eTag) {
+      return { error: "the item moved on before its version could be pinned", reason: "needs_reconcile" };
+    }
+    // The newest version IS ours as long as the eTag still matches the write.
+    // SharePoint lists it a moment after the write returns, hence the retry.
+    const versions = await provider.listVersions(client, target).catch(() => []);
+    if (versions.length) {
+      return { versionId: versions[0].versionId, storedSha256: await storedIdentity(provider, client, target) };
+    }
+    if (attempt < attempts - 1) await new Promise((resolve) => setTimeout(resolve, delayMs));
+  }
+  return { error: "no version was listed for the write, so it cannot be pinned", reason: "conditional_write_unsupported" };
+}
+
+async function createMutable(provider, client, folder, artifact, bytes, name) {
+  const created = await createImmutable(provider, client, folder, artifact, bytes, name);
+  if (created.error) return created;
+  const target = { driveId: created.ref.driveId, itemId: created.ref.itemId };
+  const pinned = await pinAfterWrite(provider, client, target, created.written ?? null);
+  if (pinned.error) return { error: `'${artifact.artifactId}' was created but ${pinned.error}`, reason: pinned.reason };
+  return { ref: refFor(client, artifact, created.written, { versionId: pinned.versionId, mutability: "mutable", storedSha256: pinned.storedSha256 }) };
+}
+
+async function createImmutable(provider, client, folder, artifact, bytes, name) {
+  const existing = await provider.getItemByPath(client, folder, name).catch(() => null);
+  if (existing) {
+    // The name is content-addressed by the local bytes' hash (or, for an owned
+    // mutable input, reserved for this deck), so an item under it was written
+    // from these bytes — by this deck, possibly by an attempt that died before
+    // it could journal the answer. Its identity is what the server holds now.
+    const storedSha256 = await storedIdentity(provider, client, { driveId: existing.driveId, itemId: existing.itemId });
+    return { ref: refFor(client, artifact, existing, { versionId: null, storedSha256 }), written: existing, reused: true };
+  }
+  // The deck's own write routes by size (`routeForSize`); this one had no such
+  // check, so an artifact above the single-PUT ceiling 413'd into an
+  // `unknown` outcome that blocks publishing and repeats the same oversized PUT
+  // on every retry. There is no create-through-session route, so refuse plainly.
+  const sizing = provider.routeForSize(client.host, bytes.length);
+  if (sizing.large) {
+    return {
+      error: `'${artifact.artifactId}' is ${bytes.length} bytes; a new artifact cannot exceed ${sizing.smallMaxBytes}`,
+      reason: "conditional_write_unsupported",
+    };
+  }
+  const result = await provider.createConflictFail(client, folder, name, bytes);
+  if (result.outcome !== "committed") {
+    return {
+      error: result.why ?? `creating '${name}' was refused (${result.reason})`,
+      reason: result.reason ?? "unknown_outcome",
+    };
+  }
+  const storedSha256 = await storedIdentity(provider, client, { driveId: result.item.driveId, itemId: result.item.itemId });
+  return { ref: refFor(client, artifact, result.item, { versionId: null, storedSha256 }), written: result.item };
+}
+
+async function replaceMutable(provider, client, remote, artifact, bytes) {
+  const ref = (remote.committedRefs ?? []).find((r) => r.artifactId === artifact.artifactId);
+  if (!ref?.itemId) {
+    return { error: `'${artifact.artifactId}' has no bound item to replace`, reason: "identity_unresolved" };
+  }
+  const target = { driveId: ref.driveId, itemId: ref.itemId };
+  const current = await provider.getItem(client, target);
+  // The ref's sha256 is what the server stored at the pairing; the item is
+  // unchanged if it still hashes to that.
+  const snapshot = await provider.downloadSnapshot(client, target);
+  if (snapshot.sha256 !== ref.sha256 || (snapshot.revision?.eTag && snapshot.revision.eTag !== current.eTag)) {
+    return { error: `'${artifact.artifactId}' changed since its approved pairing`, reason: "needs_reconcile" };
+  }
+  // Same routing rule as the deck's own write: above the single-PUT ceiling the
+  // bytes go through an upload session. Without this a large shared workbook 413'd
+  // into an `unknown` outcome the deck could never clear or retry past.
+  const sizing = provider.routeForSize(client.host, bytes.length);
+  const result = sizing.large
+    ? await provider.replaceLarge(client, target, bytes, { ifMatch: current.eTag })
+    : await provider.replaceSmall(client, target, bytes, { ifMatch: current.eTag });
+  if (result.outcome !== "committed") {
+    return {
+      error: result.why ?? `replacing '${artifact.artifactId}' was refused (${result.reason})`,
+      reason: result.reason ?? "unknown_outcome",
+    };
+  }
+  const pinned = await pinAfterWrite(provider, client, target, result.item);
+  if (pinned.error) return { error: `'${artifact.artifactId}' was replaced but ${pinned.error}`, reason: pinned.reason };
+  return { ref: refFor(client, artifact, result.item, { versionId: pinned.versionId, mutability: "mutable", storedSha256: pinned.storedSha256 }) };
+}
+
+function refFor(client, artifact, item, { versionId, mutability = "immutable", storedSha256 = null }) {
+  return {
+    artifactId: artifact.artifactId,
+    purpose: artifact.purpose,
+    required: artifact.required !== false,
+    mutability,
+    provider: "sharepoint",
+    tenant: new URL(client.host).hostname,
+    host: new URL(client.host).hostname,
+    driveId: item.driveId,
+    itemId: item.itemId,
+    ...(versionId ? { versionId } : {}),
+    // The stored bytes' hash — the one a download can be checked against.
+    sha256: storedSha256 ?? artifact.sha256,
+    bytes: artifact.bytes,
+  };
+}
+
+/**
+ * The context these exact bytes will ship with.
+ *
+ * Refs that resolved in THIS run replace the ones they supersede; every other
+ * ref the deck was already paired with is carried forward unchanged. An
+ * artifact nobody re-uploaded keeps pointing at the exact version it was
+ * approved against, which is the whole point of pinning it.
+ */
+export function finalizeContext({ context, remote, refs, owners, declarations, operationId }) {
+  const previous = context?.context ?? {};
+  const fresh = new Map(refs.map((r) => [r.artifactId, r]));
+  const ownerOf = owners ?? new Map();
+  return {
+    v: 1,
+    deckId: remote.deckId ?? previous.deckId ?? remote.documentInstance,
+    documentInstance: remote.documentInstance,
+    ...(previous.brand ? { brand: previous.brand } : {}),
+    ...(previous.intent ? { intent: previous.intent } : {}),
+    extensions: (declarations ?? []).map((d) => {
+      const paired = [...(d.refs ?? []), ...(remote.committedRefs ?? []).filter((r) =>
+        !(d.refs ?? []).some((p) => p.artifactId === r.artifactId) &&
+        (ownerOf.get(r.artifactId) ?? (declarations.length === 1 ? d.id : null)) === d.id)];
+      const carried = paired.map((r) => fresh.get(r.artifactId) ?? r);
+      const known = new Set(carried.map((r) => r.artifactId));
+      const added = refs.filter(
+        (r) => !known.has(r.artifactId) && (ownerOf.get(r.artifactId) ?? d.id) === d.id,
+      );
+      return {
+        id: d.id,
+        protocolVersion: 1,
+        ...(d.dataVersion !== undefined ? { dataVersion: d.dataVersion } : {}),
+        required: d.required !== false,
+        refs: [...carried, ...added],
+      };
+    }),
+    operationId,
+  };
+}
+
+/** Bake a context into a package's bytes, returning the new bytes. */
+export function withContext(bytes, context) {
+  const files = unzip(Buffer.from(bytes));
+  bakePresentationContext(files, context);
+  return Buffer.from(zip(files));
+}
+
+// ---------------------------------------------------------------------------
+// the manual branch
+// ---------------------------------------------------------------------------
+
+/**
+ * Everything a read-only or manual deck needs to be published by hand: the
+ * validated .pptx, the required external context, the changed attachments, and
+ * one short instruction per file with its exact hash.
+ *
+ * Refs that could not be resolved carry `artifactId` + `sha256` placeholders
+ * rather than invented remote identities, and the status is
+ * `pendingManualUpload` — never `saved`. A later authorized read recognizes the
+ * actual upload by content, which is evidence; it is NOT a claim that the
+ * browser upload had any of the concurrency protection a conditional write has.
+ */
+export async function prepareManualHandoff(
+  workspaceDir,
+  { candidate, manifest, context, decision, note = () => {} },
+) {
+  const outDir = path.join(workspaceDir, "state", "handoff", candidate.candidateId);
+  fs.mkdirSync(outDir, { recursive: true });
+  const deckFile = path.join(outDir, "deck.pptx");
+  fs.writeFileSync(deckFile, candidateBytes(workspaceDir, candidate.candidateId));
+
+  const collected = collectManifest(workspaceDir, mergeArtifacts(manifest), { extensionId: null });
+  const files = [
+    {
+      role: "deck",
+      file: deckFile,
+      sha256: candidate.outputSha256,
+      bytes: candidate.outputBytes,
+      instruction: "upload this file over the existing presentation, keeping its name",
+    },
+  ];
+  for (const artifact of collected.artifacts) {
+    if (!artifact.uploadable) continue;
+    const copy = path.join(outDir, `${artifact.extensionId}-${artifact.artifactId}`.replace(/[^a-zA-Z0-9._-]/g, "-") + path.extname(artifact.file));
+    fs.copyFileSync(artifact.file, copy);
+    files.push({
+      role: artifact.purpose ?? "attachment",
+      artifactId: artifact.artifactId,
+      file: copy,
+      sha256: artifact.sha256,
+      bytes: artifact.bytes,
+      required: artifact.required !== false,
+      instruction: `upload beside the presentation; the deck refers to it as ${artifact.artifactId}`,
+    });
+  }
+  const manifestFile = path.join(outDir, "handoff.json");
+  const record = {
+    schemaVersion: 1,
+    status: "pendingManualUpload",
+    preparedAt: nowIso(),
+    reason: decision?.reason ?? null,
+    mode: decision?.mode ?? null,
+    candidateId: candidate.candidateId,
+    candidateSha256: candidate.outputSha256,
+    contextDigest: context?.context ? contextDigest(context.context) : null,
+    // Unresolved refs are placeholders, deliberately. A fabricated remote id
+    // here would later be indistinguishable from one that was really created.
+    unresolvedRefs: collected.artifacts
+      .filter((a) => a.uploadable)
+      .map((a) => ({ artifactId: a.artifactId, sha256: a.sha256, resolved: false })),
+    files: files.map((f) => ({ ...f, file: path.relative(workspaceDir, f.file) })),
+  };
+  fs.writeFileSync(manifestFile, `${JSON.stringify(record, null, 2)}\n`);
+  const remote = readRemote(workspaceDir);
+  if (remote) {
+    writeRemote(workspaceDir, {
+      ...remote,
+      pendingCandidateId: candidate.candidateId,
+      manualHandoff: { at: nowIso(), dir: path.relative(workspaceDir, outDir) },
+    });
+  }
+  note(`prepared a manual handoff in ${outDir} — nothing was written to SharePoint.`);
+  return { dir: outDir, manifest: manifestFile, record };
+}
+
+// ---------------------------------------------------------------------------
+// rename
+// ---------------------------------------------------------------------------
+
+/**
+ * Rename the bound item. Identity does not move, no deck is rendered, and no
+ * second file is created — the receipt refreshes labels only. Accepted content
+ * markers remain unchanged until pull proves which bytes they represent.
+ */
+export async function renameBound(workspaceDir, { provider, client, name, note = () => {} }) {
+  const remote = readRemote(workspaceDir);
+  if (!remote) {
+    const e = new Error("this deck is not bound to a remote copy");
+    e.code = "identity_unresolved";
+    throw e;
+  }
+  const current = await provider.getItem(client, itemRef(remote));
+  const operation = beginOperation(workspaceDir, {
+    kind: "rename",
+    deck: { driveId: remote.driveId, itemId: remote.itemId, expectedETag: current.eTag },
+    evidence: { from: current.name, to: name },
+  });
+  stepOperation(workspaceDir, operation.operationId, { phase: "deck-write", step: "rename" });
+  const result = await provider.renameItem(client, itemRef(remote), name, { ifMatch: current.eTag });
+  if (result.outcome === "unknown") {
+    return { status: "unknown", reason: "unknown_outcome", why: result.why, operation };
+  }
+  if (result.outcome === "refused") {
+    abandonOperation(workspaceDir, operation.operationId, `rename refused: ${result.reason}`);
+    return { status: "blocked", reason: result.reason, name };
+  }
+  if (result.item?.itemId && result.item.itemId !== remote.itemId) {
+    return {
+      status: "unknown",
+      reason: "unknown_outcome",
+      why: "the rename was confirmed against a different item",
+      operation,
+    };
+  }
+  const receipt = writeReceipt(workspaceDir, operation.operationId, {
+    item: result.item,
+    version: result.version,
+    candidateId: null,
+    candidateSha256: null,
+    refs: remote.committedRefs ?? [],
+    route: "rename",
+  });
+  // Labels move independently of accepted content. The item may already have
+  // contained an unseen colleague save before this rename.
+  const after = readRemote(workspaceDir);
+  writeRemote(workspaceDir, {
+    ...after,
+    name: result.item?.name ?? name,
+    webUrl: result.item?.webUrl ?? after.webUrl,
+    // A successful rename proves only the label, never acceptance of its bytes.
+    // Preserve both markers so an intervening colleague save still requires pull.
+    lastReceipt: { operationId: operation.operationId, confirmedAt: receipt.confirmedAt, route: "rename" },
+    pendingOperationId: null,
+  });
+  stepOperation(workspaceDir, operation.operationId, { phase: "finalized", step: "finalized" });
+  note(`renamed to ${result.item?.name ?? name}; the deck still publishes to the same item.`);
+  return { status: "committed", receipt, name: result.item?.name ?? name };
+}
+
+// ---------------------------------------------------------------------------
+// cold open: is this the document the context thinks it is?
+// ---------------------------------------------------------------------------
+
+/**
+ * Compare the context's physical identity with the item the user's link actually
+ * resolved to.
+ *
+ * `own`       the same document — carry on.
+ * `fork`      a different one, or one that cannot be verified. The logical id is
+ *             reminted and mutable context is forked before anything is changed;
+ *             immutable refs may be shared, because sharing an immutable object
+ *             cannot damage the original.
+ * `unknown`   no context at all and no local binding — inspection is fine,
+ *             managed publication is not, because the absence of metadata is not
+ *             proof that no business gate ever applied.
+ */
+export function classifyInstance({ context, resolved, remote }) {
+  const here = documentInstance({
+    provider: "sharepoint",
+    tenant: resolved.tenant,
+    driveId: resolved.driveId,
+    itemId: resolved.itemId,
+  });
+  const claimed = context?.context?.documentInstance ?? null;
+  if (claimed && here && claimed === here) return { kind: "own", instance: here };
+  if (claimed && here && claimed !== here) {
+    return {
+      kind: "fork",
+      instance: here,
+      why: "these bytes were published to a different item — this is a copy",
+      shareImmutable: true,
+    };
+  }
+  if (!claimed && remote?.documentInstance === here) {
+    // Warm deck whose tags were stripped by a host save. The binding remembers
+    // what this is; the loss is reported, the gates are not dropped.
+    return { kind: "own", instance: here, tagsLost: true };
+  }
+  if (!claimed) return { kind: "unknown", instance: here };
+  return { kind: "fork", instance: here, why: "the document instance could not be verified" };
+}
+
+/** Everything a hydrated artifact needs, fetched and written under containment. */
+export async function hydrateContext(workspaceDir, { provider, client, context, note = () => {}, staged = false, companions = {} }) {
+  if (!staged) {
+    const tx = stageWorkspace(workspaceDir);
+    try {
+      const result = await hydrateContext(tx.workspace, { provider, client, context, note, staged: true, companions });
+      if (!result.blockers.length) tx.activate();
+      return { ...result, written: result.written.map(p => ({ ...p, path: path.resolve(workspaceDir, path.relative(tx.workspace, p.path)) })) };
+    } finally { tx.dispose(); }
+  }
+  const blockers = [];
+  const { declarations } = declaredExtensions(workspaceDir, context);
+  const hydrate = runDeclared(workspaceDir, declarations, "hydrate", {
+    revision: revisionSummary(workspaceDir),
+    dependencies: pairedRefs(workspaceDir, context),
+    context: context?.context ?? null,
+  });
+  const written = [];
+  for (const result of hydrate.results) {
+    for (const artifact of result.response.artifacts ?? []) {
+      const ref = (result.declaration.refs ?? []).find((r) => r.artifactId === artifact.artifactId);
+      if ((!ref?.driveId || !ref?.itemId) && !companions[artifact.artifactId]) {
+        if (artifact.required !== false) blockers.push({ code: 'artifact_missing', message: `No pinned ref for ${artifact.artifactId}` });
+        continue;
+      }
+      try {
+        const bytes = companions[artifact.artifactId] ?? (ref.versionId
+          ? await provider.downloadVersion(client, { driveId: ref.driveId, itemId: ref.itemId }, ref.versionId)
+          : (await provider.downloadSnapshot(client, { driveId: ref.driveId, itemId: ref.itemId })).bytes);
+        // `ref` is deliberately allowed to be absent when a --companion supplies the
+        // bytes (the guard above admits exactly that case), so its hash must be read
+        // optionally — `ref.sha256` threw a TypeError that the catch below turned
+        // into an `artifact_missing` blocker, failing the one case the guard exists for.
+        const sha256 = ref?.sha256 ?? artifact.sha256 ?? null;
+        const placement = materializeArtifact(workspaceDir, { ...artifact, extensionId: result.id, sha256 }, bytes);
+        if (placement.isolated && artifact.required !== false) blockers.push({ code: 'artifact_missing', message: `Unsafe materialization path for ${artifact.artifactId}` });
+        written.push(placement);
+        if (!placement.isolated) {
+          const registryPath = path.join(workspaceDir, "state", "artifact-materializations.json");
+          let registry = { artifacts: [] };
+          try { registry = JSON.parse(fs.readFileSync(registryPath, "utf8")); } catch {}
+          registry.artifacts = (registry.artifacts ?? []).filter((a) => !(a.extensionId === result.id && a.artifactId === artifact.artifactId));
+          registry.artifacts.push({ extensionId: result.id, artifactId: artifact.artifactId, localPath: path.relative(workspaceDir, placement.path), sha256 });
+          fs.mkdirSync(path.dirname(registryPath), { recursive: true });
+          fs.writeFileSync(`${registryPath}.tmp`, JSON.stringify(registry));
+          fs.renameSync(`${registryPath}.tmp`, registryPath);
+        }
+      } catch (err) {
+        if (artifact.required !== false) blockers.push({ code: 'artifact_missing', message: `${artifact.artifactId}: ${err.message}` });
+        note(`'${artifact.artifactId}' could not be restored: ${err?.message ?? err}`);
+      }
+    }
+  }
+  const restored = written.length ? runDeclared(workspaceDir, declarations, "hydrate", {
+    revision: revisionSummary(workspaceDir), dependencies: pairedRefs(workspaceDir, context), context: context?.context ?? null,
+  }) : hydrate;
+  const slides = restored.results.flatMap((r) => r.response.hydrate?.slides ?? []);
+  return { hydrate, written, blockers: [...blockers, ...restored.blockers], slides: [...new Set(slides)].sort((a, b) => a - b) };
+}
+
+/** Explicit classification cannot erase remembered or embedded business gates. */
+export function classifyOrdinary(workspaceDir, context) {
+  const remote = readRemote(workspaceDir);
+  if (context?.corrupt || declaredExtensions(workspaceDir, context).declarations.length) throw Object.assign(new Error('Recover the declared context; --ordinary cannot remove business gates.'), { code: 'validation_required' });
+  const revision = readRevision(workspaceDir);
+  if (!revision) throw new Error('Adopt the deck before classifying it.');
+  writeRevision(workspaceDir, { ...revision, origin: { ...revision.origin, classification: 'ordinary', classifiedAt: nowIso() } });
+  if (remote) writeRemote(workspaceDir, { ...remote, originUnknown: false, ordinary: true });
+}
+