@tokenoftrust/storefront-runner 1.4.1 → 2.0.0

package/packages/public-runtime/src/compliance-obligations.ts

@@ -0,0 +1,310 @@
+/**
+ * Extension-policy compliance obligations — the complete, extensible floor model.
+ *
+ * An OBLIGATION is a mandated compliance duty: an age/identity gate, excise-tax
+ * collection, an FDA nicotine warning, a PACT Act shipment notice, an adult
+ * signature, a California Prop 65 warning, a shipping/jurisdiction restriction, and
+ * any future duty a later card registers. The set a tenant owes is SERVER-DERIVED
+ * from its authoritative `TenantConfig.compliance` — an app manifest or a raw-HTML
+ * page can never be an input to resolution, so nothing external can drop or weaken
+ * a configured duty (ADR 0014 G1 `integration-regulated-floor-nonwaivable`, D-R7
+ * tamper-recovery). Raw HTML and managed apps resolve the SAME obligation set
+ * (ADR 0015 `integration-schema-shared`).
+ *
+ * The compliance-authority axis is kernel-01's `ASSURANCE_SURFACES`
+ * (`unregulated-marketing` | `commerce` | `regulated`) — the single vocabulary;
+ * this module never invents a second. (The finer `SURFACES` in
+ * `integration-capabilities.ts` is a separate axis; ext-policy-11 reconciles the
+ * two.)
+ *
+ * The registry is OPEN — a future duty registers a spec without editing resolution
+ * or gating logic. An obligation id OUTSIDE the registry is UNKNOWN and FAILS
+ * CLOSED (`verifyObligationCoverage`), never assumed satisfied.
+ *
+ * Obligation ids `age_gate`, `excise`, and `jurisdiction` are IDENTICAL to the
+ * promotion-evidence check ids (ext-prereq-03 `REQUIRED_FOR_PROMOTE`), so
+ * ext-policy-06 maps an obligation straight onto its evidence row with no
+ * translation table.
+ */
+import type { TenantConfig } from "./tenant.js";
+import { ASSURANCE_SURFACES, type AssuranceSurface } from "./integration/assurance.js";
+
+/** Contract token — bump the minor for additive vocabulary, the major for a break (ADR 0006 semver). */
+export const COMPLIANCE_OBLIGATION_MODEL = "compliance-obligation-model@1" as const;
+export type ComplianceObligationModel = typeof COMPLIANCE_OBLIGATION_MODEL;
+
+/** The only input to obligation resolution: the tenant's authoritative config. */
+export type ObligationTenant = Pick<TenantConfig, "compliance" | "siteType">;
+
+/**
+ * Platform-owned protected UI/preflight anchors. A third-party integration can
+ * never remove, hide, overlay, or mutate these (D-R7). This is the authoritative
+ * list the capability-specific conformance suite and ext-policy-09 sentinels key
+ * on; here it is the declarative floor, not the detective control.
+ */
+export const PROTECTED_SURFACES = [
+  "age-gate",
+  "compliance-warning",
+  "shipping-jurisdiction-notice",
+  "cart-preflight",
+  "checkout-controls",
+] as const;
+export type ProtectedSurface = (typeof PROTECTED_SURFACES)[number];
+
+/** A registered compliance duty. */
+export interface ObligationSpec {
+  /** Stable, wire-serialized obligation id. */
+  id: string;
+  /** Operator-facing label. */
+  label: string;
+  /** The compliance-authority surface this duty belongs to (kernel-01 axis). */
+  surface: AssuranceSurface;
+  /**
+   * Platform-owned protected anchors this obligation renders. Non-empty ⇒ the
+   * obligation is tamper-protected: an integration can never disable it (D-R7).
+   */
+  protectedSurfaces: readonly ProtectedSurface[];
+  /**
+   * Pure predicate over authoritative tenant config: does this tenant configure
+   * this obligation? The ONLY resolution input — never an app/raw-HTML declaration.
+   */
+  applies: (tenant: ObligationTenant) => boolean;
+}
+
+/** A resolved (applicable) obligation for a specific tenant. */
+export interface ResolvedObligation {
+  id: string;
+  label: string;
+  surface: AssuranceSurface;
+  protectedSurfaces: readonly ProtectedSurface[];
+}
+
+const REGISTRY = new Map<string, ObligationSpec>();
+
+/**
+ * Register a compliance obligation. Extensible seam — a future duty registers a
+ * spec here (or from a downstream card) and flows through resolution, surface
+ * derivation, coverage verification, and the floor guard with no core edit. A
+ * duplicate id is a programming error and throws.
+ */
+export function registerObligation(spec: ObligationSpec): void {
+  if (REGISTRY.has(spec.id)) {
+    throw new Error(`Duplicate compliance obligation id: ${spec.id}`);
+  }
+  REGISTRY.set(spec.id, spec);
+}
+
+/** Every registered obligation spec, in registration order. */
+export function obligationSpecs(): ObligationSpec[] {
+  return [...REGISTRY.values()];
+}
+
+/** Is this id a registered obligation? Anything else is UNKNOWN → fails closed. */
+export function isKnownObligation(id: string): boolean {
+  return REGISTRY.has(id);
+}
+
+// ── Built-in floor obligations ──────────────────────────────────────────────
+// Each derives PURELY from `TenantConfig.compliance`. `age_gate`, `excise`, and
+// `jurisdiction` share the promotion-evidence check ids (ext-prereq-03).
+
+const BUILTIN_OBLIGATIONS: readonly ObligationSpec[] = [
+  {
+    id: "age_gate",
+    label: "Age/identity verification gate",
+    surface: "regulated",
+    protectedSurfaces: ["age-gate", "cart-preflight"],
+    applies: (t) => !!t.compliance?.minAge,
+  },
+  {
+    id: "excise",
+    label: "Excise tax collection",
+    surface: "regulated",
+    protectedSurfaces: ["checkout-controls"],
+    applies: (t) => !!t.compliance?.nicotineWarning || !!t.compliance?.exciseTax,
+  },
+  {
+    id: "nicotine_warning",
+    label: "FDA nicotine warning",
+    surface: "regulated",
+    protectedSurfaces: ["compliance-warning"],
+    applies: (t) => !!t.compliance?.nicotineWarning,
+  },
+  {
+    id: "pact_act",
+    label: "PACT Act shipment notice",
+    surface: "regulated",
+    protectedSurfaces: ["compliance-warning", "shipping-jurisdiction-notice"],
+    applies: (t) => !!t.compliance?.pactAct,
+  },
+  {
+    id: "adult_signature",
+    label: "Adult signature on delivery",
+    surface: "regulated",
+    protectedSurfaces: ["shipping-jurisdiction-notice", "cart-preflight"],
+    applies: (t) => !!t.compliance?.adultSignature,
+  },
+  {
+    id: "prop65",
+    label: "California Prop 65 warning",
+    surface: "commerce",
+    protectedSurfaces: ["compliance-warning"],
+    applies: (t) => !!t.compliance?.prop65,
+  },
+  {
+    id: "jurisdiction",
+    label: "Restricted shipping / jurisdiction eligibility",
+    surface: "commerce",
+    protectedSurfaces: ["shipping-jurisdiction-notice", "cart-preflight"],
+    applies: (t) =>
+      !!t.compliance?.stateEligibility || !!t.compliance?.shippingRestriction,
+  },
+];
+
+for (const spec of BUILTIN_OBLIGATIONS) registerObligation(spec);
+
+// ── Resolution (server-derived, floor-only) ─────────────────────────────────
+
+/**
+ * The tenant's REQUIRED obligation set, derived purely from authoritative config.
+ * An app/raw-HTML declaration is never an argument, so no integration can drop a
+ * duty (ADR G1 / D-R7). Order is stable (registration order) so the serialized
+ * `configuredObligations` and the assurance record stay deterministic.
+ */
+export function resolveObligations(tenant: ObligationTenant): ResolvedObligation[] {
+  const out: ResolvedObligation[] = [];
+  for (const spec of REGISTRY.values()) {
+    if (spec.applies(tenant)) {
+      out.push({
+        id: spec.id,
+        label: spec.label,
+        surface: spec.surface,
+        protectedSurfaces: spec.protectedSurfaces,
+      });
+    }
+  }
+  return out;
+}
+
+/** The resolved obligation ids — the shape gates and the assurance record carry. */
+export function resolveObligationIds(tenant: ObligationTenant): string[] {
+  return resolveObligations(tenant).map((o) => o.id);
+}
+
+const SURFACE_RANK: Record<AssuranceSurface, number> = Object.fromEntries(
+  ASSURANCE_SURFACES.map((s, i) => [s, i]),
+) as Record<AssuranceSurface, number>;
+
+/**
+ * The tenant's compliance-authority surface (kernel-01 axis): the MOST restrictive
+ * surface any applied obligation implies, else the siteType floor (a marketing site
+ * with no duty is `unregulated-marketing`; a commerce site is `commerce`).
+ */
+export function resolveObligationSurface(tenant: ObligationTenant): AssuranceSurface {
+  let surface: AssuranceSurface =
+    tenant.siteType === "marketing" ? "unregulated-marketing" : "commerce";
+  for (const o of resolveObligations(tenant)) {
+    if (SURFACE_RANK[o.surface] > SURFACE_RANK[surface]) surface = o.surface;
+  }
+  return surface;
+}
+
+/** True iff the tenant resolves to the `regulated` authority surface. */
+export function isRegulated(tenant: ObligationTenant): boolean {
+  return resolveObligationSurface(tenant) === "regulated";
+}
+
+/**
+ * The union of platform-owned protected anchors the tenant's applied obligations
+ * render, in canonical order. Drives the conformance suite and the ext-policy-09
+ * sentinels — the set an integration can never disable (D-R7).
+ */
+export function protectedSurfacesFor(tenant: ObligationTenant): ProtectedSurface[] {
+  const seen = new Set<ProtectedSurface>();
+  for (const o of resolveObligations(tenant)) {
+    for (const s of o.protectedSurfaces) seen.add(s);
+  }
+  return PROTECTED_SURFACES.filter((s) => seen.has(s));
+}
+
+// ── Fail-closed coverage gate (mirrors ext-prereq-03 verifyPromotionEvidence) ──
+
+export interface ObligationCoverageVerdict {
+  /** True only when the declaration COMPLETELY, non-ambiguously covers the floor. */
+  ok: boolean;
+  /** Every reason coverage is insufficient (empty ⇔ ok). */
+  blockers: string[];
+}
+
+/**
+ * The single fail-CLOSED authority for "does this declaration satisfy the tenant's
+ * compliance floor?". The required set is SERVER-DERIVED from tenant config, never
+ * taken from the (spoofable) declaration. Rejects on any of: an absent declaration
+ * (no array), an omitted required obligation, an UNKNOWN obligation id (registry
+ * drift / a spoofed row), or a duplicated id (an ambiguous set that could mask a
+ * missing duty). Shared by the raw-HTML path and the managed-app path (ADR 0015).
+ */
+export function verifyObligationCoverage(
+  tenant: ObligationTenant,
+  declaredIds: readonly string[] | null | undefined,
+): ObligationCoverageVerdict {
+  // Absent declaration — fail closed. Nothing declared against a regulated floor is
+  // exactly what this gate exists to refuse.
+  if (!Array.isArray(declaredIds)) {
+    return {
+      ok: false,
+      blockers: [
+        "Obligation coverage is absent — nothing declared against the compliance floor.",
+      ],
+    };
+  }
+
+  const blockers: string[] = [];
+  const seen = new Set<string>();
+  for (const id of declaredIds) {
+    if (!isKnownObligation(id)) {
+      blockers.push(`Unknown compliance obligation declared: ${id}`);
+    }
+    if (seen.has(id)) {
+      blockers.push(`Duplicated compliance obligation declared: ${id}`);
+    }
+    seen.add(id);
+  }
+
+  for (const id of resolveObligationIds(tenant)) {
+    if (!seen.has(id)) {
+      blockers.push(`Required compliance obligation omitted: ${id}`);
+    }
+  }
+
+  return { ok: blockers.length === 0, blockers };
+}
+
+export interface ObligationFloorViolation {
+  obligation: string;
+  reason: string;
+}
+
+/**
+ * Surface any attempt by an integration to disable a configured obligation. The
+ * resolved floor is unchanged regardless — `resolveObligations` never reads this
+ * input — so this only records the attempt for denial/audit (D-R7). Any id in
+ * `requestedDisable` that names a resolved required obligation is a violation.
+ */
+export function obligationFloorViolations(
+  tenant: ObligationTenant,
+  requestedDisable?: readonly string[] | null,
+): ObligationFloorViolation[] {
+  if (!requestedDisable) return [];
+  const required = new Set(resolveObligationIds(tenant));
+  const out: ObligationFloorViolation[] = [];
+  for (const id of requestedDisable) {
+    if (required.has(id)) {
+      out.push({
+        obligation: id,
+        reason: `${id} is a configured compliance obligation and cannot be disabled by an integration.`,
+      });
+    }
+  }
+  return out;
+}

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

@@ -10,6 +10,11 @@
  * The middleware decides the header name — `Content-Security-Policy` (enforce)
  * vs `Content-Security-Policy-Report-Only` (rollout). This only builds the value.
  */
+// The embed catalog DATA lives in a dependency-free .mjs so plain-node tooling
+// (the dev-loop lint) can share this exact copy — see embed-catalog.mjs. csp.ts
+// owns the TYPE (EmbedProvider) and re-exports the data under it below.
+import { EMBED_PROVIDERS as EMBED_PROVIDERS_DATA } from "./embed-catalog.mjs";
+
 export interface CspOptions {
   /** Per-request nonce; the same value goes on the platform's inline tags. */
   nonce: string;
@@ -85,6 +90,100 @@ export const STOREFRONT_CSP_ALLOWLIST = {
   connectSrc: ["https://cloudflareinsights.com"],
 } as const;
 
+/**
+ * Curated catalog of known third-party embeds a tenant may opt into. Keyed by a
+ * stable provider slug the tenant lists in `.tot/config.json` `embeds:`; the
+ * platform (never the tenant) owns the exact origins each provider needs, so a
+ * tenant can enable "pipedrive" without ever hand-writing a CSP origin — and a
+ * novel provider requires a reviewed catalog entry here, not a config edit.
+ *
+ * `markers` are substrings that appear in rendered HTML when the embed is
+ * actually present on a page (so `embedCspAdditions` can add origins ONLY to the
+ * pages that use them — the same derive-from-actual-usage posture as
+ * {@link appWidgetCspAdditions}). Origins are EXACT hosts, never wildcards. An
+ * embed renders in its own cross-origin iframe governed by the provider's CSP,
+ * so `frameSrc` mounts it and `connectSrc`/`scriptSrc` cover only what the
+ * loader needs in the PARENT document.
+ */
+export interface EmbedProvider {
+  /** Human label for lint/report messages. */
+  label: string;
+  /** Substrings whose presence in rendered HTML means the embed is on the page. */
+  markers: readonly string[];
+  scriptSrc?: readonly string[];
+  connectSrc?: readonly string[];
+  frameSrc?: readonly string[];
+}
+
+export const EMBED_PROVIDERS: Readonly<Record<string, EmbedProvider>> =
+  EMBED_PROVIDERS_DATA;
+
+export type EmbedProviderKey = keyof typeof EMBED_PROVIDERS;
+
+/**
+ * Canonical published-artifact path for a tenant's embed opt-in — the SAME
+ * colocated `tenants/<id>/…` config-as-code spine as capabilities/theme. A
+ * tenant self-serves by committing `embeds.json` (a JSON array of catalog
+ * slugs, e.g. `["pipedrive"]`) to their repo; the reconcile pipeline keys the
+ * KV artifact by this path and the storefront reads it back per environment
+ * (localhost=working tree, preview=PR head, live=promoted). No platform code
+ * change needed to enable a catalogued embed.
+ */
+export function embedsArtifactPath(tenantId: string): string {
+  return `tenants/${tenantId}/embeds.json`;
+}
+
+/**
+ * Effective embed opt-in for a tenant: the build-time `TenantConfig.embeds`
+ * default overlaid with the tenant's published `embeds.json` (self-serve,
+ * per-environment) when present — deduped and FILTERED to slugs that exist in
+ * EMBED_PROVIDERS. The filter is the security floor: a tenant can only enable a
+ * platform-vetted provider, never introduce an arbitrary origin; an unknown
+ * slug is dropped here (and flagged by the embeds.json validator + lint).
+ */
+export function resolveEffectiveEmbeds(
+  buildDefault: readonly string[] | undefined,
+  published: readonly string[] | null,
+): string[] {
+  const merged = new Set<string>([...(buildDefault ?? []), ...(published ?? [])]);
+  return [...merged].filter((slug) => slug in EMBED_PROVIDERS);
+}
+
+export interface EmbedCspAdditions {
+  scriptSrc: string[];
+  connectSrc: string[];
+  frameSrc: string[];
+}
+
+/**
+ * CSP additions for the third-party embeds ACTUALLY rendered on this page.
+ *
+ * An origin is added only when BOTH hold: (1) the tenant opted the provider in
+ * via `.tot/config.json` `embeds:` (audit trail + platform review of novel
+ * providers), and (2) the provider's marker appears in the rendered HTML (so a
+ * page that doesn't embed the form never carries the origin). This keeps the
+ * strict policy tenant- AND page-scoped — never a blanket global relaxation.
+ *
+ * Unknown keys in `enabled` are ignored here (the lint surfaces them); a marker
+ * present WITHOUT the matching opt-in is likewise not allowed here — that's the
+ * blocked-embed case the lint/report loop is meant to catch before it ships.
+ */
+export function embedCspAdditions(
+  enabled: readonly string[],
+  renderedHtml: string,
+): EmbedCspAdditions {
+  const out: EmbedCspAdditions = { scriptSrc: [], connectSrc: [], frameSrc: [] };
+  for (const key of new Set(enabled)) {
+    const provider = EMBED_PROVIDERS[key];
+    if (!provider) continue;
+    if (!provider.markers.some((m) => renderedHtml.includes(m))) continue;
+    if (provider.scriptSrc) out.scriptSrc.push(...provider.scriptSrc);
+    if (provider.connectSrc) out.connectSrc.push(...provider.connectSrc);
+    if (provider.frameSrc) out.frameSrc.push(...provider.frameSrc);
+  }
+  return out;
+}
+
 /**
  * CSP additions for a managed-checkout tenant. The loader comes from the checkout
  * CDN; cart requests, frames, and add-to-cart form POSTs hit the store's own

package/packages/public-runtime/src/customization-preview.ts

@@ -142,6 +142,8 @@ export interface EnvResolutionInput {
   /** Platform preview-signing secret (env), if configured. */
   secret?: string | null;
   nowSeconds: number;
+  /** Request pathname — used only to exempt the token dispenser itself (see {@link isPreviewDispatcherPath}). */
+  pathname?: string;
 }
 
 export interface EnvResolution {
@@ -152,16 +154,37 @@ export interface EnvResolution {
   reject?: { status: number; message: string };
 }
 
+/**
+ * The bare tenant-preview DISPATCHER path (`/<tenant>/preview` or
+ * `/<tenant>/preview/`, e.g. `pages/preview/index.astro`, tenant-first) — the page
+ * whose ENTIRE job is to mint a fresh `__preview` token and hand it to the
+ * visitor. On a preview-prefixed host this path would otherwise hit the SAME
+ * "no token -> 401" gate `resolveCustomizationEnv` enforces for every other
+ * path, deadlocking a signed-in-but-token-less visitor: they can never reach
+ * the one page that gives them a token. Distinct from `isCandidatePreviewPath`
+ * (loginGate.ts) — that exempts several preview routes from the LOGIN wall; this
+ * exempts exactly ONE route from the TOKEN wall. `<tenant>` is required to look
+ * like a real tenant id (contains a `.`) so this never accidentally matches a
+ * sibling route. Matched on the pre-strip request path.
+ */
+export function isPreviewDispatcherPath(pathname: string): boolean {
+  const m = pathname.match(/^\/([^/]+)\/preview\/?$/);
+  return m != null && m[1]!.includes(".");
+}
+
 /**
  * Decide which customization environment to serve. Production hosts always get
  * `live` and never consult a token. Preview hosts are auth-gated: a valid,
  * unexpired, tenant-matching token yields `test` (noindex); anything else is
- * rejected.
+ * rejected. The one exception is the token-dispenser path itself (see
+ * {@link isPreviewDispatcherPath}) — it renders the dispatcher's own minimal
+ * page, never tenant content, so it's let through as `live`/no-token rather
+ * than 401ing on the very request that would otherwise fetch it a token.
  */
 export async function resolveCustomizationEnv(
   input: EnvResolutionInput,
 ): Promise<EnvResolution> {
-  if (!input.isPreviewHost) {
+  if (!input.isPreviewHost || isPreviewDispatcherPath(input.pathname ?? "")) {
     return { env: "live", noindex: false };
   }
   if (!input.secret) {

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

@@ -15,6 +15,7 @@ import {
   type ChannelName,
   type PointerRecord,
   type SiteVersionManifest,
+  type SiteVersionSummary,
 } from "./customization-versioning.js";
 import type { CustomizationEnv } from "./customization-preview.js";
 
@@ -93,6 +94,27 @@ export async function resolveChannelVersion(
   return pointer?.channels?.[channel] ?? null;
 }
 
+/**
+ * The static-bundle `treeDigest` a channel currently serves (ADR 0012), or null
+ * when the tenant has no digest companion for that channel (a hosted tenant — it
+ * sets only `channels`, never `channelDigests`).
+ *
+ * This is the RECONCILED read the digest-addressed serving path
+ * (`static-bundle.ts`), the pointer verify (`createPointerVerifyTarget`), and
+ * the pointer-served "current" read (`resolveStaticLiveDigestFromPointer`) use
+ * INSTEAD of `resolveChannelVersion` for a static tenant: the versionId
+ * (`channels[ch]`, the Gitea sha) is NOT the R2 key — the treeDigest is, and it
+ * lives here. Reads the pointer fresh; never throws.
+ */
+export async function resolveChannelDigest(
+  get: KvGet,
+  tenantId: string,
+  channel: ChannelName,
+): Promise<string | null> {
+  const pointer = await readPointer(get, tenantId);
+  return pointer?.channelDigests?.[channel] ?? null;
+}
+
 /** Read one immutable site-version manifest, or null. Never throws. */
 export async function readSiteVersion(
   get: KvGet,
@@ -108,12 +130,112 @@ export async function readSiteVersion(
   }
 }
 
+/** A manifest is BUILT (servable) when it exists AND materialized ≥1 artifact. */
+function isBuiltManifest(m: SiteVersionManifest | null): m is SiteVersionManifest {
+  return !!m && Object.keys(m.artifacts ?? {}).length > 0;
+}
+
+/**
+ * Read a tenant's version-history index (list of summaries), NEWEST first — the
+ * runtime read-side view of the same `siteVersionIndexKey` the KV store appends
+ * to (stored oldest-first). Never throws — malformed/absent → `[]`.
+ */
+export async function readSiteVersionIndex(
+  get: KvGet,
+  tenantId: string,
+): Promise<SiteVersionSummary[]> {
+  const raw = await get(siteVersionIndexKey(tenantId));
+  if (!raw) return [];
+  try {
+    return (JSON.parse(raw) as SiteVersionSummary[]).slice().reverse();
+  } catch {
+    return [];
+  }
+}
+
+/** The outcome of self-healing a channel pointer to a SERVABLE version. */
+export interface ServableChannelVersion {
+  /**
+   * The versionId to actually SERVE from: the pointed version when it is built,
+   * else the newest BUILT version in history (self-heal), else `null` (nothing
+   * built at all — the caller falls back to build-time, still never a bare 404).
+   */
+  versionId: string | null;
+  /** The versionId the channel pointer NAMES (may dangle at an unbuilt version). */
+  pointedVersionId: string | null;
+  /**
+   * True when the pointer named a version with no built manifest — so the read
+   * was self-healed onto an older built version (or found none). Signals the
+   * caller to enqueue a rebuild of the pointed version.
+   */
+  dangling: boolean;
+}
+
+/** Optional seam so a self-healing read can enqueue a rebuild of the dangling
+ *  version. Best-effort/fail-open: never awaited into the serve path, never
+ *  throws through it. Absent ⇒ pure resolution (no side effect). */
+export type EnqueueRebuild = (info: {
+  tenantId: string;
+  channel: ChannelName;
+  versionId: string;
+}) => void;
+
+/**
+ * Resolve the SERVABLE version for a channel, self-healing a dangling pointer.
+ *
+ * A channel pointer can name a version that was never built (or whose manifest
+ * was evicted). Serving that naively empties/404s the whole surface. Instead: if
+ * the pointed version has no built manifest, fall back to the newest version in
+ * history that DOES, and flag `dangling` so the caller can enqueue a rebuild.
+ * Only kicks in when the pointed
+ * manifest is entirely absent/unbuilt — a present manifest that merely omits one
+ * path stays authoritative (unchanged behavior). Reads fresh; never throws.
+ */
+export async function resolveServableChannelVersion(
+  get: KvGet,
+  tenantId: string,
+  channel: ChannelName,
+  enqueueRebuild?: EnqueueRebuild,
+): Promise<ServableChannelVersion> {
+  const pointedVersionId = await resolveChannelVersion(get, tenantId, channel);
+  if (!pointedVersionId) {
+    return { versionId: null, pointedVersionId: null, dangling: false };
+  }
+  const pointed = await readSiteVersion(get, tenantId, pointedVersionId);
+  if (isBuiltManifest(pointed)) {
+    return { versionId: pointedVersionId, pointedVersionId, dangling: false };
+  }
+  // Dangling: the pointer names an unbuilt/absent version. Self-heal onto the
+  // newest BUILT version in history so the surface keeps rendering last-good.
+  let healed: string | null = null;
+  for (const summary of await readSiteVersionIndex(get, tenantId)) {
+    if (summary.versionId === pointedVersionId) continue;
+    if (isBuiltManifest(await readSiteVersion(get, tenantId, summary.versionId))) {
+      healed = summary.versionId;
+      break;
+    }
+  }
+  if (enqueueRebuild) {
+    try {
+      enqueueRebuild({ tenantId, channel, versionId: pointedVersionId });
+    } catch {
+      /* fail-open: enqueue is best-effort, never breaks the read */
+    }
+  }
+  return { versionId: healed, pointedVersionId, dangling: true };
+}
+
 /**
  * Resolve a single artifact's content via the VERSIONED path:
  * channel → versionId → site-version manifest → content hash → bytes. Returns
  * null (so the caller falls back to build-time) when the tenant has no channel
- * pointer, the version manifest is missing, the path isn't in the snapshot, or
- * the content is gone. Never throws.
+ * pointer, the path isn't in the snapshot, or the content is gone. Never throws.
+ *
+ * Self-healing: when the channel pointer DANGLES (names an unbuilt/absent
+ * version), the artifact is read from the newest built version instead of
+ * returning null for every path — so a dangling `preview`/`live` pointer serves
+ * the last built site rather than 404ing the whole surface. See
+ * {@link resolveServableChannelVersion}.
  */
 export async function readVersionedArtifact(
   get: KvGet,
@@ -121,7 +243,7 @@ export async function readVersionedArtifact(
   channel: ChannelName,
   path: string,
 ): Promise<string | null> {
-  const versionId = await resolveChannelVersion(get, tenantId, channel);
+  const { versionId } = await resolveServableChannelVersion(get, tenantId, channel);
   if (!versionId) return null;
   const manifest = await readSiteVersion(get, tenantId, versionId);
   const contentHash = manifest?.artifacts?.[path];
@@ -163,3 +285,34 @@ export async function readPublishedArtifact(
   if (!versionId) return null;
   return get(customizationArtifactKey(tenantId, versionId));
 }
+
+/**
+ * List artifact paths in the immutable site version selected for `(tenant, env)`.
+ *
+ * `null` means the tenant/channel has not adopted versioned publishing, so a
+ * caller may use its local/legacy fallback. Once a channel pointer exists the
+ * manifest is authoritative and this returns an array (possibly empty). This is
+ * the enumeration companion to `readPublishedArtifact`: indexes, sitemaps, and
+ * collection routes can discover one tenant's content at request time without
+ * bundling every configured tenant into the framework Worker.
+ */
+export async function listPublishedArtifactPaths(
+  get: KvGet,
+  tenantId: string,
+  env: CustomizationEnv,
+  prefix = "",
+): Promise<string[] | null> {
+  const pointer = await readPointer(get, tenantId);
+  if (!pointer) return null;
+
+  const channel = channelFromEnv(env);
+  if (!pointer.channels?.[channel]) return null;
+
+  const { versionId } = await resolveServableChannelVersion(get, tenantId, channel);
+  if (!versionId) return [];
+  const manifest = await readSiteVersion(get, tenantId, versionId);
+  if (!manifest) return [];
+  return Object.keys(manifest.artifacts ?? {})
+    .filter((path) => path.startsWith(prefix))
+    .sort((a, b) => a.localeCompare(b));
+}

package/packages/public-runtime/src/customization-versioning.ts

@@ -37,6 +37,15 @@ export type ChannelPointers = Partial<Record<ChannelName, string>>;
  * - `channels`: the versioned-publish channel pointers (`live`/`preview` →
  *   a single site `versionId`). Additive + optional; when present it is
  *   authoritative for that channel and shadows the legacy selection.
+ * - `channelDigests`: (ADR 0012) the RECONCILED static-serving companion to
+ *   `channels`. For a static-publish tenant, `channels[ch]` still holds the site
+ *   `versionId` (the tenant Gitea commit sha — the hosted contract), while
+ *   `channelDigests[ch]` holds that same publish's bundle `treeDigest` (the
+ *   content-addressed R2 key prefix `versions/<digest>/` `static-bundle.ts`
+ *   reads). The two are DISTINCT namespaces — the Gitea sha is NOT the treeDigest
+ *   — and are written in the SAME CAS pointer write (`setChannel`), so they can
+ *   never drift. Absent for a hosted tenant (which only ever sets/reads
+ *   `channels`).
  * - `rev`: optimistic-concurrency token, incremented on every successful write.
  */
 export interface PointerRecord {
@@ -45,6 +54,7 @@ export interface PointerRecord {
   live: Selection;
   test: Selection;
   channels?: ChannelPointers;
+  channelDigests?: ChannelPointers;
 }
 
 export function emptyPointer(tenantId: string): PointerRecord {