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

package/dist/types/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/types/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"}

package/dist/types/cli/daemon/index.d.ts

@@ -0,0 +1,12 @@
+export { readPidFile, writePidFile, deletePidFile, isProcessAlive } from './pid-file';
+export type { PidFile, PidFileOptions } from './pid-file';
+export { readStatusFile, writeStatusFile, isStatusStale } from './status-file';
+export type { DaemonStatus, StatusFileOptions } from './status-file';
+export { resolveAgentRuntimeState, formatDuration, formatTimestamp } from './state';
+export type { AgentRuntimeKind, AgentRuntimeState } from './state';
+export { createShutdownCoordinator } from './shutdown';
+export type { ShutdownCoordinator } from './shutdown';
+export { installSignalHandlers } from './signal-handlers';
+export { runAgent } from './runtime';
+export type { RuntimeOptions } from './runtime';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/cli/daemon/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/cli/daemon/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACtF,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE1D,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC/E,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAErE,OAAO,EAAE,wBAAwB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AACpF,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEnE,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AACvD,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC"}

package/dist/types/cli/daemon/pid-file.d.ts

@@ -0,0 +1,13 @@
+export interface PidFile {
+    pid: number;
+    started_at: string;
+    version: string;
+}
+export interface PidFileOptions {
+    path: string;
+}
+export declare function writePidFile(opts: PidFileOptions, info: PidFile): Promise<void>;
+export declare function readPidFile(opts: PidFileOptions): Promise<PidFile | null>;
+export declare function deletePidFile(opts: PidFileOptions): Promise<void>;
+export declare function isProcessAlive(pid: number): boolean;
+//# sourceMappingURL=pid-file.d.ts.map

package/dist/types/cli/daemon/pid-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pid-file.d.ts","sourceRoot":"","sources":["../../../../src/cli/daemon/pid-file.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,OAAO;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAarF;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAW/E;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CASvE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAUnD"}

package/dist/types/cli/daemon/readiness.d.ts

@@ -0,0 +1,30 @@
+export interface ReadinessOptions {
+    /** Max time to wait in ms. Default 8000. */
+    timeoutMs?: number;
+    /** Poll interval in ms. Default 250. */
+    intervalMs?: number;
+}
+export interface ReadinessResult {
+    ready: boolean;
+    pid: number | null;
+    /** Time spent waiting in ms. */
+    waitedMs: number;
+    /** Why we stopped polling. */
+    reason: 'ready' | 'timeout' | 'process_dead' | 'no_pid';
+}
+/**
+ * Poll until the daemon has written a fresh PID file AND a non-stale status
+ * file with a live process. Fixes the start → status race where status was
+ * queried before the detached daemon had a chance to write its files.
+ */
+export declare function waitForAgentReady(pidFile: string, statusFile: string, opts?: ReadinessOptions): Promise<ReadinessResult>;
+/**
+ * Poll until the daemon process is gone AND its PID file is cleaned up.
+ * Fixes the symmetric race on stop, so an immediately-following status
+ * check never reports a half-shutdown agent.
+ */
+export declare function waitForAgentGone(pidFile: string, opts?: ReadinessOptions): Promise<{
+    gone: boolean;
+    waitedMs: number;
+}>;
+//# sourceMappingURL=readiness.d.ts.map

package/dist/types/cli/daemon/readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.d.ts","sourceRoot":"","sources":["../../../../src/cli/daemon/readiness.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,gBAAgB;IAC/B,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,cAAc,GAAG,QAAQ,CAAC;CACzD;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,eAAe,CAAC,CA0C1B;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAqB9C"}

package/dist/types/cli/daemon/runtime.d.ts

@@ -0,0 +1,366 @@
+import { MachineConfig } from '../../config/machine-config';
+import { DatabasesConfig } from '../../config/db-config';
+import type { DatabaseLookupResult, DatabaseRefusalCode } from '../../execution/database-lookup';
+import type { AuditSinkHealth } from '../../audit/types';
+import { DbEntry } from '../../config/db-config';
+export interface RuntimeOptions {
+    machineConfig: MachineConfig;
+    databasesConfig: DatabasesConfig;
+    relayUrl: string;
+    auditDir: string;
+    statusFile: string;
+    pidFile: string;
+    foreground: boolean;
+    autoExitMs?: number;
+}
+export declare class RuntimeStats {
+    queries_served: number;
+    streams_served: number;
+    migrations_run: number;
+    cancellations: number;
+    permission_denies: number;
+    audit_buffer_overflows: number;
+    /**
+     * Appends this process saw rejected. `audit_events_written` is deliberately
+     * absent: it is derived from the sink, never counted here.
+     */
+    audit_events_failed: number;
+}
+/**
+ * The audit half of the daemon status block.
+ *
+ * `DaemonStatus` does not yet declare `audit_events_failed` or an `audit`
+ * block, so they are produced here and the owner of `status-file.ts` can spread
+ * this object straight into `DaemonStatus['stats']` once the type declares them.
+ */
+export interface DaemonAuditStats {
+    /** Appends the sink confirmed. Never includes a record it rejected. */
+    audit_events_written: number;
+    /** Records the sink could not persist. Audit loss, counted rather than hidden. */
+    audit_events_failed: number;
+    /** Records admitted above the audit queue high-water mark. */
+    audit_buffer_overflows: number;
+    /**
+     * Records the bounded queue discarded outright under pressure.
+     *
+     * Distinct from the two counters above, and the reason it is promoted out of
+     * the `audit` block: an overflow is *admitted* and eventually written, while a
+     * drop never reaches the file at all. It is fire-and-forget telemetry only —
+     * allow/deny decisions are written straight through and never queued, so a
+     * non-zero value means silent history loss, not a lost authorization record.
+     * Surfaced next to `audit_buffer_overflows` so an operator reading `stats`
+     * sees that the trail is lossy rather than having to know that the number
+     * exists somewhere else in the status file.
+     */
+    audit_dropped: number;
+    /**
+     * Full sink health, verbatim from {@link AuditSink.getHealth}:
+     * `dir`, `active_path`, `ready`, `writable`, `dir_mode`, `file_mode`,
+     * `retained_from_seq`, `last_write_at`, `last_error`, `last_error_at`,
+     * `error_count`, `events_written`, `events_failed`, `bytes_written`,
+     * `rotations`, `chain_id`, `seq`, `chain_error`, `queue_depth`,
+     * `overflow_admitted`, `dropped`.
+     */
+    audit: AuditSinkHealth;
+}
+/**
+ * Reconcile the audit counters from the sink's own health.
+ *
+ * `events_written` is the sink's count of appends that resolved, so a rejected
+ * record can never inflate it. `events_failed` is the greater of the rejection
+ * this process counted on the awaited path and the sink's queue-level failure
+ * count, which also covers the fire-and-forget `log()` path. `dropped` is the
+ * sink's own discard count, carried through unchanged: it has no local counter to
+ * reconcile against, because a dropped record never reaches this process at all.
+ */
+export declare function buildDaemonAuditStats(stats: RuntimeStats, health: AuditSinkHealth): DaemonAuditStats;
+/** What a shutdown needs from the audit stack, and nothing more. */
+export interface AuditShutdownTarget {
+    /** Drains the sink's queue and fsyncs everything written but not committed. */
+    flush(): Promise<void>;
+    /** Flushes and releases the file handle. Always called *after* `flush`. */
+    close(): Promise<void>;
+}
+/**
+ * Builds the daemon's audit shutdown step: flush, then close — in that order,
+ * exactly once, however many times it is called.
+ *
+ * Close-after-flush matters: `close()` on its own would be enough for the fd,
+ * but the point of flushing first is that records already counted as written by
+ * the sink reach the disk, and `LocalAuditWriter.flush()` is what advances the
+ * chain head to match. Closing *instead of* flushing would drop both.
+ *
+ * Idempotent because shutdown can arrive twice (a signal and an explicit
+ * `stop`, or a handler registered on two coordinators). Concurrent callers await
+ * the *same* promise rather than starting a second flush/close pair, so a signal
+ * that lands mid-shutdown cannot interleave with it. A failed attempt is not
+ * remembered as done: the memo is cleared so a later stop retries instead of
+ * reporting a shutdown that never completed.
+ */
+export declare function createAuditShutdown(target: AuditShutdownTarget): () => Promise<void>;
+export interface RelayResolution {
+    /** The URL the agent will actually connect to. */
+    url: string;
+    /** True when the URL came from `--relay` rather than the persisted config. */
+    isOverride: boolean;
+    /** Host of the persisted `cloud_url`, or null when it cannot be parsed. */
+    configuredHost: string | null;
+    /** Host of the requested relay URL, or null when it cannot be parsed. */
+    relayHost: string | null;
+    /** True when the override names a different host than the persisted config. */
+    hostChanged: boolean;
+}
+/**
+ * Validate a relay URL with exactly the rule `cloud_url` must already satisfy
+ * in `validateMachineConfig`: a well-formed `wss://` URL with an explicit
+ * authority and no userinfo. `ws://`, `http://`, `WSS://`, `wss:/host` and
+ * unparseable input are all refused.
+ *
+ * Throws {@link ConfigInvalidError} rather than falling back to the configured
+ * URL: silently ignoring the flag would leave the operator believing the agent
+ * is talking to the relay they named.
+ */
+export declare function assertSecureRelayUrl(raw: string): string;
+export declare function relayHostMismatchWarning(configuredHost: string, relayHost: string): string;
+/**
+ * Decide which URL the agent uses, and whether that silently redirects the
+ * token to a host the operator never configured.
+ */
+export declare function resolveRelayOverride(relayUrl: string | undefined, persistedCloudUrl: string): RelayResolution;
+/**
+ * Render a URL for a terminal or a log: scheme and host only. Userinfo, path
+ * tokens, query and fragment are masked, so echoing a URL can never disclose a
+ * credential.
+ */
+export declare function redactUrlForDisplay(raw: string): string;
+/** Connections per database pool when nothing valid is configured. */
+export declare const DEFAULT_POOL_MAX = 15;
+export declare const MIN_POOL_MAX = 1;
+export declare const MAX_POOL_MAX = 200;
+/**
+ * Resolve the per-pool connection ceiling.
+ *
+ * Anything that is not an integer inside `[MIN_POOL_MAX, MAX_POOL_MAX]` — a
+ * non-numeric value, zero, a negative number, or an absurd ceiling that would
+ * be refused by PostgreSQL's own `max_connections` — falls back to the
+ * default. Previously `SW_PG_POOL_MAX` was passed straight through
+ * `parseInt`, so `abc` produced `NaN` and `999999` asked the database for a
+ * connection storm.
+ */
+export declare function resolvePoolMax(env?: NodeJS.ProcessEnv): number;
+/** Shortest approval window that is still an approval rather than a formality. */
+export declare const MIN_APPROVAL_TIMEOUT_MS = 5000;
+export declare const MAX_APPROVAL_TIMEOUT_MS = 3600000;
+/**
+ * Resolve the manual-approval window.
+ *
+ * `0` and negative values are never honoured: they would expire every pending
+ * approval the instant it was created, turning the approval gate into a no-op.
+ * Garbage falls back to `DEFAULTS.APPROVAL_TIMEOUT_MS`, and an in-range value
+ * is clamped rather than rejected so a deliberate typo cannot silently widen
+ * the window.
+ */
+export declare function resolveApprovalTimeoutMs(env?: NodeJS.ProcessEnv): number;
+/**
+ * Mirror `PoolManager.maxStatementTimeoutMs` for the startup posture log: the
+ * environment may lower the ceiling but never raise it past the compiled-in
+ * hard cap.
+ */
+export declare function resolveStatementTimeoutMs(env?: NodeJS.ProcessEnv): number;
+/**
+ * Mirror the query runner's streaming row ceiling for the posture log. Same
+ * rule as its private `readBoundedEnvInt`, including its `parseInt` semantics:
+ * NaN, zero and negatives fall back, absurd values are clamped.
+ */
+export declare function resolveMaxStreamRows(env?: NodeJS.ProcessEnv): number;
+export interface E2EAdminGate {
+    requested: boolean;
+    allowed: boolean;
+    reason: string;
+}
+/**
+ * Gate for the historical `SW_AGENT_E2E` escape hatch that used to start an
+ * unauthenticated loopback admin server with `/admin/shutdown`.
+ *
+ * There is no admin server in this build, so `allowed: true` still starts
+ * nothing. The gate exists so the conditions that would have to hold before
+ * such a control plane could be reintroduced are stated once, in code, rather
+ * than in a comment: never in production, never in a daemonised process, and
+ * only with an explicit second opt-in.
+ */
+export declare function resolveE2EAdminGate(env?: NodeJS.ProcessEnv): E2EAdminGate;
+export interface SecurityPostureEntry {
+    name: string;
+    resolved: string;
+    detail: string;
+}
+/**
+ * The resolved value of every input that changes this process's security
+ * posture, so the effective configuration is observable in the log rather than
+ * implicit in whatever environment the process happened to inherit.
+ *
+ * `env` is the environment the values are actually resolved from — the live one,
+ * after the refused variables have been stripped, so a reported value is the
+ * value in effect. `inherited` is the pre-strip snapshot, used only to say
+ * whether a variable was set at all; pass it so the report can distinguish "not
+ * set" from "set, and ignored".
+ */
+export declare function resolveSecurityPosture(env?: NodeJS.ProcessEnv, inherited?: NodeJS.ProcessEnv): SecurityPostureEntry[];
+/**
+ * Render the posture block. `secrets` are replaced with `***` in every line, so
+ * an agent token or an ingest URL can never reach the log through this path.
+ */
+export declare function formatSecurityPosture(entries: SecurityPostureEntry[], secrets?: Array<string | undefined>): string[];
+/**
+ * One permitted `(project_name, db_alias)` pairing. A rule with only
+ * `project_name` permits that project under any alias; a rule with only
+ * `db_alias` permits that alias under any project.
+ */
+export interface DatabaseScopeRule {
+    project_name?: string;
+    db_alias?: string;
+}
+/** Environment channel for the allow-list, for installs that cannot edit config. */
+export declare const ALLOWED_DATABASES_ENV = "SW_AGENT_ALLOWED_DATABASES";
+/** Config key read for the allow-list; the schema still needs to declare it. */
+export declare const ALLOWED_DATABASES_CONFIG_KEY = "allowed_databases";
+/**
+ * Validate an allow-list declaration. Returns null when nothing is configured
+ * (the backwards-compatible unscoped case) and throws when something is
+ * configured but malformed — a typo must not widen the scope it was meant to
+ * narrow.
+ */
+export declare function parseScopeRules(raw: unknown): DatabaseScopeRule[] | null;
+/** Parse the comma-separated environment form of the allow-list. */
+export declare function parseScopeEnv(raw: string | undefined): DatabaseScopeRule[] | null;
+/**
+ * Effective allow-list, resolved from both declaration channels.
+ *
+ * The environment can only **NARROW**. the two were unioned, so anybody
+ * who could set `SW_AGENT_ALLOWED_DATABASES` in the daemon's environment could
+ * add a database the operator had deliberately excluded — an environment
+ * variable is a weaker channel than a config file and must not be the stronger
+ * one. When both channels declare a scope, the result is their intersection; a
+ * rule survives only if some config rule and some env rule can both match the
+ * same entry. An empty intersection is a scope that permits nothing.
+ *
+ * Null means nothing was declared anywhere. That is no longer "every database is
+ * permitted": see {@link resolveDatabaseScopeDecision}.
+ */
+export declare function resolveDatabaseScope(machineConfig: MachineConfig, env?: NodeJS.ProcessEnv): DatabaseScopeRule[] | null;
+/**
+ * Config key that restores the pre-remediation permissive default.
+ *
+ * RISK: with no allow-list and this key set to `true`, ONE agent token reaches
+ * EVERY configured database on the host — typically dev, staging and production —
+ * and any authenticated principal on the relay can name any of them. It exists
+ * only so an existing deployment can keep working across this upgrade with a
+ * deliberate, visible choice; the default is fail-closed.
+ */
+export declare const ALLOW_UNSCOPED_DATABASES_CONFIG_KEY = "allow_unscoped_databases";
+/** Machine-config path for the same escape hatch. */
+export declare const ALLOW_UNSCOPED_DATABASES_CONFIG_PATH = "security.allow_unscoped_databases";
+export interface DatabaseScopeDecision {
+    /** Effective allow-list, or null when nothing was declared. */
+    rules: DatabaseScopeRule[] | null;
+    /** True when the environment channel narrowed (or contradicted) the config. */
+    env_narrowed: boolean;
+    /**
+     * Whether the pre-remediation default is deliberately restored. Only ever true
+     * for the literal boolean `true` under `security.allow_unscoped_databases` —
+     * a string, a number or `1` does not restore it, so a typo cannot silently
+     * re-open every database.
+     */
+    allow_unscoped: boolean;
+    /** True when at least one channel declared an allow-list. */
+    scoped: boolean;
+    /**
+     * True when this installation will serve `ping` only, because no allow-list was
+     * declared and the permissive default was not explicitly restored.
+     */
+    fail_closed: boolean;
+}
+/**
+ * The effective database scope, and whether this installation fails closed.
+ *
+ * . The default was "no allow-list means every configured database", so an
+ * install that had never been configured — the default install — let a session
+ * authenticated for one project read any other project on the host, including
+ * production. The default is now the opposite: nothing declared means nothing is
+ * reachable except `ping`, and the refusal is audited.
+ *
+ * Restoring the old behaviour requires the explicit
+ * `security.allow_unscoped_databases: true`.
+ */
+export declare function resolveDatabaseScopeDecision(machineConfig: MachineConfig, env?: NodeJS.ProcessEnv): DatabaseScopeDecision;
+/** True when the entry is permitted. An absent allow-list permits everything. */
+export declare function scopeAllowsEntry(rules: DatabaseScopeRule[] | null, entry: DbEntry): boolean;
+export interface DeniedDatabaseRequest {
+    project: string;
+    db_alias?: string;
+    reason: string;
+    /**
+     * Machine-readable refusal code, carried so the console line and any audit
+     * record agree on what happened. Optional for callers that only render text.
+     */
+    code?: DatabaseRefusalCode;
+}
+export interface LookupDbOptions {
+    getDatabases: () => DbEntry[];
+    scope: DatabaseScopeRule[] | null;
+    onDenied?: (attempt: DeniedDatabaseRequest) => void;
+    /**
+     * The effective scope decision. When it is absent the lookup keeps the
+     * permissive historical behaviour of `scope === null` meaning "everything",
+     * which is exactly what a caller with no decision object is assumed to want;
+     * the daemon always supplies one.
+     */
+    decision?: DatabaseScopeDecision;
+}
+/**
+ * Resolve an inbound frame's self-declared `project_name` / `db_alias` to a
+ * database entry, refusing anything outside the allow-list.
+ *
+ * Two refusals that did not exist before:
+ *
+ *   - **Fail closed with no allow-list**. With nothing declared, this
+ *     installation serves `ping` only. Restoring the old "everything is
+ *     reachable" default requires the explicit
+ *     `security.allow_unscoped_databases: true`.
+ *   - **Project/alias collision**. When a frame names BOTH a project and
+ *     an alias and they select *different* entries, the frame is refused. The
+ *     old code silently preferred the project, executed against it, echoed the
+ *     alias back and recorded neither — so the operation and the audit trail
+ *     both named a database the operation never touched. Naming the same entry
+ *     two ways is accepted.
+ *
+ * The result carries the refusal code rather than only `null` so the caller can
+ * audit the refusal under its own reason instead of a generic "unavailable".
+ */
+export declare function createLookupDb(opts: LookupDbOptions): (project: string, alias?: string) => DatabaseLookupResult;
+/**
+ * What an operator needs to know about this installation's database scope.
+ *
+ * Three states, and they read very differently on purpose:
+ *
+ *   - **scoped** — an allow-list is in force. Nothing to say.
+ *   - **fail-closed (the new default)** — nothing is declared, so this agent
+ *     serves `ping` only. This is the upgrade notice  asks for: an existing
+ *     install that never configured `allowed_databases` previously reached every
+ *     database on the host and will now reach none, and an operator who has not
+ *     read a changelog needs to be told that in the first seconds of the daemon,
+ *     not in a log file nobody opens.
+ *   - **unscoped by explicit opt-in** — every configured database is reachable
+ *     again, and the risk is named in full.
+ */
+export declare function databaseScopeWarningLines(scope: DatabaseScopeRule[] | null, databases: DbEntry[], decision?: DatabaseScopeDecision): string[];
+/**
+ * One-line summary for `sw-agent status`.
+ *
+ * The warning above goes to the console of a detached daemon, which most
+ * operators never see; this is the part that has to reach the CLI an operator
+ * actually runs. See the `security` block of `DaemonStatus`.
+ */
+export declare function describeDatabaseScope(decision: DatabaseScopeDecision, databases: DbEntry[]): string;
+export declare function runAgent(opts: RuntimeOptions): Promise<number>;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/types/cli/daemon/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../../src/cli/daemon/runtime.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAuB,MAAM,wBAAwB,CAAC;AAwB9E,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAQjG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAIzD,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAIjD,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,aAAa,CAAC;IAC7B,eAAe,EAAE,eAAe,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,YAAY;IACvB,cAAc,SAAK;IACnB,cAAc,SAAK;IACnB,cAAc,SAAK;IACnB,aAAa,SAAK;IAClB,iBAAiB,SAAK;IACtB,sBAAsB,SAAK;IAC3B;;;OAGG;IACH,mBAAmB,SAAK;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,oBAAoB,EAAE,MAAM,CAAC;IAC7B,kFAAkF;IAClF,mBAAmB,EAAE,MAAM,CAAC;IAC5B,8DAA8D;IAC9D,sBAAsB,EAAE,MAAM,CAAC;IAC/B;;;;;;;;;;;OAWG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,KAAK,EAAE,eAAe,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,eAAe,GACtB,gBAAgB,CAQlB;AAMD,oEAAoE;AACpE,MAAM,WAAW,mBAAmB;IAClC,+EAA+E;IAC/E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,2EAA2E;IAC3E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAcpF;AAMD,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,UAAU,EAAE,OAAO,CAAC;IACpB,2EAA2E;IAC3E,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,yEAAyE;IACzE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,+EAA+E;IAC/E,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAcxD;AAUD,wBAAgB,wBAAwB,CAAC,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAS1F;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,iBAAiB,EAAE,MAAM,GACxB,eAAe,CAoBjB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAgBvD;AAMD,sEAAsE;AACtE,eAAO,MAAM,gBAAgB,KAAK,CAAC;AACnC,eAAO,MAAM,YAAY,IAAI,CAAC;AAC9B,eAAO,MAAM,YAAY,MAAM,CAAC;AAahC;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAM3E;AAED,kFAAkF;AAClF,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AAC7C,eAAO,MAAM,uBAAuB,UAAY,CAAC;AAEjD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CASrF;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAOtF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAMjF;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,CAiBtF;AAcD,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,SAAS,GAAE,MAAM,CAAC,UAAgB,GACjC,oBAAoB,EAAE,CAuGxB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,oBAAoB,EAAE,EAC/B,OAAO,GAAE,KAAK,CAAC,MAAM,GAAG,SAAS,CAAM,GACtC,MAAM,EAAE,CASV;AAMD;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,oFAAoF;AACpF,eAAO,MAAM,qBAAqB,+BAA+B,CAAC;AAElE,gFAAgF;AAChF,eAAO,MAAM,4BAA4B,sBAAsB,CAAC;AAwChE;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,iBAAiB,EAAE,GAAG,IAAI,CAsCxE;AAED,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,iBAAiB,EAAE,GAAG,IAAI,CAOjF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,aAAa,EAAE,aAAa,EAC5B,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,iBAAiB,EAAE,GAAG,IAAI,CAQ5B;AAuCD;;;;;;;;GAQG;AACH,eAAO,MAAM,mCAAmC,6BAA6B,CAAC;AAE9E,qDAAqD;AACrD,eAAO,MAAM,oCAAoC,sCAAoD,CAAC;AAEtG,MAAM,WAAW,qBAAqB;IACpC,+DAA+D;IAC/D,KAAK,EAAE,iBAAiB,EAAE,GAAG,IAAI,CAAC;IAClC,+EAA+E;IAC/E,YAAY,EAAE,OAAO,CAAC;IACtB;;;;;OAKG;IACH,cAAc,EAAE,OAAO,CAAC;IACxB,6DAA6D;IAC7D,MAAM,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAC1C,aAAa,EAAE,aAAa,EAC5B,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,qBAAqB,CA2BvB;AAeD,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,iBAAiB,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAO3F;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,IAAI,CAAC,EAAE,mBAAmB,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,OAAO,EAAE,CAAC;IAC9B,KAAK,EAAE,iBAAiB,EAAE,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC;IACpD;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,eAAe,GACpB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,oBAAoB,CAsF3D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,iBAAiB,EAAE,GAAG,IAAI,EACjC,SAAS,EAAE,OAAO,EAAE,EACpB,QAAQ,CAAC,EAAE,qBAAqB,GAC/B,MAAM,EAAE,CAmCV;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,qBAAqB,EAC/B,SAAS,EAAE,OAAO,EAAE,GACnB,MAAM,CAiBR;AAED,wBAAsB,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAwiBpE"}

package/dist/types/cli/daemon/shutdown.d.ts

@@ -0,0 +1,7 @@
+export interface ShutdownCoordinator {
+    register(name: string, cleanup: () => Promise<void>): () => void;
+    shutdown(timeoutMs?: number): Promise<'clean' | 'timeout'>;
+    isShuttingDown(): boolean;
+}
+export declare function createShutdownCoordinator(): ShutdownCoordinator;
+//# sourceMappingURL=shutdown.d.ts.map

package/dist/types/cli/daemon/shutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../../../src/cli/daemon/shutdown.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,MAAM,IAAI,CAAC;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;IAC3D,cAAc,IAAI,OAAO,CAAC;CAC3B;AAiED,wBAAgB,yBAAyB,IAAI,mBAAmB,CAE/D"}

package/dist/types/cli/daemon/signal-handlers.d.ts

@@ -0,0 +1,3 @@
+import { ShutdownCoordinator } from './shutdown';
+export declare function installSignalHandlers(coordinator: ShutdownCoordinator): () => void;
+//# sourceMappingURL=signal-handlers.d.ts.map

package/dist/types/cli/daemon/signal-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal-handlers.d.ts","sourceRoot":"","sources":["../../../../src/cli/daemon/signal-handlers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEjD,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,mBAAmB,GAAG,MAAM,IAAI,CA2BlF"}