@stigmer/server 3.14.0-dev.20260910084630

package/dist/store/postgres/store.js

@@ -0,0 +1,873 @@
+/**
+ * Postgres driver — implements the Store contract over node-postgres
+ * (DD-010), method-for-method against sqlite/store.ts so the two drivers
+ * stay contract-twins: same typed errors, same full-scan find* semantics
+ * (shared scanners in ../proto-fields.ts), same ledger string formats.
+ * Selected at boot when DATABASE_URL is set (boot/config.ts precedence).
+ *
+ * Concurrency model (DD-010, the recorded semantic widening): atomicity is
+ * per-resource, not global. updateResource runs
+ * BEGIN → SELECT ... FOR UPDATE → modify() → UPDATE → COMMIT on one pooled
+ * connection — the synchronous `modify` contract (interface.ts) means no
+ * caller I/O can ever hold the row lock open. Concurrent writes to
+ * DIFFERENT resources may interleave; sqlite's incidental global write
+ * serialization is deliberately NOT emulated (rejected alternative in
+ * DD-010 — an advisory lock around every write would discard the
+ * concurrency a team-scale database exists to provide).
+ *
+ * Other write contracts and their mechanisms here:
+ * - first-writer-wins event appends: one multi-row INSERT ON CONFLICT DO
+ *   NOTHING, rowCount = the true inserted count;
+ * - fire-identity schedule-run upserts: ON CONFLICT DO UPDATE guarded by
+ *   completed_at = '' (terminal rows immutable);
+ * - single-holder audit tags: two UPDATEs in one transaction, missing
+ *   target rolls back (the #341 head-repoint contract);
+ * - at-most-once OAuth state redemption: DELETE ... RETURNING (atomic
+ *   without an explicit transaction).
+ *
+ * BIGINT/COUNT results arrive from pg as strings (precision posture);
+ * every numeric read is explicitly Number()-converted at the row mapping.
+ *
+ * Proven by the shared store contract suite (../__tests__/store-contract.ts)
+ * under TEST_DATABASE_URL, __tests__/ (migrations, tsquery, driver
+ * physicals), and end-to-end by the conformance suites on local-postgres /
+ * local-postgres-execution (DD-011).
+ */
+import { fromBinary, toBinary } from "@bufbuild/protobuf";
+import pg from "pg";
+import { AuditNotFoundError, DELIVERED_SIGNAL_DEDUPE_TTL_MS, PENDING_OAUTH_STATE_TTL_MS, ResourceNotFoundError, } from "../interface.js";
+import { NOOP_STORE_LOGGER } from "../logger.js";
+import { apiResourceKindName, filterRowsByLabel, scanForFieldMatch, } from "../proto-fields.js";
+import { rfc3339Seconds } from "../rfc3339.js";
+import { runMigrations } from "./migrations.js";
+import { normalizeTsRankScore, renderTsQueryExpression } from "./tsquery.js";
+/**
+ * The text search config every query-side to_tsquery call must name —
+ * it MUST match the config baked into the migration's generated tsvector
+ * (a mismatched config searches a differently-stemmed document and
+ * silently returns wrong membership).
+ */
+const TEXT_SEARCH_CONFIG = "english";
+export class PostgresStore {
+    bootstrapState;
+    signalDedupe;
+    oauthGrants;
+    pendingOAuthStates;
+    pool;
+    logger;
+    constructor(pool, logger) {
+        this.pool = pool;
+        this.logger = logger;
+        this.bootstrapState = new PostgresBootstrapStateStore(() => this.open());
+        this.signalDedupe = new PostgresSignalDedupeStore(() => this.open(), logger);
+        this.oauthGrants = new PostgresOAuthGrantStore(() => this.open());
+        this.pendingOAuthStates = new PostgresPendingOAuthStateStore(() => this.open());
+    }
+    /**
+     * Connects to databaseUrl, runs migrations (advisory-locked, so
+     * concurrent boots serialize), and returns the ready store. Any failure
+     * here is a loud boot throw — never a degraded server (the same posture
+     * as SqliteStore.open; the composition root does not catch it).
+     */
+    static async open(databaseUrl, logger = NOOP_STORE_LOGGER) {
+        const pool = new pg.Pool({ connectionString: databaseUrl });
+        // An idle pooled connection dropping (server restart, network blip)
+        // emits 'error' on the pool; without a listener that is a process
+        // crash. The next query checks out a fresh connection, so warn-only.
+        pool.on("error", (error) => {
+            logger.warn("postgres pool idle-connection error", {
+                error: error.message,
+            });
+        });
+        // Migrations run on a dedicated client: pg_advisory_lock is
+        // session-scoped, so lock and unlock must ride the same connection.
+        const client = await pool.connect();
+        try {
+            await runMigrations(client);
+        }
+        catch (error) {
+            client.release();
+            await pool.end();
+            throw error;
+        }
+        client.release();
+        return new PostgresStore(pool, logger);
+    }
+    // ---------------------------------------------------------------------------
+    // Resource operations
+    // ---------------------------------------------------------------------------
+    async saveResource(kind, id, schema, msg) {
+        const data = toBinary(schema, msg);
+        await this.open().query(`INSERT INTO resources (kind, id, data, updated_at) VALUES ($1, $2, $3, now())
+       ON CONFLICT (kind, id) DO UPDATE SET data = excluded.data, updated_at = now()`, [apiResourceKindName(kind), id, Buffer.from(data)]);
+    }
+    async getResource(kind, id, schema) {
+        const kindName = apiResourceKindName(kind);
+        const result = await this.open().query(`SELECT data FROM resources WHERE kind = $1 AND id = $2`, [kindName, id]);
+        const row = result.rows[0];
+        if (row === undefined) {
+            throw new ResourceNotFoundError(`${kindName}/${id}`);
+        }
+        return fromBinary(schema, row.data);
+    }
+    async updateResource(kind, id, schema, modify) {
+        const kindName = apiResourceKindName(kind);
+        // FOR UPDATE locks exactly this row for the transaction — the DD-010
+        // per-resource atomicity contract. `modify` is synchronous by contract
+        // (interface.ts), so no caller I/O can extend the lock's hold time.
+        return this.withTransaction(async (client) => {
+            const result = await client.query(`SELECT data FROM resources WHERE kind = $1 AND id = $2 FOR UPDATE`, [kindName, id]);
+            const row = result.rows[0];
+            if (row === undefined) {
+                throw new ResourceNotFoundError(`${kindName}/${id}`);
+            }
+            const msg = fromBinary(schema, row.data);
+            modify(msg);
+            const data = toBinary(schema, msg);
+            await client.query(`UPDATE resources SET data = $3, updated_at = now() WHERE kind = $1 AND id = $2`, [kindName, id, Buffer.from(data)]);
+            return msg;
+        });
+    }
+    async listResources(kind) {
+        const result = await this.open().query(`SELECT data FROM resources WHERE kind = $1`, [apiResourceKindName(kind)]);
+        return result.rows.map((row) => row.data);
+    }
+    async deleteResource(kind, id) {
+        await this.open().query(`DELETE FROM resources WHERE kind = $1 AND id = $2`, [apiResourceKindName(kind), id]);
+    }
+    async findByField(kind, fieldPath, value, schema) {
+        const kindName = apiResourceKindName(kind);
+        const rows = await this.listResources(kind);
+        const match = scanForFieldMatch(rows, schema, fieldPath, value);
+        if (match === undefined) {
+            throw new ResourceNotFoundError(`${kindName} where ${fieldPath}=${value}`);
+        }
+        return match;
+    }
+    async findAllByField(kind, fieldPath, value) {
+        // Go-parity quirk preserved (interface.ts doc; both drivers mirror it):
+        // returns ALL rows of the kind, unfiltered. The parameters are kept so
+        // the signature stays surface-identical.
+        void fieldPath;
+        void value;
+        return this.listResources(kind);
+    }
+    async findAllByLabel(kind, labelKey, labelValue, schema) {
+        const rows = await this.listResources(kind);
+        return filterRowsByLabel(rows, schema, labelKey, labelValue);
+    }
+    async findResourcesRawOrderedAfter(kind, afterIdExclusive, limit) {
+        if (limit <= 0) {
+            throw new Error(`limit must be positive, got ${limit}`);
+        }
+        // Keyset pagination over the (kind, id) primary key — stable under
+        // concurrent writes (the interface's maintenance-surface contract).
+        const result = await this.open().query(`SELECT id, data FROM resources WHERE kind = $1 AND id > $2 ORDER BY id LIMIT $3`, [apiResourceKindName(kind), afterIdExclusive, limit]);
+        return result.rows;
+    }
+    async replaceResourceDataIfUnchanged(kind, id, expectedData, newData) {
+        // BYTEA equality in the WHERE clause makes the compare-and-swap one
+        // atomic statement: zero rows changed means the row moved on (or was
+        // deleted) since the read — a lost swap, never an upsert.
+        const result = await this.open().query(`UPDATE resources SET data = $1, updated_at = now() WHERE kind = $2 AND id = $3 AND data = $4`, [
+            Buffer.from(newData),
+            apiResourceKindName(kind),
+            id,
+            Buffer.from(expectedData),
+        ]);
+        return result.rowCount === 1;
+    }
+    async deleteResourcesByKind(kind) {
+        const result = await this.open().query(`DELETE FROM resources WHERE kind = $1`, [apiResourceKindName(kind)]);
+        return result.rowCount ?? 0;
+    }
+    async deleteResourcesByIdPrefix(kind, idPrefix) {
+        // LIKE with the wildcard characters of the PREFIX escaped — sqlite's
+        // GLOB has no LIKE-metacharacter hazard, this port must not either.
+        const result = await this.open().query(`DELETE FROM resources WHERE kind = $1 AND id LIKE $2 ESCAPE '\\'`, [apiResourceKindName(kind), `${escapeLikePattern(idPrefix)}%`]);
+        return result.rowCount ?? 0;
+    }
+    // ---------------------------------------------------------------------------
+    // Audit operations
+    // ---------------------------------------------------------------------------
+    async saveAudit(kind, resourceId, schema, msg, versionHash, tag) {
+        const data = toBinary(schema, msg);
+        await this.open().query(`INSERT INTO resource_audit (kind, resource_id, data, version_hash, tag, archived_at)
+       VALUES ($1, $2, $3, $4, $5, now())`, [
+            apiResourceKindName(kind),
+            resourceId,
+            Buffer.from(data),
+            versionHash,
+            tag,
+        ]);
+    }
+    async getAuditByHash(kind, resourceId, versionHash, schema) {
+        const record = await this.getAuditRecordByHash(kind, resourceId, versionHash);
+        return fromBinary(schema, record.data);
+    }
+    async getAuditByTag(kind, resourceId, tag, schema) {
+        const record = await this.getAuditRecordByTag(kind, resourceId, tag);
+        return fromBinary(schema, record.data);
+    }
+    async listAuditHistory(kind, resourceId) {
+        const records = await this.listAuditRecords(kind, resourceId);
+        return records.map((record) => record.data);
+    }
+    async deleteAuditByResourceId(kind, resourceId) {
+        const result = await this.open().query(`DELETE FROM resource_audit WHERE kind = $1 AND resource_id = $2`, [apiResourceKindName(kind), resourceId]);
+        return result.rowCount ?? 0;
+    }
+    async countAuditEntries(kind, resourceId) {
+        const result = await this.open().query(`SELECT COUNT(*) AS count FROM resource_audit WHERE kind = $1 AND resource_id = $2`, [apiResourceKindName(kind), resourceId]);
+        return Number(result.rows[0].count);
+    }
+    async getLatestAuditHash(kind, resourceId) {
+        const kindName = apiResourceKindName(kind);
+        // id DESC breaks archived_at ties from sub-timestamp inserts — the
+        // same recency contract as sqlite's rowid tie-break.
+        const result = await this.open().query(`SELECT version_hash FROM resource_audit
+       WHERE kind = $1 AND resource_id = $2
+       ORDER BY archived_at DESC, id DESC
+       LIMIT 1`, [kindName, resourceId]);
+        const row = result.rows[0];
+        if (row === undefined) {
+            throw new AuditNotFoundError(`${kindName}/${resourceId}`);
+        }
+        return row.version_hash ?? "";
+    }
+    async setAuditTag(kind, resourceId, versionHash, tag) {
+        const kindName = apiResourceKindName(kind);
+        // Single transaction: clear the prior holder, assign the target. A
+        // missing target rolls back, leaving the prior holder untouched — the
+        // #341 head-repoint contract.
+        await this.withTransaction(async (client) => {
+            await client.query(`UPDATE resource_audit SET tag = ''
+         WHERE kind = $1 AND resource_id = $2 AND tag = $3`, [kindName, resourceId, tag]);
+            const result = await client.query(`UPDATE resource_audit SET tag = $1
+         WHERE kind = $2 AND resource_id = $3 AND version_hash = $4`, [tag, kindName, resourceId, versionHash]);
+            if ((result.rowCount ?? 0) === 0) {
+                throw new AuditNotFoundError(`${kindName}/${resourceId} (hash=${versionHash})`);
+            }
+        });
+    }
+    async listAuditRecords(kind, resourceId) {
+        const result = await this.open().query(`SELECT data, version_hash, tag FROM resource_audit
+       WHERE kind = $1 AND resource_id = $2
+       ORDER BY archived_at DESC, id DESC`, [apiResourceKindName(kind), resourceId]);
+        return result.rows.map((row) => ({
+            data: row.data,
+            versionHash: row.version_hash ?? "",
+            tag: row.tag ?? "",
+        }));
+    }
+    async getAuditRecordByHash(kind, resourceId, versionHash) {
+        const kindName = apiResourceKindName(kind);
+        // Duplicates for one hash are legal — newest wins (stigmer-cloud#191).
+        const result = await this.open().query(`SELECT data, tag FROM resource_audit
+       WHERE kind = $1 AND resource_id = $2 AND version_hash = $3
+       ORDER BY archived_at DESC, id DESC
+       LIMIT 1`, [kindName, resourceId, versionHash]);
+        const row = result.rows[0];
+        if (row === undefined) {
+            throw new AuditNotFoundError(`${kindName}/${resourceId} (hash=${versionHash})`);
+        }
+        return { data: row.data, versionHash, tag: row.tag ?? "" };
+    }
+    async getAuditRecordByTag(kind, resourceId, tag) {
+        const kindName = apiResourceKindName(kind);
+        const result = await this.open().query(`SELECT data, version_hash FROM resource_audit
+       WHERE kind = $1 AND resource_id = $2 AND tag = $3
+       ORDER BY archived_at DESC, id DESC
+       LIMIT 1`, [kindName, resourceId, tag]);
+        const row = result.rows[0];
+        if (row === undefined) {
+            throw new AuditNotFoundError(`${kindName}/${resourceId} (tag=${tag})`);
+        }
+        return { data: row.data, versionHash: row.version_hash ?? "", tag };
+    }
+    // ---------------------------------------------------------------------------
+    // Workflow execution events
+    // ---------------------------------------------------------------------------
+    async appendWorkflowExecutionEvents(executionId, events) {
+        if (events.length === 0) {
+            return 0;
+        }
+        // One multi-row INSERT: atomic without an explicit transaction, and
+        // ON CONFLICT DO NOTHING makes rowCount the true first-writer-wins
+        // inserted count (oss#308).
+        const values = [];
+        const tuples = [];
+        for (const [i, event] of events.entries()) {
+            const base = i * 5;
+            tuples.push(`($${base + 1}, $${base + 2}, $${base + 3}, $${base + 4}, $${base + 5})`);
+            values.push(executionId, event.sequenceNumber, event.eventType, event.taskName, Buffer.from(event.data));
+        }
+        const result = await this.open().query(`INSERT INTO workflow_execution_events (execution_id, sequence_number, event_type, task_name, data)
+       VALUES ${tuples.join(", ")}
+       ON CONFLICT (execution_id, sequence_number) DO NOTHING`, values);
+        return result.rowCount ?? 0;
+    }
+    async getWorkflowExecutionEvents(executionId, afterSequence, eventType, taskName, limit) {
+        const effectiveLimit = limit <= 0 ? 100 : limit;
+        let query = `SELECT execution_id, sequence_number, event_type, task_name, data, created_at
+      FROM workflow_execution_events
+      WHERE execution_id = $1 AND sequence_number > $2`;
+        const args = [executionId, afterSequence];
+        if (eventType !== "") {
+            args.push(eventType);
+            query += ` AND event_type = $${args.length}`;
+        }
+        if (taskName !== "") {
+            args.push(taskName);
+            query += ` AND task_name = $${args.length}`;
+        }
+        args.push(effectiveLimit);
+        query += ` ORDER BY sequence_number ASC LIMIT $${args.length}`;
+        const result = await this.open().query(query, args);
+        return result.rows.map((row) => ({
+            executionId: row.execution_id,
+            sequenceNumber: Number(row.sequence_number),
+            eventType: row.event_type,
+            taskName: row.task_name,
+            data: row.data,
+            createdAt: row.created_at,
+        }));
+    }
+    async getMaxEventSequence(executionId) {
+        const result = await this.open().query(`SELECT COALESCE(MAX(sequence_number), 0) AS max_seq FROM workflow_execution_events WHERE execution_id = $1`, [executionId]);
+        return Number(result.rows[0].max_seq);
+    }
+    // ---------------------------------------------------------------------------
+    // Schedule runs (fire ledger)
+    // ---------------------------------------------------------------------------
+    async upsertScheduleRun(record) {
+        // Default recorded_at is RFC-3339 whole seconds (Go time.RFC3339) —
+        // the ledger's house convention for lexicographic comparison.
+        const recordedAt = record.recordedAt !== "" ? record.recordedAt : rfc3339Seconds(new Date());
+        // The ON CONFLICT WHERE guard is the terminal-immutability contract:
+        // rows with a completed_at never get downgraded by a replayed write.
+        await this.open().query(`INSERT INTO schedule_runs
+        (schedule_id, org, nominal_fire_time, origin, outcome, reason, execution_id, recorded_at, completed_at)
+      VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+      ON CONFLICT (schedule_id, nominal_fire_time, origin) DO UPDATE SET
+        outcome = excluded.outcome,
+        reason = excluded.reason,
+        execution_id = excluded.execution_id,
+        completed_at = excluded.completed_at
+      WHERE schedule_runs.completed_at = ''`, [
+            record.scheduleId,
+            record.org,
+            record.nominalFireTime,
+            record.origin,
+            record.outcome,
+            record.reason,
+            record.executionId,
+            recordedAt,
+            record.completedAt,
+        ]);
+    }
+    async markLatestScheduleRunTerminal(scheduleId, origin, outcome, reason, completedAt) {
+        await this.open().query(`UPDATE schedule_runs SET outcome = $1, reason = $2, completed_at = $3
+       WHERE schedule_id = $4 AND origin = $5 AND completed_at = ''
+       AND nominal_fire_time = (
+         SELECT MAX(nominal_fire_time) FROM schedule_runs
+         WHERE schedule_id = $4 AND origin = $5 AND completed_at = ''
+       )`, [outcome, reason, completedAt, scheduleId, origin]);
+    }
+    async listScheduleRuns(scheduleId, offset, limit) {
+        const effectiveLimit = limit <= 0 ? 50 : limit;
+        const effectiveOffset = offset < 0 ? 0 : offset;
+        const totalResult = await this.open().query(`SELECT COUNT(*) AS total FROM schedule_runs WHERE schedule_id = $1`, [scheduleId]);
+        const result = await this.open().query(`SELECT schedule_id, org, nominal_fire_time, origin, outcome, reason, execution_id, recorded_at, completed_at
+       FROM schedule_runs
+       WHERE schedule_id = $1
+       ORDER BY nominal_fire_time DESC, origin DESC
+       LIMIT $2 OFFSET $3`, [scheduleId, effectiveLimit, effectiveOffset]);
+        return {
+            total: Number(totalResult.rows[0].total),
+            runs: result.rows.map((row) => ({
+                scheduleId: row.schedule_id,
+                org: row.org,
+                nominalFireTime: row.nominal_fire_time,
+                origin: row.origin,
+                outcome: row.outcome,
+                reason: row.reason,
+                executionId: row.execution_id,
+                recordedAt: row.recorded_at,
+                completedAt: row.completed_at,
+            })),
+        };
+    }
+    async deleteScheduleRunsBySchedule(scheduleId) {
+        const result = await this.open().query(`DELETE FROM schedule_runs WHERE schedule_id = $1`, [scheduleId]);
+        return result.rowCount ?? 0;
+    }
+    async pruneScheduleRuns(recordedBefore) {
+        const result = await this.open().query(`DELETE FROM schedule_runs WHERE recorded_at < $1`, [recordedBefore]);
+        return result.rowCount ?? 0;
+    }
+    // ---------------------------------------------------------------------------
+    // Search index (tsvector/tsquery — DD-009's Postgres rendering)
+    // ---------------------------------------------------------------------------
+    async upsertSearchIndex(kind, resourceId, entry) {
+        const kindName = apiResourceKindName(kind);
+        // DELETE + INSERT in one transaction, not ON CONFLICT DO UPDATE: a
+        // re-upserted row must take a fresh `seq`, keeping the list-mode
+        // tie-break "newest write last-wins" — the same recency semantics the
+        // sqlite driver gets from FTS5's delete+insert rowid.
+        await this.withTransaction(async (client) => {
+            await client.query(`DELETE FROM search_index WHERE kind = $1 AND resource_id = $2`, [kindName, resourceId]);
+            await client.query(`INSERT INTO search_index (kind, resource_id, name, description, tags, org, visibility, created_at)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`, [
+                kindName,
+                resourceId,
+                entry.name,
+                entry.description,
+                entry.tags,
+                entry.org,
+                entry.visibility,
+                entry.createdAt,
+            ]);
+        });
+    }
+    async deleteSearchIndex(kind, resourceId) {
+        await this.open().query(`DELETE FROM search_index WHERE kind = $1 AND resource_id = $2`, [apiResourceKindName(kind), resourceId]);
+    }
+    async querySearchIndex(query) {
+        // Search mode is "terms present", even when they sanitize to an empty
+        // tsquery expression — to_tsquery's rejection of that expression is
+        // the preserved behavior for such queries (see tsquery.ts; the FTS5
+        // driver fails the same way on an empty MATCH).
+        const searchMode = query.terms !== undefined;
+        const args = [];
+        const push = (value) => {
+            args.push(value);
+            return `$${args.length}`;
+        };
+        let matchClause = "";
+        if (query.terms !== undefined) {
+            const param = push(renderTsQueryExpression(query.terms));
+            matchClause = `search @@ to_tsquery('${TEXT_SEARCH_CONFIG}', ${param}) AND `;
+        }
+        // `::text[]` is load-bearing: node-pg serializes a JS array as a
+        // Postgres array literal, but ANY() without the cast can fail to
+        // infer the element type ("op ANY/ALL (array) requires array on
+        // right side").
+        const kindParam = `${push(query.kinds)}::text[]`;
+        // The scope-filter fragments — same composition as the sqlite driver's
+        // port of Go's buildScopeFilter: org (strict or public-widened) and
+        // the independent public subtraction.
+        const scopeClauses = [];
+        if (query.orgFilter !== "") {
+            const orgParam = push(query.orgFilter);
+            scopeClauses.push(query.crossOrgPublic
+                ? `AND (org = ${orgParam} OR visibility = 'visibility_public')`
+                : `AND org = ${orgParam}`);
+        }
+        if (query.excludePublic) {
+            scopeClauses.push(`AND visibility != 'visibility_public'`);
+        }
+        if (query.authorizedIdsByKind !== undefined) {
+            // The 20260830.01 scoping arm: per-kind resource_id allowlists.
+            // An empty set contributes NO clause — that kind matches nothing —
+            // and all-kinds-empty renders a constant-false predicate (never an
+            // `IN ()` accident, per the interface contract).
+            const kindClauses = [];
+            for (const kind of query.kinds) {
+                const ids = query.authorizedIdsByKind.get(kind);
+                if (ids === undefined) {
+                    kindClauses.push(`kind = ${push(kind)}`);
+                }
+                else if (ids.size > 0) {
+                    const idsParam = `${push([...ids])}::text[]`;
+                    kindClauses.push(`(kind = ${push(kind)} AND resource_id = ANY(${idsParam}))`);
+                }
+            }
+            scopeClauses.push(kindClauses.length === 0
+                ? `AND FALSE`
+                : `AND (${kindClauses.join(" OR ")})`);
+        }
+        const scopeSql = scopeClauses.join("\n        ");
+        // Statement 1 — full counts per kind (zero-count kinds never appear:
+        // the counts come from GROUP BY over matches).
+        const countResult = await this.open().query(`SELECT kind, COUNT(*) AS cnt
+       FROM search_index
+       WHERE ${matchClause}kind = ANY(${kindParam})
+       ${scopeSql}
+       GROUP BY kind`, args);
+        const countsByKind = {};
+        let totalCount = 0;
+        for (const row of countResult.rows) {
+            const cnt = Number(row.cnt);
+            countsByKind[row.kind] = cnt;
+            totalCount += cnt;
+        }
+        // Count short-circuit before the page statement (contract-twin of the
+        // sqlite driver's port of Go's EmptyResult).
+        if (totalCount === 0) {
+            return { countsByKind: {}, totalCount: 0, hits: [] };
+        }
+        // Statement 2 — the ranked page. Search mode: ts_rank over the
+        // weighted document, higher = better, with explicit (kind,
+        // resource_id) tie-breaks for the within-driver determinism DD-009
+        // requires. List mode: score pinned exactly 1.0, newest first with the
+        // seq tie-break (created_at is whole seconds — see migrations.ts).
+        const limitParam = push(query.limit);
+        const offsetParam = push(query.offset);
+        const pageSql = searchMode
+            ? `SELECT kind, resource_id, ts_rank(search, to_tsquery('${TEXT_SEARCH_CONFIG}', $1)) AS rank
+         FROM search_index
+         WHERE search @@ to_tsquery('${TEXT_SEARCH_CONFIG}', $1) AND kind = ANY(${kindParam})
+         ${scopeSql}
+         ORDER BY rank DESC, kind ASC, resource_id ASC
+         LIMIT ${limitParam} OFFSET ${offsetParam}`
+            : `SELECT kind, resource_id, 1.0 AS rank
+         FROM search_index
+         WHERE kind = ANY(${kindParam})
+         ${scopeSql}
+         ORDER BY created_at DESC, seq DESC
+         LIMIT ${limitParam} OFFSET ${offsetParam}`;
+        const pageResult = await this.open().query(pageSql, args);
+        // The interface promises wire-ready scores: normalize ts_rank here;
+        // list mode's score is pinned exactly 1.0 (P1 DD-001 — the driver
+        // returns the wire score).
+        const hits = pageResult.rows.map((row) => ({
+            kind: row.kind,
+            resourceId: row.resource_id,
+            score: searchMode ? normalizeTsRankScore(Number(row.rank)) : 1.0,
+        }));
+        return { countsByKind, totalCount, hits };
+    }
+    async clearSearchIndex() {
+        await this.open().query(`DELETE FROM search_index`);
+    }
+    // ---------------------------------------------------------------------------
+    // Lifecycle
+    // ---------------------------------------------------------------------------
+    async close() {
+        if (this.pool === undefined) {
+            return; // already closed
+        }
+        const pool = this.pool;
+        this.pool = undefined;
+        await pool.end();
+    }
+    /** Live pool or the contract's "store is closed" error (both drivers). */
+    open() {
+        if (this.pool === undefined) {
+            throw new Error("store is closed");
+        }
+        return this.pool;
+    }
+    /**
+     * BEGIN/COMMIT/ROLLBACK on one checked-out client — pg pools route each
+     * query to any idle connection, so multi-statement transactions must pin
+     * one. The rollback error (connection already broken) never masks the
+     * original failure.
+     */
+    async withTransaction(fn) {
+        const client = await this.open().connect();
+        try {
+            await client.query("BEGIN");
+            const result = await fn(client);
+            await client.query("COMMIT");
+            return result;
+        }
+        catch (error) {
+            try {
+                await client.query("ROLLBACK");
+            }
+            catch (rollbackError) {
+                this.logger.warn("postgres transaction rollback failed", {
+                    error: String(rollbackError),
+                });
+            }
+            throw error;
+        }
+        finally {
+            client.release();
+        }
+    }
+}
+// =============================================================================
+// Bootstrap state
+// =============================================================================
+class PostgresBootstrapStateStore {
+    open;
+    constructor(open) {
+        this.open = open;
+    }
+    async get(key) {
+        const result = await this.open().query(`SELECT value FROM bootstrap_state WHERE key = $1`, [key]);
+        const row = result.rows[0];
+        // Missing key → "" and NOT an error — the cross-driver contract.
+        return row?.value ?? "";
+    }
+    async set(key, value) {
+        await this.open().query(`INSERT INTO bootstrap_state (key, value, updated_at) VALUES ($1, $2, now())
+       ON CONFLICT (key) DO UPDATE SET value = excluded.value, updated_at = now()`, [key, value]);
+    }
+    async getAll() {
+        const result = await this.open().query(`SELECT key, value FROM bootstrap_state`);
+        return new Map(result.rows.map((row) => [
+            row.key,
+            row.value,
+        ]));
+    }
+    async delete(key) {
+        await this.open().query(`DELETE FROM bootstrap_state WHERE key = $1`, [
+            key,
+        ]);
+    }
+    async clear() {
+        await this.open().query(`DELETE FROM bootstrap_state`);
+    }
+}
+// =============================================================================
+// Signal dedupe
+// =============================================================================
+class PostgresSignalDedupeStore {
+    open;
+    logger;
+    constructor(open, logger) {
+        this.open = open;
+        this.logger = logger;
+    }
+    async claim(org, idempotencyKey, executionId, signalName, ttlMs) {
+        const pool = this.open();
+        const id = buildDedupeKey(org, idempotencyKey);
+        const now = new Date();
+        const createdAt = now.toISOString();
+        const expiresAt = new Date(now.getTime() + ttlMs).toISOString();
+        // Expired rows are cleaned before claiming so keys become reusable —
+        // failure is non-critical (warn and continue), the cross-driver
+        // contract.
+        try {
+            await pool.query(`DELETE FROM signal_dedupe WHERE expires_at < $1`, [
+                now.toISOString(),
+            ]);
+        }
+        catch (error) {
+            this.logger.warn("failed to cleanup expired dedupe records", {
+                error: String(error),
+            });
+        }
+        // ON CONFLICT DO NOTHING instead of catch-the-unique-violation: same
+        // first-claimer-wins outcome, no error-text sniffing.
+        const result = await pool.query(`INSERT INTO signal_dedupe (id, org, idempotency_key, execution_id, signal_name, status, created_at, expires_at)
+       VALUES ($1, $2, $3, $4, $5, 'CLAIMED', $6, $7)
+       ON CONFLICT (id) DO NOTHING`, [id, org, idempotencyKey, executionId, signalName, createdAt, expiresAt]);
+        if ((result.rowCount ?? 0) === 1) {
+            return { status: "SUCCESS" };
+        }
+        const record = await this.loadRecord(pool, id);
+        if (record === undefined) {
+            // The holder vanished between INSERT and SELECT — surface as a
+            // claim failure rather than fabricating a record.
+            throw new Error(`load existing record: ${id} disappeared`);
+        }
+        return { status: "DUPLICATE", record };
+    }
+    async markDelivered(org, idempotencyKey) {
+        const id = buildDedupeKey(org, idempotencyKey);
+        const now = new Date();
+        // Extending expires_at here is the load-bearing half of the two-phase
+        // hold: delivery earns DELIVERED_SIGNAL_DEDUPE_TTL_MS. The status guard
+        // makes re-marking a no-op and keeps a takeover's fresh claim intact.
+        const result = await this.open().query(`UPDATE signal_dedupe
+       SET status = 'DELIVERED', delivered_at = $1, expires_at = $2
+       WHERE id = $3 AND status = 'CLAIMED'`, [
+            now.toISOString(),
+            new Date(now.getTime() + DELIVERED_SIGNAL_DEDUPE_TTL_MS).toISOString(),
+            id,
+        ]);
+        if ((result.rowCount ?? 0) === 0) {
+            this.logger.warn("no dedupe record updated - may be already delivered or doesn't exist", { id });
+        }
+    }
+    async release(org, idempotencyKey) {
+        const id = buildDedupeKey(org, idempotencyKey);
+        // Status-guarded DELETE: only an in-flight claim can be freed, so a
+        // release racing markDelivered can never unblock a delivered key.
+        await this.open().query(`DELETE FROM signal_dedupe WHERE id = $1 AND status = 'CLAIMED'`, [id]);
+    }
+    async loadRecord(pool, id) {
+        const result = await pool.query(`SELECT id, org, idempotency_key, execution_id, signal_name, status, created_at, delivered_at, expires_at
+       FROM signal_dedupe WHERE id = $1`, [id]);
+        const row = result.rows[0];
+        if (row === undefined) {
+            return undefined;
+        }
+        return {
+            id: row.id,
+            org: row.org,
+            idempotencyKey: row.idempotency_key,
+            executionId: row.execution_id,
+            signalName: row.signal_name,
+            status: row.status,
+            createdAt: row.created_at,
+            deliveredAt: row.delivered_at ?? "",
+            expiresAt: row.expires_at,
+        };
+    }
+}
+/** Composite dedupe key: "{org}:{idempotency_key}" (both drivers). */
+function buildDedupeKey(org, idempotencyKey) {
+    return `${org}:${idempotencyKey}`;
+}
+// =============================================================================
+// MCP OAuth grants
+// =============================================================================
+class PostgresOAuthGrantStore {
+    open;
+    constructor(open) {
+        this.open = open;
+    }
+    async upsert(grant) {
+        const now = Math.floor(Date.now() / 1000);
+        const createdAt = grant.createdAt !== 0 ? grant.createdAt : now;
+        await this.open().query(`INSERT INTO oauth_grant (
+        identity_account_id, resource_id, resource_kind, org_id,
+        access_token_expires_at, client_id, auth_method, token_endpoint,
+        access_token_env_var, refresh_token_env_var, environment_id,
+        created_at, updated_at
+      ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)
+      ON CONFLICT (identity_account_id, resource_id, org_id) DO UPDATE SET
+        resource_kind = excluded.resource_kind,
+        access_token_expires_at = excluded.access_token_expires_at,
+        client_id = excluded.client_id,
+        auth_method = excluded.auth_method,
+        token_endpoint = excluded.token_endpoint,
+        access_token_env_var = excluded.access_token_env_var,
+        refresh_token_env_var = excluded.refresh_token_env_var,
+        environment_id = excluded.environment_id,
+        updated_at = excluded.updated_at`, [
+            grant.identityAccountId,
+            grant.resourceId,
+            grant.resourceKind,
+            grant.orgId,
+            grant.accessTokenExpiresAt,
+            grant.clientId,
+            grant.authMethod,
+            grant.tokenEndpoint,
+            grant.accessTokenEnvVar,
+            grant.refreshTokenEnvVar,
+            grant.environmentId,
+            createdAt,
+            now,
+        ]);
+    }
+    async find(identityAccountId, resourceId, orgId) {
+        const result = await this.open().query(`SELECT identity_account_id, resource_id, resource_kind, org_id,
+        access_token_expires_at, client_id, auth_method, token_endpoint,
+        access_token_env_var, refresh_token_env_var, environment_id,
+        created_at, updated_at
+       FROM oauth_grant
+       WHERE identity_account_id = $1 AND resource_id = $2 AND org_id = $3`, [identityAccountId, resourceId, orgId]);
+        const row = result.rows[0];
+        if (row === undefined) {
+            return undefined; // no grant is a normal state, not an error
+        }
+        return {
+            identityAccountId: row.identity_account_id,
+            resourceId: row.resource_id,
+            resourceKind: row.resource_kind,
+            orgId: row.org_id,
+            accessTokenExpiresAt: Number(row.access_token_expires_at),
+            clientId: row.client_id,
+            authMethod: row.auth_method,
+            tokenEndpoint: row.token_endpoint,
+            accessTokenEnvVar: row.access_token_env_var,
+            refreshTokenEnvVar: row.refresh_token_env_var,
+            environmentId: row.environment_id,
+            createdAt: Number(row.created_at),
+            updatedAt: Number(row.updated_at),
+        };
+    }
+    async delete(identityAccountId, resourceId, orgId) {
+        await this.open().query(`DELETE FROM oauth_grant
+       WHERE identity_account_id = $1 AND resource_id = $2 AND org_id = $3`, [identityAccountId, resourceId, orgId]);
+    }
+    async deleteByResourceId(resourceId, orgId) {
+        const result = await this.open().query(`DELETE FROM oauth_grant
+       WHERE resource_id = $1 AND org_id = $2`, [resourceId, orgId]);
+        return result.rowCount ?? 0;
+    }
+}
+// =============================================================================
+// MCP pending OAuth state
+// =============================================================================
+class PostgresPendingOAuthStateStore {
+    open;
+    constructor(open) {
+        this.open = open;
+    }
+    async save(state) {
+        const createdAt = state.createdAt !== 0 ? state.createdAt : Math.floor(Date.now() / 1000);
+        await this.open().query(`INSERT INTO pending_oauth_state (
+        state, code_verifier, client_id, client_secret, token_endpoint,
+        mcp_server_id, identity_account_id, target_env_var, auth_method,
+        token_auth_method, redirect_uri, org, created_at
+      ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13)`, [
+            state.state,
+            state.codeVerifier,
+            state.clientId,
+            state.clientSecret,
+            state.tokenEndpoint,
+            state.mcpServerId,
+            state.identityAccountId,
+            state.targetEnvVar,
+            state.authMethod,
+            state.tokenAuthMethod,
+            state.redirectUri,
+            state.org,
+            createdAt,
+        ]);
+    }
+    async getAndDelete(stateParam) {
+        // DELETE ... RETURNING is the at-most-once redemption in one atomic
+        // statement — the same contract sqlite implements as a read+delete
+        // transaction.
+        const result = await this.open().query(`DELETE FROM pending_oauth_state WHERE state = $1
+       RETURNING state, code_verifier, client_id, client_secret, token_endpoint,
+         mcp_server_id, identity_account_id, target_env_var, auth_method,
+         token_auth_method, redirect_uri, org, created_at`, [stateParam]);
+        const row = result.rows[0];
+        if (row === undefined) {
+            return undefined;
+        }
+        const createdAt = Number(row.created_at);
+        const ageMs = Date.now() - createdAt * 1000;
+        if (ageMs > PENDING_OAUTH_STATE_TTL_MS) {
+            return undefined; // expired: deleted on the way out, never redeemed
+        }
+        return {
+            state: row.state,
+            codeVerifier: row.code_verifier,
+            clientId: row.client_id,
+            clientSecret: row.client_secret,
+            tokenEndpoint: row.token_endpoint,
+            mcpServerId: row.mcp_server_id,
+            identityAccountId: row.identity_account_id,
+            targetEnvVar: row.target_env_var,
+            authMethod: row.auth_method,
+            tokenAuthMethod: row.token_auth_method,
+            redirectUri: row.redirect_uri,
+            org: row.org,
+            createdAt,
+        };
+    }
+    async cleanupExpired() {
+        const cutoff = Math.floor(Date.now() / 1000) - PENDING_OAUTH_STATE_TTL_MS / 1000;
+        const result = await this.open().query(`DELETE FROM pending_oauth_state WHERE created_at < $1`, [cutoff]);
+        return result.rowCount ?? 0;
+    }
+}
+/** Escapes LIKE metacharacters so a prefix matches literally. */
+function escapeLikePattern(value) {
+    return value
+        .replaceAll("\\", "\\\\")
+        .replaceAll("%", "\\%")
+        .replaceAll("_", "\\_");
+}
+//# sourceMappingURL=store.js.map