@poppykit/server 0.1.1 → 0.2.0

package/API.md

@@ -19,3 +19,7 @@ and do not need the optional reference issuer. Your framework owns HTTPS routing
 trusted public URLs, ingress limits, request cancellation and private-error handling.
 
 Run the [quickstart](examples/quickstart.mjs) without a listener or external service.
+
+The optional Postgres entry point ships its adapters, `createPostgresPool`,
+`postgresMigration`, `migratePostgres` and schema-version export; see [storage](STORAGE.md).
+TypeScript Postgres consumers also install `@types/pg@8.23.1` as a development dependency.

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.2.0 (release candidate)
+
+Add bundled Postgres company stores/coordinator with explicit migrations, atomic host transaction composition, savepoints and pool lifecycle.
+
 ## 0.1.1
 
 Documentation refresh: registry installation, runnable quickstarts, focused guides

package/README.md

@@ -6,12 +6,14 @@ supplies accounts, consent UI, agent, business tools and HTTPS routing. [MIT](LI
 
 ## Install
 
+Version 0.2.0 is a release candidate until its publishing workflow completes.
+
 Requires Node **24.12.0+** and ESM. CI tests Node 24.12.0 on Linux, macOS and Windows;
 later majors are not separately certified. SQLite is optional/experimental and
 requires local filesystem locking.
 
 ```sh
-npm install @poppykit/server@0.1.1
+npm install @poppykit/server@0.2.0
 ```
 
 ## Configure a service

package/STORAGE.md

@@ -110,3 +110,71 @@ state. Default payload retention is indefinite; operators should retain at least
 30 days and explicitly choose any shorter policy. See [DELIVERY.md](DELIVERY.md)
 for distinct lifetimes and client recovery behavior. No automatic destructive
 reset or history deletion was added.
+
+## Postgres
+
+`@poppykit/server/postgres` ships `PostgresCompanyDatabase`, explicit migrations,
+and `createPostgresPool` in this package. Install optional peer `pg@8.23.1` when
+using that subpath. Core/reference-auth imports load neither database driver.
+Supported baseline: Node 24.12+, PostgreSQL 17, including Supabase transaction pooling.
+No application, Google login or Supabase Auth dependency is required.
+
+```ts
+import { createPostgresPool, migratePostgres,
+  PostgresCompanyDatabase } from '@poppykit/server/postgres';
+const pool = createPostgresPool({ connectionString: process.env.DATABASE_URL });
+// Explicit operator/deployment migration; do this before handling requests.
+await migratePostgres(pool, 'poppy_server');
+const database = new PostgresCompanyDatabase(pool);
+const issuerStore = database.issuer('https://company.example/issuer');
+const conversationStore = database.conversations('https://company.example/issuer');
+// Reference issuer: store: issuerStore, coordinator: database.
+// Conversation service: store: conversationStore, policy: issuer.authority.policy.
+await database.close(); // after in-flight requests end; leaves caller pool open
+await pool.end();
+```
+
+Use one database object for issuer/coordinator/conversations. `withTransaction`
+passes a generic query connection to host DB work inside that same transaction:
+
+```ts
+await issuer.authority.policy.withCurrent(principal, ['records:write'], () =>
+  database.withTransaction(async connection => {
+    await connection.query('UPDATE application.records SET value=$1 WHERE owner=$2',
+      [validatedValue, trustedAccountId]);
+  }));
+```
+
+The policy holds the issuer authority fence through commit; revocation waits or
+wins before mutation. The host must still validate ownership, payload digests,
+current business revisions and its own idempotency receipts. Issuer namespace
+metadata and per-conversation binding/message locks use transaction-scoped advisory
+locks, including absent keys; no process mutex or session lock substitutes for them.
+Nested mutations use savepoints. Await nested mutations sequentially: overlapping
+siblings reject explicitly, while recursion is supported. Escaped query handles
+reject after their scope ends. External model/network/KMS calls belong outside this
+boundary. Fences do not make arbitrary external effects exactly-once.
+
+Pool defaults are max 2, acquisition 3s/idle 10s, verified TLS; configure a trusted
+CA through `ssl`, never insecure TLS URL overrides. Explicit `ssl:false` is for a
+trusted local test server. Caller-created pools remain their owner's responsibility.
+Transactions/statements are bounded to 5s, lock waits 2s, with unnamed parameterized
+queries and one checkout from BEGIN to COMMIT/ROLLBACK. No LISTEN, named prepares
+or session state is required. `close` never closes a caller-supplied pool; callers
+of `createPostgresPool` own and must end that pool.
+
+Immutable SQL ships at `migrations/postgres/0001_poppy_server.sql`.
+`postgresMigration('poppy_server')` returns reviewable SQL and
+`migratePostgres(pool,'poppy_server')` is the explicit atomic apply/version check.
+No constructor/request-time DDL or automatic SQLite import/reset exists. Unknown or
+missing versions fail closed. Version 1 does not certify arbitrary manual table
+edits: inspect migration history and reconcile drift before applying new versions.
+Applied migrations are immutable, corrections require new versioned files. Back up,
+review and rehearse live changes; roll application code back only to compatible
+schemas, or restore a reviewed backup for destructive reversal. No populated-schema
+drop/downgrade is automated. The disposable test runner is development tooling,
+never a production migration command.
+
+`runIssuerAdapterContract` joins the existing reusable conversation contract in
+`@poppykit/server/adapter-contract`. Run both against two fresh shared handles;
+process death, lock ordering and DB durability still require backend-specific tests.

package/dist/adapter-contract.d.ts

@@ -1,4 +1,12 @@
 import type { ConversationOptions } from './conversation/service.js';
+import type { IssuerStore } from './reference-auth/store.js';
+export type IssuerAdapterFixture = () => Promise<{
+    store: IssuerStore;
+    second: IssuerStore;
+    close(): Promise<void>;
+}>;
+/** A fresh shared namespace, including absent-row serialization; no vendor-specific fixture is required. */
+export declare function runIssuerAdapterContract(fixture: IssuerAdapterFixture): void;
 type Store = ConversationOptions['store'] & {
     inspect(): Promise<import('./conversation/service.js').ConversationStoreState>;
     adminTransaction<T>(change: (draft: import('./conversation/service.js').ConversationStoreState) => T): Promise<T>;

package/dist/adapter-contract.js

@@ -5,6 +5,24 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { AuthorityError } from './auth/authority.js';
 import { createConversationService, resetConversationState } from './conversation/service.js';
+/** A fresh shared namespace, including absent-row serialization; no vendor-specific fixture is required. */
+export function runIssuerAdapterContract(fixture) {
+    test('issuer adapter contract: replay updates serialize, snapshots detach and failed callbacks roll back', async () => {
+        const f = await fixture(), selection = { kind: 'browser', sessionId: 'absent', replayKey: 'counter' };
+        try {
+            await Promise.all(Array.from({ length: 10 }, (_, i) => (i % 2 ? f.store : f.second).transaction(selection, state => { state.replay.counter = (state.replay.counter ?? 0) + 1; })));
+            const state = await f.store.read(selection);
+            assert.equal(state.replay.counter, 10);
+            state.replay.counter = 999;
+            await assert.rejects(f.store.transaction(selection, draft => { draft.replay.counter = 0; throw new Error('rollback'); }), /rollback/);
+            await assert.rejects(f.store.transaction(selection, async (draft) => { draft.replay.counter = 0; }));
+            assert.equal((await f.second.read(selection)).replay.counter, 10);
+        }
+        finally {
+            await f.close();
+        }
+    });
+}
 const endpoint = 'https://contract.example.test/poppy/conversations';
 const base = { issuer: 'https://auth.contract.test', clientId: 'https://agent.contract.test/client', sessionId: 's1', userId: 'u_1', scopes: [], tokenExpiresAt: 9e12, sessionVersion: 1 };
 const principals = {
@@ -51,6 +69,18 @@ export function runConversationAdapterContract(fixture) {
             await opened.close();
         }
     }
+    test('adapter contract: concurrent conflicting output retries publish one immutable result', () => withFixture(async ({ store, second }) => {
+        const a = serviceOn(store, clock), b = serviceOn(second, clock);
+        const id = (await call(a, '', 'signedOut', { message })).body.conversation_id;
+        const work = (await a.claim());
+        const results = await Promise.allSettled([a.reply(work, 'same-call', reply), b.reply(work, 'same-call', { ...reply, text: 'conflicting result' })]);
+        assert.equal(results.filter(result => result.status === 'fulfilled').length, 1);
+        const failed = results.find(result => result.status === 'rejected');
+        assert.ok(failed && failed.status === 'rejected');
+        assert.equal(failed.reason.code, 'output_conflict');
+        const events = (await call(a, `/${id}/events`, 'signedOut')).body.events;
+        assert.equal(events.filter(event => event.message?.id === reply.id).length, 1);
+    }));
     test('adapter contract: reads and results are detached; failed, non-JSON and async changes roll back', () => withFixture(async ({ store, second }) => {
         const snapshot = await store.inspect();
         snapshot.bindings.leaked = {};

package/dist/postgres-runtime.d.ts

@@ -0,0 +1,30 @@
+import type { Pool, PoolConfig, QueryResult, QueryResultRow } from 'pg';
+export type PostgresSchema = 'poppy_client' | 'poppy_provider' | 'poppy_server';
+export type PostgresConnection = {
+    query<R extends QueryResultRow = QueryResultRow>(sql: string, values?: unknown[]): Promise<QueryResult<R>>;
+};
+export declare function json(value: unknown): string;
+export declare function synchronous<T>(value: T): T;
+/** Remote defaults verify TLS; plaintext must be explicitly selected for a trusted local test server. */
+export declare function createPostgresPool(config: PoolConfig): Pool;
+export declare const postgresSchemaVersion = 1;
+export declare function postgresMigration(schema: PostgresSchema): Promise<string>;
+/** Explicit administration only. Constructors never execute DDL. */
+export declare function migratePostgres(pool: Pool, schema: PostgresSchema): Promise<void>;
+export declare class PostgresRuntime {
+    readonly pool: Pool;
+    readonly schema: PostgresSchema;
+    private readonly ownsPool;
+    private readonly context;
+    private closed;
+    readonly metrics: {
+        rowsRead: number;
+        rowsWritten: number;
+    };
+    constructor(pool: Pool, schema: PostgresSchema, ownsPool?: boolean);
+    close(): Promise<void>;
+    run<T>(action: () => Promise<T>): Promise<T>;
+    connection(): PostgresConnection;
+    query<R extends QueryResultRow = QueryResultRow>(sql: string, values?: unknown[]): Promise<R[]>;
+    lock(key: string): Promise<void>;
+}

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.1",
+  "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
+    }
   }
 }