@oimlsmart/platform-server 0.1.1 → 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.1",
+  "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,
@@ -62,6 +64,7 @@ import {
   type InstrumentRegistrationScopeStatus,
   type PlatformEvent,
   resolveOrgContext,
+  parseOrgMemberCone,
   type RecoveryCodeState,
   type ServerStore,
   type SessionView,
@@ -175,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) {}
@@ -258,6 +262,14 @@ export class D1ServerStore implements ServerStore {
         ).run()
         await this.db.prepare('CREATE INDEX IF NOT EXISTS idx_org_memberships_org ON org_memberships (org_id, state)').run()
         await this.db.prepare('CREATE INDEX IF NOT EXISTS idx_org_memberships_user ON org_memberships (user_id, state)').run()
+        // TODO.identity-features/09 (the org-member data cone): the cone
+        // column arrives with migration 0017 — a dev D1 predating it
+        // grows the column here. NULL = org-wide: existing memberships
+        // keep their posture silently.
+        const membershipCols = await this.db.prepare('PRAGMA table_info(org_memberships)').all<{ name: string }>()
+        if (!membershipCols.results.some(c => c.name === 'cone')) {
+          await this.db.prepare('ALTER TABLE org_memberships ADD COLUMN cone TEXT').run()
+        }
         const sessionCols = await this.db.prepare('PRAGMA table_info(sessions)').all<{ name: string }>()
         if (!sessionCols.results.some(c => c.name === 'active_org')) {
           await this.db.prepare('ALTER TABLE sessions ADD COLUMN active_org TEXT').run()
@@ -569,7 +581,9 @@ export class D1ServerStore implements ServerStore {
       // The stale stamp never lingers (the membership ended mid-session).
       await this.stmt('UPDATE sessions SET active_org = NULL WHERE user_id = ? AND active_org = ?', payload.id, activeOrg).run()
     }
-    return { ...payload, orgId: resolved.orgId, roles: resolved.roles }
+    // TODO.identity-features/09: the context membership's cone rides the
+    // payload — the entity gates enforce it without a store round-trip.
+    return { ...payload, orgId: resolved.orgId, roles: resolved.roles, cone: resolved.cone }
   }
 
   async deleteSession(token: string): Promise<void> {
@@ -1986,6 +2000,9 @@ export class D1ServerStore implements ServerStore {
       userId: row.user_id as string,
       orgId: row.org_id as string,
       roles,
+      // The cone (TODO.identity-features/09): NULL parses to the
+      // org-wide default — a pre-existing membership keeps its posture.
+      cone: parseOrgMemberCone((row.cone as string | null) ?? null),
       state: row.state as OrgMembershipState,
       isPrimary: row.is_primary === 1,
       invitedBy: (row.invited_by as string | null) ?? null,
@@ -2109,6 +2126,16 @@ export class D1ServerStore implements ServerStore {
     return this.getOrgMembership(userId, orgId)
   }
 
+  /** Set the membership's data cone (TODO.identity-features/09): the
+   *  canonical spelling, or NULL for the org-wide default. */
+  async setOrgMembershipCone(userId: string, orgId: string, cone: string | null): Promise<OrgMembership | null> {
+    await this.ensureMembershipSupport()
+    const existing = await this.getOrgMembership(userId, orgId)
+    if (!existing) return null
+    await this.stmt('UPDATE org_memberships SET cone = ? WHERE user_id = ? AND org_id = ?', cone, userId, orgId).run()
+    return this.getOrgMembership(userId, orgId)
+  }
+
   /** Remove the row (the declined invitation; the erasure's cleanup). */
   async deleteOrgMembership(userId: string, orgId: string): Promise<boolean> {
     await this.ensureMembershipSupport()
@@ -2799,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,
@@ -2818,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/store.ts

@@ -107,6 +107,14 @@ function migrateAuthTables(db: Database.Database): void {
            'active', 1, COALESCE(last_login, created_at)
     FROM users WHERE org_id IS NOT NULL
   `)
+  // TODO.identity-features/09 (the org-member data cone): the
+  // membership's cone column arrives with migration 0017 — a dev file
+  // predating it grows the column here. NULL = org-wide: existing
+  // memberships keep their posture silently.
+  const membershipCols = db.prepare('PRAGMA table_info(org_memberships)').all() as Array<{ name: string }>
+  if (membershipCols.length && !membershipCols.some(c => c.name === 'cone')) {
+    db.exec('ALTER TABLE org_memberships ADD COLUMN cone TEXT')
+  }
   // TODO.identity-sso/02+03 (the strong-authentication wave): the amr
   // provenance columns on sessions → codes → access tokens.
   if (!sessionCols.some(c => c.name === 'amr')) {
@@ -781,13 +789,16 @@ export function findPendingOrgJoinRequestByEmail(email: string): OrgJoinRequest
 // AS; the columns' last writer never resurrects a disabled membership.
 
 import type { OrgMembership, OrgMembershipState } from '../../store'
-import { resolveOrgContext } from '../../store'
+import { resolveOrgContext, parseOrgMemberCone } from '../../store'
 
 interface OrgMembershipRow {
   id: string
   user_id: string
   org_id: string
   roles: string
+  /** TODO.identity-features/09 — the membership's data cone (the nullable
+   *  column; absent on a pre-migration row read). */
+  cone?: string | null
   state: OrgMembershipState
   is_primary: number
   invited_by: string | null
@@ -803,6 +814,9 @@ function membershipPayload(row: OrgMembershipRow): OrgMembership {
     userId: row.user_id,
     orgId: row.org_id,
     roles: parseRoles(row.roles) ?? [],
+    // The cone (TODO.identity-features/09): NULL parses to the org-wide
+    // default — a pre-existing membership keeps its posture silently.
+    cone: parseOrgMemberCone(row.cone),
     state: row.state,
     isPrimary: row.is_primary === 1,
     invitedBy: row.invited_by,
@@ -844,7 +858,9 @@ function applySessionOrgContext(activeOrg: string | null, payload: AuthUserPaylo
   if (activeOrg && !(active && active.state === 'active')) {
     getDb().prepare('UPDATE sessions SET active_org = NULL WHERE user_id = ? AND active_org = ?').run(payload.id, activeOrg)
   }
-  return { ...payload, orgId: resolved.orgId, roles: resolved.roles }
+  // TODO.identity-features/09: the context membership's cone rides the
+  // payload — the entity gates enforce it without a store round-trip.
+  return { ...payload, orgId: resolved.orgId, roles: resolved.roles, cone: resolved.cone }
 }
 
 export function listOrgMemberships(userId: string): OrgMembership[] {
@@ -938,6 +954,17 @@ export function setOrgMembershipState(
   return getOrgMembership(userId, orgId)
 }
 
+/** Set the membership's data cone (TODO.identity-features/09): the
+ *  canonical column spelling, or NULL for the org-wide default. Answers
+ *  null when no membership exists. */
+export function setOrgMembershipCone(userId: string, orgId: string, cone: string | null): OrgMembership | null {
+  const db = getDb()
+  const existing = getOrgMembership(userId, orgId)
+  if (!existing) return null
+  db.prepare('UPDATE org_memberships SET cone = ? WHERE user_id = ? AND org_id = ?').run(cone, userId, orgId)
+  return getOrgMembership(userId, orgId)
+}
+
 /** Remove the row (the holder declining an invitation; the erasure's
  *  cleanup). The route refuses the PRIMARY membership. */
 export function deleteOrgMembership(userId: string, orgId: string): boolean {

package/src/store/sqlite.ts

@@ -67,6 +67,7 @@ import {
   setInstrumentRegistrationLifecycle,
   setOrgMembershipRoles,
   setOrgMembershipState,
+  setOrgMembershipCone,
   setOrgRegistryOrgState,
   setSessionActiveOrg,
   setUserActive,
@@ -95,12 +96,19 @@ import {
 import {
   deleteNotifyEntityMute,
   deleteNotifyRule,
+  getNotifyDelivery,
   getNotifyPreferences,
+  listNotifyDeliveriesForEvent,
   listNotifyEntityMutes,
   listNotifyInboxStates,
   listNotifyRules,
+  markNotifyDelivery,
+  notifyDigestPendingForUser,
+  notifyDigestPendingUsers,
   notifyEntityMutesForEvent,
+  notifyFailedDeliveries,
   notifyRulesForEvent,
+  putNotifyDelivery,
   putNotifyEntityMute,
   putNotifyInboxState,
   putNotifyPreferences,
@@ -164,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,
@@ -198,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 {
@@ -412,6 +422,9 @@ export function createSqliteServerStore(): ServerStore {
     ): Promise<OrgMembership | null> {
       return setOrgMembershipState(userId, orgId, state, actor)
     },
+    async setOrgMembershipCone(userId: string, orgId: string, cone: string | null): Promise<OrgMembership | null> {
+      return setOrgMembershipCone(userId, orgId, cone)
+    },
     async deleteOrgMembership(userId: string, orgId: string): Promise<boolean> {
       return deleteOrgMembership(userId, orgId)
     },
@@ -958,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()
@@ -979,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

@@ -40,6 +40,15 @@ export interface AuthUserPayload {
    *  (absent = the primary role only). */
   roles?: string[]
   orgId: string | null
+  /** TODO.identity-features/09 — the ACTIVE org context's data cone (the
+   *  membership's posture, resolved by the session-backed read; the OP's
+   *  `cone` claim carries the same value). ABSENT on constructors that
+   *  never resolve a membership (the row-backed reads); NULL = the
+   *  context resolved no membership (an org-free account — the cone
+   *  never applies to it). The cone only ever NARROWS: the enforcement
+   *  reads it at the two choke points (the entity API's read/write
+   *  gates), never as a grant. */
+  cone?: OrgMemberCone | null
   avatarUrl?: string
   /** TODO.identity/04: the account's sign-in provider family ('demo',
    *  'github', 'oidc', the OP's account provider) — projected from the
@@ -269,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).
@@ -670,6 +717,73 @@ export interface OrgJoinRequest {
  *  act, never an automatic one). */
 export type OrgMembershipState = 'invited' | 'active' | 'disabled'
 
+// ── the per-member data cone (TODO.identity-features/09) ─────────────
+// Every org membership carries a CONE — the org administrator's answer
+// to "what can this member see and do" (the design: the org-wide default
+// keeps today's behavior; 'assigned' narrows the member to the org's
+// rows that NAME them; 'read-only' is the orthogonal modifier that
+// refuses the member's writes). The cone lives on the membership row
+// (org_memberships.cone, a nullable TEXT column — NULL is org-wide, so
+// existing memberships keep their posture silently), rides the OP's
+// claims in the active-org context, and is enforced at the platform's
+// two choke points ONLY (the read gate and the write gate). THE
+// INVARIANT: the cone only ever NARROWS — nothing in this machinery can
+// grant.
+
+/** The cone's scope: org-wide (the default — every row the org sees) or
+ *  assigned (only the org's rows that NAME the member — the operator on
+ *  the test run, the assignment's performer, the engagement's inquirer). */
+export type OrgMemberConeScope = 'org-wide' | 'assigned'
+
+/** The parsed cone (the payload shape every consumer reads). */
+export interface OrgMemberCone {
+  scope: OrgMemberConeScope
+  /** The orthogonal modifier: the member reads per the scope but the
+   *  write gate refuses them (a reviewer's posture). */
+  readOnly: boolean
+}
+
+/** The DEFAULT cone (a NULL column): org-wide, writable — today's
+ *  behavior, kept silently by every pre-existing membership. */
+export const ORG_MEMBER_CONE_DEFAULT: OrgMemberCone = { scope: 'org-wide', readOnly: false }
+
+/** The FAIL-CLOSED cone: a stored value the parser cannot read narrows
+ *  to the tightest posture (never a silent re-widen — the platform's
+ *  standing doctrine: a malformed permission input never grants). */
+export const ORG_MEMBER_CONE_FAIL_CLOSED: OrgMemberCone = { scope: 'assigned', readOnly: true }
+
+/** The canonical column spellings (NULL is the default — the column
+ *  stays NULL for org-wide+writable, keeping the expand-only posture
+ *  clean). 'org-wide' parses but never encodes (it IS the default). */
+export function encodeOrgMemberCone(cone: OrgMemberCone): string | null {
+  if (cone.scope === 'assigned') return cone.readOnly ? 'assigned+read-only' : 'assigned'
+  return cone.readOnly ? 'read-only' : null
+}
+
+/** Parse the stored cone (total, never throws): NULL/empty/'org-wide'
+ *  answer the default; a recognized composition parses; ANYTHING else
+ *  fails CLOSED (the narrowest cone) — a hand-edited or corrupt row
+ *  narrows the member, it never widens them. */
+export function parseOrgMemberCone(raw: string | null | undefined): OrgMemberCone {
+  if (raw === null || raw === undefined) return { ...ORG_MEMBER_CONE_DEFAULT }
+  const tokens = raw.split('+').map(t => t.trim()).filter(Boolean)
+  if (tokens.length === 0) return { ...ORG_MEMBER_CONE_DEFAULT }
+  let scopeSeen: OrgMemberConeScope | null = null
+  let readOnly = false
+  for (const token of tokens) {
+    if (token === 'read-only') {
+      if (readOnly) return { ...ORG_MEMBER_CONE_FAIL_CLOSED } // a doubled modifier is not a spelling
+      readOnly = true
+    } else if (token === 'org-wide' || token === 'assigned') {
+      if (scopeSeen !== null) return { ...ORG_MEMBER_CONE_FAIL_CLOSED } // two scopes is not a spelling
+      scopeSeen = token
+    } else {
+      return { ...ORG_MEMBER_CONE_FAIL_CLOSED } // an unknown token
+    }
+  }
+  return { scope: scopeSeen ?? 'org-wide', readOnly }
+}
+
 /** An account's membership in ONE organization (the org_memberships
  *  row): the per-org role set + the lifecycle state. The PRIMARY
  *  membership (isPrimary) is the backward-compatible one: the users
@@ -684,6 +798,10 @@ export interface OrgMembership {
   /** The PER-ORG role set (JSON on the row): the roles the account holds
    *  when acting AS this org. */
   roles: string[]
+  /** The membership's data cone (TODO.identity-features/09), parsed from
+   *  the row's nullable column — the DEFAULT object when the column is
+   *  NULL (org-wide, writable); never null on the payload. */
+  cone: OrgMemberCone
   state: OrgMembershipState
   isPrimary: boolean
   invitedBy: string | null
@@ -693,13 +811,16 @@ export interface OrgMembership {
   disabledBy: string | null
 }
 
-/** The effective org context: the org the account acts AS and the role
- *  set that context carries. The session payloads and the OP's token
- *  claims both resolve through resolveOrgContext, so the two never
- *  drift. */
+/** The effective org context: the org the account acts AS, the role
+ *  set that context carries, and the context membership's data cone
+ *  (TODO.identity-features/09 — NULL when NO membership row resolved:
+ *  the pre-memberships dual-read and the org-free account carry no
+ *  cone). The session payloads and the OP's token claims both resolve
+ *  through resolveOrgContext, so the two never drift. */
 export interface OrgContextResolution {
   orgId: string | null
   roles: string[]
+  cone: OrgMemberCone | null
 }
 
 /**
@@ -733,14 +854,16 @@ export function resolveOrgContext(
     const m = context.active
     if (m && m.orgId === context.activeOrg && m.state === 'active') {
       const global = user.orgId ? [] : accountRoles
-      return { orgId: context.activeOrg, roles: [...new Set([...m.roles, ...global])] }
+      return { orgId: context.activeOrg, roles: [...new Set([...m.roles, ...global])], cone: m.cone }
     }
   }
-  if (!user.orgId) return { orgId: null, roles: accountRoles }
+  if (!user.orgId) return { orgId: null, roles: accountRoles, cone: null }
   const p = context.primary
-  if (!p) return { orgId: user.orgId, roles: accountRoles }
-  if (p.state !== 'active') return { orgId: null, roles: [] }
-  return { orgId: user.orgId, roles: [...new Set([...accountRoles, ...p.roles])] }
+  // The pre-memberships dual-read (no primary row) carries NO cone — the
+  // org-wide default the enforcement reads for a cone-less context.
+  if (!p) return { orgId: user.orgId, roles: accountRoles, cone: null }
+  if (p.state !== 'active') return { orgId: null, roles: [], cone: null }
+  return { orgId: user.orgId, roles: [...new Set([...accountRoles, ...p.roles])], cone: p.cone }
 }
 
 // ── the organization registry (TODO.identity-features/05) ────────────
@@ -1539,6 +1662,13 @@ export interface ServerStore {
     state: OrgMembershipState,
     actor?: string | null,
   ): Promise<OrgMembership | null>
+  /** Set the membership's data cone (TODO.identity-features/09): the
+   *  CANONICAL column spelling (encodeOrgMemberCone's answer — NULL is
+   *  the org-wide default) or NULL to clear. The input's validation is
+   *  the ROUTE's (parse + re-encode; the store writes what it is given,
+   *  the parser's fail-closed posture backstops a bad cell). Answers
+   *  null when no membership exists. */
+  setOrgMembershipCone(userId: string, orgId: string, cone: string | null): Promise<OrgMembership | null>
   /** Remove the row — the holder declining an invitation, and the
    *  erasure's cleanup. (The routes refuse the PRIMARY membership: the
    *  primary binding moves through the account's role/org assignment,
@@ -1781,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