@oimlsmart/platform-server 0.2.12 → 0.2.14

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.12",
+  "version": "0.2.14",
   "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,
@@ -46,6 +47,7 @@ import {
   type EmailChangeToken,
   type EnrollmentToken,
   type EntityChange,
+  type EntityListOptions,
   type EntityRow,
   type EntityWriteInput,
   type EventEntityKey,
@@ -88,6 +90,7 @@ import {
   type InstrumentRegistrationLifecycle,
   type InstrumentRegistrationScopeStatus,
   type InstrumentRegistrationWriteInput,
+  type JournalAppend,
   type PersonalAccessToken,
   type PlatformEvent,
   resolveOrgContext,
@@ -427,6 +430,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
@@ -3503,7 +3543,7 @@ export class D1ServerStore implements ServerStore {
 
   // ── the workflow entity store + change journal ───────────────────
 
-  async listEntities(store: string): Promise<EntityRow[]> {
+  async listEntities(store: string, options?: EntityListOptions): Promise<EntityRow[]> {
     // The ORDER BY is the seam's contract (the 0.2.3 pin): the answer
     // arrives in (org_id, rowid) order — the read's observable order
     // since migration 0001, when the planner walked
@@ -3512,6 +3552,19 @@ export class D1ServerStore implements ServerStore {
     // insertion (the smart app's render-baseline red, oimlsmart/smart
     // PR #264) — a list read's order is a consumer-visible contract,
     // never the planner's pick.
+    // options.orgId narrows the candidate set (the seam's EntityListOptions
+    // — the portal-load audit's R3-fix3): the kept groups (NULL stamps,
+    // then the named org) are the two lowest org_id buckets, so the
+    // filtered ORDER BY is the unfiltered order's restriction to the
+    // candidates — a gate-driven projection of either answer is
+    // byte-identical.
+    if (options?.orgId) {
+      const res = await this.stmt(
+        'SELECT store, id, org_id, data, updated_at FROM entities WHERE store = ? AND (org_id = ? OR org_id IS NULL) ORDER BY org_id, rowid',
+        store, options.orgId,
+      ).all<EntityRow>()
+      return res.results
+    }
     const res = await this.stmt(
       'SELECT store, id, org_id, data, updated_at FROM entities WHERE store = ? ORDER BY org_id, rowid', store,
     ).all<EntityRow>()
@@ -3525,6 +3578,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
@@ -3533,6 +3591,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> {
@@ -3555,6 +3614,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 })))
     }
   }
 
@@ -3563,6 +3626,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
   }
@@ -3589,6 +3653,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.
@@ -3659,6 +3728,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

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, EntityListOptions, 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,12 +54,38 @@ 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 (?, ?, ?)'
 
-export function listEntities(store: string): EntityRow[] {
+/** 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, options?: EntityListOptions): 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
   // migration 0001's idx_entities_store_org walk, made planner-proof
   // when migration 0023's expression index offered a second
   // store-prefixed plan.
+  // options.orgId narrows the candidate set (the seam's EntityListOptions
+  // — the portal-load audit's R3-fix3): the kept groups (NULL stamps,
+  // then the named org) are the two lowest org_id buckets, so the
+  // filtered ORDER BY is the unfiltered order's restriction to the
+  // candidates — a gate-driven projection of either answer is
+  // byte-identical.
+  if (options?.orgId) {
+    return getDb()
+      .prepare('SELECT store, id, org_id, data, updated_at FROM entities WHERE store = ? AND (org_id = ? OR org_id IS NULL) ORDER BY org_id, rowid')
+      .all(store, options.orgId) as EntityRow[]
+  }
   return getDb()
     .prepare('SELECT store, id, org_id, data, updated_at FROM entities WHERE store = ? ORDER BY org_id, rowid')
     .all(store) as EntityRow[]
@@ -45,6 +97,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 +110,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 +133,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 +150,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
@@ -94,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/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).

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 EntityListOptions, 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,
@@ -1012,12 +1015,15 @@ export function createSqliteServerStore(): ServerStore {
     },
 
     // ── the workflow entity store + change journal ──
-    async listEntities(store: string): Promise<EntityRow[]> {
-      return listEntities(store)
+    async listEntities(store: string, options?: EntityListOptions): Promise<EntityRow[]> {
+      return listEntities(store, options)
     },
     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

@@ -138,6 +138,29 @@ export interface EntityRow {
   updated_at: string
 }
 
+/** listEntities' candidate narrowing (the 2026-09-01 portal-load audit,
+ *  R3-fix3): the entities table carries an indexed org_id column
+ *  (idx_entities_store_org, migration 0001) that reads never used —
+ *  every list scanned the whole store and left the org cone to the
+ *  consumer's per-row gate. */
+export interface EntityListOptions {
+  /** Narrow the CANDIDATE set to the rows stamped under this org (org_id
+   *  = the value — orgIdOf's first-org-field stamp, or the writer's own
+   *  org on the stamping write paths) PLUS the unstamped rows (org_id IS
+   *  NULL — a stamp-less row is never excluded: the stamp's absence says
+   *  nothing about the row's cone). A candidate filter, NEVER a
+   *  visibility decision: which rows of the narrowed set answer is the
+   *  consumer's in-memory gate, authoritative as before. The consumer
+   *  enables the filter only where its gate provably denies every row
+   *  the filter drops (the per-store verification rides the consumer's
+   *  change — org_id stamps the FIRST org field, so multi-org-field
+   *  stores are never narrowed). The answer keeps the seam's declared
+   *  order: (org_id, rowid) over the kept rows — the unfiltered order's
+   *  restriction to the candidate set, so a gate-driven projection of
+   *  either answer is byte-identical. */
+  orgId?: string
+}
+
 // ── federation peers (TODO.federation/04) ────────────────────────────
 
 /** A pinned federation peer: the counterparty instance's descriptor,
@@ -175,6 +198,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. */
@@ -265,6 +298,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
@@ -2467,9 +2508,28 @@ export interface ServerStore {
    *  first, then by org id, then by insertion). Both backends spell the
    *  ORDER BY explicitly — a list read's order is a consumer-visible
    *  contract, never the planner's pick (the 0.2.3 pin, after
-   *  migration 0023's expression index flipped the unnamed walk). */
-  listEntities(store: string): Promise<EntityRow[]>
+   *  migration 0023's expression index flipped the unnamed walk).
+   *  `options.orgId` narrows the candidate set in SQL (EntityListOptions
+   *  — the portal-load audit's R3-fix3); the narrowed answer is the same
+   *  order's restriction to the candidates. */
+  listEntities(store: string, options?: EntityListOptions): 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⁴
@@ -2516,6 +2576,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
@@ -2545,6 +2620,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). */