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

package/apps/storefront/src/lib/blog/teaser.ts

@@ -0,0 +1,83 @@
+/**
+ * Teaser truncation for gated posts. A members-only post is still a 200 with
+ * partial content (indexable — see the B4.0 spike's SEO note), so an anonymous /
+ * unentitled reader gets the first few blocks of the real body plus a paywall
+ * card, not a hard wall.
+ *
+ * Truncation is by TOP-LEVEL BLOCK COUNT, cutting only on an element boundary so
+ * the returned string is never a partial tag. The blog renderer emits each block
+ * (`<p>`, `<h2>`, `<ul>`, `<blockquote>`, `<pre>`, …) as a top-level sibling, so
+ * "first N blocks" is a clean prefix of the rendered HTML; the boundary scan also
+ * tolerates legacy/migrated `contentHtml` from other sources.
+ */
+
+const VOID_TAGS = new Set([
+  "area", "base", "br", "col", "embed", "hr", "img", "input",
+  "link", "meta", "param", "source", "track", "wbr",
+]);
+
+/** Default teaser length: enough to be a genuine content sample, not the whole story. */
+const DEFAULT_BLOCKS = 3;
+
+/**
+ * The first `blocks` top-level block elements of `contentHtml`. Returns the whole
+ * string when it has fewer than `blocks` top-level elements. Cuts only after a
+ * top-level element closes (or a void/self-closing element), so HTML is never
+ * severed mid-tag.
+ */
+export function teaserHtml(contentHtml: string, blocks: number = DEFAULT_BLOCKS): string {
+  if (blocks <= 0) return "";
+  const n = contentHtml.length;
+  let i = 0;
+  let depth = 0;
+  let topLevel = 0;
+
+  while (i < n) {
+    if (contentHtml[i] !== "<") {
+      i++;
+      continue;
+    }
+    if (contentHtml.startsWith("<!--", i)) {
+      const end = contentHtml.indexOf("-->", i + 4);
+      i = end === -1 ? n : end + 3;
+      continue;
+    }
+    const gt = contentHtml.indexOf(">", i);
+    if (gt === -1) break; // malformed tail — stop rather than emit a partial tag
+    const tag = contentHtml.slice(i, gt + 1);
+    i = gt + 1;
+
+    const closing = tag.startsWith("</");
+    const selfClosing = tag.endsWith("/>");
+    const name = tag.match(/^<\/?\s*([a-zA-Z][a-zA-Z0-9-]*)/)?.[1]?.toLowerCase() ?? "";
+
+    if (closing) {
+      if (depth > 0) depth--;
+      if (depth === 0) {
+        topLevel++;
+        if (topLevel >= blocks) return contentHtml.slice(0, i);
+      }
+    } else if (selfClosing || VOID_TAGS.has(name)) {
+      if (depth === 0) {
+        topLevel++;
+        if (topLevel >= blocks) return contentHtml.slice(0, i);
+      }
+    } else {
+      depth++;
+    }
+  }
+  return contentHtml;
+}
+
+/**
+ * The body HTML to render for an article: full content when the viewer is
+ * entitled (or the post is ungated), a teaser otherwise. The single place the
+ * gate/teaser branch lives, so the public/full-content path stays provably
+ * unchanged — `articleBodyHtml(html, { gated: false, ... }) === html`.
+ */
+export function articleBodyHtml(
+  contentHtml: string,
+  opts: { gated: boolean; unlock: boolean },
+): string {
+  return opts.gated && !opts.unlock ? teaserHtml(contentHtml) : contentHtml;
+}

package/apps/storefront/src/lib/blog/types.ts

@@ -5,6 +5,16 @@ export interface BlogImage {
   height?: number;
 }
 
+export type PostStatus = "draft" | "published" | "unlisted" | "scheduled"; // "scheduled" added in B3.1
+
+/**
+ * Per-post entitlement gate — who may read the body. Orthogonal to `PostStatus`
+ * (which answers "is this published to the live site"): a post has both. Checked
+ * at render time via `viewerHasBlogAccess`, never folded into `isVisibleOnLive`.
+ * Room for future `"tier:<id>"` / `"assurance:<acr>"`; only these three today.
+ */
+export type BlogAccess = "public" | "authenticated" | "members";
+
 export interface BlogPostSummary {
   source: { platform: "wordpress"; id: string };
   slug: string;
@@ -18,9 +28,33 @@ export interface BlogPostSummary {
   categories: string[];
   tags: string[];
   featuredImage?: BlogImage;
+  status: PostStatus; // seeded/legacy posts without this field default to "published"
+  scheduledAt?: string; // ISO date; when status === "scheduled", the post goes live once this instant has passed (B3.1)
+  canonicalUrl?: string; // syndication override (B1.6)
+  inLanguage?: string; // default "en" (B1.6)
+  access?: BlogAccess; // entitlement gate; default "public". Orthogonal to `status` (B4.0)
+  translationGroupId?: string; // stable id shared by every language variant of one article; absent = singleton (I1)
 }
 
 export interface BlogPost extends BlogPostSummary {
   oldSlugs: string[];
   contentHtml: string;
+  // Markdown source for the admin editor (B3.4). When present, `contentHtml` is
+  // its rendered output; migrated/legacy posts may carry only `contentHtml`.
+  bodyMarkdown?: string;
+}
+
+/**
+ * Optional per-tenant × per-collection author bios, keyed by the author's slug
+ * (see `authorSlug`). Sourced from `tenants/<id>/content/<collection>/authors.json`;
+ * absent file or missing key falls back to just the byline name.
+ */
+export interface AuthorBio {
+  name: string;
+  bio?: string;
+  title?: string; // role/title, e.g. "Founder"
+  avatar?: string; // image path (site-relative or absolute)
+  url?: string; // personal/site URL
+  sameAs?: string[]; // social profile URLs — E-E-A-T signal (feeds Person.sameAs, B1.6)
+  twitter?: string; // handle, e.g. "@ada" (feeds twitter:creator, B1.6)
 }

package/apps/storefront/src/lib/blog/viewCounts.ts

@@ -0,0 +1,243 @@
+/**
+ * Per-post view counts: the "first demand signal" for the blog platform.
+ *
+ * Rides the EXISTING RUM beacon (`api/rum/vitals.ts`) rather than adding a new
+ * ingestion path. Each page load emits exactly one CLS field-vitals sample (LCP
+ * and INP are conditional), so the beacon handler treats that CLS sample as the
+ * one-per-view signal and increments counters when it lands on a blog-post URL.
+ * All counts are keyed by (tenant, collection, slug) — no PII, no per-visitor
+ * identity.
+ *
+ * Two counters per view, written together:
+ *   - a rolling LIFETIME total (`blogViewsKey`), unbounded; and
+ *   - a per-UTC-day BUCKET (`blogViewsDayKey`, TTL-expiring) that powers the
+ *     time-series sparkline and the "views over last N days" top-posts ranking.
+ * The day buckets are additive to the lifetime total, not a replacement.
+ *
+ * Storage is the TENANT_CACHE KV namespace — the same binding the newsletter stub
+ * writes to and the only durable store bound on the live `preview` worker. The
+ * increment is a read-modify-write, so under concurrency some increments can be
+ * lost to KV's last-write-wins semantics: acceptable for a rough demand signal,
+ * not a billing counter.
+ *
+ * Tenant/collection-generic by construction — nothing here is bound to
+ * `the-build` or `tokenoftrust.com`.
+ */
+import { getPost, listPosts } from "./collection.js";
+
+// Mirror the engine's guards (collection.ts): a collection is one path segment;
+// a slug is lower-kebab. Keeping them local avoids widening the engine's surface.
+const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+const SEGMENT_RE = /^[a-z0-9][a-z0-9._-]*$/;
+
+// Daily buckets auto-expire this many days after their last write. Comfortably
+// past the widest window the dashboard reads (30d), so a "last N days" query
+// never asks for a key that should still exist but was reaped.
+const DAY_BUCKET_TTL_DAYS = 45;
+const DAY_MS = 86_400_000;
+
+/** KV key for one post's rolling lifetime view count. */
+export function blogViewsKey(tenantId: string, collection: string, slug: string): string {
+  return `blogviews:${tenantId}:${collection}:${slug}`;
+}
+
+/** `yyyy-mm-dd` (UTC) stamp for a Date — the day-bucket suffix. */
+export function dayStamp(date: Date): string {
+  return date.toISOString().slice(0, 10);
+}
+
+/**
+ * KV key for one post's views on ONE UTC day. Distinct from `blogViewsKey` by
+ * the trailing `:<yyyy-mm-dd>` segment, so the lifetime counter and the daily
+ * buckets never collide.
+ */
+export function blogViewsDayKey(
+  tenantId: string,
+  collection: string,
+  slug: string,
+  day: string,
+): string {
+  return `${blogViewsKey(tenantId, collection, slug)}:${day}`;
+}
+
+/**
+ * Parse a request pathname into a candidate (collection, slug) post ref, or null
+ * if it is not shaped like a post URL. A post lives at `<base>/<slug>/`, so the
+ * LAST two non-empty path segments are the candidate collection + slug. Taking
+ * the last two (not the first) naturally ignores any `/<domain>` basePath prefix
+ * (DNS-free preview routing) and rejects listing/section pages (`/the-build/`,
+ * `/the-build/category/x/`, `/the-build/author/x/`) and file routes
+ * (`/the-build/rss.xml`, whose slug fails `SLUG_RE`) — those either fail the
+ * guards or resolve to no post. This is only a SHAPE guard; the caller confirms
+ * the post actually exists and is live via `getPost`.
+ */
+export function parseBlogPostPath(path: string): { collection: string; slug: string } | null {
+  const segs = path.split("/").filter(Boolean);
+  if (segs.length < 2) return null;
+  const slug = segs[segs.length - 1]!;
+  const collection = segs[segs.length - 2]!;
+  if (!SEGMENT_RE.test(collection) || !SLUG_RE.test(slug)) return null;
+  return { collection, slug };
+}
+
+async function readCount(kv: KVNamespace, key: string): Promise<number> {
+  const raw = await kv.get(key);
+  const n = raw == null ? 0 : Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n >= 0 ? n : 0;
+}
+
+/**
+ * Increment the view counter for a post IF the pathname resolves to a live
+ * (published or unlisted) post for this tenant. Drafts, 404s, and non-blog paths
+ * are ignored — `getPost` returns null on the live path for anything not visible.
+ * Best-effort: never throws (a telemetry beacon must never fail the request).
+ */
+export async function recordBlogView(
+  kv: KVNamespace,
+  tenantId: string,
+  path: string,
+): Promise<void> {
+  try {
+    const ref = parseBlogPostPath(path);
+    if (!ref) return;
+    const post = await getPost(tenantId, ref.collection, ref.slug);
+    if (!post) return; // not a live post (draft / 404 / non-blog) — do not count
+    const key = blogViewsKey(tenantId, ref.collection, ref.slug);
+    const dayKey = blogViewsDayKey(tenantId, ref.collection, ref.slug, dayStamp(new Date()));
+    const [lifetime, today] = await Promise.all([readCount(kv, key), readCount(kv, dayKey)]);
+    await Promise.all([
+      // Rolling lifetime counter — unbounded.
+      kv.put(key, String(lifetime + 1)),
+      // Additive daily bucket for the time-series/top-posts dashboard. TTL keeps
+      // the day-bucket keyspace bounded (a day is only ever written on that day,
+      // so it expires ~45d after it stops receiving writes).
+      kv.put(dayKey, String(today + 1), { expirationTtl: (DAY_BUCKET_TTL_DAYS * DAY_MS) / 1000 }),
+    ]);
+  } catch {
+    /* swallow — view counting is best-effort telemetry */
+  }
+}
+
+/**
+ * READER for the future admin "Blog" tab (B2.1, not yet in this base branch).
+ * The tab is server-rendered with `Astro.locals.tenant` and can obtain the KV via
+ * `readKv("TENANT_CACHE")`, so it calls this directly with the slugs from
+ * `listPosts(tenantId, collection, { includeUnpublished: true })` to render a
+ * "Views" column. Returns a slug -> count map (missing keys read as 0); a null KV
+ * (local dev, no binding) yields all-zero counts.
+ */
+export async function getBlogViewCounts(
+  kv: KVNamespace | undefined,
+  tenantId: string,
+  collection: string,
+  slugs: readonly string[],
+): Promise<Record<string, number>> {
+  const out: Record<string, number> = {};
+  for (const slug of slugs) out[slug] = 0;
+  if (!kv) return out;
+  await Promise.all(
+    slugs.map(async (slug) => {
+      out[slug] = await readCount(kv, blogViewsKey(tenantId, collection, slug));
+    }),
+  );
+  return out;
+}
+
+/** The UTC day stamps for the last `days` days, oldest first (today is last). */
+export function recentDayStamps(days: number, now: Date = new Date()): string[] {
+  const n = Math.max(1, Math.floor(days));
+  const end = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+  const out: string[] = [];
+  for (let i = n - 1; i >= 0; i--) out.push(dayStamp(new Date(end - i * DAY_MS)));
+  return out;
+}
+
+/** One day of a post's view series. */
+export interface DailyViews {
+  day: string;
+  views: number;
+}
+
+/**
+ * Per-day view series for one post over the last `days` days (oldest first),
+ * for a sparkline/trend. Missing days read as 0; a null KV yields an all-zero
+ * series of the right length.
+ */
+export async function getPostViewSeries(
+  kv: KVNamespace | undefined,
+  tenantId: string,
+  collection: string,
+  slug: string,
+  days: number,
+  now: Date = new Date(),
+): Promise<DailyViews[]> {
+  const stamps = recentDayStamps(days, now);
+  if (!kv) return stamps.map((day) => ({ day, views: 0 }));
+  return Promise.all(
+    stamps.map(async (day) => ({
+      day,
+      views: await readCount(kv, blogViewsDayKey(tenantId, collection, slug, day)),
+    })),
+  );
+}
+
+/** One ranked row in the top-posts dashboard. */
+export interface TopPost {
+  collection: string;
+  slug: string;
+  title: string;
+  status: string;
+  /** Views within the window (`sinceDays`), or lifetime when no window given. */
+  views: number;
+  /** Lifetime total, always populated. */
+  lifetime: number;
+  /** Per-day series over the window, oldest first — omitted when unwindowed. */
+  series?: DailyViews[];
+}
+
+/**
+ * Rank a collection's posts by view count, most-viewed first.
+ *
+ * KV has no cross-key aggregation, so we take the simplest correct approach:
+ * enumerate the known posts via `listPosts` and read each one's counter(s). At
+ * blog scale (tens of posts) this is a bounded fan-out of parallel KV gets, not
+ * a scan — fine for an admin-tab render, and it needs no write-time index to
+ * keep in sync. `opts.sinceDays` ranks by a windowed sum of the daily buckets
+ * (and returns the series for a sparkline); without it, ranking is by lifetime.
+ */
+export async function getTopPosts(
+  kv: KVNamespace | undefined,
+  tenantId: string,
+  collection: string,
+  opts?: { limit?: number; sinceDays?: number; now?: Date },
+): Promise<TopPost[]> {
+  const posts = await listPosts(tenantId, collection, { includeUnpublished: true });
+  const now = opts?.now ?? new Date();
+  const rows = await Promise.all(
+    posts.map(async (post) => {
+      const lifetime = kv ? await readCount(kv, blogViewsKey(tenantId, collection, post.slug)) : 0;
+      if (opts?.sinceDays == null) {
+        return {
+          collection,
+          slug: post.slug,
+          title: post.title,
+          status: post.status,
+          views: lifetime,
+          lifetime,
+        } satisfies TopPost;
+      }
+      const series = await getPostViewSeries(
+        kv,
+        tenantId,
+        collection,
+        post.slug,
+        opts.sinceDays,
+        now,
+      );
+      const views = series.reduce((sum, d) => sum + d.views, 0);
+      return { collection, slug: post.slug, title: post.title, status: post.status, views, lifetime, series } satisfies TopPost;
+    }),
+  );
+  rows.sort((a, b) => b.views - a.views || b.lifetime - a.lifetime);
+  return opts?.limit != null ? rows.slice(0, Math.max(0, opts.limit)) : rows;
+}

package/apps/storefront/src/lib/d1/catalog.ts

@@ -1,5 +1,5 @@
 /**
- * D1 catalog read-model queries (the one-store target — epics/edge-read-replica.md).
+ * D1 catalog read-model queries (the one-store target).
  *
  * Queries run against a small `Queryable` seam so the SAME code serves D1 in the
  * Worker (via `fromD1`) and an in-memory `node:sqlite` in tests. Covers FTS5
@@ -154,7 +154,7 @@ export async function getProductByHandle(
 }
 
 /**
- * All active-status products, full data. No pagination — the D3 inventory
+ * All active-status products, full data. No pagination — the inventory
  * projection (`api/apps/v1/inventory.ts`) reads the whole active catalog to
  * build its per-SKU list, mirroring `searchProducts`'s active-only scoping.
  */

package/apps/storefront/src/lib/d1/schema-apps.ts

@@ -1,9 +1,8 @@
 /**
  * Drizzle schema — the source of truth for `STOREFRONT_APPS_DB` *migration
- * generation* (ADR-0002). Split out of `schema.ts` (which now covers only the
- * catalog + customization tables on `CATALOG_DB`): these tables are the
- * storefront-apps registry/webhooks/orders spine and belong to a DEDICATED
- * D1, never the catalog.
+ * generation*. `schema.ts` covers the catalog + customization tables on
+ * `CATALOG_DB`; these tables are the storefront-apps registry/webhooks/orders
+ * spine and belong to a DEDICATED D1, never the catalog.
  *
  * `drizzle-kit generate --config drizzle.config.apps.ts` diffs this into
  * numbered SQL under `migrations-apps/`, applied by `wrangler d1 migrations
@@ -11,8 +10,8 @@
  */
 import { sqliteTable, text, integer, real, index, uniqueIndex, primaryKey } from "drizzle-orm/sqlite-core";
 
-// --- Private Apps registry (PrivateApps epic, D2) ----------------------------
-// One install per (app, tenant, env). `installId` is the future JWT `sub`.
+// --- Private Apps registry --------------------------------------------------
+// One install per (app, tenant, env). `installId` is the JWT `sub`.
 // Append-only `app_audit_log` is never pruned by the service layer.
 export const appInstalls = sqliteTable(
   "app_installs",
@@ -71,7 +70,61 @@ export const appAuditLog = sqliteTable(
   }),
 );
 
-// --- Webhook event spine (PrivateApps epic, D4 Chunk A) ---------------------
+// --- Operational activity timeline ------------------------------------------
+// The low-volume / high-value LIFECYCLE cohort of the actor×action telemetry
+// spine (DECISIONS.md §8). Only actions whose catalog `spec.sinks` include
+// "timeline" land here; the high-volume cohort goes to Cloudflare Analytics
+// Engine (binding `ACTIVITY_ANALYTICS`), and EVERY action also goes to Workers
+// Logs. Reuses the EXISTING STOREFRONT_APPS_DB (precedent: `app_audit_log`
+// above) rather than a new binding — the cohort is small (~50k rows/month at
+// 10× pilot) and the timeline query UI needs point queries + joins + arbitrary
+// retention that Analytics Engine cannot give.
+//
+// `id` is the emitter-minted event UUID and the PRIMARY KEY, so a retried/
+// replayed ingest is idempotent (INSERT OR IGNORE). `tenant_id` is written from
+// the AUTHENTICATED ingest identity, never the client-supplied `scope.tenantId`
+// (see api/activity.ts) — that is the multi-tenant isolation boundary. `payload`
+// is the SERVER-redacted JSON (default-deny allowlist + canary scan re-applied
+// at ingest, never trusting client-side redaction alone). The core columns
+// mirror the `ActivityEvent` envelope's non-payload zone (packages/public-
+// runtime/src/activity/event.ts), flattened for SQL point queries.
+export const activityEvents = sqliteTable(
+  "activity_events",
+  {
+    id: text("id").primaryKey(),
+    tenantId: text("tenant_id").notNull(),
+    action: text("action").notNull(),
+    actorKind: text("actor_kind").notNull(),
+    // Opaque, pseudonymized actor id — NEVER raw email/PII (emitter's contract).
+    actorId: text("actor_id").notNull(),
+    actorRef: text("actor_ref"),
+    source: text("source").notNull(),
+    status: text("status").notNull(),
+    // Low-cardinality error CLASS, never a raw exception message.
+    errorClass: text("error_class"),
+    durationMs: integer("duration_ms"),
+    changeId: text("change_id"),
+    traceId: text("trace_id"),
+    // Server-redacted payload JSON (args + rendered lanes), default "{}".
+    payload: text("payload").notNull().default("{}"),
+    // Envelope contract version (ACTIVITY_SCHEMA_VERSION) so a reader can migrate.
+    schemaVersion: integer("schema_version").notNull(),
+    // Emit-clock ISO-8601 (the event's `at`).
+    at: text("at").notNull(),
+    // Server receive-clock ISO-8601 (when ingest stored it).
+    ingestedAt: text("ingested_at").notNull(),
+  },
+  (t) => ({
+    // The timeline query: a tenant's events newest-first.
+    idxActivityTenantAt: index("idx_activity_tenant_at").on(t.tenantId, t.at),
+    // Filter a tenant's timeline by action family (dashboards glob the prefix).
+    idxActivityTenantAction: index("idx_activity_tenant_action").on(t.tenantId, t.action),
+    // Join a change's whole lifecycle span across actions.
+    idxActivityChange: index("idx_activity_change").on(t.changeId),
+  }),
+);
+
+// --- Webhook event spine ----------------------------------------------------
 // Immutable event log. `id` is the semantic event id we mint — distinct from
 // any per-delivery wire envelope id (see `webhookDeliveries.deliveryId` below).
 export const webhookEvents = sqliteTable("webhook_events", {
@@ -141,10 +194,10 @@ export const webhookInstallHealth = sqliteTable("webhook_install_health", {
   updatedAt: text("updated_at").notNull(),
 });
 
-// --- Order ingestion (PrivateApps epic, D6 Chunk A) --------------------------
+// --- Order ingestion --------------------------------------------------------
 // The read-model `ordersStore.ts` diffs incoming Foxy orders against (created
-// → fulfilled transitions, for a later chunk's event emission) and that the
-// attribution route (also later) reads from for its cross-tenant ownership
+// → fulfilled transitions, for event emission) and that the
+// attribution route reads from for its cross-tenant ownership
 // check. `(tenantId, externalOrderId)` is the composite PK — same "no
 // synthetic id, the natural key IS the key" style as `customizationVersions`
 // (schema.ts) — no SQL FK to `appAttributions.orderId` (repo convention — code-only).
@@ -171,7 +224,7 @@ export const orders = sqliteTable(
   }),
 );
 
-// First idempotency ledger in the codebase (D6 Chunk A) — keyed per
+// The idempotency ledger — keyed per
 // `(installId, idempotencyKey)` so a retried write (e.g. attribution POST)
 // replays the stored `responseBody` instead of re-applying the mutation.
 // `bodyHash` (sha256 of the canonical request body) lets a caller re-sending
@@ -188,9 +241,38 @@ export const idempotencyKeys = sqliteTable(
   (t) => ({ pk: primaryKey({ columns: [t.installId, t.idempotencyKey] }) }),
 );
 
-// App-owned attribution/commission records (`attribution:write`, D6 — later
-// chunk owns the route). `orderId` references `orders.externalOrderId` in code
-// only (no SQL FK, repo convention); the route chunk enforces the cross-tenant
+// --- Encrypted outbound social OAuth tokens ---------------------------------
+// The ONLY retrievable secret store in this codebase: per-`(tenant, network)`
+// OAuth access/refresh tokens we must REPLAY to X/LinkedIn, so — unlike the
+// one-way-hashed `app_credentials` above — they are stored ENCRYPTED-AT-REST,
+// not hashed. `ciphertext` is AES-GCM(base64) over the JSON token payload and
+// `iv` its per-write 96-bit nonce (base64); the key-encryption-key (KEK) is a
+// Worker env binding (`SOCIAL_TOKEN_KEK`), NEVER a column here — mirroring how
+// every other real secret in this codebase is an env binding, not row data.
+// Composite PK `(tenant_id, network)` is the natural key (same "the natural key
+// IS the key" style as `orders`); a rotate is an INSERT OR REPLACE overwrite.
+// `expires_at` is the token's own OAuth expiry (nullable — long-lived manual
+// creds have none), distinct from the row's `updated_at` bookkeeping clock.
+export const socialTokens = sqliteTable(
+  "social_tokens",
+  {
+    tenantId: text("tenant_id").notNull(),
+    network: text("network").notNull(),
+    ciphertext: text("ciphertext").notNull(),
+    iv: text("iv").notNull(),
+    expiresAt: text("expires_at"),
+    createdAt: text("created_at").notNull(),
+    updatedAt: text("updated_at").notNull(),
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.tenantId, t.network] }),
+    idxSocialTokensTenant: index("idx_social_tokens_tenant").on(t.tenantId),
+  }),
+);
+
+// App-owned attribution/commission records (`attribution:write`). `orderId`
+// references `orders.externalOrderId` in code
+// only (no SQL FK, repo convention); the route enforces the cross-tenant
 // ownership check the contract requires before ever writing a row here.
 export const appAttributions = sqliteTable(
   "app_attributions",
@@ -211,3 +293,54 @@ export const appAttributions = sqliteTable(
     idxAppAttributionsTenantOrder: index("idx_app_attributions_tenant_order").on(t.tenantId, t.orderId),
   }),
 );
+
+// --- Newsletter subscribers -------------------------------------------------
+// First-party audience for the blog/newsletter digest, kept in OUR D1 (not a
+// vendor list) so the per-tenant isolation + GDPR data-control invariants stay
+// under our control.
+// `tenantId` is the isolation boundary, written from the resolved host/session
+// — NEVER a client body. Keyed on `(tenant_id, collection, email)` so a tenant
+// with multiple collections (e.g. `blog` + `the-build`) runs independent lists.
+// `token` is an opaque random used for both confirm + one-click unsubscribe
+// links; `consentIpHash` is sha256(ip+salt) — never a raw IP (PII). Timestamps
+// are ISO-8601 text. `status`: pending | confirmed | unsubscribed | bounced.
+export const newsletterSubscribers = sqliteTable(
+  "newsletter_subscribers",
+  {
+    tenantId: text("tenant_id").notNull(),
+    collection: text("collection").notNull(),
+    email: text("email").notNull(),
+    status: text("status").notNull().default("pending"),
+    token: text("token").notNull(),
+    consentSource: text("consent_source"),
+    consentIpHash: text("consent_ip_hash"),
+    subscribedAt: text("subscribed_at").notNull(),
+    confirmedAt: text("confirmed_at"),
+    unsubscribedAt: text("unsubscribed_at"),
+    lastSentAt: text("last_sent_at"),
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.tenantId, t.collection, t.email] }),
+    idxNewsletterTenantCollStatus: index("idx_newsletter_tenant_coll_status").on(
+      t.tenantId,
+      t.collection,
+      t.status,
+    ),
+  }),
+);
+
+// Idempotent per-digest send log so a re-triggered digest can't double-send.
+// Keyed on `(tenant_id, collection, digest_id)` (e.g. `the-build-2026-W34`);
+// `postSlugs` is a JSON array of the slugs included in that digest.
+export const newsletterSends = sqliteTable(
+  "newsletter_sends",
+  {
+    tenantId: text("tenant_id").notNull(),
+    collection: text("collection").notNull(),
+    digestId: text("digest_id").notNull(),
+    postSlugs: text("post_slugs").notNull().default("[]"),
+    recipientCount: integer("recipient_count").notNull().default(0),
+    sentAt: text("sent_at").notNull(),
+  },
+  (t) => ({ pk: primaryKey({ columns: [t.tenantId, t.collection, t.digestId] }) }),
+);

package/apps/storefront/src/lib/dev/activityIngestToken.ts

@@ -1,8 +1,7 @@
 /**
  * Opaque, SESSION-KV-backed credential that lets a developer's LOCAL dev-loop
  * process authenticate POST /api/dev/activity on the hosted Worker — the
- * local→hosted activity bridge (handoff
- * 2026-07-14-hosted-dev-activity-bridge-and-stepper).
+ * local→hosted activity bridge.
  *
  * Minted alongside the existing cli-signin-code paste
  * (apps/storefront/src/lib/dev/cliSignInCode.ts) and cached by the CLI in
@@ -30,8 +29,7 @@ export interface ActivityIngestClaims {
    * sign-in code was issued (see api/dev/cli-signin-code.ts). It rides in the
    * claims so every runtime/activity write the local loop makes with this token
    * is stampable with the same id — support looks a live session up by it.
-   * Optional so tokens minted before this field existed still verify (they just
-   * carry no trace); every freshly-minted token sets it.
+   * Optional: a token without it carries no trace; every freshly-minted token sets it.
    */
   traceId?: string;
 }

package/apps/storefront/src/lib/dev/activityStore.ts

@@ -1,9 +1,8 @@
 /**
  * Per-vendor "recent activity" feed for the hosted /dev panel — a small ring
  * buffer of file-save events reported by a developer's LOCAL dev loop (see
- * activityIngestToken.ts for the write-path auth). File-level only, per
- * decision (no per-line diff, no separate published-history tier — see
- * handoff 2026-07-14-hosted-dev-activity-bridge-and-stepper).
+ * activityIngestToken.ts for the write-path auth). File-level only: no
+ * per-line diff, no separate published-history tier.
  */
 
 export type ActivityEventKind = "change" | "add" | "unlink" | "up";
@@ -62,8 +61,7 @@ export async function clearActivity(kv: KVNamespace, appDomain: string): Promise
 
 /**
  * Business-readable translation of a reported file path + event, for the
- * activity log. File-level only — no per-line diff enrichment (Darrin,
- * 2026-07-14: "we can show that in step 2").
+ * activity log. File-level only — no per-line diff enrichment.
  */
 export function describeActivity(file: string | undefined, event: ActivityEventKind): string {
   if (event === "up") return "Your store is running locally";

package/apps/storefront/src/lib/dev/apiBase.ts

@@ -3,12 +3,9 @@
  * click-to-source). Local `astro dev` serves these off dev-server-only plugins at
  * `/__tot/*` (dev-plugins/dev-file-browser.mjs, dev-write.mjs, dev-diff.mjs, ...) —
  * paths that don't exist in the deployed Cloudflare Worker. The hosted Worker instead
- * serves the SAME shape off `/api/dev/*` Astro API routes, landing incrementally
+ * serves the SAME shape off `/api/dev/*` Astro API routes
  * (cp-tree, cp-file, cp-write, cp-diff, cp-locate). One dev.astro UI, one resolver.
  *
- * See decision `architecture-environment-aware-cockpit`
- * (workstream tot-lime-cloud-dev-cockpit).
- *
  * `basePath` is the request's tenant prefix ("" host-routed, "/<tenant>" path-routed).
  * The HOSTED routes are tenant-scoped through the middleware's host/path resolution, so
  * a `/<tenant>/cockpit` render must call `/<tenant>/api/dev/*` for `locals.tenant` to be