@tokenoftrust/storefront-runner 2.0.3 → 2.0.5

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,
+  };
+}

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

@@ -0,0 +1,162 @@
+/**
+ * Publish-time `data-tot-el` safety net — the FALLBACK identity path for
+ * content that never flows through git review.
+ *
+ * `dt-id-writeback` (a sibling unit) is the PRIMARY path: a git-time rewriter
+ * that proposes `data-tot-el` for git-tracked tenant content and writes it
+ * back to source as a reviewable diff. This module exists for everything
+ * that bypasses that review — AI-edit drafts materialized into
+ * `dev-draft:` KV (see `DevDraftContentProvider`, lib/storyblok/provider.ts)
+ * and direct KV-published edits (`PublishedContentProvider`'s overlay over
+ * the customization store). Content sourced from `LocalContentProvider`
+ * (build-bundled from git-tracked `tenants/<id>/content/*`) is explicitly
+ * OUT of scope here — it is dt-id-writeback's job, and re-stamping it here
+ * would fight a human-reviewed, permanently-committed id.
+ *
+ * Shares the SAME structural derivation engine
+ * (`@tot/public-runtime`'s tracking-id-derivation.ts) the git-time rewriter
+ * uses, fed from an `HTMLRewriter` element/end-tag callback pair instead of
+ * a `parse5` tree — see the "Feeding it" section of
+ * docs/architecture/interaction-tracking-attribute-contract.md and
+ * dt-id-derivation's handoff note ("keep an ancestor stack across
+ * HTMLRewriter element/end-tag callbacks and derive at the open tag; one
+ * deriver per document").
+ *
+ * NO DOM-TEXT READS: only `element.tagName` and `element.attributes` are
+ * ever read here, matching the payload guardrail
+ * tracking-id-derivation.ts's own module doc documents and tests (a source
+ * sweep + a closed attribute allowlist) — never `element.text`, never a
+ * child's character data.
+ */
+import {
+  createTrackingIdDeriver,
+  isTrackableNode,
+  TRACKING_ATTR_EL,
+  type StructuralNode,
+} from "@tot/public-runtime";
+
+/**
+ * HTML elements with no end tag. Never pushed onto the ancestor stack, and
+ * `onEndTag` is never registered for them — HTMLRewriter would never call a
+ * callback registered on a void element's (nonexistent) end tag.
+ */
+const VOID_TAGS: ReadonlySet<string> = new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr",
+]);
+
+/**
+ * Minimal shape of the Workers `HTMLRewriter` Element handler this module
+ * needs. Deliberately NOT `@cloudflare/workers-types` (not installed in this
+ * repo — see apps/storefront/env.d.ts's own note) — a local, narrow surface
+ * so this file typechecks in both the Workers runtime and plain Node/vitest.
+ */
+interface RewriterElement {
+  tagName: string;
+  attributes: IterableIterator<[string, string]>;
+  /** True for a void element or one written self-closed (`<foo />`) — either
+   * way, no end tag will ever fire for it. */
+  selfClosing?: boolean;
+  setAttribute(name: string, value: string): void;
+  onEndTag(handler: () => void | Promise<void>): void;
+}
+
+interface MinimalHTMLRewriter {
+  on(selector: string, handlers: { element(el: RewriterElement): void }): MinimalHTMLRewriter;
+  transform(response: Response): Response;
+}
+
+type HTMLRewriterCtor = new () => MinimalHTMLRewriter;
+
+function getHtmlRewriterCtor(): HTMLRewriterCtor | null {
+  const ctor = (globalThis as Record<string, unknown>).HTMLRewriter;
+  return typeof ctor === "function" ? (ctor as HTMLRewriterCtor) : null;
+}
+
+/**
+ * True when the Workers `HTMLRewriter` global is available in this runtime.
+ * Absent in plain Node (vitest, `astro check`, a bare `node` script) — every
+ * caller must treat a false return as "pass the content through unchanged",
+ * never throw. Exported so tests can assert the no-op fallback explicitly.
+ */
+export function hasHtmlRewriter(): boolean {
+  return getHtmlRewriterCtor() !== null;
+}
+
+/** Build the closed-allowlist-fed attrs bag HTMLRewriter's Element exposes. */
+function attrsOf(element: RewriterElement): Record<string, string> {
+  const attrs: Record<string, string> = {};
+  for (const [name, value] of element.attributes) attrs[name] = value;
+  return attrs;
+}
+
+/**
+ * Stamp `data-tot-el` onto every trackable element in `html` that doesn't
+ * already declare one — a single streaming pass, ONE deriver for the whole
+ * document (so ids stay unique within it), maintaining an outermost-first
+ * open-tag stack across element/end-tag callbacks the same way a `parse5`
+ * tree walk would.
+ *
+ * An element that already carries `data-tot-el` (confidence: "declared") is
+ * left completely untouched — its value is only `reserve()`-d into this
+ * document's deriver, so a later element in the SAME pass can never propose
+ * a colliding id. There is no pre-scan pass (this repo has no prior art for
+ * one over raw tenant HTML at publish time — see the module doc): a
+ * declared id that appears LATER in the document than an already-derived
+ * proposal is a known, accepted single-pass limitation, no worse than
+ * shipping no identity for this content at all.
+ *
+ * No-op (returns `html` unchanged) when `HTMLRewriter` isn't available in
+ * this runtime.
+ */
+export async function stampTrackingIdsAtPublish(html: string): Promise<string> {
+  const HTMLRewriter = getHtmlRewriterCtor();
+  if (!HTMLRewriter) return html;
+
+  const deriver = createTrackingIdDeriver();
+  // Outermost-first open-tag stack, shared across every element/end-tag
+  // callback for the WHOLE document — one deriver, one stack, per document
+  // (dt-id-derivation's handoff note).
+  const stack: StructuralNode[] = [];
+
+  const rewriter = new HTMLRewriter().on("*", {
+    element(element: RewriterElement) {
+      const tag = element.tagName.toLowerCase();
+      const attrs = attrsOf(element);
+      const node: StructuralNode = { tag, attrs };
+      const existing = attrs[TRACKING_ATTR_EL];
+
+      if (existing && existing.trim().length > 0) {
+        // confidence: "declared" — already identified. Leave it alone; just
+        // reserve it so nothing derived later in this pass can collide.
+        deriver.reserve(existing);
+      } else if (isTrackableNode(node)) {
+        const ancestors = stack.slice();
+        const derived = deriver.derive({ node, ancestors });
+        element.setAttribute(TRACKING_ATTR_EL, derived.el);
+      }
+
+      if (!VOID_TAGS.has(tag) && !element.selfClosing) {
+        stack.push(node);
+        element.onEndTag(() => {
+          stack.pop();
+        });
+      }
+    },
+  });
+
+  const rewritten = rewriter.transform(new Response(html));
+  return await rewritten.text();
+}

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

@@ -0,0 +1,214 @@
+/**
+ * Resolve (and, on first sight, provision) ONE TENANT'S OWN raw-interaction D1
+ * database.
+ *
+ * The isolation claim of `dt-storage-per-tenant-d1` rests on this module: the
+ * ONLY way the write path gets a database handle is `resolveTenantStore()`,
+ * which takes a tenant id and returns a `Queryable` bound to that tenant's
+ * database UUID and nothing else. There is no handle in this codebase that
+ * spans two tenants' raw rows, so a forgotten `WHERE tenant_id = ?` cannot leak
+ * across tenants — the wrong-tenant rows are not in the database being queried.
+ *
+ * THE THREE STEPS, all idempotent and all cached per isolate:
+ *   1. NAME   — derive the database name deterministically from the tenant id
+ *               (`<prefix>-<sanitized tenant>-<8 hex of sha256(tenant)>`). The
+ *               hash suffix is what keeps the mapping injective after
+ *               sanitizing: two distinct tenant ids that sanitize to the same
+ *               slug still get different databases.
+ *   2. DIRECTORY — read `tracking_tenant_databases` in the shared
+ *               STOREFRONT_APPS_DB for an existing `(name, uuid)`. Present ⇒
+ *               done, zero control-plane calls on the hot path.
+ *   3. PROVISION — absent ⇒ find-or-create the D1 database over REST, apply the
+ *               idempotent schema, stamp `interaction_store_meta`, and record
+ *               the mapping in the directory. Concurrent first-beacons race
+ *               benignly: `ensureDatabase` re-resolves by name and the
+ *               directory write is an upsert.
+ *
+ * BEST-EFFORT, NEVER THROWS. Every entry point returns `undefined` when the
+ * store cannot be reached (no REST credentials, no apps-DB directory, a
+ * control-plane error) — "sink unavailable, skip it", the posture
+ * `activity/store.ts` already sets for an unbound sink. A telemetry beacon must
+ * never fail because storage is unconfigured.
+ */
+import { sha256Hex } from "@tot/public-runtime";
+import { readEnv } from "../env.js";
+import type { Queryable } from "../d1/catalog.js";
+import {
+  ensureDatabase,
+  fromD1Rest,
+  type D1ControlConfig,
+} from "./d1Control.js";
+import {
+  INTERACTION_D1_SCHEMA,
+  INTERACTION_SCHEMA_VERSION,
+  interactionMetaUpsert,
+} from "./interactionSchema.js";
+
+/** Fallback name prefix when `TRACKING_D1_NAME_PREFIX` is unset. */
+const DEFAULT_NAME_PREFIX = "tot-storefront-dt";
+
+/** D1 database names are limited; keep the readable slug well inside it. */
+const MAX_SLUG_LEN = 32;
+
+/** A resolved per-tenant store: the tenant it belongs to and its query handle. */
+export interface TenantInteractionStore {
+  tenantId: string;
+  databaseName: string;
+  databaseUuid: string;
+  db: Queryable;
+}
+
+/** One directory row of `tracking_tenant_databases`. */
+export interface TenantDatabaseRecord {
+  tenant_id: string;
+  database_name: string;
+  database_uuid: string;
+  schema_version: number;
+}
+
+/**
+ * Deterministic, injective database name for a tenant. The readable slug is for
+ * humans in the Cloudflare dashboard; the hash suffix is what guarantees two
+ * different tenant ids never collide onto one database even when their slugs do.
+ */
+export async function tenantDatabaseName(tenantId: string, prefix: string): Promise<string> {
+  const slug =
+    tenantId
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, MAX_SLUG_LEN)
+      .replace(/-+$/, "") || "tenant";
+  const digest = (await sha256Hex(tenantId)).slice(0, 8);
+  return `${prefix}-${slug}-${digest}`;
+}
+
+/** The configured name prefix for this environment. */
+export async function trackingNamePrefix(): Promise<string> {
+  return (await readEnv("TRACKING_D1_NAME_PREFIX")) ?? DEFAULT_NAME_PREFIX;
+}
+
+/** Read a tenant's directory row, or null. Never throws. */
+export async function readTenantDatabase(
+  apps: Queryable,
+  tenantId: string,
+): Promise<TenantDatabaseRecord | null> {
+  try {
+    return await apps.first<TenantDatabaseRecord>(
+      `SELECT tenant_id, database_name, database_uuid, schema_version
+         FROM tracking_tenant_databases WHERE tenant_id = ?`,
+      tenantId,
+    );
+  } catch {
+    return null;
+  }
+}
+
+/** Upsert a tenant's directory row. Never throws. */
+export async function recordTenantDatabase(
+  apps: Queryable,
+  record: { tenantId: string; databaseName: string; databaseUuid: string; at: string },
+): Promise<void> {
+  try {
+    await apps.run(
+      `INSERT INTO tracking_tenant_databases
+         (tenant_id, database_name, database_uuid, schema_version, created_at, updated_at, pruned_rows)
+       VALUES (?,?,?,?,?,?,0)
+       ON CONFLICT(tenant_id) DO UPDATE SET
+         database_name = excluded.database_name,
+         database_uuid = excluded.database_uuid,
+         schema_version = excluded.schema_version,
+         updated_at = excluded.updated_at`,
+      record.tenantId,
+      record.databaseName,
+      record.databaseUuid,
+      INTERACTION_SCHEMA_VERSION,
+      record.at,
+      record.at,
+    );
+  } catch (err) {
+    console.error(
+      `[tracking:interaction] directory write failed for ${record.tenantId}: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+}
+
+/** Apply the idempotent per-tenant schema and stamp its meta row. */
+export async function applyInteractionSchema(
+  db: Queryable,
+  tenantId: string,
+  at: string,
+): Promise<void> {
+  await db.exec(INTERACTION_D1_SCHEMA);
+  const meta = interactionMetaUpsert(tenantId, at);
+  await db.run(meta.sql, ...meta.params);
+}
+
+/** Injected seams — so the whole resolution is testable without Cloudflare. */
+export interface ResolveDeps {
+  /** The shared STOREFRONT_APPS_DB handle holding the directory table. */
+  apps: Queryable;
+  /** D1 REST credentials + transport. */
+  control: D1ControlConfig;
+  /** Environment-scoped database-name prefix. */
+  namePrefix: string;
+  /** ISO-8601 "now", for the directory + meta rows. */
+  at: string;
+}
+
+/**
+ * Resolve a tenant's store, provisioning it on first sight. Returns undefined
+ * when the store cannot be reached — never throws.
+ *
+ * A resolved handle is cached per isolate (`storeCache`) so the steady state is
+ * ZERO control-plane and ZERO directory calls per beacon.
+ */
+const storeCache = new Map<string, TenantInteractionStore>();
+
+/** Test seam: drop the per-isolate resolution cache. */
+export function clearTenantStoreCache(): void {
+  storeCache.clear();
+}
+
+export async function resolveTenantStore(
+  tenantId: string,
+  deps: ResolveDeps,
+): Promise<TenantInteractionStore | undefined> {
+  if (!tenantId) return undefined;
+  const cached = storeCache.get(tenantId);
+  if (cached) return cached;
+
+  try {
+    const existing = await readTenantDatabase(deps.apps, tenantId);
+    if (existing && existing.schema_version >= INTERACTION_SCHEMA_VERSION) {
+      const store: TenantInteractionStore = {
+        tenantId,
+        databaseName: existing.database_name,
+        databaseUuid: existing.database_uuid,
+        db: fromD1Rest(deps.control, existing.database_uuid),
+      };
+      storeCache.set(tenantId, store);
+      return store;
+    }
+
+    // First sight for this tenant (or a schema bump): provision.
+    const databaseName = existing?.database_name ?? (await tenantDatabaseName(tenantId, deps.namePrefix));
+    const databaseUuid = existing?.database_uuid ?? (await ensureDatabase(deps.control, databaseName));
+    const db = fromD1Rest(deps.control, databaseUuid);
+    await applyInteractionSchema(db, tenantId, deps.at);
+    await recordTenantDatabase(deps.apps, { tenantId, databaseName, databaseUuid, at: deps.at });
+
+    const store: TenantInteractionStore = { tenantId, databaseName, databaseUuid, db };
+    storeCache.set(tenantId, store);
+    return store;
+  } catch (err) {
+    console.error(
+      `[tracking:interaction] store resolution failed for ${tenantId}: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+    return undefined;
+  }
+}