@tokenoftrust/storefront-runner 1.4.2-rc.0 → 2.0.0

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

@@ -52,6 +52,38 @@ export interface ReviewEnvironmentEvidence {
   /** Derived upstream: every `REQUIRED_FOR_PROMOTE` check is `pass`. */
   promotable: boolean;
   generatedAt: string;
+  /**
+   * True when this verdict was computed locally but the `change_report_evidence`
+   * push to MCP did NOT land (even after retry) — MCP has no evidence (or a stale
+   * one) for this commit, so `preview_status`/`change_ready` can disagree with
+   * `promotable` above (fb-1787938036559-ppmu4e). Absent/false ⇒ the push
+   * succeeded, this verdict is the same one MCP is serving. A UI/CLI should
+   * treat `true` as "evidence missing upstream — offer a retry", not as a
+   * failed verdict.
+   */
+  pushFailed?: boolean;
+  /** The push failure's error message, when `pushFailed` is true. */
+  pushError?: string;
+}
+
+/** Durable, reviewer-facing progress for one bounded candidate reconcile. */
+export interface CandidateReconcileLifecycle {
+  phase:
+    | "queued"
+    | "archive-requested"
+    | "archive-downloading"
+    | "archive-validating"
+    | "archive-ingesting"
+    | "evidence-reporting"
+    | "ready"
+    | "blocked";
+  correlationId: string;
+  startedAt: string;
+  lastUpdatedAt: string;
+  elapsedMs: number;
+  bytes?: number;
+  files?: number;
+  terminalError?: { code: string; message: string; correlationId: string; elapsedMs: number } | null;
 }
 
 /**
@@ -110,11 +142,13 @@ export interface ReviewEnvironment {
    * dead/unregistered webhook shows as "queued since <submittedAt>, never
    * picked up" instead of no record at all). Additive + optional: every OTHER
    * writer of this projection (`reconcileCandidate`, `acceptCandidateAtomic`,
-   * retire/GC) predates this field and simply carries it forward unset/
+   * terminal cleanup) simply carries it forward unset/
    * untouched — only the submit-ack path ever sets it. Deliberately distinct
    * from `updatedAt`, which every writer bumps on any recompute for any reason.
    */
   submittedAt?: string;
+  /** Bounded reconcile progress and terminal reason, if this candidate has run. */
+  reconcileLifecycle?: CandidateReconcileLifecycle;
 }
 
 /** KV key for one tenant-change `ReviewEnvironment` projection. */
@@ -136,10 +170,10 @@ export interface CandidateKv {
 }
 
 /**
- * A {@link CandidateKv} that can also DELETE a key — the eviction surface the
- * retire/GC path (unit U7) needs. Kept separate from `CandidateKv` so the many
+ * A {@link CandidateKv} that can also DELETE a key — the terminal candidate
+ * cleanup surface. Kept separate from `CandidateKv` so the many
  * write-only `{ get, put }` adapters (the webhook reconcile, build-on-demand,
- * accept) are unaffected: only the retire endpoint constructs a delete-capable
+ * accept) are unaffected: only terminal cleanup constructs a delete-capable
  * adapter. A real Cloudflare KV namespace satisfies this structurally.
  */
 export interface CandidateKvDeletable extends CandidateKv {
@@ -266,17 +300,17 @@ export async function writeReviewEnvironment(
 
 /**
  * Evict one `ReviewEnvironment` record AND remove its `changeId` from the tenant
- * index — the KV half of retire/GC (unit U7). The per-record key is deleted
+ * index. The per-record key is deleted
  * outright; the tenant index is updated by the SAME serialized read-modify-write
- * `writeReviewEnvironment` uses (see {@link serializeIndexWrite}), so a retire that
+ * `writeReviewEnvironment` uses (see {@link serializeIndexWrite}), so a deletion that
  * races a concurrent write for a DIFFERENT candidate never resurrects a dropped
  * entry or leaves a dangling index id (the corruption risk this helper exists to
  * prevent — the mirror-image of `writeReviewEnvironment`'s append).
  *
  * IDEMPOTENT by contract: deleting an already-absent candidate is a clean no-op.
  * Returns whether anything was actually removed (`true` iff the record existed OR
- * the index carried the id), so the caller can report `evicted` honestly while a
- * repeat retire still succeeds.
+ * the index carried the id), so the caller can report cleanup honestly while a
+ * repeat deletion still succeeds.
  */
 export async function deleteReviewEnvironment(
   kv: CandidateKvDeletable,

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

@@ -1,8 +1,8 @@
 /**
  * Order READ DTO — the FROZEN v1 contract shape the storefront consumes from
- * the checkout order API's `GET /commerce/orders[/:orderId]` (card 8585 / U1). Kept in
+ * the checkout order API's `GET /commerce/orders[/:orderId]` (card 8585). 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)
+ * order client, the Orders admin route, and the view-model mapping
  * all code against one source of truth.
  *
  * Authoritative API shape lives with the checkout order service; this file

package/packages/public-runtime/src/checkout-style-publish.ts

@@ -10,7 +10,7 @@
  * HMAC-SHA256 of `JSON.stringify(body)` keyed by the STORE'S ToT SECRET KEY —
  * byte-identical to the commerce service's webhook-signature verifier. That
  * secret is the storefront's `TOT_SECRET_KEY`; this is independent of the
- * provider API credentials (see decision `u11b-not-blocked-by-u7`).
+ * provider API credentials.
  *
  * Edge-safe + node-free (WebCrypto HMAC); the network call is injected so the
  * flow is fully unit-testable offline. The caller (the checkout-styling promote
@@ -190,7 +190,7 @@ export async function publishCheckoutTheme(
 /**
  * Convenience: the env → checkout service base URL for this workstream's targets.
  * qa/test use the non-prod proxy; live uses the prod proxy. Kept here so the
- * promote hook (U13) resolves one place.
+ * promote hook resolves one place.
  */
 export function checkoutServiceBaseUrl(env: CustomizationEnv): string {
   // "test" is the qa target's env; "live" is prod.

package/packages/public-runtime/src/checkout-style.ts

@@ -2,7 +2,7 @@
  * Checkout-styling data model + published-artifact read plumbing.
  *
  * The hosted checkout is styled by CSS pushed through the commerce service's theme
- * endpoint (U11). This module owns the *source of truth* for that styling: a
+ * endpoint. This module owns the *source of truth* for that styling: a
  * small, structured, tenant-editable descriptor that later units render into
  * ASCII-safe CSS. It sits on the SAME versioned publish spine as theme/content
  * (D1VersionStore + KV pointers) — resolution is per-environment via
@@ -12,11 +12,11 @@
  * Two colocated artifacts under `tenants/<id>/`:
  *   - `checkout-style.json` — the structured `CheckoutStyle` descriptor (below).
  *   - `checkout.css`        — an optional raw-CSS escape hatch a merchant edits
- *                             directly; hosted + pushed to checkout as-is (U11).
+ *                             directly; hosted + pushed to checkout as-is.
  *
  * Pure + dependency-free (node-free, edge-safe): the caller injects the same
  * `KvGet` used for theme/content, keeping this unit-testable and storage-agnostic.
- * No UI here — that's U12.
+ * No UI here — that lives elsewhere.
  */
 import type { CustomizationEnv } from "./customization-preview.js";
 import type { DeepPartial, ThemeTokens } from "./tenant.js";
@@ -64,7 +64,7 @@ export interface CheckoutStyleButton {
 
 /**
  * The structured checkout-styling descriptor — the `checkout-style.json`
- * artifact. This is the model a merchant edits (U12) and that U11 renders into
+ * artifact. This is the model a merchant edits and the renderer turns into
  * the CSS pushed to checkout. A published artifact is a `DeepPartial` of this
  * (a merchant may set one field without restating the rest); `resolveCheckout
  * Style` merges it over `DEFAULT_CHECKOUT_STYLE` so the resolved value is always
@@ -105,7 +105,7 @@ export const DEFAULT_CHECKOUT_STYLE: CheckoutStyle = {
  * Derive a checkout style FROM a tenant's brand `ThemeTokens`, so the checkout is
  * consistent with the look/feel the merchant already chose for the storefront
  * instead of a neutral default. This is the "from theme" seam: the settings editor
- * (U12) seeds a merchant's starting style from it, and a tenant that ships a brand
+ * seeds a merchant's starting style from it, and a tenant that ships a brand
  * theme gets an in-brand checkout with no hand-authoring.
  *
  * It maps the small, opinionated checkout surface onto the full theme palette:
@@ -289,13 +289,13 @@ export async function resolveCheckoutStyleCss(
 }
 
 // ---------------------------------------------------------------------------
-// CSS serialization (the artifact pushed to checkout) — U11
+// CSS serialization (the artifact pushed to checkout)
 // ---------------------------------------------------------------------------
 
 /**
  * True iff every character is 7-bit ASCII (code point < 128). The checkout
  * template cache pass is NOT Unicode-safe — a non-ASCII byte in the cached
- * checkout content yields a BLANK page. So the publisher (U11) MUST gate both
+ * checkout content yields a BLANK page. So the publisher MUST gate both
  * the generated token CSS and any raw override through this before pushing a
  * `content_url` to `/theme/foxy`. We reject rather than transliterate, so a
  * merchant is told to fix their input instead of getting silently-mangled CSS.

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

@@ -97,7 +97,7 @@ export interface BuildVariantCartPayloadOptions {
   secret?: string;
   purchaseOption?: ProductPurchaseOption;
   /**
-   * The member-adjusted EFFECTIVE price to sign (F11b), computed server-side via
+   * The member-adjusted EFFECTIVE price to sign, computed server-side via
    * membership.ts `priceForPurchaseOption` for the shopper's resolved eligibility.
    * When set it REPLACES the list/subscription price as the single signed source
    * of truth, so a given price is only ever valid for the member context it was
@@ -189,7 +189,7 @@ export function cartFieldsForVariant(
 
 /**
  * Validate a caller-supplied EFFECTIVE price before it becomes the signed source
- * of truth (F11b). The member-adjusted price (membership.ts
+ * of truth. The member-adjusted price (membership.ts
  * `priceForPurchaseOption`) is computed server-side and threaded in so the SIGNED
  * price reflects the shopper's resolved eligibility. It must be a finite,
  * non-negative amount no greater than the list price — an effective price is
@@ -325,7 +325,7 @@ export async function buildVariantCartPayload(
   variant: CatalogVariant,
   opts: BuildVariantCartPayloadOptions,
 ): Promise<VariantCartPayload> {
-  // Hide-at-launch guard (F11b): refuse to SIGN a subscription option while
+  // Hide-at-launch guard: refuse to SIGN a subscription option while
   // Autopilot is disabled. `visiblePurchaseOptions` removes subscription options
   // for such tenants, so one reaching the signer means the visibility filter was
   // bypassed (e.g. a crafted request) — signing it would mint a valid subscription