@taprootio/site-authoring 0.3.0 → 0.5.0

package/src/cli.js

@@ -1,6 +1,7 @@
 import {
   CLI_BINARY_NAME,
   CLI_NAME,
+  CLI_UPGRADE_COMMAND,
   CLI_VERSION,
   DEFAULT_LOGIN_KEY_NAME,
   DEPLOY_TARGET_PRODUCTION,
@@ -22,6 +23,8 @@ import {
   VERB_PREVIEW_PAGE,
   VERB_PREVIEW_REVOKE,
   VERB_PULL,
+  VERB_REDIRECTS_PULL,
+  VERB_REDIRECTS_PUSH,
   VERB_SITES,
   VERB_STATUS,
   VERB_THEME_PUSH,
@@ -56,8 +59,21 @@ import {
   CAPABILITY_DEPLOYMENTS,
   CAPABILITY_DESIGN,
 } from "./capabilities.js";
+import { assertCliCurrent } from "./session.js";
 import { VERB_HANDLERS } from "./verbs/index.js";
 
+/**
+ * The verbs the local version gate applies to (TR00703).
+ *
+ * Exactly the three that make no request. Every other verb reaches Taproot,
+ * whose own refusal is authoritative and better informed than this recording,
+ * so gating them here would only duplicate an answer — and gating `login`,
+ * `logout`, or `env` would take away the commands an operator needs while they
+ * are outdated. `--help` and `--version` are outside it for the same reason:
+ * they are how someone finds out what they have.
+ */
+const VERSION_GATED_OFFLINE_VERBS = Object.freeze([VERB_HELP, VERB_VALIDATE, VERB_WHOAMI]);
+
 // One entry per verb, in help order. `tokens` is the exact leading positional
 // sequence; matching prefers the longest sequence, so a two-token family can
 // never be shadowed by a one-token verb.
@@ -197,8 +213,9 @@ const VERBS = Object.freeze([
       + "The homepage is recorded with an empty path, so address it as '/'. "
       + "A selected path resolves to its one authoritative source from metadata alone, and that page is then validated "
       + "exactly as a whole push would validate it — site binding, manifest integrity, live create-or-update "
-      + "resolution, system-page rules, path uniqueness against the live site, media ownership, and two workspace "
-      + "files claiming one path all still fail closed. What a selection does not do is convert or validate the "
+      + "resolution, system-page rules, path uniqueness against the live site, media ownership, a live page whose "
+      + "stored-state revision moved since this workspace last reconciled with it (pages.push_conflict), and two "
+      + "workspace files claiming one path all still fail closed. What a selection does not do is convert or validate the "
       + "documents of pages it is not sending: an unrelated page left on an obsolete contract is reported by the "
       + "whole-workspace push, not used to block this one. The result states the selection and how many sources were "
       + "discovered and validated. "
@@ -219,6 +236,28 @@ const VERBS = Object.freeze([
     tokens: ["nav", "push"],
     summary: "Replace the whole navigation tree from the local workspace.",
   },
+  {
+    name: VERB_REDIRECTS_PULL,
+    // A redirect is a content path, and both halves of the map — read and
+    // replace — are gated on site.pages.edit_any, which only Content carries.
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["redirects", "pull"],
+    summary: "Snapshot the site's whole redirect map into redirects.json.",
+    note: "Also part of 'pull'. Run it on its own to re-read the map after a page rename, or after a push was "
+      + "refused as a conflict, without re-pulling every page. It records the map's revision in the pull "
+      + "manifest; 'redirects push' sends that revision so a stale replace is refused rather than deleting an "
+      + "entry a rename recorded. See 'taproot-site help redirects'.",
+  },
+  {
+    name: VERB_REDIRECTS_PUSH,
+    capabilities: [CAPABILITY_CONTENT],
+    tokens: ["redirects", "push"],
+    summary: "Validate redirects.json and replace the whole redirect map.",
+    note: "Run 'redirects pull' first. The whole file is validated locally by entry index — path normalization, "
+      + "targets, statuses, duplicates, chains, and loops — before anything is sent, and the site refuses a "
+      + "source a live page occupies. Entries take effect on the next deploy. "
+      + "See 'taproot-site help redirects'.",
+  },
   {
     name: VERB_THEME_PUSH,
     capabilities: [CAPABILITY_DESIGN],
@@ -304,7 +343,7 @@ const VERBS = Object.freeze([
     // Content.
     capabilities: [CAPABILITY_CONTENT, CAPABILITY_DEPLOYMENTS],
     tokens: ["status"],
-    summary: "Report deployments, readiness, and image processing.",
+    summary: "Report the platform authoring switch, the CLI release, deployments, readiness, and image processing.",
     note: "Broken references are not included: that read remains"
       + " session-only on the server, so the result reports it as uncovered"
       + " rather than pretending an empty list means a clean site.",
@@ -353,6 +392,15 @@ whoami, and env need no configuration and no site. The offline help family is
 human-readable by default; add --json for stable reference data. Exit codes: 0
 success, 1 failure, 2 usage fault.
 
+Troubleshooting: a command that fails with field=CliUpgradeRequired (or
+refusal=cli_outdated) means this CLI is behind the latest published release,
+which is the only release Taproot accepts. Nothing is wrong with the
+credential, the request, or the site, and no retry of this version succeeds.
+Run '${CLI_UPGRADE_COMMAND}' and try again; if the
+release is minutes old, npm may not serve it yet, so wait and retry the
+upgrade. Once a run has recorded a newer release, help, validate, and whoami
+refuse the same way offline. --version and --help always answer.
+
 Verbs:
 ${VERBS.map((verb) => `  ${verb.tokens.join(" ").padEnd(14)} ${verb.summary}`).join("\n")}
 
@@ -408,11 +456,22 @@ function verbHelp(verb) {
   // would have had to gain.
   const selfContained = verb.offline && !verb.readsLocalState;
   const prefix = selfContained ? CLI_BINARY_NAME : `${CLI_BINARY_NAME} [--config <path>]`;
+  // The offline boundary states the version gate too (TR00703). It is the one
+  // thing these verbs read that is not their own input, and a boundary sentence
+  // that omitted it would be describing a verb that no longer exists.
+  // `env` is offline too and deliberately outside the gate — switching Taproots
+  // is one of the things an outdated CLI must still be able to do — so the
+  // sentence is attached per verb rather than to offline-ness.
+  const upgradeGate = VERSION_GATED_OFFLINE_VERBS.includes(verb.name)
+    ? " It refuses only when a previous sign-in exchange recorded a newer published release than this CLI, because "
+      + "Taproot accepts only the latest; with nothing recorded it runs."
+    : "";
   const boundary = selfContained
-    ? "This offline verb reads no configuration or credential and performs no network request or write."
+    ? "This offline verb uses no credential and reads no configuration, and performs no network request and no "
+      + `write.${upgradeGate}`
     : verb.offline
     ? "This verb answers entirely from local state — the stored sign-in and the configuration — and makes no "
-      + "network request and no write."
+      + `network request and no write.${upgradeGate}`
     : verb.credentialFree
     ? `This verb reads the configuration but requires no existing credential. `
       + `${PUBLISH_KEY_ENVIRONMENT_VARIABLE} always takes precedence over the stored credential, so setting it leaves `
@@ -500,6 +559,7 @@ function parseReferenceArguments(arguments_) {
       || topic === "appearance"
       || topic === "footer"
       || topic === "fixture"
+      || topic === "redirects"
     )
     && (subject !== undefined || extra.length > 0)) {
     throw usageError("help.usage", `The '${topic}' topic does not accept a name.`);
@@ -549,6 +609,7 @@ function referenceResult(parsed) {
       return { ...result, topic: "component", component };
     }
     case "nav":
+    case "redirects":
     case "media":
     case "preview":
     case "fixture":
@@ -855,10 +916,14 @@ export async function runCli({
       return 0;
     }
     if (parsed.mode === "reference") {
+      await assertCliCurrent(environment);
       const result = referenceResult(parsed);
       stdout.write(parsed.json ? `${serializeResult(result)}\n` : formatReferenceResult(result));
       return 0;
     }
+    if (VERSION_GATED_OFFLINE_VERBS.includes(parsed.verb)) {
+      await assertCliCurrent(environment);
+    }
     // Own properties only: a verb name must never resolve through the
     // prototype chain to something like `constructor`.
     const handler = Object.hasOwn(handlers, parsed.verb) ? handlers[parsed.verb] : undefined;

package/src/constants.js

@@ -1,5 +1,5 @@
 export const CLI_NAME = "@taprootio/site-authoring";
-export const CLI_VERSION = "0.3.0";
+export const CLI_VERSION = "0.5.0";
 export const CLI_BINARY_NAME = "taproot-site";
 export const RESULT_SCHEMA_VERSION = 1;
 export const CONFIG_FILE_NAME = "taproot-site.json";
@@ -82,6 +82,8 @@ export const VERB_LOGIN = "login";
 export const VERB_LOGOUT = "logout";
 export const VERB_PAGES_PUSH = "pages push";
 export const VERB_NAV_PUSH = "nav push";
+export const VERB_REDIRECTS_PULL = "redirects pull";
+export const VERB_REDIRECTS_PUSH = "redirects push";
 export const VERB_THEME_PUSH = "theme push";
 export const VERB_FOOTER_PUSH = "footer push";
 export const VERB_MEDIA_UPLOAD = "media upload";
@@ -109,6 +111,7 @@ export const REFUSAL_CREDENTIAL_REJECTED = "credential_rejected";
 export const REFUSAL_PLAN_LIMIT = "plan_limit";
 export const REFUSAL_THROTTLED = "throttled";
 export const REFUSAL_CAPABILITY_MISSING = "capability_missing";
+export const REFUSAL_CLI_OUTDATED = "cli_outdated";
 export const REFUSAL_UNCLASSIFIED = "unclassified";
 
 export const REFUSAL_KINDS = Object.freeze([
@@ -117,6 +120,7 @@ export const REFUSAL_KINDS = Object.freeze([
   REFUSAL_PLAN_LIMIT,
   REFUSAL_THROTTLED,
   REFUSAL_CAPABILITY_MISSING,
+  REFUSAL_CLI_OUTDATED,
   REFUSAL_UNCLASSIFIED,
 ]);
 
@@ -127,6 +131,34 @@ export const ROLLOUT_REFUSAL_FIELD = "SiteAuthoringRollout";
 export const CREDENTIAL_REFUSAL_FIELD = "ExternalApiKey";
 export const PLAN_LIMIT_REFUSAL_FIELD = "UpgradePrompt";
 
+/**
+ * The field Taproot refuses an outdated CLI with (TR00703).
+ *
+ * Named so the name alone is the instruction, because for every CLI published
+ * before this check that is the whole message: an unknown refusal field prints
+ * as "Taproot rejected the request field '<name>'." and nothing else.
+ */
+export const CLI_UPGRADE_REFUSAL_FIELD = "CliUpgradeRequired";
+
+/**
+ * How an operator gets current. Composed from {@link CLI_NAME} so the command
+ * in a refusal cannot drift from the package that refusal is about.
+ */
+export const CLI_UPGRADE_COMMAND = `npm install -g ${CLI_NAME}@latest`;
+
+/**
+ * The platform switch behind every `platform_paused` refusal, and where the one
+ * person who can undo it goes to look (TR00692).
+ *
+ * Held here rather than written out at each site because four surfaces say it —
+ * the pre-write warning, `status`, `whoami`, and the refusal guidance — and a
+ * setting key spelled four ways is a key an operator cannot search for. The key
+ * is a wire identity and is never reworded; the location is display text.
+ */
+export const EXTERNAL_WRITES_SETTING_KEY = "site_authoring.external_writes_enabled";
+export const EXTERNAL_WRITES_SETTING_LOCATION =
+  "Admin → Platform settings → Site Authoring (\"External site authoring writes enabled\")";
+
 /**
  * The `google.rpc.ErrorInfo` reason a key-mode permission denial carries
  * (TR00691, `SiteAuthoringKeyDenial` on the server). A wire identity, matched
@@ -165,6 +197,10 @@ export const LIMITS = Object.freeze({
   configDiscoveryParents: 32,
   workspacePathBytes: 4 * 1024,
   apiResponseBytes: 1024 * 1024,
+  // The redirect map is the one read whose valid size exceeds the ordinary
+  // response bound: two thousand entries with long absolute targets. Sized
+  // with the workspace file that holds it (WORKSPACE_LIMITS.redirectsBytes).
+  redirectMapResponseBytes: 8 * 1024 * 1024,
   requestMilliseconds: 60_000,
   uploadMilliseconds: 5 * 60_000,
   deploymentMilliseconds: 30 * 60_000,

package/src/content/components.js

@@ -1,7 +1,9 @@
-// Espalier 4.2 exposes this registry value only through its root component,
-// whose import also registers `esp-root`. Replace this with the side-effect-free
-// shared registry export when Espalier publishes that package subpath.
-import { BUILT_IN_IMAGE_TEXTURES } from "@taprootio/espalier/root";
+// Espalier 4.8.0 publishes the texture registry as a side-effect-free subpath
+// (TR00630). Import it from there, never from `@taprootio/espalier/root`: that
+// module registers `esp-root`, so a process already holding another Espalier
+// copy — the generator's Playwright Node process, for one — cannot load this
+// pipeline at all once a component module is in the graph.
+import { BUILT_IN_IMAGE_TEXTURES } from "@taprootio/espalier/shared/image-texture-registry";
 import { hasAsciiControl } from "../errors.js";
 import {
   CONTENT_ERROR_CODES as CODES,
@@ -195,7 +197,8 @@ const TESTIMONIAL = Object.freeze({
   borderWidth: num({
     integer: true,
     minimum: 0,
-    description: "Pixel border around the whole set of quotations — the grid or the carousel; 0 leaves it unbordered.",
+    description:
+      "Pixel border around each quotation, as on a card grid; a carousel shows the visible slide's own box and is never framed. 0 boxes nothing.",
   }),
 });
 

package/src/credentials.js

@@ -6,6 +6,7 @@ import path from "node:path";
 import { atomicWriteFile } from "./atomic-file.js";
 import { readBoundedFile } from "./bounded-file.js";
 import { SITE_AUTHORING_CAPABILITIES } from "./capabilities.js";
+import { parseCliVersion } from "./cli-release.js";
 
 import {
   CANONICAL_TIMESTAMP,
@@ -63,6 +64,11 @@ export const KEY_PREFIX = /^[\w.-]{1,64}$/u;
 const PROJECTION_UUID = "00000000-0000-4000-8000-000000000000";
 const PROJECTION_TIMESTAMP = "2000-01-01T00:00:00.000Z";
 const PROJECTION_KEY_PREFIX_LENGTH = 64;
+// A version string as long as the reader admits (MAXIMUM_VERSION_LENGTH in
+// cli-release.js, 64 characters), for the same reason the prefix above is
+// padded: the projection is an upper bound on the record a first exchange will
+// write (TR00703).
+const PROJECTION_LATEST_CLI_VERSION = `999999.999999.999999-${"a".repeat(43)}`;
 
 function usableDirectory(value) {
   return typeof value === "string"
@@ -134,9 +140,17 @@ function normalizeEntry(entry) {
     "A stored credential record has an invalid createdAt.",
   );
   // What the last exchange produced. Entirely non-secret — a site id, the
-  // capabilities that exchange asked for, and when the credential it returned
-  // dies — and the only way `whoami` can answer "what can this actually do"
-  // without a network round trip. Absent before the first exchange.
+  // capabilities that exchange asked for, when the credential it returned dies,
+  // when the exchange happened, and what Taproot then said about the
+  // platform-wide authoring switch — and the only way `whoami` can answer "what
+  // can this actually do" without a network round trip. Absent before the first
+  // exchange.
+  //
+  // `at` and `externalWritesEnabled` are optional on top of that (TR00692), and
+  // `latestCliVersion` on top of those (TR00703): a record written by an
+  // earlier version carries none of them, and a server that predates either
+  // field carries no value for it. Refusing those would make a routine upgrade
+  // look like a corrupt store.
   requireStoreShape(
     entry.lastExchange === undefined
       || (entry.lastExchange !== null
@@ -146,7 +160,16 @@ function normalizeEntry(entry) {
         && Array.isArray(entry.lastExchange.capabilities)
         && entry.lastExchange.capabilities.every((value) => typeof value === "string")
         && typeof entry.lastExchange.expiresAt === "string"
-        && CANONICAL_TIMESTAMP.test(entry.lastExchange.expiresAt)),
+        && CANONICAL_TIMESTAMP.test(entry.lastExchange.expiresAt)
+        && (entry.lastExchange.at === undefined
+          || (typeof entry.lastExchange.at === "string" && CANONICAL_TIMESTAMP.test(entry.lastExchange.at)))
+        && (entry.lastExchange.externalWritesEnabled === undefined
+          || typeof entry.lastExchange.externalWritesEnabled === "boolean")
+        // Only a version this side can compare is admitted, because the value's
+        // whole job is to be compared: a record carrying something unparseable
+        // could never gate anything, so storing it would be storing noise.
+        && (entry.lastExchange.latestCliVersion === undefined
+          || parseCliVersion(entry.lastExchange.latestCliVersion) !== undefined)),
     "A stored credential record has an invalid lastExchange.",
   );
   return Object.freeze({
@@ -161,6 +184,13 @@ function normalizeEntry(entry) {
         siteId: entry.lastExchange.siteId,
         capabilities: Object.freeze([...entry.lastExchange.capabilities]),
         expiresAt: entry.lastExchange.expiresAt,
+        ...(entry.lastExchange.at === undefined ? {} : { at: entry.lastExchange.at }),
+        ...(entry.lastExchange.externalWritesEnabled === undefined
+          ? {}
+          : { externalWritesEnabled: entry.lastExchange.externalWritesEnabled }),
+        ...(entry.lastExchange.latestCliVersion === undefined
+          ? {}
+          : { latestCliVersion: entry.lastExchange.latestCliVersion }),
       }),
     }),
     createdAt: entry.createdAt,
@@ -469,6 +499,11 @@ export async function assertCredentialCapacity(environment, apiOrigin) {
       siteId: PROJECTION_UUID,
       capabilities: [...SITE_AUTHORING_CAPABILITIES],
       expiresAt: PROJECTION_TIMESTAMP,
+      at: PROJECTION_TIMESTAMP,
+      // `false` rather than `true`: it serializes one byte longer, and the
+      // projection's whole job is to be an upper bound on the real record.
+      externalWritesEnabled: false,
+      latestCliVersion: PROJECTION_LATEST_CLI_VERSION,
     },
     createdAt: PROJECTION_TIMESTAMP,
   });

package/src/errors.js

@@ -112,6 +112,31 @@ export class SiteAuthoringError extends Error {
     return this;
   }
 
+  /**
+   * Attach the JSON paths at which two documents differ.
+   *
+   * Separate from `alternatives`, which is the bounded list of other values or
+   * targets a caller can act on — the files in a pull conflict, but equally the
+   * help topics, page types, or revisions another failure offers. These name
+   * locations inside one document, decide nothing, and exist so a conflict can
+   * be triaged without re-fetching both sides by hand.
+   *
+   * A list and no list are different facts, so anything that is not a list
+   * leaves the field unset rather than becoming an empty one: `[]` means the
+   * documents were compared and found identical, and absent means there was
+   * nothing to compare them against. Collapsing the second into the first would
+   * tell an agent the body is unchanged for a comparison that never ran.
+   */
+  withDifferences(paths) {
+    this.differences = Array.isArray(paths)
+      ? paths
+        .filter((value) => typeof value === "string")
+        .slice(0, 100)
+        .map((value) => sanitizeDiagnostic(value, "path"))
+      : undefined;
+    return this;
+  }
+
   /** Attach the non-secret identity needed to inspect or revoke a created preview. */
   withPreviewRecovery(preview) {
     const recovery = normalizePreviewRecovery(preview);

package/src/fixture-contract.js

@@ -22,6 +22,7 @@ export const FIXTURE_REQUIRED_ROOT_FIELDS = Object.freeze([
   "pages",
   "pagesTruncated",
   "navigation",
+  "redirects",
   "settings",
   "settingsSkipped",
   "fixture",

package/src/json-path-diff.js

@@ -0,0 +1,167 @@
+/**
+ * Says *what* differs between two page documents, in JSON paths.
+ *
+ * A conflict that only says "this page changed on the site" leaves the operator
+ * with a choice nobody can make well: re-push identical content, or abandon the
+ * local source. On the SHY production home page (2026-09-03) the entire
+ * difference was `$.content[0].attrs.decoration.image.src` and the sibling
+ * `.urls` — two fields the API re-projects on every read from live image state
+ * — and a list of paths would have shown that in one line.
+ *
+ * This decides nothing. The revision comparison decides; this explains it. So
+ * it is deliberately generous about what counts as a difference and strictly
+ * bounded in what it will spend finding out: a diagnostic that hangs on a
+ * hostile document is worse than one that says "and more".
+ */
+
+/** How many differing paths one report carries before it says "and more". */
+export const JSON_DIFFERENCE_LIMIT = 20;
+
+/**
+ * How deep the comparison descends. `canonicalDocumentHash` refuses a document
+ * nesting deeper than this, and every document compared here has already been
+ * through it, so the bound is unreachable for real content. A subtree at the
+ * bound is reported as differing rather than skipped in silence: over-reporting
+ * a diagnostic is safe, and quietly not comparing is not.
+ */
+const MAXIMUM_DEPTH = 100;
+
+/**
+ * A ceiling on total work, because both sides are documents this process did
+ * not author: one is the site's, the other a file on disk.
+ */
+const MAXIMUM_VISITS = 200_000;
+
+/** How much of one object key a path segment carries. */
+const MAXIMUM_SEGMENT_SCALARS = 64;
+
+/** How long one rendered path may be before its middle is elided. */
+const MAXIMUM_PATH_SCALARS = 200;
+
+const PLAIN_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+
+function boundSegment(key) {
+  const scalars = [...key];
+  return scalars.length <= MAXIMUM_SEGMENT_SCALARS
+    ? key
+    : `${scalars.slice(0, MAXIMUM_SEGMENT_SCALARS).join("")}…`;
+}
+
+function childPath(path, key) {
+  const segment = boundSegment(key);
+  return PLAIN_KEY.test(segment) ? `${path}.${segment}` : `${path}[${JSON.stringify(segment)}]`;
+}
+
+function indexPath(path, index) {
+  return `${path}[${index}]`;
+}
+
+function boundPath(path) {
+  const scalars = [...path];
+  if (scalars.length <= MAXIMUM_PATH_SCALARS) return path;
+  const head = scalars.slice(0, MAXIMUM_PATH_SCALARS - 20).join("");
+  const tail = scalars.slice(-19).join("");
+  return `${head}…${tail}`;
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * The paths at which two parsed JSON values differ.
+ *
+ * Returns `{ paths, truncated }`. `paths` is empty when the two documents are
+ * structurally identical — which, on a page whose revision moved, is the useful
+ * answer: the stored state changed in a field this comparison does not cover.
+ *
+ * `truncated` means the walk stopped early — either more than `limit`
+ * differences exist, or the documents are large enough to have exhausted the
+ * work ceiling — so the list is a sample rather than the whole story.
+ */
+export function describeJsonDifferences(left, right, { limit = JSON_DIFFERENCE_LIMIT } = {}) {
+  const bound = Number.isSafeInteger(limit) && limit > 0 ? limit : JSON_DIFFERENCE_LIMIT;
+  // One past the reported bound. Stopping *at* the bound could not tell "these
+  // are all of them" from "there were more", and a sample presented as a
+  // complete list is the kind of diagnostic that sends someone looking in the
+  // wrong place.
+  const cap = bound + 1;
+  const paths = [];
+  let exhausted = false;
+  let visits = 0;
+
+  const record = (path) => {
+    paths.push(boundPath(path));
+  };
+
+  const walk = (leftValue, rightValue, path, depth) => {
+    if (paths.length >= cap || exhausted) return;
+    visits += 1;
+    if (visits > MAXIMUM_VISITS) {
+      exhausted = true;
+      return;
+    }
+    if (depth > MAXIMUM_DEPTH) {
+      record(path);
+      return;
+    }
+
+    if (Array.isArray(leftValue) && Array.isArray(rightValue)) {
+      const shared = Math.min(leftValue.length, rightValue.length);
+      for (let index = 0; index < shared; index += 1) {
+        walk(leftValue[index], rightValue[index], indexPath(path, index), depth + 1);
+        if (paths.length >= cap || exhausted) return;
+      }
+      // An added or removed element is named by its own index rather than by
+      // the array, so "one section was appended" reads differently from "every
+      // section moved".
+      for (let index = shared; index < Math.max(leftValue.length, rightValue.length); index += 1) {
+        record(indexPath(path, index));
+        if (paths.length >= cap || exhausted) return;
+      }
+      return;
+    }
+
+    if (isPlainObject(leftValue) && isPlainObject(rightValue)) {
+      // Sorted so two runs over the same pair of documents report the same
+      // paths in the same order, whatever order the members arrived in.
+      const keys = [...new Set([...Object.keys(leftValue), ...Object.keys(rightValue)])].sort();
+      for (const key of keys) {
+        const inLeft = Object.hasOwn(leftValue, key);
+        const inRight = Object.hasOwn(rightValue, key);
+        if (!inLeft || !inRight) {
+          record(childPath(path, key));
+        } else {
+          walk(leftValue[key], rightValue[key], childPath(path, key), depth + 1);
+        }
+        if (paths.length >= cap || exhausted) return;
+      }
+      return;
+    }
+
+    // Different kinds, or two scalars. `Object.is` rather than `===` so two
+    // NaN bodies do not read as a difference; JSON has no NaN, but these
+    // documents reach here through `JSON.parse` of untrusted bytes and a
+    // caller may hand over something else.
+    if (!Object.is(leftValue, rightValue)) record(path);
+  };
+
+  walk(left, right, "$", 0);
+  return { paths: paths.slice(0, bound), truncated: exhausted || paths.length > bound };
+}
+
+/**
+ * The paths a conflict may claim, or `undefined` when no claim is honest.
+ *
+ * An empty list is the statement "compared, and the body is identical", which
+ * an agent reads as "look at the title, path, or description instead". That
+ * statement cannot be made when nothing was compared, and it cannot be made
+ * when the walk exhausted its budget before it reached a difference: two
+ * documents that agree for the first two hundred thousand nodes and differ
+ * afterwards are different, not identical.
+ */
+export function reportableDifferencePaths(differences) {
+  if (differences === undefined) return undefined;
+  if (differences.paths.length === 0 && differences.truncated) return undefined;
+  return differences.paths;
+}

package/src/output.js

@@ -42,6 +42,15 @@ export function failureResult(error) {
   if (Array.isArray(error.completedWrites) && error.completedWrites.length > 0) {
     result.error.completedWrites = error.completedWrites;
   }
+  // Three states, and an agent acts differently on each. Absent: the two
+  // documents were never compared, because this workspace kept no copy of the
+  // site's previous version. Empty: they were compared and the body is
+  // identical, so the change that raised the conflict is in the page's title,
+  // path, or description. Non-empty: the JSON paths at which they differ.
+  // Suppressing the empty array would collapse the first two into one.
+  if (Array.isArray(error.differences)) {
+    result.error.differences = error.differences;
+  }
   const previewRecovery = normalizePreviewRecovery(error.previewRecovery);
   if (previewRecovery) result.error.preview = previewRecovery;
   const refusal = typeof error.refusalKind === "function" ? error.refusalKind() : undefined;