@oimlsmart/platform-server 0.2.10 → 0.2.12

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/package.json

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

@@ -30,8 +30,10 @@
 
 import type { D1Database, D1PreparedStatement } from '@cloudflare/workers-types'
 import {
+  APPEND_EVENTS_CHUNK,
   DEMO_PASSWORD,
   EVENTS_BULK_KEY_CHUNK,
+  INSTRUMENT_REGISTRATIONS_CHUNK,
   PUT_ENTITIES_CHUNK,
   StoreUnavailable,
   type AccountEmail,
@@ -48,6 +50,7 @@ import {
   type EntityWriteInput,
   type EventEntityKey,
   type EventKeyFilter,
+  type EventWriteInput,
   type FederationPeer,
   type IdentityApproval,
   type IdentityLink,
@@ -84,6 +87,7 @@ import {
   type InstrumentRegistration,
   type InstrumentRegistrationLifecycle,
   type InstrumentRegistrationScopeStatus,
+  type InstrumentRegistrationWriteInput,
   type PersonalAccessToken,
   type PlatformEvent,
   resolveOrgContext,
@@ -423,6 +427,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 write's INSERT — ONE textual source for
+ *  createInstrumentRegistration and createInstrumentRegistrations alike
+ *  (the batch verb appends RETURNING * so the stored row answers off
+ *  the write itself; the single verb keeps its .run() + by-id
+ *  read-back pair). */
+const INSTRUMENT_REGISTRATION_INSERT_SQL = `INSERT OR IGNORE INTO instrument_registrations
+       (id, certificate_id, holder_org_id, standard_id, serial_number, manufacture_date, designations, scope_status, scope_detail, registered_by)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+
+/** 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). 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
    *  it: the facade below is per-instance and would never hit. */
@@ -3423,23 +3442,10 @@ export class D1ServerStore implements ServerStore {
 
   /** Register the instrument; NULL on the (certificate, serial)
    *  conflict (the route's honest 409). */
-  async createInstrumentRegistration(input: {
-    id: string
-    certificateId: string
-    holderOrgId: string
-    standardId: string
-    serialNumber: string
-    manufactureDate?: string | null
-    designations?: Record<string, unknown>
-    scopeStatus: InstrumentRegistrationScopeStatus
-    scopeDetail?: string | null
-    registeredBy?: string | null
-  }): Promise<InstrumentRegistration | null> {
+  async createInstrumentRegistration(input: InstrumentRegistrationWriteInput): Promise<InstrumentRegistration | null> {
     await this.ensureInstrumentRegistrationSupport()
     const res = await this.stmt(
-      `INSERT OR IGNORE INTO instrument_registrations
-         (id, certificate_id, holder_org_id, standard_id, serial_number, manufacture_date, designations, scope_status, scope_detail, registered_by)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      INSTRUMENT_REGISTRATION_INSERT_SQL,
       input.id, input.certificateId, input.holderOrgId, input.standardId, input.serialNumber,
       input.manufactureDate ?? null, JSON.stringify(input.designations ?? {}),
       input.scopeStatus, input.scopeDetail ?? null, input.registeredBy ?? null,
@@ -3448,6 +3454,37 @@ export class D1ServerStore implements ServerStore {
     return this.getInstrumentRegistration(input.id)
   }
 
+  /** The batch register write (the seam's contract, mechanically):
+   *  each row's INSERT OR IGNORE … RETURNING * rides ONE db.batch per
+   *  INSTRUMENT_REGISTRATIONS_CHUNK rows, the statements in INPUT order,
+   *  the chunks SERIALLY — the register's insertion order IS the CSV's
+   *  row order. The per-row answer comes off the batch's own results:
+   *  the stored row, or NULL when the RETURNING came back empty (the
+   *  (certificate, serial) conflict — the single verb's honest null).
+   *  The chunk is the atomic unit: a D1 batch lands all-or-nothing; a
+   *  failed chunk throws with its rows unlanded, earlier chunks
+   *  standing, later chunks never issued. */
+  async createInstrumentRegistrations(rows: readonly InstrumentRegistrationWriteInput[]): Promise<(InstrumentRegistration | null)[]> {
+    await this.ensureInstrumentRegistrationSupport()
+    if (rows.length === 0) return []
+    const out: (InstrumentRegistration | null)[] = []
+    for (let i = 0; i < rows.length; i += INSTRUMENT_REGISTRATIONS_CHUNK) {
+      const chunk = rows.slice(i, i + INSTRUMENT_REGISTRATIONS_CHUNK)
+      const statements = chunk.map(row => this.stmt(
+        `${INSTRUMENT_REGISTRATION_INSERT_SQL} RETURNING *`,
+        row.id, row.certificateId, row.holderOrgId, row.standardId, row.serialNumber,
+        row.manufactureDate ?? null, JSON.stringify(row.designations ?? {}),
+        row.scopeStatus, row.scopeDetail ?? null, row.registeredBy ?? null,
+      ))
+      const results = await this.db.batch(statements)
+      for (const res of results) {
+        const stored = res.results[0] as Record<string, unknown> | undefined
+        out.push(stored ? D1ServerStore.toInstrumentRegistration(stored) : null)
+      }
+    }
+    return out
+  }
+
   /** The lifecycle act (the transition rule is the route's); stamps
    *  updated_at/by. NULL when the register does not carry the id. */
   async setInstrumentRegistrationLifecycle(
@@ -3564,28 +3601,47 @@ 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,
     }
   }
 
-  async appendEvent(input: {
-    id: string
-    domain: string
-    entityId: string
-    action: string
-    payload: string
-  }): Promise<PlatformEvent> {
+  async appendEvent(input: EventWriteInput): Promise<PlatformEvent> {
     // 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,
+      EVENT_INSERT_SQL,
+      input.id, input.domain, input.entityId, input.action, input.payload, input.mentions ?? null,
     ).first<Record<string, unknown>>()
     return D1ServerStore.toPlatformEvent(row!)
   }
 
+  /** The bulk append (the seam's contract, mechanically): each event's
+   *  INSERT … RETURNING * rides ONE db.batch per APPEND_EVENTS_CHUNK
+   *  rows, the statements in INPUT order, the chunks SERIALLY — the
+   *  events' seq order IS the input order. The answer is the stored
+   *  rows, input-aligned. The chunk is the atomic unit: a D1 batch
+   *  lands all-or-nothing; a failed chunk throws with its events
+   *  unlanded, earlier chunks standing, later chunks never issued. */
+  async appendEvents(events: readonly EventWriteInput[]): Promise<PlatformEvent[]> {
+    if (events.length === 0) return []
+    const out: PlatformEvent[] = []
+    for (let i = 0; i < events.length; i += APPEND_EVENTS_CHUNK) {
+      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.mentions ?? null,
+      ))
+      const results = await this.db.batch(statements)
+      for (const res of results) {
+        out.push(D1ServerStore.toPlatformEvent(res.results[0] as Record<string, unknown>))
+      }
+    }
+    return out
+  }
+
   async eventsAfter(seq: number, limit = 500): Promise<PlatformEvent[]> {
     const res = await this.stmt(
       'SELECT * FROM events WHERE seq > ? ORDER BY seq LIMIT ?', seq, limit,
@@ -3788,6 +3844,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,
     }
   }
@@ -3806,6 +3863,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 (?, ?)',
@@ -3823,6 +3881,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/events.ts

@@ -9,7 +9,7 @@
 // ═══════════════════════════════════════════════════════════════════
 
 import { getDb } from './store'
-import { EVENTS_BULK_KEY_CHUNK, type EventEntityKey, type EventKeyFilter, type PlatformEvent } from '../../store'
+import { APPEND_EVENTS_CHUNK, EVENTS_BULK_KEY_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,26 +30,51 @@ function toPlatformEvent(row: EventRow): PlatformEvent {
     entityId: row.entity_id,
     action: row.action,
     payload: row.payload,
+    mentions: row.mentions,
     at: row.at,
   }
 }
 
-export function appendEvent(input: {
-  id: string
-  domain: string
-  entityId: string
-  action: string
-  payload: string
-}): PlatformEvent {
+/** 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,
   )
 }
 
+/** The bulk append (the seam's appendEvents, the 2026-09-07 audit's
+ *  chain half): each event lands exactly as appendEvent would land it —
+ *  the INSERT … RETURNING * answers the stored row off the write itself —
+ *  the answer rows in INPUT order (their seqs strictly increase in it),
+ *  one transaction per APPEND_EVENTS_CHUNK rows. The chunk is the atomic
+ *  unit, matching the D1 batch's all-or-nothing; a failed chunk throws
+ *  with its events unlanded, earlier chunks standing, later chunks never
+ *  issued. The chunks run serially, so the events' seq order IS the
+ *  input order. */
+export function appendEvents(events: readonly EventWriteInput[]): PlatformEvent[] {
+  if (events.length === 0) return []
+  const db = getDb()
+  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, e.mentions ?? null) as EventRow))
+      }
+    })()
+  }
+  return out
+}
+
 /** The feed's raw leg: events past the cursor, seq-ordered. */
 export function eventsAfter(seq: number, limit = 500): PlatformEvent[] {
   const rows = getDb()

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

@@ -149,7 +149,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 +162,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 +225,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 +242,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).
@@ -1355,7 +1367,9 @@ import type {
   InstrumentRegistration,
   InstrumentRegistrationLifecycle,
   InstrumentRegistrationScopeStatus,
+  InstrumentRegistrationWriteInput,
 } from '../../store'
+import { INSTRUMENT_REGISTRATIONS_CHUNK } from '../../store'
 
 interface InstrumentRegistrationRow {
   id: string
@@ -1430,18 +1444,7 @@ export function getInstrumentRegistration(id: string): InstrumentRegistration |
 /** Register the instrument; NULL on the (certificate, serial) conflict
  *  (the same physical unit never registers twice under one certificate —
  *  the route's honest 409). */
-export function createInstrumentRegistration(input: {
-  id: string
-  certificateId: string
-  holderOrgId: string
-  standardId: string
-  serialNumber: string
-  manufactureDate?: string | null
-  designations?: Record<string, unknown>
-  scopeStatus: InstrumentRegistrationScopeStatus
-  scopeDetail?: string | null
-  registeredBy?: string | null
-}): InstrumentRegistration | null {
+export function createInstrumentRegistration(input: InstrumentRegistrationWriteInput): InstrumentRegistration | null {
   const res = getDb().prepare(
     `INSERT OR IGNORE INTO instrument_registrations
        (id, certificate_id, holder_org_id, standard_id, serial_number, manufacture_date, designations, scope_status, scope_detail, registered_by)
@@ -1455,6 +1458,42 @@ export function createInstrumentRegistration(input: {
   return getInstrumentRegistration(input.id)
 }
 
+/** The batch register write (the seam's createInstrumentRegistrations,
+ *  the 2026-09-07 audit's REAL J1): each row lands exactly as
+ *  createInstrumentRegistration would land it — the INSERT OR IGNORE …
+ *  RETURNING * answers the stored row off the write itself (NULL when it
+ *  comes back empty: the (certificate, serial) conflict), the per-row
+ *  answers aligned with the INPUT order — one transaction per
+ *  INSTRUMENT_REGISTRATIONS_CHUNK rows. The chunk is the atomic unit,
+ *  matching the D1 batch's all-or-nothing; a failed chunk throws with
+ *  its rows unlanded, earlier chunks standing, later chunks never
+ *  issued. The chunks run serially, so the register's insertion order
+ *  IS the input's row order. */
+export function createInstrumentRegistrations(rows: readonly InstrumentRegistrationWriteInput[]): (InstrumentRegistration | null)[] {
+  if (rows.length === 0) return []
+  const db = getDb()
+  const insert = db.prepare(
+    `INSERT OR IGNORE INTO instrument_registrations
+       (id, certificate_id, holder_org_id, standard_id, serial_number, manufacture_date, designations, scope_status, scope_detail, registered_by)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?) RETURNING *`,
+  )
+  const out: (InstrumentRegistration | null)[] = []
+  for (let i = 0; i < rows.length; i += INSTRUMENT_REGISTRATIONS_CHUNK) {
+    const chunk = rows.slice(i, i + INSTRUMENT_REGISTRATIONS_CHUNK)
+    db.transaction(() => {
+      for (const row of chunk) {
+        const stored = insert.get(
+          row.id, row.certificateId, row.holderOrgId, row.standardId, row.serialNumber,
+          row.manufactureDate ?? null, JSON.stringify(row.designations ?? {}),
+          row.scopeStatus, row.scopeDetail ?? null, row.registeredBy ?? null,
+        ) as InstrumentRegistrationRow | undefined
+        out.push(stored ? instrumentRegistrationPayload(stored) : null)
+      }
+    })()
+  }
+  return out
+}
+
 /** The lifecycle act (the transition rule is the route's); stamps
  *  updated_at/by. NULL when the register does not carry the id. */
 export function setInstrumentRegistrationLifecycle(

package/src/store/sqlite.ts

@@ -22,6 +22,7 @@ import {
   createOrgMembership,
   createOrgRegistryOrg,
   createInstrumentRegistration,
+  createInstrumentRegistrations,
   createSession,
   decideCertificateHolderClaim,
   decideIdentityApproval,
@@ -91,6 +92,7 @@ import {
 } from './sqlite/entities'
 import {
   appendEvent,
+  appendEvents,
   eventsAfter,
   eventsMatching,
   getEvent,
@@ -189,7 +191,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 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 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 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,
@@ -571,20 +573,12 @@ export function createSqliteServerStore(): ServerStore {
     async getInstrumentRegistration(id: string): Promise<InstrumentRegistration | null> {
       return getInstrumentRegistration(id)
     },
-    async createInstrumentRegistration(input: {
-      id: string
-      certificateId: string
-      holderOrgId: string
-      standardId: string
-      serialNumber: string
-      manufactureDate?: string | null
-      designations?: Record<string, unknown>
-      scopeStatus: InstrumentRegistrationScopeStatus
-      scopeDetail?: string | null
-      registeredBy?: string | null
-    }): Promise<InstrumentRegistration | null> {
+    async createInstrumentRegistration(input: InstrumentRegistrationWriteInput): Promise<InstrumentRegistration | null> {
       return createInstrumentRegistration(input)
     },
+    async createInstrumentRegistrations(rows: readonly InstrumentRegistrationWriteInput[]): Promise<(InstrumentRegistration | null)[]> {
+      return createInstrumentRegistrations(rows)
+    },
     async setInstrumentRegistrationLifecycle(
       id: string,
       lifecycle: InstrumentRegistrationLifecycle,
@@ -1044,15 +1038,12 @@ export function createSqliteServerStore(): ServerStore {
     },
 
     // ── the platform event store (TODO.notify/01) ──
-    async appendEvent(input: {
-      id: string
-      domain: string
-      entityId: string
-      action: string
-      payload: string
-    }): Promise<PlatformEvent> {
+    async appendEvent(input: EventWriteInput): Promise<PlatformEvent> {
       return appendEvent(input)
     },
+    async appendEvents(events: readonly EventWriteInput[]): Promise<PlatformEvent[]> {
+      return appendEvents(events)
+    },
     async eventsAfter(seq: number, limit = 500): Promise<PlatformEvent[]> {
       return eventsAfter(seq, limit)
     },

package/src/store.ts

@@ -206,7 +206,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,9 +219,26 @@ 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
 }
 
+/** One row of the bulk append (appendEvents): appendEvent's legs — the
+ *  same fields, so each event lands exactly as the single-row verb
+ *  would land it (the EntityWriteInput pattern). */
+export interface EventWriteInput {
+  id: string
+  domain: string
+  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/**`,
  *  `certificate` + `issued` across the domain, one entity's
  *  `test-run/asg-…-001/**`) compiles to the columns it pins; absent legs
@@ -243,6 +265,17 @@ export interface EventEntityKey {
  *  backends stay answer-identical. */
 export const EVENTS_BULK_KEY_CHUNK = 49
 
+/** 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
+ *  chunk is one db.batch of APPEND_EVENTS_CHUNK statements — the
+ *  INSTRUMENT_REGISTRATIONS_CHUNK order. The chunk bounds the ATOMIC
+ *  unit (a D1 batch is all-or-nothing; the SQLite half's per-chunk
+ *  transaction matches it). Chunks issue SERIALLY, in input order —
+ *  the events' seq order IS the input order, and parallel chunks would
+ *  forfeit it. */
+export const APPEND_EVENTS_CHUNK = 50
+
 // ── the notification subscriptions store (TODO.notify/02) ────────────
 
 /** The rule row's mode: 'subscribe' adds the user to the candidates of
@@ -308,7 +341,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,
@@ -318,6 +354,7 @@ export interface NotifyInboxState {
   eventId: string
   readAt: string | null
   doneAt: string | null
+  savedAt: string | null
   createdAt: string
 }
 
@@ -1339,6 +1376,35 @@ export interface InstrumentRegistration {
   updatedBy: string | null
 }
 
+/** One row of the batch register write (createInstrumentRegistrations):
+ *  createInstrumentRegistration's legs — the same fields, so each row
+ *  lands exactly as the single-row verb would land it (the
+ *  EntityWriteInput pattern). */
+export interface InstrumentRegistrationWriteInput {
+  id: string
+  certificateId: string
+  holderOrgId: string
+  standardId: string
+  serialNumber: string
+  manufactureDate?: string | null
+  designations?: Record<string, unknown>
+  scopeStatus: InstrumentRegistrationScopeStatus
+  scopeDetail?: string | null
+  registeredBy?: string | null
+}
+
+/** The batch register write's chunk, in ROWS (createInstrumentRegistrations):
+ *  each row contributes ONE statement (the INSERT OR IGNORE … RETURNING *
+ *  answers the stored row off the write itself), so a chunk is one
+ *  db.batch of INSTRUMENT_REGISTRATIONS_CHUNK statements — half the
+ *  PUT_ENTITIES_CHUNK statement load, the same conservative order. The
+ *  chunk bounds the ATOMIC unit (a D1 batch is all-or-nothing; the
+ *  SQLite half's per-chunk transaction matches it). Chunks issue
+ *  SERIALLY, in input order — the register's insertion order IS the
+ *  input's row order (the CSV commit's chain events sequence after it,
+ *  same order), and parallel chunks would forfeit it. */
+export const INSTRUMENT_REGISTRATIONS_CHUNK = 50
+
 /** Per-store org fields for the READ visibility (the multi-party
  *  model: a row is visible when ANY named field equals the user's
  *  org). The field names are the entities' REAL ones (verified against
@@ -2357,18 +2423,35 @@ export interface ServerStore {
   /** Register the instrument. NULL on the (certificate_id,
    *  serial_number) conflict — the same physical unit never registers
    *  twice under one certificate (the route's honest 409). */
-  createInstrumentRegistration(input: {
-    id: string
-    certificateId: string
-    holderOrgId: string
-    standardId: string
-    serialNumber: string
-    manufactureDate?: string | null
-    designations?: Record<string, unknown>
-    scopeStatus: InstrumentRegistrationScopeStatus
-    scopeDetail?: string | null
-    registeredBy?: string | null
-  }): Promise<InstrumentRegistration | null>
+  createInstrumentRegistration(input: InstrumentRegistrationWriteInput): Promise<InstrumentRegistration | null>
+  /** The BATCH register write (the 2026-09-07 performance audit's REAL
+   *  J1 — the CSV commit awaited createInstrumentRegistration per
+   *  imported row: ~10⁴ rows = minutes of serial D1 writes at demo
+   *  latency, two round trips each): every row lands exactly as the
+   *  single-row verb would land it, but the rows ride ONE db.batch per
+   *  INSTRUMENT_REGISTRATIONS_CHUNK rows, the INSERT OR IGNORE …
+   *  RETURNING * answering the stored row off the write itself (the
+   *  appendEvent halving — never the INSERT + SELECT-by-id pair).
+   *
+   *  The per-row answer, aligned with the INPUT order: the stored row,
+   *  or NULL on the (certificate_id, serial_number) conflict — the
+   *  single verb's honest null, so the route's per-row refusal leg (the
+   *  serial registered between the evaluation and the commit) rides
+   *  unchanged.
+   *
+   *  The ordering contract: the statements ride each batch in input
+   *  order and the chunks issue SERIALLY, so the register's insertion
+   *  order IS the input's row order (the CSV row order; the commit's
+   *  chain events sequence after it, same order). A caller
+   *  parallelizing the call itself forfeits the contract.
+   *
+   *  The failure contract mirrors putEntities: the chunk is the ATOMIC
+   *  unit (a D1 batch is all-or-nothing; the SQLite half wraps each
+   *  chunk in a transaction). A failed chunk lands NOTHING of its rows
+   *  and the call throws — earlier chunks' writes STAND, later chunks
+   *  never issue. An empty rows list resolves to [] without issuing a
+   *  statement. */
+  createInstrumentRegistrations(rows: readonly InstrumentRegistrationWriteInput[]): Promise<(InstrumentRegistration | null)[]>
   /** The lifecycle act (registered ⇄ out_of_service → withdrawn; the
    *  transition RULE is the route's — withdrawn is terminal): stamps
    *  updated_at/by. NULL when the register does not carry the id. */
@@ -2439,13 +2522,21 @@ export interface ServerStore {
    *  acting request's envelope). Answers the stored row (seq + at read
    *  back) off the INSERT's own RETURNING — ONE round trip, never the
    *  INSERT + SELECT-by-id pair. */
-  appendEvent(input: {
-    id: string
-    domain: string
-    entityId: string
-    action: string
-    payload: string
-  }): Promise<PlatformEvent>
+  appendEvent(input: EventWriteInput): Promise<PlatformEvent>
+  /** The BULK append (the 2026-09-07 performance audit's chain half —
+   *  the CSV registration commit's one chain event per imported serial,
+   *  a second serial loop after the register writes): every event lands
+   *  exactly as appendEvent would land it, the rows riding ONE
+   *  db.batch per APPEND_EVENTS_CHUNK rows. Answers the stored rows in
+   *  INPUT order — the seqs strictly increase in it (the statements
+   *  ride each batch in input order, the chunks SERIALLY; the same
+   *  semantic contract as putEntities').
+   *
+   *  The failure contract mirrors putEntities: the chunk is the ATOMIC
+   *  unit; a failed chunk lands NOTHING of its events and the call
+   *  throws — earlier chunks stand, later chunks never issue. An empty
+   *  list resolves to [] without issuing a statement. */
+  appendEvents(events: readonly EventWriteInput[]): Promise<PlatformEvent[]>
   /** The feed's raw leg: events past the cursor, seq-ordered. The
    *  visibility gate is the READER's layer (server/notify-feed.ts) —
    *  never waived here, never duplicated into the SQL. */
@@ -2517,17 +2608,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) ──