slidemind 0.3.20 → 0.4.0

package/src/bridge/sharepoint.mjs

@@ -0,0 +1,914 @@
+// The direct SharePoint adapter: read an item, prove a snapshot is consistent,
+// and replace it under a server-enforced precondition.
+//
+// This module is written against the direct-endpoint shapes listed in
+// `docs/slidemind-cli-connect/20-sharepoint-pull-publish.md`; the ones exercised
+// live on 2026-09-16 are marked there. Every write sends `If-Match` and treats a
+// 412 as the mechanism working; the pull-before-write in lib/publish.mjs catches
+// a foreign save before any byte leaves.
+//
+// Direct endpoints are not Graph, and the differences bite exactly where the
+// safety lives:
+//   - upload-session creation is the `oneDrive.createUploadSession` action, not
+//     Graph's `microsoft.graph.createUploadSession`;
+//   - conflict behaviour rides `@name.conflictBehavior`, not the Graph
+//     annotation;
+//   - Graph's documentation that an If-Match on session CREATION is honoured at
+//     COMMIT does not transfer, and would not prove exclusion against an Office
+//     writer even if it did.
+//
+// Two transport rules are absolute:
+//   1. The bearer goes to the configured API origin and nowhere else. Download
+//      URLs and upload-session URLs are PREAUTHENTICATED — they carry their own
+//      credential in the query string, and forwarding an Authorization header to
+//      them would hand a second credential to a host we did not choose.
+//   2. A read may be retried. A write whose outcome is unknown may NOT — it goes
+//      to inspection first, because "did my replace land?" and "should I send
+//      these bytes again?" are the same question and the wrong answer is a
+//      duplicate document or a clobbered save.
+
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+
+export const PROVIDER = "sharepoint";
+
+// The direct (non-Graph) API version these routes are written against. Recorded
+// in doc 20; a tenant that answers a different one is a proof failure, not a
+// silent fallback.
+export const API_VERSION = "v2.1";
+
+export const ROUTES = [
+  "read",
+  "create",
+  "rename",
+  "conditionalSmall",
+  "conditionalLarge",
+  "exactVersionRead",
+];
+
+const sha256 = (bytes) => createHash("sha256").update(Buffer.from(bytes)).digest("hex");
+
+// ---------------------------------------------------------------------------
+// routes and limits
+// ---------------------------------------------------------------------------
+
+// The documented single-PUT ceiling and upload-session chunk size. Both are
+// fixed: a payload above `smallMaxBytes` goes through an upload session.
+export const LIMITS = Object.freeze({ smallMaxBytes: 4 * 1024 * 1024, chunkBytes: 10 * 1024 * 1024 });
+
+/** Every route is live. Kept as a function so the mode logic has one place to ask. */
+export function capabilities() {
+  return { routes: Object.fromEntries(ROUTES.map((r) => [r, "supported"])), limits: LIMITS };
+}
+
+/** Which conditional route carries a payload of this size. */
+export function routeForSize(_host, bytes) {
+  return { large: bytes > LIMITS.smallMaxBytes, smallMaxBytes: LIMITS.smallMaxBytes };
+}
+
+// ---------------------------------------------------------------------------
+// transport
+// ---------------------------------------------------------------------------
+
+/** A URL with its query stripped — the only form a transfer URL may be printed in. */
+export function redactUrl(url) {
+  try {
+    const u = new URL(String(url));
+    return `${u.origin}${u.pathname}${u.search ? "?<redacted>" : ""}`;
+  } catch {
+    return "<unparseable url>";
+  }
+}
+
+// HTTPS, or plain HTTP on loopback — the same transport rule the setup claim and
+// the Entra authority hold to, so a local mock host can exercise these paths
+// without loosening anything a real tenant would meet.
+function transportAllowed(url) {
+  if (url.protocol === "https:") return true;
+  return (
+    url.protocol === "http:" &&
+    ["127.0.0.1", "localhost", "::1", "[::1]"].includes(url.hostname)
+  );
+}
+
+function assertSameOrigin(origin, url) {
+  const target = new URL(url, origin);
+  if (target.origin !== new URL(origin).origin) {
+    const e = new Error(
+      `refusing to send credentials to ${redactUrl(target)} — the authorized API origin is ${new URL(origin).origin}`,
+    );
+    e.code = "origin_not_allowed";
+    throw e;
+  }
+  if (!transportAllowed(target)) {
+    const e = new Error(`refusing a non-HTTPS SharePoint request to ${redactUrl(target)}`);
+    e.code = "origin_not_allowed";
+    throw e;
+  }
+  return target;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// Retry-After wins when the server sent one; otherwise exponential with jitter,
+// so a throttled tenant is not hammered back into throttling by a fleet of
+// synchronized clients.
+function backoffMs(attempt, response) {
+  const header = response?.headers?.get?.("retry-after");
+  if (header) {
+    const seconds = Number(header);
+    if (Number.isFinite(seconds)) return Math.min(seconds * 1000, 60_000);
+    const at = Date.parse(header);
+    if (Number.isFinite(at)) return Math.max(0, Math.min(at - Date.now(), 60_000));
+  }
+  const base = Math.min(1000 * 2 ** attempt, 16_000);
+  return base / 2 + Math.random() * (base / 2);
+}
+
+const RETRYABLE = new Set([429, 502, 503, 504]);
+
+/**
+ * One authenticated request to the configured origin.
+ *
+ * `retry` is opt-in and means "this request is SAFE to repeat". Never pass it
+ * for a write: a POST/PUT/PATCH that timed out may have been applied, and the
+ * recovery for that is inspection, not another attempt.
+ */
+export async function apiFetch(
+  client,
+  urlPath,
+  { method = "GET", headers = {}, body = null, retry = false, raw = false } = {},
+) {
+  const url = assertSameOrigin(client.origin, urlPath);
+  const attempts = retry ? Number(client.maxRetries ?? 4) : 1;
+  let lastResponse = null;
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    let response;
+    try {
+      response = await client.fetch(url.toString(), {
+        method,
+        headers: {
+          accept: "application/json",
+          authorization: `Bearer ${client.token}`,
+          ...headers,
+        },
+        body,
+        redirect: "manual",
+      });
+    } catch (err) {
+      if (retry && attempt < attempts - 1) {
+        await sleep(backoffMs(attempt, null));
+        continue;
+      }
+      const e = new Error(`SharePoint request failed: ${err?.message ?? err}`);
+      e.code = "offline";
+      e.cause = err;
+      throw e;
+    }
+    lastResponse = response;
+    // A redirect off the API origin is a preauthenticated transfer destination.
+    // It is returned as a CAPABILITY for the caller to fetch without a bearer —
+    // never followed here, because `fetch`'s own redirect handling would carry
+    // the Authorization header across the hop.
+    if (response.status >= 300 && response.status < 400) {
+      const location = response.headers.get("location");
+      return { response, redirect: location ?? null, status: response.status, json: null, bytes: null };
+    }
+    if (RETRYABLE.has(response.status) && retry && attempt < attempts - 1) {
+      await sleep(backoffMs(attempt, response));
+      continue;
+    }
+    if (raw) {
+      const bytes = Buffer.from(await response.arrayBuffer());
+      return { response, status: response.status, bytes, json: null, redirect: null };
+    }
+    const text = await response.text();
+    let json = null;
+    try {
+      json = text ? JSON.parse(text) : null;
+    } catch {
+      /* non-JSON body — kept as text on the error path */
+    }
+    return { response, status: response.status, json, text, bytes: null, redirect: null };
+  }
+  return { response: lastResponse, status: lastResponse?.status ?? 0, json: null, bytes: null };
+}
+
+/**
+ * Fetch a server-issued preauthenticated URL. NO bearer, ever.
+ *
+ * The URL must have arrived in a validated API response — the caller passes what
+ * the API handed it, and this refuses anything that is not HTTPS. The query
+ * string is the credential, so it never reaches a log line: every error here
+ * names the redacted form.
+ */
+export async function transferFetch(client, url, { retry = true } = {}) {
+  let target;
+  try {
+    target = new URL(String(url));
+  } catch {
+    const e = new Error("the API returned a transfer destination that is not a URL");
+    e.code = "invalid_transfer_url";
+    throw e;
+  }
+  if (!transportAllowed(target)) {
+    const e = new Error(`refusing a non-HTTPS transfer destination (${redactUrl(target)})`);
+    e.code = "invalid_transfer_url";
+    throw e;
+  }
+  const attempts = retry ? Number(client.maxRetries ?? 4) : 1;
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    let response;
+    try {
+      // `redirect: "follow"` is safe HERE and only here: no Authorization header
+      // is attached, so a redirect cannot leak a credential. It can only ever
+      // spend the URL's own embedded one, which is what it is for.
+      response = await client.fetch(target.toString(), { redirect: "follow" });
+    } catch (err) {
+      if (attempt < attempts - 1) {
+        await sleep(backoffMs(attempt, null));
+        continue;
+      }
+      const e = new Error(`could not fetch ${redactUrl(target)}: ${err?.message ?? err}`);
+      e.code = "offline";
+      throw e;
+    }
+    if (RETRYABLE.has(response.status) && attempt < attempts - 1) {
+      await sleep(backoffMs(attempt, response));
+      continue;
+    }
+    if (response.status < 200 || response.status >= 300) {
+      const e = new Error(`${redactUrl(target)} answered ${response.status}`);
+      e.code = "transfer_failed";
+      e.status = response.status;
+      throw e;
+    }
+    return Buffer.from(await response.arrayBuffer());
+  }
+  const e = new Error(`could not fetch ${redactUrl(target)}`);
+  e.code = "offline";
+  throw e;
+}
+
+// ---------------------------------------------------------------------------
+// the client
+// ---------------------------------------------------------------------------
+
+/**
+ * A client bound to one SharePoint origin and one delegated token.
+ *
+ * `fetch` is injected so the mock-host suite can drive every branch — redirects,
+ * 412s, name conflicts, equal-size races — against a local `node:http` server
+ * without a tenant.
+ */
+export function createClient({ origin, token, fetch: fetchImpl = globalThis.fetch, maxRetries = 4 }) {
+  if (!origin) throw new Error("createClient: origin is required");
+  if (!token) {
+    const e = new Error(
+      "no SharePoint access token — run `slidemind login` (one sign-in mints both resources).",
+    );
+    e.code = "write_scope_missing";
+    throw e;
+  }
+  return {
+    origin: String(origin).replace(/\/$/, ""),
+    token,
+    fetch: fetchImpl,
+    maxRetries,
+    host: new URL(origin).origin,
+  };
+}
+
+// Item metadata is requested by explicit field list: a `$select` keeps the
+// response small and, more importantly, makes doc 20's "fields relied upon"
+// list checkable against the code rather than aspirational.
+const ITEM_FIELDS = [
+  "id",
+  "name",
+  "eTag",
+  "cTag",
+  "size",
+  "webUrl",
+  "lastModifiedDateTime",
+  "parentReference",
+  "file",
+  "folder",
+  "deleted",
+].join(",");
+
+// The folder facet plus SharePoint ids, asked for only where a folder is the
+// subject (destination lookup, child listing). Kept off ITEM_FIELDS so the
+// routes proved live on 2026-09-16 keep their observed `$select` verbatim.
+const FOLDER_FIELDS = `${ITEM_FIELDS},sharepointIds`;
+
+function itemBase(client, { driveId, itemId }) {
+  return `/_api/${API_VERSION}/drives/${encodeURIComponent(driveId)}/items/${encodeURIComponent(itemId)}`;
+}
+
+/** The normalized metadata every other call compares on. */
+export function normalizeItem(json) {
+  if (!json) return null;
+  return {
+    itemId: json.id ?? null,
+    driveId: json.parentReference?.driveId ?? null,
+    // The folder a first-create and a content-addressed artifact land in. A
+    // label, like `name` — publishing never routes on it.
+    parentId: json.parentReference?.id ?? null,
+    parentPath: json.parentReference?.path ?? null,
+    name: json.name ?? null,
+    // The PUT (create) response hands back an HTML-escaped webUrl; GET does not.
+    webUrl: json.webUrl ? String(json.webUrl).replace(/&amp;/g, "&") : null,
+    // eTag changes on ANY change (metadata included); cTag only on content.
+    // Which one a check uses is load-bearing — see `sameSnapshot`.
+    eTag: json.eTag ?? null,
+    cTag: json.cTag ?? null,
+    size: typeof json.size === "number" ? json.size : null,
+    lastModifiedDateTime: json.lastModifiedDateTime ?? null,
+    deleted: Boolean(json.deleted),
+    // One of the two facets says what the item IS; anything else (a package,
+    // a notebook) is neither and is not offered as a destination or a deck.
+    kind: json.folder ? "folder" : json.file ? "file" : null,
+    childCount: typeof json.folder?.childCount === "number" ? json.folder.childCount : null,
+    mimeType: json.file?.mimeType ?? null,
+    tenantId: json.sharepointIds?.tenantId ?? null,
+  };
+}
+
+function providerError(status, json, { on }) {
+  const detail = json?.error?.message ?? json?.error_description ?? `HTTP ${status}`;
+  const e = new Error(`SharePoint ${on} failed (${status}): ${detail}`);
+  e.status = status;
+  e.providerCode = json?.error?.code ?? null;
+  e.on = on;
+  return e;
+}
+
+/** Resolve the item a user's link names. The LINK selects the target — nothing else does. */
+export async function resolveLink(client, link) {
+  const encoded = Buffer.from(String(link), "utf8")
+    .toString("base64")
+    .replace(/=+$/, "")
+    .replace(/\//g, "_")
+    .replace(/\+/g, "-");
+  const res = await apiFetch(
+    client,
+    `/_api/${API_VERSION}/shares/u!${encoded}/driveItem?$select=${ITEM_FIELDS}`,
+    { retry: true },
+  );
+  if (res.status < 200 || res.status >= 300) throw providerError(res.status, res.json, { on: "link resolution" });
+  const item = normalizeItem(res.json);
+  if (!item?.itemId || !item?.driveId) {
+    const e = new Error("that link resolved to something without a drive item identity");
+    e.code = "identity_unresolved";
+    throw e;
+  }
+  return item;
+}
+
+export async function getItem(client, ref, { fields = ITEM_FIELDS } = {}) {
+  const res = await apiFetch(client, `${itemBase(client, ref)}?$select=${fields}`, {
+    retry: true,
+  });
+  if (res.status === 404) {
+    const e = new Error("the bound item is gone from SharePoint");
+    e.code = "remote_missing";
+    e.status = 404;
+    throw e;
+  }
+  if (res.status < 200 || res.status >= 300) throw providerError(res.status, res.json, { on: "metadata read" });
+  return normalizeItem(res.json);
+}
+
+/**
+ * Do two metadata reads describe the same stored content?
+ *
+ * Content identity is `cTag` where the provider gives one, because an eTag also
+ * moves on a pure metadata change and would send a pull chasing bytes nobody
+ * touched. Size alone is never enough — that is the equal-size race the spec
+ * names — so it is an extra check, not the check.
+ */
+export function sameSnapshot(a, b) {
+  if (!a || !b) return false;
+  if (a.cTag && b.cTag) return a.cTag === b.cTag && a.size === b.size;
+  return a.eTag === b.eTag && a.size === b.size;
+}
+
+/**
+ * One consistent snapshot of the item's bytes, with the revision they belong to.
+ *
+ * Preferred route: pin an exact version and read THAT — a version, once written,
+ * does not change under the read. Where exact-version reads are unproved, the
+ * fallback is metadata A → bytes → metadata B, and the two metadata reads must
+ * agree; if they do not, the attempt is discarded and retried, bounded. Bytes
+ * are never labelled with an eTag that was not proved to describe them.
+ */
+export async function downloadSnapshot(client, ref, { versionId = null, attempts = 3 } = {}) {
+  if (versionId) {
+    const bytes = await downloadVersion(client, ref, versionId);
+    const meta = await getItem(client, ref);
+    return { bytes, revision: { ...meta, versionId }, pinned: true, sha256: sha256(bytes) };
+  }
+  let lastBefore = null;
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    const before = await getItem(client, ref);
+    lastBefore = before;
+    const bytes = await downloadContent(client, ref);
+    const after = await getItem(client, ref);
+    if (sameSnapshot(before, after)) {
+      return { bytes, revision: after, pinned: false, sha256: sha256(bytes) };
+    }
+  }
+  const e = new Error(
+    "the item kept changing while it was being read — nothing was staged. Try again in a moment.",
+  );
+  e.code = "snapshot_raced";
+  e.lastSeen = lastBefore;
+  throw e;
+}
+
+async function downloadContent(client, ref) {
+  const res = await apiFetch(client, `${itemBase(client, ref)}/content`, {
+    retry: true,
+    raw: true,
+  });
+  // The documented shape: the content route answers a 302 to a short-lived
+  // preauthenticated URL. The bearer stops here; the URL carries its own.
+  if (res.redirect) return transferFetch(client, res.redirect);
+  if (res.status < 200 || res.status >= 300) throw providerError(res.status, null, { on: "content read" });
+  return res.bytes;
+}
+
+/**
+ * One item by name inside a folder, or null when there is none.
+ *
+ * This is how a content-addressed artifact is REUSED rather than uploaded
+ * again: a name that already exists is fetched and its bytes compared, so an
+ * unchanged context costs a metadata read instead of a new stored object. Null
+ * on 404 — "not there" is the ordinary answer here, not a failure.
+ */
+export async function getItemByPath(client, { driveId, parentId }, name) {
+  const res = await apiFetch(
+    client,
+    `/_api/${API_VERSION}/drives/${encodeURIComponent(driveId)}/items/${encodeURIComponent(parentId)}` +
+      `:/${encodeURIComponent(name)}?$select=${ITEM_FIELDS}`,
+    { retry: true },
+  );
+  if (res.status === 404) return null;
+  if (res.status < 200 || res.status >= 300) throw providerError(res.status, res.json, { on: "folder lookup" });
+  return normalizeItem(res.json);
+}
+
+// ---------------------------------------------------------------------------
+// folders — destination lookup and bounded child listing
+// ---------------------------------------------------------------------------
+
+// The daemon's "Open SharePoint link → pick a child" flow reads ONE level at a
+// time. There is no recursion and no `$expand`: a library with ten thousand
+// items costs the user a page, not the CLI a crawl. Doc 20 R7/R8.
+
+/** How many children one page carries. The cursor continues from there. */
+export const CHILD_PAGE_SIZE = 50;
+
+function coded(code, message) {
+  const e = new Error(message);
+  e.code = code;
+  return e;
+}
+
+/** A ref is `{driveId,itemId}` already, or a link the user pasted. */
+async function folderRef(client, ref) {
+  if (ref && typeof ref === "object" && ref.driveId && ref.itemId) return ref;
+  if (typeof ref === "string") {
+    const item = await resolveLink(client, ref);
+    return { driveId: item.driveId, itemId: item.itemId };
+  }
+  throw coded("validation_failed", "a folder is named by {driveId,itemId} or a link");
+}
+
+/**
+ * The folder a plan or deck would be created in, with the identity a
+ * destination record stores. A file is refused here rather than at the first
+ * write: `not_a_folder` is the honest answer to "connect this deck to that link".
+ */
+export async function getFolder(client, ref) {
+  const item = await getItem(client, await folderRef(client, ref), { fields: FOLDER_FIELDS });
+  if (item.kind !== "folder") throw coded("not_a_folder", `${item.name ?? "that item"} is not a folder`);
+  return {
+    id: item.itemId,
+    driveId: item.driveId,
+    parentId: item.parentId,
+    name: item.name,
+    webUrl: item.webUrl,
+    eTag: item.eTag,
+    childCount: item.childCount,
+    tenantId: item.tenantId,
+  };
+}
+
+/**
+ * Is `name` already taken inside the folder? R6 by another door: 404 is
+ * "free", anything found is handed back so the caller can offer "open the
+ * existing one" instead of silently creating a sibling.
+ */
+export async function resolveDestination(client, ref, name) {
+  const { driveId, itemId } = await folderRef(client, ref);
+  const item = await getItemByPath(client, { driveId, parentId: itemId }, name);
+  return { exists: item !== null, item };
+}
+
+const encodeCursor = (o) => Buffer.from(JSON.stringify(o), "utf8").toString("base64url");
+
+// A cursor is OPAQUE to the caller and UNTRUSTED here: it comes back from a
+// browser or a job file, so the next-link inside it is checked against the
+// folder it was issued for and the origin the bearer is allowed to reach before
+// a single byte is sent. A forged cursor cannot walk another folder or carry
+// the token to another host.
+function decodeCursor(client, cursor, { driveId, itemId }) {
+  let parsed;
+  try {
+    parsed = JSON.parse(Buffer.from(String(cursor), "base64url").toString("utf8"));
+  } catch {
+    throw coded("validation_failed", "that page cursor is not one this listing issued");
+  }
+  if (parsed?.driveId !== driveId || parsed?.itemId !== itemId || typeof parsed?.nextLink !== "string") {
+    throw coded("validation_failed", "that page cursor belongs to a different folder");
+  }
+  let next;
+  try {
+    next = new URL(parsed.nextLink);
+  } catch {
+    throw coded("validation_failed", "that page cursor carries no usable next page");
+  }
+  const childrenPath = `${itemBase(client, { driveId, itemId })}/children`;
+  if (next.origin !== client.host || next.pathname !== childrenPath) {
+    throw coded("access_denied", `refusing to continue a listing at ${redactUrl(next)}`);
+  }
+  return `${next.pathname}${next.search}`;
+}
+
+/**
+ * One page of a folder's IMMEDIATE children — folders and files only, `pageSize`
+ * at a time, continued through the returned `nextCursor` and never recursed.
+ */
+export async function listChildren(client, ref, { cursor = null, pageSize = CHILD_PAGE_SIZE } = {}) {
+  const { driveId, itemId } = await folderRef(client, ref);
+  const top = Math.min(Math.max(1, Number(pageSize) || CHILD_PAGE_SIZE), CHILD_PAGE_SIZE);
+  const urlPath = cursor
+    ? decodeCursor(client, cursor, { driveId, itemId })
+    : `${itemBase(client, { driveId, itemId })}/children?$select=${FOLDER_FIELDS}&$top=${top}`;
+  const res = await apiFetch(client, urlPath, { retry: true });
+  if (res.status === 404) throw coded("remote_missing", "that folder is gone from SharePoint");
+  if (res.status === 403) throw coded("access_denied", "you cannot list that folder");
+  if (res.status < 200 || res.status >= 300) throw providerError(res.status, res.json, { on: "folder listing" });
+  const items = (res.json?.value ?? [])
+    .map(normalizeItem)
+    .filter((i) => i.kind && !i.deleted)
+    .map((i) => ({
+      id: i.itemId,
+      driveId: i.driveId ?? driveId,
+      name: i.name,
+      kind: i.kind,
+      ...(i.kind === "folder" ? { childCount: i.childCount } : { size: i.size, mimeType: i.mimeType }),
+      webUrl: i.webUrl,
+      eTag: i.eTag,
+      lastModified: i.lastModifiedDateTime,
+    }));
+  const nextLink = res.json?.["@odata.nextLink"];
+  return {
+    items,
+    nextCursor: typeof nextLink === "string" && nextLink ? encodeCursor({ driveId, itemId, nextLink }) : null,
+  };
+}
+
+export async function listVersions(client, ref) {
+  const res = await apiFetch(client, `${itemBase(client, ref)}/versions`, { retry: true });
+  if (res.status < 200 || res.status >= 300) throw providerError(res.status, res.json, { on: "version list" });
+  return (res.json?.value ?? []).map((v) => ({
+    versionId: v.id ?? null,
+    size: typeof v.size === "number" ? v.size : null,
+    lastModifiedDateTime: v.lastModifiedDateTime ?? null,
+    lastModifiedBy: v.lastModifiedBy?.user?.displayName ?? null,
+  }));
+}
+
+export async function downloadVersion(client, ref, versionId) {
+  const res = await apiFetch(
+    client,
+    `${itemBase(client, ref)}/versions/${encodeURIComponent(versionId)}/content`,
+    { retry: true, raw: true },
+  );
+  if (res.redirect) return transferFetch(client, res.redirect);
+  if (res.status < 200 || res.status >= 300) {
+    throw providerError(res.status, null, { on: `version ${versionId} read` });
+  }
+  return res.bytes;
+}
+
+// ---------------------------------------------------------------------------
+// writes
+// ---------------------------------------------------------------------------
+
+// Every write answers in this shape. `outcome` is the only field a caller may
+// branch on, and `unknown` is a first-class answer — not an exception to swallow.
+function landed(route, item, version) {
+  // A 2xx whose body was empty or unparseable normalizes to `null`, and a receipt
+  // with no item and no version is indistinguishable from one that never happened:
+  // publish would skip its identity check, keep the previous acceptedETag, and read
+  // its own save back as a foreign one forever after. Unconfirmed IS `unknown`.
+  if (!item?.itemId) return unknown(route, "the write answered no item metadata, so its outcome is unconfirmed");
+  return { outcome: "committed", route, item, version };
+}
+function refused(route, reason, detail = {}) {
+  return { outcome: "refused", route, reason, ...detail };
+}
+function unknown(route, why) {
+  return { outcome: "unknown", route, why };
+}
+
+/**
+ * Replace an item's bytes under a server-enforced precondition, small route.
+ *
+ * `ifMatch` is the eTag the caller proved was current moments ago. A 412 is the
+ * SUCCESS of this mechanism, not its failure: somebody else's save is in the
+ * file and the caller must rebase rather than overwrite.
+ */
+export async function replaceSmall(client, ref, bytes, { ifMatch }) {
+  if (!ifMatch) {
+    const e = new Error("a conditional replace needs the eTag it expects to replace");
+    e.code = "conditional_write_unsupported";
+    throw e;
+  }
+  let res;
+  try {
+    res = await apiFetch(client, `${itemBase(client, ref)}/content`, {
+      method: "PUT",
+      headers: {
+        "content-type":
+          "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        "if-match": ifMatch,
+      },
+      body: bytes,
+      // NEVER retried: a PUT that timed out may already be the stored version.
+      retry: false,
+    });
+  } catch (err) {
+    return unknown("conditionalSmall", err?.message ?? String(err));
+  }
+  if (res.status === 412) return refused("conditionalSmall", "needs_reconcile");
+  if (res.status === 403) return refused("conditionalSmall", "target_access_denied", { status: 403 });
+  if (res.status === 404) return refused("conditionalSmall", "remote_missing", { status: 404 });
+  if (res.status === 429 || res.status === 503) {
+    return refused("conditionalSmall", "throttled", { status: res.status });
+  }
+  if (res.status < 200 || res.status >= 300) {
+    // A response we cannot classify is not a failure we may assume: the write
+    // may have been applied on the far side of whatever went wrong.
+    return unknown("conditionalSmall", `HTTP ${res.status}`);
+  }
+  const item = normalizeItem(res.json);
+  return landed("conditionalSmall", item, {
+    eTag: item?.eTag ?? null,
+    cTag: item?.cTag ?? null,
+    size: item?.size ?? null,
+    lastModifiedDateTime: item?.lastModifiedDateTime ?? null,
+  });
+}
+
+/**
+ * Replace an item's bytes through an upload session, large route.
+ *
+ * The precondition rides BOTH the session creation and the final chunk, because
+ * which of the two the server enforces at visibility has not been observed
+ * (doc 20 §0.2); the belt-and-braces is free.
+ */
+export async function replaceLarge(client, ref, bytes, { ifMatch, onProgress = null }) {
+  if (!ifMatch) {
+    const e = new Error("a conditional replace needs the eTag it expects to replace");
+    e.code = "conditional_write_unsupported";
+    throw e;
+  }
+  const chunkBytes = LIMITS.chunkBytes;
+  let session;
+  try {
+    const res = await apiFetch(client, `${itemBase(client, ref)}/oneDrive.createUploadSession`, {
+      method: "POST",
+      headers: { "content-type": "application/json", "if-match": ifMatch },
+      body: JSON.stringify({ item: { "@name.conflictBehavior": "replace" } }),
+      retry: false,
+    });
+    if (res.status === 412) return refused("conditionalLarge", "needs_reconcile");
+    if (res.status < 200 || res.status >= 300) {
+      return unknown("conditionalLarge", `session creation answered ${res.status}`);
+    }
+    session = res.json;
+  } catch (err) {
+    // Session creation alone changes nothing visible, but saying so would be a
+    // guess — a created session is a server-side resource with our name on it.
+    return unknown("conditionalLarge", err?.message ?? String(err));
+  }
+  const uploadUrl = session?.uploadUrl;
+  if (!uploadUrl) return unknown("conditionalLarge", "the session carried no uploadUrl");
+  // Every other server-supplied destination is transport-checked before we send to
+  // it (assertSameOrigin, transferFetch). This one carries the whole deck, so an
+  // API answer naming an http:// or otherwise unacceptable uploadUrl must not get
+  // the bytes in cleartext just because no bearer rides along.
+  let uploadTarget;
+  try {
+    uploadTarget = new URL(String(uploadUrl));
+  } catch {
+    return unknown("conditionalLarge", "the session carried an uploadUrl that is not a URL");
+  }
+  if (!transportAllowed(uploadTarget)) {
+    return unknown("conditionalLarge", `refusing a non-HTTPS upload destination (${redactUrl(uploadTarget)})`);
+  }
+
+  const total = bytes.length;
+  for (let offset = 0; offset < total; offset += chunkBytes) {
+    const end = Math.min(offset + chunkBytes, total);
+    const last = end === total;
+    const chunk = bytes.subarray(offset, end);
+    let response;
+    try {
+      // The session URL is preauthenticated: no bearer. Same rule as a download.
+      response = await client.fetch(uploadTarget.toString(), {
+        method: "PUT",
+        headers: {
+          "content-length": String(chunk.length),
+          "content-range": `bytes ${offset}-${end - 1}/${total}`,
+          // The precondition again, on the request that makes the bytes visible.
+          ...(last ? { "if-match": ifMatch } : {}),
+        },
+        body: chunk,
+        redirect: "follow",
+      });
+    } catch (err) {
+      return unknown("conditionalLarge", `chunk at ${offset} failed: ${err?.message ?? err}`);
+    }
+    if (response.status === 412) return refused("conditionalLarge", "needs_reconcile");
+    if (!last) {
+      if (response.status !== 202 && !(response.status >= 200 && response.status < 300)) {
+        return unknown("conditionalLarge", `chunk at ${offset} answered ${response.status}`);
+      }
+      onProgress?.({ uploaded: end, total });
+      continue;
+    }
+    if (response.status < 200 || response.status >= 300) {
+      return unknown("conditionalLarge", `the final chunk answered ${response.status}`);
+    }
+    let json = null;
+    try {
+      json = JSON.parse(await response.text());
+    } catch {
+      return unknown("conditionalLarge", "the commit answered a body that is not JSON");
+    }
+    const item = normalizeItem(json);
+    onProgress?.({ uploaded: total, total });
+    return landed("conditionalLarge", item, {
+      eTag: item?.eTag ?? null,
+      cTag: item?.cTag ?? null,
+      size: item?.size ?? null,
+      lastModifiedDateTime: item?.lastModifiedDateTime ?? null,
+    });
+  }
+  return unknown("conditionalLarge", "the upload ended without a commit response");
+}
+
+/**
+ * Create a new item, refusing an existing name.
+ *
+ * `fail` rather than `rename`: the destination folder is someone's actual
+ * document library, and a silent `deck 1.pptx` next to their `deck.pptx`
+ * is how two versions of one deck start circulating.
+ */
+export async function createConflictFail(client, { driveId, parentId }, name, bytes) {
+  const url =
+    `/_api/${API_VERSION}/drives/${encodeURIComponent(driveId)}/items/${encodeURIComponent(parentId)}` +
+    `:/${encodeURIComponent(name)}:/content?%40name.conflictBehavior=fail`;
+  let res;
+  try {
+    res = await apiFetch(client, url, {
+      method: "PUT",
+      headers: {
+        "content-type":
+          "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+      },
+      body: bytes,
+      retry: false,
+    });
+  } catch (err) {
+    return unknown("create", err?.message ?? String(err));
+  }
+  if (res.status === 409) return refused("create", "name_conflict", { name });
+  if (res.status === 403) return refused("create", "target_access_denied", { status: 403 });
+  if (res.status < 200 || res.status >= 300) return unknown("create", `HTTP ${res.status}`);
+  const item = normalizeItem(res.json);
+  return landed("create", item, {
+    eTag: item?.eTag ?? null,
+    cTag: item?.cTag ?? null,
+    size: item?.size ?? null,
+    lastModifiedDateTime: item?.lastModifiedDateTime ?? null,
+  });
+}
+
+/**
+ * Rename the bound item under its expected revision. Identity does not move, no
+ * second file is created, and an existing name refuses.
+ */
+export async function renameItem(client, ref, name, { ifMatch }) {
+  if (!ifMatch) {
+    const e = new Error("a rename needs the revision it expects to rename");
+    e.code = "conditional_write_unsupported";
+    throw e;
+  }
+  let res;
+  try {
+    res = await apiFetch(client, itemBase(client, ref), {
+      method: "PATCH",
+      headers: { "content-type": "application/json", "if-match": ifMatch },
+      body: JSON.stringify({ name, "@name.conflictBehavior": "fail" }),
+      retry: false,
+    });
+  } catch (err) {
+    return unknown("rename", err?.message ?? String(err));
+  }
+  if (res.status === 412) return refused("rename", "needs_reconcile");
+  if (res.status === 409) return refused("rename", "name_conflict", { name });
+  if (res.status === 403) return refused("rename", "target_access_denied", { status: 403 });
+  if (res.status === 404) return refused("rename", "remote_missing", { status: 404 });
+  if (res.status < 200 || res.status >= 300) return unknown("rename", `HTTP ${res.status}`);
+  const item = normalizeItem(res.json);
+  return landed("rename", item, {
+    eTag: item?.eTag ?? null,
+    cTag: item?.cTag ?? null,
+    size: item?.size ?? null,
+    lastModifiedDateTime: item?.lastModifiedDateTime ?? null,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// unknown-outcome inspection
+// ---------------------------------------------------------------------------
+
+/**
+ * Did OUR write land?
+ *
+ * Answered from content identity, never from a timestamp and never from "someone
+ * saved after we started". `expectedSha256` is the candidate we were uploading;
+ * if a version of the item hashes to it, that version is ours. A newer version
+ * on top of it does not make ours a failure — it makes ours superseded, which is
+ * a different thing with a different remedy (stage the newer one, keep the
+ * receipt for the version that actually landed).
+ *
+ * Returns:
+ *   { landed: true,  version, superseded }  our bytes are in the history
+ *   { landed: false, current }              they are not, and a retry is safe
+ *   { landed: null,  why }                  we could not tell — do NOT resend
+ */
+export async function inspectWriteOutcome(client, ref, { expectedSha256, expectedBytes = null }) {
+  let current;
+  try {
+    current = await getItem(client, ref);
+  } catch (err) {
+    if (err?.code === "remote_missing") return { landed: false, current: null, missing: true };
+    return { landed: null, why: err?.message ?? String(err) };
+  }
+  // The cheap case first: the item as it stands IS our bytes.
+  try {
+    const head = await downloadSnapshot(client, ref);
+    if (head.sha256 === expectedSha256) {
+      return { landed: true, version: head.revision, superseded: false, current };
+    }
+  } catch (err) {
+    return { landed: null, why: err?.message ?? String(err), current };
+  }
+  let versions;
+  try {
+    versions = await listVersions(client, ref);
+  } catch (err) {
+    return { landed: null, why: err?.message ?? String(err), current };
+  }
+  for (const version of versions) {
+    // Size is a cheap prefilter only; identity is the hash. A version of another
+    // LENGTH cannot hash to ours, so skipping it saves downloading a whole deck —
+    // and this loop runs on the recovery path, where the history can be long.
+    // Only ever skips what the hash below would have rejected anyway.
+    if (expectedBytes != null && typeof version.size === "number" && version.size !== expectedBytes) continue;
+    try {
+      const bytes = await downloadVersion(client, ref, version.versionId);
+      if (sha256(bytes) === expectedSha256) {
+        return { landed: true, version, superseded: true, current };
+      }
+    } catch {
+      return {
+        landed: null,
+        why: `version ${version.versionId} could not be read, so the history is incomplete`,
+        current,
+      };
+    }
+  }
+  return { landed: false, current };
+}
+
+export { sha256 as sha256Bytes };