@astram/guard 0.18.0 → 0.20.0

package/dist/audit/audit-chain-sealer.d.ts

@@ -0,0 +1,90 @@
+import { type LoggerService } from '@nestjs/common';
+import type { Pool } from 'mariadb';
+import { type Clock, type FrameworkSchemas, type HashFunction } from '@astram/core';
+/** Lookback for the incremental scan (SPEC §10). */
+export declare const AUDIT_SEAL_LOOKBACK_MS: number;
+/** Full sweep and table re-probe period (SPEC §10). */
+export declare const AUDIT_SEAL_SWEEP_MS: number;
+/** Candidate rows per keyset page (SPEC §10). */
+export declare const AUDIT_SEAL_PAGE = 1000;
+/** Keyset pages per tick (SPEC §10). */
+export declare const AUDIT_SEAL_PAGES = 10;
+/** Tenants sealed per tick (SPEC §10). */
+export declare const AUDIT_SEAL_TENANTS = 200;
+/** Parked (stuck) tenants held at most (SPEC §10). */
+export declare const AUDIT_SEAL_STUCK = 200;
+/** The logger surface the sealer uses (Nest `Logger` shape). */
+export type AuditSealerLogger = Pick<LoggerService, 'log' | 'warn' | 'error'>;
+export interface AuditChainSealerOptions {
+    /** `SHIELD_DB_POOL`. Only `getConnection()` is used: every statement runs on the lock's session. */
+    readonly pool: Pool;
+    /** Resolved framework database names (`FRAMEWORK_SCHEMAS`). */
+    readonly schemas: FrameworkSchemas;
+    /** Chain hash (`NodeSha256Hash` in production). */
+    readonly hash: HashFunction;
+    /** Rows per tenant per tick (`AUDIT_SEAL_BATCH`). */
+    readonly batch: number;
+    /** Sealer clock: `ac_sealed_at_ms` and the sweep period. Default `Date.now`. */
+    readonly clock?: Clock;
+    /** Default `new Logger('Shield')`. */
+    readonly logger?: AuditSealerLogger;
+}
+/**
+ * A log-safe class for an error: a typed core reason, a driver error code / errno, or
+ * `unexpected`. Never the message (it can echo row content, e.g. a duplicate-key value).
+ */
+export declare function auditSealErrorClass(err: unknown): string;
+/** The leader lock name: `<ns>:audit_sealer` (single layout: `<db>:audit_sealer`), ≤ 64 chars. */
+export declare function auditSealerLockName(schemas: Pick<FrameworkSchemas, 'namespace'>): string;
+export declare class AuditChainSealer {
+    private readonly pool;
+    private readonly hash;
+    private readonly batch;
+    private readonly clock;
+    private readonly logger;
+    private readonly lockName;
+    private readonly logTable;
+    private readonly chainTable;
+    private readonly checkpointTable;
+    /** Sealer clock at the start of the last sweep; `undefined` ⇒ the next leader tick sweeps. */
+    private lastSweepAtMs;
+    /** Tenants parked until the next sweep (exact strings). */
+    private readonly stuck;
+    /** `(reason, tenant)` keys already logged this sweep. */
+    private readonly logged;
+    /** The stuck-set overflow was logged this sweep. */
+    private overflowLogged;
+    /**
+     * Backlog cursor (SPEC §5.G step 2): the oldest position the last tick left unsealed because
+     * of the batch / page / tenant caps (stuck tenants excluded). Leader memory only.
+     */
+    private cursor;
+    constructor(options: AuditChainSealerOptions);
+    /**
+     * One tick. Always releases the lock and returns (or destroys) the connection before it
+     * settles. A tenant batch error never rejects; an unexpected error (e.g. the candidate read
+     * failing) rejects after the cleanup.
+     */
+    tick(): Promise<void>;
+    private forgetLeadership;
+    private sealOnce;
+    /** The oldest position the caps left behind, skipping stuck tenants; `undefined` ⇒ none. */
+    private oldestLeftBehind;
+    /** `MIN(MAX(ac_occurred_at_ms), db now) − lookback`, or `undefined` for an empty chain. */
+    private readWindowStart;
+    /**
+     * Keyset-paged candidate read, grouped by exact tenant string, ≤ `batch` rows per tenant and
+     * ≤ 200 tenants (first appearance in keyset order; the rest wait for the next tick). The
+     * first page starts after `windowStart`, or at the backlog cursor `start` when given. Also
+     * returns what the caps left behind, for the backlog cursor.
+     */
+    private readCandidates;
+    /** Each tenant's head: the `MAX(ac_sequence)` chain row, else its latest checkpoint. */
+    private readHeads;
+    /** Link and insert one tenant's batch in one transaction; errors stay with this tenant. */
+    private sealTenant;
+    /** Log a failed batch (once per tenant and reason per sweep) and park it if it repeats. */
+    private recordFailure;
+    private logOnce;
+}
+//# sourceMappingURL=audit-chain-sealer.d.ts.map

package/dist/audit/audit-chain-sealer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-chain-sealer.d.ts","sourceRoot":"","sources":["../../src/audit/audit-chain-sealer.ts"],"names":[],"mappings":"AAmCA,OAAO,EAAU,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,KAAK,EAAE,IAAI,EAAkB,MAAM,SAAS,CAAC;AACpD,OAAO,EASL,KAAK,KAAK,EACV,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAEtB,oDAAoD;AACpD,eAAO,MAAM,sBAAsB,QAAc,CAAC;AAClD,uDAAuD;AACvD,eAAO,MAAM,mBAAmB,QAAc,CAAC;AAC/C,iDAAiD;AACjD,eAAO,MAAM,eAAe,OAAO,CAAC;AACpC,wCAAwC;AACxC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AACnC,0CAA0C;AAC1C,eAAO,MAAM,kBAAkB,MAAM,CAAC;AACtC,sDAAsD;AACtD,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAOpC,gEAAgE;AAChE,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,aAAa,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAE9E,MAAM,WAAW,uBAAuB;IACtC,oGAAoG;IACpG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,sCAAsC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;CACrC;AAyDD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CASxD;AAUD,kGAAkG;AAClG,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,WAAW,CAAC,GAAG,MAAM,CAOxF;AAOD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAO;IAC5B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IAEzC,8FAA8F;IAC9F,OAAO,CAAC,aAAa,CAAqB;IAC1C,2DAA2D;IAC3D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,yDAAyD;IACzD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,oDAAoD;IACpD,OAAO,CAAC,cAAc,CAAS;IAC/B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAA6B;gBAE/B,OAAO,EAAE,uBAAuB;IAa5C;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAgD3B,OAAO,CAAC,gBAAgB;YAQV,QAAQ;IAwCtB,4FAA4F;IAC5F,OAAO,CAAC,gBAAgB;IAWxB,2FAA2F;YAC7E,eAAe;IAa7B;;;;;OAKG;YACW,cAAc;IA0H5B,wFAAwF;YAC1E,SAAS;IAyDvB,2FAA2F;YAC7E,UAAU;IAmExB,2FAA2F;IAC3F,OAAO,CAAC,aAAa;IAuBrB,OAAO,CAAC,OAAO;CAMhB"}

package/dist/audit/audit-chain-sealer.js

@@ -0,0 +1,520 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuditChainSealer = exports.AUDIT_SEAL_STUCK = exports.AUDIT_SEAL_TENANTS = exports.AUDIT_SEAL_PAGES = exports.AUDIT_SEAL_PAGE = exports.AUDIT_SEAL_SWEEP_MS = exports.AUDIT_SEAL_LOOKBACK_MS = void 0;
+exports.auditSealErrorClass = auditSealErrorClass;
+exports.auditSealerLockName = auditSealerLockName;
+/**
+ * `AuditChainSealer` — one tick of the deferred audit sealer (audit-chain-store SPEC §5.G,
+ * §10, §11, §13).
+ *
+ * Writers keep appending plain rows to `<audit>.audit_log`; one leader per namespace (named
+ * lock) chains every committed row per tenant into the append-only `<audit>.audit_chain`.
+ * A tick:
+ *   1. checks out ONE pool connection and takes `GET_LOCK('<ns>:audit_sealer', 0)`; not
+ *      acquired ⇒ return the connection, no work;
+ *   2. window start `W = MIN(MAX(ac_occurred_at_ms), db now) − 15 min` from the chain alone
+ *      (`idx_ac_occurred`); empty chain ⇒ no bound. The first tick of a leader and then one
+ *      tick per hour is a sweep: no bound, the stuck set and the logged-once memory clear.
+ *      Backlog cursor: when the batch / page / tenant caps leave rows behind, the oldest such
+ *      `(al_occurred_at_ms, al_uuid)` (stuck tenants excluded) is kept in memory and the next
+ *      tick starts its keyset there instead of at `W` when it is older; cleared when a tick
+ *      leaves nothing behind, on lock loss and at each sweep (which may set it again);
+ *   3./4. reads candidates in keyset pages on `idx_audit_time` (1000 rows, ≤ 10 pages, stops at
+ *      200 tenants), anti-joined into `uq_ac_al_uuid`, excluding parked tenants and tenants
+ *      that already hold `batch` rows this tick; groups them by exact tenant string in Node;
+ *      reads each tenant's head (chain PK, else latest checkpoint, else genesis);
+ *   5. links each tenant's rows with core `auditEventFromRow` + `linkEntry` and inserts them
+ *      in ONE transaction per tenant on the same connection. A failed batch rolls back alone;
+ *      a repeating error (duplicate key 1062, `AuditRowError`, `AuditValidationError`) parks
+ *      the tenant until the next sweep (≤ 200 parked), anything else retries next tick;
+ *   6. `finally`: `RELEASE_LOCK`, then return the connection; if the release fails (or the
+ *      lock state is unknown) destroy the connection instead, so a pooled connection never
+ *      carries the lock.
+ *
+ * Every `audit_log` ⇄ chain comparison and every tenant filter on `audit_log` carries
+ * `COLLATE utf8mb4_nopad_bin` on the `audit_log` side (exact bytes, NO PAD; `audit_log` is
+ * `utf8mb4_unicode_ci`, a bare comparison raises error 1267). Database names come from
+ * `FrameworkSchemas`, never a literal. Logs carry fixed text, tenant and sequence only:
+ * never `err.message` and never row content (SPEC §11).
+ */
+const node_crypto_1 = require("node:crypto");
+const common_1 = require("@nestjs/common");
+const core_1 = require("@astram/core");
+/** Lookback for the incremental scan (SPEC §10). */
+exports.AUDIT_SEAL_LOOKBACK_MS = 15 * 60_000;
+/** Full sweep and table re-probe period (SPEC §10). */
+exports.AUDIT_SEAL_SWEEP_MS = 60 * 60_000;
+/** Candidate rows per keyset page (SPEC §10). */
+exports.AUDIT_SEAL_PAGE = 1000;
+/** Keyset pages per tick (SPEC §10). */
+exports.AUDIT_SEAL_PAGES = 10;
+/** Tenants sealed per tick (SPEC §10). */
+exports.AUDIT_SEAL_TENANTS = 200;
+/** Parked (stuck) tenants held at most (SPEC §10). */
+exports.AUDIT_SEAL_STUCK = 200;
+/** MariaDB's limit on a `GET_LOCK` name. */
+const MAX_LOCK_NAME = 64;
+/** MariaDB duplicate-key error number. */
+const ER_DUP_ENTRY = 1062;
+/** A BIGINT column value as a `bigint` for ordering; `undefined` when it is not an integer. */
+function ordinalOf(value) {
+    try {
+        if (typeof value === 'bigint')
+            return value;
+        if (typeof value === 'number' && Number.isInteger(value))
+            return BigInt(value);
+        if (typeof value === 'string' && /^-?\d+$/.test(value.trim()))
+            return BigInt(value.trim());
+    }
+    catch {
+        // fall through
+    }
+    return undefined;
+}
+/** Thrown inside a tick when the connection can no longer be trusted (rollback failed). */
+class ConnectionUnusable extends Error {
+    constructor() {
+        super('audit_sealer_connection_unusable');
+        this.name = 'ConnectionUnusable';
+    }
+}
+const DRIVER_CODE = /^[A-Z][A-Z0-9_]{0,63}$/;
+/**
+ * A log-safe class for an error: a typed core reason, a driver error code / errno, or
+ * `unexpected`. Never the message (it can echo row content, e.g. a duplicate-key value).
+ */
+function auditSealErrorClass(err) {
+    if (err instanceof core_1.AuditRowError)
+        return `row_rejected:${err.reason}`;
+    if (err instanceof core_1.AuditValidationError)
+        return `event_rejected:${err.reason}`;
+    if (typeof err === 'object' && err !== null) {
+        const { code, errno } = err;
+        if (typeof code === 'string' && DRIVER_CODE.test(code))
+            return `db_error:${code}`;
+        if (typeof errno === 'number' && Number.isSafeInteger(errno))
+            return `db_error:${errno}`;
+    }
+    return 'unexpected';
+}
+/** Errors that repeat on every retry of the same rows, so the tenant is parked (SPEC §5.G.3). */
+function isRepeating(err) {
+    if (err instanceof core_1.AuditRowError || err instanceof core_1.AuditValidationError)
+        return true;
+    return (typeof err === 'object' && err !== null && err.errno === ER_DUP_ENTRY);
+}
+/** The leader lock name: `<ns>:audit_sealer` (single layout: `<db>:audit_sealer`), ≤ 64 chars. */
+function auditSealerLockName(schemas) {
+    const name = `${schemas.namespace}:audit_sealer`;
+    if (name.length <= MAX_LOCK_NAME)
+        return name;
+    // A 55-char namespace or 64-char single-layout database exceeds MariaDB's limit: keep the
+    // name unique per namespace with a digest (same approach as the migrate ledger lock).
+    const digest = (0, node_crypto_1.createHash)('sha256').update(schemas.namespace, 'utf8').digest('hex');
+    return `audit_sealer:${digest.slice(0, MAX_LOCK_NAME - 'audit_sealer:'.length)}`;
+}
+const quoteId = (name) => `\`${name.replace(/`/g, '``')}\``;
+/** `?, ?, …` for `n` parameters. */
+const placeholders = (n) => Array.from({ length: n }, () => '?').join(', ');
+class AuditChainSealer {
+    pool;
+    hash;
+    batch;
+    clock;
+    logger;
+    lockName;
+    logTable;
+    chainTable;
+    checkpointTable;
+    /** Sealer clock at the start of the last sweep; `undefined` ⇒ the next leader tick sweeps. */
+    lastSweepAtMs;
+    /** Tenants parked until the next sweep (exact strings). */
+    stuck = new Set();
+    /** `(reason, tenant)` keys already logged this sweep. */
+    logged = new Set();
+    /** The stuck-set overflow was logged this sweep. */
+    overflowLogged = false;
+    /**
+     * Backlog cursor (SPEC §5.G step 2): the oldest position the last tick left unsealed because
+     * of the batch / page / tenant caps (stuck tenants excluded). Leader memory only.
+     */
+    cursor;
+    constructor(options) {
+        this.pool = options.pool;
+        this.hash = options.hash;
+        this.batch = options.batch;
+        this.clock = options.clock ?? { nowMs: () => Date.now() };
+        this.logger = options.logger ?? new common_1.Logger('Shield');
+        this.lockName = auditSealerLockName(options.schemas);
+        const db = quoteId(options.schemas.audit);
+        this.logTable = `${db}.${quoteId('audit_log')}`;
+        this.chainTable = `${db}.${quoteId('audit_chain')}`;
+        this.checkpointTable = `${db}.${quoteId('audit_chain_checkpoint')}`;
+    }
+    /**
+     * One tick. Always releases the lock and returns (or destroys) the connection before it
+     * settles. A tenant batch error never rejects; an unexpected error (e.g. the candidate read
+     * failing) rejects after the cleanup.
+     */
+    async tick() {
+        const conn = await this.pool.getConnection();
+        /** GET_LOCK's answer; stays `undefined` (outcome unknown) when the statement fails. */
+        let locked;
+        let destroy = false;
+        try {
+            const rows = (await conn.query('SELECT GET_LOCK(?, 0) AS acquired', [
+                this.lockName,
+            ]));
+            const acquired = rows[0]?.acquired;
+            locked = acquired !== null && acquired !== undefined && Number(acquired) === 1;
+            if (!locked) {
+                // Another instance leads. If this one leads again later it is a new leader: it sweeps
+                // first and starts with an empty stuck set.
+                this.forgetLeadership();
+                return;
+            }
+            await this.sealOnce(conn);
+        }
+        catch (err) {
+            if (!(err instanceof ConnectionUnusable))
+                throw err;
+            destroy = true;
+        }
+        finally {
+            if (locked === undefined) {
+                // GET_LOCK failed: whether the session holds the lock is unknown, so never pool it.
+                destroy = true;
+            }
+            else if (locked) {
+                try {
+                    await conn.query('SELECT RELEASE_LOCK(?) AS released', [this.lockName]);
+                }
+                catch {
+                    destroy = true;
+                }
+            }
+            if (destroy) {
+                try {
+                    conn.destroy();
+                }
+                catch {
+                    // The socket is closed either way; the server drops the session's lock with it.
+                }
+            }
+            else {
+                try {
+                    await conn.release();
+                }
+                catch {
+                    // Returning a connection to a closing pool is non-fatal.
+                }
+            }
+        }
+    }
+    forgetLeadership() {
+        this.lastSweepAtMs = undefined;
+        this.stuck.clear();
+        this.logged.clear();
+        this.overflowLogged = false;
+        this.cursor = undefined;
+    }
+    async sealOnce(conn) {
+        const now = this.clock.nowMs();
+        const sweep = this.lastSweepAtMs === undefined || now - this.lastSweepAtMs >= exports.AUDIT_SEAL_SWEEP_MS;
+        if (sweep) {
+            this.lastSweepAtMs = now;
+            this.stuck.clear();
+            this.logged.clear();
+            this.overflowLogged = false;
+            // The sweep scans from the start; it sets the cursor again if it leaves rows behind.
+            this.cursor = undefined;
+        }
+        const windowStart = sweep ? undefined : await this.readWindowStart(conn);
+        // Start from the backlog cursor instead of W when it is older (SPEC §5.G step 2).
+        const start = windowStart !== undefined &&
+            this.cursor !== undefined &&
+            this.cursor.ordinal <= BigInt(windowStart)
+            ? this.cursor
+            : undefined;
+        const read = await this.readCandidates(conn, start === undefined ? windowStart : undefined, start);
+        // Rows left behind by the caps, before sealing: if the connection dies mid-tick, the next
+        // tick still resumes from here.
+        this.cursor = this.oldestLeftBehind(read);
+        const { groups } = read;
+        if (groups.size === 0)
+            return;
+        const heads = await this.readHeads(conn, [...groups.keys()]);
+        for (const [tenant, rows] of groups) {
+            await this.sealTenant(conn, tenant, rows, heads.get(tenant));
+        }
+        // Tenants parked during this tick wait for the sweep: their rows do not hold the cursor.
+        this.cursor = this.oldestLeftBehind(read);
+    }
+    /** The oldest position the caps left behind, skipping stuck tenants; `undefined` ⇒ none. */
+    oldestLeftBehind(read) {
+        let oldest = read.tail;
+        for (const [tenant, position] of read.leftBehind) {
+            if (this.stuck.has(tenant))
+                continue;
+            if (oldest === undefined || read.order.get(position) < read.order.get(oldest)) {
+                oldest = position;
+            }
+        }
+        return oldest;
+    }
+    /** `MIN(MAX(ac_occurred_at_ms), db now) − lookback`, or `undefined` for an empty chain. */
+    async readWindowStart(conn) {
+        const rows = (await conn.query(`SELECT MAX(ac_occurred_at_ms) AS max_ms,
+              CAST(UNIX_TIMESTAMP(NOW(3)) * 1000 AS SIGNED) AS now_ms
+         FROM ${this.chainTable}`));
+        const row = rows[0];
+        if (row?.max_ms === null || row?.max_ms === undefined)
+            return undefined;
+        const max = (0, core_1.toSafeInteger)(row.max_ms);
+        const dbNow = row.now_ms === null || row.now_ms === undefined ? max : (0, core_1.toSafeInteger)(row.now_ms);
+        return Math.min(max, dbNow) - exports.AUDIT_SEAL_LOOKBACK_MS;
+    }
+    /**
+     * Keyset-paged candidate read, grouped by exact tenant string, ≤ `batch` rows per tenant and
+     * ≤ 200 tenants (first appearance in keyset order; the rest wait for the next tick). The
+     * first page starts after `windowStart`, or at the backlog cursor `start` when given. Also
+     * returns what the caps left behind, for the backlog cursor.
+     */
+    async readCandidates(conn, windowStart, start) {
+        const groups = new Map();
+        const full = new Set();
+        const leftBehind = new Map();
+        const order = new Map();
+        /** Per full tenant, the read-order index of its last taken row. */
+        const lastTaken = new Map();
+        let after = start;
+        let index = 0;
+        let lastRow;
+        let exhausted = false;
+        const positionOf = (row, inclusive) => {
+            const ordinal = ordinalOf(row.al_occurred_at_ms);
+            if (ordinal === undefined)
+                return undefined;
+            return { occurred: row.al_occurred_at_ms, ordinal, uuid: row.al_uuid, inclusive };
+        };
+        for (let page = 0; page < exports.AUDIT_SEAL_PAGES; page++) {
+            const where = [];
+            const params = [];
+            if (windowStart !== undefined) {
+                where.push('al_occurred_at_ms > ?');
+                params.push(windowStart);
+            }
+            if (after !== undefined) {
+                // The cursor row itself is still unsealed: an inclusive start keeps it (`>=`).
+                where.push(`(al_occurred_at_ms > ? OR (al_occurred_at_ms = ? AND al_uuid ${after.inclusive ? '>=' : '>'} ?))`);
+                params.push(after.occurred, after.occurred, after.uuid);
+            }
+            const excluded = [...this.stuck, ...full];
+            if (excluded.length > 0) {
+                where.push(`al_tenant_id COLLATE utf8mb4_nopad_bin NOT IN (${placeholders(excluded.length)})`);
+                params.push(...excluded);
+            }
+            where.push(`NOT EXISTS (SELECT 1 FROM ${this.chainTable}
+                      WHERE ac_al_uuid = al_uuid COLLATE utf8mb4_nopad_bin)`);
+            params.push(exports.AUDIT_SEAL_PAGE);
+            const rows = (await conn.query(`SELECT al_uuid, al_type, al_occurred_at_ms, al_actor_id, al_tenant_id, al_action_key,
+                al_resource_json, al_decision_json, al_attributes_json
+           FROM ${this.logTable}
+          WHERE ${where.join('\n            AND ')}
+          ORDER BY al_occurred_at_ms, al_uuid
+          LIMIT ?`, params));
+            for (const row of rows) {
+                const i = index++;
+                const tenant = row.al_tenant_id;
+                if (this.stuck.has(tenant))
+                    continue;
+                let group = groups.get(tenant);
+                let skip = false;
+                if (group === undefined) {
+                    if (groups.size >= exports.AUDIT_SEAL_TENANTS) {
+                        skip = true; // tenant cap
+                    }
+                    else {
+                        group = [];
+                        groups.set(tenant, group);
+                    }
+                }
+                else if (group.length >= this.batch) {
+                    skip = true; // batch cap
+                }
+                if (skip || group === undefined) {
+                    if (!leftBehind.has(tenant)) {
+                        const position = positionOf(row, true);
+                        if (position !== undefined) {
+                            leftBehind.set(tenant, position);
+                            order.set(position, i);
+                        }
+                    }
+                    continue;
+                }
+                group.push(row);
+                if (group.length >= this.batch) {
+                    full.add(tenant);
+                    lastTaken.set(tenant, { index: i, row });
+                }
+            }
+            lastRow = rows[rows.length - 1] ?? lastRow;
+            if (rows.length < exports.AUDIT_SEAL_PAGE) {
+                exhausted = true;
+                break;
+            }
+            if (groups.size >= exports.AUDIT_SEAL_TENANTS)
+                break;
+            const last = rows[rows.length - 1];
+            after = { occurred: last.al_occurred_at_ms, uuid: last.al_uuid, inclusive: false };
+        }
+        // A full tenant's later rows were excluded from the following pages (NOT IN), so it may
+        // have rows left even when none was seen: resume strictly after its last taken row.
+        for (const [tenant, taken] of lastTaken) {
+            if (leftBehind.has(tenant))
+                continue;
+            const position = positionOf(taken.row, false);
+            if (position === undefined)
+                continue;
+            leftBehind.set(tenant, position);
+            // Strictly after row `index`: before any row read later, after the row itself.
+            order.set(position, taken.index + 0.5);
+        }
+        // Paging stopped on `pages` or `tenants` with a full last page: the rest was never read.
+        let tail;
+        if (!exhausted && lastRow !== undefined) {
+            tail = positionOf(lastRow, false);
+            if (tail !== undefined)
+                order.set(tail, index - 1 + 0.5);
+        }
+        return { groups, leftBehind, tail, order };
+    }
+    /** Each tenant's head: the `MAX(ac_sequence)` chain row, else its latest checkpoint. */
+    async readHeads(conn, tenants) {
+        const heads = new Map();
+        const chainRows = (await conn.query(`SELECT ac.ac_tenant_id, ac.ac_sequence, ac.ac_entry_hash,
+              CASE WHEN al.al_uuid IS NULL THEN 1 ELSE 0 END AS al_missing
+         FROM (SELECT ac_tenant_id AS head_tenant, MAX(ac_sequence) AS head_sequence
+                 FROM ${this.chainTable}
+                WHERE ac_tenant_id IN (${placeholders(tenants.length)})
+                GROUP BY ac_tenant_id) h
+         JOIN ${this.chainTable} ac
+           ON ac.ac_tenant_id = h.head_tenant AND ac.ac_sequence = h.head_sequence
+         LEFT JOIN ${this.logTable} al
+           ON al.al_uuid = ac.ac_al_uuid COLLATE utf8mb4_unicode_ci
+          AND al.al_uuid COLLATE utf8mb4_nopad_bin = ac.ac_al_uuid`, tenants));
+        for (const r of chainRows) {
+            heads.set(r.ac_tenant_id, {
+                anchor: {
+                    tenantId: r.ac_tenant_id,
+                    sequenceNumber: (0, core_1.toSafeInteger)(r.ac_sequence),
+                    entryHash: r.ac_entry_hash,
+                },
+                missingRow: Number(r.al_missing) === 1,
+            });
+        }
+        const rest = tenants.filter((t) => !heads.has(t));
+        if (rest.length === 0)
+            return heads;
+        const checkpoints = (await conn.query(`SELECT c.acc_tenant_id, c.acc_sequence, c.acc_entry_hash
+         FROM (SELECT acc_tenant_id AS cp_tenant, MAX(acc_sequence) AS cp_sequence
+                 FROM ${this.checkpointTable}
+                WHERE acc_tenant_id IN (${placeholders(rest.length)})
+                GROUP BY acc_tenant_id) m
+         JOIN ${this.checkpointTable} c
+           ON c.acc_tenant_id = m.cp_tenant AND c.acc_sequence = m.cp_sequence`, rest));
+        for (const r of checkpoints) {
+            heads.set(r.acc_tenant_id, {
+                anchor: {
+                    tenantId: r.acc_tenant_id,
+                    sequenceNumber: (0, core_1.toSafeInteger)(r.acc_sequence),
+                    entryHash: r.acc_entry_hash,
+                },
+                missingRow: false,
+            });
+        }
+        return heads;
+    }
+    /** Link and insert one tenant's batch in one transaction; errors stay with this tenant. */
+    async sealTenant(conn, tenant, rows, head) {
+        if (head?.missingRow) {
+            // Keep sealing from the head's hash; audit:verify keeps reporting missing_row there.
+            this.logOnce('head_missing_row', tenant, `audit sealer: tenant ${JSON.stringify(tenant)} head at sequence ` +
+                `${head.anchor.sequenceNumber} has no audit_log row; sealing continues from its hash`);
+        }
+        let prev = head?.anchor;
+        /** The sequence being linked or inserted; a failure is reported at it. */
+        let sequence = prev !== undefined ? prev.sequenceNumber + 1 : 0;
+        let inTransaction = false;
+        try {
+            const links = rows.map((row) => {
+                sequence = prev !== undefined ? prev.sequenceNumber + 1 : 0;
+                const event = (0, core_1.auditEventFromRow)(row);
+                const link = (0, core_1.linkEntry)(event, prev, this.hash);
+                prev = { tenantId: tenant, sequenceNumber: link.sequenceNumber, entryHash: link.entryHash };
+                return { row, link, occurredAtMs: event.occurredAtMs };
+            });
+            const sealedAtMs = this.clock.nowMs();
+            await conn.beginTransaction();
+            inTransaction = true;
+            for (const { row, link, occurredAtMs } of links) {
+                sequence = link.sequenceNumber;
+                await conn.query(`INSERT INTO ${this.chainTable}
+             (ac_tenant_id, ac_sequence, ac_al_uuid, ac_content_hash, ac_prev_hash,
+              ac_entry_hash, ac_occurred_at_ms, ac_sealed_at_ms)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [
+                    tenant,
+                    link.sequenceNumber,
+                    row.al_uuid,
+                    link.contentHash,
+                    link.prevHash,
+                    link.entryHash,
+                    occurredAtMs,
+                    sealedAtMs,
+                ]);
+            }
+            await conn.commit();
+            inTransaction = false;
+        }
+        catch (err) {
+            let rollbackFailed = false;
+            if (inTransaction) {
+                try {
+                    await conn.rollback();
+                }
+                catch {
+                    rollbackFailed = true;
+                }
+            }
+            this.recordFailure(tenant, sequence, err);
+            if (rollbackFailed)
+                throw new ConnectionUnusable();
+        }
+    }
+    /** Log a failed batch (once per tenant and reason per sweep) and park it if it repeats. */
+    recordFailure(tenant, sequence, err) {
+        const reason = auditSealErrorClass(err);
+        const repeating = isRepeating(err);
+        if (repeating && this.stuck.size >= exports.AUDIT_SEAL_STUCK && !this.stuck.has(tenant)) {
+            // Systemic failure: one count-only line per sweep, no per-tenant log, retried each tick.
+            if (!this.overflowLogged) {
+                this.overflowLogged = true;
+                this.logger.error(`audit sealer: ${exports.AUDIT_SEAL_STUCK} tenants are parked (the maximum); further ` +
+                    'tenants failing with a repeating error are retried every tick until the next sweep');
+            }
+            return;
+        }
+        if (repeating)
+            this.stuck.add(tenant);
+        this.logOnce(reason, tenant, `audit sealer: tenant ${JSON.stringify(tenant)} batch rolled back at sequence ${sequence} ` +
+            `(${reason}); ${repeating ? 'parked until the next sweep' : 'retried next tick'}`);
+    }
+    logOnce(reason, tenant, message) {
+        const key = `${reason}\u0000${tenant}`;
+        if (this.logged.has(key))
+            return;
+        this.logged.add(key);
+        this.logger.error(message);
+    }
+}
+exports.AuditChainSealer = AuditChainSealer;

package/dist/audit/audit-seal-config.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `AUDIT_SEAL_*` env loader for the deferred audit sealer (audit-chain-store SPEC §5.I, §10,
+ * §13). Read once at boot by the persistence wiring; an invalid value fails the boot with the
+ * variable name and its bounds, never the value (it might be a misplaced secret). Unset, empty
+ * or whitespace-only ⇒ the default (as `loadMessageConfig`).
+ */
+/** The two tunables of the sealer (the sealer itself cannot be switched off, SPEC §11). */
+export interface AuditSealConfig {
+    /** Milliseconds between the end of one tick and the start of the next. */
+    readonly intervalMs: number;
+    /** Rows sealed per tenant per tick. */
+    readonly batch: number;
+}
+export declare const DEFAULT_AUDIT_SEAL_INTERVAL_MS = 2000;
+export declare const MIN_AUDIT_SEAL_INTERVAL_MS = 500;
+export declare const MAX_AUDIT_SEAL_INTERVAL_MS = 60000;
+export declare const DEFAULT_AUDIT_SEAL_BATCH = 500;
+export declare const MIN_AUDIT_SEAL_BATCH = 1;
+export declare const MAX_AUDIT_SEAL_BATCH = 5000;
+/** Load and validate `AUDIT_SEAL_INTERVAL_MS` and `AUDIT_SEAL_BATCH`. Throws on an invalid value. */
+export declare function loadAuditSealConfig(env: NodeJS.ProcessEnv): AuditSealConfig;
+//# sourceMappingURL=audit-seal-config.d.ts.map

package/dist/audit/audit-seal-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-seal-config.d.ts","sourceRoot":"","sources":["../../src/audit/audit-seal-config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,2FAA2F;AAC3F,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,eAAO,MAAM,8BAA8B,OAAO,CAAC;AACnD,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAC9C,eAAO,MAAM,0BAA0B,QAAS,CAAC;AACjD,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAC5C,eAAO,MAAM,oBAAoB,IAAI,CAAC;AACtC,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAqBzC,qGAAqG;AACrG,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,eAAe,CAiB3E"}

package/dist/audit/audit-seal-config.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * `AUDIT_SEAL_*` env loader for the deferred audit sealer (audit-chain-store SPEC §5.I, §10,
+ * §13). Read once at boot by the persistence wiring; an invalid value fails the boot with the
+ * variable name and its bounds, never the value (it might be a misplaced secret). Unset, empty
+ * or whitespace-only ⇒ the default (as `loadMessageConfig`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_AUDIT_SEAL_BATCH = exports.MIN_AUDIT_SEAL_BATCH = exports.DEFAULT_AUDIT_SEAL_BATCH = exports.MAX_AUDIT_SEAL_INTERVAL_MS = exports.MIN_AUDIT_SEAL_INTERVAL_MS = exports.DEFAULT_AUDIT_SEAL_INTERVAL_MS = void 0;
+exports.loadAuditSealConfig = loadAuditSealConfig;
+exports.DEFAULT_AUDIT_SEAL_INTERVAL_MS = 2000;
+exports.MIN_AUDIT_SEAL_INTERVAL_MS = 500;
+exports.MAX_AUDIT_SEAL_INTERVAL_MS = 60_000;
+exports.DEFAULT_AUDIT_SEAL_BATCH = 500;
+exports.MIN_AUDIT_SEAL_BATCH = 1;
+exports.MAX_AUDIT_SEAL_BATCH = 5000;
+/** Plain decimal digits only (no sign, exponent, radix prefix or fraction). */
+const PLAIN_DIGITS = /^[0-9]{1,10}$/;
+function boundedInteger(env, name, fallback, min, max) {
+    const value = env[name]?.trim();
+    if (!value)
+        return fallback;
+    const n = PLAIN_DIGITS.test(value) ? Number(value) : NaN;
+    if (!Number.isSafeInteger(n) || n < min || n > max) {
+        throw new Error(`${name} must be a whole number between ${min} and ${max}`);
+    }
+    return n;
+}
+/** Load and validate `AUDIT_SEAL_INTERVAL_MS` and `AUDIT_SEAL_BATCH`. Throws on an invalid value. */
+function loadAuditSealConfig(env) {
+    return {
+        intervalMs: boundedInteger(env, 'AUDIT_SEAL_INTERVAL_MS', exports.DEFAULT_AUDIT_SEAL_INTERVAL_MS, exports.MIN_AUDIT_SEAL_INTERVAL_MS, exports.MAX_AUDIT_SEAL_INTERVAL_MS),
+        batch: boundedInteger(env, 'AUDIT_SEAL_BATCH', exports.DEFAULT_AUDIT_SEAL_BATCH, exports.MIN_AUDIT_SEAL_BATCH, exports.MAX_AUDIT_SEAL_BATCH),
+    };
+}