@taprootio/site-authoring 0.3.0 → 0.4.0

package/src/verbs/redirects-push.js

@@ -0,0 +1,100 @@
+import { replaceSiteRedirectMap, withRefusalGuidance } from "../api.js";
+import { VERB_REDIRECTS_PUSH } from "../constants.js";
+import { SiteAuthoringError } from "../errors.js";
+import {
+  projectRedirectMapForWorkspace,
+  REDIRECT_KIND_GONE,
+  REDIRECTS_FILE_NAME,
+  validateRedirectsDocument,
+} from "../redirects-contract.js";
+import { advanceRedirectsManifest, readRedirectsWorkspaceContext } from "../redirects-workspace.js";
+import { boundedList, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
+import { ApiError } from "../transport.js";
+import { readWorkspaceJson, WORKSPACE_LIMITS, writeWorkspaceJson } from "../workspace.js";
+
+const MAXIMUM_REPORTED = 200;
+
+/**
+ * `redirects push` — replace the whole map from the workspace file.
+ *
+ * The revision travels with the write. A push whose baseline predates a page
+ * rename is refused as a conflict rather than committing a map that silently
+ * drops the rename's entry, and the guidance says to re-pull and reconcile
+ * rather than to retry.
+ */
+function translateConflict(error) {
+  if (error instanceof ApiError && error.hasField("ExpectedRevision")) {
+    return new SiteAuthoringError(
+      "redirects.concurrent_modification",
+      "The redirect map changed after this workspace read it — most often a page or tag rename recorded its own "
+        + `entry. Run 'taproot-site redirects pull', reconcile ${REDIRECTS_FILE_NAME}, and retry. Nothing was `
+        + "written.",
+      { field: "revision", status: error.status },
+    );
+  }
+  return error;
+}
+
+export async function redirectsPush(invocation) {
+  const session = await openSession(invocation);
+  const { client, config, siteId, onProgress } = session;
+  warnIfExternalWritesPaused(session, VERB_REDIRECTS_PUSH);
+  const context = await readRedirectsWorkspaceContext(config.workspaceDir, siteId);
+  const validated = validateRedirectsDocument(
+    await readWorkspaceJson(config.workspaceDir, REDIRECTS_FILE_NAME, WORKSPACE_LIMITS.redirectsBytes),
+    siteId,
+    // The entry cap is scoped against the map this workspace pulled, the way
+    // the site scopes it against the rows it holds: a site whose accumulated
+    // path history is already over the cap can push its own map back, or a
+    // smaller one, without deleting a live redirect to satisfy a number.
+    { baselineEntries: context.redirects.entries },
+  );
+  onProgress(
+    `Validated ${validated.entries.length} redirect entr${validated.entries.length === 1 ? "y" : "ies"}: `
+      + "path normalization, targets, statuses, duplicates, chains, and loops.",
+  );
+
+  // The manifest baseline wins over the file's own `revision` field. The file
+  // is authored by hand and its revision is a record of a read, not a claim a
+  // caller gets to make; taking it from the manifest keeps a hand-edited value
+  // from widening what a push may overwrite.
+  const expectedRevision = context.redirects.revision;
+
+  let map;
+  try {
+    map = await withRefusalGuidance(
+      onProgress,
+      "redirects push",
+      async () => await replaceSiteRedirectMap(client, siteId, expectedRevision, validated.entries),
+    );
+  } catch (error) {
+    throw translateConflict(error);
+  }
+
+  const document_ = projectRedirectMapForWorkspace(siteId, map);
+  try {
+    // The document lands before its baseline, exactly as `footer push` orders
+    // its two writes: if the manifest write fails, a stale revision refuses the
+    // next push rather than letting it overwrite the map just saved.
+    await writeWorkspaceJson(config.workspaceDir, REDIRECTS_FILE_NAME, document_);
+    await advanceRedirectsManifest(config.workspaceDir, siteId, map);
+  } catch (error) {
+    if (error instanceof SiteAuthoringError) throw error.withCompletedWrites(["redirects"]);
+    throw error;
+  }
+  onProgress("Replaced the site's redirect map and recorded its new revision.");
+
+  const reported = boundedList(document_.entries, MAXIMUM_REPORTED);
+  return successResult(VERB_REDIRECTS_PUSH, siteId, {
+    redirectsFile: REDIRECTS_FILE_NAME,
+    revision: map.revision,
+    redirects: {
+      total: map.entries.length,
+      gone: map.entries.filter((entry) => entry.kind === REDIRECT_KIND_GONE).length,
+      items: reported.items,
+      ...(reported.truncated ? { itemsTruncated: true } : {}),
+    },
+    written: { items: ["redirects"], count: 1 },
+    nextStep: "deploy --staging",
+  });
+}

package/src/verbs/status.js

@@ -6,11 +6,22 @@ import {
   listSiteImages,
   withRefusalGuidance,
 } from "../api.js";
-import { VERB_STATUS } from "../constants.js";
+import {
+  CLI_UPGRADE_COMMAND,
+  CLI_VERSION,
+  EXTERNAL_WRITES_SETTING_KEY,
+  EXTERNAL_WRITES_SETTING_LOCATION,
+  PUBLISH_KEY_ENVIRONMENT_VARIABLE,
+  REFUSAL_CLI_OUTDATED,
+  REFUSAL_PLATFORM_PAUSED,
+  VERB_STATUS,
+} from "../constants.js";
+import { isBehindLatest } from "../cli-release.js";
 import { boundedList, openSession, successResult } from "../session.js";
 
 /**
- * `status` — deployments, publishing readiness, and image processing.
+ * `status` — the platform authoring switch, the CLI release, deployments,
+ * publishing readiness, and image processing.
  *
  * Broken references are deliberately absent. `GetSiteBrokenReferences` is
  * session-only under TR00602's read list, and TR00604 adds no server surface,
@@ -26,8 +37,82 @@ const MAXIMUM_BLOCKERS = 50;
 const BROKEN_REFERENCES_NOTE =
   "GetSiteBrokenReferences is session-only on the shipped contract, so a key-authorized CLI cannot read it.";
 
+const PLATFORM_UNKNOWN_NOTE =
+  "Taproot never reported the platform authoring switch on this run: either no sign-in token exchange happened "
+  + `(${PUBLISH_KEY_ENVIRONMENT_VARIABLE} supplies the site credential directly and skips it), or the Taproot that `
+  + "answered the exchange predates the field.";
+
+const CLI_RELEASE_UNKNOWN_NOTE =
+  "Taproot never named the latest published CLI release on this run: either no sign-in token exchange happened "
+  + `(${PUBLISH_KEY_ENVIRONMENT_VARIABLE} supplies the site credential directly and skips it), or the Taproot that `
+  + "answered the exchange predates the field.";
+
+/**
+ * Which release this CLI is against the latest Taproot named (TR00703).
+ *
+ * The same three-state shape as the platform switch, and reported the same way:
+ * a known answer carries `latestVersion`, an unknown one carries
+ * `latestKnown: false` and the reason. It is named `cliRelease` rather than
+ * `cli` because every result already carries a top-level `cli` naming this
+ * package and its version, and shadowing that would change what a field means
+ * depending on which verb produced it.
+ *
+ * `behind: true` is not reachable through a live exchange, and deliberately not
+ * removed: the exchange that supplies this value refuses an outdated CLI before
+ * it answers, so a run that gets here was accepted. What the branch protects is
+ * the case where those two facts ever come apart — a server that reports a
+ * latest it does not enforce — where reporting `behind: false` would be a
+ * confident lie rather than a missing field.
+ */
+function reportCliRelease(release, onProgress) {
+  const latestVersion = release?.latestVersion;
+  if (latestVersion === undefined) {
+    onProgress(`CLI release: ${CLI_VERSION}. Latest not known on this run. ${CLI_RELEASE_UNKNOWN_NOTE}`);
+    return { version: CLI_VERSION, latestKnown: false, reason: CLI_RELEASE_UNKNOWN_NOTE };
+  }
+  const behind = isBehindLatest(latestVersion);
+  onProgress(
+    behind
+      ? `CLI release: ${CLI_VERSION} is BEHIND the latest published release ${latestVersion}, and Taproot accepts `
+        + `only the latest, so every online verb is refused (refusal=${REFUSAL_CLI_OUTDATED}). Upgrade with: `
+        + CLI_UPGRADE_COMMAND
+      : `CLI release: ${CLI_VERSION}; latest published release ${latestVersion}.`,
+  );
+  return { version: CLI_VERSION, latestVersion, behind };
+}
+
+/**
+ * The rollout switch as `status` reports it (TR00692), on both channels.
+ *
+ * Three states, and the JSON says which it is by shape rather than by a
+ * three-valued boolean: a known state carries `externalWritesEnabled`, and an
+ * unknown one carries `externalWritesKnown: false` and the reason. An
+ * automation reading `platform.externalWritesEnabled === false` is therefore
+ * never reading an absent field as "paused".
+ */
+function reportPlatform(platform, onProgress) {
+  const enabled = platform?.externalWritesEnabled;
+  if (enabled === undefined) {
+    onProgress(`Platform authoring switch: not known on this run. ${PLATFORM_UNKNOWN_NOTE}`);
+    return { externalWritesKnown: false, reason: PLATFORM_UNKNOWN_NOTE };
+  }
+  onProgress(
+    enabled
+      ? "Platform authoring switch: external site authoring writes are enabled."
+      : "Platform authoring switch: external site authoring writes are PAUSED platform-wide, so every write verb "
+        + `is refused (refusal=${REFUSAL_PLATFORM_PAUSED}). A Taproot administrator re-enables the platform `
+        + `setting '${EXTERNAL_WRITES_SETTING_KEY}' (${EXTERNAL_WRITES_SETTING_LOCATION}).`,
+  );
+  return { externalWritesEnabled: enabled };
+}
+
 export async function status(invocation) {
-  const { client, siteId, onProgress } = await openSession(invocation);
+  const { client, siteId, platform, release, onProgress } = await openSession(invocation);
+  // Said first, and before any wire read: an operator running `status` because
+  // writes are being refused should not have to wait on three network calls to
+  // learn that the platform is paused — and this answer needs none of them.
+  const platformReport = reportPlatform(platform, onProgress);
+  const cliReleaseReport = reportCliRelease(release, onProgress);
 
   return await withRefusalGuidance(onProgress, "status check", async () => {
     onProgress("Reading publishing readiness.");
@@ -60,6 +145,8 @@ export async function status(invocation) {
     onProgress(`Broken references are not reported: ${BROKEN_REFERENCES_NOTE}`);
 
     return successResult(VERB_STATUS, siteId, {
+      platform: platformReport,
+      cliRelease: cliReleaseReport,
       readiness: {
         state: readiness.state,
         approvedPageCount: readiness.approvedPageCount,

package/src/verbs/theme-push.js

@@ -13,7 +13,7 @@ import {
   readAppearanceWorkspaceContext,
   requireFooterContentPushed,
 } from "../footer-workspace.js";
-import { boundedList, openSession, successResult } from "../session.js";
+import { boundedList, openSession, successResult, warnIfExternalWritesPaused } from "../session.js";
 import {
   SETTINGS_TYPE_BRAND,
   SETTINGS_TYPE_SITE_HEADER,
@@ -108,7 +108,12 @@ export async function validateThemeWorkspace(workspaceDir, siteId, knownImageIds
 }
 
 export async function themePush(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_THEME_PUSH);
   const appearanceContext = await readAppearanceWorkspaceContext(config.workspaceDir, siteId);
   const { publishing, themes, scalarOperations, footerColors } = await validateThemeWorkspace(
     config.workspaceDir,

package/src/verbs/validate.js

@@ -14,6 +14,13 @@ import {
   FIXTURE_ROOT_FIELDS,
 } from "../fixture-contract.js";
 import { FOOTER_SETTINGS_FILE } from "../footer-workspace.js";
+import {
+  isRedirectMapRevision,
+  REDIRECT_KIND_GONE,
+  REDIRECTS_FILE_NAME,
+  validateRedirectsDocument,
+  normalizeRedirectPath,
+} from "../redirects-contract.js";
 import { boundedList, successResult } from "../session.js";
 import { SETTINGS_GROUPS, SETTINGS_TYPE_SITE_PUBLISHING_PREFERENCES } from "../settings-catalog.js";
 import { validateFooterWorkspaceDocument } from "./footer-push.js";
@@ -118,6 +125,23 @@ function validateFixtureManifest(manifest) {
       "navigation",
     );
   }
+  // The redirect baseline is bound the way navigation is, with the revision a
+  // push is fenced by. A fixture's revision is a deterministic placeholder like
+  // every other identity in one — it proves the shape, never a live read.
+  if (
+    !isPlainObject(manifest.redirects)
+    || manifest.redirects.file !== REDIRECTS_FILE_NAME
+    || !isRedirectMapRevision(manifest.redirects.revision)
+    || !Number.isSafeInteger(manifest.redirects.entries)
+    || manifest.redirects.entries < 0
+  ) {
+    fail(
+      "fixture.redirects_invalid",
+      `The fixture manifest must bind '${REDIRECTS_FILE_NAME}', a 64-character lowercase hex revision, and its `
+        + "non-negative entry count.",
+      "redirects",
+    );
+  }
   if (!Array.isArray(manifest.settingsSkipped) || manifest.settingsSkipped.length !== 0) {
     fail(
       "fixture.settings_invalid",
@@ -453,6 +477,51 @@ export async function validateFixture(invocation = {}) {
     );
   }
 
+  onProgress("Validating the redirect map: paths, targets, statuses, chains, and loops.");
+  const redirectsDocument = await readWorkspaceJson(
+    fixtureRoot,
+    REDIRECTS_FILE_NAME,
+    WORKSPACE_LIMITS.redirectsBytes,
+  );
+  const redirects = validateRedirectsDocument(redirectsDocument, manifest.siteId);
+  if (redirects.entries.length !== manifest.redirects.entries) {
+    fail(
+      "fixture.redirects_count_mismatch",
+      `${REDIRECTS_FILE_NAME} contains ${redirects.entries.length} entr${
+        redirects.entries.length === 1 ? "y" : "ies"
+      }, but the fixture manifest records ${manifest.redirects.entries}.`,
+      "redirects.entries",
+    );
+  }
+  // A fixture is self-contained, so the occupancy rule the site enforces can be
+  // checked here too: a source the fixture's own pages occupy would be refused
+  // at the API, and saying so offline is the whole point of this verb. Paths
+  // compare case-insensitively, as the site's citext path column does, and a
+  // refusal names the entry where the author wrote it: the validated map is
+  // sorted by path, so its index is not the document's.
+  const fixturePagePaths = new Set(
+    manifest.pages.map((entry) =>
+      (`/${normalizePagePath(entry.path) ?? ""}`.replace(/\/+$/u, "") || "/").toLowerCase()
+    ),
+  );
+  const authoredIndexByPath = new Map();
+  for (const [index, entry] of redirectsDocument.entries.entries()) {
+    const path = normalizeRedirectPath(entry?.path);
+    if (path !== undefined && !authoredIndexByPath.has(path.toLowerCase())) {
+      authoredIndexByPath.set(path.toLowerCase(), index);
+    }
+  }
+  for (const entry of redirects.entries) {
+    const key = entry.path.toLowerCase();
+    if (fixturePagePaths.has(key)) {
+      fail(
+        "fixture.redirect_path_occupied",
+        `Redirect source '${entry.path}' is a page in this fixture, so it cannot also be a redirect source.`,
+        `entries[${authoredIndexByPath.get(key) ?? 0}].path`,
+      );
+    }
+  }
+
   onProgress("Validating the closed footer document and local page/image targets.");
   validateFooterWorkspaceDocument(
     await readWorkspaceJson(fixtureRoot, FOOTER_SETTINGS_FILE, WORKSPACE_LIMITS.settingsBytes),
@@ -483,6 +552,10 @@ export async function validateFixture(invocation = {}) {
         ...(reportedPages.truncated ? { itemsTruncated: true } : {}),
       },
       navigation: { items: navigation.items, maximumDepth: NAVIGATION_MAXIMUM_DEPTH },
+      redirects: {
+        entries: redirects.entries.length,
+        gone: redirects.entries.filter((entry) => entry.kind === REDIRECT_KIND_GONE).length,
+      },
       themes: 2,
       appearanceSettings: presentation.scalarOperations.length,
       footer: true,
@@ -497,6 +570,7 @@ export async function validateFixture(invocation = {}) {
       "fixture structure and bounded files",
       "page content and named theme contexts",
       "navigation shape and local page-resource references",
+      "redirect-map shape, normalization, chains, loops, and fixture-local path occupancy",
       "complete theme, appearance, header, brand, and footer semantics",
       "fixture-local image identities and reserved delivery origins",
     ],

package/src/verbs/whoami.js

@@ -1,9 +1,67 @@
-import { CLI_BINARY_NAME, PUBLISH_KEY_ENVIRONMENT_VARIABLE, VERB_LOGIN, VERB_USE, VERB_WHOAMI } from "../constants.js";
+import {
+  CLI_BINARY_NAME,
+  CLI_UPGRADE_COMMAND,
+  CLI_VERSION,
+  EXTERNAL_WRITES_SETTING_KEY,
+  EXTERNAL_WRITES_SETTING_LOCATION,
+  PUBLISH_KEY_ENVIRONMENT_VARIABLE,
+  VERB_LOGIN,
+  VERB_STATUS,
+  VERB_USE,
+  VERB_WHOAMI,
+} from "../constants.js";
+import { isBehindLatest } from "../cli-release.js";
 import { credentialApiOrigin, findCredential } from "../credentials.js";
 import { SITE_AUTHORING_CAPABILITIES } from "../capabilities.js";
 import { openAnonymousSession, successResult } from "../session.js";
 import { environmentNameFor } from "../settings.js";
 
+/**
+ * What the last exchange recorded about the platform authoring switch, dated
+ * with that exchange (TR00692).
+ *
+ * Never presented as the current state: this verb makes no request, so the
+ * value is as old as the last exchange, and `status` is where a current answer
+ * comes from. A record written before the field existed says so plainly rather
+ * than reading as "enabled".
+ */
+function platformLine(lastExchange) {
+  const when = lastExchange.at === undefined ? "at that exchange" : `as of ${lastExchange.at}`;
+  if (lastExchange.externalWritesEnabled === undefined) {
+    return `Platform authoring switch: not recorded by that exchange. Run '${CLI_BINARY_NAME} ${VERB_STATUS}' `
+      + "for a current answer.";
+  }
+  return lastExchange.externalWritesEnabled
+    ? `Platform authoring switch ${when}: external site authoring writes were enabled. This is a recording, not a `
+      + `live read; run '${CLI_BINARY_NAME} ${VERB_STATUS}' for the current answer.`
+    : `Platform authoring switch ${when}: external site authoring writes were PAUSED platform-wide. A Taproot `
+      + `administrator re-enables the platform setting '${EXTERNAL_WRITES_SETTING_KEY}' `
+      + `(${EXTERNAL_WRITES_SETTING_LOCATION}). This is a recording, not a live read; run `
+      + `'${CLI_BINARY_NAME} ${VERB_STATUS}' for the current answer.`;
+}
+
+/**
+ * The latest published CLI release that exchange recorded (TR00703), dated the
+ * same way and for the same reason.
+ *
+ * A run that is actually behind never reaches here — the gate in `runCli`
+ * refuses `whoami` outright — so this line is what a *current* CLI reads as
+ * confirmation, and what a CLI whose store predates the field reads as "not
+ * recorded". It is still stated as a recording rather than as live fact,
+ * because that is what it is.
+ */
+function cliReleaseLine(lastExchange) {
+  if (lastExchange.latestCliVersion === undefined) {
+    return `Latest CLI release: not recorded by that exchange. This CLI is ${CLI_VERSION}; run `
+      + `'${CLI_BINARY_NAME} ${VERB_STATUS}' for a current answer.`;
+  }
+  const when = lastExchange.at === undefined ? "at that exchange" : `as of ${lastExchange.at}`;
+  return isBehindLatest(lastExchange.latestCliVersion)
+    ? `Latest CLI release ${when}: ${lastExchange.latestCliVersion}. This CLI is ${CLI_VERSION} and is behind it; `
+      + `Taproot accepts only the latest. Upgrade with: ${CLI_UPGRADE_COMMAND}`
+    : `Latest CLI release ${when}: ${lastExchange.latestCliVersion}. This CLI is ${CLI_VERSION}.`;
+}
+
 /**
  * `taproot-site whoami` — which Taproot, which account, which site, until when.
  *
@@ -75,6 +133,12 @@ export async function whoami(invocation) {
       `That credential ${lapsed ? "expired" : "expires"} ${lastExchange.expiresAt}`
         + `${lapsed ? "; the next command mints another." : "."}`,
     );
+    // The platform authoring switch as of that exchange, dated (TR00692). It is
+    // reported as a recording rather than as the current state, because this
+    // command is offline by design and an operator reading an undated flag
+    // would take a snapshot from last week for a fact about right now.
+    onProgress(platformLine(lastExchange));
+    onProgress(cliReleaseLine(lastExchange));
   }
 
   return successResult(VERB_WHOAMI, config?.siteId, {
@@ -101,6 +165,20 @@ export async function whoami(invocation) {
         capabilities: lastExchange.capabilities,
         expiresAt: lastExchange.expiresAt,
         expired: Date.parse(lastExchange.expiresAt) <= now,
+        // Both absent on a record written before TR00692, and
+        // `externalWritesEnabled` also absent when the server that answered the
+        // exchange predated the field. Absent means "not recorded", never
+        // "enabled": an automation that wants a current answer reads
+        // `platform` off `status`, which says which of the three states it is.
+        ...(lastExchange.at === undefined ? {} : { at: lastExchange.at }),
+        ...(lastExchange.externalWritesEnabled === undefined
+          ? {}
+          : { externalWritesEnabled: lastExchange.externalWritesEnabled }),
+        // Absent on a record written before TR00703, and on one whose server
+        // predated the field. Absent means "not recorded", never "current".
+        ...(lastExchange.latestCliVersion === undefined
+          ? {}
+          : { latestCliVersion: lastExchange.latestCliVersion }),
       },
     }),
     ...(environmentOverride ? { capabilitiesKnown: false } : {}),

package/src/workspace.js

@@ -4,7 +4,7 @@ import { lstat, mkdir, open, readdir, unlink } from "node:fs/promises";
 import path from "node:path";
 
 import { atomicWriteFile } from "./atomic-file.js";
-import { hasAsciiControl, SiteAuthoringError } from "./errors.js";
+import { hasAsciiControl, sanitizeDiagnostic, SiteAuthoringError } from "./errors.js";
 
 /**
  * The local workspace: what `pull` writes, what the push verbs read back, and
@@ -103,15 +103,141 @@ export function internalPageBaselineFile(pageId) {
     : undefined;
 }
 
-// Version 5 makes the page list a source registry: each entry names the one
-// authoritative `file` for its path, the `sourceFormat` that file carries, and
-// the `baseline` hashes pull compares against to detect a remote edit it
-// cannot reconcile. Version 4 classified pulled page files as editable,
-// metadata-only, or an integrity-checked read-only projection but recorded no
-// registry, so a push against one cannot tell an intentional format change
-// from a stale entry. The package is in-repo and unreleased, so an older
-// manifest is re-pulled rather than migrated.
-export const MANIFEST_VERSION = 5;
+/**
+ * Where the revision of a *preserved* remote body is recorded, beside the body
+ * itself.
+ *
+ * The manifest records what this workspace last **reconciled** with, and a
+ * refused pull reconciles nothing — it writes no manifest at all, which is what
+ * makes the same conflict repeat until somebody resolves it. But the refusal
+ * does show the operator the site's version, and after that the site's version
+ * is no longer news. Without somewhere to record that, the push refusal added
+ * for a concurrent remote edit would also refuse the pull conflict's own
+ * documented recovery — "push the local source to make the site match it" —
+ * and the only way out of a conflict would be to give up the local source.
+ *
+ * So this records what the workspace last **saw**, which is a different fact.
+ * A push into a page whose site revision equals the one already shown is the
+ * operator's informed override; a push into one that has moved *again* is still
+ * refused. Any pull that reconciles the page removes it, because the manifest
+ * then carries the newer and stronger claim.
+ */
+export function internalPageObservedRevisionFile(pageId) {
+  return typeof pageId === "string" && SAFE_SEGMENT.test(pageId)
+    ? `${INTERNAL_PAGE_BASELINE_DIRECTORY}/${pageId}.revision.json`
+    : undefined;
+}
+
+// Version 6 records the site's own `baseline.revision` for every tracked page:
+// the opaque revision of the stored authoring state the site reported when this
+// workspace last agreed with it. Version 5 could only compare one pull's body
+// against the next, because the bytes a push sends are not the bytes a read
+// returns — so a push could not tell whether the page it was about to
+// overwrite had moved since, and a change in the API's image-delivery
+// projection between two pulls read as a remote edit. Version 5 made the page
+// list a source registry (`file`, `sourceFormat`, `baseline`); version 4
+// classified pulled files but recorded no registry. The package is in-repo and
+// its manifests are workspace state, so an older one is re-pulled rather than
+// migrated.
+export const MANIFEST_VERSION = 6;
+
+/**
+ * The shape of a page body revision as the site reports it: a scheme name and
+ * a hex digest. The CLI never derives one — it only records what it was told
+ * and compares it with what it is told next — so this is a containment check
+ * on a server string that reaches the manifest and the terminal, not a claim
+ * about how the value is computed.
+ */
+export const PAGE_BODY_REVISION = /^[a-z][a-z0-9]{0,15}:[0-9a-f]{16,128}$/u;
+
+/** A revision as recorded or reported, or `undefined` when there is not one. */
+export function normalizePageBodyRevision(value) {
+  return typeof value === "string" && PAGE_BODY_REVISION.test(value) ? value : undefined;
+}
+
+/**
+ * The revision of the remote body this workspace last saw for a page, or
+ * `undefined` when it has not seen one it did not also reconcile with.
+ *
+ * Damaged or absent internal state is simply "nothing seen": it costs the
+ * operator one pull, which is the same position a workspace that has never
+ * conflicted is in, and is never worth refusing a verb over.
+ */
+export async function readObservedPageRevision(workspaceDir, pageId) {
+  return (await readObservedPageRecord(workspaceDir, pageId))?.revision;
+}
+
+/**
+ * Everything a refused pull recorded for a page: the version the operator was
+ * shown, and the differences the refusal named beside it.
+ *
+ * The version is named either way it can be named. A site that reports a
+ * revision is recorded by `revision`; a site that predates the revision
+ * contract is compared by the canonical hash of its body, and is recorded by
+ * `remoteHash` instead — the same value that comparison is made against. A
+ * hash-only record therefore reports no revision, which is what keeps
+ * `readObservedPageRevision` — and so the push guard it arms — untouched by
+ * this: an override is a statement about a revision, and there is none here.
+ *
+ * The differences are recorded rather than recomputed because the refusal
+ * overwrites the preserved baseline with the version it is refusing. On the
+ * next pull, with nothing further changed on the site, a fresh comparison would
+ * find the preserved copy and the site's document identical and report "the
+ * change is in the page's title, path, or description" for what was a body
+ * edit. The record is what lets a repeated refusal say the same true thing the
+ * first one did; a page that has moved *again* carries a different revision, so
+ * the record no longer applies and the comparison is redone.
+ *
+ * Fail-soft on everything, exactly like the revision read it backs: this is
+ * workspace state a hand edit or an interrupted write can reach, and no verb is
+ * worth refusing over a diagnostic.
+ */
+export async function readObservedPageRecord(workspaceDir, pageId) {
+  const file = internalPageObservedRevisionFile(pageId);
+  if (file === undefined) return undefined;
+  let parsed;
+  try {
+    // The existence check is inside the guard too: a directory or a symlink
+    // where the record should be is "nothing seen", not a refusal.
+    if (!await workspaceFileExists(workspaceDir, file)) return undefined;
+    parsed = await readWorkspaceJson(workspaceDir, file, WORKSPACE_LIMITS.settingsBytes);
+  } catch {
+    return undefined;
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed) || parsed.pageId !== pageId) {
+    return undefined;
+  }
+  const revision = normalizePageBodyRevision(parsed.revision);
+  const remoteHash = typeof parsed.remoteHash === "string" && WORKSPACE_CONTENT_HASH.test(parsed.remoteHash)
+    ? parsed.remoteHash
+    : undefined;
+  // A record naming neither version says nothing about what was shown, which is
+  // the same position as no record at all.
+  if (revision === undefined && remoteHash === undefined) return undefined;
+  return { revision, remoteHash, differences: normalizeObservedDifferences(parsed.differences) };
+}
+
+/**
+ * How many recorded paths one record carries back. The same bound
+ * `SiteAuthoringError#withDifferences` applies, because these paths reach a
+ * refusal's message and its `differences` field by that route.
+ */
+const OBSERVED_DIFFERENCE_PATHS = 100;
+
+/** A recorded `{ paths, truncated }`, or `undefined` when there is not one. */
+function normalizeObservedDifferences(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value) || !Array.isArray(value.paths)) {
+    return undefined;
+  }
+  return {
+    paths: value.paths
+      .filter((entry) => typeof entry === "string")
+      .slice(0, OBSERVED_DIFFERENCE_PATHS)
+      .map((entry) => sanitizeDiagnostic(entry, "path")),
+    truncated: value.truncated === true,
+  };
+}
+
 export const PAGE_WORKSPACE_MODE_EDITABLE = "editable";
 export const PAGE_WORKSPACE_MODE_METADATA_ONLY = "metadata-only";
 export const PAGE_WORKSPACE_MODE_READ_ONLY = "read-only";
@@ -129,6 +255,10 @@ export const WORKSPACE_LIMITS = Object.freeze({
   // One authored page: a Markdown source or a ProseMirror document.
   documentBytes: 2 * 1024 * 1024,
   navigationBytes: 1024 * 1024,
+  // The redirect map: sized from the contract's own bounds (entries, path
+  // and target bytes, pretty-printed JSON overhead) rather than borrowed from
+  // the navigation tree, so the site's own pulled map always reads back.
+  redirectsBytes: 8 * 1024 * 1024,
   settingsBytes: 256 * 1024,
   manifestBytes: 8 * 1024 * 1024,
   mediaBytes: 32 * 1024 * 1024,
@@ -223,10 +353,13 @@ function isDiscoverablePageSource(file) {
  * - An entry whose `file` is missing, unrecognized, or not a file the workspace
  *   walk could have produced is **dropped**. It names no source this package
  *   would ever read, so there is nothing to protect.
- * - A `baseline` that is not a usable pair of hashes is **discarded and
- *   reported**. Losing it costs one pull's worth of conflict detection and
+ * - A `baseline` carrying no usable hash and no usable revision is **discarded
+ *   and reported**. Losing it costs one pull's worth of conflict detection and
  *   nothing else: the next pull re-establishes it from what it reads, and the
- *   authored source is never written over in the meantime.
+ *   authored source is never written over in the meantime. Individual members
+ *   are dropped the same way — an unusable `revision` beside two good hashes
+ *   leaves the entry compared the way version 5 compared it, which is the same
+ *   position a workspace that has not pulled since is in.
  * - A `sourceFormat` that disagrees with the file's own extension is recorded
  *   as `formatMismatch` and the extension wins. `pages push` refuses on it —
  *   it is a hand-edited manifest and re-pulling is the fix — while `pull`
@@ -254,9 +387,14 @@ export function pageSourceRegistry(manifest) {
     const declared = entry.baseline;
     const remoteHash = normalizeBaselineHash(declared?.remoteHash);
     const sourceHash = normalizeBaselineHash(declared?.sourceHash);
-    const baseline = remoteHash === undefined && sourceHash === undefined
+    const revision = normalizePageBodyRevision(declared?.revision);
+    const baseline = remoteHash === undefined && sourceHash === undefined && revision === undefined
       ? undefined
-      : { ...(remoteHash === undefined ? {} : { remoteHash }), ...(sourceHash === undefined ? {} : { sourceHash }) };
+      : {
+        ...(remoteHash === undefined ? {} : { remoteHash }),
+        ...(sourceHash === undefined ? {} : { sourceHash }),
+        ...(revision === undefined ? {} : { revision }),
+      };
     const record = {
       pageId: entry.pageId,
       file: entry.file,