@tokenoftrust/storefront-runner 2.4.25 → 2.4.27

package/apps/storefront/src/lib/publication/mountedDiscovery.ts

@@ -28,6 +28,7 @@ import {
   PUBLICATION_DISCOVERY_ENTRY_KINDS_V1,
   type PublicationDiscoveryEntryKindV1,
 } from "@tot/public-runtime";
+import { publicationRecoveryActiveV1, publicationRecoveryKeyV1 } from "@tot/public-runtime/publication-recovery";
 import { rawPageCanonicalUrl } from "../rawMarketingHtml.js";
 
 export type DiscoverySurfaceV1 = "sitemap" | "feeds" | "publicSearch" | "llms";
@@ -135,14 +136,18 @@ export async function readMountedPublicationDiscoveryV1(input: {
   if (mounts.size === 0 || !input.store) return [];
   let projectionJson: string | null;
   let stateJson: string | null;
+  let recoveryJson: string | null;
   try {
-    [projectionJson, stateJson] = await Promise.all([
+    [projectionJson, stateJson, recoveryJson] = await Promise.all([
       input.store.get(publicationMountedDiscoveryKeyV1(input.tenant.tenant_id)),
       input.store.get(publicationVersionStateKey(input.tenant.tenant_id)),
+      input.store.get(publicationRecoveryKeyV1(input.tenant.tenant_id)),
     ]);
   } catch {
     return [];
   }
+  // Under a whole-site recovery the mounts serve the whole-site release, which lists itself.
+  if (publicationRecoveryActiveV1(recoveryJson)) return [];
   if (!projectionJson || !stateJson || projectionJson.length > MAX_PROJECTION_CHARS) return [];
   const state = parsePublicationVersionStateV1Json(stateJson);
   if (!state.ok) return [];

package/apps/storefront/src/lib/publication/runtimeSource.ts

@@ -12,6 +12,7 @@ import {
   type PublicationRoutePlanV1,
   type RouteTierIndexV1,
 } from "@tot/public-runtime";
+import { publicationRecoveryActiveV1, publicationRecoveryKeyV1 } from "@tot/public-runtime/publication-recovery";
 
 export interface PublicationStateStoreV1 {
   get(key: string): Promise<string | null>;
@@ -110,7 +111,9 @@ export type PublicationRuntimeSourceV1 =
  * Resolve one live request from the public KV state projection into its exact
  * immutable artifact. A carried plan is checked against current route authority
  * before state or object-store I/O. Only an unselected root keeps the legacy
- * adapter; a mounted space never falls through to root content.
+ * adapter; a mounted space never falls through to root content — except under a
+ * whole-site recovery (`publicationRecoveryKeyV1`), when every public space serves
+ * the tenant's whole-site release on `live`, exactly as before its spaces went live.
  */
 export async function resolvePublicationRuntimeSourceV1(input: {
   index: RouteTierIndexV1;
@@ -132,11 +135,18 @@ export async function resolvePublicationRuntimeSourceV1(input: {
   }
 
   let stateJson: string | null;
+  let recoveryJson: string | null = null;
   try {
-    stateJson = await input.store.get(publicationVersionStateKey(input.plan.manifest.tenant));
+    [stateJson, recoveryJson] = await Promise.all([
+      input.store.get(publicationVersionStateKey(input.plan.manifest.tenant)),
+      input.channel === "live" && input.plan.manifest.visibility === "public"
+        ? input.store.get(publicationRecoveryKeyV1(input.plan.manifest.tenant))
+        : Promise.resolve(null),
+    ]);
   } catch {
     return { status: "unavailable", code: "publication_artifact_source_unavailable" };
   }
+  if (publicationRecoveryActiveV1(recoveryJson)) return { status: "legacy-root" };
   if (stateJson === null) {
     return isRoot
       ? { status: "legacy-root" }

package/apps/storefront/src/lib/publication/servingMode.ts

@@ -0,0 +1,52 @@
+/**
+ * Whether a tenant's ROOT is served by a publication space, which decides what a whole-site
+ * promotion (ship, rollback, hotfix, re-publish, platform reconcile) can do for it.
+ *
+ * While the root public space is live and no whole-site recovery holds, a whole-site promotion
+ * cannot reach visitors: on Cloudflare the selected root space shadows the whole-site live channel
+ * (the job would report success while visitors kept the space), and on CloudFront the aggregate
+ * pointer refuses a whole-site publish after minutes of rendering. So it refuses up front with
+ * `publication_root_is_space`, naming the root space and how its content goes live instead.
+ *
+ * Behaviour follows the declared topology and the editorial state, never the tenant id.
+ */
+import type { PublicationVersionStateV1, TenantConfig } from "@tot/public-runtime";
+import { publicationRecoveryActiveV1, publicationRecoveryKeyV1 } from "@tot/public-runtime/publication-recovery";
+
+export const PUBLICATION_ROOT_IS_SPACE = "publication_root_is_space";
+
+export type PublicationServingModeV1 =
+  | { mode: "whole-site"; reason: "no-root-space" | "root-not-live" | "recovered" }
+  | { mode: "spaces"; root: { spaceId: string; versionId: string; revision: number; source: string } };
+
+export async function publicationServingModeV1(input: {
+  tenant: Pick<TenantConfig, "tenant_id" | "publicationSpaces">;
+  readState(): Promise<PublicationVersionStateV1>;
+  kvGet(key: string): Promise<string | null>;
+}): Promise<PublicationServingModeV1> {
+  const root = input.tenant.publicationSpaces?.find((space) => space.tenant === input.tenant.tenant_id &&
+    space.visibility === "public" && space.routes.canonicalMount === "/");
+  if (!root) return { mode: "whole-site", reason: "no-root-space" };
+  if (publicationRecoveryActiveV1(await input.kvGet(publicationRecoveryKeyV1(input.tenant.tenant_id)))) {
+    return { mode: "whole-site", reason: "recovered" };
+  }
+  const pointer = (await input.readState()).pointers.find((candidate) =>
+    candidate.tenant === input.tenant.tenant_id && candidate.spaceId === root.id && candidate.channel === "live");
+  if (!pointer) return { mode: "whole-site", reason: "root-not-live" };
+  return { mode: "spaces", root: { spaceId: root.id, versionId: pointer.versionId, revision: pointer.revision,
+    source: `${root.source.forge}:${root.source.repo}` } };
+}
+
+/** The refusal a whole-site promotion gets while the root is a live publication space. */
+export function publicationRootIsSpaceRefusalV1(
+  tenantId: string,
+  mode: Extract<PublicationServingModeV1, { mode: "spaces" }>,
+): string {
+  const { spaceId, versionId, revision, source } = mode.root;
+  return `${PUBLICATION_ROOT_IS_SPACE}: ${tenantId}'s root is served by publication space "${spaceId}" ` +
+    `(source ${source}, live ${versionId} at revision ${revision}), so a whole-site release would never reach visitors. ` +
+    `Put root content live by activating a root-space version: build it ` +
+    `(scripts/publish/build-publication-space-version.ts --tenant ${tenantId} --space ${spaceId} --source-sha <sha>), then ` +
+    `POST /api/publication-spaces/${spaceId}/review and /api/publication-spaces/${spaceId}/activate. ` +
+    `To serve the whole site instead, recover it first (scripts/publish/recover-publication-tenant.mjs recover).`;
+}

package/apps/storefront/src/pages/tenants/[id]/[...path].ts

@@ -41,6 +41,7 @@ import {
   type R2BucketLike,
   type TenantConfig,
 } from "@tot/public-runtime";
+import { publicationRecoveryActiveV1, publicationRecoveryKeyV1 } from "@tot/public-runtime/publication-recovery";
 import { readWithImagePreviewRewriteOverlay } from "@tot/public-runtime/image-preview-rewrite-overlay";
 import { readR2, readKv, readEnv } from "@/lib/env";
 import {
@@ -95,8 +96,12 @@ async function tryServePublicationRootAsset(input: {
   const tenant = input.tenant;
   if (!tenant || tenant.tenant_id !== input.tenantId ||
     !tenant.publicationSpaces?.some((space) => space.routes.canonicalMount === "/")) return null;
-  const stateJson = await input.kvGet(publicationVersionStateKey(input.tenantId));
-  if (stateJson === null) return null;
+  const [stateJson, recoveryJson] = await Promise.all([
+    input.kvGet(publicationVersionStateKey(input.tenantId)),
+    input.channel === "live" ? input.kvGet(publicationRecoveryKeyV1(input.tenantId)) : Promise.resolve(null),
+  ]);
+  // A whole-site recovery serves the whole-site release's assets, through the legacy pointer.
+  if (stateJson === null || publicationRecoveryActiveV1(recoveryJson)) return null;
   const state = parsePublicationVersionStateV1Json(stateJson);
   if (!state.ok) return null;
   const read = await readPublicationRootAssetV1({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.4.25",
+  "version": "2.4.27",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/cli/src/publication-spaces.mjs

@@ -0,0 +1,223 @@
+/**
+ * A tenant's publication topology as a developer's workspace sees it: one ROOT repository serving
+ * `/`, plus any MOUNTED spaces — each its own repository serving one mount (`/blog`, `/docs`).
+ *
+ * The platform declares the topology; the workspace only records what it was told, in
+ * `.tot/publication-spaces.json` (written by `tot clone`, never committed — the root repo's git
+ * excludes it, and the `spaces/` folder each mounted space is cloned into). Every command that needs
+ * to know which repository owns a URL or a file reads it through this module, so `tot validate`,
+ * `tot dev`, `tot clone` and the change router answer the same way.
+ *
+ * Mount matching mirrors packages/public-runtime/src/publication-space.ts
+ * (`publicationMountMatchesPath`): a mount owns itself and everything below it, segment-wise and
+ * case-sensitively; the longest matching mount wins and `/` owns what nothing else claims.
+ * apps/storefront/src/config/publicationSpaceOwnership.test.ts pins the two together.
+ *
+ * Dependency-free: the published CLI ships it as-is.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** Where `tot clone` puts each mounted space, relative to the root checkout: `spaces/<spaceId>/`. */
+export const SPACES_DIR = "spaces";
+/** The workspace's record of the declared topology, relative to the root checkout. */
+export const TOPOLOGY_FILE = ".tot/publication-spaces.json";
+export const TOPOLOGY_VERSION = 1;
+
+const SPACE_ID = /^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$/;
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/**
+ * @typedef {{ forge: string, repo: string, defaultBranch: string }} SpaceSource
+ * @typedef {{ id: string, mount: string, visibility: "public"|"internal", source: SpaceSource,
+ *   aliases?: string[], collections?: Record<string, string> }} TopologySpace
+ * @typedef {{ version: 1, tenant: string, spaces: TopologySpace[] }} Topology
+ */
+
+/** A mount in canonical form: leading `/`, no trailing `/` except the root itself. Null when not a mount. */
+export function normalizeMount(value) {
+  if (typeof value !== "string" || !value.startsWith("/") || /[?#\\]/.test(value)) return null;
+  const trimmed = value.replace(/\/+$/, "");
+  if (!trimmed) return "/";
+  if (trimmed.split("/").slice(1).some((seg) => !seg || seg === "." || seg === "..")) return null;
+  return trimmed;
+}
+
+/** A request path reduced to what routing reads: no origin, query or fragment; NFC; single slashes. */
+export function normalizeRequestPath(value) {
+  let path = String(value ?? "").trim();
+  try {
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(path)) path = new URL(path).pathname;
+  } catch {
+    return null;
+  }
+  path = path.replace(/[?#].*$/, "");
+  if (!path.startsWith("/")) path = `/${path}`;
+  try {
+    path = decodeURIComponent(path);
+  } catch {
+    return null;
+  }
+  path = path.normalize("NFC").replace(/\/{2,}/g, "/");
+  return path;
+}
+
+/** Does `mount` own `path` (both normalized)? A mount owns itself and every path below it. */
+export function mountMatchesPath(mount, path) {
+  if (mount === "/") return true;
+  return path === mount || path === `${mount}/` || path.startsWith(`${mount}/`);
+}
+
+/**
+ * Parse a recorded topology. Throws with the reason on anything malformed — a half-read topology
+ * would route a change to the wrong repository.
+ * @param {unknown} input
+ * @returns {Topology}
+ */
+export function parseTopology(input) {
+  const raw = /** @type {any} */ (input);
+  if (!isObject(raw) || raw.version !== TOPOLOGY_VERSION || typeof raw.tenant !== "string" || !raw.tenant ||
+    !Array.isArray(raw.spaces)) {
+    throw new Error(`${TOPOLOGY_FILE} is not a version-${TOPOLOGY_VERSION} topology`);
+  }
+  const ids = new Set();
+  const mounts = new Set();
+  const spaces = raw.spaces.map((space, index) => {
+    const at = `${TOPOLOGY_FILE} spaces[${index}]`;
+    if (!isObject(space) || typeof space.id !== "string" || !SPACE_ID.test(space.id)) throw new Error(`${at}: invalid id`);
+    const mount = normalizeMount(space.mount);
+    if (!mount) throw new Error(`${at}: invalid mount`);
+    if (space.visibility !== "public" && space.visibility !== "internal") throw new Error(`${at}: invalid visibility`);
+    const source = space.source;
+    if (!isObject(source) || typeof source.forge !== "string" || typeof source.repo !== "string" || !source.repo ||
+      typeof source.defaultBranch !== "string" || !source.defaultBranch) throw new Error(`${at}: invalid source`);
+    if (ids.has(space.id)) throw new Error(`${at}: duplicate id ${space.id}`);
+    if (mounts.has(mount)) throw new Error(`${at}: duplicate mount ${mount}`);
+    ids.add(space.id);
+    mounts.add(mount);
+    const aliases = Array.isArray(space.aliases) ? space.aliases.map(normalizeMount).filter(Boolean) : [];
+    return {
+      id: space.id,
+      mount,
+      visibility: space.visibility,
+      source: { forge: source.forge, repo: source.repo, defaultBranch: source.defaultBranch },
+      ...(aliases.length ? { aliases } : {}),
+      ...(isObject(space.collections) ? { collections: { ...space.collections } } : {}),
+    };
+  });
+  if (spaces.filter((space) => space.mount === "/").length !== 1) {
+    throw new Error(`${TOPOLOGY_FILE}: exactly one space must own "/"`);
+  }
+  return { version: TOPOLOGY_VERSION, tenant: raw.tenant, spaces };
+}
+
+/**
+ * Build a topology from the platform's declared-space list (`GET /api/publication-spaces`, whose
+ * rows carry `id`, `visibility`, `canonicalMount`, `source` and `routes`).
+ * @param {string} tenant
+ * @param {unknown} rows
+ * @returns {Topology}
+ */
+export function topologyFromDeclaredSpaces(tenant, rows) {
+  if (!Array.isArray(rows)) throw new Error("the platform returned no publication-space list");
+  return parseTopology({
+    version: TOPOLOGY_VERSION,
+    tenant,
+    spaces: rows.map((row) => ({
+      id: row?.id,
+      mount: row?.routes?.canonicalMount ?? row?.canonicalMount,
+      visibility: row?.visibility,
+      source: row?.source,
+      aliases: Array.isArray(row?.routes?.aliases) ? row.routes.aliases.map((alias) => alias?.from) : undefined,
+      collections: row?.routes?.collections,
+    })),
+  });
+}
+
+/** The root space (owns `/`; `parseTopology` guarantees exactly one). @param {Topology} topology */
+export function rootSpace(topology) {
+  return /** @type {TopologySpace} */ (topology.spaces.find((space) => space.mount === "/"));
+}
+
+/** The mounted spaces, longest mount first. @param {Topology} topology */
+export function mountedSpaces(topology) {
+  return topology.spaces.filter((space) => space.mount !== "/").sort((a, b) => b.mount.length - a.mount.length);
+}
+
+/**
+ * Which space owns a URL path: the longest canonical mount (or alias) that owns it, else the root.
+ * Returns null for a path that cannot be read as a URL path.
+ * @param {Topology} topology
+ * @param {string} urlPath
+ * @returns {{ space: TopologySpace, via: "mount"|"alias"|"root" } | null}
+ */
+export function owningSpace(topology, urlPath) {
+  const path = normalizeRequestPath(urlPath);
+  if (path === null) return null;
+  /** @type {{ space: TopologySpace, via: "mount"|"alias", mount: string } | null} */
+  let best = null;
+  for (const space of topology.spaces) {
+    if (space.mount === "/") continue;
+    /** @type {Array<[string, "mount"|"alias"]>} */
+    const claims = [[space.mount, "mount"], ...(space.aliases ?? []).map((alias) => /** @type {[string, "alias"]} */ ([alias, "alias"]))];
+    for (const [mount, via] of claims) {
+      if (mountMatchesPath(mount, path) && (!best || mount.length > best.mount.length)) best = { space, via, mount };
+    }
+  }
+  if (best) return { space: best.space, via: best.via };
+  return { space: rootSpace(topology), via: "root" };
+}
+
+/** A mounted space's working tree, relative to the root checkout. @param {TopologySpace} space */
+export function spaceDir(space) {
+  return space.mount === "/" ? "" : `${SPACES_DIR}/${space.id}`;
+}
+
+/**
+ * Which space a workspace file belongs to, from its path relative to the root checkout:
+ * `spaces/<id>/...` is that space's, everything else is the root's. A file under `spaces/` naming
+ * no declared space belongs to none (null) — it must not be routed anywhere.
+ * @param {Topology} topology
+ * @param {string} relPath
+ * @returns {{ space: TopologySpace, path: string } | null}
+ */
+export function spaceForWorkspaceFile(topology, relPath) {
+  const rel = String(relPath).replace(/\\/g, "/").replace(/^\.\//, "");
+  if (rel === SPACES_DIR || rel.startsWith(`${SPACES_DIR}/`)) {
+    const [, id, ...rest] = rel.split("/");
+    const space = topology.spaces.find((candidate) => candidate.mount !== "/" && candidate.id === id);
+    return space ? { space, path: rest.join("/") } : null;
+  }
+  return { space: rootSpace(topology), path: rel };
+}
+
+/** Read a workspace's recorded topology, or null when the workspace records none. Throws when malformed. */
+export function readWorkspaceTopology(workspace) {
+  const file = join(workspace, TOPOLOGY_FILE);
+  if (!existsSync(file)) return null;
+  return parseTopology(JSON.parse(readFileSync(file, "utf8")));
+}
+
+/**
+ * Record a topology in a root checkout, and keep it — and the cloned spaces — out of the root
+ * repository: both are listed in the checkout's own `.git/info/exclude`, never in a committed file.
+ */
+export function writeWorkspaceTopology(workspace, topology) {
+  const file = join(workspace, TOPOLOGY_FILE);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(parseTopology(topology), null, 2)}\n`);
+  excludeFromRootRepo(workspace, [`/${TOPOLOGY_FILE}`, `/${SPACES_DIR}/`]);
+}
+
+/** Append patterns to `<workspace>/.git/info/exclude`, once each. No-op outside a git checkout. */
+export function excludeFromRootRepo(workspace, patterns) {
+  const gitDir = join(workspace, ".git");
+  if (!existsSync(gitDir)) return;
+  const file = join(gitDir, "info", "exclude");
+  mkdirSync(dirname(file), { recursive: true });
+  const current = existsSync(file) ? readFileSync(file, "utf8") : "";
+  const lines = new Set(current.split("\n").map((line) => line.trim()));
+  const missing = patterns.filter((pattern) => !lines.has(pattern));
+  if (!missing.length) return;
+  appendFileSync(file, `${current && !current.endsWith("\n") ? "\n" : ""}${missing.join("\n")}\n`);
+}

package/packages/public-runtime/package.json

@@ -21,6 +21,7 @@
     "./embed-catalog": "./src/embed-catalog.mjs",
     "./retention-holds": "./src/retention-holds.ts",
     "./publication-content-redirects": "./src/publication-content-redirects.ts",
+    "./publication-recovery": "./src/publication-recovery.ts",
     "./tenant-embed-defaults": "./src/tenant-embed-defaults.mjs",
     "./declared-tenant-config": "./src/declared-tenant-config.mjs",
     "./compliance-coherence": "./src/compliance-coherence.mjs",

package/packages/public-runtime/src/publication-recovery.ts

@@ -0,0 +1,132 @@
+/**
+ * A whole-site recovery: a tenant served by its public publication spaces is put back on a
+ * whole-site release, and later resumed onto its spaces, each in one reviewed action
+ * (scripts/publish/recover-publication-tenant.mjs).
+ *
+ * The Worker holds the record under `publicationRecoveryKeyV1(tenant)`. While it is present every
+ * public space of the tenant serves through the whole-site path instead (`legacy-root`), whatever
+ * its live pointer selects; the editorial state is untouched, so a resume serves exactly what was
+ * live before plus anything activated during the recovery. On CloudFront the same fence rides in
+ * the KVS `live` value (scripts/publish/lib/cloudfront-live-pointer.mjs).
+ *
+ * Every recover and resume also writes an immutable audit record under
+ * `publicationRecoveryAuditKeyV1`, which is never deleted.
+ */
+import type { PublicationSpaceManifestV1 } from "./publication-space.js";
+import type { PublicationVersionStateV1 } from "./publication-version.js";
+
+export const PUBLICATION_RECOVERY_ID_RE = /^rcv_[a-z0-9][a-z0-9-]{6,78}[a-z0-9]$/;
+const SHA40_RE = /^[0-9a-f]{40}$/;
+const DIGEST_RE = /^[A-Za-z0-9_-]{1,128}$/;
+const PRINCIPAL_RE = /^[A-Za-z0-9][A-Za-z0-9._:@-]{0,159}$/;
+const INSTANT_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+
+/** One public space as it was serving when the recovery replaced it. */
+export interface PublicationRecoverySpaceV1 {
+  spaceId: string;
+  revision: number;
+  versionId: string;
+}
+
+export interface PublicationRecoveryV1 {
+  schemaVersion: 1;
+  tenant: string;
+  recoveryId: string;
+  /**
+   * The whole-site release now served: its version (a tenant commit sha) and bundle digest, each
+   * null when the tenant has none on that plane (a tenant whose whole site is its committed
+   * baseline has neither).
+   */
+  wholeSite: { versionId: string | null; digest: string | null };
+  /** The public spaces' live pointers it replaced, and their generation (the sum of revisions). */
+  fromSpaces: { generation: number; spaces: PublicationRecoverySpaceV1[] };
+  principal: string;
+  at: string;
+}
+
+export type PublicationRecoveryEventV1 = "recover" | "resume";
+
+export function publicationRecoveryKeyV1(tenant: string): string {
+  return `cust:publication-recovery:${tenant}`;
+}
+
+export function publicationRecoveryAuditKeyV1(tenant: string, recoveryId: string, event: PublicationRecoveryEventV1): string {
+  if (!PUBLICATION_RECOVERY_ID_RE.test(recoveryId)) throw new Error("publication recovery id is malformed");
+  return `cust:publication-recovery-audit:${tenant}:${recoveryId}:${event}`;
+}
+
+function exactKeys(value: object, keys: readonly string[]): boolean {
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+}
+
+function nullable(value: unknown, re: RegExp): value is string | null {
+  return value === null || (typeof value === "string" && re.test(value));
+}
+
+export function validatePublicationRecoveryV1(value: unknown): value is PublicationRecoveryV1 {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  if (!exactKeys(record, ["schemaVersion", "tenant", "recoveryId", "wholeSite", "fromSpaces", "principal", "at"])) return false;
+  const wholeSite = record.wholeSite as Record<string, unknown> | null;
+  const fromSpaces = record.fromSpaces as Record<string, unknown> | null;
+  if (record.schemaVersion !== 1 || typeof record.tenant !== "string" || !record.tenant ||
+    typeof record.recoveryId !== "string" || !PUBLICATION_RECOVERY_ID_RE.test(record.recoveryId) ||
+    typeof record.principal !== "string" || !PRINCIPAL_RE.test(record.principal) ||
+    typeof record.at !== "string" || !INSTANT_RE.test(record.at) || new Date(record.at).toISOString() !== record.at ||
+    !wholeSite || typeof wholeSite !== "object" || !exactKeys(wholeSite, ["versionId", "digest"]) ||
+    !nullable(wholeSite.versionId, SHA40_RE) || !nullable(wholeSite.digest, DIGEST_RE) ||
+    !fromSpaces || typeof fromSpaces !== "object" || !exactKeys(fromSpaces, ["generation", "spaces"]) ||
+    !Array.isArray(fromSpaces.spaces) || fromSpaces.spaces.length === 0 ||
+    !Number.isSafeInteger(fromSpaces.generation)) return false;
+  let sum = 0;
+  const ids = new Set<string>();
+  for (const space of fromSpaces.spaces as unknown[]) {
+    if (!space || typeof space !== "object" || !exactKeys(space, ["spaceId", "revision", "versionId"])) return false;
+    const { spaceId, revision, versionId } = space as Record<string, unknown>;
+    if (typeof spaceId !== "string" || !spaceId || ids.has(spaceId) || typeof versionId !== "string" || !versionId ||
+      !Number.isSafeInteger(revision) || (revision as number) < 1) return false;
+    ids.add(spaceId);
+    sum += revision as number;
+  }
+  return sum === fromSpaces.generation;
+}
+
+export function parsePublicationRecoveryV1Json(json: string | null): PublicationRecoveryV1 | null {
+  if (json === null) return null;
+  try {
+    const value = JSON.parse(json) as unknown;
+    return validatePublicationRecoveryV1(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The tenant's public spaces as they serve on `live`, sorted by space, and their generation. This
+ * is what a recovery replaces and what its caller must name (a compare-and-set): for a CloudFront
+ * tenant it is the aggregate generation its publish wrote.
+ */
+export function publicationServingSpacesV1(
+  tenant: { tenant_id: string; publicationSpaces?: readonly PublicationSpaceManifestV1[] },
+  state: PublicationVersionStateV1,
+): { generation: number; spaces: PublicationRecoverySpaceV1[] } {
+  const spaces: PublicationRecoverySpaceV1[] = [];
+  for (const manifest of [...(tenant.publicationSpaces ?? [])].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0)) {
+    if (manifest.visibility !== "public" || manifest.tenant !== tenant.tenant_id) continue;
+    const pointer = state.pointers.find((candidate) =>
+      candidate.tenant === tenant.tenant_id && candidate.spaceId === manifest.id && candidate.channel === "live");
+    if (pointer) spaces.push({ spaceId: manifest.id, revision: pointer.revision, versionId: pointer.versionId });
+  }
+  return { generation: spaces.reduce((sum, space) => sum + space.revision, 0), spaces };
+}
+
+/**
+ * Whether the tenant is recovered to its whole site, read fail-safe: a record that exists but does
+ * not validate still counts as recovered, because serving the whole site is the direction a
+ * recovery exists to guarantee. Only an absent record means the spaces serve.
+ */
+export function publicationRecoveryActiveV1(json: string | null): boolean {
+  return json !== null;
+}

package/scripts/dev/publication-spaces-loop.mjs

@@ -0,0 +1,122 @@
+/**
+ * `tot dev`'s mounted publication spaces: run `publication-spaces-dev.ts` (compose the tenant's
+ * declared spaces from their local working trees through the publish-path composition, then seed
+ * the dev server's local state) alongside the dev server, and again whenever a space's working tree
+ * changes — so `/docs`, `/blog`, ... render locally from the same route plan visitors get, and a
+ * save in a space shows on the next reload.
+ *
+ * The composition is the private control plane, so it runs only where the platform tree is present
+ * (the storefront monorepo). The public runner ships without it; there a checkout that has cloned
+ * spaces is told which paths will not render, instead of silently serving 404s under each mount.
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { startWatch } from "./checkout-watch.mjs";
+
+export const SEEDER = "scripts/dev/publication-spaces-dev.ts";
+
+/** Can this tree compose publication spaces? (The public runner cannot: no control plane.) */
+export function publicationSpacesComposable(repoRoot) {
+  return existsSync(join(repoRoot, SEEDER)) &&
+    existsSync(join(repoRoot, "packages", "private-controlplane")) &&
+    existsSync(join(repoRoot, "apps", "storefront", "node_modules", ".bin", "tsx"));
+}
+
+/** The seeder argv for a tenant (and the developer's checkout, in workspace mode). Pure. */
+export function seederArgs(repoRoot, tenant, workspace) {
+  return [join(repoRoot, SEEDER), "--tenant", tenant, ...(workspace ? ["--workspace", workspace] : [])];
+}
+
+/** Read the seeder's one-line JSON verdict from its stdout; null when it printed none. Pure. */
+export function parseSeederVerdict(stdout) {
+  const line = String(stdout).trim().split("\n").filter(Boolean).pop();
+  if (!line) return null;
+  try {
+    const parsed = JSON.parse(line);
+    return parsed && typeof parsed.status === "string" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The developer-facing line for a verdict. Pure. */
+export function describeVerdict(verdict, { first }) {
+  if (!verdict) return "  ⚠ mounted publication spaces could not be composed — their paths will 404 locally.";
+  switch (verdict.status) {
+    case "seeded": {
+      const mounts = verdict.spaces.map((space) => `${space.mount}/ (${space.spaceId})`).join(", ");
+      return first ? `  ✓ mounted spaces render locally: ${mounts}` : `  ↻ re-composed mounted spaces: ${mounts} — reload to see it`;
+    }
+    case "incomplete":
+      return `  ⚠ mounted spaces not composed — ${verdict.missing.join("; ")}. Their paths 404 locally until cloned (tot clone).`;
+    case "refused":
+      return `  ✗ the publish-path composition refused ${verdict.spaceId ?? "this topology"}: ${verdict.code} — a publish would refuse it too.`;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Compose + seed once now, then again on every change under `watchDirs()`. Runs are serialized: a
+ * save during a run schedules exactly one more. Returns `{ close }`.
+ * @param {{ repoRoot: string, tenant: string, workspace: string|null, log?: (line: string) => void,
+ *   spawnImpl?: typeof spawn, watch?: typeof startWatch, watchDirs?: (verdict: any) => string[] }} input
+ */
+export function startPublicationSpacesLoop({
+  repoRoot, tenant, workspace, log = console.log, spawnImpl = spawn, watch = startWatch,
+  watchDirs = (verdict) => verdict?.watch ?? [],
+}) {
+  const appDir = join(repoRoot, "apps", "storefront");
+  const tsx = join(appDir, "node_modules", ".bin", "tsx");
+  const watchers = [];
+  let running = false;
+  let again = false;
+  let closed = false;
+  let first = true;
+  let watching = false;
+
+  const run = () => {
+    if (closed) return;
+    if (running) { again = true; return; }
+    running = true;
+    let stdout = "";
+    let stderr = "";
+    const child = spawnImpl(tsx, seederArgs(repoRoot, tenant, workspace), { cwd: appDir, stdio: ["ignore", "pipe", "pipe"] });
+    child.stdout?.on("data", (chunk) => { stdout += chunk; });
+    child.stderr?.on("data", (chunk) => { stderr += chunk; });
+    child.on("close", () => {
+      running = false;
+      const verdict = parseSeederVerdict(stdout);
+      if (!verdict && stderr.trim()) log(`  ⚠ ${stderr.trim().split("\n").pop()}`);
+      const line = describeVerdict(verdict, { first });
+      if (line && !(verdict?.status === "none")) log(line);
+      first = false;
+      if (!watching && verdict && verdict.status !== "none") {
+        watching = true;
+        for (const dir of watchDirs(verdict)) {
+          try {
+            watchers.push(watch(dir, true, () => run()));
+          } catch {
+            log(`  ⚠ could not watch ${dir} — re-run tot dev to pick up its changes.`);
+          }
+        }
+      }
+      if (again) { again = false; run(); }
+    });
+    child.on("error", (error) => {
+      running = false;
+      log(`  ⚠ mounted publication spaces could not be composed: ${error.message}`);
+    });
+  };
+
+  run();
+  return {
+    close() {
+      closed = true;
+      for (const watcher of watchers) {
+        try { watcher.close(); } catch { /* best effort */ }
+      }
+    },
+  };
+}

package/scripts/tot-dev.mjs

@@ -68,6 +68,8 @@ import { busyPortMessage, classifyBusyPort, lockPort, unlockPort } from "./dev/p
 import { resync, startWatch } from "./dev/checkout-watch.mjs";
 import { standaloneGraftPlan } from "./dev/standalone-graft-plan.mjs";
 import { findMissingCtaIds } from "./tenant/validate.mjs";
+import { publicationSpacesComposable, startPublicationSpacesLoop } from "./dev/publication-spaces-loop.mjs";
+import { SPACES_DIR } from "../packages/cli/src/publication-spaces.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const repoRoot = resolve(here, ".."); // scripts/ -> repo root
@@ -415,14 +417,13 @@ console.log(`  Private local preview — nothing is published. Server binds all
 }
 
 // --- boot astro dev (Vite HMR); --host so IPv4 `localhost`/127.0.0.1 both work -
-// In standalone mode we MUST keep astro in the FOREGROUND, attached to this
-// process: Astro 7 auto-detects an agent-run terminal and forks the dev server to
-// a detached daemon (`astro dev stop/status`), which would make THIS process exit
-// immediately — firing our cleanup and tearing down the graft symlinks while the
-// daemon keeps serving the (restored) in-tree content. Setting ASTRO_DEV_BACKGROUND
-// tells Astro "you are already the managed child → run foreground" (see astro's
-// cli/dev/{index,background}.js), so our SIGINT/exit lifecycle and symlink cleanup
-// stay correct. Monorepo mode is left untouched (current behavior).
+// astro MUST stay in the FOREGROUND, attached to this process: Astro 7 auto-detects
+// an agent-run terminal and forks the dev server to a detached daemon (`astro dev
+// stop/status`), which would make THIS process exit immediately — firing our cleanup
+// (tearing down the graft, stopping the publication-space loop) while the daemon
+// keeps serving. Setting ASTRO_DEV_BACKGROUND tells Astro "you are already the
+// managed child → run foreground" (see astro's cli/dev/{index,background}.js), so
+// our SIGINT/exit lifecycle stays correct in both modes.
 // TOT_DEV_TENANT tells the inline-AI edit loop (astro.config.mjs's
 // inlineAiEditPlugin, scripts/dev/ai-edit.mjs) which tenant's content/theme to
 // read+write: one `tot dev <tenant>` run always serves exactly one tenant, so
@@ -433,9 +434,7 @@ console.log(`  Private local preview — nothing is published. Server binds all
 // MUST read+write it, NOT the in-tree graft, or browser edits are silently lost
 // on the next resync. MONOREPO: the in-tree tenants/<id>/ dir.
 const devSourceRoot = resolveDevSourceRoot(workspacePath, repoRoot, tenant);
-const spawnEnv = workspacePath
-  ? { ...process.env, ASTRO_DEV_BACKGROUND: "1", TOT_DEV_TENANT: tenant, TOT_DEV_SOURCE_ROOT: devSourceRoot }
-  : { ...process.env, TOT_DEV_TENANT: tenant, TOT_DEV_SOURCE_ROOT: devSourceRoot };
+const spawnEnv = { ...process.env, ASTRO_DEV_BACKGROUND: "1", TOT_DEV_TENANT: tenant, TOT_DEV_SOURCE_ROOT: devSourceRoot };
 // LAUNCHER-AGNOSTIC astro spawn: the published runner tree may have been
 // installed by pnpm OR npm (npm ships with every Node — the runner must not
 // require pnpm at RUNTIME), so resolve astro's real entry through Node's own
@@ -453,12 +452,31 @@ const child = spawn(
   { cwd: appDir, stdio: "inherit", env: spawnEnv },
 );
 
+// --- mounted publication spaces (/docs, /blog, ...) -----------------------------
+// Composed from their local working trees through the publish-path composition and seeded into
+// the dev server's local state while astro boots, then again on every save in a space (see
+// scripts/dev/publication-spaces-loop.mjs). The public runner has no composition, so there a
+// checkout with cloned spaces is told its mounted paths will not render rather than left to 404.
+let spacesLoop = null;
+if (publicationSpacesComposable(repoRoot)) {
+  spacesLoop = startPublicationSpacesLoop({
+    repoRoot,
+    tenant,
+    workspace: workspacePath ? resolve(workspacePath) : null,
+  });
+} else if (workspacePath && existsSync(join(resolve(workspacePath), SPACES_DIR))) {
+  console.warn(
+    `  ⚠ this checkout has mounted publication spaces (${SPACES_DIR}/) — the public preview engine renders the root only, so their paths 404 here.`,
+  );
+}
+
 // Clean up grafts + the port lock on every exit path so we never leave
 // symlinks in the tree, or a lock a LATER run would misread as still live.
 function shutdown(signal) {
   child.kill(signal);
 }
 function cleanupAll() {
+  spacesLoop?.close();
   cleanupGrafts();
   unlockPort(resolvedPort);
 }