@tokenoftrust/storefront-runner 0.1.0

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

@@ -0,0 +1,157 @@
+/**
+ * Runtime read path for published customizations (store→app wiring). Resolves,
+ * for a tenant + environment, the content of a published artifact from a simple
+ * key/value store — so the `{ live, test }` pointer actually selects what the
+ * storefront serves (the live domain → `live`, a gated preview → `test`).
+ *
+ * Pure + dependency-free: the caller injects a `get(key) => Promise<string|null>`
+ * (Cloudflare KV in prod, MemoryKv in dev), keeping this module storage-agnostic
+ * and unit-testable. The app layer parses the returned string into the right
+ * shape (e.g. DeepPartial<ThemeTokens>) and falls back to the build-time artifact
+ * when nothing is published (so an un-customized tenant is unaffected).
+ */
+import {
+  channelFromEnv,
+  type ChannelName,
+  type PointerRecord,
+  type SiteVersionManifest,
+} from "./customization-versioning.js";
+import type { CustomizationEnv } from "./customization-preview.js";
+
+export type KvGet = (key: string) => Promise<string | null>;
+
+/** KV key layout for the customization store (mirrors the tenant-cache style). */
+export function customizationPointerKey(tenantId: string): string {
+  return `cust:pointer:${tenantId}`;
+}
+export function customizationArtifactKey(
+  tenantId: string,
+  versionId: string,
+): string {
+  return `cust:artifact:${tenantId}:${versionId}`;
+}
+/** KV key for one immutable site-version manifest. */
+export function siteVersionKey(tenantId: string, versionId: string): string {
+  return `cust:version:${tenantId}:${versionId}`;
+}
+/** KV key for a tenant's version-history index (list of summaries). */
+export function siteVersionIndexKey(tenantId: string): string {
+  return `cust:versions:${tenantId}`;
+}
+
+/**
+ * Canonical artifact path for a tenant's theme override.
+ *
+ * Colocated layout: a tenant IS the repo-root directory `tenants/<id>/`, so the
+ * theme lives at `tenants/<id>/theme.json`. The storefront's published-content
+ * read overlay (provider.ts) keys KV artifacts by this path.
+ */
+export function themeArtifactPath(tenantId: string): string {
+  return `tenants/${tenantId}/theme.json`;
+}
+
+/**
+ * Canonical artifact path for a tenant content file (e.g. "home.json"). Colocated
+ * under `tenants/<id>/content/` — see themeArtifactPath for the contract note.
+ */
+export function contentArtifactPath(tenantId: string, relative: string): string {
+  return `tenants/${tenantId}/content/${relative}`;
+}
+
+async function readPointer(
+  get: KvGet,
+  tenantId: string,
+): Promise<PointerRecord | null> {
+  const raw = await get(customizationPointerKey(tenantId));
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw) as PointerRecord;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The `versionId` a channel currently points at, or null when the tenant has no
+ * channel pointer (i.e. is still on the legacy per-path model). Reads the pointer
+ * fresh; never throws.
+ */
+export async function resolveChannelVersion(
+  get: KvGet,
+  tenantId: string,
+  channel: ChannelName,
+): Promise<string | null> {
+  const pointer = await readPointer(get, tenantId);
+  return pointer?.channels?.[channel] ?? null;
+}
+
+/** Read one immutable site-version manifest, or null. Never throws. */
+export async function readSiteVersion(
+  get: KvGet,
+  tenantId: string,
+  versionId: string,
+): Promise<SiteVersionManifest | null> {
+  const raw = await get(siteVersionKey(tenantId, versionId));
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw) as SiteVersionManifest;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 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.
+ */
+export async function readVersionedArtifact(
+  get: KvGet,
+  tenantId: string,
+  channel: ChannelName,
+  path: string,
+): Promise<string | null> {
+  const versionId = await resolveChannelVersion(get, tenantId, channel);
+  if (!versionId) return null;
+  const manifest = await readSiteVersion(get, tenantId, versionId);
+  const contentHash = manifest?.artifacts?.[path];
+  if (!contentHash) return null;
+  return get(customizationArtifactKey(tenantId, contentHash));
+}
+
+/**
+ * Read the published artifact content for (tenant, env, path), or null when
+ * nothing is published (no pointer, no selection for that path, or no stored
+ * content). Never throws on malformed data — returns null so the caller falls
+ * back to the build-time artifact.
+ *
+ * Resolution is versioned-first with a legacy fallback:
+ *   - If the tenant has a channel pointer for the resolved channel
+ *     (`channelFromEnv(env)`), resolve via the immutable site version. A channel
+ *     pointer is AUTHORITATIVE — if the snapshot omits this path we return null
+ *     (fall back to build-time), never the stale legacy selection.
+ *   - Otherwise fall back to the LEGACY per-artifact-path selection
+ *     (`pointer[env][path]`), so tenants not yet cut over are unaffected.
+ */
+export async function readPublishedArtifact(
+  get: KvGet,
+  tenantId: string,
+  env: CustomizationEnv,
+  path: string,
+): Promise<string | null> {
+  const pointer = await readPointer(get, tenantId);
+  if (!pointer) return null;
+
+  const channel = channelFromEnv(env);
+  if (pointer.channels?.[channel]) {
+    // Versioned model engaged for this channel — authoritative.
+    return readVersionedArtifact(get, tenantId, channel, path);
+  }
+
+  // Legacy per-path selection.
+  const versionId = pointer?.[env]?.[path];
+  if (!versionId) return null;
+  return get(customizationArtifactKey(tenantId, versionId));
+}

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

@@ -0,0 +1,64 @@
+/**
+ * Tenant browser-script vocabulary the renderer needs: the slot / strategy /
+ * isolation constants, the CSP hash helper, and the sandboxed widget iframe
+ * attributes the renderer draws (`components/WidgetFrame.astro`).
+ *
+ * Dependency-free + Workers-portable (Web Crypto, btoa).
+ */
+
+export const SCRIPT_SLOTS = [
+  "product.aside",
+  "home.section",
+  "global.footer",
+] as const;
+export const SCRIPT_STRATEGIES = ["defer", "on-idle", "on-interaction"] as const;
+export const SCRIPT_ISOLATIONS = ["sandbox", "inline"] as const;
+
+export type ScriptSlot = (typeof SCRIPT_SLOTS)[number];
+export type ScriptStrategy = (typeof SCRIPT_STRATEGIES)[number];
+export type ScriptIsolation = (typeof SCRIPT_ISOLATIONS)[number];
+
+export interface ScriptRegistration {
+  src: string;
+  slot: ScriptSlot;
+  strategy: ScriptStrategy;
+  isolation: ScriptIsolation;
+}
+
+/** The base64 `'sha256-…'` CSP source expression that pins this exact bundle. */
+export async function cspHash(content: string | Uint8Array): Promise<string> {
+  const bytes =
+    typeof content === "string" ? new TextEncoder().encode(content) : content;
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    bytes as unknown as BufferSource,
+  );
+  let bin = "";
+  for (const b of new Uint8Array(digest)) bin += String.fromCharCode(b);
+  return `'sha256-${btoa(bin)}'`;
+}
+
+/**
+ * Sandbox token list for tenant widgets: scripts only, **no
+ * `allow-same-origin`**. Omitting same-origin forces an opaque origin, so the
+ * widget is cross-origin to the page — it cannot read parent cookies/DOM, nor
+ * its own cookies/localStorage — even when served from the platform's own
+ * origin. That's why v1 needs no separate widget domain.
+ */
+export const WIDGET_SANDBOX = "allow-scripts";
+
+export interface WidgetFrameAttrs {
+  sandbox: string;
+  loading: "eager" | "lazy";
+  referrerpolicy: "no-referrer";
+}
+
+/** Iframe attributes for a sandboxed widget, derived from its load strategy. */
+export function widgetFrameAttrs(strategy: ScriptStrategy): WidgetFrameAttrs {
+  return {
+    sandbox: WIDGET_SANDBOX,
+    // "defer" loads with the page; idle/interaction defer to lazy (near-viewport).
+    loading: strategy === "defer" ? "eager" : "lazy",
+    referrerpolicy: "no-referrer",
+  };
+}

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

@@ -0,0 +1,95 @@
+/**
+ * Pointer/selection **types** for published customizations, as the storefront
+ * read path sees them: which content version is selected for `live` vs `test`,
+ * per artifact path. Types only — nothing here reads, writes, or mutates state.
+ */
+
+/** Metadata for one immutable, content-addressed artifact version. */
+export interface ArtifactVersion {
+  tenantId: string;
+  /** Repo-relative tenant-owned path (e.g. themes/tenants/<id>.theme.json). */
+  path: string;
+  /** Content-addressed id: sha256(content) hex. */
+  versionId: string;
+  size: number;
+  createdAt: string;
+}
+
+/** Which version of each artifact is selected for an environment. */
+export type Selection = Record<string, string>;
+
+/**
+ * A publish **channel**: the audience-facing surface a request resolves to.
+ * `live` is what production hosts serve; `preview` is what a gated preview host
+ * serves. (The middleware's `CustomizationEnv` "test" maps to the `preview`
+ * channel — see `channelFromEnv`.)
+ */
+export type ChannelName = "live" | "preview";
+
+/** Channel → versionId. Optional/partial: a channel may be unset. */
+export type ChannelPointers = Partial<Record<ChannelName, string>>;
+
+/**
+ * Per-tenant pointer record.
+ *
+ * - `live` / `test`: the LEGACY per-artifact-path selections (kept so tenants not
+ *   yet cut over to the versioned model resolve exactly as before).
+ * - `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.
+ * - `rev`: optimistic-concurrency token, incremented on every successful write.
+ */
+export interface PointerRecord {
+  tenantId: string;
+  rev: number;
+  live: Selection;
+  test: Selection;
+  channels?: ChannelPointers;
+}
+
+export function emptyPointer(tenantId: string): PointerRecord {
+  return { tenantId, rev: 0, live: {}, test: {} };
+}
+
+/**
+ * Map the middleware's customization env to a publish channel. Production hosts
+ * resolve `live` → `live`; a gated preview resolves `test` → `preview`.
+ */
+export function channelFromEnv(env: "live" | "test"): ChannelName {
+  return env === "live" ? "live" : "preview";
+}
+
+/**
+ * A reference to a tenant's public-asset bundle for a version. The asset lane
+ * stores the BYTES in R2 keyed by this same `versionId`; the site-version
+ * manifest carries only the reference (publish never writes asset bytes).
+ */
+export interface AssetBundleRef {
+  versionId: string;
+  count?: number;
+}
+
+/**
+ * An immutable, content-addressed snapshot of a tenant's whole site, keyed by a
+ * single `versionId` (a Gitea commit sha, or a content hash when there is no
+ * commit). `artifacts` maps each artifact path to the sha256 of its content; the
+ * bytes live at `cust:artifact:<tenant>:<contentHash>` (the existing, deduped
+ * content store). `assets` references the public-asset bundle (bytes owned by the
+ * asset lane's R2). A version is written once and never mutated.
+ */
+export interface SiteVersionManifest {
+  tenantId: string;
+  versionId: string;
+  source: "commit" | "hash";
+  createdAt: string;
+  artifacts: Record<string, string>;
+  assets?: AssetBundleRef;
+}
+
+/** Compact list-index entry for version history (KV has no cheap scan). */
+export interface SiteVersionSummary {
+  versionId: string;
+  source: "commit" | "hash";
+  createdAt: string;
+  artifactCount: number;
+}

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

@@ -0,0 +1,184 @@
+/**
+ * FoxyCart cart engine — renderer-safe helpers (Track A).
+ *
+ * The storefront's whole job as a FoxyCart front end is small: include Foxy's
+ * loader.js, and emit add-to-cart links/forms whose product name/value pairs are
+ * HMAC-signed with the store's "cart validation" secret so the price can't be
+ * tampered. This module builds the fields for a catalog variant and (in signed
+ * mode) signs them with WebCrypto HMAC-SHA256 — pure, dependency-free, and safe
+ * in both `astro dev` (Node 20) and the Cloudflare Worker runtime.
+ *
+ * The excise-tax line is NOT computed here — it materializes inside the FoxyCart
+ * cart via the store's pre-cart webhook + `tot_excise_tax` coupon (Track B, the
+ * tot-foxycart service). See docs / the excise-tax-checkout recipe.
+ *
+ * Signing reference (Foxy "HMAC product verification"):
+ *   hash = HMAC-SHA256( productcode + fieldname + fieldvalue , storeSecret )
+ *   link/form field name becomes `fieldname||hash` (value unchanged).
+ *   Editable fields (quantity) hash the value `--OPEN--` and emit
+ *   `fieldname||hash||open`. Cart-level params (cart, coupon, output, …) and
+ *   `h:`/`x:`/`__`/`utm_`-prefixed params are never signed.
+ */
+import type { CatalogProduct, CatalogVariant } from "./product.js";
+
+/**
+ * Per-tenant FoxyCart wiring. Public config only — the signing SECRET is never
+ * stored here (it's an env-injected Worker binding, resolved per request). In
+ * `unsigned-demo` mode there is no secret at all: links go to a demo store that
+ * has cart validation turned OFF, so a developer can run the full cart locally
+ * (and on our shared preview worker) with zero secrets.
+ */
+export interface FoxyCommerceConfig {
+  /** Foxy store subdomain, e.g. "tot-demo" → tot-demo.foxycart.com. */
+  storeSubDomain: string;
+  /**
+   * Full cart/checkout host. Defaults to `${storeSubDomain}.foxycart.com`; set
+   * when the store uses a branded checkout domain (e.g. secure.merchant.com).
+   */
+  storeDomain?: string;
+  /**
+   * "signed" (preview/live: cart validation ON, HMAC every field) or
+   * "unsigned-demo" (local/preview demo: validation OFF, no secret needed).
+   */
+  mode: "signed" | "unsigned-demo";
+}
+
+/** Resolved, request-scoped commerce facts stashed on `Astro.locals`. */
+export interface ResolvedFoxyCommerce extends FoxyCommerceConfig {
+  /** `https://<storeDomain>` — the loader + cart origin (for CSP + links). */
+  origin: string;
+  /** `https://<storeDomain>/cart` — the add-to-cart form action / cart link. */
+  cartUrl: string;
+  /** `https://cdn.foxycart.com/<storeSubDomain>/loader.js`. */
+  loaderSrc: string;
+}
+
+/** A single cart field before signing. `open` marks a user-editable field. */
+export interface CartField {
+  name: string;
+  value: string;
+  open?: boolean;
+}
+
+/** A cart field ready to render (name may carry the `||hash[||open]` suffix). */
+export interface RenderedCartField {
+  name: string;
+  value: string;
+}
+
+/**
+ * The add-to-cart payload for one variant, split so an island can render a form:
+ * `hidden` are fixed inputs; `quantityName` is the name to put on the visible
+ * quantity stepper (signed-and-`||open` in signed mode, plain "quantity" else).
+ */
+export interface VariantCartPayload {
+  hidden: RenderedCartField[];
+  quantityName: string;
+}
+
+const FOXY_HOST_SUFFIX = ".foxycart.com";
+
+/** Resolve the full request-scoped commerce facts from a tenant's config. */
+export function resolveFoxyCommerce(
+  config: FoxyCommerceConfig,
+): ResolvedFoxyCommerce {
+  const storeDomain =
+    config.storeDomain ?? `${config.storeSubDomain}${FOXY_HOST_SUFFIX}`;
+  const origin = `https://${storeDomain}`;
+  return {
+    ...config,
+    storeDomain,
+    origin,
+    cartUrl: `${origin}/cart`,
+    loaderSrc: `https://cdn.foxycart.com/${config.storeSubDomain}/loader.js`,
+  };
+}
+
+/**
+ * The raw (unsigned) cart fields for a variant: name, price, code, image, the
+ * variant's options, and an editable quantity. `code` is the Foxy "productcode"
+ * — the salt every other field is hashed against — so it must be stable per SKU.
+ */
+export function cartFieldsForVariant(
+  product: CatalogProduct,
+  variant: CatalogVariant,
+): { code: string; fields: CartField[] } {
+  const code = variant.sku && variant.sku.length ? variant.sku : variant.id;
+  const image = product.images.find((i) => i.id === variant.image_id)?.url ??
+    product.images[0]?.url;
+  const fields: CartField[] = [
+    { name: "name", value: variant.title || product.title },
+    { name: "price", value: variant.price.toFixed(2) },
+    { name: "code", value: code },
+    { name: "quantity", value: "1", open: true },
+  ];
+  if (image) fields.push({ name: "image", value: image });
+  // Variant options (Flavor, Nicotine strength, …) travel as product options so
+  // the cart line reflects the exact variant the shopper picked.
+  for (const [optName, optVal] of Object.entries(variant.option_values)) {
+    if (optName && optVal) fields.push({ name: optName, value: optVal });
+  }
+  return { code, fields };
+}
+
+/** Lowercase hex HMAC-SHA256(message) under `secret`, via WebCrypto. */
+async function hmacHex(secret: string, message: string): Promise<string> {
+  const enc = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    enc.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, enc.encode(message));
+  return [...new Uint8Array(sig)]
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/**
+ * Sign one field for product `code`. Editable fields hash the sentinel
+ * `--OPEN--` and gain the `||open` suffix so Foxy accepts a user-entered value.
+ */
+async function signField(
+  secret: string,
+  code: string,
+  field: CartField,
+): Promise<RenderedCartField> {
+  const valueToHash = field.open ? "--OPEN--" : field.value;
+  const hash = await hmacHex(secret, code + field.name + valueToHash);
+  const name = field.open
+    ? `${field.name}||${hash}||open`
+    : `${field.name}||${hash}`;
+  return { name, value: field.value };
+}
+
+/**
+ * Build the render-ready add-to-cart payload for a variant. In `unsigned-demo`
+ * mode fields pass through verbatim (no secret touched); in `signed` mode every
+ * field is HMAC-signed. Deterministic output → the signed form is edge-cacheable.
+ */
+export async function buildVariantCartPayload(
+  product: CatalogProduct,
+  variant: CatalogVariant,
+  opts: { mode: FoxyCommerceConfig["mode"]; secret?: string },
+): Promise<VariantCartPayload> {
+  const { code, fields } = cartFieldsForVariant(product, variant);
+  const signed = opts.mode === "signed";
+  if (signed && !opts.secret) {
+    throw new Error(
+      "buildVariantCartPayload: signed mode requires a cart secret",
+    );
+  }
+
+  const rendered: RenderedCartField[] = signed
+    ? await Promise.all(fields.map((f) => signField(opts.secret!, code, f)))
+    : fields.map((f) => ({ name: f.name, value: f.value }));
+
+  // Split the quantity field out: the island puts it on the visible stepper.
+  const qtyIdx = fields.findIndex((f) => f.name === "quantity");
+  const quantityName = rendered[qtyIdx]?.name ?? "quantity";
+  const hidden = rendered.filter((_, i) => i !== qtyIdx);
+  return { hidden, quantityName };
+}

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

@@ -0,0 +1,30 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// @tot/public-runtime — the PUBLIC, edge-shipped runtime model.
+//
+// Open-sourceable, renderer-safe surface. It ships into the Cloudflare Worker
+// (edge) bundle and is the public IP boundary, so it MUST stay node-free and MUST
+// NOT import @tot/private-controlplane. Machine-enforced by
+// scripts/playbooks/check-public-runtime-purity.sh (wired into `pnpm check`).
+//
+// Purpose + the public/private split, in full:
+//   docs/architecture/decisions/0008-public-private-runtime-split.md
+// ─────────────────────────────────────────────────────────────────────────────
+
+// The storefront renderer model: tenant + product + catalog types, the CSP
+// builder, the customization read/apply runtime, and the read-only pointer /
+// preview / script types the renderer needs. Read/apply only.
+export * from "./product.js";
+export * from "./tenant.js";
+export * from "./foxy.js";
+export * from "./capabilities.js";
+export * from "./catalog-api.js";
+export * from "./search.js";
+export * from "./catalog-d1.js";
+export * from "./csp.js";
+export * from "./customization-preview.js";
+export * from "./customization-runtime.js";
+export * from "./customization-versioning.js";
+export * from "./customization-scripts.js";
+export * from "./customization-reconcile.js";
+export * from "./tenant-assets.js";
+export * from "./binary-path.js";

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

@@ -0,0 +1,159 @@
+/**
+ * Canonical storefront catalog model.
+ *
+ * This is the SINGLE SOURCE OF TRUTH for the product shape that flows:
+ *   Shopify --(ETL transform)--> these types --(load)--> ToT catalog API
+ *   ToT catalog API --(ToTClient)--> these types --> Astro storefront
+ *
+ * Every record is tenant-scoped. Handles/slugs are unique PER TENANT.
+ *
+ * NOTE on grain: a Shopify "product" maps to one CatalogProduct with embedded
+ * variants/images/options. This is deliberately NOT the per-SKU grain of ToT's
+ * excise `excise_tax_product_by_app_domain` table — see DECISIONS.md
+ * ("ToT catalog store").
+ */
+
+export type ProductStatus = "active" | "draft" | "archived";
+
+export type Currency = string; // ISO 4217, e.g. "USD"
+
+export interface SourceRef {
+  /** Origin platform. Phase 1 is always "shopify". */
+  platform: "shopify";
+  /** Stable source id, e.g. Shopify legacyResourceId or gid. Upsert key. */
+  source_id: string;
+  /** Original handle/slug from the source platform (pre-collision-resolution). */
+  source_handle?: string;
+}
+
+export interface SeoFields {
+  title?: string;
+  description?: string;
+}
+
+export interface PriceRange {
+  min: number;
+  max: number;
+  currency: Currency;
+}
+
+export interface ProductOption {
+  name: string;
+  position: number;
+  values: string[];
+}
+
+export interface CatalogImage {
+  id: string;
+  /** Final URL after rehost (R2/Cloudflare Images) OR original Shopify CDN URL. */
+  url: string;
+  alt?: string;
+  position: number;
+  /** Intrinsic dimensions — required for responsive images + CLS-free layout. */
+  width?: number;
+  height?: number;
+  /** Variant ids (CatalogVariant.id) this image is associated with. */
+  variant_ids?: string[];
+  /** True if rehosted to our own storage; false if still pointing at Shopify CDN. */
+  rehosted?: boolean;
+}
+
+export interface Metafield {
+  namespace: string;
+  key: string;
+  value: string;
+  type?: string;
+}
+
+export interface InventoryState {
+  quantity?: number;
+  /** Shopify inventory policy: "deny" | "continue". */
+  policy?: string;
+  available: boolean;
+}
+
+export interface CatalogVariant {
+  tenant_id: string;
+  id: string; // stable internal id (tenant-unique)
+  product_id: string;
+  source: SourceRef;
+  sku?: string;
+  title: string;
+  price: number;
+  compare_at_price?: number;
+  currency: Currency;
+  /** Map of optionName -> chosen value, e.g. { "Color": "Black", "Size": "M" }. */
+  option_values: Record<string, string>;
+  inventory: InventoryState;
+  barcode?: string;
+  weight?: number;
+  weight_unit?: string;
+  position: number;
+  /** CatalogImage.id of the variant's featured image, if any. */
+  image_id?: string;
+}
+
+export interface CatalogProduct {
+  tenant_id: string;
+  /** Stable internal id (tenant-unique). */
+  id: string;
+  source: SourceRef;
+  /** Slug, unique per tenant. Primary read key for /products/<handle>. */
+  handle: string;
+  title: string;
+  description_html: string;
+  description_text: string;
+  vendor?: string;
+  product_type?: string;
+  tags: string[];
+  status: ProductStatus;
+  seo: SeoFields;
+  options: ProductOption[];
+  images: CatalogImage[];
+  variants: CatalogVariant[];
+  price_range: PriceRange;
+  /** Collection handles (or ids) this product belongs to. */
+  collections: string[];
+  metafields: Metafield[];
+  created_at: string; // ISO 8601
+  updated_at: string; // ISO 8601
+  migrated_at: string; // ISO 8601
+  /** Content hash for incremental sync / change detection. */
+  source_checksum: string;
+}
+
+/**
+ * A product review (full content), pulled from the merchant's reviews app
+ * (e.g. Stamped.io public widget API) during migration. The aggregate
+ * (count + average) also lives in product metafields; this is the per-review
+ * detail. Keyed to a product by handle in the reviews store.
+ */
+export interface Review {
+  author: string;
+  rating: number; // 1–5
+  title?: string;
+  body: string;
+  date?: string; // ISO 8601
+  verifiedBuyer?: boolean;
+}
+
+export interface CatalogCollection {
+  tenant_id: string;
+  id: string;
+  source: SourceRef;
+  handle: string;
+  title: string;
+  description_html?: string;
+  description_text?: string;
+  image?: CatalogImage;
+  seo: SeoFields;
+  /** Resolved product handles (Phase 1 resolves rules to a static membership list). */
+  product_handles: string[];
+  /** For smart collections, the original rule (kept for re-resolution / audit). */
+  rule?: Record<string, unknown>;
+  position?: number;
+  created_at: string;
+  updated_at: string;
+  migrated_at: string;
+  source_checksum: string;
+}