npm - @tokenoftrust/storefront-runner - Versions diffs - 1.4.1 → 2.0.0 - Mend

@tokenoftrust/storefront-runner 1.4.1 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (474) hide show

package/apps/storefront/src/config/resolver.ts CHANGED Viewed

@@ -55,7 +55,7 @@ function localTenantDirIds(): string[] {
   return [...ids];
 }
-// (E2) Catalog fixtures committed on disk, keyed by data scope (== out/catalog dir
+// Catalog fixtures committed on disk, keyed by data scope (== out/catalog dir
 // name). A dev tenant whose scope has fixtures is served as a real COMMERCE tenant
 // (see devTenantSeed); one without them degrades to a marketing home. Keys only —
 // the same fixtures the FixtureToTClient reads. Repo root is four up from config/.
@@ -73,7 +73,7 @@ function catalogScopes(): Set<string> {
   return scopes;
 }
-// (E3) A slug tenant (dir name != its domain) declares its resolvable appDomain in
+// A slug tenant (dir name != its domain) declares its resolvable appDomain in
 // the checkout's `.tot/config.json` `scope`. Read eagerly (tiny JSON) so synthesis
 // can resolve it at `/<domain>/`; trusted only when it looks like a hostname (has a
 // dot), mirroring scripts/tot-dev.mjs resolveDomain. Only the DEV fallback consults
@@ -110,8 +110,8 @@ function slugScopes(): Map<string, string> {
 function devFallbackResolver(): TenantResolver {
   if (!import.meta.env.DEV) return staticResolver;
   const staticIds = new Set(staticTenants.map((t) => t.tenant_id));
-  const withCatalog = catalogScopes(); // E2
-  const scopes = slugScopes(); // E3
+  const withCatalog = catalogScopes();
+  const scopes = slugScopes();
   const dev = devTenantsToSeed(localTenantDirIds(), staticIds, getTenantTheme, {
     scopeFor: (id) => scopes.get(id),
     hasCatalog: (scope) => withCatalog.has(scope),

package/apps/storefront/src/layouts/Layout.astro CHANGED Viewed

@@ -23,6 +23,9 @@ import { referenceTheme } from "@/themes/reference";
 import { mergeTheme } from "@/themes/schema";
 import { organizationLd, websiteLd } from "@/lib/jsonld";
 import { nonceInlineTags, CHROME_BODY_MARKER } from "@/lib/rawMarketingHtml";
+import { resolveHeaderVariant, resolveFooterVariant } from "@/lib/chrome/variant";
+import type { HeaderVariant, FooterVariant } from "@/lib/chrome/model";
+import { renderIntegrationPhases } from "@tot/public-runtime";
 import { readViewerSession } from "@/lib/auth/route";
 import AppWidgetFrame from "@/components/apps/AppWidgetFrame.astro";
 import { getRegistryService } from "@/lib/apps/adminService.js";
@@ -36,15 +39,70 @@ interface Props {
   ogImage?: string;
   noindex?: boolean;
   jsonLd?: Record<string, unknown> | Record<string, unknown>[];
+  /** Alternate RSS/Atom feeds this page advertises (threaded to <Seo>). */
+  feeds?: { title: string; href: string }[];
   /** Wider pages (PLP/home) drop the prose max-width. */
   fullBleed?: boolean;
+  /**
+   * Explicit per-page header/footer content-variant override (see
+   * lib/chrome/model.ts HeaderVariant/FooterVariant). NEVER inferred from the
+   * route/CSS/title — a page that wants e.g. a minimal checkout header sets
+   * this prop. Absent ⇒ the tenant's chrome-config default
+   * (chrome.header.variant / chrome.footer.variant). An unrecognized value
+   * (page-supplied or the config's own default) fails closed with an
+   * actionable error rather than silently falling back.
+   */
+  headerVariant?: HeaderVariant;
+  footerVariant?: FooterVariant;
+  // --- Article SEO hardening: pass-through to <Seo> (all additive) ---
+  article?: import("@/lib/seo/meta.js").ArticleMeta;
+  imageAlt?: string;
+  imageWidth?: number;
+  imageHeight?: number;
+  twitterSite?: string;
+  twitterCreator?: string;
+  canonicalOverride?: string;
+  // --- hreflang / <html lang> (additive) ---
+  /** Per-variant `hreflang` alternates for a translated article; threaded to
+   *  <Seo>. Absent/empty ⇒ no alternate links (singleton unchanged). */
+  alternates?: import("@/lib/seo/alternates.js").Alternate[];
+  /** Overrides `<html lang>` (e.g. a translated article's `inLanguage`). Absent ⇒
+   *  the tenant-locale default, so non-translated pages are unchanged. */
+  lang?: string;
 }
-const { title, description, path, ogType, ogImage, noindex, jsonLd } =
-  Astro.props;
+const {
+  title,
+  description,
+  path,
+  ogType,
+  ogImage,
+  noindex,
+  jsonLd,
+  feeds,
+  article,
+  imageAlt,
+  imageWidth,
+  imageHeight,
+  twitterSite,
+  twitterCreator,
+  canonicalOverride,
+  alternates,
+  lang,
+  headerVariant,
+  footerVariant,
+} = Astro.props;
 const { tenant, themeStyle, canonicalBase, basePath, cspNonce, features, capabilities } =
   Astro.locals;
+// Fixed-phase integration engine (ext-kernel-04): ONE engine emits the
+// renderer-owned phases (platform.environment, consent.defaults, head.early,
+// body.start, document.deferred) into the head + body-start + body-deferred
+// boundaries. `rawHtmlResponse` is the other mount of the SAME engine, so both
+// documents carry byte-identical phase markup. The nonce is stamped per response
+// from a placeholder by the middleware, never serialized (ADR 0018).
+const integrationPhases = renderIntegrationPhases(Astro.locals.integrationPlan, cspNonce);
 // Organization JSON-LD is emitted site-wide (brief §8); pages add their own
 // graphs (Product, BreadcrumbList…) via the jsonLd prop.
 const pageGraphs = jsonLd ? (Array.isArray(jsonLd) ? jsonLd : [jsonLd]) : [];
@@ -58,6 +116,12 @@ const theme = mergeTheme(referenceTheme, tenant.theme_tokens);
 const chrome = await Astro.locals.content.getChrome();
+// Explicit variant resolution (fail-closed): the page's override wins over
+// the tenant's chrome-config default; an unrecognized value throws with an
+// actionable message rather than silently falling back (lib/chrome/variant.ts).
+const resolvedHeaderVariant = resolveHeaderVariant(headerVariant, chrome.header.variant);
+const resolvedFooterVariant = resolveFooterVariant(footerVariant, chrome.footer.variant);
 // SHARED CHROME: if the tenant ships content/<id>/chrome.html (the pixel-perfect
 // header/footer the raw marketing pages use), render THAT chrome around the
 // Layout content too — so commerce pages (collections/products/search/…) share
@@ -65,7 +129,7 @@ const chrome = await Astro.locals.content.getChrome();
 // <!--PAGE_BODY-->: everything before = header, after = footer; pull its tenant
 // stylesheet links into <head>; nonce its inline tags for CSP. Tenants without a
 // chrome.html keep the token-driven Header/Footer (below).
-const chromeHtml = await Astro.locals.content.getChromeHtml();
+const chromeHtml = await Astro.locals.content.getChromeHtml(path);
 let sharedChrome: { header: string; footer: string; css: string[] } | null = null;
 if (chromeHtml && chromeHtml.includes(CHROME_BODY_MARKER)) {
   const headEnd = chromeHtml.indexOf("</head>");
@@ -85,7 +149,7 @@ if (chromeHtml && chromeHtml.includes(CHROME_BODY_MARKER)) {
 const compliance = tenant.compliance;
-// Site-chrome data resolution (unit I4 — chrome/* is the canonical, prop-driven
+// Site-chrome data resolution (chrome/* is the canonical, prop-driven
 // component set; this Layout is the ONE place that resolves session/feature/
 // theme state into their props. Skipped entirely when sharedChrome (a raw
 // content/<id>/chrome.html override) is present — that path wins outright.
@@ -119,25 +183,34 @@ if (features.catalog) {
 // white logo); a light header always shows the text wordmark (no logo image).
 const headerDark = theme.brand.headerVariant === "dark";
 const headerLogoSrc = headerDark ? theme.brand.logoLight : theme.brand.logoDark;
-const headerLogo =
+const themeHeaderLogo =
   headerDark && headerLogoSrc && /^(https?:|\/)/.test(headerLogoSrc)
     ? { src: headerLogoSrc, alt: tenant.displayName }
     : undefined;
+// chrome.header.brand (lib/chrome/model.ts ChromeBrand) is the governed,
+// schema-validated brand identity — SOURCE OF TRUTH per field when set,
+// falling back to the theme-derived values above only where a field is
+// absent, so a tenant that hasn't authored a brand config is unaffected.
+const brand = chrome.header.brand;
+const brandLogoValid = brand?.logo && /^(https?:|\/)/.test(brand.logo.src) ? brand.logo : undefined;
+const headerLogo = brandLogoValid ?? themeHeaderLogo;
+const headerWordmark = brand?.label ?? tenant.displayName;
+const headerBrandHref = brand?.href;
 // Footer bottom bar: a "Legal"-titled column's links win; otherwise every
 // column's links flatten into the policy-link row (mirrors the retired
 // nav/Footer.astro exactly).
 const legalCol = chrome.footer.columns.find((c) => /legal/i.test(c.title));
 const bottomLinks = legalCol ? legalCol.links : chrome.footer.columns.flatMap((c) => c.links);
-const legalLine = `© ${new Date().getFullYear()} ${tenant.displayName}${
-  chrome.footer.legal ? ` · ${chrome.footer.legal}` : ""
-}`;
+const legalBase = chrome.footer.bottom?.copyright ?? `© ${new Date().getFullYear()} ${tenant.displayName}`;
+const legalLine = `${legalBase}${chrome.footer.bottom?.note ? ` · ${chrome.footer.bottom.note}` : ""}`;
 const analyticsToken = import.meta.env.PUBLIC_CF_ANALYTICS_TOKEN;
 const analyticsEnabled =
   analyticsToken && !/REPLACE|PLACEHOLDER/i.test(analyticsToken);
-// Private-app widgets (D5) — global.footer slot. Resolved once here so it
+// Private-app widgets — global.footer slot. Resolved once here so it
 // renders for BOTH footer paths below (the tenant-owned chrome.html splice
 // and the generic <Footer>) instead of being owned by either. No dark-mode
 // preference infra exists yet — "light" is the only theme hint until it does.
@@ -156,10 +229,18 @@ const footerWidgets = await renderWidgetSlot(
 ---
 <!doctype html>
-<html lang={tenant.locale.split("-")[0] ?? "en"} data-base-path={basePath || undefined}>
+<html lang={lang ?? tenant.locale.split("-")[0] ?? "en"} data-base-path={basePath || undefined}>
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
+    {/* Renderer-owned head phases (platform.environment → consent.defaults →
+        head.early), emitted before any tenant/app code — the Layout half of "one
+        engine, two mounts" (rawHtmlResponse is the other). Same engine output, so
+        both mounts are byte-identical. Carries only public values; the nonce is a
+        script attribute stamped per response, never serialized (ADR 0018). */}
+    <Fragment set:html={integrationPhases.head} />
     <link rel="icon" type="image/svg+xml" href={theme.brand.favicon} />
     {/* Per-tenant theme tokens injected at the edge (brief §7). The id is the
@@ -185,6 +266,15 @@ const footerWidgets = await renderWidgetSlot(
       ogImage={ogImage}
       noindex={noindex}
       jsonLd={allJsonLd}
+      feeds={feeds}
+      article={article}
+      imageAlt={imageAlt}
+      imageWidth={imageWidth}
+      imageHeight={imageHeight}
+      twitterSite={twitterSite}
+      twitterCreator={twitterCreator}
+      canonicalOverride={canonicalOverride}
+      alternates={alternates}
     />
     {
@@ -198,6 +288,10 @@ const footerWidgets = await renderWidgetSlot(
     }
   </head>
   <body>
+    {/* body.start fallback boundary (ext-kernel-04) — the renderer-owned mount
+        point for body-start contributions, before any page content. */}
+    <Fragment set:html={integrationPhases.bodyStart} />
     <a
       href="#main"
       class="sr-only focus:not-sr-only focus:absolute focus:z-50 focus:m-3 focus:rounded-md focus:bg-[var(--color-primary)] focus:px-4 focus:py-2 focus:text-[var(--color-primary-contrast)]"
@@ -214,16 +308,20 @@ const footerWidgets = await renderWidgetSlot(
     ) : (
       <>
         <div class="sticky top-0 z-40">
-          {chrome.announcement && <AnnouncementBar text={chrome.announcement} variant="static" />}
+          {chrome.header.announcement?.messages[0] && (
+            <AnnouncementBar text={chrome.header.announcement.messages[0]} variant="static" />
+          )}
           <SiteHeader
             logo={headerLogo}
-            wordmark={tenant.displayName}
-            nav={chrome.nav}
+            wordmark={headerWordmark}
+            brandHref={headerBrandHref}
+            nav={chrome.header.nav}
             variant={headerDark ? "dark" : "light"}
-            announcement={chrome.announcement}
+            layout={resolvedHeaderVariant}
+            announcement={chrome.header.announcement?.messages[0]}
             searchAction={features.productSearch ? "/search" : undefined}
             savedItemsHref={features.savedItems ? "/saved" : undefined}
-            headerCtas={chrome.headerCtas}
+            headerCtas={chrome.header.ctas}
             authLink={authLink}
             sticky={false}
           />
@@ -244,8 +342,9 @@ const footerWidgets = await renderWidgetSlot(
         <SiteFooter
           brand={{
             wordmark: tenant.displayName,
-            contact: chrome.footer.tagline ? [chrome.footer.tagline] : undefined,
+            contact: chrome.footer.brand?.text ? [chrome.footer.brand.text] : undefined,
           }}
+          variant={resolvedFooterVariant}
           columns={chrome.footer.columns}
           newsletter={features.newsletter ? { title: "Newsletter", placeholder: "you@example.com" } : undefined}
           social={chrome.footer.social}
@@ -255,7 +354,7 @@ const footerWidgets = await renderWidgetSlot(
       </>
     )}
-    {/* Private-app widgets (D5, global.footer) — sandboxed per install; one
+    {/* Private-app widgets (global.footer) — sandboxed per install; one
         resolution above covers both footer paths. */}
     {footerWidgets.map((w) => (
       <div class="container-prose py-6">
@@ -357,6 +456,8 @@ const footerWidgets = await renderWidgetSlot(
           function fix(a) {
             var href = a.getAttribute("href");
             if (!href || href.charAt(0) !== "/" || href.charAt(1) === "/") return;
+            // Global asset namespaces are root-served under every tenant.
+            if (href.indexOf("/tenants/") === 0 || href.indexOf("/shared/") === 0) return;
             if (href === base || href.indexOf(base + "/") === 0) return;
             a.setAttribute("href", base + href);
           }
@@ -381,7 +482,7 @@ const footerWidgets = await renderWidgetSlot(
       </script>
     )}
-    {/* Dev-loop theme hot-patch (D1): tenant-hot-reload.mjs broadcasts a
+    {/* Dev-loop theme hot-patch: tenant-hot-reload.mjs broadcasts a
         `tot:theme-vars` HMR custom event on every theme.json save instead of
         forcing a full reload; swap the CSS var block in place so edits repaint
         instantly with no lost scroll position. import.meta.hot is undefined in
@@ -397,7 +498,7 @@ const footerWidgets = await renderWidgetSlot(
       </script>
     )}
-    {/* Private-app widget postMessage bridge (D5) — mounted unconditionally
+    {/* Private-app widget postMessage bridge — mounted unconditionally
         (cheap no-op with zero tracked iframes); scans for
         `[data-tot-widget-origin]` frames itself, so it doesn't need to know
         which slots rendered above. */}
@@ -431,14 +532,38 @@ const footerWidgets = await renderWidgetSlot(
       }
     </script>
-    {/* Field Web Vitals (F14 RUM) — measures LCP/INP/CLS for real visitors and
+    {/* Field Web Vitals (RUM) — measures LCP/INP/CLS for real visitors and
         beacons per-route samples to the RUM sink. ~1KB, no framework; no-ops
         where PerformanceObserver is absent. This is the per-route-template
-        signal F16's `core-web-vitals` monitor consumes (the CF Web Analytics
+        signal the `core-web-vitals` monitor consumes (the CF Web Analytics
         beacon above only gives aggregate field CWV). */}
     <script>
       import { startWebVitals } from "@/lib/analytics/webVitals";
       startWebVitals();
     </script>
+    {/* Protected-surface tamper sentinel (ext-policy-09, D-R7) — a DETECTIVE
+        runtime control. Full-parent third-party code shares this document and its
+        DOM reach can't be enforceably narrowed, so this never prevents mutation: it
+        detects tampering of the platform-owned compliance/commerce surfaces
+        (policy-04 PROTECTED_SURFACES), restores safe state, evidences it, and
+        suspends the attributable integration. No-ops when no integration plan is
+        present. */}
+    <script>
+      import { bootTamperSentinel } from "@/lib/compliance/tamper-sentinel-boot";
+      bootTamperSentinel();
+    </script>
+    {/* document.deferred global-entry boundary (ext-kernel-04) — the last phase,
+        the renderer-owned mount point for the deferred integration entry. */}
+    <Fragment set:html={integrationPhases.bodyDeferred} />
+    {/* document.deferred lifecycle boot (ext-kernel-05) — initializes the plan's
+        integrations exactly once per document, wires the reserved completed-
+        navigation event, and disposes on teardown; a no-op for an empty plan. */}
+    <script>
+      import { bootIntegrationLifecycleFromDocument } from "@tot/public-runtime";
+      bootIntegrationLifecycleFromDocument();
+    </script>
   </body>
 </html>

package/apps/storefront/src/lib/activity/alerts.ts CHANGED Viewed

@@ -1,17 +1,17 @@
 /**
- * Operational-activity ALERT conditions (card D7) — the detection layer on top of
- * the D5 query surface.
+ * Operational-activity ALERT conditions — the detection layer on top of
+ * the activity query surface.
  *
- * D1–D5 make operational activity queryable; D7 turns four specific, high-value
- * conditions in that stream into ALERTS. It deliberately follows the SAME shape as
- * this repo's only other alert contract, F14's `analytics/rumAlert.ts`: a set of
+ * The query surface makes operational activity queryable; this turns four specific,
+ * high-value conditions in that stream into ALERTS. It follows the same shape as
+ * this repo's other alert contract, `analytics/rumAlert.ts`: a set of
  * PURE, transport-agnostic detectors that take a window of activity and return a
- * structured `ActivityAlert[]`. WHERE the alerts go (a log line, a future
+ * structured `ActivityAlert[]`. WHERE the alerts go (a log line, a
  * PagerDuty/Slack sink, a polled endpoint) is the sink's job — there is NO outbound
- * notification transport in this repo today (rumAlert is likewise detection-only),
- * so D7 does not invent one. It also does NOT add a cron: the checker is on-demand
+ * notification transport in this repo (rumAlert is likewise detection-only),
+ * so this layer does not invent one. It also does NOT add a cron: the checker is on-demand
  * (computed when `/admin/ops-timeline` loads, or when the read-only alerts endpoint
- * is polled), exactly as the card scopes it.
+ * is polled).
  *
  * THE FOUR CONDITIONS (and how each avoids false-positive noise):
  *
@@ -37,7 +37,7 @@
  *      still legitimately in flight (received < grace ago) never fires; a terminal
  *      after the received (any status) clears it.
  *
- *   4. deploy-skew — promotes D5's visibility-only `deriveDeploySkew()` into an
+ *   4. deploy-skew — promotes the visibility-only `deriveDeploySkew()` into an
  *      alert. `skewDetected` is true on EVERY normal rollout (two isolates coexist
  *      briefly), so alerting on it directly would page on every deploy. Instead this
  *      fires ONLY when the build serving this request differs from the newest
@@ -45,12 +45,10 @@
  *      period (default 15m) — i.e. THIS isolate failed to roll to a deploy that
  *      finished long ago (a persistent stale isolate), not a rollout in progress.
  *
- * DATA DEPENDENCY (honest wiring status, mirroring F16's `WiringStatus`). The
- * detectors read the D1 `activity_events` timeline through the D5 `queryActivity`
- * seam, so they alert on whatever is in that timeline. Getting SERVER-emitted
- * lifecycle events INTO D1 is the D1/D4 fan-out wiring (today `recordActivity()` is
- * logs-only; `deployVersion.ts` notes the swap to a timeline-fanning emitter is
- * pending) — NOT D7's job. `preview.serve` stays `analytics`-sink by design (too
+ * DATA DEPENDENCY. The detectors read the D1 `activity_events` timeline through the
+ * `queryActivity` seam, so they alert on whatever is in that timeline. Getting
+ * server-emitted lifecycle events into the timeline is the fan-out wiring's job, not
+ * this layer's. `preview.serve` stays `analytics`-sink by design (too
  * high-volume to timeline wholesale); detector 2 is source-agnostic (the rumAlert
  * precedent) and fires against an Analytics-Engine-sourced or seeded feed. See
  * `ALERT_CONDITIONS` for the per-condition source + wiring note.
@@ -63,10 +61,10 @@ import {
 } from "./query.js";
 import type { Queryable } from "../d1/catalog.js";
-/** Severity, mirroring F14's `rumAlert.AlertSeverity` / F16's `manifest.Severity`. */
+/** Severity, mirroring `rumAlert.AlertSeverity` / `manifest.Severity`. */
 export type AlertSeverity = "page" | "critical" | "warning" | "info";
-/** The four D7 conditions. Stable ids — a downstream sink/dashboard keys on them. */
+/** The four conditions. Stable ids — a downstream sink/dashboard keys on them. */
 export type ActivityAlertType =
   | "silent-terminal"
   | "recurring-preview-miss"
@@ -276,7 +274,7 @@ export interface DeploySkewAlertOptions {
 }
 /**
- * Promote D5's visibility-only `DeploySkewSummary` into an alert, WITHOUT firing on
+ * Promote the visibility-only `DeploySkewSummary` into an alert, WITHOUT firing on
  * every normal rollout. Fires only when the build serving this request differs from
  * the newest observed build AND that newest build has been latest for longer than
  * `graceMs` — i.e. THIS isolate never rolled to a deploy that finished long ago.

package/apps/storefront/src/lib/activity/candidateSubmitLease.ts ADDED Viewed

@@ -0,0 +1,87 @@
+import type { D1Like } from "@/lib/d1/catalog";
+const DIAGNOSTIC_STUCK_AFTER_MS = 5 * 60 * 1000;
+/**
+ * Atomically reserve one tenant/change across authorization, Gitea, and finalization.
+ * `expires_at` is an operator-visible stuck-work deadline, never an automatic takeover:
+ * a live but slow submit cannot lose ownership underneath its forge mutation.
+ */
+export async function acquireCandidateSubmitLease(
+  db: D1Like,
+  tenantId: string,
+  changeId: string,
+  authorizationId: string,
+  now = new Date(),
+): Promise<boolean> {
+  const acquiredAt = now.toISOString();
+  const expiresAt = new Date(now.getTime() + DIAGNOSTIC_STUCK_AFTER_MS).toISOString();
+  const row = await db.prepare(`
+    INSERT INTO candidate_submit_leases
+      (tenant_id, change_id, authorization_id, status, acquired_at, expires_at)
+    VALUES (?, ?, ?, 'active', ?, ?)
+    ON CONFLICT(tenant_id, change_id) DO UPDATE SET
+      authorization_id = excluded.authorization_id,
+      status = 'active',
+      acquired_at = excluded.acquired_at,
+      expires_at = excluded.expires_at
+    WHERE candidate_submit_leases.status <> 'active'
+       OR candidate_submit_leases.authorization_id = excluded.authorization_id
+    RETURNING authorization_id
+  `).bind(tenantId, changeId, authorizationId, acquiredAt, expiresAt).first() as
+    { authorization_id?: string } | null;
+  return row?.authorization_id === authorizationId;
+}
+export type CandidateSubmitLeaseState = "active" | "completed" | "missing";
+/** Atomically prove ownership for the callback work. Active leases are never stolen. */
+export async function renewCandidateSubmitLease(
+  db: D1Like,
+  tenantId: string,
+  changeId: string,
+  authorizationId: string,
+  now = new Date(),
+): Promise<CandidateSubmitLeaseState> {
+  const current = await db.prepare(`
+    SELECT authorization_id, status FROM candidate_submit_leases
+    WHERE tenant_id = ? AND change_id = ?
+  `).bind(tenantId, changeId).first() as
+    { authorization_id?: string; status?: string } | null;
+  if (current?.authorization_id !== authorizationId) return "missing";
+  if (current.status === "completed") return "completed";
+  const expiresAt = new Date(now.getTime() + DIAGNOSTIC_STUCK_AFTER_MS).toISOString();
+  const row = await db.prepare(`
+    UPDATE candidate_submit_leases SET expires_at = ?
+    WHERE tenant_id = ? AND change_id = ? AND authorization_id = ? AND status = 'active'
+    RETURNING authorization_id
+  `).bind(expiresAt, tenantId, changeId, authorizationId).first() as
+    { authorization_id?: string } | null;
+  return row?.authorization_id === authorizationId ? "active" : "missing";
+}
+/** Mark the attempt immutable/idempotent while allowing a later submit to acquire. */
+export async function completeCandidateSubmitLease(
+  db: D1Like,
+  tenantId: string,
+  changeId: string,
+  authorizationId: string,
+): Promise<void> {
+  await db.prepare(`
+    UPDATE candidate_submit_leases SET status = 'completed'
+    WHERE tenant_id = ? AND change_id = ? AND authorization_id = ? AND status = 'active'
+  `).bind(tenantId, changeId, authorizationId).run();
+}
+/** Release only this attempt; it can never unlock a newer submit. */
+export async function releaseCandidateSubmitLease(
+  db: D1Like,
+  tenantId: string,
+  changeId: string,
+  authorizationId: string,
+): Promise<void> {
+  await db.prepare(`
+    DELETE FROM candidate_submit_leases
+    WHERE tenant_id = ? AND change_id = ? AND authorization_id = ? AND status = 'active'
+  `).bind(tenantId, changeId, authorizationId).run();
+}

package/apps/storefront/src/lib/activity/changeActorAttribution.ts CHANGED Viewed

@@ -2,25 +2,36 @@
  * Owner-facing "who did this" attribution for a candidate change or aggregate —
  * DELIBERATELY separate from the anonymized activity spine. `ActivityActor.id`
  * is a salted, non-reversible hash by design (see `recordActivity.ts`'s header:
- * a raw PII id in the core zone would defeat the D0 contract), so it can never
+ * a raw PII id in the core zone would defeat the redaction contract), so it can never
  * answer "who submitted/accepted/rejected/shipped this" for an owner reviewing
  * `/admin#publish`. This persists the real email (never joined into the general
  * `queryActivity()` surface, never cross-tenant) alongside the existing hashed
  * event, so the two concerns stay separate: analytics stays anonymized, and
  * this stays a narrow, owner-only-readable accountability record.
  *
- * `sub` (the tot20-issued, stable user id) would be a better key than email —
- * email is a mutable account attribute, not the identity itself — but `sub`
- * is dropped before `SessionRecord` today (see `auth/session.ts`). Threading
- * it through is a real follow-up, not done here; email is what every call site
- * already has.
+ * MCP-submitted candidates carry the tot20-issued stable subject plus a verified
+ * email/display label. Storefront-local UI actions still use their authenticated
+ * session email until the same subject is threaded through `SessionRecord`.
  */
 import { displayNameFromEmail } from "./recordActivity";
-export type ChangeActorAction = "submit" | "reject" | "accept" | "ship" | "build";
+export type ChangeActorAction = "submit" | "reject" | "resolve" | "accept" | "ship" | "build";
+export interface ChangeActorIdentity {
+  kind: "human" | "service";
+  /** Immutable identity-provider subject for a person, or app subject for a service. */
+  subject: string;
+  /** Present only for a verified human identity. */
+  email: string | null;
+  /** Owner-facing label. */
+  name: string;
+}
 export interface ChangeActorRecord {
-  email: string;
+  /** Older records may predate structured identity and omit these two fields. */
+  kind?: ChangeActorIdentity["kind"];
+  subject?: string;
+  email: string | null;
   /** Best-effort display name — no real name is captured anywhere today, so
    *  this is always {@link displayNameFromEmail}'s local-part guess. Swap the
    *  source here (not the callers) if a real name ever becomes available. */
@@ -37,6 +48,14 @@ function attributionKey(tenantId: string, subjectId: string, action: ChangeActor
   return `cust:change-actor:${tenantId}:${subjectId}:${action}`;
 }
+function submitAuthorizationKey(
+  tenantId: string,
+  changeId: string,
+  authorizationId: string,
+): string {
+  return `cust:change-actor-authorization:${tenantId}:${changeId}:${authorizationId}`;
+}
 /**
  * Persist who took `action` on `subjectId` (a `changeId` for reject/accept/build,
  * or the aggregate id for ship). Best-effort — never blocks or fails the
@@ -51,6 +70,8 @@ export async function recordChangeActor(
 ): Promise<void> {
   try {
     const record: ChangeActorRecord = {
+      kind: "human",
+      subject: `email:${email.trim().toLowerCase()}`,
       email,
       name: displayNameFromEmail(email),
       at: new Date().toISOString(),
@@ -61,6 +82,65 @@ export async function recordChangeActor(
   }
 }
+/**
+ * Persist an actor as a required part of a privileged mutation's authorization
+ * boundary. Unlike {@link recordChangeActor}, storage failures propagate so the
+ * caller can fail closed before performing the mutation.
+ */
+export async function recordRequiredChangeActor(
+  kv: ChangeActorKv,
+  tenantId: string,
+  subjectId: string,
+  action: ChangeActorAction,
+  actor: ChangeActorIdentity,
+  at: string,
+): Promise<void> {
+  const record: ChangeActorRecord = { ...actor, at };
+  await kv.put(attributionKey(tenantId, subjectId, action), JSON.stringify(record));
+}
+/**
+ * Stage an immutable, per-attempt submit authorization before the forge write.
+ * This deliberately does not replace the canonical `submit` actor: a failed
+ * Gitea update must never make an older PR look like it was submitted by the
+ * actor whose later attempt failed.
+ */
+export async function recordCandidateSubmitAuthorization(
+  kv: ChangeActorKv,
+  tenantId: string,
+  changeId: string,
+  authorizationId: string,
+  actor: ChangeActorIdentity,
+  authorizedAt: string,
+): Promise<void> {
+  const record: ChangeActorRecord = { ...actor, at: authorizedAt };
+  await kv.put(
+    submitAuthorizationKey(tenantId, changeId, authorizationId),
+    JSON.stringify(record),
+  );
+}
+/** Read one exact pre-forge authorization. Missing/corrupt data fails closed. */
+export async function readCandidateSubmitAuthorization(
+  kv: ChangeActorKv,
+  tenantId: string,
+  changeId: string,
+  authorizationId: string,
+): Promise<ChangeActorRecord | null> {
+  try {
+    const raw = await kv.get(submitAuthorizationKey(tenantId, changeId, authorizationId));
+    return raw ? JSON.parse(raw) as ChangeActorRecord : null;
+  } catch {
+    return null;
+  }
+}
+/** Browser responses never need the immutable identity-provider subject. */
+export function ownerVisibleChangeActor(record: ChangeActorRecord): ChangeActorRecord {
+  const { subject: _subject, ...visible } = record;
+  return visible;
+}
 /** Read every recorded action's attribution for one subject. Best-effort per
  *  action: a missing/corrupt record is simply absent from the result, never
  *  a thrown error. */
@@ -69,7 +149,7 @@ export async function readChangeActors(
   tenantId: string,
   subjectId: string,
 ): Promise<Partial<Record<ChangeActorAction, ChangeActorRecord>>> {
-  const actions: ChangeActorAction[] = ["submit", "reject", "accept", "ship", "build"];
+  const actions: ChangeActorAction[] = ["submit", "reject", "resolve", "accept", "ship", "build"];
   const out: Partial<Record<ChangeActorAction, ChangeActorRecord>> = {};
   await Promise.all(
     actions.map(async (action) => {