@poppykit/server 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,22 +1,18 @@
 # Changelog
 
-## 0.1.0 — initial development release candidate (unpublished)
+## 0.1.1
 
-Request authentication, existing-issuer integration, optional Direct/Device/Mediated
-reference issuer, atomic targeted SQLite adapters, JSON/SSE conversation lifecycle,
-API/browser/feedback hooks and independent-peer/crash regressions.
+Documentation refresh: registry installation, runnable quickstarts, focused guides
+and the tagged GitHub/OIDC release runbook. No runtime API, storage format or
+third-party dependency change.
 
-- Select MIT licensing and ship the complete LICENSE.
-- Prepare public package metadata and the initial 0.1.0 version.
-- Preserve J8 strict TypeScript tests, real subprocess/security regressions and
-  immutable installed-package verification on Linux, macOS and Windows.
+## 0.1.0
 
-No npm publication has occurred. Version 0.x APIs/storage may still change; record
-compatibility and migration/reset implications with future changes. This release
-does not promise stable 1.0 compatibility or certify external host integrations.
+Initial MIT development release, published manually. Discovery, safe HTTPS, all
+three sign-in methods, targeted durable storage and recovery, conversations and
+API/browser/feedback hooks. The CLI uses the client SDK with trusted secure-backend
+adapters. J8 established strict typed tests and exact installed-artifact checks.
 
-## 0.0.0 — historical private development candidates
-
-J1–J8 established protocol capabilities, targeted storage, durable recovery,
-documentation, strict tests and fail-closed release verification. Their prior
-commits/artifact results remain historical evidence for those exact candidates.
+Version 0.x may still change APIs/storage; future changes must explain compatibility,
+migration/reset and security implications. No stable 1.0 or external-host certification
+is promised. Older private 0.0.0 candidates retain their own historical evidence.

package/CONTRIBUTING.md

@@ -1,50 +1,38 @@
 # Contributing
 
-This package targets Personal Agent Protocol draft 0.2. Check the current
-[specification](https://personalagentprotocol.org/docs/0.2/spec) and
-[guides](https://personalagentprotocol.org/docs/0.2/guides); retained snapshots and
-tests are supporting evidence. Distinguish MUST requirements, SHOULD recommendations
-and product choices. Individual extensions and demo/business workflows are excluded.
+Follow the live draft 0.2 [specification](https://personalagentprotocol.org/docs/0.2/spec)
+and [guides](https://personalagentprotocol.org/docs/0.2/guides). Tests/snapshots are
+supporting evidence. Demo/business workflows and individual extensions are excluded.
+Code is [MIT](LICENSE); confirm rights for third-party contributions.
 
 Use Node 24.12.0, TypeScript 5.9.3 and @types/node 24.10.0.
-Install with the pinned pnpm version in package.json and `pnpm install --frozen-lockfile`.
-Run `npm run typecheck`, `npm run build`, `npm test` and `npm run check:docs`.
-CI partitions tests without omitting any test file; full `npm test` remains useful
-locally. Read [RELEASING.md](RELEASING.md) before changing workflow/release behavior.
+Install the packageManager-pinned pnpm and run pnpm install --frozen-lockfile.
 
-Keep changes small and complete: include callers, declarations, regression checks
-and documentation. Do not log credentials, weaken destination validation or silently
-reset persisted data. Pull requests must explain checks actually run and limitations.
-Use the repository's Issues for non-sensitive defects and feature discussions.
-Code is licensed under [MIT](LICENSE). No separate contribution agreement is
-configured; confirm permission for third-party contributions and obtain owner
-authorization before publishing.
+```sh
+npm run typecheck
+npm run build
+npm run typecheck:tests
+npm test
+npm run check:docs
+```
 
-## TypeScript test harness and coverage
+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,
+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.
 
-First-party tests, executable fixtures, process workers and packaged verification
-scripts are canonical `.mts` files. Run `npm run typecheck:tests` for the complete
-strict program and `npm run build:tests` before individual
-`node scripts/run-checks.mjs GROUP` commands (unit, contracts, integration or
-validation). `npm test` performs that checked harness build and runs all groups.
-Build production first with `npm run build`; tests import compiled `dist/*.js`,
-not TypeScript source. No loader or native type stripping replaces the compiler.
+`npm 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
+are retained, but arbitrary children may not merge and killed workers may not flush.
+Installed/OS/host checks are separate evidence; no percentage proves conformance.
 
-The existing TypeScript compiler emits ignored adjacent `.mjs` files only after
-all strict diagnostics pass. Failed builds remove stale canonical outputs.
-`scripts/build-tests.mjs` is compiler/bootstrap tooling, not an unchecked test
-runner. Canonical test sources use LF, enforced by `.gitattributes`, so Linux and
-Windows validate the same exact source bytes. Test output stays outside the npm
-package allowlist. Retained JavaScript release/build tools and packaged examples
-are genuine production tooling/examples; retained protocol captures are references.
-
-Run `npm run coverage` for a production build, checked harness and native Node
-24.12.0 line/branch/function report. `coverage/summary.txt`, `coverage/lcov.info`,
-`coverage/report.json` and `coverage/raw/` are generated local reports. Metrics
-refer to first-party compiled `dist` JavaScript; production emits no source maps
-and no TypeScript remapping is claimed. Third-party `node_modules` is excluded;
-unloaded modules are listed explicitly. Raw child-process reports are retained,
-but arbitrary subprocess execution is not guaranteed to be merged into the native
-runner summary, and killed/crashed workers may not flush counters. Actual installed
-package/OS checks remain separate evidence. No percentage threshold substitutes
-for protocol, negative/security, process and platform assertions.
+Include callers, meaningful regression evidence and docs with behavior changes.
+Preserve credential/destination validation, private errors and persisted data.
+Report checks actually run and limits. Use Issues for non-sensitive defects and
+[SECURITY.md](SECURITY.md) for vulnerabilities. Follow [RELEASING.md](RELEASING.md)
+before tagging/publishing; obtain explicit owner authorization.

package/DELIVERY.md

@@ -3,48 +3,12 @@
 The SDK targets Personal Agent Protocol draft 0.2. Company content, messages,
 unknown events and partial text remain untrusted data for the host application.
 
-## Client
+## Client interoperability
 
-Bind `createConversationClient` to the existing auth lifecycle:
-
-```ts
-const target = await auth.target(connectionId);
-const conversations = createConversationClient({
-  ...target, connectionId, store, clock: { now: Date.now },
-  authorizedRequest: request => auth.authorizedFetch(connectionId, request, target),
-  authorization: (id, scopes) => auth.authorization(id, scopes),
-});
-for await (const item of conversations.watch(conversationId, { consumer: 'ui', signal })) {
-  await processEvent(item.event);
-  await item.ack();
-}
-```
-
-`authorization(eventOrError)` returns the single auth lifecycle's verified
-required/granted/missing scopes and eligible methods. The UI requests consent and
-chooses an advertised method; Device or Mediated does not require Direct support.
-
-`read` returns one page; `drain` follows `has_more` immediately. Named consumers
-advance only on explicit acknowledgement. `watch` accepts SSE or JSON fallback,
-skips unknown event types, deduplicates up to 10,000 event IDs per invocation, and
-never rewinds its cursor on a duplicate. JSON pagination has its separate
-`maxPages` bound (default 1000), without consuming reconnect attempts. Reconnects
-are bounded (default 4); exhaustion is explicit `reconnect_exhausted`.
-
-`lastEventId` takes precedence over the starting cursor. On reconnect the watcher
-sends `Last-Event-ID`. `onPartial` is display-only: a null value clears unfinished
-text on completion/disconnect; never execute or reason from an incomplete delta.
-Messages are actionable only after a complete `message` event. SSE frames and
-JSON fallback are limited to 1 MiB, streams to 16 MiB, and partial text per stream
-to 1 MiB. UTF-8 fragmentation and CR/LF/CRLF are supported.
-
-`cursor_expired` is an explicit history gap. Inform the user, then reset a named
-consumer and reread retained history, or supply `onHistoryGap` returning true.
-Automatic recovery is limited to one reset per watch; it does not recover missing
-events. Checkpoints and pending sends survive process restart with durable stores.
-Send retries keep their original connection, issuer, endpoint, ID, body and read
-parameters. Abort signals are invocation-local and are never persisted. Canceling
-delivery does not cancel an accepted company action or prove a lost send failed.
+Clients keep immutable retry targets/message IDs, explicitly acknowledge named
+consumers and treat cursor_expired as a history gap, not recovered history. A
+disconnected client cannot undo accepted work. The [client delivery guide](https://github.com/LMol-4/poppykit-client/blob/main/DELIVERY.md)
+specifies watch/reconnect bounds, partial text, pagination and checkpoint handling.
 
 ## Node transport
 
@@ -67,7 +31,7 @@ the durable cursor and fresh authorization.
 Metadata caching remains bounded and honors freshness, Age, validators, no-cache
 and no-store, with a 300-second upper bound. Expired entries revalidate; 304s retain
 prior caching directives. `resolver.invalidate(target?)` fences old pending cache
-writes without bypassing fetch concurrency/rate limits. J2 rejects changed saved
+writes without bypassing fetch concurrency/rate limits. The auth lifecycle rejects changed saved
 issuer/endpoint/resource bindings rather than rerouting persisted work.
 
 ## Company service and retention

package/README.md

@@ -1,117 +1,68 @@
 # PoppyKit server
 
-TypeScript SDK for companies exposing services through [Personal Agent Protocol
-draft 0.2](https://personalagentprotocol.org/docs/0.2/spec). Verify requests, serve
-JSON/SSE conversations, enforce current permissions, support browser-session joining
-and accept feedback. Your company owns accounts, consent UI, agent and business tools.
+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).
 
-## Installation
+## Install
 
-Requires Node **24.12.0 or later** and ESM. CI certifies Node 24.12.0; later majors
-have no separate certification. Optional SQLite uses experimental `node:sqlite`
-and requires local filesystem locking.
-
-Version **0.1.0** is an initial development release candidate under the [MIT license](LICENSE).
-It has not been published. Install a verified tarball:
+Requires Node **24.12.0+** and ESM. CI tests Node 24.12.0 on Linux, macOS and Windows;
+later majors are not separately certified. SQLite is optional/experimental and
+requires local filesystem locking.
 
 ```sh
-npm install ./poppykit-server-0.1.0.tgz
+npm install @poppykit/server@0.1.1
 ```
 
-The only production dependency is `jose@6.2.12`. Neither client SDK nor CLI is required.
-First-publication preparation is in [RELEASING.md](RELEASING.md).
-
-## Quickstart
-
-The complete [quickstart](examples/quickstart.mjs) creates an optional reference
-issuer, verified request authenticator and conversation service, then checks that
-an unauthenticated request is rejected. It starts no network listener:
-
-```sh
-node examples/quickstart.mjs
-```
+## Configure a service
 
-Its essential service configuration is:
+This runnable example starts no listener and rejects an unauthenticated request.
+`:memory:` is non-durable; use a private file and configured company sign-in hooks
+in production. The reference issuer is optional; [existing issuers](AUTH.md) use
+an ExternalAuthorityAdapter instead.
 
 ```js
 import { createRequestAuthenticator, createConversationService } from '@poppykit/server';
-const conversations = createConversationService({
-  endpoint, store: database.conversations(issuer), policy: auth.authority.policy,
-  authenticator: createRequestAuthenticator({ authority: auth.authority,
-    endpoints: [{ origin: 'https://company.example', pathPrefix: '/conversations', resource: endpoint }],
-    now: Date.now }), clock: { now: Date.now },
-});
+import { createMetadataResolver, createNodeTransport, createReferenceIssuer } from '@poppykit/server/reference-auth';
+import { SqliteCompanyDatabase } from '@poppykit/server/sqlite';
+
+const database = new SqliteCompanyDatabase(':memory:');
+const transport = createNodeTransport();
+try {
+  const issuer = 'https://company.example/issuer';
+  const endpoint = 'https://company.example/conversations';
+  const auth = createReferenceIssuer({
+    issuer, tokenEndpoint: issuer + '/token', revocationEndpoint: issuer + '/revoke',
+    poppyDomains: ['company.example'], directScopes: [], resources: [endpoint],
+    metadata: createMetadataResolver(transport), store: database.issuer(issuer),
+    coordinator: database, now: Date.now,
+  });
+  const service = createConversationService({
+    endpoint, store: database.conversations(issuer), policy: auth.authority.policy,
+    authenticator: createRequestAuthenticator({ authority: auth.authority,
+      endpoints: [{ origin: 'https://company.example', pathPrefix: '/conversations', resource: endpoint }],
+      now: Date.now }), clock: { now: Date.now },
+  });
+  console.log((await service.handle(new Request(endpoint, { method: 'POST',
+    headers: { 'content-type': 'application/json' }, body: '{}' }))).status); // 401
+} finally {
+  transport.close?.();
+  database.close();
+}
 ```
 
-`database`, `auth`, `issuer` and `endpoint` are created in the runnable example.
-Use a private database file for persistence and your HTTPS framework to route
-trusted public Requests to `conversations.handle(request)`. Configure company
-account/consent hooks before advertising sign-in methods.
-
-## Configuration and authentication
-
-Existing issuers integrate through `ExternalAuthorityAdapter`: provide token
-introspection, an explicit revocation-visibility guarantee and `AuthorityPolicy`
-that orders checks with protected writes. `createRequestAuthenticator` verifies
-the actual public method/URL and DPoP/resource binding. Resolve public URLs at
-your trusted proxy boundary; do not trust arbitrary forwarded headers. Core
-imports do not load or run the optional reference issuer.
-
-The separate `/reference-auth` implements Direct, Device and Mediated flows.
-Configure endpoints/trusted hooks, publish discovery/authorization metadata and
-route token/revocation and method handlers. Your company authenticates humans,
-protects consent with browser sessions/CSRF, delivers/verifies codes and chooses
-scopes. Opening a consent link never approves it. See [AUTH.md](AUTH.md).
-
-## Examples and common operations
-
-Route protocol requests to `conversations.handle(request)`. Workers use `claim`,
-`reply`, `finish` and lifecycle methods rather than writing rows directly. Use
-`requireAccount(work, scopes)` or protected-operation hooks before accessing
-account data. Model text cannot grant permission. Your application owns tool
-execution, validation and effect idempotency; receipt/publication deduplication
-does not make external writes exactly-once.
-
-`createBrowserSessions` integrates your cookie store with current session authority.
-`createFeedbackHandler` accepts validated reports, including signed-out sessions.
-`mcpResourceMetadata` and `mcpAuthorizationError` integrate an existing MCP server
-and issuer. See [INTEGRATIONS.md](INTEGRATIONS.md), [DELIVERY.md](DELIVERY.md) and
-the independent generic request fixtures in `tests/independent-peer.test.mjs`.
-
-## Errors, cancellation, retries and limits
-
-`AuthorityError` contains a safe code, HTTP status and authentication headers.
-Conversation handlers return protocol responses for known errors; your framework
-must handle unexpected host failures without exposing private diagnostics. Bound
-ingress bodies/rates before authentication. Propagate cancellation; a disconnected
-client cannot undo accepted application work.
-
-JSON pages and SSE events obey UTF-8 budgets. Notifications are hints; durable
-targeted reads reconcile lost notifications. [DELIVERY.md](DELIVERY.md) documents
-cursor/history gaps, waiting and record-specific retention. Choose
-`stop-account-work` or `allow-accepted-work-to-finish` deliberately; new requests
-always need current access. Immediate reference-issuer revocation visibility is
-an implementation policy, not a universal protocol requirement.
-
-## Storage and production responsibilities
-
-Use one `SqliteCompanyDatabase` for reference issuer, conversations and coordinator
-so authorization, revocation and protected writes share a transaction. SQLite
-serializes writers and requires local filesystem locking. Supply your own
-`ConversationStore`, `IssuerStore` and `AuthorityCoordinator` for other databases;
-adapters enforce cross-process atomicity. [STORAGE.md](STORAGE.md) specifies
-contracts, retention and explicit reset.
-
-Company credentials and signing infrastructure remain your responsibility. The
-personal-agent identity provider is a distinct trust role in the client package.
-No model, database service, deployment vendor or demo is required.
-
-## Reference and support
-
-[API.md](API.md) maps public entry points and declarations to deeper guides.
-This independent draft implementation has generic integration and packaged tests;
-deployed issuer, proxy, database and browser policies need operator validation.
-Individual extensions and business workflows are excluded. See
-[CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md),
-[CHANGELOG.md](CHANGELOG.md) and [RELEASING.md](RELEASING.md). No public license
-grant has been selected; licensing remains an owner decision before publication.
+## Guides
+
+- [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.
+- [Integrations](INTEGRATIONS.md): MCP, browser cookies and feedback.
+- [API exports](API.md), [contributing](CONTRIBUTING.md), [security](SECURITY.md),
+  [changelog](CHANGELOG.md) and [releasing](RELEASING.md).
+
+Your ingress must bound bodies/rates before authentication, supply the trusted
+public URL and propagate cancellation. Never trust arbitrary forwarding headers.
+Use current policy before protected work; model text cannot grant permission.
+Receipt/publication deduplication does not make external effects exactly-once.
+Validate deployed database, issuer and browser policies; no model/service vendor
+or demo application is required.

package/RELEASING.md

@@ -1,193 +1,91 @@
-# Release preparation and owner runbook
-
-The owner selected the **MIT** license and initial development version **0.1.0**.
-`private: false`, `publishConfig.access: public` and the shipped [LICENSE](LICENSE)
-prepare these candidates for a public release; they do not publish anything.
-No package has been published. Tags, npm publication and external settings remain
-separate owner-authorized actions. This is an initial 0.x release, not a stable 1.0
-compatibility promise.
-
-## Verification graph
-
-Every push, pull request and manual CI run calls the same repository-local
-`.github/workflows/verify.yml`. Documentation-only changes run the graph too;
-there are no path filters. A clean GitHub-hosted Linux job builds and packs once.
-The release manifest binds full source SHAs, package/version, filenames, byte
-counts, SHA256 and npm SHA512 integrity to those unchanged tarballs.
-
-| Job | Responsibility |
-| --- | --- |
-| candidate | Typecheck/build from exact source, pack once, record/upload identity |
-| fast | Documentation links/fences and small unit checks |
-| contracts | Storage, authentication, network and conversation contracts |
-| integration | API/browser/feedback and independent peers; CLI installs all pinned candidates |
-| packaged-linux/windows/macos | Install unchanged tarballs; startup, exports, SQLite and representative platform behavior |
-| validation | Release failure simulations, registry/toolchain guards and actual workflow wiring assertions |
-| gate | Always report; require each allowlisted job result to equal success and recheck artifact identity |
-
-The candidate job strictly typechecks and compiles the complete TypeScript test
-harness once before packing. It uploads a separate same-run `test-harness`
-artifact, never inside an npm candidate. Each unprivileged test/OS job checks the
-full source commit, complete canonical source inventory, exact LF source hashes
-and exact emitted-output hashes before using that harness. Runtime/packaged checks
-still import the unchanged candidate's installed JavaScript and execute real npm
-shims. The publisher consumes only tested npm tarballs and never the harness.
-
-All deterministic source tests run once on Linux, partitioned by
-`.github/test-groups.json`. Its runner rejects unassigned/duplicate test files.
-The CLI does not rerun complete SDK suites. It checks out the exact full client
-and server SHAs in its candidate JSON files, builds/installs their tarballs, and
-tests the combined package boundary. The SDKs have no dependency on one another;
-the server candidate is a CLI integration peer, not a production CLI dependency.
-Private cross-repository checkouts require owner-provided read access; no local
-untracked sibling directory is assumed.
-
-Node 24.12.0 is the supported CI baseline on GitHub-hosted ubuntu-latest,
-windows-latest and macos-latest. Later Node majors are not separately certified.
-The CLI checks unsupported Node 22.17.1 once on Linux. Most JavaScript/type checks
-do not need an OS-by-runtime matrix. Packaged OS checks exercise installed shims,
-paths/SQLite and the CLI's generic encrypted-backend/lifecycle fixture. They do
-not certify a production OS keyring, physical terminal, browser engine or KMS.
-
-SDK ordinary CI may restore a pnpm cache keyed by its frozen lockfile; installed
-dependencies are never shared across OSes. Release-context verification restores
-no dependency cache. The unpublished CLI dependency is supplied explicitly as a
-tarball; SDK lockfiles and full commit/version pins govern inputs, with exact
-TypeScript 5.9.3/@types-node 24.10.0/undici-types 7.16.0 tooling. No privileged
-release consumes a pull-request cache, artifact or check-name lookup. Artifacts
-are downloaded from this run only, and their manifest digest comes from the
-candidate job output. Failure logs retain seven days; candidates retain fourteen.
-Expired/missing artifacts require a new complete verification run.
-
-## Release workflow and fail-closed gate
-
-`release.yml` is manual dispatch only. Dispatch an existing owner-approved
-`vVERSION` tag, supply the full tagged commit, matching version/tag, and
-leave `publish=false` for verification only. A branch dispatch, wrong SHA,
-version/tag mismatch, moved tag or missing/changed artifact is rejected. Do not
-push a tag merely to test workflow syntax. All actions are pinned to immutable
-commits; reusable verification is the same commit as its caller.
-
-The allowlist is candidate, fast, contracts, integration, packaged-linux,
-packaged-windows, packaged-macos and validation. Missing, empty, failed, canceled
-and skipped results all fail. The always-running gate has no permission to
-publish. The publisher needs the reusable verification workflow to succeed AND
-its ready output to be exactly true AND explicit publish selection. It then
-rechecks source/commit/ref/version, manifest digest, every tarball, unchanged
-packed metadata, private/license policy, npm/toolchain and registry state.
-
-Only the publishing job requests `id-token: write`. It runs on GitHub-hosted
-Linux in protected environment `npm`. There is no publish credential in PR CI,
-no workflow_run artifact promotion, no checkout of PR code in a privileged job,
-no build/install/pack in the publisher, and no automatic publication on push/tag.
-Publication uses `npm publish TESTED_TARBALL --access public --provenance --ignore-scripts`.
-It publishes the unchanged bytes downloaded and checked in that job. Publication
-is serialized per repository and is never canceled by a newer release run.
-
-Safe local tests execute the gate with failed/canceled/missing/skipped checks,
-wrong commit/version/tag/ref, missing artifact, tampered tarball/manifest and an
-absent trusted digest. Registry tests reject an existing version, unauthorized or
-uncertain registry responses, unsupported tools and mismatched dependency bytes.
-These simulations and actionlint validate code/wiring. They do not prove GitHub
-environment settings, npm ownership or OIDC exchange work.
-
-Any documentation/package-metadata/source change after J6 creates a new candidate.
-J6 evidence applies only to J6's recorded commits/digests. Re-run this complete
-graph on final commits/tarballs and retain the new manifests/platform results.
-Never label changed bytes publishable using old evidence. A passing Windows
-local run does not substitute for actual hosted Linux/macOS jobs.
-
-## Owner configuration — external, not performed by this repository
-
-Rechecked against [npm trusted publishers](https://docs.npmjs.com/trusted-publishers/),
-[GitHub secure use](https://docs.github.com/en/actions/reference/security/secure-use),
-[OIDC](https://docs.github.com/en/actions/concepts/security/openid-connect), and
-[deployment environments](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments)
-on **2026-10-23**. Recheck those live requirements before first publication:
-
-1. The owner confirmed the `@poppykit` scope and selected MIT/version 0.1.0.
-   Confirm the actual publishing account has package-name/maintainer rights and
-   the chosen version is unused. The complete LICENSE is in the package allowlist
-   and release notes describe this initial development candidate.
-   Confirm repository.url exactly matches the actual GitHub repository.
-2. Protect main, release tags, Actions files/scripts and candidate pins with
-   repository rules and review/CODEOWNERS appropriate to the actual team. Require
-   the complete verification result for the exact commit. Prevent unreviewed
-   workflow changes or tag replacement. Read-only PR permissions and trusted
-   publishing cannot enforce these owner settings themselves.
-3. Create environment `npm` in each package repository with required reviewers,
-   self-approval restrictions, protected release-tag rules and no admin bypass
-   where the repository plan supports them. Confirm feature availability; an
-   unprotected environment name alone provides no approval barrier. Add environment
-   variable `NPM_PUBLISH_ENABLED=true` only after setup/authorization. Missing
-   or false configuration fails the publisher's check.
-4. Configure each npm package's trusted publisher for GitHub owner `LMol-4`,
-   the corresponding `poppykit-client`, `poppykit-server` or `poppykit-cli`
-   repository, workflow filename **release.yml**, and environment **npm**.
-   Match spelling/case and the initiating workflow identity. verify.yml is a
-   reusable verifier, not the publishing workflow. Reassess identity if introducing
-   a reusable publisher or changing callers; workflow_call/dispatch identity has
-   documented caller nuances. This setup authorizes a workflow identity, not its
-   test results. The gate supplies the independent verification condition.
-5. npm currently requires npm >=11.5.1 and Node >=22.14.0 for trusted publishing;
-   this workflow uses Node24.12.0 and checks npm's version without upgrading it.
-   GitHub-hosted runners are supported; self-hosted runners are not supported for
-   this npm path. GitHub permissions must permit OIDC. No NODE_AUTH_TOKEN is set.
-   Do not silently fall back to a long-lived publish token when OIDC fails.
-6. Verify provenance requirements, repository visibility and package visibility
-   in the current npm documentation. Trusted publishing generates provenance
-   automatically for supported public packages/public repositories; explicit
-   --provenance must not be treated as proof without checking the registry record.
-   A private-source repository may need an owner-approved alternative or visibility
-   decision; do not claim provenance supported where it is not.
-7. Current npm publisher configurations require first successful use within two
-   days or expire; configure near the authorized release. npm supports up to ten
-   configurations, with separate direct-publish/staging/dist-tag permissions.
-   Grant only this workflow's required direct publication capability, review other
-   publishers/tokens and restrict alternative access according to owner policy.
-   Keep recovery access separate from the normal workflow.
-
-## First publication and bootstrap
-
-A new package may need first publication using authorized npm-owner authentication
-before package settings/trusted publishing are available. npm name availability
-has not been established by creating a GitHub repository. The owner must confirm
-the current bootstrap flow and explicitly authorize it. Do not place bootstrap
-tokens in PR workflows or temporarily make publication unconditional.
-
-Prepare a license/version-ready candidate, run the exact full verification graph,
-retain/download the unchanged manifest/tarball and verify its digest. If the first
-publication must be manual, an authorized owner uses their own current npm login/
-2FA or narrowly scoped supported bootstrap credential to publish those exact bytes,
-then removes temporary credentials and configures the trusted publisher. Record
-the resulting version/integrity/provenance. A dry run is not proof of bootstrap
-permissions or production OIDC authentication. Current 0.1.0 candidates have public-ready metadata, but publication still
-requires all exact-byte checks, owner settings and separate authorization.
-
-## Package order, existing versions and partial recovery
-
-Release by actual production dependencies: client and server are independent;
-either SDK can publish first. Publish the client before a CLI version requiring
-that exact client version. The CLI registry guard requires the published client's
-dist.integrity to match its tested candidate tarball. If it differs, stop and
-reconcile/retest the actual dependency; do not silently replace tested bytes.
-
-Before publishing, npm view must confirm that this package version is absent.
-Only a structured E404 is considered absent; auth/network/registry failures stop.
-An existing version stops publication even after an uncertain earlier response.
-Inspect npm's published version, integrity, provenance and intended dist-tag using
-read-only registry commands. Never overwrite or blindly republish. If the exact
-bytes already published, record that success and resume the remaining package's
-separate verified release. Multi-repository releases are not atomic. Do not unpublish
-a successful dependency as rollback. If correction is required, choose a new
-version, update dependent pins/lockfiles/release notes and verify a new candidate.
-
-This runbook does not authorize publication, tag pushes, package ownership changes,
-external settings, deployment or demo implementation.
-
-Candidate metadata is inspected with the archive basename and its directory as
-`cwd`. This avoids GNU tar interpreting a Windows drive colon as a remote archive;
-stderr is preserved in failure diagnostics. Negative checks exercise GNU tar on
-Windows with space/Unicode candidate paths and retain wrong/missing/changed bytes
-and fail-closed gate cases. Local success does not certify a future hosted run or
-any newly packed bytes.
+# Releasing
+
+Use the tagged GitHub Actions workflow, not a local rebuild. Packages are MIT;
+0.1.0 was manually bootstrapped. Version 0.1.1 refreshes documentation without
+changing runtime APIs. Each new version needs its own source/artifact evidence.
+
+## Before tagging
+
+- Confirm npm ownership, unused versions, supported Node 24.12.0 and npm>=11.5.1.
+  Keep the pinned compiler/dependencies; do not upgrade tooling during a release.
+- Update version, changelog and shipped docs. CLI's client dependency and both
+  candidate JSON files must match exact final SDK versions/full source SHAs.
+- Review the full diff and run typecheck, build, tests and documentation checks.
+  Preserve the existing API/storage/security contracts and historical evidence.
+- Protect source, workflow files, pins and release tags with repository review/rules.
+  All actions are commit-pinned; release verification never restores a PR cache.
+- Verify GitHub environment **npm**: variable **NPM_PUBLISH_ENABLED=true**,
+  intended required reviewer, no admin bypass, and allowed deployment tags **v***.
+  Reviewers approve the real pending deployment; automation must not approve for them.
+- Configure the npm package's GitHub trusted publisher: owner **LMol-4**, this
+  package repository, workflow **release.yml**, environment **npm**. Match case.
+  Enable **direct npm publish** permission; this workflow does not stage a publish.
+  Configure near the release: unused configurations expire after two days. Public
+  source/package visibility and supported GitHub-hosted runners are required for
+  this provenance path. Do not supply NODE_AUTH_TOKEN or fall back to a long-lived
+  token if OIDC fails. Confirm current [npm requirements](https://docs.npmjs.com/trusted-publishers/).
+
+## Publish exact tagged source
+
+Client and server are independent. Publish client before CLI: the CLI registry
+guard requires its tested client tarball integrity to equal the published one.
+
+1. Merge reviewed source to main. Record the full SHA and create/push an approved
+   immutable **vVERSION** tag at that exact commit. Never move or replace a tag.
+
+   ```sh
+   git tag vVERSION FULL_SHA
+   git push origin refs/tags/vVERSION
+   ```
+2. Dispatch **Release** from that tag, with matching version, tag and full commit.
+   Optional `publish=false` rehearses verification only. A later publishing dispatch
+   is a new run with newly identified artifacts; it does not reuse a rehearsal's bytes.
+3. Dispatch with `publish=true` when authorized. Example (replace all placeholders):
+
+   ```sh
+   gh workflow run release.yml --repo LMol-4/PACKAGE --ref vVERSION -f version=VERSION -f tag=vVERSION -f commit=FULL_SHA -f publish=true
+   ```
+
+4. Wait for candidate, fast, contracts, integration, packaged-linux/windows/macos,
+   validation and gate to succeed. Missing, failed, canceled or skipped prerequisites
+   fail closed. Then follow the Actions environment-approval link. Do not bypass it.
+5. The publisher rechecks source/tag/ref/version, trusted manifest digest, unchanged
+   tarball metadata/bytes, owner enablement, registry absence and dependency integrity.
+   It publishes the same-run tested tarball with `--access public --provenance
+   --ignore-scripts`; it never installs, builds or packs again.
+6. Save run URL, full source SHAs, manifest SHA256, filenames, versions, byte counts,
+   tarball SHA256/npm SHA512 and registry integrity/provenance. Download before the
+   14-day candidate retention expires. Verify registry bytes, a clean exact-version
+   registry install, exported modules and the real npm CLI shim.
+
+Ordinary main/tag CI is useful evidence but is not a tagged Release/OIDC publishing
+run. A dry run or green tests alone do not prove npm authentication or provenance.
+The separate checked test-harness artifact is source/output-hash bound, used only
+by unprivileged verification jobs, and never published in an npm package.
+
+## Failure and partial release
+
+Stop on tag/source/version/digest mismatch, unknown registry responses or changed
+client integrity. Do not weaken gates, repack approved bytes, change pins silently,
+force an overwrite or use a token fallback. Inspect the failed job and preserve logs.
+For OIDC/auth failure check publisher spelling/case, workflow/environment identity,
+expiry, reviewer approval, permissions and npm/toolchain support before a new run.
+
+If a version already exists, compare its registry integrity and provenance with the
+saved receipt. Matching successful publication is recorded, never republished.
+For partial publication, finish only absent packages; verify the published client's
+exact bytes before CLI. If bytes differ or a fix is needed, use a reviewed new
+version and complete verification. A source checkout rollback cannot undo an npm
+publication or external side effect. Deprecation, dist-tag changes, unpublish and
+replacement versions need separate owner authorization; never delete evidence.
+
+## Verification limits
+
+Deterministic source suites run once per verification graph on Linux; exhaustive
+file groups reject omissions/duplicates. Packaged jobs test actual installed JS,
+exports/declarations/content/SQLite and representative platform behavior; CLI also
+tests real shims, auth/retry processes and API/browser/feedback wiring. They do not
+certify a production keyring, physical terminal, browser engine, KMS or TLS deployment.
+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).

package/SECURITY.md

@@ -4,10 +4,10 @@ Do not put credentials, tokens, private keys, personal records or exploit detail
 in a public issue. Use this repository's GitHub **Security → Report a vulnerability**
 when private reporting is enabled. If it is unavailable, request a private contact
 from the repository owner without disclosing the vulnerability publicly. The owner
-must enable/confirm that route before public release; no response SLA is promised.
+must enable/confirm that route; no response SLA is promised.
 
 Include affected commit/version, a minimal reproduction using synthetic data,
-impact and the trust boundary involved. These unpublished draft packages have no
-released-version support window yet. Custom vaults, issuers, browser controllers,
+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.

package/STORAGE.md

@@ -1,7 +1,6 @@
 # Company persistence and authorization
 
-J1 replaces whole-state storage on request paths with domain selections. This is a
-breaking adapter change in an unpublished package. Node 24.12.0 or later is required.
+Request paths use targeted domain selections, not whole-state rewrites. Node 24.12.0 or later 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.
@@ -46,10 +45,8 @@ still apply inside the SDK; a namespace name alone is not authentication.
 Conversation selections resolve an ID, message receipt, work ID, or next eligible
 claim. Reads include the related parent/Direct Conversation binding group, not
 unrelated conversations. A worker query selects the oldest eligible message for a
-conversation; publication rechecks lease and fence. Event delivery currently reads
-the selected conversation group's retained events. J3 owns bounded page queries,
-notification-backed waits, streaming and retention; this does not claim those jobs
-are complete. `ConversationNotifications` defines subscribe/unsubscribe/publish:
+conversation; publication rechecks lease and fence. Cursor-relative event selectors bound delivery reads without loading work/history
+aggregates. `ConversationNotifications` defines subscribe/unsubscribe/publish:
 subscribe before reading, treat wakes as hints, and always reconcile durable state
 after a wake or bounded timeout. Publishing after commit is best-effort, not an outbox.
 
@@ -75,8 +72,8 @@ an uncertain result for reconciliation. Never claim universal exactly-once execu
 
 `cleanup(namespace, now, limit)` bounds deletion to at most 1000 expired short-lived
 codes, authorizations, access tokens or replay entries. It does not delete grants,
-work intent, message receipts or conversation events. J3 must preserve receipt
-identity through retention for the conversation lifetime. Finished work pruning is
+work intent, message receipts or conversation events. Receipt identity remains
+through retention for the conversation lifetime. Finished work pruning is
 per selected conversation binding group; unrelated conversation growth cannot
 force another conversation's receipts out of storage.
 
@@ -92,12 +89,8 @@ development reset, stop all processes, resolve uncertain external effects, and
 explicitly move aside the database and WAL/SHM files. Reopen a fresh database to
 obtain new generations. Never reset a live database behind active processes.
 
-`tests/storage.test.mts` exercises real child-process contention and termination
-before commit, after acceptance, and after a synthetic external side effect. It
-also checks publication fencing/deduplication, detached values, rollback, account
-token rotation versus revocation, namespace isolation, and unchanged read counts
-after adding unrelated conversations. These are local Windows/Node results;
-other OS runner evidence belongs to J5/J6.
+Contract tests cover real process contention/death, publication fences, rotation/
+revocation, rollback, isolation and targeted read counts; see [contributing](CONTRIBUTING.md).
 
 ## Bounded conversation delivery and retention
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poppykit/server",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "description": "Personal Agent Protocol company SDK",
   "repository": {