@taprootio/site-authoring 0.3.0 → 0.4.0

package/src/reference-help.js

@@ -13,6 +13,13 @@ import {
   SHIPPED_FIXTURE_NAME,
   shippedFixtureDirectory,
 } from "./fixture-contract.js";
+import {
+  DEFAULT_REDIRECT_STATUS,
+  GONE_STATUS,
+  REDIRECT_LIMITS,
+  REDIRECT_STATUSES,
+  REDIRECTS_FILE_NAME,
+} from "./redirects-contract.js";
 import { SETTINGS_GROUPS } from "./settings-catalog.js";
 import {
   canonicalizeComponentData,
@@ -49,7 +56,7 @@ import {
 
 export { getAppearanceReference, getFooterReference, getThemeReference };
 
-export const REFERENCE_VERSION = 16;
+export const REFERENCE_VERSION = 17;
 export const PAGE_TYPES = Object.freeze(["free-form"]);
 export const REFERENCE_TOPICS = Object.freeze([
   Object.freeze({ name: "pages", usage: `${CLI_BINARY_NAME} help pages`, summary: "List authorable page types." }),
@@ -69,6 +76,11 @@ export const REFERENCE_TOPICS = Object.freeze([
     summary: "Describe one component schema and show a valid example.",
   }),
   Object.freeze({ name: "nav", usage: `${CLI_BINARY_NAME} help nav`, summary: "Describe nav.json item shapes." }),
+  Object.freeze({
+    name: "redirects",
+    usage: `${CLI_BINARY_NAME} help redirects`,
+    summary: "Author redirects.json: entry shape, normalization, and the refusals.",
+  }),
   Object.freeze({
     name: "media",
     usage: `${CLI_BINARY_NAME} help media`,
@@ -125,6 +137,81 @@ const WORKFLOW_REFERENCES = Object.freeze({
       })]),
     }),
   }),
+  redirects: Object.freeze({
+    title: "Redirect map workspace contract",
+    summary:
+      `${REDIRECTS_FILE_NAME} is the site's whole redirect map. 'redirects push' replaces it, fenced by the `
+      + "revision 'redirects pull' recorded, so a stale write is refused rather than deleting an entry a page "
+      + "rename added.",
+    usage: `${CLI_BINARY_NAME} redirects pull | ${CLI_BINARY_NAME} redirects push`,
+    details: Object.freeze([
+      `${REDIRECTS_FILE_NAME} is { siteId, revision, entries }, not a bare array. 'redirects pull' writes it and `
+      + "records the revision in .taproot-site-manifest.json; 'pull' writes it too.",
+      "An entry is { path, kind, target, status }. kind is 'redirect' (the default) or 'gone'; a gone entry "
+      + `carries no target and serves ${GONE_STATUS}.`,
+      `status defaults to ${DEFAULT_REDIRECT_STATUS} and accepts ${REDIRECT_STATUSES.join(", ")}. A migration `
+      + `wants ${DEFAULT_REDIRECT_STATUS}: it is what tells search engines the old URL has moved for good.`,
+      "path is normalized exactly as the published-site edge normalizes a request: a leading slash is added, "
+      + "trailing slashes are stripped, and nothing else changes — so a legacy source keeps its suffix and "
+      + "'/faqs.html' is a real, representable path. It carries no query string, fragment, or host.",
+      "Write a path — and the path part of a site-relative target — in the percent-encoded spelling a browser "
+      + "sends ('/caf%C3%A9', '/old%20page'), never the raw one: the edge keys on the encoded pathname, so a raw "
+      + "space or non-ASCII character is stored under a key no request matches, and a raw target beside an "
+      + "encoded source is the self-loop loop detection cannot see.",
+      "target is a site-relative path such as '/classes', or an absolute credential-free http(s) URL. A "
+      + "site-relative target keeps its trailing slash: it is a Location a browser follows, not a route key.",
+      "A path, or the path part of a site-relative target, is refused when any segment is '.' or '..', when two "
+      + "slashes run together, or when a dot or slash is percent-encoded ('%2e', '%2f'); a target's query string "
+      + "may carry any of those. The edge and the generator resolve "
+      + "those away, so '/x/../visit' would be checked as itself and served as '/visit' — past the occupancy, "
+      + "chain, and loop rules that were asked about a different path. Write the resolved path instead.",
+      "origin is reported by the site and ignored on push: 'authored' is what you declared, 'path_history' is "
+      + "what a page or tag rename recorded. Pull the map, edit it, push the whole thing back — an entry you "
+      + "did not change keeps its origin.",
+      "Refused, offline and again at the site, each naming the entry index: a chain (a target that is itself a "
+      + "source in the same map); a loop (an entry targeting itself); a duplicate path; a gone entry carrying a "
+      + "target; and a status outside the allowed set. A chain or loop is judged on the target's path alone, so "
+      + "'/b?x=1' and '/b' are the same destination to it.",
+      "Refused by the site, which alone knows what it serves: a path a live page, Docs resource, or generated "
+      + "resource already occupies. '/' is such a path while the site's home page is served there — and a "
+      + "usable source once the home page has moved, which is the entry a home-page rename records.",
+      `Bounded: at most ${REDIRECT_LIMITS.entries} entries, ${REDIRECT_LIMITS.pathBytes} bytes of path, and `
+      + `${REDIRECT_LIMITS.targetBytes} bytes of target, matching the edge's own key and value limits.`,
+      `The ${REDIRECT_LIMITS.pathBytes}-byte path bound governs what you declare, not what the site already `
+      + "holds. A page may sit at a longer path, and renaming it records a path_history entry there that "
+      + "'redirects pull' returns; such an entry passes 'validate' and pushes back unchanged. The site is the "
+      + "authority on that — it alone knows whether a push introduces the path or carries it back — so a push "
+      + "that lengthens or changes one is still refused there.",
+      `The ${REDIRECT_LIMITS.entries}-entry bound is scoped the same way: a pulled map already holding more `
+      + "than that validates and pushes back unchanged, and only a document holding more entries than both the "
+      + "bound and the count the last pull recorded is refused — so accumulated path history never has to be "
+      + "deleted to make a push land.",
+      "A push whose recorded revision predates a page rename is refused as redirects.concurrent_modification. "
+      + `Run 'redirects pull', reconcile ${REDIRECTS_FILE_NAME}, and retry; nothing was written.`,
+      "Converting an engagement's CSV into this file is the agent's job. The CLI's contract is JSON, on "
+      + "purpose: a real migration list needs judgement about which old URLs still deserve a destination and "
+      + "which are simply gone.",
+      "Entries take effect on the next deploy, staging first. They are written to the edge's key-value store "
+      + "when the deploy syncs routing, and that store is eventually consistent, so a spot-check run "
+      + "immediately afterwards can briefly still see the previous map. Re-check before concluding an entry "
+      + "did not land.",
+    ]),
+    example: Object.freeze({
+      siteId: "<site-uuid>",
+      revision: "<revision-recorded-by-redirects-pull>",
+      entries: Object.freeze([
+        Object.freeze({ path: "/faqs.html", kind: "redirect", target: "/faq", status: 301 }),
+        Object.freeze({ path: "/old-blog", kind: "redirect", target: "/journal", status: 301 }),
+        Object.freeze({
+          path: "/book",
+          kind: "redirect",
+          target: "https://booking.example.test/riverbend",
+          status: 302,
+        }),
+        Object.freeze({ path: "/summer-2019-retreat.html", kind: "gone" }),
+      ]),
+    }),
+  }),
   media: Object.freeze({
     title: "Media upload contract",
     summary: "Upload workspace-root-relative raster files and receive component-ready media objects.",
@@ -194,6 +281,10 @@ const WORKFLOW_REFERENCES = Object.freeze({
       "pages must declare at least one entry, pagesTruncated must be false, and settingsSkipped must be empty: a "
       + "partial snapshot is not a fixture.",
       `navigation binds { file: "${NAVIGATION_FILE_NAME}", items }, and items must equal the tree's own item count.`,
+      `redirects binds { file: "${REDIRECTS_FILE_NAME}", revision, entries }, and entries must equal the map's own `
+      + "entry count. The revision is a deterministic 64-character lowercase hex placeholder, like every other "
+      + "identity in a fixture: it proves the shape, never a live read. No redirect source may be a page in the "
+      + `same fixture. See '${CLI_BINARY_NAME} help redirects' for the entry contract.`,
       `settings binds all ${SETTINGS_GROUPS.length} authorable groups, each with settingsType, file, and entityId: ${
         SETTINGS_GROUPS.map((group) => `${group.settingsType} to '${SETTINGS_DIRECTORY}/${group.file}'`).join("; ")
       }.`,
@@ -690,9 +781,11 @@ const FREE_FORM_REFERENCE = Object.freeze({
       pull:
         "pull keeps a tracked source that is still on disk and never writes a second editable file for the same page.",
       internalState:
-        `${INTERNAL_PAGE_BASELINE_DIRECTORY}/<pageId>.pm.json holds the site's document for a page tracked as Markdown. `
-        + "It is internal state: it is never discovered as a page source and is never pushed, and any pull rewrites "
-        + "it, so it is safe to ignore in version control.",
+        `${INTERNAL_PAGE_BASELINE_DIRECTORY}/<pageId>.pm.json holds the site's document for a page tracked as Markdown, `
+        + "and <pageId>.revision.json beside it records the revision a refused pull already showed you — which is what "
+        + "lets the refusal's own recovery push proceed. Both are internal state: never discovered as a page source "
+        + "and never pushed, and a pull that reconciles the page rewrites or removes them, so they are safe to ignore "
+        + "in version control.",
       formatChange:
         "Remove the tracked source, then author the other format beside it. Two editable sources for one path is a "
         + "refusal, not a guess.",
@@ -706,6 +799,24 @@ const FREE_FORM_REFERENCE = Object.freeze({
         + "refuses before changing anything under pages/ and preserves the site's version as internal state. A "
         + "locally edited .pm.json is kept rather than overwritten, and only collides when the site changed too.",
       conflictError: "pages.pull_conflict",
+      conflictDetail:
+        "A reported conflict names the JSON paths at which the site's document differs from the copy this workspace "
+        + "last reconciled with, in error.differences, which carries three states. 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 was to the page's title, path, or description. "
+        + "Non-empty: the JSON paths at which the body differs.",
+      pushConflict:
+        "pages push fails closed on a concurrent remote edit: the site reports each page's stored-state revision, the "
+        + "workspace records the revision of what it last wrote or pulled, and a push whose target now carries a "
+        + "different revision is refused before any page is sent. The refusal carries both revisions in "
+        + "error.alternatives, recorded first and live second. The guard is armed once both are known — a page this "
+        + "workspace has never reconciled with, or a Taproot that predates the revision contract, leaves it unarmed "
+        + "rather than refusing every push. A pull that refuses records the revision it showed you, so the pull "
+        + "conflict's own recovery push still goes through; a page that moved again since is refused again.",
+      pushConflictError: "pages.push_conflict",
+      revisionSource:
+        "baseline.revision in the manifest, from bodyRevision on the page read, the page listing, and the create and "
+        + "update responses. It is opaque: compare it, never derive or parse it.",
       conflictRecovery:
         "Either push the local source to make the site match it, or delete the local source and pull again to adopt "
         + "the site's document as that page's source.",
@@ -993,7 +1104,13 @@ export function formatReferenceResult(result) {
         sourceRule.renamedSource
       } (${sourceRule.renamedSourceError})\n  conflicts             ${
         sourceRule.conflict
-      } (${sourceRule.conflictError})\n  recovery              ${
+      } (${sourceRule.conflictError})\n  conflict detail       ${
+        sourceRule.conflictDetail
+      }\n  push conflicts        ${
+        sourceRule.pushConflict
+      } (${sourceRule.pushConflictError})\n  revision              ${
+        sourceRule.revisionSource
+      }\n  recovery              ${
         sourceRule.conflictRecovery
       }\n  push selection        ${sourceRule.pushSelection}\n\nSystem page projections:\n${
         page.workspace.systemPages.map((systemPage) =>

package/src/session.js

@@ -3,12 +3,17 @@ import {
   CLI_NAME,
   CLI_VERSION,
   DEFAULT_API_BASE_URL,
+  EXTERNAL_WRITES_SETTING_KEY,
+  EXTERNAL_WRITES_SETTING_LOCATION,
   PUBLISH_KEY_ENVIRONMENT_VARIABLE,
+  REFUSAL_PLATFORM_PAUSED,
   RESULT_SCHEMA_VERSION,
+  ROLLOUT_REFUSAL_FIELD,
   VERB_LOGIN,
   VERB_USE,
 } from "./constants.js";
 import { loadSiteConfig } from "./config.js";
+import { cliOutdatedError, compareCliVersions, isBehindLatest } from "./cli-release.js";
 import {
   credentialApiOrigin,
   readCredentialStore,
@@ -16,7 +21,7 @@ import {
   updateCredentialMetadata,
 } from "./credentials.js";
 import { SiteAuthoringError } from "./errors.js";
-import { exchangeSiteAuthoringToken } from "./api.js";
+import { exchangeSiteAuthoringToken, withRefusalGuidance } from "./api.js";
 import { SiteApiClient } from "./transport.js";
 import { readStoredApiBaseUrl } from "./settings.js";
 
@@ -38,6 +43,26 @@ import { readStoredApiBaseUrl } from "./settings.js";
 /** The optional seams a test (or a future caller) may inject. */
 const CLIENT_OPTION_KEYS = ["fetch", "signal", "sleep", "now", "timeoutSignal"];
 
+/**
+ * What a session knows about the platform's authoring rollout switch when
+ * nothing told it (TR00692).
+ *
+ * Three states, not two, and the third is the honest one: `TAPROOT_SITE_KEY`
+ * skips the exchange entirely and no other read on the contract exposes the
+ * switch, so those runs know nothing about it. Collapsing unknown into "paused"
+ * would warn on every write against a healthy platform; collapsing it into
+ * "enabled" would claim a fact nobody supplied.
+ */
+const UNKNOWN_PLATFORM = Object.freeze({ externalWritesEnabled: undefined });
+
+/**
+ * What a session knows about the latest published release when nothing told it
+ * (TR00703) — the same three-state shape, and unknown for the same reasons: a
+ * `TAPROOT_SITE_KEY` run never exchanges, and a Taproot that predates the field
+ * answers with nothing.
+ */
+const UNKNOWN_CLI_RELEASE = Object.freeze({ latestVersion: undefined });
+
 function progressSink(invocation) {
   return typeof invocation.onProgress === "function" ? invocation.onProgress : () => {};
 }
@@ -166,7 +191,19 @@ export async function openSession(invocation = {}) {
     if (!config.siteId) throw siteMissingError();
     const client = invocation.client
       ?? new SiteApiClient(buildClientOptions(invocation, apiBaseUrl, environmentToken));
-    return { config, client, siteId: config.siteId, now, onProgress };
+    // No exchange happens on this path, and nothing else on the contract reads
+    // the platform switch — so its state is genuinely unknown here rather than
+    // assumed. Reporting it as enabled would be a guess, and reporting it as
+    // paused would warn on every write against a healthy platform.
+    return {
+      config,
+      client,
+      siteId: config.siteId,
+      platform: UNKNOWN_PLATFORM,
+      release: UNKNOWN_CLI_RELEASE,
+      now,
+      onProgress,
+    };
   }
 
   let config;
@@ -192,14 +229,33 @@ export async function openSession(invocation = {}) {
   // A caller may supply the site client directly (tests, and the verbs that
   // already hold one); otherwise the sign-in is exchanged for one.
   if (invocation.client) {
-    return { config, client: invocation.client, siteId: config.siteId, now, onProgress };
+    return {
+      config,
+      client: invocation.client,
+      siteId: config.siteId,
+      platform: UNKNOWN_PLATFORM,
+      release: UNKNOWN_CLI_RELEASE,
+      now,
+      onProgress,
+    };
   }
 
   const accountClient = new SiteApiClient(buildClientOptions(invocation, apiBaseUrl, signIn.key));
-  const exchanged = await exchangeSiteAuthoringToken(accountClient, {
-    siteId: config.siteId,
-    capabilities: invocation.capabilities ?? [],
-  });
+  // Announced here, not left to the generic failure line. The exchange is the
+  // first request every site verb makes and it sits outside each verb's own
+  // `withRefusalGuidance`, so a refusal raised by it used to reach the operator
+  // as a field name and nothing else. That matters most for `cli_outdated`,
+  // whose whole remedy is a command the operator has to be handed (TR00703),
+  // but it is true of every classified refusal the exchange can raise.
+  const exchanged = await withRefusalGuidance(
+    onProgress,
+    "sign-in token exchange",
+    async () =>
+      await exchangeSiteAuthoringToken(accountClient, {
+        siteId: config.siteId,
+        capabilities: invocation.capabilities ?? [],
+      }),
+  );
   // Two non-secret facts the store should now carry: the sign-in's slid
   // deadline, and what this exchange actually produced — the latter is the only
   // thing that lets `whoami` answer offline with the real grant rather than the
@@ -224,6 +280,20 @@ export async function openSession(invocation = {}) {
           siteId: exchanged.siteId,
           capabilities: exchanged.capabilities,
           expiresAt: exchanged.expiresAt,
+          // When this exchange happened, so `whoami` can date what it reports
+          // rather than presenting a snapshot as current fact. Recorded for
+          // every exchange, not only the ones that saw a platform state, so the
+          // field has one meaning.
+          at: new Date(now()).toISOString(),
+          ...(exchanged.externalWritesEnabled === undefined
+            ? {}
+            : { externalWritesEnabled: exchanged.externalWritesEnabled }),
+          // The latest published release Taproot named (TR00703). Recorded for
+          // the offline verbs, which have no request to be refused and would
+          // otherwise keep validating against a contract that has moved.
+          ...(exchanged.latestCliVersion === undefined
+            ? {}
+            : { latestCliVersion: exchanged.latestCliVersion }),
         },
       },
     );
@@ -242,11 +312,95 @@ export async function openSession(invocation = {}) {
       expiresAt: exchanged.expiresAt,
       capabilities: exchanged.capabilities,
     },
+    platform: Object.freeze({ externalWritesEnabled: exchanged.externalWritesEnabled }),
+    release: Object.freeze({ latestVersion: exchanged.latestCliVersion }),
     now,
     onProgress,
   };
 }
 
+/**
+ * Refuses an offline verb when the last exchange said a newer CLI exists
+ * (TR00703).
+ *
+ * **Only for the verbs that make no request.** `help`, `validate`, and `whoami`
+ * are the whole set: every other verb reaches the server, and the server's own
+ * refusal is both authoritative and better informed than this recording. Gating
+ * them here would only duplicate an answer — and gating `login`, `logout`, or
+ * `env` would break the commands an operator needs *while* they are outdated.
+ *
+ * **Best effort, and silent on every uncertainty.** Nothing recorded proceeds,
+ * so a clean machine can still validate a fixture. A store this process cannot
+ * read or parse proceeds too: an unreadable file is not evidence that this CLI
+ * is behind, and turning a corrupt store into a refusal to run `help` would
+ * take away the command that explains how to fix it. Only a recorded version
+ * this side can parse and compare stops anything.
+ *
+ * The store holds one record per API origin, and the highest recorded version
+ * across all of them is what counts. npm publishes one package: whichever
+ * Taproot last answered, it was naming the same registry, so the newest answer
+ * is the current fact rather than a per-origin opinion. Taking the maximum also
+ * keeps a stale development Taproot from masking production's answer.
+ */
+export async function assertCliCurrent(environment = process.env) {
+  let store;
+  try {
+    store = await readCredentialStore(environment);
+  } catch {
+    // Deliberately swallowed; see above.
+    return undefined;
+  }
+  let latest;
+  for (const credential of store.credentials) {
+    const recorded = credential.lastExchange?.latestCliVersion;
+    if (recorded === undefined) continue;
+    if (latest === undefined || (compareCliVersions(recorded, latest) ?? 0) > 0) latest = recorded;
+  }
+  if (latest === undefined || !isBehindLatest(latest)) return undefined;
+  throw cliOutdatedError(latest);
+}
+
+/**
+ * The one pre-write warning: the platform has external site authoring paused,
+ * so this verb's write is going to be refused (TR00692).
+ *
+ * **Advisory, never a gate.** The value is a snapshot the token exchange took
+ * before this run did any work, and the authority is still the transactional
+ * freeze inside the write itself — so a paused platform warns and then proceeds
+ * exactly as before, and the refusal that follows keeps its `platform_paused`
+ * classification for automation to branch on. An operator who flipped the
+ * switch back on between the exchange and the write gets their write.
+ *
+ * Silent in the two cases that are not "paused": enabled, and unknown. Unknown
+ * is the `TAPROOT_SITE_KEY` path, which never exchanges and therefore was never
+ * told — see {@link UNKNOWN_PLATFORM}.
+ *
+ * **Contract.** Call it once, immediately after `openSession` and before any
+ * validation, reading, or wire work, passing the whole session object and the
+ * verb's own name (its `VERB_*` constant). It prints at most one progress line
+ * and returns whether it printed one; it never throws, never reads, and never
+ * changes what the verb does next.
+ *
+ * @param {{ platform?: { externalWritesEnabled?: boolean }, onProgress?: (message: string) => void }} session
+ *   The session `openSession` returned.
+ * @param {string} [verb] The verb's display name, for the warning's first clause.
+ * @returns {boolean} Whether a warning was printed.
+ */
+export function warnIfExternalWritesPaused(session, verb = "This write") {
+  // The guard settles both questions: only a session object can carry `false`
+  // here, so nothing below needs to defend against a missing one.
+  if (session?.platform?.externalWritesEnabled !== false) return false;
+  const onProgress = progressSink(session);
+  onProgress(
+    `WARNING: Taproot has external site authoring paused platform-wide, so '${verb}' is expected to be refused `
+      + `at the write (refusal=${REFUSAL_PLATFORM_PAUSED}, field=${ROLLOUT_REFUSAL_FIELD}). The credential and the `
+      + `request are both fine. A Taproot administrator re-enables it with the platform setting `
+      + `'${EXTERNAL_WRITES_SETTING_KEY}' (${EXTERNAL_WRITES_SETTING_LOCATION}). Continuing anyway: this is what `
+      + "Taproot reported when this run's credential was exchanged, and the write itself is the authority.",
+  );
+  return true;
+}
+
 /**
  * The credential-free half of the session seam, for the verbs that manage the
  * credential rather than use it.

package/src/transport.js

@@ -2,6 +2,7 @@ import {
   CAPABILITY_REFUSAL_FIELD,
   CAPABILITY_REFUSAL_REASON,
   CLI_NAME,
+  CLI_UPGRADE_REFUSAL_FIELD,
   CLI_VERSION,
   CREDENTIAL_REFUSAL_FIELD,
   GRPC_RESOURCE_EXHAUSTED,
@@ -12,6 +13,7 @@ import {
   PLAN_LIMIT_REFUSAL_FIELD,
   PUBLISH_KEY_ENVIRONMENT_VARIABLE,
   REFUSAL_CAPABILITY_MISSING,
+  REFUSAL_CLI_OUTDATED,
   REFUSAL_CREDENTIAL_REJECTED,
   REFUSAL_PLAN_LIMIT,
   REFUSAL_PLATFORM_PAUSED,
@@ -443,10 +445,17 @@ export class ApiError extends SiteAuthoringError {
 
   /**
    * Classifies a refusal into the one thing the caller should do next. The
-   * five kinds are genuinely different behaviors, and collapsing them into
+   * six kinds are genuinely different behaviors, and collapsing them into
    * "the request failed" is what makes an agent retry a revoked credential
    * forever or treat a plan ceiling as a transient outage:
    *
+   * - `cli_outdated` (field `CliUpgradeRequired`) — this CLI is behind the
+   *   latest published release, and Taproot supports only the latest. **Upgrade
+   *   this package**; nothing about the credential, the request, or the site is
+   *   wrong, and no retry of this version can succeed. Classified first,
+   *   because it is the one refusal that says the client itself is the problem:
+   *   every other kind describes a state the current binary could act on
+   *   (TR00703).
    * - `platform_paused` (field `SiteAuthoringRollout`) — external authoring is
    *   switched off platform-wide. **Retry later** or ask the operator; the
    *   credential and the request are both fine.
@@ -484,6 +493,7 @@ export class ApiError extends SiteAuthoringError {
   refusalKind() {
     // Fields first: they are the specific statement, and a named refusal
     // outranks whatever status happens to carry it.
+    if (this.hasField(CLI_UPGRADE_REFUSAL_FIELD)) return REFUSAL_CLI_OUTDATED;
     if (this.hasField(ROLLOUT_REFUSAL_FIELD)) return REFUSAL_PLATFORM_PAUSED;
     if (this.hasField(CREDENTIAL_REFUSAL_FIELD)) return REFUSAL_CREDENTIAL_REJECTED;
     if (this.hasField(PLAN_LIMIT_REFUSAL_FIELD)) return REFUSAL_PLAN_LIMIT;
@@ -500,8 +510,8 @@ export class ApiError extends SiteAuthoringError {
   }
 }
 
-async function parseJsonResponse(response, signal) {
-  const bytes = await readBoundedBody(response, signal);
+async function parseJsonResponse(response, signal, maximumBytes = LIMITS.apiResponseBytes) {
+  const bytes = await readBoundedBody(response, signal, maximumBytes);
   try {
     return JSON.parse(bytes.toString("utf8"));
   } catch {
@@ -610,6 +620,11 @@ export class SiteApiClient {
     attempts = LIMITS.requestAttempts,
     deadline,
     now = this.now,
+    // How large a body this one call may read. The default bounds every read
+    // the way it always has; a caller raises it only for the one contract
+    // whose valid answer is larger, and never above what its workspace file
+    // may hold.
+    maximumResponseBytes = LIMITS.apiResponseBytes,
   } = {}, replaceableMutation) {
     const url = new URL(path, this.apiBaseUrl);
     if (
@@ -618,6 +633,9 @@ export class SiteApiClient {
       || !ALLOWED_METHODS.has(method)
       || (deadline !== undefined && !Number.isFinite(deadline))
       || typeof now !== "function"
+      || !Number.isSafeInteger(maximumResponseBytes)
+      || maximumResponseBytes <= 0
+      || maximumResponseBytes > LIMITS.redirectMapResponseBytes
     ) {
       throw new SiteAuthoringError(
         "transport.request_contract",
@@ -695,7 +713,7 @@ export class SiteApiClient {
       }
       if (response.status >= 200 && response.status < 300 && !response.redirected) {
         try {
-          const parsed = await parseJsonResponse(response, attemptSignal);
+          const parsed = await parseJsonResponse(response, attemptSignal, maximumResponseBytes);
           if (remainingBudget(deadline, now) <= 0) throw deadlineError();
           return parsed;
         } catch (error) {
@@ -729,7 +747,7 @@ export class SiteApiClient {
       }
       let responseBody;
       try {
-        responseBody = await parseJsonResponse(response, attemptSignal);
+        responseBody = await parseJsonResponse(response, attemptSignal, maximumResponseBytes);
       } catch {
         // A response arrived, so the mutation's fate is whatever its status
         // says: a 4xx refused it, a 5xx may have committed it first.

package/src/verbs/approve.js

@@ -7,7 +7,7 @@ import {
 } from "../api.js";
 import { VERB_APPROVE } from "../constants.js";
 import { SiteAuthoringError } from "../errors.js";
-import { boundedList, openSession, successResult } from "../session.js";
+import { boundedList, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
 import {
   normalizePagePath,
   readManifest,
@@ -36,7 +36,12 @@ const MAXIMUM_REPORTED = 200;
 const MAXIMUM_BATCH = 100;
 
 export async function approve(invocation) {
-  const { client, config, siteId, onProgress } = await openSession(invocation);
+  const session = await openSession(invocation);
+  const { client, config, siteId, onProgress } = session;
+  // One advisory line before this verb does any work, and only when the
+  // exchange said the platform is paused. It changes nothing else: the write
+  // still runs and its refusal still classifies as platform_paused (TR00692).
+  warnIfExternalWritesPaused(session, VERB_APPROVE);
   const manifest = await readManifest(config.workspaceDir, siteId);
   const manifestByPageId = new Map(
     manifest.pages.filter((entry) => typeof entry?.pageId === "string").map((entry) => [entry.pageId, entry]),

package/src/verbs/deploy.js

@@ -17,10 +17,30 @@ import {
   VERB_DEPLOY,
 } from "../constants.js";
 import { SiteAuthoringError } from "../errors.js";
-import { boundedList, openSession, successResult } from "../session.js";
+import { boundedList, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
 import { CANDIDATE_SELECTABLE_SETTINGS_TYPES } from "../settings-catalog.js";
 import { readManifest, writeManifest } from "../workspace.js";
 
+/**
+ * What a deploy does not finish (TR00702).
+ *
+ * A deploy writes the site's redirect and gone entries into the edge's
+ * key-value store as part of syncing routing. That store is eventually
+ * consistent, so a spot-check run the second a deploy reports success can
+ * briefly read the previous map, and taking that for "the redirect did not
+ * land" is the wrong conclusion to reach in front of a customer waiting to cut
+ * DNS over.
+ *
+ * No number is quoted, because there is none to quote: the coordinator holds
+ * nothing back for a standard site's redirects. Its propagation grace governs
+ * only the *deletion* of a superseded Docs pointer namespace; a standard site's
+ * rows are written and removed immediately.
+ */
+const REDIRECT_PROPAGATION_NOTE =
+  "Redirect and gone entries are written to the edge's key-value store when this deploy syncs routing. That "
+  + "store is eventually consistent, so a spot-check run immediately afterwards can briefly still see the "
+  + "previous map; re-check before concluding an entry is missing.";
+
 /**
  * `deploy --staging` / `deploy --production` — readiness, deploy, poll to
  * completion.
@@ -202,7 +222,12 @@ export async function deploy(invocation) {
       "deployTarget",
     );
   }
-  const { client, config, siteId, now, onProgress } = await openSession(invocation);
+  const session = await openSession(invocation);
+  const { client, config, siteId, now, onProgress } = session;
+  // One advisory line before this verb does any work, and only when the
+  // exchange said the platform is paused. It changes nothing else: the write
+  // still runs and its refusal still classifies as platform_paused (TR00692).
+  warnIfExternalWritesPaused(session, VERB_DEPLOY);
   const manifest = await readManifest(config.workspaceDir, siteId, { required: false });
   const selection = explicitSelection(invocation);
 
@@ -233,6 +258,7 @@ export async function deploy(invocation) {
         now,
       });
       await recordDeployment(config, manifest, "production", completed);
+      onProgress(REDIRECT_PROPAGATION_NOTE);
       return successResult(VERB_DEPLOY, siteId, {
         target,
         environment: DEPLOYMENT_ENVIRONMENT_PRODUCTION,
@@ -310,6 +336,7 @@ export async function deploy(invocation) {
     });
     await recordDeployment(config, manifest, "staging", completed);
     const stagingPreview = await inspectStagingPreview(client, siteId, onProgress);
+    onProgress(REDIRECT_PROPAGATION_NOTE);
     return successResult(VERB_DEPLOY, siteId, {
       target,
       environment: DEPLOYMENT_ENVIRONMENT_STAGING,

package/src/verbs/footer-push.js

@@ -4,7 +4,7 @@ import { SiteAuthoringError } from "../errors.js";
 import { projectFooterSettingsForWorkspace, validateFooterDocument } from "../footer-contract.js";
 import { computeFooterDraftHash } from "../footer-draft-hash.js";
 import { advanceFooterManifest, FOOTER_SETTINGS_FILE, readFooterWorkspaceContext } from "../footer-workspace.js";
-import { openSession, successResult } from "../session.js";
+import { openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
 import { SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES } from "../settings-catalog.js";
 import { ApiError } from "../transport.js";
 import { readWorkspaceJson, WORKSPACE_LIMITS, writeWorkspaceJson } from "../workspace.js";
@@ -56,7 +56,12 @@ function translateConcurrency(error) {
 }
 
 export async function footerPush(invocation) {
-  const { client, config, siteId, onProgress } = await openSession(invocation);
+  const session = await openSession(invocation);
+  const { client, config, siteId, onProgress } = session;
+  // One advisory line before this verb does any work, and only when the
+  // exchange said the platform is paused. It changes nothing else: the write
+  // still runs and its refusal still classifies as platform_paused (TR00692).
+  warnIfExternalWritesPaused(session, VERB_FOOTER_PUSH);
   const context = await readFooterWorkspaceContext(config.workspaceDir, siteId);
   const { document: document_, footerSettings } = validateFooterWorkspaceDocument(
     await readWorkspaceJson(config.workspaceDir, FOOTER_SETTINGS_FILE, WORKSPACE_LIMITS.settingsBytes),

package/src/verbs/index.js

@@ -8,9 +8,11 @@ import {
   VERB_MEDIA_UPLOAD,
   VERB_NAV_PUSH,
   VERB_PAGES_PUSH,
-  VERB_PULL,
   VERB_PREVIEW_PAGE,
   VERB_PREVIEW_REVOKE,
+  VERB_PULL,
+  VERB_REDIRECTS_PULL,
+  VERB_REDIRECTS_PUSH,
   VERB_SITES,
   VERB_STATUS,
   VERB_THEME_PUSH,
@@ -30,6 +32,8 @@ import { pagesPush } from "./pages-push.js";
 import { pull } from "./pull.js";
 import { previewPage } from "./preview-page.js";
 import { previewRevoke } from "./preview-revoke.js";
+import { redirectsPull } from "./redirects-pull.js";
+import { redirectsPush } from "./redirects-push.js";
 import { sites } from "./sites.js";
 import { status } from "./status.js";
 import { themePush } from "./theme-push.js";
@@ -110,6 +114,8 @@ export const VERB_HANDLERS = Object.freeze({
   [VERB_PULL]: pull,
   [VERB_PAGES_PUSH]: pagesPush,
   [VERB_NAV_PUSH]: navPush,
+  [VERB_REDIRECTS_PULL]: redirectsPull,
+  [VERB_REDIRECTS_PUSH]: redirectsPush,
   [VERB_THEME_PUSH]: themePush,
   [VERB_FOOTER_PUSH]: footerPush,
   [VERB_MEDIA_UPLOAD]: mediaUpload,