@tokenoftrust/storefront-runner 2.0.4 → 2.0.6

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

@@ -0,0 +1,252 @@
+/**
+ * The interaction-tracking chain's HEALTH ASSERTION — the thing that makes a
+ * broken collection chain loud instead of silent.
+ *
+ * Why it exists. Every other part of this system is correctly fail-quiet at
+ * runtime: the delegated listener returns without an event when there is no
+ * `data-tot-el` up the ancestor chain (that is the `tracking: "none"` opt-out,
+ * where ABSENCE is the declaration), and the consent/environment gate drops a
+ * disallowed interaction with no error. Both are right. Together they mean a
+ * surface that was never stamped at all produces exactly the same observable
+ * result as a surface nobody clicked — which is the failure mode that made the
+ * legacy mixin useless for years: no way to tell "collection is broken" from
+ * "legitimately idle".
+ *
+ * This module is the one place that CAN tell them apart, because it looks at
+ * the rendered markup rather than at the event stream:
+ *
+ *   - `mount_missing` — the document carries actionable elements but not the
+ *     serialized listener, so no click on it can ever be seen. FATAL.
+ *   - `chrome_unstamped` — the surface carries actionable elements and NOT ONE
+ *     of them carries `data-tot-el`. FATAL. Zero-of-N is not an opt-out
+ *     declaration; a real opt-out is per element, and an author opting out of
+ *     every single element still leaves the OTHER elements stamped. This is
+ *     the finding that covers the **sharedChrome bypass path**: a tenant that
+ *     ships a hand-authored `content/<id>/chrome.html` bypasses governed
+ *     chrome entirely, so `validateChromeConfig` never sees it,
+ *     `trackingAttributes()` never stamps it, and `rewriteTrackingIds`
+ *     (dt-id-writeback) explicitly refuses to touch chrome. Nothing else in
+ *     the chain would ever say a word about it.
+ *   - `stamp_incomplete` — elements carry `data-tot-el` but no
+ *     `data-tot-action`. NOT fatal: the publish-time safety net
+ *     (`publishSafetyNet.ts`) stamps identity only, by design, and there is no
+ *     derivation path from identity to intent. Reported because those rows
+ *     land in the store un-analyzable, which is worth seeing.
+ *
+ * NO DOM-TEXT READS: only `tagName` and the parsed attribute list are ever
+ * read, matching the payload guardrail the listener and every consumer are
+ * held to. Actionability is decided by `@tot/public-runtime`'s shared
+ * `isTrackableNode` — the same oracle the derivation engine and the writeback
+ * rewriter use, so "actionable" cannot mean three different things.
+ */
+import { parse } from "parse5";
+import {
+  INTERACTION_TRACKING_BOOT_JS,
+  TRACKING_ATTR_ACTION,
+  TRACKING_ATTR_EL,
+  isTrackableNode,
+  type StructuralNode,
+} from "@tot/public-runtime";
+
+/** The finding codes, in the order this module reports them. */
+export type TrackingHealthCode = "mount_missing" | "chrome_unstamped" | "stamp_incomplete";
+
+/** The codes that mean the chain is BROKEN rather than merely imperfect. */
+const FATAL_CODES: ReadonlySet<TrackingHealthCode> = new Set<TrackingHealthCode>([
+  "mount_missing",
+  "chrome_unstamped",
+]);
+
+export interface TrackingHealthFinding {
+  code: TrackingHealthCode;
+  /** Human-actionable one-liner; carries counts and tags, never content. */
+  detail: string;
+  fatal: boolean;
+}
+
+export interface TrackingHealthReport {
+  /** True iff there is no FATAL finding — i.e. a click here can be collected. */
+  ok: boolean;
+  /** Elements an interaction can originate from (`isTrackableNode`). */
+  actionable: number;
+  /** Of those, how many carry `data-tot-el`. */
+  stamped: number;
+  /** Of the stamped ones, how many also carry `data-tot-action`. */
+  attributed: number;
+  findings: TrackingHealthFinding[];
+}
+
+export interface TrackingHealthOptions {
+  /**
+   * Require the serialized listener to be present. True for a whole document,
+   * false for a chrome WRAPPER inspected before `rawHtmlResponse()` has
+   * injected the listener into it.
+   */
+  requireMount?: boolean;
+  /** A label for the log/error line — e.g. `chrome.html (tenant acme)`. */
+  surface?: string;
+}
+
+/** Thrown by {@link assertTrackingChainHealthy} on a FATAL finding. */
+export class TrackingChainBrokenError extends Error {
+  readonly report: TrackingHealthReport;
+
+  constructor(report: TrackingHealthReport, surface: string) {
+    const codes = report.findings.filter((f) => f.fatal).map((f) => f.code);
+    super(
+      `interaction tracking is BROKEN on ${surface} [${codes.join(", ")}] — ` +
+        report.findings
+          .filter((f) => f.fatal)
+          .map((f) => f.detail)
+          .join("; ") +
+        ` (actionable=${report.actionable}, stamped=${report.stamped}, ` +
+        `attributed=${report.attributed}). A click on this surface produces NO ` +
+        `retrievable event, and nothing else in the chain reports it: the listener ` +
+        `returns silently when no ${TRACKING_ATTR_EL} is present, which is also how a ` +
+        `legitimate \`tracking: "none"\` opt-out looks.`,
+    );
+    this.name = "TrackingChainBrokenError";
+    this.report = report;
+  }
+}
+
+interface P5Attr {
+  name: string;
+  value: string;
+}
+interface P5Node {
+  nodeName: string;
+  tagName?: string;
+  attrs?: P5Attr[];
+  childNodes?: P5Node[];
+}
+
+function nonEmpty(v: string | undefined): boolean {
+  return typeof v === "string" && v.trim().length > 0;
+}
+
+/**
+ * Inspect one rendered surface (a full document, a chrome wrapper, or a body
+ * fragment). PURE — no I/O, no logging, no throwing. `html` that parses to
+ * nothing actionable is healthy by definition: a surface with no actionable
+ * element has nothing to collect, and saying otherwise would make every
+ * text-only page a false alarm.
+ */
+export function inspectTrackingChain(
+  html: string,
+  options: TrackingHealthOptions = {},
+): TrackingHealthReport {
+  let actionable = 0;
+  let stamped = 0;
+  let attributed = 0;
+  const unstampedTags = new Set<string>();
+
+  const walk = (node: P5Node): void => {
+    if (node.tagName) {
+      const attrs: Record<string, string> = {};
+      for (const a of node.attrs ?? []) attrs[a.name] = a.value;
+      const structural: StructuralNode = { tag: node.tagName.toLowerCase(), attrs };
+      const hasEl = nonEmpty(attrs[TRACKING_ATTR_EL]);
+      if (isTrackableNode(structural)) {
+        actionable += 1;
+        if (hasEl) {
+          stamped += 1;
+          if (nonEmpty(attrs[TRACKING_ATTR_ACTION])) attributed += 1;
+        } else {
+          unstampedTags.add(structural.tag);
+        }
+      } else if (hasEl) {
+        // Stamped but not actionable by the shared oracle (e.g. a stamped
+        // wrapper). Counted so `stamped` never understates the surface.
+        stamped += 1;
+        if (nonEmpty(attrs[TRACKING_ATTR_ACTION])) attributed += 1;
+      }
+    }
+    for (const child of node.childNodes ?? []) walk(child);
+  };
+  walk(parse(html) as P5Node);
+
+  const findings: TrackingHealthFinding[] = [];
+
+  if (options.requireMount && actionable > 0 && !html.includes(INTERACTION_TRACKING_BOOT_JS)) {
+    findings.push({
+      code: "mount_missing",
+      detail: `${actionable} actionable element(s) but the serialized interaction-tracking listener is not in this document`,
+      fatal: true,
+    });
+  }
+
+  if (actionable > 0 && stamped === 0) {
+    findings.push({
+      code: "chrome_unstamped",
+      detail:
+        `${actionable} actionable element(s) (${[...unstampedTags].sort().join(", ")}) and NOT ONE ` +
+        `carries ${TRACKING_ATTR_EL} — an unstamped surface, not a per-element opt-out`,
+      fatal: true,
+    });
+  } else if (stamped > attributed) {
+    findings.push({
+      code: "stamp_incomplete",
+      detail: `${stamped - attributed} of ${stamped} stamped element(s) carry no ${TRACKING_ATTR_ACTION}, so their rows land un-analyzable`,
+      fatal: false,
+    });
+  }
+
+  return {
+    ok: !findings.some((f) => f.fatal),
+    actionable,
+    stamped,
+    attributed,
+    findings,
+  };
+}
+
+/**
+ * {@link inspectTrackingChain}, but a FATAL finding THROWS. For build/publish
+ * gates and tests — anywhere a broken chain should stop the line rather than
+ * be noted.
+ */
+export function assertTrackingChainHealthy(
+  html: string,
+  options: TrackingHealthOptions = {},
+): TrackingHealthReport {
+  const report = inspectTrackingChain(html, options);
+  if (!report.ok) throw new TrackingChainBrokenError(report, options.surface ?? "this surface");
+  return report;
+}
+
+/**
+ * The render-path form: NEVER throws, emits ONE distinct structured line per
+ * distinct outcome so a broken surface is visible in Workers Logs. Returns the
+ * report so a caller can act on it.
+ *
+ * Non-throwing on purpose — a tenant whose hand-authored chrome was never
+ * stamped should get a loud log line, not a blank page.
+ */
+const reported = new Set<string>();
+/** Bound the dedupe set so a long-lived isolate cannot grow it without limit. */
+const REPORTED_MAX = 64;
+
+export function reportTrackingChainHealth(
+  html: string,
+  options: TrackingHealthOptions = {},
+): TrackingHealthReport {
+  const report = inspectTrackingChain(html, options);
+  if (report.findings.length === 0) return report;
+  const surface = options.surface ?? "unknown-surface";
+  const key = `${surface}|${report.findings.map((f) => f.code).join(",")}|${report.actionable}/${report.stamped}`;
+  if (reported.has(key)) return report;
+  if (reported.size >= REPORTED_MAX) reported.clear();
+  reported.add(key);
+  for (const finding of report.findings) {
+    const line = `[tracking:health] ${finding.fatal ? "BROKEN" : "degraded"} ${finding.code} on ${surface}: ${finding.detail}`;
+    if (finding.fatal) console.error(line);
+    else console.warn(line);
+  }
+  return report;
+}
+
+/** Test-only: forget which lines have already been emitted. */
+export function resetTrackingHealthReportingForTests(): void {
+  reported.clear();
+}

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

@@ -0,0 +1,107 @@
+/**
+ * The RAW interaction-event table — the schema of a TENANT'S OWN D1 database.
+ *
+ * PER-TENANT, NOT PER-COLUMN. Every other D1 table in this repo lives in a
+ * shared database and carries a `tenant_id` column as its isolation boundary
+ * (see `d1/schema-apps.ts`). This one does NOT work that way: each tenant gets
+ * its OWN D1 database holding only its own rows, so cross-tenant leakage is
+ * impossible BY CONSTRUCTION rather than by a correct `WHERE tenant_id = ?` in
+ * every query. A missing predicate here cannot reach another tenant's data —
+ * there is no other tenant's data in the file.
+ *
+ * `tenant_id` is still stored on the row (redundantly, one constant value per
+ * database) deliberately: it makes an exported/backed-up/rolled-up row
+ * self-describing, and it lets a mis-routed insert be DETECTED (a row whose
+ * `tenant_id` disagrees with the database's owner is a routing bug, and
+ * `dt-tenant-isolation` can assert on exactly that).
+ *
+ * WHY D1 AND NOT A SHARED STORE: D1 is not billed per database — thousands of
+ * databases cost the same as one — so per-tenant databases are the endorsed
+ * shape, not a workaround. The hard limit is 10GB PER DATABASE (~30M rows at a
+ * 90-day window for a busy tenant), which is a per-tenant ceiling rather than a
+ * global one; `interaction_store_meta` below carries the counters
+ * `dt-prune-and-rollup` needs to surface a tenant approaching it.
+ *
+ * RETENTION is a 90-day window, enforced by a DELETE-based prune in a later
+ * unit (`dt-prune-and-rollup`) — D1 has no TTL. This schema only has to make
+ * that prune cheap, which is what `idx_interaction_events_ingested_at` is for:
+ * `DELETE FROM interaction_events WHERE ingested_at < ?` is an index range
+ * scan, not a table scan. `ingested_at` (the SERVER receive clock) is the prune
+ * key, never `ts` (a CLIENT clock a beacon can skew arbitrarily).
+ *
+ * SCHEMA IS APPLIED, NOT MIGRATED. A per-tenant database is created on demand
+ * at runtime, so it cannot ride the numbered `migrations-apps/` lineage (which
+ * `wrangler d1 migrations apply` runs against ONE named binding). Instead this
+ * DDL is idempotent (`IF NOT EXISTS` throughout) and applied at provision time;
+ * `INTERACTION_SCHEMA_VERSION` is recorded in `interaction_store_meta` so a
+ * future version bump can be detected and re-applied per tenant.
+ */
+
+/** Bumped whenever `INTERACTION_D1_SCHEMA` changes; recorded per database. */
+export const INTERACTION_SCHEMA_VERSION = 1;
+
+/**
+ * Idempotent DDL for one tenant's raw-interaction database. Multi-statement:
+ * applied via `Queryable.exec`, which both the D1 binding and the D1 HTTP API
+ * accept as a semicolon-separated script.
+ */
+export const INTERACTION_D1_SCHEMA = `
+CREATE TABLE IF NOT EXISTS interaction_events (
+  -- Owning tenant. One constant value per database (see the module note): the
+  -- isolation boundary is the DATABASE, this column is provenance + a
+  -- mis-routing tripwire.
+  tenant_id TEXT NOT NULL,
+  -- Stream discriminator, always "interaction" today. Present from row one so a
+  -- second stream can land in the same table without a migration.
+  stream TEXT NOT NULL,
+  -- The six TotInteraction fields, flattened for SQL aggregation.
+  type TEXT NOT NULL,
+  el TEXT NOT NULL,
+  action TEXT,
+  placement TEXT,
+  scope TEXT,
+  idx INTEGER,
+  -- Groups the events of one collector lifetime (~one page load).
+  correlation_id TEXT NOT NULL,
+  -- Monotonic within correlation_id, assigned by the client collector.
+  seq INTEGER NOT NULL,
+  -- Client emit clock (ISO-8601). Informational: never the prune or ordering key.
+  ts TEXT NOT NULL,
+  -- Server receive clock (ISO-8601). THE retention/prune key.
+  ingested_at TEXT NOT NULL,
+  -- (correlation_id, seq) is the collector's own natural identity, so a
+  -- retried/duplicated beacon re-inserting the same event is a no-op under
+  -- INSERT OR IGNORE rather than a double-count.
+  PRIMARY KEY (correlation_id, seq)
+);
+CREATE INDEX IF NOT EXISTS idx_interaction_events_ingested_at
+  ON interaction_events (ingested_at);
+CREATE INDEX IF NOT EXISTS idx_interaction_events_stream_ingested_at
+  ON interaction_events (stream, ingested_at);
+CREATE INDEX IF NOT EXISTS idx_interaction_events_el
+  ON interaction_events (el, ingested_at);
+CREATE TABLE IF NOT EXISTS interaction_store_meta (
+  -- Single-row table. The constant primary key makes that a schema invariant.
+  -- (Keep every inline comment free of semicolons: this DDL is executed as one
+  -- semicolon-separated script.)
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  tenant_id TEXT NOT NULL,
+  schema_version INTEGER NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+`;
+
+/** Statements that stamp/refresh the single `interaction_store_meta` row. */
+export function interactionMetaUpsert(tenantId: string, at: string): {
+  sql: string;
+  params: readonly unknown[];
+} {
+  return {
+    sql: `INSERT INTO interaction_store_meta (id, tenant_id, schema_version, created_at, updated_at)
+          VALUES (1, ?, ?, ?, ?)
+          ON CONFLICT(id) DO UPDATE SET schema_version = excluded.schema_version,
+                                        updated_at = excluded.updated_at`,
+    params: [tenantId, INTERACTION_SCHEMA_VERSION, at, at],
+  };
+}

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

@@ -0,0 +1,260 @@
+/**
+ * Scheduled PRUNE + ROLLUP for the per-tenant raw-interaction D1 stores
+ * (`dt-storage-per-tenant-d1`).
+ *
+ * WHAT THIS DOES, per tenant, per sweep:
+ *   1. READ the rows aging out of the 90-day window (`ingested_at < cutoff`,
+ *      the SERVER receive clock — never the client `ts`, which a beacon can
+ *      skew arbitrarily).
+ *   2. ROLL UP those rows via the already-built, pure `aggregateInteractions()`
+ *      and write them to the dedicated `INTERACTION_ANALYTICS` dataset via
+ *      the already-built `writeInteractionAnalytics()` — durable long-term
+ *      aggregates survive the delete below. Both are reused verbatim from
+ *      `interactionStore.ts`, never reimplemented here.
+ *   3. DELETE those same rows. `DELETE FROM interaction_events WHERE
+ *      ingested_at < ?` is an index range scan
+ *      (`idx_interaction_events_ingested_at`), not a table scan.
+ *   4. MEASURE the database's current size (`PRAGMA page_count * page_size`)
+ *      and warn when a tenant is approaching D1's 10GB-per-database ceiling —
+ *      the point is to surface this BEFORE writes start failing, not after.
+ *   5. WRITE BACK the `tracking_tenant_databases` bookkeeping columns
+ *      (`last_pruned_at`, `pruned_rows`, `size_bytes`, `size_checked_at`) that
+ *      `dt-storage-per-tenant-d1` added for exactly this purpose.
+ *
+ * WORK QUEUE. One sweep processes a bounded BATCH of tenants
+ * (`ORDER BY last_pruned_at ASC` — SQLite sorts NULL first, so a tenant that
+ * has never been pruned is swept immediately), not the whole fleet in one
+ * invocation. A frequent-enough cron (see `workers/pruneRollupWorker.ts`)
+ * cycles fairly through every tenant over time instead of risking one run
+ * exceeding the Worker's CPU/wall-clock budget as the tenant count grows.
+ *
+ * NOT DONE HERE (by design, per the binding decisions this unit follows):
+ *   - No DROP-based time-partitioned schema. The DROP-vs-DELETE cost
+ *     asymmetry noted in `d1-cost-basis-verified` is UNVERIFIED inference;
+ *     this sticks to the straightforward `DELETE ... WHERE ingested_at < ?`
+ *     against the single `interaction_events` table dt-storage-per-tenant-d1
+ *     already built. A future optimization pass can revisit it once verified.
+ *   - No outbound alert transport. Same posture as `activity/alerts.ts`: this
+ *     module DETECTS a tenant approaching the ceiling and logs it
+ *     (`console.warn`, grep-able in Workers Logs) plus returns it in the
+ *     structured sweep result — where it goes from there (a dashboard, a
+ *     polled endpoint) is a sink's job, not this module's.
+ *
+ * BEST-EFFORT PER TENANT. One tenant's prune failing (a REST error, a
+ * transient D1 fault) is caught, logged, and recorded in that tenant's
+ * outcome — it never aborts the rest of the batch.
+ */
+import type { Queryable } from "../d1/catalog.js";
+import type { AnalyticsEngineLike } from "../activity/store.js";
+import { fromD1Rest, type D1ControlConfig } from "./d1Control.js";
+import { aggregateInteractions, writeInteractionAnalytics } from "./interactionStore.js";
+import type { StampedInteractionEvent } from "./collectorIngest.js";
+
+/** The settled retention window (`settled-operational-choices`). */
+export const DEFAULT_RETENTION_DAYS = 90;
+
+/** How many tenants one sweep invocation processes. */
+export const DEFAULT_BATCH_SIZE = 25;
+
+/** D1's documented per-database ceiling. */
+export const D1_SIZE_CEILING_BYTES = 10 * 1024 * 1024 * 1024;
+
+/** Warn at 80% of the ceiling — well before writes start failing. */
+const DEFAULT_SIZE_WARNING_RATIO = 0.8;
+
+/** One row of the prune work queue. */
+export interface TenantPruneRow {
+  tenant_id: string;
+  database_uuid: string;
+  last_pruned_at: string | null;
+}
+
+export interface PruneSweepDeps {
+  /** The shared STOREFRONT_APPS_DB handle holding the directory table. */
+  apps: Queryable;
+  /** D1 REST credentials + transport, for reaching each tenant's own database. */
+  control: D1ControlConfig;
+  /** The dedicated interaction AE dataset. Absent ⇒ rollup is skipped, prune
+   *  still runs (never block retention on an unavailable aggregates sink). */
+  analytics?: AnalyticsEngineLike;
+  /** ISO-8601 "now" — injected so the sweep is deterministic under test. */
+  now: string;
+  retentionDays?: number;
+  batchSize?: number;
+  /** Absolute byte threshold for the ceiling warning; defaults to 80% of
+   *  `D1_SIZE_CEILING_BYTES`. */
+  sizeWarningBytes?: number;
+}
+
+export interface TenantPruneOutcome {
+  tenantId: string;
+  prunedRows: number;
+  aggregatesWritten: number;
+  sizeBytes: number | null;
+  /** True when `sizeBytes` is at/above the warning threshold. */
+  sizeWarning: boolean;
+  /** Set only when this tenant's sweep failed; the batch still continues. */
+  error?: string;
+}
+
+export interface PruneSweepResult {
+  tenantsSwept: number;
+  totalPrunedRows: number;
+  totalAggregatesWritten: number;
+  tenants: TenantPruneOutcome[];
+}
+
+/** Map one raw `interaction_events` row (snake_case D1 columns) back to the
+ *  `StampedInteractionEvent` shape `aggregateInteractions()` expects. PURE. */
+export function rawRowToEvent(row: Record<string, unknown>): StampedInteractionEvent {
+  return {
+    type: "click",
+    el: String(row.el ?? ""),
+    action: (row.action as string | null) ?? null,
+    placement: (row.placement as string | null) ?? null,
+    scope: (row.scope as string | null) ?? null,
+    index: (row.idx as number | null) ?? null,
+    ts: String(row.ts ?? ""),
+    correlationId: String(row.correlation_id ?? ""),
+    seq: Number(row.seq ?? 0),
+    tenant_id: String(row.tenant_id ?? ""),
+    stream: "interaction",
+    ingested_at: String(row.ingested_at ?? ""),
+  };
+}
+
+/** The prune work queue: oldest-`last_pruned_at`-first (NULL — never pruned —
+ *  sorts first in SQLite ASC). Never throws. */
+export async function listPruneCandidates(
+  apps: Queryable,
+  batchSize: number,
+): Promise<TenantPruneRow[]> {
+  try {
+    return await apps.all<TenantPruneRow>(
+      `SELECT tenant_id, database_uuid, last_pruned_at
+         FROM tracking_tenant_databases
+        ORDER BY last_pruned_at ASC
+        LIMIT ?`,
+      batchSize,
+    );
+  } catch (err) {
+    console.error(
+      `[tracking:prune] directory read failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return [];
+  }
+}
+
+/** `PRAGMA page_count * page_size` — the current on-disk size of one tenant's
+ *  database. Returns null (never throws) when the pragmas are unavailable. */
+async function readDatabaseSizeBytes(db: Queryable): Promise<number | null> {
+  try {
+    const pageCount = await db.first<{ page_count: number }>("PRAGMA page_count");
+    const pageSize = await db.first<{ page_size: number }>("PRAGMA page_size");
+    if (!pageCount || !pageSize) return null;
+    const count = Number(pageCount.page_count);
+    const size = Number(pageSize.page_size);
+    if (!Number.isFinite(count) || !Number.isFinite(size)) return null;
+    return count * size;
+  } catch {
+    return null;
+  }
+}
+
+/** Prune + roll up ONE tenant's database. Never throws. */
+export async function pruneTenant(
+  row: TenantPruneRow,
+  deps: PruneSweepDeps,
+): Promise<TenantPruneOutcome> {
+  const retentionDays = deps.retentionDays ?? DEFAULT_RETENTION_DAYS;
+  const sizeWarningBytes =
+    deps.sizeWarningBytes ?? Math.floor(D1_SIZE_CEILING_BYTES * DEFAULT_SIZE_WARNING_RATIO);
+  const cutoff = new Date(
+    Date.parse(deps.now) - retentionDays * 24 * 60 * 60 * 1000,
+  ).toISOString();
+
+  try {
+    const db = fromD1Rest(deps.control, row.database_uuid);
+
+    // Read the aging-out rows BEFORE deleting them — the rollup needs them.
+    const aging = await db.all<Record<string, unknown>>(
+      `SELECT tenant_id, stream, type, el, action, placement, scope, idx, correlation_id, seq, ts, ingested_at
+         FROM interaction_events WHERE ingested_at < ?`,
+      cutoff,
+    );
+
+    let aggregatesWritten = 0;
+    if (aging.length > 0) {
+      if (deps.analytics) {
+        const aggregates = aggregateInteractions(aging.map(rawRowToEvent));
+        writeInteractionAnalytics(deps.analytics, aggregates);
+        aggregatesWritten = aggregates.length;
+      }
+      // The DELETE itself never depends on the rollup succeeding — retention
+      // must not stall because the aggregates sink is unavailable.
+      await db.run(`DELETE FROM interaction_events WHERE ingested_at < ?`, cutoff);
+    }
+
+    const sizeBytes = await readDatabaseSizeBytes(db);
+    const sizeWarning = sizeBytes != null && sizeBytes >= sizeWarningBytes;
+    if (sizeWarning) {
+      console.warn(
+        `[tracking:prune] tenant ${row.tenant_id} database at ${sizeBytes} bytes — ` +
+          `approaching the ${D1_SIZE_CEILING_BYTES}-byte D1 per-database ceiling`,
+      );
+    }
+
+    await deps.apps.run(
+      `UPDATE tracking_tenant_databases
+          SET last_pruned_at = ?, pruned_rows = pruned_rows + ?, size_bytes = ?, size_checked_at = ?
+        WHERE tenant_id = ?`,
+      deps.now,
+      aging.length,
+      sizeBytes,
+      deps.now,
+      row.tenant_id,
+    );
+
+    return {
+      tenantId: row.tenant_id,
+      prunedRows: aging.length,
+      aggregatesWritten,
+      sizeBytes,
+      sizeWarning,
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`[tracking:prune] sweep failed for ${row.tenant_id}: ${message}`);
+    return {
+      tenantId: row.tenant_id,
+      prunedRows: 0,
+      aggregatesWritten: 0,
+      sizeBytes: null,
+      sizeWarning: false,
+      error: message,
+    };
+  }
+}
+
+/**
+ * Run one bounded batch of the prune sweep: pull the oldest-pruned tenants
+ * off the work queue and prune+roll-up each in turn. Sequential, not
+ * parallel — keeps one invocation's D1 REST call volume predictable rather
+ * than fanning every tenant in the batch out concurrently.
+ */
+export async function runPruneSweep(deps: PruneSweepDeps): Promise<PruneSweepResult> {
+  const batchSize = deps.batchSize ?? DEFAULT_BATCH_SIZE;
+  const candidates = await listPruneCandidates(deps.apps, batchSize);
+
+  const tenants: TenantPruneOutcome[] = [];
+  for (const row of candidates) {
+    tenants.push(await pruneTenant(row, deps));
+  }
+
+  return {
+    tenantsSwept: tenants.length,
+    totalPrunedRows: tenants.reduce((n, t) => n + t.prunedRows, 0),
+    totalAggregatesWritten: tenants.reduce((n, t) => n + t.aggregatesWritten, 0),
+    tenants,
+  };
+}