@tokenoftrust/storefront-runner 1.4.0 → 1.4.2-rc.0

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 (u3): 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];

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 {

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

@@ -36,7 +36,14 @@ export * from "./raw-html-policy.js";
 export * from "./review-trust-proof.js";
 export * from "./compliance/index.js";
 export * from "./tenant-assets.js";
+export * from "./static-bundle.js";
 export * from "./binary-path.js";
 export * from "./hot-standby-readiness.js";
 export * from "./hash.js";
 export * from "./widget-postmessage.js";
+
+// Operational activity telemetry contract (card D0): the actor×action
+// ActivityEvent envelope, the allowlisted action catalog, and the default-deny
+// redaction contract. Pure types + pure functions; the store decision + cost
+// model live in the repo-root DECISIONS.md §8. See ./activity/README.md.
+export * from "./activity/index.js";

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

@@ -0,0 +1,357 @@
+/**
+ * Digest-addressed static-bundle serving (T2, ADR 0012 —
+ * `docs/architecture/decisions/0012-instant-static-rollback-pointer-substrate.md`),
+ * T6-aware (per-file content-addressed asset dedup,
+ * `docs/epics/proposed/storefront-instant-static-rollback.md` Addendum §A).
+ *
+ * Reads an already-materialized, already-staged static bundle
+ * (`scripts/publish/materialize-tenant.mjs` output, staged by
+ * `scripts/publish/stage-bundle.mjs` to `versions/<treeDigest>/…` PLUS the
+ * shared `assets/<sha256>` pool, T6) straight out of R2 and serves the bytes
+ * VERBATIM — no re-render, no per-request CSP-nonce middleware (the bundle
+ * carries one pinned nonce for its whole tree; see the ADR's "Consequences"
+ * section). This is the read half: the write path (what PUTs a bundle into this
+ * R2 bucket) is `scripts/publish/lib/r2-runner.mjs`, which stages every
+ * `versions/<digest>/` bundle at candidate-prebuild time. Every static-publish
+ * tenant's production reads are served through here.
+ *
+ * DIGEST CONTRACT (RECONCILED, T14 — ADR 0012): the caller resolves "what to
+ * serve" via `resolveChannelDigest(get, tenantId, "live")` — the `channelDigests`
+ * companion to the `live` channel pointer, NOT `resolveChannelVersion` (which
+ * returns the versionId / Gitea sha, a DIFFERENT namespace than the treeDigest).
+ * `gatedPromote` (go-live) and `rollbackCandidateAtomic` (rollback) write the
+ * staged bundle's real `treeDigest` to `channelDigests.live` in the SAME CAS flip
+ * that moves the versionId, so this module gets the exact R2 key prefix
+ * `versions/<treeDigest>/`. A static tenant whose `live` has a versionId but no
+ * digest companion yet resolves to `null` here and fails closed (see below)
+ * rather than serving the wrong bytes under the versionId.
+ *
+ * T6 KEY RESOLUTION (`kind: "route"` vs `kind: "asset"`, `scripts/publish/lib/
+ * asset-pool.mjs`'s classification, carried verbatim in `manifest.files`): the
+ * manifest is now read on EVERY request (not just HTML, as before T6) because
+ * it's the ONLY source of truth for which R2 key a bundle-relative path
+ * resolves to — `kind: "route"` files still live at `versions/<digest>/<rel>`
+ * (rendered fresh per version), `kind: "asset"` files live at the SHARED,
+ * content-addressed `assets/<sha256><ext>` pool (`staticBundleAssetPoolKey`,
+ * kept in lockstep with `scripts/publish/lib/asset-pool.mjs`'s `assetPoolKey`
+ * — that module can't be imported here, this is the Worker bundle, that one
+ * runs under plain node). A `rel` absent from `manifest.files` (a genuinely
+ * unexpected path, or a pre-T6 manifest with no `files` classification) falls
+ * back to the OLD `versions/<digest>/<rel>` lookup — fail-closed on a miss
+ * either way, never a guess.
+ */
+import { assetContentType } from "./tenant-assets.js";
+
+// ---------------------------------------------------------------------------
+// R2 seam — same structural subset tenant-assets.ts uses (no workers-types dep)
+// ---------------------------------------------------------------------------
+
+export interface StaticBundleR2ObjectLike {
+  body: ReadableStream<Uint8Array> | null;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  size?: number;
+}
+
+export interface StaticBundleR2BucketLike {
+  get(key: string): Promise<StaticBundleR2ObjectLike | null>;
+}
+
+// ---------------------------------------------------------------------------
+// Path mapping — request pathname -> bundle-relative object path
+// ---------------------------------------------------------------------------
+
+/**
+ * Reject empty, absolute-outside-bundle, or traversal-bearing relative paths
+ * (mirrors `tenant-assets.ts`'s `isSafeRel`, duplicated here to keep this
+ * module import-independent of the assets pointer model).
+ */
+function isSafeRel(rel: string): boolean {
+  if (!rel) return false;
+  return !rel.split("/").some((seg) => seg === ".." || seg === ".");
+}
+
+/**
+ * Map a request pathname to the bundle-relative file the materializer wrote
+ * for it — the SAME transform `scripts/publish/lib/materialize.mjs`'s
+ * `bundlePathForRoute` (routes) and `assetFilePath` (assets) apply, ported
+ * here as one pure function since `scripts/` is not importable from the
+ * Worker bundle:
+ *   "/"            -> "index.html"
+ *   "/about"       -> "about/index.html"   (directory-index for pretty URLs)
+ *   "/a/b/"        -> "a/b/index.html"
+ *   "/sitemap.xml" -> "sitemap.xml"        (a real file extension: as-is)
+ *   "/_astro/x.js" -> "_astro/x.js"        (asset: as-is)
+ * Returns null for an unsafe path (traversal, decode failure).
+ */
+export function staticBundleRelPath(pathname: string): string | null {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(pathname);
+  } catch {
+    return null;
+  }
+  const clean = decoded.replace(/^\/+/, "").replace(/\/+$/, "");
+  if (clean === "") return "index.html";
+  if (!isSafeRel(clean)) return null;
+  const last = clean.split("/").pop() || "";
+  if (/\.[a-z0-9]+$/i.test(last)) return clean;
+  return `${clean}/index.html`;
+}
+
+/** Full R2 object key for a `route`-kind bundle-relative path at a given digest. */
+export function staticBundleObjectKey(digest: string, rel: string): string {
+  return `versions/${digest}/${rel}`;
+}
+
+/** R2 key for a digest's bundle manifest (materialize-tenant.mjs's `manifest.json`). */
+export function staticBundleManifestKey(digest: string): string {
+  return `versions/${digest}/manifest.json`;
+}
+
+/**
+ * T6: the shared content-addressed pool key for one asset's hash — MUST stay
+ * in lockstep with `scripts/publish/lib/asset-pool.mjs`'s `assetPoolKey`
+ * (same extension-preserving `assets/<sha256hex><ext>` shape; that module
+ * can't be imported here since this is the Worker bundle and that one runs
+ * under plain node — both sides' tests assert the exact key shape).
+ */
+export function staticBundleAssetPoolKey(hash: string, rel: string): string {
+  const dot = rel.lastIndexOf(".");
+  const slash = rel.lastIndexOf("/");
+  const ext = dot > slash ? rel.slice(dot) : "";
+  return `assets/${hash}${ext}`;
+}
+
+/**
+ * Resolve the R2 key to fetch for a `rel` bundle path, using the manifest's
+ * T6 file classification: `kind: "asset"` -> the shared pool key (by content
+ * hash, NOT the version); anything else (`kind: "route"`, or `rel` absent
+ * from `files` entirely — a pre-T6 manifest, or a genuinely unlisted path) ->
+ * the per-version `versions/<digest>/<rel>` key, same as before T6.
+ */
+export function resolveStaticBundleObjectKey(
+  digest: string,
+  rel: string,
+  files: StaticBundleManifest["files"] | undefined,
+): string {
+  const entry = files?.[rel];
+  if (entry?.kind === "asset" && entry.hash) {
+    return staticBundleAssetPoolKey(entry.hash, rel);
+  }
+  return staticBundleObjectKey(digest, rel);
+}
+
+// ---------------------------------------------------------------------------
+// Manifest (CSP pinned-nonce header) — read once per hit for an HTML response
+// ---------------------------------------------------------------------------
+
+/** One `manifest.files` entry (T6, `scripts/publish/lib/asset-pool.mjs`'s `classifyBundleFiles` shape). */
+export interface StaticBundleFileEntry {
+  hash: string;
+  kind: "route" | "asset";
+}
+
+/** The slice of `materialize-tenant.mjs`'s manifest this read path needs. */
+export interface StaticBundleManifest {
+  treeDigest: string;
+  pinnedNonce: string;
+  csp: { headerName: string; value: string } | null;
+  /** 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>;
+}
+
+function parseManifest(raw: string): StaticBundleManifest | null {
+  try {
+    const m = JSON.parse(raw) as Partial<StaticBundleManifest>;
+    if (typeof m.treeDigest !== "string" || typeof m.pinnedNonce !== "string") return null;
+    const csp =
+      m.csp &&
+      typeof (m.csp as { headerName?: unknown }).headerName === "string" &&
+      typeof (m.csp as { value?: unknown }).value === "string"
+        ? (m.csp as { headerName: string; value: string })
+        : null;
+    let files: StaticBundleManifest["files"];
+    if (m.files && typeof m.files === "object") {
+      files = {};
+      for (const [rel, entry] of Object.entries(m.files as Record<string, unknown>)) {
+        const e = entry as Partial<StaticBundleFileEntry> | null;
+        if (
+          e &&
+          typeof e.hash === "string" &&
+          (e.kind === "route" || e.kind === "asset")
+        ) {
+          files[rel] = { hash: e.hash, kind: e.kind };
+        }
+      }
+    }
+    return { treeDigest: m.treeDigest, pinnedNonce: m.pinnedNonce, csp, files };
+  } catch {
+    return null;
+  }
+}
+
+/** Read+parse a digest's `manifest.json` from R2. Null on any miss/malformed data. */
+export async function readStaticBundleManifest(
+  bucket: StaticBundleR2BucketLike,
+  digest: string,
+): Promise<StaticBundleManifest | null> {
+  const object = await bucket.get(staticBundleManifestKey(digest));
+  if (!object) return null;
+  const text = new TextDecoder().decode(await object.arrayBuffer());
+  return parseManifest(text);
+}
+
+// ---------------------------------------------------------------------------
+// Serve — resolve digest, stream the object from R2, fail closed on a miss
+// ---------------------------------------------------------------------------
+
+export interface ServeStaticBundleDeps {
+  bucket: StaticBundleR2BucketLike;
+  /**
+   * The digest to serve, already resolved by the caller (typically
+   * `resolveChannelVersion(get, tenantId, "live")` — see the module
+   * docstring's DIGEST CONTRACT). `null` means "pointer-serving is on for
+   * this tenant but nothing is live yet" — fails closed, same as a missing
+   * object, per the ADR: this path is only ever reached for a confirmed
+   * pointer-serving tenant, so an unresolved digest is itself a fault, not a
+   * "fall through to SSR" signal.
+   */
+  digest: string | null;
+  /** Best-effort diagnostic sink (never throws, never blocks the response). */
+  onFailClosed?: (detail: string) => void;
+}
+
+/** Structured detail for the one fail-closed shape this module can produce. */
+export class StaticBundleUnavailableError extends Error {
+  readonly code = "static-bundle-unavailable" as const;
+  constructor(detail: string) {
+    super(detail);
+    this.name = "StaticBundleUnavailableError";
+  }
+}
+
+function failClosed(deps: ServeStaticBundleDeps, detail: string): Response {
+  try {
+    deps.onFailClosed?.(detail);
+  } catch {
+    /* diagnostic sink must never break the response path */
+  }
+  // 503, not a 200 masquerading as content and not a 404 (which would read as
+  // "this route doesn't exist" — it does, the bundle is just unreachable) and
+  // never an SSR fallthrough: this route is ONLY reached for a tenant
+  // confirmed to be on the pointer-serving model, so an unreadable bundle is
+  // an infra fault to surface (verify/monitoring), not a content gap.
+  return new Response("Static bundle unavailable", {
+    status: 503,
+    headers: {
+      "cache-control": "no-store",
+      "x-tot-static-bundle": "fail-closed",
+    },
+  });
+}
+
+/** 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";
+
+/**
+ * Serve `pathname` from the digest-addressed static bundle in R2.
+ *
+ * Returns `null` — the ONE "fall through to SSR" signal — when the manifest's
+ * `files` map proves `pathname` is not part of this bundle's static surface:
+ * app surfaces (/admin, /cockpit, checkout, …) share the tenant's host but are
+ * never materialized into a bundle, so the caller must render them. Only a
+ * manifest WITH `files` can prove non-membership; a pre-T6 manifest keeps the
+ * fetch-then-fail-closed path.
+ *
+ * Every OTHER outcome (hit, unsafe path, unresolved digest, missing manifest,
+ * missing object for a LISTED file) terminates the request here rather than
+ * falling through — a staged digest's listed route must never silently degrade
+ * into SSR (wrong/divergent bytes), per the ADR's fail-closed guidance.
+ *
+ * T6: the manifest is now read FIRST, on every request (not just HTML, as
+ * before T6) — it's the only source of truth for whether `rel` resolves to
+ * the per-version `versions/<digest>/<rel>` key or the shared content-addressed
+ * `assets/<sha256>` pool key (`resolveStaticBundleObjectKey`). A missing
+ * manifest fails closed the same way a missing object always has: the
+ * manifest is deliberately the LAST thing `stage-bundle.mjs` writes for a
+ * digest (see `s3-publish.mjs`'s `buildManifestPromoteStep`), so its absence
+ * means this digest was never fully staged — serving from it would be wrong
+ * before T6 too, this just makes the fail-closed check unconditional.
+ *
+ * On a hit, serves the R2 bytes VERBATIM with a Cache-Control keyed by the
+ * manifest's file `kind` (long-lived immutable for the shared `asset` pool —
+ * safe because the key itself is the content hash; short/revalidating for a
+ * `route` doc, rendered fresh per version at a STABLE, non-digest url) and,
+ * for an HTML response, the bundle's PINNED CSP header read back from the
+ * same manifest read — never the Worker's per-request nonce middleware, per
+ * the ADR's CSP-consequences note.
+ */
+export async function serveStaticBundle(
+  deps: ServeStaticBundleDeps,
+  pathname: string,
+): Promise<Response | null> {
+  const { bucket, digest } = deps;
+  if (!digest) {
+    return failClosed(deps, "pointer-serving tenant has no resolved live digest");
+  }
+
+  const rel = staticBundleRelPath(pathname);
+  if (!rel) {
+    return failClosed(deps, `unsafe/unparseable path: ${JSON.stringify(pathname)}`);
+  }
+
+  const manifest = await readStaticBundleManifest(bucket, digest);
+  if (!manifest) {
+    return failClosed(deps, `missing/unreadable manifest for digest ${digest}`);
+  }
+
+  const entry = manifest.files?.[rel];
+  if (manifest.files && !entry) {
+    // Provably not in this bundle's static surface — an app surface (/admin,
+    // /cockpit, …) or a route this version never materialized. SSR owns it.
+    return null;
+  }
+  const objectKey = resolveStaticBundleObjectKey(digest, rel, manifest.files);
+  const object = await bucket.get(objectKey);
+  if (!object) {
+    return failClosed(deps, `missing R2 object ${objectKey}`);
+  }
+
+  const isHtml = rel.endsWith(".html");
+  // T6 cache tier: use the manifest's `kind` classification when present.
+  // A pre-T6 manifest (no `files` at all) falls back to the ORIGINAL
+  // isHtml-based heuristic — every non-html path used to be treated as a
+  // long-cacheable asset, which this preserves exactly for an old bundle
+  // this Worker version might still encounter mid-rollout.
+  const cacheControl = entry
+    ? entry.kind === "asset"
+      ? ASSET_CACHE_CONTROL
+      : ROUTE_CACHE_CONTROL
+    : isHtml
+      ? ROUTE_CACHE_CONTROL
+      : ASSET_CACHE_CONTROL;
+  const headers: Record<string, string> = {
+    "content-type": assetContentType(rel),
+    // Cache-key-by-digest lives in the caller's edge-cache layer for `route`
+    // keys (versions/<digest>/<rel> is digest-scoped — a pointer flip is a
+    // clean cache miss on the NEW digest's keys, never a stale serve of the
+    // old one); `asset` keys are ADDITIONALLY digest-independent (content-
+    // addressed by hash), so they're safe to cache forever downstream too.
+    // This header governs downstream/browser caching of the STABLE URL:
+    "cache-control": cacheControl,
+    "x-tot-static-bundle": "hit",
+    "x-tot-static-bundle-digest": digest,
+  };
+
+  if (isHtml && manifest.csp) {
+    headers[manifest.csp.headerName] = manifest.csp.value;
+  }
+
+  if (typeof object.size === "number") {
+    headers["content-length"] = String(object.size);
+  }
+  const body: BodyInit = object.body ?? (await object.arrayBuffer());
+  return new Response(body, { status: 200, headers });
+}

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

@@ -392,6 +392,34 @@ export interface TenantConfig {
   features?: Partial<TenantFeatures>;
   /** Regulated-commerce affordances; undefined for unregulated tenants. */
   compliance?: ComplianceConfig;
+  /**
+   * Per-tenant newsletter compliance/sender config. Sourced when a digest is
+   * built and sent (the send pipeline is a later unit). Distinct from the
+   * {@link TenantFeatures} `newsletter` flag, which only gates the CAPTURE form:
+   * this object supplies the CAN-SPAM physical postal address rendered in every
+   * email footer, plus the sender identity. Absent for tenants that don't send a
+   * newsletter; a sender falls back to a platform default when a field is unset.
+   */
+  newsletter?: {
+    /**
+     * Physical postal mailing address rendered in every newsletter email footer
+     * (CAN-SPAM §5(a)(5) requirement). Plain text; multi-line allowed.
+     */
+    postalAddress: string;
+    /** Display name on the `From:` header; falls back to `displayName`. */
+    fromName?: string;
+    /** `Reply-To:` address for the newsletter; falls back to a platform default. */
+    replyTo?: string;
+    /**
+     * Verified sending address on the `From:` header, e.g.
+     * `the-build@mail.tokenoftrust.store`. MUST be an address on a domain that is
+     * SPF/DKIM/DMARC-verified with the ESP (Resend) — NOT the tenant's own store
+     * domain, which is not a verified sending domain and would fail alignment.
+     * Unset → the send path derives `<collection>@mail.tokenoftrust.store` (the
+     * shared verified domain). Override only to use a per-tenant verified sender.
+     */
+    fromAddress?: string;
+  };
   /**
    * Cart/checkout engine wiring (Track A). Present on commerce tenants
    * that have a checkout store; drives the loader + signed add-to-cart. The
@@ -426,14 +454,14 @@ export interface TenantConfig {
    */
   capabilities?: Partial<CapabilityConfig>;
   /**
-   * Static-publish target (T5, tokenoftrust-com-static-publish epic). This
-   * tenant's PUBLIC site is materialized to an external static host
-   * (S3/CloudFront) OFF the Worker and republished on go-live. A per-tenant
-   * PROPERTY, not a global dark flag: presence opts the tenant in (default ON);
-   * `enabled: false` opts back out without dropping the target coordinates. The
-   * dispatch credentials/coordinates live in env/secrets, NEVER here. `target` is
-   * an opaque, TARGET-NEUTRAL label (S3 now, R2 later) forwarded verbatim into the
-   * publish job so ONE reconcile publish-sink drives any target.
+   * Static-publish target. This tenant's PUBLIC site is served by the Worker+R2
+   * pointer/digest plane (ADR 0012): go-live and rollback are instant, in-request
+   * KV `live` pointer flips over an already-staged, content-addressed bundle in
+   * R2. A per-tenant PROPERTY, not a global dark flag: presence opts the tenant in
+   * (default ON); `enabled: false` opts back out without dropping the target
+   * coordinates. The dispatch credentials/coordinates live in env/secrets, NEVER
+   * here. `target` is an opaque, TARGET-NEUTRAL label forwarded verbatim into the
+   * background stage/publish job so ONE reconcile publish-sink drives any target.
    */
   staticPublish?: {
     /** Target-neutral label, e.g. "www-s3". Forwarded into the dispatch payload. */

package/scripts/build/copy-tenant-assets.mjs

@@ -16,12 +16,20 @@
  * Idempotent: it wipes+rewrites the destination on every run. `TENANT_ASSETS_DEST`
  * overrides the destination (used by tests / spikes).
  *
- * VERSIONED TENANTS (decision `assets-r2-versioned`): a tenant whose assets are
+ * VERSIONED TENANTS: a tenant whose assets are
  * served version-scoped from R2 (src/pages/tenants/[id]/[...path].ts) must NOT be
  * baked here — otherwise the static file would shadow the R2 route. Opt a tenant
  * out by adding a `tenants/<id>/.tot/assets-versioned` marker file, or by listing
  * its id in the `TENANT_ASSETS_VERSIONED` env (comma-separated). Non-versioned
- * tenants keep the baked path unchanged (back-compat).
+ * tenants are baked here.
+ *
+ * TENANT_ASSETS_BAKE_VERSIONED=1 overrides ALL of the above and bakes every
+ * tenant's public/ regardless of versioned-ness. Set by the STATIC-plane bundle
+ * build (scripts/publish/materialize-tenant.mjs): the S3/CloudFront static site
+ * has no R2 asset route — a bundle is self-contained by definition — so
+ * skipping a versioned tenant's assets there just produces a bundle whose pages
+ * reference files that don't exist. The Worker-plane build never sets this, so
+ * R2 shadowing semantics are unchanged there.
  */
 import { cp, mkdir, readdir, rm } from "node:fs/promises";
 import { existsSync } from "node:fs";
@@ -44,9 +52,11 @@ const versionedEnv = new Set(
     .map((s) => s.trim())
     .filter(Boolean),
 );
+const bakeVersioned = process.env.TENANT_ASSETS_BAKE_VERSIONED === "1";
 const isVersioned = (id) =>
-  versionedEnv.has(id) ||
-  existsSync(join(src, id, ".tot", "assets-versioned"));
+  !bakeVersioned &&
+  (versionedEnv.has(id) ||
+    existsSync(join(src, id, ".tot", "assets-versioned")));
 
 let copied = 0;
 let skipped = 0;

package/scripts/dev/ai-edit.mjs

@@ -15,7 +15,7 @@
  * `tot` CLI, so `~/.tot/credentials.json` is directly readable. No token
  * plumbing needed between the CLI and the dev server.
  *
- * Scope (decision `d2-resolved-inline-ai-scope`): content + theme.json ONLY.
+ * Scope: content + theme.json ONLY.
  * The MCP tool enforces this server-side; nothing here widens it.
  */
 import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from "node:fs";

package/scripts/dev/checkout-watch.mjs

@@ -35,8 +35,8 @@ export function resync(sourceRoot, targetRoot, rel) {
  * RELIABILITY-FIRST: defaults to an mtime POLL, not native `fs.watch`. Native watch
  * is event-driven but LOSSY on macOS — editors that save via write-temp-then-rename
  * (VS Code, vim, JetBrains, …) routinely deliver NO change event on the original
- * path, so the save silently fails to hot-reload (the 2026-07-14 "didn't reload"
- * report). The poll stat()s the tree on a short interval and never misses an edit.
+ * path, so the save silently fails to hot-reload. The poll stat()s the tree on a
+ * short interval and never misses an edit.
  *
  * Opt into event-driven native watch with TOT_DEV_NATIVE_WATCH=1 (it still falls
  * back to polling where recursive watch is unavailable, e.g. Linux). Dependency-free