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

package/dist/cjs/execution/canceller.js

@@ -0,0 +1,209 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Canceller = void 0;
+const pg_1 = require("pg");
+const pool_1 = require("./pool");
+class Canceller {
+    inFlight = new Map();
+    opts;
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    register(req) {
+        this.inFlight.set(req.request_id, req);
+    }
+    unregister(requestId) {
+        this.inFlight.delete(requestId);
+    }
+    getInFlight() {
+        return this.inFlight;
+    }
+    /**
+     * Cancel a request by request_id using pg_cancel_backend on a separate
+     * connection (PostgreSQL cannot cancel a query from the busy session).
+     */
+    async cancel(requestId, dbEntry) {
+        const req = this.inFlight.get(requestId);
+        if (!req) {
+            return {
+                cancelled: false,
+                terminated: false,
+                local_abort: false,
+                reason: 'No in-flight request found with the specified ID.',
+            };
+        }
+        // Cooperative local cancellation. Every runner that registers an in-flight
+        // request listens on this controller, so firing it stops the local work at
+        // the next checkpoint (between FETCH batches, before the next statement)
+        // with no database round trip at all. This happens first and never depends
+        // on the connection below succeeding.
+        const localAbortFired = !req.abort.signal.aborted;
+        req.abort.abort();
+        let client = null;
+        let cleanup = () => { };
+        if (this.opts.poolManager) {
+            try {
+                const acquired = await this.opts.poolManager.acquire(dbEntry);
+                client = acquired.client;
+                // This connection is about to issue `pg_cancel_backend`. From here on its
+                // session is no longer a session this pool can vouch for: it has acted on
+                // a backend the pool knows nothing about, and nothing that happens next
+                // can prove the session clean again.
+                //
+                // Marking it dirty is what makes `PoolManager.release` destroy it instead
+                // of recycling it. Releasing it normally would put a connection that has
+                // already cancelled someone else's session back into the idle queue, where
+                // the next unrelated request inherits it — the same reason
+                // `MigrationRunner` marks its client dirty before it opens a transaction.
+                // The cost is one reconnect per cancel, which is the point: reusing the
+                // pool instead of dialling a new connection is what keeps a stream of
+                // cancels from exhausting `max_connections`, and it does not require
+                // recycling the connection that did it.
+                (0, pool_1.markSessionDirty)(acquired.client);
+                cleanup = acquired.release;
+            }
+            catch {
+                client = null;
+            }
+        }
+        if (!client) {
+            // Fall back to a one-off connection. Mirror the pool's TLS negotiation
+            // exactly. The previous code fell back to `sslConfig = false`, which
+            // silently downgraded a credential-bearing connection to plaintext when
+            // the CA file could not be read.
+            let sslConfig;
+            try {
+                sslConfig = (0, pool_1.buildSslConfig)(dbEntry.ssl_mode, dbEntry.ssl_root_cert);
+            }
+            catch (err) {
+                // Audit M-02: fail CLOSED, and report it as the failure it is.
+                //
+                // `cancelled` is the wire fact documented on CancelResultPayload —
+                // "whether the cancel signal was sent". No signal reached PostgreSQL,
+                // so it is `false`; the cooperative abort that did fire is reported
+                // separately and exactly, through `local_abort`. Claiming `cancelled:
+                // true` here told the browser the backend had been signalled while a
+                // blocked statement kept running.
+                //
+                // The detail is logged rather than folded into `reason`, which stays the
+                // stable `ssl_error` code this contract specifies and that
+                // validateCancelResultPayload accepts as a plain string.
+                console.error(`Canceller: refusing to open a cancellation connection for ${dbEntry.db_alias} without TLS ` +
+                    `(ssl_mode ${dbEntry.ssl_mode}): ${err instanceof Error ? err.message : String(err)}`);
+                return {
+                    cancelled: false,
+                    terminated: false,
+                    local_abort: localAbortFired,
+                    reason: 'ssl_error',
+                };
+            }
+            const password = dbEntry.password_stored ||
+                (dbEntry.password_env ? process.env[dbEntry.password_env] : undefined);
+            if (!password) {
+                // Same contract as the TLS refusal above: no signal reached PostgreSQL,
+                // so `cancelled` is false and the cooperative abort is reported through
+                // `local_abort` alone. Claiming `cancelled: true` here told the browser
+                // the backend had been signalled when nothing was ever sent.
+                return {
+                    cancelled: false,
+                    terminated: false,
+                    local_abort: localAbortFired,
+                    reason: 'No password available for the cancellation connection.',
+                };
+            }
+            const clientConfig = {
+                host: dbEntry.host,
+                port: dbEntry.port,
+                database: dbEntry.database,
+                user: dbEntry.user,
+                password,
+                ssl: sslConfig,
+                connectionTimeoutMillis: 5_000,
+                application_name: 'schema-weaver-pg-connector-cancel',
+            };
+            const c = new pg_1.Client(clientConfig);
+            try {
+                await c.connect();
+            }
+            catch (err) {
+                // The connection never opened, so no cancel signal was sent. Fail closed
+                // for the same reason as the TLS path, and keep the underlying cause on
+                // the console rather than folding it into the stable `reason` string.
+                console.error(`Canceller: could not open a cancellation connection for ${dbEntry.db_alias}: ${err instanceof Error ? err.message : String(err)}`);
+                return {
+                    cancelled: false,
+                    terminated: false,
+                    local_abort: localAbortFired,
+                    reason: `Could not open a cancellation connection: ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+            client = c;
+            cleanup = () => {
+                c.end().catch(() => { });
+            };
+        }
+        try {
+            const cancelRes = await client.query('SELECT pg_cancel_backend($1) AS cancelled', [req.pid]);
+            const wasCancelled = cancelRes.rows[0]?.cancelled === true;
+            if (wasCancelled) {
+                return { cancelled: true, terminated: true, local_abort: localAbortFired };
+            }
+            // PostgreSQL answered `false`: no cancel signal was delivered. That is
+            // the server's own verdict and it governs `cancelled`.
+            //
+            // This previously reported `cancelled: localAbortFired`, which is `true`
+            // whenever the local AbortController fired. A caller that trusted the
+            // field was told a blocked statement had been stopped while it kept
+            // running on the server — the exact failure the `catch` branch below was
+            // already corrected for. A local abort stops OUR loop; only
+            // pg_cancel_backend stops PostgreSQL's.
+            return {
+                cancelled: false,
+                terminated: true,
+                local_abort: localAbortFired,
+                reason: 'PostgreSQL reported the cancel signal was not delivered (pg_cancel_backend ' +
+                    'returned false). The backend was likely already idle, gone, or the PID was ' +
+                    'recycled. The local fetch loop was aborted' +
+                    (localAbortFired ? '.' : ', but it had already finished.'),
+            };
+        }
+        catch (err) {
+            // `pg_cancel_backend` did not return a verdict, so no signal is known to
+            // have reached PostgreSQL. The previous `cancelled: localAbortFired` made
+            // a fired local abort indistinguishable from a delivered cancel, so the
+            // browser was told a blocked statement had been stopped while it kept
+            // running. Fail closed and keep the cause on the console.
+            console.error(`Canceller: pg_cancel_backend failed for ${dbEntry.db_alias} (pid ${req.pid}): ${err instanceof Error ? err.message : String(err)}`);
+            return {
+                cancelled: false,
+                terminated: false,
+                local_abort: localAbortFired,
+                reason: `pg_cancel_backend failed: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        finally {
+            // A connection that has issued a cancel is never handed back for reuse.
+            //
+            // Pooled: `markSessionDirty` above makes this release *destroy* the
+            //   connection instead of returning it to the idle queue, so the next
+            //   request cannot inherit a session that just cancelled a backend.
+            // One-off: `cleanup` ends the dedicated connection, and its rejection is
+            //   already swallowed there.
+            //
+            // Both are the same call, so there is one branch — not a conditional whose
+            // arms happen to be identical. Neither may throw: this runs in a `finally`,
+            // and an exception raised while unwinding would replace the cancel result
+            // the caller is about to report to the browser with a release failure that
+            // says nothing about whether the query was actually stopped.
+            try {
+                cleanup();
+            }
+            catch {
+                // The cancel outcome above stands; a connection that will not release is
+                // the pool's problem to log, not a reason to misreport the cancel.
+            }
+        }
+    }
+}
+exports.Canceller = Canceller;
+//# sourceMappingURL=canceller.js.map

package/dist/cjs/execution/canceller.js.map

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

package/dist/cjs/execution/database-lookup.d.ts

@@ -0,0 +1,56 @@
+import type { DbEntry } from '../config/db-config';
+/**
+ * Why a frame's `(project, db_alias)` did not resolve to a database.
+ *
+ * These are the codes that reach the audit trail as `denial_reason` on a `deny`
+ * record, so they are stable, data-free and closed. They never name a database
+ * that exists: distinguishing "you named a project that is not configured" from
+ * "that project is out of scope" would be a database-existence oracle.
+ */
+export type DatabaseRefusalCode = 
+/** No configured entry matches the frame. */
+'database_not_found'
+/** The entry exists but the allow-list does not permit it. */
+ | 'database_out_of_scope'
+/** No allow-list is configured at all, so this installation serves ping only. */
+ | 'database_scope_not_configured'
+/** `project` and `db_alias` select different configured entries. */
+ | 'db_alias_project_mismatch';
+export interface DatabaseLookupRefusal {
+    ok: false;
+    code: DatabaseRefusalCode;
+    /** Data-free, caller-safe explanation. Never names a configured database. */
+    reason: string;
+    /** The project the frame claimed. */
+    asserted_project: string;
+    /** The `db_alias` the frame claimed, or `''` when it carried none. */
+    asserted_db_alias: string;
+}
+export interface DatabaseLookupHit {
+    ok: true;
+    entry: DbEntry;
+}
+export type DatabaseLookupResult = DatabaseLookupHit | DatabaseLookupRefusal;
+/**
+ * The lookup signature the dispatcher accepts.
+ *
+ * `DbEntry | null` is still accepted so an existing caller — and every test that
+ * passes a one-line `lookupDb` — keeps working; a `null` is read as
+ * `database_not_found`, which is exactly what it meant before. A caller that
+ * wants to say *why* (the allow-list, a project/alias collision) returns the rich
+ * form, and the dispatcher records that code instead of a generic
+ * `db_unavailable`.
+ */
+export type LookupDbFn = (project: string, alias?: string) => DbEntry | DatabaseLookupResult | null;
+/** Read the entry out of any accepted lookup result, or null. */
+export declare function resolvedEntry(result: DbEntry | DatabaseLookupResult | null): DbEntry | null;
+/** Whether a lookup result is a refusal rather than a hit. */
+export declare function isLookupRefusal(result: DbEntry | DatabaseLookupResult | null): result is DatabaseLookupRefusal;
+/**
+ * Normalise any accepted lookup result into the rich form.
+ *
+ * A legacy `DbEntry | null` becomes a hit or `database_not_found`, so the
+ * dispatcher has exactly one shape to audit from.
+ */
+export declare function normaliseLookupResult(result: DbEntry | DatabaseLookupResult | null, assertedProject: string, assertedAlias: string | undefined): DatabaseLookupResult;
+//# sourceMappingURL=database-lookup.d.ts.map

package/dist/cjs/execution/database-lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-lookup.d.ts","sourceRoot":"","sources":["../../../src/execution/database-lookup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB;AAC7B,6CAA6C;AAC3C,oBAAoB;AACtB,8DAA8D;GAC5D,uBAAuB;AACzB,iFAAiF;GAC/E,+BAA+B;AACjC,oEAAoE;GAClE,2BAA2B,CAAC;AAEhC,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,KAAK,CAAC;IACV,IAAI,EAAE,mBAAmB,CAAC;IAC1B,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,gBAAgB,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,IAAI,CAAC;IACT,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,MAAM,oBAAoB,GAAG,iBAAiB,GAAG,qBAAqB,CAAC;AAE7E;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAAG,CACvB,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,KACX,OAAO,GAAG,oBAAoB,GAAG,IAAI,CAAC;AAE3C,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,oBAAoB,GAAG,IAAI,GAAG,OAAO,GAAG,IAAI,CAI3F;AAED,8DAA8D;AAC9D,wBAAgB,eAAe,CAC7B,MAAM,EAAE,OAAO,GAAG,oBAAoB,GAAG,IAAI,GAC5C,MAAM,IAAI,qBAAqB,CAOjC;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,GAAG,oBAAoB,GAAG,IAAI,EAC7C,eAAe,EAAE,MAAM,EACvB,aAAa,EAAE,MAAM,GAAG,SAAS,GAChC,oBAAoB,CAatB"}

package/dist/cjs/execution/database-lookup.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvedEntry = resolvedEntry;
+exports.isLookupRefusal = isLookupRefusal;
+exports.normaliseLookupResult = normaliseLookupResult;
+/** Read the entry out of any accepted lookup result, or null. */
+function resolvedEntry(result) {
+    if (result === null || result === undefined)
+        return null;
+    if (isLookupRefusal(result))
+        return null;
+    return 'entry' in result ? result.entry : result;
+}
+/** Whether a lookup result is a refusal rather than a hit. */
+function isLookupRefusal(result) {
+    return (typeof result === 'object' &&
+        result !== null &&
+        'ok' in result &&
+        result.ok === false);
+}
+/**
+ * Normalise any accepted lookup result into the rich form.
+ *
+ * A legacy `DbEntry | null` becomes a hit or `database_not_found`, so the
+ * dispatcher has exactly one shape to audit from.
+ */
+function normaliseLookupResult(result, assertedProject, assertedAlias) {
+    if (result === null || result === undefined) {
+        return {
+            ok: false,
+            code: 'database_not_found',
+            reason: `No configured database matches project "${assertedProject}"`,
+            asserted_project: assertedProject,
+            asserted_db_alias: assertedAlias ?? '',
+        };
+    }
+    if (isLookupRefusal(result))
+        return result;
+    if ('entry' in result)
+        return result;
+    return { ok: true, entry: result };
+}
+//# sourceMappingURL=database-lookup.js.map

package/dist/cjs/execution/database-lookup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-lookup.js","sourceRoot":"","sources":["../../../src/execution/database-lookup.ts"],"names":[],"mappings":";;AAsDA,sCAIC;AAGD,0CASC;AAQD,sDAiBC;AA1CD,iEAAiE;AACjE,SAAgB,aAAa,CAAC,MAA6C;IACzE,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACzD,IAAI,eAAe,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,OAAO,OAAO,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;AACnD,CAAC;AAED,8DAA8D;AAC9D,SAAgB,eAAe,CAC7B,MAA6C;IAE7C,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,IAAI,IAAI,MAAM;QACb,MAA2B,CAAC,EAAE,KAAK,KAAK,CAC1C,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAgB,qBAAqB,CACnC,MAA6C,EAC7C,eAAuB,EACvB,aAAiC;IAEjC,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAC5C,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,oBAAoB;YAC1B,MAAM,EAAE,2CAA2C,eAAe,GAAG;YACrE,gBAAgB,EAAE,eAAe;YACjC,iBAAiB,EAAE,aAAa,IAAI,EAAE;SACvC,CAAC;IACJ,CAAC;IACD,IAAI,eAAe,CAAC,MAAM,CAAC;QAAE,OAAO,MAAM,CAAC;IAC3C,IAAI,OAAO,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IACrC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AACrC,CAAC"}

package/dist/cjs/execution/dispatcher.d.ts

@@ -0,0 +1,181 @@
+import { AgentMessage, EventKind, Role } from '../protocol/envelope';
+import { PoolManager } from './pool';
+import { QueryRunner } from './query-runner';
+import { MigrationRunner } from './migration-runner';
+import { Canceller } from './canceller';
+import { Introspector } from './introspection';
+import { ErrorCode } from '../protocol/errors';
+import { PermissionChecker } from '../permissions/checker';
+import { PlanRegistry } from '../permissions/plan-registry';
+import { MachineConfig } from '../config/machine-config';
+import { PermissionLevel } from '../permissions/types';
+import { AuditSink } from '../audit/sink';
+import { AuditAction } from '../audit/types';
+import { RateLimiter } from './rate-limiter';
+import { type LookupDbFn } from './database-lookup';
+export interface DispatcherOptions {
+    poolManager: PoolManager;
+    queryRunner: QueryRunner;
+    migrationRunner: MigrationRunner;
+    canceller: Canceller;
+    introspector: Introspector;
+    permissionChecker: PermissionChecker;
+    planRegistry: PlanRegistry;
+    /**
+     * Look up the DB entry for a frame's `(project, db_alias)`.
+     *
+     * Returning the rich `DatabaseLookupResult` lets the caller say *why* a frame
+     * resolved to nothing (out of scope, no allow-list configured, or a
+     * project/alias collision) so the refusal is audited under a distinct reason
+     * instead of a generic "unavailable". A plain `DbEntry | null` is still
+     * accepted and is read as "no such database".
+     */
+    lookupDb: LookupDbFn;
+    /** Look up machine config (for default permission). */
+    getMachineConfig: () => MachineConfig;
+    /** Send a message back to the browser. */
+    send: (msg: AgentMessage) => Promise<void>;
+    /**
+     * Transport drain signal, awaited by the streaming fetch loop before every
+     * cursor fetch (audit H-10). Supplying it is what makes the pause/resume real:
+     * `send` alone only stops the producer when the socket write callback fires,
+     * which cannot see bytes already queued in the transport.
+     *
+     * Optional by design. Without it a stream still completes — it just
+     * self-throttles on each awaited chunk send instead of the send buffer.
+     */
+    waitForDrain?: () => Promise<void>;
+    /** Optional audit sink for logging decisions and outcomes. */
+    auditSink?: AuditSink;
+    /**
+     * Budget and concurrency control for inbound work. Defaults to a process-wide
+     * limiter; an explicit instance is only for tests and for a host that wants
+     * its own policy.
+     */
+    rateLimiter?: RateLimiter;
+}
+export declare class Dispatcher {
+    private readonly opts;
+    private readonly rateLimiter;
+    constructor(opts: DispatcherOptions);
+    private sendResponse;
+    /**
+     * `pg_error` is deliberately limited to the two allow-listed fields. Passing
+     * `detail` or `hint` here is a compile error on purpose: both routinely carry
+     * row data (`DETAIL:  Key (email)=(alice@corp.com) already exists.`) and the
+     * risk only ever grows.
+     */
+    private sendError;
+    /**
+     * Register a migration plan. Callers must have passed `evaluateEventGate`;
+     * this method re-checks the shape of the payload and never invents an
+     * effective permission level for the audit record.
+     */
+    handlePlanRegister(msg: AgentMessage, statements: string[], riskLevel: 'low' | 'medium' | 'high' | undefined, permissionLevel: PermissionLevel, resolvedAlias?: string): Promise<void>;
+    /**
+     * Derive the authorization decision for an inbound `event` frame.
+     *
+     * `PlanRegistry.canRegister` owns the plan-registration decision, so asking
+     * it directly is what keeps the entry gate and the registry from disagreeing.
+     */
+    private evaluateGate;
+    /**
+     * Handle an inbound `event` frame.
+     *
+     * Every kind is authorized before any handler runs. The previous
+     * implementation dispatched `approval_response` and `plan_register` from the
+     * top of `handle()`, ahead of the query/migration permission pipeline, so a
+     * `viewer` could resolve another user's pending manual approval and could
+     * register an arbitrary migration plan for later replay at `auto_upgrade`.
+     */
+    private handleEvent;
+    /**
+     * Handle one inbound frame.
+     *
+     * The frame's `(project, db_alias)` is resolved first and everything after —
+     * every authorization decision, every database call, every audit record —
+     * happens inside the resolved-database context. That ordering is the durable
+     * half of the  fix: the audit sink takes the resolved identity from the
+     * context, so no call site can write the frame's own claim into the record, and
+     * a frame that resolves to nothing is recorded as `unresolved` rather than as
+     * the database it asked for.
+     */
+    handle(msg: AgentMessage): Promise<void>;
+    /**
+     * The fields every audit record for one frame carries.
+     *
+     * Centralised so the asserted identity (`project`, `db_alias_asserted`) is
+     * recorded identically on allows and denials: the resolved identity comes from
+     * the sink's context, and these two come from the frame. A record that names
+     * what the frame claimed and what the agent resolved is the only way a
+     * mismatch like  is visible to anyone reading the trail afterwards.
+     */
+    private auditBase;
+    /** Awaited audit write, or a no-op when no sink is configured. */
+    private auditDeny;
+    private handleResolved;
+    /**
+     * Arm the independent approval watchdog for one request.
+     *
+     * Returns the timer so the caller can clear it. The watchdog fires only if an
+     * approval for THIS request is still outstanding at the handler's reaper
+     * deadline; if the request is merely running a long query, or already finished,
+     * it does nothing. It releases the concurrency permit — `RateLimitPermit`
+     * releases are idempotent, so the ordinary `finally` remains correct — and
+     * records `approval_promise_stranded`, because a stranded promise is exactly
+     * the condition that used to leak a permit per attack and disable the database
+     * for everyone.
+     */
+    private armApprovalWatchdog;
+    /**
+     * `cancel`, bound to the request it names.
+     *
+     * The only gate used to be `hasCapability(role, 'cancel')`, so any developer
+     * could abort any other principal's in-flight query in any project, and the
+     * target's database was resolved from the ATTACKER's project when the target
+     * had none. Two binding conditions are now required on top of the capability:
+     * the caller is the requesting principal, or holds a STRICTLY more privileged
+     * role. The target's database comes from the target's own frame and nowhere
+     * else.
+     */
+    private handleCancel;
+    /**
+     * Map an internal failure to an outbound `error` payload.
+     *
+     * PostgreSQL errors are reduced to an allow-list of fields plus a curated
+     * message per SQLSTATE. `detail` and `hint` are never forwarded: a duplicate
+     * key violation ships `Key (email)=(alice@corp.com) already exists.` in
+     * `detail`, and messages embed the offending SQL and absolute paths.
+     */
+    private mapErrorToPayload;
+}
+interface EventGateDecision {
+    allowed: boolean;
+    errorCode: ErrorCode;
+    reason: string;
+    /** Audit action to record on denial; null when the frame is not an action. */
+    auditAction: AuditAction | null;
+    code: string;
+}
+/**
+ * Decide whether an inbound `event` frame may be handled at all.
+ *
+ * This runs before any event handler. The `event` branch used to sit ahead of
+ * the query/migration permission pipeline, so a `viewer` could resolve another
+ * user's pending manual approval and could register an arbitrary migration
+ * plan for later replay under `auto_upgrade` — the default level. Both kinds
+ * now derive their required capability from the same `hasCapability` matrix
+ * the query path uses, and any kind the agent does not accept inbound is
+ * refused outright.
+ *
+ * `approval_response` requires both `query_write` and `ddl`: an approval can
+ * authorise a write or a DDL statement, so the responder must be able to do
+ * everything it can authorise.
+ */
+export declare function evaluateEventGate(kind: EventKind | undefined, role: Role, permissionLevel: PermissionLevel, canRegisterPlan?: (role: Role, permissionLevel: PermissionLevel) => {
+    allowed: boolean;
+    code?: string;
+    reason?: string;
+}): EventGateDecision;
+export {};
+//# sourceMappingURL=dispatcher.d.ts.map

package/dist/cjs/execution/dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../../src/execution/dispatcher.ts"],"names":[],"mappings":"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"}