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

package/dist/types/execution/sql-parser.d.ts

@@ -0,0 +1,195 @@
+export declare class SqlParserUnavailableError extends Error {
+    constructor(cause?: unknown);
+}
+export declare class SqlParseError extends Error {
+    /** libpg_query error code, e.g. 'syntax_error'. */
+    readonly pgCode: string;
+    /** 1-based cursor position from PostgreSQL, 0 if unknown. */
+    readonly cursorPosition: number;
+    constructor(message: string, pgCode?: string, cursorPosition?: number);
+}
+/** Load the WASM parser. Idempotent and safe to call concurrently. */
+export declare function initSqlParser(): Promise<void>;
+/** True once the WASM module is loaded and parsing is possible. */
+export declare function isSqlParserReady(): boolean;
+/** Throws unless the parser is loaded. Use at the top of any SQL path. */
+export declare function assertParserReady(): void;
+/**
+ * Parse one or more SQL statements into libpg_query raw parse nodes.
+ *
+ * @throws {SqlParserUnavailableError} if the WASM module is not loaded
+ * @throws {SqlParseError} on a PostgreSQL syntax/semantic error
+ */
+export declare function parseSql(sql: string): RawParseResult;
+export interface RawParseResult {
+    version: number;
+    stmts: RawStmt[];
+}
+export interface RawStmt {
+    stmt: Record<string, any>;
+    stmt_location?: number;
+    stmt_len?: number;
+}
+/**
+ * Root node type of a statement (e.g. 'SelectStmt', 'DropStmt').
+ * Returns 'none' for an empty node.
+ */
+export declare function rootNodeType(stmt: RawStmt | undefined): string;
+/**
+ * The root node payload for a statement — i.e. the value of the single root
+ * key, not the `{ NodeName: {...} }` wrapper. Callers that want to walk the
+ * whole tree should use `walkAst(stmt.stmt, …)` instead.
+ */
+export declare function rootNode(stmt: RawStmt | undefined): any;
+/**
+ * Depth-first walk over every node in a parse tree, invoking `visit` on each
+ * node. libpg_query marks nodes two ways depending on level: raw parse trees
+ * wrap each node in a single-key object (e.g. `{ SelectStmt: {...} }`), while
+ * `nodeType`-tagged trees use `{ nodeType: 'SelectStmt' }`. We support both.
+ *
+ * The node name is read from the *key* that holds the child, never from the
+ * child's own keys. A wrapper can sit directly inside a list — e.g.
+ * `fromClause[0].RangeFunction.functions[0].List.items[0].FuncCall` — and a
+ * walk that only recognises a wrapper when it is the sole key of a *nested*
+ * object silently misses every node in that position. That omission is a
+ * security bug here: it made `SELECT * FROM pg_read_file('/etc/passwd') AS
+ * t(contents)` collect zero function names and classify as a read.
+ */
+export declare function walkAst(node: unknown, visit: (type: string, payload: any) => void): void;
+/**
+ * Extract every function name referenced anywhere in the statement, lower-cased
+ * and dot-joined so both `pg_read_file` and `pg_catalog.pg_read_file` are
+ * recognised. PostgreSQL folds unquoted identifiers to lower case; folding
+ * quoted ones too (`"PG_READ_FILE"`) only ever makes the match set larger,
+ * which is the safe direction.
+ */
+export declare function collectFunctionNames(stmt: RawStmt): string[];
+/**
+ * True when the SELECT contains a data-modifying CTE
+ * (`WITH x AS (INSERT …) SELECT …`). PostgreSQL executes those even though the
+ * outer statement is a SELECT.
+ */
+export declare function hasWritableCte(selectNode: any): boolean;
+/** SELECT … INTO <table> creates and populates a table. */
+export declare function getSelectInto(selectNode: any): any | null;
+/** Row-level locking clauses (FOR UPDATE / FOR SHARE / FOR NO KEY UPDATE …). */
+export declare function getLockingClauses(selectNode: any): any[];
+/** Side effects a `SELECT` envelope can carry, anywhere in the statement. */
+export interface ReadSideEffects {
+    /** `SELECT … INTO <table>` creates and populates a table. */
+    selectsInto: boolean;
+    /** Row-level locking clauses: FOR UPDATE / SHARE / NO KEY UPDATE / KEY SHARE. */
+    lockingClauses: any[];
+    /** A data-modifying CTE (`WITH x AS (DELETE …) SELECT …`). */
+    writableCte: boolean;
+}
+/**
+ * Find every read-shaped side effect in a statement.
+ *
+ * This walks *all* `SelectStmt` nodes rather than only the outermost one: a
+ * locking clause or a data-modifying CTE in a sub-select or CTE body takes the
+ * same locks and performs the same writes as one at the top level.
+ */
+export declare function findReadSideEffects(stmt: RawStmt): ReadSideEffects;
+/**
+ * True for `EXPLAIN ANALYZE`, which EXECUTES the statement it explains.
+ *
+ * libpg_query does not expose an `analyze` flag on `ExplainStmt`; the option is
+ * a `DefElem` with `defname: 'analyze'` in the `options` list, so reading a
+ * boolean field (as an earlier version did) always reported false.
+ */
+export declare function explainExecutesStatement(node: any): boolean;
+/**
+ * Root nodes that are session/transaction utilities rather than schema changes.
+ * They still require elevated capability (utility maps to `ddl` in the role
+ * policy) but they are not DDL for audit purposes. Note that PostgreSQL's
+ * ANALYZE also parses as `VacuumStmt`, so it is covered here.
+ */
+export declare const UTILITY_ROOTS: ReadonlySet<string>;
+/** Statements whose root node performs row modifications. */
+export declare const WRITE_ROOTS: ReadonlySet<string>;
+/**
+ * Root nodes that are acceptable as "read only".
+ *
+ * This is an ALLOWLIST, not a denylist. Anything not listed here is not a
+ * read. That is the entire point: adding a new PostgreSQL statement type
+ * cannot accidentally make it readable.
+ */
+export declare const READ_ROOTS: ReadonlySet<string>;
+/**
+ * Root nodes that modify schema, roles, or persistent database state.
+ * Anything not in READ_ROOTS or WRITE_ROOTS and not here is `utility`.
+ */
+export declare const DDL_ROOTS: ReadonlySet<string>;
+/**
+ * Root nodes that cannot run inside a transaction block.
+ * Used by the migration strategy detector, which previously mis-classified
+ * `DROP INDEX CONCURRENTLY` and `ALTER SYSTEM` as transactional.
+ */
+export declare const NON_TRANSACTIONAL_ROOTS: ReadonlySet<string>;
+/** Roots that can execute arbitrary code or reach outside the database. */
+export declare const EXECUTABLE_ROOTS: ReadonlySet<string>;
+/**
+ * Functions that must never be reachable from a statement classified as a
+ * read, because they mutate state, read server files, reach other systems, or
+ * produce a side effect that escapes the transaction.
+ * Matched case-insensitively against the fully-qualified name *and* against
+ * the bare name, so `pg_catalog.pg_read_file` and `pg_read_file` both match.
+ *
+ * This list is NOT a security boundary and must not be presented as one. It is
+ * defence in depth in front of the control that is: every function a statement
+ * references is resolved against `pg_proc` and only `IMMUTABLE`, non-`SECURITY
+ * DEFINER` calls count as a read
+ * (`statement-classifier.ts` → `classifySelect`, `function-effects.ts`). That
+ * control is name-independent, which is what closes the class this list cannot:
+ * an operator's own `SECURITY DEFINER` helper around `pg_read_file`, or any
+ * VOLATILE function that INSERTs, parses as a plain `SELECT` and appears on no
+ * list at all.
+ *
+ * The claim that used to sit here — that a miss "cannot reach the host" because
+ * the connection is read-only — was FALSE. `default_transaction_read_only`
+ * constrains writes to relations and nothing else, and it does not span a
+ * second connection opened inside a function body. A read of a server file, a
+ * `NOTIFY` delivered on commit, an XID allocation, or a `dblink` round trip all
+ * succeed at `read_only`; only the write arm of a VOLATILE function is blocked.
+ * `RECOMMENDED_PG_ROLE` in `src/permissions/role-policy.ts` (the EXECUTE
+ * revokes, plus the default-privileges row that stops them decaying) is what a
+ * miss cannot get past.
+ */
+export declare const DENIED_READ_FUNCTIONS: ReadonlySet<string>;
+/**
+ * Name prefixes denied for the same reason as {@link DENIED_READ_FUNCTIONS}.
+ *
+ * Families are matched on the bare function name so `dblink_fetch_result` and
+ * `postgres_fdw_validator` cannot be used to walk around the explicit list.
+ * Prefix rules are cheaper than enumerating every member of a function family
+ * and cannot be evaded by picking a sibling we forgot to write down.
+ *
+ * `txid_`, `pg_advisory_` and `pg_snapshot_` are here because the families
+ * grow: `pg_advisory_xact_lock_shared` and `txid_current_if_assigned` exist on
+ * some releases and not others.
+ */
+export declare const DENIED_READ_FUNCTION_PREFIXES: readonly string[];
+/**
+ * Name suffixes denied for the same reason as {@link DENIED_READ_FUNCTIONS}.
+ *
+ * A prefix cannot express "every function whose name ends this way", and the
+ * families that matter are named by their suffix: `dblink_exec`,
+ * `dblink_send_query`, `postgres_fdw_disconnect`, `mysql_fdw_connect_u`. They
+ * are matched on the bare function name, exactly as the prefixes are.
+ *
+ * This costs generality, not safety: a function called `x_disconnect` that does
+ * nothing is refused as a read, which is the correct direction for a control
+ * that has to be conservative about names it cannot resolve.
+ */
+export declare const DENIED_READ_FUNCTION_SUFFIXES: readonly string[];
+/** True when a (lower-cased, dot-joined) function name is denied in a read. */
+export declare function isDeniedReadFunction(name: string): boolean;
+/** Every denylisted function a statement references. */
+export declare function findDeniedReadFunction(fnNames: Iterable<string>): string[];
+/**
+ * Node-level transactionality that the root-node set cannot express.
+ * libpg_query uses a `concurrent` boolean on IndexStmt and DropStmt.
+ */
+export declare function isNonTransactionalNode(rootType: string, node: any): boolean;
+//# sourceMappingURL=sql-parser.d.ts.map

package/dist/types/execution/sql-parser.d.ts.map

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

package/dist/types/execution/statement-classifier.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Statement classification, driven by the real PostgreSQL grammar.
+ *
+ * The previous implementation split the SQL on whitespace and looked at the
+ * first token. That is unsound: it classified `SELECT 1; DROP TABLE users` as a
+ * read, and it classified `SELECT * INTO t ...` as a read even though it
+ * creates a table. Both were reachable from the cloud and both executed.
+ *
+ * This implementation parses with libpg_query (WASM) and classifies from the
+ * AST. The guarantee it provides, and its exact limits:
+ *
+ *   - The number of statements is COUNTED by PostgreSQL's own grammar, so
+ *     multi-statement smuggling is structural rather than lexical: a `;` inside
+ *     a string literal, a dollar-quoted body, a quoted identifier or a comment
+ *     cannot split a statement, and a real second statement always is visible.
+ *     `statement_count !== 1` is never a read.
+ *   - Classification is ALLOWLIST-based on the root node: a statement type this
+ *     module does not recognise is `unknown`, which is not a read.
+ *   - `SELECT` is treated as a command envelope, not a read-only assertion.
+ *     `SELECT … INTO`, row-locking clauses, data-modifying CTEs, executable
+ *     blocks and denylisted volatile/privileged functions are detected anywhere
+ *     in the statement and demote it out of `read`.
+ *   - A parse failure and an unavailable parser both FAIL CLOSED: they throw,
+ *     and no lexical heuristic is ever consulted as a fallback. An
+ *     authorization decision must never be made from this module's guesswork.
+ *   - A function reference is a claim that has to be PROVED. Every function the
+ *     statement calls is resolved against `pg_proc` on the caller's connection
+ *     (`function-effects.ts`), and only `provolatile = 'i' AND prosecdef =
+ *     false` counts as a read. A VOLATILE or SECURITY DEFINER function, an
+ *     unknown one, and — deliberately — one the catalogue could not be asked
+ *     about all carry `side_effect` and are never a provable read. With no
+ *     resolver supplied every statement that calls anything is escalated; see
+ *     {@link ClassifyOptions.resolveFunctionEffects}.
+ *
+ * It is still not a substitute for PostgreSQL's own enforcement. The database
+ * is the authority on what a statement does, and the agent's read-only
+ * guarantee is `default_transaction_read_only = on` on the connection — which
+ * constrains WRITES only, and therefore does not constrain a function that
+ * reads a file, notifies a channel, or allocates a transaction id. Those are
+ * why the function-effect analysis above is a control in its own right rather
+ * than an optimisation of the deny-list in `sql-parser.ts`.
+ */
+import { SqlParseError, SqlParserUnavailableError, walkAst } from './sql-parser';
+import type { RawStmt } from './sql-parser';
+import type { FunctionEffectResolver } from './function-effects';
+import type { StatementClassification } from './types';
+/** Reasons a syntactically valid SELECT is still not a safe read. */
+export type ReadViolation = 'selects_into' | 'row_locking' | 'writable_cte' | 'denied_function' | 'side_effect' | 'multiple_statements' | 'executable_block' | 'parse_error' | 'parser_unavailable';
+/**
+ * Violations that mean "this parsed as a read but it is not one".
+ *
+ * A statement carrying any of these is never reported as a provable read, and
+ * the permission layer treats it as a privileged operation rather than a
+ * `query_read`.
+ */
+export declare const READ_ESCAPE_VIOLATIONS: ReadonlySet<ReadViolation>;
+/**
+ * Options for a classification that can consult a database.
+ *
+ * `resolveFunctionEffects` is optional and its absence is meaningful: without
+ * it this module cannot prove any function call is effect-free, so it reports
+ * `side_effect` for every one of them and the statement is escalated. That is
+ * the fail-closed direction, and it is required — the alternative (treating an
+ * absent catalogue verdict as "safe") is the vulnerability being fixed.
+ */
+export interface ClassifyOptions {
+    resolveFunctionEffects?: FunctionEffectResolver;
+}
+export declare class StatementClassificationError extends Error {
+    readonly code: ReadViolation | 'unknown_statement';
+    constructor(message: string, code: ReadViolation | 'unknown_statement');
+}
+/**
+ * Classify a SQL string using the PostgreSQL parser.
+ *
+ * @throws {SqlParserUnavailableError} if the parser has not been initialised
+ * @throws {SqlParseError} if PostgreSQL cannot parse the input
+ */
+export declare function classifyStatement(sql: string, options?: ClassifyOptions): Promise<StatementClassification>;
+/**
+ * Classify a parsed statement list, resolving every function the statements
+ * reference against `pg_proc` in ONE batched read.
+ *
+ * The names of every statement in the list are collected before the lookup, so
+ * a migration plan of twenty statements still costs one catalogue query.
+ */
+export declare function classifyStatements(stmts: RawStmt[], options?: ClassifyOptions): Promise<StatementClassification>;
+/**
+ * Classify using an already-parsed statement list (sync; parser must be ready).
+ *
+ * No catalogue is consulted here, so any statement that calls a function is
+ * escalated. Callers that hold a connection should use {@link classifyStatements}
+ * (or `classifyStatement`) with a resolver instead.
+ */
+export declare function classifyParsedStatements(stmts: RawStmt[]): StatementClassification;
+/**
+ * Classify and throw instead of returning, for call sites that must fail
+ * closed on anything they cannot prove is a read.
+ */
+export declare function assertSingleReadStatement(sql: string, options?: ClassifyOptions): Promise<StatementClassification>;
+export { SqlParseError, SqlParserUnavailableError };
+export { walkAst };
+//# sourceMappingURL=statement-classifier.d.ts.map

package/dist/types/execution/statement-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statement-classifier.d.ts","sourceRoot":"","sources":["../../../src/execution/statement-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,OAAO,EAML,aAAa,EACb,yBAAyB,EASzB,OAAO,EACR,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAgD,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAE/G,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAIvD,qEAAqE;AACrE,MAAM,MAAM,aAAa,GACrB,cAAc,GACd,aAAa,GACb,cAAc,GACd,iBAAiB,GACjB,aAAa,GACb,qBAAqB,GACrB,kBAAkB,GAClB,aAAa,GACb,oBAAoB,CAAC;AAEzB;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,aAAa,CAO5D,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;CACjD;AAKD,qBAAa,4BAA6B,SAAQ,KAAK;aAGnC,IAAI,EAAE,aAAa,GAAG,mBAAmB;gBADzD,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,aAAa,GAAG,mBAAmB;CAK5D;AAgCD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,uBAAuB,CAAC,CAGlC;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,OAAO,EAAE,EAChB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,uBAAuB,CAAC,CASlC;AAgBD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,uBAAuB,CAMlF;AA+YD;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,uBAAuB,CAAC,CA0BlC;AAED,OAAO,EAAE,aAAa,EAAE,yBAAyB,EAAE,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,CAAC"}

package/dist/types/execution/types.d.ts

@@ -0,0 +1,189 @@
+import type { AgentMessage, MigrationStatementStatus } from '../protocol/envelope';
+import type { PoolClient, QueryArrayConfig, QueryArrayResult, QueryConfig } from 'pg';
+import type { FunctionEffectRecord, SideEffectKind } from './function-effects';
+/**
+ * node-postgres selects the **simple** query protocol whenever `values` is
+ * falsy (`pg/lib/query.js` → `requiresPreparation`: `if (!this.values) return
+ * false`), and the simple protocol executes *every* semicolon-separated
+ * statement in one round trip. A payload without `params` therefore reached
+ * PostgreSQL as a multi-command string.
+ *
+ * `queryMode: 'extended'` forces Parse/Bind/Execute. PostgreSQL refuses to
+ * parse more than one command into a single prepared statement, so anything
+ * sent through {@link extendedQuery} reaches the engine as exactly one command
+ * regardless of what the classifier or the protocol validator admitted.
+ * `$1`-style parameters keep working because Bind still carries `values`.
+ *
+ * `queryMode` is not yet declared by `@types/pg`.
+ */
+export type ExtendedQueryConfig = QueryConfig & {
+    queryMode: 'extended';
+};
+export type ExtendedQueryArrayConfig = QueryArrayConfig & {
+    queryMode: 'extended';
+};
+/** Minimal result shape used by the internal session/hardening statements. */
+export interface SimpleResult {
+    rows: unknown[];
+    rowCount: number | null;
+    fields: Array<{
+        name: string;
+        dataTypeID: number;
+    }>;
+}
+/**
+ * Build a query config that is guaranteed to travel over the extended query
+ * protocol. `values` is always an array, so node-postgres never takes the
+ * falsy-`values` shortcut; an empty array means "no bind parameters".
+ */
+export declare function extendedQuery(text: string, values?: readonly unknown[]): ExtendedQueryConfig;
+/** {@link extendedQuery} for `rowMode: 'array'` results. */
+export declare function extendedArrayQuery(text: string, values?: readonly unknown[]): ExtendedQueryArrayConfig;
+/** Run a single statement over the extended protocol. */
+export declare function runExtended(client: PoolClient, text: string, values?: readonly unknown[]): Promise<SimpleResult>;
+/** Run a single statement over the extended protocol, rows as arrays. */
+export declare function runExtendedArray(client: PoolClient, text: string, values?: readonly unknown[]): Promise<QueryArrayResult<unknown[]>>;
+/** Result of classifying a SQL statement. */
+export interface StatementClassification {
+    /** High-level type. Derived from the PostgreSQL parse tree root node. */
+    type: 'read' | 'write' | 'ddl' | 'utility' | 'unknown';
+    /** Specific statement kind (SELECT, DROP TABLE, ALTER ROLE, …). */
+    kind: string;
+    /** Whether this statement can run inside a transaction block. */
+    transactional: boolean;
+    /** Detected statement name (uppercased). */
+    verb: string;
+    /**
+     * How many statements PostgreSQL's parser found in the input. Anything other
+     * than 1 must be rejected: the previous token classifier could not see a
+     * trailing `; DROP TABLE`, and node-postgres executes every statement when
+     * the simple query protocol is used.
+     */
+    statement_count: number;
+    /** False when the input could not be parsed. Callers must fail closed. */
+    parse_ok: boolean;
+    /**
+     * Reasons a syntactically valid SELECT is nonetheless not a safe read:
+     * SELECT INTO creates a table, writable CTEs and FOR UPDATE mutate state,
+     * denylisted functions reach the filesystem, other servers, or session
+     * control, and any function reference the catalogue could not prove
+     * `IMMUTABLE` may do anything the calling role may do. Empty array means the
+     * statement is a provable read.
+     */
+    read_violations: string[];
+    /**
+     * Per-function catalogue verdicts for the statement.
+     *
+     * Optional in the type only, so that a hand-built classification (a test
+     * fixture, an older constructor in another package) still compiles. It is
+     * ALWAYS populated by the classifier, and the permission layer treats an
+     * absent array as UNKNOWN rather than as "no functions were referenced" —
+     * `isProvableRead()` refuses such a classification. Reading it as "empty,
+     * therefore safe" is precisely the bug this field exists to close.
+     */
+    function_effects?: FunctionEffectRecord[];
+    /**
+     * Side effects the statement's function references perform outside the
+     * transaction: notifications, advisory locks, sequence advances, XID
+     * allocation, session mutation, remote I/O.
+     *
+     * Optional for the same reason as {@link StatementClassification.function_effects}
+     * and treated the same way: absent means "not known", which is not safe.
+     */
+    side_effects?: SideEffectKind[];
+}
+/** Tracks one in-flight request. */
+export interface InFlightRequest {
+    request_id: string;
+    db_alias: string;
+    /** PG backend PID for this request. Used by canceller. */
+    pid: number;
+    /** When the request started (epoch ms). */
+    started_at: number;
+    /** The originating message, when the caller supplies it. */
+    message?: AgentMessage;
+    /** Abort controller for cancellation. */
+    abort: AbortController;
+    /** Whether this is a streaming request. */
+    is_streaming: boolean;
+}
+/** Result of a single migration statement execution. */
+export interface StatementResult {
+    index: number;
+    status: MigrationStatementStatus;
+    ms: number;
+    rows_affected: number;
+    error?: string;
+    pg_error_code?: string;
+}
+/** Snapshot of one table's schema. */
+export interface TableSnapshot {
+    schema: string;
+    name: string;
+    type: 'table' | 'view' | 'materialized_view';
+    columns: Array<{
+        name: string;
+        type: string;
+        nullable: boolean;
+        default: string | null;
+        is_primary_key: boolean;
+        is_unique: boolean;
+        is_foreign_key: boolean;
+        foreign_key?: {
+            references_schema: string;
+            references_table: string;
+            references_column: string;
+            on_delete: string | null;
+            on_update: string | null;
+        };
+    }>;
+    indexes: Array<{
+        name: string;
+        columns: string[];
+        is_unique: boolean;
+        is_primary: boolean;
+        definition: string;
+    }>;
+    constraints: Array<{
+        name: string;
+        type: 'CHECK' | 'FOREIGN KEY' | 'UNIQUE' | 'PRIMARY KEY' | 'EXCLUSION';
+        definition: string;
+    }>;
+    triggers: Array<{
+        name: string;
+        event: string;
+        timing: string;
+        function: string;
+    }>;
+    partition_info?: {
+        is_partitioned: boolean;
+        partition_key: string | null;
+        partitions: Array<{
+            name: string;
+            for_values: string;
+        }>;
+    };
+    owner: string;
+    comment: string | null;
+}
+/** Full schema snapshot of a database. */
+export interface SchemaSnapshot {
+    pg_version: string;
+    snapshot_at: number;
+    schemas: string[];
+    tables: TableSnapshot[];
+    extensions: Array<{
+        name: string;
+        version: string;
+        enabled: boolean;
+    }>;
+    size_bytes: number;
+}
+/** Pool manager events. */
+export interface PoolManagerEvents {
+    onPoolOpen?: (dbAlias: string) => void;
+    onPoolClose?: (dbAlias: string, reason: 'idle' | 'explicit' | 'error') => void;
+    onConnectionAcquired?: (dbAlias: string) => void;
+    onConnectionReleased?: (dbAlias: string) => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/execution/types.d.ts.map

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

package/dist/types/index.d.ts

@@ -0,0 +1,34 @@
+export declare const VERSION = "2.0.0";
+export * from './config/machine-config';
+export * from './config/db-config';
+export * from './config/paths';
+export * from './config/token';
+export * from './config/schema';
+export { PROTOCOL_VERSION, DEFAULTS, LIMITS } from './protocol/constants';
+export { AgentMessage, Role, MessageType, EventKind, MigrationStatementStatus, createMessage, } from './protocol/envelope';
+export * from './protocol/messages';
+export { ErrorCode, ErrorMetadata, ERROR_CATALOG, getErrorMetadata, isFatalError, isRetryableError, makeError, } from './protocol/errors';
+export { serialize, deserialize, serializeToBytes, deserializeFromBytes, ProtocolError, } from './protocol/serialize';
+export { validateEnvelope, validatePayload, validateMessage, } from './protocol/validate';
+export { WakeChannel, WakeChannelOptions } from './channels/wake-channel';
+export { DataChannel, DataChannelOptions } from './channels/data-channel';
+export { AgentSession, AgentSessionOptions } from './channels/agent-session';
+export { Backoff, sleep, withJitter } from './channels/reconnect';
+export { WakeChannelState, DataChannelState, DataChannelCloseReason, WakeEvent, AgentSessionState, MessageHandler, StateChangeHandler, } from './channels/types';
+export { PoolManager, PoolError } from './execution/pool';
+export { QueryRunner, QueryTooLargeError, QueryCancelledError, QueryRunContext } from './execution/query-runner';
+export { MigrationRunner, MigrationInProgressError, MigrationContext } from './execution/migration-runner';
+export { Canceller } from './execution/canceller';
+export { Introspector } from './execution/introspection';
+export { Dispatcher, DispatcherOptions } from './execution/dispatcher';
+export { classifyStatement } from './execution/statement-classifier';
+export { detectNonTransactional } from './execution/non-tx-detector';
+export * from './execution/types';
+export { PermissionChecker, PermissionCheckerOptions } from './permissions/checker';
+export { AutoUpgradeChecker, AutoUpgradeOptions } from './permissions/auto-upgrade';
+export { ManualApprovalHandler, ManualApprovalOptions } from './permissions/manual-approval';
+export { PlanRegistry, RegisteredPlan, PlanRegistryOptions } from './permissions/plan-registry';
+export { ROLE_CAPABILITIES, RoleCapability, hasCapability, capabilityForClassification, capabilityForMessageType, } from './permissions/role-policy';
+export { ActionRequest, PermissionDecision, AutoUpgradeResult, ManualApprovalResult, } from './permissions/types';
+export * from './audit';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,UAAU,CAAC;AAG/B,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAGhC,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC1E,OAAO,EACL,YAAY,EACZ,IAAI,EACJ,WAAW,EACX,SAAS,EACT,wBAAwB,EACxB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,OAAO,EACL,SAAS,EACT,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,SAAS,GACV,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,oBAAoB,EACpB,aAAa,GACd,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,SAAS,EACT,iBAAiB,EACjB,cAAc,EACd,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AACjH,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAC3G,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,cAAc,mBAAmB,CAAC;AAGlC,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACpF,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACpF,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAC7F,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAChG,OAAO,EACL,iBAAiB,EAAE,cAAc,EAAE,aAAa,EAChD,2BAA2B,EAAE,wBAAwB,GACtD,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,aAAa,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,oBAAoB,GAC3E,MAAM,qBAAqB,CAAC;AAG7B,cAAc,SAAS,CAAC"}

package/dist/types/permissions/auto-upgrade.d.ts

@@ -0,0 +1,40 @@
+import { ActionRequest, AutoUpgradeResult } from './types';
+import { PlanRegistry } from './plan-registry';
+export interface AutoUpgradeOptions {
+    planRegistry: PlanRegistry;
+}
+export declare class AutoUpgradeChecker {
+    private readonly opts;
+    constructor(opts: AutoUpgradeOptions);
+    /**
+     * Check whether auto-upgrade should be granted.
+     *
+     * Only meaningful when permission_level === 'auto_upgrade'.
+     *
+     * Auto-upgrade is granted only when ALL of the following hold:
+     *   - the effective permission level really is `auto_upgrade`; this checker
+     *     grants nothing at `read_only`, `manual` or `full`, so a caller that
+     *     reaches it on the wrong path is refused rather than trusted
+     *   - the message really is a `migration_run`
+     *   - the role holds `migration_run`
+     *   - a plan id is present and is registered, unexpired, and its statements
+     *     hash matches the statements being submitted
+     *   - the plan's registering principal is bound to this execution: the runner
+     *     is the registrant, or holds a strictly more privileged role, and the
+     *     permission level at execution is at least as permissive as the level the
+     *     plan was registered under
+     *   - every statement parses, is exactly one statement, and is not a read
+     *   - the plan is consumed, so it cannot be replayed
+     *
+     * The last four conditions are decided by ONE synchronous call into the
+     * registry (`consume()`), not by a validate-then-authorise-then-delete
+     * sequence: `consume()` removes the plan in the same tick it grants it, so
+     * no interleaving of two `migration_run` frames can ever be granted twice.
+     *
+     * Without the provenance rules the registry is a self-attesting allow-list:
+     * the same untrusted principal registers the plan and runs it, so a statement
+     * hash match proves nothing at all.
+     */
+    check(req: ActionRequest, statements?: string[]): Promise<AutoUpgradeResult>;
+}
+//# sourceMappingURL=auto-upgrade.d.ts.map

package/dist/types/permissions/auto-upgrade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-upgrade.d.ts","sourceRoot":"","sources":["../../../src/permissions/auto-upgrade.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAsB,MAAM,SAAS,CAAC;AAC/E,OAAO,EAAE,YAAY,EAA2B,MAAM,iBAAiB,CAAC;AAKxE,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,YAAY,CAAC;CAC5B;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;gBAE9B,IAAI,EAAE,kBAAkB;IAIpC;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,KAAK,CAAC,GAAG,EAAE,aAAa,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAoHnF"}

package/dist/types/permissions/checker.d.ts

@@ -0,0 +1,53 @@
+import { ActionRequest, PermissionDecision, PermissionLevel } from './types';
+import { AutoUpgradeChecker } from './auto-upgrade';
+import { ManualApprovalHandler } from './manual-approval';
+import { PlanRegistry } from './plan-registry';
+import type { FunctionEffectResolver } from '../execution/function-effects';
+export { PermissionLevel };
+export interface PermissionCheckerOptions {
+    autoUpgradeChecker: AutoUpgradeChecker;
+    manualApprovalHandler: ManualApprovalHandler;
+    planRegistry: PlanRegistry;
+    /**
+     * Optional default resolver for function-effect analysis.
+     *
+     * When omitted, `check()`'s own `resolveFunctionEffects` argument is used,
+     * and when THAT is omitted too the analysis reports nothing was analysable —
+     * so every statement that calls a function is escalated. Supplying it here
+     * keeps one resolver per database entry rather than one per call.
+     */
+    resolveFunctionEffects?: FunctionEffectResolver;
+}
+export declare class PermissionChecker {
+    readonly opts: PermissionCheckerOptions;
+    constructor(opts: PermissionCheckerOptions);
+    /**
+     * Decide whether a request may proceed. This is the ONLY method the
+     * dispatcher calls.
+     *
+     * Order of checks (all of them must pass):
+     *   0. Parse. A statement we cannot parse is denied, never guessed at. A
+     *      parse error and an unavailable parser are both terminal.
+     *   1. Exactly one statement. Multi-statement execution is refused outright
+     *      because node-postgres uses the simple query protocol when no bind
+     *      parameters are supplied, and the simple protocol runs every
+     *      semicolon-separated statement.
+     *   2. Anti-spoofing. The browser-claimed intent must match the parsed
+     *      classification. No intent value exempts the request from this check;
+     *      `intent: 'migration'` is accepted only on the `migration_run` message
+     *      type and never in place of the comparison.
+     *   3. Role capability for the message type and for the parsed class. A
+     *      classification that is not a *provable* read requires `ddl`.
+     *   4. Permission level.
+     *
+     * @param resolveFunctionEffects Answers "what can this function call do?"
+     *      from `pg_proc` on a live connection. It is an argument, not a global,
+     *      because only the caller knows which database the statement is about —
+     *      and OIDs, and therefore which overloads exist, are per-database. A
+     *      caller that cannot supply one gets `analysed: false`, and every
+     *      statement that calls a function is then escalated rather than
+     *      trusted.
+     */
+    check(req: ActionRequest, statements?: string[], resolveFunctionEffects?: FunctionEffectResolver): Promise<PermissionDecision>;
+}
+//# sourceMappingURL=checker.d.ts.map

package/dist/types/permissions/checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checker.d.ts","sourceRoot":"","sources":["../../../src/permissions/checker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAS7E,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AAI5E,OAAO,EAAE,eAAe,EAAE,CAAC;AAE3B,MAAM,WAAW,wBAAwB;IACvC,kBAAkB,EAAE,kBAAkB,CAAC;IACvC,qBAAqB,EAAE,qBAAqB,CAAC;IAC7C,YAAY,EAAE,YAAY,CAAC;IAC3B;;;;;;;OAOG;IACH,sBAAsB,CAAC,EAAE,sBAAsB,CAAC;CACjD;AAED,qBAAa,iBAAiB;IAC5B,SAAgB,IAAI,EAAE,wBAAwB,CAAC;gBAEnC,IAAI,EAAE,wBAAwB;IAI1C;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,KAAK,CACT,GAAG,EAAE,aAAa,EAClB,UAAU,CAAC,EAAE,MAAM,EAAE,EACrB,sBAAsB,CAAC,EAAE,sBAAsB,GAC9C,OAAO,CAAC,kBAAkB,CAAC;CA0P/B"}