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

package/apps/storefront/tsconfig.json

@@ -1,4 +1,9 @@
 {
+  // Unlike the packages/* configs (which extend the repo's ../../tsconfig.base.json),
+  // the storefront extends Astro's own preset: it wires up .astro type resolution
+  // (.astro/types.d.ts), Astro/Vite bundler module resolution, and the Preact JSX
+  // runtime the client islands compile against. verbatimModuleSyntax is turned off
+  // (the base sets it on) because the JSX/Preact + Astro compilation model needs it.
   "extends": "astro/tsconfigs/strict",
   "compilerOptions": {
     "strict": true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "1.4.1",
+  "version": "1.4.2-rc.0",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@tot/public-runtime",
   "version": "0.1.0",
+  "description": "Public, edge-shipped storefront runtime model — renderer-safe tenant/product/catalog types, the CSP builder, the customization read/apply runtime, and the activity-telemetry contract. Node-free and open-sourceable; bundles into the Cloudflare Worker and must not import @tot/private-controlplane.",
   "private": true,
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",

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

@@ -179,6 +179,26 @@ export const ACTION_CATALOG = {
     argsAllow: ["changeId", "result", "evidenceStatus"], 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": {
+    // T1 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.version_observed": {
@@ -186,6 +206,11 @@ export const ACTION_CATALOG = {
     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,6 +233,15 @@ export const ACTION_CATALOG = {
     argsAllow: ["changeId"], renderedAllow: ["reason"],
     desc: "A change was rejected (reason required).",
   },
+  "change.resolve": {
+    // u3 (tot-merge-conflict-resolution-ux): 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
     // (merchant), ToT staff (admin), a ship-on-behalf developer (dev), AND the
@@ -247,6 +281,24 @@ export const ACTION_CATALOG = {
     argsAllow: ["changeId"], renderedAllow: [],
     desc: "A change was integrated into the shared preview.",
   },
+  "change.rebuild": {
+    // u15: 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": {
+    // u12: 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).

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/customization-preview.ts

@@ -142,6 +142,8 @@ export interface EnvResolutionInput {
   /** Platform preview-signing secret (env), if configured. */
   secret?: string | null;
   nowSeconds: number;
+  /** Request pathname — used only to exempt the token dispenser itself (see {@link isPreviewDispatcherPath}). */
+  pathname?: string;
 }
 
 export interface EnvResolution {
@@ -152,16 +154,37 @@ export interface EnvResolution {
   reject?: { status: number; message: string };
 }
 
+/**
+ * The bare tenant-preview DISPATCHER path (`/<tenant>/preview` or
+ * `/<tenant>/preview/`, e.g. `pages/preview/index.astro`, tenant-first) — the page
+ * whose ENTIRE job is to mint a fresh `__preview` token and hand it to the
+ * visitor. On a preview-prefixed host this path would otherwise hit the SAME
+ * "no token -> 401" gate `resolveCustomizationEnv` enforces for every other
+ * path, deadlocking a signed-in-but-token-less visitor: they can never reach
+ * the one page that gives them a token. Distinct from `isCandidatePreviewPath`
+ * (loginGate.ts) — that exempts several preview routes from the LOGIN wall; this
+ * exempts exactly ONE route from the TOKEN wall. `<tenant>` is required to look
+ * like a real tenant id (contains a `.`) so this never accidentally matches a
+ * sibling route. Matched on the pre-strip request path.
+ */
+export function isPreviewDispatcherPath(pathname: string): boolean {
+  const m = pathname.match(/^\/([^/]+)\/preview\/?$/);
+  return m != null && m[1]!.includes(".");
+}
+
 /**
  * Decide which customization environment to serve. Production hosts always get
  * `live` and never consult a token. Preview hosts are auth-gated: a valid,
  * unexpired, tenant-matching token yields `test` (noindex); anything else is
- * rejected.
+ * rejected. The one exception is the token-dispenser path itself (see
+ * {@link isPreviewDispatcherPath}) — it renders the dispatcher's own minimal
+ * page, never tenant content, so it's let through as `live`/no-token rather
+ * than 401ing on the very request that would otherwise fetch it a token.
  */
 export async function resolveCustomizationEnv(
   input: EnvResolutionInput,
 ): Promise<EnvResolution> {
-  if (!input.isPreviewHost) {
+  if (!input.isPreviewHost || isPreviewDispatcherPath(input.pathname ?? "")) {
     return { env: "live", noindex: false };
   }
   if (!input.secret) {

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

@@ -15,6 +15,7 @@ import {
   type ChannelName,
   type PointerRecord,
   type SiteVersionManifest,
+  type SiteVersionSummary,
 } from "./customization-versioning.js";
 import type { CustomizationEnv } from "./customization-preview.js";
 
@@ -93,6 +94,27 @@ export async function resolveChannelVersion(
   return pointer?.channels?.[channel] ?? null;
 }
 
+/**
+ * The static-bundle `treeDigest` a channel currently serves (ADR 0012), or null
+ * when the tenant has no digest companion for that channel (a hosted tenant — it
+ * sets only `channels`, never `channelDigests`).
+ *
+ * This is the RECONCILED read the digest-addressed serving path
+ * (`static-bundle.ts`), the pointer verify (`createPointerVerifyTarget`), and
+ * the pointer-served "current" read (`resolveStaticLiveDigestFromPointer`) use
+ * INSTEAD of `resolveChannelVersion` for a static tenant: the versionId
+ * (`channels[ch]`, the Gitea sha) is NOT the R2 key — the treeDigest is, and it
+ * lives here. Reads the pointer fresh; never throws.
+ */
+export async function resolveChannelDigest(
+  get: KvGet,
+  tenantId: string,
+  channel: ChannelName,
+): Promise<string | null> {
+  const pointer = await readPointer(get, tenantId);
+  return pointer?.channelDigests?.[channel] ?? null;
+}
+
 /** Read one immutable site-version manifest, or null. Never throws. */
 export async function readSiteVersion(
   get: KvGet,
@@ -108,12 +130,112 @@ export async function readSiteVersion(
   }
 }
 
+/** A manifest is BUILT (servable) when it exists AND materialized ≥1 artifact. */
+function isBuiltManifest(m: SiteVersionManifest | null): m is SiteVersionManifest {
+  return !!m && Object.keys(m.artifacts ?? {}).length > 0;
+}
+
+/**
+ * Read a tenant's version-history index (list of summaries), NEWEST first — the
+ * runtime read-side view of the same `siteVersionIndexKey` the KV store appends
+ * to (stored oldest-first). Never throws — malformed/absent → `[]`.
+ */
+export async function readSiteVersionIndex(
+  get: KvGet,
+  tenantId: string,
+): Promise<SiteVersionSummary[]> {
+  const raw = await get(siteVersionIndexKey(tenantId));
+  if (!raw) return [];
+  try {
+    return (JSON.parse(raw) as SiteVersionSummary[]).slice().reverse();
+  } catch {
+    return [];
+  }
+}
+
+/** The outcome of self-healing a channel pointer to a SERVABLE version. */
+export interface ServableChannelVersion {
+  /**
+   * The versionId to actually SERVE from: the pointed version when it is built,
+   * else the newest BUILT version in history (self-heal), else `null` (nothing
+   * built at all — the caller falls back to build-time, still never a bare 404).
+   */
+  versionId: string | null;
+  /** The versionId the channel pointer NAMES (may dangle at an unbuilt version). */
+  pointedVersionId: string | null;
+  /**
+   * True when the pointer named a version with no built manifest — so the read
+   * was self-healed onto an older built version (or found none). Signals the
+   * caller to enqueue a rebuild of the pointed version.
+   */
+  dangling: boolean;
+}
+
+/** Optional seam so a self-healing read can enqueue a rebuild of the dangling
+ *  version. Best-effort/fail-open: never awaited into the serve path, never
+ *  throws through it. Absent ⇒ pure resolution (no side effect). */
+export type EnqueueRebuild = (info: {
+  tenantId: string;
+  channel: ChannelName;
+  versionId: string;
+}) => void;
+
+/**
+ * Resolve the SERVABLE version for a channel, self-healing a dangling pointer.
+ *
+ * A channel pointer can name a version that was never built (or whose manifest
+ * was evicted). Serving that naively empties/404s the whole surface. Instead: if
+ * the pointed version has no built manifest, fall back to the newest version in
+ * history that DOES, and flag `dangling` so the caller can enqueue a rebuild.
+ * Only kicks in when the pointed
+ * manifest is entirely absent/unbuilt — a present manifest that merely omits one
+ * path stays authoritative (unchanged behavior). Reads fresh; never throws.
+ */
+export async function resolveServableChannelVersion(
+  get: KvGet,
+  tenantId: string,
+  channel: ChannelName,
+  enqueueRebuild?: EnqueueRebuild,
+): Promise<ServableChannelVersion> {
+  const pointedVersionId = await resolveChannelVersion(get, tenantId, channel);
+  if (!pointedVersionId) {
+    return { versionId: null, pointedVersionId: null, dangling: false };
+  }
+  const pointed = await readSiteVersion(get, tenantId, pointedVersionId);
+  if (isBuiltManifest(pointed)) {
+    return { versionId: pointedVersionId, pointedVersionId, dangling: false };
+  }
+  // Dangling: the pointer names an unbuilt/absent version. Self-heal onto the
+  // newest BUILT version in history so the surface keeps rendering last-good.
+  let healed: string | null = null;
+  for (const summary of await readSiteVersionIndex(get, tenantId)) {
+    if (summary.versionId === pointedVersionId) continue;
+    if (isBuiltManifest(await readSiteVersion(get, tenantId, summary.versionId))) {
+      healed = summary.versionId;
+      break;
+    }
+  }
+  if (enqueueRebuild) {
+    try {
+      enqueueRebuild({ tenantId, channel, versionId: pointedVersionId });
+    } catch {
+      /* fail-open: enqueue is best-effort, never breaks the read */
+    }
+  }
+  return { versionId: healed, pointedVersionId, dangling: true };
+}
+
 /**
  * Resolve a single artifact's content via the VERSIONED path:
  * channel → versionId → site-version manifest → content hash → bytes. Returns
  * null (so the caller falls back to build-time) when the tenant has no channel
- * pointer, the version manifest is missing, the path isn't in the snapshot, or
- * the content is gone. Never throws.
+ * pointer, the path isn't in the snapshot, or the content is gone. Never throws.
+ *
+ * Self-healing (u3): when the channel pointer DANGLES (names an unbuilt/absent
+ * version), the artifact is read from the newest built version instead of
+ * returning null for every path — so a dangling `preview`/`live` pointer serves
+ * the last built site rather than 404ing the whole surface. See
+ * {@link resolveServableChannelVersion}.
  */
 export async function readVersionedArtifact(
   get: KvGet,
@@ -121,7 +243,7 @@ export async function readVersionedArtifact(
   channel: ChannelName,
   path: string,
 ): Promise<string | null> {
-  const versionId = await resolveChannelVersion(get, tenantId, channel);
+  const { versionId } = await resolveServableChannelVersion(get, tenantId, channel);
   if (!versionId) return null;
   const manifest = await readSiteVersion(get, tenantId, versionId);
   const contentHash = manifest?.artifacts?.[path];

package/packages/public-runtime/src/customization-versioning.ts

@@ -37,6 +37,15 @@ export type ChannelPointers = Partial<Record<ChannelName, string>>;
  * - `channels`: the versioned-publish channel pointers (`live`/`preview` →
  *   a single site `versionId`). Additive + optional; when present it is
  *   authoritative for that channel and shadows the legacy selection.
+ * - `channelDigests`: (ADR 0012) the RECONCILED static-serving companion to
+ *   `channels`. For a static-publish tenant, `channels[ch]` still holds the site
+ *   `versionId` (the tenant Gitea commit sha — the hosted contract), while
+ *   `channelDigests[ch]` holds that same publish's bundle `treeDigest` (the
+ *   content-addressed R2 key prefix `versions/<digest>/` `static-bundle.ts`
+ *   reads). The two are DISTINCT namespaces — the Gitea sha is NOT the treeDigest
+ *   — and are written in the SAME CAS pointer write (`setChannel`), so they can
+ *   never drift. Absent for a hosted tenant (which only ever sets/reads
+ *   `channels`).
  * - `rev`: optimistic-concurrency token, incremented on every successful write.
  */
 export interface PointerRecord {
@@ -45,6 +54,7 @@ export interface PointerRecord {
   live: Selection;
   test: Selection;
   channels?: ChannelPointers;
+  channelDigests?: ChannelPointers;
 }
 
 export function emptyPointer(tenantId: string): PointerRecord {

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

@@ -36,6 +36,7 @@ export * from "./raw-html-policy.js";
 export * from "./review-trust-proof.js";
 export * from "./compliance/index.js";
 export * from "./tenant-assets.js";
+export * from "./static-bundle.js";
 export * from "./binary-path.js";
 export * from "./hot-standby-readiness.js";
 export * from "./hash.js";