@oimlsmart/platform-server 0.2.1 → 0.2.3

package/migrations/0023_entities_action_index.sql

@@ -0,0 +1,24 @@
+-- The 2026-09-06 performance audit's audit-chain read: the OP console's
+-- last-sign-in-per-account read (lastAccountSignIns) string-matched
+-- EVERY auditEvents row's data blob (two data LIKE '%…%' clauses —
+-- O(journal) per call, degrading as the journal grows). The auditEvents
+-- rows are entities rows whose data JSON carries the typed legs
+-- (action, entity_id, timestamp), so the read compiles to json_extract
+-- equality — and this expression index makes it a walk over the
+-- (store, action) slice instead of the journal: only the sign-in rows
+-- are ever visited.
+--
+-- The json_valid GUARD is load-bearing: an unguarded json_extract index
+-- expression RAISES 'malformed JSON' on any corrupt entities row —
+-- the corrupt row would become unwritable, and the unguarded query
+-- would throw where the retired LIKE fold skipped. The CASE guard
+-- lands the corrupt row's legs at NULL (indexed, never matched); the
+-- query spells the identical expression so the planner proves the
+-- index applies. Expand-only per the migration contract; schema.sql's
+-- mirror lands in the same commit.
+CREATE INDEX IF NOT EXISTS idx_entities_store_action ON entities (
+  store,
+  json_extract(CASE WHEN json_valid(data) THEN data ELSE '{}' END, '$.action'),
+  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')
+);

package/package.json

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

@@ -31,6 +31,7 @@
 import type { D1Database, D1PreparedStatement } from '@cloudflare/workers-types'
 import {
   DEMO_PASSWORD,
+  EVENTS_BULK_KEY_CHUNK,
   StoreUnavailable,
   type AccountEmail,
   type AddAccountEmailResult,
@@ -42,6 +43,7 @@ import {
   type EnrollmentToken,
   type EntityChange,
   type EntityRow,
+  type EventEntityKey,
   type EventKeyFilter,
   type FederationPeer,
   type IdentityApproval,
@@ -1931,22 +1933,30 @@ export class D1ServerStore implements ServerStore {
 
   /** The last OP-side sign-in per account, FROM THE AUDIT CHAIN: the
    *  newest auditEvents row whose action is a sign-in
-   *  ('account.sign_in' / 'upstream_sign_in') per entity_id. */
+   *  ('account.sign_in' / 'upstream_sign_in') per entity_id. The typed
+   *  read (the 2026-09-06 audit): the legs come out of the data JSON by
+   *  json_extract against idx_entities_store_action (migration 0023) —
+   *  the sign-in slice is an index walk, never the O(journal) data-LIKE
+   *  scan. The json_valid guard spells the index's expression exactly
+   *  (a corrupt entities row answers NULL legs, never a raised
+   *  'malformed JSON'). The action match stays exact (the retired
+   *  LIKE's closing quote made it so too) — and now spelling-proof:
+   *  the legs parse the JSON, so a serialized-with-spaces row answers
+   *  and an embedded lookalike substring never does. */
   async lastAccountSignIns(): Promise<Record<string, string>> {
     const res = await this.stmt(
-      `SELECT data FROM entities
+      `SELECT json_extract(CASE WHEN json_valid(data) THEN data ELSE '{}' END, '$.entity_id') AS entity_id,
+              MAX(json_extract(CASE WHEN json_valid(data) THEN data ELSE '{}' END, '$.timestamp')) AS ts
+       FROM entities
        WHERE store = 'auditEvents'
-         AND (data LIKE '%"action":"account.sign_in"%' OR data LIKE '%"action":"upstream_sign_in"%')`,
-    ).all<{ data: string }>()
+         AND json_extract(CASE WHEN json_valid(data) THEN data ELSE '{}' END, '$.action') IN ('account.sign_in', 'upstream_sign_in')
+       GROUP BY json_extract(CASE WHEN json_valid(data) THEN data ELSE '{}' END, '$.entity_id')`,
+    ).all<{ entity_id: string | null; ts: string | null }>()
     const out: Record<string, string> = {}
-    for (const { data } of res.results) {
-      try {
-        const event = JSON.parse(data) as { entity_id?: string; timestamp?: string }
-        if (typeof event.entity_id !== 'string' || typeof event.timestamp !== 'string') continue
-        if (!out[event.entity_id] || event.timestamp > out[event.entity_id]!) {
-          out[event.entity_id] = event.timestamp
-        }
-      } catch { /* a malformed audit row is skipped, never trusted */ }
+    for (const { entity_id, ts } of res.results) {
+      // A row missing either leg (the malformed audit row) is skipped,
+      // never trusted — the same posture the JSON fold held.
+      if (typeof entity_id === 'string' && typeof ts === 'string') out[entity_id] = ts
     }
     return out
   }
@@ -3225,8 +3235,16 @@ export class D1ServerStore implements ServerStore {
   // ── the workflow entity store + change journal ───────────────────
 
   async listEntities(store: string): 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
+    // idx_entities_store_org. Migration 0023's expression index offered
+    // a second store-prefixed walk and the unnamed order flipped to
+    // 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.
     const res = await this.stmt(
-      'SELECT store, id, org_id, data, updated_at FROM entities WHERE store = ?', store,
+      'SELECT store, id, org_id, data, updated_at FROM entities WHERE store = ? ORDER BY org_id, rowid', store,
     ).all<EntityRow>()
     return res.results
   }
@@ -3296,11 +3314,14 @@ export class D1ServerStore implements ServerStore {
     action: string
     payload: string
   }): Promise<PlatformEvent> {
-    await this.stmt(
-      'INSERT INTO events (id, domain, entity_id, action, payload) VALUES (?, ?, ?, ?, ?)',
+    // ONE round trip: the RETURNING clause (SQLite ≥ 3.35, D1 included)
+    // answers the stored row — seq + the default at — off the INSERT
+    // itself; the SELECT-by-id read-back retired (the 2026-09-06 audit:
+    // two round trips per event, halved).
+    const row = await this.stmt(
+      'INSERT INTO events (id, domain, entity_id, action, payload) VALUES (?, ?, ?, ?, ?) RETURNING *',
       input.id, input.domain, input.entityId, input.action, input.payload,
-    ).run()
-    const row = await this.stmt('SELECT * FROM events WHERE id = ?', input.id).first<Record<string, unknown>>()
+    ).first<Record<string, unknown>>()
     return D1ServerStore.toPlatformEvent(row!)
   }
 
@@ -3322,8 +3343,28 @@ export class D1ServerStore implements ServerStore {
   }
 
   /** The subscription grammar's SQL resolution: the pinned columns match
-   *  by equality; the free legs stay out of the WHERE. */
-  async eventsMatching(filter: EventKeyFilter, limit = 500): Promise<PlatformEvent[]> {
+   *  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, entityId) pair in ONE statement per EVENTS_BULK_KEY_CHUNK
+   *  keys — the OR-of-ANDs WHERE walks idx_events_domain_entity per term
+   *  (never a compound SELECT: the D1 5-term cap rule) — and answers the
+   *  MERGED set, seq-ordered, limit-truncated after the merge. */
+  async eventsMatching(filter: EventKeyFilter | { keys: readonly EventEntityKey[] }, limit = 500): Promise<PlatformEvent[]> {
+    if ('keys' in filter) {
+      if (filter.keys.length === 0) return []
+      const merged: PlatformEvent[] = []
+      for (let i = 0; i < filter.keys.length; i += EVENTS_BULK_KEY_CHUNK) {
+        const chunk = filter.keys.slice(i, i + EVENTS_BULK_KEY_CHUNK)
+        const where = chunk.map(() => '(domain = ? AND entity_id = ?)').join(' OR ')
+        const args = chunk.flatMap(k => [k.domain, k.entityId])
+        const res = await this.stmt(
+          `SELECT * FROM events WHERE ${where} ORDER BY seq LIMIT ?`, ...args, limit,
+        ).all<Record<string, unknown>>()
+        merged.push(...res.results.map(D1ServerStore.toPlatformEvent))
+      }
+      merged.sort((a, b) => a.seq - b.seq)
+      return merged.slice(0, limit)
+    }
     const where: string[] = []
     const args: unknown[] = []
     if (filter.domain !== undefined) { where.push('domain = ?'); args.push(filter.domain) }

package/src/store/sqlite/entities.ts

@@ -21,8 +21,13 @@ export { ORG_FIELDS, CATALOG_STORES, orgIdOf } from '../../store'
 import type { EntityRow, EntityChange } from '../../store'
 
 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
+  // migration 0001's idx_entities_store_org walk, made planner-proof
+  // when migration 0023's expression index offered a second
+  // store-prefixed plan.
   return getDb()
-    .prepare('SELECT store, id, org_id, data, updated_at FROM entities WHERE store = ?')
+    .prepare('SELECT store, id, org_id, data, updated_at FROM entities WHERE store = ? ORDER BY org_id, rowid')
     .all(store) as EntityRow[]
 }
 

package/src/store/sqlite/events.ts

@@ -9,7 +9,7 @@
 // ═══════════════════════════════════════════════════════════════════
 
 import { getDb } from './store'
-import type { EventKeyFilter, PlatformEvent } from '../../store'
+import { EVENTS_BULK_KEY_CHUNK, type EventEntityKey, type EventKeyFilter, type PlatformEvent } from '../../store'
 
 interface EventRow {
   seq: number
@@ -40,12 +40,12 @@ export function appendEvent(input: {
   action: string
   payload: string
 }): PlatformEvent {
-  const db = getDb()
-  db.prepare(
-    `INSERT INTO events (id, domain, entity_id, action, payload) VALUES (?, ?, ?, ?, ?)`,
-  ).run(input.id, input.domain, input.entityId, input.action, input.payload)
+  // ONE statement: RETURNING answers the stored row (seq + the default
+  // at) off the INSERT itself — the same halving as the D1 half.
   return toPlatformEvent(
-    db.prepare('SELECT * FROM events WHERE id = ?').get(input.id) as EventRow,
+    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,
   )
 }
 
@@ -69,8 +69,28 @@ export function getEvent(id: string): PlatformEvent | null {
 }
 
 /** The subscription grammar's SQL resolution: the pinned columns match
- *  by equality; the free legs stay out of the WHERE. */
-export function eventsMatching(filter: EventKeyFilter, limit = 500): PlatformEvent[] {
+ *  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,
+ *  entityId) pair in ONE statement per EVENTS_BULK_KEY_CHUNK keys — the
+ *  same chunking as the D1 half, so the backends stay answer-identical —
+ *  and answers the MERGED set, seq-ordered, limit-truncated after the
+ *  merge. */
+export function eventsMatching(filter: EventKeyFilter | { keys: readonly EventEntityKey[] }, limit = 500): PlatformEvent[] {
+  if ('keys' in filter) {
+    if (filter.keys.length === 0) return []
+    const merged: PlatformEvent[] = []
+    for (let i = 0; i < filter.keys.length; i += EVENTS_BULK_KEY_CHUNK) {
+      const chunk = filter.keys.slice(i, i + EVENTS_BULK_KEY_CHUNK)
+      const where = chunk.map(() => '(domain = ? AND entity_id = ?)').join(' OR ')
+      const args = chunk.flatMap(k => [k.domain, k.entityId])
+      const rows = getDb()
+        .prepare(`SELECT * FROM events WHERE ${where} ORDER BY seq LIMIT ?`)
+        .all(...args, limit) as EventRow[]
+      merged.push(...rows.map(toPlatformEvent))
+    }
+    merged.sort((a, b) => a.seq - b.seq)
+    return merged.slice(0, limit)
+  }
   const where: string[] = []
   const args: unknown[] = []
   if (filter.domain !== undefined) { where.push('domain = ?'); args.push(filter.domain) }

package/src/store/sqlite/op-accounts-store.ts

@@ -406,22 +406,27 @@ export function eraseOpAccount(userId: string): {
 /** The last OP-side sign-in per account, FROM THE AUDIT CHAIN: the
  *  newest auditEvents row whose action is a sign-in ('account.sign_in'
  *  — the password login; 'upstream_sign_in' — a linked-provider
- *  sign-in) per entity_id (the account id). */
+ *  sign-in) per entity_id (the account id). The typed read (the
+ *  2026-09-06 audit): json_extract against idx_entities_store_action —
+ *  an index walk over the sign-in slice, never the O(journal)
+ *  data-LIKE scan; the json_valid guard spells the index's expression
+ *  exactly (a corrupt entities row answers NULL legs, never a raised
+ *  'malformed JSON'). The action match stays exact (the retired LIKE's
+ *  closing quote made it so too) — and now spelling-proof: the legs
+ *  parse the JSON, so a serialized-with-spaces row answers and an
+ *  embedded lookalike substring never does. */
 export function lastAccountSignIns(): Record<string, string> {
   const rows = getDb().prepare(
-    `SELECT data FROM entities
+    `SELECT json_extract(CASE WHEN json_valid(data) THEN data ELSE '{}' END, '$.entity_id') AS entity_id,
+            MAX(json_extract(CASE WHEN json_valid(data) THEN data ELSE '{}' END, '$.timestamp')) AS ts
+     FROM entities
      WHERE store = 'auditEvents'
-       AND (data LIKE '%"action":"account.sign_in"%' OR data LIKE '%"action":"upstream_sign_in"%')`,
-  ).all() as Array<{ data: string }>
+       AND json_extract(CASE WHEN json_valid(data) THEN data ELSE '{}' END, '$.action') IN ('account.sign_in', 'upstream_sign_in')
+     GROUP BY json_extract(CASE WHEN json_valid(data) THEN data ELSE '{}' END, '$.entity_id')`,
+  ).all() as Array<{ entity_id: string | null; ts: string | null }>
   const out: Record<string, string> = {}
-  for (const { data } of rows) {
-    try {
-      const event = JSON.parse(data) as { entity_id?: string; timestamp?: string }
-      if (typeof event.entity_id !== 'string' || typeof event.timestamp !== 'string') continue
-      if (!out[event.entity_id] || event.timestamp > out[event.entity_id]!) {
-        out[event.entity_id] = event.timestamp
-      }
-    } catch { /* a malformed audit row is skipped, never trusted */ }
+  for (const { entity_id, ts } of rows) {
+    if (typeof entity_id === 'string' && typeof ts === 'string') out[entity_id] = ts
   }
   return out
 }

package/src/store/sqlite/schema.sql

@@ -110,6 +110,18 @@ CREATE TABLE IF NOT EXISTS entities (
   PRIMARY KEY (store, id)
 );
 CREATE INDEX IF NOT EXISTS idx_entities_store_org ON entities (store, org_id);
+-- The audit chain's typed legs (the 2026-09-06 audit's sign-in recency
+-- read — migration 0023): (store, action, entity_id, timestamp) out of
+-- the data JSON, so the per-account last-sign-in read walks the
+-- sign-in slice instead of string-matching the journal. The json_valid
+-- guard keeps a corrupt entities row writable (an unguarded
+-- json_extract index expression would raise on the INSERT).
+CREATE INDEX IF NOT EXISTS idx_entities_store_action ON entities (
+  store,
+  json_extract(CASE WHEN json_valid(data) THEN data ELSE '{}' END, '$.action'),
+  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 change journal: every write appends (seq, store, type, id) —
 -- the SSE stream tails it (each client filters its stores).

package/src/store/sqlite.ts

@@ -179,7 +179,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 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 OidcConsentGrant, type OidcKeyRow, 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 EmailChangeToken, type EnrollmentToken, type EntityChange, type EntityRow, type EventEntityKey, 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 OidcConsentGrant, type OidcKeyRow, 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,
@@ -1008,7 +1008,7 @@ export function createSqliteServerStore(): ServerStore {
     async getEvent(id: string): Promise<PlatformEvent | null> {
       return getEvent(id)
     },
-    async eventsMatching(filter: EventKeyFilter, limit = 500): Promise<PlatformEvent[]> {
+    async eventsMatching(filter: EventKeyFilter | { keys: readonly EventEntityKey[] }, limit = 500): Promise<PlatformEvent[]> {
       return eventsMatching(filter, limit)
     },
 

package/src/store.ts

@@ -200,6 +200,22 @@ export interface EventKeyFilter {
   action?: string
 }
 
+/** One pinned (domain, entityId) pair of the bulk history read — the
+ *  participant-history shape (an entity's own event journal), never a
+ *  partial pattern: both legs are pinned, so every key resolves against
+ *  idx_events_domain_entity. */
+export interface EventEntityKey {
+  domain: string
+  entityId: string
+}
+
+/** The bulk read's statement chunk: D1 caps a statement at 100 bound
+ *  parameters (two per key + the limit), so a bulk call issues
+ *  ceil(keys / 49) statements — ONE for any realistic inbox window —
+ *  never one per key. The SQLite half chunks identically so the two
+ *  backends stay answer-identical. */
+export const EVENTS_BULK_KEY_CHUNK = 49
+
 // ── the notification subscriptions store (TODO.notify/02) ────────────
 
 /** The rule row's mode: 'subscribe' adds the user to the candidates of
@@ -1741,7 +1757,13 @@ export interface ServerStore {
    *  the latest auditEvents row whose action is a sign-in
    *  ('account.sign_in' — the password login; 'upstream_sign_in' — a
    *  linked-provider sign-in) per entity_id. Answers userId → ISO
-   *  timestamp; accounts that never signed in are absent. */
+   *  timestamp; accounts that never signed in are absent. The typed
+   *  read: json_extract legs (json_valid-guarded, the index's exact
+   *  spelling) against idx_entities_store_action (migration 0023) — an
+   *  index walk over the sign-in slice, never a data-LIKE scan of the
+   *  journal. The action match stays exact (the retired LIKE's closing
+   *  quote made it so too) and becomes spelling-proof: the legs parse
+   *  the JSON. */
   lastAccountSignIns(): Promise<Record<string, string>>
 
   // ── the account console (TODO.identity/06) ──
@@ -2199,17 +2221,39 @@ export interface ServerStore {
   ): Promise<InstrumentRegistration | null>
 
   // ── the workflow entity store + change journal ──
+  /** The store's rows, in the seam's declared order: (org_id, rowid) —
+   *  the read's observable order since migration 0001 (NULL org ids
+   *  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[]>
   getEntity(store: string, id: string): Promise<EntityRow | undefined>
   putEntity(store: string, id: string, orgId: string | null, data: string): Promise<void>
   deleteEntity(store: string, id: string): Promise<boolean>
   changesAfter(seq: number, limit?: number): Promise<EntityChange[]>
+  /** The GLOBAL journal high-water: the bootstrap snapshot's ETag leg
+   *  (any write anywhere bumps the one seq — conservative, never
+   *  stale).
+   *
+   *  NAMED FOLLOW-UP, DOC ONLY (the smart side references it from
+   *  server/routes/bootstrap.ts: the per-store `seqs` snapshot carries
+   *  the journal position a delta-loading client would resume from):
+   *  the PER-STORE high-water — `latestChangeSeqFor(store)` — answering
+   *  MAX(seq) over one store's slice of the SAME journal. The contract
+   *  when it lands: the seq stays global and monotone (the per-store
+   *  read is a PROJECTION of the one journal, never a second
+   *  sequence); it exists so a per-store conditional revalidation /
+   *  SSE resume probe costs one indexed read instead of a payload
+   *  fetch; and its query wants the (store, seq) walk — the index
+   *  rides the same commit, expand-only per the migration contract. */
   latestChangeSeq(): Promise<number>
 
   // ── the platform event store (TODO.notify/01) ──
   /** Append one declared event (the emitter's write; one row inside the
    *  acting request's envelope). Answers the stored row (seq + at read
-   *  back). */
+   *  back) off the INSERT's own RETURNING — ONE round trip, never the
+   *  INSERT + SELECT-by-id pair. */
   appendEvent(input: {
     id: string
     domain: string
@@ -2229,6 +2273,20 @@ export interface ServerStore {
    *  pins, equality-matched (`WHERE domain = ? AND entity_id = ?` — the
    *  column split's whole point, never a string scan on a composed key). */
   eventsMatching(filter: EventKeyFilter, limit?: number): Promise<PlatformEvent[]>
+  /** The BULK history read (the 2026-09-06 performance audit's
+   *  notify-inbox seam): the participant-history class awaits the
+   *  single-key form once per DISTINCT entity — ~100 D1 round trips for
+   *  a 500-event window. The bulk form resolves every pinned (domain,
+   *  entityId) pair in ONE statement per chunk of EVENTS_BULK_KEY_CHUNK
+   *  (the OR-of-ANDs WHERE walks idx_events_domain_entity per term;
+   *  never a compound SELECT — the D1 5-term cap rule).
+   *
+   *  The ordering contract: the answer is the MERGED matched set,
+   *  seq-ordered (never grouped per key); `limit` truncates the merged
+   *  set exactly as the single-key form truncates its own; duplicate
+   *  keys match their rows once (the OR is a set union, not a concat);
+   *  an empty keys list answers [] without issuing a statement. */
+  eventsMatching(filter: { keys: readonly EventEntityKey[] }, limit?: number): Promise<PlatformEvent[]>
 
   // ── the notification subscriptions store (TODO.notify/02) ──
   /** The user's own rule rows (both modes) — the settings page's list. */