@tokenoftrust/storefront-runner 2.4.24 → 2.4.25

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

@@ -62,8 +62,23 @@ export class PublicationSpaceContentProvider implements ContentProvider {
   constructor(
     private readonly sharedRoot: ContentProvider,
     private readonly publication: OpenPublicationArtifactV1,
+    /**
+     * A discovery document (sitemap, feeds, search index, llms.txt) lists every page of the space,
+     * so it reads any of them; a page request reads only the page its plan selected.
+     */
+    private readonly wholeSpace = false,
   ) {}
 
+  /** The space-relative slug a page request may read, or null. `""` is the space's home. */
+  private readableSlug(slug: string): string | null {
+    if (!this.wholeSpace) return selectedPageSlug(this.plan, slug);
+    const requested = stripSlashes(slug);
+    const mount = stripSlashes(this.plan.manifest.routes.canonicalMount);
+    if (!mount) return requested;
+    if (requested === mount) return "";
+    return requested.startsWith(`${mount}/`) ? requested.slice(mount.length + 1) : null;
+  }
+
   private get plan(): PublicationRouteRenderPlanV1 {
     return this.publication.selection;
   }
@@ -86,7 +101,7 @@ export class PublicationSpaceContentProvider implements ContentProvider {
   }
 
   async getPageHtml(slug: string): Promise<string | null> {
-    const selected = selectedPageSlug(this.plan, slug);
+    const selected = this.readableSlug(slug);
     if (selected === null) return null;
     const raw = this.publication.readContent(
       selected ? `pages-html/${selected}.html` : "home.html",
@@ -122,10 +137,11 @@ export class PublicationSpaceContentProvider implements ContentProvider {
   }
 
   async getPage(slug: string): Promise<EditorialPage | null> {
-    const selected = selectedPageSlug(this.plan, slug);
+    const selected = this.readableSlug(slug);
     if (!selected) return null;
     const page = (await this.sourcePages()).find((candidate) => candidate.slug === selected);
-    return page ? rebasePage(this.plan, page, stripSlashes(this.plan.canonicalPath)) : null;
+    if (!page) return null;
+    return this.wholeSpace ? rebasePage(this.plan, page) : rebasePage(this.plan, page, stripSlashes(this.plan.canonicalPath));
   }
 
   async listPages(): Promise<EditorialPage[]> {
@@ -152,8 +168,9 @@ export class PublicationSpaceContentProvider implements ContentProvider {
 export function bindPublicationSpaceContentProviderV1(
   sharedRoot: ContentProvider,
   publication?: OpenPublicationArtifactV1,
+  options: { wholeSpace?: boolean } = {},
 ): ContentProvider {
   return publication
-    ? new PublicationSpaceContentProvider(sharedRoot, publication)
+    ? new PublicationSpaceContentProvider(sharedRoot, publication, options.wholeSpace ?? false)
     : sharedRoot;
 }

package/apps/storefront/src/middleware/index.ts

@@ -25,7 +25,7 @@ import { getTenantResolver } from "@/config/resolver";
 import { readEnv, readKv, readR2 } from "@/lib/runtimeEnv";
 import { resolveCdnForwardRouting, resolveTenantRouting } from "@/lib/tenantRouting";
 import { crossSiteFormRefusal, verifyCdnForward } from "@/lib/cdnForward";
-import { compileRouteTierIndexV1, type RouteTierIndexV1 } from "@tot/public-runtime";
+import { compileRouteTierIndexV1, resolvePublicationRoutePlanV1, type RouteTierIndexV1 } from "@tot/public-runtime";
 import type { PublicationArtifactBucketV1, TenantConfig } from "@tot/public-runtime";
 import { DEV_DRAFT_COOKIE } from "@/lib/dev/devDraft";
 import { applySecurityHeaders } from "@/lib/securityHeaders";
@@ -39,6 +39,7 @@ import { HEALTH_PATH, healthResponse } from "@/lib/health";
 import { observeDeployVersion } from "@/lib/activity/deployVersion";
 import { primeActivityKillSwitch } from "@/lib/activity/killSwitch";
 import {
+  isPlatformPublicDiscoveryPath,
   platformStaticRootLocationV1,
   publicationRedirectLocationV1,
   resolveMiddlewareBranchV1,
@@ -314,6 +315,14 @@ async function serveRequest(
     return asset;
   }
 
+  // A tenant's discovery documents (sitemap, feeds, search index, llms.txt, robots) are the root's:
+  // when the root is a publication space, they render from its selected version, as its pages do.
+  const discoveryRoot = isPlatformPublicDiscoveryPath(renderPath)
+    ? resolvePublicationRoutePlanV1(routeTierIndexFor(tenant), "/")
+    : null;
+  const publicationSourceRoute = discoveryRoot?.action === "render" ? discoveryRoot : publication;
+  const publicationSourcePath = discoveryRoot?.action === "render" ? "/" : renderPath;
+
   if (branch === "public-render") {
     return await servePublicRender({
       context,
@@ -326,9 +335,11 @@ async function serveRequest(
       cache,
       kv,
       routeTierIndex: routeTierIndexFor(tenant),
-      publicationRequestPath: renderPath,
-      publicationRoute: publication,
-      publicationBucket,
+      publicationRequestPath: publicationSourcePath,
+      publicationRoute: publicationSourceRoute,
+      publicationBucket: discoveryRoot?.action === "render"
+        ? await readR2("TENANT_ASSETS") as unknown as PublicationArtifactBucketV1 | undefined
+        : publicationBucket,
     });
   }
 

package/apps/storefront/src/middleware/renderChain.ts

@@ -14,6 +14,7 @@ import { mergeTheme, themeToCssVars } from "@/themes/schema";
 import { createToTClient } from "@/lib/tot/ToTClient";
 import { readEnv, readR2 } from "@/lib/runtimeEnv";
 import { tryServeStaticBundle } from "./staticBundle.js";
+import { isPlatformPublicDiscoveryPath } from "./routeBranch.js";
 import { resolveCandidateContentPin, type CandidateContentPin } from "./candidatePin.js";
 import { createContentProvider, DevDraftContentProvider } from "@/lib/storyblok/provider";
 import { bindPublicationSpaceContentProviderV1 } from "@/lib/publication/contentProvider.js";
@@ -82,6 +83,7 @@ import {
   HTML_CACHE_POLICY_CAPTURE_HEADER,
   HTML_CACHE_POLICY_CAPTURE_PROBE,
 } from "@tot/public-runtime";
+import { publicationContentRedirectLocationV1 } from "@tot/public-runtime/publication-content-redirects";
 import { loadTenantIntegrationDeclarations } from "@/lib/integration/tenantDeclarations";
 import { resolveTenantCommerce } from "@/lib/checkoutCommerce";
 import {
@@ -236,6 +238,21 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
     if (isInternalPublication) applyInternalContentResponsePolicy(response.headers);
     return response;
   }
+  // The owning space's content-declared redirects answer before anything renders, as the CloudFront
+  // redirect plane does for the same declarations: a same-origin target keeps the path-routing prefix
+  // and the query; an off-site target (the root space only) is sent as declared.
+  if (publicationSource.status === "selected") {
+    const location = publicationContentRedirectLocationV1(publicationSource.artifact, input.publicationRequestPath);
+    if (location) {
+      const response = new Response(null, {
+        status: 308,
+        headers: { location: location.startsWith("/") ? `${url.origin}${basePath}${location}${url.search}` : location },
+      });
+      applySecurityHeaders(response.headers);
+      if (isInternalPublication) applyInternalContentResponsePolicy(response.headers);
+      return response;
+    }
+  }
 
   // The tenant as it renders in THIS environment: its record with the declared
   // `.tot/config.json` fields applied (compliance, siteType, capabilities,
@@ -613,6 +630,8 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   locals.content = bindPublicationSpaceContentProviderV1(
     sharedRootContent,
     publicationSource.status === "selected" ? publicationSource.artifact : undefined,
+    // A discovery document lists the whole space it is bound to, not one selected page.
+    { wholeSpace: isPlatformPublicDiscoveryPath(renderPath) },
   );
   // Developer-draft content overlay — serves the AI-edited artifacts to the draft
   // owner only; every other viewer keeps the published/base chain above.

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

@@ -17,6 +17,10 @@
  * Preview sessions also consult the image-capture rewrite overlay so rewritten
  * `public/*.css` (and similar text assets) serve `/_a/<sha>` references.
  *
+ * A tenant whose ROOT is a publication space serves these paths from that space's selected version
+ * (its public asset lane, `<namespace>/<path>`), the same URL a whole-site tenant serves them at;
+ * otherwise the legacy asset pointer below answers.
+ *
  * Version selection, in order: a candidate/revision pin (`tot_preview_version` +
  * token cookie); else, for a shared-preview viewer (preview host, or a valid token
  * for this tenant), the version the content `preview` channel serves — what the
@@ -24,11 +28,18 @@
  */
 import type { APIContext } from "astro";
 import {
+  ASSET_CACHE_CONTROL,
   assetContentType,
+  compileRouteTierIndexV1,
+  parsePublicationVersionStateV1Json,
   parseTenantAssetPath,
+  publicationVersionStateKey,
+  readPublicationRootAssetV1,
   resolveChannelVersion,
   serveTenantAsset,
+  type PublicationArtifactReadBucketV1,
   type R2BucketLike,
+  type TenantConfig,
 } from "@tot/public-runtime";
 import { readWithImagePreviewRewriteOverlay } from "@tot/public-runtime/image-preview-rewrite-overlay";
 import { readR2, readKv, readEnv } from "@/lib/env";
@@ -68,6 +79,42 @@ async function tryServePreviewRewriteOverlay(input: {
   });
 }
 
+/** The root publication space's asset, or null when the tenant's root is not a selected space. */
+async function tryServePublicationRootAsset(input: {
+  /** The tenant the request resolved to (`Astro.locals.tenant`). */
+  tenant: TenantConfig | undefined;
+  bucket: PublicationArtifactReadBucketV1;
+  kvGet: (key: string) => Promise<string | null>;
+  tenantId: string;
+  pathname: string;
+  channel: "live" | "preview";
+  ifNoneMatch: string | null;
+}): Promise<Response | null> {
+  const parsed = parseTenantAssetPath(input.pathname);
+  if (!parsed || parsed.tenantId !== input.tenantId) return null;
+  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 state = parsePublicationVersionStateV1Json(stateJson);
+  if (!state.ok) return null;
+  const read = await readPublicationRootAssetV1({
+    index: compileRouteTierIndexV1(tenant), state: state.value, channel: input.channel,
+    bucket: input.bucket, relativePath: parsed.rel,
+  });
+  if (read.status === "legacy-root") return null;
+  if (read.status === "absent") {
+    return new Response("Not found", { status: 404, headers: { "cache-control": "no-store" } });
+  }
+  const etag = `"${read.sha256}"`;
+  const headers = { "content-type": assetContentType(parsed.rel), "cache-control": ASSET_CACHE_CONTROL, etag };
+  if (input.ifNoneMatch && input.ifNoneMatch.split(",").some((value) => value.trim().replace(/^W\//, "") === etag)) {
+    return new Response(null, { status: 304, headers });
+  }
+  return new Response(read.bytes as Uint8Array<ArrayBuffer>, { status: 200, headers });
+}
+
 export async function GET(context: APIContext): Promise<Response> {
   const [bucket, kv] = await Promise.all([
     readR2("TENANT_ASSETS"),
@@ -106,6 +153,17 @@ export async function GET(context: APIContext): Promise<Response> {
   const previewVersionId = pinnedVersionId ?? sharedPreview.versionId;
 
   const pathname = url.pathname;
+  const fromPublication = await tryServePublicationRootAsset({
+    tenant: context.locals.tenant,
+    bucket: bucket as unknown as PublicationArtifactReadBucketV1,
+    kvGet: (key) => kv.get(key),
+    tenantId: urlTenant,
+    pathname,
+    channel: sharedPreview.preview || context.locals.customizationEnv === "test" ? "preview" : "live",
+    ifNoneMatch: context.request.headers.get("if-none-match"),
+  });
+  if (fromPublication) return fromPublication;
+
   if (previewVersionId) {
     const overlay = await tryServePreviewRewriteOverlay({
       kvGet: (key) => kv.get(key),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.4.24",
+  "version": "2.4.25",
   "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/public-runtime/package.json

@@ -20,6 +20,7 @@
     "./catalog-files": "./src/catalog-files.ts",
     "./embed-catalog": "./src/embed-catalog.mjs",
     "./retention-holds": "./src/retention-holds.ts",
+    "./publication-content-redirects": "./src/publication-content-redirects.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/schemas/publication-space/v1/manifest.schema.json

@@ -85,6 +85,19 @@
             "blog": { "$ref": "#/$defs/collectionBase" },
             "the-build": { "$ref": "#/$defs/collectionBase" }
           }
+        },
+        "externalRedirects": {
+          "description": "Exact paths the ROOT space sends to another origin; a mounted space declares none.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["from", "to"],
+            "properties": {
+              "from": { "$ref": "#/$defs/path" },
+              "to": { "type": "string", "pattern": "^https://[^/?#@\\s]+(?:/[^?#\\s]*)?$" }
+            }
+          }
         }
       }
     },

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

@@ -42,8 +42,8 @@ export interface PublicationArtifactBundleExpectationV1 {
 
 /** Locale-independent canonical order for immutable publication files. */
 export function comparePublicationArtifactFilesV1(
-  left: PublicationArtifactFileV1,
-  right: PublicationArtifactFileV1,
+  left: Pick<PublicationArtifactFileV1, "lane" | "path">,
+  right: Pick<PublicationArtifactFileV1, "lane" | "path">,
 ): number {
   const leftIdentity = `${left.lane}\0${left.path}`;
   const rightIdentity = `${right.lane}\0${right.path}`;
@@ -96,10 +96,28 @@ export function publicationArtifactFileBytesV1(file: PublicationArtifactFileV1):
   }
 }
 
+/** The identity fields a bundle or its index must carry for `expected`. */
+function identityMatches(
+  value: Omit<PublicationArtifactBundleV1, "files">,
+  expected: PublicationArtifactBundleExpectationV1,
+): boolean {
+  return value.tenant === expected.tenant && value.spaceId === expected.spaceId &&
+    value.versionId === expected.versionId && value.sourceSha === expected.sourceSha &&
+    /^[0-9a-f]{40}$/.test(value.sourceSha) && value.artifactDigest === expected.artifactDigest &&
+    /^[0-9a-f]{64}$/.test(value.artifactDigest) && typeof value.sourceLock === "string" &&
+    /^[0-9a-f]{64}$/.test(value.sourceLock) &&
+    ["public", "internal"].includes(value.visibility) && typeof value.assetNamespace === "string" &&
+    !!value.assetNamespace && ["public", "authorized"].includes(value.assetAccess) &&
+    (expected.visibility === undefined || value.visibility === expected.visibility) &&
+    (expected.assetNamespace === undefined || value.assetNamespace === expected.assetNamespace) &&
+    (expected.assetAccess === undefined || value.assetAccess === expected.assetAccess);
+}
+
 /**
- * Canonical marker admission shared by the writer-side activation gate and the
- * renderer. It validates shape, identity, source provenance/lock, and recomputes
- * the complete file-list digest; a marker cannot define its own admission facts.
+ * Full in-memory bundle admission: the producer side (a freshly built version, a CI composition)
+ * holds every file's bytes. It validates shape, identity and source lock, and recomputes the digest;
+ * a bundle cannot define its own admission facts. A stored artifact is admitted by its index
+ * (`validatePublicationArtifactIndexV1`).
  */
 export async function validatePublicationArtifactBundleV1(
   value: unknown,
@@ -109,17 +127,7 @@ export async function validatePublicationArtifactBundleV1(
   const bundle = value as PublicationArtifactBundleV1;
   if (!hasExactKeys(bundle, ["tenant", "spaceId", "versionId", "sourceSha", "artifactDigest",
     "sourceLock", "visibility", "assetNamespace", "assetAccess", "files"]) ||
-    bundle.tenant !== expected.tenant || bundle.spaceId !== expected.spaceId ||
-    bundle.versionId !== expected.versionId || bundle.sourceSha !== expected.sourceSha ||
-    !/^[0-9a-f]{40}$/.test(bundle.sourceSha) || bundle.artifactDigest !== expected.artifactDigest ||
-    !/^[0-9a-f]{64}$/.test(bundle.artifactDigest) || typeof bundle.sourceLock !== "string" ||
-    !/^[0-9a-f]{64}$/.test(bundle.sourceLock) ||
-    !["public", "internal"].includes(bundle.visibility) || typeof bundle.assetNamespace !== "string" ||
-    !bundle.assetNamespace ||
-    !["public", "authorized"].includes(bundle.assetAccess) || !Array.isArray(bundle.files) ||
-    (expected.visibility !== undefined && bundle.visibility !== expected.visibility) ||
-    (expected.assetNamespace !== undefined && bundle.assetNamespace !== expected.assetNamespace) ||
-    (expected.assetAccess !== undefined && bundle.assetAccess !== expected.assetAccess)) return { ok: false };
+    !identityMatches(bundle, expected) || !Array.isArray(bundle.files)) return { ok: false };
   const paths = new Set<string>();
   for (const file of bundle.files) {
     if (!validPublicationArtifactFileV1(file) || !publicationArtifactFileBytesV1(file)) {
@@ -148,23 +156,114 @@ export async function validatePublicationArtifactBundleV1(
   }
 }
 
+/**
+ * One file as the artifact INDEX records it: its identity and the sha256 of its bytes, never the
+ * bytes themselves. The artifact digest is computed over exactly these rows, so an index proves
+ * its version without carrying any content.
+ */
+export interface PublicationArtifactIndexFileV1 {
+  lane: PublicationArtifactFileV1["lane"];
+  path: string;
+  encoding: PublicationArtifactFileV1["encoding"];
+  byteSize: number;
+  sha256: string;
+}
+
+/**
+ * The stored marker for one tenant+space+version: the bundle's identity and its file index. It grows
+ * with the number of files, never with their bytes; each file's bytes are their own object, addressed
+ * by sha256 (`publicationArtifactObjectKeyV1`), and a reader fetches only the files it serves.
+ */
+export interface PublicationArtifactIndexV1 extends Omit<PublicationArtifactBundleV1, "files"> {
+  files: PublicationArtifactIndexFileV1[];
+}
+
+/** The digest over index rows: the one formula the writer, the index validator and readers share. */
+async function publicationArtifactIndexDigestV1(files: readonly PublicationArtifactIndexFileV1[]): Promise<string> {
+  const rows = [...files].sort(comparePublicationArtifactFilesV1)
+    .map((file) => `${file.lane}\0${file.path}\0${file.encoding}\0${file.byteSize}\0${file.sha256}`);
+  return sha256Hex(rows.join("\n"));
+}
+
+/** The index row for one complete file. */
+export async function publicationArtifactIndexFileV1(
+  file: PublicationArtifactFileV1,
+): Promise<PublicationArtifactIndexFileV1> {
+  const bytes = publicationArtifactFileBytesV1(file);
+  if (!bytes) throw new Error("publication artifact file is malformed");
+  return { lane: file.lane, path: file.path, encoding: file.encoding, byteSize: file.byteSize,
+    sha256: await sha256Hex(bytes) };
+}
+
 /** Canonical content digest shared by the trusted writer and renderer readback. */
 export async function publicationArtifactDigestV1(
   files: readonly PublicationArtifactFileV1[],
 ): Promise<string> {
   if (!Array.isArray(files)) throw new Error("publication artifact file list is malformed");
-  const ordered = [...files].sort(comparePublicationArtifactFilesV1);
   const paths = new Set<string>();
-  const rows = await Promise.all(ordered.map(async (file) => {
+  const rows = await Promise.all(files.map(async (file) => {
     if (!validPublicationArtifactFileV1(file) || paths.has(file.path)) {
       throw new Error("publication artifact file is malformed or duplicated");
     }
     paths.add(file.path);
-    const bytes = publicationArtifactFileBytesV1(file);
-    if (!bytes) throw new Error("publication artifact file is malformed");
-    return `${file.lane}\0${file.path}\0${file.encoding}\0${file.byteSize}\0${await sha256Hex(bytes)}`;
+    return publicationArtifactIndexFileV1(file);
   }));
-  return sha256Hex(rows.join("\n"));
+  return publicationArtifactIndexDigestV1(rows);
+}
+
+/** The index a complete bundle stores as its marker. */
+export async function publicationArtifactIndexV1(
+  bundle: PublicationArtifactBundleV1,
+): Promise<PublicationArtifactIndexV1> {
+  const { files, ...identity } = bundle;
+  const rows = await Promise.all([...files].sort(comparePublicationArtifactFilesV1)
+    .map((file) => publicationArtifactIndexFileV1(file)));
+  return { ...identity, files: rows };
+}
+
+function validIndexFile(value: unknown): value is PublicationArtifactIndexFileV1 {
+  if (!value || typeof value !== "object" || !hasExactKeys(value,
+    ["lane", "path", "encoding", "byteSize", "sha256"])) return false;
+  const file = value as PublicationArtifactIndexFileV1;
+  return ["content", "public-asset", "authorized-asset"].includes(file.lane) &&
+    ["utf8", "base64"].includes(file.encoding) && typeof file.path === "string" &&
+    safeArtifactPath(file.path) && Number.isSafeInteger(file.byteSize) && file.byteSize >= 0 &&
+    typeof file.sha256 === "string" && /^[0-9a-f]{64}$/.test(file.sha256);
+}
+
+/**
+ * Admission for a stored index, shared by review admission, the renderer and every off-path reader.
+ * It validates shape and identity, recomputes the artifact digest from the rows and the source lock
+ * from that digest: an index cannot define its own admission facts, exactly as a full bundle could not.
+ */
+export async function validatePublicationArtifactIndexV1(
+  value: unknown,
+  expected: PublicationArtifactBundleExpectationV1,
+): Promise<{ ok: true; value: PublicationArtifactIndexV1 } | { ok: false }> {
+  if (!value || typeof value !== "object") return { ok: false };
+  const index = value as PublicationArtifactIndexV1;
+  if (!hasExactKeys(index, ["tenant", "spaceId", "versionId", "sourceSha", "artifactDigest",
+    "sourceLock", "visibility", "assetNamespace", "assetAccess", "files"]) ||
+    !identityMatches(index, expected) || !Array.isArray(index.files)) return { ok: false };
+  const paths = new Set<string>();
+  for (const file of index.files) {
+    if (!validIndexFile(file)) return { ok: false };
+    if ((file.lane === "public-asset" && index.assetAccess !== "public") ||
+      (file.lane === "authorized-asset" && index.assetAccess !== "authorized")) return { ok: false };
+    if (paths.has(file.path)) return { ok: false };
+    paths.add(file.path);
+  }
+  try {
+    const digest = await publicationArtifactIndexDigestV1(index.files);
+    if (digest !== expected.artifactDigest) return { ok: false };
+    const sourceLock = await publicationArtifactSourceLockV1({
+      tenant: expected.tenant, spaceId: expected.spaceId, forge: expected.forge, repo: expected.repo,
+      sourceSha: expected.sourceSha, versionId: expected.versionId, artifactDigest: digest,
+    });
+    return sourceLock === index.sourceLock ? { ok: true, value: index } : { ok: false };
+  } catch {
+    return { ok: false };
+  }
 }
 
 /** Canonical source lock binds one immutable artifact to its configured source. */
@@ -183,41 +282,174 @@ export function publicationArtifactSourceLockV1(input: {
   ].join("\0"));
 }
 
-/** Physical immutable namespace. Logical artifact paths are always relative. */
-export function publicationArtifactKeyV1(
-  tenant: string,
-  spaceId: string,
-  versionId: string,
-  lane: PublicationArtifactFileV1["lane"],
-  relativePath: string,
-): string {
+function assertSafeIdentity(tenant: string, spaceId: string, versionId: string): void {
   if (!PUBLICATION_ARTIFACT_IDENTIFIER_RE.test(tenant) ||
     !PUBLICATION_ARTIFACT_IDENTIFIER_RE.test(spaceId) ||
     !PUBLICATION_ARTIFACT_VERSION_RE.test(versionId)) {
     throw new Error("publication artifact identity is unsafe");
   }
-  if (!["content", "public-asset", "authorized-asset"].includes(lane) ||
-    !relativePath || relativePath.startsWith("/") || relativePath.includes("\\") ||
-    relativePath.includes("\0") ||
-    relativePath.split("/").some((part) => !part || part === "." || part === "..")) {
-    throw new Error("publication artifact path is unsafe");
-  }
-  return `publications/${tenant}/${spaceId}/${versionId}/${lane}/${relativePath}`;
 }
 
-/** The largest `bundle.json` marker review admission reads; a larger one is never built. */
-export const PUBLICATION_ARTIFACT_MARKER_MAX_BYTES = 16 * 1024 * 1024;
+/**
+ * Physical address of one file's bytes: its sha256 under the version. A tenant's file names never
+ * reach an object key, so a key is ASCII by construction and no tool between writer and reader can
+ * re-encode it (a store CLI percent-encodes a non-ASCII key, which strands the object under a name
+ * the reader never asks for).
+ */
+export function publicationArtifactObjectKeyV1(
+  tenant: string,
+  spaceId: string,
+  versionId: string,
+  sha256: string,
+): string {
+  assertSafeIdentity(tenant, spaceId, versionId);
+  if (!/^[0-9a-f]{64}$/.test(sha256)) throw new Error("publication artifact object address is unsafe");
+  return `publications/${tenant}/${spaceId}/${versionId}/objects/${sha256}`;
+}
 
-/** Marker address for one immutable tenant+space+version bundle. */
-export function publicationArtifactBundleKeyV1(
+/**
+ * The largest index review admission and readers accept. An index row costs about 200 bytes, so this
+ * admits tens of thousands of files whatever their size.
+ */
+export const PUBLICATION_ARTIFACT_INDEX_MAX_BYTES = 16 * 1024 * 1024;
+
+/** Index (marker) address for one immutable tenant+space+version artifact. */
+export function publicationArtifactIndexKeyV1(
   tenant: string,
   spaceId: string,
   versionId: string,
 ): string {
-  if (!PUBLICATION_ARTIFACT_IDENTIFIER_RE.test(tenant) ||
-    !PUBLICATION_ARTIFACT_IDENTIFIER_RE.test(spaceId) ||
-    !PUBLICATION_ARTIFACT_VERSION_RE.test(versionId)) {
-    throw new Error("publication artifact identity is unsafe");
+  assertSafeIdentity(tenant, spaceId, versionId);
+  return `publications/${tenant}/${spaceId}/${versionId}/index.json`;
+}
+
+/**
+ * Every object one bundle stores, in write order: one per distinct file content (addressed by
+ * sha256), then its index. The single definition of the stored layout, shared by the writer and
+ * every reader's test fixtures.
+ */
+export async function publicationArtifactObjectsV1(
+  bundle: PublicationArtifactBundleV1,
+): Promise<Array<{ key: string; bytes: Uint8Array }>> {
+  const index = await publicationArtifactIndexV1(bundle);
+  const objects = new Map<string, Uint8Array>();
+  for (const file of bundle.files) {
+    const bytes = publicationArtifactFileBytesV1(file);
+    if (!bytes) throw new Error("publication bundle contained malformed file bytes");
+    const key = publicationArtifactObjectKeyV1(bundle.tenant, bundle.spaceId, bundle.versionId, await sha256Hex(bytes));
+    if (!objects.has(key)) objects.set(key, bytes);
+  }
+  return [...[...objects].map(([key, bytes]) => ({ key, bytes })), {
+    key: publicationArtifactIndexKeyV1(bundle.tenant, bundle.spaceId, bundle.versionId),
+    bytes: new TextEncoder().encode(JSON.stringify(index)),
+  }];
+}
+
+/** One stored object, as R2 and test stores both expose it. */
+export interface PublicationArtifactStoredObjectV1 {
+  text(): Promise<string>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  size?: number;
+}
+
+/** Provider-neutral object-store read surface. */
+export interface PublicationArtifactReadBucketV1 {
+  get(key: string): Promise<PublicationArtifactStoredObjectV1 | null>;
+}
+
+export type PublicationArtifactIndexReadV1 =
+  | { ok: true; index: PublicationArtifactIndexV1 }
+  | { ok: false; code: "publication_artifact_marker_missing" | "publication_artifact_marker_malformed" |
+    "publication_artifact_source_unavailable" };
+
+/** Read and admit the index for `expected`. Never reads a file's bytes. */
+export async function readPublicationArtifactIndexV1(
+  bucket: PublicationArtifactReadBucketV1,
+  expected: PublicationArtifactBundleExpectationV1,
+): Promise<PublicationArtifactIndexReadV1> {
+  let stored: PublicationArtifactStoredObjectV1 | null;
+  try {
+    stored = await bucket.get(publicationArtifactIndexKeyV1(expected.tenant, expected.spaceId, expected.versionId));
+  } catch {
+    return { ok: false, code: "publication_artifact_source_unavailable" };
+  }
+  if (!stored) return { ok: false, code: "publication_artifact_marker_missing" };
+  if (typeof stored.size === "number" && stored.size > PUBLICATION_ARTIFACT_INDEX_MAX_BYTES) {
+    return { ok: false, code: "publication_artifact_marker_malformed" };
+  }
+  let value: unknown;
+  try {
+    const text = await stored.text();
+    if (new TextEncoder().encode(text).byteLength > PUBLICATION_ARTIFACT_INDEX_MAX_BYTES) {
+      return { ok: false, code: "publication_artifact_marker_malformed" };
+    }
+    value = JSON.parse(text);
+  } catch {
+    return { ok: false, code: "publication_artifact_marker_malformed" };
+  }
+  const checked = await validatePublicationArtifactIndexV1(value, expected);
+  return checked.ok ? { ok: true, index: checked.value } : { ok: false, code: "publication_artifact_marker_malformed" };
+}
+
+export type PublicationArtifactFileReadV1 =
+  | { ok: true; bytes: Uint8Array }
+  | { ok: false; code: "publication_artifact_file_missing" | "publication_artifact_file_mismatch" |
+    "publication_artifact_source_unavailable" };
+
+/** Fetch one indexed file's bytes and prove them against its row (length and sha256). */
+export async function readPublicationArtifactFileV1(
+  bucket: PublicationArtifactReadBucketV1,
+  index: Pick<PublicationArtifactIndexV1, "tenant" | "spaceId" | "versionId">,
+  file: PublicationArtifactIndexFileV1,
+): Promise<PublicationArtifactFileReadV1> {
+  let stored: PublicationArtifactStoredObjectV1 | null;
+  try {
+    stored = await bucket.get(publicationArtifactObjectKeyV1(index.tenant, index.spaceId, index.versionId, file.sha256));
+  } catch {
+    return { ok: false, code: "publication_artifact_source_unavailable" };
+  }
+  if (!stored) return { ok: false, code: "publication_artifact_file_missing" };
+  let bytes: Uint8Array;
+  try {
+    bytes = new Uint8Array(await stored.arrayBuffer());
+  } catch {
+    return { ok: false, code: "publication_artifact_file_missing" };
+  }
+  if (bytes.byteLength !== file.byteSize || await sha256Hex(bytes) !== file.sha256) {
+    return { ok: false, code: "publication_artifact_file_mismatch" };
+  }
+  return { ok: true, bytes };
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (let offset = 0; offset < bytes.byteLength; offset += 0x8000) {
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + 0x8000));
+  }
+  return btoa(binary);
+}
+
+/**
+ * The files of an admitted index that `include` selects, with their proven bytes, as a bundle whose
+ * `files` list is exactly that selection. Off-path readers (review evidence, original staging) select
+ * the text they scan and the originals they stage instead of loading a whole site into memory.
+ * Null when any selected file is missing or does not match its row.
+ */
+export async function readPublicationArtifactSelectionV1(
+  bucket: PublicationArtifactReadBucketV1,
+  index: PublicationArtifactIndexV1,
+  include: (file: PublicationArtifactIndexFileV1) => boolean,
+): Promise<PublicationArtifactBundleV1 | null> {
+  const files: PublicationArtifactFileV1[] = [];
+  for (const row of index.files) {
+    if (!include(row)) continue;
+    const read = await readPublicationArtifactFileV1(bucket, index, row);
+    if (!read.ok) return null;
+    const content = row.encoding === "utf8"
+      ? new TextDecoder("utf-8", { fatal: true }).decode(read.bytes)
+      : bytesToBase64(read.bytes);
+    files.push({ lane: row.lane, path: row.path, encoding: row.encoding, content, byteSize: row.byteSize });
   }
-  return `publications/${tenant}/${spaceId}/${versionId}/bundle.json`;
+  const { files: _rows, ...identity } = index;
+  return { ...identity, files };
 }

package/packages/public-runtime/src/publication-content-redirects.ts

@@ -0,0 +1,61 @@
+/**
+ * A publication space's content-declared redirects on the Worker: `content/redirects.json` and every
+ * `content/<collection>/redirects.json` of the version the request opened, matched by the redirect
+ * contract's own resolver. The same set the aggregate writes to the CloudFront redirect plane, so
+ * the two CDNs answer one request the same way.
+ *
+ * Only the space that OWNS the request path is consulted (its artifact is the one the request
+ * opened), which is the composition's precedence rule: a mount owns every path under it. Only the
+ * root space may send a visitor to another origin; a mounted space's off-site entry never applies.
+ */
+import {
+  buildRedirectSet,
+  COLLECTION_REDIRECTS_PATH,
+  declaredRedirectsFromContent,
+  redirectResolver,
+} from "./publication-redirects.mjs";
+import type { OpenPublicationArtifactV1 } from "./publication-reader.js";
+
+type Resolve = (path: string) => string | null;
+
+/** Resolvers per immutable version; a version's declarations never change once stored. */
+const resolvers = new Map<string, Resolve>();
+const MAX_CACHED_VERSIONS = 64;
+
+function compile(artifact: OpenPublicationArtifactV1): Resolve {
+  const entries: { path: string; json: unknown }[] = [];
+  const read = (relative: string) => {
+    const text = artifact.readContent(relative);
+    if (text !== null) entries.push({ path: `content/${relative}`, json: JSON.parse(text) as unknown });
+  };
+  try {
+    read("redirects.json");
+    for (const relative of artifact.listContentPaths()) {
+      if (COLLECTION_REDIRECTS_PATH.test(`content/${relative}`)) read(relative);
+    }
+    const set = buildRedirectSet(declaredRedirectsFromContent(entries));
+    // A declaration composition would refuse publishes nothing here either.
+    if (!set.ok) return () => null;
+    const isRoot = artifact.selection.manifest.routes.canonicalMount === "/";
+    const resolve = redirectResolver(set.redirects.filter(({ to }) => isRoot || to.startsWith("/")));
+    return (path) => resolve(path)?.location ?? null;
+  } catch {
+    return () => null;
+  }
+}
+
+/** Where `requestPath` redirects within its own space's declarations, or null. */
+export function publicationContentRedirectLocationV1(
+  artifact: OpenPublicationArtifactV1,
+  requestPath: string,
+): string | null {
+  const { tenant, spaceId, versionId, artifactDigest } = artifact.index;
+  const key = `${tenant}\0${spaceId}\0${versionId}\0${artifactDigest}`;
+  let resolve = resolvers.get(key);
+  if (!resolve) {
+    resolve = compile(artifact);
+    if (resolvers.size >= MAX_CACHED_VERSIONS) resolvers.delete(resolvers.keys().next().value!);
+    resolvers.set(key, resolve);
+  }
+  return resolve(requestPath);
+}

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

@@ -1,12 +1,13 @@
 import {
-  publicationArtifactBundleKeyV1,
-  publicationArtifactFileBytesV1,
-  publicationArtifactKeyV1,
-  validatePublicationArtifactBundleV1,
-  type PublicationArtifactBundleV1,
-  type PublicationArtifactFileV1,
+  readPublicationArtifactFileV1,
+  readPublicationArtifactIndexV1,
+  type PublicationArtifactIndexFileV1,
+  type PublicationArtifactIndexV1,
+  type PublicationArtifactReadBucketV1,
+  type PublicationArtifactStoredObjectV1,
 } from "./publication-artifact.js";
 import {
+  resolvePublicationRoutePlanV1,
   selectPublicationRouteVersionV1,
   type PublicationRouteFailureCodeV1,
   type PublicationRoutePlanV1,
@@ -18,15 +19,10 @@ import type {
 } from "./publication-version.js";
 import type { RouteTierIndexV1 } from "./route-tier.js";
 
-export interface PublicationStoredObjectV1 {
-  text(): Promise<string>;
-  arrayBuffer(): Promise<ArrayBuffer>;
-}
+export type PublicationStoredObjectV1 = PublicationArtifactStoredObjectV1;
 
 /** Provider-neutral object-store read surface; R2 and test stores both satisfy it. */
-export interface PublicationArtifactBucketV1 {
-  get(key: string): Promise<PublicationStoredObjectV1 | null>;
-}
+export type PublicationArtifactBucketV1 = PublicationArtifactReadBucketV1;
 
 export type PublicationArtifactOpenFailureCodeV1 =
   | PublicationRouteFailureCodeV1
@@ -38,13 +34,17 @@ export type PublicationArtifactOpenFailureCodeV1 =
 
 export interface OpenPublicationArtifactV1 {
   selection: SelectedPublicationRouteV1;
-  bundle: PublicationArtifactBundleV1;
+  /** The admitted file index of the selected version. */
+  index: PublicationArtifactIndexV1;
   /** Read a UTF-8 artifact relative to the selected space's content/ root. */
   readContent(relativePath: string): string | null;
   /** List paths relative to the selected space's content/ root. */
   listContentPaths(prefix?: string): string[];
-  /** Read bytes relative to this space's declared asset namespace. */
-  readAsset(relativePath: string): Uint8Array | null;
+  /**
+   * Read bytes relative to this space's declared asset namespace. Fetched on demand and proven
+   * against the index, so opening a version never reads its assets.
+   */
+  readAsset(relativePath: string): Promise<Uint8Array | null>;
 }
 
 export type OpenPublicationArtifactResultV1 =
@@ -57,11 +57,6 @@ function safeRelativePath(path: string, allowEmpty = false): boolean {
     path.split("/").every((part) => !!part && part !== "." && part !== "..");
 }
 
-function equalBytes(left: Uint8Array, right: Uint8Array): boolean {
-  return left.byteLength === right.byteLength &&
-    left.every((value, index) => value === right[index]);
-}
-
 /**
  * Open exactly one selected publication version and validate every physical
  * object before rendering from it. A route/state/provenance/object failure is
@@ -91,25 +86,7 @@ async function openSelectedPublicationArtifactV1(
   bucket: PublicationArtifactBucketV1,
 ): Promise<OpenPublicationArtifactResultV1> {
   const { manifest, publicationVersion } = selection;
-  let marker: PublicationStoredObjectV1 | null;
-  try {
-    marker = await bucket.get(publicationArtifactBundleKeyV1(
-      manifest.tenant,
-      manifest.id,
-      publicationVersion.versionId,
-    ));
-  } catch {
-    return { ok: false, code: "publication_artifact_source_unavailable" };
-  }
-  if (!marker) return { ok: false, code: "publication_artifact_marker_missing" };
-
-  let markerValue: unknown;
-  try {
-    markerValue = JSON.parse(await marker.text());
-  } catch {
-    return { ok: false, code: "publication_artifact_marker_malformed" };
-  }
-  const checked = await validatePublicationArtifactBundleV1(markerValue, {
+  const admitted = await readPublicationArtifactIndexV1(bucket, {
     tenant: manifest.tenant,
     spaceId: manifest.id,
     versionId: publicationVersion.versionId,
@@ -121,55 +98,38 @@ async function openSelectedPublicationArtifactV1(
     assetNamespace: manifest.assets.namespace,
     assetAccess: manifest.assets.access,
   });
-  if (!checked.ok) return { ok: false, code: "publication_artifact_marker_malformed" };
+  if (!admitted.ok) return { ok: false, code: admitted.code };
+  const { index } = admitted;
 
-  const physical = new Map<string, Uint8Array>();
-  for (const file of checked.value.files) {
-    const expected = publicationArtifactFileBytesV1(file);
-    if (!expected) return { ok: false, code: "publication_artifact_marker_malformed" };
-    let stored: PublicationStoredObjectV1 | null;
-    try {
-      stored = await bucket.get(publicationArtifactKeyV1(
-        manifest.tenant,
-        manifest.id,
-        publicationVersion.versionId,
-        file.lane,
-        file.path,
-      ));
-    } catch {
-      return { ok: false, code: "publication_artifact_source_unavailable" };
-    }
-    if (!stored) return { ok: false, code: "publication_artifact_file_missing" };
-    let actual: Uint8Array;
+  // The renderer reads content synchronously, so the content lane is loaded and proven up front.
+  // Assets are not: a page never needs every image its space carries.
+  const contentFiles = index.files.filter(
+    (file): file is PublicationArtifactIndexFileV1 & { encoding: "utf8" } =>
+      file.lane === "content" && file.encoding === "utf8" && file.path.startsWith("content/"),
+  );
+  const content = new Map<string, string>();
+  for (const file of contentFiles) {
+    const read = await readPublicationArtifactFileV1(bucket, index, file);
+    if (!read.ok) return { ok: false, code: read.code };
     try {
-      actual = new Uint8Array(await stored.arrayBuffer());
+      content.set(file.path, new TextDecoder("utf-8", { fatal: true }).decode(read.bytes));
     } catch {
-      return { ok: false, code: "publication_artifact_file_missing" };
-    }
-    if (!equalBytes(actual, expected)) {
       return { ok: false, code: "publication_artifact_file_mismatch" };
     }
-    physical.set(`${file.lane}\0${file.path}`, actual);
   }
-
-  const contentFiles = checked.value.files.filter(
-    (file): file is PublicationArtifactFileV1 & { encoding: "utf8" } =>
-      file.lane === "content" && file.encoding === "utf8" && file.path.startsWith("content/"),
-  );
   const assetLane = manifest.assets.access === "public" ? "public-asset" : "authorized-asset";
   const assetPrefix = `${manifest.assets.namespace}/`;
+  const assets = new Map(index.files
+    .filter((file) => file.lane === assetLane && file.path.startsWith(assetPrefix))
+    .map((file) => [file.path.slice(assetPrefix.length), file]));
   return {
     ok: true,
     value: {
       selection,
-      bundle: checked.value,
+      index,
       readContent(relativePath) {
         if (!safeRelativePath(relativePath)) return null;
-        const path = `content/${relativePath}`;
-        const file = contentFiles.find((candidate) => candidate.path === path);
-        if (!file) return null;
-        const bytes = physical.get(`content\0${path}`);
-        return bytes ? new TextDecoder().decode(bytes) : null;
+        return content.get(`content/${relativePath}`) ?? null;
       },
       listContentPaths(prefix = "") {
         if (!safeRelativePath(prefix.replace(/\/$/, ""), true)) return [];
@@ -178,10 +138,62 @@ async function openSelectedPublicationArtifactV1(
           .filter((path) => path.startsWith(prefix))
           .sort();
       },
-      readAsset(relativePath) {
+      async readAsset(relativePath) {
         if (!safeRelativePath(relativePath)) return null;
-        return physical.get(`${assetLane}\0${assetPrefix}${relativePath}`) ?? null;
+        const file = assets.get(relativePath);
+        if (!file) return null;
+        const read = await readPublicationArtifactFileV1(bucket, index, file);
+        return read.ok ? read.bytes : null;
       },
     },
   };
 }
+
+export type PublicationRootAssetReadV1 =
+  | { status: "legacy-root" }
+  | { status: "found"; bytes: Uint8Array; sha256: string }
+  | { status: "absent" };
+
+/**
+ * One file of the ROOT space's public asset lane, by its path under the namespace — what a
+ * whole-site tenant serves at `/tenants/<tenant>/<path>`. Reads the selected version's index and
+ * that one object, never the content lane. `legacy-root` when the tenant's root is not a public
+ * publication space this channel selected, so the legacy asset pointer still answers.
+ */
+export async function readPublicationRootAssetV1(input: {
+  index: RouteTierIndexV1;
+  state: PublicationVersionStateV1;
+  channel: PublicationChannelV1;
+  bucket: PublicationArtifactBucketV1;
+  relativePath: string;
+}): Promise<PublicationRootAssetReadV1> {
+  const plan = resolvePublicationRoutePlanV1(input.index, "/");
+  if (plan.action !== "render" || plan.manifest.routes.canonicalMount !== "/" ||
+    plan.manifest.visibility !== "public" || plan.manifest.assets.access !== "public") {
+    return { status: "legacy-root" };
+  }
+  const selected = selectPublicationRouteVersionV1(input.index, "/", plan, input.state, input.channel);
+  if (!selected.ok) {
+    return selected.code === "publication_channel_unselected" ? { status: "legacy-root" } : { status: "absent" };
+  }
+  if (!safeRelativePath(input.relativePath)) return { status: "absent" };
+  const { manifest, publicationVersion } = selected.value;
+  const admitted = await readPublicationArtifactIndexV1(input.bucket, {
+    tenant: manifest.tenant,
+    spaceId: manifest.id,
+    versionId: publicationVersion.versionId,
+    sourceSha: publicationVersion.source.commitSha,
+    artifactDigest: publicationVersion.artifactDigest,
+    forge: manifest.source.forge,
+    repo: manifest.source.repo,
+    visibility: manifest.visibility,
+    assetNamespace: manifest.assets.namespace,
+    assetAccess: manifest.assets.access,
+  });
+  if (!admitted.ok) return { status: "absent" };
+  const path = `${manifest.assets.namespace}/${input.relativePath}`;
+  const row = admitted.index.files.find((file) => file.lane === "public-asset" && file.path === path);
+  if (!row) return { status: "absent" };
+  const read = await readPublicationArtifactFileV1(input.bucket, admitted.index, row);
+  return read.ok ? { status: "found", bytes: read.bytes, sha256: row.sha256 } : { status: "absent" };
+}

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

@@ -12,6 +12,7 @@ import {
   publicationCollectionBaseV1,
   type PublicationCollectionV1,
 } from "./blog-visibility.mjs";
+import { normalizeRedirectPath } from "./publication-redirects.mjs";
 import {
   ANNOTATION_KEYS,
   type ContractResult,
@@ -113,6 +114,14 @@ export interface PublicationSpaceAliasV1 {
   to?: string;
 }
 
+/** One exact path the root space sends to another origin. */
+export interface PublicationSpaceExternalRedirectV1 {
+  /** Normalized exact request path (`/my-account/`), never a rule. */
+  from: string;
+  /** Absolute `https:` destination without credentials, query, or fragment. */
+  to: string;
+}
+
 export interface PublicationSpaceManifestV1 {
   version: typeof PUBLICATION_SPACE_MANIFEST_VERSION;
   id: string;
@@ -127,6 +136,11 @@ export interface PublicationSpaceManifestV1 {
      * it by `publicationCollectionPathV1`.
      */
     collections?: Partial<Record<PublicationCollectionV1, string>>;
+    /**
+     * Exact paths sent off the site, as a whole-site publish does. Only the ROOT space may declare
+     * them: a mounted space owns only its mount, and its redirects stay on the tenant's origin.
+     */
+    externalRedirects?: PublicationSpaceExternalRedirectV1[];
   };
   visibility: PublicationSpaceVisibilityV1;
   authorization:
@@ -500,6 +514,62 @@ function validateCollections(
   return Object.keys(out).length ? out : undefined;
 }
 
+function isExternalDestination(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" && !url.username && !url.password && !url.search && !url.hash &&
+      url.toString().replace(/\/$/, url.pathname === "/" ? "/" : "") === value;
+  } catch {
+    return false;
+  }
+}
+
+/** The root space's exact off-site redirects; a mounted space declaring any is refused. */
+function validateExternalRedirects(
+  raw: unknown,
+  canonicalMount: string | undefined,
+  v: Violations,
+  path: string,
+): PublicationSpaceExternalRedirectV1[] | undefined {
+  if (raw === undefined) return undefined;
+  if (!Array.isArray(raw)) {
+    v.add(path, "type", "Expected externalRedirects to be an array.");
+    return undefined;
+  }
+  if (canonicalMount !== undefined && canonicalMount !== "/") {
+    v.add(path, "publication_external_redirect_on_mount",
+      "Only the root space may redirect off the site; a mounted space owns only its mount.");
+  }
+  const out: PublicationSpaceExternalRedirectV1[] = [];
+  const seen = new Set<string>();
+  raw.forEach((item, index) => {
+    const at = `${path}[${index}]`;
+    const entry = reqObject(item, v, at);
+    if (!entry) return;
+    rejectPublicationUnknownKeys(entry, ["from", "to"], v, at);
+    const from = reqString(entry, "from", v, at);
+    const to = reqString(entry, "to", v, at);
+    if (from !== undefined && (normalizeRedirectPath(from) !== from || from === "/")) {
+      v.add(`${at}.from`, "publication_external_redirect_source",
+        "An off-site redirect source is one normalized exact path, never the site root or a rule.");
+      return;
+    }
+    if (to !== undefined && !isExternalDestination(to)) {
+      v.add(`${at}.to`, "publication_external_redirect_target",
+        "An off-site redirect target is an absolute https URL without credentials, query, or fragment.");
+      return;
+    }
+    if (from === undefined || to === undefined) return;
+    if (seen.has(from)) {
+      v.add(`${at}.from`, "publication_external_redirect_duplicate", "An off-site redirect source is declared twice.");
+      return;
+    }
+    seen.add(from);
+    out.push({ from, to });
+  });
+  return out.length ? out.sort((left, right) => left.from < right.from ? -1 : left.from > right.from ? 1 : 0) : undefined;
+}
+
 /** Validate, close, and normalize one serialized publication-space manifest. */
 export function validatePublicationSpaceManifestV1(raw: unknown): ContractResult<PublicationSpaceManifestV1> {
   const v = new Violations();
@@ -519,8 +589,10 @@ export function validatePublicationSpaceManifestV1(raw: unknown): ContractResult
   let canonicalMount: string | undefined;
   let aliases: PublicationSpaceAliasV1[] | undefined;
   let collections: PublicationSpaceManifestV1["routes"]["collections"];
+  let externalRedirects: PublicationSpaceExternalRedirectV1[] | undefined;
   if (routes) {
-    rejectPublicationUnknownKeys(routes, ["canonicalMount", "aliases", "collections"], v, "routes");
+    rejectPublicationUnknownKeys(routes, ["canonicalMount", "aliases", "collections", "externalRedirects"], v,
+      "routes");
     const rawMount = reqString(routes, "canonicalMount", v, "routes");
     canonicalMount = rawMount
       ? append(v, "routes.canonicalMount", normalizePublicationPath(rawMount, { mode: "mount" }))
@@ -530,6 +602,8 @@ export function validatePublicationSpaceManifestV1(raw: unknown): ContractResult
     }
     aliases = validateAliases(routes["aliases"], canonicalMount, v, "routes.aliases");
     collections = validateCollections(routes["collections"], canonicalMount, v, "routes.collections");
+    externalRedirects = validateExternalRedirects(routes["externalRedirects"], canonicalMount, v,
+      "routes.externalRedirects");
   }
   const visibility = reqEnum<PublicationSpaceVisibilityV1>(root, "visibility", ["public", "internal"], v, "");
   const authorization = validateAuthorization(root["authorization"], v, "authorization");
@@ -581,6 +655,7 @@ export function validatePublicationSpaceManifestV1(raw: unknown): ContractResult
         canonicalMount,
         ...(aliases === undefined ? {} : { aliases }),
         ...(collections === undefined ? {} : { collections }),
+        ...(externalRedirects === undefined ? {} : { externalRedirects }),
       },
       visibility,
       authorization,