@feasibleone/blong-gogo 1.29.0 → 1.30.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [1.30.0](https://github.com/feasibleone/blong/compare/blong-gogo-v1.29.0...blong-gogo-v1.30.0) (2026-08-21)
+
+
+### Features
+
+* access sessions and audit ([694349f](https://github.com/feasibleone/blong/commit/694349f7e70973b984a30f696d2b6e892b55ec02))
+* improve MySQL handling in CI ([4770eec](https://github.com/feasibleone/blong/commit/4770eec3a24cd38cd1931da1c553e0a804ca58dd))
+
+
+### Bug Fixes
+
+* api gateway wiring ([cbdb743](https://github.com/feasibleone/blong/commit/cbdb7439a997925ca6a4ba07e046ad2809d37218))
+* blong-access-mock, silent error, expected error ([dc00429](https://github.com/feasibleone/blong/commit/dc00429a63a973996d6e94359830cc52d149b995))
+* build ([fc98bed](https://github.com/feasibleone/blong/commit/fc98beda0e7ba800682bd663eeebd4408ce04bf1))
+
 ## [1.29.0](https://github.com/feasibleone/blong/compare/blong-gogo-v1.28.0...blong-gogo-v1.29.0) (2026-08-19)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feasibleone/blong-gogo",
-  "version": "1.29.0",
+  "version": "1.30.0",
   "repository": {
     "url": "git+https://github.com/feasibleone/blong.git"
   },
@@ -87,6 +87,7 @@
     "playwright": "^1.60.0",
     "tap": "^21.6.3",
     "typescript": "^6.0.3",
+    "vite": "^8.2.1",
     "@feasibleone/blong-dev": "1.2.0"
   },
   "scripts": {

package/src/AdapterBase.ts

@@ -183,6 +183,7 @@ export class AdapterBase<T, C extends IContext> implements AdapterHandlerContext
 
     error(error: ITypedError, $meta: IMeta): ITypedError {
         if ($meta) error.method = $meta.method;
+        if (error.silent) return error;
         if (isExpectedError(error.type, $meta?.expect)) {
             (this.log as {debug?: (...args: unknown[]) => void})?.debug?.(error);
             return error;

package/src/Gateway.ts

@@ -78,6 +78,17 @@ interface IConfig extends IConfigMLE {
      * then enforces that every request's methodId is in the allowed list.
      */
     authorize?: string;
+    /**
+     * Optional access-check audit.  When set, the gateway records every
+     * authorization decision (allow/deny) at the access-check point into the
+     * configured handler, plus sanitised DML context for access.* write
+     * methods.  `exclude` lists methodId patterns (exact or `prefix*`) that
+     * must not be audited.  Best-effort — audit failures never block requests.
+     */
+    audit?: {
+        handler: string;
+        exclude?: string[];
+    };
     errorFields: unknown[];
     jwt: {
         cache: object;
@@ -171,6 +182,7 @@ export default class Gateway extends Internal implements IGateway {
         debug: false,
         expectedErrors: false,
         authorize: undefined,
+        audit: undefined,
         errorFields: [],
         jwt: {
             cache: {},
@@ -369,6 +381,8 @@ export default class Gateway extends Internal implements IGateway {
                     ...(value.bundle !== undefined && {bundle: value.bundle}),
                     ...(value.creditCost !== undefined && {creditCost: value.creditCost}),
                     ...(value.meter !== undefined && {meter: value.meter}),
+                    ...(value.audit !== undefined && {audit: value.audit}),
+                    ...(value.skipAuthorize && {skipAuthorize: true}),
                 },
                 schema: Type && {
                     ...('body' in value
@@ -530,18 +544,23 @@ export default class Gateway extends Internal implements IGateway {
                             httpResponse?: unknown;
                             [key: string]: unknown;
                         };
-                        if (
-                            isExpectedError(typedError.type as string | undefined, resolvedExpect)
-                        ) {
-                            request.log.debug(
-                                {err: error, method: methodName},
-                                'gateway expected error',
-                            );
-                        } else {
-                            request.log.error(
-                                {err: error, method: methodName},
-                                'gateway handler error',
-                            );
+                        if (!typedError.silent) {
+                            if (
+                                isExpectedError(
+                                    typedError.type as string | undefined,
+                                    resolvedExpect,
+                                )
+                            ) {
+                                request.log.debug?.(
+                                    {err: error, method: methodName},
+                                    'gateway expected error',
+                                );
+                            } else {
+                                request.log.error?.(
+                                    {err: error, method: methodName},
+                                    'gateway handler error',
+                                );
+                            }
                         }
                         this._applyMeta(
                             reply
@@ -614,6 +633,7 @@ export default class Gateway extends Internal implements IGateway {
                 errors: this.#errors,
                 audience: this.#config.jwt.audience,
                 authorize: this.#config.authorize,
+                audit: this.#config.audit,
                 local: this.#local,
                 methodId: methodId,
                 methodParts: methodParts,

package/src/adapter/browser.ts

@@ -1,3 +1,4 @@
+/// <reference types="vite/client" />
 import {realm} from '@feasibleone/blong/types';
 
 export default realm(blong => ({

package/src/adapter/schema/knex/json.test.ts

@@ -11,9 +11,11 @@ import {test} from 'tap';
 
 import {
     isDeadlock,
+    isRetryableConnectionError,
     parseJsonResult,
     parseJsonRow,
     stringifyJsonValues,
+    withConnectionRetry,
     wrapJsonBuilder,
     wrapKnex,
 } from './json.ts';
@@ -216,6 +218,173 @@ test('wrapKnex transaction() wraps the resolved trx (promise form)', async t =>
     t.end();
 });
 
+const CONN_LOST = {
+    code: 'PROTOCOL_CONNECTION_LOST',
+    fatal: true,
+    sql: 'UPDATE `t` SET `x` = 1',
+    sqlMessage: 'Connection lost: The server closed the connection.',
+    message: 'Connection lost: The server closed the connection.',
+};
+
+const DUP_ENTRY = {errno: 1062, code: 'ER_DUP_ENTRY', message: 'Duplicate entry'};
+
+const BOOM = new Error('boom');
+
+test('isRetryableConnectionError detects transient connection errors only', t => {
+    t.equal(
+        isRetryableConnectionError({code: 'PROTOCOL_CONNECTION_LOST', fatal: true}),
+        true,
+        'PROTOCOL_CONNECTION_LOST with fatal flag',
+    );
+    t.equal(isRetryableConnectionError({fatal: true}), true, 'fatal flag alone');
+    t.equal(isRetryableConnectionError({code: 'ECONNRESET'}), true, 'ECONNRESET');
+    t.equal(isRetryableConnectionError({code: 'ER_CON_COUNT_ERROR'}), true, 'too many connections');
+    t.equal(
+        isRetryableConnectionError({code: 'ER_LOCK_DEADLOCK', errno: 1213}),
+        false,
+        'deadlock is not a connection error',
+    );
+    t.equal(isRetryableConnectionError(DUP_ENTRY), false, 'constraint violation');
+    t.equal(isRetryableConnectionError(BOOM), false, 'plain error');
+    t.equal(isRetryableConnectionError(null), false, 'null');
+    t.equal(isRetryableConnectionError('PROTOCOL_CONNECTION_LOST'), false, 'string');
+    t.end();
+});
+
+test('withConnectionRetry runs once when retry is disabled (default)', async t => {
+    let calls = 0;
+    const run = async () => {
+        calls += 1;
+        throw CONN_LOST;
+    };
+    await t.rejects(withConnectionRetry(run, {}), CONN_LOST, 'error propagates');
+    t.equal(calls, 1, 'exactly one attempt');
+    t.end();
+});
+
+test('withConnectionRetry retries transient connection errors and recovers', async t => {
+    let calls = 0;
+    const run = async () => {
+        calls += 1;
+        if (calls < 3) throw CONN_LOST;
+        return 'ok';
+    };
+    const result = await withConnectionRetry(run, {
+        retry: {enabled: true, maxRetries: 3, backoffMs: 1},
+    });
+    t.equal(result, 'ok');
+    t.equal(calls, 3, 'first attempt + two retries');
+    t.end();
+});
+
+test('withConnectionRetry does not retry non-connection errors', async t => {
+    let calls = 0;
+    const run = async () => {
+        calls += 1;
+        throw DUP_ENTRY;
+    };
+    await t.rejects(
+        withConnectionRetry(run, {retry: {enabled: true, maxRetries: 3, backoffMs: 1}}),
+        DUP_ENTRY,
+    );
+    t.equal(calls, 1, 'constraint violations are not retried');
+    t.end();
+});
+
+test('withConnectionRetry gives up after maxRetries and surfaces the error', async t => {
+    let calls = 0;
+    const run = async () => {
+        calls += 1;
+        throw CONN_LOST;
+    };
+    await t.rejects(
+        withConnectionRetry(run, {retry: {enabled: true, maxRetries: 2, backoffMs: 1}}),
+        CONN_LOST,
+        'final error surfaces',
+    );
+    t.equal(calls, 3, 'first attempt + maxRetries retries');
+    t.end();
+});
+
+test('wrapJsonBuilder recovers a transient connection error via clone re-execution', async t => {
+    const builder = makeFlakyBuilder(2, CONN_LOST);
+    const wrapped = wrapJsonBuilder(builder, {
+        retry: {enabled: true, maxRetries: 5, backoffMs: 1},
+    });
+
+    const result = await wrapped.then((value: unknown) => value);
+    t.same(result, {ok: 3}, 'query succeeds after two dropped connections');
+    t.equal(builder.attempts(), 3, 'original + two clone re-executions');
+    t.end();
+});
+
+test('wrapJsonBuilder reports connection errors via onConnectionError', async t => {
+    const reported: unknown[] = [];
+    const builder = makeFlakyBuilder(1, CONN_LOST);
+    const wrapped = wrapJsonBuilder(builder, {
+        retry: {enabled: true, maxRetries: 3, backoffMs: 1},
+        onConnectionError: error => reported.push(error),
+    });
+
+    const result = await wrapped.then((value: unknown) => value);
+    t.same(result, {ok: 2}, 'recovers');
+    t.same(reported, [CONN_LOST], 'the dropped connection was reported');
+    t.end();
+});
+
+test('wrapJsonBuilder does not retry when retry is disabled', async t => {
+    const reported: unknown[] = [];
+    const builder = makeFlakyBuilder(1, CONN_LOST);
+    const wrapped = wrapJsonBuilder(builder, {
+        onConnectionError: error => reported.push(error),
+    });
+
+    await t.rejects(Promise.resolve(wrapped.then(null, null)), CONN_LOST, 'error propagates');
+    t.equal(builder.attempts(), 1, 'exactly one attempt');
+    t.same(reported, [CONN_LOST], 'connection error still reported for diagnostics');
+    t.end();
+});
+
+test('wrapJsonBuilder never retries non-connection errors', async t => {
+    const builder = makeFlakyBuilder(1, BOOM);
+    const wrapped = wrapJsonBuilder(builder, {
+        retry: {enabled: true, maxRetries: 3, backoffMs: 1},
+    });
+
+    await t.rejects(Promise.resolve(wrapped.then(null, null)), /boom/, 'error propagates');
+    t.equal(builder.attempts(), 1, 'plain errors are not retried');
+    t.end();
+});
+
+test('wrapKnex raw() retries transient connection errors by re-invoking raw', async t => {
+    let calls = 0;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const fakeKnex = (() => undefined) as any;
+    fakeKnex.raw = () => {
+        calls += 1;
+        const ok = calls > 1;
+        return {
+            then(
+                onFulfilled?: (value: unknown) => unknown,
+                onRejected?: (reason: unknown) => unknown,
+            ) {
+                return ok
+                    ? Promise.resolve({rows: [{n: calls}]}).then(onFulfilled, onRejected)
+                    : Promise.reject(CONN_LOST).then(onFulfilled, onRejected);
+            },
+        };
+    };
+    const wrapped = wrapKnex(fakeKnex, {
+        retry: {enabled: true, maxRetries: 3, backoffMs: 1},
+    });
+
+    const raw = wrapped.raw('CALL something()');
+    const result = await Promise.resolve(raw.then((value: unknown) => value));
+    t.same(result, {rows: [{n: 2}]}, 'raw re-invoked on retry');
+    t.equal(calls, 2, 'knex.raw called twice');
+    t.end();
+});
+
 /** A minimal knex-like builder whose `then` rejects with `error`. */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function makeRejectingBuilder(error: unknown): any {
@@ -241,3 +410,32 @@ function makeRejectingThenable(error: unknown): any {
         },
     };
 }
+
+/**
+ * A knex-like builder whose first `failures` `then` calls reject with `error`
+ * and whose later calls resolve. `clone()` returns a fresh builder sharing the
+ * same attempt counter, mirroring how the retry path re-runs a cloned builder.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function makeFlakyBuilder(failures: number, error: unknown): any {
+    let attempts = 0;
+    const make = () => ({
+        insert(..._args: unknown[]) {
+            return this;
+        },
+        update(..._args: unknown[]) {
+            return this;
+        },
+        then(onFulfilled?: (value: unknown) => unknown, onRejected?: (reason: unknown) => unknown) {
+            attempts += 1;
+            return attempts <= failures
+                ? Promise.reject(error).then(onFulfilled, onRejected)
+                : Promise.resolve({ok: attempts}).then(onFulfilled, onRejected);
+        },
+        clone() {
+            return make();
+        },
+        attempts: () => attempts,
+    });
+    return make();
+}

package/src/adapter/schema/knex/json.ts

@@ -17,6 +17,8 @@
  * `access_credential.credentialParamsJSON`.
  */
 
+import {type IKnexRetryOptions} from './types.ts';
+
 /** Column names ending in `JSON` are treated as JSON documents. */
 const JSON_COLUMN = /JSON$/;
 
@@ -36,11 +38,78 @@ export function isDeadlock(error: unknown): boolean {
 }
 
 /**
- * Optional hooks applied while wrapping the shared knex instance.
+ * Error codes that indicate a *transient* MySQL connection failure worth
+ * retrying — the server closed the socket, the pool hit the server's
+ * `max_connections`, or the TCP link was reset. `fatal: true` is the generic
+ * marker mysql2 sets for errors that invalidate the connection (it is set on
+ * `PROTOCOL_CONNECTION_LOST`, the error observed intermittently in CI).
+ */
+const RETRYABLE_CONNECTION_CODES = new Set([
+    'PROTOCOL_CONNECTION_LOST',
+    'PROTOCOL_ENQUEUE_AFTER_FATAL_ERROR',
+    'ECONNRESET',
+    'ETIMEDOUT',
+    'ER_CON_COUNT_ERROR', // Too many connections (server max_connections)
+    'ER_SERVER_SHUTDOWN', // Server shutting down
+    'ER_ABORTING_CONNECTION',
+]);
+
+/**
+ * Whether a query error is a transient connection failure the adapter may
+ * retry. Only connection-level failures qualify — deadlocks, constraint
+ * violations and ordinary SQL errors are never retried here.
+ */
+export function isRetryableConnectionError(error: unknown): boolean {
+    if (!error || typeof error !== 'object') return false;
+    const {code, fatal} = error as {code?: unknown; fatal?: unknown};
+    return fatal === true || (typeof code === 'string' && RETRYABLE_CONNECTION_CODES.has(code));
+}
+
+/**
+ * Optional hooks and behaviour applied while wrapping the shared knex instance.
  */
 export interface WrapKnexOptions {
     /** Invoked when a query rejects with a deadlock error, before the caller's rejection handler. */
     onDeadlock?: (error: unknown) => void;
+    /**
+     * Invoked when a query rejects with a transient connection error (before the
+     * caller's rejection handler). Fired on every failed attempt — including when
+     * retry is disabled — so connection drops can be logged for diagnostics.
+     */
+    onConnectionError?: (error: unknown) => void;
+    /**
+     * Opt-in retry of transient connection errors. Non-prod only — disabled by
+     * default; enable via the `knex.retry` config block (see `srv.db`).
+     */
+    retry?: IKnexRetryOptions;
+}
+
+/**
+ * Run `run()` once; if it rejects with a transient connection error and retry
+ * is enabled, re-run it (up to `maxRetries`) with linear backoff
+ * (`backoffMs * attempt`). Between attempts the knex pool re-establishes a
+ * healthy connection, so a query that hit a dead socket usually succeeds on the
+ * next attempt. When retry is disabled (default) the query runs exactly once.
+ */
+export async function withConnectionRetry<T>(
+    run: () => Promise<T>,
+    options: WrapKnexOptions,
+): Promise<T> {
+    const retry = options.retry;
+    if (!retry?.enabled) return run();
+    const maxRetries = retry.maxRetries ?? 3;
+    const backoffMs = retry.backoffMs ?? 250;
+    let attempt = 0;
+    for (;;) {
+        try {
+            return await run();
+        } catch (error) {
+            if (!isRetryableConnectionError(error)) throw error;
+            if (attempt >= maxRetries) throw error;
+            attempt += 1;
+            await new Promise(resolve => setTimeout(resolve, backoffMs * attempt));
+        }
+    }
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -96,7 +165,8 @@ export function parseJsonResult(result: unknown): unknown {
  * Only `insert`, `update`, and `then` are intercepted — all other builder
  * behaviour is untouched.  Chained calls keep working because knex builder
  * methods return the same instance.  The `then` rejection path is also
- * intercepted to detect MySQL deadlocks and report them via `options.onDeadlock`.
+ * intercepted to detect MySQL deadlocks and report them via `options.onDeadlock`,
+ * and to retry transient connection errors via `options.retry`.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function wrapJsonBuilder(builder: any, options: WrapKnexOptions = {}): any {
@@ -123,40 +193,83 @@ export function wrapJsonBuilder(builder: any, options: WrapKnexOptions = {}): an
     builder.then = (
         onFulfilled?: ((value: unknown) => unknown) | null,
         onRejected?: ((reason: unknown) => unknown) | null,
-    ) =>
-        originalThen(
-            (result: unknown) => {
-                const processed = parseJsonResult(result);
-                return typeof onFulfilled === 'function' ? onFulfilled(processed) : processed;
-            },
-            (reason: unknown) => {
-                if (isDeadlock(reason)) options.onDeadlock?.(reason);
-                if (typeof onRejected === 'function') return onRejected(reason);
-                throw reason;
-            },
-        );
+    ) => {
+        // Each attempt runs the query again. The first attempt executes the
+        // original builder via its captured `then`; retries re-run a fresh
+        // clone (knex builders are single-shot) whose `then` is the original
+        // prototype method — re-acquiring a healthy connection from the pool.
+        let attempt = 0;
+        const execute = () => {
+            const cloneable = typeof builder.clone === 'function';
+            const target = attempt === 0 || !cloneable ? null : builder.clone();
+            const thenFn = target ? target.then.bind(target) : originalThen;
+            attempt += 1;
+            return new Promise<unknown>((resolve, reject) => {
+                thenFn(
+                    (result: unknown) => {
+                        const processed = parseJsonResult(result);
+                        resolve(
+                            typeof onFulfilled === 'function' ? onFulfilled(processed) : processed,
+                        );
+                    },
+                    (reason: unknown) => {
+                        if (isDeadlock(reason)) options.onDeadlock?.(reason);
+                        if (isRetryableConnectionError(reason)) options.onConnectionError?.(reason);
+                        reject(reason);
+                    },
+                );
+            });
+        };
+        return withConnectionRetry(execute, options).then(undefined, (reason: unknown) => {
+            if (typeof onRejected === 'function') return onRejected(reason);
+            throw reason;
+        });
+    };
 
     return builder;
 }
 
 /**
  * Intercept the `then` rejection path of a thenable (e.g. a knex `Raw` result)
- * so MySQL deadlocks are reported via `options.onDeadlock`. Mirrors the
- * rejection interception in {@link wrapJsonBuilder} without the JSON column
- * handling, which does not apply to `raw` queries / stored-procedure calls.
+ * so MySQL deadlocks are reported via `options.onDeadlock` and transient
+ * connection errors are reported via `options.onConnectionError` / retried via
+ * `options.retry`. `rerun()` re-creates the query (e.g. re-invoking
+ * `knex.raw(...)` with the same args) so a connection failure can be retried.
+ * Mirrors the rejection interception in {@link wrapJsonBuilder} without the JSON
+ * column handling, which does not apply to `raw` queries / stored-procedure calls.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-function attachDeadlockHook(thenable: any, options: WrapKnexOptions): any {
+function attachQueryHook(thenable: any, options: WrapKnexOptions, rerun: () => any): any {
     const originalThen = thenable.then.bind(thenable);
     thenable.then = (
         onFulfilled?: ((value: unknown) => unknown) | null,
         onRejected?: ((reason: unknown) => unknown) | null,
-    ) =>
-        originalThen(onFulfilled, (reason: unknown) => {
-            if (isDeadlock(reason)) options.onDeadlock?.(reason);
+    ) => {
+        // The first attempt runs the original thenable via its captured `then`;
+        // retries re-invoke `rerun()` to obtain a fresh thenable backed by a new
+        // query (and, for raw, a freshly acquired pool connection).
+        let attempt = 0;
+        const execute = () => {
+            const target = attempt === 0 ? null : rerun();
+            const thenFn = target ? target.then.bind(target) : originalThen;
+            attempt += 1;
+            return new Promise<unknown>((resolve, reject) => {
+                thenFn(
+                    (result: unknown) =>
+                        resolve(typeof onFulfilled === 'function' ? onFulfilled(result) : result),
+                    (reason: unknown) => {
+                        if (isDeadlock(reason)) options.onDeadlock?.(reason);
+                        if (isRetryableConnectionError(reason)) options.onConnectionError?.(reason);
+                        reject(reason);
+                    },
+                );
+            });
+        };
+        return withConnectionRetry(execute, options).then(undefined, (reason: unknown) => {
             if (typeof onRejected === 'function') return onRejected(reason);
             throw reason;
         });
+    };
     return thenable;
 }
 
@@ -186,7 +299,8 @@ export function wrapKnex<T>(knex: T, options: WrapKnexOptions = {}): T {
                 const original = Reflect.get(target, prop, target);
                 if (typeof original !== 'function') return original;
                 const bound = original.bind(target);
-                return (...args: unknown[]) => attachDeadlockHook(bound(...args), options);
+                return (...args: unknown[]) =>
+                    attachQueryHook(bound(...args), options, () => bound(...args));
             }
             if (prop === 'transaction') {
                 const original = Reflect.get(target, prop, target);

package/src/adapter/schema/knex/types.ts

@@ -135,9 +135,33 @@ export interface IKnexConnection {
     user?: string;
     password?: string;
     database?: string;
+    /**
+     * mysql2 TCP keep-alive. When `true`, idle connections send keep-alive
+     * probes so a server/proxy/LB silently closing an idle socket is noticed
+     * promptly instead of surfacing later as a mid-query
+     * `PROTOCOL_CONNECTION_LOST`. Enabled for non-prod via the shared `srv.db`
+     * adapter (`core/blong-server/adapter/db.ts`).
+     */
+    enableKeepAlive?: boolean;
     [key: string]: unknown;
 }
 
+/**
+ * Opt-in retry of transient fatal connection errors (e.g. mysql2
+ * `PROTOCOL_CONNECTION_LOST`). Intended for non-prod environments (CI / dev)
+ * where a single dropped connection must not abort a whole test run. Disabled
+ * by default so production behaviour is unchanged — enable explicitly via the
+ * `knex.retry` config block (see `core/blong-server/adapter/db.ts`).
+ */
+export interface IKnexRetryOptions {
+    /** When `true`, queries that fail with a transient connection error are retried. Default `false`. */
+    enabled?: boolean;
+    /** Maximum number of retry attempts per query (excluding the first attempt). Default `3`. */
+    maxRetries?: number;
+    /** Base delay before the first retry (ms); each retry waits `backoffMs * attempt`. Default `250`. */
+    backoffMs?: number;
+}
+
 /** The `knex` config block of a DB adapter (adapter.knex / the shared `srv.db`). */
 export interface IKnexConfig {
     client?: string;
@@ -149,6 +173,17 @@ export interface IKnexConfig {
      * `default` / `ci` / `prod`, where the database is provisioned externally.
      */
     createDatabase?: boolean;
+    /**
+     * Knex/tarn pool options (passed through to the `knex` pool config, e.g.
+     * `maxConnectionLifetimeMillis` to recycle long-lived connections).
+     */
+    pool?: {
+        /** Max lifetime of a pooled connection in ms before it is recycled. */
+        maxConnectionLifetimeMillis?: number;
+        [key: string]: unknown;
+    };
+    /** Opt-in retry of transient fatal connection errors — non-prod only. */
+    retry?: IKnexRetryOptions;
     [key: string]: unknown;
 }
 

package/src/adapter/server/knex-deadlock.test.ts

@@ -12,7 +12,7 @@
 import {test} from 'tap';
 
 import {wrapKnex} from '../schema/knex/json.ts';
-import {logKnexDeadlock} from './knex.ts';
+import {logKnexConnectionError, logKnexDeadlock} from './knex.ts';
 
 function makeLog(): {log: {error: (...a: unknown[]) => void}; calls: Array<{args: unknown[]}>} {
     const calls: Array<{args: unknown[]}> = [];
@@ -97,6 +97,78 @@ test('wrapKnex onDeadlock wiring logs the deadlock (as wired in adapter start())
     t.end();
 });
 
+// Shaped like a real mysql2 connection-lost error: `fatal: true` plus the
+// `PROTOCOL_CONNECTION_LOST` code observed intermittently in CI.
+const CONN_LOST = {
+    code: 'PROTOCOL_CONNECTION_LOST',
+    fatal: true,
+    sql: 'UPDATE `t` SET `x` = 1',
+    sqlMessage: 'Connection lost: The server closed the connection.',
+    message: 'Connection lost: The server closed the connection.',
+};
+
+const EXPECTED_CONN_ENTRY = {
+    err: CONN_LOST.message,
+    code: 'PROTOCOL_CONNECTION_LOST',
+    errno: undefined,
+    fatal: true,
+    sql: CONN_LOST.sql,
+    sqlMessage: CONN_LOST.sqlMessage,
+};
+
+test('logKnexConnectionError logs full connection-error details when config.debug is set', t => {
+    const {log, calls} = makeLog();
+    logKnexConnectionError({debug: true}, log, CONN_LOST);
+
+    t.equal(calls.length, 1, 'logged exactly once');
+    t.same(calls[0].args[0], EXPECTED_CONN_ENTRY, 'entry carries err, code, errno, fatal, sql');
+    t.equal(calls[0].args[1], 'knex connection error', 'message is "knex connection error"');
+    t.end();
+});
+
+test('logKnexConnectionError logs when logLevel is debug', t => {
+    const {log, calls} = makeLog();
+    logKnexConnectionError({logLevel: 'debug'}, log, CONN_LOST);
+    t.equal(calls.length, 1, 'logged once');
+    t.end();
+});
+
+test('logKnexConnectionError stays silent unless debug or logLevel debug', t => {
+    const {log, calls} = makeLog();
+    logKnexConnectionError({logLevel: 'info'}, log, CONN_LOST);
+    logKnexConnectionError({}, log, CONN_LOST);
+    t.same(calls, [], 'no log entries when gating is off');
+    t.end();
+});
+
+test('logKnexConnectionError maps a plain Error to its message and tolerates a missing log', t => {
+    const {log, calls} = makeLog();
+    logKnexConnectionError({debug: true}, log, new Error('boom'));
+    t.equal((calls[0].args[0] as {err?: unknown}).err, 'boom', 'err is the error message');
+    t.doesNotThrow(() => logKnexConnectionError({debug: true}, undefined, CONN_LOST), 'no log');
+    t.doesNotThrow(
+        () => logKnexConnectionError({debug: true}, {}, CONN_LOST),
+        'log without error()',
+    );
+    t.end();
+});
+
+test('wrapKnex onConnectionError wiring logs the drop (as wired in adapter start())', async t => {
+    const {log, calls} = makeLog();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const fakeKnex = (() => makeRejectingBuilder(CONN_LOST)) as any;
+    const wrapped = wrapKnex(fakeKnex, {
+        onConnectionError: error => logKnexConnectionError({debug: true}, log, error),
+    });
+    const builder = wrapped('deadlock_demo');
+
+    await t.rejects(Promise.resolve(builder.then(null, null)), CONN_LOST, 'query still rejects');
+    t.equal(calls.length, 1, 'connection error logged once');
+    t.equal(calls[0].args[1], 'knex connection error', 'logged with the connection message');
+    t.same(calls[0].args[0], EXPECTED_CONN_ENTRY, 'full connection-error details logged');
+    t.end();
+});
+
 /** A minimal knex-like builder whose `then` rejects with `error`. */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function makeRejectingBuilder(error: unknown): any {

package/src/adapter/server/knex.ts

@@ -106,6 +106,41 @@ export function logKnexDeadlock(
     );
 }
 
+/**
+ * Log transient MySQL connection-error details (including the offending query)
+ * in dev mode. Called from the `wrapKnex` `onConnectionError` hook whenever a
+ * query path through the wrapped knex fails with a fatal/connection error
+ * (`PROTOCOL_CONNECTION_LOST` and similar) — whether or not retry is enabled.
+ * This is the diagnostics breadcrumb for the intermittent CI connection drops:
+ * it records which query failed and how the pool was doing at that moment.
+ */
+export function logKnexConnectionError(
+    config: {debug?: boolean; logLevel?: string},
+    log: unknown,
+    error: unknown,
+): void {
+    if (!config.debug && config.logLevel !== 'debug') return;
+    const err = error as {
+        message?: string;
+        code?: string;
+        errno?: number;
+        fatal?: boolean;
+        sql?: string;
+        sqlMessage?: string;
+    };
+    (log as {error?: (...args: unknown[]) => void})?.error?.(
+        {
+            err: err.message ?? err,
+            code: err.code,
+            errno: err.errno,
+            fatal: err.fatal,
+            sql: err.sql,
+            sqlMessage: err.sqlMessage,
+        },
+        'knex connection error',
+    );
+}
+
 export default adapter<IConfig>(({utError, schema: objectSchema}) => {
     _errors ||= utError.register(errorMap);
 
@@ -165,6 +200,9 @@ export default adapter<IConfig>(({utError, schema: objectSchema}) => {
             this.config.context = {
                 queryBuilder: wrapKnex(KnexLib(this.config.knex), {
                     onDeadlock: error => logKnexDeadlock(this.config, this.log, error),
+                    onConnectionError: error =>
+                        logKnexConnectionError(this.config, this.log, error),
+                    retry: this.config.knex.retry,
                 }) as unknown as Knex,
             };
             super.connect();
@@ -341,6 +379,9 @@ export default adapter<IConfig>(({utError, schema: objectSchema}) => {
             this.config.context = {
                 queryBuilder: wrapKnex(KnexLib(newKnexConfig as object), {
                     onDeadlock: error => logKnexDeadlock(this.config, this.log, error),
+                    onConnectionError: error =>
+                        logKnexConnectionError(this.config, this.log, error),
+                    retry: (newKnexConfig as IKnexConfig).retry ?? this.config.knex.retry,
                 }) as unknown as Knex,
             };
         },

package/src/codec/adapter/mle/ready.ts

@@ -62,8 +62,11 @@ export default handler<{
 
     // Public (auth: 'login') endpoints — pre-auth callers hold no blong token, so the MLE
     // request is encrypted with the handshake keys carried in the JWE protected header.
-    // Shared by the loginTokenCreate / accessRegistrationAdd / loginTokenExchange request senders.
-    const encryptPublic = async (params: {$http?: unknown}): Promise<{$http?: unknown}> => {
+    // Shared by the loginTokenCreate / accessRegistrationAdd / loginTokenExchange /
+    // loginTokenRefresh / loginTokenRestore request senders.
+    const encryptPublic = async (
+        params: {$http?: unknown} & Record<string, unknown>,
+    ): Promise<{$http?: unknown} & Record<string, unknown>> => {
         if (!jose) return params;
         const {$http, ...rest} = params;
         const encrypted = (await encrypt(rest, {
@@ -89,34 +92,74 @@ export default handler<{
         refreshTokenExpire = 0;
     }
 
+    /**
+     * Redeem a refresh token at `login.token.refresh` (auth: 'login' — MLE
+     * handshake keys, plain JSON-RPC response).  On success the new access +
+     * refresh tokens are stored in memory.  On refusal (revoked / inactive /
+     * expired session) the tokens are cleared so the next request surfaces a
+     * clean 401 to the caller, which the UI turns into a login prompt.
+     */
     async function refresh(this: {
         exec?(...params: unknown[]): Promise<unknown>;
         error?(error: unknown, $meta?: unknown): void;
-    }): Promise<void> {
+    }, opts: {force?: boolean} = {}): Promise<void> {
         const now = Date.now();
-        if (token && tokenExpire < now) {
+        if (token && (opts.force || tokenExpire < now)) {
             if (refreshToken && refreshTokenExpire > now) {
                 try {
                     pending =
                         pending ||
-                        (this.exec!(
-                            {
-                                path: '/rpc/login/token',
-                                method: 'POST',
-                                form: {
-                                    grant_type: 'refresh_token',
-                                    refresh_token: refreshToken,
+                        (async () => {
+                            const params = await encryptPublic({refreshToken});
+                            const result = (await this.exec!(
+                                {
+                                    path: '/rpc/login/token/refresh',
+                                    method: 'POST',
+                                    responseType: 'json',
+                                    json: {
+                                        jsonrpc: '2.0',
+                                        id: 1,
+                                        method: 'login.token.refresh',
+                                        params,
+                                    },
                                 },
-                            },
-                            {},
-                        ) as Promise<{body?: unknown}>);
+                                {},
+                            )) as {
+                                statusCode?: number;
+                                body?: {result?: IToken; error?: {type?: string; message?: string; statusCode?: number}};
+                            };
+                            return result;
+                        })();
                     const result = await pending!;
                     if (pending !== null) pending = null;
-                    readToken(result.body as IToken);
+                    const {body, statusCode} = result as {
+                        statusCode?: number;
+                        body?: {result?: IToken; error?: {type?: string; message?: string; statusCode?: number}};
+                    };
+                    // The gateway MLE-encrypts the response with the handshake
+                    // keys, so decrypt the result before reading the token.
+                    await decrypt(body as object, 'result');
+                    if (body?.error || (statusCode != null && statusCode >= 400)) {
+                        clearTokens();
+                        const error = new Error(
+                            body?.error?.message || 'Token refresh failed',
+                        ) as Error & {
+                            type?: string;
+                            statusCode?: number;
+                            auth?: boolean;
+                        };
+                        error.type = body?.error?.type || 'rpc.refreshFailed';
+                        error.statusCode = body?.error?.statusCode ?? statusCode ?? 401;
+                        error.auth = true;
+                        throw error;
+                    }
+                    readToken(body!.result as IToken);
                 } catch (error) {
                     pending = null;
-                    clearTokens();
-                    this.error!(error);
+                    // Keep auth-classified failures as-is; otherwise drop tokens
+                    // so the next request reports a clean 401.
+                    if (!(error as {auth?: boolean}).auth) clearTokens();
+                    throw error;
                 }
             } else clearTokens();
         }
@@ -184,6 +227,12 @@ export default handler<{
                 $http.headers.authorization = 'Bearer ' + token;
             }
             if ($http && params) params.$http = $http;
+            // An unexpected 401 is surfaced as-is: the automatic pre-send
+            // `refresh()` above already renewed the token when it was close to
+            // expiry, so a 401 here means the session is genuinely unusable
+            // (e.g. revoked/closed server-side) — a forced renewal would only
+            // add a failing round-trip.  The UI turns the 401 into a login
+            // prompt.
             return super.send(params, $meta);
         },
         async receive(
@@ -214,6 +263,18 @@ export default handler<{
         },
         async loginTokenCreateResponseReceive(result: Response<{result: unknown}>, $meta: unknown) {
             await decrypt(result.body, 'result');
+            if ((result.body as {error?: unknown})?.error) return super.receive(result, $meta);
+            readToken(result.body.result as IToken);
+            return super.receive(result, $meta);
+        },
+        // Explicit token renewal (auth: 'login') — the same path the automatic
+        // `refresh()` uses; feeds the new tokens into memory.
+        async loginTokenRefreshRequestSend(params: {$http?: unknown}, $meta: unknown) {
+            return super.send(await encryptPublic(params), $meta);
+        },
+        async loginTokenRefreshResponseReceive(result: Response<{result: unknown}>, $meta: unknown) {
+            await decrypt(result.body, 'result');
+            if ((result.body as {error?: unknown})?.error) return super.receive(result, $meta);
             readToken(result.body.result as IToken);
             return super.receive(result, $meta);
         },
@@ -224,5 +285,16 @@ export default handler<{
         async loginTokenExchangeRequestSend(params: {$http?: unknown}, $meta: unknown) {
             return super.send(await encryptPublic(params), $meta);
         },
+        // Session restore (auth: 'login') — exchanges the path-scoped HttpOnly
+        // cookie for fresh tokens; the response feeds the same readToken path.
+        async loginTokenRestoreRequestSend(params: {$http?: unknown}, $meta: unknown) {
+            return super.send(await encryptPublic(params), $meta);
+        },
+        async loginTokenRestoreResponseReceive(result: Response<{result: unknown}>, $meta: unknown) {
+            await decrypt(result.body, 'result');
+            if ((result.body as {error?: unknown})?.error) return super.receive(result, $meta);
+            readToken(result.body.result as IToken);
+            return super.receive(result, $meta);
+        },
     };
 });

package/src/globals.d.ts

@@ -57,12 +57,6 @@ declare module 'ut-dns-discovery' {
     export default discovery;
 }
 
-// Vite / esbuild glob-import support
-interface ImportMeta {
-    glob(patterns: string | string[]): Record<string, () => Promise<unknown>>;
-    glob<T>(patterns: string | string[], options?: object): Record<string, () => Promise<T>>;
-}
-
 declare module 'picomatch' {
     function picomatch(glob: string | string[], options?: object): (path: string) => boolean;
     export default picomatch;

package/src/jwt.ts

@@ -19,17 +19,140 @@ declare module 'fastify' {
                 permissionMap?: Buffer;
                 actorId?: string | number;
                 sessionId?: string;
+                /** Audit record id of the access-check audit for this request (set by `recordAccessAudit`). */
+                auditId?: string;
                 /** Allowed action methodIds — populated by the authorize handler. */
                 actions?: string[];
             };
         };
     }
     interface FastifyReply {
-        unstate: (name: string) => this;
+        unstate: (name: string, options?: unknown) => this;
         state: (name: string, value: string, options: unknown) => this;
     }
     interface FastifyContextConfig {
         methodName?: string;
+        audit?: boolean;
+        skipAuthorize?: boolean;
+    }
+}
+
+/**
+ * Methods that must never be recorded by the access-check audit — they are
+ * part of the access-control machinery itself and would recurse.
+ */
+const AUDIT_HARD_EXCLUDE = ['access.audit.record', 'access.authorization.list'];
+
+/** Entity tables whose DML carries a sanitised detail summary in the audit. */
+const AUDIT_DML_ENTITIES = [
+    'user',
+    'role',
+    'capability',
+    'action',
+    'credential',
+    'access',
+    'policy',
+    'flow',
+];
+const AUDIT_WRITE_OPS = ['add', 'edit', 'remove', 'insert', 'update', 'delete', 'merge'];
+
+/**
+ * Sanitised DML context for `access.*` write methods — the entity plus its
+ * id/name keys only.  Full params (credentials, hashes, descriptions) are
+ * deliberately never recorded.
+ */
+function auditDetail(methodName: string, params: unknown): object | undefined {
+    const [subject, object, operation] = String(methodName).split('.');
+    if (
+        subject !== 'access' ||
+        !AUDIT_DML_ENTITIES.includes(object) ||
+        !AUDIT_WRITE_OPS.includes(operation)
+    ) {
+        return undefined;
+    }
+    const p = (params && typeof params === 'object' ? params : {}) as Record<string, unknown>;
+    const summary: Record<string, unknown> = {entity: object};
+    for (const [key, value] of Object.entries(p)) {
+        if (
+            /Id$|Name$|Key$/.test(key) &&
+            (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean')
+        ) {
+            summary[key] = value;
+        }
+    }
+    return summary;
+}
+
+/**
+ * Best-effort recording of an access-control decision at the gateway access
+ * check.  Resolves the configured audit handler (like `authorize`) and hands
+ * it a single audit entry with the actor/session/method/outcome plus sanitised
+ * DML context.  The inserted record key is exposed on `request.auth.credentials.
+ * auditId` (→ `$meta.auth.auditId`).  Callers await it but must never let an
+ * audit failure fail the request.
+ */
+async function recordAccessAudit(
+    request: FastifyRequest,
+    audit: {handler: string; exclude?: string[]},
+    methodName: string,
+    allowed: boolean,
+    statusCode: number,
+    local: ILocal,
+    methodIdFn: (name: string) => string,
+    methodPartsFn: (name: string) => string,
+): Promise<void> {
+    // Route-level opt-out (e.g. operations that audit themselves).
+    if (request.routeOptions.config.audit === false) return;
+    const methodIdName = methodIdFn(methodName);
+    if (AUDIT_HARD_EXCLUDE.includes(methodIdName)) return;
+    const excluded = (audit.exclude ?? []).some(pattern => {
+        if (pattern.endsWith('*')) return methodIdName.startsWith(pattern.slice(0, -1));
+        return methodIdName === methodIdFn(pattern);
+    });
+    if (excluded) return;
+
+    const handlerName = methodPartsFn(audit.handler);
+    const reqName = `ports.${handlerName.split('.', 1)[0]}.request`;
+    const handler = local.get(reqName);
+    if (!handler) return;
+
+    const credentials = (request.auth?.credentials ?? {}) as {
+        actorId?: string;
+        sessionId?: string;
+    };
+    const forwarded = (request.headers['x-forwarded-for'] ?? '') as string | string[];
+    const ipAddress =
+        ([] as string[]).concat(forwarded)[0]?.split(',')[0] || request.socket.remoteAddress || '';
+    const params = (request.body as {params?: unknown} | undefined)?.params;
+    const detail = auditDetail(methodName, params);
+    const result = (await handler.method(
+        {
+            audit: [
+                {
+                    actorId: credentials.actorId,
+                    sessionId: credentials.sessionId,
+                    actionName: methodName,
+                    isSuccess: allowed,
+                    statusCode,
+                    ipAddress,
+                    ...(detail && {detail}),
+                },
+            ],
+        },
+        {
+            method: handlerName,
+            mtid: 'request',
+            auth: credentials,
+            ipAddress,
+            httpRequest: {url: request.raw?.url || request.url},
+        },
+    )) as {auditIds?: string[]} | undefined;
+    // Expose the inserted audit record key on the request auth — the gateway's
+    // `_meta()` spreads `req.auth.credentials` into the handler `$meta.auth`, so
+    // the audited handler sees it as `$meta.auth.auditId`.
+    const auditId = result?.auditIds?.[0];
+    if (auditId && request.auth) {
+        request.auth.credentials = {...request.auth.credentials, auditId};
     }
 }
 
@@ -39,6 +162,7 @@ export default fp<{
     verify: IGatewayCodec['verify'];
     errors: Errors<object>;
     authorize?: string;
+    audit?: {handler: string; exclude?: string[]};
     local?: ILocal;
     methodId?: (name: string) => string;
     methodParts?: (name: string) => string;
@@ -51,6 +175,7 @@ export default fp<{
             verify,
             errors,
             authorize,
+            audit,
             local,
             methodId,
             methodParts,
@@ -143,14 +268,18 @@ export default fp<{
 
         // Authorization hook: check the called method against allowed actions
         if (authorize && local && methodId) {
-            fastify.addHook('preHandler', function (request, _reply, done) {
+            fastify.addHook('preHandler', async function (request, _reply) {
                 // Routes with auth: false or auth: 'login' don't go through bearer auth,
                 // so credentials have no actions. Skip the authorization check.
                 if (
                     !request.routeOptions.config.auth ||
                     request.routeOptions.config.auth === 'login'
                 ) {
-                    done();
+                    return;
+                }
+                // Self-service methods (e.g. logout) are bearer-authenticated but
+                // operate only on the caller's own session — no RBAC action needed.
+                if (request.routeOptions.config.skipAuthorize) {
                     return;
                 }
                 // The authorize handler itself must be accessible without authorization,
@@ -160,36 +289,53 @@ export default fp<{
                 if (authorize && methodName && methodParts) {
                     const normalizedMethod = methodParts(authorize);
                     if (methodName === normalizedMethod) {
-                        done();
                         return;
                     }
                 }
                 const credentials = request.auth?.credentials;
                 if (!credentials?.actions) {
-                    done(new Error('Authorization denied: no actions resolved'));
-                    return;
+                    throw new Error('Authorization denied: no actions resolved');
                 }
                 if (!methodName) {
-                    done(); // no method configured — allow (backward compat)
-                    return;
+                    return; // no method configured — allow (backward compat)
                 }
                 const requestedId = methodId(methodName);
-                if (credentials.actions.includes(requestedId)) {
-                    done();
-                } else {
+                const allowed = credentials.actions.includes(requestedId);
+                // Record the access decision along with the access check — applies to
+                // every operation controlled through it.  Best-effort (an audit failure
+                // must never fail the request) but awaited so the inserted `auditId`
+                // lands on `request.auth.credentials.auditId` (→ `$meta.auth.auditId`)
+                // before the business handler runs.
+                if (audit && methodName && local && methodId && methodParts) {
+                    try {
+                        await recordAccessAudit(
+                            request,
+                            audit,
+                            methodName,
+                            allowed,
+                            allowed ? 200 : 403,
+                            local,
+                            methodId,
+                            methodParts,
+                        );
+                    } catch {
+                        // ignore — audit is best-effort
+                    }
+                }
+                if (!allowed) {
                     const error = new Error(
                         `Authorization denied: method "${methodName}" not allowed`,
                     ) as Error & {statusCode: number};
                     error.statusCode = 403;
-                    done(error);
+                    throw error;
                 }
             });
         }
 
         await fastify.register(cookie, {});
         fastify.decorateRequest('auth');
-        fastify.decorateReply('unstate', function (name: string) {
-            return this.clearCookie(name);
+        fastify.decorateReply('unstate', function (name: string, options?: unknown) {
+            return this.clearCookie(name, options as {path?: string});
         });
         (fastify.decorateReply as (name: string, fn: unknown) => void)(
             'state',

package/src/load.ts

@@ -575,6 +575,11 @@ export default async function loadRealm<T extends TSchema>(
                           deps: ['log'],
                           load: () => import(/* @vite-ignore */ './Gateway' + extension),
                       },
+                      {
+                          name: 'apiGateway',
+                          deps: ['log', 'gateway', 'local'],
+                          load: () => import(/* @vite-ignore */ './ApiGateway' + extension),
+                      },
                       {
                           name: 'restFs',
                           deps: ['log', 'gateway'],

package/template/index.browser.ts

@@ -17,6 +17,9 @@ export default browser(blong => ({
         async function ui() {
             return import('@feasibleone/blong-browser/browser.ts');
         },
+        async function login() {
+            return import('@feasibleone/blong-login/browser.ts');
+        },
         async function $subject() {
             return import('./browser.ts');
         },
@@ -30,6 +33,7 @@ export default browser(blong => ({
                     },
                 },
             },
+            login: {},
             $subject: {},
         },
     },