@tokenoftrust/storefront-runner 2.0.17 → 2.0.18

package/packages/public-runtime/src/route-tier.ts

@@ -0,0 +1,257 @@
+/**
+ * The single authority for "what is this route, and what may serve it".
+ *
+ * One question, one answer: a request path resolves through the tenant's mount
+ * registry to a publication space, and that space's declared
+ * {visibility, authorization, discovery, assets.access} produces one ADR 0013
+ * route tier. ADR 0013's tier split and the mounted-publication-spaces
+ * public/internal boundary are the same boundary; every consumer reaches it
+ * here or not at all.
+ *
+ * Provider-neutral by construction: the tier is a property of the route and the
+ * tenant's declared config, never of which substrate serves it. Pure and
+ * synchronous — no request-time D1/KV/network reads.
+ *
+ * Contract: docs/architecture/decisions/0013-public-serving-contract.md
+ */
+import type { TenantConfig } from "./tenant.js";
+import type { ContractViolation } from "./integration/result.js";
+import {
+  PUBLICATION_SPACE_RESERVED_MOUNTS,
+  type NormalizedPublicationMountEntryV1,
+  type PublicationSpaceManifestV1,
+  type PublicationSpaceRefV1,
+  type PublicationSpaceVisibilityV1,
+  PUBLICATION_SPACE_REF_VERSION,
+  normalizePublicationPath,
+  publicationMountMatchesPath,
+  resolveTenantPublicationSpacesV1,
+} from "./publication-space.js";
+
+export const ROUTE_TIER_RESOLUTION_VERSION = 1 as const;
+
+/**
+ * The ADR 0013 tiers a route can resolve to from declared config.
+ *
+ * Tier 2 (client-hydrated) is deliberately absent: it is a Tier 0 shell plus
+ * authenticated client calls, so at the serving layer a Tier 2 page IS Tier 0.
+ */
+export type RouteTierV1 =
+  /** Identical bytes for every anonymous visitor; CDN -> content-addressed storage, no origin compute. */
+  | "tier-0-static"
+  /** A decision before delivery at the CDN edge — here, a declared 308 alias. No origin hop. */
+  | "tier-1-edge-decision"
+  /** Authorization-gated and per-session; a path-scoped behavior pointing at the Worker origin. */
+  | "tier-3-origin-compute";
+
+/** Where the answer came from — a tenant space, the platform, or nowhere. */
+export type RouteTierOriginV1 =
+  | "publication-space"
+  | "platform-reserved"
+  | "unresolved";
+
+export interface ResolvedRouteTierV1 {
+  version: typeof ROUTE_TIER_RESOLUTION_VERSION;
+  tenant: string;
+  /** The normalized path resolved; the raw input when normalization refused it. */
+  path: string;
+  tier: RouteTierV1;
+  origin: RouteTierOriginV1;
+  /** The one authorization question. True for every tier other than 0 and 1. */
+  requiresAuthorization: boolean;
+  /** The owning space; absent unless `origin` is `publication-space`. */
+  space?: PublicationSpaceRefV1;
+  /** The matched mount row; absent unless `origin` is `publication-space`. */
+  mount?: NormalizedPublicationMountEntryV1;
+  /** The 308 target, on a redirect alias only. */
+  redirectTo?: string;
+  visibility: PublicationSpaceVisibilityV1;
+  authorization: PublicationSpaceManifestV1["authorization"];
+  discovery: PublicationSpaceManifestV1["discovery"];
+  assets: { access: "public" | "authorized" };
+  /** Why the route resolved to no space; empty when `origin` is `publication-space`. */
+  violations: readonly ContractViolation[];
+}
+
+/**
+ * A tenant's compiled route-tier lookup: validated once, resolved per request.
+ *
+ * An index carrying violations holds no mounts, so every route resolves to the
+ * most restrictive tier — invalid publication-space config cannot open a route.
+ */
+export interface RouteTierIndexV1 {
+  version: typeof ROUTE_TIER_RESOLUTION_VERSION;
+  tenant: string;
+  /** Longest-prefix-first, as emitted by the mount registry. */
+  mounts: readonly NormalizedPublicationMountEntryV1[];
+  spaces: ReadonlyMap<string, PublicationSpaceManifestV1>;
+  violations: readonly ContractViolation[];
+}
+
+const RESTRICTED_AUTHORIZATION = {
+  policy: "capability",
+  capability: "internal-content-reader",
+} as const satisfies PublicationSpaceManifestV1["authorization"];
+
+const RESTRICTED_DISCOVERY = {
+  sitemap: false,
+  feeds: false,
+  publicSearch: false,
+  llms: false,
+} as const satisfies PublicationSpaceManifestV1["discovery"];
+
+function failClosed(
+  tenant: string,
+  path: string,
+  origin: RouteTierOriginV1,
+  violations: readonly ContractViolation[],
+): ResolvedRouteTierV1 {
+  return {
+    version: ROUTE_TIER_RESOLUTION_VERSION,
+    tenant,
+    path,
+    tier: "tier-3-origin-compute",
+    origin,
+    requiresAuthorization: true,
+    visibility: "internal",
+    authorization: RESTRICTED_AUTHORIZATION,
+    discovery: RESTRICTED_DISCOVERY,
+    assets: { access: "authorized" },
+    violations,
+  };
+}
+
+/**
+ * Reserved platform paths match case-insensitively, unlike tenant content.
+ *
+ * Publication paths are case-SENSITIVE by policy, which is correct for tenant
+ * content but a bypass here: `/ADMIN` would miss this check, fall through to
+ * the root mount (which matches every path) and resolve public Tier 0. Every
+ * reserved entry is lowercase ASCII, so folding the path's case for this one
+ * comparison closes that without loosening mount matching anywhere else.
+ */
+function isPlatformReserved(normalizedPath: string): boolean {
+  const caseFolded = normalizedPath.toLowerCase();
+  return PUBLICATION_SPACE_RESERVED_MOUNTS.some((reserved) =>
+    publicationMountMatchesPath(reserved, caseFolded),
+  );
+}
+
+/**
+ * Compile a tenant's declared publication spaces into a route-tier index.
+ *
+ * Never throws and never refuses: config that does not validate yields an empty
+ * index carrying its violations, which resolves every route fail-closed.
+ */
+export function compileRouteTierIndexV1(
+  tenant: Pick<TenantConfig, "tenant_id" | "publicationSpaces">,
+): RouteTierIndexV1 {
+  const resolved = resolveTenantPublicationSpacesV1(tenant);
+  if (!resolved.ok) {
+    return {
+      version: ROUTE_TIER_RESOLUTION_VERSION,
+      tenant: tenant.tenant_id,
+      mounts: [],
+      spaces: new Map(),
+      violations: resolved.violations,
+    };
+  }
+  return {
+    version: ROUTE_TIER_RESOLUTION_VERSION,
+    tenant: tenant.tenant_id,
+    mounts: resolved.value.mounts,
+    spaces: new Map(resolved.value.manifests.map((manifest) => [manifest.id, manifest])),
+    violations: [],
+  };
+}
+
+/**
+ * Resolve one route to its tier. THE tier answer — no consumer may derive its
+ * own.
+ *
+ * Fail-closed at every step: a path that will not normalize, a platform-reserved
+ * path, an unmounted path, and an index built from invalid config all resolve to
+ * `tier-3-origin-compute` with authorization required. A route is public only
+ * when a validated space declares it so.
+ */
+export function resolveRouteTierV1(
+  index: RouteTierIndexV1,
+  requestPath: string,
+): ResolvedRouteTierV1 {
+  const normalized = normalizePublicationPath(requestPath, { mode: "request" });
+  if (!normalized.ok) {
+    return failClosed(index.tenant, requestPath, "unresolved", normalized.violations);
+  }
+  const path = normalized.value;
+
+  if (index.violations.length > 0) {
+    return failClosed(index.tenant, path, "unresolved", index.violations);
+  }
+
+  // Before any mount lookup: a tenant's root mount matches every path, and
+  // platform surfaces (/admin, /api, /cockpit, …) are not tenant publication
+  // content. Handing them to the root space would classify the control plane as
+  // public static.
+  if (isPlatformReserved(path)) {
+    return failClosed(index.tenant, path, "platform-reserved", [
+      {
+        path: "path",
+        code: "publication_reserved_mount",
+        message: "Path is a platform-reserved mount and is not served from a publication space.",
+      },
+    ]);
+  }
+
+  const mount = index.mounts.find((entry) => publicationMountMatchesPath(entry.mount, path));
+  if (!mount) {
+    return failClosed(index.tenant, path, "unresolved", [
+      {
+        path: "path",
+        code: "publication_route_unmounted",
+        message: "No publication mount owns this path.",
+      },
+    ]);
+  }
+
+  const manifest = index.spaces.get(mount.spaceId);
+  if (!manifest) {
+    return failClosed(index.tenant, path, "unresolved", [
+      {
+        path: "path",
+        code: "publication_space_missing",
+        message: "The mount's publication space is absent from the index.",
+      },
+    ]);
+  }
+
+  // `authorization.policy` is the tier discriminator. The manifest validator
+  // binds `visibility` and `assets.access` to it, so one derivation settles all
+  // three. A gated space stays Tier 3 whatever its mount behavior.
+  const tier: RouteTierV1 =
+    manifest.authorization.policy === "capability"
+      ? "tier-3-origin-compute"
+      : mount.behavior === "redirect-308"
+        ? "tier-1-edge-decision"
+        : "tier-0-static";
+
+  return {
+    version: ROUTE_TIER_RESOLUTION_VERSION,
+    tenant: index.tenant,
+    path,
+    tier,
+    origin: "publication-space",
+    requiresAuthorization: tier === "tier-3-origin-compute",
+    space: {
+      version: PUBLICATION_SPACE_REF_VERSION,
+      tenant: manifest.tenant,
+      spaceId: manifest.id,
+    },
+    mount,
+    ...(mount.redirectTo ? { redirectTo: mount.redirectTo } : {}),
+    visibility: manifest.visibility,
+    authorization: manifest.authorization,
+    discovery: manifest.discovery,
+    assets: { access: manifest.assets.access },
+    violations: [],
+  };
+}

package/packages/public-runtime/src/static-bundle.ts

@@ -41,6 +41,7 @@
  * either way, never a guess.
  */
 import { assetContentType } from "./tenant-assets.js";
+import { formatHtmlCacheControl } from "./html-cache-policy.js";
 
 // ---------------------------------------------------------------------------
 // R2 seam — same structural subset tenant-assets.ts uses (no workers-types dep)
@@ -156,6 +157,14 @@ export interface StaticBundleManifest {
   treeDigest: string;
   pinnedNonce: string;
   csp: { headerName: string; value: string } | null;
+  /**
+   * The route-document `Cache-Control` this bundle's tenant declared (ADR 0013
+   * `serving.htmlCachePolicy`, formatted by `formatHtmlCacheControl` at materialize).
+   * Read by BOTH serving planes so the header is the tenant's property, not the
+   * provider's. Absent on a bundle materialized before this contract ⇒ the shared
+   * `DEFAULT_HTML_CACHE_POLICY` string (see the route branch of `serveStaticBundle`).
+   */
+  htmlCacheControl?: string;
   /** T6 classification: relPath -> {hash, kind}. Absent on a pre-T6 manifest — every lookup then falls back to the old versions/<digest>/<rel> key (see `resolveStaticBundleObjectKey`). */
   files?: Record<string, StaticBundleFileEntry>;
 }
@@ -184,7 +193,8 @@ function parseManifest(raw: string): StaticBundleManifest | null {
         }
       }
     }
-    return { treeDigest: m.treeDigest, pinnedNonce: m.pinnedNonce, csp, files };
+    const htmlCacheControl = typeof m.htmlCacheControl === "string" ? m.htmlCacheControl : undefined;
+    return { treeDigest: m.treeDigest, pinnedNonce: m.pinnedNonce, csp, htmlCacheControl, files };
   } catch {
     return null;
   }
@@ -250,8 +260,6 @@ function failClosed(deps: ServeStaticBundleDeps, detail: string): Response {
   });
 }
 
-/** Cache-Control for a `route`-kind file (HTML/xml/txt — rendered fresh per version, stable non-digest url). */
-const ROUTE_CACHE_CONTROL = "public, max-age=0, s-maxage=300, stale-while-revalidate=86400";
 /** Cache-Control for an `asset`-kind file — the pool key IS the content hash, so caching forever is always correct (epic §A). */
 const ASSET_CACHE_CONTROL = "public, max-age=31536000, immutable";
 
@@ -320,6 +328,11 @@ export async function serveStaticBundle(
   }
 
   const isHtml = rel.endsWith(".html");
+  // The route-document Cache-Control is the TENANT's declared policy (ADR 0013),
+  // baked into the manifest at materialize; an old bundle without it falls to the
+  // shared DEFAULT_HTML_CACHE_POLICY string — the SAME source the S3 plane reads, so
+  // both planes emit a byte-identical header.
+  const routeCacheControl = manifest.htmlCacheControl ?? formatHtmlCacheControl();
   // Cache tier: use the manifest's `kind` classification when present.
   // A manifest with no `files` at all falls back to the ORIGINAL
   // isHtml-based heuristic — every non-html path used to be treated as a
@@ -328,9 +341,9 @@ export async function serveStaticBundle(
   const cacheControl = entry
     ? entry.kind === "asset"
       ? ASSET_CACHE_CONTROL
-      : ROUTE_CACHE_CONTROL
+      : routeCacheControl
     : isHtml
-      ? ROUTE_CACHE_CONTROL
+      ? routeCacheControl
       : ASSET_CACHE_CONTROL;
   const headers: Record<string, string> = {
     "content-type": assetContentType(rel),

package/packages/public-runtime/src/tenant-assets.ts

@@ -53,6 +53,16 @@ export interface R2ObjectLike {
   arrayBuffer(): Promise<ArrayBuffer>;
   /** Byte length, when the store knows it. */
   size?: number;
+  /** Arbitrary key/value metadata attached at `put()` time (real R2 carries this through unchanged). */
+  customMetadata?: Record<string, string>;
+}
+
+export interface R2PutOptionsLike {
+  /** Attached to the object and read back verbatim via `get().customMetadata` — used
+   *  here to carry the INGEST-TIME-KNOWN byte length + content hash so a later
+   *  verify can detect a truncated/corrupted object independent of trusting the
+   *  store's own reported size alone (see `verifyMaterializedAssets`). */
+  customMetadata?: Record<string, string>;
 }
 
 export interface R2BucketLike {
@@ -60,9 +70,14 @@ export interface R2BucketLike {
   put(
     key: string,
     value: ArrayBuffer | ArrayBufferView | ReadableStream | string,
+    options?: R2PutOptionsLike,
   ): Promise<unknown>;
 }
 
+/** `customMetadata` keys `ingestAssetVersion` stamps on every pool object (see its header). */
+export const ASSET_BYTE_LENGTH_METADATA_KEY = "byteLength";
+export const ASSET_SHA256_METADATA_KEY = "sha256";
+
 // ---------------------------------------------------------------------------
 // Channel→version pointer (one snapshot versionId per channel)
 // ---------------------------------------------------------------------------
@@ -303,10 +318,11 @@ async function putAssetWithRetry(
   bucket: R2BucketLike,
   key: string,
   bytes: Uint8Array,
+  customMetadata: Record<string, string>,
 ): Promise<void> {
   for (let attempt = 1; attempt <= R2_PUT_MAX_ATTEMPTS; attempt++) {
     try {
-      await bucket.put(key, bytes);
+      await bucket.put(key, bytes, { customMetadata });
       return;
     } catch (error) {
       if (attempt === R2_PUT_MAX_ATTEMPTS || !isTransientR2PutError(error)) throw error;
@@ -322,6 +338,13 @@ async function putAssetWithRetry(
  * Non-public files in `files` are ignored, so the whole seed/reconcile file set
  * can be passed. Pass `versionId` to bind assets to the publish snapshot id;
  * omit it to derive one from the bytes.
+ *
+ * Stamps each object's `customMetadata` with the byte length + sha256 of the
+ * EXACT bytes handed to `bucket.put()` here (the ingest-time-known-correct
+ * values) — `verifyMaterializedAssets` reads them back to detect a later
+ * truncation/corruption that mere existence + non-empty can't see (the gap
+ * that let a 79357-byte file be silently served as its first 65536 bytes,
+ * `forge-response-integrity.ts`'s `assertFileOffsetAdvances` doc).
  */
 export async function ingestAssetVersion(
   bucket: R2BucketLike,
@@ -334,9 +357,13 @@ export async function ingestAssetVersion(
   const keys: string[] = [];
   for (const a of assets) {
     const key = tenantAssetKey(tenantId, vid, a.rel);
+    const customMetadata = {
+      [ASSET_BYTE_LENGTH_METADATA_KEY]: String(a.bytes.length),
+      [ASSET_SHA256_METADATA_KEY]: await sha256Hex(a.bytes),
+    };
     // The key and bytes are immutable for this version, so retrying an ambiguous
     // transient R2 failure is idempotent even if the first write landed server-side.
-    await putAssetWithRetry(bucket, key, a.bytes);
+    await putAssetWithRetry(bucket, key, a.bytes, customMetadata);
     keys.push(key);
   }
   return { versionId: vid, keys, count: keys.length };
@@ -543,10 +570,20 @@ function matchesEtag(ifNoneMatch: string, etag: string): boolean {
 export interface AssetVerificationResult {
   /** App-asset objects expected to serve at this version. */
   expected: number;
-  /** How many were confirmed present + non-empty in R2. */
+  /** How many were confirmed present + non-empty + byte-length-correct in R2. */
   verified: number;
-  /** The served relative paths (or artifact paths) that did NOT materialize. */
+  /** The served relative paths (or artifact paths) that did NOT materialize
+   *  correctly — absent, empty, unnormalizable, OR present-but-truncated
+   *  (see `corrupted`, a labelled subset of this same list). */
   missing: string[];
+  /** The subset of `missing` that WAS present + non-empty in R2 but whose
+   *  stored byte length doesn't match the length recorded in the object's
+   *  own `customMetadata` at ingest time (`ingestAssetVersion`) — i.e. a
+   *  truncated/corrupted object, distinct from one that never landed at all.
+   *  Empty for an object with no `customMetadata` (ingested before this
+   *  check existed): that legacy case falls back to presence + non-empty
+   *  only, same as before this field existed. */
+  corrupted: string[];
   /** Set when the verification itself could not run (fail-closed, not a pass). */
   error?: string;
 }
@@ -554,16 +591,38 @@ export interface AssetVerificationResult {
 /** How many R2 existence probes run at once — matches the runtime's ~6/host reality. */
 const VERIFY_PROBE_POOL = 6;
 
+/** Parse the `customMetadata.byteLength` an ingest stamped, or `null` when absent/malformed (legacy object, or a store that drops custom metadata). */
+function expectedByteLength(customMetadata: Record<string, string> | undefined): number | null {
+  const raw = customMetadata?.[ASSET_BYTE_LENGTH_METADATA_KEY];
+  if (raw == null) return null;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? n : null;
+}
+
 /**
- * Confirm every app-asset artifact path is present + non-empty in R2 at
- * `versionId` — the EXACT object `serveTenantAsset` streams for `/tenants/<id>/<rel>`.
- * Positive, fail-closed evidence for the version-scoped asset lane: an asset whose
- * path can't normalize to a served rel, or is absent/empty in R2, is reported
- * `missing`; a systemic fault (the bucket throwing on every probe) reports the whole
- * subtree missing with an `error` rather than a vacuous pass. Checking the object at
- * the published `versionId` (not an HTTP self-fetch) is channel-independent: the
- * served route may resolve a different channel→version pointer per request, but a
- * version's bytes are fixed. `bucket` needs only `get`; the body is never read.
+ * Confirm every app-asset artifact path is present, non-empty, AND (when the
+ * object carries the `customMetadata` `ingestAssetVersion` stamps) the exact
+ * byte length recorded at ingest — in R2 at `versionId`, the EXACT object
+ * `serveTenantAsset` streams for `/tenants/<id>/<rel>`. Positive, fail-closed
+ * evidence for the version-scoped asset lane: an asset whose path can't
+ * normalize to a served rel, is absent/empty in R2, OR is present but SHORTER
+ * than its ingest-time length (truncated/corrupted — reported in `corrupted`,
+ * a labelled subset of `missing`) is reported `missing`; a systemic fault (the
+ * bucket throwing on every probe) reports the whole subtree missing with an
+ * `error` rather than a vacuous pass. A LONGER-than-expected object is also
+ * flagged (any mismatch is untrusted, not just truncation).
+ *
+ * Comparing against a byte length captured from the SAME bytes handed to
+ * `bucket.put()` at ingest catches corruption introduced between ingest and
+ * now (a bad/partial R2 write, bit-rot, a future regression in this store) —
+ * it deliberately does NOT re-derive "correct" from the upstream Gitea read
+ * again (that class of truncation is guarded independently, at the read
+ * boundary — see `forge-response-integrity.ts`'s `assertFileOffsetAdvances`).
+ * Checking the object at the published `versionId` (not an HTTP self-fetch)
+ * is channel-independent: the served route may resolve a different
+ * channel→version pointer per request, but a version's bytes are fixed.
+ * `bucket` needs only `get`; the body is never read (checking `size` against
+ * `customMetadata` is a metadata-only comparison, no download).
  */
 export async function verifyMaterializedAssets(
   bucket: Pick<R2BucketLike, "get">,
@@ -572,10 +631,11 @@ export async function verifyMaterializedAssets(
   appAssetArtifactPaths: readonly string[],
 ): Promise<AssetVerificationResult> {
   const expected = appAssetArtifactPaths.length;
-  if (expected === 0) return { expected: 0, verified: 0, missing: [] };
+  if (expected === 0) return { expected: 0, verified: 0, missing: [], corrupted: [] };
 
   try {
     const missing: string[] = [];
+    const corrupted: string[] = [];
     let verified = 0;
     let next = 0;
     const worker = async (): Promise<void> => {
@@ -591,8 +651,14 @@ export async function verifyMaterializedAssets(
         let present = false;
         try {
           const obj = await bucket.get(tenantAssetKey(tenantId, versionId, rel));
-          // Present when the object exists and (when the store reports size) is non-empty.
-          present = obj != null && (obj.size == null || obj.size > 0);
+          if (obj != null) {
+            const nonEmpty = obj.size == null || obj.size > 0;
+            const expectedLength = expectedByteLength(obj.customMetadata);
+            const lengthMatches =
+              expectedLength == null || obj.size == null || obj.size === expectedLength;
+            present = nonEmpty && lengthMatches;
+            if (nonEmpty && !lengthMatches) corrupted.push(rel);
+          }
         } catch {
           present = false;
         }
@@ -604,7 +670,8 @@ export async function verifyMaterializedAssets(
     await Promise.all(Array.from({ length: width }, worker));
     // Stable order aids diffing/readability — pool completion order is nondeterministic.
     missing.sort();
-    return { expected, verified, missing };
+    corrupted.sort();
+    return { expected, verified, missing, corrupted };
   } catch (err) {
     // Systemic failure (e.g. the bucket seam throwing on every call): fail closed —
     // report the whole subtree as unverified rather than claiming a pass.
@@ -612,6 +679,7 @@ export async function verifyMaterializedAssets(
       expected,
       verified: 0,
       missing: [...appAssetArtifactPaths],
+      corrupted: [],
       error: err instanceof Error ? err.message : String(err),
     };
   }

package/packages/public-runtime/src/tenant.ts

@@ -9,6 +9,8 @@ import type { ManagedCheckoutConfig } from "./checkout.js";
 import type { CapabilityConfig } from "./capabilities.js";
 import type { AutopilotConfig, MembershipProgramConfig } from "./membership.js";
 import type { IntegrationDeclarationInput } from "./integration/resolve.js";
+import type { PublicationSpaceManifestV1 } from "./publication-space.js";
+import type { HtmlCachePolicy } from "./html-cache-policy.js";
 
 /**
  * The shared semantic COLOR contract — the widget library's public API.
@@ -225,7 +227,28 @@ export interface ExciseTaxConfig {
  * fabricates or hand-authors mandated legal copy (per decision
  * compliance-widgets-platform-owned). Additive — a tenant lists only what applies.
  */
+/**
+ * The reviewed compliance rule profiles a tenant may select. Each names a body of
+ * counsel-reviewed rule data (age floor, excise handling, PACT Act posture,
+ * per-state bans and order caps) that the enforcement engine evaluates.
+ *
+ * A union rather than a free string so a typo cannot silently resolve to "no
+ * profile", which would fail the tenant's checkout closed with no signal that a
+ * declaration was intended.
+ */
+export type ComplianceRuleProfile = "vape-nicotine-us";
+
 export interface ComplianceConfig {
+  /**
+   * The reviewed rule PROFILE whose ruleset the enforcement gate evaluates for
+   * this tenant (see `config/compliance/rulesets.ts`). This is what makes a
+   * regulated tenant enforceable: a tenant that declares no profile resolves to
+   * no ruleset and FAILS CLOSED, which is the correct default — the rule data is
+   * counsel-reviewed content, so a tenant selects a profile rather than authoring
+   * one. Declared per tenant like any other capability; the platform never infers
+   * it from which tenant this is.
+   */
+  ruleProfile?: ComplianceRuleProfile;
   /** Minimum age to enter. Drives the soft affirmation gate (e.g. 21). */
   minAge?: number;
   /** Render the FDA nicotine warning sitewide + reinforced on PDP. */
@@ -282,6 +305,24 @@ export type SiteType = "commerce" | "marketing";
  */
 export type StorefrontMode = "enabled" | "disabled";
 
+/**
+ * Which substrate serves a tenant's LIVE public site (ADR 0013). This decides how
+ * go-live resolves the `live` pointer — NOT a display or routing hint.
+ *
+ * - `"worker-r2-pointer"` — Cloudflare Worker + R2 + KV pointer plane. Go-live
+ *   resolves the pinned version's already-staged, VALIDATED bundle digest from the
+ *   staged-version index and flips the KV `live` pointer with its
+ *   `channelDigests.live` companion in one CAS write, FAIL-CLOSED when that digest
+ *   is unresolvable or unvalidated (never a live pointer over a bundle the read
+ *   path cannot serve).
+ * - `"s3-overwrite"` — AWS S3/CloudFront copy path. Go-live is a bare KV `live`
+ *   pointer flip plus a `www-promote` dispatch that byte-copies
+ *   `versions/<digest>/` → `live/` (the digest resolved from the version ref by
+ *   CI). It has NO aggregate-keyed staged-version index, so the pointer-plane
+ *   staged-digest gate does not — and must not — apply.
+ */
+export type PublicServingProvider = "worker-r2-pointer" | "s3-overwrite";
+
 /** The one storefront mode value that permits go-live. The gate tests strict equality. */
 export const STOREFRONT_MODE_ENABLED = "enabled" as const;
 
@@ -384,6 +425,8 @@ export interface TenantConfig {
   /** Currency for display formatting. */
   currency: string;
   locale: string;
+  /** Explicit publication spaces for this tenant, including one canonical root. */
+  publicationSpaces?: readonly PublicationSpaceManifestV1[];
   /**
    * What the site is for: "commerce" (default) or "marketing". Drives feature
    * defaults (resolveTenantFeatures) and non-commerce chrome. Omitted == commerce.
@@ -491,6 +534,33 @@ export interface TenantConfig {
      */
     verifyUrl?: string;
   };
+  /**
+   * Public-serving contract (ADR 0013). Declares WHICH substrate serves this
+   * tenant's live public site — the single input that decides how go-live resolves
+   * the `live` pointer (see {@link PublicServingProvider}).
+   *
+   * ABSENT/undefined ⇒ NOT pointer-serving: a hosted tenant served by the Worker,
+   * or a static tenant whose bytes reach `live/` by an S3 copy rather than a
+   * pointer-plane digest flip. Only `provider: "worker-r2-pointer"` arms the
+   * fail-closed staged-digest gate. The `PointerBackend` seam extends this with
+   * more fields (delivery gate, cache policy) — declare them here; never infer a
+   * serving mode from `staticPublish.target`.
+   */
+  serving?: {
+    /** Which substrate serves this tenant's live public site (ADR 0013). */
+    provider: PublicServingProvider;
+    /**
+     * The route-file HTML cache policy (ADR 0013) — the browser and shared TTLs a
+     * serving substrate stamps on route documents, read by BOTH backends so the
+     * header contract is a property of the TENANT, not an artifact of the provider
+     * (today S3 stamps `max-age=300` while the Worker emits `max-age=0`; this is the
+     * declared source that unifies them). `browserMaxAge` is the `max-age` a client
+     * caches a route document for; `sharedMaxAge` the `s-maxage` the CDN caches it
+     * for; `staleWhileRevalidate` the grace window a stale document may still serve
+     * while a fresh one is fetched. All in seconds. Absent ⇒ {@link DEFAULT_HTML_CACHE_POLICY}.
+     */
+    htmlCachePolicy?: HtmlCachePolicy;
+  };
   /**
    * Storefront product/subscription state — the paywall the platform gates GO-LIVE
    * on. This is the storefront's

package/packages/public-runtime/tests/fixtures/publication-spaces/internal.json

@@ -0,0 +1,32 @@
+{
+  "version": 1,
+  "id": "knowledge",
+  "tenant": "fixture.example",
+  "source": {
+    "forge": "fixture",
+    "repo": "fixture-private-publications",
+    "defaultBranch": "main"
+  },
+  "routes": {
+    "canonicalMount": "/knowledge"
+  },
+  "visibility": "internal",
+  "authorization": {
+    "policy": "capability",
+    "capability": "internal-content-reader"
+  },
+  "discovery": {
+    "sitemap": false,
+    "feeds": false,
+    "publicSearch": false,
+    "llms": false
+  },
+  "assets": {
+    "namespace": "knowledge",
+    "access": "authorized"
+  },
+  "renderer": {
+    "contractVersion": "storefront-v1",
+    "themeContractVersion": "theme-v1"
+  }
+}