@poppykit/client 0.1.1 → 0.3.0

package/API.md

@@ -11,7 +11,7 @@ for complete option/result types. This map describes the supported integration s
 | `@poppykit/client` | `ApiTarget`, `AgentBrowserController`, `FeedbackReport` types | [integrations](INTEGRATIONS.md) |
 | `@poppykit/client/sqlite` | `SqliteAuthStore`, `SqliteConversationStore` | [storage](STORAGE.md) |
 | `@poppykit/client/memory` | `MemoryConversationStore` (non-durable) | [storage](STORAGE.md) |
-| `@poppykit/client/provider` | `createProvider`, `createProviderClient`, `createResultCipher` | [provider](PROVIDER.md) |
+| `@poppykit/client/provider` | `createProvider`, `createProviderClient`, `createResultCipher`, `createBrowserEnrollmentClient` | [provider](PROVIDER.md) |
 | `@poppykit/client/provider/sqlite` | `SqliteProviderStore` | [provider](PROVIDER.md) |
 
 ClientAuth methods include `start/get/list/target`, `authorization`,
@@ -23,3 +23,7 @@ and endpoint; never substitute profile names or model-provided URLs for that bin
 The [quickstart](examples/quickstart.mjs) is executed by CI. Integration examples
 describe adapters your application supplies; they are not built-in browser drivers
 or general API executors.
+
+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,15 @@
 # Changelog
 
+## 0.3.0 (release candidate)
+
+Add the optional challenge-bound browser enrollment client under `/provider`.
+Existing provider APIs, storage adapters and all protocol authentication methods
+retain their contracts. Enrollment secrets remain caller-controlled.
+
+## 0.2.0 (release candidate)
+
+Add bundled Postgres auth/conversation/provider stores and explicit migrations. Provider APIs and targeted storage transactions are asynchronous; await callback/result/revocation operations. SQLite and explicit legacy local-store migration remain supported.
+
 ## 0.1.1
 
 Documentation refresh: registry installation, runnable quickstarts, focused guides

package/PROVIDER.md

@@ -1,9 +1,19 @@
 # Optional identity provider
 
+`createBrowserEnrollmentClient` from this subpath is an optional hosting-service
+client. It is independent of company consent and leaves all secret custody with
+the caller. Configure an HTTPS enrollment URL on the provider origin; call
+`start(SHA256(verifier))`, show only its public `browserUrl`, then call
+`status(requestId, verifier)` from trusted code. A ready response contains the
+credential for immediate secure staging, never for model output. `cancel` revokes
+failed/uncertain delivery; hosts must consume results once, retain replay
+tombstones and revoke on failed/lost retrieval. The CLI implements that workflow.
+This optional service uses version1 JSON requests and is not a Poppy extension.
+
 Import `createProvider`, `createProviderClient`, and `createResultCipher` from
 `@poppykit/client/provider`; durable `SqliteProviderStore` is separately exported
 from `@poppykit/client/provider/sqlite`. Neither is loaded by the core import.
-This is PoppyKit provider contract **v1**, not a Personal Agent Protocol extension.
+The wire protocol remains PoppyKit provider **v1**; the 0.2 TypeScript API uses async storage, not a Personal Agent Protocol extension.
 Node 24.12+ is required for the SQLite reference adapter.
 
 An operator supplies HTTPS hosting, a provider client metadata URL, JWKS URL,
@@ -65,7 +75,7 @@ issuer, and exactly one code/error; result ciphertext is sealed atomically with
 the immutable binding. Identical pending callbacks are harmless; conflicting,
 canceled, expired and consumed callbacks fail. `takeResult` requires enrollment,
 installation, operation, issuer and exact session; it consumes within the same
-SQLite transaction before returning private callback data. Lost retrieval delivery
+storage transaction before returning private callback data. Lost retrieval delivery
 is uncertain, never a reason to exchange or retrieve again. SDK code owns PKCE and
 the exchange. Never log request URLs or responses on this route.
 
@@ -97,3 +107,26 @@ Account Tokens or DPoP keys. Revoke company authorization **before** disabling
 provider signing, or use authenticated company account controls afterward.
 This is scoped authority, redaction and provider key custody; it does not isolate
 authority from unrestricted programs running as the same OS user.
+
+## Migrating provider code to 0.2
+
+Await every provider operation, including `callback`, `takeResult`, `cancel` and
+`revokeEnrollment`; HTTP callback success is returned only after storage commits.
+Use rejected-Promise assertions for failures. Signer, enrollment authentication,
+metadata and session verification stay outside storage transactions; ResultCipher
+remains synchronous local cryptography.
+
+`ProviderSelection` declares enroll, identity, operation, begin, callback or revoke.
+Remote stores load and lock only that aggregate; out-of-selection access and thenable
+callbacks reject. Enroll locks a namespace capacity counter; identity mapping locks
+visitor/full-issuer keys across installations; callbacks re-resolve state after the
+enrollment fence. Begin/revoke inspect at most 1,001 operation rows. All valid Unicode
+operation IDs count toward limits and revocation. Existing SQLite databases retain
+records and initialize the capacity counter from their enrollment rows.
+
+For an existing local synchronous custom store, explicitly wrap it with
+`adaptLegacyProviderStore(legacyStore)`. This migration helper ignores selections
+and cannot turn local synchronous I/O into remote persistence. New remote/custom
+stores implement the targeted contract directly. The bundled Postgres adapter is
+`PostgresProviderStore` from `@poppykit/client/provider/postgres`; see
+[storage](STORAGE.md) for explicit migrations, TLS and lifecycle.

package/README.md

@@ -6,11 +6,13 @@ application supplies the agent and trusted infrastructure. [MIT](LICENSE).
 
 ## Install
 
+Version 0.3.0 is a release candidate until its publishing workflow completes.
+
 Requires Node **24.12.0+**, ESM and HTTPS. CI tests Node 24.12.0 on Linux, macOS and
 Windows; later majors are not separately certified.
 
 ```sh
-npm install @poppykit/client@0.1.1
+npm install @poppykit/client@0.3.0
 ```
 
 ## Discover a company

package/STORAGE.md

@@ -94,3 +94,63 @@ checkpoints are retained until explicit local deletion; pending/uncertain retrie
 must first be reconciled. Checkpoint acknowledgements use compare-and-set and do
 not acknowledge merely because a page or stream frame was read. Local deletion
 never deletes company history, revokes access or cancels accepted business work.
+
+## Postgres (0.2 API)
+
+The optional `@poppykit/client/postgres` exports `PostgresAuthStore` and
+`PostgresConversationStore`; `/provider/postgres` exports `PostgresProviderStore`.
+Install the optional peer `pg@8.23.1` only when choosing these subpaths.
+Protocol-only imports load neither pg nor SQLite. PostgreSQL 17 and Node 24.12+
+are supported; plain PostgreSQL and Supabase transaction pooling use the same adapter.
+There is no Supabase Auth or application dependency.
+
+```ts
+import { createPostgresPool, migratePostgres, PostgresAuthStore,
+  PostgresConversationStore } from '@poppykit/client/postgres';
+import { PostgresProviderStore } from '@poppykit/client/provider/postgres';
+const pool = createPostgresPool({ connectionString: process.env.DATABASE_URL });
+// Explicit deployment administration, once before accepting traffic:
+await migratePostgres(pool, 'poppy_client');
+await migratePostgres(pool, 'poppy_provider');
+const auth = new PostgresAuthStore(pool, 'installation:user');
+const conversations = new PostgresConversationStore(pool, 'installation:user');
+const provider = new PostgresProviderStore(pool, 'provider-instance');
+// After requests finish:
+await auth.close(); await conversations.close(); await provider.close();
+await pool.end();
+```
+
+A supplied pool belongs to the caller: adapter `close` stops that adapter and
+never ends the pool. `createPostgresPool` returns a pool owned by its caller.
+Defaults: two connections, 3s acquisition, 10s idle, verified TLS. Supply a CA via
+`ssl: { ca, rejectUnauthorized: true }` for a private root. TLS URL overrides and
+`rejectUnauthorized: false` are rejected; `ssl: false` is an explicit trusted-local
+server choice. Caller-created pools are the caller's responsibility. Queries are
+unnamed/parameterized, and each transaction uses one checked-out connection.
+Transaction/statement limits are 5s and lock waits 2s. No session locks, named
+prepared statements, LISTEN or session state are required by transaction pooling.
+Do not perform HTTP, model or KMS calls in storage callbacks.
+
+Versioned SQL ships at `migrations/postgres/0001_poppy_client.sql` and
+`0001_poppy_provider.sql`. `postgresMigration(schema)` returns its SQL for review;
+`migratePostgres` explicitly applies it atomically or accepts existing version 1.
+Construction/request paths never create or upgrade schemas. Unknown/missing
+versions fail closed. Version checks do not certify arbitrary operator edits to
+table definitions: inspect deployment migration history and stop on schema drift.
+Applied migration files are immutable; corrections require a new migration/version.
+Keep SQL and the deployment's applied-migration ledger under version control.
+Back up and rehearse before applying to durable data. Roll back application code
+only to a compatible schema/API; restore a reviewed backup for destructive reversal.
+No automatic SQLite import, live reset, schema drop or downgrade is supplied.
+
+Auth uses its namespace owner/epoch fence and indexed connection/operation selectors.
+Provider uses indexed enrollment/state/mapping selectors, an atomic capacity counter,
+and bounded per-enrollment operations. These are individual row records, not a
+whole-database snapshot. `cleanup` preserves pending/uncertain auth operations.
+Namespaces are constructor configuration, never request-supplied authority.
+
+Custom backends can run `runClientConversationAdapterContract` and
+`runProviderAdapterContract` from `@poppykit/client/adapter-contract` with two
+handles to a fresh shared namespace. Real process death and engine atomicity still
+need backend-specific checks. Database credentials and encryption keys stay outside
+records, prompts and logs; provider callback URLs remain encrypted by ResultCipher.

package/dist/adapter-contract.d.ts

@@ -0,0 +1,15 @@
+import type { ConversationStore } from './conversation-store.js';
+import type { ProviderStore } from './provider.js';
+export type ClientConversationAdapterFixture = () => Promise<{
+    store: ConversationStore;
+    second: ConversationStore;
+    close(): Promise<void>;
+}>;
+export type ProviderAdapterFixture = () => Promise<{
+    store: ProviderStore;
+    second: ProviderStore;
+    close(): Promise<void>;
+}>;
+/** Run against two handles sharing a fresh namespace; real engine/process tests remain the host's responsibility. */
+export declare function runClientConversationAdapterContract(fixture: ClientConversationAdapterFixture): void;
+export declare function runProviderAdapterContract(fixture: ProviderAdapterFixture): void;

package/dist/adapter-contract.js

@@ -0,0 +1,48 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+/** Run against two handles sharing a fresh namespace; real engine/process tests remain the host's responsibility. */
+export function runClientConversationAdapterContract(fixture) {
+    test('client adapter contract: atomic receipt preparation, terminal settlement and checkpoint compare-and-swap', async () => {
+        const f = await fixture();
+        try {
+            const key = { connectionId: 'contract', issuer: 'https://issuer.example/one', endpoint: 'https://company.example/conversations' };
+            const row = { ...key, id: 'message', fingerprint: 'original', phase: 'pending', target: null, request: { message: { id: 'message', sender: 'agent', text: 'hello' } } };
+            const saved = await Promise.all([f.store.prepareOutbound(key, row), f.second.prepareOutbound(key, { ...row, fingerprint: 'changed' })]);
+            assert.equal(saved[0].fingerprint, saved[1].fingerprint);
+            saved[0].request.message.text = 'mutated';
+            assert.equal((await f.second.getOutbound(key, row.id))?.request.message.text, 'hello');
+            await f.store.settleOutbound(key, row.id, { phase: 'accepted', response: { conversation_id: 'conversation', status: 'idle', responder: 'agent' } });
+            await f.second.settleOutbound(key, row.id, { phase: 'rejected', error: { code: 'invalid_request', status: 400 } });
+            assert.equal((await f.store.getOutbound(key, row.id))?.phase, 'accepted');
+            await assert.rejects(f.store.settleOutbound({ ...key, endpoint: 'https://other.example/conversations' }, row.id, { phase: 'accepted' }));
+            assert.equal(await f.store.getOutbound({ ...key, issuer: 'https://issuer.example/two' }, row.id), undefined);
+            const checkpoint = { connectionId: key.connectionId, issuer: key.issuer, conversationId: 'conversation', name: 'consumer', cursor: 'one' };
+            await Promise.all([f.store.advanceCheckpoint(key, checkpoint, [undefined]), f.second.advanceCheckpoint(key, { ...checkpoint, cursor: 'two' }, [undefined])]);
+            const current = await f.store.getCheckpoint(key, 'conversation', 'consumer');
+            assert.ok(current === 'one' || current === 'two');
+            await f.second.advanceCheckpoint(key, { ...checkpoint, cursor: 'stale' }, [undefined]);
+            assert.equal(await f.store.getCheckpoint(key, 'conversation', 'consumer'), current);
+        }
+        finally {
+            await f.close();
+        }
+    });
+}
+export function runProviderAdapterContract(fixture) {
+    test('provider adapter contract: capacity races, detached results, rollback and selection boundaries', async () => {
+        const f = await fixture(), selection = { kind: 'enroll', subjectHash: 'subject', requestHash: 'request' };
+        try {
+            await Promise.all(Array.from({ length: 10 }, (_, i) => (i % 2 ? f.store : f.second).transaction(selection, tx => { tx.put('capacity', 'enrollments', { count: (tx.get('capacity', 'enrollments')?.count ?? 0) + 1 }); })));
+            const result = await f.store.transaction(selection, tx => tx.get('capacity', 'enrollments'));
+            assert.equal(result?.count, 10);
+            result.count = 999;
+            await assert.rejects(f.store.transaction(selection, tx => { tx.put('capacity', 'enrollments', { count: 0 }); throw new Error('rollback'); }), /rollback/);
+            await assert.rejects(f.store.transaction(selection, async (tx) => { tx.put('capacity', 'enrollments', { count: 0 }); }), /synchronous/);
+            await assert.rejects(f.store.transaction(selection, tx => tx.get('enrollment', 'foreign')), /outside selection/);
+            assert.equal((await f.second.transaction(selection, tx => tx.get('capacity', 'enrollments')))?.count, 10);
+        }
+        finally {
+            await f.close();
+        }
+    });
+}

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,39 @@
+import type { Pool } from 'pg';
+import type { ClientAuthState } from './auth/client-auth.js';
+import type { AuthSelection, AuthStore } from './auth/store.js';
+import type { ConversationKey, ConversationStore } from './conversation-store.js';
+import type { ConsumerCheckpoint, OutboundRecord } from './conversation.js';
+export { createPostgresPool, migratePostgres, postgresMigration, postgresSchemaVersion } from './postgres-runtime.js';
+/** Namespaced references only; credentials still belong in SecretStore. The pool remains caller-owned. */
+export declare class PostgresAuthStore implements AuthStore {
+    readonly namespace: string;
+    private readonly db;
+    constructor(pool: Pool, namespace: string);
+    close(): Promise<void>;
+    get metrics(): {
+        rowsRead: number;
+        rowsWritten: number;
+    };
+    private select;
+    read(selection: AuthSelection): Promise<ClientAuthState>;
+    transaction<T>(selection: AuthSelection, change: (draft: ClientAuthState) => T): Promise<T>;
+    private put;
+    pendingOperations(after: string | undefined, limit: number): Promise<string[]>;
+    cleanup(before: number, limit?: number): Promise<number>;
+}
+export declare class PostgresConversationStore implements ConversationStore {
+    readonly namespace: string;
+    private readonly db;
+    constructor(pool: Pool, namespace: string);
+    close(): Promise<void>;
+    private outbound;
+    getOutbound(key: ConversationKey, id: string): Promise<OutboundRecord | undefined>;
+    prepareOutbound(key: ConversationKey, record: OutboundRecord): Promise<OutboundRecord>;
+    settleOutbound(key: ConversationKey, id: string, result: Pick<OutboundRecord, 'phase' | 'response' | 'error'>): Promise<void>;
+    removeOutbound(key: ConversationKey, id: string): Promise<void>;
+    private checkpointValues;
+    private checkpoint;
+    getCheckpoint(key: ConversationKey, conversation: string, name: string): Promise<string | undefined>;
+    advanceCheckpoint(key: ConversationKey, row: ConsumerCheckpoint, from: readonly (string | undefined)[]): Promise<void>;
+    resetCheckpoint(key: ConversationKey, conversation: string, name: string): Promise<void>;
+}

package/dist/postgres.js

@@ -0,0 +1,143 @@
+import { initialClientAuthState } from './auth/client-auth.js';
+import { PostgresRuntime, json, synchronous } from './postgres-runtime.js';
+export { createPostgresPool, migratePostgres, postgresMigration, postgresSchemaVersion } from './postgres-runtime.js';
+const tables = ['identities', 'connections', 'grants', 'operations', 'cleanup'];
+/** Namespaced references only; credentials still belong in SecretStore. The pool remains caller-owned. */
+export class PostgresAuthStore {
+    namespace;
+    db;
+    constructor(pool, namespace) {
+        this.namespace = namespace;
+        this.db = new PostgresRuntime(pool, 'poppy_client');
+    }
+    close() { return this.db.close(); }
+    get metrics() { return this.db.metrics; }
+    async select(selection) {
+        // Epoch/owner are shared by this auth namespace and must fence every connection mutation.
+        await this.db.lock(`${this.namespace}:auth`);
+        const get = async (table, id) => (await this.db.query('SELECT body FROM poppy_client.records WHERE ns=$1 AND kind=$2 AND id=$3', [this.namespace, table, id]))[0];
+        const meta = await get('auth_meta', 'meta');
+        const initial = initialClientAuthState();
+        if (!meta)
+            await this.put('auth_meta', 'meta', { version: initial.version, epoch: initial.epoch, owner: initial.owner });
+        const state = { ...(meta ? JSON.parse(meta.body) : { version: initial.version, epoch: initial.epoch, owner: initial.owner }), identities: {}, connections: {}, grants: {}, operations: {}, cleanup: {} };
+        const one = async (table, id) => { const row = await get(table, id); if (row)
+            state[table][id] = JSON.parse(row.body); };
+        const rows = async (table, where, values = []) => {
+            for (const row of await this.db.query(`SELECT id,body FROM poppy_client.records WHERE ns=$1 AND kind=$2 ${where}`, [this.namespace, table, ...values]))
+                state[table][row.id] = JSON.parse(row.body);
+        };
+        if ('issuer' in selection)
+            await one('identities', selection.issuer);
+        else {
+            if ('connectionId' in selection)
+                await one('connections', selection.connectionId);
+            else if ('operationId' in selection)
+                await one('operations', selection.operationId);
+            else if ('callbackHash' in selection)
+                await rows('operations', "AND body::jsonb#>>'{direct,stateHash}'=$3", [selection.callbackHash]);
+            else
+                await rows('connections', '');
+            for (const operation of Object.values(state.operations))
+                await one('connections', operation.connectionId);
+            for (const connection of Object.values(state.connections)) {
+                if (connection.grantId)
+                    await one('grants', connection.grantId);
+                if (!('list' in selection)) {
+                    await rows('operations', "AND body::jsonb->>'connectionId'=$3", [connection.id]);
+                    await rows('cleanup', "AND body::jsonb->>'connectionId'=$3", [connection.id]);
+                }
+            }
+            for (const operation of Object.values(state.operations))
+                if (operation.grantId)
+                    await one('grants', operation.grantId);
+        }
+        return state;
+    }
+    read(selection) { return this.db.run(() => this.select(selection)); }
+    transaction(selection, change) {
+        return this.db.run(async () => {
+            const state = await this.select(selection), before = structuredClone(state), result = synchronous(change(state));
+            const { version, epoch, owner } = state;
+            await this.put('auth_meta', 'meta', { version, epoch, owner });
+            for (const table of tables) {
+                for (const id of Object.keys(before[table]))
+                    if (!Object.hasOwn(state[table], id))
+                        await this.db.query('DELETE FROM poppy_client.records WHERE ns=$1 AND kind=$2 AND id=$3', [this.namespace, table, id]);
+                for (const [id, value] of Object.entries(state[table]))
+                    if (json(value) !== json(before[table][id] ?? null))
+                        await this.put(table, id, value);
+            }
+            return result;
+        });
+    }
+    async put(kind, id, value) {
+        await this.db.query('INSERT INTO poppy_client.records(ns,kind,id,body) VALUES($1,$2,$3,$4) ON CONFLICT(ns,kind,id) DO UPDATE SET body=excluded.body', [this.namespace, kind, id, json(value)]);
+        this.db.metrics.rowsWritten++;
+    }
+    async pendingOperations(after, limit) {
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000)
+            throw new TypeError('recovery limit');
+        return this.db.run(async () => (await this.db.query("SELECT id FROM poppy_client.records WHERE ns=$1 AND kind='operations' AND body::jsonb->>'phase'!='terminal' AND id>$2 ORDER BY id LIMIT $3", [this.namespace, after ?? '', limit])).map(row => row.id));
+    }
+    async cleanup(before, limit = 100) {
+        if (!Number.isFinite(before) || !Number.isSafeInteger(limit) || limit < 1 || limit > 1000)
+            throw new TypeError('cleanup limit');
+        return this.db.run(async () => { await this.db.lock(`${this.namespace}:auth`); return (await this.db.query("DELETE FROM poppy_client.records WHERE ns=$1 AND kind='operations' AND id IN (SELECT id FROM poppy_client.records WHERE ns=$1 AND kind='operations' AND body::jsonb->>'phase'='terminal' AND body::jsonb->>'status'!='uncertain' AND (body::jsonb->>'createdAt')::double precision<$2 ORDER BY (body::jsonb->>'createdAt')::double precision LIMIT $3) RETURNING id", [this.namespace, before, limit])).length; });
+    }
+}
+export class PostgresConversationStore {
+    namespace;
+    db;
+    constructor(pool, namespace) {
+        this.namespace = namespace;
+        this.db = new PostgresRuntime(pool, 'poppy_client');
+    }
+    close() { return this.db.close(); }
+    async outbound(key, id) {
+        const row = (await this.db.query('SELECT body FROM poppy_client.outbound WHERE ns=$1 AND connection=$2 AND issuer=$3 AND id=$4', [this.namespace, key.connectionId, key.issuer, id]))[0];
+        return row ? JSON.parse(row.body) : undefined;
+    }
+    getOutbound(key, id) { return this.db.run(() => this.outbound(key, id)); }
+    async prepareOutbound(key, record) {
+        if (record.connectionId !== key.connectionId || record.issuer !== key.issuer || record.endpoint !== key.endpoint)
+            throw new TypeError('outbound binding');
+        return this.db.run(async () => {
+            await this.db.query('INSERT INTO poppy_client.outbound VALUES($1,$2,$3,$4,$5) ON CONFLICT DO NOTHING', [this.namespace, key.connectionId, key.issuer, record.id, json(record)]);
+            return (await this.outbound(key, record.id));
+        });
+    }
+    settleOutbound(key, id, result) {
+        return this.db.run(async () => {
+            await this.db.lock(JSON.stringify([this.namespace, 'outbound', key.connectionId, key.issuer, id]));
+            const record = await this.outbound(key, id);
+            if (!record || record.endpoint !== key.endpoint)
+                throw new TypeError('outbound binding');
+            if (record.phase === 'pending')
+                await this.db.query('UPDATE poppy_client.outbound SET body=$5 WHERE ns=$1 AND connection=$2 AND issuer=$3 AND id=$4', [this.namespace, key.connectionId, key.issuer, id, json({ ...record, ...result })]);
+        });
+    }
+    removeOutbound(key, id) {
+        return this.db.run(async () => {
+            await this.db.lock(JSON.stringify([this.namespace, 'outbound', key.connectionId, key.issuer, id]));
+            const record = await this.outbound(key, id);
+            if (record && record.endpoint !== key.endpoint)
+                throw new TypeError('outbound binding');
+            await this.db.query('DELETE FROM poppy_client.outbound WHERE ns=$1 AND connection=$2 AND issuer=$3 AND id=$4', [this.namespace, key.connectionId, key.issuer, id]);
+        });
+    }
+    checkpointValues(key, conversation, name) { return [this.namespace, key.connectionId, key.issuer, key.endpoint, conversation, name]; }
+    async checkpoint(key, conversation, name) { return (await this.db.query('SELECT cursor FROM poppy_client.checkpoints WHERE ns=$1 AND connection=$2 AND issuer=$3 AND endpoint=$4 AND conversation=$5 AND name=$6', this.checkpointValues(key, conversation, name)))[0]?.cursor; }
+    getCheckpoint(key, conversation, name) { return this.db.run(() => this.checkpoint(key, conversation, name)); }
+    async advanceCheckpoint(key, row, from) {
+        if (row.connectionId !== key.connectionId || row.issuer !== key.issuer)
+            throw new TypeError('checkpoint binding');
+        return this.db.run(async () => {
+            const values = this.checkpointValues(key, row.conversationId, row.name);
+            await this.db.lock(JSON.stringify(['checkpoint', ...values]));
+            if (from.includes(await this.checkpoint(key, row.conversationId, row.name)))
+                await this.db.query('INSERT INTO poppy_client.checkpoints VALUES($1,$2,$3,$4,$5,$6,$7) ON CONFLICT(ns,connection,issuer,endpoint,conversation,name) DO UPDATE SET cursor=excluded.cursor', [...values, row.cursor]);
+        });
+    }
+    resetCheckpoint(key, conversation, name) { return this.db.run(async () => { const values = this.checkpointValues(key, conversation, name); await this.db.lock(JSON.stringify(['checkpoint', ...values])); await this.db.query('DELETE FROM poppy_client.checkpoints WHERE ns=$1 AND connection=$2 AND issuer=$3 AND endpoint=$4 AND conversation=$5 AND name=$6', values); }); }
+}

package/dist/provider-postgres.d.ts

@@ -0,0 +1,15 @@
+import type { Pool } from 'pg';
+import type { ProviderSelection, ProviderStore, ProviderTransaction } from './provider.js';
+export { createPostgresPool, migratePostgres, postgresMigration, postgresSchemaVersion } from './postgres-runtime.js';
+/** Targeted provider aggregates. Cryptography and human/session verification run outside its transactions. */
+export declare class PostgresProviderStore implements ProviderStore {
+    readonly namespace: string;
+    private readonly db;
+    constructor(pool: Pool, namespace: string);
+    close(): Promise<void>;
+    get metrics(): {
+        rowsRead: number;
+        rowsWritten: number;
+    };
+    transaction<T>(selection: ProviderSelection, action: (tx: ProviderTransaction) => T): Promise<T>;
+}

package/dist/provider-postgres.js

@@ -0,0 +1,96 @@
+import { providerMemoryTransaction, providerUserKey, scopedProviderTransaction } from './provider-storage.js';
+import { PostgresRuntime, json, synchronous } from './postgres-runtime.js';
+export { createPostgresPool, migratePostgres, postgresMigration, postgresSchemaVersion } from './postgres-runtime.js';
+/** Targeted provider aggregates. Cryptography and human/session verification run outside its transactions. */
+export class PostgresProviderStore {
+    namespace;
+    db;
+    constructor(pool, namespace) {
+        this.namespace = namespace;
+        this.db = new PostgresRuntime(pool, 'poppy_provider');
+    }
+    close() { return this.db.close(); }
+    get metrics() { return this.db.metrics; }
+    transaction(selection, action) {
+        return this.db.run(async () => {
+            const rows = new Map();
+            const one = async (kind, id) => {
+                const row = (await this.db.query('SELECT body FROM poppy_provider.records WHERE ns=$1 AND kind=$2 AND id=$3', [this.namespace, kind, id]))[0];
+                const key = JSON.stringify([kind, id]);
+                rows.delete(key);
+                if (row)
+                    rows.set(key, JSON.parse(row.body));
+                return row ? JSON.parse(row.body) : undefined;
+            };
+            const lock = (kind, id) => this.db.lock(JSON.stringify([this.namespace, kind, id]));
+            if (selection.kind === 'enroll') {
+                await lock('capacity', 'enrollments');
+                await one('capacity', 'enrollments');
+                await one('visitor', selection.subjectHash);
+                await one('enrollmentRequest', selection.requestHash);
+            }
+            else {
+                const lookup = selection.kind === 'callback' ? await one('state', selection.stateHash) : undefined;
+                const enrollmentId = selection.kind === 'callback' ? lookup?.enrollmentId : selection.enrollmentId;
+                if (enrollmentId) {
+                    await lock('enrollment', enrollmentId);
+                    const enrollment = await one('enrollment', enrollmentId);
+                    if ('issuer' in selection && enrollment) {
+                        const key = providerUserKey(enrollment.visitor, selection.issuer);
+                        await lock('user', key);
+                        await one('user', key);
+                    }
+                    if (selection.kind === 'begin' || selection.kind === 'revoke') {
+                        const operations = await this.db.query("SELECT id,body FROM poppy_provider.records WHERE ns=$1 AND kind='operation' AND split_part(id,':',1)=$2 ORDER BY id LIMIT 1001", [this.namespace, enrollmentId]);
+                        for (const row of operations)
+                            rows.set(JSON.stringify(['operation', row.id]), JSON.parse(row.body));
+                        if (operations.length > 1000)
+                            throw new Error('provider aggregate exceeds retained operation limit');
+                        if (selection.kind === 'begin') {
+                            const states = new Set();
+                            if (selection.stateHash)
+                                states.add(selection.stateHash);
+                            for (const row of operations) {
+                                const hash = JSON.parse(row.body).binding?.stateHash;
+                                if (hash)
+                                    states.add(hash);
+                            }
+                            for (const hash of [...states].sort()) {
+                                await lock('state', hash);
+                                await one('state', hash);
+                            }
+                        }
+                    }
+                    else {
+                        if (selection.kind === 'callback') {
+                            // Re-resolve after the enrollment lock; cleanup may have removed/rebound the selector.
+                            const current = await one('state', selection.stateHash);
+                            if (json(current ?? null) !== json(lookup ?? null))
+                                throw new Error('provider callback selector changed');
+                        }
+                        const operationId = selection.kind === 'callback' ? lookup?.operationId : 'operationId' in selection ? selection.operationId : undefined;
+                        if (operationId)
+                            await one('operation', `${enrollmentId}:${operationId}`);
+                    }
+                }
+            }
+            const before = new Map([...rows].map(([key, value]) => [key, json(value)]));
+            const result = synchronous(action(scopedProviderTransaction(selection, providerMemoryTransaction(rows))));
+            const removed = [...before.keys()].filter(key => !rows.has(key)).map(key => { const [kind, id] = JSON.parse(key); return { kind, id }; });
+            if (removed.length)
+                await this.db.query('DELETE FROM poppy_provider.records r USING jsonb_to_recordset($2::jsonb) AS d(kind text,id text) WHERE r.ns=$1 AND r.kind=d.kind AND r.id=d.id', [this.namespace, json(removed)]);
+            const changed = [];
+            for (const [key, value] of rows) {
+                const body = json(value);
+                if (before.get(key) === body)
+                    continue;
+                const [kind, id] = JSON.parse(key);
+                changed.push({ kind, id, body });
+            }
+            if (changed.length)
+                await this.db.query('INSERT INTO poppy_provider.records(ns,kind,id,body) SELECT $1,kind,id,body FROM jsonb_to_recordset($2::jsonb) AS d(kind text,id text,body text) ON CONFLICT(ns,kind,id) DO UPDATE SET body=excluded.body', [this.namespace, json(changed)]);
+            this.metrics.rowsWritten += removed.length + changed.length;
+            return result;
+        });
+    }
+}

package/dist/provider-sqlite.d.ts

@@ -1,8 +1,8 @@
-import type { ProviderStore, ProviderTransaction } from './provider.js';
+import type { ProviderSelection, ProviderStore, ProviderTransaction } from './provider.js';
 /** Optional durable provider records. Callback results must be encrypted by the separately configured cipher. */
 export declare class SqliteProviderStore implements ProviderStore {
     private readonly db;
     constructor(path: string);
     close(): void;
-    transaction<T>(action: (tx: ProviderTransaction) => T): T;
+    transaction<T>(selection: ProviderSelection, action: (tx: ProviderTransaction) => T): Promise<T>;
 }

package/dist/provider-sqlite.js

@@ -1,26 +1,29 @@
 import { DatabaseSync } from 'node:sqlite';
 import { initializeSqlite } from './sqlite-init.js';
+import { scopedProviderTransaction } from './provider-storage.js';
 /** Optional durable provider records. Callback results must be encrypted by the separately configured cipher. */
 export class SqliteProviderStore {
     db;
     constructor(path) {
         this.db = new DatabaseSync(path);
         initializeSqlite(this.db, () => this.db.exec('PRAGMA busy_timeout=5000; PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL; CREATE TABLE IF NOT EXISTS provider_records(kind TEXT NOT NULL,id TEXT NOT NULL,body TEXT NOT NULL,PRIMARY KEY(kind,id));'));
+        this.db.exec(`INSERT OR IGNORE INTO provider_records SELECT 'capacity','enrollments',json_object('count',count(*)) FROM provider_records WHERE kind='enrollment'`);
     }
     close() { this.db.close(); }
-    transaction(action) {
+    async transaction(selection, action) {
         this.db.exec('BEGIN IMMEDIATE');
         try {
-            const result = action({
+            const result = action(scopedProviderTransaction(selection, {
                 get: (kind, id) => { const row = this.db.prepare('SELECT body FROM provider_records WHERE kind=? AND id=?').get(kind, id); return row ? JSON.parse(row.body) : undefined; },
                 put: (kind, id, value) => { this.db.prepare('INSERT OR REPLACE INTO provider_records VALUES (?,?,?)').run(kind, id, JSON.stringify(value)); },
                 remove: (kind, id) => { this.db.prepare('DELETE FROM provider_records WHERE kind=? AND id=?').run(kind, id); },
-                list: (kind, prefix, limit) => this.db.prepare('SELECT id,body FROM provider_records WHERE kind=? AND id>=? AND id<? ORDER BY id LIMIT ?').all(kind, prefix, `${prefix}\uffff`, limit).map(row => ({ id: row.id, value: JSON.parse(row.body) })),
-            });
-            if (result instanceof Promise)
+                list: (kind, prefix, limit) => this.db.prepare('SELECT id,body FROM provider_records WHERE kind=? AND id>=? AND id<? ORDER BY id LIMIT ?').all(kind, prefix, `${prefix.slice(0, -1)};`, limit).map(row => ({ id: row.id, value: JSON.parse(row.body) })),
+            }));
+            if (result && typeof result.then === 'function')
                 throw new TypeError('provider transaction must be synchronous');
+            const detached = structuredClone(result);
             this.db.exec('COMMIT');
-            return result;
+            return detached;
         }
         catch (error) {
             this.db.exec('ROLLBACK');

package/dist/provider-storage.d.ts

@@ -0,0 +1,7 @@
+import type { ProviderSelection, ProviderTransaction } from './provider.js';
+type Row = Record<string, any>;
+export declare const providerUserKey: (visitor: string, issuer: string) => string;
+/** Enforces the same aggregate boundary for local, remote and custom stores. */
+export declare function scopedProviderTransaction(selection: ProviderSelection, raw: ProviderTransaction): ProviderTransaction;
+export declare function providerMemoryTransaction(rows: Map<string, Row>): ProviderTransaction;
+export {};

package/dist/provider-storage.js

@@ -0,0 +1,61 @@
+import { createHash } from 'node:crypto';
+export const providerUserKey = (visitor, issuer) => createHash('sha256').update(JSON.stringify([visitor, issuer])).digest('base64url');
+/** Enforces the same aggregate boundary for local, remote and custom stores. */
+export function scopedProviderTransaction(selection, raw) {
+    let enrollmentId = 'enrollmentId' in selection ? selection.enrollmentId : undefined;
+    let operationId = 'operationId' in selection ? selection.operationId : undefined;
+    if (selection.kind === 'callback') {
+        const lookup = raw.get('state', selection.stateHash);
+        enrollmentId = lookup?.enrollmentId;
+        operationId = lookup?.operationId;
+    }
+    const enrollment = enrollmentId ? raw.get('enrollment', enrollmentId) : undefined;
+    const userKey = 'issuer' in selection && enrollment ? providerUserKey(enrollment.visitor, selection.issuer) : undefined;
+    const states = new Set();
+    if (selection.kind === 'callback')
+        states.add(selection.stateHash);
+    if (selection.kind === 'begin') {
+        if (selection.stateHash)
+            states.add(selection.stateHash);
+        for (const row of raw.list('operation', `${enrollmentId}:`, 1001))
+            if (row.value.binding?.stateHash)
+                states.add(row.value.binding.stateHash);
+    }
+    let createdEnrollment;
+    const check = (kind, id, write = false) => {
+        let allowed = false;
+        if (selection.kind === 'enroll') {
+            allowed = (kind === 'capacity' && id === 'enrollments') || (kind === 'visitor' && id === selection.subjectHash) || (kind === 'enrollmentRequest' && id === selection.requestHash);
+            if (kind === 'enrollment' && write && (!createdEnrollment || createdEnrollment === id) && !raw.get(kind, id)) {
+                createdEnrollment = id;
+                allowed = true;
+            }
+        }
+        else {
+            allowed = (kind === 'enrollment' && id === enrollmentId) || (kind === 'user' && id === userKey) || (kind === 'state' && states.has(id));
+            if (kind === 'operation')
+                allowed = (selection.kind === 'begin' || selection.kind === 'revoke') ? id.startsWith(`${enrollmentId}:`) : id === `${enrollmentId}:${operationId}`;
+        }
+        if (!allowed)
+            throw new TypeError('provider access outside selection');
+    };
+    return {
+        get(kind, id) { check(kind, id); return raw.get(kind, id); },
+        put(kind, id, value) { check(kind, id, true); raw.put(kind, id, value); },
+        remove(kind, id) { check(kind, id); raw.remove(kind, id); },
+        list(kind, prefix, limit) {
+            if (!['begin', 'revoke'].includes(selection.kind) || kind !== 'operation' || prefix !== `${enrollmentId}:` || !Number.isSafeInteger(limit) || limit < 1 || limit > 1001)
+                throw new TypeError('provider list outside selection');
+            return raw.list(kind, prefix, limit);
+        },
+    };
+}
+export function providerMemoryTransaction(rows) {
+    const key = (kind, id) => JSON.stringify([kind, id]);
+    return {
+        get: (kind, id) => rows.get(key(kind, id)),
+        put: (kind, id, value) => { rows.set(key(kind, id), value); },
+        remove: (kind, id) => { rows.delete(key(kind, id)); },
+        list: (kind, prefix, limit) => [...rows].map(([key, value]) => ({ key: JSON.parse(key), value })).filter(row => row.key[0] === kind && row.key[1].startsWith(prefix)).sort((a, b) => a.key[1].localeCompare(b.key[1])).slice(0, limit).map(row => ({ id: row.key[1], value: row.value })),
+    };
+}

package/dist/provider.d.ts

@@ -11,10 +11,40 @@ export interface ProviderTransaction {
         value: Row;
     }[];
 }
-/** Must commit synchronously, atomically across processes; callback must not perform I/O. */
+export type ProviderSelection = {
+    kind: 'enroll';
+    subjectHash: string;
+    requestHash: string;
+} | {
+    kind: 'identity';
+    enrollmentId: string;
+    issuer: string;
+} | {
+    kind: 'operation';
+    enrollmentId: string;
+    operationId: string;
+} | {
+    kind: 'begin';
+    enrollmentId: string;
+    operationId: string;
+    issuer: string;
+    stateHash?: string;
+    at: number;
+} | {
+    kind: 'callback';
+    stateHash: string;
+} | {
+    kind: 'revoke';
+    enrollmentId: string;
+};
+/** Atomic asynchronous I/O around a pure synchronous, selection-bounded callback. */
 export interface ProviderStore {
-    transaction<T>(action: (tx: ProviderTransaction) => T): T;
+    transaction<T>(selection: ProviderSelection, action: (tx: ProviderTransaction) => T): Promise<T>;
 }
+/** Explicit migration aid for existing local synchronous stores; unsuitable for remote I/O. */
+export declare function adaptLegacyProviderStore(store: {
+    transaction<T>(action: (tx: ProviderTransaction) => T): T;
+}): ProviderStore;
 export interface ResultCipher {
     seal(value: string): string;
     open(value: string): string;
@@ -70,22 +100,22 @@ export declare function createProvider(options: ProviderOptions): {
         assertion: string;
         expiresAt: number;
     }>;
-    callback(callbackUrl: string): {
+    callback(callbackUrl: string): Promise<{
         status: string;
-    };
-    takeResult(credential: string, input: Row): {
+    }>;
+    takeResult(credential: string, input: Row): Promise<{
         status: string;
         callbackUrl?: undefined;
     } | {
         status: string;
         callbackUrl: string;
-    };
-    cancel(credential: string, input: Row): {
+    }>;
+    cancel(credential: string, input: Row): Promise<{
         status: string;
-    };
-    revokeEnrollment(credential: string, input: Row): {
+    }>;
+    revokeEnrollment(credential: string, input: Row): Promise<{
         status: string;
-    };
+    }>;
     handle(request: Request): Promise<Response>;
 };
 /** Bound trusted adapter: credentials/assertions/results never belong in harness output. */
@@ -118,4 +148,30 @@ export declare function createProviderClient(options: {
     cancel: (operationId: string) => Promise<Row>;
     revokeEnrollment: () => Promise<Row>;
 };
+/** Browser enrollment is an optional host service, separate from company consent. Keep verifier/results in trusted custody. */
+export declare function createBrowserEnrollmentClient(options: {
+    url: string;
+    provider: string;
+    company: string;
+    installationId: string;
+    transport: HttpTransport;
+}): {
+    start(challenge: string): Promise<{
+        requestId: string;
+        browserUrl: string;
+        expiresAt: number;
+    }>;
+    status(requestId: string, verifier: string): Promise<{
+        status: "pending" | "denied";
+        credential?: undefined;
+        clientId?: undefined;
+        callbackUrl?: undefined;
+    } | {
+        status: "ready";
+        credential: string;
+        clientId: string;
+        callbackUrl: string;
+    }>;
+    cancel: (requestId: string, verifier: string) => Promise<Row>;
+};
 export {};

package/dist/provider.js

@@ -1,6 +1,17 @@
 /** Optional PoppyKit provider v1. Hosting, human authentication and key custody belong to the operator. */
 import { createHash, randomBytes, createCipheriv, createDecipheriv } from 'node:crypto';
 import { secureUrl } from './network/transport.js';
+/** Explicit migration aid for existing local synchronous stores; unsuitable for remote I/O. */
+export function adaptLegacyProviderStore(store) {
+    return { async transaction(_selection, action) {
+            return store.transaction(tx => {
+                const result = action(tx);
+                if (result && typeof result.then === 'function')
+                    throw new TypeError('provider transaction must be synchronous');
+                return structuredClone(result);
+            });
+        } };
+}
 export function createResultCipher(key) {
     if (key.length !== 32)
         throw new Error('provider encryption key must be 32 bytes');
@@ -85,10 +96,12 @@ export function createProvider(options) {
         starts.push(now());
         tx.put('enrollment', enrollment.enrollmentId, { ...enrollment, starts });
     }
-    function authorizeCompany(credential, input) {
+    const enrollmentId = (credential) => credential.split('.')[0] ?? '';
+    const selectedOperation = (credential, input) => ({ kind: 'operation', enrollmentId: enrollmentId(credential), operationId: text(input.operationId) });
+    async function authorizeCompany(credential, input) {
         const domain = text(input.domain);
         text(input.issuer);
-        store.transaction(tx => { const enrollment = auth(tx, credential, text(input.installationId)); if (!enrollment.allowedCompanies.includes(domain))
+        await store.transaction({ kind: 'identity', enrollmentId: enrollmentId(credential), issuer: input.issuer }, tx => { const enrollment = auth(tx, credential, text(input.installationId)); if (!enrollment.allowedCompanies.includes(domain))
             fail('unauthorized'); });
     }
     const api = {
@@ -98,12 +111,14 @@ export function createProvider(options) {
             if (!human?.subject || !human.allowedCompanies.length)
                 fail('unauthorized');
             const installationId = text(input.installationId), key = hash(JSON.stringify([human.subject, text(input.idempotencyKey)]));
-            return store.transaction(tx => {
+            return store.transaction({ kind: 'enroll', subjectHash: hash(human.subject), requestHash: key }, tx => {
                 if (tx.get('enrollmentRequest', key))
                     fail('consumed'); // Credential delivery cannot be replayed from a verifier.
                 const subjectKey = hash(human.subject), visitor = tx.get('visitor', subjectKey)?.id ?? id();
-                if (tx.list('enrollment', '', (options.maxEnrollments ?? 10000) + 1).length >= (options.maxEnrollments ?? 10000))
+                const count = tx.get('capacity', 'enrollments')?.count ?? 0;
+                if (count >= (options.maxEnrollments ?? 10000))
                     throw new ProviderError('rate_limited', now() + 60000);
+                tx.put('capacity', 'enrollments', { count: count + 1 });
                 tx.put('visitor', subjectKey, { id: visitor });
                 const enrollmentId = id(), secret = id();
                 tx.put('enrollment', enrollmentId, { installationId, visitor, verifier: hash(secret), allowedCompanies: [...new Set(human.allowedCompanies)], revoked: false, starts: [] });
@@ -113,9 +128,9 @@ export function createProvider(options) {
         },
         async identity(credential, input) {
             exact(input, ['version', 'installationId', 'domain', 'issuer']);
-            authorizeCompany(credential, input);
+            await authorizeCompany(credential, input);
             const metadata = await verified(text(input.domain), text(input.issuer));
-            return store.transaction(tx => {
+            return store.transaction({ kind: 'identity', enrollmentId: enrollmentId(credential), issuer: input.issuer }, tx => {
                 const enrollment = auth(tx, credential, text(input.installationId));
                 if (!enrollment.allowedCompanies.includes(metadata.document.organization.domain))
                     fail('unauthorized');
@@ -129,7 +144,7 @@ export function createProvider(options) {
             text(input.operationId);
             if (input.sessionId !== undefined)
                 text(input.sessionId);
-            authorizeCompany(credential, input);
+            await authorizeCompany(credential, input);
             if (input.purpose === 'client-authentication' && (input.sessionId !== undefined || input.returnTo !== undefined))
                 fail('binding_conflict');
             if (input.purpose !== 'browser' && input.returnTo !== undefined)
@@ -145,7 +160,7 @@ export function createProvider(options) {
             const metadata = await verified(text(input.domain), text(input.issuer));
             if (input.purpose === 'browser' && (!onDomain(input.returnTo, metadata.document.organization.domain) || !metadata.document.web?.browser_session_endpoint))
                 fail('binding_conflict');
-            const identity = store.transaction(tx => {
+            const identity = await store.transaction({ kind: 'identity', enrollmentId: enrollmentId(credential), issuer: input.issuer }, tx => {
                 const enrollment = auth(tx, credential, text(input.installationId));
                 if (!enrollment.allowedCompanies.includes(metadata.document.organization.domain))
                     fail('unauthorized');
@@ -154,7 +169,7 @@ export function createProvider(options) {
             if (input.purpose === 'browser' && !await options.verifySession?.({ clientId: options.clientId, userId: identity.userId, issuer: input.issuer, sessionId: input.sessionId }))
                 fail('unauthorized');
             const binding = { issuer: input.issuer, domain: metadata.document.organization.domain, purpose: input.purpose, sessionId: input.sessionId ?? null, returnTo: input.returnTo ?? null, stateHash: input.state ? hash(input.state) : null, userId: identity.userId, browserEndpoint: metadata.document.web?.browser_session_endpoint ?? null };
-            return store.transaction(tx => {
+            return store.transaction({ kind: 'begin', enrollmentId: enrollmentId(credential), operationId: input.operationId, issuer: input.issuer, ...(binding.stateHash ? { stateHash: binding.stateHash } : {}), at: now() }, tx => {
                 const enrollment = auth(tx, credential, text(input.installationId)), key = `${enrollment.enrollmentId}:${text(input.operationId)}`, existing = tx.get('operation', key);
                 if (existing) {
                     if (!same(existing.binding, binding))
@@ -186,7 +201,7 @@ export function createProvider(options) {
         },
         async assert(credential, input) {
             exact(input, ['version', 'installationId', 'operationId', 'purpose']);
-            const snapshot = store.transaction(tx => {
+            const snapshot = await store.transaction(selectedOperation(credential, input), tx => {
                 const enrollment = auth(tx, credential, text(input.installationId)), op = operation(tx, enrollment, text(input.operationId));
                 if (op.binding.purpose !== input.purpose || !['client-authentication', 'session', 'browser'].includes(input.purpose))
                     fail('binding_conflict');
@@ -206,17 +221,17 @@ export function createProvider(options) {
             if (signature.length !== 64)
                 fail('unavailable');
             // A revoke/cancel racing external KMS signing wins before the assertion leaves the provider.
-            store.transaction(tx => { const enrollment = auth(tx, credential, input.installationId), op = operation(tx, enrollment, input.operationId); tx.put('operation', `${enrollment.enrollmentId}:${input.operationId}`, { ...op, status: 'signed' }); });
+            await store.transaction(selectedOperation(credential, input), tx => { const enrollment = auth(tx, credential, input.installationId), op = operation(tx, enrollment, input.operationId); tx.put('operation', `${enrollment.enrollmentId}:${input.operationId}`, { ...op, status: 'signed' }); });
             return { assertion: `${unsigned}.${Buffer.from(signature).toString('base64url')}`, expiresAt: exp };
         },
-        callback(callbackUrl) {
+        async callback(callbackUrl) {
             const url = new URL(callbackUrl), base = new URL(options.callbackUrl);
             if (url.origin !== base.origin || url.pathname !== base.pathname || url.username || url.password || url.hash || [...url.searchParams.keys()].some(key => !['state', 'iss', 'code', 'error'].includes(key)) || ['state', 'iss', 'code', 'error'].some(key => url.searchParams.getAll(key).length > 1))
                 fail('binding_conflict');
             const state = text(url.searchParams.get('state')), issuer = text(url.searchParams.get('iss'));
             if (!!url.searchParams.get('code') === !!url.searchParams.get('error') || callbackUrl.length > 8192)
                 fail('binding_conflict');
-            return store.transaction(tx => {
+            return store.transaction({ kind: 'callback', stateHash: hash(state) }, tx => {
                 const lookup = tx.get('state', hash(state));
                 if (!lookup)
                     fail('binding_conflict');
@@ -236,9 +251,9 @@ export function createProvider(options) {
                 return { status: 'ready' };
             });
         },
-        takeResult(credential, input) {
+        async takeResult(credential, input) {
             exact(input, ['version', 'installationId', 'operationId', 'issuer', 'sessionId']);
-            return store.transaction(tx => {
+            return store.transaction(selectedOperation(credential, input), tx => {
                 const enrollment = auth(tx, credential, text(input.installationId)), op = operation(tx, enrollment, text(input.operationId));
                 if (op.binding.issuer !== input.issuer || op.binding.sessionId !== input.sessionId || op.binding.purpose !== 'direct')
                     fail('binding_conflict');
@@ -249,9 +264,9 @@ export function createProvider(options) {
                 return { status: 'completed', callbackUrl };
             });
         },
-        cancel(credential, input) {
+        async cancel(credential, input) {
             exact(input, ['version', 'installationId', 'operationId']);
-            return store.transaction(tx => {
+            return store.transaction(selectedOperation(credential, input), tx => {
                 const enrollment = auth(tx, credential, text(input.installationId)), key = `${enrollment.enrollmentId}:${text(input.operationId)}`, op = tx.get('operation', key);
                 if (!op)
                     fail('binding_conflict');
@@ -259,9 +274,9 @@ export function createProvider(options) {
                 return { status: 'canceled' };
             });
         },
-        revokeEnrollment(credential, input) {
+        async revokeEnrollment(credential, input) {
             exact(input, ['version', 'installationId']);
-            return store.transaction(tx => {
+            return store.transaction({ kind: 'revoke', enrollmentId: enrollmentId(credential) }, tx => {
                 const enrollment = auth(tx, credential, text(input.installationId));
                 tx.put('enrollment', enrollment.enrollmentId, { ...enrollment, revoked: true });
                 for (const row of tx.list('operation', `${enrollment.enrollmentId}:`, 1000))
@@ -278,7 +293,7 @@ export function createProvider(options) {
                     return Response.json({ keys: (options.publishedKeys ? await options.publishedKeys() : [{ ...await options.signer.publicJwk(), kid: options.signer.kid }]).map(publicKey) }, { headers });
                 const url = new URL(request.url);
                 if (url.origin === new URL(options.callbackUrl).origin && url.pathname === new URL(options.callbackUrl).pathname && request.method === 'GET') {
-                    api.callback(request.url);
+                    await api.callback(request.url);
                     return Response.json({ status: 'received' }, { headers });
                 }
                 if (request.method !== 'POST' || !request.headers.get('content-type')?.startsWith('application/json'))
@@ -340,3 +355,42 @@ export function createProviderClient(options) {
         takeResult: (input) => call('takeResult', input),
         cancel: (operationId) => call('cancel', { operationId }), revokeEnrollment: () => call('revokeEnrollment', {}) };
 }
+/** Browser enrollment is an optional host service, separate from company consent. Keep verifier/results in trusted custody. */
+export function createBrowserEnrollmentClient(options) {
+    const base = https(options.url), provider = https(options.provider);
+    if (base.search || base.hash || provider.origin !== base.origin)
+        throw new TypeError('enrollment and provider must share origin');
+    async function call(action, input) {
+        const response = await options.transport.fetch(new Request(`${base.href.replace(/\/$/, '')}/${action}`, {
+            method: 'POST', headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ version: 1, installationId: options.installationId, provider: options.provider, company: options.company, ...input }),
+        }));
+        const body = object(await response.json());
+        if (!response.ok)
+            throw new ProviderError(['unauthorized', 'binding_conflict', 'expired', 'consumed', 'canceled', 'rate_limited'].includes(body.error) ? body.error : 'unavailable');
+        return body;
+    }
+    return {
+        async start(challenge) {
+            if (!/^[\w-]{43}$/.test(challenge))
+                throw new TypeError('enrollment challenge');
+            const body = await call('start', { challenge });
+            const browser = https(text(body.browserUrl));
+            if (browser.origin !== base.origin || typeof body.expiresAt !== 'number' || !/^[\w-]{43}$/.test(body.requestId))
+                fail('binding_conflict');
+            return { requestId: body.requestId, browserUrl: browser.href, expiresAt: body.expiresAt };
+        },
+        async status(requestId, verifier) {
+            const body = await call('status', { requestId, verifier });
+            if (!['pending', 'denied', 'ready'].includes(body.status))
+                fail('binding_conflict');
+            if (body.status !== 'ready')
+                return { status: body.status };
+            const clientId = https(text(body.clientId)).href, callbackUrl = https(text(body.callbackUrl)).href;
+            if (new URL(clientId).origin !== provider.origin || new URL(callbackUrl).origin !== provider.origin)
+                fail('binding_conflict');
+            return { status: 'ready', credential: text(body.credential), clientId, callbackUrl };
+        },
+        cancel: (requestId, verifier) => call('cancel', { requestId, verifier }),
+    };
+}

package/migrations/postgres/0001_poppy_client.sql

@@ -0,0 +1,16 @@
+CREATE SCHEMA poppy_client;
+CREATE TABLE poppy_client.schema_version (version integer PRIMARY KEY CHECK(version > 0));
+INSERT INTO poppy_client.schema_version VALUES (1);
+CREATE TABLE poppy_client.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_client.records (ns,kind,(body::jsonb->>'conversationId'));
+CREATE INDEX by_binding ON poppy_client.records (ns,kind,(body::jsonb->>'bindingId'));
+CREATE INDEX by_client ON poppy_client.records (ns,kind,(body::jsonb->>'clientId'));
+CREATE INDEX by_account ON poppy_client.records (ns,kind,(body::jsonb->>'accountId'));
+CREATE INDEX by_grant ON poppy_client.records (ns,kind,(body::jsonb->>'grantId'));
+CREATE INDEX by_phase ON poppy_client.records (ns,kind,(body::jsonb->>'phase'));
+CREATE INDEX by_expiry ON poppy_client.records (ns,kind,((body::jsonb->>'expiresAt')::double precision));
+CREATE INDEX by_connection ON poppy_client.records (ns,kind,(body::jsonb->>'connectionId'));
+CREATE INDEX by_callback ON poppy_client.records (ns,kind,(body::jsonb#>>'{direct,stateHash}'));
+CREATE TABLE poppy_client.outbound (ns text NOT NULL, connection text NOT NULL, issuer text NOT NULL, id text NOT NULL, body text NOT NULL, PRIMARY KEY(ns,connection,issuer,id));
+CREATE TABLE poppy_client.checkpoints (ns text NOT NULL, connection text NOT NULL, issuer text NOT NULL, endpoint text NOT NULL, conversation text NOT NULL, name text NOT NULL, cursor text NOT NULL, PRIMARY KEY(ns,connection,issuer,endpoint,conversation,name));
+CREATE UNIQUE INDEX auth_callback ON poppy_client.records(ns,((body::jsonb)#>>'{direct,stateHash}')) WHERE kind='operations';

package/migrations/postgres/0001_poppy_provider.sql

@@ -0,0 +1,14 @@
+CREATE SCHEMA poppy_provider;
+CREATE TABLE poppy_provider.schema_version (version integer PRIMARY KEY CHECK(version > 0));
+INSERT INTO poppy_provider.schema_version VALUES (1);
+CREATE TABLE poppy_provider.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 operations_enrollment ON poppy_provider.records(ns,(split_part(id,':',1)),id) WHERE kind='operation';
+CREATE INDEX by_conversation ON poppy_provider.records (ns,kind,(body::jsonb->>'conversationId'));
+CREATE INDEX by_binding ON poppy_provider.records (ns,kind,(body::jsonb->>'bindingId'));
+CREATE INDEX by_client ON poppy_provider.records (ns,kind,(body::jsonb->>'clientId'));
+CREATE INDEX by_account ON poppy_provider.records (ns,kind,(body::jsonb->>'accountId'));
+CREATE INDEX by_grant ON poppy_provider.records (ns,kind,(body::jsonb->>'grantId'));
+CREATE INDEX by_phase ON poppy_provider.records (ns,kind,(body::jsonb->>'phase'));
+CREATE INDEX by_expiry ON poppy_provider.records (ns,kind,((body::jsonb->>'expiresAt')::double precision));
+CREATE INDEX by_connection ON poppy_provider.records (ns,kind,(body::jsonb->>'connectionId'));
+CREATE INDEX by_callback ON poppy_provider.records (ns,kind,(body::jsonb#>>'{direct,stateHash}'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poppykit/client",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "private": false,
   "description": "Personal Agent Protocol client 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",
@@ -40,7 +42,8 @@
     "CHANGELOG.md",
     "RELEASING.md",
     "examples",
-    "LICENSE"
+    "LICENSE",
+    "migrations"
   ],
   "exports": {
     ".": {
@@ -62,6 +65,18 @@
     "./provider/sqlite": {
       "import": "./dist/provider-sqlite.js",
       "types": "./dist/provider-sqlite.d.ts"
+    },
+    "./postgres": {
+      "types": "./dist/postgres.d.ts",
+      "import": "./dist/postgres.js"
+    },
+    "./provider/postgres": {
+      "types": "./dist/provider-postgres.d.ts",
+      "import": "./dist/provider-postgres.js"
+    },
+    "./adapter-contract": {
+      "types": "./dist/adapter-contract.d.ts",
+      "import": "./dist/adapter-contract.js"
     }
   },
   "dependencies": {
@@ -70,5 +85,13 @@
   "license": "MIT",
   "publishConfig": {
     "access": "public"
+  },
+  "peerDependencies": {
+    "pg": "^8.23.1"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    }
   }
 }