@schema-weaver/pg-connector 0.0.0-stage → 2.0.0

package/dist/cjs/cli/daemon/error-tracker.js

@@ -0,0 +1,500 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_ERROR_ARCHIVES = exports.MAX_ERROR_LOG_BYTES = void 0;
+exports.redactErrorText = redactErrorText;
+exports.rotateErrorLog = rotateErrorLog;
+exports.trackError = trackError;
+exports.getErrorsPath = getErrorsPath;
+exports.getErrorLogFiles = getErrorLogFiles;
+exports.getErrorLogStats = getErrorLogStats;
+exports.fsyncErrorLog = fsyncErrorLog;
+exports.getFaultShutdownController = getFaultShutdownController;
+exports.registerFaultShutdownHooks = registerFaultShutdownHooks;
+exports.installGlobalHandlers = installGlobalHandlers;
+exports.resetGlobalHandlersForTests = resetGlobalHandlersForTests;
+exports.readRecentErrors = readRecentErrors;
+exports.resetErrorLogCache = resetErrorLogCache;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const paths_1 = require("../../config/paths");
+const fault_shutdown_1 = require("./fault-shutdown");
+const state_1 = require("./state");
+/** Rotate at 2 MiB. A daemon that logs an error per query must not fill a disk. */
+exports.MAX_ERROR_LOG_BYTES = 2 * 1024 * 1024;
+/** Keep the active file plus this many rotated archives. */
+exports.MAX_ERROR_ARCHIVES = 3;
+/** Longest persisted `message`, in characters. */
+const MAX_MESSAGE_CHARS = 500;
+/** Longest persisted `stack`, in characters. */
+const MAX_STACK_CHARS = 2_000;
+let initialized = false;
+let agentId;
+/* ------------------------------------------------------------------ */
+/* Redaction                                                           */
+/* ------------------------------------------------------------------ */
+/**
+ * `pg` quotes the offending token with double quotes (`syntax error at or near
+ * "DROP TABLE users"`) and embeds single-quoted literals
+ * (`duplicate key value violates unique constraint "u_email": Key (email)=(a@b.c)`
+ * / `unterminated quoted string at or near "'alice@corp.com'"`). Both forms
+ * carry user data out of the database and into a file that nobody thinks of as
+ * sensitive, so they are replaced with a placeholder before persistence.
+ */
+const SQL_DOUBLE_QUOTED = /"(?:[^"\\\n]|\\.)*"/g;
+const SQL_SINGLE_QUOTED = /'(?:[^']|'')*'/g;
+/** `Key (col)=(value)` detail emitted by a unique/pk violation. */
+const PG_KEY_VALUE_DETAIL = /=\(([^)]*)\)/g;
+/** Two or more `/`-separated segments: an absolute POSIX path. */
+const POSIX_ABSOLUTE_PATH = /\/(?:[A-Za-z0-9_.~+@-]+)(?:\/[A-Za-z0-9_.~+@-]+){1,}\/?/g;
+/** `C:\Users\...` — matched before the POSIX rule so the drive is not split. */
+const WINDOWS_ABSOLUTE_PATH = /[A-Za-z]:\\(?:[^\\\s"'|,;]+\\)*[^\\\s"'|,;]*/g;
+function shortenPosixPath(p) {
+    for (const home of homeDirPrefixes()) {
+        if (p === home)
+            return '~';
+        if (p.startsWith(home + '/'))
+            return '~/' + p.slice(home.length + 1);
+    }
+    const marker = '/node_modules/';
+    const nm = p.lastIndexOf(marker);
+    if (nm >= 0)
+        return 'node_modules/' + p.slice(nm + marker.length);
+    const segments = p.replace(/\/+$/, '').split('/').filter(Boolean);
+    if (segments.length <= 1)
+        return p;
+    return '<path>/' + segments.slice(-2).join('/');
+}
+function shortenWindowsPath(p) {
+    const segments = p.replace(/\\+$/, '').split('\\').filter(Boolean);
+    if (segments.length <= 2)
+        return '<path>/' + (segments[segments.length - 1] ?? '');
+    return '<path>/' + segments.slice(-2).join('/');
+}
+function homeDirPrefixes() {
+    const prefixes = [];
+    try {
+        const agentHome = (0, paths_1.getSwAgentDir)();
+        if (agentHome)
+            prefixes.push(agentHome.replace(/\/+$/, ''));
+    }
+    catch {
+        // The home directory may not exist yet; os.homedir() is still useful.
+    }
+    try {
+        const home = os.homedir();
+        if (home)
+            prefixes.push(home.replace(/\/+$/, ''));
+    }
+    catch {
+        // ignore
+    }
+    return prefixes.filter(Boolean);
+}
+/**
+ * Strip SQL text and absolute filesystem paths out of free-form text.
+ *
+ * `pg` error messages embed the offending statement and stack frames embed the
+ * absolute path of the agent home directory and of `node_modules`. Neither
+ * belongs in an error log that no operator is looking at.
+ */
+function redactErrorText(input) {
+    return input
+        .replace(PG_KEY_VALUE_DETAIL, '=(?)')
+        .replace(SQL_DOUBLE_QUOTED, '"?"')
+        .replace(SQL_SINGLE_QUOTED, "'?'")
+        .replace(WINDOWS_ABSOLUTE_PATH, shortenWindowsPath)
+        .replace(POSIX_ABSOLUTE_PATH, shortenPosixPath);
+}
+function clamp(text, max) {
+    return text.length > max ? text.slice(0, max) + '…' : text;
+}
+/* ------------------------------------------------------------------ */
+/* Rotation                                                            */
+/* ------------------------------------------------------------------ */
+let cachedActiveSize = null;
+function activeSize() {
+    if (cachedActiveSize !== null)
+        return cachedActiveSize;
+    try {
+        cachedActiveSize = fs.statSync(getErrorsPath()).size;
+    }
+    catch {
+        cachedActiveSize = 0;
+    }
+    return cachedActiveSize;
+}
+/**
+ * Roll `errors.jsonl` to `errors-1.jsonl`, shifting older archives down and
+ * dropping anything past the retention window. Mirrors the rotation the audit
+ * writer performs for `audit.jsonl`.
+ */
+function rotateErrorLog() {
+    const active = getErrorsPath();
+    for (let i = exports.MAX_ERROR_ARCHIVES; i >= 1; i--) {
+        const from = path.join(path.dirname(active), `errors-${i}.jsonl`);
+        const to = path.join(path.dirname(active), `errors-${i + 1}.jsonl`);
+        try {
+            fs.renameSync(from, to);
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+        }
+    }
+    try {
+        fs.renameSync(active, path.join(path.dirname(active), 'errors-1.jsonl'));
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+    // Prune anything left over from a larger previous retention window.
+    for (let i = exports.MAX_ERROR_ARCHIVES + 1; i <= exports.MAX_ERROR_ARCHIVES + 5; i++) {
+        try {
+            fs.unlinkSync(path.join(path.dirname(active), `errors-${i}.jsonl`));
+        }
+        catch {
+            // ignore
+        }
+    }
+    cachedActiveSize = 0;
+}
+let dirEnsured = null;
+function appendLine(line) {
+    const errorsPath = getErrorsPath();
+    const dir = path.dirname(errorsPath);
+    if (dirEnsured !== dir) {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        dirEnsured = dir;
+    }
+    const lineBytes = Buffer.byteLength(line, 'utf8');
+    let current = activeSize();
+    if (current > 0 && current + lineBytes > exports.MAX_ERROR_LOG_BYTES) {
+        rotateErrorLog();
+        current = 0;
+    }
+    fs.appendFileSync(errorsPath, line, { encoding: 'utf8', mode: 0o600 });
+    cachedActiveSize = current + lineBytes;
+}
+/* ------------------------------------------------------------------ */
+/* Public API                                                          */
+/* ------------------------------------------------------------------ */
+/**
+ * Track an error to the local, size-capped, rotated `errors.jsonl` log.
+ * Structured, one JSON object per line. Never throws: losing the error record
+ * must not turn a recoverable failure into a crash.
+ *
+ * The record is redacted before it is written — SQL fragments and absolute
+ * filesystem paths (the agent home directory, `node_modules`) are stripped from
+ * both `message` and `stack`. The file stays local; nothing in this module
+ * transmits it anywhere.
+ */
+function trackError(err, opts = {}) {
+    try {
+        const isErr = err instanceof Error;
+        const record = {
+            ts: new Date().toISOString(),
+            level: opts.level ?? 'error',
+            op: opts.op,
+            code: isErr ? err.code : undefined,
+            message: clamp(redactErrorText(isErr ? err.message : String(err)), MAX_MESSAGE_CHARS),
+            stack: isErr && err.stack ? clamp(redactErrorText(err.stack), MAX_STACK_CHARS) : undefined,
+            agent_id: agentId,
+            pid: process.pid,
+        };
+        appendLine(JSON.stringify(record) + '\n');
+    }
+    catch {
+        // Never let error-tracking itself throw.
+    }
+}
+/** Path to the active local error log file. */
+function getErrorsPath() {
+    return path.join((0, paths_1.getSwAgentDir)(), 'errors.jsonl');
+}
+/** Paths to every file that makes up the error log, oldest archive first. */
+function getErrorLogFiles() {
+    const dir = (0, paths_1.getSwAgentDir)();
+    const files = [];
+    for (let i = exports.MAX_ERROR_ARCHIVES; i >= 1; i--) {
+        files.push(path.join(dir, `errors-${i}.jsonl`));
+    }
+    files.push(getErrorsPath());
+    return files;
+}
+/**
+ * Summarise the on-disk error log for `sw-agent status` and `sw-agent debug`.
+ * A missing log is a valid state, not an error.
+ */
+function getErrorLogStats() {
+    const active = getErrorsPath();
+    let sizeBytes = 0;
+    let records = 0;
+    let archives = 0;
+    let lastErrorTs = null;
+    for (const file of getErrorLogFiles()) {
+        let stat;
+        try {
+            stat = fs.statSync(file);
+        }
+        catch {
+            continue;
+        }
+        sizeBytes += stat.size;
+        if (file !== active) {
+            archives++;
+            continue;
+        }
+        try {
+            const content = fs.readFileSync(file, 'utf8');
+            const lines = content.split('\n');
+            records = 0;
+            for (const line of lines) {
+                if (line.trim().length === 0)
+                    continue;
+                records++;
+                try {
+                    const parsed = JSON.parse(line);
+                    if (parsed.ts)
+                        lastErrorTs = parsed.ts;
+                }
+                catch {
+                    // ignore malformed
+                }
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    return { path: active, size_bytes: sizeBytes, records, archives, last_error_ts: lastErrorTs };
+}
+/**
+ * fsync the active error log so the record that describes a fatal fault is on
+ * the disk before the process exits.
+ *
+ * `appendLine` uses `appendFileSync`, which hands the data to the kernel and
+ * returns — it does not wait for the storage. A process that exits
+ * milliseconds later can therefore lose the one record that explains why. Best
+ * effort: a missing `errors.jsonl`, a rotated-away active file, or a filesystem
+ * that rejects `fsync` must not stop the exit, because the exit is the part that
+ * matters.
+ */
+function fsyncErrorLog() {
+    const target = getErrorsPath();
+    let fd;
+    try {
+        fd = fs.openSync(target, 'r+');
+        fs.fsyncSync(fd);
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+}
+/** The controller installed by {@link installGlobalHandlers}. Test seam. */
+let faultController = null;
+/**
+ * Hooks registered before the handlers were installed.
+ *
+ * `runAgent()` builds its audit sink and `PoolManager` after it installs the
+ * process handlers — the handlers must exist before the parser load, so a
+ * startup crash is tracked — so the runtime cannot pass them in. It calls
+ * {@link registerFaultShutdownHooks} instead.
+ */
+let lateHooks = {};
+/** The live fault controller, or null before the handlers are installed. */
+function getFaultShutdownController() {
+    return faultController;
+}
+/**
+ * Register the audit-sink and pool handles the fault path must drain before it
+ * exits. Safe to call before or after {@link installGlobalHandlers}.
+ *
+ * Without this, a fault still exits non-zero and still fsyncs `errors.jsonl`, but
+ * the audit sink is left unflushed, so the final record of the action that
+ * caused the fault may never reach the chain. See the report's
+ * OTHER-FILE CHANGE REQUESTED for the one-line call site in `runtime.ts`.
+ */
+function registerFaultShutdownHooks(hooks) {
+    lateHooks = { ...lateHooks, ...hooks };
+    faultController?.setHooks(hooks);
+}
+/**
+ * Install process-level handlers for an uncaught exception or an unhandled
+ * promise rejection.
+ *
+ * Both are FAIL-CLOSED: the fault is recorded and redacted, the audit
+ * sink and the pools are drained on a bounded timer, and the process then exits
+ * non-zero so `Restart=on-failure` brings up a clean one. The previous version
+ * only recorded the fault, which OVERRODE Node's terminate-by-default behaviour
+ * and left a daemon serving database traffic in an undefined state.
+ *
+ * `unhandledRejection` is the one place that continues — and only for a reason
+ * a call site explicitly tagged with `markNonFatalRejection`. See
+ * `fault-shutdown.ts` for why the tag is a non-enumerable symbol.
+ *
+ * Also emits the startup posture lines. This is the daemon-startup hook the
+ * runtime already owns (`runAgent()` calls it right after
+ * `stripUnrecognisedSecurityEnv()`), and the resolved agent home has to be
+ * logged from somewhere that runs exactly once per daemon start. An
+ * `AgentHomeMismatchError` thrown from here propagates out of `runAgent()` and
+ * is reported by the CLI with a non-zero exit, which is the intended
+ * fail-closed outcome: a daemon running against a home nobody configured would
+ * apply a different permission default, a different database scope and a
+ * different audit key.
+ */
+function installGlobalHandlers(currentAgentId, hooks = {}) {
+    if (initialized)
+        return;
+    initialized = true;
+    agentId = currentAgentId;
+    const effective = { ...lateHooks, ...hooks };
+    const deps = {
+        track: (err, opts) => {
+            trackError(err, opts);
+        },
+        flushLocalLog: () => {
+            fsyncErrorLog();
+        },
+        log: (line) => {
+            // Two destinations, because the operator has two.
+            //
+            // 1. The journal. The shipped unit sets `StandardError=journal`, so a
+            //    narrative that only reaches `errors.jsonl` is invisible to
+            //    `journalctl -u <unit>` — which is where an operator looks first after
+            //    an unexplained restart. Writing only to the file means the most
+            //    important line the daemon ever emits is the one they cannot see.
+            try {
+                fs.writeSync(2, `${line}\n`);
+            }
+            catch {
+                try {
+                    fs.writeSync(1, `${line}\n`);
+                }
+                catch {
+                    // Nothing left to try; the exit still happens.
+                }
+            }
+            // 2. The error log, so `sw-agent debug errors` shows the shutdown
+            //    narrative and not just its cause.
+            //
+            //    The level is taken from the line's own `[warn]` / `[fatal]` prefix
+            //    rather than assumed. The survivable path — a rejection explicitly
+            //    tagged non-fatal, which the daemon deliberately keeps running
+            //    through — is logged as `warn` by the controller, and stamping it
+            //    `fatal` here put a second, contradictory `fatal` record in the file
+            //    beside it. An operator grepping `errors.jsonl` for `fatal` to answer
+            //    "did this host die on its own?" was told yes by a line describing a
+            //    rejection it survived.
+            try {
+                trackError(line, {
+                    op: 'faultShutdown',
+                    level: /^\s*\[warn\]/i.test(line) ? 'warn' : 'fatal',
+                });
+            }
+            catch {
+                // ignore
+            }
+        },
+        exit: (code) => {
+            process.exit(code);
+        },
+        ...effective,
+    };
+    faultController = (0, fault_shutdown_1.createFaultShutdownController)(deps);
+    const controller = faultController;
+    process.on('uncaughtException', (err) => {
+        void controller.handle('uncaughtException', err);
+    });
+    process.on('unhandledRejection', (reason) => {
+        void controller.handle('unhandledRejection', reason);
+    });
+    (0, state_1.assertAndLogResolvedAgentHome)();
+}
+/** Reset the install latch. Test helper; a second install in one process is a no-op. */
+function resetGlobalHandlersForTests() {
+    initialized = false;
+    agentId = undefined;
+    faultController = null;
+    lateHooks = {};
+}
+/** Read recent error records from the local log, newest last. */
+async function readRecentErrors(limit) {
+    try {
+        const records = [];
+        for (const file of getErrorLogFiles()) {
+            let content;
+            try {
+                content = await fs.promises.readFile(file, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            for (const line of content.split('\n')) {
+                if (line.trim().length === 0)
+                    continue;
+                try {
+                    records.push(JSON.parse(line));
+                }
+                catch {
+                    // ignore malformed
+                }
+            }
+        }
+        return records.slice(-limit);
+    }
+    catch {
+        return [];
+    }
+}
+/** Reset the cached active-file size and directory memo. Test and lifecycle helper. */
+function resetErrorLogCache() {
+    cachedActiveSize = null;
+    dirEnsured = null;
+}
+//# sourceMappingURL=error-tracker.js.map

package/dist/cjs/cli/daemon/error-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-tracker.js","sourceRoot":"","sources":["../../../../src/cli/daemon/error-tracker.ts"],"names":[],"mappings":"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"}

package/dist/cjs/cli/daemon/fault-shutdown.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Fail-closed shutdown on an unexpected process-level fault.
+ *
+ * Node's default behaviour for `uncaughtException` and `unhandledRejection` is
+ * to print and terminate. Installing a handler that only records the error
+ * OVERRIDES that default: the process stays alive, keeps its PostgreSQL pools,
+ * its permission state and its audit writer, and keeps answering queries while
+ * running in a state nobody reasoned about. For a long-lived daemon that holds
+ * database credentials and executes DDL, "keep serving after an unknown fault"
+ * is the wrong answer — the correct answer is to stop, leave a durable trace,
+ * and let the supervisor restart it.
+ *
+ * Everything here is injectable so a test can assert the exit DECISION without
+ * killing the test runner: `exit`, `log`, the flush hooks and the clock are all
+ * parameters, and no module-level `process.exit` call exists in this file.
+ *
+ * ## The non-fatal rejection tag
+ *
+ * `unhandledRejection` is fail-closed by default, because a rejected promise
+ * nobody handled is a bug by definition and this daemon holds credentials. The
+ * single exception has to be explicit and greppable, so the only value that is
+ * allowed to be swallowed is one that a call site deliberately tagged:
+ *
+ * ```ts
+ * markNonFatalRejection(new Error('wake-channel reconnect already in flight'));
+ * ```
+ *
+ * It sets a non-enumerable symbol on the reason object. A `Symbol`, not a
+ * string field: it cannot collide with a database column, an error message or
+ * a JSON body, it does not survive serialisation (so it cannot be replayed by
+ * anything reading the value back), and nothing outside this module can set it
+ * except by calling {@link markNonFatalRejection}. A plain
+ * `{ nonFatal: true }` flag would be forgeable by any rejected object, which
+ * would make the tag no control at all.
+ */
+/** Which process-level event produced the fault. */
+export type FaultKind = 'uncaughtException' | 'unhandledRejection';
+/**
+ * Exit code used for a fail-closed fault. `EX_SOFTWARE` from `sysexits.h`: an
+ * internal software error, as opposed to a usage or configuration error. Any
+ * non-zero value satisfies `Restart=on-failure`; a distinct one means a fault
+ * restart is greppable in the journal and separable from an ordinary crash.
+ */
+export declare const FAULT_EXIT_CODE = 70;
+/**
+ * Upper bound on the best-effort flush before the process exits anyway.
+ *
+ * Short on purpose. The flush exists to get the last audit record onto the disk,
+ * not to complete an orderly shutdown: a daemon that cannot flush in two seconds
+ * is a daemon whose I/O is stuck, and waiting longer only widens the window in
+ * which a half-released pool keeps serving. Well under the five seconds the
+ * regression test allows.
+ */
+export declare const FAULT_FLUSH_TIMEOUT_MS = 2000;
+/**
+ * Marker for a rejection a call site has decided is safe to log and continue
+ * from. Non-enumerable, so the tag cannot be discovered by enumeration or
+ * serialisation of the reason.
+ */
+export declare const NON_FATAL_REJECTION_TAG: unique symbol;
+/**
+ * Tags a rejection as deliberately non-fatal.
+ *
+ * Only for a rejection that is genuinely a duplicate/benign outcome — a wake
+ * reconnect already in flight, a cancellation racing a completion. NEVER for a
+ * failure to record an audit record, to release a permit, to classify SQL, or to
+ * do anything the product promises not to hide.
+ */
+export declare function markNonFatalRejection<T>(reason: T): T;
+/** True when {@link markNonFatalRejection} was applied to this exact value. */
+export declare function isNonFatalRejection(reason: unknown): boolean;
+/** What the fault handler is allowed to touch. Every field is injectable. */
+export interface FaultShutdownDeps {
+    /**
+     * Records the fault in `errors.jsonl`. Must never throw; a fault handler that
+     * throws has replaced a contained failure with an uncontained one.
+     */
+    track: (err: unknown, opts: {
+        op: FaultKind;
+        level: 'fatal' | 'error' | 'warn';
+    }) => void;
+    /**
+     * Best-effort: makes the last appended record durable (append + fsync).
+     * Separate from `track` because `track` must not do I/O that can block.
+     */
+    flushLocalLog?: () => void;
+    /** Drains and fsyncs the audit sink. Registered by the daemon runtime. */
+    flushAudit?: () => Promise<void>;
+    /** Releases every PostgreSQL pool. Registered by the daemon runtime. */
+    closePools?: () => Promise<void>;
+    /** Operator/journal line. Must be synchronous; the exit can follow at once. */
+    log?: (line: string) => void;
+    /** Terminates the process. Injected so a test can observe the decision. */
+    exit: (code: number) => void;
+    /** Upper bound on the flush. Defaults to {@link FAULT_FLUSH_TIMEOUT_MS}. */
+    flushTimeoutMs?: number;
+}
+/** The decision the handler reached. Every field is asserted by the tests. */
+export interface FaultShutdownDecision {
+    /** True when this call asked the process to terminate. */
+    exit_requested: boolean;
+    /** The code passed to `exit`, or null when no exit was requested. */
+    exit_code: number | null;
+    /** True when this call was a no-op because an earlier fault is already exiting. */
+    suppressed_by_earlier_fault: boolean;
+    /** True when the rejection carried the explicit non-fatal tag. */
+    non_fatal: boolean;
+    /** True when every flush hook completed within the timeout. */
+    flushed: boolean;
+    /** True when the flush did not complete in time and the exit was forced. */
+    flush_timed_out: boolean;
+}
+/**
+ * One-shot fault handler for the whole process.
+ *
+ * Idempotent by construction: the first fault latches `firing` and every later
+ * one — including an `unhandledRejection` that lands while the first fault's
+ * flush is still in flight — returns a suppressed decision without a second
+ * flush and without a second `exit`. Without the latch, an uncaught exception
+ * followed immediately by the rejection it caused would flush and close twice,
+ * and the second `close()` on an already-closed pool rejects, which is exactly
+ * the kind of cascading undefined behaviour this module exists to stop.
+ */
+export interface FaultShutdownController {
+    handle(kind: FaultKind, err: unknown): Promise<FaultShutdownDecision>;
+    /** True once the first fatal fault has started the exit path. */
+    isFiring(): boolean;
+    /**
+     * Registers the audit/pool handles after construction.
+     *
+     * Needed because the daemon builds its audit sink and `PoolManager` AFTER it
+     * installs the process handlers — the handlers must exist before the parser
+     * load so a startup crash is tracked, and the sink does not exist until after
+     * that. Refuses once a fault is in flight: swapping the flush set mid-shutdown
+     * is how a half-completed flush becomes two.
+     */
+    setHooks(hooks: Pick<FaultShutdownDeps, 'flushAudit' | 'closePools'>): boolean;
+}
+/**
+ * Builds the controller. One per process; the process handlers hold a reference
+ * to it so they share the latch.
+ */
+export declare function createFaultShutdownController(deps: FaultShutdownDeps): FaultShutdownController;
+//# sourceMappingURL=fault-shutdown.d.ts.map

package/dist/cjs/cli/daemon/fault-shutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fault-shutdown.d.ts","sourceRoot":"","sources":["../../../../src/cli/daemon/fault-shutdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAIH,oDAAoD;AACpD,MAAM,MAAM,SAAS,GAAG,mBAAmB,GAAG,oBAAoB,CAAC;AAEnE;;;;;GAKG;AACH,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,OAAQ,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,eAA2C,CAAC;AAEhF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAiBrD;AAED,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAM5D;AAED,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,EAAE,EAAE,SAAS,CAAC;QAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC1F;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;IAC3B,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,+EAA+E;IAC/E,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,2EAA2E;IAC3E,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,8EAA8E;AAC9E,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,cAAc,EAAE,OAAO,CAAC;IACxB,qEAAqE;IACrE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,mFAAmF;IACnF,2BAA2B,EAAE,OAAO,CAAC;IACrC,kEAAkE;IAClE,SAAS,EAAE,OAAO,CAAC;IACnB,+DAA+D;IAC/D,OAAO,EAAE,OAAO,CAAC;IACjB,4EAA4E;IAC5E,eAAe,EAAE,OAAO,CAAC;CAC1B;AAWD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACtE,iEAAiE;IACjE,QAAQ,IAAI,OAAO,CAAC;IACpB;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,iBAAiB,EAAE,YAAY,GAAG,YAAY,CAAC,GAAG,OAAO,CAAC;CAChF;AAeD;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,iBAAiB,GAAG,uBAAuB,CA2I9F"}