@taprootio/site-authoring 0.2.0 → 0.4.0

package/src/transport.js

@@ -1,5 +1,8 @@
 import {
+  CAPABILITY_REFUSAL_FIELD,
+  CAPABILITY_REFUSAL_REASON,
   CLI_NAME,
+  CLI_UPGRADE_REFUSAL_FIELD,
   CLI_VERSION,
   CREDENTIAL_REFUSAL_FIELD,
   GRPC_RESOURCE_EXHAUSTED,
@@ -9,6 +12,8 @@ import {
   LIMITS,
   PLAN_LIMIT_REFUSAL_FIELD,
   PUBLISH_KEY_ENVIRONMENT_VARIABLE,
+  REFUSAL_CAPABILITY_MISSING,
+  REFUSAL_CLI_OUTDATED,
   REFUSAL_CREDENTIAL_REJECTED,
   REFUSAL_PLAN_LIMIT,
   REFUSAL_PLATFORM_PAUSED,
@@ -330,21 +335,95 @@ function fieldDescriptions(value) {
   return descriptions;
 }
 
+/**
+ * A delegation capability or permission key as the server spells it. Anything
+ * outside this shape is dropped rather than repaired: these values reach a
+ * terminal and a machine-readable result, and a name the CLI cannot vouch for
+ * is worse than a name it does not print.
+ */
+const CAPABILITY_NAME = /^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+$/u;
+const MAXIMUM_CAPABILITY_NAMES = 16;
+
+function capabilityNames(value) {
+  if (typeof value !== "string" || value === "") return [];
+  return value
+    .split(",")
+    .map((name) => name.trim())
+    .filter((name) => name.length <= 200 && CAPABILITY_NAME.test(name))
+    .slice(0, MAXIMUM_CAPABILITY_NAMES);
+}
+
+/**
+ * The key-mode capability denial the authoring API attaches as a
+ * `google.rpc.ErrorInfo` detail (TR00691), or undefined.
+ *
+ * The same bounded breadth-first walk the field extractors use, for the same
+ * reason: transcoded `details[]` entries are `Any`-packed, and pinning one path
+ * through them is how a contract change silently empties an extractor. The
+ * `reason` is the contract — a stable, namespaced classifier — so the walk
+ * keys on it rather than on `@type`, which a future packing could reshape.
+ */
+export function capabilityRefusal(value) {
+  const queue = [{ value, depth: 0 }];
+  let work = 0;
+  while (queue.length > 0 && work < 1_000) {
+    const current = queue.shift();
+    work += 1;
+    if (!current || current.depth > 8 || current.value === null || typeof current.value !== "object") continue;
+    const metadata = current.value.metadata;
+    if (
+      current.value.reason === CAPABILITY_REFUSAL_REASON
+      && metadata !== null
+      && typeof metadata === "object"
+      && !Array.isArray(metadata)
+    ) {
+      const permission = capabilityNames(metadata.permission)[0];
+      // A detail naming no permission is not this refusal, whatever it says:
+      // the guidance is built entirely out of these three values, and half of
+      // one would be a message nobody could act on.
+      if (permission !== undefined) {
+        return Object.freeze({
+          permission,
+          granted: Object.freeze(capabilityNames(metadata.granted)),
+          required: Object.freeze(capabilityNames(metadata.required)),
+        });
+      }
+    }
+    for (const child of Object.values(current.value)) {
+      if (child !== null && typeof child === "object") queue.push({ value: child, depth: current.depth + 1 });
+    }
+  }
+  return undefined;
+}
+
 export class ApiError extends SiteAuthoringError {
   constructor(httpStatus, body) {
     const grpcCode = Number.isSafeInteger(body?.code) ? body.code : undefined;
     const fields = fieldViolations(body);
+    const capability = capabilityRefusal(body);
     super(
       "api.request_rejected",
       fields.length > 0
         ? `Taproot rejected the request field '${fields[0]}'.`
+        : capability !== undefined
+        ? `Taproot refused the request: this credential does not carry a capability granting '${
+          capability.permission
+        }'.`
         : `Taproot rejected the request with HTTP ${httpStatus}.`,
-      { field: fields[0], status: grpcCode === undefined ? `http:${httpStatus}` : `grpc:${grpcCode}` },
+      {
+        // `fields` stays exactly what the wire named. The capability field is
+        // the CLI's own label for a refusal that carries no field violation at
+        // all, so it lands on the error without joining the wire-derived set
+        // that `hasField()` classifies on.
+        field: fields[0] ?? (capability === undefined ? undefined : CAPABILITY_REFUSAL_FIELD),
+        status: grpcCode === undefined ? `http:${httpStatus}` : `grpc:${grpcCode}`,
+      },
     );
     this.httpStatus = httpStatus;
     this.grpcCode = grpcCode;
     this.fields = fields;
     this.violationDescriptions = fieldDescriptions(body);
+    this.capability = capability;
   }
 
   hasField(field) {
@@ -366,10 +445,17 @@ export class ApiError extends SiteAuthoringError {
 
   /**
    * Classifies a refusal into the one thing the caller should do next. The
-   * four 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.
@@ -393,6 +479,13 @@ export class ApiError extends SiteAuthoringError {
    *   never invents the numeric limit.
    * - `throttled` (gRPC `ResourceExhausted` / HTTP 429) — the per-key
    *   throttle. **Back off** and retry with delay.
+   * - `capability_missing` (`ErrorInfo` reason `SITE_AUTHORING_CAPABILITY_MISSING`)
+   *   — the credential is valid and correctly scoped, and simply was not
+   *   exchanged for a capability this request needs. **Fix the verb table**,
+   *   not the credential: the exchange minted exactly what the verb asked for,
+   *   so a verb whose declared set is short of the requests it makes is the
+   *   defect. Distinguished from `credential_rejected` precisely because
+   *   re-issuing the same credential cannot help (TR00691).
    *
    * Anything else is `unclassified`, which is a signal to surface the raw
    * status rather than to guess.
@@ -400,9 +493,13 @@ 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;
+    // The named detail ranks with the fields and above the status mappings, for
+    // the same reason: it is the specific statement about this refusal.
+    if (this.capability !== undefined) return REFUSAL_CAPABILITY_MISSING;
     if (this.grpcCode === GRPC_RESOURCE_EXHAUSTED || this.httpStatus === HTTP_TOO_MANY_REQUESTS) {
       return REFUSAL_THROTTLED;
     }
@@ -413,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 {
@@ -523,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 (
@@ -531,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",
@@ -608,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) {
@@ -642,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,

package/src/verbs/login.js

@@ -9,6 +9,7 @@ import {
   CLI_AUTHORIZATION_CLAIM_STATUS_PENDING,
   poll,
   startCliAuthorization,
+  announceRefusal,
 } from "../api.js";
 import {
   AUTHORIZE_CLI_PATH,
@@ -328,7 +329,16 @@ export async function login(invocation) {
   try {
     authorization = await startCliAuthorization(client, { keyName });
   } catch (error) {
-    throw translateStartApiError(error);
+    // Announced only when the refusal survives translation: sign-in is the
+    // earlier of the two calls that carry this CLI's version, so it is where
+    // an outdated CLI is told to upgrade, and the remedy is a command the
+    // operator has to be handed rather than a field name (TR00703). A throttle
+    // is translated instead, because the shared guidance names a credential
+    // that does not exist yet, and announcing it first would contradict the
+    // translated line that follows.
+    const translated = translateStartApiError(error);
+    if (translated === error) announceRefusal(error, onProgress, "sign-in");
+    throw translated;
   }
 
   const verificationUrl = verificationUrlFor(apiBaseUrl);

package/src/verbs/media-upload.js

@@ -12,7 +12,7 @@ import {
 import { LIMITS, VERB_MEDIA_UPLOAD } from "../constants.js";
 import { SiteAuthoringError } from "../errors.js";
 import { contentHash, inspectImageBytes } from "../image-metadata.js";
-import { boundedList, openSession, successResult } from "../session.js";
+import { boundedList, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
 import {
   ensureWorkspaceRoot,
   inspectWorkspaceEntry,
@@ -164,7 +164,12 @@ async function waitForProcessing(client, siteId, imageIds, { onProgress, now })
 }
 
 export async function mediaUpload(invocation) {
-  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_MEDIA_UPLOAD);
   await ensureWorkspaceRoot(config);
 
   // Positional arguments name the files or directories to upload — `cli.js`

package/src/verbs/nav-push.js

@@ -9,8 +9,13 @@ import {
   withRefusalGuidance,
 } from "../api.js";
 import { VERB_NAV_PUSH } from "../constants.js";
+import {
+  CONTACT_OR_WEB_URL_MAX_LENGTH,
+  CONTACT_OR_WEB_URL_REQUIREMENT,
+  isContactOrWebUrl,
+} from "../contact-url.js";
 import { SiteAuthoringError } from "../errors.js";
-import { boundedList, openSession, successResult } from "../session.js";
+import { boundedList, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
 import {
   NAVIGATION_FILE_NAME,
   readWorkspaceJson,
@@ -44,7 +49,7 @@ import {
 const MAXIMUM_REPORTED = 100;
 const MAXIMUM_ITEMS = 1_000;
 const MAXIMUM_TITLE_LENGTH = 200;
-const MAXIMUM_URL_LENGTH = 2_048;
+const MAXIMUM_URL_LENGTH = CONTACT_OR_WEB_URL_MAX_LENGTH;
 const ITEM_KEYS = new Set(["id", "kind", "title", "resourceId", "externalUrl", "children"]);
 
 // `SaveSiteNavigation` maps both `id` and `resourceId` through
@@ -141,14 +146,10 @@ function validateItem(item, itemPath, depth, seenIds, counters) {
     if (!isBoundedText(item.externalUrl, MAXIMUM_URL_LENGTH)) {
       throw navError("nav.external_url_missing", "an EXTERNAL_URL item needs a non-empty 'externalUrl'.", itemPath);
     }
-    let url;
-    try {
-      url = new URL(item.externalUrl);
-    } catch {
-      url = undefined;
-    }
-    if (url === undefined || (url.protocol !== "https:" && url.protocol !== "http:")) {
-      throw navError("nav.external_url_invalid", "'externalUrl' must be an absolute http or https URL.", itemPath);
+    // A header item may be a phone number or an email address, not just a web
+    // page; the value is stored verbatim so the number stays dialable.
+    if (!isContactOrWebUrl(item.externalUrl, MAXIMUM_URL_LENGTH)) {
+      throw navError("nav.external_url_invalid", `'externalUrl' ${CONTACT_OR_WEB_URL_REQUIREMENT}.`, itemPath);
     }
     if (!isEmpty(item.resourceId)) {
       throw navError("nav.resource_unexpected", "an EXTERNAL_URL item must not carry 'resourceId'.", itemPath);
@@ -275,7 +276,12 @@ export function validateNavigationWorkspaceDocument(parsed, siteId, knownPages)
 }
 
 export async function navPush(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_NAV_PUSH);
   if (!await workspaceFileExists(config.workspaceDir, NAVIGATION_FILE_NAME)) {
     throw new SiteAuthoringError(
       "nav.file_missing",

package/src/verbs/pages-push.js

@@ -9,7 +9,7 @@ import {
 } from "../api.js";
 import { VERB_PAGES_PUSH } from "../constants.js";
 import { SiteAuthoringError } from "../errors.js";
-import { boundedList, openSession, successResult } from "../session.js";
+import { boundedList, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
 import { SETTINGS_TYPE_TAPROOT_STYLES } from "../settings-catalog.js";
 import {
   hasNamedFreeFormSectionContext,
@@ -18,7 +18,10 @@ import {
 } from "../content/free-form-sections.js";
 import { CONTENT_ERROR_CODES } from "../content/vocabulary.js";
 import {
+  deleteWorkspaceFile,
+  internalPageObservedRevisionFile,
   MEDIA_MANIFEST_FILE_NAME,
+  normalizePageBodyRevision,
   normalizePagePath,
   PAGE_SOURCE_EXTENSIONS,
   PAGE_SOURCE_FORMAT_MARKDOWN,
@@ -28,6 +31,7 @@ import {
   PAGES_DIRECTORY,
   readManifest,
   readMediaManifest,
+  readObservedPageRevision,
   readOnlySystem404Projections,
   readWorkspaceFile,
   readWorkspaceJson,
@@ -38,6 +42,7 @@ import {
   walkWorkspaceFiles,
   WORKSPACE_LIMITS,
   workspaceContentHash,
+  workspaceFileExists,
   writeManifest,
 } from "../workspace.js";
 
@@ -457,6 +462,45 @@ export async function readWorkspacePageSource({ workspaceDir, file, manifestEntr
   };
 }
 
+/**
+ * Refuses to overwrite a live page that moved since this workspace last
+ * reconciled with it.
+ *
+ * TR00622 left one detection gap open deliberately: a remote edit made between
+ * this workspace's own push and its next pull was adopted as the new baseline
+ * rather than reported, because the bytes a push sends are not comparable with
+ * the bytes a read returns and closing it needed a revision on the read
+ * contract. This is that revision, so the gap closes here: the site states the
+ * revision of each page's stored authoring state, the workspace records the one
+ * it last wrote or pulled, and a push into a page carrying a different one is
+ * refused before a single mutation is sent.
+ *
+ * The guard is armed by knowledge, not by policy. A page the workspace has
+ * never reconciled with records no revision, and a Taproot that predates the
+ * contract reports none; neither is evidence of a concurrent edit, and refusing
+ * on absence would make the ordinary first push of a workspace impossible.
+ * Both leave this exactly where TR00622 left it, which is where the caller
+ * already is.
+ */
+function requireReconciledRevision({ file, pagePath, target, entry, observedRevision }) {
+  // What the operator was shown by a refused pull outranks what the manifest
+  // last reconciled with. Without that, this guard would also refuse the pull
+  // conflict's own documented recovery, and the only way out of a conflict
+  // would be to abandon the local source.
+  const recorded = observedRevision ?? normalizePageBodyRevision(entry?.baseline?.revision);
+  const live = target.bodyRevision;
+  if (recorded === undefined || live === undefined || recorded === live) return;
+  const selector = pagePath || "/";
+  throw new SiteAuthoringError(
+    "pages.push_conflict",
+    `Page '${selector}' changed on the site since this workspace last reconciled with it: it now reports revision `
+      + `${live}, and '${file}' was written against ${recorded}. No page was pushed. Run `
+      + `'taproot-site pull' to see what differs and to adopt the site's version, or delete '${file}' and pull `
+      + "again to take the site's document as this page's source.",
+    { field: file, alternatives: [recorded, live] },
+  );
+}
+
 /**
  * The metadata checks that are *not* part of deciding which page a source is.
  *
@@ -557,7 +601,12 @@ export async function validateWorkspacePageDocument({
 }
 
 export async function pagesPush(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_PAGES_PUSH);
   const allowRawHtml = invocation.allowRawHtml === true;
   // Both manifests are bound to the site before anything is planned or sent:
   // every id in them is site-scoped, and a workspace pulled from another site
@@ -837,6 +886,18 @@ export async function pagesPush(invocation) {
             file,
           );
         }
+        // The record this push may spend has to be removable after the send:
+        // a directory or a symlink at its path is refused here, before any
+        // page is written, rather than discovered after the site has changed.
+        const observedRecordFile = internalPageObservedRevisionFile(target.pageId);
+        if (observedRecordFile !== undefined) await workspaceFileExists(config.workspaceDir, observedRecordFile);
+        requireReconciledRevision({
+          file,
+          pagePath,
+          target,
+          entry: manifestByPageId.get(target.pageId),
+          observedRevision: await readObservedPageRevision(config.workspaceDir, target.pageId),
+        });
       }
 
       // The duplicate-source check above only catches two workspace files
@@ -942,15 +1003,39 @@ export async function pagesPush(invocation) {
           file: page.file,
           sourceFormat: page.sourceFormat,
           // The page's remote body is now derived from exactly these bytes.
-          // Only the local half of the baseline is recorded: a read re-projects
-          // image delivery and re-serializes component data, so a hash of what
-          // was sent is not comparable with a hash of what a pull would read.
-          // The next pull establishes the remote half from what it actually
-          // reads, which is the only comparison that holds.
-          baseline: { sourceHash: page.sourceHash },
+          // No remote *hash* is recorded: a read re-projects image delivery and
+          // re-serializes component data, so a hash of what was sent is not
+          // comparable with a hash of what a pull would read, and the next pull
+          // establishes that half from what it actually reads.
+          //
+          // The revision is different in kind and is recorded here. It is the
+          // site's own statement about the stored state this mutation just
+          // wrote, so it is directly comparable with the revision the next read
+          // reports — which is what lets the *next* push tell "nobody else
+          // touched this page" from "someone did", without a pull in between.
+          // Absent against a Taproot that predates the contract, and then
+          // dropped rather than carried forward: this push moved the stored
+          // state, so whatever was recorded describes a version that no longer
+          // exists, and keeping it would refuse the *next* push over a change
+          // this workspace made itself.
+          baseline: {
+            sourceHash: page.sourceHash,
+            ...(summary.bodyRevision === undefined ? {} : { revision: summary.bodyRevision }),
+          },
           pendingApproval: true,
         });
         if (existing === undefined) manifest.pages.push(record);
+        // The override this page's record permitted has now been taken, and
+        // the baseline above records what the site holds because of it.
+        // Keeping the record would let a *later* push overwrite somebody
+        // else's edit without anyone having been shown it. Removed after the
+        // manifest record is written, so a failure here can never leave a
+        // successful mutation unrecorded; the record's shape was checked
+        // before anything was sent.
+        const observedRevisionFile = internalPageObservedRevisionFile(summary.pageId);
+        if (observedRevisionFile !== undefined) {
+          await deleteWorkspaceFile(config.workspaceDir, observedRevisionFile);
+        }
       }
     } finally {
       if (manifestDirty) await writeManifest(config.workspaceDir, manifest);

package/src/verbs/preview-page.js

@@ -7,7 +7,7 @@ import {
 } from "../api.js";
 import { VERB_PREVIEW_PAGE } from "../constants.js";
 import { asSiteAuthoringError, isCanonicalUuid, SiteAuthoringError } from "../errors.js";
-import { openSession, successResult } from "../session.js";
+import { openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
 import { normalizePagePath, readManifest } from "../workspace.js";
 
 /**
@@ -40,7 +40,12 @@ export async function previewPage(invocation) {
       { field: "pageSelector", exitCode: 2 },
     );
   }
-  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_PREVIEW_PAGE);
   let pageId = selector;
   if (!isCanonicalUuid(selector)) {
     const pagePath = normalizePagePath(selector);

package/src/verbs/preview-revoke.js

@@ -6,7 +6,7 @@ import {
 } from "../api.js";
 import { VERB_PREVIEW_REVOKE } from "../constants.js";
 import { isCanonicalUuid, SiteAuthoringError } from "../errors.js";
-import { openSession, successResult } from "../session.js";
+import { openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
 
 export async function previewRevoke(invocation) {
   if (!Array.isArray(invocation.previewIds) || invocation.previewIds.length !== 2) {
@@ -31,7 +31,12 @@ export async function previewRevoke(invocation) {
     );
   }
   const [pageId, snapshotId] = invocation.previewIds;
-  const { client, siteId, onProgress } = await openSession(invocation);
+  const session = await openSession(invocation);
+  const { client, 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_PREVIEW_REVOKE);
   try {
     return await withRefusalGuidance(onProgress, "authoring preview revocation", async () => {
       onProgress("Revoking the authoring preview and scheduling its artifacts for cleanup.");