@poppykit/server 0.1.0 → 0.2.0

package/dist/postgres-runtime.js

@@ -0,0 +1,172 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { readFile } from 'node:fs/promises';
+import pg from 'pg';
+export function json(value) {
+    return JSON.stringify(value, (_key, item) => {
+        if (item === undefined || typeof item === 'function' || typeof item === 'bigint' || (typeof item === 'number' && !Number.isFinite(item)))
+            throw new TypeError('non-JSON record');
+        return item;
+    });
+}
+export function synchronous(value) {
+    if (value && typeof value.then === 'function')
+        throw new TypeError('transaction callback must be synchronous');
+    return structuredClone(value);
+}
+/** Remote defaults verify TLS; plaintext must be explicitly selected for a trusted local test server. */
+export function createPostgresPool(config) {
+    if (config.ssl && typeof config.ssl === 'object' && config.ssl.rejectUnauthorized === false)
+        throw new TypeError('Postgres TLS verification is required');
+    if (config.connectionString && [...new URL(config.connectionString).searchParams.keys()].some(key => key.toLowerCase().startsWith('ssl') || key === 'uselibpqcompat'))
+        throw new TypeError('configure verified TLS through ssl, not connection-string overrides');
+    return new pg.Pool({ max: 2, connectionTimeoutMillis: 3000, idleTimeoutMillis: 10000, ...config, ssl: config.ssl ?? { rejectUnauthorized: true } });
+}
+export const postgresSchemaVersion = 1;
+function schemaName(schema) {
+    if (!['poppy_client', 'poppy_provider', 'poppy_server'].includes(schema))
+        throw new TypeError('unsupported Postgres schema');
+    return schema;
+}
+export async function postgresMigration(schema) {
+    schemaName(schema);
+    return readFile(new URL(`../migrations/postgres/0001_${schema}.sql`, import.meta.url), 'utf8');
+}
+/** Explicit administration only. Constructors never execute DDL. */
+export async function migratePostgres(pool, schema) {
+    schemaName(schema);
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        await client.query("SET LOCAL statement_timeout='5s'");
+        await client.query('SELECT pg_advisory_xact_lock(hashtextextended($1,0))', [`poppykit:migrate:${schema}`]);
+        const exists = (await client.query('SELECT to_regclass($1) AS name', [`${schema}.schema_version`])).rows[0].name;
+        if (exists) {
+            const rows = (await client.query(`SELECT version FROM ${schema}.schema_version`)).rows;
+            if (rows.length !== 1 || rows[0].version !== postgresSchemaVersion)
+                throw new Error('unsupported Postgres schema version');
+        }
+        else
+            await client.query(await postgresMigration(schema));
+        await client.query('COMMIT');
+    }
+    catch (error) {
+        await client.query('ROLLBACK');
+        throw error;
+    }
+    finally {
+        client.release();
+    }
+}
+function scopeActive(context) {
+    for (let scope = context; scope; scope = scope.parent)
+        if (!scope.active || !scope.state.active)
+            return false;
+    return true;
+}
+export class PostgresRuntime {
+    pool;
+    schema;
+    ownsPool;
+    context = new AsyncLocalStorage();
+    closed = false;
+    metrics = { rowsRead: 0, rowsWritten: 0 };
+    constructor(pool, schema, ownsPool = false) {
+        this.pool = pool;
+        this.schema = schema;
+        this.ownsPool = ownsPool;
+    }
+    async close() { this.closed = true; if (this.ownsPool)
+        await this.pool.end(); }
+    async run(action) {
+        if (this.closed)
+            throw new Error('Postgres adapter is closed');
+        const parent = this.context.getStore();
+        if (parent) {
+            if (!scopeActive(parent))
+                throw new Error('expired Postgres transaction');
+            if (parent.childActive)
+                throw new Error('concurrent nested Postgres transactions are unsupported; await each mutation');
+            parent.childActive = true;
+            const savepoint = `nested_${++parent.state.serial}`;
+            const child = { ...parent, parent, active: true, childActive: false, locks: new Set(parent.locks) };
+            let started = false;
+            try {
+                await parent.client.query(`SAVEPOINT ${savepoint}`);
+                started = true;
+                const result = await this.context.run(child, action);
+                if (!scopeActive(child))
+                    throw new Error('expired Postgres transaction');
+                if (child.childActive)
+                    throw new Error('unawaited nested Postgres transaction');
+                child.active = false;
+                await parent.client.query(`RELEASE SAVEPOINT ${savepoint}`);
+                parent.locks = child.locks;
+                return result;
+            }
+            catch (error) {
+                child.active = false;
+                if (started && scopeActive(parent)) {
+                    await parent.client.query(`ROLLBACK TO SAVEPOINT ${savepoint}`);
+                    await parent.client.query(`RELEASE SAVEPOINT ${savepoint}`);
+                }
+                throw error;
+            }
+            finally {
+                child.active = false;
+                parent.childActive = false;
+            }
+        }
+        const client = await this.pool.connect(), context = { client, active: true, locks: new Set(), state: { serial: 0, active: true }, childActive: false };
+        try {
+            await client.query('BEGIN');
+            await client.query("SET LOCAL statement_timeout='5s'");
+            await client.query("SET LOCAL lock_timeout='2s'");
+            await client.query("SET LOCAL idle_in_transaction_session_timeout='5s'");
+            await client.query("SET LOCAL transaction_timeout='5s'");
+            const versions = (await client.query(`SELECT version FROM ${this.schema}.schema_version`)).rows;
+            if (versions.length !== 1 || versions[0].version !== postgresSchemaVersion)
+                throw new Error('unsupported Postgres schema version');
+            const result = await this.context.run(context, action);
+            if (context.childActive)
+                throw new Error('unawaited nested Postgres transaction');
+            await client.query('COMMIT');
+            return result;
+        }
+        catch (error) {
+            context.state.active = false;
+            await client.query('ROLLBACK').catch(() => { });
+            throw error;
+        }
+        finally {
+            context.active = false;
+            context.state.active = false;
+            client.release();
+        }
+    }
+    connection() {
+        const context = this.context.getStore();
+        if (!context || !scopeActive(context))
+            throw new Error('no active Postgres transaction');
+        return { query: async (sql, values) => {
+                if (!scopeActive(context) || this.context.getStore() !== context)
+                    throw new Error('expired Postgres transaction');
+                if (context.childActive)
+                    throw new Error('concurrent Postgres transaction use is unsupported; await each mutation');
+                return context.client.query(sql, values);
+            } };
+    }
+    async query(sql, values = []) {
+        const result = await this.connection().query(sql, values);
+        this.metrics.rowsRead += result.rows.length;
+        return result.rows;
+    }
+    async lock(key) {
+        const context = this.context.getStore();
+        if (!context || !scopeActive(context))
+            throw new Error('no active Postgres transaction');
+        if (!context.locks.has(key)) {
+            await this.query('SELECT pg_advisory_xact_lock(hashtextextended($1,0))', [`${this.schema}:${key}`]);
+            context.locks.add(key);
+        }
+    }
+}

package/dist/postgres.d.ts

@@ -0,0 +1,31 @@
+import type { Pool } from 'pg';
+import type { ConversationStore } from './conversation/store.js';
+import type { IssuerStore } from './reference-auth/store.js';
+import type { PostgresConnection } from './postgres-runtime.js';
+export { createPostgresPool, migratePostgres, postgresMigration, postgresSchemaVersion } from './postgres-runtime.js';
+export type { PostgresConnection } from './postgres-runtime.js';
+/** Share this coordinator between the issuer, conversation service and host business mutations. */
+export declare class PostgresCompanyDatabase {
+    private readonly db;
+    constructor(pool: Pool);
+    get metrics(): {
+        rowsRead: number;
+        rowsWritten: number;
+    };
+    close(): Promise<void>;
+    run<T>(action: () => Promise<T>): Promise<T>;
+    withTransaction<T>(action: (connection: PostgresConnection) => Promise<T>): Promise<T>;
+    private atomic;
+    private sqlAll;
+    private sqlGet;
+    private sqlRun;
+    private rows;
+    private one;
+    private put;
+    private save;
+    private meta;
+    conversations(namespace: string): ConversationStore;
+    issuer(namespace: string): IssuerStore;
+    /** Bounded maintenance; never deletes message receipts, events, grants or work intent. */
+    cleanup(namespace: string, now: number, limit?: number): Promise<number>;
+}

package/dist/postgres.js

@@ -0,0 +1,303 @@
+import { initialConversationState } from './conversation/service.js';
+import { initialIssuerState } from './reference-auth/index.js';
+import { clientRevisionKey, accountRevisionKey } from './reference-auth/store.js';
+import { PostgresRuntime, json } from './postgres-runtime.js';
+export { createPostgresPool, migratePostgres, postgresMigration, postgresSchemaVersion } from './postgres-runtime.js';
+/** Share this coordinator between the issuer, conversation service and host business mutations. */
+export class PostgresCompanyDatabase {
+    db;
+    constructor(pool) { this.db = new PostgresRuntime(pool, 'poppy_server'); }
+    get metrics() { return this.db.metrics; }
+    close() { return this.db.close(); }
+    run(action) { return this.db.run(action); }
+    withTransaction(action) { return this.run(() => action(this.db.connection())); }
+    atomic(action) { return this.db.run(action); }
+    sqlAll(sql, values = []) { return this.db.query(sql, values); }
+    async sqlGet(sql, values = []) { return (await this.sqlAll(sql, values))[0]; }
+    async sqlRun(sql, values = []) { const result = await this.db.connection().query(sql, values); return { changes: result.rowCount ?? 0 }; }
+    async rows(ns, kind, where = '', params = []) { return this.db.query(`SELECT id,body FROM poppy_server.records WHERE ns=$1 AND kind=$2 ${where}`, [ns, kind, ...params]); }
+    async one(ns, kind, id) { const row = (await this.rows(ns, kind, 'AND id=$3', [id]))[0]; return row ? JSON.parse(row.body) : undefined; }
+    async put(ns, kind, id, value) { await this.sqlRun('INSERT INTO poppy_server.records(ns,kind,id,body) VALUES($1,$2,$3,$4) ON CONFLICT(ns,kind,id) DO UPDATE SET body=excluded.body', [ns, kind, id, json(value)]); this.metrics.rowsWritten++; }
+    async save(ns, kind, before, after) {
+        for (const id of Object.keys(before))
+            if (!Object.hasOwn(after, id)) {
+                await this.sqlRun('DELETE FROM poppy_server.records WHERE ns=$1 AND kind=$2 AND id=$3', [ns, kind, id]);
+                this.metrics.rowsWritten++;
+            }
+        for (const [id, value] of Object.entries(after))
+            if (!Object.hasOwn(before, id) || json(before[id]) !== json(value))
+                await this.put(ns, kind, id, value);
+    }
+    async meta(ns, kind, initial) {
+        const found = await this.one(ns, kind, 'meta');
+        if (found)
+            return found;
+        await this.db.lock(JSON.stringify([ns, kind, 'meta']));
+        const raced = await this.one(ns, kind, 'meta');
+        if (raced)
+            return raced;
+        const value = initial();
+        await this.put(ns, kind, 'meta', value);
+        return value;
+    }
+    conversations(namespace) {
+        const load = async (selection) => {
+            const state = { ...await this.meta(namespace, 'conversation_meta', () => { const { version, generation } = initialConversationState(); return { version, generation }; }), conversations: {}, bindings: {}, messages: {}, work: [] };
+            if (selection.messageKey)
+                await this.db.lock(JSON.stringify([namespace, 'message', selection.messageKey]));
+            let id = selection.conversationId;
+            if (selection.messageKey) {
+                const message = await this.one(namespace, 'messages', selection.messageKey);
+                if (message) {
+                    state.messages[selection.messageKey] = message;
+                    id = message.conversationId;
+                }
+            }
+            if (selection.workId)
+                id = (await this.one(namespace, 'work', selection.workId))?.conversationId;
+            if (selection.claimAt !== undefined) {
+                const row = await this.sqlGet(`SELECT w.body FROM poppy_server.records w JOIN poppy_server.records c ON c.ns=w.ns AND c.kind='conversations' AND c.id=(w.body::jsonb#>>'{conversationId}')
+          WHERE w.ns=$1 AND w.kind='work' AND (w.body::jsonb#>>'{phase}') IN ('pending','claimed','held')
+          AND (c.body::jsonb#>>'{childId}') IS NULL AND (
+            ((c.body::jsonb#>>'{responder}')='human' AND coalesce(((c.body::jsonb#>>'{humanUntil}')::double precision),0)<=$2) OR
+            ((c.body::jsonb#>>'{responder}')!='human' AND (c.body::jsonb#>>'{status}')!='queued' AND (w.body::jsonb#>>'{phase}') IN ('pending','claimed')
+              AND ((w.body::jsonb#>>'{phase}')='pending' OR coalesce(((w.body::jsonb#>>'{leaseUntil}')::double precision),0)<=$3)
+              AND NOT EXISTS (SELECT 1 FROM poppy_server.records earlier WHERE earlier.ns=w.ns AND earlier.kind='work' AND earlier.ordinal<w.ordinal
+                AND (earlier.body::jsonb#>>'{conversationId}')=(w.body::jsonb#>>'{conversationId}') AND (earlier.body::jsonb#>>'{phase}') IN ('pending','claimed'))))
+          ORDER BY w.ordinal LIMIT 1`, [namespace, selection.claimAt, selection.claimAt]);
+                if (row) {
+                    this.metrics.rowsRead++;
+                    id = JSON.parse(row.body).conversationId;
+                }
+            }
+            let target = id ? await this.one(namespace, 'conversations', id) : undefined;
+            if (target) {
+                await this.db.lock(JSON.stringify([namespace, 'binding', target.bindingId]));
+                target = await this.one(namespace, 'conversations', target.id);
+            }
+            if (!target)
+                return state;
+            if (selection.cursorCheck !== undefined) {
+                const found = await this.sqlGet("SELECT seq FROM poppy_server.event_cursors WHERE ns=$1 AND conversation=$2 AND id=$3", [namespace, target.id, selection.cursorCheck]);
+                if (!found)
+                    state.cursorStatus = 'invalid';
+                else if (!await this.sqlGet("SELECT 1 FROM poppy_server.events WHERE ns=$1 AND conversation=$2 AND seq=$3", [namespace, target.id, Number(found.seq)]))
+                    state.cursorStatus = 'expired';
+            }
+            for (const row of await this.rows(namespace, 'conversations', selection.events ? 'AND id=$3' : "AND (body::jsonb->>'bindingId')=$3", [selection.events ? target.id : target.bindingId])) {
+                const conversation = JSON.parse(row.body);
+                let from = -1;
+                if (selection.events?.cursor !== undefined) {
+                    const found = await this.sqlGet("SELECT seq FROM poppy_server.event_cursors WHERE ns=$1 AND conversation=$2 AND id=$3", [namespace, row.id, selection.events.cursor]);
+                    if (!found)
+                        conversation.eventWindow = { invalid: true, hasMore: false };
+                    else {
+                        from = Number(found.seq);
+                        if (!await this.sqlGet("SELECT 1 FROM poppy_server.events WHERE ns=$1 AND conversation=$2 AND seq=$3", [namespace, row.id, from]))
+                            conversation.eventWindow = { expired: true, hasMore: false };
+                    }
+                }
+                const events = [];
+                let hasMore = false;
+                if (selection.events) {
+                    let bytes = 0;
+                    for (const event of await this.sqlAll("SELECT body FROM poppy_server.events WHERE ns=$1 AND conversation=$2 AND seq>$3 ORDER BY seq LIMIT $4", [namespace, row.id, from, selection.events.limit + 1])) {
+                        this.metrics.rowsRead++;
+                        const size = Buffer.byteLength(event.body) + 1;
+                        if (events.length >= selection.events.limit || bytes + size > (selection.events.maxBytes ?? 1048576)) {
+                            hasMore = true;
+                            break;
+                        }
+                        events.push(event);
+                        bytes += size;
+                    }
+                    conversation.eventWindow = { ...conversation.eventWindow, hasMore };
+                }
+                else if (!selection.append)
+                    events.push(...await this.sqlAll("SELECT body FROM poppy_server.events WHERE ns=$1 AND conversation=$2 ORDER BY seq", [namespace, row.id]));
+                if (!selection.events)
+                    this.metrics.rowsRead += events.length;
+                if (selection.append && !conversation.lastUserMessage) {
+                    const last = await this.sqlGet("SELECT body FROM poppy_server.events WHERE ns=$1 AND conversation=$2 AND (body::jsonb#>>'{type}')='message' AND (body::jsonb#>>'{message,role}')='user' ORDER BY seq DESC LIMIT 1", [namespace, row.id]);
+                    if (last) {
+                        this.metrics.rowsRead++;
+                        conversation.lastUserMessage = JSON.parse(last.body).message;
+                    }
+                }
+                conversation.events = events.map(event => JSON.parse(event.body));
+                state.conversations[row.id] = conversation;
+                if (!selection.events)
+                    state.work.push(...(await this.rows(namespace, 'work', "AND (body::jsonb#>>'{conversationId}')=$3 ORDER BY ordinal", [row.id])).map(work => JSON.parse(work.body)));
+            }
+            const binding = await this.one(namespace, 'bindings', target.bindingId);
+            if (binding)
+                state.bindings[target.bindingId] = binding;
+            return state;
+        };
+        return {
+            pruneEvents: (conversationId, before, limit = 100) => {
+                if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000 || !Number.isFinite(before))
+                    throw new TypeError('retention limit');
+                return this.run(async () => {
+                    const target = await this.one(namespace, 'conversations', conversationId);
+                    if (target)
+                        await this.db.lock(JSON.stringify([namespace, 'binding', target.bindingId]));
+                    const active = await this.sqlGet("SELECT 1 FROM poppy_server.records WHERE ns=$1 AND kind='work' AND (body::jsonb#>>'{conversationId}')=$2 AND (body::jsonb#>>'{phase}') IN ('held','pending','claimed') LIMIT 1", [namespace, conversationId]);
+                    if (active)
+                        return 0;
+                    const removed = await this.sqlRun("DELETE FROM poppy_server.events WHERE ns=$1 AND conversation=$2 AND seq IN (SELECT seq FROM poppy_server.events WHERE ns=$3 AND conversation=$4 AND (body::jsonb#>>'{created_at}')<$5 ORDER BY seq LIMIT $6)", [namespace, conversationId, namespace, conversationId, new Date(before).toISOString(), limit]);
+                    return Number(removed.changes);
+                });
+            },
+            read: selection => this.run(async () => await load(selection)),
+            transaction: (selection, change) => this.run(async () => this.atomic(async () => {
+                const state = await load(selection), before = structuredClone(state);
+                const result = change(state);
+                if (result && typeof result.then === 'function')
+                    throw new TypeError('async conversation transaction');
+                if (selection.events) {
+                    if (json(state) !== json(before))
+                        throw new TypeError('event windows are read-only');
+                    return structuredClone(result);
+                }
+                if (state.version !== before.version || state.generation !== before.generation || Object.keys(before.conversations).some(id => !Object.hasOwn(state.conversations, id)))
+                    throw new TypeError('use an explicit offline reset');
+                for (const [id, conversation] of Object.entries(state.conversations)) {
+                    const oldEvents = before.conversations[id]?.events ?? [];
+                    if (conversation.events.length < oldEvents.length || oldEvents.some((event, i) => json(event) !== json(conversation.events[i])))
+                        throw new TypeError('events must be append-only');
+                    const last = Number((await this.sqlGet("SELECT coalesce(max(seq),-1) AS seq FROM poppy_server.event_cursors WHERE ns=$1 AND conversation=$2", [namespace, id])).seq);
+                    for (let i = oldEvents.length; i < conversation.events.length; i++) {
+                        const seq = last + i - oldEvents.length + 1, event = conversation.events[i];
+                        await this.sqlRun("INSERT INTO poppy_server.events VALUES ($1,$2,$3,$4)", [namespace, id, seq, json(event)]);
+                        await this.sqlRun("INSERT INTO poppy_server.event_cursors VALUES ($1,$2,$3,$4)", [namespace, id, event.id, seq]);
+                        this.metrics.rowsWritten += 2;
+                    }
+                    const { events: _events, ...record } = conversation;
+                    const { events: _oldEvents, ...old } = before.conversations[id] ?? {};
+                    if (json(record) !== json(old))
+                        await this.put(namespace, 'conversations', id, record);
+                }
+                await this.save(namespace, 'bindings', before.bindings, state.bindings);
+                await this.save(namespace, 'messages', before.messages, state.messages);
+                await this.save(namespace, 'work', Object.fromEntries(before.work.map(row => [row.id, row])), Object.fromEntries(state.work.map(row => [row.id, row])));
+                return structuredClone(result);
+            })),
+        };
+    }
+    issuer(namespace) {
+        const kinds = ['sessions', 'grants', 'refreshTokens', 'authorizations', 'codes', 'signIns', 'accessTokens', 'replay'];
+        const load = async (selection) => {
+            await this.db.lock(JSON.stringify([namespace, 'issuer']));
+            const state = { ...await this.meta(namespace, 'issuer_meta', () => { const { version, generation, nonces } = initialIssuerState(); return { version, generation, nonces }; }), sessions: {}, grants: {}, refreshTokens: {}, authorizations: {}, codes: {}, signIns: {}, accessTokens: {}, replay: {} };
+            const get = async (kind, id) => {
+                if (!id)
+                    return;
+                const value = await this.one(namespace, kind, id);
+                if (value !== undefined)
+                    state[kind][id] = value;
+            };
+            const find = async (kind, where, ...params) => {
+                for (const row of await this.rows(namespace, kind, where, params))
+                    state[kind][row.id] = JSON.parse(row.body);
+            };
+            if (selection.kind === 'access')
+                await get('accessTokens', selection.hash);
+            if (selection.kind === 'sign_in') {
+                for (const id of selection.ids)
+                    await get('signIns', id);
+                await get('sessions', selection.sessionId);
+                await get('accessTokens', selection.accessHash);
+                for (const key of selection.replayKeys)
+                    await get('replay', key);
+                const counts = (await this.sqlGet("SELECT count(*) AS n, sum(CASE WHEN (body::jsonb#>>'{clientId}')=$1 THEN 1 ELSE 0 END) AS client FROM poppy_server.records WHERE ns=$2 AND kind='signIns' AND (body::jsonb#>>'{status}') IN ('pending','approved','verifying') AND ((body::jsonb#>>'{expiresAt}')::double precision)>$3", [selection.clientId ?? '', namespace, selection.at]));
+                state.limits = { sessions: 0, earliestSessionExpiry: 0, pending: Number(counts.n), pendingForClient: Number(counts.client ?? 0) };
+            }
+            if (selection.kind === 'principal') {
+                await get('sessions', selection.sessionId);
+                await get('grants', selection.grantId);
+            }
+            if (selection.kind === 'browser') {
+                await get('sessions', selection.sessionId);
+                await get('replay', selection.replayKey);
+            }
+            if (selection.kind === 'authorization') {
+                await get('authorizations', selection.id);
+                await get('signIns', selection.revocationKey);
+            }
+            if (selection.kind === 'token') {
+                await get('sessions', selection.sessionId);
+                await get('codes', selection.codeHash);
+                await get('refreshTokens', selection.refreshHash);
+                for (const key of selection.replayKeys)
+                    await get('replay', key);
+                const counts = (await this.sqlGet("SELECT count(*) AS n, min(((body::jsonb#>>'{expiresAt}')::double precision)) AS expiry FROM poppy_server.records WHERE ns=$1 AND kind='sessions' AND (body::jsonb#>>'{clientId}')=$2 AND ((body::jsonb#>>'{expiresAt}')::double precision)>$3", [namespace, selection.clientId, selection.at]));
+                state.limits = { sessions: Number(counts.n), earliestSessionExpiry: Number(counts.expiry ?? selection.at), pending: 0, pendingForClient: 0 };
+            }
+            if (selection.kind === 'revoke') {
+                await get('refreshTokens', selection.refreshHash);
+                await get('replay', selection.replayKey);
+            }
+            if (selection.kind === 'authorize') {
+                await get('signIns', clientRevisionKey(selection.clientId));
+                const pending = (await this.sqlGet("SELECT count(*) AS n FROM poppy_server.records WHERE ns=$1 AND kind='authorizations' AND ((body::jsonb#>>'{expiresAt}')::double precision)>$2", [namespace, selection.at]));
+                const client = (await this.sqlGet("SELECT count(*) AS n FROM poppy_server.records WHERE ns=$1 AND kind='authorizations' AND (body::jsonb#>>'{clientId}')=$2 AND ((body::jsonb#>>'{expiresAt}')::double precision)>$3", [namespace, selection.clientId, selection.at]));
+                state.limits = { sessions: 0, earliestSessionExpiry: 0, pending: Number(pending.n), pendingForClient: Number(client.n) };
+            }
+            if (selection.kind === 'disconnect') {
+                for (const kind of ['grants', 'codes'])
+                    await find(kind, "AND (body::jsonb->>'clientId')=$3 AND (body::jsonb->>'accountId')=$4", selection.clientId, selection.accountId);
+                await find('signIns', "AND (body::jsonb->>'clientId')=$3 AND (body::jsonb->>'accountId')=$4", selection.clientId, selection.accountId);
+                await get('signIns', clientRevisionKey(selection.clientId));
+                await get('signIns', accountRevisionKey(selection.clientId, selection.accountId));
+            }
+            for (const record of Object.values(state.accessTokens)) {
+                await get('sessions', record.sessionId);
+                if (record.grantId)
+                    await get('grants', record.grantId);
+            }
+            for (const record of [...Object.values(state.sessions), ...Object.values(state.codes)])
+                if (record.grantId)
+                    await get('grants', record.grantId);
+            for (const record of Object.values(state.codes))
+                await get('signIns', accountRevisionKey(record.clientId, record.accountId));
+            for (const id of Object.values(state.refreshTokens))
+                await get('grants', id);
+            for (const [id, grant] of Object.entries(state.grants)) {
+                await get('refreshTokens', grant.refreshHash);
+                await get('refreshTokens', grant.previousHash);
+                if (['token', 'revoke', 'disconnect'].includes(selection.kind))
+                    await find('sessions', "AND (body::jsonb->>'grantId')=$3", id);
+            }
+            return state;
+        };
+        return {
+            read: selection => this.run(async () => await load(selection)),
+            transaction: (selection, change) => this.run(async () => this.atomic(async () => {
+                const state = await load(selection), before = structuredClone(state);
+                const result = change(state);
+                if (result && typeof result.then === 'function')
+                    throw new TypeError('async issuer transaction');
+                for (const kind of kinds)
+                    await this.save(namespace, kind, before[kind], state[kind]);
+                const { version, generation, nonces } = state;
+                if (json({ version, generation, nonces }) !== json({ version: before.version, generation: before.generation, nonces: before.nonces }))
+                    await this.put(namespace, 'issuer_meta', 'meta', { version, generation, nonces });
+                return structuredClone(result);
+            })),
+        };
+    }
+    /** Bounded maintenance; never deletes message receipts, events, grants or work intent. */
+    cleanup(namespace, now, limit = 100) {
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000)
+            throw new TypeError('cleanup limit');
+        return this.run(async () => {
+            await this.db.lock(JSON.stringify([namespace, 'issuer']));
+            const rows = await this.sqlAll(`SELECT kind,id FROM poppy_server.records WHERE ns=$1 AND
+        ((kind IN ('authorizations','codes','accessTokens') AND ((body::jsonb#>>'{expiresAt}')::double precision)<=$2) OR (kind='signIns' AND ((body::jsonb#>>'{expiresAt}')::double precision)+30000<$3) OR (kind='replay' AND (body::jsonb#>>'{}')::double precision<$4)) LIMIT $5`, [namespace, now, now, now, limit]);
+            for (const row of rows)
+                await this.sqlRun("DELETE FROM poppy_server.records WHERE ns=$1 AND kind=$2 AND id=$3", [namespace, row.kind, row.id]);
+            return rows.length;
+        });
+    }
+}

package/migrations/postgres/0001_poppy_server.sql

@@ -0,0 +1,16 @@
+CREATE SCHEMA poppy_server;
+CREATE TABLE poppy_server.schema_version (version integer PRIMARY KEY CHECK(version > 0));
+INSERT INTO poppy_server.schema_version VALUES (1);
+CREATE TABLE poppy_server.records (ns text NOT NULL, kind text NOT NULL, id text NOT NULL, body text NOT NULL CHECK (body::jsonb IS NOT NULL), ordinal bigint GENERATED ALWAYS AS IDENTITY, PRIMARY KEY(ns,kind,id));
+CREATE INDEX by_conversation ON poppy_server.records (ns,kind,(body::jsonb#>>'{conversationId}'));
+CREATE INDEX by_binding ON poppy_server.records (ns,kind,(body::jsonb#>>'{bindingId}'));
+CREATE INDEX by_client ON poppy_server.records (ns,kind,(body::jsonb#>>'{clientId}'));
+CREATE INDEX by_account ON poppy_server.records (ns,kind,(body::jsonb#>>'{accountId}'));
+CREATE INDEX by_grant ON poppy_server.records (ns,kind,(body::jsonb#>>'{grantId}'));
+CREATE INDEX by_phase ON poppy_server.records (ns,kind,(body::jsonb#>>'{phase}'));
+CREATE INDEX by_expiry ON poppy_server.records (ns,kind,((body::jsonb#>>'{expiresAt}')::double precision));
+CREATE INDEX by_connection ON poppy_server.records (ns,kind,(body::jsonb#>>'{connectionId}'));
+CREATE INDEX by_callback ON poppy_server.records (ns,kind,(body::jsonb#>>'{direct,stateHash}'));
+CREATE TABLE poppy_server.events (ns text NOT NULL, conversation text NOT NULL, seq bigint NOT NULL, body text NOT NULL, PRIMARY KEY(ns,conversation,seq));
+CREATE INDEX last_user_event ON poppy_server.events(ns,conversation,((body::jsonb)->>'type'),((body::jsonb)#>>'{message,role}'),seq);
+CREATE TABLE poppy_server.event_cursors (ns text NOT NULL, conversation text NOT NULL, id text NOT NULL, seq bigint NOT NULL, PRIMARY KEY(ns,conversation,id), UNIQUE(ns,conversation,seq));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poppykit/server",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "description": "Personal Agent Protocol company SDK",
   "repository": {
@@ -24,7 +24,9 @@
   },
   "devDependencies": {
     "@types/node": "24.10.0",
-    "typescript": "5.9.3"
+    "typescript": "5.9.3",
+    "pg": "8.23.1",
+    "@types/pg": "8.23.1"
   },
   "files": [
     "dist",
@@ -39,7 +41,8 @@
     "CHANGELOG.md",
     "RELEASING.md",
     "examples",
-    "LICENSE"
+    "LICENSE",
+    "migrations"
   ],
   "exports": {
     ".": {
@@ -57,6 +60,10 @@
     "./sqlite": {
       "types": "./dist/sqlite.d.ts",
       "import": "./dist/sqlite.js"
+    },
+    "./postgres": {
+      "types": "./dist/postgres.d.ts",
+      "import": "./dist/postgres.js"
     }
   },
   "dependencies": {
@@ -65,5 +72,13 @@
   "license": "MIT",
   "publishConfig": {
     "access": "public"
+  },
+  "peerDependencies": {
+    "pg": "^8.23.1"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    }
   }
 }