@fuzdev/fuz_app 0.118.0 → 0.120.0

package/dist/db/status.js

@@ -19,6 +19,49 @@ const has_table = async (db, table_name) => {
 		) as exists`, [table_name]);
     return row?.exists ?? false;
 };
+/**
+ * Classify one namespace's tracker rows against the code's list — the pure
+ * core of `query_db_status`.
+ *
+ * Name-prefix verifies `applied_names` (sequence-ascending, empty when the
+ * tracker is absent), mirroring `run_migrations`: they must equal the first
+ * `applied_names.length` code names by position. A divergent history (a
+ * renamed/reordered migration, same count or not) is the exact state the runner
+ * refuses to boot against, so a count-only check would report a database the
+ * runner rejects as up to date. The pending list is the code suffix past the
+ * applied count, clamped, so a binary-older history has no pending tail.
+ *
+ * @param ns - the namespace and its code-side migrations
+ * @param applied_names - the tracker's names for `ns`, sequence-ascending
+ * @returns the namespace's migration status
+ */
+const migration_status = (ns, applied_names) => {
+    const code_names = ns.migrations.map((m) => m.name);
+    const declared = code_names.length;
+    const applied = applied_names.length;
+    let divergence;
+    if (applied > declared) {
+        divergence = { kind: 'binary_older', applied, declared };
+    }
+    else {
+        const position = applied_names.findIndex((name, i) => name !== code_names[i]);
+        if (position !== -1) {
+            divergence = {
+                kind: 'name_mismatch',
+                position,
+                applied: applied_names[position],
+                expected: code_names[position]
+            };
+        }
+    }
+    return {
+        namespace: ns.namespace,
+        applied_names,
+        pending_names: code_names.slice(Math.min(applied, declared)),
+        up_to_date: applied === declared && divergence === undefined,
+        ...(divergence ? { divergence } : {})
+    };
+};
 /**
  * Query database status including connectivity, tables, and migration state.
  *
@@ -61,59 +104,17 @@ export const query_db_status = async (db, namespaces) => {
     // check migration state
     const migrations = [];
     if (namespaces?.length) {
+        // no tracker (a never-migrated database) reads as nothing applied yet
         const sv_exists = await has_table(db, 'schema_version');
-        if (sv_exists) {
-            for (const { namespace, migrations: ns_migrations } of namespaces) {
+        for (const ns of namespaces) {
+            let applied_names = [];
+            if (sv_exists) {
                 const rows = await db.query(`SELECT name FROM schema_version
 					 WHERE namespace = $1
-					 ORDER BY sequence ASC`, [namespace]);
-                const applied_names = rows.map((r) => r.name);
-                const code_names = ns_migrations.map((m) => m.name);
-                const total = code_names.length;
-                const applied = applied_names.length;
-                // Name-prefix verify, mirroring the migration runner: the applied
-                // names must equal the first `applied` code names by position. A
-                // divergent history (a renamed/reordered migration, same count or not)
-                // is the exact state `run_migrations` refuses to boot against, so a
-                // count-only check would report a DB the runner rejects as up-to-date.
-                let divergence;
-                if (applied > total) {
-                    divergence = { kind: 'binary_older', applied, declared: total };
-                }
-                else {
-                    const position = applied_names.findIndex((name, i) => name !== code_names[i]);
-                    if (position !== -1) {
-                        divergence = {
-                            kind: 'name_mismatch',
-                            position,
-                            applied: applied_names[position],
-                            expected: code_names[position]
-                        };
-                    }
-                }
-                // pending = the suffix of code names past the applied count (clamped:
-                // a binary-older history has no pending tail)
-                const pending_names = code_names.slice(Math.min(applied, total));
-                migrations.push({
-                    namespace,
-                    applied_names,
-                    pending_names,
-                    up_to_date: applied === total && pending_names.length === 0 && divergence === undefined,
-                    ...(divergence ? { divergence } : {})
-                });
-            }
-        }
-        else {
-            // no tracker — every namespace shows as "nothing applied yet"
-            for (const { namespace, migrations: ns_migrations } of namespaces) {
-                const code_names = ns_migrations.map((m) => m.name);
-                migrations.push({
-                    namespace,
-                    applied_names: [],
-                    pending_names: code_names,
-                    up_to_date: code_names.length === 0
-                });
+					 ORDER BY sequence ASC`, [ns.namespace]);
+                applied_names = rows.map((r) => r.name);
             }
+            migrations.push(migration_status(ns, applied_names));
         }
     }
     return {
@@ -130,48 +131,175 @@ export const query_db_status = async (db, namespaces) => {
 const format_divergence = (divergence) => {
     switch (divergence.kind) {
         case 'name_mismatch':
-            return `position ${divergence.position}: database has '${divergence.applied}', code has '${divergence.expected}'`;
+            return `position ${divergence.position}: database has \`${divergence.applied}\`, code has \`${divergence.expected}\``;
         case 'binary_older':
             return `database has ${divergence.applied} applied but code declares ${divergence.declared} (binary older than database)`;
     }
 };
 /**
- * Format a `DbStatus` as a human-readable string for CLI output.
+ * The code's declared migration count for a namespace — the report's
+ * denominator. `applied + pending` everywhere but a binary-older history, where
+ * the tracker holds more rows than the code declares and the pending tail is
+ * empty; the declared count is then the one the divergence carries.
+ */
+const declared_count = (m) => m.divergence?.kind === 'binary_older'
+    ? m.divergence.declared
+    : m.applied_names.length + m.pending_names.length;
+/**
+ * Format a `DbStatus` as the body of the human-facing operator report.
+ *
+ * A `tables:` count with one aligned `name  N rows` line per table, then a
+ * `migrations:` header (always printed, even with no namespaces) and one
+ * aligned line per namespace: its state (`up-to-date`, `PENDING <n>`, or
+ * `DIVERGED`), `applied/declared`, and the latest applied name (`(none)` when
+ * nothing is applied). A diverged namespace adds a `diverged:` line, a pending
+ * one a `pending:` line naming the tail. A failed connection renders the single
+ * line `connection: FAILED (<error>)`. Every line ends in a newline.
+ *
+ * The body only — the `database status` / `url:` header belongs to the CLI
+ * script, which holds the URL a `DbStatus` never sees. For a connected status
+ * the output is byte-identical with the Rust twin's `format_db_status`; both
+ * test suites pin the same fixture report.
  *
  * @param status - the status to format
  * @returns multi-line string suitable for console output
  */
 export const format_db_status = (status) => {
-    const lines = [];
     if (!status.connected) {
-        lines.push(`  Connection: FAILED${status.error ? ` (${status.error})` : ''}`);
-        return lines.join('\n');
+        return `  connection: FAILED${status.error ? ` (${status.error})` : ''}\n`;
+    }
+    const lines = [`  tables: ${status.table_count}`];
+    const table_width = Math.max(0, ...status.tables.map((t) => t.name.length));
+    for (const t of status.tables) {
+        lines.push(`    ${t.name.padEnd(table_width)}  ${t.row_count} rows`);
     }
-    lines.push(`  Connection: OK`);
-    lines.push(`  Tables: ${status.table_count}`);
-    if (status.tables.length > 0) {
-        lines.push('');
-        const max_name = Math.max(...status.tables.map((t) => t.name.length));
-        for (const t of status.tables) {
-            lines.push(`    ${t.name.padEnd(max_name)}  ${t.row_count} rows`);
+    lines.push('');
+    lines.push('  migrations:');
+    const ns_width = Math.max(0, ...status.migrations.map((m) => m.namespace.length));
+    const detail_indent = `    ${''.padEnd(ns_width)}    `;
+    for (const m of status.migrations) {
+        const state = m.divergence
+            ? 'DIVERGED'
+            : m.up_to_date
+                ? 'up-to-date'
+                : `PENDING ${m.pending_names.length}`;
+        const latest = m.applied_names.at(-1) ?? '(none)';
+        lines.push(`    ${m.namespace.padEnd(ns_width)}  ${state.padEnd(12)} ${m.applied_names.length}/${declared_count(m)}  latest: ${latest}`);
+        if (m.divergence) {
+            lines.push(`${detail_indent}diverged: ${format_divergence(m.divergence)}`);
+        }
+        else if (m.pending_names.length > 0) {
+            lines.push(`${detail_indent}pending: ${m.pending_names.join(', ')}`);
         }
     }
-    if (status.migrations.length > 0) {
-        lines.push('');
-        lines.push('  Migrations:');
-        for (const m of status.migrations) {
-            const total = m.applied_names.length + m.pending_names.length;
-            if (m.divergence) {
-                lines.push(`    ${m.namespace}: DIVERGED (${m.applied_names.length}/${total}) — ${format_divergence(m.divergence)}`);
-            }
-            else if (m.up_to_date) {
-                lines.push(`    ${m.namespace}: up to date (${m.applied_names.length}/${total})`);
-            }
-            else {
-                const pending_list = m.pending_names.join(', ');
-                lines.push(`    ${m.namespace}: applied ${m.applied_names.length}/${total} (pending: ${pending_list})`);
-            }
+    return lines.join('\n') + '\n';
+};
+/** Printed in place of a database URL `display_db_url` won't render. */
+const UNPARSEABLE_DB_URL = '(not a URL; hidden)';
+/** The port node-postgres dials when the URL names none. */
+const DEFAULT_PG_PORT = '5432';
+const MALFORMED_ESCAPE = /%(?![0-9A-Fa-f]{2})/;
+const HOSTNAME = /^[A-Za-z0-9._-]+$/;
+const SOCKET_DIR = /^\/[A-Za-z0-9._/-]*$/;
+const MISPARSED_USER = /[?=&/#]/;
+const PORT = /^\d{1,5}$/;
+/**
+ * A host as `display_db_url` prints it, or `null` when it isn't an IP literal,
+ * a hostname, or a socket directory. An IPv6 literal serializes through
+ * `new URL`, which canonicalizes it.
+ */
+const display_host = (host) => {
+    if (SOCKET_DIR.test(host))
+        return host.replaceAll('/', '%2F');
+    if (HOSTNAME.test(host))
+        return host;
+    if (!host.includes(':'))
+        return null;
+    try {
+        return new URL(`http://[${host}]`).hostname;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Render a database URL for printing from the parse node-postgres dials —
+ * `new URL`, with pg-connection-string's precedence, where a `user`, `host`, or
+ * `port` query parameter overrides the URL's own — so the line names the server
+ * dialed and no credential can leak however the input spells it.
+ *
+ * A `postgres://` or `postgresql://` URL renders as
+ * `postgres://[user@]host:port[/dbname]`: never the password, and never the
+ * query or fragment (`sslmode` and the like are dropped by design). The scheme
+ * always prints as `postgres://`. The port always prints, `5432` when the URL
+ * names none. The user and database name print percent-encoded with
+ * `encodeURIComponent`, so no control character, escape sequence, or bidi
+ * override reaches the terminal and an `@` can't pose as the separator; each
+ * prints only when non-empty. An IP-literal host prints canonically (IPv6
+ * bracketed); a Unix-socket directory prints with each `/` as `%2F`. A PGlite
+ * `file://` or `memory://` URL prints as scheme, host, and path.
+ *
+ * The whole line is `(not a URL; hidden)` for any other scheme, when `new URL`
+ * rejects the input, when it holds a malformed percent-escape (`%ZZ`), when
+ * there is no host, when the host is neither an IP literal, a hostname of
+ * `A-Z a-z 0-9 . _ -`, nor a socket directory of those characters and `/`, when
+ * the user holds `?`, `=`, `&`, `/`, or `#`, or when the port isn't a number up
+ * to 65535. The host and user rules match the Rust twin's, where they catch
+ * tokio-postgres's split at the first `@`.
+ *
+ * Twin of the Rust `fuz_db` CLI's `display_db_url`, byte-identical on the URLs
+ * both drivers read alike. They part where the drivers do: a `host=` or `port=`
+ * query parameter overrides the URL's here (tokio-postgres appends it to a list
+ * whose first entry the pool dials); a `dbname=` query parameter, which
+ * tokio-postgres honours and node-postgres ignores, and a `#…` fragment, which
+ * tokio-postgres keeps as part of the database name; tokio-postgres also
+ * accepts `key=value` strings, host lists, and an unencoded `/` or `?` in the
+ * password (here, the placeholder); an unencoded `@` in the userinfo splits at
+ * the last `@` here, rendering the user and host node-postgres dials, where the
+ * Rust twin prints the placeholder; node-postgres decodes the database name
+ * with `decodeURI`, so a reserved-character escape such as `%2F` stays literal
+ * and prints as `%252F`; an IPv4-mapped IPv6 address serializes differently;
+ * and tokio-postgres refuses an unknown query parameter (`sslpassword=`) that
+ * node-postgres passes.
+ *
+ * @param url - the database URL
+ * @returns the URL without its password, query, or fragment, or the placeholder
+ */
+export const display_db_url = (url) => {
+    if (MALFORMED_ESCAPE.test(url))
+        return UNPARSEABLE_DB_URL;
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol === 'file:' || parsed.protocol === 'memory:') {
+            return `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
+        }
+        if (parsed.protocol !== 'postgres:' && parsed.protocol !== 'postgresql:') {
+            return UNPARSEABLE_DB_URL;
         }
+        const params = parsed.searchParams;
+        const user = params.get('user') || decodeURIComponent(parsed.username);
+        const param_host = params.get('host');
+        const host = display_host(param_host || decodeURIComponent(parsed.hostname.replace(/^\[(.*)\]$/, '$1')));
+        const port = params.get('port') || parsed.port || DEFAULT_PG_PORT;
+        // pg-connection-string moves an encoded socket host into the path when a
+        // query `host=` replaces it
+        const pathname = param_host && /^%2f/i.test(parsed.hostname)
+            ? parsed.hostname + parsed.pathname
+            : parsed.pathname;
+        const dbname = decodeURI(pathname.slice(1));
+        if (host === null || MISPARSED_USER.test(user) || !PORT.test(port) || Number(port) > 65535) {
+            return UNPARSEABLE_DB_URL;
+        }
+        let shown = 'postgres://';
+        if (user)
+            shown += `${encodeURIComponent(user)}@`;
+        shown += `${host}:${port}`;
+        if (dbname)
+            shown += `/${encodeURIComponent(dbname)}`;
+        return shown;
+    }
+    catch {
+        // `new URL`, a decode, or an encode of a lone surrogate threw
+        return UNPARSEABLE_DB_URL;
     }
-    return lines.join('\n');
 };

package/dist/http/CLAUDE.md

@@ -463,13 +463,17 @@ emit_after_commit(ctx, () => notification_sender.send_to_account(account_id, msg
 ```
 
 Used for WS sends (`NotificationSender.send_to_account` for
-role-grant-offer notifications — see `auth/CLAUDE.md` §WS notifications)
-and any side effect that must run only after the transaction commits.
+role-grant-offer notifications — see `auth/CLAUDE.md` §WS notifications),
+a revocation's connection closes (`queue_connection_close` — see
+`actions/CLAUDE.md` §Connection closer), the audit emitter's listener fan-out
+for a success row (`auth/CLAUDE.md` §Audit emitter), and any side effect that
+must run only after the transaction commits.
 
 ### Key properties
 
 - **The flush owns the safety net.** `flush_post_commit_effects` wraps every thunk in `try/catch` and routes errors through `ctx.log.error`, so one failing send cannot starve sibling effects in the same batch nor corrupt the already-committed response. Per-thunk `try/catch` inside `emit_after_commit` would skip directly-pushed thunks (e.g. tests); centralizing the wrap in the flush closes that gap.
 - **Test mode (`await_pending_effects: true`) flushes both queues.** Eager: `await flush_pending_effects(pending_effects, log)`. Deferred: `await flush_post_commit_effects(post_commit_effects, log)`. Both complete before the response returns. Production mode wraps the same helpers in `void ...` and threads `on_effect_error` into `flush_pending_effects`'s `on_rejection` callback for fan-out.
+- **The deferred thunks never wait on the eager writes.** Every flush site (both modes here, and the per-message WS flush) invokes the `post_commit_effects` thunks before it awaits `pending_effects`, so a revocation's connection close is not held behind a slow audit INSERT. A thunk that needs a write — the audit emitter's success-row fan-out — awaits that write itself.
 - **Drain at the outer flush; discard at the dispatch site.** The successful-path _drain_ of both queues stays at the outer flush middleware (`server/app_server.ts`) + the per-message WS flush — adjacent, one location, no per-wrapper drain timing. What the dispatch sites (route-spec wrapper / `perform_action`) own is the _rollback discard_, via the shared `dispatch_with_post_commit_rollback` helper: on a handler throw they truncate `post_commit_effects` before the outer flush ever sees it, so the flush only drains effects from a committed handler. The eager `pending_effects` queue is never truncated — it drains regardless (attempt audits survive rollback).
 - Structurally satisfied by both `RouteContext` (HTTP) and `ActionContext` (RPC + WS) — they share the `{log, post_commit_effects}` shape, which is why this helper lives in `http/` rather than `actions/` or `auth/`.
 
@@ -533,7 +537,7 @@ a request. Twin of the Rust spine's `fuz_db_admin` router.
 400 `ERROR_TABLE_NOT_DELETABLE` before the key-shape check, because a generic
 storage endpoint has no business deleting a row whose meaning lives in the
 domain layer. `audit_log` is the sharpest: it is both the trail and, since
-`realtime/sse_auth_guard.ts` and the WS auth guard close live streams by
+`realtime/sse_auth_guard.ts` and the WS auth guard close live connections by
 listening to audit events, part of how revocation propagates. The three
 singletons each fail differently on deletion — `bootstrap_lock` leaves
 `check_bootstrap_status` advertising a window `bootstrap_account.ts` then always

package/dist/http/db_routes.d.ts

@@ -75,8 +75,8 @@ export declare const NON_BROWSABLE_TABLES: ReadonlyArray<string>;
  * row whose meaning lives in the domain layer:
  *
  * - `audit_log` — the trail and the tamper path would otherwise be the same
- *   surface. It is also how revocation propagates: `realtime/sse_auth_guard.ts`
- *   and the WS auth guard close live streams by listening to audit events, so a
+ *   surface. It is also part of how revocation propagates: `realtime/sse_auth_guard.ts`
+ *   and the WS auth guard close live connections by listening to audit events, so a
  *   raw row delete here is invisible to them.
  *   `bootstrap_lock` — deleting the singleton leaves `check_bootstrap_status`
  *   advertising an open bootstrap window on the next boot that
@@ -103,10 +103,14 @@ export interface DbRouteDeps {
      * the call via `emit_after_commit`, so the success-only trail row can
      * never claim a delete whose transaction failed at COMMIT — the pool
      * routing means the write itself never rides the request transaction.
+     * The context carries both of the request's side-effect queues: the write
+     * goes on `pending_effects`, the row's listener fan-out on
+     * `post_commit_effects`.
      */
     audit: {
         emit: (ctx: {
             pending_effects: Array<Promise<void>>;
+            post_commit_effects: Array<() => void | Promise<void>>;
         }, input: {
             event_type: 'db_admin_row_delete';
             account_id: Uuid | null;

package/dist/http/db_routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/db_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAEnD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAqC,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAiBpF;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB,UAAU,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACpB;AAED,sDAAsD;AACtD,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAC/C,sDAAsD;AACtD,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAElD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAAa,CAAC,MAAM,CAKrD,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAAa,CAAC,MAAM,CAKrD,CAAC;AAEH;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B;;;;;OAKG;IACH,KAAK,EAAE;QACN,IAAI,EAAE,CACL,GAAG,EAAE;YAAE,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;SAAE,EAC9C,KAAK,EAAE;YACN,UAAU,EAAE,qBAAqB,CAAC;YAClC,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;YACxB,EAAE,EAAE,MAAM,CAAC;YACX,QAAQ,EAAE;gBAAE,KAAK,EAAE,MAAM,CAAC;gBAAC,SAAS,EAAE,MAAM,CAAC;gBAAC,EAAE,EAAE,MAAM,CAAA;aAAE,CAAC;SAC3D,KACG,IAAI,CAAC;KACV,CAAC;CACF;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,gBAAgB,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC,8EAA8E;IAC9E,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3D,+EAA+E;IAC/E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,oBAAoB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC7C;AA2CD;;GAEG;AACH,eAAO,MAAM,qBAAqB,GACjC,MAAM,WAAW,EACjB,SAAS,cAAc,KACrB,KAAK,CAAC,SAAS,CA4XjB,CAAC"}
+{"version":3,"file":"db_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/db_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAEnD,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAqC,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAiBpF;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB,UAAU,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACpB;AAED,sDAAsD;AACtD,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAC/C,sDAAsD;AACtD,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAElD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAAa,CAAC,MAAM,CAKrD,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAAa,CAAC,MAAM,CAKrD,CAAC;AAEH;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B;;;;;;;;OAQG;IACH,KAAK,EAAE;QACN,IAAI,EAAE,CACL,GAAG,EAAE;YACJ,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;YACtC,mBAAmB,EAAE,KAAK,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;SACvD,EACD,KAAK,EAAE;YACN,UAAU,EAAE,qBAAqB,CAAC;YAClC,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;YACxB,EAAE,EAAE,MAAM,CAAC;YACX,QAAQ,EAAE;gBAAE,KAAK,EAAE,MAAM,CAAC;gBAAC,SAAS,EAAE,MAAM,CAAC;gBAAC,EAAE,EAAE,MAAM,CAAA;aAAE,CAAC;SAC3D,KACG,IAAI,CAAC;KACV,CAAC;CACF;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,gBAAgB,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC,8EAA8E;IAC9E,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3D,+EAA+E;IAC/E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,oBAAoB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC7C;AA2CD;;GAEG;AACH,eAAO,MAAM,qBAAqB,GACjC,MAAM,WAAW,EACjB,SAAS,cAAc,KACrB,KAAK,CAAC,SAAS,CA4XjB,CAAC"}

package/dist/http/db_routes.js

@@ -57,8 +57,8 @@ export const NON_BROWSABLE_TABLES = Object.freeze([
  * row whose meaning lives in the domain layer:
  *
  * - `audit_log` — the trail and the tamper path would otherwise be the same
- *   surface. It is also how revocation propagates: `realtime/sse_auth_guard.ts`
- *   and the WS auth guard close live streams by listening to audit events, so a
+ *   surface. It is also part of how revocation propagates: `realtime/sse_auth_guard.ts`
+ *   and the WS auth guard close live connections by listening to audit events, so a
  *   raw row delete here is invisible to them.
  *   `bootstrap_lock` — deleting the singleton leaves `check_bootstrap_status`
  *   advertising an open bootstrap window on the next boot that

package/dist/periodic.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Periodic background task primitive.
+ *
+ * The loop every long-running process reaches for when it owns upkeep — an
+ * expiry sweep, a cleanup pass: one pass at startup, then one per interval,
+ * until stopped. `start_periodic` is that loop in one place, so a sweep is
+ * its pass plus one call, and every sweep keeps the same rules for a slow
+ * pass, a failed pass, and shutdown. `start_auth_cleanup` (`auth/cleanup.ts`)
+ * is built on it; a consumer's own sweeps use it the same way:
+ *
+ * ```ts
+ * const temp_sweep = start_periodic('temp sweep', 60 * 60 * 1000, () => sweep_temps(root), log);
+ * // … serve …
+ * // on shutdown, before what the pass uses is torn down
+ * await temp_sweep.stop();
+ * ```
+ *
+ * Twin of the Rust spine's `fuz_sys::periodic::spawn_periodic`. The schedule
+ * is the same; shutdown differs, because a promise cannot be dropped — see
+ * `start_periodic`.
+ *
+ * @module
+ */
+import type { Logger } from '@fuzdev/fuz_util/log.ts';
+/**
+ * The longest interval `start_periodic` accepts: the largest delay a timer
+ * honors (a signed 32-bit count of milliseconds, about 24.8 days). Past it
+ * `setTimeout` fires after one millisecond instead, which would turn a long
+ * interval into a pass loop.
+ */
+export declare const PERIODIC_INTERVAL_MS_MAX: number;
+/** A running periodic task — the result of `start_periodic`. */
+export interface PeriodicTask {
+    /**
+     * End the schedule. No pass starts once this is called, and the returned
+     * promise resolves when the pass in progress, if any, has finished — it
+     * never rejects. Await it before tearing down what the pass uses (the
+     * database, say). The wait has no bound of its own; a shutdown with a
+     * deadline races it. Safe to call more than once.
+     */
+    stop: () => Promise<void>;
+}
+/**
+ * Run `pass` now, then once per `interval_ms`, until `stop` is called.
+ *
+ * - **Startup pass.** The first pass starts before this returns; later passes
+ *   follow one `interval_ms` apart, start to start.
+ * - **A slow pass delays the schedule.** Passes never overlap, and a pass that
+ *   overruns its interval pushes the next one back: the next pass starts when
+ *   the slow one ends, the one after a full `interval_ms` later — no burst of
+ *   catch-up passes.
+ * - **A failed pass is logged, never fatal.** A pass that throws or rejects
+ *   is logged at `warn` with `name` and the error object itself — so the log
+ *   carries its stack and its `cause` — and the loop goes on to the next
+ *   interval, so an outage is retried rather than ending the upkeep for the
+ *   life of the process.
+ * - **`stop` finishes the pass in progress.** It ends the schedule at once and
+ *   resolves when a pass in progress has finished; nothing is dropped
+ *   mid-flight.
+ *
+ * The timer is unref'd where the runtime hands back a timer object (Node,
+ * Bun), so a task nobody stopped does not hold the process open.
+ *
+ * `pass` is called once per pass and returns that pass's promise. `name`
+ * labels the task in the failure log.
+ *
+ * Twin of the Rust `spawn_periodic`. The schedule is that loop's
+ * `MissedTickBehavior::Delay`. Shutdown differs: the Rust task drops a pass
+ * in progress when its token is cancelled, so joining it is prompt and a pass
+ * must be safe to drop; here the pass runs to its end and `stop` waits for it.
+ *
+ * @param name - labels the task in the failure log
+ * @param interval_ms - milliseconds between the start of one pass and the start of the next
+ * @param pass - one pass; called once per pass, its resolved value is ignored
+ * @param log - where a failed pass is logged
+ * @returns the task's `stop`
+ * @throws Error if `interval_ms` is not a positive finite number or exceeds `PERIODIC_INTERVAL_MS_MAX` — at the call site, before any pass starts
+ */
+export declare const start_periodic: (name: string, interval_ms: number, pass: () => Promise<unknown>, log: Logger) => PeriodicTask;
+//# sourceMappingURL=periodic.d.ts.map

package/dist/periodic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"periodic.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/periodic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,QAAc,CAAC;AAEpD,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC5B;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,cAAc,GAC1B,MAAM,MAAM,EACZ,aAAa,MAAM,EACnB,MAAM,MAAM,OAAO,CAAC,OAAO,CAAC,EAC5B,KAAK,MAAM,KACT,YA4DF,CAAC"}

package/dist/periodic.js

@@ -0,0 +1,122 @@
+/**
+ * Periodic background task primitive.
+ *
+ * The loop every long-running process reaches for when it owns upkeep — an
+ * expiry sweep, a cleanup pass: one pass at startup, then one per interval,
+ * until stopped. `start_periodic` is that loop in one place, so a sweep is
+ * its pass plus one call, and every sweep keeps the same rules for a slow
+ * pass, a failed pass, and shutdown. `start_auth_cleanup` (`auth/cleanup.ts`)
+ * is built on it; a consumer's own sweeps use it the same way:
+ *
+ * ```ts
+ * const temp_sweep = start_periodic('temp sweep', 60 * 60 * 1000, () => sweep_temps(root), log);
+ * // … serve …
+ * // on shutdown, before what the pass uses is torn down
+ * await temp_sweep.stop();
+ * ```
+ *
+ * Twin of the Rust spine's `fuz_sys::periodic::spawn_periodic`. The schedule
+ * is the same; shutdown differs, because a promise cannot be dropped — see
+ * `start_periodic`.
+ *
+ * @module
+ */
+/**
+ * The longest interval `start_periodic` accepts: the largest delay a timer
+ * honors (a signed 32-bit count of milliseconds, about 24.8 days). Past it
+ * `setTimeout` fires after one millisecond instead, which would turn a long
+ * interval into a pass loop.
+ */
+export const PERIODIC_INTERVAL_MS_MAX = 2 ** 31 - 1;
+/**
+ * Run `pass` now, then once per `interval_ms`, until `stop` is called.
+ *
+ * - **Startup pass.** The first pass starts before this returns; later passes
+ *   follow one `interval_ms` apart, start to start.
+ * - **A slow pass delays the schedule.** Passes never overlap, and a pass that
+ *   overruns its interval pushes the next one back: the next pass starts when
+ *   the slow one ends, the one after a full `interval_ms` later — no burst of
+ *   catch-up passes.
+ * - **A failed pass is logged, never fatal.** A pass that throws or rejects
+ *   is logged at `warn` with `name` and the error object itself — so the log
+ *   carries its stack and its `cause` — and the loop goes on to the next
+ *   interval, so an outage is retried rather than ending the upkeep for the
+ *   life of the process.
+ * - **`stop` finishes the pass in progress.** It ends the schedule at once and
+ *   resolves when a pass in progress has finished; nothing is dropped
+ *   mid-flight.
+ *
+ * The timer is unref'd where the runtime hands back a timer object (Node,
+ * Bun), so a task nobody stopped does not hold the process open.
+ *
+ * `pass` is called once per pass and returns that pass's promise. `name`
+ * labels the task in the failure log.
+ *
+ * Twin of the Rust `spawn_periodic`. The schedule is that loop's
+ * `MissedTickBehavior::Delay`. Shutdown differs: the Rust task drops a pass
+ * in progress when its token is cancelled, so joining it is prompt and a pass
+ * must be safe to drop; here the pass runs to its end and `stop` waits for it.
+ *
+ * @param name - labels the task in the failure log
+ * @param interval_ms - milliseconds between the start of one pass and the start of the next
+ * @param pass - one pass; called once per pass, its resolved value is ignored
+ * @param log - where a failed pass is logged
+ * @returns the task's `stop`
+ * @throws Error if `interval_ms` is not a positive finite number or exceeds `PERIODIC_INTERVAL_MS_MAX` — at the call site, before any pass starts
+ */
+export const start_periodic = (name, interval_ms, pass, log) => {
+    if (!Number.isFinite(interval_ms) || interval_ms <= 0 || interval_ms > PERIODIC_INTERVAL_MS_MAX) {
+        throw new Error(`start_periodic (${name}): interval_ms must be a positive number of milliseconds no greater than ${PERIODIC_INTERVAL_MS_MAX}, got ${interval_ms}`);
+    }
+    let stopped = false;
+    let timer = null;
+    let in_progress = null;
+    const run_pass = async () => {
+        try {
+            await pass();
+        }
+        catch (error) {
+            // the error object itself, so the log carries its stack and cause
+            log.warn(`${name} pass failed:`, error);
+        }
+    };
+    // One pass plus the timer for the next one's earliest start. The next pass
+    // starts when both have happened — the interval elapsed and this pass
+    // finished — whichever comes last, so passes never overlap and an overrun
+    // delays the schedule by exactly its length.
+    const start_pass = () => {
+        let due = false;
+        let finished = false;
+        timer = setTimeout(() => {
+            timer = null;
+            due = true;
+            if (finished)
+                start_pass();
+        }, interval_ms);
+        // allow the process to exit even if the timer is still pending
+        if (typeof timer === 'object' && 'unref' in timer) {
+            timer.unref();
+        }
+        in_progress = run_pass()
+            // `run_pass` rejects only if the logger itself throws; swallowed so
+            // `stop` never rejects and nothing surfaces as an unhandled rejection
+            .catch(() => { })
+            .finally(() => {
+            in_progress = null;
+            finished = true;
+            if (due && !stopped)
+                start_pass();
+        });
+    };
+    start_pass();
+    return {
+        stop: async () => {
+            stopped = true;
+            if (timer !== null) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            await in_progress;
+        }
+    };
+};