@poppykit/server 0.3.1 → 0.5.0

package/API.md

@@ -5,12 +5,13 @@ completion for complete options and results; this map identifies the integration
 
 | Entry point | Main exports | Guide |
 | --- | --- | --- |
-| `@poppykit/server` | `createRequestAuthenticator`, `AuthorityError`, authority types | [authentication](AUTH.md) |
+| `@poppykit/server` | `createSessionAuthority`, `createRequestAuthenticator`, `AuthorityError`, Session/authority types | [authentication](AUTH.md) |
 | `@poppykit/server` | `createConversationService`, `createConversationNotifications` | [delivery](DELIVERY.md) |
+| `@poppykit/server` | `Author`, `AuthorType`, `Message`, `RecordedMessage`, conversation/event types | [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) |
+| `@poppykit/server/adapter-contract` | `runSessionAdapterContract`, `runBrowserCookieAdapterContract`, issuer/conversation adapter contracts | [storage](STORAGE.md) |
 
 Conversation workers claim accepted work, enforce account/scopes, publish replies
 and finish work through service operations. External effects require application
@@ -21,10 +22,17 @@ trusted public URLs, ingress limits, request cancellation and private-error hand
 Direct reference issuers now require `authorizationResultCipher` before
 `beginAuthorization`; same-decision `completeAuthorization` recovers the encrypted
 callback through its original validity window. See [AUTH.md](AUTH.md) for custody,
-revocation and one-time exchange limits. No package subpath or driver contract changed.
+revocation and one-time exchange limits. SessionStore admission and BrowserCookieStore one-use authorization are new
+custom-adapter contracts; see STORAGE.md.
 
 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.
+
+## Business Operations v2
+
+See [OPERATIONS.md](OPERATIONS.md) for the complete consent/effect contract. Root exports include `BusinessOperation`, `OperationApproval`, `OperationRequest`, `operationsV2`, `supportsOperations`, `parseBusinessOperation`, `parseOperationApproval`, `parseApprovalHeader`, `approvalHeader`, `mcpApproval`, `approvalMetaKey`, `captureApiOperationRequest`, `operationExpiry`, `operationRequiredResponse` and `operationToolError`.
+
+Server exports `createBusinessOperations`, `BusinessOperationError`, `operationApiResponse`, `operationMcpResponse`, `operationPendingResponse`, `BusinessOwner`, `OperationRevision`, `BusinessOperationRecord`, `BusinessOperationStore`, `OperationInput`, `OperationOutcome` and `ExternalOperationEffect`. Both company databases expose `businessOperations(namespace)` and scoped `withTransaction`; the adapter-contract subpath exports `runBusinessOperationAdapterContract`. Conversation options accept `operations:metadata`, and `operationContext(work)` returns its accepted binding/approval.

package/AUTH.md

@@ -1,97 +1,122 @@
 # 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.
-
-Direct hosts must configure `authorizationResultCipher: { seal, open }` with
-synchronous authenticated encryption and a durable protected key before calling
-`beginAuthorization`. Hosts already using the optional client provider can reuse
-its `createResultCipher` instance. Other hosts supply the same structural contract;
-no client package or database driver is loaded by the reference issuer.
-
-`completeAuthorization(id, browserBinding, decision)` commits one decision and
-an encrypted callback receipt atomically. Repeating the same decision returns
-the same URL after restart; changed browser/account/scopes/decision and stale
-account revocation/reset fail. Approval recovery expires at the earlier of the
-original authorization deadline and code expiry; denial uses the original deadline.
-Recovery never mints a replacement code or extends consent. The host must retain
-its authenticated owner/installation/session binding and chosen decision durably,
-then reconcile delivery outside transactions. Never retry an uncertain code exchange.
-
-`withCurrent` checks token, Session and grant expiry immediately before protected
-actions, including after body reads and long-poll waits. Streams close at token
-expiry and recheck current authority for each emitted frame; reconnect with fresh
-authentication. `withAccepted` intentionally ignores admission-token expiry while
-preserving the accepted scope ceiling, reset generation and configured revocation policy.
-
-Account Token rotation retains all issued hashes through the fixed grant lifetime.
-Replaying any ancestor revokes its entire lineage and signs its Sessions out;
-rotation never extends the grant. Client authentication remains mandatory, while
-Session Tokens can move to a new DPoP key as the protocol permits. Shared provider
-signing does not bind a copied refresh token to one provider enrollment. Keep
-tokens secret and serialize rotation; never retry a lost token response blindly.
-Bounded database cleanup removes hashes only after their lineage is expired,
-revoked or absent. No plaintext callback code is persisted.
-
-Upgrade prerequisite: older issuers discarded ancestors beyond the previous hash.
-Those missing hashes cannot be reconstructed by this update. Before public
-enablement, revoke every pre-upgrade live lineage through the issuer's normal
-revocation/disconnect flow and require fresh consent, or prove it has expired.
-Until then, the full-ancestor guarantee applies only to newly created lineages.
-This update does not reset stored data or silently revoke legacy grants.
-
-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.
+Resources own Poppy Sessions; OAuth issuers supply account grants. An existing
+issuer implements `ExternalAuthorityAdapter` (introspection and current/accepted
+authority policy) without importing the optional reference issuer. Its introspector
+must validate exact resource audience, expiry, client/account identity, scope and
+DPoP binding, and document revocation visibility and ordering with protected work.
+
+Create a separate resource Session authority and use its combined policy:
+
+```ts
+const sessions = createSessionAuthority({
+  companyId, metadata, store: database.sessions(companyId), coordinator: database,
+  accountPolicy: externalAuthority?.policy, now: Date.now,
+  maxSessionsPerClient: 10000, lifetimeSeconds: 86400,
+});
+const authenticator = createRequestAuthenticator({
+  sessions, authority: externalAuthority, now: Date.now,
+  endpoints: [{ origin: 'https://api.company.example', pathPrefix: '/conversations' }],
+});
+// Pass authenticator and sessions.policy to conversation/browser/feedback handlers.
+```
+
+`companyId` is the verified issuer, or the Company's HTTPS domain without a slash
+when issuerless. Signed-out Sessions require no authorization server or token.
+The authenticator verifies the delegated ES256 Session JWT before using any of its
+identity, audience, method/URL, token hash or continuity claims. Delegations accept
+ES256 and PS384 root signatures, require a public P-256 delegated key and expire
+within 24 hours. A root-signed Session JWT without delegation is rejected.
+Client metadata fetches refuse redirects; hosts keep the supplied safe transport's
+TLS/address and bounded-fetch checks. Operator signatures never replace these checks.
+
+Sessions are keyed by exact client_id plus sid; User and optional Agent IDs cannot
+change. Delegated keys can change on every request. Account grants and proof keys
+do not identify Sessions. The resource remembers a previously used account and
+returns invalid_session on account change. A request without an access token is
+signed out, even when the Session used an account before. One account grant can
+serve many Sessions. Introspection alone never establishes a Poppy User or sid.
+
+Session lifetime defaults to one day, admission to 10,000 active Sessions per client.
+Bundled stores serialize quota counts and creation across processes; overflow is
+429 with Retry-After until the earliest expiry. Ended/expired Sessions do not occupy
+admission slots. Call bounded database cleanup for expired Session records; the
+Company may forget ended Sessions under core 5.5. Recreated records get a fresh
+instanceId, exposed as Principal.sessionInstanceId, so future ownership contracts
+can distinguish them. Configure this cap on createSessionAuthority: passing the
+old maxSessionsPerClient option to createReferenceIssuer fails with a relocation error.
+
+`withCurrent` checks current Session instance/generation, validity, accepted scopes
+and live account policy immediately before protected work. `withAccepted` preserves
+the accepted scope ceiling and explicit work-revocation policy while allowing an
+admission token to expire. A database coordinator orders authorization with writes;
+a process mutex alone is insufficient across replicas. External effects still need
+host idempotency and reconciliation. [Operations v2](OPERATIONS.md) provides separate durable business mechanics with explicit host effect contracts.
+
+Authority errors expose response(): invalid_session is JSON/400; missing account
+authority is an errorless Bearer/DPoP challenge/401 with scope; insufficient_scope
+is 403, invalid_token is 401. Rate limits are JSON/429 with Retry-After. MCP helpers
+include resource_metadata in OAuth challenges; see [INTEGRATIONS.md](INTEGRATIONS.md).
+
+## Optional reference issuer
+
+Configure protectedResources with the Company domain identifier (no path, port or
+slash) and supportedScopes. The issuer publishes refresh_token plus enabled
+Direct/Device/Mediated grants; it does not issue signed-out Session tokens or
+advertise token exchange. Scope names, including poppy-prefixed ones, are Company
+policy; publish descriptions and optional hints. Resource-specific tokens use normal
+sign-in/refresh with resource. Configure exact MCP resources and their DPoP policy.
+The reference issuer chooses DPoP for its other account resources; an external issuer
+can also supply Bearer grants through the core authenticator.
+
+Direct uses beginAuthorization/completeAuthorization. The host authenticates the
+human, protects consent/CSRF and supplies a high-entropy browser binding. Registered
+redirects must be HTTPS on the client metadata domain or RFC 8252 loopback IP URLs;
+only a loopback port can vary. PKCE and exact issuer response validation remain
+required. OAuth dpop_jkt optionally binds the code to a proof key; it is not a Session.
+Missing binding fields in legacy pending codes fail closed.
+
+Direct also requires a synchronous authenticated authorizationResultCipher with a
+durable protected key. Complete consent and an encrypted callback receipt commit
+atomically. An identical decision recovers the same URL through its original validity
+window; changed decisions, owners, revocation or expiry fail. Recovery never issues
+a replacement code, extends consent or retries an uncertain token exchange.
+
+Device configuration supplies endpoint and verificationUri. Serve deviceAuthorization
+at that endpoint. The human page uses beginDeviceAuthorization then an explicit,
+authenticated completeDeviceAuthorization decision. Opening a link does not approve.
+Polling enforces pending/slowdown/denial/expiry and one-use codes, bound to client_id
+rather than a Session or first polling key. Apply RFC 10027 risk controls in the host;
+prefer Direct when it fits the device. Keep device codes private.
+
+Mediated configuration supplies fields, scopes, authenticate and verifyCode. Advertise
+`mediated-sign-in` version 1 and route the form grant at the normal token endpoint.
+The credentials/code never arrive with a Session JWT or account token. Client-bound
+continuations preserve the original scopes/resource/expiry. A code challenge is
+HTTP400 code_required with sign_in_id, sent_to and expires_in; continuation uses
+one_time_code without repeating credentials/scope. Hooks receive {issuer,clientId},
+not Session identity, and must enforce backend/account/network throttles. Input
+objects are cleared on exit; never log or retain credentials or OTPs.
+
+An interrupted/throwing remote hook remains verifying, is never automatically
+repeated and survives expiry/cleanup for host reconciliation. It continues counting
+toward pending limits. No expiry timer proves a remote action failed. Defaults are
+five credential attempts per client per minute, five code attempts per challenge,
+1000 pending requests globally and 100 per client; apply network limits before auth.
+Client/account revision fences prevent late consent from undoing disconnect.
+
+Refresh grants have a fixed lifetime; rotation never extends it. Retain every
+ancestor hash through that lifetime so replay revokes the lineage. Client assertions
+remain mandatory, independently of Sessions and proof-key rotation. Revocation
+signs resources out according to live account policy without deleting Sessions.
+
+Issuer record versions 3/4 upgrade to 5 under their writer lock, retaining generation,
+Sessions/maps, grants/ancestor hashes, pending consent, uncertain hooks, replay,
+nonces and encrypted recovery receipts. Only proven client/account associations
+are backfilled. Unknown/conflicting legacy records are not reinterpreted. The retired browserSessions/sessionForKey and separate mediatedSignIn entry points
+are removed. Browser joining uses resource Sessions and fixed approval snapshots;
+mediated grants use token(). Retained legacy records remain available through
+explicit storage reads for reconciliation.
+See [STORAGE.md](STORAGE.md). Earlier unsupported versions fail closed.
+
+Authentication lifecycle OperationRecord/operationId values never approve business operations. OAuth access consent, provider enrollment and mediated credential collection cannot supply business consent. [Operations v2](OPERATIONS.md) binds each actual user answer to the exact revision and request, and rechecks current Session/account authority for execution and protected replay.

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+Local migration block2 adds Operations v2 codecs, negotiated API/MCP/conversation mechanics and durable revision ownership, execution claims, local atomic effects and host external reconciliation. See [OPERATIONS.md](OPERATIONS.md). This is a local SDK checkpoint, not full CLI integration or package publication.
+
+## 0.5.0 — current-spec core migration
+
+Separate delegated resource Sessions from OAuth account grants; discover issuers and
+service resources independently; support issuerless Companies, Bearer/DPoP tokens,
+current mediated grants, code-only browser joining, current errors and feedback.
+Client auth records upgrade to v3; reference issuer records upgrade to v5 without
+resetting credentials or pending/recovery records. Stop old writers before opening
+upgraded stores. Retired public APIs are removed; see [AUTH.md](AUTH.md) and
+[STORAGE.md](STORAGE.md). Breaking local migration candidate; publication requires the recorded release gates.
+
+## 0.4.0 — 2026-10-28
+
+Historical snapshot of Personal Agent Protocol draft 0.3; the current live contract supersedes this entry. Break discovery, proof-key grants, author, browser joining and MCP Token Exchange contracts. Upgrade issuer state 3→4; stop old writers and reset conversation state to version 2. Require explicit company history scopes.
+
+Local migration candidate only. Publication and deployment require separate approval.
+
 ## 0.3.1
 
 Support Node 24.21.0 and later within Node 24 under the owner-accepted runtime policy.

package/CONFORMANCE.md

@@ -0,0 +1,73 @@
+# Current protocol contract
+
+The normative source is the [live draft 0.3 specification](https://personalagentprotocol.org/docs/0.3/spec)
+and [Mediated Sign-In v1](https://personalagentprotocol.org/docs/0.3/extensions/mediated-sign-in).
+The numbered URL is not a content pin. On 2026-10-31 the six migration sources were
+re-fetched and matched their initial snapshots byte for byte. SHA-256 identities:
+
+- Core: 0c8586c0477f523abe39b47e5a20232fc8128c24bf17bb78fff69133f97f9bb9
+- Mediated v1: 68074a6178bf4c78f09b2a88313a4067fa9e4143a338f205a63d2d884ca09f94
+- Guides: fe10657eca0b464c19cc198f3876d30f5055d8a5cb423cd147affe805206ecdd
+
+The workspace requirement matrix and exact commands, tree hashes and focused test
+receipts live in jobs/protocol-migration. Focused checks do not certify an installed
+release or any deployed service. Operations v2 SDK mechanics are implemented with opt-in host contracts;
+full candidate, native and cross-package release gates remain separate.
+
+## Host contracts and recommendations
+
+The [guides](https://personalagentprotocol.org/docs/0.3/guides) use SHOULD for each
+recommendation, including items without uppercase words. The SDK supplies protocol
+mechanics; hosts retain the following responsibilities:
+
+- Keep signing, transport and the SecretStore outside model tools. Redact identity,
+  authorization, cookie and credential headers before host logging or telemetry.
+  Secure credential storage is mandatory. Bundled auth imports private keys as
+  non-extractable CryptoKeys, but serializes keys to the host vault for durable
+  recovery; it does not promise hardware-backed, non-exportable key custody.
+- Show the verified Company name/domain after discovery redirects and on sign-in
+  forms. Explain stable pairwise signed-out recognition in the privacy notice.
+  Request the fewest task scopes, treat absent/unknown hints conservatively, and
+  obtain User consent for access and for human-operated Direct/Device sign-in.
+- Prefer Direct, then Device where viable. Assess RFC 10027 device-flow risk,
+  confirm the visible user code, protect consent pages against CSRF/framing, and
+  apply account/network abuse limits. Mediated v1 is transitional; do not use saved
+  credentials to undo a disconnect. TrustedInput must isolate credentials and OTPs.
+- Isolate an agent browser's storage per Session, load only its own join code,
+  submit promptly, rejoin after sign-in, and close its storage when the Session ends.
+  Joined cookies retain the authorized account/scope snapshot. The website must
+  prioritize that cookie and use current policy on every request; signed-in joins
+  must clear any earlier ordinary login. Signed-out joins preserve it. Website
+  logout must invalidate/remove the joined cookie through the host integration.
+- Apply account/scope checks at every application tool and channel. Do not trust
+  model/Company prose as permission or put secrets in messages/feedback. Decide
+  task exclusions, interface choice, human handoff wording and report frequency.
+- Keep deployment TLS, public-URL proxy reconstruction, internal credentials, bot
+  recognition, network throttles, key publication/rotation and tenant issuer
+  separation correct. RateLimit headers and scheduling/backoff across independent
+  tasks are host policies; SDK Retry-After state is connection-scoped.
+- Operator signatures use a host HttpTransport/edge integration implementing the
+  deployment's RFC 9421/Web Bot Auth profile. Sign only after the body, DPoP and
+  Poppy-Session/Authorization headers are final; verify Session identity separately.
+  Protect forwarded verification results and never share operator private keys.
+- Blind signing is not implemented by the bundled provider. A host requiring it
+  must supply blind client assertions and delegations together, with device-made
+  random jti values, and fail closed if PS384 is unavailable. No ES256 privacy
+  downgrade is automatic. Company verification accepts PS384 independently.
+- Local/provider delegations use coarse half-hour issuance times and expire one
+  hour after that bucket (30–60 minutes remaining on creation). Custom providers
+  must keep their delegation valid and within the documented client lifetime bound.
+  Verification deliberately avoids another sensitive delegation cache; bounded
+  metadata/JWKS caches remain, at the cost of extra signature work per request.
+- Supply the application's idempotency/reconciliation for external effects, durable
+  multi-host ownership/liveness, orphan-secret sweeps with a grace period, and
+  retention appropriate to its data. Conversation receipts are not business-effect
+  deduplication. Never reset active or uncertain work to make a test pass.
+
+See [AUTH.md](AUTH.md), [STORAGE.md](STORAGE.md) and [INTEGRATIONS.md](INTEGRATIONS.md)
+for the concrete callback/store contracts. A host integration must validate these
+boundaries in its real browser, issuer, vault, gateway and deployment environment.
+
+Operations source re-fetch: 2026-10-31, HTML SHA256 e69ade54433ece3fb2bd1ff6c441fecd11acc749eb6bac8b33939420d1f2b9eb, unchanged from block1. Core and guide hashes are unchanged as well. [Business Operations](OPERATIONS.md) defines trusted UI/business semantics, durable adapters and external idempotency/reconciliation obligations. Focused SQLite/PostgreSQL and process-crash evidence belongs to block2; full stable-candidate/package/platform gates remain block3. No deployed host or arbitrary network exactly-once claim is made.
+
+Source revalidation on 2026-11-01 found all six core/current/changelog/Operations/mediated/guides pages byte-identical to the 2026-10-31 snapshots. A numbered draft URL remains mutable. Final candidate verification and external platform limits are recorded in the workspace migration STATUS; package publication is established only by its release receipt.

package/CONTRIBUTING.md

@@ -1,30 +1,33 @@
 # 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.
+Follow the live draft 0.3 [specification](https://personalagentprotocol.org/docs/0.3/spec)
+and [guides](https://personalagentprotocol.org/docs/0.3/guides). Tests/snapshots are
+supporting evidence. Core protocol, Mediated Sign-In v1 and [Operations v2](OPERATIONS.md) are in scope.
+Operations capability publication requires complete host consent/effect integration.
+Application business workflows remain host responsibilities. Source fingerprints and
+recommendation boundaries are in [CONFORMANCE.md](CONFORMANCE.md).
 Code is [MIT](LICENSE); confirm rights for third-party contributions.
 
 Use Node 24.21.0, TypeScript 5.9.3 and @types/node 24.10.0.
 Install the packageManager-pinned pnpm and run pnpm install --frozen-lockfile --ignore-scripts.
 
 ```sh
-npm run typecheck
-npm run build
-npm run typecheck:tests
-npm test
-npm run check:docs
+pnpm run typecheck
+pnpm run build
+pnpm run typecheck:tests
+pnpm test
+pnpm 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,
+Run `pnpm 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
+`pnpm 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

package/DELIVERY.md

@@ -1,8 +1,13 @@
 # Conversation delivery and transport
 
-The SDK targets Personal Agent Protocol draft 0.2. Company content, messages,
+Conversation messages and authorization events now use draft 0.3. Company content, messages,
 unknown events and partial text remain untrusted data for the host application.
 
+Account-history access requires explicit, nonempty company `historyScopes` in
+`createConversationService`, for example `['orders:read']`. There is no protocol
+read-scope default. The configured scopes and account/owner checks apply to HTTP
+reads and worker history; sending alone grants no read access.
+
 ## Client interoperability
 
 Clients keep immutable retry targets/message IDs, explicitly acknowledge named
@@ -76,3 +81,18 @@ 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.
+
+## Unreleased draft 0.3 breaking change
+
+Protocol messages use `author: { type: 'agent' | 'human' }`; company authors may
+also carry `id`, `name` and an HTTPS `image`. Responder checks use `author.type`,
+and only the server assigns recorded `role`. Authorization events always use
+`insufficient_scope` and name required scopes, including signed-out requests.
+
+Conversation state version 2 requires an explicit clean reset of old runtime
+state; SQLite/PostgreSQL reject version 1. Stop old writers and clear history,
+receipts, cursor identities, work, client outboxes and retry handles together.
+Preserve required configuration. No historical conversion or dual wire format is
+provided. An accepted request's fingerprint is never rewritten.
+
+Business-operation retries use the operation ID and approved revision, independently of message/work IDs. A conversation acceptance is not proof the action completed. [Operations v2](OPERATIONS.md) preserves uncertain claims/attempts through timeout, process death, expiry and restart. A different operation returned on retry does not establish the earlier outcome.