melchizedek-agents 0.9.6 → 0.16.0

package/dist/lib/storage/postgres/index.js

@@ -0,0 +1,146 @@
+/**
+ * lib/storage/postgres/index.ts — every durable store on one Postgres
+ * connection (ADR 0021).
+ *
+ *   const storage = postgresStorage({ connectionString: process.env.DATABASE_URL });
+ *   createA2AApp({ ..., storage });
+ *
+ * Works on any Postgres with pgvector: Supabase through its connection
+ * string, RDS, Cloud SQL, AlloyDB, on-premises. Apply the schema first
+ * (`npm run db -- apply`, db/migrations/). With this storage plugged in, A2A
+ * tasks and conversations are shared by every instance, so the server can run
+ * more than one.
+ */
+import pg from 'pg';
+import { SupabaseVectorMemoryService } from '../../memory/supabaseMemoryService.js';
+import { ERASE_STORES } from '../../memory/erase.js';
+import { postgresMemoryStore } from './memoryStore.js';
+import { PostgresSessionService } from './sessionService.js';
+import { PostgresTaskStore, reapExpiredTasks, renewTaskLeases } from './taskStore.js';
+import { postgresTaskBackend } from './taskQueue.js';
+import { searchPathOption } from '../schema.js';
+import { createHash, randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+export { PostgresSessionService } from './sessionService.js';
+export { PostgresTaskStore } from './taskStore.js';
+export { postgresMemoryStore } from './memoryStore.js';
+/**
+ * A pool emits 'error' when an idle connection dies (a database restart, a
+ * failover, an administrator's terminate); unhandled, that event crashes the
+ * process. The pool drops the dead client and opens a fresh one on the next
+ * query, so the right response is to log it and carry on.
+ */
+function survivesIdleErrors(p, label) {
+    p.on('error', (err) => console.warn(`[storage] ${label}: an idle Postgres connection failed (${err.message}); it will be replaced.`));
+    return p;
+}
+/**
+ * The advisory-lock id for a turn-lock key: the first 64 bits of its SHA-256,
+ * signed. Hashed here rather than with Postgres' hashtext, because a key is
+ * joined with NUL separators (lib/a2a/turnLock.ts) and Postgres text cannot
+ * hold a NUL byte. The same key gives the same id on every instance.
+ */
+export function advisoryLockId(key) {
+    return BigInt.asIntN(64, BigInt(`0x${createHash('sha256').update(key).digest('hex').slice(0, 16)}`)).toString();
+}
+export function postgresStorage(options) {
+    const owned = !options.pool;
+    const pool = options.pool ??
+        survivesIdleErrors(new pg.Pool({
+            connectionString: options.connectionString,
+            ...options.poolConfig,
+            ...(searchPathOption(options.schema ?? 'public') ? { options: searchPathOption(options.schema ?? 'public') } : {}),
+        }), 'pool');
+    if (!options.pool && !options.connectionString && !options.poolConfig?.host) {
+        throw new Error('postgresStorage needs a connectionString (e.g. DATABASE_URL) or a pool');
+    }
+    const sessionService = new PostgresSessionService(pool, { ttlDays: options.ttlDays });
+    const lease = { instanceId: `${hostname()}:${process.pid}:${randomUUID().slice(0, 8)}`, ttlMs: options.taskLeaseMs ?? 60_000 };
+    const memoryService = options.memory
+        ? new SupabaseVectorMemoryService({ apiKey: options.memory.apiKey ?? '', extractor: options.memory.extractor, embedder: options.memory.embedder }, postgresMemoryStore(pool))
+        : undefined;
+    // Turn locks hold a connection for a whole turn: their own small pool.
+    let lockPool;
+    const locks = () => (lockPool ??= survivesIdleErrors(new pg.Pool({
+        ...(options.pool ? options.pool.options : { connectionString: options.connectionString, ...options.poolConfig }),
+        max: options.lockPoolMax ?? 20,
+    }), 'turn-lock pool'));
+    const turnLock = async (key, { waitMs, signal }) => {
+        const lockId = advisoryLockId(key);
+        const client = await locks().connect();
+        const deadline = Date.now() + Math.max(0, waitMs);
+        try {
+            for (;;) {
+                const r = await client.query('SELECT pg_try_advisory_lock($1::bigint) AS ok', [lockId]);
+                if (r.rows[0]?.ok)
+                    break;
+                if (Date.now() >= deadline || signal?.aborted) {
+                    client.release();
+                    return null;
+                }
+                await new Promise((res) => setTimeout(res, Math.min(200, Math.max(10, deadline - Date.now()))));
+            }
+        }
+        catch (err) {
+            client.release(err);
+            throw err;
+        }
+        let released = false;
+        const release = async () => {
+            if (released)
+                return;
+            released = true;
+            try {
+                await client.query('SELECT pg_advisory_unlock($1::bigint)', [lockId]);
+                client.release();
+            }
+            catch (err) {
+                // Dropping the connection releases a session-level lock too.
+                client.release(err);
+            }
+        };
+        return release;
+    };
+    return {
+        pool,
+        sessionService,
+        turnLock,
+        ...(memoryService ? { memoryService } : {}),
+        taskStore: (agentId) => new PostgresTaskStore(pool, agentId, { ttlDays: options.ttlDays, ownerResolver: options.taskOwner, lease }),
+        leases: { ...lease, renew: () => renewTaskLeases(pool, lease), reap: () => reapExpiredTasks(pool) },
+        taskQueue: postgresTaskBackend(pool),
+        async schemaVersion() {
+            try {
+                const r = await pool.query('SELECT max(version) AS v FROM melchizedek_schema_version');
+                return r.rows[0]?.v == null ? null : Number(r.rows[0].v);
+            }
+            catch (err) {
+                // No version table at all: the migrations were never applied.
+                if (err.code === '42P01')
+                    return null;
+                throw err;
+            }
+        },
+        async erase(scopeKey, eraseOptions = {}) {
+            if (!scopeKey?.trim())
+                throw new Error('erase: a scope key is required');
+            const r = await pool.query('SELECT store, deleted FROM melchizedek_erase_scope($1, $2, $3)', [
+                scopeKey,
+                eraseOptions.namespace ?? null,
+                eraseOptions.includeNested ?? false,
+            ]);
+            const counts = Object.fromEntries(ERASE_STORES.map((s) => [s, 0]));
+            for (const row of r.rows) {
+                if (ERASE_STORES.includes(row.store))
+                    counts[row.store] = Number(row.deleted);
+            }
+            return counts;
+        },
+        async close() {
+            if (lockPool)
+                await lockPool.end();
+            if (owned)
+                await pool.end();
+        },
+    };
+}

package/dist/lib/storage/postgres/memoryStore.d.ts

@@ -0,0 +1,11 @@
+/**
+ * lib/storage/postgres/memoryStore.ts — memory facts on a direct Postgres
+ * connection: the MemoryStore (lib/memory/store.ts) the memory service runs
+ * on, over the same table and `match_memory_facts` function the Supabase
+ * store uses.
+ */
+import type { Pool } from 'pg';
+import type { MemoryStore } from '../../memory/store.ts';
+/** pgvector's text form: '[0.1,0.2,…]'. */
+export declare function vectorLiteral(v: number[]): string;
+export declare function postgresMemoryStore(pool: Pool): MemoryStore;

package/dist/lib/storage/postgres/memoryStore.js

@@ -0,0 +1,82 @@
+/**
+ * lib/storage/postgres/memoryStore.ts — memory facts on a direct Postgres
+ * connection: the MemoryStore (lib/memory/store.ts) the memory service runs
+ * on, over the same table and `match_memory_facts` function the Supabase
+ * store uses.
+ */
+import { commitRows } from '../../memory/store.js';
+/** pgvector's text form: '[0.1,0.2,…]'. */
+export function vectorLiteral(v) {
+    return `[${v.map((x) => (Number.isFinite(x) ? x : 0)).join(',')}]`;
+}
+export function postgresMemoryStore(pool) {
+    return {
+        async existingFacts(userKey, facts) {
+            if (facts.length === 0)
+                return new Set();
+            const r = await pool.query('SELECT fact FROM adk_memory_facts WHERE user_key = $1 AND fact = ANY($2::text[])', [
+                userKey,
+                facts,
+            ]);
+            return new Set(r.rows.map((row) => row.fact));
+        },
+        async match(userKey, embedding, count) {
+            const r = await pool.query('SELECT * FROM match_memory_facts($1::vector, $2, $3)', [
+                vectorLiteral(embedding),
+                userKey,
+                count,
+            ]);
+            return r.rows.map((row) => ({
+                ...row,
+                id: String(row.id),
+                fact_date: row.fact_date instanceof Date ? row.fact_date.toISOString().slice(0, 10) : row.fact_date,
+                created_at: row.created_at instanceof Date ? row.created_at.toISOString() : row.created_at,
+                similarity: Number(row.similarity),
+            }));
+        },
+        async insert(rows) {
+            if (rows.length === 0)
+                return [];
+            const values = [];
+            const tuples = rows.map((row, i) => {
+                const b = i * 8;
+                values.push(row.user_key, row.fact, vectorLiteral(row.embedding), row.tag, row.fact_date, row.source, row.status, row.keys);
+                return `($${b + 1}, $${b + 2}, $${b + 3}::vector, $${b + 4}, $${b + 5}::date, $${b + 6}, $${b + 7}, $${b + 8}::text[])`;
+            });
+            const r = await pool.query(`INSERT INTO adk_memory_facts (user_key, fact, embedding, tag, fact_date, source, status, keys)
+         VALUES ${tuples.join(', ')}
+         RETURNING id, fact`, values);
+            return r.rows.map((row) => ({ id: String(row.id), fact: row.fact }));
+        },
+        async retire(userKey, id, supersededBy) {
+            await pool.query(`UPDATE adk_memory_facts SET status = 'superseded', superseded_by = $3, updated_at = now()
+          WHERE id = $1 AND user_key = $2`, [id, userKey, supersededBy]);
+        },
+        async deleteUser(userKey) {
+            const r = await pool.query('DELETE FROM adk_memory_facts WHERE user_key = $1', [userKey]);
+            return r.rowCount ?? 0;
+        },
+        async commit(userKey, marker, rows, retire) {
+            const r = await pool.query('SELECT new_id, new_fact FROM melchizedek_memory_commit($1, $2, $3, $4::jsonb, $5::jsonb)', [
+                userKey,
+                marker?.sessionId ?? null,
+                marker?.events ?? null,
+                JSON.stringify(commitRows(rows)),
+                JSON.stringify(retire.map((x) => ({ id: x.id, by_fact: x.byFact }))),
+            ]);
+            return r.rows.map((row) => ({ id: String(row.new_id), fact: row.new_fact }));
+        },
+        async ingestedEvents(userKey, sessionId) {
+            const r = await pool.query('SELECT events_ingested FROM melchizedek_memory_ingest WHERE user_key = $1 AND session_id = $2', [userKey, sessionId]);
+            return r.rows[0]?.events_ingested ?? 0;
+        },
+        async embeddingDimensions() {
+            const r = await pool.query('SELECT melchizedek_memory_dimensions() AS d');
+            return r.rows[0]?.d == null ? null : Number(r.rows[0].d);
+        },
+        async pruneNamespace(namespace, days) {
+            const r = await pool.query('SELECT melchizedek_prune_memory($1, $2) AS n', [namespace, days]);
+            return Number(r.rows[0]?.n ?? 0);
+        },
+    };
+}

package/dist/lib/storage/postgres/sessionService.d.ts

@@ -0,0 +1,51 @@
+/**
+ * lib/storage/postgres/sessionService.ts — ADK sessions on a direct Postgres
+ * connection (ADR 0021).
+ *
+ * WHY it differs from the Supabase session service:
+ *   That one re-uploads a conversation's WHOLE events array on every event.
+ *   Two turns on one conversation each hold a private copy, and whichever
+ *   writes last erases the other's events; the bytes written grow with the
+ *   square of the conversation's length. Here each event is one row in
+ *   adk_session_events, appended under a row lock on its session, and state
+ *   changes are merged into the stored state rather than overwriting it.
+ *
+ *   Events are stored as ADK produced them. The Supabase service trims thought
+ *   signatures and large tool payloads because it rewrites everything on every
+ *   event; appending each event once removes that cost, and a DELEGATE
+ *   conversation that is replayed to the model gets back exactly what it sent.
+ *
+ * Rows share adk_sessions with the Supabase service (same id scheme:
+ * '<appName>:<userId>:<sessionId>'), so erase and the session prune cover
+ * both. Tables: db/migrations/0001_base.sql and 0003_postgres_storage.sql.
+ */
+import { BaseSessionService } from '@google/adk';
+import type { CreateSessionRequest, DeleteSessionRequest, Event, GetSessionRequest, ListSessionsRequest, ListSessionsResponse, Session } from '@google/adk';
+import type { Pool } from 'pg';
+export interface PostgresSessionOptions {
+    /** Days a conversation is kept after its last event (expire_at). Default 7. */
+    ttlDays?: number;
+}
+/** The persisted part of a state delta: ADK never stores `temp:` keys. */
+export declare function persistedDelta(delta: Record<string, unknown> | undefined): Record<string, unknown>;
+export declare class PostgresSessionService extends BaseSessionService {
+    private readonly ttlMs;
+    private readonly pool;
+    constructor(pool: Pool, options?: PostgresSessionOptions);
+    private expireAt;
+    createSession(request: CreateSessionRequest): Promise<Session>;
+    /** Copy a legacy JSON history into rows, once, under the conversation's row lock. */
+    private importLegacyEvents;
+    getSession(request: GetSessionRequest): Promise<Session | undefined>;
+    /**
+     * Same paging contract as the Supabase service: `limit` with `page`
+     * (1-based, wins) or `offset` (0-based), optional order by last update,
+     * and the real total alongside the page. Events are omitted.
+     */
+    listSessions(request: ListSessionsRequest): Promise<ListSessionsResponse>;
+    deleteSession(request: DeleteSessionRequest): Promise<void>;
+    appendEvent(request: {
+        session: Session;
+        event: Event;
+    }): Promise<Event>;
+}

package/dist/lib/storage/postgres/sessionService.js

@@ -0,0 +1,225 @@
+/**
+ * lib/storage/postgres/sessionService.ts — ADK sessions on a direct Postgres
+ * connection (ADR 0021).
+ *
+ * WHY it differs from the Supabase session service:
+ *   That one re-uploads a conversation's WHOLE events array on every event.
+ *   Two turns on one conversation each hold a private copy, and whichever
+ *   writes last erases the other's events; the bytes written grow with the
+ *   square of the conversation's length. Here each event is one row in
+ *   adk_session_events, appended under a row lock on its session, and state
+ *   changes are merged into the stored state rather than overwriting it.
+ *
+ *   Events are stored as ADK produced them. The Supabase service trims thought
+ *   signatures and large tool payloads because it rewrites everything on every
+ *   event; appending each event once removes that cost, and a DELEGATE
+ *   conversation that is replayed to the model gets back exactly what it sent.
+ *
+ * Rows share adk_sessions with the Supabase service (same id scheme:
+ * '<appName>:<userId>:<sessionId>'), so erase and the session prune cover
+ * both. Tables: db/migrations/0001_base.sql and 0003_postgres_storage.sql.
+ */
+import { randomUUID } from 'node:crypto';
+import { BaseSessionService, createSession } from '@google/adk';
+function dbId(appName, userId, sessionId) {
+    return `${appName}:${userId}:${sessionId}`;
+}
+/** The persisted part of a state delta: ADK never stores `temp:` keys. */
+export function persistedDelta(delta) {
+    const out = {};
+    for (const [k, v] of Object.entries(delta ?? {})) {
+        if (!k.startsWith('temp:'))
+            out[k] = v;
+    }
+    return out;
+}
+/**
+ * A conversation written by the Supabase session service keeps its events as
+ * a JSON array on adk_sessions.events; this adapter keeps one row per event.
+ * Moving a deployment from one to the other (setting DATABASE_URL) must not
+ * cut every conversation off from its history, nor shift the event counts
+ * memory ingestion has recorded, so the first read or append of such a
+ * conversation copies its array into rows, in order. It runs only while the
+ * conversation has no rows, and leaves the array in place, so moving back is
+ * still possible.
+ */
+const IMPORT_LEGACY_EVENTS = `
+  INSERT INTO adk_session_events (session_id, seq, ts, event)
+  SELECT s.id, e.ord,
+         CASE WHEN jsonb_typeof(e.elem->'timestamp') = 'number' THEN (e.elem->>'timestamp')::double precision END,
+         e.elem
+    FROM adk_sessions s,
+         jsonb_array_elements(coalesce(s.events, '[]'::jsonb)) WITH ORDINALITY AS e(elem, ord)
+   WHERE s.id = $1
+     AND NOT EXISTS (SELECT 1 FROM adk_session_events WHERE session_id = $1)`;
+export class PostgresSessionService extends BaseSessionService {
+    ttlMs;
+    pool;
+    constructor(pool, options = {}) {
+        super();
+        this.pool = pool;
+        this.ttlMs = (options.ttlDays ?? 7) * 24 * 60 * 60 * 1000;
+    }
+    expireAt() {
+        return new Date(Date.now() + this.ttlMs).toISOString();
+    }
+    async createSession(request) {
+        const sessionId = request.sessionId || randomUUID();
+        const id = dbId(request.appName, request.userId, sessionId);
+        const now = Date.now();
+        // A concurrent create for the same id keeps the row that is already
+        // there, events and all, instead of resetting it.
+        const inserted = await this.pool.query(`INSERT INTO adk_sessions (id, app_name, user_id, state, events, last_update_time, expire_at)
+       VALUES ($1, $2, $3, $4::jsonb, '[]'::jsonb, $5, $6)
+       ON CONFLICT (id) DO NOTHING`, [id, request.appName, request.userId, JSON.stringify(request.state ?? {}), now, this.expireAt()]);
+        if (inserted.rowCount === 0) {
+            const existing = await this.getSession({ appName: request.appName, userId: request.userId, sessionId });
+            if (existing)
+                return existing;
+        }
+        return createSession({
+            id: sessionId,
+            appName: request.appName,
+            userId: request.userId,
+            state: request.state ?? {},
+            events: [],
+            lastUpdateTime: now,
+        });
+    }
+    /** Copy a legacy JSON history into rows, once, under the conversation's row lock. */
+    async importLegacyEvents(id) {
+        const client = await this.pool.connect();
+        try {
+            await client.query('BEGIN');
+            await client.query('SELECT 1 FROM adk_sessions WHERE id = $1 FOR UPDATE', [id]);
+            await client.query(IMPORT_LEGACY_EVENTS, [id]);
+            await client.query('COMMIT');
+        }
+        catch (err) {
+            await client.query('ROLLBACK').catch(() => { });
+            throw err;
+        }
+        finally {
+            client.release();
+        }
+    }
+    async getSession(request) {
+        const id = dbId(request.appName, request.userId, request.sessionId);
+        const row = await this.pool.query(`SELECT app_name, user_id, state, last_update_time,
+              (jsonb_array_length(coalesce(events, '[]'::jsonb)) > 0
+               AND NOT EXISTS (SELECT 1 FROM adk_session_events WHERE session_id = $1)) AS legacy
+         FROM adk_sessions WHERE id = $1`, [id]);
+        if (row.rowCount === 0)
+            return undefined;
+        if (row.rows[0].legacy)
+            await this.importLegacyEvents(id);
+        const cfg = request.config ?? {};
+        const params = [id];
+        let where = 'session_id = $1';
+        if (cfg.afterTimestamp) {
+            params.push(cfg.afterTimestamp);
+            where += ` AND ts > $${params.length}`;
+        }
+        // The newest N, returned oldest first.
+        const events = cfg.numRecentEvents
+            ? await this.pool.query(`SELECT event FROM (SELECT event, seq FROM adk_session_events WHERE ${where} ORDER BY seq DESC LIMIT ${Math.max(0, Math.floor(cfg.numRecentEvents))}) recent ORDER BY seq ASC`, params)
+            : await this.pool.query(`SELECT event FROM adk_session_events WHERE ${where} ORDER BY seq ASC`, params);
+        const r = row.rows[0];
+        return {
+            id: request.sessionId,
+            appName: r.app_name,
+            userId: r.user_id,
+            state: r.state ?? {},
+            events: events.rows.map((e) => e.event),
+            lastUpdateTime: Number(r.last_update_time ?? 0),
+        };
+    }
+    /**
+     * Same paging contract as the Supabase service: `limit` with `page`
+     * (1-based, wins) or `offset` (0-based), optional order by last update,
+     * and the real total alongside the page. Events are omitted.
+     */
+    async listSessions(request) {
+        const { limit, order } = request;
+        const offset = limit !== undefined && request.page !== undefined
+            ? (Math.max(1, request.page) - 1) * limit
+            : (request.offset ?? 0);
+        const params = [request.appName];
+        let where = 'app_name = $1';
+        if (request.userId !== undefined) {
+            params.push(request.userId);
+            where += ` AND user_id = $${params.length}`;
+        }
+        const total = await this.pool.query(`SELECT count(*)::int AS n FROM adk_sessions WHERE ${where}`, params);
+        const orderBy = order ? `ORDER BY last_update_time ${order === 'asc' ? 'ASC' : 'DESC'}, id` : 'ORDER BY id';
+        const window = `${limit !== undefined ? `LIMIT ${Math.max(0, Math.floor(limit))}` : ''} OFFSET ${Math.max(0, Math.floor(offset))}`;
+        const rows = await this.pool.query(`SELECT id, app_name, user_id, state, last_update_time FROM adk_sessions WHERE ${where} ${orderBy} ${window}`, params);
+        const sessions = rows.rows.map((row) => ({
+            id: String(row.id).slice(String(row.app_name).length + String(row.user_id).length + 2),
+            appName: row.app_name,
+            userId: row.user_id,
+            state: row.state ?? {},
+            events: [],
+            lastUpdateTime: Number(row.last_update_time ?? 0),
+        }));
+        const totalItems = total.rows[0].n;
+        return {
+            sessions,
+            page: limit ? Math.floor(offset / limit) + 1 : 1,
+            limit: limit ?? totalItems,
+            totalItems,
+            totalPages: limit ? Math.max(1, Math.ceil(totalItems / limit)) : 1,
+        };
+    }
+    async deleteSession(request) {
+        // Events go with it (ON DELETE CASCADE).
+        await this.pool.query('DELETE FROM adk_sessions WHERE id = $1', [
+            dbId(request.appName, request.userId, request.sessionId),
+        ]);
+    }
+    async appendEvent(request) {
+        const { session, event } = request;
+        // Streaming fragments are appended whole once complete.
+        if (event.partial)
+            return event;
+        // ADK's own merge: applies the state delta to the live session, strips
+        // temp: keys, pushes the event. Must run (see the Supabase service).
+        await super.appendEvent({ session, event });
+        session.lastUpdateTime = Date.now();
+        const id = dbId(session.appName, session.userId, session.id);
+        const delta = persistedDelta(event.actions?.stateDelta);
+        const stored = JSON.parse(JSON.stringify(event));
+        const client = await this.pool.connect();
+        try {
+            await client.query('BEGIN');
+            // The row lock serializes appends to one conversation across every
+            // process; a missing row (created elsewhere, or pruned) is recreated.
+            const locked = await client.query('SELECT 1 FROM adk_sessions WHERE id = $1 FOR UPDATE', [id]);
+            if (locked.rowCount === 0) {
+                await client.query(`INSERT INTO adk_sessions (id, app_name, user_id, state, events, last_update_time, expire_at)
+           VALUES ($1, $2, $3, '{}'::jsonb, '[]'::jsonb, $4, $5)
+           ON CONFLICT (id) DO NOTHING`, [id, session.appName, session.userId, session.lastUpdateTime, this.expireAt()]);
+                await client.query('SELECT 1 FROM adk_sessions WHERE id = $1 FOR UPDATE', [id]);
+            }
+            // A conversation the Supabase service wrote: its history first.
+            await client.query(IMPORT_LEGACY_EVENTS, [id]);
+            await client.query(`INSERT INTO adk_session_events (session_id, seq, ts, event)
+         VALUES ($1, (SELECT coalesce(max(seq), 0) + 1 FROM adk_session_events WHERE session_id = $1), $2, $3::jsonb)`, [id, typeof event.timestamp === 'number' ? event.timestamp : null, JSON.stringify(stored)]);
+            await client.query(`UPDATE adk_sessions
+            SET state = coalesce(state, '{}'::jsonb) || $2::jsonb,
+                last_update_time = $3,
+                expire_at = $4,
+                updated_at = now()
+          WHERE id = $1`, [id, JSON.stringify(delta), session.lastUpdateTime, this.expireAt()]);
+            await client.query('COMMIT');
+        }
+        catch (err) {
+            await client.query('ROLLBACK').catch(() => undefined);
+            throw new Error(`Failed to append event: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        finally {
+            client.release();
+        }
+        return event;
+    }
+}

package/dist/lib/storage/postgres/taskQueue.d.ts

@@ -0,0 +1,22 @@
+/**
+ * lib/storage/postgres/taskQueue.ts — the task tools' TaskBackend on
+ * Postgres (migration 0009, ADR 0021).
+ *
+ * Every rule stays in lib/tools/taskTools.ts and runs on a TaskStore
+ * snapshot; this file only loads one owner's snapshot and writes the change
+ * back, atomically:
+ *
+ *   mutate  locks the owner's counter row, then that owner's task rows
+ *           (FOR UPDATE), runs the change, and writes only what changed.
+ *           A worker's claim and a mutate on the same job therefore never
+ *           interleave: the claim skips a row a mutate holds, and a mutate
+ *           waits for a claim in flight, then reads its result.
+ *   claim   takes the oldest queued background job of ANY owner with
+ *           FOR UPDATE SKIP LOCKED, so two workers never take one job, and
+ *           leases it to the worker until the lease runs out.
+ *   recover finds running jobs whose lease ran out (the worker died) and
+ *           applies the same interrupted-job rule the file store uses.
+ */
+import type { Pool } from 'pg';
+import type { TaskBackend } from '../../tools/taskTools.ts';
+export declare function postgresTaskBackend(pool: Pool): TaskBackend;

package/dist/lib/storage/postgres/taskQueue.js

@@ -0,0 +1,101 @@
+import { applyFinish, applyInterrupted } from '../../tools/taskTools.js';
+const seqOf = (id) => Number(id.slice(1)) || 0;
+async function loadOwner(db, owner, lock) {
+    const head = await db.query(`SELECT next_id FROM melchizedek_task_owners WHERE owner = $1${lock ? ' FOR UPDATE' : ''}`, [owner]);
+    const rows = await db.query(`SELECT record FROM melchizedek_tasks WHERE owner = $1 ORDER BY seq${lock ? ' FOR UPDATE' : ''}`, [owner]);
+    return { version: 1, next_id: head.rows[0]?.next_id ?? 1, tasks: rows.rows.map((r) => r.record) };
+}
+async function inTransaction(pool, run) {
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        const out = await run(client);
+        await client.query('COMMIT');
+        return out;
+    }
+    catch (err) {
+        await client.query('ROLLBACK').catch(() => { });
+        throw err;
+    }
+    finally {
+        client.release();
+    }
+}
+export function postgresTaskBackend(pool) {
+    return {
+        read: (owner) => loadOwner(pool, owner, false),
+        async mutate(owner, change) {
+            return inTransaction(pool, async (client) => {
+                await client.query('INSERT INTO melchizedek_task_owners (owner) VALUES ($1) ON CONFLICT (owner) DO NOTHING', [owner]);
+                const store = await loadOwner(client, owner, true);
+                const before = new Map(store.tasks.map((t) => [t.id, JSON.stringify(t)]));
+                const out = change(store);
+                const after = new Set(store.tasks.map((t) => t.id));
+                for (const id of before.keys()) {
+                    if (!after.has(id))
+                        await client.query('DELETE FROM melchizedek_tasks WHERE owner = $1 AND id = $2', [owner, id]);
+                }
+                for (const t of store.tasks) {
+                    if (before.get(t.id) === JSON.stringify(t))
+                        continue;
+                    // Leaving `running` ends the job's lease; staying in it keeps it.
+                    await client.query(`INSERT INTO melchizedek_tasks (owner, id, seq, kind, status, record, updated_at)
+             VALUES ($1, $2, $3, $4, $5, $6::jsonb, NOW())
+             ON CONFLICT (owner, id) DO UPDATE
+               SET kind = EXCLUDED.kind, status = EXCLUDED.status, record = EXCLUDED.record, updated_at = NOW(),
+                   lease_owner = CASE WHEN EXCLUDED.status = 'running' THEN melchizedek_tasks.lease_owner END,
+                   lease_until = CASE WHEN EXCLUDED.status = 'running' THEN melchizedek_tasks.lease_until END`, [owner, t.id, seqOf(t.id), t.kind, t.status, JSON.stringify(t)]);
+                }
+                await client.query('UPDATE melchizedek_task_owners SET next_id = $2 WHERE owner = $1', [owner, store.next_id]);
+                return out;
+            });
+        },
+        async claimNext(worker) {
+            const stamp = new Date().toISOString();
+            const r = await pool.query(`WITH next AS (
+           SELECT owner, id FROM melchizedek_tasks
+            WHERE kind = 'background' AND status = 'queued'
+            ORDER BY seq, owner LIMIT 1 FOR UPDATE SKIP LOCKED
+         )
+         UPDATE melchizedek_tasks t
+            SET status = 'running',
+                lease_owner = $1,
+                lease_until = NOW() + ($2::int * interval '1 millisecond'),
+                updated_at = NOW(),
+                record = t.record || jsonb_build_object(
+                  'status', 'running',
+                  'attempts', COALESCE((t.record->>'attempts')::int, 0) + 1,
+                  'started_at', $3::text,
+                  'updated_at', $3::text)
+           FROM next
+          WHERE t.owner = next.owner AND t.id = next.id
+          RETURNING t.owner, t.record`, [worker.workerId, worker.leaseMs, stamp]);
+            const row = r.rows[0];
+            return row ? { ...row.record, owner: row.owner } : null;
+        },
+        async renew(worker, job) {
+            await pool.query(`UPDATE melchizedek_tasks SET lease_until = NOW() + ($4::int * interval '1 millisecond')
+          WHERE owner = $1 AND id = $2 AND lease_owner = $3 AND status = 'running'`, [job.owner, job.id, worker.workerId, worker.leaseMs]);
+        },
+        async finish(job, outcome) {
+            await this.mutate(job.owner, (store) => applyFinish(store, job.id, outcome));
+        },
+        async recover() {
+            return inTransaction(pool, async (client) => {
+                const r = await client.query(`SELECT owner, id, record FROM melchizedek_tasks
+            WHERE status = 'running' AND (lease_until IS NULL OR lease_until < NOW())
+            FOR UPDATE SKIP LOCKED`);
+                const requeued = [];
+                const failed = [];
+                for (const row of r.rows) {
+                    const t = row.record;
+                    const outcome = applyInterrupted(t);
+                    (outcome === 'failed' ? failed : requeued).push(`${row.owner || '(shared)'}:${t.id}`);
+                    await client.query(`UPDATE melchizedek_tasks SET status = $3, record = $4::jsonb, updated_at = NOW(), lease_owner = NULL, lease_until = NULL
+              WHERE owner = $1 AND id = $2`, [row.owner, row.id, t.status, JSON.stringify(t)]);
+                }
+                return { requeued, failed };
+            });
+        },
+    };
+}