slidemind 0.3.20 → 0.4.0

package/src/lib/remote.mjs

@@ -0,0 +1,661 @@
+import { assertNoActivation } from './workspace-transaction.mjs';
+// The remote half of a deck's revision state: which item it publishes to, what
+// this machine last observed there, what a publish is allowed to do, and the
+// durable record an interrupted write is recovered from.
+//
+// Everything here is SYNC and filesystem-only — the same shape contract as
+// `revision.mjs`, and for the same reason: a pack and the provider
+// client both read these records and cannot import each other.
+//
+//   state/remote.json                 the binding + capabilities + last receipt
+//   state/operations/<operationId>.json   journaled BEFORE any external write
+//   state/receipts/<operationId>.json     written only on a CONFIRMED commit
+//
+// Three rules the file exists to keep:
+//
+//   1. **Physical identity is the binding.** provider/tenant/host/driveId/itemId
+//      select the target; name/webUrl/path are labels that a rename changes and
+//      nothing routes on. A tag inside a .pptx never redirects a publish.
+//   2. **Journal before the write, receipt after the confirmation.** An
+//      operation record exists before the first byte leaves; the receipt exists
+//      only once the server has named the version it committed. A crash between
+//      the two is `unknown_outcome`, which is INSPECTED, never retried blindly.
+//   3. **Policy, grant, route support and item access are four things.** A
+//      readable item is not a writable one, a 403 is not a consent verdict, and
+//      an unproved conditional route disables automatic publication even when
+//      everything else is allowed.
+
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+export const SCHEMA_VERSION = 1;
+
+export const REMOTE_FILE = "remote.json";
+export const OPERATIONS_DIR = "operations";
+export const RECEIPTS_DIR = "receipts";
+
+/**
+ * Every typed reason a remote operation can be blocked or degraded by, from the
+ * design's §1 list. `publish`/`pull`/`ready` return ALL that apply and pick one
+ * stable primary — a caller that switches on a single string still gets a
+ * deterministic answer, and a caller that renders the list gets the whole truth.
+ *
+ * Ordered by how much they decide: the earlier reason is the primary one.
+ */
+export const REASONS = [
+  // the deck is not pointed anywhere / cannot be pointed anywhere
+  "identity_unresolved",
+  "remote_missing",
+  "context_missing",
+  // deployment or tenant policy said no before any request was made
+  "remote_saving_disabled",
+  "write_scope_missing",
+  "consent_required",
+  // the provider refused THIS item, or an artifact's exact version cannot be pinned
+  "target_access_denied",
+  "conditional_write_unsupported",
+  // a required local gate has not passed
+  "extension_missing",
+  "extension_incompatible",
+  "validation_required",
+  "needs_reconcile",
+  // a previous operation left the world in a state only inspection resolves
+  "unknown_outcome",
+  "snapshot_raced",
+  // transient
+  "throttled",
+  "offline",
+];
+
+/** Capability answers are three-valued: never infer the third from the other two. */
+export const SUPPORT = ["supported", "unsupported", "unknown"];
+export const ACCESS = ["allowed", "denied", "unknown"];
+
+/** The routes a provider adapter reports on, independently. */
+export const ROUTES = [
+  "read",
+  "create",
+  "rename",
+  "conditionalSmall",
+  "conditionalLarge",
+  "exactVersionRead",
+];
+
+/**
+ * What a deck may do with its remote copy right now.
+ *
+ * - `automatic` — a protected publish may be ATTEMPTED. Not a promise it will
+ *   succeed: item write access can still be `unknown` until the write happens.
+ * - `read-only` — reads work, managed writes are ineligible.
+ * - `manual`  — reads are unavailable; the deck exports a validated handoff.
+ * - `blocked` — a local gate must clear first (reconcile, extension, unknown
+ *   outcome); nothing remote is attempted.
+ */
+export const MODES = ["automatic", "read-only", "manual", "blocked"];
+
+const nowIso = () => new Date().toISOString();
+
+function stateDir(workspaceDir, ...sub) {
+  return path.join(workspaceDir, "state", ...sub);
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// Write-then-rename: a kill mid-write must not leave half a JSON record where
+// the operation journal is supposed to be.
+function writeJson(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + "\n");
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+// ---------------------------------------------------------------------------
+// the binding
+// ---------------------------------------------------------------------------
+
+/**
+ * The physical identity of one stored document, as one comparable string.
+ *
+ * This is what a portable context's `documentInstance` carries and what a cold
+ * open compares against the item the user's own link resolved to. Name, path and
+ * webUrl are deliberately absent: a rename must not read as a different document,
+ * and a moved file inside one drive is still the same file.
+ */
+export function documentInstance({ provider, tenant, driveId, itemId }) {
+  if (!provider || !tenant || !driveId || !itemId) return null;
+  return `${provider}:${tenant}:${driveId}:${itemId}`;
+}
+
+export function remotePath(workspaceDir) {
+  return stateDir(workspaceDir, REMOTE_FILE);
+}
+
+export function readRemote(workspaceDir) {
+  assertNoActivation(workspaceDir);
+  const data = readJson(remotePath(workspaceDir));
+  return data?.schemaVersion === SCHEMA_VERSION ? data : null;
+}
+
+/**
+ * `destination.json` as a create target, or null. Folder identity plus the
+ * saved presentation name — the folder the user connected in the workspace
+ * (src/workspace/remote-status.mjs writes it), where the first publish creates
+ * the file. A malformed or nameless file is ignored here — the workspace card
+ * reports it, publish just behaves as if no folder was chosen.
+ */
+export function savedDestination(workspaceDir) {
+  const saved = readJson(stateDir(workspaceDir, "destination.json"));
+  if (saved?.schemaVersion !== 1 || !saved.driveId || !saved.itemId || !saved.pptxName) return null;
+  if (!/\.pptx$/i.test(saved.pptxName) || /[\\/]/.test(saved.pptxName)) return null;
+  return { driveId: saved.driveId, parentId: saved.itemId, name: saved.pptxName, backendURL: saved.backendURL ?? null };
+}
+
+export function writeRemote(workspaceDir, remote) {
+  const record = { ...remote, schemaVersion: SCHEMA_VERSION, updatedAt: nowIso() };
+  writeJson(remotePath(workspaceDir), record);
+  return record;
+}
+
+/**
+ * Point a deck at an item. `identity` is the physical half and is never merged
+ * from an existing record — binding somewhere else is a REBIND, which the caller
+ * decides explicitly; this only refuses to do it silently.
+ *
+ * Throws `rebind_required` when a different item is already bound, so no caller
+ * can repoint a deck by forgetting to ask.
+ */
+export function bindRemote(
+  workspaceDir,
+  { identity, labels = {}, rebind = false, ...rest },
+) {
+  const instance = documentInstance(identity);
+  if (!instance) {
+    const e = new Error("a remote binding needs provider, tenant, driveId and itemId");
+    e.code = "identity_unresolved";
+    throw e;
+  }
+  const existing = readRemote(workspaceDir);
+  if (existing && existing.documentInstance !== instance && !rebind) {
+    const e = new Error(
+      `this deck is bound to ${existing.name ?? existing.documentInstance}. ` +
+        `Publishing it somewhere else is a rebind — pass --rebind to confirm, or open the file ` +
+        `into a fresh deck to keep both.`,
+    );
+    e.code = "rebind_required";
+    e.bound = existing;
+    throw e;
+  }
+  // A rebind starts a clean remote record: the old item's accepted eTag, its
+  // committed refs and its pending operation describe a DIFFERENT file, and
+  // carrying any of them forward would let a publish send an If-Match that
+  // belongs to someone else's document.
+  const carried = existing && existing.documentInstance === instance ? existing : {};
+  return writeRemote(workspaceDir, {
+    ...carried,
+    ...identity,
+    documentInstance: instance,
+    ...labels,
+    boundAt: carried.boundAt ?? nowIso(),
+    ...rest,
+  });
+}
+
+/** Forget the binding; the workspace and its revision state are untouched. */
+export function detachRemote(workspaceDir) {
+  const existing = readRemote(workspaceDir);
+  fs.rmSync(remotePath(workspaceDir), { force: true });
+  return existing;
+}
+
+/**
+ * Record what a read actually observed. `lastPulledAt` means "a freshness
+ * observation SUCCEEDED at this time" and is never refreshed by a failed
+ * attempt — a stale timestamp that says so beats a current one that lies.
+ */
+export function noteObservation(workspaceDir, { revision = null, failure = null, labels = {} }) {
+  const remote = readRemote(workspaceDir);
+  if (!remote) return null;
+  return writeRemote(workspaceDir, {
+    ...remote,
+    ...labels,
+    ...(revision ? { observedRevision: revision, lastPulledAt: nowIso() } : {}),
+    lastObservationError: failure ? { at: nowIso(), ...failure } : null,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// capabilities, access and the mode they add up to
+// ---------------------------------------------------------------------------
+
+/**
+ * Fold policy, grant, route support, item access and the local gates into one
+ * answer.
+ *
+ * `capabilities` maps each route of {@link ROUTES} to a {@link SUPPORT} value.
+ * `access` is `{ read, write }` over {@link ACCESS} — `write: "unknown"` is the
+ * NORMAL answer and stays that way: the only honest way to learn item write
+ * access is the publish the user actually asked for, never a surprise probe.
+ *
+ * `blockers` is every applicable reason; `reason` is the first of them in
+ * {@link REASONS} order, so a switch on one string is stable across runs.
+ *
+ * `canPublish` means a protected publish is ELIGIBLE to be attempted, not that
+ * it will be allowed. That distinction is the whole point of keeping
+ * `writeAccess` separate.
+ */
+export function computeMode({ capabilities = {}, access = {}, policy = {}, gates = {} } = {}) {
+  const blockers = new Set();
+  // Every route is live (bridge/sharepoint.mjs); `capabilities` is kept for the
+  // on-disk record and for a provider that reports a read as unsupported.
+  const support = (route) => capabilities[route] ?? "supported";
+  const readAccess = access.read ?? "unknown";
+  const writeAccess = access.write ?? "unknown";
+
+  if (policy.identityUnresolved) blockers.add("identity_unresolved");
+  if (policy.itemMissing) blockers.add("remote_missing");
+  if (policy.offline) blockers.add("offline");
+  if (policy.throttled) blockers.add("throttled");
+  if (policy.remoteSavingDisabled) blockers.add("remote_saving_disabled");
+  if (policy.writeScopeMissing) blockers.add("write_scope_missing");
+  // Only ever set from EVIDENCE the provider returned (an `invalid_grant`, a
+  // WWW-Authenticate naming insufficient_claims). A bare 403 never lands here.
+  if (policy.consentRequired) blockers.add("consent_required");
+
+  if (gates.needsReconcile) blockers.add("needs_reconcile");
+  if (gates.extensionMissing) blockers.add("extension_missing");
+  if (gates.extensionIncompatible) blockers.add("extension_incompatible");
+  if (gates.validationRequired) blockers.add("validation_required");
+  if (gates.unknownOutcome) blockers.add("unknown_outcome");
+  if (gates.contextMissing) blockers.add("context_missing");
+  if (gates.snapshotRaced) blockers.add("snapshot_raced");
+
+  if (writeAccess === "denied") blockers.add("target_access_denied");
+
+  const writesPossible = !policy.remoteSavingDisabled && !policy.writeScopeMissing;
+
+  // Reads unavailable is the manual branch — and the reason for it is kept,
+  // because "we could not read it" and "you may not write it" need different
+  // remedies.
+  const readable = readAccess !== "denied" && support("read") === "supported" && !policy.readsDisabled;
+  if (!readable && readAccess === "denied") blockers.add("target_access_denied");
+
+  let mode;
+  if (!readable) {
+    mode = "manual";
+  } else if (
+    blockers.has("context_missing") ||
+    blockers.has("identity_unresolved") ||
+    blockers.has("remote_missing") ||
+    blockers.has("needs_reconcile") ||
+    blockers.has("extension_missing") ||
+    blockers.has("extension_incompatible") ||
+    blockers.has("validation_required") ||
+    blockers.has("unknown_outcome") ||
+    blockers.has("snapshot_raced")
+  ) {
+    mode = "blocked";
+  } else if (writesPossible && writeAccess !== "denied" && !blockers.has("consent_required")) {
+    mode = "automatic";
+  } else {
+    mode = "read-only";
+  }
+
+  const ordered = REASONS.filter((r) => blockers.has(r));
+  return {
+    mode,
+    canPublish: mode === "automatic",
+    writeAccess,
+    readAccess,
+    capabilities: Object.fromEntries(ROUTES.map((r) => [r, support(r)])),
+    blockers: ordered,
+    reason: ordered[0] ?? null,
+  };
+}
+
+/**
+ * Classify a provider response into access evidence WITHOUT inventing a consent
+ * verdict. The distinction the design insists on:
+ *
+ *   - a READ 403 → the target is not readable by this user → manual.
+ *   - a WRITE 403 with readable metadata → read-only, `target_access_denied`.
+ *   - a generic 403 → never `consent_required`. Consent is claimed only when the
+ *     provider says so (a `WWW-Authenticate` naming insufficient_claims, or an
+ *     `invalid_grant` / `interaction_required` from the token endpoint).
+ */
+export function classifyAccessResponse({ status, on, headers = {}, body = null }) {
+  const challenge = String(
+    headers["www-authenticate"] ?? headers["WWW-Authenticate"] ?? "",
+  ).toLowerCase();
+  const code = String(body?.error?.code ?? body?.error ?? "").toLowerCase();
+  const consentEvidence =
+    challenge.includes("insufficient_claims") ||
+    challenge.includes("consent") ||
+    ["invalid_grant", "interaction_required", "consent_required"].includes(code);
+
+  if (status === 404) return { access: "unknown", reason: "remote_missing" };
+  if (status === 429 || status === 503) return { access: "unknown", reason: "throttled" };
+  if (status === 401) return { access: "unknown", reason: "consent_required" };
+  if (status === 403) {
+    if (consentEvidence) return { access: "unknown", reason: "consent_required" };
+    return {
+      access: "denied",
+      reason: on === "read" ? "target_access_denied" : "target_access_denied",
+    };
+  }
+  if (status >= 200 && status < 300) return { access: "allowed", reason: null };
+  return { access: "unknown", reason: null };
+}
+
+// ---------------------------------------------------------------------------
+// the operation journal — written BEFORE any external effect
+// ---------------------------------------------------------------------------
+
+/**
+ * The phases an operation passes through. Everything from `artifacts` onward may
+ * have left an effect on the server, so a restart that finds one of those must
+ * INSPECT before it acts.
+ */
+export const OPERATION_PHASES = [
+  "planned", // journaled; nothing has left this machine
+  "artifacts", // durable context / attachments may have been written
+  "deck-write", // the conditional replace or create is in flight
+  "committed", // the server confirmed; a receipt exists
+  "finalized", // local state advanced and the extension callback acknowledged
+];
+
+/** Phases whose outcome cannot be assumed without asking the server. */
+export const UNCERTAIN_PHASES = ["artifacts", "deck-write"];
+
+export function operationsDir(workspaceDir) {
+  return stateDir(workspaceDir, OPERATIONS_DIR);
+}
+
+export function operationPath(workspaceDir, operationId) {
+  return path.join(operationsDir(workspaceDir), `${operationId}.json`);
+}
+
+export function readOperation(workspaceDir, operationId) {
+  const data = readJson(operationPath(workspaceDir, operationId));
+  return data?.schemaVersion === SCHEMA_VERSION ? data : null;
+}
+
+export function listOperations(workspaceDir) {
+  let names = [];
+  try {
+    names = fs.readdirSync(operationsDir(workspaceDir));
+  } catch {
+    return [];
+  }
+  return names
+    .filter((n) => n.endsWith(".json"))
+    .map((n) => readOperation(workspaceDir, n.slice(0, -5)))
+    .filter(Boolean)
+    .sort((a, b) => (a.startedAt < b.startedAt ? 1 : -1));
+}
+
+/** Operations whose outcome the next command must resolve before it writes. */
+export function pendingOperations(workspaceDir) {
+  return listOperations(workspaceDir).filter(
+    (op) => op.phase !== "finalized" && op.phase !== "abandoned",
+  );
+}
+
+/**
+ * Journal an operation before its first external effect.
+ *
+ * `recoveryMarker` is what makes an unknown outcome findable: it rides into the
+ * server's own record of the write (the content-addressed artifact name, the
+ * created item's name, the operation id inside the uploaded context tag) so a
+ * restart can ask "is MY write the one that landed?" instead of guessing from a
+ * timestamp.
+ */
+export function beginOperation(
+  workspaceDir,
+  { kind, deck = null, destination = null, evidence = {}, plannedArtifacts = [], recoveryMarker = null },
+) {
+  const operationId = `op-${randomUUID().replace(/-/g, "").slice(0, 16)}`;
+  const record = {
+    schemaVersion: SCHEMA_VERSION,
+    operationId,
+    kind,
+    phase: "planned",
+    startedAt: nowIso(),
+    deck,
+    ...(destination ? { destination } : {}),
+    evidence,
+    plannedArtifacts,
+    pendingRefs: [],
+    committedRefs: [],
+    recoveryMarker: recoveryMarker ?? operationId,
+    steps: [],
+    receipt: null,
+  };
+  writeJson(operationPath(workspaceDir, operationId), record);
+  const remote = readRemote(workspaceDir);
+  if (remote) writeRemote(workspaceDir, { ...remote, pendingOperationId: operationId });
+  return record;
+}
+
+/** Advance an operation. The record on disk is the truth; the return value is a copy. */
+export function stepOperation(workspaceDir, operationId, { phase = null, step = null, ...patch }) {
+  const current = readOperation(workspaceDir, operationId);
+  if (!current) return null;
+  const next = {
+    ...current,
+    ...patch,
+    ...(phase ? { phase } : {}),
+    steps: step ? [...current.steps, { step, at: nowIso() }] : current.steps,
+  };
+  writeJson(operationPath(workspaceDir, operationId), next);
+  return next;
+}
+
+/**
+ * Persist a CONFIRMED receipt, idempotently.
+ *
+ * Called twice with the same operation id, the second call returns the first
+ * receipt unchanged: a retried extension callback, a resumed publish and a
+ * crash-recovery pass must all converge on one record rather than each writing
+ * their own version of what happened.
+ */
+export function writeReceipt(workspaceDir, operationId, receipt) {
+  const file = path.join(stateDir(workspaceDir, RECEIPTS_DIR), `${operationId}.json`);
+  const existing = readJson(file);
+  if (existing?.schemaVersion === SCHEMA_VERSION) return existing;
+  const record = {
+    schemaVersion: SCHEMA_VERSION,
+    operationId,
+    confirmedAt: nowIso(),
+    ...receipt,
+  };
+  writeJson(file, record);
+  stepOperation(workspaceDir, operationId, {
+    phase: "committed",
+    step: "receipt",
+    receipt: record,
+  });
+  return record;
+}
+
+export function readReceipt(workspaceDir, operationId) {
+  const data = readJson(path.join(stateDir(workspaceDir, RECEIPTS_DIR), `${operationId}.json`));
+  return data?.schemaVersion === SCHEMA_VERSION ? data : null;
+}
+
+export function listReceipts(workspaceDir) {
+  let names = [];
+  try {
+    names = fs.readdirSync(stateDir(workspaceDir, RECEIPTS_DIR));
+  } catch {
+    return [];
+  }
+  return names
+    .filter((n) => n.endsWith(".json"))
+    .map((n) => readReceipt(workspaceDir, n.slice(0, -5)))
+    .filter(Boolean)
+    .sort((a, b) => (a.confirmedAt < b.confirmedAt ? 1 : -1));
+}
+
+/**
+ * Advance the ACCEPTED remote base from a confirmed receipt. This is the remote
+ * half of acceptance — the only door besides `revision accept` (which refuses a
+ * remote-bound deck for exactly this reason).
+ *
+ * Pending refs become committed refs here and nowhere else: a ref an artifact
+ * upload resolved is not paired with anything until the deck version that names
+ * it is the one the server holds.
+ */
+export function acceptReceipt(workspaceDir, receipt) {
+  const remote = readRemote(workspaceDir);
+  if (!remote) return null;
+  if (receipt.route === "rename" || receipt.route === "rename-recovered") {
+    return writeRemote(workspaceDir, {
+      ...remote,
+      name: receipt.item?.name ?? remote.name,
+      webUrl: receipt.item?.webUrl ?? remote.webUrl,
+      pendingOperationId: null,
+      lastReceipt: { operationId: receipt.operationId, confirmedAt: receipt.confirmedAt, route: receipt.route },
+    });
+  }
+  return writeRemote(workspaceDir, {
+    ...remote,
+    // A rename or a move changes the labels; identity does not move.
+    name: receipt.item?.name ?? remote.name,
+    webUrl: receipt.item?.webUrl ?? remote.webUrl,
+    acceptedETag: receipt.version?.eTag ?? remote.acceptedETag,
+    acceptedCTag: receipt.version?.cTag ?? remote.acceptedCTag,
+    acceptedVersionId: receipt.version?.versionId ?? remote.acceptedVersionId,
+    acceptedSha256: receipt.candidateSha256 ?? remote.acceptedSha256,
+    observedRevision: receipt.version ?? remote.observedRevision,
+    lastPulledAt: nowIso(),
+    committedRefs: receipt.refs ?? remote.committedRefs ?? [],
+    pendingRefs: [],
+    pendingOperationId: null,
+    pendingCandidateId: null,
+    lastReceipt: {
+      operationId: receipt.operationId,
+      confirmedAt: receipt.confirmedAt,
+      versionId: receipt.version?.versionId ?? null,
+      eTag: receipt.version?.eTag ?? null,
+      route: receipt.route ?? null,
+    },
+  });
+}
+
+/**
+ * What a restart must do about an operation it found.
+ *
+ * `resolved` when a receipt already exists (the commit landed; only local
+ * finalization is pending), `inspect` while the phase could have left an effect,
+ * `discard` when nothing can have happened yet.
+ */
+export function operationOutcome(workspaceDir, operation) {
+  if (!operation) return null;
+  const receipt = readReceipt(workspaceDir, operation.operationId);
+  if (receipt) return { action: "resolved", receipt, operation };
+  if (UNCERTAIN_PHASES.includes(operation.phase)) {
+    return { action: "inspect", operation, reason: "unknown_outcome" };
+  }
+  return { action: "discard", operation };
+}
+
+// ---------------------------------------------------------------------------
+// what `ready` and `status` report about the remote half
+// ---------------------------------------------------------------------------
+
+/**
+ * The remote block of `ready --json`, computed WITHOUT a network call.
+ *
+ * Deliberately a disk read: `ready` runs at the top of every session and must
+ * not turn into a SharePoint round trip. It reports the last SUCCESSFUL
+ * observation and says when that was; it never claims the deck is current,
+ * because nothing here has asked. Continuous freshness is a lie a status command
+ * must not tell.
+ */
+export function remoteReadiness(workspaceDir, revisionStatus) {
+  const remote = readRemote(workspaceDir);
+  if (!remote) return null;
+  const status = revisionStatus?.(workspaceDir) ?? null;
+  const pending = pendingOperations(workspaceDir);
+  const decision = computeMode({
+    capabilities: remote.capabilities ?? {},
+    access: remote.access ?? {},
+    gates: {
+      needsReconcile: Boolean(status && (status.conflicts > 0 || status.staged.length > 0)),
+      unknownOutcome: pending.some((op) => UNCERTAIN_PHASES.includes(op.phase)),
+    },
+  });
+  return {
+    provider: remote.provider ?? "sharepoint",
+    documentInstance: remote.documentInstance,
+    name: remote.name ?? null,
+    webUrl: remote.webUrl ?? null,
+    mode: decision.mode,
+    canPublish: decision.canPublish,
+    writeAccess: decision.writeAccess,
+    capabilities: decision.capabilities,
+    blockers: decision.blockers,
+    reason: decision.reason,
+    baseRevision: remote.acceptedETag ?? null,
+    observedRemoteRevision: remote.observedRevision?.eTag ?? null,
+    lastPulledAt: remote.lastPulledAt ?? null,
+    lastObservationError: remote.lastObservationError ?? null,
+    localDirty: status?.localDirty ?? null,
+    pendingCandidate: status?.candidate?.candidateId ?? remote.pendingCandidateId ?? null,
+    stagedIncomingRevision: status?.staged?.[0]?.revisionId ?? null,
+    dependencyChanges: Object.keys(remote.dependencyObservations ?? {}),
+    operationOutcome: pending.length
+      ? { operationId: pending[0].operationId, phase: pending[0].phase }
+      : null,
+    pendingManualUpload: Boolean(remote.manualHandoff),
+  };
+}
+
+/** One human line for `ready <deck>` — observation time included, no freshness claim. */
+export function remoteHumanLine(readiness) {
+  if (!readiness) return "";
+  const where = readiness.name ?? readiness.documentInstance;
+  const when = readiness.lastPulledAt
+    ? `last checked ${readiness.lastPulledAt}`
+    : "never checked";
+  // The mode is the verdict; the blockers are why. "read-only — conditional_write_unsupported"
+  // and "blocked — needs_reconcile" need different remedies and must not share a label.
+  const state = readiness.canPublish
+    ? "publishing is available"
+    : `${readiness.mode} — ${readiness.blockers.join(", ") || readiness.reason || "no protected write route"}`;
+  return (
+    `remote:  ${where} · ${state} · ${when}\n` +
+    (readiness.stagedIncomingRevision
+      ? `         a newer save is staged (${readiness.stagedIncomingRevision}) — reconcile before publishing\n`
+      : "") +
+    (readiness.pendingManualUpload
+      ? `         a manual upload is prepared and still pending — nothing is saved remotely yet\n`
+      : "") +
+    (readiness.operationOutcome
+      ? `         a previous publish (${readiness.operationOutcome.operationId}) has an unresolved outcome\n`
+      : "")
+  );
+}
+
+/** Close an operation that inspection proved never landed. Never deletes its record. */
+export function abandonOperation(workspaceDir, operationId, why) {
+  const next = stepOperation(workspaceDir, operationId, {
+    phase: "abandoned",
+    step: "abandoned",
+    abandonedBecause: why,
+  });
+  const remote = readRemote(workspaceDir);
+  if (remote?.pendingOperationId === operationId) {
+    writeRemote(workspaceDir, { ...remote, pendingOperationId: null });
+  }
+  return next;
+}