@oimlsmart/platform-server 0.2.7 → 0.2.8

package/package.json

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

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

package/src/store/sqlite.ts

@@ -86,6 +86,7 @@ import {
   latestChangeSeq,
   latestChangeSeqFor,
   listEntities,
+  putEntities,
   putEntity,
 } from './sqlite/entities'
 import {
@@ -186,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,
@@ -1014,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)
     },

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,6 +2369,33 @@ 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