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

package/apps/storefront/src/lib/publish/shipWorkspace.ts

@@ -0,0 +1,362 @@
+/**
+ * Ship operations workspace (unit dg7) — the PURE composer behind the admin
+ * Publish tab's operations surface that sits ALONGSIDE the go-live core
+ * (AdminPublishTab.astro's change queue + accept/reject + dispatch status).
+ *
+ * dg7 is DELTA-scoped: the go-live session already delivered the Publish-tab
+ * core (the change queue from GET /api/changes, Go-live/Reject, the live-version
+ * + dispatch-status panel, and the owner-only Domain section). This module adds
+ * the operations workspace BEYOND that core — the three read/act surfaces woven
+ * into the same tab:
+ *
+ *   1. DIFF VIEW  — for one pending candidate, the artifact-level diff of what
+ *      changed (its rendered immutable version vs the current live version),
+ *      tied to the exact tenant Gitea head SHA, with the u5 immutable
+ *      `/preview/<tenant>/rev/<sha>/` link and the dg3 evidence AUTHORITY
+ *      (authoritative / stale / missing) — never a diff a reviewer would mistake
+ *      for the head when a last-good version actually renders.
+ *   2. VERSIONS  — the tenant's published-version / promotion history
+ *      (`listPromotions`, u2/u3 promotion_status), each row carrying the tenant
+ *      Gitea SHA (`gitea-only-tenant-content-authority`), its promotion time, a
+ *      `/rev/<sha>/` link, and — marking the current live one.
+ *   3. ROLLBACK  — pick a prior version and roll back THROUGH the one orchestrator
+ *      (`/api/changes/rollback` → `rollbackCandidateAtomic` / u8's
+ *      `staticRollbackOrchestrator`), rendering only the HONEST terminal state
+ *      (`rolled_back` when VERIFIED; `publish_pending` in flight; `publish_failed`
+ *      / `blocked` fail-closed) — never a false "rolled back".
+ *
+ * COMPOSES, never rebuilds:
+ *   - the u5 immutable link is `reviewDashboardRevisionHref` verbatim;
+ *   - the dg3 authority is `candidateEvidenceAuthority` /
+ *     `classifyCandidateForRender` verbatim;
+ *   - the versions come from the SAME `KVVersionStore.listPromotions` the
+ *     "one step back" rollback resolution reads;
+ *   - the rollback ACTION is the existing `/api/changes/rollback` seam — this
+ *     module only INTERPRETS its honest response, it never re-decides a ship.
+ *
+ * PURE (no I/O): the endpoints inject already-read KV data, so every honest-state
+ * decision is unit-tested without a Worker/KV — mirroring the reviewDashboard.ts /
+ * candidatePreviewState.ts split.
+ *
+ * HONEST BOUNDARY (surfaced, never faked): a FULLY-STATIC tenant serves its public
+ * site from an external `versions/<digest>/` archive whose per-version treeDigests
+ * live only in S3 — enumerable by the Node-only `listRollbackTargets`
+ * (`scripts/publish/lib/static-rollback.mjs`), NOT by the Worker. So the console
+ * can list a static tenant's promotion history + `/rev` links + the CURRENT live
+ * digest, but it cannot resolve an ARBITRARY prior version's archive digest, which
+ * `/api/changes/rollback` fail-closed requires (`targetDigest`). `rollbackMode`
+ * names this: a `control-plane` tenant rolls back one-click (targetVersionId only);
+ * a `static-archive` tenant's per-version rollback is honestly deferred to the ship
+ * CLI / CI that enumerates the archive — never a one-click that would 400.
+ */
+import { reviewDashboardRevisionHref } from "@/lib/preview/reviewDashboard";
+import {
+  candidateEvidenceAuthority,
+  classifyCandidateForRender,
+  defaultBlockedReason,
+  type CandidateEvidenceAuthority,
+} from "@/lib/preview/candidatePreviewState";
+import type { ReviewEnvironment, PromotionEvent } from "@tot/public-runtime";
+
+// ── Versions / promotion history ───────────────────────────────────────────
+
+/** One published version in the tenant's promotion history (u2/u3 promotion_status). */
+export interface WorkspaceVersion {
+  /** The tenant Gitea SHA the version serves — the content identity
+   *  (`gitea-only-tenant-content-authority`). */
+  versionId: string;
+  /** How the version was published (a Gitea commit, or a content hash). */
+  source: "commit" | "hash" | null;
+  /** ISO time the version was PROMOTED onto `live` (the promotion event). */
+  promotedAt: string;
+  /** ISO time the version was first published (from its site-version manifest). */
+  createdAt: string | null;
+  /** Artifact count in the version manifest, or `null` when the manifest is absent. */
+  artifactCount: number | null;
+  /**
+   * The content-addressed `treeDigest`, when the console can honestly know it —
+   * i.e. ONLY the current live version of a static tenant (read back from
+   * `live/manifest.json`). `null` for every other row: a prior static version's
+   * digest lives only in the S3 archive the Worker can't enumerate. Never fabricated.
+   */
+  digest: string | null;
+  /** The u5 immutable `/preview/<tenant>/rev/<sha>/` deep-link, or `null` without a SHA. */
+  revHref: string | null;
+  /** The version currently serving live (the one you never roll back TO). */
+  isCurrent: boolean;
+}
+
+/** How a rollback is honestly driven for this tenant (see the module HONEST BOUNDARY note). */
+export type RollbackMode = "control-plane" | "static-archive";
+
+/** The versions-panel view model. */
+export interface VersionsView {
+  /** The current live version + (static) the digest `live/` actually serves. */
+  current: { versionId: string | null; digest: string | null };
+  /** Promotion history, newest first, current marked. */
+  versions: WorkspaceVersion[];
+  /** Whether the tenant publishes its public site to an external static target. */
+  staticPublish: boolean;
+  /**
+   * `control-plane` → a prior version rolls back one-click via `targetVersionId`.
+   * `static-archive` → per-version rollback is deferred to the ship CLI / CI that
+   * enumerates the `versions/` archive (the Worker can't resolve the archive digest).
+   */
+  rollbackMode: RollbackMode;
+}
+
+/** A single promoted version enriched with the manifest facts the panel shows. */
+export interface VersionManifestFacts {
+  source: "commit" | "hash" | null;
+  createdAt: string | null;
+  artifactCount: number | null;
+}
+
+export interface BuildVersionsViewInput {
+  tenantId: string;
+  /** Live-promotion history, newest first (`KVVersionStore.listPromotions`). */
+  promotions: PromotionEvent[];
+  /** The current live version id (the live-channel pointer), or `null`. */
+  currentVersionId: string | null;
+  /** The digest `live/` serves — static tenants only; `null` otherwise. */
+  currentDigest: string | null;
+  /** Per-version manifest facts, keyed by versionId (absent ⇒ unknown facts). */
+  manifests: Map<string, VersionManifestFacts>;
+  staticPublish: boolean;
+}
+
+/**
+ * Assemble the versions panel from the promotion history + per-version manifest
+ * facts + the current-live pointer. Pure. The current live row is marked; the
+ * digest is populated ONLY for the current live of a static tenant (never faked
+ * for priors). `revHref` is the u5 immutable link.
+ */
+export function buildVersionsView(input: BuildVersionsViewInput): VersionsView {
+  const { tenantId, promotions, currentVersionId, currentDigest, manifests, staticPublish } = input;
+
+  const versions: WorkspaceVersion[] = promotions.map((p) => {
+    const facts = manifests.get(p.versionId);
+    const isCurrent = currentVersionId != null && p.versionId === currentVersionId;
+    return {
+      versionId: p.versionId,
+      source: facts?.source ?? null,
+      promotedAt: p.at,
+      createdAt: facts?.createdAt ?? null,
+      artifactCount: facts?.artifactCount ?? null,
+      // Honest: a digest is known only for the current live of a static tenant.
+      digest: isCurrent && staticPublish ? currentDigest : null,
+      revHref: reviewDashboardRevisionHref(tenantId, p.versionId),
+      isCurrent,
+    };
+  });
+
+  return {
+    current: { versionId: currentVersionId, digest: staticPublish ? currentDigest : null },
+    versions,
+    staticPublish,
+    rollbackMode: staticPublish ? "static-archive" : "control-plane",
+  };
+}
+
+// ── Diff view ──────────────────────────────────────────────────────────────
+
+export type DiffChangeKind = "added" | "removed" | "changed";
+
+/** One artifact path that differs between the candidate and the current live version. */
+export interface DiffEntry {
+  path: string;
+  change: DiffChangeKind;
+}
+
+/** The diff-view model for one pending candidate. */
+export interface CandidateDiffView {
+  changeId: string;
+  /** The candidate's exact head SHA — the reconcile TARGET (tenant Gitea sha). */
+  headSha: string | null;
+  /** The immutable version actually rendered + diffed — the reconcile ACTUAL. */
+  versionId: string | null;
+  /** The u5 immutable link to the exact reviewed SHA, or `null` without a head SHA. */
+  revHref: string | null;
+  /** dg3 evidence authority: authoritative (tied to head) / stale (last-good) / missing. */
+  authority: CandidateEvidenceAuthority;
+  /** The artifact-level diff (candidate rendered version vs current live), sorted by path. */
+  files: DiffEntry[];
+  /** True when the candidate has a renderable version to diff (dg3 `ready`). */
+  renderable: boolean;
+  /** When NOT renderable, the honest reason (names why) — never a fake empty diff. */
+  blockedReason: string | null;
+}
+
+export interface BuildCandidateDiffInput {
+  tenantId: string;
+  env: ReviewEnvironment;
+  /** The candidate rendered version's artifacts (path → contentHash), or `null`. */
+  candidateArtifacts: Record<string, string> | null;
+  /** The current live version's artifacts (path → contentHash), or `null` (nothing live yet). */
+  liveArtifacts: Record<string, string> | null;
+}
+
+/**
+ * Diff a candidate's rendered version against the current live version, at the
+ * artifact level (each path carries a content hash in its site-version manifest).
+ * Composes dg3's `classifyCandidateForRender` (only a `ready` candidate has a
+ * version to diff — a blocked/queued one yields an HONEST `blockedReason`, never a
+ * fabricated empty diff) and `candidateEvidenceAuthority` (so a diff of a last-good
+ * version that LAGS the head is flagged `stale`, not passed off as the head).
+ * Pure.
+ */
+export function buildCandidateDiff(input: BuildCandidateDiffInput): CandidateDiffView {
+  const { tenantId, env, candidateArtifacts, liveArtifacts } = input;
+  const classification = classifyCandidateForRender(env);
+  const authority = candidateEvidenceAuthority(env);
+  const revHref = reviewDashboardRevisionHref(tenantId, env.headSha);
+
+  if (classification.kind !== "ready") {
+    const reason =
+      classification.kind === "blocked"
+        ? classification.reason
+        : defaultBlockedReason(env.status);
+    return {
+      changeId: env.changeId,
+      headSha: env.headSha,
+      versionId: null,
+      revHref,
+      authority,
+      files: [],
+      renderable: false,
+      blockedReason: reason,
+    };
+  }
+
+  const files = diffArtifacts(candidateArtifacts ?? {}, liveArtifacts ?? {});
+  return {
+    changeId: env.changeId,
+    headSha: env.headSha,
+    versionId: classification.versionId,
+    revHref,
+    authority,
+    files,
+    renderable: true,
+    blockedReason: null,
+  };
+}
+
+/** Artifact-level diff: paths added / removed / content-changed, sorted by path. */
+export function diffArtifacts(
+  candidate: Record<string, string>,
+  live: Record<string, string>,
+): DiffEntry[] {
+  const entries: DiffEntry[] = [];
+  for (const [path, hash] of Object.entries(candidate)) {
+    if (!(path in live)) entries.push({ path, change: "added" });
+    else if (live[path] !== hash) entries.push({ path, change: "changed" });
+  }
+  for (const path of Object.keys(live)) {
+    if (!(path in candidate)) entries.push({ path, change: "removed" });
+  }
+  return entries.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+
+// ── Rollback response interpretation ─────────────────────────────────────────
+
+/** The normalized honest terminal state of a rollback, for the surface to render. */
+export type RollbackState =
+  | "rolled_back" // VERIFIED live on the prior version — the ONLY "rolled back" claim
+  | "publish_pending" // restored + dispatched, not yet verified — NOT "rolled back"
+  | "publish_failed" // fail-closed: unwired / dispatch failed / verification failed
+  | "blocked" // a gate refused (capability / no prior / race) — nothing moved
+  | "error"; // transport / unexpected shape
+
+export interface RollbackOutcome {
+  state: RollbackState;
+  /** True ONLY for `rolled_back` (the target is verified to serve the prior version). */
+  rolledBack: boolean;
+  /** The version restored TO, when known. */
+  toVersionId: string | null;
+  /** A human-legible message for the surface. */
+  message: string;
+}
+
+/**
+ * Interpret the `/api/changes/rollback` response into ONE honest terminal state,
+ * for BOTH planes without the surface having to know which it hit:
+ *   - a HOSTED (control-plane) rollback returns `{ rolledBack: true, toVersionId }`
+ *     on success (the pointer flip IS the rollback) or `{ error, reason }` on refusal;
+ *   - a STATIC rollback returns the orchestrator's honest `{ state, ... }` (u8).
+ * The rule the surface depends on: `rolledBack` is true ONLY for a verified
+ * `rolled_back` — a `publish_pending` is NEVER rendered as rolled back
+ * (`storefront-atomic-accept-is-ship-orchestrator` / `static-publish-fails-closed`).
+ * Pure.
+ */
+export function interpretRollbackResponse(
+  httpOk: boolean,
+  body: {
+    state?: unknown;
+    rolledBack?: unknown;
+    toVersionId?: unknown;
+    message?: unknown;
+    error?: unknown;
+    reason?: unknown;
+  },
+): RollbackOutcome {
+  const toVersionId = typeof body.toVersionId === "string" ? body.toVersionId : null;
+
+  // Static plane: the orchestrator's explicit honest state wins.
+  if (typeof body.state === "string") {
+    const state = normalizeRollbackState(body.state);
+    const message =
+      typeof body.message === "string" && body.message
+        ? body.message
+        : typeof body.error === "string" && body.error
+          ? body.error
+          : rollbackStateFallbackMessage(state);
+    return { state, rolledBack: state === "rolled_back", toVersionId, message };
+  }
+
+  // Control-plane: a bare success flag, or a typed refusal.
+  if (httpOk && body.rolledBack === true) {
+    return {
+      state: "rolled_back",
+      rolledBack: true,
+      toVersionId,
+      message: toVersionId ? `Rolled back live to ${toVersionId}.` : "Rolled back live.",
+    };
+  }
+
+  const reason = typeof body.reason === "string" ? body.reason : null;
+  const message =
+    typeof body.error === "string" && body.error
+      ? body.error + (reason ? ` (${reason})` : "")
+      : "Rollback failed.";
+  // A control-plane refusal is a gate refusal (capability / no prior / conflict) —
+  // nothing moved; treat as blocked (never a false rolled-back).
+  return { state: "blocked", rolledBack: false, toVersionId, message };
+}
+
+function normalizeRollbackState(raw: string): RollbackState {
+  switch (raw) {
+    case "rolled_back":
+    case "publish_pending":
+    case "publish_failed":
+    case "blocked":
+      return raw;
+    default:
+      return "error";
+  }
+}
+
+function rollbackStateFallbackMessage(state: RollbackState): string {
+  switch (state) {
+    case "rolled_back":
+      return "Rolled back live.";
+    case "publish_pending":
+      return "Restored the pointer and dispatched the re-publish — not yet verified live. Refresh to re-check.";
+    case "publish_failed":
+      return "Rollback failed — the publish path is unwired or verification failed. Nothing false went live.";
+    case "blocked":
+      return "Rollback was refused by a gate — nothing changed.";
+    case "error":
+    default:
+      return "Rollback returned an unexpected response.";
+  }
+}

package/apps/storefront/src/lib/rawChrome.ts

@@ -99,7 +99,9 @@ function renderBrand(brand: ChromeBrand, opts: { footer?: boolean } = {}): strin
   const inner = validLogo
     ? `<img src="${esc(logo.src)}" alt="${esc(logo.alt)}"${
         logo.width ? ` width="${logo.width}"` : ""
-      }${logo.height ? ` height="${logo.height}"` : ""}>`
+      }${logo.height ? ` height="${logo.height}"` : ""} loading="${
+        opts.footer ? "lazy" : "eager"
+      }" decoding="async">`
     : brand.wordmark?.length
       ? renderWordmark(brand.wordmark)
       : esc(brand.label);
@@ -279,7 +281,7 @@ function renderFooter(footer: ChromeFooter): string {
           const logo = brand?.logo && /^(https?:|\/)/.test(brand.logo.src)
             ? `<img src="${esc(brand.logo.src)}" alt="${esc(brand.logo.alt)}"${
                 brand.logo.width ? ` width="${brand.logo.width}"` : ""
-              }${brand.logo.height ? ` height="${brand.logo.height}"` : ""}>`
+              }${brand.logo.height ? ` height="${brand.logo.height}"` : ""} loading="lazy" decoding="async">`
             : brand?.wordmark?.length
               ? `<span class="brand">${renderWordmark(brand.wordmark)}</span>`
               : "";
@@ -445,6 +447,31 @@ export const CHROME_BEHAVIOR_JS = `(function () {
 /** The platform-shipped chrome stylesheet every rendered wrapper links (unit F2). */
 export const SHARED_CHROME_STYLESHEET = "/shared/commerce-chrome.css";
 
+/**
+ * The platform-shipped RAW-PAGE-BODY marketing stylesheet (unit F5). Linked only
+ * when a tenant opts in (chrome.sharedMarketingCss) and AFTER the chrome sheet, so
+ * its page-level variants (e.g. .sec-head) win over chrome's home-section ones.
+ */
+export const SHARED_MARKETING_STYLESHEET = "/shared/commerce-marketing.css";
+
+/** MIME type for a favicon href, derived from its extension (SVG marks are common now). */
+function faviconMime(href: string): string {
+  const ext = href.split(/[?#]/)[0]?.split(".").pop()?.toLowerCase();
+  switch (ext) {
+    case "svg":
+      return "image/svg+xml";
+    case "ico":
+      return "image/x-icon";
+    case "jpg":
+    case "jpeg":
+      return "image/jpeg";
+    case "webp":
+      return "image/webp";
+    default:
+      return "image/png";
+  }
+}
+
 /**
  * Render the canonical chrome wrapper document for a tenant, from its config.
  *
@@ -459,9 +486,13 @@ export function renderRawChrome(chrome: TenantChrome): string {
   const head = chrome.head ?? {};
   const headLinks = [
     head.themeColor ? `<meta name="theme-color" content="${esc(head.themeColor)}">` : "",
-    head.favicon ? `<link rel="icon" type="image/png" href="${esc(head.favicon)}">` : "",
+    head.favicon
+      ? `<link rel="icon" type="${faviconMime(head.favicon)}" href="${esc(head.favicon)}">`
+      : "",
     ...(head.themeStylesheets ?? []).map((h) => `<link rel="stylesheet" href="${esc(h)}">`),
     `<link rel="stylesheet" href="${SHARED_CHROME_STYLESHEET}">`,
+    // Opt-in raw-page-body layer, after the chrome sheet so its variants win (F5).
+    chrome.sharedMarketingCss ? `<link rel="stylesheet" href="${SHARED_MARKETING_STYLESHEET}">` : "",
   ]
     .filter(Boolean)
     .join("\n");

package/apps/storefront/src/lib/storyblok/content-model.ts

@@ -9,12 +9,15 @@
  * parent/child + Shared Components plan.
  */
 import type { ProductSectionSource } from "@tot/public-runtime";
+import type { ProseSection } from "@/lib/content/prose";
+import type { Tier } from "@/lib/membership/model";
 
 export type HomeBlock =
   | HeroBlock
   | PromoTilesBlock
   | FeaturedCollectionsBlock
   | FeaturedProductsBlock
+  | MembershipBandBlock
   | EditorialBlock
   | NewsletterBlock;
 
@@ -59,6 +62,22 @@ export interface FeaturedProductsBlock {
   limit?: number;
 }
 
+/**
+ * Membership "band" on the commerce home — the Guest / Member / Autopilot tier
+ * comparison, driven by the platform <TierCards> (F4) widget from tenant data.
+ * The widget owns the illustrative-figures affordance (a tier is an EXAMPLE
+ * unless it asserts `real: true`), so a tenant surfaces its membership model on
+ * the home page without copying tier-card HTML. The block carries the same
+ * {@link Tier} shape the standalone membership page uses.
+ */
+export interface MembershipBandBlock {
+  component: "membership_band";
+  eyebrow?: string;
+  title?: string;
+  subhead?: string;
+  tiers: Tier[];
+}
+
 export interface EditorialBlock {
   component: "editorial";
   eyebrow?: string;
@@ -249,11 +268,24 @@ export interface EditorialPage {
   title: string;
   seoTitle?: string;
   seoDescription?: string;
-  /** Sanitized HTML body. */
-  body_html: string;
+  /**
+   * Sanitized HTML body (legacy / raw path). Optional: a page authored with
+   * structured {@link ProseSection}s omits it and drives the body from `sections`
+   * instead (spec §F4). The renderer prefers `sections` when present.
+   */
+  body_html?: string;
+  /**
+   * Structured policy/prose body (spec §F4) — headings, paragraphs, lists,
+   * callouts, a contact block, needs-review flags. When present, the page route
+   * renders <ProseSections> from this instead of `set:html(body_html)`, so a
+   * tenant drives a full policy page from JSON with no HTML/CSS to copy.
+   */
+  sections?: ProseSection[];
   /** Optional hero eyebrow/intro. */
   eyebrow?: string;
   intro?: string;
+  /** ISO date (YYYY-MM-DD) rendered as a "Last updated" line (structured pages). */
+  updated?: string;
   /** When true, listed in the footer policy column. */
   isPolicy?: boolean;
 }

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

@@ -353,18 +353,25 @@ function mapHome(content: Record<string, any>): HomeContent {
 }
 
 function mapPage(content: Record<string, any>, slug: string): EditorialPage {
-  // Expect a rendered-HTML field (text/markdown component). A raw richtext object
-  // would need a resolver — we throw so the local fallback serves it instead.
+  // A page is either structured (F4 `sections`) OR raw HTML (`body_html`/`body`).
+  // Structured pages drive the body from `sections`; otherwise we expect a
+  // rendered-HTML field (a raw richtext object would need a resolver — we throw
+  // so the local fallback serves it instead).
+  const sections = Array.isArray(content.sections) ? content.sections : undefined;
   const body_html = content.body_html ?? content.body;
-  if (typeof body_html !== "string") throw new Error(`storyblok page ${slug}: body not HTML`);
+  if (!sections && typeof body_html !== "string") {
+    throw new Error(`storyblok page ${slug}: no sections and body not HTML`);
+  }
   return {
     slug: slug.replace(/^pages\//, ""),
     title: content.title ?? slug,
     seoTitle: content.seoTitle ?? content.seo_title,
     seoDescription: content.seoDescription ?? content.seo_description,
-    body_html,
+    body_html: typeof body_html === "string" ? body_html : undefined,
+    sections,
     eyebrow: content.eyebrow,
     intro: content.intro,
+    updated: content.updated,
     isPolicy: !!content.isPolicy,
   };
 }

package/apps/storefront/src/lib/subscription/model.ts

@@ -43,6 +43,74 @@ export interface SubscriptionFigure {
   real?: boolean;
 }
 
+/**
+ * The account-management actions a subscriber can take on an Autopilot order
+ * (F10). The storefront never EXECUTES these — each is a handoff into the
+ * tenant's product-owned manage-subscription portal (see {@link
+ * SubscriptionManagePortal}); this enum just gives the entry points stable,
+ * typed identities so the copy, ordering, and analytics hooks are consistent.
+ */
+export type SubscriptionManageAction =
+  | "skip"
+  | "pause"
+  | "resume"
+  | "cancel"
+  | "reschedule"
+  | "quantity"
+  | "swap"
+  | "address";
+
+/** Stable order for listing the manage actions on a surface. */
+export const SUBSCRIPTION_MANAGE_ACTIONS: SubscriptionManageAction[] = [
+  "skip",
+  "pause",
+  "resume",
+  "cancel",
+  "reschedule",
+  "quantity",
+  "swap",
+  "address",
+];
+
+/** Default label + description copy per manage action. Display only. */
+export const MANAGE_ACTION_META: Record<
+  SubscriptionManageAction,
+  { label: string; description: string }
+> = {
+  skip: {
+    label: "Skip a delivery",
+    description: "Skip your next shipment and pick back up after.",
+  },
+  pause: {
+    label: "Pause your subscription",
+    description: "Take a break — pause billing and shipments, resume anytime.",
+  },
+  resume: {
+    label: "Resume your subscription",
+    description: "Start deliveries again from a paused subscription.",
+  },
+  cancel: {
+    label: "Cancel anytime",
+    description: "Cancel your subscription with no penalty.",
+  },
+  reschedule: {
+    label: "Reschedule delivery",
+    description: "Move your next delivery date earlier or later.",
+  },
+  quantity: {
+    label: "Change quantity",
+    description: "Update how much ships each cycle.",
+  },
+  swap: {
+    label: "Swap products",
+    description: "Change which products are in your subscription.",
+  },
+  address: {
+    label: "Update address or payment",
+    description: "Change where it ships or how you pay.",
+  },
+};
+
 /**
  * One manage-subscription entry point (e.g. "Update delivery date", "Pause or
  * cancel"). This is an EDUCATION/HANDOFF link only — it points at the
@@ -56,6 +124,52 @@ export interface SubscriptionManageEntry {
   description?: string;
   /** Handoff URL into the tenant's product-owned manage-subscription flow. */
   href: string;
+  /** The typed action this entry hands off to (analytics/audit hook). */
+  action?: SubscriptionManageAction;
+}
+
+/**
+ * The provider-handoff CONTRACT for subscription management. The storefront owns
+ * only the entry points; the tenant's managed-checkout provider (Phase 2) owns
+ * the actual skip/pause/cancel/reschedule/quantity execution behind `baseHref`.
+ * A tenant supplies its portal URL and (optionally) the subset of actions it
+ * offers; `hrefForAction` overrides the default deep-link shape when the provider
+ * uses path- rather than query-based deep links.
+ */
+export interface SubscriptionManagePortal {
+  /** Base URL of the tenant's manage-subscription portal. */
+  baseHref: string;
+  /** Actions offered (in listing order). Defaults to every action. */
+  actions?: SubscriptionManageAction[];
+  /** Deep-link builder; defaults to `?action=<action>` on `baseHref`. */
+  hrefForAction?: (action: SubscriptionManageAction, baseHref: string) => string;
+}
+
+/** Default deep link into the manage portal for an action. */
+function defaultActionHref(action: SubscriptionManageAction, baseHref: string): string {
+  return `${baseHref}${baseHref.includes("?") ? "&" : "?"}action=${action}`;
+}
+
+/**
+ * Build the manage-subscription entry points for a tenant's portal — the F10
+ * skip / pause / cancel / reschedule / quantity (+ resume / swap / address)
+ * handoffs. Each entry is a plain link into `portal.baseHref`; the storefront
+ * hands off, the provider executes.
+ */
+export function buildManageEntries(
+  portal: SubscriptionManagePortal,
+): SubscriptionManageEntry[] {
+  const actions = portal.actions ?? SUBSCRIPTION_MANAGE_ACTIONS;
+  const hrefFor = portal.hrefForAction ?? defaultActionHref;
+  return actions.map((action) => {
+    const meta = MANAGE_ACTION_META[action];
+    return {
+      label: meta.label,
+      description: meta.description,
+      href: hrefFor(action, portal.baseHref),
+      action,
+    };
+  });
 }
 
 /**

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

@@ -51,9 +51,9 @@ export class FixtureToTClient implements ToTClient {
   }
 
   private scoped(): CatalogProduct[] {
-    // Fixtures are single-tenant ("pilot"); scope-filter anyway so the seam is
-    // honest for many-tenant.
-    return this.products.filter((p) => p.tenant_id === this.scope || true);
+    // Fixtures are now multi-tenant: every read is scoped to this client's
+    // tenant so one tenant can never see another's products.
+    return this.products.filter((p) => p.tenant_id === this.scope);
   }
 
   async listProducts(query: ListProductsQuery = {}): Promise<ListProductsResponse> {