@oimlsmart/platform-server 0.2.6 → 0.2.8

package/migrations/0026_entity_changes_store_seq.sql

@@ -0,0 +1,15 @@
+-- The per-store journal high-water (the ServerStore seam's
+-- latestChangeSeqFor(store), the 2026-09-07 performance audit's G1):
+-- the seam's DOC-ONLY contract since 0.2.2 ("the (store, seq) walk —
+-- the index rides the same commit") lands. The read answers MAX(seq)
+-- over one store's slice of the ONE global journal — the seq stays
+-- global and monotone, this is a projection, never a second sequence.
+-- Without the index the projection scans the journal's rowid walk and
+-- filters; with it the read is a single indexed probe, which is the
+-- contract's whole point (per-store conditional revalidation / SSE
+-- resume probes paying one read, never a payload fetch).
+--
+-- 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_entity_changes_store_seq ON entity_changes (store, seq);

package/package.json

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

@@ -32,6 +32,7 @@ import type { D1Database, D1PreparedStatement } from '@cloudflare/workers-types'
 import {
   DEMO_PASSWORD,
   EVENTS_BULK_KEY_CHUNK,
+  PUT_ENTITIES_CHUNK,
   StoreUnavailable,
   type AccountEmail,
   type AddAccountEmailResult,
@@ -44,6 +45,7 @@ import {
   type EnrollmentToken,
   type EntityChange,
   type EntityRow,
+  type EntityWriteInput,
   type EventEntityKey,
   type EventKeyFilter,
   type FederationPeer,
@@ -413,6 +415,14 @@ function boundedD1Writes(binding: D1Database, budgetMs: number): D1Database {
   }
 }
 
+/** The entity write's two statements, ONE textual source for putEntity
+ *  and putEntities alike (the multi-row write must land each row
+ *  byte-identically to the single-row verb — the upsert, then its
+ *  journal entry). */
+const ENTITY_UPSERT_SQL = `INSERT INTO entities (store, id, org_id, data, updated_at) VALUES (?, ?, ?, ?, datetime('now'))
+         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 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. */
@@ -3450,15 +3460,34 @@ export class D1ServerStore implements ServerStore {
     // all-or-nothing, the same atomicity the SQLite path gets from its
     // transaction.
     await this.db.batch([
-      this.stmt(
-        `INSERT INTO entities (store, id, org_id, data, updated_at) VALUES (?, ?, ?, ?, datetime('now'))
-         ON CONFLICT (store, id) DO UPDATE SET org_id = excluded.org_id, data = excluded.data, updated_at = datetime('now')`,
-        store, id, orgId, data,
-      ),
-      this.stmt('INSERT INTO entity_changes (store, type, id) VALUES (?, ?, ?)', store, 'persist', id),
+      this.stmt(ENTITY_UPSERT_SQL, store, id, orgId, data),
+      this.stmt(ENTITY_CHANGE_SQL, store, 'persist', id),
     ])
   }
 
+  async putEntities(store: string, rows: readonly EntityWriteInput[]): Promise<void> {
+    // The seam's contract, mechanically: each row lands exactly as
+    // putEntity would land it (the upsert, then its journal entry), the
+    // statements ride each batch in INPUT order, and the chunks issue
+    // SERIALLY — so the journal's seq order IS the input's row order
+    // (the audit-chain property the CSV commit relies on). 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.
+    if (rows.length === 0) return
+    for (let i = 0; i < rows.length; i += PUT_ENTITIES_CHUNK) {
+      const chunk = rows.slice(i, i + PUT_ENTITIES_CHUNK)
+      const statements: D1PreparedStatement[] = []
+      for (const row of chunk) {
+        statements.push(
+          this.stmt(ENTITY_UPSERT_SQL, store, row.id, row.orgId, row.data),
+          this.stmt(ENTITY_CHANGE_SQL, store, 'persist', row.id),
+        )
+      }
+      await this.db.batch(statements)
+    }
+  }
+
   async deleteEntity(store: string, id: string): Promise<boolean> {
     const res = await this.stmt('DELETE FROM entities WHERE store = ? AND id = ?', store, id).run()
     const gone = (res.meta.changes ?? 0) > 0
@@ -3480,6 +3509,16 @@ export class D1ServerStore implements ServerStore {
     return row?.seq ?? 0
   }
 
+  async latestChangeSeqFor(store: string): Promise<number> {
+    // One indexed probe over idx_entity_changes_store_seq (migration
+    // 0026) — the per-store projection of the one journal; 0 when the
+    // store carries no rows (MAX answers NULL on the empty set).
+    const row = await this.stmt(
+      'SELECT MAX(seq) AS seq FROM entity_changes WHERE store = ?', store,
+    ).first<{ seq: number | null }>()
+    return row?.seq ?? 0
+  }
+
   // ── 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.

package/src/store/sqlite/entities.ts

@@ -13,12 +13,20 @@
 // ═══════════════════════════════════════════════════════════════════
 
 import { getDb } from './store'
-import { orgIdOf } from '../../store'
+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 } from '../../store'
+import type { EntityRow, EntityChange, EntityWriteInput } from '../../store'
+
+/** The entity write's two statements, ONE textual source for putEntity
+ *  and putEntities alike (the multi-row write must land each row
+ *  byte-identically to the single-row verb — the upsert, then its
+ *  journal entry). */
+const ENTITY_UPSERT_SQL = `INSERT INTO entities (store, id, org_id, data, updated_at) VALUES (?, ?, ?, ?, datetime('now'))
+       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 ORDER BY is the seam's contract (the 0.2.3 pin, the D1 half's
@@ -40,15 +48,35 @@ export function getEntity(store: string, id: string): EntityRow | undefined {
 export function putEntity(store: string, id: string, orgId: string | null, data: string): void {
   const db = getDb()
   const write = db.transaction(() => {
-    db.prepare(
-      `INSERT INTO entities (store, id, org_id, data, updated_at) VALUES (?, ?, ?, ?, datetime('now'))
-       ON CONFLICT (store, id) DO UPDATE SET org_id = excluded.org_id, data = excluded.data, updated_at = datetime('now')`,
-    ).run(store, id, orgId, data)
-    db.prepare('INSERT INTO entity_changes (store, type, id) VALUES (?, ?, ?)').run(store, 'persist', id)
+    db.prepare(ENTITY_UPSERT_SQL).run(store, id, orgId, data)
+    db.prepare(ENTITY_CHANGE_SQL).run(store, 'persist', id)
   })
   write()
 }
 
+/** The multi-row write (the seam's putEntities, the 2026-09-07 audit's
+ *  J1): each row lands exactly as putEntity would land it, in INPUT
+ *  order, one transaction per PUT_ENTITIES_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 journal's seq
+ *  order IS the input's row order. */
+export function putEntities(store: string, rows: readonly EntityWriteInput[]): void {
+  if (rows.length === 0) return
+  const db = getDb()
+  const upsert = db.prepare(ENTITY_UPSERT_SQL)
+  const journal = db.prepare(ENTITY_CHANGE_SQL)
+  for (let i = 0; i < rows.length; i += PUT_ENTITIES_CHUNK) {
+    const chunk = rows.slice(i, i + PUT_ENTITIES_CHUNK)
+    db.transaction(() => {
+      for (const row of chunk) {
+        upsert.run(store, row.id, row.orgId, row.data)
+        journal.run(store, 'persist', row.id)
+      }
+    })()
+  }
+}
+
 export function deleteEntity(store: string, id: string): boolean {
   const db = getDb()
   let gone = false
@@ -74,3 +102,14 @@ export function latestChangeSeq(): number {
   const row = getDb().prepare('SELECT MAX(seq) AS seq FROM entity_changes').get() as { seq: number | null }
   return row.seq ?? 0
 }
+
+/** The per-store projection of the one journal (the seam's contract):
+ *  MAX(seq) over the store's own slice, 0 on a store with no writes.
+ *  Walks idx_entity_changes_store_seq — one indexed probe, never a
+ *  journal scan. */
+export function latestChangeSeqFor(store: string): number {
+  const row = getDb()
+    .prepare('SELECT MAX(seq) AS seq FROM entity_changes WHERE store = ?')
+    .get(store) as { seq: number | null }
+  return row.seq ?? 0
+}

package/src/store/sqlite/schema.sql

@@ -132,6 +132,12 @@ CREATE TABLE IF NOT EXISTS entity_changes (
   id TEXT NOT NULL,
   at TEXT NOT NULL DEFAULT (datetime('now'))
 );
+-- The per-store high-water's walk (migration 0026, the seam's
+-- latestChangeSeqFor(store)): MAX(seq) over one store's slice of the
+-- one global journal costs a single indexed probe, never a journal
+-- scan. The seq stays global and monotone — a projection, never a
+-- second sequence.
+CREATE INDEX IF NOT EXISTS idx_entity_changes_store_seq ON entity_changes (store, seq);
 
 -- TODO.notify/01 — the platform event store (the notification system's
 -- source of truth): one row per DECLARED notifiable act (the catalog,

package/src/store/sqlite.ts

@@ -84,7 +84,9 @@ import {
   deleteEntity,
   getEntity,
   latestChangeSeq,
+  latestChangeSeqFor,
   listEntities,
+  putEntities,
   putEntity,
 } from './sqlite/entities'
 import {
@@ -185,7 +187,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 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 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 {
   advanceWebauthnCounter,
   consumeMfaPending,
@@ -1013,6 +1015,9 @@ export function createSqliteServerStore(): ServerStore {
     async putEntity(store: string, id: string, orgId: string | null, data: string): Promise<void> {
       putEntity(store, id, orgId, data)
     },
+    async putEntities(store: string, rows: readonly EntityWriteInput[]): Promise<void> {
+      putEntities(store, rows)
+    },
     async deleteEntity(store: string, id: string): Promise<boolean> {
       return deleteEntity(store, id)
     },
@@ -1022,6 +1027,9 @@ export function createSqliteServerStore(): ServerStore {
     async latestChangeSeq(): Promise<number> {
       return latestChangeSeq()
     },
+    async latestChangeSeqFor(store: string): Promise<number> {
+      return latestChangeSeqFor(store)
+    },
 
     // ── the platform event store (TODO.notify/01) ──
     async appendEvent(input: {

package/src/store.ts

@@ -175,6 +175,26 @@ export interface EntityChange {
   at: 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. */
+export interface EntityWriteInput {
+  id: string
+  orgId: string | null
+  data: string
+}
+
+/** The multi-row write's batch chunk, in ROWS (putEntities): each row
+ *  contributes two statements (the upsert + its journal entry), so a
+ *  chunk is one db.batch of 2 × PUT_ENTITIES_CHUNK statements — the
+ *  same conservative order as EVENTS_BULK_KEY_CHUNK. The chunk bounds
+ *  the ATOMIC unit (a D1 batch is all-or-nothing; the SQLite half's
+ *  per-chunk transaction matches it) and keeps one batch's latency
+ *  well inside the write budget at demo-hub latency. Chunks issue
+ *  SERIALLY, in input order — the journal's seq order IS the input
+ *  order, and parallel chunks would forfeit it. */
+export const PUT_ENTITIES_CHUNK = 50
+
 // ── the platform event store (TODO.notify/01) ────────────────────────
 
 /** A notifiable platform event (TODO.notify/00's event model): one row
@@ -2349,24 +2369,51 @@ export interface ServerStore {
   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>
+  /** The MULTI-ROW write (the 2026-09-07 performance audit's J1 — the
+   *  CSV registration commit awaited putEntity per imported row, ~10⁴
+   *  rows = minutes of serial D1 writes at demo latency): every row
+   *  lands exactly as putEntity would land it (the upsert + its
+   *  journal 'persist' entry, one journal row per input row, a
+   *  duplicate id re-journals and the last write wins), but the rows
+   *  ride ONE db.batch per PUT_ENTITIES_CHUNK rows instead of one
+   *  round trip per row.
+   *
+   *  The ordering contract — a semantic property of the audit chain,
+   *  never an implementation detail: the journal's seq order IS the
+   *  input's row order. The statements ride each batch in input order
+   *  and the chunks issue SERIALLY (parallel chunks would interleave
+   *  the seq assignment); a caller parallelizing the call itself
+   *  forfeits the contract.
+   *
+   *  The failure contract: 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 — but earlier chunks' writes STAND, and later chunks
+   *  never issue. A caller needing the whole import all-or-nothing
+   *  keeps it under one chunk (or compensates above the seam; the
+   *  retry re-journals, the same caveat as any putEntity retry — the
+   *  bounded-write facade's StoreUnavailable "may have landed"
+   *  posture). An empty rows list resolves without issuing a
+   *  statement. */
+  putEntities(store: string, rows: readonly EntityWriteInput[]): 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. */
+   *  stale). */
   latestChangeSeq(): Promise<number>
+  /** The PER-STORE high-water: MAX(seq) over one store's slice of the
+   *  SAME journal. The seq stays global and monotone — the per-store
+   *  read is a PROJECTION of the one journal, never a second sequence.
+   *  A store with no writes answers 0 (the empty journal's floor, the
+   *  same as the global form's). The read is one indexed probe over
+   *  idx_entity_changes_store_seq (migration 0026 — the (store, seq)
+   *  walk rode that commit, expand-only per the migration contract),
+   *  so a per-store conditional revalidation / SSE resume probe never
+   *  pays a journal scan. Landed for the 2026-09-07 performance
+   *  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 platform event store (TODO.notify/01) ──
   /** Append one declared event (the emitter's write; one row inside the