@tokenoftrust/storefront-runner 1.3.4-rc.3 → 1.4.0

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

@@ -0,0 +1,353 @@
+/**
+ * Membership + Autopilot (subscription) purchase MECHANICS — the renderer-safe
+ * pricing/eligibility engine (F10). This is the real, testable side of the
+ * education-only widgets in `lib/membership` / `lib/subscription`: it computes
+ * member-vs-list pricing, composes a member discount with a subscription
+ * (Autopilot) discount under a tenant-configurable STACKING policy, and decides
+ * which purchase options a shopper actually sees.
+ *
+ * Node-free + dependency-free so it ships into the Cloudflare Worker (edge)
+ * bundle exactly like {@link ./checkout.ts} — it reuses that module's
+ * `purchaseOptionPrice` for the subscription leg so a subscription discount is
+ * computed in one place.
+ *
+ * HIDE-AT-LAUNCH is a first-class state. A production tenant that isn't ready to
+ * sell Autopilot / member pricing at launch turns each off with a config flag
+ * ({@link AutopilotConfig.enabled} / {@link MembershipProgramConfig.enabled}):
+ * the mechanics stay real and unit-tested, but nothing renders. See
+ * `docs/architecture/membership-subscription-mechanics.md`.
+ */
+import type {
+  CatalogProduct,
+  CatalogVariant,
+  ProductPurchaseOption,
+  PurchaseOptionKind,
+  PurchaseOptionPriceAdjustment,
+} from "./product.js";
+import { buildVariantCartPayload, purchaseOptionPrice } from "./checkout.js";
+import type {
+  BuildVariantCartPayloadOptions,
+  VariantCartPayload,
+} from "./checkout.js";
+
+/**
+ * One membership tier's pricing rule: the adjustment applied to the LIST price
+ * for a shopper who belongs to `tierId`. The adjustment shape is the same one
+ * the catalog subscription options use, so a tenant authors member and
+ * subscription discounts in one vocabulary.
+ */
+export interface MembershipTierRule {
+  /** Tier identifier, matched against {@link MemberContext.tierId}. */
+  tierId: string;
+  /** Optional display label, e.g. "Member". */
+  label?: string;
+  /** Discount applied to the list price for this tier. */
+  priceAdjustment: PurchaseOptionPriceAdjustment;
+}
+
+/**
+ * How a member discount and a subscription (Autopilot) discount combine when a
+ * member buys a subscription option. Parameterized because real tenant rules
+ * are not yet known (F10 acceptance) — a tenant picks the policy that matches
+ * its program; tests exercise every branch.
+ *
+ * - `best_of` (default): the shopper pays the lower of {member-only, subscription-
+ *   only}. Never double-discounts, never worse than either single offer.
+ * - `stack`: apply the member discount ON TOP of the subscription price.
+ * - `member_only`: the member discount wins; the subscription discount is
+ *   ignored on subscription options (member price still applies to one-time).
+ * - `subscription_only`: the subscription discount wins; the member discount is
+ *   ignored on subscription options (member price still applies to one-time).
+ */
+export type MembershipStackingPolicy =
+  | "best_of"
+  | "stack"
+  | "member_only"
+  | "subscription_only";
+
+export const DEFAULT_STACKING_POLICY: MembershipStackingPolicy = "best_of";
+
+/**
+ * Tenant membership program config. Lives on `TenantConfig.commerce.membership`.
+ * ABSENT or `enabled !== true` → member pricing is OFF (the launch default, since
+ * shopper membership accounts are a Phase-2 managed-checkout capability). A
+ * tenant turns it on only once it has a real member-eligibility source.
+ */
+export interface MembershipProgramConfig {
+  /** Master switch. Omit/false → no member pricing renders (hide-at-launch). */
+  enabled?: boolean;
+  /** Pricing rules per tier. */
+  tiers: MembershipTierRule[];
+  /** How member + subscription discounts combine. Default {@link DEFAULT_STACKING_POLICY}. */
+  stacking?: MembershipStackingPolicy;
+}
+
+/**
+ * Tenant Autopilot (subscription) config. Lives on `TenantConfig.commerce.autopilot`.
+ * ABSENT → Autopilot is visible wherever a product authors subscription purchase
+ * options (the framework/dev default). `enabled: false` HIDES every subscription
+ * purchase option at launch — the recorded PVC readiness state (Autopilot is
+ * marketing-education-only until the Phase-2 managed checkout ships).
+ */
+export interface AutopilotConfig {
+  /** `false` hides all subscription purchase options. Absent/true → visible. */
+  enabled?: boolean;
+}
+
+/**
+ * The resolved shopper membership context for a request. Phase 1 storefronts
+ * have no shopper-login source, so this is `{ isMember: false }`; production
+ * wires it from the resolved account claim. See
+ * `apps/storefront/src/lib/membership/eligibility.ts`.
+ */
+export interface MemberContext {
+  isMember: boolean;
+  /** The member's tier, matched against {@link MembershipTierRule.tierId}. */
+  tierId?: string;
+}
+
+/** A non-member context — the safe default when no membership source resolves. */
+export const ANONYMOUS_MEMBER: MemberContext = { isMember: false };
+
+/** True when Autopilot (subscription options) should render for this tenant. */
+export function isAutopilotEnabled(config?: AutopilotConfig | null): boolean {
+  return config?.enabled !== false;
+}
+
+/** True when member pricing should render for this tenant (opt-in). */
+export function isMembershipEnabled(
+  config?: MembershipProgramConfig | null,
+): boolean {
+  return config?.enabled === true && (config?.tiers?.length ?? 0) > 0;
+}
+
+/**
+ * The membership rule that applies to a shopper right now, or `undefined` when
+ * member pricing is off, the shopper is not a member, or no tier matches. A
+ * single-tier program matches any member (the common case); a multi-tier program
+ * matches on {@link MemberContext.tierId}.
+ */
+export function resolveMembershipRule(
+  member: MemberContext,
+  program?: MembershipProgramConfig | null,
+): MembershipTierRule | undefined {
+  if (!member.isMember || !isMembershipEnabled(program)) return undefined;
+  const tiers = program!.tiers;
+  if (member.tierId) {
+    return tiers.find((t) => t.tierId === member.tierId);
+  }
+  return tiers.length === 1 ? tiers[0] : undefined;
+}
+
+/**
+ * Apply a price adjustment to a base price, with the same validation floor as
+ * the subscription adjustment in checkout.ts: no negative/over-100% percent, no
+ * amount larger than the base. Returns a cent-rounded price.
+ */
+export function applyPriceAdjustment(
+  basePrice: number,
+  adjustment: PurchaseOptionPriceAdjustment,
+): number {
+  if (!Number.isFinite(adjustment.value) || adjustment.value < 0) {
+    throw new Error("membership price adjustment must be a non-negative number");
+  }
+  if (adjustment.type === "percent_off" && adjustment.value > 100) {
+    throw new Error("membership percent discount cannot exceed 100%");
+  }
+  if (adjustment.type === "amount_off" && adjustment.value > basePrice) {
+    throw new Error("membership amount discount cannot exceed the price");
+  }
+  const adjusted =
+    adjustment.type === "percent_off"
+      ? basePrice * (1 - adjustment.value / 100)
+      : basePrice - adjustment.value;
+  return Number(adjusted.toFixed(2));
+}
+
+/** Which discount(s) produced a priced option's effective price. */
+export type AppliedDiscount = "member" | "subscription";
+
+/**
+ * A purchase option priced for a specific shopper: the list price, the effective
+ * price after every applicable discount, and which discounts applied. `compareAt`
+ * is the list price when the effective price beats it (drives strike-through).
+ */
+export interface PricedPurchaseOption {
+  optionId: string;
+  kind: PurchaseOptionKind;
+  /** Undiscounted variant price. */
+  listPrice: number;
+  /** Effective price the shopper pays under the resolved discounts + stacking. */
+  price: number;
+  /** Discounts that shaped `price`. Empty when the shopper pays list. */
+  appliedDiscounts: AppliedDiscount[];
+  /** List price to strike through, present only when `price < listPrice`. */
+  compareAt?: number;
+}
+
+export interface PurchaseOptionPricingContext {
+  member: MemberContext;
+  program?: MembershipProgramConfig | null;
+}
+
+/**
+ * Price ONE purchase option for a shopper, composing the member discount (if the
+ * shopper is an eligible member) with the option's subscription discount (if any)
+ * under the program's stacking policy.
+ */
+export function priceForPurchaseOption(
+  listPrice: number,
+  option: ProductPurchaseOption,
+  ctx: PurchaseOptionPricingContext,
+): PricedPurchaseOption {
+  const rule = resolveMembershipRule(ctx.member, ctx.program);
+  const stacking = ctx.program?.stacking ?? DEFAULT_STACKING_POLICY;
+
+  const memberPrice =
+    rule !== undefined ? applyPriceAdjustment(listPrice, rule.priceAdjustment) : undefined;
+
+  if (option.kind !== "subscription") {
+    // One-time: member discount is the only lever.
+    const price = memberPrice ?? listPrice;
+    return finalize(option, listPrice, price, memberPrice !== undefined ? ["member"] : []);
+  }
+
+  // Subscription: the option's own discount, then compose with the member discount.
+  const subPrice = purchaseOptionPrice(listPrice, option);
+  const subApplied = subPrice < listPrice;
+
+  if (memberPrice === undefined) {
+    return finalize(option, listPrice, subPrice, subApplied ? ["subscription"] : []);
+  }
+
+  switch (stacking) {
+    case "member_only":
+      return finalize(option, listPrice, memberPrice, ["member"]);
+    case "subscription_only":
+      return finalize(option, listPrice, subPrice, subApplied ? ["subscription"] : []);
+    case "stack": {
+      // Apply the member adjustment on top of the already-subscription price.
+      const stacked = applyPriceAdjustment(subPrice, rule!.priceAdjustment);
+      const applied: AppliedDiscount[] = [];
+      if (subApplied) applied.push("subscription");
+      if (stacked < subPrice) applied.push("member");
+      return finalize(option, listPrice, stacked, applied);
+    }
+    case "best_of":
+    default: {
+      // Whichever single discount is cheaper for the shopper.
+      if (memberPrice <= subPrice) {
+        return finalize(option, listPrice, memberPrice, ["member"]);
+      }
+      return finalize(option, listPrice, subPrice, subApplied ? ["subscription"] : []);
+    }
+  }
+}
+
+function finalize(
+  option: ProductPurchaseOption,
+  listPrice: number,
+  price: number,
+  appliedDiscounts: AppliedDiscount[],
+): PricedPurchaseOption {
+  return {
+    optionId: option.id,
+    kind: option.kind,
+    listPrice,
+    price,
+    appliedDiscounts,
+    compareAt: price < listPrice ? listPrice : undefined,
+  };
+}
+
+/** Options for {@link buildMemberSignedCartPayload}. */
+export interface MemberSignedCartPayloadOptions {
+  /** Signing mode — same as the base cart builder ("signed" | "unsigned-demo"). */
+  mode: BuildVariantCartPayloadOptions["mode"];
+  /** Cart-validation secret (required in `signed` mode). */
+  secret?: string;
+  /** The purchase option this payload buys (already visibility-filtered). */
+  purchaseOption: ProductPurchaseOption;
+  /** The shopper's resolved member pricing context for THIS request. */
+  pricing: PurchaseOptionPricingContext;
+  /**
+   * Whether Autopilot is enabled for the tenant. Forwarded to the signer's
+   * hide-at-launch guard so a subscription option can't be signed when Autopilot
+   * is off. Callers should still pre-filter with {@link visiblePurchaseOptions}.
+   */
+  autopilotEnabled: boolean;
+}
+
+/**
+ * Build a signed add-to-cart payload whose price is the MEMBER-ADJUSTED effective
+ * price for the resolved shopper (F11b) — never the raw list price. The effective
+ * price is computed here, server-side, from {@link priceForPurchaseOption} (the
+ * single signed source of truth) using the membership eligibility resolved for
+ * this request, then HMAC-signed by {@link buildVariantCartPayload}.
+ *
+ * Because the price is signed per (variant, purchaseOption, memberContext), a
+ * member price is only valid on a page the server rendered for that member: a
+ * non-member's page carries the list-price signature, so a member price submitted
+ * against it fails the checkout engine's HMAC verification — and vice-versa. The
+ * client NEVER re-derives the price it pays; it can only submit what the server
+ * signed for its resolved eligibility. An anonymous/non-eligible context simply
+ * resolves to the list/subscription price, exactly matching the pre-F11b behavior.
+ */
+export async function buildMemberSignedCartPayload(
+  product: CatalogProduct,
+  variant: CatalogVariant,
+  opts: MemberSignedCartPayloadOptions,
+): Promise<VariantCartPayload> {
+  const effective = priceForPurchaseOption(
+    variant.price,
+    opts.purchaseOption,
+    opts.pricing,
+  );
+  return buildVariantCartPayload(product, variant, {
+    mode: opts.mode,
+    secret: opts.secret,
+    purchaseOption: opts.purchaseOption,
+    signedPrice: effective.price,
+    autopilotEnabled: opts.autopilotEnabled,
+  });
+}
+
+/**
+ * Filter a product's purchase options down to what a shopper should see for this
+ * tenant. When Autopilot is hidden ({@link isAutopilotEnabled} false) every
+ * subscription option is dropped; a one-time option is always preserved so the
+ * product stays buyable (falls back to a synthetic default if the product only
+ * authored subscription options).
+ */
+export function visiblePurchaseOptions(
+  options: ProductPurchaseOption[],
+  opts: { autopilotEnabled: boolean },
+): ProductPurchaseOption[] {
+  if (opts.autopilotEnabled) return options;
+  const oneTime = options.filter((o) => o.kind !== "subscription");
+  if (oneTime.length > 0) return oneTime;
+  return [{ id: "one_time", kind: "one_time", label: "One-time purchase" }];
+}
+
+const INTERVAL_UNIT_LABELS: Record<string, { one: string; many: string }> = {
+  d: { one: "day", many: "days" },
+  w: { one: "week", many: "weeks" },
+  m: { one: "month", many: "months" },
+  y: { one: "year", many: "years" },
+};
+
+/**
+ * Human-readable delivery-interval label for a subscription `frequency` (the
+ * compact checkout recurrence code, e.g. "1m", "60d", "2w"). Returns "Every
+ * month" / "Every 60 days" style copy; falls back to the raw code for anything
+ * it can't parse (never throws — display helper).
+ */
+export function describeInterval(frequency: string): string {
+  const match = /^(\d+(?:\.\d+)?|\.\d+)([dwmy])$/.exec(frequency);
+  if (!match) return frequency;
+  const amount = Number.parseFloat(match[1]!);
+  const unit = INTERVAL_UNIT_LABELS[match[2]!];
+  if (!unit || !Number.isFinite(amount) || amount <= 0) return frequency;
+  if (amount === 1) return `Every ${unit.one}`;
+  return `Every ${amount} ${unit.many}`;
+}

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

@@ -17,9 +17,23 @@ export type ProductStatus = "active" | "draft" | "archived";
 
 export type Currency = string; // ISO 4217, e.g. "USD"
 
+/**
+ * Known catalog ingestion sources. "shopify" is the Phase-1 ETL source; the F7
+ * ingestion contract adds source-agnostic paths — a directory extraction, a
+ * CSV / PIM / ERP export, or a hand-authored record. Nothing branches on this
+ * at runtime; it is honest provenance for audit + the importer's source seam.
+ * Widen this union (not a per-package copy) when a new source lands.
+ */
+export type SourcePlatform =
+  | "shopify"
+  | "directory"
+  | "csv"
+  | "manual"
+  | "synthesized";
+
 export interface SourceRef {
-  /** Origin platform. Phase 1 is always "shopify". */
-  platform: "shopify";
+  /** Origin platform (provenance only; not branched on at runtime). */
+  platform: SourcePlatform;
   /** Stable source id, e.g. Shopify legacyResourceId or gid. Upsert key. */
   source_id: string;
   /** Original handle/slug from the source platform (pre-collision-resolution). */
@@ -99,6 +113,14 @@ export interface CatalogImage {
   variant_ids?: string[];
   /** True if rehosted to our own storage; false if still pointing at Shopify CDN. */
   rehosted?: boolean;
+  /**
+   * The ORIGINAL source URL this image was rehosted from (provenance). Set once,
+   * on the first rehost, and preserved verbatim across idempotent re-runs — so
+   * `url` can flip to the R2/CDN address while the audit trail back to the
+   * merchant's source (Shopify CDN, etc.) is never lost. Absent on images that
+   * were never rehosted (their live `url` is still the source).
+   */
+  source_url?: string;
 }
 
 export interface Metafield {

package/packages/public-runtime/src/review-trust-proof.ts

@@ -0,0 +1,194 @@
+/**
+ * Review / trust-proof contract (spec §F9; docs/architecture/review-markup-policy.md).
+ *
+ * The governing rule: ratings, counts, reviews, and "verified"/social-proof
+ * badges are REAL merchant data or ABSENT — never fabricated. This module is the
+ * single, node-free home for that contract's two enforcement pieces:
+ *
+ *   1. `isFabricatedTrustProof` / `auditTrustProof` — the go-live GUARD. Catches
+ *      scraped third-party review-widget markup (Judge.me / Stamped / Yotpo /
+ *      Loox / Okendo …) with baked-in aggregate numbers before it reaches a
+ *      rendered surface. Used at ingestion (migration strips it) AND as a
+ *      fixture lint (the storefront asserts the shipped catalog is clean).
+ *   2. `readReviewAggregate` — the single reader of a product's REAL aggregate
+ *      rating from migrated metafields, real-or-absent by construction.
+ *
+ * Kept in @tot/public-runtime (renderer-safe, node-free) so both the migration
+ * pipeline (via @tot/private-controlplane's re-export) and the edge storefront
+ * share ONE definition of "what fabricated trust proof looks like".
+ */
+import type { CatalogProduct, Metafield } from "./product.js";
+import type { Review } from "./product.js";
+
+// ---------------------------------------------------------------------------
+// Fabricated-trust-proof detection.
+//
+// A migrated Shopify store carries the raw HTML of whatever reviews app it used
+// (Judge.me `jdgm-*` badges/widgets, Stamped/Yotpo/Loox/Okendo snippets) dumped
+// into product metafields. That markup has aggregate numbers baked in — "Based
+// on 369 reviews", "95% (351) reviews with 5 star rating", data-average-rating —
+// which are NOT backed by any live review source on the new storefront. Rendering
+// it manufactures social proof, so it is forbidden: reviews may only enter through
+// the real `Review[]` ingestion seam (see packages/migration/src/reviews/*).
+// ---------------------------------------------------------------------------
+
+/** Markup/text signatures of a scraped third-party review widget or badge. */
+const FABRICATED_TRUST_PROOF_SIGNATURES: readonly RegExp[] = [
+  /jdgm[-_]/i, // Judge.me widget/badge classes (jdgm-prev-badge, jdgm-rev-widg)
+  /data-(?:average-rating|number-of-reviews)\b/i, // Judge.me / Shopify review data-attrs
+  /class=["'][^"']*\bstamped[-_]/i, // Stamped.io widget markup
+  /\byotpo[-_]/i, // Yotpo widget/classes
+  /\b(?:loox|okendo|kudobuzz|shopperapproved)\b/i, // other review apps' widget hooks
+  /reviews\.io/i, // Reviews.io widget
+  /class=["'][^"']*\breview[-_]?(?:widget|badge|snippet|stars?)\b/i, // generic review-widget class
+  /\bBased on\s+\d+\s+reviews?\b/i, // baked-in aggregate sentence
+  /\d+%\s*\(\d+\)\s*reviews?\s+with\s+\d+\s+star/i, // baked-in star-breakdown row
+];
+
+/**
+ * True when a value (a metafield value or a chunk of content) carries scraped
+ * review-widget markup / a baked-in aggregate — i.e. fabricated trust proof.
+ * Plain product copy, and the numeric aggregate metafields (`reviews.rating`,
+ * `reviews.rating_count`, `stamped.reviews_*`), do NOT match.
+ */
+export function isFabricatedTrustProof(value: unknown): boolean {
+  if (typeof value !== "string" || value.length === 0) return false;
+  return FABRICATED_TRUST_PROOF_SIGNATURES.some((re) => re.test(value));
+}
+
+/** A metafield is fabricated trust proof when its value carries widget markup. */
+export function isFabricatedTrustProofMetafield(m: Pick<Metafield, "value">): boolean {
+  return isFabricatedTrustProof(m.value);
+}
+
+// ---------------------------------------------------------------------------
+// Real aggregate reader (real-or-absent).
+// ---------------------------------------------------------------------------
+
+export interface ReviewAggregate {
+  /** 0 when there is no real aggregate. */
+  average: number;
+  /** 0 when there is no real aggregate. */
+  count: number;
+}
+
+const ABSENT: ReviewAggregate = { average: 0, count: 0 };
+
+/**
+ * Parse a metafield rating value. Merchants store it either as a bare number
+ * ("4.9") or as a Shopify rating JSON blob
+ * ({"scale_min":"1.0","scale_max":"5.0","value":"4.94"}). Anything unparseable
+ * (or non-finite) reads as 0 — never a fabricated fallback.
+ */
+export function parseReviewAverage(
+  raw: string | number | null | undefined,
+): number {
+  if (raw == null || raw === "") return 0;
+  if (typeof raw === "number") return Number.isFinite(raw) ? raw : 0;
+  const s = raw.trim();
+  if (s.startsWith("{")) {
+    try {
+      const o = JSON.parse(s) as Record<string, unknown>;
+      const v = Number(o.value ?? o.average ?? o.rating);
+      return Number.isFinite(v) ? v : 0;
+    } catch {
+      return 0;
+    }
+  }
+  const n = Number(s);
+  return Number.isFinite(n) ? n : 0;
+}
+
+/**
+ * Read a product's REAL aggregate rating from its migrated metafields. Surfaces
+ * the aggregate ONLY when BOTH the average and the count are real, positive,
+ * finite numbers. A half-populated aggregate (a rating with no count, or a
+ * count with no rating) is treated as ABSENT — the render/JSON-LD layers then
+ * emit nothing, so no fabricated rating can appear.
+ */
+export function readReviewAggregate(
+  product: Pick<CatalogProduct, "metafields">,
+): ReviewAggregate {
+  const mf = (ns: string, key: string): string | undefined =>
+    product.metafields.find((m) => m.namespace === ns && m.key === key)?.value;
+
+  const count = Number(
+    mf("stamped", "reviews_count") ??
+      mf("reviews", "count") ??
+      mf("reviews", "rating_count") ??
+      "",
+  );
+  const average = parseReviewAverage(
+    mf("stamped", "reviews_average") ?? mf("reviews", "rating"),
+  );
+
+  if (!Number.isFinite(count) || count <= 0 || average <= 0) return ABSENT;
+  return { average, count };
+}
+
+// ---------------------------------------------------------------------------
+// Per-review reality + the go-live audit.
+// ---------------------------------------------------------------------------
+
+/**
+ * A review is "real" when it carries a genuine author, a rating in 1–5, and
+ * some content (body or title). Empty/placeholder/synthetic entries fail.
+ */
+export function isRealReview(r: Partial<Review>): boolean {
+  const hasAuthor = typeof r.author === "string" && r.author.trim().length > 0;
+  const hasRating =
+    typeof r.rating === "number" && r.rating >= 1 && r.rating <= 5;
+  const hasContent =
+    (typeof r.body === "string" && r.body.trim().length > 0) ||
+    (typeof r.title === "string" && r.title.trim().length > 0);
+  return hasAuthor && hasRating && hasContent;
+}
+
+export interface TrustProofViolation {
+  tenant?: string;
+  handle?: string;
+  kind: "fabricated-metafield" | "invalid-review";
+  detail: string;
+}
+
+/**
+ * Audit a tenant's catalog for fabricated trust proof — the go-live guard.
+ * Flags (a) any product metafield carrying scraped review-widget markup, and
+ * (b) any ingested review that isn't structurally real. `ok` is the gate:
+ * a clean tenant (e.g. PVC, 0 reviews) passes; fabricated markup fails.
+ */
+export function auditTrustProof(input: {
+  products: ReadonlyArray<Pick<CatalogProduct, "handle" | "metafields">>;
+  reviews?: Record<string, ReadonlyArray<Partial<Review>>>;
+  tenant?: string;
+}): { ok: boolean; violations: TrustProofViolation[] } {
+  const violations: TrustProofViolation[] = [];
+
+  for (const p of input.products) {
+    for (const m of p.metafields ?? []) {
+      if (isFabricatedTrustProofMetafield(m)) {
+        violations.push({
+          tenant: input.tenant,
+          handle: p.handle,
+          kind: "fabricated-metafield",
+          detail: `metafield ${m.namespace}.${m.key} carries scraped review-widget markup / a baked-in aggregate`,
+        });
+      }
+    }
+  }
+
+  for (const [handle, list] of Object.entries(input.reviews ?? {})) {
+    list.forEach((r, i) => {
+      if (!isRealReview(r)) {
+        violations.push({
+          tenant: input.tenant,
+          handle,
+          kind: "invalid-review",
+          detail: `review #${i} is missing a real author / rating(1–5) / content`,
+        });
+      }
+    });
+  }
+
+  return { ok: violations.length === 0, violations };
+}

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

@@ -330,18 +330,44 @@ export async function readAssetsPointer(
 }
 
 /**
- * Point a channel at a snapshot versionId (read-check-write on `rev`). KV has no
- * hardware CAS; a single serialized writer per tenant (the publish/reconcile
- * pipeline) makes the optimistic rev check sufficient — same trade-off as
- * `KVVersionStore.setPointer`.
+ * Optimistic-concurrency conflict on the assets pointer — the local analogue of
+ * `@tot/private-controlplane`'s `CustomizationError("pointer-conflict")` (which
+ * this renderer-safe module cannot import, to keep the purity boundary intact).
+ * Carries the same `"pointer-conflict"` code so callers can branch identically.
+ */
+export class AssetsPointerConflictError extends Error {
+  readonly code = "pointer-conflict" as const;
+  constructor(
+    readonly tenantId: string,
+    readonly expectedRev: number,
+    readonly foundRev: number,
+  ) {
+    super(
+      `Assets pointer for "${tenantId}" changed (expected rev ${expectedRev}, found ${foundRev}).`,
+    );
+    this.name = "AssetsPointerConflictError";
+  }
+}
+
+/**
+ * Point a channel at a snapshot versionId (CAS on `rev`). KV has no hardware CAS,
+ * so the caller reads the pointer once, passes its `rev` as `expectedRev`, and
+ * this rejects the write if the stored `rev` has since moved — two concurrent
+ * asset-promotions for one tenant can no longer silently clobber each other
+ * (last-write-wins on the whole record). Same shape as
+ * `KVVersionStore.setChannel(..., expectedRev)`.
  */
 export async function setAssetsChannel(
   kv: AssetsKv,
   tenantId: string,
   channel: CustomizationEnv,
   versionId: string,
+  expectedRev: number,
 ): Promise<AssetsPointer> {
   const current = await readAssetsPointer(kv, tenantId);
+  if (current.rev !== expectedRev) {
+    throw new AssetsPointerConflictError(tenantId, expectedRev, current.rev);
+  }
   const next: AssetsPointer = {
     ...current,
     rev: current.rev + 1,
@@ -351,12 +377,21 @@ export async function setAssetsChannel(
   return next;
 }
 
-/** Promote the test snapshot to live (atomic pointer flip). */
+/**
+ * Promote the test snapshot to live (atomic pointer flip), CAS-guarded on `rev`.
+ * The caller supplies `expectedRev` from a single prior `readAssetsPointer`; a
+ * concurrent write that lands in between throws `AssetsPointerConflictError`
+ * rather than being silently overwritten.
+ */
 export async function promoteAssets(
   kv: AssetsKv,
   tenantId: string,
+  expectedRev: number,
 ): Promise<AssetsPointer> {
   const current = await readAssetsPointer(kv, tenantId);
+  if (current.rev !== expectedRev) {
+    throw new AssetsPointerConflictError(tenantId, expectedRev, current.rev);
+  }
   const next: AssetsPointer = {
     ...current,
     rev: current.rev + 1,