@tokenoftrust/storefront-runner 1.4.0 → 1.4.2-rc.0

package/apps/storefront/src/lib/activity/query.ts

@@ -0,0 +1,403 @@
+/**
+ * Query surface over the D1 `activity_events` timeline.
+ *
+ * The READ half of the operational-activity spine: given a tenant, return that
+ * tenant's lifecycle activity newest-first for the `/admin` ops timeline UI
+ * ("who shipped/rejected what, when, why — and what happened to my change/
+ * deploy"). PURE over the injected `Queryable` seam (D1 in the Worker, an
+ * in-memory `node:sqlite` in tests), same posture as `lib/d1/catalog.ts` and the
+ * write path (`store.ts`).
+ *
+ * TENANT ISOLATION IS THE INVARIANT. `tenantId` is REQUIRED on every query and is
+ * ALWAYS the first `WHERE` predicate (`tenant_id = ?`, a bound param — never
+ * string-interpolated). There is NO code path that reads `activity_events` without
+ * a tenant equality bound in: a query with a missing/empty tenant THROWS rather
+ * than degrading to a cross-tenant scan. This mirrors the write-side isolation
+ * (ingest writes only the authenticated tenant) for the read side — a colliding
+ * `changeId`/`actorId`/`action` across two tenants can never surface tenant B's
+ * rows to a tenant-A query, because the collision is AND-ed under the tenant
+ * bound, not OR-ed with it. See `query.isolation.test.ts`.
+ *
+ * DESERIALIZATION. The stored `payload` column is the SERVER-redacted JSON
+ * (default-deny allowlist + canary scan already applied at ingest — see
+ * `ingest.ts`/`redaction.ts`); we only parse it back into `{ args, rendered }` for
+ * the UI. We never re-expand or un-redact it; a malformed row degrades to an empty
+ * payload rather than throwing the whole query.
+ *
+ * DEPLOY SKEW (lightweight). The `deploy.version_observed` action is
+ * in the timeline cohort, so its rows are queryable here. `deriveDeploySkew()`
+ * folds those rows into the set of distinct build versions observed for the tenant
+ * and compares them against the build serving THIS query (`workerCommitShort()`),
+ * surfacing "a stale/newer isolate is (or was) live" as a visible signal. The full
+ * alerting logic lives elsewhere — this only makes the data visibly queryable.
+ */
+import {
+  getActionSpec,
+  type ActivityPayload,
+  type ActorKind,
+  type ActivitySource,
+  type ActivityStatus,
+} from "@tot/public-runtime";
+import type { Queryable } from "../d1/catalog.js";
+import { workerCommitShort, UNKNOWN_COMMIT } from "./workerCommit.js";
+
+/** Hard cap on rows returned by one query — the ops timeline is paged/bounded,
+ *  never an unbounded scan. */
+export const MAX_TIMELINE_ROWS = 500;
+/** Default page size when the caller doesn't specify one. */
+export const DEFAULT_TIMELINE_ROWS = 100;
+
+/**
+ * A timeline query. `tenantId` is REQUIRED (the isolation boundary); every other
+ * field is an optional, AND-ed narrowing. Ordering is newest-first by default
+ * (`at desc`) — the natural shape for a "what just happened" operator timeline.
+ */
+export interface ActivityQuery {
+  /** REQUIRED tenant scope. Empty/missing ⇒ the query throws (never a cross-tenant scan). */
+  tenantId: string;
+  /** Exact catalog action key (e.g. "change.ship"). */
+  action?: string;
+  /** Action-family prefix (e.g. "change." → every change.* row). Mutually useful with `action`. */
+  actionPrefix?: string;
+  /** ShipLoop change/candidate id — the "what happened to THIS change" span. */
+  changeId?: string;
+  /** Opaque, pseudonymized actor id (never raw PII). */
+  actorId?: string;
+  /** Actor cohort. */
+  actorKind?: ActorKind;
+  /** Origin surface. */
+  source?: ActivitySource;
+  /** Terminal/interim status. */
+  status?: ActivityStatus;
+  /** Inclusive lower bound on the emit clock `at` (ISO-8601). */
+  since?: string;
+  /** Inclusive upper bound on the emit clock `at` (ISO-8601). */
+  until?: string;
+  /** Page size (clamped to [1, MAX_TIMELINE_ROWS]). */
+  limit?: number;
+  /** Sort direction on `at`. Default "desc" (newest first). */
+  order?: "asc" | "desc";
+}
+
+/** The raw D1 row shape (snake_case columns of `activity_events`). */
+interface ActivityRow {
+  id: string;
+  tenant_id: string;
+  action: string;
+  actor_kind: string;
+  actor_id: string;
+  actor_ref: string | null;
+  source: string;
+  status: string;
+  error_class: string | null;
+  duration_ms: number | null;
+  change_id: string | null;
+  trace_id: string | null;
+  payload: string;
+  schema_version: number;
+  at: string;
+  ingested_at: string;
+}
+
+/** One deserialized timeline row, ready for the ops UI. */
+export interface ActivityTimelineRow {
+  id: string;
+  tenantId: string;
+  action: string;
+  /** One-line human description from the catalog (undefined for an unknown action). */
+  actionDesc?: string;
+  actorKind: string;
+  actorId: string;
+  actorRef?: string;
+  source: string;
+  status: string;
+  errorClass?: string;
+  durationMs?: number;
+  changeId?: string;
+  traceId?: string;
+  /** Redacted payload, parsed back to `{ args, rendered }`. Never un-redacted. */
+  payload: ActivityPayload;
+  schemaVersion: number;
+  at: string;
+  ingestedAt: string;
+}
+
+/** Parse the stored redacted payload JSON back to `{ args, rendered }`, degrading
+ *  a malformed value to an empty payload rather than throwing the query. */
+function parsePayload(raw: string): ActivityPayload {
+  if (!raw || raw === "{}") return {};
+  try {
+    const p = JSON.parse(raw) as unknown;
+    if (!p || typeof p !== "object") return {};
+    const obj = p as Record<string, unknown>;
+    const out: ActivityPayload = {};
+    if (obj.args && typeof obj.args === "object") out.args = obj.args as Record<string, unknown>;
+    if (obj.rendered && typeof obj.rendered === "object") {
+      out.rendered = obj.rendered as Record<string, string>;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+function toTimelineRow(r: ActivityRow): ActivityTimelineRow {
+  const spec = getActionSpec(r.action);
+  return {
+    id: r.id,
+    tenantId: r.tenant_id,
+    action: r.action,
+    ...(spec ? { actionDesc: spec.desc } : {}),
+    actorKind: r.actor_kind,
+    actorId: r.actor_id,
+    ...(r.actor_ref ? { actorRef: r.actor_ref } : {}),
+    source: r.source,
+    status: r.status,
+    ...(r.error_class ? { errorClass: r.error_class } : {}),
+    ...(r.duration_ms != null ? { durationMs: r.duration_ms } : {}),
+    ...(r.change_id ? { changeId: r.change_id } : {}),
+    ...(r.trace_id ? { traceId: r.trace_id } : {}),
+    payload: parsePayload(r.payload),
+    schemaVersion: r.schema_version,
+    at: r.at,
+    ingestedAt: r.ingested_at,
+  };
+}
+
+/** Clamp a requested limit into [1, MAX_TIMELINE_ROWS]. */
+function clampLimit(limit?: number): number {
+  if (limit == null || !Number.isFinite(limit)) return DEFAULT_TIMELINE_ROWS;
+  return Math.min(MAX_TIMELINE_ROWS, Math.max(1, Math.floor(limit)));
+}
+
+/** Escape LIKE metacharacters so an `actionPrefix` is a literal prefix, not a glob. */
+function escapeLike(v: string): string {
+  return v.replace(/[\\%_]/g, (c) => `\\${c}`);
+}
+
+/**
+ * Query a tenant's activity timeline. THROWS when `tenantId` is empty — there is
+ * no unscoped read path. Every optional filter is an AND-ed narrowing bound as a
+ * parameter; `tenant_id = ?` is always present and always first, so no filter
+ * collision can widen the result across tenants.
+ */
+export async function queryActivity(
+  db: Queryable,
+  q: ActivityQuery,
+): Promise<ActivityTimelineRow[]> {
+  if (!q.tenantId || typeof q.tenantId !== "string") {
+    throw new Error("activity query: tenantId is required — every query is tenant-scoped");
+  }
+
+  // tenant_id is ALWAYS the first predicate and ALWAYS a bound param.
+  const where: string[] = ["tenant_id = ?"];
+  const params: unknown[] = [q.tenantId];
+
+  if (q.action) {
+    where.push("action = ?");
+    params.push(q.action);
+  }
+  if (q.actionPrefix) {
+    where.push("action LIKE ? ESCAPE '\\'");
+    params.push(`${escapeLike(q.actionPrefix)}%`);
+  }
+  if (q.changeId) {
+    where.push("change_id = ?");
+    params.push(q.changeId);
+  }
+  if (q.actorId) {
+    where.push("actor_id = ?");
+    params.push(q.actorId);
+  }
+  if (q.actorKind) {
+    where.push("actor_kind = ?");
+    params.push(q.actorKind);
+  }
+  if (q.source) {
+    where.push("source = ?");
+    params.push(q.source);
+  }
+  if (q.status) {
+    where.push("status = ?");
+    params.push(q.status);
+  }
+  if (q.since) {
+    where.push("at >= ?");
+    params.push(q.since);
+  }
+  if (q.until) {
+    where.push("at <= ?");
+    params.push(q.until);
+  }
+
+  const order = q.order === "asc" ? "ASC" : "DESC";
+  const limit = clampLimit(q.limit);
+  // Secondary sort on id keeps ordering deterministic when two events share `at`.
+  const sql = `SELECT * FROM activity_events
+      WHERE ${where.join(" AND ")}
+      ORDER BY at ${order}, id ${order}
+      LIMIT ?`;
+  const rows = await db.all<ActivityRow>(sql, ...params, limit);
+  return rows.map(toTimelineRow);
+}
+
+// ─── Deploy skew ─────────────────────────────────────────────────────────────
+
+/** One distinct build version observed in the tenant's timeline. */
+export interface ObservedVersion {
+  /** Short (7-char) commit, from a `deploy.version_observed` row's payload. */
+  version: string;
+  /** Deploy env/target the observation named (e.g. "preview"), when present. */
+  env?: string;
+  /** Newest `at` this version was observed. */
+  lastObservedAt: string;
+  /** How many observations of this version are in the window. */
+  count: number;
+}
+
+/**
+ * Deploy-skew summary for a tenant. Lightweight and derived, NOT an alert —
+ * alerting lives elsewhere. It answers: what build(s) has this tenant seen serving, and does
+ * the build serving THIS request match the newest one?
+ */
+export interface DeploySkewSummary {
+  /** Short commit of the build serving this query, or null when unknown (vitest/no git). */
+  runningVersion: string | null;
+  /** Distinct observed versions, newest-first. */
+  observedVersions: ObservedVersion[];
+  /** The newest observed build version, or null when none observed. */
+  latestObservedVersion: string | null;
+  /**
+   * True when skew is visible: either more than one distinct build was observed in
+   * the window (a stale isolate lingered), or the running build differs from the
+   * newest observed one. False/needs-nothing when a single version lines up.
+   */
+  skewDetected: boolean;
+}
+
+/**
+ * Fold the tenant's `deploy.version_observed` rows into a deploy-skew summary. Reads
+ * only that action (still tenant-scoped through {@link queryActivity}), so it is
+ * cheap. `runningOverride` lets a test pin the "serving" build; real callers omit it
+ * and it reads the baked-in `__GIT_SHA__` via `workerCommitShort()`.
+ */
+export async function deriveDeploySkew(
+  db: Queryable,
+  tenantId: string,
+  opts: { since?: string; until?: string; limit?: number; runningOverride?: string } = {},
+): Promise<DeploySkewSummary> {
+  const rows = await queryActivity(db, {
+    tenantId,
+    action: "deploy.version_observed",
+    since: opts.since,
+    until: opts.until,
+    limit: opts.limit ?? MAX_TIMELINE_ROWS,
+    order: "desc",
+  });
+
+  const byVersion = new Map<string, ObservedVersion>();
+  for (const r of rows) {
+    const version = typeof r.payload.args?.version === "string" ? (r.payload.args.version as string) : undefined;
+    if (!version) continue; // an "unknown" build omits version (see deployVersion.ts)
+    const env = typeof r.payload.args?.env === "string" ? (r.payload.args.env as string) : undefined;
+    const existing = byVersion.get(version);
+    if (existing) {
+      existing.count += 1;
+      // rows are newest-first, so the first `at` seen is already the latest.
+    } else {
+      byVersion.set(version, { version, ...(env ? { env } : {}), lastObservedAt: r.at, count: 1 });
+    }
+  }
+
+  const observedVersions = [...byVersion.values()].sort((a, b) =>
+    a.lastObservedAt < b.lastObservedAt ? 1 : a.lastObservedAt > b.lastObservedAt ? -1 : 0,
+  );
+  const latestObservedVersion = observedVersions[0]?.version ?? null;
+
+  const running = workerCommitShort(opts.runningOverride);
+  const runningVersion = running === UNKNOWN_COMMIT ? null : running;
+
+  const skewDetected =
+    observedVersions.length > 1 ||
+    (runningVersion != null && latestObservedVersion != null && runningVersion !== latestObservedVersion);
+
+  return { runningVersion, observedVersions, latestObservedVersion, skewDetected };
+}
+
+// ─── URL-param parsing (pure, shared by the page + tests) ────────────────────
+
+/**
+ * Build an {@link ActivityQuery} from a `URLSearchParams` and the REQUIRED,
+ * server-resolved `tenantId`. The tenant is NEVER read from the URL — it is the
+ * caller's authenticated scope — so no query string can widen or redirect the
+ * tenant boundary. Unknown/blank params are simply omitted.
+ */
+export function parseTimelineQuery(params: URLSearchParams, tenantId: string): ActivityQuery {
+  const s = (k: string): string | undefined => {
+    const v = params.get(k);
+    return v && v.trim() ? v.trim() : undefined;
+  };
+  const n = (k: string): number | undefined => {
+    const v = s(k);
+    if (v == null) return undefined;
+    const parsed = Number(v);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  };
+  const order = s("order") === "asc" ? "asc" : "desc";
+  return {
+    tenantId,
+    ...(s("action") ? { action: s("action") } : {}),
+    ...(s("actionPrefix") ? { actionPrefix: s("actionPrefix") } : {}),
+    ...(s("changeId") ? { changeId: s("changeId") } : {}),
+    ...(s("actorId") ? { actorId: s("actorId") } : {}),
+    ...(s("actorKind") ? { actorKind: s("actorKind") as ActorKind } : {}),
+    ...(s("source") ? { source: s("source") as ActivitySource } : {}),
+    ...(s("status") ? { status: s("status") as ActivityStatus } : {}),
+    ...(s("since") ? { since: s("since") } : {}),
+    ...(s("until") ? { until: s("until") } : {}),
+    ...(n("limit") != null ? { limit: n("limit") } : {}),
+    order,
+  };
+}
+
+// ─── TODO — cross-tenant MCP ops query for ToT staff ────────────────────────
+// Deliberately NOT built: storefront has no in-repo MCP tool surface to hook into
+// (the MCP tools live in the external `tot-mcp` repo; this repo only *authenticates*
+// tot-mcp callers via the `x-mcp-service-secret` webhook seam — it exposes no tool
+// server of its own). Standing up that plumbing here would be net-new MCP infra,
+// which the card marks out of scope. When a staff cross-tenant surface is wanted, it
+// should be a SEPARATE, explicitly-audited entry point (its own tenant-omitting
+// query fn + a staff-authz gate) — NOT a relaxation of `queryActivity`'s required
+// tenant bound, which stays the isolation invariant. Every function in this module
+// is deliberately single-tenant.
+
+// ─── Page orchestration (pure over the seam; the .astro just wires locals) ───
+
+/** Everything the `/admin/ops-timeline` view needs, in one tenant-scoped load. */
+export interface OpsTimelineData {
+  rows: ActivityTimelineRow[];
+  deploySkew: DeploySkewSummary;
+  query: ActivityQuery;
+}
+
+/**
+ * Load the ops-timeline view model for a tenant in one call: the filtered rows
+ * plus the deploy-skew summary. Both are tenant-scoped through {@link queryActivity},
+ * so the same isolation guarantee covers the whole page. `runningOverride` is a
+ * test seam for the serving build.
+ */
+export async function loadOpsTimeline(
+  db: Queryable,
+  query: ActivityQuery,
+  opts: { runningOverride?: string } = {},
+): Promise<OpsTimelineData> {
+  const [rows, deploySkew] = await Promise.all([
+    queryActivity(db, query),
+    deriveDeploySkew(db, query.tenantId, {
+      since: query.since,
+      until: query.until,
+      runningOverride: opts.runningOverride,
+    }),
+  ]);
+  return { rows, deploySkew, query };
+}

package/apps/storefront/src/lib/activity/recordActivity.ts

@@ -0,0 +1,101 @@
+/**
+ * Server-side activity emitter — the storefront's entry point onto the
+ * actor×action telemetry contract (`@tot/public-runtime/activity`).
+ *
+ * Every emitter builds through {@link recordActivity}, which runs the SAFE
+ * constructor `createActivityEvent()` so the payload zone is always redacted, and
+ * writes the envelope as one structured JSON line to Workers Logs.
+ *
+ * TRANSPORT — Workers Logs (DECISIONS.md §8, tier 1 "universal"). `console.log` of
+ * the structured envelope, tagged `[activity]`, so `wrangler tail` / CF-dashboard
+ * grep tooling works. `[observability]` is already enabled in
+ * `apps/storefront/wrangler.toml`, so there is nothing to provision. The
+ * analytics/timeline sinks named on each action's `spec.sinks` are the ingest/store
+ * job — this emitter writes to the firehose only.
+ *
+ * BEST-EFFORT + BOUNDED — a logging failure must NEVER throw or block the caller.
+ * Every path is wrapped; a construction/serialize fault degrades to a single
+ * `console.error` and is otherwise swallowed. Returns `void`: callers fire-and-forget.
+ */
+import type { APIContext } from "astro";
+import { createActivityEvent, type CreateActivityEventInput } from "@tot/public-runtime";
+import { isActivityDisabled } from "./killSwitch";
+
+/**
+ * Emit ONE activity event. Takes the SAME input shape as `createActivityEvent()`
+ * (action / actor / source / outcome / scope / payload) so redaction of the payload
+ * zone is guaranteed by construction. Best-effort + never throws.
+ */
+export function recordActivity(input: CreateActivityEventInput): void {
+  // Kill switch: the whole pipeline is a no-op when disabled — fail-open, the
+  // action this describes is unaffected. Covers the UI cohort too (recordUiActivity
+  // wraps this). Sync check so this fire-and-forget path stays synchronous.
+  if (isActivityDisabled()) return;
+  try {
+    const { event } = createActivityEvent(input);
+    console.log(`[activity] ${JSON.stringify(event)}`);
+  } catch (err) {
+    // Swallow-all: telemetry must never break the action it describes. A single
+    // fallback line (best-effort, itself guarded) preserves a breadcrumb.
+    try {
+      console.error(
+        `[activity] failed to record ${String((input as { action?: unknown })?.action)}: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    } catch {
+      /* nothing more we can safely do */
+    }
+  }
+}
+
+/**
+ * Opaque, stable actor id for the CORE (unredacted) zone — NEVER a raw email/name
+ * (see `event.ts` `ActivityActor`: a raw PII id there would defeat the contract).
+ * A salted SHA-256 of the identifier: the SAME input always yields the SAME id (so
+ * one person stays correlatable across events) while being non-reversible.
+ *
+ * The salt is a Worker secret (`ACTIVITY_ACTOR_SALT`). The canonical salt is the
+ * open question flagged in `redaction.ts` — this SERVER-side helper is where
+ * it lands, deliberately NOT baked into the edge-shipped `@tot/public-runtime`
+ * package (which the redaction header warns against). Best-effort: on any crypto fault it
+ * returns a coarse non-PII fallback so an emitter never throws.
+ */
+export async function hashActorId(identifier: string, salt?: string | null): Promise<string> {
+  try {
+    const data = new TextEncoder().encode(`${salt ?? ""}:${identifier}`);
+    const digest = await crypto.subtle.digest("SHA-256", data);
+    const hex = Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("");
+    return `h_${hex.slice(0, 24)}`;
+  } catch {
+    return "actor_unknown";
+  }
+}
+
+/**
+ * The real acting viewer's email for an admitted ship session — distinct from
+ * `auth.owner`, which is the TENANT owner's identity for a ship-on-behalf developer
+ * (a KV/tenant-scoping key, not the actor). Falls back to `auth.owner` only for the
+ * headless Bearer-operator path, where there is no signed-in viewer at all.
+ *
+ * Typed against a minimal `{ owner: string }` (NOT the control-plane `ShipSessionResult`)
+ * so this renderer-shared module never imports the moat — the field is all it reads.
+ * The returned email is PII: callers pass it through {@link hashActorId} for the
+ * event's `actor.id`, never into a core field raw.
+ */
+export function actorEmailFor(context: APIContext, auth: { owner: string }): string {
+  return context.locals?.viewer?.email ?? auth.owner;
+}
+
+/**
+ * Best-effort, deterministic display name from an email — a real name is NOT
+ * captured anywhere in the current session/grant model. A placeholder good enough
+ * to render a UI/log line; capturing the OAuth profile's real name at sign-in and
+ * threading it through the viewer session is the correct long-term fix.
+ */
+export function displayNameFromEmail(email: string): string {
+  const local = email.split("@")[0] ?? email;
+  const words = local.split(/[._-]+/).filter(Boolean);
+  if (words.length === 0) return email;
+  return words.map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}

package/apps/storefront/src/lib/activity/store.ts

@@ -0,0 +1,120 @@
+/**
+ * Sink fan-out for the activity spine — routes ONE redacted
+ * `ActivityEvent` to the sink(s) its catalog entry declares (`spec.sinks`), per
+ * the store decision in DECISIONS.md §8:
+ *
+ *   • "logs"      — Workers Logs firehose, EVERY action. `console.log` of the
+ *                   structured envelope. Zero provision, days-only retention.
+ *   • "analytics" — Cloudflare Analytics Engine (`ACTIVITY_ANALYTICS` binding).
+ *                   High-volume / query-light cohort; aggregate SQL, ~90 days.
+ *   • "timeline"  — D1 `STOREFRONT_APPS_DB.activity_events`. Low-volume / high-
+ *                   value lifecycle cohort; point queries + joins + arbitrary
+ *                   retention for the ops timeline UI.
+ *
+ * PURE over injected seams (a `Queryable` for D1, an `AnalyticsEngineLike` for
+ * Analytics Engine) so the same code serves the real Worker bindings and an
+ * in-memory test. BEST-EFFORT PER SINK: one sink failing (or being unbound) never
+ * blocks the others and never throws to the caller — activity telemetry must
+ * never break the request it describes. The whole fan-out runs OFF the response
+ * critical path via `runAfterResponse` at the call site.
+ */
+import { getActionSpec, type ActivityEvent, type ActivitySink } from "@tot/public-runtime";
+import type { Queryable } from "../d1/catalog.js";
+
+/** The slice of Cloudflare's Analytics Engine dataset binding we use. */
+export interface AnalyticsEngineLike {
+  writeDataPoint(point: { blobs?: (string | null)[]; doubles?: number[]; indexes?: string[] }): void;
+}
+
+export interface ActivitySinks {
+  /** D1 `STOREFRONT_APPS_DB` seam (the "timeline" sink). Absent ⇒ skipped. */
+  db?: Queryable;
+  /** Analytics Engine binding (the "analytics" sink). Absent ⇒ skipped. */
+  analytics?: AnalyticsEngineLike;
+  /** Server receive-clock ISO-8601, stamped once per ingest for the D1 row. */
+  ingestedAt: string;
+}
+
+/** Structured Workers-Logs line — grep-able on the `[activity]` tag. Never throws. */
+export function logActivity(event: ActivityEvent): void {
+  try {
+    console.log(`[activity] ${JSON.stringify(event)}`);
+  } catch {
+    // best-effort only
+  }
+}
+
+/** Map an event onto one Analytics Engine data point. `indexes` holds the tenant
+ *  (the single sampling/filter key AE allows); the core fields go to `blobs`,
+ *  numerics to `doubles`. Never throws. */
+export function writeAnalytics(analytics: AnalyticsEngineLike, event: ActivityEvent): void {
+  try {
+    analytics.writeDataPoint({
+      indexes: [event.scope.tenantId ?? ""],
+      blobs: [
+        event.action,
+        event.actor.kind,
+        event.actor.id,
+        event.source,
+        event.outcome.status,
+        event.outcome.errorClass ?? "",
+        event.scope.changeId ?? "",
+        event.scope.traceId ?? "",
+        event.id,
+        event.at,
+        event.payload ? JSON.stringify(event.payload) : "",
+      ],
+      doubles: [event.v, event.outcome.durationMs ?? 0],
+    });
+  } catch {
+    // best-effort only
+  }
+}
+
+/** Insert one event into the D1 timeline table. `INSERT OR IGNORE` on the event
+ *  `id` primary key makes a retried/replayed ingest idempotent. Never throws. */
+export async function insertTimeline(db: Queryable, event: ActivityEvent, ingestedAt: string): Promise<void> {
+  try {
+    await db.run(
+      `INSERT OR IGNORE INTO activity_events
+         (id, tenant_id, action, actor_kind, actor_id, actor_ref, source, status,
+          error_class, duration_ms, change_id, trace_id, payload, schema_version, at, ingested_at)
+       VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+      event.id,
+      event.scope.tenantId ?? "",
+      event.action,
+      event.actor.kind,
+      event.actor.id,
+      event.actor.ref ?? null,
+      event.source,
+      event.outcome.status,
+      event.outcome.errorClass ?? null,
+      event.outcome.durationMs ?? null,
+      event.scope.changeId ?? null,
+      event.scope.traceId ?? null,
+      event.payload ? JSON.stringify(event.payload) : "{}",
+      event.v,
+      event.at,
+      ingestedAt,
+    );
+  } catch (err) {
+    // best-effort: a D1 write failure is logged (the firehose still has the row)
+    // but never breaks ingest.
+    console.error(`[activity] timeline write failed for ${event.id}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+/** Which sinks this event routes to (from its catalog entry). Unknown action ⇒
+ *  logs-only (deny-by-default: never fan an unrecognized action to a store). */
+export function sinksFor(event: ActivityEvent): readonly ActivitySink[] {
+  return getActionSpec(event.action)?.sinks ?? ["logs"];
+}
+
+/** Fan one redacted event out to every sink its catalog entry declares.
+ *  Best-effort per sink; never throws. */
+export async function fanOutActivity(event: ActivityEvent, sinks: ActivitySinks): Promise<void> {
+  const routes = sinksFor(event);
+  if (routes.includes("logs")) logActivity(event);
+  if (routes.includes("analytics") && sinks.analytics) writeAnalytics(sinks.analytics, event);
+  if (routes.includes("timeline") && sinks.db) await insertTimeline(sinks.db, event, sinks.ingestedAt);
+}