@poppykit/client 0.1.0 → 0.2.0

package/API.md

@@ -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,22 +1,22 @@
 # Changelog
 
-## 0.1.0 — initial development release candidate (unpublished)
+## 0.2.0 (release candidate)
 
-Discovery, safe HTTPS, all three sign-in methods, partial grants/replacement,
-owner-aware recovery, JSON/SSE conversations, API/browser/feedback hooks, targeted
-SQLite adapters and optional constrained hosted-identity provider.
+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.
 
-- Select MIT licensing and ship the complete LICENSE.
-- Prepare public package metadata and the initial 0.1.0 version.
-- Preserve J8 strict TypeScript tests, real subprocess/security regressions and
-  immutable installed-package verification on Linux, macOS and Windows.
+## 0.1.1
 
-No npm publication has occurred. Version 0.x APIs/storage may still change; record
-compatibility and migration/reset implications with future changes. This release
-does not promise stable 1.0 compatibility or certify external host integrations.
+Documentation refresh: registry installation, runnable quickstarts, focused guides
+and the tagged GitHub/OIDC release runbook. No runtime API, storage format or
+third-party dependency change.
 
-## 0.0.0 — historical private development candidates
+## 0.1.0
 
-J1–J8 established protocol capabilities, targeted storage, durable recovery,
-documentation, strict tests and fail-closed release verification. Their prior
-commits/artifact results remain historical evidence for those exact candidates.
+Initial MIT development release, published manually. Discovery, safe HTTPS, all
+three sign-in methods, targeted durable storage and recovery, conversations and
+API/browser/feedback hooks. The CLI uses the client SDK with trusted secure-backend
+adapters. J8 established strict typed tests and exact installed-artifact checks.
+
+Version 0.x may still change APIs/storage; future changes must explain compatibility,
+migration/reset and security implications. No stable 1.0 or external-host certification
+is promised. Older private 0.0.0 candidates retain their own historical evidence.

package/CONTRIBUTING.md

@@ -1,50 +1,38 @@
 # Contributing
 
-This package targets Personal Agent Protocol draft 0.2. Check the current
-[specification](https://personalagentprotocol.org/docs/0.2/spec) and
-[guides](https://personalagentprotocol.org/docs/0.2/guides); retained snapshots and
-tests are supporting evidence. Distinguish MUST requirements, SHOULD recommendations
-and product choices. Individual extensions and demo/business workflows are excluded.
+Follow the live draft 0.2 [specification](https://personalagentprotocol.org/docs/0.2/spec)
+and [guides](https://personalagentprotocol.org/docs/0.2/guides). Tests/snapshots are
+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 with the pinned pnpm version in package.json and `pnpm install --frozen-lockfile`.
-Run `npm run typecheck`, `npm run build`, `npm test` and `npm run check:docs`.
-CI partitions tests without omitting any test file; full `npm test` remains useful
-locally. Read [RELEASING.md](RELEASING.md) before changing workflow/release behavior.
+Install the packageManager-pinned pnpm and run pnpm install --frozen-lockfile.
 
-Keep changes small and complete: include callers, declarations, regression checks
-and documentation. Do not log credentials, weaken destination validation or silently
-reset persisted data. Pull requests must explain checks actually run and limitations.
-Use the repository's Issues for non-sensitive defects and feature discussions.
-Code is licensed under [MIT](LICENSE). No separate contribution agreement is
-configured; confirm permission for third-party contributions and obtain owner
-authorization before publishing.
+```sh
+npm run typecheck
+npm run build
+npm run typecheck:tests
+npm test
+npm run check:docs
+```
 
-## TypeScript test harness and coverage
+First-party tests/workers/verification helpers are canonical `.mts`. The existing
+compiler checks the whole strict program before emitting ignored adjacent `.mjs`.
+Failed builds remove stale outputs; no loader/type stripping substitutes for checking.
+Run `npm run build:tests` before `node scripts/run-checks.mjs GROUP` (unit, contracts,
+integration, validation). Groups are exhaustive/disjoint. LF source bytes are enforced
+by Git attributes. Generated test code is outside the npm allowlist; production tests
+import built/installed JavaScript. Release/build tools and examples may remain JS.
 
-First-party tests, executable fixtures, process workers and packaged verification
-scripts are canonical `.mts` files. Run `npm run typecheck:tests` for the complete
-strict program and `npm run build:tests` before individual
-`node scripts/run-checks.mjs GROUP` commands (unit, contracts, integration or
-validation). `npm test` performs that checked harness build and runs all groups.
-Build production first with `npm run build`; tests import compiled `dist/*.js`,
-not TypeScript source. No loader or native type stripping replaces the compiler.
+`npm run coverage` builds production and checked tests, then writes native Node
+line/branch/function reports under `coverage/` (summary.txt, lcov.info, report.json,
+raw/). Metrics cover loaded first-party dist JS: no production source maps or TS
+remapping; node_modules excluded, unloaded modules listed. Raw subprocess reports
+are retained, but arbitrary children may not merge and killed workers may not flush.
+Installed/OS/host checks are separate evidence; no percentage proves conformance.
 
-The existing TypeScript compiler emits ignored adjacent `.mjs` files only after
-all strict diagnostics pass. Failed builds remove stale canonical outputs.
-`scripts/build-tests.mjs` is compiler/bootstrap tooling, not an unchecked test
-runner. Canonical test sources use LF, enforced by `.gitattributes`, so Linux and
-Windows validate the same exact source bytes. Test output stays outside the npm
-package allowlist. Retained JavaScript release/build tools and packaged examples
-are genuine production tooling/examples; retained protocol captures are references.
-
-Run `npm run coverage` for a production build, checked harness and native Node
-24.12.0 line/branch/function report. `coverage/summary.txt`, `coverage/lcov.info`,
-`coverage/report.json` and `coverage/raw/` are generated local reports. Metrics
-refer to first-party compiled `dist` JavaScript; production emits no source maps
-and no TypeScript remapping is claimed. Third-party `node_modules` is excluded;
-unloaded modules are listed explicitly. Raw child-process reports are retained,
-but arbitrary subprocess execution is not guaranteed to be merged into the native
-runner summary, and killed/crashed workers may not flush counters. Actual installed
-package/OS checks remain separate evidence. No percentage threshold substitutes
-for protocol, negative/security, process and platform assertions.
+Include callers, meaningful regression evidence and docs with behavior changes.
+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.

package/DELIVERY.md

@@ -67,33 +67,14 @@ the durable cursor and fresh authorization.
 Metadata caching remains bounded and honors freshness, Age, validators, no-cache
 and no-store, with a 300-second upper bound. Expired entries revalidate; 304s retain
 prior caching directives. `resolver.invalidate(target?)` fences old pending cache
-writes without bypassing fetch concurrency/rate limits. J2 rejects changed saved
+writes without bypassing fetch concurrency/rate limits. The auth lifecycle rejects changed saved
 issuer/endpoint/resource bindings rather than rerouting persisted work.
 
-## Company service and retention
-
-The server accepts `supportedScopes`, the union offered by its actual sign-in
-methods. `directScopes` remains a compatibility alias. One coordinator must still
-cover authority checks and durable conversation reads/mutations.
-
-Default JSON/request/frame budget is 1 MiB; the maximum encoded event is
-1 MiB minus 1025 bytes. Page sizing reserves 1024 bytes for worst-case IDs, cursors
-and envelopes and counts UTF-8 bytes. Company events and client messages that
-cannot fit are rejected before commit; no receipt/work survives a rejected write.
-Do not reduce configured budgets below those used for retained accepted events.
-
-Notifications are post-commit hints. Subscribe before reading; reconcile durable
-state on wake or every 1000 ms by default. `createConversationNotifications` is
-local acceleration only. Multiple processes work without a broker through targeted
-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
-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.
+## Peer retention
+
+The [server delivery guide](https://github.com/LMol-4/poppykit-server/blob/main/DELIVERY.md)
+describes service configuration, byte budgets, notifications and bounded streams.
+Keep the following distinct lifetimes when choosing an operator retention policy:
 
 | Record | Lifetime / deletion rule |
 | --- | --- |

package/PROVIDER.md

@@ -3,7 +3,7 @@
 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 +65,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 +97,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

@@ -1,30 +1,24 @@
 # PoppyKit client
 
-TypeScript SDK for personal-agent providers integrating [Personal Agent Protocol
-draft 0.2](https://personalagentprotocol.org/docs/0.2/spec). Discover companies,
-start sessions, use Direct/Device/Mediated sign-in, exchange JSON/SSE conversations,
-authorize API requests, join an agent browser and send feedback. Your application
-supplies the agent and trusted infrastructure.
+TypeScript SDK for [Personal Agent Protocol draft 0.2](https://personalagentprotocol.org/docs/0.2/spec):
+discovery, authentication, conversations and API/browser/feedback hooks. Your
+application supplies the agent and trusted infrastructure. [MIT](LICENSE).
 
-## Installation
+## Install
 
-Requires Node **24.12.0 or later**, ESM and HTTPS. CI certifies Node 24.12.0;
-later majors are not separately certified. Optional SQLite uses experimental
-`node:sqlite` and local filesystem locking.
+Version 0.2.0 is a release candidate until its publishing workflow completes.
 
-Version **0.1.0** is an initial development release candidate under the [MIT license](LICENSE).
-It has not been published. Install a verified tarball:
+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.0.tgz
+npm install @poppykit/client@0.2.0
 ```
 
-The only production dependency is `jose@6.2.12`. No server SDK or CLI is required.
-Registry installation instructions will accompany the first public release.
+## Discover a company
 
-## Quickstart
-
-Discovery needs no signing key, account token or database:
+No credentials or database are needed. Replace `company.example` with a company
+publishing draft 0.2 discovery:
 
 ```js
 import { createMetadataResolver, createNodeTransport } from '@poppykit/client';
@@ -38,87 +32,21 @@ try {
 }
 ```
 
-Replace `company.example` with a company publishing draft 0.2 discovery.
-Run the complete [quickstart](examples/quickstart.mjs) with a real domain, or
-`node examples/quickstart.mjs --self-check` for a deterministic offline example.
-
-## Configuration and authentication
-
-`createClientAuth(options)` owns sessions, all three sign-in methods, renewal,
-scope replacement, sign-out and recovery. Supply `namespace`, `localUserId`,
-`clientId`, registered `redirectUris`, an `AuthStore`, `SecretStore`, safe transport
-and metadata resolver. Run `recover()` at startup. Publish HTTPS client metadata
-and public JWKS; private signing keys stay in your signer or provider.
-
-Choose an `IdentitySigner`, or authenticated `AssertionProvider` and
-`ProviderIdentity` adapters. The optional `/provider` reference is documented in
-[PROVIDER.md](PROVIDER.md). Operators supply HTTPS hosting, enrollment authentication,
-company policy and signing/KMS. Anonymous sessions require a separate local signer
-with a published key; provider-only custody reports `anonymous_unavailable`.
-
-Call `start(domain)`, then `authorization(connectionId, scopes)` to inspect grants,
-missing scopes and advertised methods. `beginSignIn(connectionId, { method, scopes })`
-selects `direct`, `device` or `mediated`. Direct requires an authenticated browser
-binding and HTTPS callback. Device displays a verified human link/code and resumes
-with `continueSignIn`. Mediated invokes your `TrustedInput.collect` UI. Keep that UI,
-passwords, codes and credential adapters outside model tools. See [AUTH.md](AUTH.md)
-for partial consent, scope upgrades, cancellation and revocation.
-
-## Examples and common operations
-
-Configure conversations using the verified target and the same auth lifecycle:
-
-```js
-import { createConversationClient } from '@poppykit/client';
-const target = await auth.target(connectionId);
-const conversations = createConversationClient({
-  ...target, connectionId, store: conversationStore, clock: { now: Date.now },
-  authorizedRequest: request => auth.authorizedFetch(connectionId, request, target),
-  authorization: (id, scopes) => auth.authorization(id, scopes),
-});
-```
-
-`auth`, `connectionId` and `conversationStore` are your configured instances.
-`start`, `send`, `read`, `watch`, `ack`, `handoff` and `close` manage the lifecycle.
-Retain message IDs for retries; acknowledge durable deliveries after processing.
-[DELIVERY.md](DELIVERY.md) explains cursors, streaming, pagination and retention.
-
-Use `apiTarget`/`apiFetch` with an existing OpenAPI or MCP client. The final URL
-must be independently authorized; an OpenAPI `servers` entry grants no authority.
-`joinBrowser` accepts a trusted agent-controlled controller separate from human
-consent. `feedback` sends a single `missing` report expecting empty HTTP 202.
-[INTEGRATIONS.md](INTEGRATIONS.md) documents the adapter contracts and examples.
-
-## Errors, cancellation, retries and limits
-
-Handle `AuthFailure.code` and `ConversationError.code`; do not parse messages or
-log credential headers/private adapter errors. Pending operations are resumable;
-an uncertain remote exchange requires reconciliation and is never silently replayed.
-Declined upgrades preserve old access; sign-out never automatically reconnects.
-
-Conversation operations accept `AbortSignal`. Cancellation cannot undo bytes sent.
-Conversation retries retain message IDs/payloads with bounded backoff and Retry-After.
-Auth deadlines persist across restarts. Feedback has no automatic POST retry or
-deduplication promise. Pools, bodies, event/page sizes and reconnects are bounded;
-see [DELIVERY.md](DELIVERY.md). External effects need application idempotency.
-
-## Storage and production responsibilities
+The packaged [quickstart](examples/quickstart.mjs) also supports `--self-check`
+without a network service.
 
-Optional `/sqlite` exports `SqliteAuthStore` and `SqliteConversationStore`;
-`/memory` exports non-durable `MemoryConversationStore`. Consumers can implement
-the targeted contracts using their own databases. Store Account Tokens, DPoP keys
-and PKCE in a secure `SecretStore`; Session Tokens stay in memory. SQLite stores
-secret references and private message data, not vault encryption. Database, vault
-and remote exchange are separate boundaries; implement orphan-secret reconciliation
-and deployment ownership checks. [STORAGE.md](STORAGE.md) defines atomicity,
-recovery and explicit development reset.
+## Guides
 
-## Reference and support
+- [Authentication](AUTH.md): sessions, Direct/Device/Mediated, consent, renewal and revocation.
+- [Storage](STORAGE.md): targeted adapters, secret references, recovery and explicit resets.
+- [Delivery](DELIVERY.md): messages, streaming, cancellation, retries and retention.
+- [Integrations](INTEGRATIONS.md): verified API targets, agent browser and feedback.
+- [Optional provider](PROVIDER.md): operator-hosted signing and callback custody.
+- [API exports](API.md), [contributing](CONTRIBUTING.md), [security](SECURITY.md),
+  [changelog](CHANGELOG.md) and [releasing](RELEASING.md).
 
-[API.md](API.md) maps public exports and TypeScript declarations to deeper guides.
-This independent draft implementation has deterministic and packaged tests;
-production vaults, browsers, external issuers and hosting need operator validation.
-Individual protocol extensions and application business logic are outside the SDK.
-See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md),
-[CHANGELOG.md](CHANGELOG.md) and [RELEASING.md](RELEASING.md). No public license grant
-has been selected; publication remains blocked pending the owner's license decision.
+Keep Account Tokens, DPoP keys and PKCE in a secure SecretStore; never expose them
+to model tools. An uncertain remote result must not be silently replayed. SQLite
+is optional/experimental and is not vault encryption. Production issuers, vaults,
+browsers and hosting require operator validation; individual extensions and
+application business workflows are outside this SDK.