@tokenoftrust/storefront-runner 2.0.4 → 2.0.5

package/apps/storefront/src/lib/tracking-writeback/writebackCandidate.ts

@@ -0,0 +1,110 @@
+/**
+ * dt-id-writeback — turns {@link deriveTrackingWriteback} proposals for one or
+ * more tenant body documents into the SAME reviewable-candidate shape the admin
+ * Blog tab already rides (`pages/api/admin/blog.ts`): a content-only
+ * {@link FileChange} patch opened via `ChangeClient.openCandidate`, so a human
+ * reviews a real PR diff and accepts it — never a silent runtime mutation.
+ *
+ * This module is pure (no MCP call, no ChangeClient dependency) so the patch +
+ * PR body construction is unit-testable without a live forge; the route that
+ * calls `openCandidate` is a thin wrapper (see the sibling API route).
+ */
+import { deriveTrackingWriteback, type TrackingWritebackProposal } from "./rewriteTrackingIds.js";
+import type { DerivationOptions } from "@tot/public-runtime";
+
+/** One tenant body document to scan — repo-relative path + its current content. */
+export interface WritebackSourceFile {
+  /** e.g. "content/home.html" or "content/acme/pages-html/pricing.html". */
+  path: string;
+  content: string;
+}
+
+/** One file this writeback pass actually changed, plus its full proposal list. */
+export interface WritebackFileResult {
+  path: string;
+  content: string;
+  proposals: readonly TrackingWritebackProposal[];
+}
+
+export interface WritebackCandidatePlan {
+  /** Files that gained at least one new `data-tot-el` — the `FileChange` patch. */
+  patch: { path: string; content: string }[];
+  /** Every changed file's full proposal list, for the PR body + a caller's own reporting. */
+  files: WritebackFileResult[];
+  /** True iff `patch` is non-empty — nothing to open when false. */
+  hasChanges: boolean;
+  /** Count of `needsReview: true` rows across every changed file — the review flag. */
+  needsReviewCount: number;
+}
+
+/**
+ * Run the derivation writeback over every source file and assemble the patch a
+ * candidate PR would carry. Files with no undeclared trackable elements (already
+ * fully migrated, or nothing trackable) are omitted from `patch` entirely — this
+ * never proposes a no-op change.
+ */
+export function planTrackingWriteback(
+  sources: readonly WritebackSourceFile[],
+  options?: DerivationOptions,
+): WritebackCandidatePlan {
+  const files: WritebackFileResult[] = [];
+  const patch: { path: string; content: string }[] = [];
+  let needsReviewCount = 0;
+
+  for (const source of sources) {
+    const result = deriveTrackingWriteback(source.content, options);
+    if (!result.changed) continue;
+    files.push({ path: source.path, content: result.html, proposals: result.proposals });
+    patch.push({ path: source.path, content: result.html });
+    needsReviewCount += result.proposals.filter((p) => p.needsReview && !p.alreadyDeclared).length;
+  }
+
+  return { patch, files, hasChanges: patch.length > 0, needsReviewCount };
+}
+
+/**
+ * Render the candidate PR's body: a per-file listing of every NEWLY-assigned
+ * `data-tot-el`, with `needsReview: true` rows called out in their own section
+ * (per the derivation engine's own design intent — a positional id is the one a
+ * human should rename before accepting). `signals` is the diff annotation.
+ */
+export function formatWritebackReviewBody(plan: WritebackCandidatePlan): string {
+  const lines: string[] = [
+    "Derived `data-tot-el` identity for tenant-authored body elements that had none.",
+    "`confidence: \"declared\"` elements are untouched (never overwritten).",
+    "",
+  ];
+
+  const needsReview = plan.files.flatMap((f) =>
+    f.proposals
+      .filter((p) => p.needsReview && !p.alreadyDeclared)
+      .map((p) => ({ file: f.path, proposal: p })),
+  );
+
+  if (needsReview.length > 0) {
+    lines.push(
+      `## ⚠ Needs review — ${needsReview.length} element${needsReview.length === 1 ? "" : "s"} named by position`,
+      "",
+      "These derived ids leaned on sibling order (no author-chosen name, class, or link found). " +
+        "Rename them to something meaningful before accepting.",
+      "",
+    );
+    for (const { file, proposal } of needsReview) {
+      lines.push(`- \`${file}\`: \`${proposal.el}\` — ${proposal.snippet} _(${proposal.signals.join(", ")})_`);
+    }
+    lines.push("");
+  }
+
+  for (const file of plan.files) {
+    const assigned = file.proposals.filter((p) => !p.alreadyDeclared);
+    if (assigned.length === 0) continue;
+    lines.push(`## \`${file.path}\` — ${assigned.length} id${assigned.length === 1 ? "" : "s"} assigned`, "");
+    for (const p of assigned) {
+      const flag = p.needsReview ? "⚠ " : "";
+      lines.push(`- ${flag}\`${p.el}\` (${p.confidence}) — ${p.snippet} _(${p.signals.join(", ")})_`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n").trimEnd() + "\n";
+}

package/apps/storefront/src/pages/api/admin/interaction-insights.ts

@@ -0,0 +1,101 @@
+/**
+ * `GET /api/admin/interaction-insights` — dt-tenant-isolation. The first
+ * merchant-visible read over the per-tenant declarative-interaction D1
+ * databases `dt-storage-per-tenant-d1` built. The release-order doc's hard
+ * invariant — "no merchant-visible surface ships until dt-tenant-isolation
+ * lands" — is this route: it is the read authorization layer, not a rebuild
+ * of the storage layer underneath it.
+ *
+ * AUTH mirrors `/api/admin/activity-alerts` and every other tenant-scoped
+ * admin JSON route: `requireAdminApiEntry` — fail-closed, bound to
+ * `Astro.locals.tenant` (Host-resolved, never client input). The tenant this
+ * route reads for is `context.locals.tenant.tenant_id`, ALWAYS — there is no
+ * code path here that reads a tenant id from the query string, the body, or
+ * any header, so a malicious/malformed request cannot make this route open a
+ * different tenant's database no matter what it sends.
+ *
+ * ISOLATION — `resolveTenantStore` (dt-storage-per-tenant-d1) returns a
+ * handle bound to exactly one tenant's database UUID; `assertStoreOwnership`
+ * (dt-tenant-isolation, `tenantReadAccess.ts`) additionally confirms the
+ * resolved store's own `interaction_store_meta` row names THIS tenant before
+ * any row is read. Every query in `tenantReadAccess.ts` runs against that one
+ * scoped handle — never a query spanning tenants.
+ *
+ * No cross-tenant ADMIN/operator path is added here. There is no concrete
+ * near-term consumer for "ToT ops views any tenant's interaction data" (the
+ * existing staff cross-vendor path — `staffAdmits`/`enter-vendor` — grants
+ * DASHBOARD entry to a vendor, not a bypass of this route's own tenant
+ * scoping) — see the unit's completion report for the reasoning.
+ */
+import type { APIContext } from "astro";
+import { requireAdminApiEntry } from "@/lib/auth/adminApiGuard";
+import { readD1 } from "@/lib/env";
+import { fromD1 } from "@/lib/d1/catalog";
+import { resolveTenantStore, trackingNamePrefix } from "@/lib/tracking/tenantD1Registry";
+import { readD1Control } from "@/lib/tracking/d1Control";
+import { readTenantInteractionInsights } from "@/lib/tracking/tenantReadAccess";
+
+export const prerender = false;
+
+const JSON_HEADERS = {
+  "content-type": "application/json; charset=utf-8",
+  "cache-control": "no-store",
+  "x-robots-tag": "noindex, nofollow",
+};
+
+/** Query-string cap on the recent-events feed; clamped again in tenantReadAccess. */
+const MAX_LIMIT = 200;
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), { status, headers: JSON_HEADERS });
+}
+
+export async function GET(context: APIContext): Promise<Response> {
+  const access = await requireAdminApiEntry(context);
+  if (!access.ok) return json({ ok: false, reason: access.reason }, access.status);
+
+  // The ONLY tenant id this route ever uses. Host-resolved by tenant-routing
+  // middleware, never taken from `context.request` — see the module header.
+  const tenantId = context.locals.tenant?.tenant_id;
+  if (!tenantId) return json({ ok: false, status: "no_tenant", message: "no store resolved for this request" }, 400);
+
+  const rawLimit = Number(new URL(context.request.url).searchParams.get("limit") ?? "");
+  const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? Math.min(rawLimit, MAX_LIMIT) : undefined;
+
+  const [appsD1, control, namePrefix] = await Promise.all([
+    readD1("STOREFRONT_APPS_DB"),
+    readD1Control(),
+    trackingNamePrefix(),
+  ]);
+  if (!appsD1 || !control) {
+    // Sink not provisioned in this environment (local dev, an un-provisioned
+    // tier) — best-effort, same posture as activity-alerts' dbAvailable:false.
+    return json({ ok: true, dbAvailable: false, totalEvents: 0, byAction: [], recent: [] });
+  }
+
+  const store = await resolveTenantStore(tenantId, {
+    apps: fromD1(appsD1),
+    control,
+    namePrefix,
+    at: new Date().toISOString(),
+  });
+  if (!store) {
+    return json({ ok: true, dbAvailable: false, totalEvents: 0, byAction: [], recent: [] });
+  }
+
+  const insights = await readTenantInteractionInsights(store, { limit });
+  if (!insights) {
+    // Ownership assertion failed — fail-closed, never serve a store we could
+    // not verify belongs to this tenant.
+    return json({ ok: false, status: "store_unverified", message: "could not verify tenant store ownership" }, 503);
+  }
+
+  return json({
+    ok: true,
+    dbAvailable: true,
+    tenantId,
+    totalEvents: insights.totalEvents,
+    byAction: insights.byAction,
+    recent: insights.recent,
+  });
+}

package/apps/storefront/src/pages/api/tracking/interaction.ts

@@ -0,0 +1,123 @@
+/**
+ * POST /api/tracking/interaction (dt-collector-v1) — the beacon sink for
+ * declarative interaction tracking.
+ *
+ * The browser collector (`@/lib/tracking/interactionCollector`) batches
+ * `TotInteraction`s captured off `installInteractionTracking` /
+ * `onInteraction` (`@tot/public-runtime`) — via `dt-consent-environment-gate`'s
+ * consent/environment wrapper in front of it — and POSTs them here with
+ * `navigator.sendBeacon`, same transport contract as the F14 RUM beacon
+ * (`pages/api/rum/vitals.ts`): unauthenticated (a beacon carries no
+ * credentials), tenant resolved from `context.locals.tenant.tenant_id`
+ * (never the body), 204 on every outcome so a beacon never errors, retries,
+ * or blocks page unload.
+ *
+ * VALIDATION — `collectorIngest.ts` re-derives every field from the raw body
+ * under a default-deny allowlist (`collectorAllowlist.ts`): an unlisted key is
+ * dropped and counted, a listed-but-wrong-typed field rejects that event. Never
+ * trust the client for `tenant_id` or `stream` — both are stamped here, always.
+ *
+ * STORAGE — two sinks, fanned out past the response (`interactionStore.ts`,
+ * same shape as `pages/api/activity.ts`'s `fanOutActivity`):
+ *
+ *   • RAW ROWS → the tenant's OWN D1 database, resolved (and provisioned on
+ *     first sight) by `tenantD1Registry.resolveTenantStore`. ONE DATABASE PER
+ *     TENANT, so cross-tenant leakage is impossible by construction, not by a
+ *     correct `WHERE tenant_id = ?`. The directory that maps tenant → database
+ *     lives in the shared `STOREFRONT_APPS_DB`
+ *     (`tracking_tenant_databases`); the rows never do.
+ *   • AGGREGATES → the DEDICATED `INTERACTION_ANALYTICS` Analytics Engine
+ *     dataset (`storefront_interactions`) — NOT the operational spine's
+ *     `storefront_activity` dataset — rolled up to one point per dimension
+ *     tuple, so no per-event identity reaches AE.
+ *
+ * Both sinks are best-effort: unconfigured or failing, the batch falls back to
+ * the Workers Logs firehose and the beacon still 204s. `stream` (always
+ * `"interaction"` today) is the discriminator column to route on if a second
+ * stream is ever added.
+ */
+import type { APIContext } from "astro";
+import { readD1, readAnalytics, runAfterResponse, type CfExecutionContextLike } from "@/lib/env";
+import { fromD1 } from "@/lib/d1/catalog";
+import { ingestInteractions, type StampedInteractionEvent } from "@/lib/tracking/collectorIngest";
+import { readD1Control } from "@/lib/tracking/d1Control";
+import { resolveTenantStore, trackingNamePrefix } from "@/lib/tracking/tenantD1Registry";
+import { persistInteractions } from "@/lib/tracking/interactionStore";
+import type { AnalyticsEngineLike } from "@/lib/activity/store";
+
+export const prerender = false;
+
+/** Cap the batch so one beacon can't fan out unbounded off-path work. */
+const MAX_BATCH = 50;
+
+/**
+ * Resolve both sinks and write the batch. Runs PAST the response
+ * (`runAfterResponse`), so binding resolution + the D1 REST round-trip never
+ * hold the beacon open. Never throws — a telemetry beacon must not fail because
+ * storage is unconfigured or unreachable.
+ */
+async function storeInteractions(
+  tenantId: string,
+  events: StampedInteractionEvent[],
+  ingestedAt: string,
+): Promise<void> {
+  try {
+    const [appsDb, analyticsBinding, control, namePrefix] = await Promise.all([
+      readD1("STOREFRONT_APPS_DB"),
+      readAnalytics("INTERACTION_ANALYTICS"),
+      readD1Control(),
+      trackingNamePrefix(),
+    ]);
+
+    // The raw sink needs BOTH the directory (shared apps D1) and the D1 REST
+    // credentials that address a per-tenant database; either absent ⇒ skip it.
+    const store =
+      appsDb && control
+        ? await resolveTenantStore(tenantId, {
+            apps: fromD1(appsDb),
+            control,
+            namePrefix,
+            at: ingestedAt,
+          })
+        : undefined;
+
+    await persistInteractions(events, {
+      store,
+      analytics: (analyticsBinding as AnalyticsEngineLike | undefined) ?? undefined,
+    });
+  } catch {
+    /* never fail a telemetry beacon */
+  }
+}
+
+export async function POST(context: APIContext): Promise<Response> {
+  try {
+    const tenantId = (context.locals as { tenant?: { tenant_id?: string } })?.tenant?.tenant_id;
+    // No resolved tenant (e.g. a request that never went through tenant
+    // resolution) ⇒ nothing to stamp or store; still 204, never error the beacon.
+    if (!tenantId) return new Response(null, { status: 204 });
+
+    const parsed: unknown = await context.request.json();
+    const events = Array.isArray(parsed)
+      ? parsed
+      : parsed && typeof parsed === "object" && Array.isArray((parsed as { events?: unknown }).events)
+        ? (parsed as { events: unknown[] }).events
+        : [];
+    if (events.length === 0) return new Response(null, { status: 204 });
+
+    const batch = events.slice(0, MAX_BATCH);
+    const ingestedAt = new Date().toISOString();
+    const { accepted } = ingestInteractions(batch, tenantId, ingestedAt);
+
+    if (accepted.length > 0) {
+      const cfContext = (context.locals as { cfContext?: CfExecutionContextLike })?.cfContext ?? null;
+      runAfterResponse(
+        storeInteractions(tenantId, accepted.map((a) => a.event), ingestedAt),
+        cfContext,
+      );
+    }
+  } catch {
+    /* never fail a telemetry beacon */
+  }
+  return new Response(null, { status: 204 });
+}

package/apps/storefront/src/pages/style-guide/[tenant]/[theme].astro

@@ -43,6 +43,7 @@ import SiteHeader from "@/components/chrome/SiteHeader.astro";
 import MegaMenu from "@/components/chrome/MegaMenu.astro";
 import NavDropdown from "@/components/chrome/NavDropdown.astro";
 import SiteFooter from "@/components/chrome/SiteFooter.astro";
+import { CHROME_PLACEMENT } from "@/lib/chrome/trackingPlacements";
 import NicotineWarning from "@/components/compliance/NicotineWarning.astro";
 import PactActNotice from "@/components/compliance/PactActNotice.astro";
 import AdultSignatureNotice from "@/components/compliance/AdultSignatureNotice.astro";
@@ -88,28 +89,33 @@ const { tenant, theme } = Astro.params;
 const cspNonce = Astro.locals.cspNonce;
 
 // --- Sample chrome data (preview-only; no live tenant content) ----------------
+// Every actionable item declares its tracking intent (`action`) alongside its
+// identity (`id`) — the two are different axes and neither is derived from the
+// other. See docs/architecture/interaction-tracking-attribute-contract.md.
 const sampleNav: ChromeNavItem[] = [
-  { id: "nav-new", label: "New", href: "#", flag: true, badge: "NEW" },
+  { id: "nav-new", action: "nav-new", label: "New", href: "#", flag: true, badge: "NEW" },
   {
     id: "nav-shop",
+    action: "nav-shop",
     label: "Shop",
     href: "#",
     columns: [
-      { title: "Category", links: [{ id: "nav-shop-disposables", label: "Disposables", href: "#" }, { id: "nav-shop-eliquid", label: "E-Liquid", href: "#" }, { id: "nav-shop-devices", label: "Devices", href: "#" }] },
-      { title: "Featured", links: [{ id: "nav-shop-bestsellers", label: "Best Sellers", href: "#" }, { id: "nav-shop-onsale", label: "On Sale", href: "#", badge: "%" }] },
-      { title: "Brands", links: [{ id: "nav-shop-northwind", label: "Northwind", href: "#" }, { id: "nav-shop-summit", label: "Summit Co.", href: "#" }] },
+      { title: "Category", links: [{ id: "nav-shop-disposables", action: "nav-disposables", label: "Disposables", href: "#" }, { id: "nav-shop-eliquid", action: "nav-eliquid", label: "E-Liquid", href: "#" }, { id: "nav-shop-devices", action: "nav-devices", label: "Devices", href: "#" }] },
+      { title: "Featured", links: [{ id: "nav-shop-bestsellers", action: "nav-bestsellers", label: "Best Sellers", href: "#" }, { id: "nav-shop-onsale", action: "nav-on-sale", label: "On Sale", href: "#", badge: "%" }] },
+      { title: "Brands", links: [{ id: "nav-shop-northwind", action: "nav-brand-northwind", label: "Northwind", href: "#" }, { id: "nav-shop-summit", action: "nav-brand-summit", label: "Summit Co.", href: "#" }] },
     ],
   },
-  { id: "nav-coils", label: "Coils & Parts", href: "#", children: [{ id: "nav-coils-coils", label: "Coils", href: "#" }, { id: "nav-coils-pods", label: "Pods", href: "#" }, { id: "nav-coils-batteries", label: "Batteries", href: "#" }] },
-  { id: "nav-sale", label: "On Sale", href: "#" },
+  { id: "nav-coils", action: "nav-coils-and-parts", label: "Coils & Parts", href: "#", children: [{ id: "nav-coils-coils", action: "nav-coils", label: "Coils", href: "#" }, { id: "nav-coils-pods", action: "nav-pods", label: "Pods", href: "#" }, { id: "nav-coils-batteries", action: "nav-batteries", label: "Batteries", href: "#" }] },
+  { id: "nav-sale", action: "nav-on-sale", label: "On Sale", href: "#" },
 ];
 const sampleSocial = [
   { label: "X", href: "#", iconPath: "M18.9 2H22l-7.1 8.1L23 22h-6.6l-5-6.6L5.7 22H2.6l7.6-8.7L1.5 2h6.8l4.5 6 5.1-6z" },
 ];
 const sampleFooterCols = [
-  { title: "Shop", links: [{ id: "ftr-shop-disposables", label: "Disposables", href: "#" }, { id: "ftr-shop-eliquid", label: "E-Liquid", href: "#" }, { id: "ftr-shop-devices", label: "Devices", href: "#" }] },
-  { title: "Support", links: [{ id: "ftr-support-contact", label: "Contact", href: "#" }, { id: "ftr-support-shipping", label: "Shipping", href: "#" }, { id: "ftr-support-returns", label: "Returns", href: "#" }] },
-  { title: "Company", links: [{ id: "ftr-company-about", label: "About", href: "#" }, { id: "ftr-company-blog", label: "Blog", href: "#" }] },
+  // The footer repeats the header's intents: same `action`, different placement.
+  { title: "Shop", links: [{ id: "ftr-shop-disposables", action: "nav-disposables", label: "Disposables", href: "#" }, { id: "ftr-shop-eliquid", action: "nav-eliquid", label: "E-Liquid", href: "#" }, { id: "ftr-shop-devices", action: "nav-devices", label: "Devices", href: "#" }] },
+  { title: "Support", links: [{ id: "ftr-support-contact", action: "nav-contact", label: "Contact", href: "#" }, { id: "ftr-support-shipping", action: "nav-shipping", label: "Shipping", href: "#" }, { id: "ftr-support-returns", action: "nav-returns", label: "Returns", href: "#" }] },
+  { title: "Company", links: [{ id: "ftr-company-about", action: "nav-about", label: "About", href: "#" }, { id: "ftr-company-blog", action: "nav-blog", label: "Blog", href: "#" }] },
 ];
 // BrandGrid samples: text-wordmark tiles and logo-image tiles (Img renders
 // deterministic placeholders offline so the image code path is exercised
@@ -321,12 +327,17 @@ const sampleManageEntries: SubscriptionManageEntry[] = [
 // --- Sample islands data (preview-only) ----------------------------------
 const sampleMobileNav = [
   {
+    id: "mnav-shop",
+    action: "nav-shop",
     label: "Shop",
     href: "#",
-    children: [{ label: "Disposables", href: "#" }, { label: "E-Liquid", href: "#" }],
+    children: [
+      { id: "mnav-shop-disposables", action: "nav-disposables", label: "Disposables", href: "#" },
+      { id: "mnav-shop-eliquid", action: "nav-eliquid", label: "E-Liquid", href: "#" },
+    ],
   },
-  { label: "Coils & Parts", href: "#" },
-  { label: "On Sale", href: "#" },
+  { id: "mnav-coils", action: "nav-coils-and-parts", label: "Coils & Parts", href: "#" },
+  { id: "mnav-sale", action: "nav-on-sale", label: "On Sale", href: "#" },
 ];
 const sampleFromProduct = sampleProducts.find((p) => p.handle === "sample-from")!;
 const sampleRecentlyViewed: RVItem[] = [
@@ -1149,7 +1160,7 @@ const componentVarsInline = Object.entries(componentVars)
       <section class="sg-block">
         <p class="sg-h">Chrome — UtilityNav</p>
         <UtilityNav
-          links={[{ id: "util-news", label: "News", href: "#" }, { id: "util-about", label: "About", href: "#" }, { id: "util-contact", label: "Contact", href: "#" }]}
+          links={[{ id: "util-news", action: "nav-news", label: "News", href: "#" }, { id: "util-about", action: "nav-about", label: "About", href: "#" }, { id: "util-contact", action: "nav-contact", label: "Contact", href: "#" }]}
           locale="English"
           currency="United States (USD $)"
           social={sampleSocial}
@@ -1181,7 +1192,15 @@ const componentVarsInline = Object.entries(componentVars)
         <p class="sg-h">Chrome — NavDropdown accordion (mobile mega parity, zero-JS)</p>
         <div style="max-width:18rem;background:var(--color-surface);border:1px solid var(--color-border);border-radius:8px;padding:8px 12px">
           <ul class="grid">
-            {sampleNav.map((item) => <NavDropdown item={item} mode="accordion" />)}
+            {sampleNav.map((item, i) => (
+              <NavDropdown
+                item={item}
+                mode="accordion"
+                placement={CHROME_PLACEMENT.mobileMenu}
+                menuPlacement={CHROME_PLACEMENT.mobileMenu}
+                index={i}
+              />
+            ))}
           </ul>
         </div>
         <p class="form-help" style="margin-top:8px;color:var(--color-muted)">Same nav items in the mobile menu: mega columns become inline <code>&lt;details&gt;</code> accordions (keyboard + touch operable). Toggle a caret item to expand.</p>

package/apps/storefront/src/workers/pruneRollupWorker.ts

@@ -0,0 +1,120 @@
+/**
+ * The scheduled Cloudflare Worker entry for `dt-prune-and-rollup`.
+ *
+ * A SEPARATE, DEDICATED Worker script from the Astro-adapted storefront
+ * Worker — deliberately, not a `scheduled` export bolted onto the Astro
+ * entry. The @astrojs/cloudflare adapter OWNS `dist/server/entry.mjs` and
+ * bakes its target environment in at BUILD time via `CLOUDFLARE_ENV`
+ * (`wrangler.toml`'s own "DEPLOY FOOTGUN" comment); the documented way to add
+ * a non-`fetch` handler there is a custom entrypoint that re-imports the
+ * adapter's generated `handle()`, which would make this cron trigger's
+ * correctness depend on the SAME footgun-prone build/deploy sequencing as
+ * the whole storefront. This module instead has nothing to do with Astro at
+ * all — it is a plain `ExportedHandler` deployed under its own Worker name
+ * (`wrangler.prune-rollup.toml`, `[triggers]` below), reusing the tracking
+ * library's already-built, framework-agnostic pieces
+ * (`lib/tracking/pruneRollup.ts`, `d1Control.ts`, `interactionStore.ts`).
+ * There is no other scheduled-Worker precedent in this repo to follow; this
+ * is the first one, chosen to keep the footgun-prone Astro deploy path
+ * completely untouched.
+ *
+ * BINDINGS (declared in `wrangler.prune-rollup.toml`, not this file):
+ *   - `STOREFRONT_APPS_DB` — the SAME shared D1 database the main storefront
+ *     Worker binds, for the `tracking_tenant_databases` directory.
+ *   - `INTERACTION_ANALYTICS` — the SAME Analytics Engine dataset the main
+ *     Worker writes rollups to.
+ *   - `CF_ACCOUNT_ID` / `TRACKING_D1_API_TOKEN` (secret) — D1 REST
+ *     credentials for reaching each tenant's OWN database (Worker bindings
+ *     are static; a per-tenant database can only be addressed over the D1
+ *     HTTP API, same reasoning as `d1Control.ts`'s module doc).
+ *   - `TRACKING_D1_NAME_PREFIX` (optional) — unused by this worker directly,
+ *     kept only for parity/documentation; the prune sweep addresses tenants
+ *     by `database_uuid` from the directory, never by re-deriving the name.
+ */
+import type { Queryable } from "../lib/d1/catalog.js";
+import type { D1Like } from "../lib/d1/catalog.js";
+import { fromD1 } from "../lib/d1/catalog.js";
+import type { AnalyticsEngineLike } from "../lib/activity/store.js";
+import type { D1ControlConfig } from "../lib/tracking/d1Control.js";
+import { runPruneSweep, type PruneSweepResult } from "../lib/tracking/pruneRollup.js";
+
+/** The env bindings this Worker needs — a local, minimal slice (this repo
+ *  does not take a `@cloudflare/workers-types` dependency; see `d1Control.ts`
+ *  and `activity/store.ts` for the same convention). */
+export interface PruneRollupEnv {
+  STOREFRONT_APPS_DB: D1Like;
+  INTERACTION_ANALYTICS?: AnalyticsEngineLike;
+  CF_ACCOUNT_ID?: string;
+  TRACKING_D1_API_TOKEN?: string;
+  /** Tenants processed per invocation; overridable for a slower/faster cron. */
+  PRUNE_BATCH_SIZE?: string;
+}
+
+/** The minimal slice of Cloudflare's `ScheduledController` this handler uses. */
+export interface ScheduledControllerLike {
+  scheduledTime: number;
+}
+
+/** The minimal slice of Cloudflare's `ExecutionContext` this handler uses. */
+export interface ExecutionContextLike {
+  waitUntil(promise: Promise<unknown>): void;
+}
+
+/** Build the D1 REST control config from env, or undefined when unconfigured
+ *  (mirrors `d1Control.ts`'s `readD1Control()` "skip, never fail" posture). */
+function controlFromEnv(env: PruneRollupEnv): D1ControlConfig | undefined {
+  if (!env.CF_ACCOUNT_ID || !env.TRACKING_D1_API_TOKEN) return undefined;
+  return { accountId: env.CF_ACCOUNT_ID, apiToken: env.TRACKING_D1_API_TOKEN };
+}
+
+/**
+ * The pure orchestration the `scheduled` export below delegates to — kept
+ * separate so it is callable/testable without a real `ScheduledController`.
+ * Never throws: a misconfigured environment (no D1 REST credentials) logs
+ * and no-ops rather than failing the cron invocation.
+ */
+export async function handleScheduledPrune(
+  env: PruneRollupEnv,
+  now: string = new Date().toISOString(),
+): Promise<PruneSweepResult | undefined> {
+  const control = controlFromEnv(env);
+  if (!control) {
+    console.error(
+      "[tracking:prune] skipped — CF_ACCOUNT_ID/TRACKING_D1_API_TOKEN not configured",
+    );
+    return undefined;
+  }
+
+  const apps: Queryable = fromD1(env.STOREFRONT_APPS_DB);
+  const batchSize = env.PRUNE_BATCH_SIZE ? Number.parseInt(env.PRUNE_BATCH_SIZE, 10) : undefined;
+
+  const result = await runPruneSweep({
+    apps,
+    control,
+    analytics: env.INTERACTION_ANALYTICS,
+    now,
+    ...(batchSize && Number.isFinite(batchSize) ? { batchSize } : {}),
+  });
+
+  console.info(
+    `[tracking:prune] swept ${result.tenantsSwept} tenant(s), pruned ${result.totalPrunedRows} row(s), ` +
+      `wrote ${result.totalAggregatesWritten} aggregate(s)`,
+  );
+  return result;
+}
+
+export default {
+  async scheduled(
+    controller: ScheduledControllerLike,
+    env: PruneRollupEnv,
+    ctx: ExecutionContextLike,
+  ): Promise<void> {
+    ctx.waitUntil(
+      handleScheduledPrune(env, new Date(controller.scheduledTime).toISOString()).catch((err) => {
+        console.error(
+          `[tracking:prune] sweep threw: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }),
+    );
+  },
+};

package/package.json

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

package/packages/public-runtime/node_modules/.bin/vitest

@@ -25,9 +25,9 @@ case `uname -a` in
 esac
 
 if [ -z "$NODE_PATH" ]; then
-  export NODE_PATH="/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/vitest@2.1.8_@types+node@26.4.1_happy-dom@20.13.1_lightningcss@1.33.0/node_modules/vitest/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/vitest@2.1.8_@types+node@26.4.1_happy-dom@20.13.1_lightningcss@1.33.0/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/node_modules"
+  export NODE_PATH="/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/vitest@2.1.8_@types+node@26.4.1_happy-dom@20.13.2_lightningcss@1.33.0/node_modules/vitest/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/vitest@2.1.8_@types+node@26.4.1_happy-dom@20.13.2_lightningcss@1.33.0/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/node_modules"
 else
-  export NODE_PATH="/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/vitest@2.1.8_@types+node@26.4.1_happy-dom@20.13.1_lightningcss@1.33.0/node_modules/vitest/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/vitest@2.1.8_@types+node@26.4.1_happy-dom@20.13.1_lightningcss@1.33.0/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/node_modules:$NODE_PATH"
+  export NODE_PATH="/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/vitest@2.1.8_@types+node@26.4.1_happy-dom@20.13.2_lightningcss@1.33.0/node_modules/vitest/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/vitest@2.1.8_@types+node@26.4.1_happy-dom@20.13.2_lightningcss@1.33.0/node_modules:/home/runner/work/storefront/storefront/storefront-runner-dist/node_modules/.pnpm/node_modules:$NODE_PATH"
 fi
 if [ -n "$exe" ] && [ -x "$basedir/node.exe" ]; then
   exec "$basedir/node.exe"  "$basedir_win/../vitest/vitest.mjs" "$@"