@poppykit/server 0.0.0-stage → 0.1.0

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,22 @@
+# Changelog
+
+## 0.1.0 — initial development release candidate (unpublished)
+
+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.
+
+- 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.
+
+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.
+
+## 0.0.0 — historical private development candidates
+
+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.

package/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# 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.
+
+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.
+
+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.
+
+## TypeScript test harness and coverage
+
+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.
+
+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.

package/DELIVERY.md

@@ -0,0 +1,113 @@
+# 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
+
+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.
+
+## 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. J2 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,117 @@
-# 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 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.
+
+## Installation
+
+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.1.0** is an initial development release candidate under the [MIT license](LICENSE).
+It has not been published. Install a verified tarball:
+
+```sh
+npm install ./poppykit-server-0.1.0.tgz
+```
+
+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).
+
+## 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:
+
+```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 },
+});
+```
+
+`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.