@poppykit/server 0.0.0-stage → 0.1.1

package/API.md

@@ -0,0 +1,21 @@
+# API reference
+
+All public entry points ship TypeScript declarations in `dist`. Use editor
+completion for complete options and results; this map identifies the integration seams.
+
+| Entry point | Main exports | Guide |
+| --- | --- | --- |
+| `@poppykit/server` | `createRequestAuthenticator`, `AuthorityError`, authority types | [authentication](AUTH.md) |
+| `@poppykit/server` | `createConversationService`, `createConversationNotifications` | [delivery](DELIVERY.md) |
+| `@poppykit/server` | `createBrowserSessions`, `createFeedbackHandler`, MCP metadata/error helpers | [integrations](INTEGRATIONS.md) |
+| `@poppykit/server/reference-auth` | `createReferenceIssuer`, `createMetadataResolver`, `createNodeTransport` | [authentication](AUTH.md) |
+| `@poppykit/server/sqlite` | `SqliteCompanyDatabase` | [storage](STORAGE.md) |
+| `@poppykit/server/adapter-contract` | adapter verification helpers | [storage](STORAGE.md) |
+
+Conversation workers claim accepted work, enforce account/scopes, publish replies
+and finish work through service operations. External effects require application
+idempotency and reconciliation. Existing issuers implement `ExternalAuthorityAdapter`
+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.

package/AUTH.md

@@ -0,0 +1,60 @@
+# Company authentication
+
+Integrating an existing issuer uses the core `ExternalAuthorityAdapter` and
+`createRequestAuthenticator`. It does not import, run, or persist the optional
+reference issuer. The host must describe its issuer's revocation visibility and
+order authorization checks with protected work. The reference issuer is a
+separate `/reference-auth` import and uses the shared company database coordinator
+for immediate revocation visibility.
+
+Reference Direct sign-in uses `beginAuthorization` / `completeAuthorization`.
+The host authenticates the human and protects consent with its own browser
+session/CSRF controls; pass a high-entropy browser binding. Registered callback
+URLs must be HTTPS on the client metadata domain and exactly match registration.
+
+Enable reference Device sign-in with `device: { endpoint, verificationUri,
+scopes }`. Route the configured device endpoint to `deviceAuthorization`.
+On the human page call `beginDeviceAuthorization(userCode, browserBinding)` and
+show the client identity and requested scopes. After an authenticated explicit
+approve/decline action call `completeDeviceAuthorization`. Opening a link must
+never approve it. The token endpoint handles durable polling intervals, slowdown,
+denial, expiry, partial consent, one-use codes and the Session's sticky account.
+
+Enable Mediated sign-in with `mediated: { endpoint, scopes, fields,
+authenticate, verifyCode }` and route that endpoint and its sign-in-ID children
+to `mediatedSignIn`. The SDK authenticates the Session Token and DPoP proof,
+validates declared fields, counts attempts before calling the host backend,
+and binds challenges to the initiating client, UserID and Session. The host
+verifies credentials in `authenticate` and may return an account plus a narrower
+scope list. It may instead return a challenge handle and safe delivery hint,
+then verify codes using `verifyCode`. Host hooks must not log or retain credentials
+and must enforce their own backend security and OTP delivery/verification.
+
+Credentials and codes exist only during the trusted handler call; the SDK clears
+input objects on exit, stores no passwords/codes and never includes them in
+responses. Backend errors return a safe unavailable code. Pending remote hooks
+are not automatically repeated after interruption. An operation left verifying
+expires; the user can explicitly start another sign-in subject to attempt limits.
+
+Defaults are five credential attempts per Session per minute, 100 per client per
+minute, five code attempts per challenge, and ten-minute sign-in expiry. Configure
+limits for your service and apply network-level limits before authentication.
+SQLite persists attempt windows and bounded tombstones; `cleanup` removes sign-in
+records only after their original expiry plus 30 seconds. A failed/expired code
+continues returning the same terminal status through that retained window.
+
+Each pending request captures a client revision. Account disconnect increments
+the revision and records that account's fence; later credential/consent results
+for that account cannot undo disconnect. Requests for other accounts sharing the
+same personal-agent client continue. A fresh explicit sign-in captures the new
+revision. Revision and per-account fence records remain until explicit issuer
+reset and never count as pending requests. Terminal method tombstones also do
+not consume pending quota.
+
+Issuer state is version 3. Older development state is refused without mutation;
+there is no automatic migration. Follow the explicit stop/backup/reset procedure
+in [STORAGE.md](STORAGE.md) only for state you choose to discard.
+
+Advertise only configured methods in your `poppy.json`; `authorizationMetadata()`
+adds the device endpoint only when enabled. There is no login/consent UI, identity
+provider, CLI or application workflow in this package.

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.1
+
+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.1.0
+
+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

@@ -0,0 +1,38 @@
+# Contributing
+
+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 the packageManager-pinned pnpm and run pnpm install --frozen-lockfile.
+
+```sh
+npm run typecheck
+npm run build
+npm run typecheck:tests
+npm test
+npm run check:docs
+```
+
+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.
+
+`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.
+
+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

@@ -0,0 +1,77 @@
+# Conversation delivery and transport
+
+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 interoperability
+
+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
+
+`createNodeTransport` uses Node HTTPS agents, with separate discovery, JSON and
+stream pools. Defaults: 8 pools total, 2 connections per pool (including pending
+TLS), 32 active operations, 15-second JSON timeout, and 5-second discovery timeout.
+There is no hidden request queue: excess pool capacity fails `overloaded`, so a
+later attempt performs fresh DNS and policy checks. Hosts decide scheduling.
+Streams use `transport.stream` with a 5-minute/16-MiB lifetime budget. Call
+`transport.close()` to cancel outstanding reads, DNS waiters, connects and streams.
+
+Every request rechecks DNS and current address policy before pool assignment.
+Changed approved addresses retire incompatible pools; actual TLS peers and reused
+sockets are checked before HTTP bytes. TLS certificates remain verified. Only
+explicit hostname/address exceptions permit private peers. Discovery never carries
+credentials and follows only HTTPS redirects; credential-bearing requests never
+follow redirects. Pool retirement may interrupt an active stream; reconnect uses
+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. 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.
+
+| Record | Lifetime / deletion rule |
+| --- | --- |
+| Conversation and message receipts | Entire conversation lifetime, including after closure and payload pruning; no automatic deletion |
+| Event payloads | Retained indefinitely by default; host may call SQLite `pruneEvents(id, before, limit)` in bounded batches; recommend at least 30 days |
+| Event cursor identities | Conversation lifetime; distinguish expired payloads (410) from foreign cursors (400) |
+| Active work | Never pruned while held/pending/claimed; event pruning protects these conversations |
+| Completed work | Bounded inspection retention; stale fences cannot publish |
+| Latest user message, context and account binding | Operational conversation record, retained for its lifetime, including handoff after payload pruning |
+| Client outbound/checkpoints | Retained until explicit local store deletion/reset; preserve pending/uncertain sends until reconciled |
+| Pending auth and replay records | Separate auth validity/owner rules in AUTH.md and STORAGE.md; not the event TTL |
+| CLI transcripts/retries | CLI ownership; local deletion never deletes company history or revokes authorization |
+
+Pruning is explicit operator policy, never automatic data loss. It preserves old
+message receipts and cursor identity. Concurrent reads see a coherent snapshot or
+`cursor_expired`. Invalid/expired waited-POST cursors are rejected before accepting
+the new write; an existing message ID still returns its original receipt.

package/INTEGRATIONS.md

@@ -0,0 +1,84 @@
+# API, browser and feedback integration
+
+Use the same authority policy and coordinator as protected conversation work.
+Supply the trusted public request URL; never derive it from arbitrary forwarding
+headers. Custom issuers and transports remain responsible for their documented
+revocation, address-validation and storage guarantees.
+
+## MCP authentication
+
+```ts
+const metadata = mcpResourceMetadata({ resource: mcpUrl, issuer, dpop: true });
+const authenticator = createRequestAuthenticator({ authority, now: Date.now,
+  endpoints: [{ origin: 'https://company.example', pathPrefix: '/mcp', resource: mcpUrl,
+    mcp: { dpop: true, metadataUrl: 'https://company.example/.well-known/oauth-protected-resource/mcp' } }],
+});
+// Serve metadata publicly without credentials. In the existing MCP handler:
+try {
+  const principal = await authenticator.authenticate(request);
+  return await authority.policy.withCurrent(principal, ['tools:read'], () => handleMcp(request));
+} catch (error) {
+  if (error instanceof AuthorityError) return mcpAuthorizationError(error, metadataUrl, true);
+  throw error;
+}
+```
+
+MCP metadata identifies the exact resource URL, issuer and ES256 support when
+enabled. Challenges include Bearer and, if supported, DPoP with `resource_metadata`.
+The exact endpoint accepts no child paths or added query. All other APIs retain
+DPoP-only authentication. Configure the reference issuer `mcpResources` with the
+same `{url,dpop}` list: every grant chooses Bearer for a non-DPoP MCP server even
+when a proof was provided. DPoP MCP requires a valid proof. Bearer tokens are
+resource-bound; DPoP-bound tokens cannot be presented as Bearer.
+
+An existing issuer can accept ordinary MCP OAuth clients through its own flow.
+Its introspector returns `dpopJkt: null` only for truly unbound Bearer credentials;
+ordinary MCP principals have empty `userId` and an account-bound session owned by
+the MCP client. Such sessions end on sign-in revocation/expiry and must not
+continue signed out. The external issuer must enforce this on every introspection
+and policy check and document its revocation visibility. The reference issuer
+implements personal-agent grants; it does not add a general OAuth login product.
+
+## Browser sessions
+
+```ts
+const browser = createBrowserSessions({ endpoint: browserEndpoint, domain: companyDomain,
+  metadata, authority: referenceIssuer.browserSessions,
+  policy: referenceIssuer.authority.policy, cookies: cookieStore, now: Date.now,
+});
+// Mount browser.join on browserEndpoint; no request-body logging at this route.
+const result = await browser.withSession(request, ['records:read'], principal => readRecords(principal));
+```
+
+`BrowserCookieStore.put/get` stores SHA256 cookie-value hashes, session bindings and
+expiry. Supply durable storage with targeted operations and expire old rows. Never
+store plaintext cookie values. `BrowserSessionAuthority.join` must atomically
+consume assertion jti and validate an active same-client/same-user session; `current`
+must read current session permissions. The reference issuer implements both on its
+existing durable issuer store/coordinator; SQLite uses targeted browser selectors.
+
+The browser handler verifies JWKS signature, asymmetric algorithm, typ, exact aud,
+times/lifetime, replay, client/user/session and HTTPS company return URL. Invalid
+requests return 400 with no cookie; successful requests set a host-only cookie and
+return 303 to the validated URL. Defaults are `__Host-poppy-session`, Path=/, Secure,
+HttpOnly, SameSite=Lax and max 3600 seconds capped by the current session lifetime.
+SameSite=None is supported; Strict is refused. `authenticate` resolves current
+authority on every request. Use `withSession` for scoped mutations so permission
+checks and work are ordered by the same policy/coordinator. Sign-in, scope changes
+and revocation are reflected immediately; no permissions are cached in cookies.
+Host adapters must isolate the agent browser from the user's consent browser.
+
+## Feedback
+
+`createFeedbackHandler({endpoint, authenticator, policy, accept, allow?})` validates
+a Session Token, including a signed-out token with no account scope. It checks the
+JSON/UTF8 byte budget and nonempty task/description limits (200/2000 Unicode
+codepoints), accepts unknown kinds and passes only a frozen inert-data report to
+`accept`. Do not interpret its text as instructions, including in later model use.
+The optional host `allow` hook supplies rate limiting; false returns 429. Malformed
+reports return 400, auth errors use the shared challenge, success is empty 202.
+There is no protocol deduplication identifier and no exactly-once promise. Hosts
+own report retention, privacy filtering and downstream side-effect handling.
+
+`tests/integrations.test.mts` exercises browser replay/current authority in memory
+and SQLite, MCP schemes/resources/ordinary-client integration and feedback.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PoppyKit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,68 @@
-# Temporary Holding Version
+# PoppyKit server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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).
+
+## Install
+
+Requires Node **24.12.0+** and ESM. CI tests Node 24.12.0 on Linux, macOS and Windows;
+later majors are not separately certified. SQLite is optional/experimental and
+requires local filesystem locking.
+
+```sh
+npm install @poppykit/server@0.1.1
+```
+
+## Configure a service
+
+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';
+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();
+}
+```
+
+## 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.

package/RELEASING.md

@@ -0,0 +1,91 @@
+# Releasing
+
+Use the tagged GitHub Actions workflow, not a local rebuild. Packages are MIT;
+0.1.0 was manually bootstrapped. Version 0.1.1 refreshes documentation without
+changing runtime APIs. Each new version needs its own source/artifact evidence.
+
+## Before tagging
+
+- Confirm npm ownership, unused versions, supported Node 24.12.0 and npm>=11.5.1.
+  Keep the pinned compiler/dependencies; do not upgrade tooling during a release.
+- Update version, changelog and shipped docs. CLI's client dependency and both
+  candidate JSON files must match exact final SDK versions/full source SHAs.
+- Review the full diff and run typecheck, build, tests and documentation checks.
+  Preserve the existing API/storage/security contracts and historical evidence.
+- Protect source, workflow files, pins and release tags with repository review/rules.
+  All actions are commit-pinned; release verification never restores a PR cache.
+- Verify GitHub environment **npm**: variable **NPM_PUBLISH_ENABLED=true**,
+  intended required reviewer, no admin bypass, and allowed deployment tags **v***.
+  Reviewers approve the real pending deployment; automation must not approve for them.
+- Configure the npm package's GitHub trusted publisher: owner **LMol-4**, this
+  package repository, workflow **release.yml**, environment **npm**. Match case.
+  Enable **direct npm publish** permission; this workflow does not stage a publish.
+  Configure near the release: unused configurations expire after two days. Public
+  source/package visibility and supported GitHub-hosted runners are required for
+  this provenance path. Do not supply NODE_AUTH_TOKEN or fall back to a long-lived
+  token if OIDC fails. Confirm current [npm requirements](https://docs.npmjs.com/trusted-publishers/).
+
+## Publish exact tagged source
+
+Client and server are independent. Publish client before CLI: the CLI registry
+guard requires its tested client tarball integrity to equal the published one.
+
+1. Merge reviewed source to main. Record the full SHA and create/push an approved
+   immutable **vVERSION** tag at that exact commit. Never move or replace a tag.
+
+   ```sh
+   git tag vVERSION FULL_SHA
+   git push origin refs/tags/vVERSION
+   ```
+2. Dispatch **Release** from that tag, with matching version, tag and full commit.
+   Optional `publish=false` rehearses verification only. A later publishing dispatch
+   is a new run with newly identified artifacts; it does not reuse a rehearsal's bytes.
+3. Dispatch with `publish=true` when authorized. Example (replace all placeholders):
+
+   ```sh
+   gh workflow run release.yml --repo LMol-4/PACKAGE --ref vVERSION -f version=VERSION -f tag=vVERSION -f commit=FULL_SHA -f publish=true
+   ```
+
+4. Wait for candidate, fast, contracts, integration, packaged-linux/windows/macos,
+   validation and gate to succeed. Missing, failed, canceled or skipped prerequisites
+   fail closed. Then follow the Actions environment-approval link. Do not bypass it.
+5. The publisher rechecks source/tag/ref/version, trusted manifest digest, unchanged
+   tarball metadata/bytes, owner enablement, registry absence and dependency integrity.
+   It publishes the same-run tested tarball with `--access public --provenance
+   --ignore-scripts`; it never installs, builds or packs again.
+6. Save run URL, full source SHAs, manifest SHA256, filenames, versions, byte counts,
+   tarball SHA256/npm SHA512 and registry integrity/provenance. Download before the
+   14-day candidate retention expires. Verify registry bytes, a clean exact-version
+   registry install, exported modules and the real npm CLI shim.
+
+Ordinary main/tag CI is useful evidence but is not a tagged Release/OIDC publishing
+run. A dry run or green tests alone do not prove npm authentication or provenance.
+The separate checked test-harness artifact is source/output-hash bound, used only
+by unprivileged verification jobs, and never published in an npm package.
+
+## Failure and partial release
+
+Stop on tag/source/version/digest mismatch, unknown registry responses or changed
+client integrity. Do not weaken gates, repack approved bytes, change pins silently,
+force an overwrite or use a token fallback. Inspect the failed job and preserve logs.
+For OIDC/auth failure check publisher spelling/case, workflow/environment identity,
+expiry, reviewer approval, permissions and npm/toolchain support before a new run.
+
+If a version already exists, compare its registry integrity and provenance with the
+saved receipt. Matching successful publication is recorded, never republished.
+For partial publication, finish only absent packages; verify the published client's
+exact bytes before CLI. If bytes differ or a fix is needed, use a reviewed new
+version and complete verification. A source checkout rollback cannot undo an npm
+publication or external side effect. Deprecation, dist-tag changes, unpublish and
+replacement versions need separate owner authorization; never delete evidence.
+
+## Verification limits
+
+Deterministic source suites run once per verification graph on Linux; exhaustive
+file groups reject omissions/duplicates. Packaged jobs test actual installed JS,
+exports/declarations/content/SQLite and representative platform behavior; CLI also
+tests real shims, auth/retry processes and API/browser/feedback wiring. They do not
+certify a production keyring, physical terminal, browser engine, KMS or TLS deployment.
+Windows GNU tar is given archive basename plus directory cwd to avoid drive-colon
+remote parsing. Failure logs retain seven days. Expired/missing artifacts require a
+new full run, not relabeling old results. See [CONTRIBUTING.md](CONTRIBUTING.md).

package/SECURITY.md

@@ -0,0 +1,13 @@
+# Security reporting
+
+Do not put credentials, tokens, private keys, personal records or exploit details
+in a public issue. Use this repository's GitHub **Security → Report a vulnerability**
+when private reporting is enabled. If it is unavailable, request a private contact
+from the repository owner without disclosing the vulnerability publicly. The owner
+must enable/confirm that route; no response SLA is promised.
+
+Include affected commit/version, a minimal reproduction using synthetic data,
+impact and the trust boundary involved. These draft packages have no promised
+support window or response SLA. Custom vaults, issuers, browser controllers,
+proxy routing and deployment policy remain operator responsibilities. Redaction
+and scoped authority do not isolate an unrestricted same-user program.

package/STORAGE.md

@@ -0,0 +1,112 @@
+# Company persistence and authorization
+
+Request paths use targeted domain selections, not whole-state rewrites. Node 24.12.0 or later is required.
+The optional `@poppykit/server/sqlite` entry point exports `SqliteCompanyDatabase`.
+The core and reference issuer entry points do not import SQLite. Consumers can
+implement `ConversationStore`, `IssuerStore` and `AuthorityCoordinator` themselves.
+The tested Node 24.12.0 runtime marks `node:sqlite` experimental.
+
+```ts
+import { SqliteCompanyDatabase } from '@poppykit/server/sqlite';
+const database = new SqliteCompanyDatabase('/private/path/company.db');
+const issuer = 'https://company.example/issuer';
+const issuerStore = database.issuer(issuer);
+const conversationStore = database.conversations(issuer);
+// Reference issuer options: store: issuerStore, coordinator: database.
+// Conversation options: store: conversationStore, policy: referenceIssuer.authority.policy.
+// Close database only after all in-flight requests/work have ended.
+```
+
+Use the same database instance for the reference issuer, its coordinator, and its
+conversation storage. A policy check and the protected conversation mutation join
+one SQLite transaction. Revocation/rotation/acceptance cannot interleave between
+authorization and commit. External issuers still supply their own policy and must
+state revocation latency and how their checks are ordered with protected writes.
+Never replace the coordinator with a process-local mutex for a multi-process service.
+
+SQLite uses WAL and FULL synchronous commits. A database serializes writers; this
+reference adapter does not promise parallel SQLite writers. The short per-instance
+queue protects its single connection, and SQLite coordinates separate processes.
+There is no application-wide static lock: separate databases are independent. The
+coordinator is a database transaction boundary, not a lock held during external
+model, vault, or HTTP calls. SQL busy retries are bounded. Use a local filesystem
+with correct SQLite locks; network-mounted multi-host SQLite is unsupported.
+
+## Domain records and guarantees
+
+Every primary key includes a namespace (use the exact full issuer). Sessions,
+grants, current/previous token hashes, authorization requests, codes, access-token
+hashes, replay keys, conversation metadata, shared account bindings, message
+receipts and work intent are separate records. Ordered events are a separate table
+keyed by namespace/conversation/sequence. Indexes cover client, account, grant,
+conversation, binding, phase and expiry. User identity and authorization checks
+still apply inside the SDK; a namespace name alone is not authentication.
+
+Conversation selections resolve an ID, message receipt, work ID, or next eligible
+claim. Reads include the related parent/Direct Conversation binding group, not
+unrelated conversations. A worker query selects the oldest eligible message for a
+conversation; publication rechecks lease and fence. Cursor-relative event selectors bound delivery reads without loading work/history
+aggregates. `ConversationNotifications` defines subscribe/unsubscribe/publish:
+subscribe before reading, treat wakes as hints, and always reconcile durable state
+after a wake or bounded timeout. Publishing after commit is best-effort, not an outbox.
+
+Issuer selections address metadata, token admission, a principal, a token hash, an
+authorization, or a client/account disconnect. Session and authorization limits
+use indexed counts rather than loading other clients' records. Related grant
+sessions are loaded when revocation must sign them out atomically.
+
+All mutations run synchronous callbacks over detached domain records. Async
+callbacks and non-JSON values are rejected. Exceptions roll back; domain savepoints
+also roll back if an enclosing policy caller catches an error. Returned values and
+retained callback objects cannot mutate persisted state after commit. Only changed
+rows and newly appended events are written. Conversation deletion, event rewriting,
+and generation reset are not silently accepted through a targeted transaction.
+
+Acceptance, event append, message deduplication receipt and pending work commit in
+one transaction. There is no second outbox. The same message ID with different
+content/target conflicts. Claim recovery can execute application work again after
+a lease expires: the fence prevents stale SDK publication, but cannot undo or
+deduplicate arbitrary external effects. The application's downstream system needs
+its own idempotency key (such as the stable work ID), or the application must retain
+an uncertain result for reconciliation. Never claim universal exactly-once execution.
+
+`cleanup(namespace, now, limit)` bounds deletion to at most 1000 expired short-lived
+codes, authorizations, access tokens or replay entries. It does not delete grants,
+work intent, message receipts or conversation events. Receipt identity remains
+through retention for the conversation lifetime. Finished work pruning is
+per selected conversation binding group; unrelated conversation growth cannot
+force another conversation's receipts out of storage.
+
+## Non-durable use and resets
+
+`new SqliteCompanyDatabase(':memory:')` is an explicit non-durable adapter for tests
+and development. Each instance is separate, is lost at close/process death, and
+offers no cross-process persistence. The test fixture's object store is also
+non-durable and is not evidence of database atomicity.
+
+No old whole-state files are migrated or deleted automatically. For a disposable
+development reset, stop all processes, resolve uncertain external effects, and
+explicitly move aside the database and WAL/SHM files. Reopen a fresh database to
+obtain new generations. Never reset a live database behind active processes.
+
+Contract tests cover real process contention/death, publication fences, rotation/
+revocation, rollback, isolation and targeted read counts; see [contributing](CONTRIBUTING.md).
+
+## Bounded conversation delivery and retention
+
+`ConversationSelection.events` loads a cursor-relative, count/byte-bounded event
+window without work/history aggregates; it is read-only inside transactions.
+`append` loads operational records without historical event payloads. `cursorCheck`
+checks retained cursor identities for waited POSTs. These selectors preserve the
+shared authority coordinator. Custom adapters must implement equivalent targeted
+reads before claiming the same operation-count guarantees.
+
+SQLite `pruneEvents(conversationId, beforeUnixMilliseconds, limit=100)` deletes at
+most 1000 old payloads per call and refuses active held/pending/claimed work.
+Message receipts, event cursor identities and the latest user message/context stay
+with the conversation for its lifetime. Closure is not deletion. Retention uses
+one database transaction; concurrent writers/readers see a coherent before/after
+state. Default payload retention is indefinite; operators should retain at least
+30 days and explicitly choose any shorter policy. See [DELIVERY.md](DELIVERY.md)
+for distinct lifetimes and client recovery behavior. No automatic destructive
+reset or history deletion was added.

package/dist/adapter-contract.d.ts

@@ -0,0 +1,12 @@
+import type { ConversationOptions } from './conversation/service.js';
+type Store = ConversationOptions['store'] & {
+    inspect(): Promise<import('./conversation/service.js').ConversationStoreState>;
+    adminTransaction<T>(change: (draft: import('./conversation/service.js').ConversationStoreState) => T): Promise<T>;
+};
+export type ConversationAdapterFixture = () => Promise<{
+    store: Store;
+    second: Store;
+    close(): Promise<void>;
+}>;
+export declare function runConversationAdapterContract(fixture: ConversationAdapterFixture): void;
+export {};