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

package/dist/esm/execution/introspection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspection.d.ts","sourceRoot":"","sources":["../../../src/execution/introspection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAElF,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAGjD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,WAAW,CAAC;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,mBAQxC,CAAC;AAEH,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;gBAE9B,IAAI,EAAE,mBAAmB;IAIrC;;;;;;;;;;;;;;;OAeG;IACG,UAAU,CACd,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,OAAO,EAChB,IAAI,GAAE,IAAe,GACpB,OAAO,CAAC,uBAAuB,CAAC;CAoapC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO5D;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC9B,IAAI,CAwBN"}

package/dist/esm/execution/introspection.js

@@ -0,0 +1,442 @@
+import { extendedQuery } from './types';
+import { introspectionDetailFor } from '../permissions/role-policy';
+/**
+ * Fields dropped at `structure` detail. Listed explicitly (rather than
+ * "delete whatever looks internal") so the reduction is auditable: adding a
+ * column to a snapshot query does not silently become a leak, it has to be added
+ * here deliberately.
+ */
+export const STRUCTURE_ONLY_DROPPED_FIELDS = Object.freeze([
+    'indexes[].definition',
+    'constraints[].definition',
+    'columns[].default',
+    'triggers (entirely)',
+    'owner',
+    'comment',
+    'partition_info[].for_values',
+]);
+export class Introspector {
+    poolManager;
+    constructor(opts) {
+        this.poolManager = opts.poolManager;
+    }
+    /**
+     * Take a schema snapshot.
+     *
+     * `role` is the authenticated envelope's role; it selects the detail level via
+     * `introspectionDetailFor` in permissions/role-policy.ts. It defaults to
+     * `structure` rather than `full`, so a caller that forgets to pass it cannot
+     * leak the full schema — the reverse of the usual default would be fail-open.
+     *
+     * Every catalogue query below goes out through `extendedQuery`, so it travels
+     * over the extended query protocol: node-postgres takes the simple protocol
+     * whenever `values` is falsy, and that protocol executes every
+     * semicolon-separated statement in one round trip. The SQL here is
+     * agent-authored and carries no caller-supplied text, but pinning it means a
+     * future edit cannot quietly turn one catalogue query into a multi-command
+     * string.
+     */
+    async introspect(payload, dbEntry, role = 'viewer') {
+        const detail = introspectionDetailFor(role);
+        const full = detail === 'full';
+        const { client, release } = await this.poolManager.acquire(dbEntry);
+        try {
+            // 1. Version
+            const versionRes = await client.query(extendedQuery('SELECT version();'));
+            const pg_version = versionRes.rows[0]?.version || 'unknown';
+            // Honour `pg_version_hint` (audit L-08). It used to be type-checked by
+            // `validateIntrospectPayload` and then never read, which is a contract
+            // lie: a caller was free to ask for a "12.0" snapshot and receive the live
+            // server's schema, labelled as though it answered the question.
+            //
+            // It is treated as an assertion about which server the caller means, not as
+            // a request to rewrite the catalogue. A declared major version that does
+            // not match the connected server fails the request closed: the snapshot
+            // would describe a database the caller did not ask about, and silently
+            // serving it is exactly the confusion the field invited.
+            assertVersionHintMatches(pg_version, payload.pg_version_hint);
+            // 2. Schemas
+            const schemasRes = await client.query(extendedQuery(`
+        SELECT schema_name FROM information_schema.schemata
+        WHERE schema_name NOT LIKE 'pg_%' AND schema_name != 'information_schema'
+        ORDER BY schema_name;
+      `));
+            const schemas = schemasRes.rows.map((r) => r.schema_name);
+            // 3. Tables & Views
+            const tablesRes = await client.query(extendedQuery(`
+        SELECT
+          t.table_schema, t.table_name,
+          CASE
+            WHEN t.table_type = 'BASE TABLE' THEN 'table'
+            WHEN t.table_type = 'VIEW' THEN 'view'
+          END as type,
+          ${full
+                ? `pg_catalog.obj_description(c.oid) as comment,
+          pg_catalog.pg_get_userbyid(c.relowner) as owner`
+                : `NULL::text as comment,
+          NULL::text as owner`}
+        FROM information_schema.tables t
+        JOIN pg_catalog.pg_class c ON c.relname = t.table_name
+        JOIN pg_catalog.pg_namespace n ON n.oid = c.relnamespace AND n.nspname = t.table_schema
+        WHERE t.table_schema NOT LIKE 'pg_%' AND t.table_schema != 'information_schema'
+        ORDER BY t.table_schema, t.table_name;
+      `));
+            let matViewsRows = [];
+            if (payload.include_views !== false) {
+                const matViewsRes = await client.query(extendedQuery(`
+          SELECT schemaname as table_schema, matviewname as table_name, 'materialized_view' as type
+          FROM pg_catalog.pg_matviews
+          WHERE schemaname NOT LIKE 'pg_%'
+          ORDER BY schemaname, matviewname;
+        `));
+                matViewsRows = matViewsRes.rows;
+            }
+            // Populate TableSnapshots
+            const tablesMap = new Map();
+            const tablesList = [];
+            for (const row of tablesRes.rows) {
+                if (payload.include_views === false && row.type === 'view') {
+                    continue;
+                }
+                const key = `${row.table_schema}.${row.table_name}`;
+                const tableSnap = {
+                    schema: row.table_schema,
+                    name: row.table_name,
+                    type: row.type || 'table',
+                    columns: [],
+                    indexes: [],
+                    constraints: [],
+                    triggers: [],
+                    owner: full ? row.owner || '' : '',
+                    comment: full ? row.comment || null : null,
+                };
+                tablesMap.set(key, tableSnap);
+                tablesList.push(tableSnap);
+            }
+            for (const row of matViewsRows) {
+                const key = `${row.table_schema}.${row.table_name}`;
+                const tableSnap = {
+                    schema: row.table_schema,
+                    name: row.table_name,
+                    type: 'materialized_view',
+                    columns: [],
+                    indexes: [],
+                    constraints: [],
+                    triggers: [],
+                    owner: '',
+                    comment: null,
+                };
+                tablesMap.set(key, tableSnap);
+                tablesList.push(tableSnap);
+            }
+            // 4. Columns
+            const columnsRes = await client.query(extendedQuery(`
+        SELECT
+          c.table_schema, c.table_name, c.column_name,
+          c.data_type, c.udt_name, c.is_nullable, c.column_default,
+          c.character_maximum_length, c.numeric_precision, c.numeric_scale,
+          c.ordinal_position
+        FROM information_schema.columns c
+        WHERE c.table_schema NOT LIKE 'pg_%' AND c.table_schema != 'information_schema'
+        ORDER BY c.table_schema, c.table_name, c.ordinal_position;
+      `));
+            for (const row of columnsRes.rows) {
+                const key = `${row.table_schema}.${row.table_name}`;
+                const table = tablesMap.get(key);
+                if (!table)
+                    continue;
+                table.columns.push({
+                    name: row.column_name,
+                    type: row.udt_name || row.data_type,
+                    nullable: row.is_nullable === 'YES',
+                    default: full ? row.column_default || null : null,
+                    is_primary_key: false,
+                    is_unique: false,
+                    is_foreign_key: false,
+                });
+            }
+            // 5. PK / Uniques
+            const constraintsRes = await client.query(extendedQuery(`
+        SELECT
+          tc.table_schema, tc.table_name, tc.constraint_name, tc.constraint_type,
+          string_agg(kcu.column_name, ',' ORDER BY kcu.ordinal_position) as columns
+        FROM information_schema.table_constraints tc
+        JOIN information_schema.key_column_usage kcu
+          ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+        WHERE tc.constraint_type IN ('PRIMARY KEY', 'UNIQUE')
+          AND tc.table_schema NOT LIKE 'pg_%'
+        GROUP BY tc.table_schema, tc.table_name, tc.constraint_name, tc.constraint_type;
+      `));
+            for (const row of constraintsRes.rows) {
+                const key = `${row.table_schema}.${row.table_name}`;
+                const table = tablesMap.get(key);
+                if (!table)
+                    continue;
+                const cols = (row.columns || '').split(',');
+                if (row.constraint_type === 'PRIMARY KEY') {
+                    for (const colName of cols) {
+                        const col = table.columns.find((c) => c.name === colName);
+                        if (col)
+                            col.is_primary_key = true;
+                    }
+                }
+                else if (row.constraint_type === 'UNIQUE') {
+                    for (const colName of cols) {
+                        const col = table.columns.find((c) => c.name === colName);
+                        if (col)
+                            col.is_unique = true;
+                    }
+                }
+            }
+            // 6. Foreign keys
+            const fksRes = await client.query(extendedQuery(`
+        SELECT
+          tc.table_schema, tc.table_name, kcu.column_name,
+          ccu.table_schema AS references_schema, ccu.table_name AS references_table, ccu.column_name AS references_column,
+          rc.delete_rule AS on_delete, rc.update_rule AS on_update,
+          tc.constraint_name
+        FROM information_schema.table_constraints tc
+        JOIN information_schema.key_column_usage kcu ON tc.constraint_name = kcu.constraint_name
+        JOIN information_schema.referential_constraints rc ON tc.constraint_name = rc.constraint_name
+        JOIN information_schema.constraint_column_usage ccu ON rc.unique_constraint_name = ccu.constraint_name
+        WHERE tc.constraint_type = 'FOREIGN KEY'
+          AND tc.table_schema NOT LIKE 'pg_%';
+      `));
+            for (const row of fksRes.rows) {
+                const key = `${row.table_schema}.${row.table_name}`;
+                const table = tablesMap.get(key);
+                if (!table)
+                    continue;
+                const col = table.columns.find((c) => c.name === row.column_name);
+                if (col) {
+                    col.is_foreign_key = true;
+                    col.foreign_key = {
+                        references_schema: row.references_schema,
+                        references_table: row.references_table,
+                        references_column: row.references_column,
+                        on_delete: row.on_delete || null,
+                        on_update: row.on_update || null,
+                    };
+                }
+            }
+            // 7. Indexes
+            if (payload.include_indexes !== false) {
+                const indexesRes = await client.query(extendedQuery(`
+          SELECT
+            schemaname, tablename, indexname, indexdef
+          FROM pg_catalog.pg_indexes
+          WHERE schemaname NOT LIKE 'pg_%'
+          ORDER BY schemaname, tablename, indexname;
+        `));
+                for (const row of indexesRes.rows) {
+                    const key = `${row.schemaname}.${row.tablename}`;
+                    const table = tablesMap.get(key);
+                    if (!table)
+                        continue;
+                    const isUnique = row.indexdef.toUpperCase().includes('UNIQUE');
+                    const isPrimary = row.indexdef.toUpperCase().includes('PRIMARY KEY') || row.indexname.endsWith('_pkey');
+                    let cols = [];
+                    const match = row.indexdef.match(/\((.*)\)$/);
+                    if (match) {
+                        cols = match[1].split(',').map((c) => c.trim().replace(/"/g, ''));
+                    }
+                    table.indexes.push({
+                        name: row.indexname,
+                        columns: cols,
+                        is_unique: isUnique,
+                        is_primary: isPrimary,
+                        // The index body is the DDL text; it is not part of the data model
+                        // a read-only user needs, so `structure` omits it. The name,
+                        // columns and uniqueness survive, which is what a schema browser
+                        // shows.
+                        definition: full ? row.indexdef : '',
+                    });
+                }
+            }
+            // 8. Check constraints
+            const checksRes = await client.query(extendedQuery(`
+        SELECT
+          tc.table_schema, tc.table_name, tc.constraint_name,
+          cc.check_clause
+        FROM information_schema.table_constraints tc
+        JOIN information_schema.check_constraints cc ON tc.constraint_name = cc.constraint_name
+        WHERE tc.constraint_type = 'CHECK'
+          AND tc.table_schema NOT LIKE 'pg_%';
+      `));
+            for (const row of checksRes.rows) {
+                const key = `${row.table_schema}.${row.table_name}`;
+                const table = tablesMap.get(key);
+                if (!table)
+                    continue;
+                table.constraints.push({
+                    name: row.constraint_name,
+                    type: 'CHECK',
+                    // The check clause IS the validation rule. `structure` keeps the
+                    // constraint's existence and name, not the expression.
+                    definition: full ? row.check_clause : '',
+                });
+            }
+            // 9. Triggers
+            //
+            // Trigger metadata is dropped entirely at `structure`: `action_statement`
+            // is the trigger function's source, which for an audit trigger is the
+            // table's own change history in PL/pgSQL. The query is not even issued for
+            // a reduced snapshot, so the data does not exist in this process to leak.
+            if (full && payload.include_triggers !== false) {
+                const triggersRes = await client.query(extendedQuery(`
+          SELECT
+            event_object_schema, event_object_table, trigger_name,
+            event_manipulation, action_timing, action_statement
+          FROM information_schema.triggers
+          WHERE event_object_schema NOT LIKE 'pg_%'
+          ORDER BY event_object_schema, event_object_table, trigger_name;
+        `));
+                for (const row of triggersRes.rows) {
+                    const key = `${row.event_object_schema}.${row.event_object_table}`;
+                    const table = tablesMap.get(key);
+                    if (!table)
+                        continue;
+                    table.triggers.push({
+                        name: row.trigger_name,
+                        event: row.event_manipulation,
+                        timing: row.action_timing,
+                        function: row.action_statement,
+                    });
+                }
+            }
+            // 10. Extensions
+            let extensions = [];
+            if (payload.include_extensions !== false) {
+                const extensionsRes = await client.query(extendedQuery(`
+          SELECT extname, extversion
+          FROM pg_catalog.pg_extension
+          WHERE extname NOT LIKE 'pg_%';
+        `));
+                extensions = extensionsRes.rows.map((row) => ({
+                    name: row.extname,
+                    version: row.extversion,
+                    enabled: true,
+                }));
+            }
+            // 11. Partitions
+            if (payload.include_partitions !== false) {
+                const partitionsRes = await client.query(extendedQuery(`
+          SELECT
+            parent.relname AS parent_table,
+            parent_n.nspname AS parent_schema,
+            child.relname AS child_table,
+            pg_get_expr(child.relpartbound, child.oid) AS for_values
+          FROM pg_catalog.pg_inherits inh
+          JOIN pg_catalog.pg_class parent ON inh.inhparent = parent.oid
+          JOIN pg_catalog.pg_class child ON inh.inhrelid = child.oid
+          JOIN pg_catalog.pg_namespace parent_n ON parent.relnamespace = parent_n.oid
+          WHERE parent_n.nspname NOT LIKE 'pg_%';
+        `));
+                for (const row of partitionsRes.rows) {
+                    const parentKey = `${row.parent_schema}.${row.parent_table}`;
+                    const parentTable = tablesMap.get(parentKey);
+                    if (parentTable) {
+                        if (!parentTable.partition_info) {
+                            parentTable.partition_info = {
+                                is_partitioned: true,
+                                partition_key: null,
+                                partitions: [],
+                            };
+                        }
+                        parentTable.partition_info.partitions.push({
+                            name: row.child_table,
+                            // The partition bound is the row-range predicate; not part of the
+                            // relation structure.
+                            for_values: full ? row.for_values || '' : '',
+                        });
+                    }
+                }
+            }
+            // The database's on-disk size, reported under its own name.
+            //
+            // Audit M-30: this used to be `Buffer.byteLength(JSON.stringify(snapshot))`
+            // under the field `size_bytes`, i.e. the size of the JSON *response* filed
+            // as the size of the *database*. `pg_database_size` is the real value. It
+            // can fail on a hardened server that revokes EXECUTE from it, in which case
+            // the field is `null` — an honest "unknown" rather than a plausible-looking
+            // number that means something else.
+            let databaseSizeBytes = null;
+            try {
+                const sizeRes = await client.query(extendedQuery('SELECT pg_database_size(current_database()) AS bytes;'));
+                const bytes = sizeRes.rows[0]?.bytes;
+                databaseSizeBytes = typeof bytes === 'number' && Number.isFinite(bytes) ? bytes : null;
+            }
+            catch (err) {
+                console.warn('Introspector: could not read pg_database_size; reporting size_bytes as null rather ' +
+                    `than substituting a different measurement: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            const snapshot = {
+                pg_version,
+                snapshot_at: Date.now(),
+                schemas,
+                tables: tablesList,
+                extensions,
+                size_bytes: databaseSizeBytes ?? 0,
+            };
+            return {
+                pg_version: snapshot.pg_version,
+                snapshot_at: snapshot.snapshot_at,
+                schema: {
+                    tables: snapshot.tables,
+                },
+                extensions: snapshot.extensions,
+                schemas: snapshot.schemas,
+                size_bytes: databaseSizeBytes,
+                snapshot_json_bytes: Buffer.byteLength(JSON.stringify(snapshot), 'utf8'),
+                detail,
+            };
+        }
+        finally {
+            release();
+        }
+    }
+}
+/**
+ * Major version from a PostgreSQL version string.
+ *
+ * `SELECT version()` returns e.g. `PostgreSQL 16.2 (Debian 16.2-1.pgdg120+1) on
+ * x86_64-pc-linux-gnu`, and a caller-supplied hint may be `16`, `16.2` or the
+ * same string. Only the leading `major.minor` is meaningful for compatibility,
+ * so the major is what is compared.
+ */
+export function parseMajorVersion(raw) {
+    const match = /(\d+)(?:\.\d+)?/.exec(raw);
+    if (!match) {
+        return null;
+    }
+    const major = Number(match[1]);
+    return Number.isInteger(major) && major > 0 ? major : null;
+}
+/**
+ * Fail closed when the caller's declared server version is not the server we are
+ * connected to. An absent hint (`null`/blank) imposes no expectation.
+ *
+ * Throws a plain `Error`; the dispatcher converts it into an error frame, so the
+ * caller learns that no snapshot was taken rather than receiving one that
+ * answers a question it did not ask.
+ */
+export function assertVersionHintMatches(serverVersion, hint) {
+    if (hint === null || hint === undefined || hint.trim() === '') {
+        return;
+    }
+    const declared = parseMajorVersion(hint);
+    if (declared === null) {
+        throw new Error(`pg_version_hint "${hint}" is not a PostgreSQL version; refusing to snapshot a server the ` +
+            'caller could not have meant.');
+    }
+    const actual = parseMajorVersion(serverVersion);
+    if (actual === null) {
+        throw new Error(`Could not determine the connected server's major version from ${JSON.stringify(serverVersion)}, ` +
+            `so the declared hint "${hint}" cannot be verified. Refusing rather than assuming a match.`);
+    }
+    if (declared !== actual) {
+        throw new Error(`pg_version_hint declares PostgreSQL ${declared} but this database is PostgreSQL ${actual}. ` +
+            'The snapshot would describe a different server, so the request was refused.');
+    }
+}
+//# sourceMappingURL=introspection.js.map

package/dist/esm/execution/introspection.js.map

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

package/dist/esm/execution/migration-runner.d.ts

@@ -0,0 +1,128 @@
+import { PoolManager } from './pool';
+import { DbEntry } from '../config/db-config';
+import { MigrationRunPayload, MigrationResultPayload } from '../protocol/messages';
+import { InFlightRequest } from './types';
+import { AgentMessage, Role } from '../protocol/envelope';
+export declare class MigrationInProgressError extends Error {
+    /** Error catalog code. Not a SQLSTATE: `safePgCode` requires exactly 5. */
+    readonly code = "migration_in_progress";
+    constructor(message: string);
+}
+export declare class MigrationStrategyConflictError extends Error {
+    readonly code = "migration_strategy_conflict";
+    constructor(message: string);
+}
+/**
+ * The plan could not be verified: something in it does not parse, contains
+ * more than one statement, or is a statement form the agent cannot prove runs
+ * inside a transaction block. The run is refused rather than guessed at.
+ */
+export declare class MigrationPlanUnsafeError extends Error {
+    readonly code = "migration_plan_unsafe";
+    constructor(message: string);
+}
+/**
+ * The migration stopped partway with statements already committed.
+ *
+ * `MigrationRunner.run` never *resolves* with `status: 'partial'`: a caller
+ * that only inspects a returned value can therefore never mistake a
+ * half-applied schema for a success. The per-statement detail is on
+ * {@link MigrationPartiallyAppliedError.result} for a caller that wants to
+ * report it.
+ */
+export declare class MigrationPartiallyAppliedError extends Error {
+    readonly code = "migration_partial";
+    readonly result: MigrationResultPayload;
+    readonly pg_error_code?: string;
+    constructor(message: string, result: MigrationResultPayload);
+}
+/** The run exceeded its overall deadline and was abandoned. */
+export declare class MigrationTimeoutError extends Error {
+    readonly code = "migration_timeout";
+    constructor(message: string);
+}
+/**
+ * Absolute ceiling on one migration statement, in milliseconds. A caller
+ * cannot raise it, and it can never exceed the agent-wide statement ceiling in
+ * `pool.ts` — nothing is allowed to turn `statement_timeout` off.
+ */
+export declare const MAX_MIGRATION_STATEMENT_TIMEOUT_MS: number;
+/** Absolute ceiling on the whole migration run, in milliseconds. */
+export declare const MAX_MIGRATION_DEADLINE_MS: 1800000;
+/** How long a migration statement may wait for a lock before it is cancelled. */
+export declare const MIGRATION_LOCK_TIMEOUT_MS = 10000;
+export interface MigrationBudget {
+    /** `statement_timeout` applied to every statement of the run. */
+    statementTimeoutMs: number;
+    /** Wall-clock budget for the whole run, enforced by the runner. */
+    deadlineMs: number;
+    /** `lock_timeout` applied to every statement of the run. */
+    lockTimeoutMs: number;
+}
+/**
+ * Turn a caller-supplied `timeout_ms` into the three server-side budgets.
+ *
+ * The number is never trusted: it is floored to an integer, and clamped to
+ * {@link MAX_MIGRATION_STATEMENT_TIMEOUT_MS} / {@link MAX_MIGRATION_DEADLINE_MS}.
+ * `0`, a negative number, `NaN` and `Infinity` all mean "use the server
+ * default" — never "no timeout", which is how a remote caller would otherwise
+ * be able to remove the ceiling by asking for zero.
+ */
+export declare function resolveMigrationBudget(requestedTimeoutMs?: number): MigrationBudget;
+export interface MigrationRunnerOptions {
+    poolManager: PoolManager;
+    /**
+     * Per-installation secret the advisory lock key is derived from. Defaults to
+     * the agent token in the machine config, which is generated once per install
+     * and never leaves the host.
+     */
+    lockSecret?: string;
+}
+export interface MigrationContext {
+    dbEntry: DbEntry;
+    request_id: string;
+    project: string;
+    user: {
+        id: string;
+        role: Role;
+    };
+    db_alias: string;
+    /** Called for each statement status change. */
+    onProgress?: (event: AgentMessage) => void | Promise<void>;
+    abortSignal?: AbortSignal;
+    registerInFlight?: (req: InFlightRequest) => void;
+    unregisterInFlight?: (request_id: string) => void;
+}
+/**
+ * Advisory lock key for SW migrations.
+ *
+ * Keyed with HMAC-SHA256 over a per-installation secret. The previous version
+ * hashed the project name with a bare MD5, so anybody who could guess (or was
+ * told) a project name could compute the lock key, take the lock from another
+ * session, and deny migrations for that project indefinitely. A keyed MAC is
+ * not derivable by a third party with database access, because the secret never
+ * reaches the database.
+ */
+export declare function advisoryLockKey(projectName: string, secret: string): {
+    key1: number;
+    key2: number;
+};
+export declare class MigrationRunner {
+    private readonly poolManager;
+    private readonly injectedLockSecret?;
+    private resolvedLockSecret;
+    constructor(opts: MigrationRunnerOptions);
+    /**
+     * The installation secret the lock key is keyed with.
+     *
+     * An explicit option wins (tests, embedders). Otherwise the agent token from
+     * the machine config is used: it is per-installation, secret, and stable
+     * across processes, which is exactly what mutual exclusion between two agents
+     * needs. If the machine config cannot be read the fallback is a random
+     * per-process secret — still unguessable from outside, so the lock key cannot
+     * be pre-taken by anyone with database access.
+     */
+    private lockSecret;
+    run(payload: MigrationRunPayload, ctx: MigrationContext): Promise<MigrationResultPayload>;
+}
+//# sourceMappingURL=migration-runner.d.ts.map

package/dist/esm/execution/migration-runner.d.ts.map

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