@tokenoftrust/storefront-runner 2.0.17 → 2.0.19

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

@@ -0,0 +1,853 @@
+/**
+ * Versioned publication-space contracts shared by tenant configuration,
+ * materialization, routing, and editorial control-plane callers.
+ *
+ * This module owns path normalization. Downstream callers must consume the
+ * normalized mounts emitted here rather than decode or canonicalize paths again.
+ */
+import type { TenantConfig } from "./tenant.js";
+import {
+  ANNOTATION_KEYS,
+  type ContractResult,
+  type ContractViolation,
+  Violations,
+  isPlainObject,
+  reqBool,
+  reqEnum,
+  reqLiteral,
+  reqObject,
+  reqString,
+} from "./integration/result.js";
+
+export const PUBLICATION_SPACE_MANIFEST_VERSION = 1 as const;
+export const PUBLICATION_SPACE_REF_VERSION = 1 as const;
+export const PUBLICATION_MOUNT_ENTRY_VERSION = 1 as const;
+
+/** URL paths are case-sensitive; Unicode is normalized to NFC before encoding. */
+export const PUBLICATION_SPACE_PATH_CASE_POLICY = "sensitive" as const;
+export const PUBLICATION_SPACE_UNICODE_POLICY = "nfc" as const;
+
+/** Platform-owned path segments that tenant publication mounts may not claim. */
+export const PUBLICATION_SPACE_RESERVED_MOUNTS = [
+  "/.well-known",
+  "/__evidence",
+  "/__preview",
+  "/_astro",
+  "/_style-guide",
+  "/admin",
+  "/api",
+  "/apps",
+  "/assets",
+  "/auth",
+  "/brand",
+  "/capabilities",
+  "/cockpit",
+  "/dashboard",
+  "/dev",
+  "/favicon.svg",
+  "/health",
+  "/js",
+  "/llms.txt",
+  "/platform",
+  "/preview",
+  "/products",
+  "/collections",
+  "/search",
+  "/saved",
+  "/robots.txt",
+  "/shared",
+  "/sitemap.xml",
+  "/style-guide",
+  "/tenants",
+] as const;
+
+export type PublicationSpaceForgeV1 = "gitea" | "github" | "fixture";
+export type PublicationSpaceVisibilityV1 = "public" | "internal";
+export type PublicationAliasBehaviorV1 = "render" | "redirect-308";
+
+export interface PublicationSpaceSourceV1 {
+  forge: PublicationSpaceForgeV1;
+  repo: string;
+  defaultBranch: string;
+}
+
+export interface PublicationSpaceAliasV1 {
+  from: string;
+  behavior: PublicationAliasBehaviorV1;
+  /** Required for redirects; render aliases target the owning canonical mount. */
+  to?: string;
+}
+
+export interface PublicationSpaceManifestV1 {
+  version: typeof PUBLICATION_SPACE_MANIFEST_VERSION;
+  id: string;
+  tenant: string;
+  source: PublicationSpaceSourceV1;
+  routes: {
+    canonicalMount: string;
+    aliases?: PublicationSpaceAliasV1[];
+  };
+  visibility: PublicationSpaceVisibilityV1;
+  authorization:
+    | { policy: "public" }
+    | { policy: "capability"; capability: "internal-content-reader" };
+  discovery: {
+    sitemap: boolean;
+    feeds: boolean;
+    publicSearch: boolean;
+    llms: boolean;
+  };
+  assets: {
+    namespace: string;
+    access: "public" | "authorized";
+  };
+  renderer: {
+    contractVersion: string;
+    themeContractVersion: string;
+  };
+}
+
+export interface PublicationSpaceRefV1 {
+  version: typeof PUBLICATION_SPACE_REF_VERSION;
+  tenant: string;
+  spaceId: string;
+}
+
+/** A normalized route-registry row. P1 can consume these without re-normalizing. */
+export interface NormalizedPublicationMountEntryV1 {
+  version: typeof PUBLICATION_MOUNT_ENTRY_VERSION;
+  tenant: string;
+  spaceId: string;
+  kind: "canonical" | "alias";
+  mount: string;
+  canonicalMount: string;
+  behavior: "render" | "redirect-308";
+  redirectTo?: string;
+}
+
+export interface PublicationPathNormalizationOptions {
+  /** Request paths discard query/fragment; manifest mounts reject them. */
+  mode?: "request" | "mount";
+}
+
+const IDENTIFIER_RE = /^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$/;
+const REPO_RE = /^[A-Za-z0-9](?:[A-Za-z0-9._/-]{0,254}[A-Za-z0-9])?$/;
+const BRANCH_RE = /^(?![-/.])(?!HEAD$)(?!.*\/\.)(?!.*(?:\.\.|@\{|\\|\s|~|\^|:|\?|\*|\[|\/\/))(?!.*(?:^|\/)[^/]*\.lock(?:\/|$))(?!.*[\/.]$)[A-Za-z0-9._/-]+$/;
+const CONTROL_RE = /[\u0000-\u001f\u007f]/;
+const ENCODED_SEPARATOR_RE = /%(?:2f|5c)/i;
+
+function rejectPublicationUnknownKeys(
+  obj: Record<string, unknown>,
+  allowed: readonly string[],
+  v: Violations,
+  path: string,
+): void {
+  const allowedKeys = new Set([...allowed, ...ANNOTATION_KEYS]);
+  if (Object.keys(obj).some((key) => !allowedKeys.has(key))) {
+    v.add(path || "(root)", "unknown_field", "Unexpected field in publication-space contract.");
+  }
+}
+
+function oneViolation(code: string, message: string): ContractResult<string> {
+  return { ok: false, violations: [{ path: "path", code, message }] };
+}
+
+function hasDangerousSecondDecode(segment: string): boolean {
+  if (!/%[0-9a-f]{2}/i.test(segment)) return false;
+  try {
+    const twice = decodeURIComponent(segment).normalize("NFC");
+    return (
+      twice === "." ||
+      twice === ".." ||
+      twice.includes("/") ||
+      twice.includes("\\") ||
+      CONTROL_RE.test(twice)
+    );
+  } catch {
+    return false;
+  }
+}
+
+function encodeCanonicalSegment(segment: string): string {
+  return encodeURIComponent(segment).replace(/%[0-9a-f]{2}/gi, (value) => value.toUpperCase());
+}
+
+/**
+ * Normalize a publication path exactly once.
+ *
+ * Rules: absolute path only; request query/fragment excluded; repeated and
+ * trailing slashes collapse; each segment is decoded once, NFC-normalized, and
+ * canonically percent-encoded; case is preserved; traversal, separators,
+ * controls, malformed encodings, and dangerous double encodings are rejected.
+ */
+export function normalizePublicationPath(
+  input: string,
+  options: PublicationPathNormalizationOptions = {},
+): ContractResult<string> {
+  if (typeof input !== "string" || input.length === 0) {
+    return oneViolation("publication_path_required", "Publication path must be a non-empty string.");
+  }
+  if (!input.startsWith("/")) {
+    return oneViolation("publication_path_absolute", "Publication path must start with '/'.");
+  }
+
+  const delimiter = input.search(/[?#]/);
+  if (options.mode === "mount" && delimiter !== -1) {
+    return oneViolation(
+      "publication_mount_query_fragment",
+      "Publication mounts cannot contain a query string or fragment.",
+    );
+  }
+  const path = delimiter === -1 ? input : input.slice(0, delimiter);
+  if (path.includes("\\")) {
+    return oneViolation("publication_path_backslash", "Backslashes are forbidden in publication paths.");
+  }
+  if (CONTROL_RE.test(path)) {
+    return oneViolation("publication_path_control", "Control characters are forbidden in publication paths.");
+  }
+
+  const normalizedSegments: string[] = [];
+  for (const rawSegment of path.split("/")) {
+    if (rawSegment.length === 0) continue;
+    if (ENCODED_SEPARATOR_RE.test(rawSegment)) {
+      return oneViolation(
+        "publication_path_encoded_separator",
+        "Encoded path separators are forbidden in publication paths.",
+      );
+    }
+    let decoded: string;
+    try {
+      decoded = decodeURIComponent(rawSegment).normalize("NFC");
+    } catch {
+      return oneViolation(
+        "publication_path_malformed_encoding",
+        "Publication path contains malformed percent encoding.",
+      );
+    }
+    if (decoded === "." || decoded === "..") {
+      return oneViolation(
+        "publication_path_traversal",
+        "Dot and dot-dot traversal segments are forbidden in publication paths.",
+      );
+    }
+    if (decoded.includes("/") || decoded.includes("\\")) {
+      return oneViolation(
+        "publication_path_encoded_separator",
+        "Encoded path separators are forbidden in publication paths.",
+      );
+    }
+    if (CONTROL_RE.test(decoded)) {
+      return oneViolation("publication_path_control", "Control characters are forbidden in publication paths.");
+    }
+    if (hasDangerousSecondDecode(decoded)) {
+      return oneViolation(
+        "publication_path_double_encoding",
+        "Publication path contains a double-encoded traversal or separator.",
+      );
+    }
+    try {
+      normalizedSegments.push(encodeCanonicalSegment(decoded));
+    } catch {
+      return oneViolation(
+        "publication_path_malformed_unicode",
+        "Publication path contains malformed Unicode.",
+      );
+    }
+  }
+
+  return { ok: true, value: normalizedSegments.length === 0 ? "/" : `/${normalizedSegments.join("/")}` };
+}
+
+/** Segment-boundary mount matching: /blog matches /blog/x but not /blogger. */
+export function publicationMountMatchesPath(mount: string, normalizedPath: string): boolean {
+  return mount === "/" || normalizedPath === mount || normalizedPath.startsWith(`${mount}/`);
+}
+
+function append(v: Violations, path: string, result: ContractResult<string>): string | undefined {
+  if (result.ok) return result.value;
+  for (const item of result.violations) {
+    v.add(path, item.code, item.message);
+  }
+  return undefined;
+}
+
+function validateIdentifier(value: string | undefined, v: Violations, path: string, label: string): string | undefined {
+  if (value !== undefined && !IDENTIFIER_RE.test(value)) {
+    v.add(path, "publication_identifier", `${label} must be a lowercase stable identifier.`);
+    return undefined;
+  }
+  return value;
+}
+
+function isReservedMount(mount: string): boolean {
+  return PUBLICATION_SPACE_RESERVED_MOUNTS.some((reserved) => publicationMountMatchesPath(reserved, mount));
+}
+
+function validateSource(raw: unknown, v: Violations, path: string): PublicationSpaceSourceV1 | undefined {
+  const source = reqObject(raw, v, path);
+  if (!source) return undefined;
+  rejectPublicationUnknownKeys(source, ["forge", "repo", "defaultBranch"], v, path);
+  const forge = reqEnum<PublicationSpaceForgeV1>(source, "forge", ["gitea", "github", "fixture"], v, path);
+  const repo = reqString(source, "repo", v, path);
+  const defaultBranch = reqString(source, "defaultBranch", v, path);
+  if (repo && (!REPO_RE.test(repo) || repo.includes("..") || repo.includes("//"))) {
+    v.add(`${path}.repo`, "publication_source_repo", "Source repo must be a stable repository name or owner/name.");
+  }
+  if (defaultBranch && (defaultBranch.length > 256 || !BRANCH_RE.test(defaultBranch))) {
+    v.add(`${path}.defaultBranch`, "publication_source_branch", "Default branch is not a safe git ref name.");
+  }
+  if (!forge || !repo || !defaultBranch) return undefined;
+  return { forge, repo, defaultBranch };
+}
+
+function validateAliases(
+  raw: unknown,
+  canonicalMount: string | undefined,
+  v: Violations,
+  path: string,
+): PublicationSpaceAliasV1[] | undefined {
+  if (raw === undefined) return undefined;
+  if (!Array.isArray(raw)) {
+    v.add(path, "type", "Expected aliases to be an array.");
+    return undefined;
+  }
+  const aliases: PublicationSpaceAliasV1[] = [];
+  raw.forEach((entry, index) => {
+    const itemPath = `${path}[${index}]`;
+    const alias = reqObject(entry, v, itemPath);
+    if (!alias) return;
+    rejectPublicationUnknownKeys(alias, ["from", "behavior", "to"], v, itemPath);
+    const rawFrom = reqString(alias, "from", v, itemPath);
+    const behavior = reqEnum<PublicationAliasBehaviorV1>(
+      alias,
+      "behavior",
+      ["render", "redirect-308"],
+      v,
+      itemPath,
+    );
+    const from = rawFrom
+      ? append(v, `${itemPath}.from`, normalizePublicationPath(rawFrom, { mode: "mount" }))
+      : undefined;
+    const rawTo = typeof alias["to"] === "string" ? alias["to"] : undefined;
+    if ("to" in alias && rawTo === undefined) {
+      v.add(`${itemPath}.to`, "type", "Alias target must be a non-empty string.");
+    }
+    const to = rawTo
+      ? append(v, `${itemPath}.to`, normalizePublicationPath(rawTo, { mode: "mount" }))
+      : undefined;
+    if (from === "/") {
+      v.add(`${itemPath}.from`, "publication_root_alias", "The root mount cannot be an alias.");
+    }
+    if (from && isReservedMount(from)) {
+      v.add(`${itemPath}.from`, "publication_reserved_mount", "Alias mount is platform-reserved.");
+    }
+    if (behavior === "redirect-308" && !to) {
+      v.add(`${itemPath}.to`, "publication_alias_target_required", "A redirect-308 alias requires a target.");
+    }
+    if (behavior === "render" && "to" in alias) {
+      v.add(`${itemPath}.to`, "publication_render_alias_target", "A render alias targets its canonical mount and cannot set 'to'.");
+    }
+    if (from && canonicalMount && from === canonicalMount) {
+      v.add(`${itemPath}.from`, "publication_route_conflict", "Alias mount duplicates its canonical mount.");
+    }
+    if (from && behavior) aliases.push(to ? { from, behavior, to } : { from, behavior });
+  });
+  return aliases;
+}
+
+function validateAuthorization(
+  raw: unknown,
+  v: Violations,
+  path: string,
+): PublicationSpaceManifestV1["authorization"] | undefined {
+  const auth = reqObject(raw, v, path);
+  if (!auth) return undefined;
+  const policy = reqEnum<"public" | "capability">(auth, "policy", ["public", "capability"], v, path);
+  if (policy === "public") {
+    rejectPublicationUnknownKeys(auth, ["policy"], v, path);
+    return { policy: "public" };
+  }
+  rejectPublicationUnknownKeys(auth, ["policy", "capability"], v, path);
+  const capability = reqEnum<"internal-content-reader">(
+    auth,
+    "capability",
+    ["internal-content-reader"],
+    v,
+    path,
+  );
+  return capability ? { policy: "capability", capability } : undefined;
+}
+
+function validateDiscovery(
+  raw: unknown,
+  v: Violations,
+  path: string,
+): PublicationSpaceManifestV1["discovery"] | undefined {
+  const discovery = reqObject(raw, v, path);
+  if (!discovery) return undefined;
+  rejectPublicationUnknownKeys(discovery, ["sitemap", "feeds", "publicSearch", "llms"], v, path);
+  const sitemap = reqBool(discovery, "sitemap", v, path);
+  const feeds = reqBool(discovery, "feeds", v, path);
+  const publicSearch = reqBool(discovery, "publicSearch", v, path);
+  const llms = reqBool(discovery, "llms", v, path);
+  if ([sitemap, feeds, publicSearch, llms].some((value) => value === undefined)) return undefined;
+  return { sitemap: sitemap!, feeds: feeds!, publicSearch: publicSearch!, llms: llms! };
+}
+
+function validateAssets(
+  raw: unknown,
+  v: Violations,
+  path: string,
+): PublicationSpaceManifestV1["assets"] | undefined {
+  const assets = reqObject(raw, v, path);
+  if (!assets) return undefined;
+  rejectPublicationUnknownKeys(assets, ["namespace", "access"], v, path);
+  const namespace = validateIdentifier(reqString(assets, "namespace", v, path), v, `${path}.namespace`, "Asset namespace");
+  const access = reqEnum<"public" | "authorized">(assets, "access", ["public", "authorized"], v, path);
+  return namespace && access ? { namespace, access } : undefined;
+}
+
+function validateRenderer(
+  raw: unknown,
+  v: Violations,
+  path: string,
+): PublicationSpaceManifestV1["renderer"] | undefined {
+  const renderer = reqObject(raw, v, path);
+  if (!renderer) return undefined;
+  rejectPublicationUnknownKeys(renderer, ["contractVersion", "themeContractVersion"], v, path);
+  const contractVersion = reqString(renderer, "contractVersion", v, path);
+  const themeContractVersion = reqString(renderer, "themeContractVersion", v, path);
+  return contractVersion && themeContractVersion ? { contractVersion, themeContractVersion } : undefined;
+}
+
+/** Validate, close, and normalize one serialized publication-space manifest. */
+export function validatePublicationSpaceManifestV1(raw: unknown): ContractResult<PublicationSpaceManifestV1> {
+  const v = new Violations();
+  const root = reqObject(raw, v, "");
+  if (!root) return { ok: false, violations: v.items };
+  rejectPublicationUnknownKeys(
+    root,
+    ["version", "id", "tenant", "source", "routes", "visibility", "authorization", "discovery", "assets", "renderer"],
+    v,
+    "",
+  );
+  reqLiteral(root, "version", PUBLICATION_SPACE_MANIFEST_VERSION, v, "");
+  const id = validateIdentifier(reqString(root, "id", v, ""), v, "id", "Publication-space id");
+  const tenant = validateIdentifier(reqString(root, "tenant", v, ""), v, "tenant", "Tenant");
+  const source = validateSource(root["source"], v, "source");
+  const routes = reqObject(root["routes"], v, "routes");
+  let canonicalMount: string | undefined;
+  let aliases: PublicationSpaceAliasV1[] | undefined;
+  if (routes) {
+    rejectPublicationUnknownKeys(routes, ["canonicalMount", "aliases"], v, "routes");
+    const rawMount = reqString(routes, "canonicalMount", v, "routes");
+    canonicalMount = rawMount
+      ? append(v, "routes.canonicalMount", normalizePublicationPath(rawMount, { mode: "mount" }))
+      : undefined;
+    if (canonicalMount && canonicalMount !== "/" && isReservedMount(canonicalMount)) {
+      v.add("routes.canonicalMount", "publication_reserved_mount", "Canonical mount is platform-reserved.");
+    }
+    aliases = validateAliases(routes["aliases"], canonicalMount, v, "routes.aliases");
+  }
+  const visibility = reqEnum<PublicationSpaceVisibilityV1>(root, "visibility", ["public", "internal"], v, "");
+  const authorization = validateAuthorization(root["authorization"], v, "authorization");
+  const discovery = validateDiscovery(root["discovery"], v, "discovery");
+  const assets = validateAssets(root["assets"], v, "assets");
+  const renderer = validateRenderer(root["renderer"], v, "renderer");
+
+  if (visibility && authorization) {
+    const matches =
+      (visibility === "public" && authorization.policy === "public") ||
+      (visibility === "internal" && authorization.policy === "capability");
+    if (!matches) {
+      v.add(
+        "authorization.policy",
+        "publication_visibility_authorization_mismatch",
+        "Publication visibility does not match its authorization policy.",
+      );
+    }
+  }
+  if (visibility === "internal" && discovery && Object.values(discovery).some(Boolean)) {
+    v.add(
+      "discovery",
+      "publication_internal_discovery",
+      "Internal publication spaces must be disabled on every public discovery surface.",
+    );
+  }
+  if (visibility && assets) {
+    const expected = visibility === "public" ? "public" : "authorized";
+    if (assets.access !== expected) {
+      v.add(
+        "assets.access",
+        "publication_visibility_asset_mismatch",
+        "Publication visibility does not match its asset access policy.",
+      );
+    }
+  }
+
+  if (!v.ok || !id || !tenant || !source || !routes || !canonicalMount || !visibility || !authorization || !discovery || !assets || !renderer) {
+    return { ok: false, violations: v.items };
+  }
+  return {
+    ok: true,
+    value: {
+      version: PUBLICATION_SPACE_MANIFEST_VERSION,
+      id,
+      tenant,
+      source,
+      routes: aliases === undefined ? { canonicalMount } : { canonicalMount, aliases },
+      visibility,
+      authorization,
+      discovery,
+      assets,
+      renderer,
+    },
+  };
+}
+
+/** Validate one closed publication-space reference. */
+export function validatePublicationSpaceRefV1(raw: unknown): ContractResult<PublicationSpaceRefV1> {
+  const v = new Violations();
+  const root = reqObject(raw, v, "");
+  if (!root) return { ok: false, violations: v.items };
+  rejectPublicationUnknownKeys(root, ["version", "tenant", "spaceId"], v, "");
+  reqLiteral(root, "version", PUBLICATION_SPACE_REF_VERSION, v, "");
+  const tenant = validateIdentifier(reqString(root, "tenant", v, ""), v, "tenant", "Tenant");
+  const spaceId = validateIdentifier(reqString(root, "spaceId", v, ""), v, "spaceId", "Publication-space id");
+  if (!v.ok || !tenant || !spaceId) return { ok: false, violations: v.items };
+  return { ok: true, value: { version: PUBLICATION_SPACE_REF_VERSION, tenant, spaceId } };
+}
+
+function normalizedMountField(
+  obj: Record<string, unknown>,
+  key: string,
+  v: Violations,
+  path: string,
+): string | undefined {
+  const raw = reqString(obj, key, v, path);
+  if (!raw) return undefined;
+  const normalized = normalizePublicationPath(raw, { mode: "mount" });
+  const value = append(v, `${path ? `${path}.` : ""}${key}`, normalized);
+  if (value && value !== raw) {
+    v.add(
+      `${path ? `${path}.` : ""}${key}`,
+      "publication_mount_not_normalized",
+      "Normalized mount entries must store the canonical path form.",
+    );
+  }
+  return value;
+}
+
+/** Validate a closed, already-normalized mount-registry row. */
+export function validateNormalizedPublicationMountEntryV1(
+  raw: unknown,
+): ContractResult<NormalizedPublicationMountEntryV1> {
+  const v = new Violations();
+  const root = reqObject(raw, v, "");
+  if (!root) return { ok: false, violations: v.items };
+  rejectPublicationUnknownKeys(
+    root,
+    ["version", "tenant", "spaceId", "kind", "mount", "canonicalMount", "behavior", "redirectTo"],
+    v,
+    "",
+  );
+  reqLiteral(root, "version", PUBLICATION_MOUNT_ENTRY_VERSION, v, "");
+  const tenant = validateIdentifier(reqString(root, "tenant", v, ""), v, "tenant", "Tenant");
+  const spaceId = validateIdentifier(reqString(root, "spaceId", v, ""), v, "spaceId", "Publication-space id");
+  const kind = reqEnum<"canonical" | "alias">(root, "kind", ["canonical", "alias"], v, "");
+  const mount = normalizedMountField(root, "mount", v, "");
+  const canonicalMount = normalizedMountField(root, "canonicalMount", v, "");
+  const behavior = reqEnum<"render" | "redirect-308">(
+    root,
+    "behavior",
+    ["render", "redirect-308"],
+    v,
+    "",
+  );
+  const redirectTo = "redirectTo" in root
+    ? normalizedMountField(root, "redirectTo", v, "")
+    : undefined;
+
+  if (kind === "canonical") {
+    if (mount && canonicalMount && mount !== canonicalMount) {
+      v.add("mount", "publication_canonical_mount_mismatch", "A canonical row's mount must equal canonicalMount.");
+    }
+    if (behavior && behavior !== "render") {
+      v.add("behavior", "publication_canonical_behavior", "Canonical rows must use render behavior.");
+    }
+  }
+  if (kind === "alias" && mount === "/") {
+    v.add("mount", "publication_root_alias", "The root mount cannot be an alias.");
+  }
+  if (kind === "alias" && mount && canonicalMount && mount === canonicalMount) {
+    v.add("mount", "publication_route_conflict", "Alias mount duplicates its canonical mount.");
+  }
+  if (behavior === "redirect-308" && !redirectTo) {
+    v.add("redirectTo", "publication_alias_target_required", "A redirect-308 row requires redirectTo.");
+  }
+  if (behavior === "render" && "redirectTo" in root) {
+    v.add("redirectTo", "publication_render_alias_target", "A render row cannot set redirectTo.");
+  }
+  if (mount && mount !== "/" && isReservedMount(mount)) {
+    v.add("mount", "publication_reserved_mount", "Mount is platform-reserved.");
+  }
+  if (canonicalMount && canonicalMount !== mount && canonicalMount !== "/" && isReservedMount(canonicalMount)) {
+    v.add("canonicalMount", "publication_reserved_mount", "Canonical mount is platform-reserved.");
+  }
+
+  if (!v.ok || !tenant || !spaceId || !kind || !mount || !canonicalMount || !behavior) {
+    return { ok: false, violations: v.items };
+  }
+  return {
+    ok: true,
+    value: {
+      version: PUBLICATION_MOUNT_ENTRY_VERSION,
+      tenant,
+      spaceId,
+      kind,
+      mount,
+      canonicalMount,
+      behavior,
+      ...(redirectTo ? { redirectTo } : {}),
+    },
+  };
+}
+
+function addRegistryViolation(
+  violations: ContractViolation[],
+  path: string,
+  code: string,
+  message: string,
+): void {
+  violations.push({ path, code, message });
+}
+
+function detectAliasLoops(entries: readonly NormalizedPublicationMountEntryV1[], violations: ContractViolation[]): void {
+  const byTenant = new Map<string, NormalizedPublicationMountEntryV1[]>();
+  for (const entry of entries) {
+    const tenantEntries = byTenant.get(entry.tenant) ?? [];
+    tenantEntries.push(entry);
+    byTenant.set(entry.tenant, tenantEntries);
+  }
+  for (const tenantEntries of byTenant.values()) {
+    tenantEntries.sort((left, right) => right.mount.length - left.mount.length || left.mount.localeCompare(right.mount));
+    for (const start of tenantEntries) {
+      if (start.behavior !== "redirect-308" || !start.redirectTo) continue;
+      const seen = new Set<string>([start.mount]);
+      let target: string | undefined = start.redirectTo;
+      while (target) {
+        const matched = tenantEntries.find((entry) => publicationMountMatchesPath(entry.mount, target!));
+        if (!matched || matched.behavior !== "redirect-308" || !matched.redirectTo) break;
+        if (seen.has(matched.mount)) {
+        addRegistryViolation(
+          violations,
+          "mounts",
+          "publication_alias_loop",
+          "Alias redirect loop detected.",
+        );
+        break;
+        }
+        seen.add(matched.mount);
+        target = matched.redirectTo;
+      }
+    }
+  }
+}
+
+/**
+ * Validate a tenant mount registry and emit deterministic longest-prefix rows.
+ * Duplicate route ownership, duplicate ids/namespaces, missing roots, and alias
+ * loops fail before any registry can be activated.
+ */
+export function validatePublicationSpaceRegistryV1(
+  raw: readonly unknown[],
+): ContractResult<NormalizedPublicationMountEntryV1[]> {
+  if (!Array.isArray(raw)) {
+    return {
+      ok: false,
+      violations: [{ path: "spaces", code: "type", message: "Publication-space registry must be an array." }],
+    };
+  }
+  const manifests: PublicationSpaceManifestV1[] = [];
+  const violations: ContractViolation[] = [];
+  raw.forEach((item, index) => {
+    const result = validatePublicationSpaceManifestV1(item);
+    if (result.ok) manifests.push(result.value);
+    else for (const violation of result.violations) violations.push({ ...violation, path: `spaces[${index}].${violation.path}` });
+  });
+  if (violations.length > 0) return { ok: false, violations };
+
+  const ids = new Map<string, number>();
+  const namespaces = new Map<string, number>();
+  const routes = new Map<string, number>();
+  const roots = new Map<string, { count: number; firstIndex: number }>();
+  const entries: NormalizedPublicationMountEntryV1[] = [];
+
+  manifests.forEach((manifest, index) => {
+    const idKey = `${manifest.tenant}\u0000${manifest.id}`;
+    const previousId = ids.get(idKey);
+    if (previousId !== undefined) {
+      addRegistryViolation(
+        violations,
+        `spaces[${index}].id`,
+        "publication_duplicate_space_id",
+        `Publication-space id duplicates the earlier entry at spaces[${previousId}] for the same tenant.`,
+      );
+    } else ids.set(idKey, index);
+
+    const namespaceKey = `${manifest.tenant}\u0000${manifest.assets.namespace}`;
+    const previousNamespace = namespaces.get(namespaceKey);
+    if (previousNamespace !== undefined) {
+      addRegistryViolation(
+        violations,
+        `spaces[${index}].assets.namespace`,
+        "publication_asset_namespace_reuse",
+        `Asset namespace is already owned by the earlier entry at spaces[${previousNamespace}] for the same tenant.`,
+      );
+    } else namespaces.set(namespaceKey, index);
+
+    const tenantRoot = roots.get(manifest.tenant) ?? { count: 0, firstIndex: index };
+    if (manifest.routes.canonicalMount === "/") tenantRoot.count += 1;
+    roots.set(manifest.tenant, tenantRoot);
+    const addEntry = (entry: NormalizedPublicationMountEntryV1): void => {
+      const routeKey = `${entry.tenant}\u0000${entry.mount}`;
+      const previousRoute = routes.get(routeKey);
+      if (previousRoute !== undefined) {
+        addRegistryViolation(
+          violations,
+          `spaces[${index}].routes`,
+          "publication_route_conflict",
+          `Normalized route is already owned by the earlier entry at spaces[${previousRoute}] for the same tenant.`,
+        );
+      } else routes.set(routeKey, index);
+      entries.push(entry);
+    };
+
+    addEntry({
+      version: PUBLICATION_MOUNT_ENTRY_VERSION,
+      tenant: manifest.tenant,
+      spaceId: manifest.id,
+      kind: "canonical",
+      mount: manifest.routes.canonicalMount,
+      canonicalMount: manifest.routes.canonicalMount,
+      behavior: "render",
+    });
+    for (const alias of manifest.routes.aliases ?? []) {
+      addEntry({
+        version: PUBLICATION_MOUNT_ENTRY_VERSION,
+        tenant: manifest.tenant,
+        spaceId: manifest.id,
+        kind: "alias",
+        mount: alias.from,
+        canonicalMount: manifest.routes.canonicalMount,
+        behavior: alias.behavior,
+        ...(alias.to ? { redirectTo: alias.to } : {}),
+      });
+    }
+  });
+
+  for (const tenant of new Set(manifests.map((manifest) => manifest.tenant))) {
+    const tenantRoot = roots.get(tenant)!;
+    if (tenantRoot.count !== 1) {
+      addRegistryViolation(
+        violations,
+        `spaces[${tenantRoot.firstIndex}].routes.canonicalMount`,
+        "publication_root_mount_count",
+        "Each tenant must have exactly one canonical root mount.",
+      );
+    }
+  }
+  detectAliasLoops(entries, violations);
+  if (violations.length > 0) return { ok: false, violations };
+
+  entries.sort(
+    (left, right) =>
+      left.tenant.localeCompare(right.tenant) ||
+      right.mount.length - left.mount.length ||
+      left.mount.localeCompare(right.mount) ||
+      left.kind.localeCompare(right.kind),
+  );
+  return { ok: true, value: entries };
+}
+
+/** Parse JSON and return the same stable violation model as object validation. */
+export function parsePublicationSpaceManifestV1Json(json: string): ContractResult<PublicationSpaceManifestV1> {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(json);
+  } catch {
+    return {
+      ok: false,
+      violations: [{ path: "(root)", code: "publication_invalid_json", message: "Publication-space manifest is not valid JSON." }],
+    };
+  }
+  return validatePublicationSpaceManifestV1(raw);
+}
+
+/** Serialize a validated manifest in canonical property order. */
+export function serializePublicationSpaceManifestV1(manifest: PublicationSpaceManifestV1): string {
+  const result = validatePublicationSpaceManifestV1(manifest);
+  if (!result.ok) {
+    throw new Error(`Invalid PublicationSpaceManifestV1: ${result.violations.map((item) => item.code).join(", ")}`);
+  }
+  return `${JSON.stringify(result.value, null, 2)}\n`;
+}
+
+export interface ResolvedTenantPublicationSpacesV1 {
+  manifests: PublicationSpaceManifestV1[];
+  refs: PublicationSpaceRefV1[];
+  mounts: NormalizedPublicationMountEntryV1[];
+}
+
+/** Resolve a tenant's explicit publication spaces through one validated path. */
+export function resolveTenantPublicationSpacesV1(
+  tenant: Pick<TenantConfig, "tenant_id" | "publicationSpaces">,
+): ContractResult<ResolvedTenantPublicationSpacesV1> {
+  if (!Array.isArray(tenant.publicationSpaces) || tenant.publicationSpaces.length === 0) {
+    return {
+      ok: false,
+      violations: [{
+        path: "publicationSpaces",
+        code: "publication_spaces_required",
+        message: "Publication spaces are required before publication routing can resolve.",
+      }],
+    };
+  }
+  const rawManifests = [...tenant.publicationSpaces];
+  const registry = validatePublicationSpaceRegistryV1(rawManifests);
+  if (!registry.ok) return registry;
+
+  const manifests: PublicationSpaceManifestV1[] = [];
+  const violations: ContractViolation[] = [];
+  rawManifests.forEach((raw, index) => {
+    const parsed = validatePublicationSpaceManifestV1(raw);
+    if (!parsed.ok) {
+      for (const violation of parsed.violations) {
+        violations.push({ ...violation, path: `spaces[${index}].${violation.path}` });
+      }
+      return;
+    }
+    if (parsed.value.tenant !== tenant.tenant_id) {
+      violations.push({
+        path: `spaces[${index}].tenant`,
+        code: "publication_tenant_mismatch",
+        message: "Publication-space tenant does not match the containing tenant.",
+      });
+      return;
+    }
+    manifests.push(parsed.value);
+  });
+  if (violations.length > 0) return { ok: false, violations };
+  return {
+    ok: true,
+    value: {
+      manifests,
+      refs: manifests.map((manifest) => ({
+        version: PUBLICATION_SPACE_REF_VERSION,
+        tenant: manifest.tenant,
+        spaceId: manifest.id,
+      })),
+      mounts: registry.value,
+    },
+  };
+}