@oimlsmart/platform-server 0.1.9 → 0.2.0

package/README.md

@@ -11,8 +11,14 @@ pin IS the contract (TODO.repos/01).
 ## What it is
 
 - `store`, the ServerStore seam: the interface, every row type, the
-  demo-account plan, `installStore`/`getStore`. Worker-safe.
-- `store/d1`, the Cloudflare D1 implementation. Worker-safe.
+  demo-account plan, `installStore`/`getStore`, and `StoreUnavailable`
+  (the bounded writes' honest timeout error). Worker-safe.
+- `store/d1`, the Cloudflare D1 implementation: every write/batch/DDL
+  statement races a confirmation budget (`DEFAULT_STORE_WRITE_BUDGET_MS`
+  = 5 s; the consumer's `STORE_WRITE_BUDGET_MS` env binding retunes it
+  through `resolveStoreWriteBudgetMs` + the `d1StoreFor`/`D1ServerStore`
+  options) — a timeout throws the seam's `StoreUnavailable`. Reads stay
+  unbounded. Worker-safe.
 - `store/sqlite`, the node implementation (better-sqlite3): the server
   store composed from the sync modules, the entity-store verbs, the raw
   driver handle, the schema (`SQLITE_SCHEMA_PATH`), and the migration

package/package.json

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

@@ -16,11 +16,22 @@
 // d1-store.test.ts runs this class against a better-sqlite3-backed D1
 // facade (the binding contract with real semantics) plus the real
 // workerd binding through scripts/cloudflare-smoke.ts there.
+//
+// THE BOUNDED-WRITE DISCIPLINE (the 2026-09-01 outage's lesson): every
+// write/batch/DDL statement races a confirmation budget (the default
+// DEFAULT_STORE_WRITE_BUDGET_MS, tunable per deployment through the
+// consumer's STORE_WRITE_BUDGET_MS env binding) — a slow/hung store
+// write answers StoreUnavailable in seconds, never spins the request
+// forever. READS stay unbounded here: the read-path latency story is
+// read replication, not this bound. The constructor wraps the binding
+// in the bounded facade ONCE (boundedD1Writes below); the ensure memos
+// key on the RAW binding (a rejected chain still evicts itself).
 // ═══════════════════════════════════════════════════════════════════
 
 import type { D1Database, D1PreparedStatement } from '@cloudflare/workers-types'
 import {
   DEMO_PASSWORD,
+  StoreUnavailable,
   type AccountEmail,
   type AddAccountEmailResult,
   type AdvanceCounterResult,
@@ -255,8 +266,159 @@ const lastSeenWrites = new Map<string, number>()
 const LAST_SEEN_THROTTLE_MS = 60_000
 const LAST_SEEN_CACHE_CAP = 4096
 
+// ── The bounded-write discipline (the 2026-09-01 outage's lesson) ────
+// Yesterday's outage: a cross-region path flap hung the identity
+// service's D1 WRITES indefinitely and the login page spun for minutes.
+// The discipline: every write/batch/DDL statement races a confirmation
+// budget and a timeout answers StoreUnavailable — an honest error in
+// seconds, never an infinite spin. READS (SELECT/PRAGMA/…) pass through
+// untouched: the read-path latency story is read replication, a
+// separate fix. The bound wraps the BINDING once at construction (the
+// store's every write path — the 180+ .run() sites, the batches, the
+// ensure chains' DDL — flows through it), so no call site changes.
+
+/** The default write-confirmation budget: D1's healthy write latency is
+ *  tens of ms; 5 s is two orders of magnitude past any honest p99 yet
+ *  still "seconds" to a waiting human — the 503 reaches the login page
+ *  before the browser's own patience ends. Tunable per deployment (the
+ *  consumer's STORE_WRITE_BUDGET_MS env binding). */
+export const DEFAULT_STORE_WRITE_BUDGET_MS = 5_000
+
+export interface D1WriteBudgetOptions {
+  /** The write/batch/DDL confirmation budget in ms. Absent:
+   *  DEFAULT_STORE_WRITE_BUDGET_MS. */
+  writeBudgetMs?: number
+}
+
+/** The consumer-side env resolution (the resolveInstanceProfileFromEnv
+ *  posture — the kernel never reads process.env; the Worker-safe
+ *  modules take the env binding as an argument). Unset/garbage resolves
+ *  undefined — the store's default stands, never a silent 0. */
+export function resolveStoreWriteBudgetMs(env?: { STORE_WRITE_BUDGET_MS?: string }): number | undefined {
+  const raw = env?.STORE_WRITE_BUDGET_MS?.trim()
+  if (!raw) return undefined
+  const parsed = Number.parseInt(raw, 10)
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined
+}
+
+/** The write-classified leading verbs (DDL included). Everything else —
+ *  SELECT, the PRAGMA probes, EXPLAIN — is a read and stays unbounded. */
+const WRITE_STATEMENT = /^\s*(?:insert|update|delete|replace|create|alter|drop|vacuum|reindex)\b/i
+
+/** The statement's idempotency posture for StoreUnavailable.retrySafe:
+ *  the shapes whose replay converges after a write that may have
+ *  landed — keyed UPDATE/DELETE/REPLACE, INSERT OR IGNORE/REPLACE, the
+ *  ON CONFLICT upserts, the IF NOT EXISTS heals. A plain INSERT is NOT
+ *  claimed safe (a retry could double-land). */
+function writeRetrySafe(sql: string): boolean {
+  if (/^\s*(?:update|delete|replace)\b/i.test(sql)) return true
+  if (/^\s*insert\s+or\s+(?:ignore|replace)\b/i.test(sql)) return true
+  if (/^\s*insert\b/i.test(sql) && /\bon\s+conflict\b/i.test(sql)) return true
+  if (/^\s*create\b/i.test(sql) && /\bif\s+not\s+exists\b/i.test(sql)) return true
+  return false
+}
+
+/** The error/log label for a write: the verb phrase + the target object
+ *  ('UPDATE sessions', 'CREATE TABLE IF NOT EXISTS org_memberships').
+ *  Never the bound values — the label is all an error may carry. */
+function sqlWriteLabel(sql: string): string {
+  const flat = sql.trim().replace(/\s+/g, ' ')
+  const m = /^((?:insert(?:\s+or\s+(?:ignore|replace))?\s+into|update|delete\s+from|replace\s+into|create\s+(?:unique\s+)?(?:table|index)(?:\s+if\s+not\s+exists)?|alter\s+table|drop\s+(?:table|index)(?:\s+if\s+exists)?))\s+("?\w+"?)/i.exec(flat)
+  if (m) return `${m[1].toUpperCase()} ${m[2]}`
+  return flat.slice(0, 60)
+}
+
+/** Race a write against its confirmation budget. The in-flight write is
+ *  never cancelled (D1 has no abort) — the race's handlers stay attached
+ *  past the timeout, so a late settling (success OR failure) never
+ *  surfaces as an unhandled rejection. */
+function raceWriteBudget<T>(operation: string, budgetMs: number, retrySafe: boolean, pending: Promise<T>): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new StoreUnavailable(operation, budgetMs, retrySafe)), budgetMs)
+    pending.then(
+      value => { clearTimeout(timer); resolve(value) },
+      (error: unknown) => { clearTimeout(timer); reject(error) },
+    )
+  })
+}
+
+/** The wrapper → the underlying statement (+ its idempotency posture).
+ *  batch() hands the REAL statements back to the binding: the runtime
+ *  reads the SQL off the statement object itself, so a wrapper is not a
+ *  statement to it. WeakMap-keyed — the entries die with the wrappers. */
+const unwrappedStatements = new WeakMap<D1PreparedStatement, { stmt: D1PreparedStatement; retrySafe: boolean }>()
+
+/** The write-bounded statement facade: read-classified SQL returns the
+ *  raw statement untouched; write-classified SQL gets every terminal
+ *  (run/first/all/raw — INSERT … RETURNING reads back through a write)
+ *  raced against the budget. bind() stays chainable on the wrapper. */
+function boundedStatement(stmt: D1PreparedStatement, sql: string, budgetMs: number): D1PreparedStatement {
+  if (!WRITE_STATEMENT.test(sql)) return stmt
+  const operation = sqlWriteLabel(sql)
+  const retrySafe = writeRetrySafe(sql)
+  const wrap = (s: D1PreparedStatement): D1PreparedStatement => {
+    const wrapped = {
+      bind: (...values: unknown[]): D1PreparedStatement => wrap(s.bind(...values)),
+      first: (<T = unknown>(colName?: string) =>
+        raceWriteBudget(operation, budgetMs, retrySafe, (colName === undefined ? s.first<T>() : s.first<T>(colName)) as Promise<T | null>)
+      ) as D1PreparedStatement['first'],
+      run: (<T = Record<string, unknown>>() =>
+        raceWriteBudget(operation, budgetMs, retrySafe, s.run<T>())
+      ) as D1PreparedStatement['run'],
+      all: (<T = Record<string, unknown>>() =>
+        raceWriteBudget(operation, budgetMs, retrySafe, s.all<T>())
+      ) as D1PreparedStatement['all'],
+      raw: (<T = unknown[]>(options?: { columnNames?: boolean }) =>
+        options?.columnNames
+          ? raceWriteBudget(operation, budgetMs, retrySafe, s.raw<T>({ columnNames: true }))
+          : raceWriteBudget(operation, budgetMs, retrySafe, s.raw<T>(options as { columnNames?: false } | undefined))
+      ) as D1PreparedStatement['raw'],
+    }
+    unwrappedStatements.set(wrapped as D1PreparedStatement, { stmt: s, retrySafe })
+    return wrapped as D1PreparedStatement
+  }
+  return wrap(stmt)
+}
+
+/** The binding facade the store holds: prepare() bounds write-classified
+ *  statements, batch()/exec() race their own budget (a D1 batch is ONE
+ *  round-trip — one budget, retry-safe exactly when every member is),
+ *  dump()/the reads pass through, withSession()'s session gets the same
+ *  discipline. One budget per round-trip, never per row. */
+function boundedD1Writes(binding: D1Database, budgetMs: number): D1Database {
+  const boundedBatch = <T>(run: (real: D1PreparedStatement[]) => Promise<T>, statements: D1PreparedStatement[],): Promise<T> => {
+    const real = statements.map(s => unwrappedStatements.get(s)?.stmt ?? s)
+    const retrySafe = statements.length > 0 && statements.every(s => unwrappedStatements.get(s)?.retrySafe === true)
+    return raceWriteBudget(`batch (${statements.length} statements)`, budgetMs, retrySafe, run(real))
+  }
+  return {
+    prepare: (sql: string) => boundedStatement(binding.prepare(sql), sql, budgetMs),
+    batch: <T = unknown>(statements: D1PreparedStatement[]) => boundedBatch(r => binding.batch<T>(r), statements),
+    exec: (sql: string) => raceWriteBudget('exec (DDL script)', budgetMs, false, binding.exec(sql)),
+    dump: () => binding.dump(),
+    withSession: (constraintOrBookmark?: string) => {
+      const session = binding.withSession(constraintOrBookmark)
+      return {
+        prepare: (sql: string) => boundedStatement(session.prepare(sql), sql, budgetMs),
+        batch: <T = unknown>(statements: D1PreparedStatement[]) => boundedBatch(r => session.batch<T>(r), statements),
+        getBookmark: () => session.getBookmark(),
+      }
+    },
+  }
+}
+
 export class D1ServerStore implements ServerStore {
-  constructor(private readonly db: D1Database) {}
+  /** The RAW binding — the ensure memos (and d1StoreFor's map) key on
+   *  it: the facade below is per-instance and would never hit. */
+  private readonly binding: D1Database
+  /** The bounded-write facade over the binding (the discipline note
+   *  above) — every statement/batch the store issues flows through it. */
+  private readonly db: D1Database
+
+  constructor(binding: D1Database, opts?: D1WriteBudgetOptions) {
+    this.binding = binding
+    this.db = boundedD1Writes(binding, opts?.writeBudgetMs ?? DEFAULT_STORE_WRITE_BUDGET_MS)
+  }
 
   private stmt(sql: string, ...params: unknown[]): D1PreparedStatement {
     return this.db.prepare(sql).bind(...params)
@@ -267,7 +429,7 @@ export class D1ServerStore implements ServerStore {
   //  user methods ensure them defensively (PRAGMA probe + ALTER),
   //  memoized per (binding, chain) at module scope (the header note).
   private ensureUserColumns(): Promise<void> {
-    return ensured(this.db, 'usersColumns', async () => {
+    return ensured(this.binding, 'usersColumns', async () => {
       const cols = await this.db.prepare('PRAGMA table_info(users)').all<{ name: string }>()
       const names = new Set(cols.results.map(c => c.name))
       if (!names.has('roles')) await this.db.prepare('ALTER TABLE users ADD COLUMN roles TEXT').run()
@@ -284,7 +446,7 @@ export class D1ServerStore implements ServerStore {
   // them defensively (the ensureUserColumns posture, memoized per
   // (binding, chain) at module scope).
   private ensureSessionColumns(): Promise<void> {
-    return ensured(this.db, 'sessionColumns', async () => {
+    return ensured(this.binding, 'sessionColumns', async () => {
       const cols = await this.db.prepare('PRAGMA table_info(sessions)').all<{ name: string }>()
       const names = new Set(cols.results.map(c => c.name))
       if (!names.has('user_agent')) await this.db.prepare('ALTER TABLE sessions ADD COLUMN user_agent TEXT').run()
@@ -304,7 +466,7 @@ export class D1ServerStore implements ServerStore {
   // migration's twin) is IDEMPOTENT and rides the ensure: every
   // org-bound account's primary membership mirrors the legacy columns.
   private ensureMembershipSupport(): Promise<void> {
-    return ensured(this.db, 'membershipSupport', async () => {
+    return ensured(this.binding, 'membershipSupport', async () => {
       await this.db.prepare(
         `CREATE TABLE IF NOT EXISTS org_memberships (
            id TEXT PRIMARY KEY,
@@ -359,7 +521,7 @@ export class D1ServerStore implements ServerStore {
   // defensively (the ensureMembershipSupport posture, memoized per
   // (binding, chain) at module scope).
   private ensureOrgRegistrySupport(): Promise<void> {
-    return ensured(this.db, 'orgRegistrySupport', async () => {
+    return ensured(this.binding, 'orgRegistrySupport', async () => {
       await this.db.prepare(
         `CREATE TABLE IF NOT EXISTS org_registry (
            id TEXT PRIMARY KEY,
@@ -399,7 +561,7 @@ export class D1ServerStore implements ServerStore {
   // ensureOrgRegistrySupport posture, memoized per (binding, chain) at
   // module scope).
   private ensureHolderAttributionSupport(): Promise<void> {
-    return ensured(this.db, 'holderAttributionSupport', async () => {
+    return ensured(this.binding, 'holderAttributionSupport', async () => {
       await this.db.prepare(
         `CREATE TABLE IF NOT EXISTS certificate_holder_orgs (
            certificate_id TEXT PRIMARY KEY,
@@ -439,7 +601,7 @@ export class D1ServerStore implements ServerStore {
   // ensure it defensively (the ensureOrgRegistrySupport posture,
   // memoized per (binding, chain) at module scope).
   private ensureInstrumentRegistrationSupport(): Promise<void> {
-    return ensured(this.db, 'instrumentRegistrationSupport', async () => {
+    return ensured(this.binding, 'instrumentRegistrationSupport', async () => {
       await this.db.prepare(
         `CREATE TABLE IF NOT EXISTS instrument_registrations (
            id TEXT PRIMARY KEY,
@@ -471,7 +633,7 @@ export class D1ServerStore implements ServerStore {
   // per (binding, chain) at module scope), so a dev D1 migrated from
   // before the wave never 500s the core flow.
   private ensureOidcColumns(): Promise<void> {
-    return ensured(this.db, 'oidcColumns', async () => {
+    return ensured(this.binding, 'oidcColumns', async () => {
       const codeCols = await this.db.prepare('PRAGMA table_info(oidc_codes)').all<{ name: string }>()
       if (!codeCols.results.some(c => c.name === 'amr')) {
         await this.db.prepare('ALTER TABLE oidc_codes ADD COLUMN amr TEXT').run()
@@ -489,7 +651,7 @@ export class D1ServerStore implements ServerStore {
   // it defensively (the ensureOrgRegistrySupport posture, memoized per
   // (binding, chain) at module scope).
   private ensurePersonalAccessTokenSupport(): Promise<void> {
-    return ensured(this.db, 'personalAccessTokenSupport', async () => {
+    return ensured(this.binding, 'personalAccessTokenSupport', async () => {
       await this.db.prepare(
         `CREATE TABLE IF NOT EXISTS personal_access_tokens (
            id TEXT PRIMARY KEY,
@@ -519,7 +681,7 @@ export class D1ServerStore implements ServerStore {
   // it defensively (the ensurePersonalAccessTokenSupport posture,
   // memoized per (binding, chain) at module scope).
   private ensureConsentGrantSupport(): Promise<void> {
-    return ensured(this.db, 'consentGrantSupport', async () => {
+    return ensured(this.binding, 'consentGrantSupport', async () => {
       await this.db.prepare(
         `CREATE TABLE IF NOT EXISTS oidc_consent_grants (
            id TEXT PRIMARY KEY,
@@ -544,7 +706,7 @@ export class D1ServerStore implements ServerStore {
   // ensureConsentGrantSupport posture, memoized per (binding, chain) at
   // module scope).
   private ensureAccountEmailSupport(): Promise<void> {
-    return ensured(this.db, 'accountEmailSupport', async () => {
+    return ensured(this.binding, 'accountEmailSupport', async () => {
       await this.db.prepare(
         `CREATE TABLE IF NOT EXISTS account_emails (
            user_id TEXT NOT NULL REFERENCES users(id),
@@ -3373,7 +3535,7 @@ export class D1ServerStore implements ServerStore {
   // (Memoized per (binding, chain) at module scope — the header note.)
 
   private ensureNotifyDeliverySupport(): Promise<void> {
-    return ensured(this.db, 'notifyDeliverySupport', async () => {
+    return ensured(this.binding, 'notifyDeliverySupport', async () => {
       await this.db.prepare(
         `CREATE TABLE IF NOT EXISTS notify_deliveries (
            id TEXT PRIMARY KEY,
@@ -3522,14 +3684,21 @@ export class D1ServerStore implements ServerStore {
 
 /** The worker entry's install: one store per binding, memoized (the
  *  store is a stateless facade over the binding — safe to share across
- *  the isolate's concurrent requests). */
+ *  the isolate's concurrent requests). The write budget comes from the
+ *  FIRST resolution's opts: the memoized store keeps it (the
+ *  deployment's env is constant, so every request passes the same
+ *  value — a changed budget needs a fresh binding/isolate). */
 const byBinding = new WeakMap<D1Database, D1ServerStore>()
 
-export function d1StoreFor(binding: D1Database): D1ServerStore {
+export function d1StoreFor(binding: D1Database, opts?: D1WriteBudgetOptions): D1ServerStore {
   let store = byBinding.get(binding)
   if (!store) {
-    store = new D1ServerStore(binding)
+    store = new D1ServerStore(binding, opts)
     byBinding.set(binding, store)
   }
   return store
 }
+
+// The seam's honest-unavailable error, re-exported where the consumer's
+// route surface already imports the D1 half from.
+export { StoreUnavailable }

package/src/store.ts

@@ -1354,6 +1354,38 @@ export const DEMO_ACCOUNTS = [
 
 export const DEMO_PASSWORD = 'demo2026'
 
+/** The store's honest unavailable answer (the 2026-09-01 lesson — a
+ *  hung store write must answer in seconds, never spin the caller
+ *  forever): a bounded WRITE's confirmation did not arrive within its
+ *  budget. The route surface maps it to a 503 naming the store's
+ *  TEMPORARY unavailability + the retryability.
+ *
+ *  The timed-out write may STILL land — the store accepted the
+ *  statement and it was the confirmation path that hung, so the error
+ *  never claims the write was lost. `retrySafe` names the statement's
+ *  own idempotency posture: true (an upsert, a keyed UPDATE/DELETE, an
+ *  IF NOT EXISTS heal) — a retry converges; false (a plain INSERT) —
+ *  reconcile before retrying. The reads are NOT bounded by this
+ *  discipline (the read-path latency story is read replication); only
+ *  write/batch/DDL statements throw this. */
+export class StoreUnavailable extends Error {
+  constructor(
+    /** The write's label — the verb + the target (e.g.
+     *  'UPDATE sessions', 'batch (6 statements)'); never row data. */
+    readonly operation: string,
+    /** The confirmation budget the write exceeded, in ms. */
+    readonly budgetMs: number,
+    /** The statement's idempotency posture (the class note). */
+    readonly retrySafe: boolean,
+  ) {
+    super(
+      `the store write did not confirm within ${budgetMs} ms (${operation}) — the store is briefly unavailable; `
+      + `the write may have landed — retry is safe for idempotent operations${retrySafe ? ' (this one is)' : ''}`,
+    )
+    this.name = 'StoreUnavailable'
+  }
+}
+
 /** The async store contract the routes consume. Every method mirrors a
  *  sync counterpart in store.ts / entities.ts — same SQL, same
  *  semantics, awaited. */