@tokenoftrust/storefront-runner 1.4.1 → 2.0.0

package/packages/public-runtime/src/activity/catalog.ts

@@ -1,5 +1,5 @@
 // ─────────────────────────────────────────────────────────────────────────────
-// Action catalog — the ALLOWLISTED registry of actionKeys (card D0).
+// Action catalog — the ALLOWLISTED registry of actionKeys.
 //
 // The `action` field of an ActivityEvent is NEVER a free string. It is one of
 // the keys below, and each key ships a spec: which actor kinds may emit it,
@@ -7,22 +7,22 @@
 // default-DENY allowlist of payload fields that survive redaction for it.
 //
 // WHY A FIXED CATALOG. Free-string actions make the downstream query/alert
-// surface (D5/D6/D7) intractable: you cannot build a dashboard, an alert rule,
+// surface intractable: you cannot build a dashboard, an alert rule,
 // or a redaction allowlist against an open vocabulary. Adding a NEW action is a
 // deliberate edit HERE (plus, for the CLI, the JS mirror + its keep-in-step
 // test — see the module README), not an ad-hoc string at a call site.
 //
 // GROUNDING. These keys were reverse-engineered from the activity surfaces that
-// already exist informally in this repo, so D1–D3 map onto them 1:1 rather than
-// inventing new vocab:
+// already exist informally in this repo, so those surfaces map onto them 1:1
+// rather than inventing new vocab:
 //   • CLI command dispatch + ~/.tot/activity.log  → cli.command.*
 //   • obstacle beacon (obstacle-beacon.cjs)       → cli.obstacle.reported
 //   • local→hosted dev bridge (dev/activityStore, runtimeStore, obstacleStore)
 //                                                 → dev.*
 //   • preview serve / reconcile / Gitea webhook   → preview.* / reconcile.* / webhook.*
-//   • deploy version observed (provenance, D2)    → deploy.version_observed
+//   • deploy version observed (provenance)         → deploy.version_observed
 //   • ShipLoop CHANGE_STATES + admin routes
-//     (accept/reject/ship/revert/rollback/integrate/publish/invite/retire)
+//     (accept/reject/ship/revert/rollback/integrate/publish/invite)
 //                                                 → change.* / content.* / grant.* / preview.*
 //   • app installs (STOREFRONT_APPS_DB)           → app.*
 //   • agent cohort (later)                         → agent.*
@@ -154,7 +154,7 @@ export const ACTION_CATALOG = {
     desc: "A preview build finished (result: ok|failed).",
   },
   "preview.override": {
-    // D9: an AUTHENTICATED operator accepted the risk of a blocking-safety finding for a
+    // An AUTHENTICATED operator accepted the risk of a blocking-safety finding for a
     // specific commit (/api/preview/override), letting the reconcile materialize past it.
     // Cockpit-gated (signed-in real developer capability + session tenant), so the acting
     // cohort is owner→merchant, staff→admin, or a signed-in developer→dev. The required
@@ -166,7 +166,7 @@ export const ACTION_CATALOG = {
   "webhook.reconcile.received": {
     // Gitea candidate-reconcile webhook (api/changes/candidate-reconcile.ts). Low
     // volume (one per PR push, NOT per request) and the lifecycle PARTNER of
-    // `reconcile.terminal` — timelined so D7's reconcile-hang watchdog can correlate
+    // `reconcile.terminal` — timelined so the reconcile-hang watchdog can correlate
     // "received" against "terminal" for the same changeId and detect an ABSENCE.
     actors: ["system"], source: "server", sinks: LIFECYCLE,
     argsAllow: ["repo", "action", "branch", "changeId"], renderedAllow: [],
@@ -174,18 +174,43 @@ export const ACTION_CATALOG = {
   },
   "reconcile.terminal": {
     // A reconcile reached a terminal state (reconciled|blocked|failed). Low
-    // volume, high value → timelined for the ops UI (D5).
+    // volume, high value → timelined for the ops UI.
     actors: ["system"], source: "server", sinks: LIFECYCLE,
-    argsAllow: ["changeId", "result", "evidenceStatus"], renderedAllow: [],
+    argsAllow: ["changeId", "result", "evidenceStatus", "evidencePushError"], renderedAllow: [],
     desc: "A candidate reconcile reached a terminal state.",
   },
+  "candidate.closed": {
+    // A `pull_request` `closed` webhook drove a candidate to its TERMINAL status
+    // (candidate-reconcile.ts): `merged` (squash-merged) or `closed` (closed
+    // unmerged), so the row leaves the operator's review queue. Low volume (one
+    // per PR close), high value — the end-of-life marker for a candidate's timeline.
+    actors: ["system"], source: "server", sinks: LIFECYCLE,
+    argsAllow: ["changeId", "merged", "result", "status"], renderedAllow: [],
+    desc: "A merged/closed PR webhook transitioned a candidate to a terminal state.",
+  },
+  "prebuild.dispatched": {
+    // Background pre-build (docs/epics/proposed/storefront-instant-static-rollback.md
+    // Addendum §B): a successful candidate reconcile fired (or failed to fire) the
+    // materialize+validate+STAGE-ONLY repository_dispatch for a static-publish
+    // tenant (candidate-reconcile.ts). Fail-open by design — this never gates the
+    // candidate reaching `ready`; recorded so a stuck/never-dispatched prebuild is
+    // observable rather than silently absent.
+    actors: ["system"], source: "server", sinks: LIFECYCLE,
+    argsAllow: ["changeId", "headSha"], renderedAllow: [],
+    desc: "A candidate's background static-prebuild dispatch (stage-only) succeeded or failed.",
+  },
 
-  // ── Deploy provenance (source: server or cli) — card D2 ────────────────────
+  // ── Deploy provenance (source: server or cli) ────────────────────
   "deploy.version_observed": {
     actors: ["system", "dev"], source: "server", sinks: PROVENANCE,
     argsAllow: ["version", "commit", "env", "observedFrom"], renderedAllow: [],
     desc: "A deployed worker version/commit was observed (provenance).",
   },
+  "publish.readiness_evidence.recorded": {
+    actors: ["system"], source: "server", sinks: PROVENANCE,
+    argsAllow: ["routes", "cfFailures", "statusMismatches", "targetHealthy"], renderedAllow: [],
+    desc: "Go-live readiness dual-run evidence was recorded for a tenant (u9 producer).",
+  },
 
   // ── ShipLoop change lifecycle (source: ui/server) ──────────────────────────
   // 1:1 with the admin ship routes + CHANGE_STATES (change-record.ts). Low
@@ -208,8 +233,17 @@ export const ACTION_CATALOG = {
     argsAllow: ["changeId"], renderedAllow: ["reason"],
     desc: "A change was rejected (reason required).",
   },
+  "change.resolve": {
+    // One-click conflict resolution via
+    // candidate_refresh. Same admission ladder as change.reject (resolveShipSession
+    // → ship-on-behalf floor), so the same actor cohort. `strategy` is a
+    // low-cardinality enum (ours|theirs|merge), safe to render.
+    actors: ["admin"], source: "ui", sinks: LIFECYCLE,
+    argsAllow: ["changeId"], renderedAllow: ["strategy"],
+    desc: "A not-mergeable change was resolved by rebuilding it from the base tip under a strategy.",
+  },
   "change.ship": {
-    // D6: the admin/cockpit "Publish" (go-live) handler admits the store OWNER
+    // The admin/cockpit "Publish" (go-live) handler admits the store OWNER
     // (merchant), ToT staff (admin), a ship-on-behalf developer (dev), AND the
     // headless Bearer/CLI operator (agent) — the actor list reflects who actually
     // reaches POST /api/changes/ship, not a placeholder subset.
@@ -218,7 +252,7 @@ export const ACTION_CATALOG = {
     desc: "A change was shipped to the live channel.",
   },
   "change.revert": {
-    // D9: same admission ladder as change.ship/rollback (resolveShipSession) — owner
+    // Same admission ladder as change.ship/rollback (resolveShipSession) — owner
     // (merchant), staff (admin), ship-on-behalf dev, headless operator (agent). The
     // `/api/changes/revert` route gates on the SAME seam, so the emitter cohort matches.
     actors: ["admin", "merchant", "dev", "agent"], source: "ui", sinks: LIFECYCLE,
@@ -226,7 +260,7 @@ export const ACTION_CATALOG = {
     desc: "A change was reverted.",
   },
   "change.hotfix": {
-    // D9: the owner-only emergency HOTFIX lane (/api/changes/hotfix) — a DISTINCT verb
+    // The owner-only emergency HOTFIX lane (/api/changes/hotfix) — a DISTINCT verb
     // from change.ship (never a `--base main` flag): a bypass-normal-flow live promote
     // from `main` while `preview` holds other unshipped work. Same resolveShipSession
     // ladder as ship/rollback (owner ⊇ ship-on-behalf), so the same cohort set.
@@ -235,18 +269,36 @@ export const ACTION_CATALOG = {
     desc: "An emergency hotfix was released to the live channel (bypassing unshipped preview work).",
   },
   "change.rollback": {
-    // D6: same admission ladder as change.ship (resolveShipSession) — owner
+    // Same admission ladder as change.ship (resolveShipSession) — owner
     // (merchant), staff (admin), ship-on-behalf dev, headless operator (agent).
     actors: ["admin", "merchant", "dev", "agent"], source: "ui", sinks: LIFECYCLE,
     argsAllow: ["changeId", "toVersion"], renderedAllow: ["reason"],
     desc: "The live channel was rolled back to a prior version.",
   },
   "change.integrate": {
-    // D6: accept/integrate (resolveShipSession) admits the same cohort set.
+    // Accept/integrate (resolveShipSession) admits the same cohort set.
     actors: ["admin", "merchant", "dev", "agent"], source: "ui", sinks: LIFECYCLE,
     argsAllow: ["changeId"], renderedAllow: [],
     desc: "A change was integrated into the shared preview.",
   },
+  "change.rebuild": {
+    // Retry a dead aggregate rebuild without a new merge (/api/changes/rebuild).
+    // Same admission ladder as change.integrate/revert (resolveShipSession) — the
+    // route gates on the SAME seam, so the emitter cohort matches. No changeId: a
+    // rebuild retries the tenant's most recent integration attempt, not one candidate.
+    actors: ["admin", "merchant", "dev", "agent"], source: "ui", sinks: LIFECYCLE,
+    argsAllow: [], renderedAllow: [],
+    desc: "A dead aggregate rebuild was retried without a new merge.",
+  },
+  "change.resync": {
+    // Advance the shared preview aggregate to an out-of-band branch tip
+    // without a candidate/<changeId> PR (/api/changes/resync). Same admission
+    // ladder as change.integrate/rebuild (resolveShipSession). No changeId: a
+    // resync pins an operator-supplied branch/sha, not one candidate.
+    actors: ["admin", "merchant", "dev", "agent"], source: "ui", sinks: LIFECYCLE,
+    argsAllow: [], renderedAllow: [],
+    desc: "The shared preview aggregate was resynced to an out-of-band branch tip.",
+  },
   "change.transition": {
     // Generic SDLC transition for states without a dedicated verb above
     // (triage↔in_progress↔ready_for_review↔announced↔closed).
@@ -262,7 +314,7 @@ export const ACTION_CATALOG = {
     desc: "Tenant customization/content was published to a version.",
   },
   "content.checkout_style.saved": {
-    // NEW (D10): a tenant's checkout styling was saved to a versioned test artifact
+    // NEW: a tenant's checkout styling was saved to a versioned test artifact
     // (Settings → Checkout styling → publishToTest spine). A persistent tenant
     // customization — low volume, high value → timelined. Actor cohort mirrors the
     // route's own auth (resolveOwnerSession): a merchant saving their own tenant, or
@@ -272,7 +324,7 @@ export const ACTION_CATALOG = {
     desc: "A tenant's checkout styling was saved to a version.",
   },
   "change.go_live": {
-    // D9: renamed from the orphaned, un-namespaced `go_live` (the ONE key that broke the
+    // Renamed from the orphaned, un-namespaced `go_live` (the ONE key that broke the
     // domain-prefix rule). The snake_case suffix is kept (the `deploy.version_observed`
     // precedent) — only the missing `change.` domain prefix is added. Wired into
     // /api/preview/promote (promote the current preview snapshot to live).
@@ -285,9 +337,9 @@ export const ACTION_CATALOG = {
   // Invitee identity is PII → DROPPED by allowlist; only the role/resource +
   // an opaque hashed invitee ref (rendered) survive.
   "grant.invite": {
-    // D6: the self-serve "Invite a Developer" handler admits an owner (merchant) or
+    // The self-serve "Invite a Developer" handler admits an owner (merchant) or
     // staff (admin) session, and the headless operator (agent) via the Bearer seam.
-    // D11: the SECOND invite path (grants/team-invite.ts) is session-authed by vendor
+    // The SECOND invite path (grants/team-invite.ts) is session-authed by vendor
     // MEMBERSHIP — a signed-in team member who is neither owner nor staff classifies as
     // "dev" (see uiActor.classifyActorKind), so `dev` joins the admission set.
     actors: ["admin", "merchant", "dev", "agent"], source: "ui", sinks: LIFECYCLE,
@@ -295,14 +347,14 @@ export const ACTION_CATALOG = {
     desc: "A developer/team invite was issued.",
   },
   "grant.approve": {
-    // D6: the browserless CLI sign-in approval is taken by whoever is signed in
+    // The browserless CLI sign-in approval is taken by whoever is signed in
     // (owner→merchant, staff→admin, or a signed-in developer→dev).
     actors: ["admin", "merchant", "dev"], source: "ui", sinks: LIFECYCLE,
     argsAllow: ["role", "resource"], renderedAllow: [],
     desc: "A pending access request / CLI sign-in was approved.",
   },
   "grant.revoke": {
-    // D9: the self-serve "remove a developer from my team" handler (/api/grants/revoke),
+    // The self-serve "remove a developer from my team" handler (/api/grants/revoke),
     // the inverse of grant.invite — same resolveOwnerSession seam, so the same cohort
     // (owner→merchant, staff→admin, headless operator→agent). The revoked developer's
     // identity is PII → DROPPED by the allowlist; only an opaque hashed ref survives.
@@ -320,10 +372,14 @@ export const ACTION_CATALOG = {
     argsAllow: ["changeId"], renderedAllow: ["inviteeRef"],
     desc: "A reviewer/developer was invited to a preview.",
   },
-  "preview.retire": {
-    actors: ["admin", "merchant"], source: "ui", sinks: LIFECYCLE,
-    argsAllow: ["changeId"], renderedAllow: [],
-    desc: "A preview environment was retired.",
+  "preview.evidence.retry": {
+    // An operator retried the change_report_evidence push for an already-`ready`
+    // candidate whose evidence.pushFailed was set (candidate-evidence-retry.ts) —
+    // the manual recovery for fb-1787938036559-ppmu4e when the automatic retry in
+    // reportPreviewEvidence still didn't land.
+    actors: ["admin", "merchant", "dev", "system"], source: "server", sinks: LIFECYCLE,
+    argsAllow: ["changeId", "versionId", "pushed"], renderedAllow: [],
+    desc: "An operator retried a candidate's evidence push to MCP after it failed.",
   },
   "store.connect": {
     actors: ["merchant", "admin"], source: "ui", sinks: LIFECYCLE,
@@ -377,8 +433,8 @@ export const ACTION_CATALOG = {
 
   // ── Agent cohort (source: server/cli) — later ──────────────────────────────
   // Placeholder spine so the agent cohort (a later card) has stable keys to emit
-  // against without reopening D0. Args are deliberately empty until that card
-  // defines what an agent action is allowed to record.
+  // against without reopening the action catalog. Args are deliberately empty until
+  // that card defines what an agent action is allowed to record.
   "agent.action.invoked": {
     actors: ["agent"], source: "server", sinks: HIGH_VOLUME,
     argsAllow: ["tool"], renderedAllow: [],
@@ -390,9 +446,9 @@ export const ACTION_CATALOG = {
     desc: "An automated agent action finished.",
   },
 
-  // ── D11: remaining grant/staff-ops gaps + machine/agent-driven mutations ─────
-  // Follow-on to D0–D8: wires the invite/grant paths, staff-impersonation, cache,
-  // and machine-authed (signature/idempotency/app-JWT) mutations that D6 left out.
+  // ── Remaining grant/staff-ops gaps + machine/agent-driven mutations ─────
+  // Wires the invite/grant paths, staff-impersonation, cache,
+  // and machine-authed (signature/idempotency/app-JWT) mutations the earlier catalog entries left out.
   // Grant/staff actions are low-volume lifecycle → timelined; the machine cohort's
   // high-volume streams (order-forward, attribution) are analytics-only.
   "grant.issue": {
@@ -433,7 +489,7 @@ export const ACTION_CATALOG = {
   },
   "store.connect.completed": {
     // domain/callback.ts — the CI completion callback for the www-domain job, the
-    // machine-side terminal PARTNER of D6's `store.connect`. Signature-authed, one per
+    // machine-side terminal PARTNER of `store.connect`. Signature-authed, one per
     // connect run (rare) → low-volume lifecycle terminal, timelined like reconcile.terminal.
     actors: ["system"], source: "server", sinks: LIFECYCLE,
     argsAllow: ["status", "state", "action"], renderedAllow: [],
@@ -469,7 +525,7 @@ export const ACTION_CATALOG = {
 
   // ── Meta (source: server) ──────────────────────────────────────────────────
   "system.ingest.rejected": {
-    // The ingest endpoint (D4) rejected an event (unknown action, actor
+    // The ingest endpoint rejected an event (unknown action, actor
     // mismatch, canary tripped). Self-telemetry so a leak attempt is visible.
     actors: ["system"], source: "server", sinks: HIGH_VOLUME,
     argsAllow: ["reason", "attemptedAction"], renderedAllow: [],

package/packages/public-runtime/src/activity/event.ts

@@ -1,12 +1,12 @@
 // ─────────────────────────────────────────────────────────────────────────────
-// ActivityEvent — the versioned actor×action telemetry envelope (card D0).
+// ActivityEvent — the versioned actor×action telemetry envelope.
 //
 // One event = "an ACTOR performed an ACTION, here is the OUTCOME." It is the
 // single shape every operational-activity emitter produces and every sink
 // stores, across the whole storefront platform (dev/CLI first, then merchant/
-// admin/agent). Downstream cards import this directly:
-//   D1 server recordActivity() · D2 deploy provenance · D3 CLI emitActivity
-//   D4 ingest+store · D5 query/timeline UI · D6/D7 alerts.
+// admin/agent). Downstream consumers import this directly: server
+// recordActivity() · deploy provenance · CLI emitActivity · ingest+store ·
+// the query/timeline UI · alerts.
 //
 // TWO ZONES, and the split is load-bearing:
 //   1. CORE fields (everything except `payload`) — always safe to store. They
@@ -86,9 +86,9 @@ export interface ActivityScope {
    */
   traceId?: string;
   /**
-   * BUILD PROVENANCE (card D2). The git commit SHA the running server/edge build
+   * BUILD PROVENANCE. The git commit SHA the running server/edge build
    * was cut from — stamped by the emitter onto every SERVER-sourced event so the
-   * query surface (D5) can derive **deploy skew**: is the build that produced this
+   * query surface can derive **deploy skew**: is the build that produced this
    * event == the pushed umbrella tip, or is a stale worker still serving? Core,
    * non-secret by construction (a 40-hex git sha, never PII/free-text), so it is
    * never redacted. Absent on `cli`/`ui`-sourced events and on any build with no

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

@@ -1,7 +1,7 @@
 // ─────────────────────────────────────────────────────────────────────────────
 // @tot/public-runtime/activity — the operational activity telemetry contract.
 //
-// Card D0: the actor×action ActivityEvent envelope, the allowlisted action
+// The actor×action ActivityEvent envelope, the allowlisted action
 // catalog, and the default-deny redaction contract. This is the FOUNDATION the
 // downstream cards import directly — nothing here does I/O or picks a store; it
 // is pure types + pure functions so server, edge, and the CLI's JS mirror can
@@ -9,7 +9,7 @@
 // DECISIONS.md §8; the per-action routing lives on each catalog entry (sinks).
 //
 // See ./README.md for the envelope shape, catalog rules, redaction contract,
-// and the CLI-mirror keep-in-step obligation for card D3.
+// and the CLI-mirror keep-in-step obligation.
 // ─────────────────────────────────────────────────────────────────────────────
 export * from "./event.js";
 export * from "./catalog.js";

package/packages/public-runtime/src/activity/redaction.ts

@@ -1,7 +1,7 @@
 // ─────────────────────────────────────────────────────────────────────────────
-// Redaction contract for the activity payload zone (card D0).
+// Redaction contract for the activity payload zone.
 //
-// This is the surface card D8 (adversarial PII/secret-leak review) will attack,
+// This is the surface the adversarial PII/secret-leak review will attack,
 // so the posture is deliberately conservative. Three layers, in order:
 //
 //   1. DEFAULT-DENY ALLOWLIST. For a given action, ONLY the top-level payload
@@ -20,12 +20,12 @@
 //      shapes (JWTs, bearer tokens, API keys, private keys, emails, card/phone
 //      numbers) AND secret-looking KEY NAMES. A hit replaces the value with a
 //      redaction marker and is REPORTED (the fact of the hit, never the value) so
-//      D6/D7 can alert and D8 can audit. A secret-named key is dropped outright.
+//      alerting can flag it and auditing can review it. A secret-named key is dropped outright.
 //
 // The safe constructor createActivityEvent() runs all three before an event is
 // ever returned — you cannot build an event whose payload skipped redaction.
 //
-// OPEN QUESTION (owned by D1/D4): the canonical actor-id pseudonymization salt.
+// OPEN QUESTION: the canonical actor-id pseudonymization salt.
 // This module scrubs PII that leaks into the PAYLOAD, but actor.id in the CORE
 // zone is the emitter's responsibility to pseudonymize. A shared, salted,
 // non-reversible hash helper (with the salt as a Worker secret) should land with

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/catalog-d1.ts

@@ -1,6 +1,6 @@
 /**
  * D1 (edge SQLite) catalog read-model — schema + row projections (the one-store
- * target from epics/edge-read-replica.md). The storefront reads search, faceted
+ * target). The storefront reads search, faceted
  * listing, and full products from D1; the ETL emits the rows. This is the shared
  * contract both sides agree on.
  *

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