@oimlsmart/platform-server 0.1.2 → 0.1.3

package/migrations/0018_notify_email.sql

@@ -0,0 +1,51 @@
+-- TODO.notify/04 — the email channel's delivery store (migration 0018
+-- in the shared numbering; 0017 is the cones wave's — identity-features
+-- /09). One row per (event, recipient) — the fan-out's record of WHO
+-- the event reached and on WHICH channel mark (TODO.notify/00: "the
+-- delivery lands on the audit/notification store (a notification row
+-- per recipient with the channel marks)"):
+--
+--   reason        the resolution's STRONGEST reason (subscribed /
+--                 assigned / author / actor / role-default) — every
+--                 notification carries its why, the delivery row
+--                 included;
+--   email         the resolved email posture (immediate | digest | off)
+--                 — the channel split's outcome (the inbox is the
+--                 constant, never a column);
+--   email_status  NULL when email = 'off'; else the email leg's state:
+--                 sent | failed | rate_limited for the immediate leg,
+--                 digest_pending → digest_sent | digest_failed for the
+--                 daily rollup, digest_dropped when the event left the
+--                 store before the rollup, 'unavailable' when the
+--                 instance carries NO mailer (the honest degradation:
+--                 nothing queues — a console-posture instance marks the
+--                 row unavailable at event time and the digest never
+--                 accumulates);
+--   email_at      the terminal stamp (the send / the drop), NULL while
+--                 pending.
+--
+-- The rows name the user + the event WITHOUT foreign keys (the
+-- subscriptions store's own posture, migration 0014's: the user's
+-- delivery record is their own, never the workflow's) — the demo reset
+-- and the retention sweep delete events while a delivery row simply
+-- never joins. The UNIQUE (event_id, user_id) makes the fan-out
+-- idempotent (a re-driven event updates, never duplicates). The
+-- mailer's own audit (entity_type 'email') stands alongside — this
+-- table is the PER-RECIPIENT notification record, the audit trail the
+-- per-SEND one. The package's migrations test pins this set's end state
+-- to schema.sql (src/store/sqlite) in lockstep.
+CREATE TABLE IF NOT EXISTS notify_deliveries (
+  id TEXT PRIMARY KEY,
+  event_id TEXT NOT NULL,
+  user_id TEXT NOT NULL,
+  reason TEXT NOT NULL,
+  email TEXT NOT NULL,
+  email_status TEXT,
+  email_at TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  UNIQUE (event_id, user_id)
+);
+CREATE INDEX IF NOT EXISTS idx_notify_deliveries_event ON notify_deliveries (event_id);
+CREATE INDEX IF NOT EXISTS idx_notify_deliveries_user ON notify_deliveries (user_id);
+-- The digest rollup + the retry sweep read by status.
+CREATE INDEX IF NOT EXISTS idx_notify_deliveries_status ON notify_deliveries (email_status);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oimlsmart/platform-server",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "The OIML SMART platform server kernel: the store seam (ServerStore + the D1 and SQLite implementations), the canonical D1 migration set both deployments apply, the instance profile, the mailer, the RBAC map, the OIDC/OAuth client cones, and the shared role/permission vocabulary. Consumed by the smart monorepo (browser/) and the identity service.",
   "type": "module",
   "repository": {

package/src/store/d1.ts

@@ -35,6 +35,8 @@ import {
   type IdentityLink,
   type IdentityProvider,
   type MfaPending,
+  type NotifyDelivery,
+  type NotifyDeliveryStatus,
   type NotifyEntityMute,
   type NotifyInboxState,
   type NotifyPreferences,
@@ -176,8 +178,9 @@ function toAdminRow(user: UserRecord & { last_login?: string | null; provider?:
  *  (none WITHOUT ROWID — schema.sql). The TODO.notify/01 event store
  *  wipes with them — its rows reference the workflow entities a reset
  *  removes (the feed's read-time visibility gate would drop the orphans
- *  anyway; wiping keeps the demo honest). */
-const WIPE_TABLES = ['entity_changes', 'evidence_records', 'entities', 'events', 'instrument_registrations'] as const
+ *  anyway; wiping keeps the demo honest). TODO.notify/04: the delivery
+ *  store wipes alongside (its rows reference the wiped events). */
+const WIPE_TABLES = ['entity_changes', 'evidence_records', 'entities', 'events', 'instrument_registrations', 'notify_deliveries'] as const
 
 export class D1ServerStore implements ServerStore {
   constructor(private readonly db: D1Database) {}
@@ -2823,12 +2826,132 @@ export class D1ServerStore implements ServerStore {
     return D1ServerStore.toNotifyInboxState(row!)
   }
 
+  // ── the email channel's delivery store (TODO.notify/04) ───────────
+  // The SAME statements as sqlite/notify.ts's sync half (D1 is SQLite).
+  // The defensive ensure mirrors the instrument_registrations posture:
+  // a dev D1 migrated from before migration 0018 lacks the table.
+
+  private notifyDeliverySupportEnsured: Promise<void> | null = null
+
+  private ensureNotifyDeliverySupport(): Promise<void> {
+    if (!this.notifyDeliverySupportEnsured) {
+      this.notifyDeliverySupportEnsured = (async () => {
+        await this.db.prepare(
+          `CREATE TABLE IF NOT EXISTS notify_deliveries (
+             id TEXT PRIMARY KEY,
+             event_id TEXT NOT NULL,
+             user_id TEXT NOT NULL,
+             reason TEXT NOT NULL,
+             email TEXT NOT NULL,
+             email_status TEXT,
+             email_at TEXT,
+             created_at TEXT NOT NULL DEFAULT (datetime('now')),
+             UNIQUE (event_id, user_id)
+           )`,
+        ).run()
+        await this.db.prepare('CREATE INDEX IF NOT EXISTS idx_notify_deliveries_event ON notify_deliveries (event_id)').run()
+        await this.db.prepare('CREATE INDEX IF NOT EXISTS idx_notify_deliveries_user ON notify_deliveries (user_id)').run()
+        await this.db.prepare('CREATE INDEX IF NOT EXISTS idx_notify_deliveries_status ON notify_deliveries (email_status)').run()
+      })()
+    }
+    return this.notifyDeliverySupportEnsured
+  }
+
+  private static toNotifyDelivery(row: Record<string, unknown>): NotifyDelivery {
+    return {
+      id: row.id as string,
+      eventId: row.event_id as string,
+      userId: row.user_id as string,
+      reason: row.reason as string,
+      email: row.email as NotifyDelivery['email'],
+      emailStatus: (row.email_status as NotifyDelivery['emailStatus']) ?? null,
+      emailAt: (row.email_at as string | null) ?? null,
+      createdAt: row.created_at as string,
+    }
+  }
+
+  async putNotifyDelivery(input: {
+    id: string
+    eventId: string
+    userId: string
+    reason: string
+    email: NotifyDelivery['email']
+    emailStatus: NotifyDelivery['emailStatus']
+  }): Promise<NotifyDelivery> {
+    await this.ensureNotifyDeliverySupport()
+    await this.stmt(
+      `INSERT INTO notify_deliveries (id, event_id, user_id, reason, email, email_status, email_at)
+       VALUES (?, ?, ?, ?, ?, ?, CASE WHEN ? IS NULL OR ? = 'digest_pending' THEN NULL ELSE datetime('now') END)
+       ON CONFLICT (event_id, user_id) DO UPDATE SET
+         reason = excluded.reason,
+         email = excluded.email`,
+      input.id, input.eventId, input.userId, input.reason, input.email, input.emailStatus, input.emailStatus, input.emailStatus,
+    ).run()
+    const row = await this.stmt(
+      'SELECT * FROM notify_deliveries WHERE event_id = ? AND user_id = ?', input.eventId, input.userId,
+    ).first<Record<string, unknown>>()
+    return D1ServerStore.toNotifyDelivery(row!)
+  }
+
+  async getNotifyDelivery(eventId: string, userId: string): Promise<NotifyDelivery | null> {
+    await this.ensureNotifyDeliverySupport()
+    const row = await this.stmt(
+      'SELECT * FROM notify_deliveries WHERE event_id = ? AND user_id = ?', eventId, userId,
+    ).first<Record<string, unknown>>()
+    return row ? D1ServerStore.toNotifyDelivery(row) : null
+  }
+
+  async listNotifyDeliveriesForEvent(eventId: string): Promise<NotifyDelivery[]> {
+    await this.ensureNotifyDeliverySupport()
+    const res = await this.stmt(
+      'SELECT * FROM notify_deliveries WHERE event_id = ? ORDER BY created_at, id', eventId,
+    ).all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toNotifyDelivery)
+  }
+
+  async notifyDigestPendingUsers(): Promise<string[]> {
+    await this.ensureNotifyDeliverySupport()
+    const res = await this.stmt(
+      "SELECT DISTINCT user_id FROM notify_deliveries WHERE email_status = 'digest_pending' ORDER BY user_id",
+    ).all<{ user_id: string }>()
+    return res.results.map(r => r.user_id)
+  }
+
+  async notifyDigestPendingForUser(userId: string): Promise<NotifyDelivery[]> {
+    await this.ensureNotifyDeliverySupport()
+    const res = await this.stmt(
+      "SELECT * FROM notify_deliveries WHERE user_id = ? AND email_status = 'digest_pending' ORDER BY created_at, id", userId,
+    ).all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toNotifyDelivery)
+  }
+
+  async notifyFailedDeliveries(limit = 100): Promise<NotifyDelivery[]> {
+    await this.ensureNotifyDeliverySupport()
+    const res = await this.stmt(
+      "SELECT * FROM notify_deliveries WHERE email_status = 'failed' ORDER BY created_at, id LIMIT ?", limit,
+    ).all<Record<string, unknown>>()
+    return res.results.map(D1ServerStore.toNotifyDelivery)
+  }
+
+  /** The status mark: the terminal marks stamp email_at; a re-queue to
+   *  'digest_pending' CLEARS it (a pending row carries no stamp). */
+  async markNotifyDelivery(id: string, status: NotifyDeliveryStatus): Promise<void> {
+    await this.ensureNotifyDeliverySupport()
+    if (status === 'digest_pending') {
+      await this.stmt('UPDATE notify_deliveries SET email_status = ?, email_at = NULL WHERE id = ?', status, id).run()
+    } else {
+      await this.stmt("UPDATE notify_deliveries SET email_status = ?, email_at = datetime('now') WHERE id = ?", status, id).run()
+    }
+  }
+
   // ── provisioning / dev support ───────────────────────────────────
 
   async wipeWorkflowStores(range?: { after: number; through: number }): Promise<number> {
     // The register table joins the wipe defensively (a dev D1 migrated
-    // from before migration 0016 lacks it — the ensure posture).
+    // from before migration 0016 lacks it — the ensure posture). The
+    // delivery store (0018) the same.
     await this.ensureInstrumentRegistrationSupport()
+    await this.ensureNotifyDeliverySupport()
     // The wipe's tables in one batch (all-or-nothing, the putEntity
     // pattern). A ranged round charges one bounded statement per table;
     // the range-less form is the direct-call default (small stores,
@@ -2842,12 +2965,14 @@ export class D1ServerStore implements ServerStore {
 
   async workflowStoreRowCeiling(): Promise<number> {
     await this.ensureInstrumentRegistrationSupport()
+    await this.ensureNotifyDeliverySupport()
     const row = await this.stmt(
       `SELECT MAX(ceiling) AS ceiling FROM (
          SELECT MAX(rowid) AS ceiling FROM entity_changes
          UNION ALL SELECT MAX(rowid) FROM evidence_records
          UNION ALL SELECT MAX(rowid) FROM entities
          UNION ALL SELECT MAX(rowid) FROM events
+         UNION ALL SELECT MAX(rowid) FROM notify_deliveries
          UNION ALL SELECT MAX(rowid) FROM instrument_registrations)`,
     ).first<{ ceiling: number | null }>()
     return row?.ceiling ?? 0

package/src/store/sqlite/notify.ts

@@ -16,12 +16,18 @@
 // per-event read/done markers the computed feed joins (one row per
 // (user, event), written lazily at the first act on the row).
 //
+// Plus TODO.notify/04's delivery store: notify_deliveries, one row per
+// (event, recipient) — the email channel's per-recipient record (the
+// reason, the resolved posture, the email leg's state; the digest
+// sweep's queue and the retry sweep's read).
+//
 // The D1 store (../d1.ts) runs the SAME statements against the binding;
 // the d1-store suite's tripwire pins the two schemas in lockstep.
 // ═══════════════════════════════════════════════════════════════════
 
 import { getDb } from './store'
 import type {
+  NotifyDelivery,
   NotifyEntityMute,
   NotifyInboxState,
   NotifyPreferences,
@@ -245,3 +251,104 @@ export function putNotifyInboxState(input: {
       .get(input.userId, input.eventId) as InboxStateRow,
   )
 }
+
+// ── the email channel's delivery store (TODO.notify/04) ──────────────
+
+interface DeliveryRow {
+  id: string
+  event_id: string
+  user_id: string
+  reason: string
+  email: string
+  email_status: string | null
+  email_at: string | null
+  created_at: string
+}
+
+function toNotifyDelivery(row: DeliveryRow): NotifyDelivery {
+  return {
+    id: row.id,
+    eventId: row.event_id,
+    userId: row.user_id,
+    reason: row.reason,
+    email: row.email as NotifyDelivery['email'],
+    emailStatus: row.email_status as NotifyDelivery['emailStatus'],
+    emailAt: row.email_at,
+    createdAt: row.created_at,
+  }
+}
+
+/** The fan-out's write: the upsert on UNIQUE (event_id, user_id). The
+ *  status only ever moves FORWARD through the caller's marks — the
+ *  upsert itself never overwrites a terminal stamp (a re-driven event
+ *  refreshes reason + posture, keeps the email leg's state). An INITIAL
+ *  write carrying a terminal status stamps email_at (pending states —
+ *  NULL and 'digest_pending' — never carry a stamp). */
+export function putNotifyDelivery(input: {
+  id: string
+  eventId: string
+  userId: string
+  reason: string
+  email: NotifyDelivery['email']
+  emailStatus: NotifyDelivery['emailStatus']
+}): NotifyDelivery {
+  const db = getDb()
+  db.prepare(
+    `INSERT INTO notify_deliveries (id, event_id, user_id, reason, email, email_status, email_at)
+     VALUES (?, ?, ?, ?, ?, ?, CASE WHEN ? IS NULL OR ? = 'digest_pending' THEN NULL ELSE datetime('now') END)
+     ON CONFLICT (event_id, user_id) DO UPDATE SET
+       reason = excluded.reason,
+       email = excluded.email`,
+  ).run(input.id, input.eventId, input.userId, input.reason, input.email, input.emailStatus, input.emailStatus, input.emailStatus)
+  return toNotifyDelivery(
+    db.prepare('SELECT * FROM notify_deliveries WHERE event_id = ? AND user_id = ?')
+      .get(input.eventId, input.userId) as DeliveryRow,
+  )
+}
+
+export function getNotifyDelivery(eventId: string, userId: string): NotifyDelivery | null {
+  const row = getDb()
+    .prepare('SELECT * FROM notify_deliveries WHERE event_id = ? AND user_id = ?')
+    .get(eventId, userId) as DeliveryRow | undefined
+  return row ? toNotifyDelivery(row) : null
+}
+
+export function listNotifyDeliveriesForEvent(eventId: string): NotifyDelivery[] {
+  const rows = getDb()
+    .prepare('SELECT * FROM notify_deliveries WHERE event_id = ? ORDER BY created_at, id')
+    .all(eventId) as DeliveryRow[]
+  return rows.map(toNotifyDelivery)
+}
+
+/** The digest sweep's first read: the DISTINCT users holding pending
+ *  rows (one digest message per user per run). */
+export function notifyDigestPendingUsers(): string[] {
+  const rows = getDb()
+    .prepare("SELECT DISTINCT user_id FROM notify_deliveries WHERE email_status = 'digest_pending' ORDER BY user_id")
+    .all() as Array<{ user_id: string }>
+  return rows.map(r => r.user_id)
+}
+
+export function notifyDigestPendingForUser(userId: string): NotifyDelivery[] {
+  const rows = getDb()
+    .prepare("SELECT * FROM notify_deliveries WHERE user_id = ? AND email_status = 'digest_pending' ORDER BY created_at, id")
+    .all(userId) as DeliveryRow[]
+  return rows.map(toNotifyDelivery)
+}
+
+/** The retry sweep's read: the failed immediates, oldest first. */
+export function notifyFailedDeliveries(limit = 100): NotifyDelivery[] {
+  const rows = getDb()
+    .prepare("SELECT * FROM notify_deliveries WHERE email_status = 'failed' ORDER BY created_at, id LIMIT ?")
+    .all(limit) as DeliveryRow[]
+  return rows.map(toNotifyDelivery)
+}
+
+/** The status mark. The terminal marks stamp email_at; a re-queue to
+ *  'digest_pending' CLEARS it (a pending row carries no stamp). */
+export function markNotifyDelivery(id: string, status: NonNullable<NotifyDelivery['emailStatus']>): void {
+  const terminal = status === 'digest_pending' ? null : "datetime('now')"
+  getDb()
+    .prepare(`UPDATE notify_deliveries SET email_status = ?, email_at = ${terminal ?? 'NULL'} WHERE id = ?`)
+    .run(status, id)
+}

package/src/store/sqlite/schema.sql

@@ -220,6 +220,33 @@ CREATE TABLE IF NOT EXISTS notify_inbox_state (
 );
 CREATE INDEX IF NOT EXISTS idx_notify_inbox_state_user ON notify_inbox_state (user_id);
 
+-- TODO.notify/04 — the email channel's delivery store (migration 0018):
+-- one row per (event, recipient), the fan-out's record of who the event
+-- reached and on which channel mark. reason is the resolution's
+-- strongest reason; email the resolved posture (immediate | digest |
+-- off — the inbox is the constant, never a column); email_status the
+-- email leg's state (NULL when off; sent | failed | rate_limited;
+-- digest_pending → digest_sent | digest_failed | digest_dropped;
+-- 'unavailable' on a mailer-less instance — nothing queues there).
+-- NO foreign keys (the subscriptions store's posture): a wiped event
+-- simply never joins. UNIQUE (event_id, user_id) keeps the fan-out
+-- idempotent. The mailer's per-SEND audit (entity_type 'email') stands
+-- alongside — this table is the PER-RECIPIENT record.
+CREATE TABLE IF NOT EXISTS notify_deliveries (
+  id TEXT PRIMARY KEY,
+  event_id TEXT NOT NULL,
+  user_id TEXT NOT NULL,
+  reason TEXT NOT NULL,
+  email TEXT NOT NULL,
+  email_status TEXT,
+  email_at TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  UNIQUE (event_id, user_id)
+);
+CREATE INDEX IF NOT EXISTS idx_notify_deliveries_event ON notify_deliveries (event_id);
+CREATE INDEX IF NOT EXISTS idx_notify_deliveries_user ON notify_deliveries (user_id);
+CREATE INDEX IF NOT EXISTS idx_notify_deliveries_status ON notify_deliveries (email_status);
+
 -- The evidence store (TODO.ops/09 — the monitor daemon's durable
 -- streams): append-only records across restarts. The adapter contract
 -- (src/evidence-store/adapter.ts) is tiny: append, query, getByIds,

package/src/store/sqlite.ts

@@ -96,12 +96,19 @@ import {
 import {
   deleteNotifyEntityMute,
   deleteNotifyRule,
+  getNotifyDelivery,
   getNotifyPreferences,
+  listNotifyDeliveriesForEvent,
   listNotifyEntityMutes,
   listNotifyInboxStates,
   listNotifyRules,
+  markNotifyDelivery,
+  notifyDigestPendingForUser,
+  notifyDigestPendingUsers,
   notifyEntityMutesForEvent,
+  notifyFailedDeliveries,
   notifyRulesForEvent,
+  putNotifyDelivery,
   putNotifyEntityMute,
   putNotifyInboxState,
   putNotifyPreferences,
@@ -165,7 +172,7 @@ import {
   updateOpAccount,
   updateUserName,
 } from './sqlite/op-accounts-store'
-import { installStore, type AuthUserPayload, type CertificateHolderClaim, type CertificateHolderOrg, type CompleteEmailChangeResult, type CompleteEnrollmentResult, type EmailChangeToken, type EnrollmentToken, type EntityChange, type EntityRow, type EventKeyFilter, type FederationPeer, type IdentityApproval, type IdentityLink, type IdentityProvider, type InstrumentRegistration, type InstrumentRegistrationLifecycle, type InstrumentRegistrationScopeStatus, type NotifyEntityMute, type NotifyInboxState, type NotifyPreferences, type NotifyRule, type OAuthInitialAssignment, type OidcAccessToken, type OidcAuthorization, type OidcClient, type OidcClientLaunch, type OidcCode, type OidcKeyRow, type OpAccountErasure, type OpClientRoleAssignment, type OpLiveSession, type OrgJoinRequest, type OrgMembership, type OrgMembershipState, type OrgRegistryContact, type OrgRegistryOrg, type OrgRegistryState, type PlatformEvent, type ServerStore, type SessionView, type SsoSignInState, type UserAdminRow, type AdvanceCounterResult, type MfaPending, type RecoveryCodeState, type TotpSecret, type WebauthnChallenge, type WebauthnCredential } from '../store'
+import { installStore, type AuthUserPayload, type CertificateHolderClaim, type CertificateHolderOrg, type CompleteEmailChangeResult, type CompleteEnrollmentResult, type EmailChangeToken, type EnrollmentToken, type EntityChange, type EntityRow, type EventKeyFilter, type FederationPeer, type IdentityApproval, type IdentityLink, type IdentityProvider, type InstrumentRegistration, type InstrumentRegistrationLifecycle, type InstrumentRegistrationScopeStatus, type NotifyDelivery, type NotifyDeliveryStatus, type NotifyEntityMute, type NotifyInboxState, type NotifyPreferences, type NotifyRule, type OAuthInitialAssignment, type OidcAccessToken, type OidcAuthorization, type OidcClient, type OidcClientLaunch, type OidcCode, type OidcKeyRow, type OpAccountErasure, type OpClientRoleAssignment, type OpLiveSession, type OrgJoinRequest, type OrgMembership, type OrgMembershipState, type OrgRegistryContact, type OrgRegistryOrg, type OrgRegistryState, type PlatformEvent, type ServerStore, type SessionView, type SsoSignInState, type UserAdminRow, type AdvanceCounterResult, type MfaPending, type RecoveryCodeState, type TotpSecret, type WebauthnChallenge, type WebauthnCredential } from '../store'
 import {
   advanceWebauthnCounter,
   consumeMfaPending,
@@ -199,8 +206,10 @@ import {
  *  gate would drop the orphans anyway; wiping keeps the demo honest).
  *  TODO.register/03: the instrument register wipes too — the e2e
  *  isolation contract resets it with the rest of the mutable workflow
- *  state. */
-const WIPE_TABLES = ['entity_changes', 'evidence_records', 'entities', 'events', 'instrument_registrations'] as const
+ *  state. TODO.notify/04: the delivery store wipes alongside — its rows
+ *  reference the wiped events (the per-recipient record is the
+ *  workflow's, never the user's own state). */
+const WIPE_TABLES = ['entity_changes', 'evidence_records', 'entities', 'events', 'instrument_registrations', 'notify_deliveries'] as const
 
 export function createSqliteServerStore(): ServerStore {
   return {
@@ -962,6 +971,36 @@ export function createSqliteServerStore(): ServerStore {
       return putNotifyInboxState(input)
     },
 
+    // ── the email channel's delivery store (TODO.notify/04) ──
+    async putNotifyDelivery(input: {
+      id: string
+      eventId: string
+      userId: string
+      reason: string
+      email: NotifyDelivery['email']
+      emailStatus: NotifyDeliveryStatus | null
+    }): Promise<NotifyDelivery> {
+      return putNotifyDelivery(input)
+    },
+    async getNotifyDelivery(eventId: string, userId: string): Promise<NotifyDelivery | null> {
+      return getNotifyDelivery(eventId, userId)
+    },
+    async listNotifyDeliveriesForEvent(eventId: string): Promise<NotifyDelivery[]> {
+      return listNotifyDeliveriesForEvent(eventId)
+    },
+    async notifyDigestPendingUsers(): Promise<string[]> {
+      return notifyDigestPendingUsers()
+    },
+    async notifyDigestPendingForUser(userId: string): Promise<NotifyDelivery[]> {
+      return notifyDigestPendingForUser(userId)
+    },
+    async notifyFailedDeliveries(limit?: number): Promise<NotifyDelivery[]> {
+      return notifyFailedDeliveries(limit)
+    },
+    async markNotifyDelivery(id: string, status: NotifyDeliveryStatus): Promise<void> {
+      markNotifyDelivery(id, status)
+    },
+
     // ── provisioning / dev support ──
     async wipeWorkflowStores(range?: { after: number; through: number }): Promise<number> {
       const db = getDb()
@@ -983,6 +1022,7 @@ export function createSqliteServerStore(): ServerStore {
            UNION ALL SELECT MAX(rowid) FROM evidence_records
            UNION ALL SELECT MAX(rowid) FROM entities
            UNION ALL SELECT MAX(rowid) FROM events
+           UNION ALL SELECT MAX(rowid) FROM notify_deliveries
            UNION ALL SELECT MAX(rowid) FROM instrument_registrations)`,
       ).get() as { ceiling: number | null }
       return row.ceiling ?? 0

package/src/store.ts

@@ -278,6 +278,44 @@ export interface NotifyInboxState {
   createdAt: string
 }
 
+// ── the email channel's delivery store (TODO.notify/04) ──────────────
+
+/** The email leg's state on a delivery row: NULL when the resolved
+ *  posture is 'off' (the inbox carries the event, the mailbox never
+ *  does); 'sent' / 'failed' / 'rate_limited' for the immediate leg (the
+ *  retry sweep re-attempts 'failed'); 'digest_pending' → 'digest_sent' /
+ *  'digest_failed' for the daily rollup ('digest_dropped' when the event
+ *  left the store before the rollup ran); 'unavailable' when the
+ *  instance carries NO mailer (the honest degradation: nothing queues —
+ *  a console-posture instance marks the row at event time and the digest
+ *  never accumulates). */
+export type NotifyDeliveryStatus =
+  | 'sent' | 'failed' | 'rate_limited' | 'unavailable'
+  | 'digest_pending' | 'digest_sent' | 'digest_failed' | 'digest_dropped'
+
+/** One delivery row (TODO.notify/00: "a notification row per recipient
+ *  with the channel marks"): the fan-out's record that the event reached
+ *  this user — the resolution's STRONGEST reason, the resolved email
+ *  posture, and the email leg's state. The inbox is the constant, never
+ *  a column. UNIQUE (event_id, user_id): a re-driven event updates, never
+ *  duplicates. NO foreign keys (the subscriptions store's posture) — a
+ *  wiped event simply never joins. The mailer's per-SEND audit
+ *  (entity_type 'email') stands alongside; this table is the
+ *  PER-RECIPIENT record. */
+export interface NotifyDelivery {
+  id: string
+  eventId: string
+  userId: string
+  /** The resolution's strongest reason (NOTIFY_REASON_PRECEDENCE's first). */
+  reason: string
+  /** The resolved email posture (the channel split's outcome). */
+  email: NotifyChannelPreference
+  emailStatus: NotifyDeliveryStatus | null
+  /** The terminal stamp (the send / the drop); NULL while pending. */
+  emailAt: string | null
+  createdAt: string
+}
+
 // ── the OIDC Provider (TODO.identity/01) ─────────────────────────────
 
 /** A registered relying party (an instance allowed to request tokens).
@@ -1873,6 +1911,36 @@ export interface ServerStore {
     done?: boolean
   }): Promise<NotifyInboxState>
 
+  // ── the email channel's delivery store (TODO.notify/04) ──
+  /** The fan-out's write (the upsert on UNIQUE (event_id, user_id) — a
+   *  re-driven event updates, never duplicates). Answers the stored row. */
+  putNotifyDelivery(input: {
+    id: string
+    eventId: string
+    userId: string
+    reason: string
+    email: NotifyChannelPreference
+    emailStatus: NotifyDeliveryStatus | null
+  }): Promise<NotifyDelivery>
+  /** The by-pair read (the idempotence leg + the proofs). */
+  getNotifyDelivery(eventId: string, userId: string): Promise<NotifyDelivery | null>
+  /** One event's delivery rows (the proofs; the fan-out's own log). */
+  listNotifyDeliveriesForEvent(eventId: string): Promise<NotifyDelivery[]>
+  /** THE DIGEST SWEEP's reads: the users holding digest-pending rows,
+   *  then one user's pending rows (created_at order — the day's story). */
+  notifyDigestPendingUsers(): Promise<string[]>
+  notifyDigestPendingForUser(userId: string): Promise<NotifyDelivery[]>
+  /** THE RETRY SWEEP's read: the failed immediate rows, oldest first
+   *  (bounded — the sweep re-attempts per run, the mailer's rate limits
+   *  stand per attempt). */
+  notifyFailedDeliveries(limit?: number): Promise<NotifyDelivery[]>
+  /** The terminal/pending mark: the status + the stamp (email_at sets on
+   *  the terminal marks — sent/failed/rate_limited/unavailable/
+   *  digest_sent/digest_failed/digest_dropped — and CLEARS back to NULL
+   *  when a row re-enters digest_pending, so a retry's re-queue is
+   *  honest). */
+  markNotifyDelivery(id: string, status: NotifyDeliveryStatus): Promise<void>
+
   // ── provisioning / dev support ──
   /** The mutable workflow stores emptied (the dev-reset + demo reseed
    *  leg): entities, entity_changes, evidence_records, events, and