@tokenoftrust/storefront-runner 2.2.89 → 2.2.90

package/agency-kit/tools/lib/tot-repo-mappings.mjs

@@ -0,0 +1,153 @@
+/**
+ * `.tot/config.json` mapping resolution — the ONE reading of a store repo's
+ * declared layout, shared by every consumer: the hosted reconcile (preview,
+ * candidate, aggregate, publication), `tot dev`'s checkout graft, `tot validate`,
+ * the platform's materialize / asset-repair scripts, and this kit's
+ * `repair-tenant-config.mjs`. The platform imports this file from the kit.
+ *
+ * A mapping is `{ workspace, repo, kind }`:
+ *   - `workspace` — where the files physically live in the store repo. It is the
+ *     only source of truth for location; nothing assumes a `tenants/<id>/` layout
+ *     inside the store's own repo.
+ *   - `repo` — the storefront artifact target, `tenants/<segment>/<rel>`. Only
+ *     `<rel>` (the tenant-relative path: `theme.json`, `content/`, `public/`, …)
+ *     is read from it. The tenant namespace always comes from the CANONICAL
+ *     tenant id — the store's registered id hosted, the config's `tenant` locally
+ *     — never from `<segment>`, so a config whose segment disagrees with its
+ *     tenant id resolves identically on every surface.
+ *
+ * Pure and dependency-free so kit tools, platform `.mjs` scripts and TypeScript
+ * consumers (types in the adjacent `.d.mts`) all import it. The published CLI
+ * installs without the kit, so it ships a byte-identical copy that its own test
+ * suite holds equal to this file.
+ */
+
+/** Platform test tenants nest one level deeper: `tenants/e2e/<id>.e2e.test/`. */
+const TARGET_RE = /^tenants\/(?:e2e\/([^/]+\.e2e\.test)|([^/]+))(?:\/(.*))?$/;
+
+/**
+ * Split a declared mapping target into the tenant segment it names and the
+ * tenant-relative path it addresses. Null when the target is not under
+ * `tenants/<segment>/`, or when its relative part is not a clean path (empty,
+ * `.` or `..` segments) — such a target could address outside the tenant.
+ * A trailing `/` (tree target) is preserved on `rel`; the tenant root is `""`.
+ * @param {unknown} repo
+ * @returns {{ segment: string, rel: string } | null}
+ */
+export function parseMappingTarget(repo) {
+  if (typeof repo !== "string") return null;
+  const m = TARGET_RE.exec(repo);
+  if (!m) return null;
+  const segment = m[1] ?? m[2];
+  const rel = m[3] ?? "";
+  const parts = rel.replace(/\/$/, "").split("/");
+  if (rel && parts.some((p) => !p || p === "." || p === "..")) return null;
+  return { segment, rel };
+}
+
+/** The canonical artifact root for a tenant: `tenants/<tenantId>/`. */
+export function tenantArtifactRoot(tenantId) {
+  return `tenants/${tenantId}/`;
+}
+
+function asDir(path) {
+  return path === "" || path.endsWith("/") ? path : `${path}/`;
+}
+
+function mappingsOf(config) {
+  return Array.isArray(config?.mappings) ? config.mappings : [];
+}
+
+/**
+ * Map a tenant-repo path to its tenant-relative path (e.g. `content/home.json`).
+ * First match wins; a `file` mapping matches exactly, a `tree` mapping by prefix.
+ * Null when no mapping covers the path or the covering mapping's target is not
+ * a valid tenant target.
+ * @param {{ mappings?: unknown }} config
+ * @param {string} workspacePath
+ * @returns {string | null}
+ */
+export function mapWorkspaceToTenantRelative(config, workspacePath) {
+  for (const m of mappingsOf(config)) {
+    if (!m || typeof m !== "object" || typeof m.workspace !== "string") continue;
+    if (m.kind === "file") {
+      if (workspacePath !== m.workspace) continue;
+      const target = parseMappingTarget(m.repo);
+      return target ? target.rel : null;
+    }
+    if (m.kind === "tree") {
+      const ws = asDir(m.workspace);
+      if (!workspacePath.startsWith(ws)) continue;
+      const target = parseMappingTarget(m.repo);
+      return target ? asDir(target.rel) + workspacePath.slice(ws.length) : null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Map a tenant-repo path to its storefront artifact path under the CANONICAL
+ * tenant root (`tenants/<tenantId>/<rel>`). Null when unmapped.
+ * @param {{ mappings?: unknown }} config
+ * @param {string} tenantId
+ * @param {string} workspacePath
+ * @returns {string | null}
+ */
+export function mapWorkspaceToArtifact(config, tenantId, workspacePath) {
+  const rel = mapWorkspaceToTenantRelative(config, workspacePath);
+  return rel === null ? null : tenantArtifactRoot(tenantId) + rel;
+}
+
+/**
+ * The inverse: where a tenant-relative path (`theme.json`, `content`, `public`,
+ * `content/home.json`) lives in the tenant repo, per the declared mappings.
+ * Unmapped paths resolve to themselves — the flat checkout layout — so a
+ * consumer still finds files the mappings do not cover (and the config-coverage
+ * check reports the gap).
+ * @param {{ mappings?: unknown }} config
+ * @param {string} relPath tenant-relative, no leading `/`
+ * @returns {string}
+ */
+export function workspacePathForTenantRelative(config, relPath) {
+  const bare = relPath.replace(/\/$/, "");
+  for (const m of mappingsOf(config)) {
+    if (!m || typeof m !== "object" || typeof m.workspace !== "string") continue;
+    const target = parseMappingTarget(m.repo);
+    if (!target) continue;
+    const targetRel = target.rel.replace(/\/$/, "");
+    const ws = m.workspace.replace(/\/$/, "");
+    if (m.kind === "file") {
+      if (targetRel === bare) return ws;
+      continue;
+    }
+    if (m.kind !== "tree") continue;
+    if (targetRel === bare) return ws;
+    const prefix = asDir(targetRel);
+    if (bare.startsWith(prefix)) {
+      const rest = bare.slice(prefix.length);
+      return ws ? `${ws}/${rest}` : rest;
+    }
+  }
+  return bare;
+}
+
+/**
+ * Mappings whose declared target names a tenant segment other than the
+ * canonical tenant id. They still resolve correctly (the segment is never
+ * read); this exists so validators can tell the author the config disagrees
+ * with itself.
+ * @param {{ mappings?: unknown }} config
+ * @param {string} tenantId
+ * @returns {{ workspace: string, repo: string, segment: string }[]}
+ */
+export function foreignTenantSegments(config, tenantId) {
+  const out = [];
+  for (const m of mappingsOf(config)) {
+    if (!m || typeof m !== "object") continue;
+    const target = parseMappingTarget(m.repo);
+    if (target && target.segment !== tenantId) {
+      out.push({ workspace: String(m.workspace ?? ""), repo: m.repo, segment: target.segment });
+    }
+  }
+  return out;
+}

package/apps/storefront/src/config/devTenantSeed.ts

@@ -36,10 +36,10 @@ export interface DevTenantHints {
    */
   appDomain?: string;
   /**
-   * True when catalog fixtures for this tenant's data scope are committed on
-   * disk (the same `packages/migration/out/catalog/<scope>/` the FixtureToTClient
-   * reads). When true we serve a real COMMERCE tenant so /collections + /products
-   * render from them; when false we degrade to a marketing home (no catalog).
+   * True when the checkout has a catalog: its own `content/catalog/products/` files,
+   * or a grandfathered in-repo snapshot for its data scope. When true we serve a real
+   * COMMERCE tenant so /collections + /products render from it; when false we degrade
+   * to a marketing home (no catalog).
    */
   hasCatalog?: boolean;
   /**
@@ -117,8 +117,8 @@ export function synthesizeDevTenant(
 export interface DevTenantSeedOptions {
   /** Resolved appDomain for a slug tenant (from `.tot/config.json` scope). */
   scopeFor?: (id: string) => string | undefined;
-  /** Whether catalog fixtures are committed on disk for a given data scope. */
-  hasCatalog?: (scope: string) => boolean;
+  /** Whether the checkout `id` (data scope `scope`) has a catalog on disk. */
+  hasCatalog?: (scope: string, id: string) => boolean;
   /** The tenant's parsed `tenants/<id>/analytics.json`, or undefined when it has none. */
   analyticsFor?: (id: string) => unknown;
 }
@@ -147,7 +147,7 @@ export function devTenantsToSeed(
     seen.add(id);
     const appDomain = opts.scopeFor?.(id);
     const scope = appDomain ?? id;
-    const hasCatalog = opts.hasCatalog?.(scope) ?? false;
+    const hasCatalog = opts.hasCatalog?.(scope, id) ?? false;
     const analyticsRaw = opts.analyticsFor?.(id);
     out.push(synthesizeDevTenant(id, themeFor(id), { appDomain, hasCatalog, analyticsRaw }));
   }

package/apps/storefront/src/config/publicationSpaceRegistry.ts

@@ -14,6 +14,7 @@ const ROOT_SOURCES: Readonly<Record<string, PublicationSpaceSourceV1>> = {
   "verify.e2e.test": { forge: "fixture", repo: "verify.e2e.test", defaultBranch: "main" },
   "fixture.e2e.test": { forge: "fixture", repo: "fixture.e2e.test", defaultBranch: "main" },
   "chrome.e2e.test": { forge: "fixture", repo: "chrome.e2e.test", defaultBranch: "main" },
+  "catalog.e2e.test": { forge: "fixture", repo: "catalog.e2e.test", defaultBranch: "main" },
 };
 
 /** Node-safe publication topology authority shared by runtime config and CI composition. */

package/apps/storefront/src/config/resolver.ts

@@ -72,6 +72,23 @@ const catalogFixtureFiles = import.meta.glob(
   "../../../../packages/migration/out/catalog/*/products.json",
 );
 
+// A checkout's own catalog files (ADR 0033): `tot dev` grafts the store's
+// `content/catalog/` here, and the catalog reader serves them.
+const storeCatalogFiles = import.meta.glob([
+  "../../../../tenants/*/content/catalog/products/*.json",
+  "../../../../tenants/e2e/*/content/catalog/products/*.json",
+]);
+
+/** Tenant dir ids whose checkout carries its own catalog files. */
+function storeCatalogIds(): Set<string> {
+  const ids = new Set<string>();
+  for (const key of Object.keys(storeCatalogFiles)) {
+    const id = tenantIdFromPath(key);
+    if (id) ids.add(id);
+  }
+  return ids;
+}
+
 /** Data scopes (== out/catalog dir names) that have committed catalog fixtures. */
 function catalogScopes(): Set<string> {
   const scopes = new Set<string>();
@@ -120,13 +137,14 @@ function devFallbackResolver(): TenantResolver {
   if (!import.meta.env.DEV) return staticResolver;
   const staticIds = new Set(staticTenants.map((t) => t.tenant_id));
   const withCatalog = catalogScopes();
+  const withStoreCatalog = storeCatalogIds();
   const scopes = slugScopes();
   // The SAME tenant-owned analytics read the static registry uses; here it serves only
   // the tenants that have NO registry entry (see config/tenantAnalyticsFiles.ts).
   const analytics = tenantAnalyticsRawById();
   const dev = devTenantsToSeed(localTenantDirIds(), staticIds, getTenantTheme, {
     scopeFor: (id) => scopes.get(id),
-    hasCatalog: (scope) => withCatalog.has(scope),
+    hasCatalog: (scope, id) => withStoreCatalog.has(id) || withCatalog.has(scope),
     analyticsFor: (id) => analytics.get(id),
   });
   if (dev.length === 0) return staticResolver;

package/apps/storefront/src/lib/storyblok/provider.ts

@@ -81,6 +81,11 @@ export interface ContentProvider {
   readArtifact(relative: string): Promise<string | null>;
   /** Artifact paths relative to `content/`; null means use a legacy fallback. */
   listArtifactPaths(prefix?: string): Promise<string[] | null>;
+  /**
+   * True when each `readArtifact` is its own request-time store read (the KV-backed version
+   * providers), so a caller that reads many artifacts in one request budgets against it.
+   */
+  readonly perRequestArtifactReads?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -155,6 +160,23 @@ const artifactGlobs = import.meta.glob<string>([
   import: "default",
 });
 
+/**
+ * Glob keys by their `/tenants/…/<id>/content/<path>` tail, the form `readArtifact` asks for.
+ * A store's catalog is one artifact per product, so a page reads thousands of them; a linear
+ * scan of every key per read made a 3k-product page cost seconds.
+ */
+let artifactKeysByTail: Map<string, string> | undefined;
+function artifactKeyFor(tail: string): string | undefined {
+  if (!artifactKeysByTail) {
+    artifactKeysByTail = new Map();
+    for (const key of Object.keys(artifactGlobs)) {
+      const at = key.indexOf("/tenants/");
+      if (at >= 0) artifactKeysByTail.set(key.slice(at), key);
+    }
+  }
+  return artifactKeysByTail.get(tail);
+}
+
 const DEFAULT_SCOPE = "home";
 
 function pickContent<T>(
@@ -337,7 +359,7 @@ export class LocalContentProvider implements ContentProvider {
   async readArtifact(relative: string): Promise<string | null> {
     const normalized = relative.replace(/^\/+/, "");
     const marker = `${tenantDirSegment(this.scope)}content/${normalized}`;
-    const key = Object.keys(artifactGlobs).find((candidate) => candidate.endsWith(marker));
+    const key = artifactKeyFor(marker);
     return key ? artifactGlobs[key]!() : null;
   }
 
@@ -571,6 +593,7 @@ export interface ContentCustomization {
 }
 
 export class PublishedContentProvider implements ContentProvider {
+  readonly perRequestArtifactReads = true;
   constructor(
     private readonly base: ContentProvider,
     private readonly tenantId: string,
@@ -695,6 +718,7 @@ export class PublishedContentProvider implements ContentProvider {
 // ---------------------------------------------------------------------------
 
 export class VersionPinnedContentProvider implements ContentProvider {
+  readonly perRequestArtifactReads = true;
   constructor(
     private readonly base: ContentProvider,
     private readonly tenantId: string,

package/apps/storefront/src/lib/tot/ToTClient.ts

@@ -2,10 +2,11 @@
  * ToTClient — the storefront's SINGLE source of product truth.
  *
  * Two backends behind one interface:
- *   - D1ToTClient      — the Cloudflare D1 edge read replica (FTS5 search + SQL
- *                        facets), used when a CATALOG_DB binding is wired.
- *   - FixtureToTClient — reads packages/migration/out/catalog/*.json so the
- *                        whole site renders offline with no creds.
+ *   - D1ToTClient      — the D1 serving projection (FTS5 search + SQL facets), for a
+ *                        tenant that declares `catalog.serving: "d1"`.
+ *   - FixtureToTClient — an in-memory catalog: the store's own `content/catalog/`
+ *                        files (tenantCatalog.ts), or the grandfathered in-repo
+ *                        snapshot under packages/migration/out/catalog/<scope>/.
  *
  * Public listings (PLP/search/featured) MUST exclude non-active products. The
  * `trail-cap` fixture is a `draft` and is the canary: it must NOT appear on any
@@ -26,6 +27,7 @@ import { D1ToTClient } from "./d1Client.js";
 import { fromD1, type D1Like } from "../d1/catalog.js";
 import { buildSearchIndex, type SearchIndex } from "../search/index.js";
 import type { ToTClient } from "./totClientInterface.js";
+import { readTenantCatalogFiles, type CatalogArtifactSource } from "./tenantCatalog.js";
 
 // The contract lives in its own module so d1Client can implement it without a
 // circular edge back to this file (which imports D1ToTClient for the factory).
@@ -35,7 +37,7 @@ export type { ToTClient } from "./totClientInterface.js";
 const isActive = (p: CatalogProduct) => p.status === "active";
 
 // ---------------------------------------------------------------------------
-// FixtureToTClient — local JSON, used when no live catalog creds are present.
+// FixtureToTClient — an in-memory catalog (store files or the in-repo snapshot).
 // ---------------------------------------------------------------------------
 
 export class FixtureToTClient implements ToTClient {
@@ -109,7 +111,7 @@ export class FixtureToTClient implements ToTClient {
 }
 
 // ---------------------------------------------------------------------------
-// Factory — D1 edge replica when bound, else the bundled fixture snapshot.
+// Factory — the declared catalog serving artifact (ADR 0033).
 // ---------------------------------------------------------------------------
 
 type FixtureBundle = {
@@ -118,10 +120,9 @@ type FixtureBundle = {
   reviews: Record<string, Review[]>;
 };
 
-// Per-tenant fixtures live under out/catalog/<tot_data_scope>/. Vite resolves
-// these globs at build time and bundles every tenant's JSON, so the worker has
-// no runtime filesystem dependency. reviews.json is OPTIONAL (only present after
-// the migration's reviews step) — a tenant without it just gets {}.
+// The grandfathered in-repo snapshot: packages/migration/out/catalog/<tot_data_scope>/,
+// tracked only for the tenants in scripts/tenant/catalog-in-repo-exceptions.json (plus
+// the e2e scopes). Vite resolves these globs at build time. reviews.json is optional.
 const productGlobs = import.meta.glob<CatalogProduct[]>(
   "../../../../../packages/migration/out/catalog/*/products.json",
   { import: "default" },
@@ -162,16 +163,60 @@ async function loadFixtures(scope: string): Promise<FixtureBundle> {
   return bundle;
 }
 
+/**
+ * Resolves its backend on the first read, so a page that never touches the catalog
+ * (a blog post, an editorial page) never pays for — or fails on — reading it.
+ */
+class DeferredToTClient implements ToTClient {
+  private client?: Promise<ToTClient>;
+  constructor(private readonly load: () => Promise<ToTClient>) {}
+  private resolved(): Promise<ToTClient> {
+    this.client ??= this.load();
+    return this.client;
+  }
+  async listProducts(query?: ListProductsQuery) { return (await this.resolved()).listProducts(query); }
+  async getProductByHandle(handle: string) { return (await this.resolved()).getProductByHandle(handle); }
+  async listCollections() { return (await this.resolved()).listCollections(); }
+  async getCollectionByHandle(handle: string) { return (await this.resolved()).getCollectionByHandle(handle); }
+  async search(q: string, limit?: number) { return (await this.resolved()).search(q, limit); }
+  async getFeatured(limit?: number) { return (await this.resolved()).getFeatured(limit); }
+  async getAllActiveProducts() { return (await this.resolved()).getAllActiveProducts(); }
+  async getReviews(handle: string) { return (await this.resolved()).getReviews(handle); }
+}
+
+/**
+ * The tenant's catalog, selected by its declared `catalog.serving` (ADR 0033):
+ *
+ *   "d1"            the D1 serving projection. The caller supplies it only where a
+ *                   per-request D1 read is allowed (the control plane); a public or
+ *                   static render has none, so a d1 tenant refuses there rather than
+ *                   serving a different artifact.
+ *   "files"         (default) in order:
+ *                   1. the store's own `content/catalog/` files, read through `content`
+ *                      (the request's tenant content source);
+ *                   2. the grandfathered in-repo snapshot for `tot_data_scope`;
+ *                   3. an empty catalog.
+ */
 export async function createToTClient(
   tenant: TenantConfig,
   d1?: D1Like,
+  content?: CatalogArtifactSource,
 ): Promise<ToTClient> {
-  // Edge read replica: when a D1 binding is wired,
-  // serve reads from it (FTS5 search + SQL facets). Otherwise the bundled fixture
-  // snapshot renders the site offline. The tot20 HTTP catalog API has been retired,
-  // so the read path is fully edge-native.
-  if (d1) return new D1ToTClient(fromD1(d1));
-
-  const { products, collections, reviews } = await loadFixtures(tenant.tot_data_scope);
-  return new FixtureToTClient(products, collections, tenant.tot_data_scope, reviews);
+  if (tenant.catalog?.serving === "d1") {
+    if (d1) return new D1ToTClient(fromD1(d1));
+    return new DeferredToTClient(async () => {
+      throw new Error(
+        `catalog: ${tenant.tenant_id} declares catalog.serving: "d1", and this render has no ` +
+          `D1 serving projection (public and static renders never read D1 per request, ADR 0013).`,
+      );
+    });
+  }
+  return new DeferredToTClient(async () => {
+    const files = await readTenantCatalogFiles(tenant, content);
+    if (files) {
+      return new FixtureToTClient(files.products, files.collections, tenant.tot_data_scope);
+    }
+    const { products, collections, reviews } = await loadFixtures(tenant.tot_data_scope);
+    return new FixtureToTClient(products, collections, tenant.tot_data_scope, reviews);
+  });
 }

package/apps/storefront/src/lib/tot/tenantCatalog.ts

@@ -0,0 +1,126 @@
+/**
+ * The catalog reader for a store's own `content/catalog/` files (ADR 0033 "content,
+ * cold"). Reads through the SAME artifact source every other tenant content surface
+ * uses (`ContentProvider.readArtifact` / `listArtifactPaths`), so it follows the store's
+ * `.tot/config.json` content mapping and whichever version the request selected:
+ *
+ *   - hosted preview (Worker): the reconciled version manifest in KV, one read per file;
+ *   - static publish (both CDNs) and `tot dev`: the store's checkout as materialized
+ *     into the build (`LocalContentProvider`'s build-time globs).
+ *
+ * Parsing and validation are the kit's shared catalog module: one bad file refuses the
+ * whole catalog with every failing path named, never a partial catalog with a product
+ * silently missing.
+ */
+import type { CatalogCollection, CatalogProduct, TenantConfig } from "@tot/public-runtime";
+import {
+  CATALOG_ARTIFACT_PREFIX,
+  CatalogFileError,
+  readCatalogFiles,
+  type CatalogStore,
+} from "@tot/public-runtime/catalog-files";
+import { LocalContentProvider, type ContentProvider } from "../storyblok/provider.js";
+
+export type CatalogArtifactSource = Pick<
+  ContentProvider,
+  "readArtifact" | "listArtifactPaths" | "perRequestArtifactReads"
+>;
+
+export interface TenantCatalogFiles {
+  products: CatalogProduct[];
+  collections: CatalogCollection[];
+}
+
+/**
+ * The most catalog files one request may read from a per-request source. A Worker
+ * invocation may make 1,000 calls to KV and other bindings, and each artifact read is
+ * one of them; the rest of the budget is left to the page's other reads. Measured
+ * against a 2,959-product, 357-collection catalog (3,316 files, 44.6 MB at 13.4 KB per
+ * product, ~290 ms to validate): that store cannot be read file by file per request on
+ * the hosted preview, while `tot dev` and the static publish read it from the checkout.
+ */
+export const CATALOG_REQUEST_READ_BUDGET = 800;
+
+/**
+ * The selected source and its catalog paths. A source that cannot enumerate (`null`:
+ * no versioned manifest selected) yields to the store's build-time content, the same
+ * rule the blog and page indexes apply.
+ */
+async function catalogPaths(
+  tenant: TenantConfig,
+  content: CatalogArtifactSource | undefined,
+): Promise<{ source: CatalogArtifactSource; paths: string[] }> {
+  const listed = content ? await content.listArtifactPaths(CATALOG_ARTIFACT_PREFIX) : null;
+  if (content && listed !== null) return { source: content, paths: listed };
+  const local = new LocalContentProvider(tenant.tenant_id);
+  return { source: local, paths: await local.listArtifactPaths(CATALOG_ARTIFACT_PREFIX) };
+}
+
+/**
+ * A build-time source serves the same bytes to every page a build renders, so a parsed
+ * file is reused while its text is unchanged (a `tot dev` save changes the text). A
+ * static publish renders a page per product; without this each page re-validated the
+ * whole catalog.
+ */
+const parsedBuildFiles = new Map<string, { raw: string; catalog: TenantCatalogFiles }>();
+
+function readBuildCatalog(
+  tenantId: string,
+  entries: Array<{ path: string; raw: string | null }>,
+  store: CatalogStore,
+): TenantCatalogFiles {
+  const products: CatalogProduct[] = [];
+  const collections: CatalogCollection[] = [];
+  const failures: Array<{ path: string; issues: readonly string[] }> = [];
+  for (const entry of entries) {
+    const key = `${tenantId}\0${entry.path}`;
+    let catalog = parsedBuildFiles.get(key);
+    if (!catalog || catalog.raw !== entry.raw) {
+      try {
+        const parsed = readCatalogFiles([entry], store);
+        catalog = entry.raw === null ? undefined : { raw: entry.raw, catalog: parsed };
+        if (catalog) parsedBuildFiles.set(key, catalog);
+      } catch (error) {
+        if (!(error instanceof CatalogFileError)) throw error;
+        failures.push(...error.failures);
+        continue;
+      }
+    }
+    if (!catalog) continue;
+    products.push(...catalog.catalog.products);
+    collections.push(...catalog.catalog.collections);
+  }
+  if (failures.length > 0) throw new CatalogFileError(failures);
+  return { products, collections };
+}
+
+/**
+ * The store's catalog files, or null when it has none. Throws `CatalogFileError` naming
+ * every file that fails validation, and refuses a per-request source holding more files
+ * than `CATALOG_REQUEST_READ_BUDGET` before reading any of them.
+ */
+export async function readTenantCatalogFiles(
+  tenant: TenantConfig,
+  content: CatalogArtifactSource | undefined,
+): Promise<TenantCatalogFiles | null> {
+  const { source, paths } = await catalogPaths(tenant, content);
+  if (paths.length === 0) return null;
+
+  if (source.perRequestArtifactReads && paths.length > CATALOG_REQUEST_READ_BUDGET) {
+    throw new Error(
+      `catalog: ${tenant.tenant_id} has ${paths.length} files in content/catalog/, and the hosted ` +
+        `preview reads at most ${CATALOG_REQUEST_READ_BUDGET} catalog files per request (one read ` +
+        `each, inside the Worker's per-request limit). \`tot dev\` and the published site render ` +
+        `this catalog from the checkout.`,
+    );
+  }
+
+  const store: CatalogStore = {
+    tenantScope: tenant.tot_data_scope,
+    inventoryProvider: tenant.inventory?.provider,
+  };
+  const entries = await Promise.all(paths.map(async (path) => ({ path, raw: await source.readArtifact(path) })));
+  return source.perRequestArtifactReads
+    ? readCatalogFiles(entries, store)
+    : readBuildCatalog(tenant.tenant_id, entries, store);
+}

package/apps/storefront/src/middleware/controlPlane.ts

@@ -263,12 +263,12 @@ export async function serveControlPlane(input: ControlPlaneInput): Promise<Respo
     publicationBucket: input.publicationBucket,
     managedIntegrationDeclarations,
     readTenantConsentSnapshot: () => readSavedConsentSnapshot(tenant.tenant_id),
-    // The D1 catalog edge read replica, when this deploy opts into it. Deferred to
-    // the chain's own catalog build so a request the static bundle or the edge
-    // cache answers never pays for it. The public branch never resolves it at all
-    // — see `publicRender`.
+    // The D1 catalog serving projection, for a tenant that declares
+    // `catalog.serving: "d1"` (ADR 0033). Deferred to the chain's own catalog build
+    // so a request the static bundle or the edge cache answers never pays for it.
+    // The public branch never resolves it at all — see `publicRender`.
     readCatalogD1: async (): Promise<D1Like | undefined> =>
-      (await readEnv("USE_D1_CATALOG")) === "1" ? await readD1("CATALOG_DB") : undefined,
+      tenant.catalog?.serving === "d1" ? await readD1("CATALOG_DB") : undefined,
     internalContentGrant: input.internalContentGrant,
   });
 }

package/apps/storefront/src/middleware/renderChain.ts

@@ -441,16 +441,6 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
     if (hit) return await stampResponseNonce(hit, freshNonce());
   }
 
-  // Catalog source selection (docs/architecture/product-catalog.md).
-  // A store's product source graduates over its life: JSON fixtures (dev default) ->
-  // D1 edge replica (staging) -> hosted ToT catalog (go-live). The read backend is
-  // chosen by the CALLER: the control plane resolves the D1 edge replica when
-  // USE_D1_CATALOG=1; the public branch never does, so `createToTClient` falls back
-  // to the bundled JSON fixture snapshot. The hosted catalog graduates the SAME
-  // canonical records into the D1 read model (emitCatalogSql), so JSON/D1/hosted
-  // render identically — pinned by lib/tot/sourceSelection.test.ts.
-  const tot = await createToTClient(tenant, await input.readCatalogD1?.());
-
   const proto = url.protocol === "http:" ? "http" : "https";
   // Canonical base uses the tenant's canonical domain in prod; for local dev we
   // keep the actual host (plus any /<domain> base path) so links resolve.
@@ -468,7 +458,19 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // pointer, the artifact is resolved through the immutable site version
   // (channel -> versionId -> manifest -> content). Tenants with no channel
   // pointer fall back to the legacy per-path selection — no behavior change.
-  const kvGet = kv ? (key: string) => kv.get(key) : async () => null;
+  // Request-scoped read memo: every content read resolves the same pointer and
+  // version manifest, and a catalog render reads one artifact per catalog file.
+  const kvReads = new Map<string, Promise<string | null>>();
+  const kvGet = kv
+    ? (key: string) => {
+        let read = kvReads.get(key);
+        if (!read) {
+          read = kv.get(key);
+          kvReads.set(key, read);
+        }
+        return read;
+      }
+    : async () => null;
 
   // Self-heal a DANGLING channel pointer: the pointer for this env's channel may
   // name a version that was never built (or whose manifest was evicted).
@@ -600,7 +602,6 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
       ? await resolveTenantCommerce(tenant)
       : null;
   locals.commerce = commerce ?? undefined;
-  locals.tot = tot;
   // Resolve the shared root adapter first. An opened publication version then
   // becomes authoritative for selected content while a mounted space may still
   // reuse root-owned chrome. Neither source falls through to another space.
@@ -624,6 +625,12 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
       kvGet,
     );
   }
+  // Catalog serving is declared per tenant (`catalog.serving`, ADR 0033 and
+  // docs/architecture/product-catalog.md). The store's own `content/catalog/` files
+  // are read through the SAME content source just resolved, so they follow the
+  // request's selected version exactly as pages and the blog do. Only the control
+  // plane supplies the D1 projection; the public branch never reads D1.
+  locals.tot = await createToTClient(tenant, await input.readCatalogD1?.(), locals.content);
   locals.themeStyle = themeToCssVars(theme);
   locals.canonicalBase = canonicalBase;
   locals.customizationEnv = customization.env;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.2.89",
+  "version": "2.2.90",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/package.json

@@ -17,6 +17,7 @@
     "./image-preview-rewrite-overlay": "./src/image-preview-rewrite-overlay.ts",
     "./hosted-image-media-types": "./src/hosted-image-media-types.ts",
     "./durable-assets": "./src/durable-assets.ts",
+    "./catalog-files": "./src/catalog-files.ts",
     "./retention-holds": "./src/retention-holds.ts",
     "./tenant-embed-defaults": "./src/tenant-embed-defaults.mjs",
     "./declared-tenant-config": "./src/declared-tenant-config.mjs",