@tokenoftrust/storefront-runner 1.3.2

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

@@ -0,0 +1,136 @@
+/**
+ * Order READ DTO — the FROZEN v1 contract shape the storefront consumes from
+ * tot-foxycart's `GET /commerce/orders[/:orderId]` (card 8585 / U1). Kept in
+ * `@tot/public-runtime` (types only, no secrets, edge-safe) so the server-side
+ * order client (U2), the Orders admin route (U2), and the view-model mapping (U3)
+ * all code against one source of truth.
+ *
+ * Authoritative spec: `docs/storefront-foxycart-contract.md` §9 (tot-foxycart).
+ *
+ * READ-ONLY (scope-locks): no write/mutation shapes here. Two fields are
+ * ENRICHED-later by U4 (the tot20 identity/age join) and are `null`/`[]` until
+ * then — `verification` (summary) and `verificationDetail` (detail). Consumers
+ * MUST tolerate that (render risk "pending", readiness/evidence empty) so no
+ * contract change is needed when U4 lands.
+ */
+
+/** Payment state of an order. */
+export type FoxyOrderPayment = "authorized" | "captured" | "refunded";
+
+/** Fulfillment / queue state of an order. */
+export type FoxyOrderFulfillment =
+  | "unfulfilled"
+  | "ready_to_ship"
+  | "hold_review_required"
+  | "completed";
+
+export interface FoxyOrderCustomer {
+  /** ToT-core customer id, or null for a guest / unlinked order. */
+  id: string | null;
+  name: string;
+}
+
+/** A row in the orders list. All fields populated by U1 EXCEPT `verification`. */
+export interface FoxyOrderSummary {
+  /** Order / transaction id (string). */
+  id: string;
+  /** ISO 8601 placed-at timestamp. */
+  placedAt: string;
+  currency: string;
+  customer: FoxyOrderCustomer;
+  /** Human one-liner, e.g. "Vape Pen Starter Kit +1 more". */
+  itemsSummary: string;
+  itemCount: number;
+  /** Order total in MAJOR currency units (e.g. dollars). */
+  total: number;
+  payment: FoxyOrderPayment;
+  fulfillment: FoxyOrderFulfillment;
+  /** Why the order is held, or null. */
+  blocker: string | null;
+  /**
+   * Identity/age verification summary — ENRICHED by U4 (tot20 join). `null` from
+   * U1; consumers render risk as "pending" until it is filled.
+   */
+  verification: FoxyOrderVerification | null;
+}
+
+/** U4-filled verification summary (shape reserved; opaque to U1/U2/U3). */
+export interface FoxyOrderVerification {
+  riskLevel?: string;
+  [k: string]: unknown;
+}
+
+export interface FoxyOrderLineItem {
+  sku: string;
+  name: string;
+  quantity: number;
+  /** Unit price in MAJOR currency units. */
+  unitPrice: number;
+}
+
+export interface FoxyOrderTotals {
+  subtotal: number;
+  shipping: number;
+  estimatedTax: number;
+  taxesAndFees: number;
+  total: number;
+}
+
+export interface FoxyOrderShippingAddress {
+  line1: string;
+  line2: string;
+  city: string;
+  region: string;
+  postalCode: string;
+  country: string;
+  name: string;
+}
+
+/** U4-filled per-order verification detail; `readinessChecks`/`evidenceTimeline` empty from U1. */
+export interface FoxyOrderVerificationDetail {
+  readinessChecks: unknown[];
+  evidenceTimeline: unknown[];
+}
+
+/** A single order's full detail (summary + line items, totals, address, verification detail). */
+export interface FoxyOrderDetail extends FoxyOrderSummary {
+  /** The excise line (TOT_EXCISE_TAX) is NOT here — it surfaces in totals.taxesAndFees. */
+  lineItems: FoxyOrderLineItem[];
+  totals: FoxyOrderTotals;
+  shippingAddress: FoxyOrderShippingAddress | null;
+  verificationDetail: FoxyOrderVerificationDetail;
+}
+
+export interface FoxyOrderPage {
+  limit: number;
+  cursor: string | null;
+  /** Opaque cursor for the next page, or null on the last page. */
+  nextCursor: string | null;
+  /** Total matching orders when the source can count, else null. */
+  total: number | null;
+}
+
+/** `GET /commerce/orders` response envelope. */
+export interface FoxyOrderListResponse {
+  orders: FoxyOrderSummary[];
+  page: FoxyOrderPage;
+}
+
+/** `GET /commerce/orders/:orderId` response envelope. */
+export interface FoxyOrderDetailResponse {
+  order: FoxyOrderDetail;
+}
+
+/** Optional list filters (all server-side; see contract §9). */
+export interface FoxyOrderListFilters {
+  queue?: string;
+  status?: string;
+  /** ISO datetime lower bound. */
+  from?: string;
+  /** ISO datetime upper bound. */
+  to?: string;
+  /** 1–100; server defaults to 25. */
+  limit?: number;
+  /** Opaque cursor from a prior page's `nextCursor`. */
+  cursor?: string;
+}

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

@@ -0,0 +1,196 @@
+/**
+ * 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";
+  /**
+   * Optional per-tenant CSS to brand Foxy's sidecart. Foxy's v2.0 sidecart
+   * renders into our own page DOM (root `#fc`, light DOM — no iframe/shadow), so
+   * it inherits the theme's CSS custom properties and can be restyled with plain
+   * CSS. `<FoxySidecartStyles>` already emits a brand baseline derived from the
+   * theme tokens; this string is APPENDED after it for bespoke overrides. Scope
+   * every rule under `#fc` and use `!important` to beat Foxy's own
+   * responsive_styles.css (it loads after our <head> style). NB: this styles the
+   * in-page sidecart only — the hosted checkout page is a separate origin,
+   * themed in the Foxy admin template.
+   */
+  sidecartCss?: string;
+}
+
+/** 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/hot-standby-readiness.ts

@@ -0,0 +1,140 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Hot Standby readiness contract (hsby-A2, epic #8600).
+//
+// The machine-readable shape every Hot Standby surface shares: the sync report
+// (hsby-B3) and preview/evidence/grants/commerce producers each write their own
+// section; the merchant/staff dashboard (hsby-F1) and the Go scorecard feed
+// (hsby-F3/H3) render and export it. Contract semantics, hard rules (never
+// fabricate; unknown ≠ a guessed value; every blocker has a DRI), and the
+// versioning policy: docs/hot-standby-readiness-contract.md.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Worst-first order matters: see overallReadinessState(). */
+export type ReadinessState =
+  | "unknown"
+  | "blocked"
+  | "pending"
+  | "in_progress"
+  | "ready";
+
+export type ReadinessArea =
+  | "catalog_sync"
+  | "content_theme"
+  | "preview"
+  | "compliance_evidence"
+  | "developer_access"
+  | "commerce_cutover";
+
+export interface ReadinessBlocker {
+  /** Stable slug, e.g. "sample-store-missing-shopify-token". */
+  id: string;
+  area: ReadinessArea;
+  summary: string;
+  /** Named owner (person or role). A blocker without a DRI is invalid. */
+  dri: string;
+  /** ISO date the blocker was recorded. */
+  since: string;
+}
+
+export interface CatalogSyncStatus {
+  state: ReadinessState;
+  /** ISO timestamp of the last successful sync; null if never synced. */
+  lastSuccessAt: string | null;
+  sourcePlatform: "shopify" | "custom" | "other";
+  /** Opaque incremental-sync marker (source cursor); null before first sync. */
+  sourceMarker: string | null;
+  /** EA starts on_demand; tightens as automation lands (offer doc §Freshness). */
+  mode: "on_demand" | "scheduled" | "realtime";
+  /** Merchant-safe pointer to the hsby-B3 sync report; null if none. */
+  reportRef: string | null;
+  blockingError: string | null;
+}
+
+export interface ContentThemeStatus {
+  state: ReadinessState;
+  themeId: string | null;
+  pagesPorted: number;
+  pagesTotal: number;
+  /** One-liner from the migration manifest's fidelity audit; null if unaudited. */
+  fidelityNote: string | null;
+}
+
+export interface PreviewStatus {
+  state: ReadinessState;
+  previewUrl: string | null;
+  lastReconcileAt: string | null;
+  /** False = last reconcile failed; last-good preview stays live, error shows here. */
+  lastReconcileOk: boolean | null;
+  error: string | null;
+}
+
+export interface ComplianceEvidenceStatus {
+  state: ReadinessState;
+  /** Real evidence-gate output only — never synthesized. */
+  gatePassing: boolean | null;
+  lastEvidenceAt: string | null;
+  reportRef: string | null;
+}
+
+export interface DeveloperAccessStatus {
+  state: ReadinessState;
+  invitedCount: number;
+  activeCount: number;
+  lastActivityAt: string | null;
+  /** Failed app-binding / entitlement states, merchant-safe strings (hsby-E4). */
+  entitlementFailures: string[];
+}
+
+export interface CommerceCutoverStatus {
+  state: ReadinessState;
+  checkoutMode: "none" | "unsigned_demo" | "signed";
+  /** hsby-G2 live-readiness gate items; empty until a live pilot is approved. */
+  gateChecklist: Array<{ item: string; done: boolean }>;
+  /** Only ever true after an explicit human go recorded on the board. */
+  cutoverApproved: boolean;
+}
+
+export interface HotStandbyReadiness {
+  /** Bump rules: docs/hot-standby-readiness-contract.md §Versioning. */
+  contractVersion: 1;
+  tenantId: string;
+  appDomain: string;
+  /** ISO timestamp of assembly — renderers display age, never hide staleness. */
+  generatedAt: string;
+  catalogSync: CatalogSyncStatus;
+  contentTheme: ContentThemeStatus;
+  preview: PreviewStatus;
+  complianceEvidence: ComplianceEvidenceStatus;
+  developerAccess: DeveloperAccessStatus;
+  commerceCutover: CommerceCutoverStatus;
+  blockers: ReadinessBlocker[];
+}
+
+const WORST_FIRST: readonly ReadinessState[] = [
+  "blocked",
+  "unknown",
+  "pending",
+  "in_progress",
+  "ready",
+];
+
+/**
+ * Worst-of-sections rollup. Renderers use this, not their own derivation, so
+ * staff and merchant views can never disagree about the headline state. A
+ * non-empty blockers list forces "blocked" regardless of section states.
+ */
+export function overallReadinessState(r: HotStandbyReadiness): ReadinessState {
+  if (r.blockers.length > 0) return "blocked";
+  const states = [
+    r.catalogSync.state,
+    r.contentTheme.state,
+    r.preview.state,
+    r.complianceEvidence.state,
+    r.developerAccess.state,
+    r.commerceCutover.state,
+  ];
+  for (const worst of WORST_FIRST) {
+    if (states.includes(worst)) return worst;
+  }
+  return "ready";
+}

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

@@ -0,0 +1,34 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// @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 "./foxy-orders.js";
+export * from "./capabilities.js";
+export * from "./checkout-style.js";
+export * from "./checkout-style-publish.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";
+export * from "./hot-standby-readiness.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;
+}