@poppykit/server 0.1.0 → 0.2.0

package/API.md

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

package/CHANGELOG.md

@@ -1,22 +1,22 @@
 # Changelog
 
-## 0.1.0 — initial development release candidate (unpublished)
+## 0.2.0 (release candidate)
 
-Request authentication, existing-issuer integration, optional Direct/Device/Mediated
-reference issuer, atomic targeted SQLite adapters, JSON/SSE conversation lifecycle,
-API/browser/feedback hooks and independent-peer/crash regressions.
+Add bundled Postgres company stores/coordinator with explicit migrations, atomic host transaction composition, savepoints and pool lifecycle.
 
-- 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

@@ -3,48 +3,12 @@
 The SDK targets Personal Agent Protocol draft 0.2. Company content, messages,
 unknown events and partial text remain untrusted data for the host application.
 
-## Client
+## Client interoperability
 
-Bind `createConversationClient` to the existing auth lifecycle:
-
-```ts
-const target = await auth.target(connectionId);
-const conversations = createConversationClient({
-  ...target, connectionId, store, clock: { now: Date.now },
-  authorizedRequest: request => auth.authorizedFetch(connectionId, request, target),
-  authorization: (id, scopes) => auth.authorization(id, scopes),
-});
-for await (const item of conversations.watch(conversationId, { consumer: 'ui', signal })) {
-  await processEvent(item.event);
-  await item.ack();
-}
-```
-
-`authorization(eventOrError)` returns the single auth lifecycle's verified
-required/granted/missing scopes and eligible methods. The UI requests consent and
-chooses an advertised method; Device or Mediated does not require Direct support.
-
-`read` returns one page; `drain` follows `has_more` immediately. Named consumers
-advance only on explicit acknowledgement. `watch` accepts SSE or JSON fallback,
-skips unknown event types, deduplicates up to 10,000 event IDs per invocation, and
-never rewinds its cursor on a duplicate. JSON pagination has its separate
-`maxPages` bound (default 1000), without consuming reconnect attempts. Reconnects
-are bounded (default 4); exhaustion is explicit `reconnect_exhausted`.
-
-`lastEventId` takes precedence over the starting cursor. On reconnect the watcher
-sends `Last-Event-ID`. `onPartial` is display-only: a null value clears unfinished
-text on completion/disconnect; never execute or reason from an incomplete delta.
-Messages are actionable only after a complete `message` event. SSE frames and
-JSON fallback are limited to 1 MiB, streams to 16 MiB, and partial text per stream
-to 1 MiB. UTF-8 fragmentation and CR/LF/CRLF are supported.
-
-`cursor_expired` is an explicit history gap. Inform the user, then reset a named
-consumer and reread retained history, or supply `onHistoryGap` returning true.
-Automatic recovery is limited to one reset per watch; it does not recover missing
-events. Checkpoints and pending sends survive process restart with durable stores.
-Send retries keep their original connection, issuer, endpoint, ID, body and read
-parameters. Abort signals are invocation-local and are never persisted. Canceling
-delivery does not cancel an accepted company action or prove a lost send failed.
+Clients keep immutable retry targets/message IDs, explicitly acknowledge named
+consumers and treat cursor_expired as a history gap, not recovered history. A
+disconnected client cannot undo accepted work. The [client delivery guide](https://github.com/LMol-4/poppykit-client/blob/main/DELIVERY.md)
+specifies watch/reconnect bounds, partial text, pagination and checkpoint handling.
 
 ## Node transport
 
@@ -67,7 +31,7 @@ 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

package/README.md

@@ -1,117 +1,70 @@
 # PoppyKit server
 
-TypeScript SDK for companies exposing services through [Personal Agent Protocol
-draft 0.2](https://personalagentprotocol.org/docs/0.2/spec). Verify requests, serve
-JSON/SSE conversations, enforce current permissions, support browser-session joining
-and accept feedback. Your company owns accounts, consent UI, agent and business tools.
+TypeScript SDK for companies implementing [Personal Agent Protocol draft 0.2](https://personalagentprotocol.org/docs/0.2/spec).
+Verify requests, serve conversations and enforce current authority. Your company
+supplies accounts, consent UI, agent, business tools and HTTPS routing. [MIT](LICENSE).
 
-## Installation
+## Install
 
-Requires Node **24.12.0 or later** and ESM. CI certifies Node 24.12.0; later majors
-have no separate certification. Optional SQLite uses experimental `node:sqlite`
-and requires 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+** and ESM. CI tests Node 24.12.0 on Linux, macOS and Windows;
+later majors are not separately certified. SQLite is optional/experimental and
+requires local filesystem locking.
 
 ```sh
-npm install ./poppykit-server-0.1.0.tgz
+npm install @poppykit/server@0.2.0
 ```
 
-The only production dependency is `jose@6.2.12`. Neither client SDK nor CLI is required.
-First-publication preparation is in [RELEASING.md](RELEASING.md).
+## Configure a service
 
-## Quickstart
-
-The complete [quickstart](examples/quickstart.mjs) creates an optional reference
-issuer, verified request authenticator and conversation service, then checks that
-an unauthenticated request is rejected. It starts no network listener:
-
-```sh
-node examples/quickstart.mjs
-```
-
-Its essential service configuration is:
+This runnable example starts no listener and rejects an unauthenticated request.
+`:memory:` is non-durable; use a private file and configured company sign-in hooks
+in production. The reference issuer is optional; [existing issuers](AUTH.md) use
+an ExternalAuthorityAdapter instead.
 
 ```js
 import { createRequestAuthenticator, createConversationService } from '@poppykit/server';
-const conversations = createConversationService({
-  endpoint, store: database.conversations(issuer), policy: auth.authority.policy,
-  authenticator: createRequestAuthenticator({ authority: auth.authority,
-    endpoints: [{ origin: 'https://company.example', pathPrefix: '/conversations', resource: endpoint }],
-    now: Date.now }), clock: { now: Date.now },
-});
+import { createMetadataResolver, createNodeTransport, createReferenceIssuer } from '@poppykit/server/reference-auth';
+import { SqliteCompanyDatabase } from '@poppykit/server/sqlite';
+
+const database = new SqliteCompanyDatabase(':memory:');
+const transport = createNodeTransport();
+try {
+  const issuer = 'https://company.example/issuer';
+  const endpoint = 'https://company.example/conversations';
+  const auth = createReferenceIssuer({
+    issuer, tokenEndpoint: issuer + '/token', revocationEndpoint: issuer + '/revoke',
+    poppyDomains: ['company.example'], directScopes: [], resources: [endpoint],
+    metadata: createMetadataResolver(transport), store: database.issuer(issuer),
+    coordinator: database, now: Date.now,
+  });
+  const service = createConversationService({
+    endpoint, store: database.conversations(issuer), policy: auth.authority.policy,
+    authenticator: createRequestAuthenticator({ authority: auth.authority,
+      endpoints: [{ origin: 'https://company.example', pathPrefix: '/conversations', resource: endpoint }],
+      now: Date.now }), clock: { now: Date.now },
+  });
+  console.log((await service.handle(new Request(endpoint, { method: 'POST',
+    headers: { 'content-type': 'application/json' }, body: '{}' }))).status); // 401
+} finally {
+  transport.close?.();
+  database.close();
+}
 ```
 
-`database`, `auth`, `issuer` and `endpoint` are created in the runnable example.
-Use a private database file for persistence and your HTTPS framework to route
-trusted public Requests to `conversations.handle(request)`. Configure company
-account/consent hooks before advertising sign-in methods.
-
-## Configuration and authentication
-
-Existing issuers integrate through `ExternalAuthorityAdapter`: provide token
-introspection, an explicit revocation-visibility guarantee and `AuthorityPolicy`
-that orders checks with protected writes. `createRequestAuthenticator` verifies
-the actual public method/URL and DPoP/resource binding. Resolve public URLs at
-your trusted proxy boundary; do not trust arbitrary forwarded headers. Core
-imports do not load or run the optional reference issuer.
-
-The separate `/reference-auth` implements Direct, Device and Mediated flows.
-Configure endpoints/trusted hooks, publish discovery/authorization metadata and
-route token/revocation and method handlers. Your company authenticates humans,
-protects consent with browser sessions/CSRF, delivers/verifies codes and chooses
-scopes. Opening a consent link never approves it. See [AUTH.md](AUTH.md).
-
-## Examples and common operations
-
-Route protocol requests to `conversations.handle(request)`. Workers use `claim`,
-`reply`, `finish` and lifecycle methods rather than writing rows directly. Use
-`requireAccount(work, scopes)` or protected-operation hooks before accessing
-account data. Model text cannot grant permission. Your application owns tool
-execution, validation and effect idempotency; receipt/publication deduplication
-does not make external writes exactly-once.
-
-`createBrowserSessions` integrates your cookie store with current session authority.
-`createFeedbackHandler` accepts validated reports, including signed-out sessions.
-`mcpResourceMetadata` and `mcpAuthorizationError` integrate an existing MCP server
-and issuer. See [INTEGRATIONS.md](INTEGRATIONS.md), [DELIVERY.md](DELIVERY.md) and
-the independent generic request fixtures in `tests/independent-peer.test.mjs`.
-
-## Errors, cancellation, retries and limits
-
-`AuthorityError` contains a safe code, HTTP status and authentication headers.
-Conversation handlers return protocol responses for known errors; your framework
-must handle unexpected host failures without exposing private diagnostics. Bound
-ingress bodies/rates before authentication. Propagate cancellation; a disconnected
-client cannot undo accepted application work.
-
-JSON pages and SSE events obey UTF-8 budgets. Notifications are hints; durable
-targeted reads reconcile lost notifications. [DELIVERY.md](DELIVERY.md) documents
-cursor/history gaps, waiting and record-specific retention. Choose
-`stop-account-work` or `allow-accepted-work-to-finish` deliberately; new requests
-always need current access. Immediate reference-issuer revocation visibility is
-an implementation policy, not a universal protocol requirement.
-
-## Storage and production responsibilities
-
-Use one `SqliteCompanyDatabase` for reference issuer, conversations and coordinator
-so authorization, revocation and protected writes share a transaction. SQLite
-serializes writers and requires local filesystem locking. Supply your own
-`ConversationStore`, `IssuerStore` and `AuthorityCoordinator` for other databases;
-adapters enforce cross-process atomicity. [STORAGE.md](STORAGE.md) specifies
-contracts, retention and explicit reset.
-
-Company credentials and signing infrastructure remain your responsibility. The
-personal-agent identity provider is a distinct trust role in the client package.
-No model, database service, deployment vendor or demo is required.
-
-## Reference and support
-
-[API.md](API.md) maps public entry points and declarations to deeper guides.
-This independent draft implementation has generic integration and packaged tests;
-deployed issuer, proxy, database and browser policies need operator validation.
-Individual extensions and business workflows are excluded. 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; licensing remains an owner decision before publication.
+## Guides
+
+- [Authentication](AUTH.md): external/reference issuers, consent and revocation.
+- [Storage](STORAGE.md): shared authority coordinator, cross-process transactions and reset.
+- [Delivery](DELIVERY.md): workers, streaming, cursors, retention and effect idempotency.
+- [Integrations](INTEGRATIONS.md): MCP, browser cookies and feedback.
+- [API exports](API.md), [contributing](CONTRIBUTING.md), [security](SECURITY.md),
+  [changelog](CHANGELOG.md) and [releasing](RELEASING.md).
+
+Your ingress must bound bodies/rates before authentication, supply the trusted
+public URL and propagate cancellation. Never trust arbitrary forwarding headers.
+Use current policy before protected work; model text cannot grant permission.
+Receipt/publication deduplication does not make external effects exactly-once.
+Validate deployed database, issuer and browser policies; no model/service vendor
+or demo application is required.