@tokenoftrust/storefront-runner 2.0.3 → 2.0.5

package/apps/storefront/src/components/chrome/UtilityNav.astro

@@ -7,6 +7,8 @@
  */
 import type { ChromeLink, SocialLink } from "@/lib/chrome/model";
 import { withBase } from "@/lib/basePath";
+import { CHROME_PLACEMENT } from "@/lib/chrome/trackingPlacements";
+import { trackingAttributes } from "@tot/public-runtime";
 
 interface Props {
   links?: ChromeLink[];
@@ -19,6 +21,15 @@ interface Props {
 const { links = [], locale, currency, social = [], class: className } = Astro.props;
 const { basePath } = Astro.locals;
 const hrefOf = (l: ChromeLink) => (l.external ? l.href : withBase(basePath, l.href));
+const linkStamp = (l: ChromeLink, index: number) =>
+  trackingAttributes({
+    el: l.id,
+    action: l.action,
+    tracking: l.tracking,
+    placement: CHROME_PLACEMENT.utilityNav,
+    scope: "utility-nav",
+    index,
+  });
 ---
 
 <div
@@ -30,12 +41,13 @@ const hrefOf = (l: ChromeLink) => (l.external ? l.href : withBase(basePath, l.hr
   <div class="container-prose flex h-9 items-center justify-between gap-4 text-[0.72rem]">
     <ul class="flex items-center gap-5">
       {
-        links.map((l) => (
+        links.map((l, i) => (
           <li>
             <a
               href={hrefOf(l)}
               class="transition-colors hover:text-primary"
               {...(l.external ? { rel: "noopener noreferrer" } : {})}
+              {...linkStamp(l, i)}
             >
               {l.label}
             </a>

package/apps/storefront/src/components/islands/MobileNav.tsx

@@ -12,14 +12,30 @@
  */
 import { useCallback, useEffect, useRef, useState } from "preact/hooks";
 import { isCurrentNavHref } from "@/lib/chrome/navCurrent";
+import { CHROME_PLACEMENT } from "@/lib/chrome/trackingPlacements";
+import { trackingAttributes } from "@tot/public-runtime";
 
+/**
+ * `action`/`tracking` are declared loosely here (not the strict
+ * `TrackingDeclaration` union `SiteHeader.astro` maps from) — a fresh object
+ * literal spreading a discriminated union's fields widens to two independent
+ * optional properties, so TS can no longer see "exactly one of the two" at
+ * the type level. `trackingAttributes()` is still the runtime oracle: it
+ * throws on an invalid combination regardless of what the type allows.
+ */
 interface NavChild {
+  id: string;
   label: string;
   href: string;
+  action?: string;
+  tracking?: "none";
 }
 interface NavItem {
+  id: string;
   label: string;
   href: string;
+  action?: string;
+  tracking?: "none";
   children?: NavChild[];
 }
 
@@ -212,7 +228,7 @@ export default function MobileNav({ nav, announcement, currentPath }: Props) {
 
             <nav aria-label="Mobile" class="flex-1 px-2 py-4">
               <ul class="space-y-1">
-                {nav.map((item) => (
+                {nav.map((item, i) => (
                   <li key={item.href}>
                     {item.children && item.children.length > 0 ? (
                       <div class="px-3 py-2">
@@ -222,11 +238,19 @@ export default function MobileNav({ nav, announcement, currentPath }: Props) {
                             currentPath && isCurrentNavHref(currentPath, item.href) ? "page" : undefined
                           }
                           class="block font-display text-base font-medium text-text hover:text-primary"
+                          {...trackingAttributes({
+                            el: item.id,
+                            action: item.action,
+                            tracking: item.tracking,
+                            placement: CHROME_PLACEMENT.mobileMenu,
+                            scope: "nav-mobile",
+                            index: i,
+                          })}
                         >
                           {item.label}
                         </a>
                         <ul class="mt-1 space-y-0.5 border-l border-border pl-3">
-                          {item.children.map((child) => (
+                          {item.children.map((child, ci) => (
                             <li key={child.href}>
                               <a
                                 href={child.href}
@@ -234,6 +258,14 @@ export default function MobileNav({ nav, announcement, currentPath }: Props) {
                                   currentPath && isCurrentNavHref(currentPath, child.href) ? "page" : undefined
                                 }
                                 class="block rounded px-2 py-1.5 font-body text-sm text-muted hover:bg-border/40 hover:text-text"
+                                {...trackingAttributes({
+                                  el: child.id,
+                                  action: child.action,
+                                  tracking: child.tracking,
+                                  placement: CHROME_PLACEMENT.mobileMenu,
+                                  scope: `nav-mobile-mega:${item.id}`,
+                                  index: ci,
+                                })}
                               >
                                 {child.label}
                               </a>
@@ -248,6 +280,14 @@ export default function MobileNav({ nav, announcement, currentPath }: Props) {
                           currentPath && isCurrentNavHref(currentPath, item.href) ? "page" : undefined
                         }
                         class="block rounded px-3 py-2.5 font-display text-base font-medium text-text hover:bg-border/40 hover:text-primary"
+                        {...trackingAttributes({
+                          el: item.id,
+                          action: item.action,
+                          tracking: item.tracking,
+                          placement: CHROME_PLACEMENT.mobileMenu,
+                          scope: "nav-mobile",
+                          index: i,
+                        })}
                       >
                         {item.label}
                       </a>

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

@@ -23,12 +23,13 @@ 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/adminService.js";
+import { getRegistryService } from "@/lib/apps/registryAccess.js";
 import { renderWidgetSlot } from "@/lib/apps/widgets/renderSlot.js";
 
 interface Props {
@@ -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/apps/registryAccess.ts

@@ -0,0 +1,45 @@
+/**
+ * Renderer-shared registry access — split out of `adminService.ts` (2026-09-02
+ * audit) because `getRegistryService`/`json` are needed by the actual page
+ * render path (Layout.astro, index.astro, products/[handle].astro resolve
+ * installed app widgets on every request) AND by the webhook dispatcher
+ * (`getDispatcher.ts`/`emit.ts`), while the REST of `adminService.ts`
+ * (`getManagedAnalyticsService`, `registryErrorResponse`, `parseInstallId`,
+ * `requireOwnedInstall`, `requireManageRole`) is reached only from the
+ * operator-only `/api/apps/admin/*` cluster. ESM loads a whole file's imports
+ * regardless of which export is used, so keeping both halves in one file meant
+ * every page render transitively pulled in the admin-only chain too (and made
+ * `adminService.ts` impossible to drop from the public storefront-runner
+ * without also breaking the renderer). This file is the renderer-safe half;
+ * `adminService.ts` re-exports `json` from here for its own admin-only helpers.
+ */
+import { AppRegistryService } from "./registryService.js";
+import { D1CredentialStore } from "./credentials.js";
+import { DEFAULT_APP_GATEWAY_KID, APP_GATEWAY_KID_ENV } from "./gatewayKeys.js";
+import { fromD1 } from "../d1/catalog.js";
+import { readD1, readEnv } from "../env.js";
+
+/**
+ * No-store JSON response — install/rotate bodies carry a one-time client
+ * secret and must never be edge- or browser-cached.
+ */
+export function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json", "cache-control": "no-store" },
+  });
+}
+
+/**
+ * Build an `AppRegistryService` over the real `STOREFRONT_APPS_DB` D1
+ * binding, or return a 503 Response when that binding isn't configured in
+ * this runtime. Never leaks binding/secret detail in the response body.
+ */
+export async function getRegistryService(): Promise<AppRegistryService | Response> {
+  const d1 = await readD1("STOREFRONT_APPS_DB");
+  if (!d1) return json({ error: "app registry not configured" }, 503);
+  const db = fromD1(d1);
+  const activeKid = (await readEnv(APP_GATEWAY_KID_ENV)) ?? DEFAULT_APP_GATEWAY_KID;
+  const credentials = new D1CredentialStore(db, activeKid);
+  return new AppRegistryService(db, credentials);
+}

package/apps/storefront/src/lib/auth/adminEntry.ts

@@ -30,13 +30,13 @@
  */
 import type { SessionRecord } from "./session.js";
 import { sessionHostCapability } from "./loginGate.js";
-import { decideIsOwner } from "@/lib/change/route/route";
 import {
+  decideIsOwner,
   resolveShipCapabilities,
+  OWNER_CAPABILITIES,
+  type Capability,
   type ShipCapabilities,
-} from "@/lib/change/route/ship-capabilities";
-import type { Capability } from "@/lib/change/types";
-import { OWNER_CAPABILITIES } from "@/lib/grants/session";
+} from "@/lib/shared/capability";
 
 /** Which entry case a viewer is in, for chrome + the DoD test matrix. */
 export type AdminEntryPrincipal =

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).