@oimlsmart/platform-server 0.2.11 → 0.2.13

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OIML SMART project contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/migrations/0027_notify_mentions_saved.sql

@@ -0,0 +1,33 @@
+-- TODO.notify/05's remainders (platform-server#25 — the smart side's
+-- TODO.notify/00 banner: the mentions-parse half and the per-event saved
+-- flag ride a KERNEL migration). Expand-only per the migration contract
+-- (append, never renumber): two columns, both NULL-defaulted, existing
+-- rows untouched.
+--
+--   events.mentions            the act's @user mentions (TODO.notify/00's
+--                              "Mentions land as the 'mentioned' reason"):
+--                              a JSON array of the mentioned USER IDS,
+--                              resolved by the comment surfaces' parse at
+--                              event time and recorded ON THE ROW — the
+--                              inbox feed computes its reasons at READ,
+--                              and a mention is a fact of the act, never
+--                              re-derivable from the entity. NULL = none
+--                              (every pre-0027 row, every mention-free
+--                              act). The recipient resolution's
+--                              'mentioned' candidate class reads it; the
+--                              mutes and the visibility gate still win
+--                              (a mention never widens access).
+--
+--   notify_inbox_state.saved_at  the per-event saved flag (TODO.notify/
+--                              00's inbox state "read / done / saved",
+--                              the GitHub Save): stamps at the save act,
+--                              clears at the un-save. Independent of
+--                              read/done — a saved row that is done stays
+--                              saved in the archive. The marker row's
+--                              posture is unchanged (the user's own state,
+--                              lazily written, no foreign keys).
+--
+-- The schema's SQLite mirror (src/store/sqlite/schema.sql) updates in
+-- the same commit; test/migrations.test.ts fails the package otherwise.
+ALTER TABLE events ADD COLUMN mentions TEXT;
+ALTER TABLE notify_inbox_state ADD COLUMN saved_at TEXT;

package/migrations/0028_entities_certificate_number_index.sql

@@ -0,0 +1,22 @@
+-- The public register's certificate-number lookup (the ServerStore
+-- seam's findCertificatesByNumber): the smart side's verify surfaces
+-- (/api/verify/status?number=, the credential verify's register
+-- cross-check) full-scanned listEntities('certificates') and
+-- JSON-parsed every row to case-fold certificate_number — O(store
+-- rows) read per lookup. The guarded expression index (migration
+-- 0023's spelling) makes the keyed read an index walk: (store, the
+-- certificate_number out of the data JSON) — COLLATE NOCASE because
+-- the register's number match is case-insensitive (the ASCII fold;
+-- certificate numbers are ASCII by the number grammar).
+--
+-- The json_valid GUARD is load-bearing (0023's lesson): an unguarded
+-- json_extract index expression would raise on the INSERT of a corrupt
+-- entities row; the guard keeps a corrupt row writable.
+--
+-- CREATE INDEX IF NOT EXISTS is the idempotent guard (the migration
+-- contract's expand-only discipline; a consumer that already carries
+-- the index converges). schema.sql's mirror lands in the same commit.
+CREATE INDEX IF NOT EXISTS idx_entities_store_certificate_number ON entities (
+  store,
+  json_extract(CASE WHEN json_valid(data) THEN data ELSE '{}' END, '$.certificate_number') COLLATE NOCASE
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oimlsmart/platform-server",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "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

@@ -33,6 +33,7 @@ import {
   APPEND_EVENTS_CHUNK,
   DEMO_PASSWORD,
   EVENTS_BULK_KEY_CHUNK,
+  EVENTS_ID_CHUNK,
   INSTRUMENT_REGISTRATIONS_CHUNK,
   PUT_ENTITIES_CHUNK,
   StoreUnavailable,
@@ -88,6 +89,7 @@ import {
   type InstrumentRegistrationLifecycle,
   type InstrumentRegistrationScopeStatus,
   type InstrumentRegistrationWriteInput,
+  type JournalAppend,
   type PersonalAccessToken,
   type PlatformEvent,
   resolveOrgContext,
@@ -427,6 +429,43 @@ const ENTITY_UPSERT_SQL = `INSERT INTO entities (store, id, org_id, data, update
          ON CONFLICT (store, id) DO UPDATE SET org_id = excluded.org_id, data = excluded.data, updated_at = datetime('now')`
 const ENTITY_CHANGE_SQL = 'INSERT INTO entity_changes (store, type, id) VALUES (?, ?, ?)'
 
+/** The journal fan-out's ISOLATE-scope registry (the seam's
+ *  onJournalAppend): one module-scope set — a registration through ANY
+ *  D1ServerStore instance hears every journal append landing in this
+ *  isolate, whichever instance wrote it. Cross-isolate writes never
+ *  fire it (the database is the source of truth; the consumer's poll
+ *  stays the fallback). */
+const journalListeners = new Set<(appends: readonly JournalAppend[]) => void>()
+
+/** Fires the registry with one write's appended triples, AFTER the
+ *  write stands (the batch resolved / the row gone). Synchronous, in
+ *  the write's continuation; a listener's throw is swallowed per
+ *  listener — the write path never breaks for a listener. The snapshot
+ *  keeps an unregistering listener's removal honest mid-emit. */
+function emitJournalAppends(appends: readonly JournalAppend[]): void {
+  if (appends.length === 0 || journalListeners.size === 0) return
+  for (const listener of [...journalListeners]) {
+    try {
+      listener(appends)
+    } catch { /* a listener never breaks the write path */ }
+  }
+}
+
+/** The register's number lookup (findCertificatesByNumber): the keyed
+ *  read against idx_entities_store_certificate_number (migration 0028)
+ *  — the json_valid-guarded extract's exact spelling, COLLATE NOCASE
+ *  for the register's case-insensitive number match. INDEXED BY pins
+ *  the walk: without it the planner prefers idx_entities_store_org for
+ *  the ORDER BY (org_id, rowid) — the seam's list order, kept so the
+ *  first match IS the retiring listEntities scan's first match — and
+ *  the "index" would walk the whole store; with it a database behind
+ *  migration 0028 errors honestly, never scans silently. */
+const CERTIFICATE_NUMBER_SQL = `SELECT store, id, org_id, data, updated_at
+       FROM entities INDEXED BY idx_entities_store_certificate_number
+       WHERE store = 'certificates'
+         AND json_extract(CASE WHEN json_valid(data) THEN data ELSE '{}' END, '$.certificate_number') COLLATE NOCASE = ?
+       ORDER BY org_id, rowid`
+
 /** The register write's INSERT — ONE textual source for
  *  createInstrumentRegistration and createInstrumentRegistrations alike
  *  (the batch verb appends RETURNING * so the stored row answers off
@@ -438,8 +477,9 @@ const INSTRUMENT_REGISTRATION_INSERT_SQL = `INSERT OR IGNORE INTO instrument_reg
 
 /** The event append's INSERT … RETURNING * — ONE textual source for
  *  appendEvent and appendEvents alike (the stored row — seq + the
- *  default at — answers off the write itself). */
-const EVENT_INSERT_SQL = 'INSERT INTO events (id, domain, entity_id, action, payload) VALUES (?, ?, ?, ?, ?) RETURNING *'
+ *  default at — answers off the write itself). The mentions column
+ *  (migration 0027) lands from the input, NULL when absent. */
+const EVENT_INSERT_SQL = 'INSERT INTO events (id, domain, entity_id, action, payload, mentions) VALUES (?, ?, ?, ?, ?, ?) RETURNING *'
 
 export class D1ServerStore implements ServerStore {
   /** The RAW binding — the ensure memos (and d1StoreFor's map) key on
@@ -3524,6 +3564,11 @@ export class D1ServerStore implements ServerStore {
     return row ?? undefined
   }
 
+  async findCertificatesByNumber(number: string): Promise<EntityRow[]> {
+    const res = await this.stmt(CERTIFICATE_NUMBER_SQL, number).all<EntityRow>()
+    return res.results
+  }
+
   async putEntity(store: string, id: string, orgId: string | null, data: string): Promise<void> {
     // The upsert + its journal entry ride ONE batch — D1 batches are
     // all-or-nothing, the same atomicity the SQLite path gets from its
@@ -3532,6 +3577,7 @@ export class D1ServerStore implements ServerStore {
       this.stmt(ENTITY_UPSERT_SQL, store, id, orgId, data),
       this.stmt(ENTITY_CHANGE_SQL, store, 'persist', id),
     ])
+    emitJournalAppends([{ store, type: 'persist', id }])
   }
 
   async putEntities(store: string, rows: readonly EntityWriteInput[]): Promise<void> {
@@ -3554,6 +3600,10 @@ export class D1ServerStore implements ServerStore {
         )
       }
       await this.db.batch(statements)
+      // The fan-out fires per LANDED chunk (the triples in input order)
+      // — a failed chunk throws before its emit, so a listener never
+      //  hears of rows that did not stand.
+      emitJournalAppends(chunk.map((row): JournalAppend => ({ store, type: 'persist', id: row.id })))
     }
   }
 
@@ -3562,6 +3612,7 @@ export class D1ServerStore implements ServerStore {
     const gone = (res.meta.changes ?? 0) > 0
     if (gone) {
       await this.stmt('INSERT INTO entity_changes (store, type, id) VALUES (?, ?, ?)', store, 'remove', id).run()
+      emitJournalAppends([{ store, type: 'remove', id }])
     }
     return gone
   }
@@ -3588,6 +3639,11 @@ export class D1ServerStore implements ServerStore {
     return row?.seq ?? 0
   }
 
+  onJournalAppend(listener: (appends: readonly JournalAppend[]) => void): () => void {
+    journalListeners.add(listener)
+    return () => { journalListeners.delete(listener) }
+  }
+
   // ── the platform event store (TODO.notify/01) ─────────────────────
   // The event rows port directly (D1 is SQLite) — the same statements
   // as sqlite/events.ts's sync half.
@@ -3600,6 +3656,7 @@ export class D1ServerStore implements ServerStore {
       entityId: row.entity_id as string,
       action: row.action as string,
       payload: row.payload as string,
+      mentions: (row.mentions as string | null) ?? null,
       at: row.at as string,
     }
   }
@@ -3611,7 +3668,7 @@ export class D1ServerStore implements ServerStore {
     // two round trips per event, halved).
     const row = await this.stmt(
       EVENT_INSERT_SQL,
-      input.id, input.domain, input.entityId, input.action, input.payload,
+      input.id, input.domain, input.entityId, input.action, input.payload, input.mentions ?? null,
     ).first<Record<string, unknown>>()
     return D1ServerStore.toPlatformEvent(row!)
   }
@@ -3630,7 +3687,7 @@ export class D1ServerStore implements ServerStore {
       const chunk = events.slice(i, i + APPEND_EVENTS_CHUNK)
       const statements = chunk.map(e => this.stmt(
         EVENT_INSERT_SQL,
-        e.id, e.domain, e.entityId, e.action, e.payload,
+        e.id, e.domain, e.entityId, e.action, e.payload, e.mentions ?? null,
       ))
       const results = await this.db.batch(statements)
       for (const res of results) {
@@ -3657,6 +3714,28 @@ export class D1ServerStore implements ServerStore {
     return row ? D1ServerStore.toPlatformEvent(row) : null
   }
 
+  /** The bulk by-id read (the seam's contract, mechanically): every id
+   *  resolves in ONE statement per EVENTS_ID_CHUNK ids — the IN walk
+   *  against the id UNIQUE index (never a compound SELECT: the D1
+   *  5-term cap rule), the chunks serial — and the answer is
+   *  INPUT-ALIGNED: position i carries the row for ids[i], null where
+   *  no event carries the id (the per-id getEvent loop's exact
+   *  answers; a duplicate id answers its row at every position). An
+   *  empty list answers [] without issuing a statement. */
+  async getEvents(ids: readonly string[]): Promise<(PlatformEvent | null)[]> {
+    if (ids.length === 0) return []
+    const byId = new Map<string, PlatformEvent>()
+    for (let i = 0; i < ids.length; i += EVENTS_ID_CHUNK) {
+      const chunk = ids.slice(i, i + EVENTS_ID_CHUNK)
+      const marks = chunk.map(() => '?').join(', ')
+      const res = await this.stmt(
+        `SELECT * FROM events WHERE id IN (${marks})`, ...chunk,
+      ).all<Record<string, unknown>>()
+      for (const row of res.results) byId.set(row.id as string, D1ServerStore.toPlatformEvent(row))
+    }
+    return ids.map(id => byId.get(id) ?? null)
+  }
+
   /** The subscription grammar's SQL resolution: the pinned columns match
    *  by equality; the free legs stay out of the WHERE. The BULK form
    *  (the 2026-09-06 audit's notify-inbox seam) resolves every pinned
@@ -3842,6 +3921,7 @@ export class D1ServerStore implements ServerStore {
       eventId: row.event_id as string,
       readAt: (row.read_at as string | null) ?? null,
       doneAt: (row.done_at as string | null) ?? null,
+      savedAt: (row.saved_at as string | null) ?? null,
       createdAt: row.created_at as string,
     }
   }
@@ -3860,6 +3940,7 @@ export class D1ServerStore implements ServerStore {
     eventId: string
     read?: boolean
     done?: boolean
+    saved?: boolean
   }): Promise<NotifyInboxState> {
     await this.stmt(
       'INSERT OR IGNORE INTO notify_inbox_state (user_id, event_id) VALUES (?, ?)',
@@ -3877,6 +3958,12 @@ export class D1ServerStore implements ServerStore {
         input.done ? 1 : 0, input.userId, input.eventId,
       ).run()
     }
+    if (input.saved !== undefined) {
+      await this.stmt(
+        "UPDATE notify_inbox_state SET saved_at = CASE WHEN ? THEN datetime('now') ELSE NULL END WHERE user_id = ? AND event_id = ?",
+        input.saved ? 1 : 0, input.userId, input.eventId,
+      ).run()
+    }
     const row = await this.stmt(
       'SELECT * FROM notify_inbox_state WHERE user_id = ? AND event_id = ?',
       input.userId, input.eventId,

package/src/store/sqlite/entities.ts

@@ -18,7 +18,33 @@ import { PUT_ENTITIES_CHUNK, orgIdOf } from '../../store'
 export type { EntityRow, EntityChange } from '../../store'
 export { ORG_FIELDS, CATALOG_STORES, orgIdOf } from '../../store'
 
-import type { EntityRow, EntityChange, EntityWriteInput } from '../../store'
+import type { EntityRow, EntityChange, EntityWriteInput, JournalAppend } from '../../store'
+
+/** The journal fan-out's ISOLATE-scope registry (the seam's
+ *  onJournalAppend, the D1 half's twin): one module-scope set — a
+ *  registration through any store instance hears every journal append
+ *  landing in this process. */
+const journalListeners = new Set<(appends: readonly JournalAppend[]) => void>()
+
+/** The seam's registration verb: the answer is the unregister
+ *  (idempotent). */
+export function onJournalAppend(listener: (appends: readonly JournalAppend[]) => void): () => void {
+  journalListeners.add(listener)
+  return () => { journalListeners.delete(listener) }
+}
+
+/** Fires the registry with one write's appended triples, AFTER the
+ *  write stands (the transaction committed). A listener's throw is
+ *  swallowed per listener — the write path never breaks for a
+ *  listener. */
+function emitJournalAppends(appends: readonly JournalAppend[]): void {
+  if (appends.length === 0 || journalListeners.size === 0) return
+  for (const listener of [...journalListeners]) {
+    try {
+      listener(appends)
+    } catch { /* a listener never breaks the write path */ }
+  }
+}
 
 /** The entity write's two statements, ONE textual source for putEntity
  *  and putEntities alike (the multi-row write must land each row
@@ -28,6 +54,21 @@ const ENTITY_UPSERT_SQL = `INSERT INTO entities (store, id, org_id, data, update
        ON CONFLICT (store, id) DO UPDATE SET org_id = excluded.org_id, data = excluded.data, updated_at = datetime('now')`
 const ENTITY_CHANGE_SQL = 'INSERT INTO entity_changes (store, type, id) VALUES (?, ?, ?)'
 
+/** The register's number lookup (the seam's findCertificatesByNumber,
+ *  the D1 half's CERTIFICATE_NUMBER_SQL's twin): the keyed read against
+ *  idx_entities_store_certificate_number (migration 0028) — the
+ *  json_valid-guarded extract's exact spelling, COLLATE NOCASE for the
+ *  register's case-insensitive number match. INDEXED BY pins the walk:
+ *  without it the planner prefers idx_entities_store_org for the ORDER
+ *  BY (org_id, rowid) — the seam's list order, kept so the first match
+ *  IS the retiring listEntities scan's first match — and the "index"
+ *  would walk the whole store. */
+const CERTIFICATE_NUMBER_SQL = `SELECT store, id, org_id, data, updated_at
+       FROM entities INDEXED BY idx_entities_store_certificate_number
+       WHERE store = 'certificates'
+         AND json_extract(CASE WHEN json_valid(data) THEN data ELSE '{}' END, '$.certificate_number') COLLATE NOCASE = ?
+       ORDER BY org_id, rowid`
+
 export function listEntities(store: string): EntityRow[] {
   // The ORDER BY is the seam's contract (the 0.2.3 pin, the D1 half's
   // twin): (org_id, rowid) — the read's observable order since
@@ -45,6 +86,12 @@ export function getEntity(store: string, id: string): EntityRow | undefined {
     .get(store, id) as EntityRow | undefined
 }
 
+/** The register's keyed number lookup — one index walk, never the
+ *  listEntities scan + per-row JSON parse. */
+export function findCertificatesByNumber(number: string): EntityRow[] {
+  return getDb().prepare(CERTIFICATE_NUMBER_SQL).all(number) as EntityRow[]
+}
+
 export function putEntity(store: string, id: string, orgId: string | null, data: string): void {
   const db = getDb()
   const write = db.transaction(() => {
@@ -52,6 +99,7 @@ export function putEntity(store: string, id: string, orgId: string | null, data:
     db.prepare(ENTITY_CHANGE_SQL).run(store, 'persist', id)
   })
   write()
+  emitJournalAppends([{ store, type: 'persist', id }])
 }
 
 /** The multi-row write (the seam's putEntities, the 2026-09-07 audit's
@@ -74,6 +122,9 @@ export function putEntities(store: string, rows: readonly EntityWriteInput[]): v
         journal.run(store, 'persist', row.id)
       }
     })()
+    // The fan-out fires per LANDED chunk (the D1 half's posture) — a
+    // failed chunk throws before its emit.
+    emitJournalAppends(chunk.map((row): JournalAppend => ({ store, type: 'persist', id: row.id })))
   }
 }
 
@@ -88,6 +139,7 @@ export function deleteEntity(store: string, id: string): boolean {
     }
   })
   write()
+  if (gone) emitJournalAppends([{ store, type: 'remove', id }])
   return gone
 }
 

package/src/store/sqlite/events.ts

@@ -9,7 +9,7 @@
 // ═══════════════════════════════════════════════════════════════════
 
 import { getDb } from './store'
-import { APPEND_EVENTS_CHUNK, EVENTS_BULK_KEY_CHUNK, type EventEntityKey, type EventKeyFilter, type EventWriteInput, type PlatformEvent } from '../../store'
+import { APPEND_EVENTS_CHUNK, EVENTS_BULK_KEY_CHUNK, EVENTS_ID_CHUNK, type EventEntityKey, type EventKeyFilter, type EventWriteInput, type PlatformEvent } from '../../store'
 
 interface EventRow {
   seq: number
@@ -18,6 +18,7 @@ interface EventRow {
   entity_id: string
   action: string
   payload: string
+  mentions: string | null
   at: string
 }
 
@@ -29,17 +30,23 @@ function toPlatformEvent(row: EventRow): PlatformEvent {
     entityId: row.entity_id,
     action: row.action,
     payload: row.payload,
+    mentions: row.mentions,
     at: row.at,
   }
 }
 
+/** The event append's INSERT … RETURNING * — ONE textual source for
+ *  appendEvent and appendEvents alike (the D1 half's EVENT_INSERT_SQL's
+ *  twin; the stored row answers off the write itself). The mentions
+ *  column (migration 0027) lands from the input, NULL when absent. */
+const EVENT_INSERT_SQL = 'INSERT INTO events (id, domain, entity_id, action, payload, mentions) VALUES (?, ?, ?, ?, ?, ?) RETURNING *'
+
 export function appendEvent(input: EventWriteInput): PlatformEvent {
   // ONE statement: RETURNING answers the stored row (seq + the default
   // at) off the INSERT itself — the same halving as the D1 half.
   return toPlatformEvent(
-    getDb().prepare(
-      `INSERT INTO events (id, domain, entity_id, action, payload) VALUES (?, ?, ?, ?, ?) RETURNING *`,
-    ).get(input.id, input.domain, input.entityId, input.action, input.payload) as EventRow,
+    getDb().prepare(EVENT_INSERT_SQL)
+      .get(input.id, input.domain, input.entityId, input.action, input.payload, input.mentions ?? null) as EventRow,
   )
 }
 
@@ -55,15 +62,13 @@ export function appendEvent(input: EventWriteInput): PlatformEvent {
 export function appendEvents(events: readonly EventWriteInput[]): PlatformEvent[] {
   if (events.length === 0) return []
   const db = getDb()
-  const insert = db.prepare(
-    `INSERT INTO events (id, domain, entity_id, action, payload) VALUES (?, ?, ?, ?, ?) RETURNING *`,
-  )
+  const insert = db.prepare(EVENT_INSERT_SQL)
   const out: PlatformEvent[] = []
   for (let i = 0; i < events.length; i += APPEND_EVENTS_CHUNK) {
     const chunk = events.slice(i, i + APPEND_EVENTS_CHUNK)
     db.transaction(() => {
       for (const e of chunk) {
-        out.push(toPlatformEvent(insert.get(e.id, e.domain, e.entityId, e.action, e.payload) as EventRow))
+        out.push(toPlatformEvent(insert.get(e.id, e.domain, e.entityId, e.action, e.payload, e.mentions ?? null) as EventRow))
       }
     })()
   }
@@ -89,6 +94,28 @@ export function getEvent(id: string): PlatformEvent | null {
   return row ? toPlatformEvent(row) : null
 }
 
+/** The BULK by-id read (the notify digest's event join): every id
+ *  resolves in ONE statement per EVENTS_ID_CHUNK ids — the IN walk
+ *  against the id UNIQUE index, the same chunking as the D1 half, so
+ *  the backends stay answer-identical. The answer is INPUT-ALIGNED:
+ *  position i carries the row for ids[i], null where no event carries
+ *  the id (the per-id getEvent loop's exact answers; a duplicate id
+ *  answers its row at every position). An empty list answers []
+ *  without issuing a statement. */
+export function getEvents(ids: readonly string[]): (PlatformEvent | null)[] {
+  if (ids.length === 0) return []
+  const byId = new Map<string, PlatformEvent>()
+  for (let i = 0; i < ids.length; i += EVENTS_ID_CHUNK) {
+    const chunk = ids.slice(i, i + EVENTS_ID_CHUNK)
+    const marks = chunk.map(() => '?').join(', ')
+    const rows = getDb()
+      .prepare(`SELECT * FROM events WHERE id IN (${marks})`)
+      .all(...chunk) as EventRow[]
+    for (const row of rows) byId.set(row.id, toPlatformEvent(row))
+  }
+  return ids.map(id => byId.get(id) ?? null)
+}
+
 /** The subscription grammar's SQL resolution: the pinned columns match
  *  by equality; the free legs stay out of the WHERE. The BULK form (the
  *  2026-09-06 audit's notify-inbox seam) resolves every pinned (domain,

package/src/store/sqlite/notify.ts

@@ -205,6 +205,7 @@ interface InboxStateRow {
   event_id: string
   read_at: string | null
   done_at: string | null
+  saved_at: string | null
   created_at: string
 }
 
@@ -214,6 +215,7 @@ function toNotifyInboxState(row: InboxStateRow): NotifyInboxState {
     eventId: row.event_id,
     readAt: row.read_at,
     doneAt: row.done_at,
+    savedAt: row.saved_at,
     createdAt: row.created_at,
   }
 }
@@ -233,6 +235,7 @@ export function putNotifyInboxState(input: {
   eventId: string
   read?: boolean
   done?: boolean
+  saved?: boolean
 }): NotifyInboxState {
   const db = getDb()
   db.prepare(
@@ -246,6 +249,10 @@ export function putNotifyInboxState(input: {
     db.prepare("UPDATE notify_inbox_state SET done_at = CASE WHEN ? THEN datetime('now') ELSE NULL END WHERE user_id = ? AND event_id = ?")
       .run(input.done ? 1 : 0, input.userId, input.eventId)
   }
+  if (input.saved !== undefined) {
+    db.prepare("UPDATE notify_inbox_state SET saved_at = CASE WHEN ? THEN datetime('now') ELSE NULL END WHERE user_id = ? AND event_id = ?")
+      .run(input.saved ? 1 : 0, input.userId, input.eventId)
+  }
   return toNotifyInboxState(
     db.prepare('SELECT * FROM notify_inbox_state WHERE user_id = ? AND event_id = ?')
       .get(input.userId, input.eventId) as InboxStateRow,

package/src/store/sqlite/schema.sql

@@ -122,6 +122,15 @@ CREATE INDEX IF NOT EXISTS idx_entities_store_action ON entities (
   json_extract(CASE WHEN json_valid(data) THEN data ELSE '{}' END, '$.entity_id'),
   json_extract(CASE WHEN json_valid(data) THEN data ELSE '{}' END, '$.timestamp')
 );
+-- The public register's certificate-number lookup (migration 0028, the
+-- seam's findCertificatesByNumber): (store, certificate_number) out of
+-- the data JSON, COLLATE NOCASE for the register's case-insensitive
+-- number match, so the keyed read is an index walk instead of a
+-- listEntities scan + per-row JSON parse. The same json_valid guard.
+CREATE INDEX IF NOT EXISTS idx_entities_store_certificate_number ON entities (
+  store,
+  json_extract(CASE WHEN json_valid(data) THEN data ELSE '{}' END, '$.certificate_number') COLLATE NOCASE
+);
 
 -- The change journal: every write appends (seq, store, type, id) —
 -- the SSE stream tails it (each client filters its stores).
@@ -149,7 +158,12 @@ CREATE INDEX IF NOT EXISTS idx_entity_changes_store_seq ON entity_changes (store
 -- envelope (the summary line, the deep link, the actors, the entity's
 -- store for the read-time visibility gate). seq is the feed cursor;
 -- written inside the acting request's envelope, never blocking the
--- triggering flow (the mailer doctrine).
+-- triggering flow (the mailer doctrine). mentions (migration 0027,
+-- TODO.notify/05's remainders) is the act's @user mentions as a JSON
+-- array of user ids, resolved by the comment surfaces' parse at event
+-- time and recorded ON THE ROW — a mention is a fact of the act, never
+-- re-derivable from the entity at the feed's read-time computation.
+-- NULL = none.
 CREATE TABLE IF NOT EXISTS events (
   seq INTEGER PRIMARY KEY AUTOINCREMENT,
   id TEXT UNIQUE NOT NULL,
@@ -157,6 +171,7 @@ CREATE TABLE IF NOT EXISTS events (
   entity_id TEXT NOT NULL,
   action TEXT NOT NULL,
   payload TEXT NOT NULL,
+  mentions TEXT,
   at TEXT NOT NULL DEFAULT (datetime('now'))
 );
 CREATE INDEX IF NOT EXISTS idx_events_domain_entity ON events (domain, entity_id);
@@ -219,7 +234,10 @@ CREATE TABLE IF NOT EXISTS notify_preferences (
 -- TODO.notify/03 — the inbox state: the per-user per-event read markers
 -- (migration 0014). One row per (user, event), written lazily at the
 -- first act on the inbox row: read_at stamps the mark-read, done_at the
--- archive (a done row leaves the feed; the marker keeps the state). The
+-- archive (a done row leaves the feed; the marker keeps the state),
+-- saved_at the per-event saved flag (migration 0027, TODO.notify/05's
+-- remainders — the GitHub Save, independent of read/done: a saved row
+-- that is done stays saved in the archive). The
 -- feed itself is COMPUTED at read (events × the user's rules × the
 -- visibility gate) — this table is the state the computation joins, and
 -- a marker on a wiped event simply never joins (the user's state is
@@ -233,6 +251,7 @@ CREATE TABLE IF NOT EXISTS notify_inbox_state (
   event_id TEXT NOT NULL,
   read_at TEXT,
   done_at TEXT,
+  saved_at TEXT,
   created_at TEXT NOT NULL DEFAULT (datetime('now')),
   PRIMARY KEY (user_id, event_id)
 );

package/src/store/sqlite/store.ts

@@ -154,6 +154,18 @@ function migrateAuthTables(db: Database.Database): void {
   if (emailChangeCols.length && !emailChangeCols.some(c => c.name === 'kind')) {
     db.exec("ALTER TABLE email_change_tokens ADD COLUMN kind TEXT NOT NULL DEFAULT 'change'")
   }
+  // TODO.notify/05's remainders (migration 0027): the event row's
+  // mentions column + the inbox marker's saved_at stamp — a dev file
+  // predating it grows the columns here. NULL = none / unsaved: existing
+  // rows keep their posture silently.
+  const eventCols = db.prepare('PRAGMA table_info(events)').all() as Array<{ name: string }>
+  if (eventCols.length && !eventCols.some(c => c.name === 'mentions')) {
+    db.exec('ALTER TABLE events ADD COLUMN mentions TEXT')
+  }
+  const inboxCols = db.prepare('PRAGMA table_info(notify_inbox_state)').all() as Array<{ name: string }>
+  if (inboxCols.length && !inboxCols.some(c => c.name === 'saved_at')) {
+    db.exec('ALTER TABLE notify_inbox_state ADD COLUMN saved_at TEXT')
+  }
 }
 
 // AuthUserPayload lives in ./backend (see the re-export above).

package/src/store/sqlite.ts

@@ -83,10 +83,12 @@ import {
 import {
   changesAfter,
   deleteEntity,
+  findCertificatesByNumber,
   getEntity,
   latestChangeSeq,
   latestChangeSeqFor,
   listEntities,
+  onJournalAppend,
   putEntities,
   putEntity,
 } from './sqlite/entities'
@@ -96,6 +98,7 @@ import {
   eventsAfter,
   eventsMatching,
   getEvent,
+  getEvents,
   latestEventSeq,
 } from './sqlite/events'
 import {
@@ -191,7 +194,7 @@ import {
   updateOpAccount,
   updateUserName,
 } from './sqlite/op-accounts-store'
-import { installStore, type AccountEmail, type AddAccountEmailResult, type AuthUserPayload, type CertificateHolderClaim, type CertificateHolderOrg, type CompleteEmailChangeResult, type CompleteEnrollmentResult, type ConsumeOidcRefreshTokenResult, type EmailChangeToken, type EnrollmentToken, type EntityChange, type EntityRow, type EntityWriteInput, type EventEntityKey, type EventKeyFilter, type EventWriteInput, type FederationPeer, type IdentityApproval, type IdentityLink, type IdentityProvider, type InstrumentRegistration, type InstrumentRegistrationLifecycle, type InstrumentRegistrationScopeStatus, type InstrumentRegistrationWriteInput, 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 OidcConsentGrant, type OidcKeyRow, type OidcRefreshToken, type OpAccountErasure, type OpClientRoleAssignment, type OpLiveSession, type OrgJoinRequest, type OrgMembership, type OrgMembershipState, type OrgRegistryContact, type OrgRegistryOrg, type OrgRegistryState, type PersonalAccessToken, 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 AccountEmail, type AddAccountEmailResult, type AuthUserPayload, type CertificateHolderClaim, type CertificateHolderOrg, type CompleteEmailChangeResult, type CompleteEnrollmentResult, type ConsumeOidcRefreshTokenResult, type EmailChangeToken, type EnrollmentToken, type EntityChange, type EntityRow, type EntityWriteInput, type EventEntityKey, type EventKeyFilter, type EventWriteInput, type FederationPeer, type IdentityApproval, type IdentityLink, type IdentityProvider, type InstrumentRegistration, type InstrumentRegistrationLifecycle, type InstrumentRegistrationScopeStatus, type InstrumentRegistrationWriteInput, type JournalAppend, 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 OidcConsentGrant, type OidcKeyRow, type OidcRefreshToken, type OpAccountErasure, type OpClientRoleAssignment, type OpLiveSession, type OrgJoinRequest, type OrgMembership, type OrgMembershipState, type OrgRegistryContact, type OrgRegistryOrg, type OrgRegistryState, type PersonalAccessToken, 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,
@@ -1018,6 +1021,9 @@ export function createSqliteServerStore(): ServerStore {
     async getEntity(store: string, id: string): Promise<EntityRow | undefined> {
       return getEntity(store, id)
     },
+    async findCertificatesByNumber(number: string): Promise<EntityRow[]> {
+      return findCertificatesByNumber(number)
+    },
     async putEntity(store: string, id: string, orgId: string | null, data: string): Promise<void> {
       putEntity(store, id, orgId, data)
     },
@@ -1036,6 +1042,9 @@ export function createSqliteServerStore(): ServerStore {
     async latestChangeSeqFor(store: string): Promise<number> {
       return latestChangeSeqFor(store)
     },
+    onJournalAppend(listener: (appends: readonly JournalAppend[]) => void): () => void {
+      return onJournalAppend(listener)
+    },
 
     // ── the platform event store (TODO.notify/01) ──
     async appendEvent(input: EventWriteInput): Promise<PlatformEvent> {
@@ -1053,6 +1062,9 @@ export function createSqliteServerStore(): ServerStore {
     async getEvent(id: string): Promise<PlatformEvent | null> {
       return getEvent(id)
     },
+    async getEvents(ids: readonly string[]): Promise<(PlatformEvent | null)[]> {
+      return getEvents(ids)
+    },
     async eventsMatching(filter: EventKeyFilter | { keys: readonly EventEntityKey[] }, limit = 500): Promise<PlatformEvent[]> {
       return eventsMatching(filter, limit)
     },

package/src/store.ts

@@ -175,6 +175,16 @@ export interface EntityChange {
   at: string
 }
 
+/** The journal fan-out's payload (onJournalAppend): the (store, type,
+ *  id) triple one entity_changes row carries. seq/at are the
+ *  database's (the write path never reads them back) — the consumer
+ *  re-reads via changesAfter from its own cursor. */
+export interface JournalAppend {
+  store: string
+  type: 'persist' | 'remove'
+  id: string
+}
+
 /** One row of the multi-row write (putEntities): putEntity's (id,
  *  orgId, data) legs — the store is the call's, once for the whole
  *  batch. */
@@ -206,7 +216,12 @@ export const PUT_ENTITIES_CHUNK = 50
  *  composed key is derived at read, never stored. `payload` is the JSON
  *  envelope the catalog row declares (the summary line, the deep link,
  *  the actors, the entity's store for the read-time visibility gate).
- *  `seq` is the feed cursor (the entity_changes journal's pattern). */
+ *  `mentions` (migration 0027, TODO.notify/05's remainders) is the act's
+ *  @user mentions as a JSON array of user ids — the comment surfaces'
+ *  parse resolves them at event time and records them ON THE ROW (a
+ *  mention is a fact of the act; the feed's read-time reason computation
+ *  could never re-derive it from the entity). NULL = none. `seq` is the
+ *  feed cursor (the entity_changes journal's pattern). */
 export interface PlatformEvent {
   seq: number
   id: string
@@ -214,6 +229,9 @@ export interface PlatformEvent {
   entityId: string
   action: string
   payload: string
+  /** The mentioned user ids' JSON array (raw, the payload/channelOverrides
+   *  posture — the consumer parses); NULL = no mentions. */
+  mentions: string | null
   at: string
 }
 
@@ -226,6 +244,9 @@ export interface EventWriteInput {
   entityId: string
   action: string
   payload: string
+  /** The act's mentioned user ids (JSON array; TODO.notify/05's
+   *  remainders) — absent/NULL lands NULL (no mentions). */
+  mentions?: string | null
 }
 
 /** The key pattern's SQL legs: a subscription pattern (`application/**`,
@@ -254,6 +275,14 @@ export interface EventEntityKey {
  *  backends stay answer-identical. */
 export const EVENTS_BULK_KEY_CHUNK = 49
 
+/** The bulk by-id read's statement chunk (getEvents): D1 caps a
+ *  statement at 100 bound parameters and the IN list binds ONE per id
+ *  (no limit parameter — the answer size is the matched-id count), so
+ *  a bulk call issues ceil(ids / 99) statements — ONE for any
+ *  realistic digest window — never one per id. The SQLite half chunks
+ *  identically so the two backends stay answer-identical. */
+export const EVENTS_ID_CHUNK = 99
+
 /** The bulk append's chunk, in ROWS (appendEvents): each event
  *  contributes ONE statement (the INSERT … RETURNING * answers the
  *  stored row off the write itself, the appendEvent halving), so a
@@ -330,7 +359,10 @@ export interface NotifyPreferences {
  *  lazily at read"): one row per (user, event), created at the first act
  *  on the inbox row. `readAt` stamps the mark-read (NULL = unread);
  *  `doneAt` stamps the archive (NULL = in the inbox — a done row leaves
- *  the feed, the marker keeps the state). 'saved' joins with wave 05.
+ *  the feed, the marker keeps the state); `savedAt` (migration 0027,
+ *  TODO.notify/05's remainders) stamps the per-event saved flag — the
+ *  GitHub Save, independent of read/done (a saved row that is done stays
+ *  saved in the archive).
  *  The feed is COMPUTED at read (events × the user's rules × the
  *  visibility gate); this table is the state that computation joins. A
  *  marker on a wiped event never joins (the user's state is their own,
@@ -340,6 +372,7 @@ export interface NotifyInboxState {
   eventId: string
   readAt: string | null
   doneAt: string | null
+  savedAt: string | null
   createdAt: string
 }
 
@@ -2455,6 +2488,22 @@ export interface ServerStore {
    *  migration 0023's expression index flipped the unnamed walk). */
   listEntities(store: string): Promise<EntityRow[]>
   getEntity(store: string, id: string): Promise<EntityRow | undefined>
+  /** The public register's certificate-number lookup (the verify
+   *  surfaces' keyed read — the 2026-09-07 performance audit's
+   *  public-lookup seam): the register resolved a number by
+   *  full-scanning listEntities('certificates') and JSON-parsing every
+   *  row to case-fold certificate_number — O(store rows) per lookup.
+   *  The keyed read walks idx_entities_store_certificate_number
+   *  (migration 0028): the json_valid-guarded extract, COLLATE NOCASE
+   *  (the register's number match is case-insensitive; the fold is
+   *  ASCII, the number grammar's alphabet). Answers every match in the
+   *  seam's list order (org_id, rowid), so the first match IS the
+   *  retiring scan's first match. The statement INDEXED BY-pins the
+   *  walk: a database behind migration 0028 errors honestly, never
+   *  scans silently. The hardcoded store name follows the
+   *  lastAccountSignIns 'auditEvents' precedent — the read's semantics
+   *  ARE the consumer's data convention. */
+  findCertificatesByNumber(number: string): Promise<EntityRow[]>
   putEntity(store: string, id: string, orgId: string | null, data: string): Promise<void>
   /** The MULTI-ROW write (the 2026-09-07 performance audit's J1 — the
    *  CSV registration commit awaited putEntity per imported row, ~10⁴
@@ -2501,6 +2550,21 @@ export interface ServerStore {
    *  audit's G1: the smart side's bootstrap composite ETag switches
    *  from the global seq to the per-set composite of these. */
   latestChangeSeqFor(store: string): Promise<number>
+  /** The journal fan-out (the SSE stream's true-push wake): registers a
+   *  listener on the ISOLATE-scope registry — every entity_changes
+   *  append landing in THIS isolate (putEntity's entry, each putEntities
+   *  chunk's entries as the chunk lands, deleteEntity's remove) fires it
+   *  synchronously AFTER the write stands, with the appended (store,
+   *  type, id) triples in the write's input order. The answer is the
+   *  unregister (idempotent).
+   *
+   *  The honesty boundary: the journal's source of truth is the
+   *  DATABASE — a write landing in ANOTHER isolate (a sibling Worker)
+   *  never fires this isolate's listeners, so a consumer keeps its poll
+   *  as the fallback and treats the fan-out as a wake-up hint, never a
+   *  correctness channel. A listener's throw is swallowed per listener:
+   *  the write path never breaks for a listener. */
+  onJournalAppend(listener: (appends: readonly JournalAppend[]) => void): () => void
 
   // ── the platform event store (TODO.notify/01) ──
   /** Append one declared event (the emitter's write; one row inside the
@@ -2530,6 +2594,17 @@ export interface ServerStore {
   /** The by-id read (the inbox state write's guard — TODO.notify/03: a
    *  marker lands only on an event that exists and is the caller's). */
   getEvent(id: string): Promise<PlatformEvent | null>
+  /** The BULK by-id read (the notify digest's event join): the digest
+   *  run awaited getEvent once per queued delivery row — N serial round
+   *  trips for N rows. The bulk form resolves every id in ONE statement
+   *  per chunk of EVENTS_ID_CHUNK ids (the IN walk against the id UNIQUE
+   *  index; never a compound SELECT — the D1 5-term cap rule).
+   *
+   *  The answer contract: INPUT-ALIGNED — position i answers the row for
+   *  ids[i], null where no event carries the id (exactly the per-id
+   *  getEvent loop's answers; a duplicate id answers its row at every
+   *  position). An empty list answers [] without issuing a statement. */
+  getEvents(ids: readonly string[]): Promise<(PlatformEvent | null)[]>
   /** The subscription grammar's SQL resolution: the columns the pattern
    *  pins, equality-matched (`WHERE domain = ? AND entity_id = ?` — the
    *  column split's whole point, never a string scan on a composed key). */
@@ -2593,17 +2668,20 @@ export interface ServerStore {
   putNotifyPreferences(userId: string, channels: string): Promise<NotifyPreferences>
 
   // ── the inbox state (TODO.notify/03) ──
-  /** The user's inbox markers (the feed's join: read/done per event).
-   *  Written lazily at the first act — most events carry no row. */
+  /** The user's inbox markers (the feed's join: read/done/saved per
+   *  event). Written lazily at the first act — most events carry no row. */
   listNotifyInboxStates(userId: string): Promise<NotifyInboxState[]>
   /** The marker write (the upsert on PRIMARY KEY (user_id, event_id)):
    *  each PRESENT flag sets its stamp (datetime('now')) or clears it
-   *  (NULL); absent flags keep. Answers the stored row. */
+   *  (NULL); absent flags keep. `saved` (migration 0027, TODO.notify/05's
+   *  remainders) is the per-event saved flag, the same stamp/clear
+   *  posture. Answers the stored row. */
   putNotifyInboxState(input: {
     userId: string
     eventId: string
     read?: boolean
     done?: boolean
+    saved?: boolean
   }): Promise<NotifyInboxState>
 
   // ── the email channel's delivery store (TODO.notify/04) ──