@starci/hfs 4.11.22 → 4.12.2

package/runtime/engine/db/event-compact.d.mts

@@ -0,0 +1,21 @@
+/** Declared sizes: the ledger event bound and the inline summary caps (every cap keeps the summary far below the bound). */
+export declare const EVENT_LIMITS: Readonly<{
+    payloadBytes: 16384;
+    rows: 8;
+    ids: 8;
+    stringChars: 200;
+    lineChars: 600;
+    depth: 8;
+}>;
+export declare const REFUSAL_SCHEMA = "starci/admission-refusal@1";
+/**
+ * The stored form of an event payload: `{payloadJson, payloadSha}`. The payload is redacted. It goes whole to the blob store (`spill(bytes)`
+ * stores it and returns its sha, kept when the caller already holds one) when it carries an admission record (the bounded summary is the inline
+ * JSON) or when it is over the inline bound (the inline JSON is its top-level scalars and the sha). This is the one path of every event writer:
+ * a payload that grows with its input (a file list, a manifest, a critique, a menu) never fails the write, and a reader that needs the whole
+ * payload goes through engine/db/event-payload.mjs.
+ */
+export declare function eventPayloadRecord(payload: unknown, payloadSha: string | null | undefined, spill: (bytes: Buffer) => string): {
+    payloadJson: string | null;
+    payloadSha: string | null | undefined;
+};

package/runtime/engine/db/event-compact.mjs

@@ -5,56 +5,50 @@
 import { isPlainObject } from '../plain-object.mjs';
 import { list } from '../../scripts/lib/list.mjs';
 import { redactData } from '../../scripts/lib/redact.mjs';
-
 /** Declared sizes: the ledger event bound and the inline summary caps (every cap keeps the summary far below the bound). */
 export const EVENT_LIMITS = Object.freeze({ payloadBytes: 16384, rows: 8, ids: 8, stringChars: 200, lineChars: 600, depth: 8 });
 const ADMISSION_SCHEMA = 'starci/agent-admission@1';
 export const REFUSAL_SCHEMA = 'starci/admission-refusal@1';
-
 const clip = (value, max = EVENT_LIMITS.stringChars) => (typeof value === 'string' && value.length > max ? `${value.slice(0, max)}...` : value);
-
-/** The primitive fields of an object, long strings clipped: quota snapshots and other nested records are dropped. */
+const scalarFields = (value) => Object.fromEntries(Object.entries(value).filter(([, v]) => v === null || ['string', 'number', 'boolean'].includes(typeof v)).map(([k, v]) => [k, clip(v)]));
 function scalars(value) {
-  if (!isPlainObject(value)) return value ?? null;
-  return Object.fromEntries(Object.entries(value).filter(([, v]) => v === null || ['string', 'number', 'boolean'].includes(typeof v)).map(([k, v]) => [k, clip(v)]));
+    if (!isPlainObject(value))
+        return value ?? null;
+    return scalarFields(value);
 }
 const rowOf = (row) => ({ id: row?.id ?? null, provider: row?.provider ?? null, model: row?.model ?? null, codes: list(row?.codes).slice(0, EVENT_LIMITS.rows).map((code) => clip(code, 80)) });
-
 function admissionSummary(a) {
-  const receipt = isPlainObject(a.receipt) ? { ...scalars(a.receipt), ...(isPlainObject(a.receipt.scope) ? { scope: scalars(a.receipt.scope) } : {}) } : null;
-  return { schema: a.schema, ok: a.ok === true, reason: clip(a.reason ?? null), policyVersion: a.policyVersion ?? null, chosenBy: clip(a.chosenBy ?? null),
-    overrideApplied: a.overrideApplied === true, resetAt: a.resetAt ?? null, request: scalars(a.request), selected: scalars(a.selected),
-    eligibleCount: list(a.eligible).length, eligible: list(a.eligible).slice(0, EVENT_LIMITS.ids).map((row) => row?.id ?? null),
-    rejectedCount: list(a.rejected).length, rejected: list(a.rejected).slice(0, EVENT_LIMITS.rows).map(rowOf),
-    ...(receipt ? { receipt } : {}), summarized: true };
+    const receipt = isPlainObject(a.receipt) ? { ...scalarFields(a.receipt), ...(isPlainObject(a.receipt.scope) ? { scope: scalars(a.receipt.scope) } : {}) } : null;
+    return { schema: a.schema, ok: a.ok === true, reason: clip(a.reason ?? null), policyVersion: a.policyVersion ?? null, chosenBy: clip(a.chosenBy ?? null),
+        overrideApplied: a.overrideApplied === true, resetAt: a.resetAt ?? null, request: scalars(a.request), selected: scalars(a.selected),
+        eligibleCount: list(a.eligible).length, eligible: list(a.eligible).slice(0, EVENT_LIMITS.ids).map((row) => row?.id ?? null),
+        rejectedCount: list(a.rejected).length, rejected: list(a.rejected).slice(0, EVENT_LIMITS.rows).map(rowOf),
+        ...(receipt ? { receipt } : {}), summarized: true };
 }
-
 function refusalSummary(r) {
-  const rows = list(r.rejected), alternatives = list(r.alternatives);
-  return { schema: r.schema, class: r.class ?? null, queuedBecause: r.queuedBecause ?? null, line: clip(r.line ?? null, EVENT_LIMITS.lineChars),
-    rejectedCount: rows.length, rejected: rows.slice(0, EVENT_LIMITS.rows).map(rowOf),
-    alternativesCount: alternatives.length, alternatives: alternatives.slice(0, EVENT_LIMITS.ids).map((entry) => clip(String(entry))), summarized: true };
+    const rows = list(r.rejected), alternatives = list(r.alternatives);
+    return { schema: r.schema, class: r.class ?? null, queuedBecause: r.queuedBecause ?? null, line: clip(r.line ?? null, EVENT_LIMITS.lineChars),
+        rejectedCount: rows.length, rejected: rows.slice(0, EVENT_LIMITS.rows).map(rowOf),
+        alternativesCount: alternatives.length, alternatives: alternatives.slice(0, EVENT_LIMITS.ids).map((entry) => clip(String(entry))), summarized: true };
 }
-
 const SUMMARIES = Object.freeze({ [ADMISSION_SCHEMA]: admissionSummary, [REFUSAL_SCHEMA]: refusalSummary });
-
 /** `{payload, compacted}`: every admission-shaped record in `payload` replaced by its bounded summary; `compacted` says whether one was. */
 function compactEventPayload(payload, depth = 0) {
-  if (depth > EVENT_LIMITS.depth || payload === null || typeof payload !== 'object') return { payload, compacted: false };
-  if (isPlainObject(payload) && typeof payload.schema === 'string' && payload.summarized !== true && SUMMARIES[payload.schema])
-    return { payload: SUMMARIES[payload.schema](payload), compacted: true };
-  let compacted = false;
-  const visit = (value) => { const inner = compactEventPayload(value, depth + 1); compacted ||= inner.compacted; return inner.payload; };
-  const copy = Array.isArray(payload) ? payload.map((item) => visit(item)) : Object.fromEntries(Object.entries(payload).map(([k, v]) => [k, visit(v)]));
-  return { payload: compacted ? copy : payload, compacted };
+    if (depth > EVENT_LIMITS.depth || payload === null || typeof payload !== 'object')
+        return { payload, compacted: false };
+    const summarize = isPlainObject(payload) && typeof payload.schema === 'string' ? SUMMARIES[payload.schema] : undefined;
+    if (isPlainObject(payload) && payload.summarized !== true && summarize)
+        return { payload: summarize(payload), compacted: true };
+    let compacted = false;
+    const visit = (value) => { const inner = compactEventPayload(value, depth + 1); compacted ||= inner.compacted; return inner.payload; };
+    const copy = Array.isArray(payload) ? payload.map((item) => visit(item)) : Object.fromEntries(Object.entries(payload).map(([k, v]) => [k, visit(v)]));
+    return { payload: compacted ? copy : payload, compacted };
 }
-
 /** A payload's bounded inline view when it went whole to the blob store: its top-level scalars (long strings clipped) and where the rest is. */
 function spilledView(redacted, bytes, sha) {
-  const flat = isPlainObject(redacted) ? scalars(redacted) : {};
-  return { ...flat, spilled: true, sha256: sha, bytes };
+    const flat = isPlainObject(redacted) ? scalarFields(redacted) : {};
+    return { ...flat, spilled: true, sha256: sha, bytes };
 }
-
 /**
  * The stored form of an event payload: `{payloadJson, payloadSha}`. The payload is redacted. It goes whole to the blob store (`spill(bytes)`
  * stores it and returns its sha, kept when the caller already holds one) when it carries an admission record (the bounded summary is the inline
@@ -63,11 +57,13 @@ function spilledView(redacted, bytes, sha) {
  * payload goes through engine/db/event-payload.mjs.
  */
 export function eventPayloadRecord(payload, payloadSha, spill) {
-  if (payload === null || payload === undefined) return { payloadJson: null, payloadSha };
-  const redacted = redactData(payload);
-  const { payload: inline, compacted } = compactEventPayload(redacted);
-  const json = JSON.stringify(inline);
-  if (compacted || payloadSha || json.length <= EVENT_LIMITS.payloadBytes) return { payloadJson: json, payloadSha: compacted && !payloadSha ? spill(Buffer.from(JSON.stringify(redacted))) : payloadSha };
-  const sha = spill(Buffer.from(JSON.stringify(redacted)));
-  return { payloadJson: JSON.stringify(spilledView(redacted, json.length, sha)), payloadSha: sha };
+    if (payload === null || payload === undefined)
+        return { payloadJson: null, payloadSha };
+    const redacted = redactData(payload);
+    const { payload: inline, compacted } = compactEventPayload(redacted);
+    const json = JSON.stringify(inline);
+    if (compacted || payloadSha || json.length <= EVENT_LIMITS.payloadBytes)
+        return { payloadJson: json, payloadSha: compacted && !payloadSha ? spill(Buffer.from(JSON.stringify(redacted))) : payloadSha };
+    const sha = spill(Buffer.from(JSON.stringify(redacted)));
+    return { payloadJson: JSON.stringify(spilledView(redacted, json.length, sha)), payloadSha: sha };
 }

package/runtime/engine/db/machine-connection.d.mts

@@ -0,0 +1,68 @@
+import type { SqlDb } from './sqlite-types.mjs';
+/** A raw `DatabaseSync` as the resilient connection holds it. */
+export interface RawConnection extends SqlDb {
+    readonly isTransaction: boolean;
+}
+/** The resilient connection: the raw one behind retry-and-reopen, with `reopen` and `raw` as extras. */
+export interface ResilientDb extends SqlDb {
+    readonly isTransaction: boolean;
+    reopen(): void;
+    readonly raw: RawConnection;
+}
+/** A retry that recovered. */
+export interface Recovery {
+    where: string;
+    retries: number;
+    at: number;
+}
+/** The error persistent corruption raises, carrying the quick_check it observed. */
+export type MachineCorruptError = Error & {
+    code?: unknown;
+    cause?: unknown;
+    file?: string;
+    retries?: number;
+    where?: string;
+    quickCheck?: string[] | null;
+    deferred?: string;
+};
+/** Records a persistent corruption incident and returns the error to throw. */
+export type IncidentReporter = (file: string, error: unknown, details: {
+    retries: number;
+    where: string;
+}) => MachineCorruptError;
+export declare const MACHINE_BUSY_TIMEOUT_MS = 15000;
+export declare const MACHINE_BUSY_CODE = "STARCI_MACHINE_BUSY";
+export declare const MACHINE_CORRUPT_CODE = "STARCI_MACHINE_CORRUPT";
+export declare const CORRUPT_RETRY_DELAYS_MS: readonly number[];
+export declare const waitForRetry: (ms: number) => "ok" | "not-equal" | "timed-out";
+export declare const isMachineBusy: (error: unknown) => boolean;
+export declare const isBusyError: (error: unknown) => boolean;
+export declare const isCorruptError: (error: unknown) => boolean;
+export declare const errText: (error: unknown) => string;
+/** Persistent corruption diagnostics observe the store and stderr without recording an incident. */
+export declare function corruptDiagnostic(file: string, error: unknown, { retries, where }: {
+    retries: number;
+    where: string;
+}): MachineCorruptError;
+/** Connection retries share one policy; the machine owner supplies operational incident persistence. */
+export declare function machineConnectionMethods({ reportIncident }: {
+    reportIncident: IncidentReporter;
+}): {
+    openWithRetry: <T>(openRaw: () => T, { file, onCorrupt }: {
+        file: string;
+        onCorrupt?: IncidentReporter;
+    }) => T;
+    connectionState: (openRaw: () => RawConnection, { file, inTransaction, onCorrupt }: {
+        file: string;
+        inTransaction?: () => boolean;
+        onCorrupt?: IncidentReporter;
+    }) => {
+        db: ResilientDb;
+        recovered: Recovery[];
+        noteRecovered: (r: {
+            where: string;
+            retries: number;
+        }) => void;
+        close(): void;
+    };
+};

package/runtime/engine/db/machine-connection.mjs

@@ -2,8 +2,10 @@ import { installRefResolver } from './ref-value.mjs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { sleepSync as scaledSleepSync } from '../../scripts/lib/sleep-sync.mjs';
-
+const fieldsOf = (error) => (typeof error === 'object' && error !== null ? error : {});
 const require = createRequire(import.meta.url);
+/** The named member of a statement (a method the driver provides): called as written, so a missing one is the same TypeError it always was. */
+const methodOf = (target, name) => target[name];
 export const MACHINE_BUSY_TIMEOUT_MS = 15000;
 export const MACHINE_BUSY_CODE = 'STARCI_MACHINE_BUSY';
 export const MACHINE_CORRUPT_CODE = 'STARCI_MACHINE_CORRUPT';
@@ -11,140 +13,185 @@ const OPEN_RETRY_DELAYS_MS = Object.freeze([0, 300, 900]);
 const BUSY_RETRY_DELAYS_MS = Object.freeze([100, 300, 900, 2000]);
 export const CORRUPT_RETRY_DELAYS_MS = Object.freeze([25, 150, 600]);
 export const waitForRetry = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-export const isMachineBusy = (error) => error?.code === MACHINE_BUSY_CODE;
-export const isBusyError = (error) => error?.errcode === 5 || error?.errcode === 6 || /SQLITE_BUSY|database is (?:locked|busy)/i.test(String(error?.message ?? error));
+export const isMachineBusy = (error) => fieldsOf(error).code === MACHINE_BUSY_CODE;
+export const isBusyError = (error) => fieldsOf(error).errcode === 5 || fieldsOf(error).errcode === 6 || /SQLITE_BUSY|database is (?:locked|busy)/i.test(String(fieldsOf(error).message ?? error));
 export const isCorruptError = (error) => {
-  if (!error) return false;
-  if (error.code === MACHINE_CORRUPT_CODE) return true;
-  const code = Number(error.errcode);
-  if (Number.isInteger(code) && ((code & 0xff) === 11 || (code & 0xff) === 26)) return true;
-  return /database disk image is malformed|file is not a database|SQLITE_CORRUPT|SQLITE_NOTADB/i.test(String(error.message ?? error));
+    if (!error)
+        return false;
+    if (fieldsOf(error).code === MACHINE_CORRUPT_CODE)
+        return true;
+    const code = Number(fieldsOf(error).errcode);
+    if (Number.isInteger(code) && ((code & 0xff) === 11 || (code & 0xff) === 26))
+        return true;
+    return /database disk image is malformed|file is not a database|SQLITE_CORRUPT|SQLITE_NOTADB/i.test(String(fieldsOf(error).message ?? error));
 };
-export const errText = (error) => String(error?.message ?? error).slice(0, 500);
-const busyError = (file, error, { retries, where }) => Object.assign(new Error(`machine-db-busy: ${file} ${where}: database still locked after busy_timeout and ${retries} retries: ${String(error?.message ?? error).slice(0, 200)}`),
-  { code: MACHINE_BUSY_CODE, cause: error, file, retries, where });
-
+export const errText = (error) => String(fieldsOf(error).message ?? error).slice(0, 500);
+const busyError = (file, error, { retries, where }) => Object.assign(new Error(`machine-db-busy: ${file} ${where}: database still locked after busy_timeout and ${retries} retries: ${String(fieldsOf(error).message ?? error).slice(0, 200)}`), { code: MACHINE_BUSY_CODE, cause: error, file, retries, where });
 /** Persistent corruption diagnostics observe the store and stderr without recording an incident. */
 export function corruptDiagnostic(file, error, { retries, where }) {
-  if (error?.code === MACHINE_CORRUPT_CODE) return error;
-  const out = Object.assign(new Error(`machine-db-corrupt: ${file} ${where}: SQLITE_CORRUPT persisted after ${retries} reopen(s): ${errText(error)}`),
-    { code: MACHINE_CORRUPT_CODE, cause: error, file, retries, where });
-  let check = null;
-  try {
-    const { DatabaseSync } = require('node:sqlite');
-    const db = installRefResolver(new DatabaseSync(file, { readOnly: true, timeout: MACHINE_BUSY_TIMEOUT_MS }));
-    try { check = db.prepare('PRAGMA quick_check').all().map((r) => r.quick_check).slice(0, 20); } finally { db.close(); }
-  } catch (e) { check = [`quick_check failed: ${errText(e)}`]; }
-  out.quickCheck = check;
-  process.stderr.write(`[machine-db] INCIDENT ${out.message} (quick_check: ${JSON.stringify(check)})\n`);
-  return out;
+    if (fieldsOf(error).code === MACHINE_CORRUPT_CODE)
+        return error; // it carries the corrupt code, so it is already this module's error
+    const out = Object.assign(new Error(`machine-db-corrupt: ${file} ${where}: SQLITE_CORRUPT persisted after ${retries} reopen(s): ${errText(error)}`), { code: MACHINE_CORRUPT_CODE, cause: error, file, retries, where });
+    let check = null;
+    try {
+        const { DatabaseSync } = require('node:sqlite');
+        const db = installRefResolver(new DatabaseSync(file, { readOnly: true, timeout: MACHINE_BUSY_TIMEOUT_MS }));
+        try {
+            check = db.prepare('PRAGMA quick_check').all().map((r) => r.quick_check).slice(0, 20);
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch (e) {
+        check = [`quick_check failed: ${errText(e)}`];
+    }
+    out.quickCheck = check;
+    process.stderr.write(`[machine-db] INCIDENT ${out.message} (quick_check: ${JSON.stringify(check)})\n`);
+    return out;
 }
-
 /** Which open failure is retryable: a busy wait, an 'unable to open' reopen, or a first corrupt hit; null rethrows. */
 const openFailureKind = (error) => {
-  if (isBusyError(error) && !isCorruptError(error)) return 'busy';
-  if (/unable to open/i.test(String(error?.message ?? ''))) return 'open';
-  if (isCorruptError(error) && error.code !== MACHINE_CORRUPT_CODE) return 'corrupt';
-  return null;
+    if (isBusyError(error) && !isCorruptError(error))
+        return 'busy';
+    if (/unable to open/i.test(String(fieldsOf(error).message ?? '')))
+        return 'open';
+    if (isCorruptError(error) && fieldsOf(error).code !== MACHINE_CORRUPT_CODE)
+        return 'corrupt';
+    return null;
 };
-
 const transientBusy = (error) => isBusyError(error) && !isMachineBusy(error) && !isCorruptError(error);
-
 function resilientConnection(openRaw, { file, inTransaction, onRecovered, onCorrupt }) {
-  let raw = openRaw(), generation = 0;
-  const reopen = () => { try { raw.close(); } catch { /* closed */ } raw = openRaw(); generation += 1; };
-  const recoverCorrupt = (error, retries, where) => {
-    if (!isCorruptError(error) || error.code === MACHINE_CORRUPT_CODE) throw error;
-    if (inTransaction() || raw.isTransaction) throw error;
-    if (retries >= CORRUPT_RETRY_DELAYS_MS.length) throw onCorrupt(file, error, { retries, where });
-    waitForRetry(CORRUPT_RETRY_DELAYS_MS[retries]);
-    try { reopen(); } catch (openError) { if (!isCorruptError(openError)) throw openError; }
-  };
-  const retrying = (where, op) => {
-    let busyRetries = 0;
-    for (let retries = 0; ; retries += 1) {
-      try {
-        const out = op();
-        if (retries) onRecovered({ where, retries });
-        return out;
-      } catch (error) {
-        if (!transientBusy(error)) { recoverCorrupt(error, retries, where); continue; }
-        if (inTransaction() || raw.isTransaction) throw error;
-        if (busyRetries >= BUSY_RETRY_DELAYS_MS.length) throw busyError(file, error, { retries: busyRetries, where });
-        scaledSleepSync(BUSY_RETRY_DELAYS_MS[busyRetries]);
-        busyRetries += 1;
-        retries -= 1;
-      }
+    let raw = openRaw(), generation = 0;
+    const reopen = () => { try {
+        raw.close();
     }
-  };
-  const prepare = (sql) => {
-    let stmt = null, gen = -1;
-    const settings = [];
-    const current = () => {
-      if (gen !== generation) {
-        stmt = raw.prepare(sql);
-        for (const [k, a] of settings) stmt[k](...a);
-        gen = generation;
-      }
-      return stmt;
+    catch { /* closed */ } raw = openRaw(); generation += 1; };
+    const recoverCorrupt = (error, retries, where) => {
+        if (!isCorruptError(error) || fieldsOf(error).code === MACHINE_CORRUPT_CODE)
+            throw error;
+        if (inTransaction() || raw.isTransaction)
+            throw error;
+        if (retries >= CORRUPT_RETRY_DELAYS_MS.length)
+            throw onCorrupt(file, error, { retries, where });
+        waitForRetry(CORRUPT_RETRY_DELAYS_MS[retries]); // retries < the list length, by the check above
+        try {
+            reopen();
+        }
+        catch (openError) {
+            if (!isCorruptError(openError))
+                throw openError;
+        }
+    };
+    const retrying = (where, op) => {
+        let busyRetries = 0;
+        for (let retries = 0;; retries += 1) {
+            try {
+                const out = op();
+                if (retries)
+                    onRecovered({ where, retries });
+                return out;
+            }
+            catch (error) {
+                if (!transientBusy(error)) {
+                    recoverCorrupt(error, retries, where);
+                    continue;
+                }
+                if (inTransaction() || raw.isTransaction)
+                    throw error;
+                if (busyRetries >= BUSY_RETRY_DELAYS_MS.length)
+                    throw busyError(file, error, { retries: busyRetries, where });
+                scaledSleepSync(BUSY_RETRY_DELAYS_MS[busyRetries]); // busyRetries < the list length, by the check above
+                busyRetries += 1;
+                retries -= 1;
+            }
+        }
+    };
+    const prepare = (sql) => {
+        let stmt = null, gen = -1;
+        const settings = [];
+        const current = () => {
+            if (gen !== generation) {
+                stmt = raw.prepare(sql);
+                for (const [k, a] of settings)
+                    methodOf(stmt, k).apply(stmt, a); // the driver's set* statement options, replayed on a reopened statement
+                gen = generation;
+            }
+            return stmt;
+        };
+        retrying(`prepare ${sql.slice(0, 80)}`, current);
+        return new Proxy({}, {
+            get(_, prop) {
+                if (prop === 'run' || prop === 'get' || prop === 'all' || prop === 'iterate')
+                    return (...args) => retrying(`${prop} ${sql.slice(0, 80)}`, () => current()[prop](...args));
+                if (typeof prop === 'string' && /^set[A-Z]/.test(prop))
+                    return (...args) => { settings.push([prop, args]); const target = current(); return methodOf(target, prop).apply(target, args); };
+                const value = current()[prop];
+                return typeof value === 'function' ? value.bind(current()) : value;
+            },
+        });
     };
-    retrying(`prepare ${sql.slice(0, 80)}`, current);
     return new Proxy({}, {
-      get(_, prop) {
-        if (prop === 'run' || prop === 'get' || prop === 'all' || prop === 'iterate') return (...args) => retrying(`${prop} ${sql.slice(0, 80)}`, () => current()[prop](...args));
-        if (typeof prop === 'string' && /^set[A-Z]/.test(prop)) return (...args) => { settings.push([prop, args]); return current()[prop](...args); };
-        const value = current()[prop];
-        return typeof value === 'function' ? value.bind(current()) : value;
-      },
+        get(_, prop) {
+            if (prop === 'prepare')
+                return prepare;
+            if (prop === 'exec')
+                return (sql) => retrying(`exec ${String(sql).slice(0, 80)}`, () => raw.exec(sql));
+            if (prop === 'reopen')
+                return reopen;
+            if (prop === 'raw')
+                return raw;
+            const value = raw[prop];
+            return typeof value === 'function' ? value.bind(raw) : value;
+        },
     });
-  };
-  return new Proxy({}, {
-    get(_, prop) {
-      if (prop === 'prepare') return prepare;
-      if (prop === 'exec') return (sql) => retrying(`exec ${String(sql).slice(0, 80)}`, () => raw.exec(sql));
-      if (prop === 'reopen') return reopen;
-      if (prop === 'raw') return raw;
-      const value = raw[prop];
-      return typeof value === 'function' ? value.bind(raw) : value;
-    },
-  });
 }
-
 /** Connection retries share one policy; the machine owner supplies operational incident persistence. */
 export function machineConnectionMethods({ reportIncident }) {
-  function openWithRetry(openRaw, { file, onCorrupt = reportIncident }) {
-    let lastError, busyOpens = 0, failures = 0;
-    const retryOpenFailure = (error) => {
-      lastError = error;
-      const kind = openFailureKind(error);
-      if (kind === null) throw error;
-      if (kind === 'busy') {
-        if (busyOpens >= BUSY_RETRY_DELAYS_MS.length) throw busyError(path.resolve(file), error, { retries: busyOpens, where: 'open' });
-        scaledSleepSync(BUSY_RETRY_DELAYS_MS[busyOpens]);
-        busyOpens += 1;
-        return true;
-      }
-      failures += 1;
-      return failures < OPEN_RETRY_DELAYS_MS.length;
-    };
-    for (;;) {
-      if (failures && OPEN_RETRY_DELAYS_MS[failures]) waitForRetry(OPEN_RETRY_DELAYS_MS[failures]);
-      try { return openRaw(); }
-      catch (error) { if (!retryOpenFailure(error)) break; }
+    function openWithRetry(openRaw, { file, onCorrupt = reportIncident }) {
+        let lastError, busyOpens = 0, failures = 0;
+        const retryOpenFailure = (error) => {
+            lastError = error;
+            const kind = openFailureKind(error);
+            if (kind === null)
+                throw error;
+            if (kind === 'busy') {
+                if (busyOpens >= BUSY_RETRY_DELAYS_MS.length)
+                    throw busyError(path.resolve(file), error, { retries: busyOpens, where: 'open' });
+                scaledSleepSync(BUSY_RETRY_DELAYS_MS[busyOpens]); // busyOpens < the list length, by the check above
+                busyOpens += 1;
+                return true;
+            }
+            failures += 1;
+            return failures < OPEN_RETRY_DELAYS_MS.length;
+        };
+        for (;;) {
+            const delay = OPEN_RETRY_DELAYS_MS[failures];
+            if (failures && delay)
+                waitForRetry(delay);
+            try {
+                return openRaw();
+            }
+            catch (error) {
+                if (!retryOpenFailure(error))
+                    break;
+            }
+        }
+        if (isCorruptError(lastError))
+            throw onCorrupt(path.resolve(file), lastError, { retries: OPEN_RETRY_DELAYS_MS.length - 1, where: 'open' });
+        throw lastError;
     }
-    if (isCorruptError(lastError)) throw onCorrupt(path.resolve(file), lastError, { retries: OPEN_RETRY_DELAYS_MS.length - 1, where: 'open' });
-    throw lastError;
-  }
-
-  function connectionState(openRaw, { file, inTransaction = () => false, onCorrupt = reportIncident }) {
-    const recovered = [];
-    const noteRecovered = (r) => {
-      recovered.push({ ...r, at: Date.now() });
-      process.stderr.write(`[machine-db] transient SQLITE_CORRUPT recovered after ${r.retries} reopen(s) at ${r.where} (${file})\n`);
-    };
-    const db = resilientConnection(openRaw, { file, inTransaction, onRecovered: noteRecovered, onCorrupt });
-    return { db, recovered, noteRecovered, close() { try { db.close(); } catch { /* closed */ } } };
-  }
-
-  return { openWithRetry, connectionState };
+    function connectionState(openRaw, { file, inTransaction = () => false, onCorrupt = reportIncident }) {
+        const recovered = [];
+        const noteRecovered = (r) => {
+            recovered.push({ ...r, at: Date.now() });
+            process.stderr.write(`[machine-db] transient SQLITE_CORRUPT recovered after ${r.retries} reopen(s) at ${r.where} (${file})\n`);
+        };
+        const db = resilientConnection(openRaw, { file, inTransaction, onRecovered: noteRecovered, onCorrupt });
+        return { db, recovered, noteRecovered, close() { try {
+                db.close();
+            }
+            catch { /* closed */ } } };
+    }
+    return { openWithRetry, connectionState };
 }

package/runtime/engine/db/machine-open.d.mts

@@ -0,0 +1,26 @@
+import type { IncidentReporter } from './machine-connection.mjs';
+import type { SqlDb } from './sqlite-types.mjs';
+export declare const pragma: (db: SqlDb, name: string) => unknown;
+/** What the connection opener is bound to: the schema methods, the retrying opener and the corruption reporter of machine.mjs. */
+export interface MachineOpenDeps {
+    checkSchema(db: SqlDb, file: string): void;
+    createSchema(db: SqlDb, context: {
+        file: string;
+        env: NodeJS.ProcessEnv;
+        now: () => number;
+    }): void;
+    openWithRetry<T>(openRaw: () => T, options: {
+        file: string;
+        onCorrupt?: IncidentReporter;
+    }): T;
+    corruptIncident: IncidentReporter;
+}
+/** The connection opener bound to the schema methods and the corruption reporter of machine.mjs. */
+export declare function machineOpenMethods({ checkSchema, createSchema, openWithRetry, corruptIncident }: MachineOpenDeps): {
+    openConnection: (file: string, { readOnly, env, now, onCorrupt }?: {
+        readOnly?: boolean;
+        env?: NodeJS.ProcessEnv;
+        now?: () => number;
+        onCorrupt?: IncidentReporter;
+    }) => SqlDb;
+};