@poppykit/server 0.4.0 → 0.5.0

package/API.md

@@ -5,13 +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
@@ -22,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,126 +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.
-
-For draft 0.3 discovery configure `protectedResources`, including
-`https://company.example` (host only, no port/path/trailing slash), and
-`supportedScopes`, the company-defined account scopes. This replaces
-`poppyDomains` and `directScopes` in reference issuer options. Direct and Device
-use that same supported list; Device configuration no longer has a `scopes` field.
-Mediated retains its own subset. Publish descriptions in company `auth.scopes` or
-a listed OpenAPI document. Names starting with `poppy:` are reserved. Issuer
-metadata emits the mandatory session/refresh grants and enabled sign-in grants.
-Token exchange for Bearer-only MCP remains a later migration stage.
-
-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, or RFC 8252 HTTP loopback IP
-callbacks (`127.0.0.1` or `[::1]`). Registration matching permits only the loopback
-port to vary; exchange must repeat the actual authorization redirect exactly.
-Direct requests require `dpop_jkt`; codes retain it and exchange requires that
-Session Key. Missing bindings in old pending authorizations/codes fail closed.
-
-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
-Account Tokens can start Sessions with new keys; a Session never changes its key. 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.
-
-Pre-version-3 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,
-}`. 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.
-The first authenticated poll atomically binds the device code to its live Session
-Key, including pending/slow-down polls. Other keys receive `invalid_grant`.
-Old device records without the new binding slot require a fresh flow. Prefer
-Direct whenever viable; enable Device only for appropriate device constraints
-under RFC 10027. Verification links remain HTTPS on issuer/protected-resource hosts.
-
-Hosted consent can resolve `sessionForKey({ clientId, userId, sessionKey })` to the
-current company Session without treating a client's local Session ID as a server
-ID. It validates live client/User ownership and returns current account/scopes.
-
-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 4. SQLite/PostgreSQL upgrade normalized version 3 under
-their writer lock; grant lineage survives. Earlier unsupported development versions
-still fail closed. See [STORAGE.md](STORAGE.md) for the exact upgrade behavior.
-
-Token admission selects an internal Session ID atomically by the DPoP thumbprint.
-It checks the client, User and optional assertion `agent_id` against the existing
-Session. Known ended keys return `invalid_grant`; key mappings/tombstones are
-retained indefinitely in this reference implementation. Token requests reject the
-old `session_id` parameter; responses omit `session_id` and `signed_in`.
-
-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,8 +1,20 @@
 # 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
 
-Target pinned Personal Agent Protocol draft 0.3. 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.
+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.
 

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,32 +1,33 @@
 # Contributing
 
-Follow the pinned draft 0.3 [specification](https://personalagentprotocol.org/docs/0.3/spec)
+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. This unreleased checkout has completed only the discovery
-stage of migration; auth, wire/storage and integrations still need their stages.
-Demo/business workflows and individual extensions are excluded.
+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

@@ -94,3 +94,5 @@ 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.