@tokenoftrust/storefront-runner 2.0.4 → 2.0.5

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

@@ -23,9 +23,10 @@ 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 { reportTrackingChainHealth } from "@/lib/tracking/interactionHealth";
 import { resolveHeaderVariant, resolveFooterVariant } from "@/lib/chrome/variant";
 import type { HeaderVariant, FooterVariant } from "@/lib/chrome/model";
-import { renderIntegrationPhases } from "@tot/public-runtime";
+import { renderIntegrationPhases, INTERACTION_TRACKING_BOOT_JS } from "@tot/public-runtime";
 import { readViewerSession } from "@/lib/auth/route";
 import AppWidgetFrame from "@/components/apps/AppWidgetFrame.astro";
 import { getRegistryService } from "@/lib/apps/registryAccess.js";
@@ -130,6 +131,15 @@ const resolvedFooterVariant = resolveFooterVariant(footerVariant, chrome.footer.
 // 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(path);
+if (chromeHtml) {
+  // HEALTH: this is the sharedChrome BYPASS path — a hand-authored chrome.html
+  // wins outright over the governed chrome components below, so nothing
+  // validated its tracking declarations and nothing stamped them. A wholly
+  // unstamped wrapper means no click on this page's chrome can ever be
+  // collected, and every other layer stays silent about it (absence is also how
+  // a legitimate opt-out looks). One structured line per surface, never a throw.
+  reportTrackingChainHealth(chromeHtml, { surface: `sharedChrome:${tenant.tenant_id}` });
+}
 let sharedChrome: { header: string; footer: string; css: string[] } | null = null;
 if (chromeHtml && chromeHtml.includes(CHROME_BODY_MARKER)) {
   const headEnd = chromeHtml.indexOf("</head>");
@@ -277,13 +287,44 @@ const footerWidgets = await renderWidgetSlot(
       alternates={alternates}
     />
 
+    {
+      /* Cloudflare Web Analytics is a non-essential measurement destination —
+         gate it on the SAME neutral consent broker every vendor loader reads
+         (ext-kernel-04 `consent.defaults` phase, published above as
+         `window.__TOT_INTEGRATION_CONSENT__`). The token rides a <meta> tag
+         (any script attribute, incl. define:vars, forces is:inline and drops
+         module processing — this script needs a real import) rather than a
+         page global; the script fail-closes like every other consumer of that
+         global: an absent/tampered snapshot denies, so an unconfigured CMP
+         means this never loads rather than loading ungated. */
+      analyticsEnabled && <meta name="cf-beacon-token" content={analyticsToken} />
+    }
     {
       analyticsEnabled && (
-        <script
-          defer
-          src="https://static.cloudflareinsights.com/beacon.min.js"
-          data-cf-beacon={`{"token": "${analyticsToken}"}`}
-        />
+        <script>
+          import {
+            parseConsentSnapshot,
+            isPurposeEligible,
+            defaultConsentSnapshot,
+            INTEGRATION_CONSENT_GLOBAL,
+          } from "@tot/public-runtime";
+
+          const snapshot =
+            parseConsentSnapshot((window as unknown as Record<string, unknown>)[INTEGRATION_CONSENT_GLOBAL]) ??
+            defaultConsentSnapshot();
+
+          const token = document
+            .querySelector('meta[name="cf-beacon-token"]')
+            ?.getAttribute("content");
+
+          if (token && isPurposeEligible(snapshot, "analytics")) {
+            const beacon = document.createElement("script");
+            beacon.defer = true;
+            beacon.src = "https://static.cloudflareinsights.com/beacon.min.js";
+            beacon.setAttribute("data-cf-beacon", JSON.stringify({ token }));
+            document.head.appendChild(beacon);
+          }
+        </script>
       )
     }
   </head>
@@ -554,6 +595,23 @@ const footerWidgets = await renderWidgetSlot(
       bootTamperSentinel();
     </script>
 
+    {/* Declarative interaction tracking (dt-contract-v1) — ONE delegated click
+        listener, installed once per document, that resolves the nearest
+        ancestor carrying `data-tot-el` and reports its declared
+        identity/action/placement (plus the data-tot-scope/data-tot-i instance
+        pair). It reads declared attributes ONLY: no textContent/innerText/alt/
+        value/placeholder, no form-field reads. Delivery, consent gating and
+        environment gating are NOT here — each interaction is dispatched as a
+        `tot:interaction` CustomEvent for the collector to consume.
+
+        This is the Astro-mount half of the install; `rawHtmlResponse()` is the
+        other (ADR 0015 one-engine-two-mounts). Both embed the SAME serialized
+        listener, and the install-once marker makes a double install a no-op —
+        which is what makes the raw chrome wrapper spliced into this document
+        (above) safe. Emitted as `is:inline` + the page nonce so it needs no
+        entry in lib/cspStaticHashes.ts. */}
+    <script is:inline nonce={cspNonce} set:html={INTERACTION_TRACKING_BOOT_JS}></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} />

package/apps/storefront/src/lib/chrome/ctaIdentity.ts

@@ -0,0 +1,21 @@
+/**
+ * Governed-CTA identity attribute — the ONE mapping from a `ChromeCta` config
+ * to the markup identity every renderer stamps onto its rendered anchor.
+ *
+ * Two render paths draw on the same governed `ChromeCta` config: `rawChrome.ts`
+ * (the RAW-page chrome wrapper) and `SiteHeader.astro` (the app-Layout header).
+ * Both must emit the identical identity attribute for the identical CTA, so a
+ * downstream consumer (tracking, an operator's own selectors) never has to care
+ * which surface rendered the page. Keeping the derivation in ONE function,
+ * imported by both, makes that a structural guarantee rather than a convention
+ * two files have to remember to keep in sync.
+ */
+import type { ChromeCta } from "./model.js";
+
+/** The identity attribute name governed CTAs are stamped with. */
+export const CTA_IDENTITY_ATTR = "data-cta-id";
+
+/** The (name, value) pair a governed CTA's config resolves to for markup identity. */
+export function ctaIdentityAttr(cta: ChromeCta): { name: string; value: string } {
+  return { name: CTA_IDENTITY_ATTR, value: cta.id };
+}

package/apps/storefront/src/lib/chrome/examples/tokenoftrust.chrome.example.json

@@ -18,15 +18,15 @@
       }
     },
     "nav": [
-      { "id": "nav-platform", "label": "Platform", "href": "/#platform" },
-      { "id": "nav-industries", "label": "Industries", "href": "/#industries" },
-      { "id": "nav-resources", "label": "Resources", "href": "https://help.tokenoftrust.com", "external": true },
-      { "id": "nav-pricing", "label": "Pricing", "href": "https://tokenoftrust.com/pricing/", "external": true },
-      { "id": "nav-login", "label": "Login", "href": "https://app.tokenoftrust.com", "external": true }
+      { "id": "nav-platform", "action": "nav-platform", "label": "Platform", "href": "/#platform" },
+      { "id": "nav-industries", "action": "nav-industries", "label": "Industries", "href": "/#industries" },
+      { "id": "nav-resources", "action": "nav-resources", "label": "Resources", "href": "https://help.tokenoftrust.com", "external": true },
+      { "id": "nav-pricing", "action": "nav-pricing", "label": "Pricing", "href": "https://tokenoftrust.com/pricing/", "external": true },
+      { "id": "nav-login", "action": "nav-login", "label": "Login", "href": "https://app.tokenoftrust.com", "external": true }
     ],
     "ctas": [
-      { "id": "cta-book-demo", "label": "Book Demo", "href": "https://tokenoftrust.com/contact/", "variant": "secondary" },
-      { "id": "cta-start-free", "label": "Start For Free", "href": "https://app.tokenoftrust.com", "variant": "primary" }
+      { "id": "cta-book-demo", "action": "cta-book-demo", "label": "Book Demo", "href": "https://tokenoftrust.com/contact/", "variant": "secondary" },
+      { "id": "cta-start-free", "action": "cta-start-for-free", "label": "Start For Free", "href": "https://app.tokenoftrust.com", "variant": "primary" }
     ]
   },
   "footer": {
@@ -38,36 +38,36 @@
       {
         "title": "Platform",
         "links": [
-          { "id": "ftr-platform-idv", "label": "Identity Verification", "href": "/#platform" },
-          { "id": "ftr-platform-age", "label": "Age Assurance", "href": "/#platform" },
-          { "id": "ftr-platform-fraud", "label": "Fraud Prevention", "href": "/#platform" },
-          { "id": "ftr-platform-evidence", "label": "Compliance Evidence", "href": "/#platform" },
-          { "id": "ftr-platform-aml", "label": "AML · PACT Act · Tax", "href": "/#platform" }
+          { "id": "ftr-platform-idv", "action": "nav-identity-verification", "label": "Identity Verification", "href": "/#platform" },
+          { "id": "ftr-platform-age", "action": "nav-age-assurance", "label": "Age Assurance", "href": "/#platform" },
+          { "id": "ftr-platform-fraud", "action": "nav-fraud-prevention", "label": "Fraud Prevention", "href": "/#platform" },
+          { "id": "ftr-platform-evidence", "action": "nav-compliance-evidence", "label": "Compliance Evidence", "href": "/#platform" },
+          { "id": "ftr-platform-aml", "action": "nav-aml-pact-act-tax", "label": "AML · PACT Act · Tax", "href": "/#platform" }
         ]
       },
       {
         "title": "Industries",
         "links": [
-          { "id": "ftr-industries-alcohol", "label": "Alcohol", "href": "/#industries" },
-          { "id": "ftr-industries-vape", "label": "Tobacco & Vape", "href": "/#industries" },
-          { "id": "ftr-industries-age-restricted", "label": "Age-Restricted Goods", "href": "/#industries" },
-          { "id": "ftr-industries-marketplaces", "label": "Marketplaces", "href": "/#industries" }
+          { "id": "ftr-industries-alcohol", "action": "nav-alcohol", "label": "Alcohol", "href": "/#industries" },
+          { "id": "ftr-industries-vape", "action": "nav-tobacco-and-vape", "label": "Tobacco & Vape", "href": "/#industries" },
+          { "id": "ftr-industries-age-restricted", "action": "nav-age-restricted-goods", "label": "Age-Restricted Goods", "href": "/#industries" },
+          { "id": "ftr-industries-marketplaces", "action": "nav-marketplaces", "label": "Marketplaces", "href": "/#industries" }
         ]
       },
       {
         "title": "Company",
         "links": [
-          { "id": "ftr-company-pricing", "label": "Pricing", "href": "https://tokenoftrust.com/pricing/", "external": true },
-          { "id": "ftr-company-contact", "label": "Contact Sales", "href": "https://tokenoftrust.com/contact/", "external": true },
-          { "id": "ftr-company-resources", "label": "Resources", "href": "https://help.tokenoftrust.com", "external": true },
-          { "id": "ftr-company-login", "label": "Login", "href": "https://app.tokenoftrust.com", "external": true }
+          { "id": "ftr-company-pricing", "action": "nav-pricing", "label": "Pricing", "href": "https://tokenoftrust.com/pricing/", "external": true },
+          { "id": "ftr-company-contact", "action": "nav-contact-sales", "label": "Contact Sales", "href": "https://tokenoftrust.com/contact/", "external": true },
+          { "id": "ftr-company-resources", "action": "nav-resources", "label": "Resources", "href": "https://help.tokenoftrust.com", "external": true },
+          { "id": "ftr-company-login", "action": "nav-login", "label": "Login", "href": "https://app.tokenoftrust.com", "external": true }
         ]
       },
       {
         "title": "Legal",
         "links": [
-          { "id": "ftr-legal-privacy", "label": "Privacy Policy", "href": "https://tokenoftrust.com/privacy/", "external": true },
-          { "id": "ftr-legal-terms", "label": "Terms", "href": "https://tokenoftrust.com/terms/", "external": true }
+          { "id": "ftr-legal-privacy", "action": "nav-privacy-policy", "label": "Privacy Policy", "href": "https://tokenoftrust.com/privacy/", "external": true },
+          { "id": "ftr-legal-terms", "action": "nav-terms", "label": "Terms", "href": "https://tokenoftrust.com/terms/", "external": true }
         ]
       }
     ],

package/apps/storefront/src/lib/chrome/trackingPlacements.ts

@@ -0,0 +1,36 @@
+/**
+ * Canonical `data-tot-placement` values for governed chrome + navigation (V1
+ * pilot scope: chrome CTAs, primary nav, mega-menu children, utility nav,
+ * footer, mobile nav — see docs/declarative-interaction-tracking-contract.md
+ * and decision v1-scope-chrome-nav-pilot). ONE source of truth shared by both
+ * the component renderer (SiteHeader.astro / MegaMenu.astro / NavDropdown.astro
+ * / MobileNav.tsx / UtilityNav.astro / SiteFooter.astro) and the raw-string
+ * renderer (rawChrome.ts), so the same section can never emit a different
+ * placement literal on the two surfaces.
+ *
+ * Placement is always passed explicitly by whichever renderer knows where it
+ * is rendering (decision identity-action-placement-split-v2) — never inferred
+ * from DOM position, component nesting, or render mode.
+ */
+export const CHROME_PLACEMENT = {
+  /** Header-actions cluster CTAs (rawChrome's `.header-cta`, SiteHeader's `headerCtas`). */
+  header: "header",
+  /** Primary-nav top-level items — desktop bar (raw `.primary-nav`, MegaMenu/NavDropdown mode="bar"). */
+  primaryNav: "primary-nav",
+  /** Mega-menu / single-column dropdown children, on either surface. */
+  megaMenu: "mega-menu",
+  /** The thin utility bar above the header. */
+  utilityNav: "utility-nav",
+  /** Footer link columns. */
+  footer: "footer",
+  /**
+   * Footer bottom legal/policy link row — component surface only. The raw
+   * renderer's `ChromeFooter.bottom` carries text only (no links); its footer
+   * columns cover the same links under `footer` above.
+   */
+  footerBottom: "footer-bottom",
+  /** The mobile nav drawer (MobileNav island) and its no-JS accordion fallback. */
+  mobileMenu: "mobile-menu",
+} as const;
+
+export type ChromePlacement = (typeof CHROME_PLACEMENT)[keyof typeof CHROME_PLACEMENT];

package/apps/storefront/src/lib/d1/schema-apps.ts

@@ -149,6 +149,63 @@ export const activityEvents = sqliteTable(
   }),
 );
 
+// --- Per-tenant raw-interaction store directory ------------------------------
+// The DIRECTORY of per-tenant D1 databases that hold raw declarative-tracking
+// interaction rows — one database per tenant (`lib/tracking/interactionSchema.ts`
+// is that database's schema). This table holds NO interaction data: only the
+// `tenant_id → (database_name, database_uuid)` mapping the Worker needs to
+// address a tenant's own database over the D1 REST API, since Worker bindings
+// are static and cannot be created per tenant at runtime.
+//
+// It lives in the SHARED STOREFRONT_APPS_DB on purpose: a directory of tenants
+// is inherently cross-tenant, and keeping it here means the isolation boundary
+// stays exactly one hop — a lookup returns ONE tenant's database handle, and
+// that database contains nothing else. `tenant_id` is the primary key, so one
+// tenant can never map to two databases (and two tenants can never share one).
+//
+// This is the seam the follow-on units read:
+//   • `dt-tenant-isolation`   — resolves the caller's authorized tenant to
+//                               exactly one `database_uuid`; a merchant read
+//                               that is not in their own row cannot be built.
+//   • `dt-prune-and-rollup`   — ENUMERATES this table to sweep every tenant's
+//                               90-day window (`last_pruned_at` / `pruned_rows`
+//                               are its bookkeeping), and uses `size_bytes` /
+//                               `size_checked_at` to surface a tenant nearing
+//                               D1's 10GB per-database ceiling.
+export const trackingTenantDatabases = sqliteTable(
+  "tracking_tenant_databases",
+  {
+    tenantId: text("tenant_id").primaryKey(),
+    // The Cloudflare D1 database name, derived deterministically from the tenant
+    // id (`lib/tracking/tenantD1Registry.ts`) — recorded so an operator can find
+    // it in the dashboard without re-deriving.
+    databaseName: text("database_name").notNull(),
+    // The D1 UUID — what the REST data plane actually addresses.
+    databaseUuid: text("database_uuid").notNull(),
+    // Applied `INTERACTION_SCHEMA_VERSION`; a bump re-applies the DDL per tenant.
+    schemaVersion: integer("schema_version").notNull(),
+    createdAt: text("created_at").notNull(),
+    updatedAt: text("updated_at").notNull(),
+    // Bookkeeping for the scheduled prune (written by `dt-prune-and-rollup`).
+    lastPrunedAt: text("last_pruned_at"),
+    prunedRows: integer("pruned_rows").notNull().default(0),
+    // Last observed database size + when, for the 10GB-ceiling warning.
+    sizeBytes: integer("size_bytes"),
+    sizeCheckedAt: text("size_checked_at"),
+  },
+  (t) => ({
+    // Two tenants sharing one database would defeat the whole structural-
+    // isolation claim, so make it impossible at the schema level.
+    uqTrackingTenantDatabasesUuid: uniqueIndex("uq_tracking_tenant_databases_uuid").on(
+      t.databaseUuid,
+    ),
+    // The prune sweep's work queue: oldest-pruned first.
+    idxTrackingTenantDatabasesPruned: index("idx_tracking_tenant_databases_pruned").on(
+      t.lastPrunedAt,
+    ),
+  }),
+);
+
 // --- Webhook event spine ----------------------------------------------------
 // Immutable event log. `id` is the semantic event id we mint — distinct from
 // any per-delivery wire envelope id (see `webhookDeliveries.deliveryId` below).

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

@@ -26,6 +26,9 @@
  */
 import { CHROME_BODY_MARKER, CHROME_HEAD_MARKER } from "./rawMarketingHtml.js";
 import { isCurrentNavHref } from "./chrome/navCurrent.js";
+import { ctaIdentityAttr } from "./chrome/ctaIdentity.js";
+import { CHROME_PLACEMENT } from "./chrome/trackingPlacements.js";
+import { trackingAttributesHtml } from "@tot/public-runtime";
 import type {
   ChromeAgeGate,
   ChromeAnnouncement,
@@ -165,12 +168,27 @@ function renderAnnouncement(a: ChromeAnnouncement): string {
 
 function renderUtilityNav(u: ChromeUtilityNav): string {
   const links = (u.links ?? [])
-    .map((l) => `<li><a href="${esc(l.href)}"${relFor(l)}>${esc(l.label)}</a></li>`)
+    .map((l, i) => {
+      const stamp = trackingAttributesHtml({
+        el: l.id,
+        action: l.action,
+        tracking: l.tracking,
+        placement: CHROME_PLACEMENT.utilityNav,
+        scope: "utility-nav",
+        index: i,
+      });
+      return `<li><a href="${esc(l.href)}"${relFor(l)}${stamp}>${esc(l.label)}</a></li>`;
+    })
     .join("");
   const locale = (u.locale ?? []).map((s) => `<span class="sel">${esc(s)}</span>`).join("");
   const social = u.social?.length ? `<span class="social">${renderSocial(u.social)}</span>` : "";
   const cue = u.memberCue
-    ? `<a class="member-cue" href="${esc(u.memberCue.href)}">${esc(u.memberCue.label)}</a>`
+    ? `<a class="member-cue" href="${esc(u.memberCue.href)}"${trackingAttributesHtml({
+        el: u.memberCue.id,
+        action: u.memberCue.action,
+        tracking: u.memberCue.tracking,
+        placement: CHROME_PLACEMENT.utilityNav,
+      })}>${esc(u.memberCue.label)}</a>`
     : "";
   const right = `${locale}${social}${cue}`;
   return (
@@ -194,7 +212,7 @@ function renderUtilityNav(u: ChromeUtilityNav): string {
  * unprefixed and exact-match-only (see navCurrent.ts). Omitted ⇒ no item is
  * ever marked current (callers that don't know the request path, e.g. tests).
  */
-function renderNavItem(item: ChromeNavItem, currentPath?: string): string {
+function renderNavItem(item: ChromeNavItem, index: number, currentPath?: string): string {
   const columns = item.columns?.length
     ? item.columns
     : item.children?.length
@@ -207,9 +225,19 @@ function renderNavItem(item: ChromeNavItem, currentPath?: string): string {
   const haspopup = hasPanel ? ' aria-haspopup="true"' : "";
   const itemCurrent = currentPath !== undefined && isCurrentNavHref(currentPath, item.href);
   const ariaCurrent = itemCurrent ? ' aria-current="page"' : "";
-  const link = `<a${linkClass} href="${esc(item.href)}"${haspopup}${ariaCurrent}>${esc(item.label)}${badge}${caret}</a>`;
+  const itemStamp = trackingAttributesHtml({
+    el: item.id,
+    action: item.action,
+    tracking: item.tracking,
+    placement: CHROME_PLACEMENT.primaryNav,
+    scope: "nav-primary",
+    index,
+  });
+  const link = `<a${linkClass} href="${esc(item.href)}"${haspopup}${ariaCurrent}${itemStamp}>${esc(item.label)}${badge}${caret}</a>`;
   if (!hasPanel) return `<li class="nav-item">${link}</li>`;
 
+  const megaScope = `nav-mega:${item.id}`;
+  let childIndex = 0;
   const wide = columns.length > 1 ? " mega--wide" : "";
   const cols = columns
     .map((c) => {
@@ -219,7 +247,15 @@ function renderNavItem(item: ChromeNavItem, currentPath?: string): string {
           const childCurrent =
             currentPath !== undefined && isCurrentNavHref(currentPath, l.href, l.external);
           const childAriaCurrent = childCurrent ? ' aria-current="page"' : "";
-          return `<a href="${esc(l.href)}"${relFor(l)}${childAriaCurrent}>${esc(l.label)}</a>`;
+          const childStamp = trackingAttributesHtml({
+            el: l.id,
+            action: l.action,
+            tracking: l.tracking,
+            placement: CHROME_PLACEMENT.megaMenu,
+            scope: megaScope,
+            index: childIndex++,
+          });
+          return `<a href="${esc(l.href)}"${relFor(l)}${childAriaCurrent}${childStamp}>${esc(l.label)}</a>`;
         })
         .join("");
       return `<div class="mega__col">${heading}${links}</div>`;
@@ -257,22 +293,35 @@ function renderHeader(header: ChromeHeader, variant: HeaderVariant, currentPath?
   const minimal = variant === "minimal";
   // Header CTAs, on the same `!minimal` rule the Astro SiteHeader applies, so the
   // two surfaces render the same governed config identically. Each carries its
-  // stable `id` as `data-cta-id`, so the governed identity is present in the
-  // served DOM rather than implied by label or href.
+  // identity attribute (ctaIdentityAttr, shared with SiteHeader.astro), so the
+  // governed identity is present in the served DOM rather than implied by label
+  // or href.
   const ctas =
     minimal || !header.ctas?.length
       ? ""
       : header.ctas
-          .map(
-            (c) =>
+          .map((c, i) => {
+            const idAttr = ctaIdentityAttr(c);
+            const stamp = trackingAttributesHtml({
+              el: c.id,
+              action: c.action,
+              tracking: c.tracking,
+              placement: CHROME_PLACEMENT.header,
+              scope: "header-ctas",
+              index: i,
+            });
+            return (
               `<a class="header-cta header-cta--${esc(c.variant ?? "primary")}" ` +
-              `data-cta-id="${esc(c.id)}" href="${esc(c.href)}">${esc(c.label)}</a>`,
-          )
+              `${idAttr.name}="${esc(idAttr.value)}" href="${esc(c.href)}"${stamp}>${esc(c.label)}</a>`
+            );
+          })
           .join("");
   const hamburger = minimal
     ? ""
     : `<button class="hamburger" id="hamburger" aria-label="Toggle navigation menu" aria-expanded="false" aria-controls="primaryNav"><span></span><span></span><span></span></button>`;
-  const navItems = header.nav.map((item) => renderNavItem(item, currentPath)).join("\n          ");
+  const navItems = header.nav
+    .map((item, i) => renderNavItem(item, i, currentPath))
+    .join("\n          ");
   const navBar = minimal
     ? ""
     : `  <nav class="primary-nav-bar" aria-label="Primary">\n` +
@@ -343,9 +392,19 @@ function renderFooter(footer: ChromeFooter): string {
         })()
       : "";
   const columns = footer.columns
-    .map((c) => {
+    .map((c, colIndex) => {
       const links = c.links
-        .map((l) => `<li><a href="${esc(l.href)}"${relFor(l)}>${esc(l.label)}</a></li>`)
+        .map((l, i) => {
+          const stamp = trackingAttributesHtml({
+            el: l.id,
+            action: l.action,
+            tracking: l.tracking,
+            placement: CHROME_PLACEMENT.footer,
+            scope: `footer-col:${colIndex}`,
+            index: i,
+          });
+          return `<li><a href="${esc(l.href)}"${relFor(l)}${stamp}>${esc(l.label)}</a></li>`;
+        })
         .join("");
       return `      <div class="footer-col">\n        <h4>${esc(c.title)}</h4>\n        <ul>${links}</ul>\n      </div>`;
     })

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

@@ -17,8 +17,10 @@
  */
 import {
   renderIntegrationPhases,
+  INTERACTION_TRACKING_BOOT_JS,
   type EffectivePlan,
 } from "@tot/public-runtime";
+import { reportTrackingChainHealth } from "./tracking/interactionHealth.js";
 
 export { rawHtmlPolicy } from "@tot/public-runtime";
 
@@ -113,6 +115,23 @@ function injectBodyEnd(html: string, snippet: string): string {
   return html + snippet;
 }
 
+/**
+ * The declarative-interaction-tracking listener as a nonce-carrying inline
+ * `<script>` — the raw-mount half of the install (`Layout.astro` is the other,
+ * ADR 0015 one-engine-two-mounts). Both mounts embed the SAME serialized
+ * listener from `@tot/public-runtime`, so no markup path can drift into a
+ * second implementation, and the listener's install-once marker makes a second
+ * copy in the same document (a tenant `chrome.html` wrapper that also carries
+ * it) a no-op.
+ *
+ * Carries the nonce itself because it is spliced AFTER `nonceInlineTags` has
+ * run — same discipline as the render engine's phase markup.
+ */
+export function interactionTrackingScript(nonce: string): string {
+  const nonceAttr = nonce ? ` nonce="${nonce}"` : "";
+  return `<script${nonceAttr}>${INTERACTION_TRACKING_BOOT_JS}</script>`;
+}
+
 /** Stamp `nonce` onto every inline `<style>`/`<script>` so a strict CSP admits them. */
 export function nonceInlineTags(html: string, nonce: string): string {
   return html
@@ -167,6 +186,12 @@ export function rawHtmlResponse(
     isFullDocument(html) || !opts.chromeWrapper
       ? html
       : wrapFragmentInChrome(html, opts.chromeWrapper);
+  // HEALTH: a raw surface bypasses governed chrome, so `validateChromeConfig`
+  // never saw it and `trackingAttributes()` never stamped it. If NOT ONE of its
+  // actionable elements carries an identity, no click on this page can ever be
+  // collected — and every other layer is silent about that by design (absence
+  // is also how a legitimate opt-out looks). One structured line, never a throw.
+  reportTrackingChainHealth(composed, { surface: `raw:${opts.basePath || "/"}` });
   // DEV ONLY: these pages are served verbatim, bypassing Astro's render pipeline,
   // so the Vite HMR client is never injected — a save would reach the server (see
   // the tenantHotReload plugin in astro.config.mjs) but the browser would have no
@@ -201,6 +226,11 @@ export function rawHtmlResponse(
   composed = injectHeadStart(composed, phases.head);
   composed = injectBodyStart(composed, phases.bodyStart);
   composed = injectBodyEnd(composed, phases.bodyDeferred);
+  // Declarative interaction tracking, last in the body so the whole document —
+  // a verbatim tenant document, a fragment spliced into a hand-authored
+  // `chrome.html`, or a fragment spliced into the generated `renderRawChrome`
+  // wrapper — is already present when the delegated listener binds.
+  composed = injectBodyEnd(composed, interactionTrackingScript(opts.nonce));
   const doc = prefixTenantLinks(composed, opts.basePath);
   return new Response(doc, {
     headers: { "content-type": "text/html; charset=utf-8" },

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

@@ -30,6 +30,7 @@ import {
 import { renderRawChrome } from "../rawChrome.js";
 import { parseChromeConfig } from "../chrome/parseConfig.js";
 import { parseChromeAssignments } from "../chrome/model.js";
+import { stampTrackingIdsAtPublish } from "../tracking/publishSafetyNet.js";
 
 /** Safe, always-valid fallback when neither the tenant's own chrome.json nor
  * the default scope's validates — the storefront must always render. */
@@ -599,12 +600,21 @@ export class PublishedContentProvider implements ContentProvider {
   // Raw whole-page documents (T0 marketing tenants) publish via KV too, so a
   // vendor edit previews / goes live with NO Worker rebuild. Artifact path mirrors
   // the source file: content/<tenant>/home.html and .../pages-html/<slug>.html.
+  //
+  // This is content that bypasses git review entirely (a direct KV publish,
+  // never touched by dt-id-writeback's reviewable-diff flow) — so the
+  // publish-time HTMLRewriter safety net (publishSafetyNet.ts) stamps
+  // `data-tot-el` on it here, at the read boundary, before it ever reaches a
+  // route. The base chain's own git-tracked content is NOT re-stamped: that
+  // is dt-id-writeback's job.
   async getHomeHtml(): Promise<string | null> {
-    return (await this.publishedRaw("home.html")) ?? this.base.getHomeHtml();
+    const raw = await this.publishedRaw("home.html");
+    return raw !== null ? stampTrackingIdsAtPublish(raw) : this.base.getHomeHtml();
   }
   async getPageHtml(slug: string): Promise<string | null> {
     const rel = `pages-html/${normalizeRawPageSlug(slug)}.html`;
-    return (await this.publishedRaw(rel)) ?? this.base.getPageHtml(slug);
+    const raw = await this.publishedRaw(rel);
+    return raw !== null ? stampTrackingIdsAtPublish(raw) : this.base.getPageHtml(slug);
   }
   listPageHtmlSlugs(): Promise<string[]> {
     return this.listArtifactPaths("pages-html/").then((paths) =>
@@ -618,8 +628,9 @@ export class PublishedContentProvider implements ContentProvider {
   async getChromeHtml(currentPath?: string): Promise<string | null> {
     // A published raw chrome.html override (parallels the home.html/pages-html
     // publish path) wins, so a vendor edit previews / goes live with no rebuild.
+    // Same bypasses-git-review reasoning as getHomeHtml/getPageHtml above: stamp it.
     const publishedHtml = await this.publishedRaw("chrome.html");
-    if (publishedHtml) return publishedHtml;
+    if (publishedHtml) return stampTrackingIdsAtPublish(publishedHtml);
     // Else, if the PUBLISHED chrome.json opts into shared chrome, render
     // the canonical wrapper from it — so a config edit previews without a rebuild.
     const config = parseChromeConfig(await this.published<unknown>("chrome.json"));
@@ -696,12 +707,17 @@ export class DevDraftContentProvider implements ContentProvider {
     return this.get(`dev-draft:${this.tenantId}:${this.draftId}:${path}`);
   }
 
+  // AI-edit drafts (WS5 G4 `/api/content-edit/ai-edit`) never touch
+  // dt-id-writeback's git-reviewed flow either — same publish-time
+  // HTMLRewriter safety net as PublishedContentProvider above.
   async getHomeHtml(): Promise<string | null> {
-    return (await this.draftRaw("content/home.html")) ?? this.base.getHomeHtml();
+    const draft = await this.draftRaw("content/home.html");
+    return draft !== null ? stampTrackingIdsAtPublish(draft) : this.base.getHomeHtml();
   }
   async getPageHtml(slug: string): Promise<string | null> {
     const rel = `content/pages-html/${normalizeRawPageSlug(slug)}.html`;
-    return (await this.draftRaw(rel)) ?? this.base.getPageHtml(slug);
+    const draft = await this.draftRaw(rel);
+    return draft !== null ? stampTrackingIdsAtPublish(draft) : this.base.getPageHtml(slug);
   }
   getHome(): Promise<HomeContent> {
     return this.base.getHome();

package/apps/storefront/src/lib/tracking/collectorAllowlist.ts

@@ -0,0 +1,40 @@
+/**
+ * OWNER: dt-collector-v1. Central allowlist for `POST /api/tracking/interaction`.
+ *
+ * Default-deny, same posture as `@tot/public-runtime`'s activity redaction
+ * contract (`activity/redaction.ts`): the wire payload posted by the browser
+ * collector may carry ONLY these keys. Anything else is dropped and counted —
+ * never stored, never coerced into a known field. There is no per-action
+ * catalog here (unlike the activity spine) because the shape is fixed by the
+ * `TotInteraction` contract (`packages/public-runtime/src/interaction-tracking.ts`):
+ * one event kind, always the same fields.
+ *
+ * Every field here is either a `TotInteraction` attribute-contract field (read
+ * from `data-tot-*`, never from rendered content) or something this unit's own
+ * client-side collector synthesizes (ts / correlationId / seq) — never
+ * anything DOM-derived. Extending this allowlist is the ONE place a new field
+ * must be declared before the ingest module (`collectorIngest.ts`) will accept
+ * it from the wire.
+ */
+
+/** The exact keys a posted interaction event may carry. */
+export const INTERACTION_WIRE_ALLOWLIST = [
+  "type",
+  "el",
+  "action",
+  "placement",
+  "scope",
+  "index",
+  "ts",
+  "correlationId",
+  "seq",
+] as const;
+
+export type InteractionWireKey = (typeof INTERACTION_WIRE_ALLOWLIST)[number];
+
+const ALLOWLIST_SET: ReadonlySet<string> = new Set(INTERACTION_WIRE_ALLOWLIST);
+
+/** True when `key` is a declared field. Anything else must be dropped, not stored. */
+export function isAllowedInteractionKey(key: string): key is InteractionWireKey {
+  return ALLOWLIST_SET.has(key);
+}