@poppykit/server 0.4.0 → 0.5.1

package/INTEGRATIONS.md

@@ -1,94 +1,87 @@
 # 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.
+Use trusted configured public URLs, the resource Session authenticator and its
+combined Session/account policy. Never derive public targets from arbitrary
+forwarding headers. The host supplies framework routing and ingress limits.
 
-## MCP authentication
+## APIs and MCP
 
-```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;
-}
-```
+Publish RFC 9728 metadata for a service that needs narrower tokens. Its resource
+identifies that service; normal sign-in/refresh accepts the configured resource.
+MCP resource metadata must exactly identify the advertised URL and name the
+Company issuer when account access exists. `mcpResourceMetadata({resource,issuer?,
+dpop})` supports issuerless resources too. Serve metadata without credentials.
+RFC 9728 inserts the well-known path before the resource path and preserves a query.
+
+Configure an MCP ResourceEndpoint with the resource's exact origin, pathPrefix,
+resource and mcp: {dpop,metadataUrl}. Query-bearing resources are allowed, but the
+whole request URL must match exactly: child paths or changed queries are rejected.
+Bearer is MCP's baseline. DPoP is accepted only when advertised; introspection
+returns dpopJkt:null only for an unbound token. Normal OAuth grants issue Bearer
+MCP tokens without token exchange. A token for one service is refused elsewhere.
+
+An ordinary MCP client without Poppy-Session can use its account access token.
+Its Principal has no Poppy User or Session. A Personal Agent sends its Session
+header on every API/MCP request; when present, the authenticator verifies it and
+joins the token's client identity. Poppy Session state is independent of both older
+MCP transport lifecycles and MCP 2026-07-28 per-request transport metadata. The SDK
+does not implement JSON-RPC, initialization or Mcp-Session-Id management.
+
+Catch AuthorityError and use mcpAuthorizationError(error,metadataUrl,dpop) for OAuth
+challenges containing resource_metadata. invalid_session remains JSON/400 and rate
+limits JSON/429 with Retry-After. Use sessions.policy.withCurrent for protected work.
 
-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. Non-DPoP MCP targets require Token Exchange of a current
-DPoP Session Token, a matching client assertion and the Session Key proof. Other
-grants reject those targets with invalid_target; exchange rejects DPoP MCP targets.
-Exchange preserves the Session and narrows subject scopes without rotating an
-Account Token. Metadata advertises exchange when a Bearer-only MCP resource exists.
-DPoP MCP continues using normal DPoP token grants. 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
+## Browser joining
 
 ```ts
-const browser = createBrowserSessions({ endpoint: browserEndpoint, domain: companyDomain,
-  authority: referenceIssuer.browserSessions,
-  policy: referenceIssuer.authority.policy, cookies: cookieStore, now: Date.now,
+const browser = createBrowserSessions({
+  endpoint: browserEndpoint, domain: companyDomain, authenticator,
+  policy: sessions.policy, cookies: database.browserCookies(companyId), now: Date.now,
+  clearLogin: async (request, headers) => hostLogin.clear(request, headers),
 });
-// Mount browser.join on browserEndpoint; no request-body logging at this route.
-const result = await browser.withSession(request, ['records:read'], principal => readRecords(principal));
+// GET/POST browserEndpoint -> browser.join
+// POST browserEndpoint + '/authorize' -> browser.authorize (preserve endpoint query)
 ```
 
-`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. The same store must implement `putJoin(codeHash,
-{cookieHash, expiresAt})` and atomic `consumeJoin(codeHash)`, which removes and
-returns the entry even if expired. Expire abandoned joins and rate-limit the public
-route in the host. Cookie/code hashes may be shared durably across handler replicas.
-`BrowserSessionAuthority.join(sessionKey)` resolves an existing active key; it never
-creates a Session. `current` reads current permissions. The reference issuer uses
-targeted key/Session selectors on its existing memory/SQLite/PostgreSQL stores.
-
-Mount both GET and POST. GET sets only a 60-second Strict __Host-poppy_join cookie
-and emits a random 256-bit hidden code, no-store, frame-ancestors none and same-origin
-opener isolation. POST consumes the submitted code first, including failed cookie,
-origin and proof checks. It requires that browser's cookie and a valid Session Key
-DPoP proof whose nonce is the code and which has no ath. Invalid requests return 400
-with no cookie; success clears the join cookie, sets the Session cookie and returns
-303 to the endpoint's website root. No provider signing/JWKS assertion is involved. 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.
+GET creates only a short-lived Strict join cookie and hidden random code, with
+no-store, framing and opener protection. The trusted agent reads its own isolated
+browser's code and separately POSTs JSON {code} to /authorize with Session/account
+credentials. Success is 204. It then submits only code in the browser form. Never
+accept a code from Company/model text, another browser or a user message.
+
+Browser POST atomically consumes the code, including failed submissions, checks its
+cookie/origin/site/expiry and prior authorization, and sets a new opaque cookie.
+No token, JWT or proof is carried by the browser form or URL. Success clears the
+join cookie and redirects 303 to the Company root. A signed-out join preserves an
+existing human website login; a signed-in join requires clearLogin to invalidate
+and clear host login, and replaces a previous protocol cookie.
+
+BrowserCookieStore supplies put/get/remove plus putJoin/authorizeJoin/consumeJoin.
+Stores persist only cookie/code hashes. authorizeJoin and consumeJoin serialize
+one-use code decisions across replicas. Bundled SQLite/PostgreSQL implementations
+are available through database.browserCookies(namespace). Rate-limit the public
+GET/POST routes and run bounded expiry cleanup.
+
+A browser cookie stores the authorization snapshot approved at join: same Session,
+account and scopes until rejoin. It does not gain later scopes or sign-in authority.
+Admission-token expiry alone does not end the approved cookie; Session expiry,
+revocation and current account policy still apply. Use browser.withSession for
+scoped work ordered by the same policy/coordinator. Defaults are Secure, HttpOnly,
+Path=/ and SameSite=Lax, at most one hour capped by Session lifetime.
 
 ## 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.
+createFeedbackHandler validates the Session before attributing a report and checks
+current authority without account scopes. Reports require only task/description,
+nonempty and at most 200/2000 Unicode codepoints, within a bounded JSON/UTF8 body.
+Unknown fields are inert data. accept receives a frozen report and verified Principal;
+never treat report text as instructions or put secrets/personal data into it.
+
+The optional allow hook returning false yields 429 with Retry-After:60. Malformed
+reports are 400; successful acceptance is 202 with no body. The client also supports
+a Company's 200 alternative response. Hosts own report retention, privacy filtering
+and downstream effect handling; feedback has no deduplication identifier.
+
+## Operations v2
+
+[OPERATIONS.md](OPERATIONS.md) defines API403/Poppy-Approval, MCP structuredContent/_meta and conversation operation/approval integration. Publish support only after all interfaces in use have trusted consent and durable effect recovery. Ordinary MCP clients retain their OAuth flow; one unsupported tool returns a tool error. No v1 extension endpoint is added.

package/OPERATIONS.md

@@ -0,0 +1,142 @@
+# Business operations (Operations v2)
+
+Enable `extensions.operations: operationsV2` in Company discovery only after
+installing these mechanics on every interface offering approval-gated actions.
+There is no v1 operations endpoint. The SDK does not auto-advertise support.
+`createBusinessOperations({companyId,metadata,policy,store,now?,retentionMs?,
+maxRevisions?,effectTimeoutMs?})` verifies the client's exact v2 metadata before returning an
+operation. Use the same verified Session/account policy and database coordinator
+as request authentication. OAuth-only MCP identity cannot approve Poppy work.
+
+The host chooses a stable URL-safe `operationId` for one business action, from
+its own records. It must never derive another action identity from the submitted
+approval, allocate a fresh action on retry, or reuse an ID for different work.
+The service stores every issued, unexpired revision with its exact request.
+A newer revision does not invalidate an older one. Summary/terms/expiry changes
+always receive a fresh opaque revision. Default admission is 1000 live revisions
+per action; overflow is 429/Retry-After, preserving issued revisions.
+
+## Propose and execute
+
+`OperationInput` contains `operationId`, authenticated `principal`, required
+`scopes`, `request`, optional parsed `approval`, and `proposal()`. The proposal
+callback supplies the current `summary`, optional `terms`, and `expires_at`.
+Describe every action condition, amount, recipient and date in the summary and
+terms. Give the User at least 15 minutes where business conditions permit. Use
+request/resource field names in structured terms, and document `approval_required`
+in your OpenAPI responses. These business-semantic choices belong to the host.
+
+Call `propose(input)` to publish terms without an effect, or route every action
+through `local`/`external`: without a valid approval they return
+`{kind:'approval_required',operation}` and execute nothing. Current authorization,
+scopes and ownership precede receipt replay. Signed-out ownership includes the
+exact Session instance/generation, not just a reused sid. Signed-in ownership
+includes Company, client, User and account; another Session of that same identity
+can approve. Signed-out access to account work receives an OAuth account challenge.
+Foreign identities see the same `operation_not_found` error. Recheck current
+policy before exposing protected results. Model text and Company conversation
+text cannot create the approval field.
+
+Bind requests with `captureApiOperationRequest(request)` (complete method/URL,
+base64 exact body bytes), `{channel:'mcp',url,name,arguments}`, or
+`{channel:'conversation',endpoint,conversationId}`. Use `parseApprovalHeader`,
+`mcpApproval(params)` or the accepted conversation message's `approval`.
+A mismatched/expired/unknown revision or wrong request performs nothing and
+returns freshly generated terms, never the rejected approval's revision.
+Execution is serialized by business action ID across all revisions and workers.
+
+`OperationOutcome` is `approval_required`, `pending` or `completed` (result and
+replay flag). `operationApiResponse(outcome,success?)` maps proposal to403 JSON and
+pending to503/Retry-After. The default success is JSON200; pass a stable response
+builder for your API's status/headers. Replay returns the first committed result
+or an equivalent response. No approval goes in WWW-Authenticate.
+`operationMcpResponse` produces the structured tool error or successful tool
+result, and HTTP503/Retry-After for unresolved work. Pass a caught
+`BusinessOperationError('extension_required')` to it for an ordinary tool error;
+only refusing the entire MCP client uses the OAuth extension_required challenge.
+
+## Local and external effect contracts
+
+`local(input,async approvedRevision => result)` executes only same-database
+mutations. Use `database.withTransaction` inside the callback, on the SAME
+`SqliteCompanyDatabase`/`PostgresCompanyDatabase` instance as the operation store
+and authorization coordinator. The host mutation and operation receipt commit or
+roll back together, including process death. Never put a network call, another
+database or nontransactional filesystem effect in `local`. It receives the actual
+approved revision: execute those exact terms, not a freshly recomputed quote.
+SQLite supplies scoped `run/get`; PostgreSQL supplies a scoped query connection.
+Handles reject use after their transaction ends.
+
+`external(input,adapter)` commits an uncertain execution claim BEFORE invoking
+`adapter.execute({key,operation})`. The key is derived from Company/action ID,
+not revision or message ID. The host MUST guarantee durable idempotency for that
+key in the external system, including concurrent calls and old paused workers.
+It must preserve the approved terms and authenticate/authorize the action at its
+submission boundary. Already accepted effects may finish during subsequent
+revocation; revocation cannot retroactively undo an external system's commit.
+Arbitrary network effects are not exactly-once, and a local receipt alone cannot
+make them so. Do not use this API with a downstream lacking this contract.
+
+Execution/reconciliation has a default30s deadline (`effectTimeoutMs`). It returns pending on a deadline, without cancelling or freeing a possibly running effect. A timeout/throw/process death leaves the claim uncertain indefinitely. Retrying
+returns pending and never calls execute again automatically. Lease expiration,
+new terms, process restart and receipt cleanup cannot release the claim.
+`reconcile(input,adapter)` asks the host's durable system by the same key:
+
+- `pending`: remain fenced, answer503 with Retry-After.
+- `completed,result`: record the actual outcome and replay it.
+- `absent`: assert the old worker cannot later commit outside that idempotency
+  fence; the SDK may submit the same key and original approved revision again.
+
+Reconciliation itself must be safe concurrently with execute and other
+reconcilers. The first committed result is immutable. Preserve a meaningful
+business failure as an equivalent terminal outcome when definitively known;
+never describe unknown effect state as failure. Hosts enforce ingress quotas,
+worker deadlines and external reconciliation scheduling. A deadline must return
+pending without deleting the durable claim, even if its worker is still alive.
+
+## Conversations
+
+Configure `createConversationService({operations:metadata,...})` only on an
+endpoint with complete v2 execution. It refuses unsupported clients with the
+extension challenge. It accepts approval-only user-side messages and operation-only
+Company messages, gated by current client metadata on requests/publication.
+`operationContext(work)` provides the accepted principal, conversation binding
+and only the actual message approval. Use that context with the business service,
+then `reply` with `operation` when proposing or the actual business outcome after
+execution. A conversation's lease/message receipts do not deduplicate effects.
+Repeated approval in a new message adds no event or work; same message-ID retries
+retain the ordinary original receipt. Cross-conversation approval fails binding.
+
+## Store contract, retention and migration
+
+`database.businessOperations(companyNamespace)` implements
+`BusinessOperationStore`: an asynchronous, serializable transaction on one action
+slot, including absent-row serialization across processes. Local host effects
+and policy checks must enlist in the same coordinator. Exceptions roll back the
+slot and effects even inside an enclosing transaction. Snapshots/results detach;
+unknown record versions and changed IDs are refused. Run
+`runBusinessOperationAdapterContract` from the adapter-contract subpath for a
+custom store, plus your engine's process-death/effect-enlistment tests.
+
+Business record version1 uses the existing SQLite/PostgreSQL `records` table,
+kind `business_operations`. No applied SQL migration is rewritten, no old writer
+can overwrite this kind through existing targeted auth/conversation selectors,
+and no credentials or user rows are removed. Authentication lifecycle records
+remain separate. Stop incompatible future writers before any version transition.
+
+Each execution retains its first protected result at least through the approved
+revision's expiry (default also24h after claim). `prune(operationId)` only drops a
+completed result and terms strictly AFTER retention. It keeps a minimal owner/
+action tombstone permanently; later attempts can get fresh terms but cannot
+execute that business action again. Uncertain claims/terms never prune. If you
+need to retire tombstones, an authoritative permanent business fence must still
+prevent re-execution; deleting the namespace is not retention. Protect stored
+terms/results with your database access/encryption policy. Approval attribution
+records the owner, approved revision and claim time; this states what the agent
+asserted, not proof of what a human saw.
+
+`node examples/operations.mjs --self-check` uses only synthetic identities and a
+private temporary SQLite file. Real hosts use the request authenticator and
+combined Session/account policy, not the example's test policy. Process-crash,
+concurrent-process, independent wire and PostgreSQL acceptance is in
+`tests/operations.test.mts`.

package/README.md

@@ -1,24 +1,10 @@
 # PoppyKit server
 
-Draft 0.3 migration (2026-10-28), pinned to the public source captured that day.
-Client/CLI 0.5.0 and server 0.4.0 break the earlier protocol contracts. Stop old
-writers and follow the documented storage/reset procedure before compatible
-writers resume. Registry, deployment and live acceptance have separate receipts.
-
-The Node 24.21.0 minimum is an owner-accepted compatibility baseline. Use a current patched Node 24 runtime where available; this minimum does not establish that older runtimes contain later security fixes. Build and release CI read `.node-version`.
-
 TypeScript SDK for companies implementing [Personal Agent Protocol draft 0.3](https://personalagentprotocol.org/docs/0.3/spec).
-Verify requests, serve conversations and enforce current authority. Your company
-supplies accounts, consent UI, agent, business tools and HTTPS routing. [MIT](LICENSE).
+Verify requests and serve conversations using your accounts, agent and business tools. [MIT](LICENSE).
 
 ## Install
 
-Use the exact version verified by its protected release workflow; check registry publication before installation.
-
-Requires Node **24.x, at least 24.21.0**, and ESM. CI tests Node 24.21.0 on Linux, macOS and Windows;
-other Node majors are unsupported. SQLite is optional/experimental and
-requires local filesystem locking.
-
 ```sh
 npm install @poppykit/server
 ```
@@ -31,7 +17,7 @@ in production. The reference issuer is optional; [existing issuers](AUTH.md) use
 an ExternalAuthorityAdapter instead.
 
 ```js
-import { createRequestAuthenticator, createConversationService } from '@poppykit/server';
+import { createRequestAuthenticator, createConversationService, createSessionAuthority } from '@poppykit/server';
 import { createMetadataResolver, createNodeTransport, createReferenceIssuer } from '@poppykit/server/reference-auth';
 import { SqliteCompanyDatabase } from '@poppykit/server/sqlite';
 
@@ -40,21 +26,24 @@ const transport = createNodeTransport();
 try {
   const issuer = 'https://company.example/issuer';
   const endpoint = 'https://company.example/conversations';
+  const metadata = createMetadataResolver(transport);
   const auth = createReferenceIssuer({
     issuer, tokenEndpoint: issuer + '/token', revocationEndpoint: issuer + '/revoke',
     protectedResources: ['https://company.example'], supportedScopes: [], resources: [endpoint],
-    metadata: createMetadataResolver(transport), store: database.issuer(issuer),
+    metadata, store: database.issuer(issuer),
     coordinator: database, now: Date.now,
   });
+  const sessions = createSessionAuthority({companyId:issuer,metadata,store:database.sessions(issuer),
+    coordinator:database,accountPolicy:auth.authority.policy,now:Date.now});
   const service = createConversationService({
     historyScopes: ['orders:read'],
-    endpoint, store: database.conversations(issuer), policy: auth.authority.policy,
-    authenticator: createRequestAuthenticator({ authority: auth.authority,
+    endpoint, store: database.conversations(issuer), policy: sessions.policy,
+    authenticator: createRequestAuthenticator({ sessions, 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
+    headers: { 'content-type': 'application/json' }, body: '{}' }))).status); // 400
 } finally {
   transport.close?.();
   database.close();
@@ -63,6 +52,8 @@ try {
 
 ## Guides
 
+- [Business operations](OPERATIONS.md): exact per-operation approval, durable retries and effect contracts.
+
 - [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.

package/RELEASING.md

@@ -89,3 +89,5 @@ certify a production keyring, physical terminal, browser engine, KMS or TLS depl
 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).
+
+The local Operations SDK checkpoint does not satisfy release acceptance. Complete the block3 CLI business-approval experience and stable all-tests/package/native gates before publication. Operations metadata must remain opt-in to fully configured hosts. Include OPERATIONS.md and both operation examples in candidate archives.

package/SECURITY.md

@@ -11,3 +11,5 @@ 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.
+
+Business-operation approval requires the trusted per-operation UI described in [OPERATIONS.md](OPERATIONS.md). Keep Company/model text separate from user consent. Local effects must share the receipt transaction; arbitrary network effects require host idempotency and reconciliation. Retain uncertain claims until the actual outcome is known.

package/STORAGE.md

@@ -3,7 +3,8 @@
 Request paths use targeted domain selections, not whole-state rewrites. Node 24.x, at least 24.21.0, 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.
+implement `ConversationStore`, `IssuerStore`, `SessionStore`, `BrowserCookieStore`
+and `AuthorityCoordinator` themselves.
 The tested Node 24.21.0 runtime marks `node:sqlite` experimental.
 
 ```ts
@@ -71,7 +72,8 @@ its own idempotency key (such as the stable work ID), or the application must re
 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, replay entries or expired/revoked/orphaned
+codes, authorizations, access tokens, browser cookies/join codes, expired resource
+Sessions, replay entries or expired/revoked/orphaned
 Account Token hashes. Every used hash for a live lineage remains replay-detectable
 through its fixed expiry; retained size follows rotation volume. It does not delete grants,
 work intent, message receipts or conversation events. Receipt identity remains
@@ -81,21 +83,23 @@ force another conversation's receipts out of storage.
 
 ## Non-durable use and resets
 
-Normalized issuer state version 3 upgrades to version 4 once, under the existing
-SQLite writer/PostgreSQL namespace lock. Stop old writers before using the new
-adapter. No SQL schema change is needed: `sessionKeys` records use the existing
-namespace/kind/ID primary key. Token selectors load that mapping and its internal
-Session ID in the same transaction as creation, ownership checks and rotation.
-Mappings remain indefinitely after a Session ends, preventing key reuse.
-
-Old keys could belong to several Sessions, so the upgrade ends old Sessions and
-tombstones every known old access-token key rather than guessing a mapping.
-Internal Session IDs, sticky account records, stable Users, grants, all retained
-Account Token hashes, revocation fences and accepted-work authority remain.
-Legacy pending authorization/code/Device/Mediated records are retired: restart
-sign-in rather than accepting consent without the new binding. Existing compatible
-Account Tokens can create fresh-key Sessions. Unsupported earlier state versions
-are refused. The upgrade scans a namespace once; normal selectors stay targeted.
+Normalized issuer state versions 3 and 4 upgrade to version 5 once, under the
+existing SQLite writer/PostgreSQL namespace lock. Stop old writers before opening
+the new adapters; their version checks reject the upgraded namespace. Applied SQL
+migration history is unchanged: this is a JSON record-format transition.
+
+The upgrade preserves the generation, Sessions and key mappings, grants and every
+retained refresh-token hash, pending authorizations/codes, verifying sign-in hooks,
+replay fences and nonces. It does not expire Sessions or clear pending consent.
+Access-token records gain client/account identity only where an existing grant or
+Session proves it; conflicting or missing associations remain unresolved. Unknown
+earlier versions fail closed. Custom issuer adapters must upgrade the complete
+namespace under their writer lock before normal targeted reads.
+
+OAuth account access is independent of resource Sessions. The record upgrade does
+not replay or reinterpret old pending requests. Keep uncertain
+work and encrypted delivery references for reconciliation; do not reset a store or
+reinterpret an unresolved record as a fresh request.
 
 `new SqliteCompanyDatabase(':memory:')` is an explicit non-durable adapter for tests
 and development. Each instance is separate, is lost at close/process death, and
@@ -196,3 +200,44 @@ never a production migration command.
 `runIssuerAdapterContract` joins the existing reusable conversation contract in
 `@poppykit/server/adapter-contract`. Run both against two fresh shared handles;
 process death, lock ordering and DB durability still require backend-specific tests.
+
+
+## Resource Sessions and browser cookies
+
+Use database.sessions(companyId) and database.browserCookies(companyId), also for
+issuerless Companies. Resource Session records and their namespace generation are
+separate from legacy issuer Sessions and account grants. No applied SQL history is
+rewritten; these records use the existing namespaced JSON table and indexes.
+
+SessionStore.read(clientId,sid) returns version, generation and the stored record.
+transaction(clientId,sid,at,change) must serialize admission across all sids for that
+client, including absent records, and supply SessionAdmission.activeCount and
+earliestExpiry for non-ended records with expiresAt > at. Counts and record commit
+are one transaction. Callbacks are synchronous/detached; rollback and binding checks
+apply. PostgreSQL takes client-before-sid advisory locks, SQLite its writer lock.
+The default authority cap is 10,000 live Sessions per client, lifetime one day.
+Expired records may be explicitly forgotten by bounded cleanup; a recreated sid
+has a fresh instanceId, distinct from its prior resource Session. Operations v2
+must preserve this distinction when defining signed-out approval ownership.
+
+BrowserCookieStore stores opaque hashes and immutable approved Principal snapshots.
+authorizeJoin(codeHash,principal) conditionally authorizes one live join;
+consumeJoin atomically removes/returns it, including expired entries. remove deletes
+a superseded browser-cookie hash. The host must implement these atomic operations
+across replicas and use current account/Session policy when serving cookies.
+Uncertain mediated verifying records are excluded from expiry cleanup and remain
+in pending capacity counts until host reconciliation; never delete them to free quota.
+
+Custom Session/browser adapters can run runSessionAdapterContract and
+runBrowserCookieAdapterContract from @poppykit/server/adapter-contract against two
+shared handles. See [legacy retirement](migrations/RETIREMENT.md) before any deletion.
+
+## Business operation persistence
+
+[Operations storage contracts](OPERATIONS.md#store-contract-retention-and-migration) are separate from authentication lifecycle operations and message receipts. BusinessOperationStore uses an asynchronous transaction for same-database effects, unlike synchronous issuer/conversation callbacks. SQLite and PostgreSQL use the separate business_operations record kind. Use the same company database instance for policy, operation storage and local effects. No existing SQL history, credentials or uncertain work is deleted. Unknown versions fail closed. External effects require a durable downstream idempotency/reconciliation contract. Never prune or release an uncertain business claim after a worker deadline.
+
+Postgres adapters handle socket errors while they own a checked-out connection.
+Connection loss invalidates the transaction, rejects the operation and discards
+the broken connection. A successful retry must reconcile durable state first;
+a lost COMMIT response does not prove rollback. Callers still own their pool and
+its idle `error` handler, and host-enlisted connection lifetimes.

package/dist/adapter-contract.d.ts

@@ -7,6 +7,18 @@ export type IssuerAdapterFixture = () => Promise<{
 }>;
 /** A fresh shared namespace, including absent-row serialization; no vendor-specific fixture is required. */
 export declare function runIssuerAdapterContract(fixture: IssuerAdapterFixture): void;
+export type SessionAdapterFixture = () => Promise<{
+    store: import('./auth/session.js').SessionStore;
+    second: import('./auth/session.js').SessionStore;
+    close(): Promise<void>;
+}>;
+export declare function runSessionAdapterContract(fixture: SessionAdapterFixture): void;
+export type BrowserCookieAdapterFixture = () => Promise<{
+    store: import('./browser.js').BrowserCookieStore;
+    second: import('./browser.js').BrowserCookieStore;
+    close(): Promise<void>;
+}>;
+export declare function runBrowserCookieAdapterContract(fixture: BrowserCookieAdapterFixture): void;
 type Store = ConversationOptions['store'] & {
     inspect(): Promise<import('./conversation/service.js').ConversationStoreState>;
     adminTransaction<T>(change: (draft: import('./conversation/service.js').ConversationStoreState) => T): Promise<T>;
@@ -17,4 +29,10 @@ export type ConversationAdapterFixture = () => Promise<{
     close(): Promise<void>;
 }>;
 export declare function runConversationAdapterContract(fixture: ConversationAdapterFixture): void;
+export type BusinessOperationAdapterFixture = () => Promise<{
+    store: import('./operations.js').BusinessOperationStore;
+    second: import('./operations.js').BusinessOperationStore;
+    close(): Promise<void>;
+}>;
+export declare function runBusinessOperationAdapterContract(fixture: BusinessOperationAdapterFixture): void;
 export {};