@tokenoftrust/storefront-runner 2.2.84 → 2.2.86

package/agency-kit/tools/lib/redirect-declaration.mjs

@@ -0,0 +1,627 @@
+// @ts-check
+// The pure core that turns a tenant's DECLARED redirects into a substrate-neutral redirect set
+// the publish pipeline can emit.
+//
+// This module is the one copy of the redirect contract: the declaration format, the edge budget
+// and the reference matcher. It lives in the agency kit so a store developer's `redirect-map.mjs`
+// validates a map exactly as a publish will, with nothing but the kit installed; the platform
+// imports this file rather than carrying a copy. It imports nothing.
+//
+// A tenant's public site is served CDN -> static object (ADR 0013), so a redirect cannot be a
+// request-time decision in the Worker: it must exist in the published artifact. Both substrates
+// express it the same way — a precomputed set consulted by the single permitted edge function —
+// so the set below is substrate-neutral and the adapters only serialize it.
+//
+// Redirects are DECLARED, never derived from a tenant id. Three declaration sources normalize into
+// the one `redirect-308` contract `PublicationSpaceAliasV1` already defines:
+//   - publication-space `routes.aliases` entries whose behavior is `redirect-308`;
+//   - a content collection's `redirects.json` (old slug -> new slug), which becomes
+//     `/<collection>/<old>/` -> `/<collection>/<new>/`;
+//   - the tenant-wide `content/redirects.json` (relative path -> relative path or an explicit
+//     HTTPS destination), for legacy URLs that belong to no single collection.
+// Adding a tenant is a declaration, not a code change.
+//
+// Two kinds of entry:
+//   - EXACT: `/old/` -> `/new/` (or an explicit `https:` URL). Matches one path.
+//   - RULE:  `/blogs/news/*` -> `/blog/*`. Matches every path under the directory prefix, the
+//     directory itself included. A `*` at the end of the target receives the rest of the request
+//     path; a target without `*` sends the whole family to one page. A rule's target is always a
+//     same-origin path, and `*` is only ever the trailing segment of either side.
+// Precedence at the edge: an exact entry beats any rule; among rules the longest prefix wins. The
+// query string is forwarded to a same-origin target and dropped for an external one.
+// `resolveRedirect` below is the reference matcher; the Cloudflare static plane
+// (`packages/public-runtime/src/static-bundle.ts`) and the CloudFront function
+// (`scripts/publish/cloudfront/live-pointer-rewrite.mjs`) implement the same semantics in their own
+// runtimes and are held to it by the shared cases in
+// `packages/public-runtime/tests/fixtures/redirect-match-cases.json`.
+//
+// 308 rather than 301 throughout: both pass ranking signal, and 308 additionally preserves the
+// request method, so a redirected non-GET is not silently rewritten. The declared alias contract
+// already specifies 308; collection renames join it rather than introducing a second status.
+//
+// Fails closed. An ambiguous declaration (one `from`, two targets), a cycle, a rule whose target
+// another rule would redirect again, or a set that exceeds the substrate's ceiling REFUSES rather
+// than emitting a partial set — a redirect that silently does not exist is the failure this
+// mechanism exists to prevent.
+
+/** The status every materialized redirect carries. */
+export const REDIRECT_STATUS = 308;
+
+/** Bump only when the meaning of a whole-site delivery manifest changes without changing its values. */
+export const WHOLE_SITE_DELIVERY_CONTRACT = "whole-site-delivery-v1";
+
+/**
+ * CloudFront KeyValueStore quotas (AWS CloudFront quota table, read 2026-10-06). The CloudFront
+ * plane stores each entry as its own key, `redirect:<namespace>:<from>` -> `<to>`, so these — not
+ * the function's 10 KB code limit — bound the set. The Cloudflare plane reads the same set from
+ * the bundle manifest in R2, which has no tighter ceiling.
+ */
+export const KVS_STORE_LIMIT_BYTES = 5 * 1024 * 1024;
+export const KVS_KEY_LIMIT_BYTES = 512;
+export const KVS_VALUE_LIMIT_BYTES = 1024;
+/** Room kept for the store's own keys (`live`, `preview`, `promotions`). */
+export const KVS_RESERVED_BYTES = 64 * 1024;
+/**
+ * Bytes available to one redirect set. A publish stages the new namespace before it prunes the
+ * old one, so two complete sets share the store for the length of a flip.
+ */
+export const REDIRECT_MAP_BUDGET_BYTES = Math.floor((KVS_STORE_LIMIT_BYTES - KVS_RESERVED_BYTES) / 2);
+/** `redirect:` + a sha256 hex namespace + `:` — the key bytes every entry carries before its path. */
+export const REDIRECT_KEY_OVERHEAD_BYTES = "redirect:".length + 64 + 1;
+/**
+ * The CloudFront function reads one key per distinct rule depth on a request no exact entry
+ * matched, so the number of distinct depths is the per-request cost of rules. Bounded here.
+ */
+export const REDIRECT_RULE_MAX_DEPTHS = 8;
+
+const encoder = new TextEncoder();
+/** @param {string} value */
+const byteLength = (value) => encoder.encode(value).byteLength;
+
+/**
+ * @typedef {Object} DeclaredRedirect
+ * @property {string} from    root-absolute request path, or a `/<dir>/*` rule
+ * @property {string} to      root-absolute destination path (a rule may end in `/*`)
+ * @property {string} source  which declaration produced it, for the report
+ */
+
+/**
+ * @typedef {Object} RedirectSet
+ * @property {boolean} ok
+ * @property {{from: string, to: string}[]} redirects  normalized, deduped, chain-collapsed
+ * @property {string[]} violations  why it refused; empty when ok
+ * @property {number} bytes         storage the set occupies at the edge (KVS keys + values)
+ * @property {number} budget        bytes available to the set
+ * @property {number} rules         how many entries are `/*` rules
+ */
+
+/**
+ * Normalize a declared path to the form the edge function compares against: root-absolute, no
+ * query or fragment, with a trailing slash unless the last segment names a file.
+ * Returns null when the value cannot be a same-origin request path.
+ * @param {string} raw
+ * @returns {string | null}
+ */
+export function normalizeRedirectPath(raw) {
+  if (typeof raw !== "string") return null;
+  const trimmed = raw.trim();
+  if (!trimmed.startsWith("/")) return null;
+  // Protocol-relative (`//host/...`) would leave the origin.
+  if (trimmed.startsWith("//")) return null;
+  const withoutSuffix = trimmed.split("?")[0].split("#")[0];
+  if (withoutSuffix.includes("..") || withoutSuffix.includes("\\")) return null;
+  const collapsed = withoutSuffix.replace(/\/{2,}/g, "/");
+  if (collapsed === "/") return "/";
+  // The last NON-EMPTY segment: a trailing slash otherwise hides the filename from this test.
+  const segments = collapsed.split("/").filter(Boolean);
+  const last = segments[segments.length - 1] ?? "";
+  const namesFile = last.includes(".");
+  if (namesFile) return collapsed.replace(/\/$/, "");
+  return collapsed.endsWith("/") ? collapsed : `${collapsed}/`;
+}
+
+/** Is this normalized entry a `/<dir>/*` rule rather than an exact path? */
+export function isRedirectRule(/** @type {string} */ from) {
+  return typeof from === "string" && from.endsWith("/*");
+}
+
+/**
+ * The directory a rule covers: `/blogs/news/*` -> `/blogs/news/`. Null unless `raw` is a
+ * root-absolute directory followed by exactly one trailing `*`.
+ * @param {string} raw
+ * @returns {string | null}
+ */
+export function ruleDirectory(raw) {
+  if (typeof raw !== "string") return null;
+  const trimmed = raw.trim();
+  if (!trimmed.endsWith("/*") || trimmed.indexOf("*") !== trimmed.length - 1) return null;
+  const dir = trimmed.slice(0, -1);
+  if (!dir.startsWith("/") || dir.startsWith("//")) return null;
+  if (/[?#\\]/.test(dir) || dir.split("/").includes("..")) return null;
+  return dir.replace(/\/{2,}/g, "/");
+}
+
+/**
+ * Normalize a declared SOURCE: an exact path, or a `/<dir>/*` rule. A rule over the whole site
+ * (`/*`) is refused — it would shadow every page, which is a domain move, not a redirect.
+ * @param {string} raw
+ * @returns {string | null}
+ */
+export function normalizeRedirectSource(raw) {
+  if (typeof raw !== "string") return null;
+  if (!raw.includes("*")) return normalizeRedirectPath(raw);
+  const dir = ruleDirectory(raw);
+  if (dir === null || dir === "/") return null;
+  return `${dir}*`;
+}
+
+/**
+ * Normalize a same-origin path or a deliberately external HTTPS destination.
+ *
+ * A source is always same-origin; a TARGET may leave the origin, but only when the declaration
+ * says so in full: `https:` only, no credentials, no query, no fragment. Anything else — including
+ * every shape that merely looks absolute — is not a usable destination and refuses.
+ * @param {string} raw
+ * @returns {string | null}
+ */
+function normalizeRedirectDestination(/** @type {string} */ raw) {
+  if (typeof raw !== "string" || raw.includes("*")) return null;
+  const sameOrigin = normalizeRedirectPath(raw);
+  if (sameOrigin !== null) return sameOrigin;
+  try {
+    const url = new URL(raw);
+    if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) {
+      return null;
+    }
+    return url.toString().replace(/\/$/, url.pathname === "/" ? "/" : "");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A rule's target: a same-origin path, or a same-origin directory ending in `*` that receives the
+ * rest of the request path. Never off-origin: a captured remainder must never pick a host.
+ * @param {string} raw
+ * @returns {string | null}
+ */
+function normalizeRuleTarget(raw) {
+  if (typeof raw !== "string") return null;
+  if (!raw.includes("*")) return normalizeRedirectPath(raw);
+  const dir = ruleDirectory(raw);
+  return dir === null ? null : `${dir}*`;
+}
+
+/**
+ * The path form both edges compare a request against: a directory request gains its trailing
+ * slash, a file request is left alone.
+ * @param {string} pathname
+ * @returns {string}
+ */
+export function redirectRequestPath(pathname) {
+  if (pathname === "/") return pathname;
+  const last = pathname.split("/").pop() ?? "";
+  if (last.includes(".")) return pathname;
+  return pathname.endsWith("/") ? pathname : `${pathname}/`;
+}
+
+/**
+ * Where a rule sends a request whose path continues `capture` past the rule's directory. Null
+ * when the result would not be a same-origin path — a capture such as `/evil.example` under a
+ * root target would otherwise become `//evil.example`.
+ * @param {string} to
+ * @param {string} capture
+ * @returns {string | null}
+ */
+export function ruleLocation(to, capture) {
+  const location = to.endsWith("/*") ? `${to.slice(0, -1)}${capture}` : to;
+  return location.startsWith("/") && !location.startsWith("//") && !location.includes("\\")
+    ? location
+    : null;
+}
+
+/**
+ * The reference matcher: which entry answers `pathname`, and where it sends it.
+ * Exact entries are compared against the request as sent and in its trailing-slash form; a rule
+ * matches when the trailing-slash form starts with its directory, and the longest directory wins.
+ * @param {readonly {from: string, to: string}[]} redirects
+ * @param {string} pathname  the request path, without query
+ * @returns {{from: string, to: string, location: string} | null}
+ */
+export function resolveRedirect(redirects, pathname) {
+  const path = redirectRequestPath(pathname);
+  /** @type {{from: string, to: string} | null} */
+  let rule = null;
+  for (const entry of redirects ?? []) {
+    if (isRedirectRule(entry.from)) {
+      const dir = entry.from.slice(0, -1);
+      if (path.startsWith(dir) && (rule === null || dir.length > rule.from.length - 1)) rule = entry;
+    } else if (entry.from === pathname || entry.from === path) {
+      return { from: entry.from, to: entry.to, location: entry.to };
+    }
+  }
+  if (rule === null) return null;
+  const location = ruleLocation(rule.to, path.slice(rule.from.length - 1));
+  return location === null ? null : { from: rule.from, to: rule.to, location };
+}
+
+/**
+ * The distinct directory depths of a set's rules, deepest first: `/blogs/news/*` is depth 2.
+ * The CloudFront function probes exactly these prefixes, so it reads nothing for a set without
+ * rules and one key per depth for a set with them.
+ * @param {readonly {from: string}[]} redirects
+ * @returns {number[]}
+ */
+export function redirectRuleDepths(redirects) {
+  const depths = new Set();
+  for (const { from } of redirects ?? []) {
+    if (isRedirectRule(from)) depths.add(from.split("/").filter(Boolean).length - 1);
+  }
+  return [...depths].sort((a, b) => b - a);
+}
+
+/**
+ * Turn a content collection's `redirects.json` (old slug -> new slug) into declared redirects
+ * under that collection's route prefix.
+ * @param {string} collection  e.g. "blog"
+ * @param {Record<string, unknown>} rows
+ * @returns {DeclaredRedirect[]}
+ */
+export function redirectsFromCollection(collection, rows) {
+  if (!rows || typeof rows !== "object") return [];
+  /** @type {DeclaredRedirect[]} */
+  const out = [];
+  for (const [oldSlug, newSlug] of Object.entries(rows)) {
+    if (typeof newSlug !== "string" || !oldSlug || !newSlug) continue;
+    out.push({
+      from: `/${collection}/${oldSlug}/`,
+      to: `/${collection}/${newSlug}/`,
+      source: `content/${collection}/redirects.json`,
+    });
+  }
+  return out;
+}
+
+/**
+ * Turn the tenant-wide `content/redirects.json` map into root-relative declarations.
+ * Its keys and same-origin values are repository paths without a leading slash; an
+ * explicit HTTPS destination remains absolute and is validated by `buildRedirectSet`.
+ * A key ending in `/*` declares a rule (`"blogs/news/*": "blog/*"`).
+ * @param {Record<string, unknown>} rows
+ * @returns {DeclaredRedirect[]}
+ */
+export function redirectsFromSiteMap(rows) {
+  if (!rows || typeof rows !== "object" || Array.isArray(rows)) {
+    throw new TypeError(
+      "content/redirects.json must be an object mapping relative paths to destinations",
+    );
+  }
+  /** @type {DeclaredRedirect[]} */
+  const out = [];
+  for (const [from, rawTo] of Object.entries(rows)) {
+    if (
+      !from || from.startsWith("/") || typeof rawTo !== "string" || !rawTo || rawTo.startsWith("/")
+    ) {
+      throw new TypeError(
+        "content/redirects.json keys and same-origin destinations must be non-empty paths without a leading slash",
+      );
+    }
+    const rootedFrom = `/${from}`;
+    const isExternal = /^[A-Za-z][A-Za-z0-9+.-]*:/.test(rawTo);
+    const rootedTo = isExternal ? rawTo : `/${rawTo}`;
+    const rule = rootedFrom.includes("*");
+    out.push({
+      from: normalizeRedirectSource(rootedFrom) ?? rootedFrom,
+      to: isExternal ? rawTo : (rule ? normalizeRuleTarget(rootedTo) : normalizeRedirectPath(rootedTo)) ?? rootedTo,
+      source: SITE_REDIRECTS_PATH,
+    });
+  }
+  return out;
+}
+
+/**
+ * A content collection's redirect declaration, as it appears in a composed bundle's file list.
+ * `content/blog/redirects.json` declares redirects for the `blog` collection.
+ */
+export const COLLECTION_REDIRECTS_PATH = /^content\/([A-Za-z0-9][A-Za-z0-9_-]*)\/redirects\.json$/;
+
+/** The tenant-wide redirect declaration, for legacy URLs that belong to no single collection. */
+export const SITE_REDIRECTS_PATH = "content/redirects.json";
+
+/**
+ * Does this composed file declare redirects the composition lifts into `routes.aliases`?
+ * @param {string} path
+ * @returns {boolean}
+ */
+export function isRedirectDeclarationPath(path) {
+  return path === SITE_REDIRECTS_PATH || COLLECTION_REDIRECTS_PATH.test(path ?? "");
+}
+
+/**
+ * Declared redirects for every content collection present in a composed revision.
+ *
+ * Reads the COMPOSED files rather than a working tree, so the redirects are bound to the same
+ * revision as the pages they point at — a rename and its redirect can never publish apart.
+ *
+ * @param {{path: string, json: unknown}[]} entries  composed files, already parsed
+ * @returns {DeclaredRedirect[]}
+ */
+export function declaredRedirectsFromContent(entries) {
+  /** @type {DeclaredRedirect[]} */
+  const out = [];
+  for (const entry of entries ?? []) {
+    if (entry?.path === SITE_REDIRECTS_PATH) {
+      out.push(...redirectsFromSiteMap(/** @type {Record<string, unknown>} */ (entry.json)));
+      continue;
+    }
+    const match = COLLECTION_REDIRECTS_PATH.exec(entry?.path ?? "");
+    if (!match) continue;
+    out.push(
+      ...redirectsFromCollection(
+        /** @type {string} */ (match[1]),
+        /** @type {Record<string, unknown>} */ (entry.json),
+      ),
+    );
+  }
+  return out;
+}
+
+/**
+ * Turn publication-space aliases into declared redirects. Only `redirect-308` aliases produce a
+ * redirect; a `render` alias is served, not redirected.
+ * @param {{from?: string, behavior?: string, to?: string}[]} aliases
+ * @param {string} [source]
+ * @returns {DeclaredRedirect[]}
+ */
+export function redirectsFromAliases(aliases, source = "publication-space routes.aliases") {
+  if (!Array.isArray(aliases)) return [];
+  /** @type {DeclaredRedirect[]} */
+  const out = [];
+  for (const alias of aliases) {
+    if (!alias || alias.behavior !== "redirect-308") continue;
+    if (typeof alias.from !== "string" || typeof alias.to !== "string") continue;
+    out.push({ from: alias.from, to: alias.to, source });
+  }
+  return out;
+}
+
+/**
+ * `resolveRedirect` over a whole set at once: exact entries in a map, rules in a list (a set has
+ * few rules and may have thousands of exact entries).
+ * @param {readonly {from: string, to: string}[]} entries
+ * @returns {(pathname: string) => {from: string, to: string, location: string} | null}
+ */
+export function redirectResolver(entries) {
+  /** @type {Map<string, string>} */
+  const exact = new Map();
+  /** @type {{from: string, to: string}[]} */
+  const rules = [];
+  for (const entry of entries ?? []) {
+    if (isRedirectRule(entry.from)) rules.push(entry);
+    else exact.set(entry.from, entry.to);
+  }
+  return (pathname) => {
+    for (const from of [pathname, redirectRequestPath(pathname)]) {
+      const to = exact.get(from);
+      if (to !== undefined) return { from, to, location: to };
+    }
+    return resolveRedirect(rules, pathname);
+  };
+}
+
+/**
+ * Follow a location through the declared set until nothing redirects it again, so a chain
+ * (a -> b, b -> c, or a -> a path a rule covers) resolves to one hop. A chain costs an extra round
+ * trip on every visit and dilutes the signal the redirect exists to preserve. A cycle is
+ * unresolvable and refuses.
+ * @param {(pathname: string) => string | null} resolve
+ * @param {string} from
+ * @param {string} to
+ * @returns {{to: string} | {cycle: string[]}}
+ */
+function collapseChain(resolve, from, to) {
+  const seen = [from];
+  let location = to;
+  while (location.startsWith("/")) {
+    const next = resolve(location);
+    if (next === null) break;
+    if (seen.includes(location)) return { cycle: [...seen, location] };
+    seen.push(location);
+    location = next;
+  }
+  if (seen.includes(location)) return { cycle: [...seen, location] };
+  return { to: location };
+}
+
+/**
+ * The KVS bytes one entry occupies on the CloudFront plane: its key and its value.
+ * @param {{from: string, to: string}} entry
+ */
+function entryBytes(entry) {
+  return { key: REDIRECT_KEY_OVERHEAD_BYTES + byteLength(entry.from), value: byteLength(entry.to) };
+}
+
+/**
+ * Build the substrate-neutral redirect set from every declared source.
+ * @param {DeclaredRedirect[]} declared
+ * @param {number} [budget]
+ * @returns {RedirectSet}
+ */
+export function buildRedirectSet(declared, budget = REDIRECT_MAP_BUDGET_BYTES) {
+  /** @type {string[]} */
+  const violations = [];
+  /** @type {Map<string, string>} */
+  const direct = new Map();
+  /** @type {Map<string, string>} */
+  const origin = new Map();
+
+  for (const entry of declared) {
+    const from = normalizeRedirectSource(entry.from);
+    if (from === null) {
+      violations.push(
+        `${entry.source}: redirect source is not a usable request path (a rule is "<dir>/*", never the whole site)`,
+      );
+      continue;
+    }
+    const rule = isRedirectRule(from);
+    const to = rule ? normalizeRuleTarget(entry.to) : normalizeRedirectDestination(entry.to);
+    if (to === null) {
+      violations.push(
+        rule
+          ? `${entry.source}: rule "${from}" needs a same-origin target path, optionally ending in "/*"`
+          : `${entry.source}: redirect target is not a usable destination path`,
+      );
+      continue;
+    }
+    if (from === to) {
+      violations.push(`${entry.source}: "${from}" redirects to itself`);
+      continue;
+    }
+    const existing = direct.get(from);
+    if (existing !== undefined && existing !== to) {
+      violations.push(
+        `"${from}" is declared twice with different targets ("${existing}" in ${origin.get(from)}, "${to}" in ${entry.source})`,
+      );
+      continue;
+    }
+    direct.set(from, to);
+    origin.set(from, entry.source);
+  }
+
+  const declaredEntries = [...direct].map(([from, to]) => ({ from, to }));
+  const rules = declaredEntries.filter((entry) => isRedirectRule(entry.from));
+
+  // A capturing rule's target directory must not sit under a rule's directory: every capture would
+  // then take a second hop, and a rule into its own directory never terminates. (A fixed target
+  // is collapsed through the rules below like any other chain.)
+  for (const rule of rules) {
+    if (!rule.to.endsWith("/*")) continue;
+    const target = rule.to.slice(0, -1);
+    for (const other of rules) {
+      if (target.startsWith(other.from.slice(0, -1))) {
+        violations.push(
+          `rule "${rule.from}" -> "${rule.to}" lands under rule "${other.from}", so every match would redirect twice`,
+        );
+      }
+    }
+  }
+
+  // An exact entry under a capturing rule's TARGET would make that capture a second hop
+  // (`/blogs/news/old/` -> `/blog/old/` -> `/blog/new/`). The composed one-hop entry is added
+  // beside it, so every request still takes exactly one redirect. A rule into the site root
+  // composes nothing: every exact entry is under `/`, and the paths it would add (`/pages/<any
+  // legacy path>/`) are not URLs anyone published.
+  /** @type {Map<string, string>} */
+  const composed = new Map();
+  for (const rule of rules) {
+    if (!rule.to.endsWith("/*") || rule.to === "/*") continue;
+    const target = rule.to.slice(0, -1);
+    const dir = rule.from.slice(0, -1);
+    for (const entry of declaredEntries) {
+      if (isRedirectRule(entry.from) || !entry.from.startsWith(target)) continue;
+      const from = `${dir}${entry.from.slice(target.length)}`;
+      if (!direct.has(from)) composed.set(from, entry.to);
+    }
+  }
+  const entries = [...declaredEntries, ...[...composed].map(([from, to]) => ({ from, to }))];
+  const resolver = redirectResolver(entries);
+  /** @param {string} pathname */
+  const resolve = (pathname) => resolver(pathname)?.location ?? null;
+
+  /** @type {{from: string, to: string}[]} */
+  const redirects = [];
+  for (const entry of [...entries].sort((a, b) => a.from.localeCompare(b.from))) {
+    if (isRedirectRule(entry.from) && entry.to.endsWith("/*")) {
+      redirects.push(entry);
+      continue;
+    }
+    const resolved = collapseChain(resolve, entry.from, entry.to);
+    if ("cycle" in resolved) {
+      violations.push(`redirect cycle: ${resolved.cycle.join(" -> ")}`);
+      continue;
+    }
+    redirects.push({ from: entry.from, to: resolved.to });
+  }
+
+  const depths = redirectRuleDepths(redirects);
+  if (depths.length > REDIRECT_RULE_MAX_DEPTHS) {
+    violations.push(
+      `rules span ${depths.length} directory depths; the edge reads one key per depth, so at most ${REDIRECT_RULE_MAX_DEPTHS} are allowed`,
+    );
+  }
+  let bytes = 0;
+  for (const entry of redirects) {
+    const size = entryBytes(entry);
+    if (size.key > KVS_KEY_LIMIT_BYTES || size.value > KVS_VALUE_LIMIT_BYTES) {
+      violations.push(
+        `"${entry.from}" is too long for one edge key-value entry (key ${size.key}/${KVS_KEY_LIMIT_BYTES} bytes, target ${size.value}/${KVS_VALUE_LIMIT_BYTES} bytes)`,
+      );
+    }
+    bytes += size.key + size.value;
+  }
+  if (bytes > budget) {
+    violations.push(
+      `redirect set is ${bytes} bytes, over the ${budget}-byte edge budget (${redirects.length} redirects) — collapse a URL family into one "<dir>/*" rule`,
+    );
+  }
+
+  return {
+    ok: violations.length === 0,
+    redirects,
+    violations,
+    bytes,
+    budget,
+    rules: redirects.filter((entry) => isRedirectRule(entry.from)).length,
+  };
+}
+
+/**
+ * The declared set as publication-space aliases — the shape `routes.aliases` already carries and
+ * `publicationRedirects()` (scripts/publish/lib/publication-space-release.mjs) already consumes on
+ * its way into the live pointer. Emitting this rather than a parallel structure is what keeps
+ * redirects ONE contract: the edge function, the pointer value, and the declaration all agree
+ * because there is only one of them.
+ *
+ * An alias is a mount: it redirects its path and everything under it, appending the remainder to
+ * the target. A capturing rule (`/x/*` -> `/y/*`) is exactly that mount (`/x` -> `/y`). A rule
+ * that sends a family to one page, or captures into the site root, has no mount form and throws.
+ *
+ * Returns an empty array when the set refused, so a caller that ignores `ok` cannot publish a
+ * half-built topology.
+ * @param {RedirectSet} set
+ * @returns {{from: string, behavior: "redirect-308", to: string}[]}
+ */
+export function aliasesFromRedirectSet(set) {
+  if (!set.ok) return [];
+  return set.redirects.map(({ from, to }) => {
+    if (!isRedirectRule(from)) {
+      return { from, behavior: /** @type {"redirect-308"} */ ("redirect-308"), to };
+    }
+    if (!to.endsWith("/*") || to === "/*") {
+      throw new TypeError(`rule "${from}" -> "${to}" has no publication-space alias form`);
+    }
+    return {
+      from: from.slice(0, -2),
+      behavior: /** @type {"redirect-308"} */ ("redirect-308"),
+      to: to.slice(0, -2),
+    };
+  });
+}
+
+/**
+ * @param {RedirectSet} set
+ * @returns {string}
+ */
+export function formatRedirectSetReport(set) {
+  const lines = [];
+  lines.push(
+    `== Redirect materialization == ${set.redirects.length} redirect(s) (${set.rules} rule(s)), ${set.bytes}/${set.budget} bytes`,
+  );
+  for (const violation of set.violations) lines.push(`  REFUSE: ${violation}`);
+  lines.push(
+    set.ok
+      ? `OK — every declared redirect materializes at ${REDIRECT_STATUS}.`
+      : `REFUSED — ${set.violations.length} violation(s); nothing emitted.`,
+  );
+  return lines.join("\n");
+}

package/apps/storefront/src/components/Seo.astro

@@ -23,6 +23,9 @@ interface Props {
   jsonLd?: JsonLd | JsonLd[];
   /** Alternate RSS/Atom feeds this page advertises (e.g. a collection's feed). */
   feeds?: { title: string; href: string }[];
+  /** A paginated collection's siblings — path-only (like `path`), joined to the
+   *  same canonical base. Absent fields emit no link (first/last page). */
+  pagination?: { prev?: string; next?: string };
   // --- B1.6 article SEO hardening (all additive/optional) ---
   /** Open Graph `article:*` meta; emitted only when `ogType === "article"`. */
   article?: ArticleMeta;
@@ -51,6 +54,7 @@ const {
   noindex = false,
   jsonLd,
   feeds = [],
+  pagination,
   article,
   imageAlt,
   imageWidth,
@@ -84,6 +88,10 @@ const articleMeta = articleSeoMetaTags({
 
 const graphs = jsonLd ? (Array.isArray(jsonLd) ? jsonLd : [jsonLd]) : [];
 const alternateLinks = withXDefault(alternates);
+const paginationLinks = [
+  ...(pagination?.prev ? [{ rel: "prev", href: new URL(pagination.prev, canonicalBase + "/").toString() }] : []),
+  ...(pagination?.next ? [{ rel: "next", href: new URL(pagination.next, canonicalBase + "/").toString() }] : []),
+];
 ---
 
 <title>{fullTitle}</title>
@@ -91,6 +99,10 @@ const alternateLinks = withXDefault(alternates);
 <link rel="canonical" href={canonical} />
 {noindex && <meta name="robots" content="noindex,nofollow" />}
 
+{
+  paginationLinks.map((l) => <link rel={l.rel} href={l.href} />)
+}
+
 {
   feeds.map((f) => (
     <link rel="alternate" type="application/rss+xml" title={f.title} href={f.href} />