@poppykit/server 0.1.1 → 0.3.0

package/API.md

@@ -18,4 +18,13 @@ idempotency and reconciliation. Existing issuers implement `ExternalAuthorityAda
 and do not need the optional reference issuer. Your framework owns HTTPS routing,
 trusted public URLs, ingress limits, request cancellation and private-error handling.
 
+Direct reference issuers now require `authorizationResultCipher` before
+`beginAuthorization`; same-decision `completeAuthorization` recovers the encrypted
+callback through its original validity window. See [AUTH.md](AUTH.md) for custody,
+revocation and one-time exchange limits. No package subpath or driver contract changed.
+
 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/AUTH.md

@@ -12,6 +12,43 @@ The host authenticates the human and protects consent with its own browser
 session/CSRF controls; pass a high-entropy browser binding. Registered callback
 URLs must be HTTPS on the client metadata domain and exactly match registration.
 
+Direct hosts must configure `authorizationResultCipher: { seal, open }` with
+synchronous authenticated encryption and a durable protected key before calling
+`beginAuthorization`. Hosts already using the optional client provider can reuse
+its `createResultCipher` instance. Other hosts supply the same structural contract;
+no client package or database driver is loaded by the reference issuer.
+
+`completeAuthorization(id, browserBinding, decision)` commits one decision and
+an encrypted callback receipt atomically. Repeating the same decision returns
+the same URL after restart; changed browser/account/scopes/decision and stale
+account revocation/reset fail. Approval recovery expires at the earlier of the
+original authorization deadline and code expiry; denial uses the original deadline.
+Recovery never mints a replacement code or extends consent. The host must retain
+its authenticated owner/installation/session binding and chosen decision durably,
+then reconcile delivery outside transactions. Never retry an uncertain code exchange.
+
+`withCurrent` checks token, Session and grant expiry immediately before protected
+actions, including after body reads and long-poll waits. Streams close at token
+expiry and recheck current authority for each emitted frame; reconnect with fresh
+authentication. `withAccepted` intentionally ignores admission-token expiry while
+preserving the accepted scope ceiling, reset generation and configured revocation policy.
+
+Account Token rotation retains all issued hashes through the fixed grant lifetime.
+Replaying any ancestor revokes its entire lineage and signs its Sessions out;
+rotation never extends the grant. Client authentication remains mandatory, while
+Session Tokens can move to a new DPoP key as the protocol permits. Shared provider
+signing does not bind a copied refresh token to one provider enrollment. Keep
+tokens secret and serialize rotation; never retry a lost token response blindly.
+Bounded database cleanup removes hashes only after their lineage is expired,
+revoked or absent. No plaintext callback code is persisted.
+
+Upgrade prerequisite: older issuers discarded ancestors beyond the previous hash.
+Those missing hashes cannot be reconstructed by this update. Before public
+enablement, revoke every pre-upgrade live lineage through the issuer's normal
+revocation/disconnect flow and require fresh consent, or prove it has expired.
+Until then, the full-ancestor guarantee applies only to newly created lineages.
+This update does not reset stored data or silently revoke legacy grants.
+
 Enable reference Device sign-in with `device: { endpoint, verificationUri,
 scopes }`. Route the configured device endpoint to `deviceAuthorization`.
 On the human page call `beginDeviceAuthorization(userCode, browserBinding)` and

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.3.0
+
+Require Node 24 >=24.22.1 within 24.x. Enforce current-token expiry after waits and
+at streamed delivery while preserving already-accepted work's authority ceiling.
+Deduplicate reserved string output IDs and retain refresh-token ancestors through
+fixed grant expiry so replay revokes descendants. Direct Sign-In hosts must supply
+the documented durable `authorizationResultCipher`; identical decisions recover
+their original encrypted callback. Before public enablement, revoke pre-upgrade
+live grant lineages and obtain fresh consent, or prove their fixed expiry.
+Required release verification now includes isolated PostgreSQL contracts.
+
+## 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/CONTRIBUTING.md

@@ -5,8 +5,8 @@ and [guides](https://personalagentprotocol.org/docs/0.2/guides). Tests/snapshots
 supporting evidence. Demo/business workflows and individual extensions are excluded.
 Code is [MIT](LICENSE); confirm rights for third-party contributions.
 
-Use Node 24.12.0, TypeScript 5.9.3 and @types/node 24.10.0.
-Install the packageManager-pinned pnpm and run pnpm install --frozen-lockfile.
+Use Node 24.22.1, TypeScript 5.9.3 and @types/node 24.10.0.
+Install the packageManager-pinned pnpm and run pnpm install --frozen-lockfile --ignore-scripts.
 
 ```sh
 npm run typecheck
@@ -36,3 +36,11 @@ Preserve credential/destination validation, private errors and persisted data.
 Report checks actually run and limits. Use Issues for non-sensitive defects and
 [SECURITY.md](SECURITY.md) for vulnerabilities. Follow [RELEASING.md](RELEASING.md)
 before tagging/publishing; obtain explicit owner authorization.
+
+Required CI also runs scripts/postgres-ci.mjs in a dedicated disposable PostgreSQL17
+cluster with POPPY_DISPOSABLE_POSTGRES=1, D1_LOCAL=1 and explicit loopback PGHOST,
+PGPORT, PGUSER, PGPASSWORD, PGDATABASE. Build production/tests first; use a fresh
+database without SDK schemas. Never point it at shared/cloud data. It migrates
+only this package's schemas, runs all named durable suites, rejects skips/missing
+discovery and leaves cluster destruction to its owner. Default source-suite skips
+do not replace this gate. See the workflow for the pinned image and setup.

package/DELIVERY.md

@@ -53,8 +53,9 @@ SQLite reconciliation; deployments can implement the same notification contract
 with their own distributed adapter. Lost/duplicate hints cannot erase a commit.
 SQLite event windows and append operations do not reload complete event histories.
 
-Server streams default to 30 seconds and apply pull backpressure, rechecking
-current authority before further pages. This bounded-connection policy omits
+Server streams default to 30 seconds, end earlier at token expiry and apply pull
+backpressure, rechecking current authority before every emitted frame. Reconnect
+with a fresh credential and the last handled event ID. This bounded-connection policy omits
 periodic idle comments; proxies may close an idle stream sooner, and the client
 reconnects. Longer-lived deployments should supply heartbeat handling at their
 HTTP adapter. Hosts must propagate disconnect/AbortSignal and body cancellation.

package/README.md

@@ -6,12 +6,14 @@ supplies accounts, consent UI, agent, business tools and HTTPS routing. [MIT](LI
 
 ## Install
 
-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
+This source contains unreleased repairs; final version selection and publication are pending.
+
+Requires Node **24.x, at least 24.22.1**, and ESM. CI tests Node 24.22.1 on Linux, macOS and Windows;
+other Node majors are unsupported. SQLite is optional/experimental and
 requires local filesystem locking.
 
 ```sh
-npm install @poppykit/server@0.1.1
+npm install @poppykit/server
 ```
 
 ## Configure a service

package/RELEASING.md

@@ -6,7 +6,7 @@ changing runtime APIs. Each new version needs its own source/artifact evidence.
 
 ## Before tagging
 
-- Confirm npm ownership, unused versions, supported Node 24.12.0 and npm>=11.5.1.
+- Confirm npm ownership, unused versions, supported Node 24.x (at least 24.22.1) and npm>=11.5.1.
   Keep the pinned compiler/dependencies; do not upgrade tooling during a release.
 - Update version, changelog and shipped docs. CLI's client dependency and both
   candidate JSON files must match exact final SDK versions/full source SHAs.
@@ -47,7 +47,7 @@ guard requires its tested client tarball integrity to equal the published one.
    ```
 
 4. Wait for candidate, fast, contracts, integration, packaged-linux/windows/macos,
-   validation and gate to succeed. Missing, failed, canceled or skipped prerequisites
+   validation, postgres and gate to succeed. The postgres job uses its own disposable PostgreSQL17 cluster and the same-run checked candidate/harness; zero discovery or any skipped database case fails. Missing, failed, canceled or skipped prerequisites
    fail closed. Then follow the Actions environment-approval link. Do not bypass it.
 5. The publisher rechecks source/tag/ref/version, trusted manifest digest, unchanged
    tarball metadata/bytes, owner enablement, registry absence and dependency integrity.

package/STORAGE.md

@@ -1,10 +1,10 @@
 # Company persistence and authorization
 
-Request paths use targeted domain selections, not whole-state rewrites. Node 24.12.0 or later is required.
+Request paths use targeted domain selections, not whole-state rewrites. Node 24.x, at least 24.22.1, is required.
 The optional `@poppykit/server/sqlite` entry point exports `SqliteCompanyDatabase`.
 The core and reference issuer entry points do not import SQLite. Consumers can
 implement `ConversationStore`, `IssuerStore` and `AuthorityCoordinator` themselves.
-The tested Node 24.12.0 runtime marks `node:sqlite` experimental.
+The tested Node 24.22.1 runtime marks `node:sqlite` experimental.
 
 ```ts
 import { SqliteCompanyDatabase } from '@poppykit/server/sqlite';
@@ -35,7 +35,7 @@ with correct SQLite locks; network-mounted multi-host SQLite is unsupported.
 ## Domain records and guarantees
 
 Every primary key includes a namespace (use the exact full issuer). Sessions,
-grants, current/previous token hashes, authorization requests, codes, access-token
+grants, every live-lineage Account Token hash, authorization requests, codes, access-token
 hashes, replay keys, conversation metadata, shared account bindings, message
 receipts and work intent are separate records. Ordered events are a separate table
 keyed by namespace/conversation/sequence. Indexes cover client, account, grant,
@@ -71,7 +71,9 @@ its own idempotency key (such as the stable work ID), or the application must re
 an uncertain result for reconciliation. Never claim universal exactly-once execution.
 
 `cleanup(namespace, now, limit)` bounds deletion to at most 1000 expired short-lived
-codes, authorizations, access tokens or replay entries. It does not delete grants,
+codes, authorizations, access tokens, replay entries or expired/revoked/orphaned
+Account Token hashes. Every used hash for a live lineage remains replay-detectable
+through its fixed expiry; retained size follows rotation volume. It does not delete grants,
 work intent, message receipts or conversation events. Receipt identity remains
 through retention for the conversation lifetime. Finished work pruning is
 per selected conversation binding group; unrelated conversation growth cannot
@@ -110,3 +112,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.x (at least 24.22.1), 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 = {
@@ -32,7 +50,7 @@ function serviceOn(store, clock) {
             return principal;
         },
     };
-    return createConversationService({ endpoint, store, authenticator, policy, clock, leaseMs: 1000 });
+    return createConversationService({ endpoint, store, authenticator, policy, clock, leaseMs: 1000, supportedScopes: ['poppy:read'] });
 }
 async function call(service, path, as, body, query = '') {
     const response = await service.handle(new Request(`${endpoint}${path}${query}`, {
@@ -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 = {};
@@ -115,6 +145,33 @@ export function runConversationAdapterContract(fixture) {
         const events = (await call(b, `/${id}/events`, 'signedOut')).body.events;
         assert.equal(events.filter(event => event.message?.id === reply.id).length, 1);
     }));
+    test('adapter contract: reserved output IDs persist atomic reply and prompt receipts across handles', () => withFixture(async ({ store, second }) => {
+        const a = serviceOn(store, clock);
+        const id = (await call(a, '', 'signedOut', { message })).body.conversation_id;
+        const work = (await a.claim());
+        for (const outputId of ['__proto__', 'constructor', 'ordinary']) {
+            const b = serviceOn(second, clock);
+            const value = { ...reply, id: `reply_${outputId}` };
+            await a.reply(work, outputId, value);
+            await b.reply(work, outputId, value);
+            await assert.rejects(b.reply(work, outputId, { ...value, text: 'changed' }), { code: 'output_conflict' });
+            await a.requestAuthorization(work, `auth_${outputId}`, ['poppy:read']);
+            await b.requestAuthorization(work, `auth_${outputId}`, ['poppy:read']);
+            await a.requestUser(work, `user_${outputId}`, outputId);
+            await b.requestUser(work, `user_${outputId}`, outputId);
+            await assert.rejects(b.requestUser(work, `user_${outputId}`, 'changed'), { code: 'output_conflict' });
+            const persisted = await second.inspect();
+            const receipt = persisted.work.find(row => row.id === work.workId);
+            assert.ok(Object.hasOwn(receipt.outputs, outputId));
+        }
+        const events = (await call(serviceOn(second, clock), `/${id}/events`, 'signedOut')).body.events;
+        assert.equal(events.filter(event => event.message?.role === 'company').length, 3);
+        assert.equal(events.filter(event => event.type === 'authorization').length, 3);
+        assert.equal(events.filter(event => event.type === 'user_requested').length, 3);
+        clock.t += 1000;
+        await serviceOn(second, clock).claim();
+        await assert.rejects(a.reply(work, '__proto__', reply), { code: 'stale_work' });
+    }));
     test('adapter contract: a waited POST committed before a crash is recovered unchanged on the other handle', () => withFixture(async ({ store, second }) => {
         const crashing = serviceOn({ read: () => store.inspect(), transaction: (_selection, change) => store.adminTransaction(change).then(() => { throw new Error('crash after commit'); }) }, clock);
         await assert.rejects(call(crashing, '', 'signedOut', { message }, '?wait=10'), { message: 'crash after commit' });

package/dist/conversation/service.js

@@ -391,7 +391,7 @@ export function createConversationService(options) {
             if (!streaming) {
                 const deadline = Date.now() + read.waitSeconds * 1000, logicalDeadline = clock.now() + read.waitSeconds * 1000;
                 while (!first.events.length && Date.now() < deadline && clock.now() < logicalDeadline && !signal.aborted) {
-                    await wait(Math.min(pollIntervalMs, deadline - Date.now(), logicalDeadline - clock.now()), seen);
+                    await wait(Math.min(pollIntervalMs, deadline - Date.now(), logicalDeadline - clock.now(), principal.tokenExpiresAt - clock.now()), seen);
                     seen = revision;
                     if (signal.aborted)
                         throw signal.reason;
@@ -401,12 +401,18 @@ export function createConversationService(options) {
                 cleanup();
                 return json(200, first);
             }
-            lifetime = setTimeout(cleanup, streamMs);
-            const encoder = new TextEncoder(), deadline = Date.now() + streamMs;
+            const duration = Math.max(0, Math.min(streamMs, principal.tokenExpiresAt - clock.now()));
+            lifetime = setTimeout(cleanup, duration);
+            const encoder = new TextEncoder(), deadline = Date.now() + duration;
             let pending = first, index = 0, bytes = 0, cancelled = false;
             const stream = new ReadableStream({
                 async pull(target) {
                     try {
+                        if (clock.now() >= principal.tokenExpiresAt) {
+                            cleanup();
+                            target.close();
+                            return;
+                        }
                         signal.throwIfAborted();
                         while (index >= pending.events.length) {
                             if (Date.now() >= deadline || pending.status === 'closed' && !pending.has_more) {
@@ -421,6 +427,7 @@ export function createConversationService(options) {
                             pending = await deliver();
                             index = 0;
                         }
+                        await policy.withCurrent(principal, [], async () => { });
                         const event = pending.events[index++];
                         const frame = encoder.encode('id: ' + event.id + '\ndata: ' + JSON.stringify(event) + '\n\n');
                         bytes += frame.byteLength;
@@ -433,7 +440,7 @@ export function createConversationService(options) {
                         target.enqueue(frame);
                     }
                     catch (error) {
-                        const expired = stop.signal.aborted && !request.signal.aborted;
+                        const expired = (stop.signal.aborted || clock.now() >= principal.tokenExpiresAt) && !request.signal.aborted;
                         cleanup();
                         if (cancelled)
                             return;
@@ -570,7 +577,7 @@ export function createConversationService(options) {
     function firstOutput(work, outputId, payload) {
         const previous = own(work.outputs, outputId);
         if (previous === undefined) {
-            work.outputs[outputId] = payload;
+            work.outputs = { ...work.outputs, [outputId]: payload };
             return true;
         }
         if (previous !== payload)

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,304 @@
+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->'completion' IS NULL 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->'completion' IS NULL 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 AS retained 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)
+        OR (kind='refreshTokens' AND NOT EXISTS (SELECT 1 FROM poppy_server.records AS lineage WHERE lineage.ns=retained.ns AND lineage.kind='grants' AND lineage.id=retained.body::jsonb#>>'{}' AND (lineage.body::jsonb->>'expiresAt')::double precision>$5 AND lineage.body::jsonb->>'revoked'='false'))) LIMIT $6`, [namespace, now, 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/dist/reference-auth/index.d.ts

@@ -41,6 +41,10 @@ interface AuthorizationRecord {
     browserHash: string;
     expiresAt: number;
     revision: number;
+    completion?: {
+        decisionHash: string;
+        callback: string;
+    };
 }
 interface CodeRecord {
     clientId: string;
@@ -156,6 +160,11 @@ export interface ReferenceIssuerOptions {
         dpop: boolean;
     }[];
     metadata: MetadataResolver;
+    /** Required for Direct Sign-In: synchronous authenticated encryption with a durable host-owned key. */
+    authorizationResultCipher?: {
+        seal(value: string): string;
+        open(value: string): string;
+    };
     store: IssuerStore;
     coordinator: AuthorityCoordinator;
     now: () => number;

package/dist/reference-auth/index.js

@@ -661,8 +661,7 @@ export function createReferenceIssuer(options) {
                 if (!scopes.every(item => lineage.scopes.includes(item)))
                     throw new TokenError('invalid_scope');
                 const successor = random(32);
-                // Older hashes are forgotten: the previous one is enough to revoke after a lost rotation response.
-                delete draft.refreshTokens[lineage.previousHash];
+                // Retain ancestors until the fixed grant expiry so every replay can revoke its descendants.
                 lineage.previousHash = lineage.refreshHash;
                 lineage.refreshHash = tokenHash(successor);
                 draft.refreshTokens[lineage.refreshHash] = grantId;
@@ -702,9 +701,9 @@ export function createReferenceIssuer(options) {
             const presented = tokenHash(refreshToken);
             const grantId = own(draft.refreshTokens, presented);
             const lineage = grantId === undefined ? undefined : own(draft.grants, grantId);
-            // Reuse of the previous Account Token (e.g. a retry after a lost response) revokes the lineage, so its Sessions
+            // Reuse of any ancestor Account Token (e.g. a retry after a lost response) revokes the lineage, so its Sessions
             // continue signed out instead of staying bound to a successor nobody holds (RFC 9700 4.14.2).
-            if (lineage && lineage.clientId === clientId && presented === lineage.previousHash) {
+            if (lineage && lineage.clientId === clientId && presented !== lineage.refreshHash) {
                 revokeGrant(draft, grantId);
                 return null;
             }
@@ -777,7 +776,7 @@ export function createReferenceIssuer(options) {
             const state = await read({ kind: 'principal', sessionId: principal.sessionId, ...(principal.grantId ? { grantId: principal.grantId } : {}) });
             const session = own(state.sessions, principal.sessionId);
             if (principal.issuer !== issuer || principal.issuerGeneration !== state.generation || !session || session.clientId !== principal.clientId
-                || session.expiresAt <= now() || session.userId !== principal.userId || !liveGrant(state, principal))
+                || principal.tokenExpiresAt <= now() || session.expiresAt <= now() || session.userId !== principal.userId || !liveGrant(state, principal))
                 throw new AuthorityError('invalid_token');
             requireScopes(principal.scopes, scopes);
             return action();
@@ -858,6 +857,8 @@ export function createReferenceIssuer(options) {
         // Validates the whole request before persisting anything; the host renders login and consent from the view.
         // Unauthenticated: hosts must rate-limit their /authorize route; the pending cap only bounds state and coordinator time.
         async beginAuthorization(request, browserBinding) {
+            if (!options.authorizationResultCipher)
+                throw new TypeError('authorizationResultCipher is required for Direct Sign-In');
             if (typeof browserBinding !== 'string' || !browserBinding)
                 throw new TypeError('browserBinding');
             const params = uniqueParams(new URL(request.url).searchParams, () => new AuthorizationError('invalid_request'));
@@ -905,7 +906,7 @@ export function createReferenceIssuer(options) {
                 const at = now();
                 prune(draft, at);
                 // shortcut: an unauthenticated caller can fill one client's slots for AUTHORIZATION_MS (10 minutes); hosts must rate-limit /authorize.
-                const pending = Object.values(draft.authorizations);
+                const pending = Object.values(draft.authorizations).filter(record => !record.completion);
                 if ((draft.limits?.pending ?? pending.length) >= maxPending || (draft.limits?.pendingForClient ?? pending.filter(record => record.clientId === clientId).length) >= maxPendingPerClient)
                     throw fail('temporarily_unavailable');
                 const id = random(16);
@@ -914,8 +915,11 @@ export function createReferenceIssuer(options) {
                 return { id, clientId, clientName: client.client_name, scopes, expiresAt };
             });
         },
-        // Consumes the authorization once; the browser binding is checked before deny as well as approve.
+        // Commit once; a bound identical decision can recover the encrypted callback without minting another code.
         async completeAuthorization(id, browserBinding, decision) {
+            const cipher = options.authorizationResultCipher;
+            if (!cipher)
+                throw new TypeError('authorizationResultCipher is required for Direct Sign-In');
             if (typeof id !== 'string' || typeof browserBinding !== 'string')
                 throw new AuthorizationError('invalid_request');
             const snapshot = own((await read({ kind: 'authorization', id })).authorizations, id);
@@ -924,21 +928,32 @@ export function createReferenceIssuer(options) {
                 const record = own(draft.authorizations, id);
                 if (!record || record.expiresAt <= now() || record.browserHash !== tokenHash(browserBinding))
                     throw new AuthorizationError('invalid_request');
-                const fields = { state: record.state, iss: issuer };
-                if ('denied' in decision && decision.denied === true) {
-                    delete draft.authorizations[id];
-                    return callback(record.redirectUri, { error: 'access_denied', ...fields });
-                }
+                const denied = 'denied' in decision && decision.denied === true;
                 const { accountId, scopes } = decision;
                 // Partial consent narrows; the host may never grant more than was requested.
-                if (typeof accountId !== 'string' || !accountId || !Array.isArray(scopes) || !scopes.length || !scopes.every(scope => record.scopes.includes(scope)))
+                if (!denied && (typeof accountId !== 'string' || !accountId || !Array.isArray(scopes) || !scopes.length || !scopes.every(scope => record.scopes.includes(scope))))
                     throw new TypeError('decision');
-                if (!consentCurrent(draft, record.clientId, accountId, record.revision))
+                if (!denied && !consentCurrent(draft, record.clientId, accountId, record.revision))
                     throw new AuthorizationError('invalid_request');
-                delete draft.authorizations[id];
+                const granted = denied ? [] : [...new Set(scopes)].sort();
+                const decisionHash = tokenHash(JSON.stringify(denied ? { denied: true } : { accountId, scopes: granted }));
+                if (record.completion) {
+                    if (record.completion.decisionHash !== decisionHash)
+                        throw new AuthorizationError('invalid_request');
+                    return cipher.open(record.completion.callback);
+                }
+                const fields = { state: record.state, iss: issuer };
+                if (denied) {
+                    const href = callback(record.redirectUri, { error: 'access_denied', ...fields });
+                    record.completion = { decisionHash, callback: cipher.seal(href) };
+                    return href;
+                }
                 const code = random(32);
-                draft.codes[tokenHash(code)] = { clientId: record.clientId, redirectUri: record.redirectUri, codeChallenge: record.codeChallenge, accountId, scopes: [...new Set(scopes)], expiresAt: now() + CODE_MS, grantId: null, revision: record.revision };
-                return callback(record.redirectUri, { code, ...fields });
+                record.expiresAt = Math.min(record.expiresAt, now() + CODE_MS);
+                draft.codes[tokenHash(code)] = { clientId: record.clientId, redirectUri: record.redirectUri, codeChallenge: record.codeChallenge, accountId: accountId, scopes: granted, expiresAt: record.expiresAt, grantId: null, revision: record.revision };
+                const href = callback(record.redirectUri, { code, ...fields });
+                record.completion = { decisionHash, callback: cipher.seal(href) };
+                return href;
             });
             return new URL(href);
         },

package/dist/sqlite.js

@@ -307,8 +307,8 @@ export class SqliteCompanyDatabase {
             }
             if (selection.kind === 'authorize') {
                 get('signIns', clientRevisionKey(selection.clientId));
-                const pending = this.db.prepare("SELECT count(*) AS n FROM records WHERE ns=? AND kind='authorizations' AND json_extract(body,'$.expiresAt')>?").get(namespace, selection.at);
-                const client = this.db.prepare("SELECT count(*) AS n FROM records WHERE ns=? AND kind='authorizations' AND json_extract(body,'$.clientId')=? AND json_extract(body,'$.expiresAt')>?").get(namespace, selection.clientId, selection.at);
+                const pending = this.db.prepare("SELECT count(*) AS n FROM records WHERE ns=? AND kind='authorizations' AND json_extract(body,'$.completion') IS NULL AND json_extract(body,'$.expiresAt')>?").get(namespace, selection.at);
+                const client = this.db.prepare("SELECT count(*) AS n FROM records WHERE ns=? AND kind='authorizations' AND json_extract(body,'$.completion') IS NULL AND json_extract(body,'$.clientId')=? AND json_extract(body,'$.expiresAt')>?").get(namespace, selection.clientId, selection.at);
                 state.limits = { sessions: 0, earliestSessionExpiry: 0, pending: Number(pending.n), pendingForClient: Number(client.n) };
             }
             if (selection.kind === 'disconnect') {
@@ -359,8 +359,9 @@ export class SqliteCompanyDatabase {
         if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000)
             throw new TypeError('cleanup limit');
         return this.run(async () => {
-            const rows = this.db.prepare(`SELECT kind,id FROM records WHERE ns=? AND
-        ((kind IN ('authorizations','codes','accessTokens') AND json_extract(body,'$.expiresAt')<=?) OR (kind='signIns' AND json_extract(body,'$.expiresAt')+30000<?) OR (kind='replay' AND CAST(body AS REAL)<?)) LIMIT ?`).all(namespace, now, now, now, limit);
+            const rows = this.db.prepare(`SELECT kind,id FROM records AS retained WHERE ns=? AND
+        ((kind IN ('authorizations','codes','accessTokens') AND json_extract(body,'$.expiresAt')<=?) OR (kind='signIns' AND json_extract(body,'$.expiresAt')+30000<?) OR (kind='replay' AND CAST(body AS REAL)<?)
+        OR (kind='refreshTokens' AND NOT EXISTS (SELECT 1 FROM records AS lineage WHERE lineage.ns=retained.ns AND lineage.kind='grants' AND lineage.id=json_extract(retained.body,'$') AND json_extract(lineage.body,'$.expiresAt')>? AND json_extract(lineage.body,'$.revoked')=0))) LIMIT ?`).all(namespace, now, now, now, now, limit);
             for (const row of rows)
                 this.db.prepare('DELETE FROM records WHERE ns=? AND kind=? AND id=?').run(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.3.0",
   "private": false,
   "description": "Personal Agent Protocol company SDK",
   "repository": {
@@ -9,7 +9,7 @@
   },
   "type": "module",
   "engines": {
-    "node": ">=24.12.0"
+    "node": ">=24.22.1 <25"
   },
   "packageManager": "pnpm@11.25.0",
   "scripts": {
@@ -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
+    }
   }
 }