@tokenoftrust/storefront-runner 0.1.0

package/apps/storefront/src/themes/tenants/index.ts

@@ -0,0 +1,51 @@
+/**
+ * Per-vendor theme registry.
+ *
+ * A tenant's theme override lives at the colocated repo-root path
+ * `tenants/<tenant_id>/theme.json` (a DeepPartial<ThemeTokens> — only the tokens
+ * you want to override; the reference theme fills the rest) and it's
+ * auto-discovered at build time. This is the seam the brand adopter targets: its
+ * `out/branding/<tenant>.theme.json` output is written to `tenants/<id>/theme.json`.
+ *
+ * Files may include documentation keys (`_vendor`, `_note`, `$schema`); those are
+ * stripped so only real tokens reach the theme merge.
+ *
+ * Depth: from src/themes/tenants/ the repo root is five levels up
+ * (tenants→themes→src→storefront→apps→root).
+ */
+import type { DeepPartial, ThemeTokens } from "@tot/public-runtime";
+
+const modules = import.meta.glob<Record<string, unknown>>(
+  "../../../../../tenants/*/theme.json",
+  {
+    eager: true,
+    import: "default",
+  },
+);
+
+function stripMeta(obj: Record<string, unknown>): DeepPartial<ThemeTokens> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (k.startsWith("_") || k.startsWith("$")) continue;
+    out[k] = v;
+  }
+  return out as DeepPartial<ThemeTokens>;
+}
+
+const THEMES: Record<string, DeepPartial<ThemeTokens>> = {};
+for (const [path, mod] of Object.entries(modules)) {
+  // Path looks like ".../tenants/<id>/theme.json" — the id is the dir segment.
+  const id = /\/tenants\/([^/]+)\/theme\.json$/.exec(path)?.[1];
+  if (!id) continue;
+  THEMES[id] = stripMeta(mod as Record<string, unknown>);
+}
+
+/** Theme-token overrides for a tenant, or {} if the vendor has no theme file. */
+export function getTenantTheme(tenantId: string): DeepPartial<ThemeTokens> {
+  return THEMES[tenantId] ?? {};
+}
+
+/** Tenant ids that ship a theme file (for diagnostics / listing). */
+export function tenantsWithThemes(): string[] {
+  return Object.keys(THEMES);
+}

package/apps/storefront/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "verbatimModuleSyntax": false,
+    "jsx": "react-jsx",
+    "jsxImportSource": "preact",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": [".astro/types.d.ts", "src/**/*", "*.config.mjs", "env.d.ts"],
+  "exclude": ["dist", "node_modules"]
+}

package/apps/storefront/vitest.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig } from "vitest/config";
+import { fileURLToPath } from "node:url";
+
+// Storefront unit tests — pure TS logic (tenant routing, search, query engine,
+// image-attr resolution, edge cache, etc.). We deliberately do NOT render .astro
+// components here: the Astro Container API needs Astro's Vite pipeline, whose
+// vite-plugin-head crashes under vitest@2 + astro@7 (configureServer reads an
+// undefined `ssr`). Render *logic* is extracted into testable modules instead
+// (e.g. lib/imageAttrs.ts), and rendered output is verified on a live preview.
+export default defineConfig({
+  // Mirror the `@` -> src alias from tsconfig so tests can import aliased modules
+  // (e.g. src/config/tenants.ts, which pulls the theme registry).
+  resolve: {
+    alias: {
+      "@": fileURLToPath(new URL("./src", import.meta.url)),
+    },
+  },
+  test: {
+    include: ["src/**/*.test.ts"],
+    environment: "node",
+  },
+});

package/apps/storefront/wrangler.toml

@@ -0,0 +1,175 @@
+# Cloudflare Workers config for the ToT storefront (Phase 1 scaffold).
+# Account/zone IDs and namespace IDs are PLACEHOLDERS — a human wires real
+# values before deploy (see README.md "Pointing at live infra").
+#
+# NOTE: the @astrojs/cloudflare v14 adapter (via @cloudflare/vite-plugin) OWNS
+# the worker entry ("main") — it generates dist/_worker.js at build time. We do
+# NOT set `main` here; doing so makes the vite plugin validate a path that does
+# not exist until after build. Bindings below are surfaced to the worker.
+
+name = "tot-storefront"
+compatibility_date = "2024-11-01"
+compatibility_flags = ["nodejs_compat"]
+account_id = "3e84256b846e0c0c8ef408d80126daac"
+workers_dev = true
+
+# --- Sessions -----------------------------------------------------------------
+# The adapter enables Astro sessions backed by Cloudflare KV via a "SESSION"
+# binding by default. Phase 1 does not use sessions (no cart/accounts), but the
+# binding must exist for build/deploy. Placeholder id.
+[[kv_namespaces]]
+binding = "SESSION"
+id = "REPLACE_WITH_SESSION_KV_NAMESPACE_ID"
+preview_id = "REPLACE_WITH_SESSION_KV_PREVIEW_ID"
+
+# --- Tenant config + catalog edge cache --------------------------------------
+# Phase 1 resolves tenants from a static map (src/config/tenants.ts). This KV
+# namespace is the migration path: per-tenant config + cached catalog reads
+# (stale-while-revalidate) live here once we go many-tenant.
+[[kv_namespaces]]
+binding = "TENANT_CACHE"
+id = "REPLACE_WITH_KV_NAMESPACE_ID"
+preview_id = "REPLACE_WITH_KV_PREVIEW_ID"
+
+# --- Rehosted product images -------------------------------------------------
+# ETL rehosts Shopify-CDN images here; the <Img> component swaps placeholders
+# for these URLs when CatalogImage.rehosted === true.
+[[r2_buckets]]
+binding = "PRODUCT_IMAGES"
+bucket_name = "tot-storefront-product-images"
+preview_bucket_name = "tot-storefront-product-images-preview"
+
+# --- Versioned tenant static assets ------------------------------------------
+# Tenant `public/**` (logo, CSS, binaries) served version-scoped from R2, keyed
+# `tenants/<id>/<versionId>/<rel>` — replaces the build-time copy-tenant-assets
+# baking for extracted/versioned tenants (decision `assets-r2-versioned`).
+# Served by src/pages/tenants/[id]/[...path].ts. Local `wrangler dev` binds a
+# miniflare R2; the real buckets are provisioned behind a human gate (no deploy
+# creates them here). preview_bucket_name backs `wrangler dev --remote=false`.
+[[r2_buckets]]
+binding = "TENANT_ASSETS"
+bucket_name = "tot-storefront-tenant-assets"
+preview_bucket_name = "tot-storefront-tenant-assets-preview"
+
+# --- Catalog edge read replica (D1) ------------------------------------------
+# The ETL emits catalog.sql (schema + rows + FTS5); load it with
+# `wrangler d1 execute CATALOG_DB --file out/catalog/<scope>/catalog.sql`. Reads
+# (search/facets/PDP) are served from D1 when USE_D1_CATALOG=1 — see
+# epics/edge-read-replica.md. Off by default; placeholder id until provisioned.
+[[d1_databases]]
+binding = "CATALOG_DB"
+database_name = "tot-storefront-catalog"
+database_id = "REPLACE_WITH_D1_DATABASE_ID"
+
+# Cloudflare for SaaS custom hostnames are configured at the zone level, not
+# here — Phase 1 ships one pilot subdomain. See DECISIONS.md.
+
+[observability]
+enabled = true
+
+[vars]
+# Non-secret defaults. Secrets (TOT_API_KEY etc.) come from `wrangler secret`
+# or .dev.vars locally — never commit them.
+PUBLIC_CF_ANALYTICS_TOKEN = "REPLACE_WITH_CF_WEB_ANALYTICS_TOKEN"
+
+# --- Preview environment (the live storefront.<subdomain>.workers.dev) --------
+# CI deploys this on merge to main (deploy.sh --env=preview). Resource ids are
+# wired from provision.sh output — ids are identifiers, not secrets; the only
+# secret (CLOUDFLARE_API_TOKEN) lives in GitHub Actions secrets. Named
+# environments do NOT inherit top-level bindings/vars, so KV/D1/vars are repeated
+# here; account_id, compatibility_*, observability, and workers_dev ARE inherited.
+# Mirrors the live `storefront` worker exactly: name override so it updates that
+# worker (not `tot-storefront-preview`), USE_D1_CATALOG=1 (edge-native read path),
+# and NO R2 binding (the live worker has none). Runtime secrets are set via
+# `wrangler secret` and persist across deploys — not declared here. Production is
+# deferred: wire [env.production] from production.generated.json when ready.
+[env.preview]
+name = "storefront"
+
+[[env.preview.kv_namespaces]]
+binding = "SESSION"
+id = "85a27218438b436db8b291c431afd0b2"
+
+[[env.preview.kv_namespaces]]
+binding = "TENANT_CACHE"
+id = "d1e2d38f32d44d0bba65f59d1c3ae908"
+
+[[env.preview.d1_databases]]
+binding = "CATALOG_DB"
+database_name = "tot-storefront-t-catalog"
+database_id = "a7bb6565-d23d-4581-a50a-ace5c12b4cba"
+
+# Versioned tenant static-asset bucket (named envs do NOT inherit the top-level
+# binding). Required for src/pages/tenants/[id]/[...path].ts to serve from R2 in
+# the live preview worker. Bucket provisioning is a human gate — CI does not
+# create R2 buckets; wire the real bucket_name before enabling versioned tenants.
+[[env.preview.r2_buckets]]
+binding = "TENANT_ASSETS"
+bucket_name = "tot-storefront-tenant-assets"
+preview_bucket_name = "tot-storefront-tenant-assets-preview"
+
+[env.preview.vars]
+PUBLIC_CF_ANALYTICS_TOKEN = "REPLACE_WITH_CF_WEB_ANALYTICS_TOKEN"
+# Site-wide maintenance kill-switch (src/lib/maintenance.ts). "1" serves a static
+# "Coming Soon" holding page for EVERY host + path, before tenant resolution or
+# any gate — the fail-safe lever to take the whole storefront offline. Back
+# online: set to "0" (or remove) and redeploy.
+MAINTENANCE_MODE = "0"
+# D1 edge catalog is opt-in but the preview D1 isn't seeded yet (CI doesn't seed
+# D1), so products 404 against it. Serve the bundled fixture snapshot (same source
+# localhost uses) for the demo; flip back to "1" once the D1 catalog is seeded.
+USE_D1_CATALOG = "0"
+# Demo access gate for named hosts. Two modes (src/lib/auth/loginGate.ts):
+#   DEMO_GATE_MODE = "password" (default) → Basic-Auth shared secret DEMO_GATE_PASSWORD
+#   DEMO_GATE_MODE = "login"              → real "Sign in with ToT" (email code → signed
+#                                           id_token, verified offline via JWKS)
+# CUTOVER (this branch): flip to "login". PRECONDITIONS before deploy, or the gate
+# fails CLOSED and locks out the demo:
+#   1. TOT_CORE_URL points at a live tot IdP serving /api/internal/access-code/{send,verify}
+#      + /api/.well-known/jwks.json  (proposed: qa.tokenoftrust.com — CONFIRM).
+#   2. Secrets set:  wrangler secret put TOT_API_KEY   --env preview
+#                    wrangler secret put TOT_SECRET_KEY --env preview   (requireSecretKey endpoints)
+#   3. tot20 has a grant roster for resource "bigdvapor.net" (else nobody can sign in).
+# Wildcard gate: EVERY tenant subdomain on these zones (present + future) plus
+# the shared path-prefix host and workers.dev host require login — no per-host
+# maintenance. `*.tokenoftrust.store` covers bigdvapor.tokenoftrust.store,
+# storefront.tokenoftrust.store (path-prefix), preview.*, etc. The image CDN
+# (cdn.tokenoftrust.store) is a no-worker carve-out route, so it never reaches
+# this middleware and is unaffected.
+# NB: the bare apex `tokenoftrust.store` is listed EXPLICITLY — the `*.` wildcard
+# matches subdomains only, so without this a path-prefix route like
+# `tokenoftrust.store/<tenant>/` would bypass the gate. The apex `/` still resolves
+# to the exempt home tenant (public); only its non-home tenant paths are gated.
+DEMO_GATE_HOSTS = "*.tokenoftrust.store,tokenoftrust.store,*.storefront.store,storefront.tokenoftrust.workers.dev"
+DEMO_GATE_MODE = "login"
+DEMO_GATE_REALM = "bigdvapor demo — enter the shared password"
+# tot IdP base for access-code + JWKS (HOST-ONLY; the code appends /api/... itself
+# — /api/internal/access-code/{federated-send,federated-verify}, /api/.well-known/
+# jwks.json, /api/clients/developerInvites). Do NOT add a /api suffix or every URL
+# doubles to /api/api/... (#8425 federated sign-in + dev-invite depend on this).
+TOT_CORE_URL = "https://qa.tokenoftrust.com"
+# Storefront's OWN app identity — the `aud` of tot20's federated multi-tenant
+# id_token (getFederatedVerifier pins aud to this). NON-secret. (#8425)
+STOREFRONT_APP_DOMAIN = "storefront.tokenoftrust.com"
+# Option-B MCP subject-capability writer — the FULL endpoint URL (used as-is by
+# recordDeveloperAppBinding, not a base). NON-secret. Its auth is the SECRET
+# MCP_SERVICE_SHARED_SECRET (wrangler secret; must match the tot-mcp side). (#8425)
+MCP_APP_BINDING_URL = "https://mcp.qa.tokenoftrust.com/internal/dev-access/subject-capability"
+# Forge/ShipLoop JSON-RPC endpoint for the storefront forge client. createForgeClient()'s
+# FetchTransport POSTs here DIRECTLY, so this is the FULL `POST /mcp` endpoint INCLUDING the
+# `/mcp` suffix (unlike TOT_CORE_URL, which is host-only and appends /api itself). Without it
+# createForgeClient() throws ForgeConfigError and the reconcile's evidence push-to-MCP
+# (reportPreviewEvidence, ADR 0010) silently no-ops → change_ready never sees a report.
+# NON-secret.
+MCP_BASE_URL = "https://mcp.qa.tokenoftrust.com/mcp"
+# FoxyCart cart/checkout (Track A). The store defaults to "tot-preview" (from the
+# tenant config) — the SHARED, ToT-owned test store (tot-preview.foxycart.com,
+# test mode, cart validation OFF for the unsigned demo). No override needed here
+# unless a different store is used per environment. Browse worker now lives on
+# tokenoftrust.store (native CF zone), so the FoxyCart branded checkout host is a
+# sibling under it — e.g. live = secure.tokenoftrust.store (CNAME → the live
+# FoxyCart store, DNS-only). Preview test checkout stays UNBRANDED on
+# tot-preview.foxycart.com. Merchant live = secure.<merchant>.com → their store.
+# Loader still loads from cdn.foxycart.com/<store>/.
+# FOXY_STORE_SUBDOMAIN = "tot-preview"
+# FOXY_STORE_DOMAIN = "secure.tokenoftrust.store"

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@tokenoftrust/storefront-runner",
+  "version": "0.1.0",
+  "license": "SEE LICENSE IN LICENSE",
+  "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
+  "packageManager": "pnpm@11.9.0",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "dev": "pnpm --filter @tot/storefront-runner dev",
+    "build": "pnpm --filter @tot/storefront-runner build",
+    "typecheck": "pnpm -r typecheck",
+    "depcruise": "pnpm --filter @tot/storefront-runner depcruise"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/packages/public-runtime/LICENSE

@@ -0,0 +1,58 @@
+Token of Trust Source-Available License — Local Development Only
+Version 1.0
+
+Copyright (c) 2026 Token of Trust, Inc. All rights reserved.
+
+1. DEFINITIONS
+   "Software" means this source code and any accompanying files in this
+   repository or distribution, including the storefront renderer runtime, the
+   `@tot/public-runtime` package, the storefront-runner distributable, and any
+   derivative works.
+   "Local Development" means running, building, and modifying the Software on a
+   machine you control, for the sole purpose of evaluating it or developing and
+   previewing your own tenant content against it. Serving the Software to any
+   third party, or over any public or shared network, is NOT Local Development.
+   "Token of Trust" means Token of Trust, Inc.
+
+2. GRANT (LOCAL DEVELOPMENT ONLY)
+   Subject to the terms below, Token of Trust grants you a personal,
+   non-exclusive, non-transferable, revocable license to use, copy, build, and
+   modify the Software SOLELY for Local Development.
+
+3. PERMISSION REQUIRED FOR EVERYTHING ELSE
+   Any use of the Software beyond Local Development requires the PRIOR WRITTEN
+   PERMISSION of Token of Trust. Without such permission you may NOT, in whole or
+   in part:
+   (a) deploy, host, serve, or otherwise run the Software in production or for
+       any third party, or on any public, staging, or shared/network-accessible
+       environment;
+   (b) use the Software for any commercial purpose or to provide a service to
+       others;
+   (c) distribute, publish, sublicense, sell, rent, lease, or otherwise make the
+       Software (or a derivative of it) available to any third party; or
+   (d) remove or obscure this license or the copyright notices.
+   To request permission, contact Token of Trust at legal@tokenoftrust.com.
+
+4. NO TRADEMARK LICENSE
+   This license grants no rights to the Token of Trust name, logos, or
+   trademarks.
+
+5. RESERVATION OF RIGHTS
+   All rights not expressly granted are reserved by Token of Trust. This is a
+   source-available license, not an open-source license; the Software is not
+   licensed under any OSI-approved license.
+
+6. TERMINATION
+   This license terminates automatically if you breach it. On termination you
+   must stop using the Software and destroy all copies in your possession.
+
+7. DISCLAIMER OF WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+8. LIMITATION OF LIABILITY
+   IN NO EVENT SHALL TOKEN OF TRUST BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM,
+   OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+   SOFTWARE.

package/packages/public-runtime/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@tot/public-runtime",
+  "version": "0.1.0",
+  "private": true,
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  }
+}

package/packages/public-runtime/src/binary-path.ts

@@ -0,0 +1,68 @@
+/**
+ * Binary-vs-text path classification — the SINGLE source of truth shared by the
+ * write side (seed's `buildSeedFiles`) and the read side (the Gitea read seam).
+ *
+ * The extraction/preview loop moves a tenant's files through two seams that MUST
+ * agree on what is binary, or a file's bytes round-trip differently on each side
+ * and binaries corrupt:
+ *
+ *   - WRITE: `customization-seed.ts#buildSeedFiles` base64-encodes binaries when
+ *     it materializes the colocated subtree into a flat Gitea-repo seed.
+ *   - READ:  `gitea-source.ts#createGiteaHttpSource().readContent` base64-encodes
+ *     binaries when it reads them back at a commit for the reconcile/assets sink.
+ *
+ * Keeping the extension set here (and importing it in both) guarantees the two
+ * seams classify identically. Runtime-portable (no `node:*`) so it is safe in the
+ * renderer, the Worker, the publish pipeline, and unit tests alike.
+ *
+ * SVG is intentionally TEXT (it is XML the verbatim-serve path can nonce-inject);
+ * CSS/JSON/HTML/JS/TXT/XML are text. Everything in the set below is opaque bytes.
+ */
+
+/**
+ * File extensions treated as BINARY (base64-encoded so raw bytes round-trip).
+ * Every other extension is emitted/read as UTF-8 text.
+ */
+export const BINARY_EXTENSIONS: ReadonlySet<string> = new Set([
+  // raster images
+  "png",
+  "jpg",
+  "jpeg",
+  "gif",
+  "webp",
+  "avif",
+  "ico",
+  "bmp",
+  "tiff",
+  "tif",
+  // fonts
+  "woff",
+  "woff2",
+  "ttf",
+  "otf",
+  "eot",
+  // media
+  "mp4",
+  "webm",
+  "mov",
+  "mp3",
+  "wav",
+  "ogg",
+  // docs / archives
+  "pdf",
+  "zip",
+  "gz",
+]);
+
+/** The lowercased extension of `path` (no leading dot), or "" when it has none. */
+export function extensionOf(path: string): string {
+  const dot = path.lastIndexOf(".");
+  const slash = path.lastIndexOf("/");
+  if (dot === -1 || dot < slash) return "";
+  return path.slice(dot + 1).toLowerCase();
+}
+
+/** True when `path` names a binary asset (base64), false for text. */
+export function isBinaryPath(path: string): boolean {
+  return BINARY_EXTENSIONS.has(extensionOf(path));
+}

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

@@ -0,0 +1,89 @@
+/**
+ * Tenant capability switches — config that travels with the PR (Track A/B).
+ *
+ * Three independently-toggleable capabilities:
+ *   - cartCheckout      — FoxyCart cart/checkout ("Powered by FoxyCart", Track A)
+ *   - ageVerification   — Token of Trust age/identity gate (21+ regulated)
+ *   - exciseTax         — excise tax collection at checkout (Track B, tot-foxycart)
+ *
+ * The source of truth is the tenant repo's `.tot/config.json` `capabilities`
+ * block — so a change is a code change that travels with a PR. Resolution is
+ * per-environment on the SAME published-artifact spine as theme/content:
+ *   localhost → working-tree config (ungated, HMR)
+ *   preview   → PR-head config reconciled to the `test` pointer
+ *   live      → the promoted config on the `live` pointer (evidence-gated promote)
+ * so each environment's capability state is independently pinned and a shared-env
+ * change is PR-gated by construction. `readPublishedArtifact(env, capabilities
+ * ArtifactPath)` overrides the build-time `TenantConfig.capabilities` default.
+ */
+import type { TenantConfig } from "./tenant.js";
+
+export interface CapabilityState {
+  enabled: boolean;
+}
+
+export interface CapabilityConfig {
+  /** FoxyCart cart/checkout: loader + signed add-to-cart. */
+  cartCheckout: CapabilityState;
+  /** Token of Trust age/identity verification (soft 21+ gate now; full ToT later). */
+  ageVerification: CapabilityState;
+  /** Excise tax collection at checkout (materialized in the FoxyCart cart). */
+  exciseTax: CapabilityState;
+}
+
+export type CapabilityKey = keyof CapabilityConfig;
+
+/** Stable capability order + labels for any surface that lists them. */
+export const CAPABILITY_KEYS: CapabilityKey[] = [
+  "cartCheckout",
+  "ageVerification",
+  "exciseTax",
+];
+
+/**
+ * Canonical published-artifact path for a tenant's capabilities. Same colocated
+ * `tenants/<id>/…` contract as theme/content, so the reconcile pipeline keys the
+ * KV artifact by it and the storefront reads it back per environment.
+ */
+export function capabilitiesArtifactPath(tenantId: string): string {
+  return `tenants/${tenantId}/capabilities.json`;
+}
+
+/**
+ * Resolve a tenant's effective capabilities: build-time `TenantConfig.capabilities`
+ * default (itself defaulted from siteType/compliance), then any per-environment
+ * published `override` layered on top. Undefined entries fall through, so a PR can
+ * flip ONE capability without restating the rest.
+ */
+export function resolveCapabilities(
+  tenant: Pick<TenantConfig, "capabilities" | "compliance" | "siteType">,
+  override?: Partial<CapabilityConfig> | null,
+): CapabilityConfig {
+  const c = tenant.capabilities;
+  const base: CapabilityConfig = {
+    // Commerce tenants get a cart by default; marketing tenants don't.
+    cartCheckout: {
+      enabled: c?.cartCheckout?.enabled ?? tenant.siteType !== "marketing",
+    },
+    // Regulated tenants (an age minimum) verify by default.
+    ageVerification: {
+      enabled: c?.ageVerification?.enabled ?? !!tenant.compliance?.minAge,
+    },
+    // Nicotine/vape tenants collect excise by default.
+    exciseTax: {
+      enabled: c?.exciseTax?.enabled ?? !!tenant.compliance?.nicotineWarning,
+    },
+  };
+  if (!override) return base;
+  return {
+    cartCheckout: {
+      enabled: override.cartCheckout?.enabled ?? base.cartCheckout.enabled,
+    },
+    ageVerification: {
+      enabled: override.ageVerification?.enabled ?? base.ageVerification.enabled,
+    },
+    exciseTax: {
+      enabled: override.exciseTax?.enabled ?? base.exciseTax.enabled,
+    },
+  };
+}

package/packages/public-runtime/src/catalog-api.ts

@@ -0,0 +1,81 @@
+/**
+ * Canonical catalog data contract (shared types). The tot20 HTTP catalog API has
+ * been retired — the storefront reads from a Cloudflare D1 edge replica — so these
+ * are now the in-process shapes shared across the catalog path:
+ *   - packages/migration  — the LOAD step's bulk-upsert result shape (counts/rows).
+ *   - apps/storefront      — the read clients' (D1 / fixture) list-query, facet,
+ *                            and list-response shapes.
+ *
+ * Tenant scoping is by `appDomain` (== TenantConfig.tot_data_scope).
+ */
+
+import type { CatalogCollection, CatalogProduct } from "./product.js";
+
+/** POST /api/catalog/products:bulkUpsert */
+export interface BulkUpsertProductsRequest {
+  appDomain?: string;
+  totApiKey?: string;
+  totSecretKey?: string;
+  products: CatalogProduct[];
+  /** When true, server skips records whose source_checksum is unchanged. */
+  incremental?: boolean;
+}
+
+export interface UpsertResultRow {
+  source_id: string;
+  handle: string;
+  action: "inserted" | "updated" | "skipped" | "error";
+  message?: string;
+}
+
+export interface BulkUpsertProductsResponse {
+  results: UpsertResultRow[];
+  counts: { inserted: number; updated: number; skipped: number; error: number };
+}
+
+/** POST /api/catalog/collections:bulkUpsert */
+export interface BulkUpsertCollectionsRequest {
+  appDomain?: string;
+  totApiKey?: string;
+  totSecretKey?: string;
+  collections: CatalogCollection[];
+  incremental?: boolean;
+}
+
+export interface BulkUpsertCollectionsResponse {
+  results: UpsertResultRow[];
+  counts: { inserted: number; updated: number; skipped: number; error: number };
+}
+
+/** GET /api/catalog/products  (list + facet, querystring-driven) */
+export interface ListProductsQuery {
+  collection?: string; // collection handle
+  sort?: "featured" | "price-asc" | "price-desc" | "newest" | "title-asc";
+  /** Facet filters: option name -> selected values. Encoded as repeated query params. */
+  filters?: Record<string, string[]>;
+  priceMin?: number;
+  priceMax?: number;
+  availability?: "in-stock" | "all";
+  tags?: string[];
+  page?: number;
+  pageSize?: number;
+  q?: string; // free-text search
+}
+
+export interface FacetValue {
+  value: string;
+  count: number;
+}
+
+export interface Facet {
+  name: string; // option name or "price"/"availability"/"tags"
+  values: FacetValue[];
+}
+
+export interface ListProductsResponse {
+  products: CatalogProduct[];
+  page: number;
+  pageSize: number;
+  total: number;
+  facets: Facet[];
+}