@poppykit/server 0.3.1 → 0.5.0

package/INTEGRATIONS.md

@@ -1,84 +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.
 
-MCP metadata identifies the exact resource URL, issuer and ES256 support when
-enabled. Challenges include Bearer and, if supported, DPoP with `resource_metadata`.
-The exact endpoint accepts no child paths or added query. All other APIs retain
-DPoP-only authentication. Configure the reference issuer `mcpResources` with the
-same `{url,dpop}` list: every grant chooses Bearer for a non-DPoP MCP server even
-when a proof was provided. DPoP MCP requires a valid proof. Bearer tokens are
-resource-bound; DPoP-bound tokens cannot be presented as Bearer.
+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 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.
+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.
 
-## Browser sessions
+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.
+
+## Browser joining
 
 ```ts
-const browser = createBrowserSessions({ endpoint: browserEndpoint, domain: companyDomain,
-  metadata, 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. `BrowserSessionAuthority.join` must atomically
-consume assertion jti and validate an active same-client/same-user session; `current`
-must read current session permissions. The reference issuer implements both on its
-existing durable issuer store/coordinator; SQLite uses targeted browser selectors.
-
-The browser handler verifies JWKS signature, asymmetric algorithm, typ, exact aud,
-times/lifetime, replay, client/user/session and HTTPS company return URL. Invalid
-requests return 400 with no cookie; successful requests set a host-only cookie and
-return 303 to the validated URL. Defaults are `__Host-poppy-session`, Path=/, Secure,
-HttpOnly, SameSite=Lax and max 3600 seconds capped by the current session lifetime.
-SameSite=None is supported; Strict is refused. `authenticate` resolves current
-authority on every request. Use `withSession` for scoped mutations so permission
-checks and work are ordered by the same policy/coordinator. Sign-in, scope changes
-and revocation are reflected immediately; no permissions are cached in cookies.
-Host adapters must isolate the agent browser from the user's consent browser.
+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,19 +1,10 @@
 # PoppyKit server
 
-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.2](https://personalagentprotocol.org/docs/0.2/spec).
-Verify requests, serve conversations and enforce current authority. Your company
-supplies accounts, consent UI, agent, business tools and HTTPS routing. [MIT](LICENSE).
+TypeScript SDK for companies implementing [Personal Agent Protocol draft 0.3](https://personalagentprotocol.org/docs/0.3/spec).
+Verify requests and serve conversations using your accounts, agent and business tools. [MIT](LICENSE).
 
 ## Install
 
-This source contains unreleased repairs; final version selection and publication are pending.
-
-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
 ```
@@ -26,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';
 
@@ -35,20 +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',
-    poppyDomains: ['company.example'], directScopes: [], resources: [endpoint],
-    metadata: createMetadataResolver(transport), store: database.issuer(issuer),
+    protectedResources: ['https://company.example'], supportedScopes: [], resources: [endpoint],
+    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({
-    endpoint, store: database.conversations(issuer), policy: auth.authority.policy,
-    authenticator: createRequestAuthenticator({ authority: auth.authority,
+    historyScopes: ['orders:read'],
+    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();
@@ -57,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,6 +83,24 @@ force another conversation's receipts out of storage.
 
 ## Non-durable use and resets
 
+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
 offers no cross-process persistence. The test fixture's object store is also
@@ -180,3 +200,38 @@ 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.

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 {};