npm - @poppykit/client - Versions diffs - 0.1.0 → 0.1.1 - Mend

@poppykit/client 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -1,22 +1,18 @@
 # Changelog
-## 0.1.0 — initial development release candidate (unpublished)
+## 0.1.1
-Discovery, safe HTTPS, all three sign-in methods, partial grants/replacement,
-owner-aware recovery, JSON/SSE conversations, API/browser/feedback hooks, targeted
-SQLite adapters and optional constrained hosted-identity provider.
+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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -67,33 +67,14 @@ 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
-The server accepts `supportedScopes`, the union offered by its actual sign-in
-methods. `directScopes` remains a compatibility alias. One coordinator must still
-cover authority checks and durable conversation reads/mutations.
-Default JSON/request/frame budget is 1 MiB; the maximum encoded event is
-1 MiB minus 1025 bytes. Page sizing reserves 1024 bytes for worst-case IDs, cursors
-and envelopes and counts UTF-8 bytes. Company events and client messages that
-cannot fit are rejected before commit; no receipt/work survives a rejected write.
-Do not reduce configured budgets below those used for retained accepted events.
-Notifications are post-commit hints. Subscribe before reading; reconcile durable
-state on wake or every 1000 ms by default. `createConversationNotifications` is
-local acceleration only. Multiple processes work without a broker through targeted
-SQLite reconciliation; deployments can implement the same notification contract
-with their own distributed adapter. Lost/duplicate hints cannot erase a commit.
-SQLite event windows and append operations do not reload complete event histories.
-Server streams default to 30 seconds and apply pull backpressure, rechecking
-current authority before further pages. This bounded-connection policy omits
-periodic idle comments; proxies may close an idle stream sooner, and the client
-reconnects. Longer-lived deployments should supply heartbeat handling at their
-HTTP adapter. Hosts must propagate disconnect/AbortSignal and body cancellation.
+## Peer retention
+The [server delivery guide](https://github.com/LMol-4/poppykit-server/blob/main/DELIVERY.md)
+describes service configuration, byte budgets, notifications and bounded streams.
+Keep the following distinct lifetimes when choosing an operator retention policy:
 | Record | Lifetime / deletion rule |
 | --- | --- |

package/README.md CHANGED Viewed

@@ -1,30 +1,22 @@
 # PoppyKit client
-TypeScript SDK for personal-agent providers integrating [Personal Agent Protocol
-draft 0.2](https://personalagentprotocol.org/docs/0.2/spec). Discover companies,
-start sessions, use Direct/Device/Mediated sign-in, exchange JSON/SSE conversations,
-authorize API requests, join an agent browser and send feedback. Your application
-supplies the agent and trusted infrastructure.
+TypeScript SDK for [Personal Agent Protocol draft 0.2](https://personalagentprotocol.org/docs/0.2/spec):
+discovery, authentication, conversations and API/browser/feedback hooks. Your
+application supplies the agent and trusted infrastructure. [MIT](LICENSE).
-## Installation
+## Install
-Requires Node **24.12.0 or later**, ESM and HTTPS. CI certifies Node 24.12.0;
-later majors are not separately certified. Optional SQLite uses experimental
-`node:sqlite` and 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+**, ESM and HTTPS. CI tests Node 24.12.0 on Linux, macOS and
+Windows; later majors are not separately certified.
 ```sh
-npm install ./poppykit-client-0.1.0.tgz
+npm install @poppykit/client@0.1.1
 ```
-The only production dependency is `jose@6.2.12`. No server SDK or CLI is required.
-Registry installation instructions will accompany the first public release.
-## Quickstart
+## Discover a company
-Discovery needs no signing key, account token or database:
+No credentials or database are needed. Replace `company.example` with a company
+publishing draft 0.2 discovery:
 ```js
 import { createMetadataResolver, createNodeTransport } from '@poppykit/client';
@@ -38,87 +30,21 @@ try {
 }
 ```
-Replace `company.example` with a company publishing draft 0.2 discovery.
-Run the complete [quickstart](examples/quickstart.mjs) with a real domain, or
-`node examples/quickstart.mjs --self-check` for a deterministic offline example.
-## Configuration and authentication
-`createClientAuth(options)` owns sessions, all three sign-in methods, renewal,
-scope replacement, sign-out and recovery. Supply `namespace`, `localUserId`,
-`clientId`, registered `redirectUris`, an `AuthStore`, `SecretStore`, safe transport
-and metadata resolver. Run `recover()` at startup. Publish HTTPS client metadata
-and public JWKS; private signing keys stay in your signer or provider.
-Choose an `IdentitySigner`, or authenticated `AssertionProvider` and
-`ProviderIdentity` adapters. The optional `/provider` reference is documented in
-[PROVIDER.md](PROVIDER.md). Operators supply HTTPS hosting, enrollment authentication,
-company policy and signing/KMS. Anonymous sessions require a separate local signer
-with a published key; provider-only custody reports `anonymous_unavailable`.
-Call `start(domain)`, then `authorization(connectionId, scopes)` to inspect grants,
-missing scopes and advertised methods. `beginSignIn(connectionId, { method, scopes })`
-selects `direct`, `device` or `mediated`. Direct requires an authenticated browser
-binding and HTTPS callback. Device displays a verified human link/code and resumes
-with `continueSignIn`. Mediated invokes your `TrustedInput.collect` UI. Keep that UI,
-passwords, codes and credential adapters outside model tools. See [AUTH.md](AUTH.md)
-for partial consent, scope upgrades, cancellation and revocation.
-## Examples and common operations
-Configure conversations using the verified target and the same auth lifecycle:
-```js
-import { createConversationClient } from '@poppykit/client';
-const target = await auth.target(connectionId);
-const conversations = createConversationClient({
-  ...target, connectionId, store: conversationStore, clock: { now: Date.now },
-  authorizedRequest: request => auth.authorizedFetch(connectionId, request, target),
-  authorization: (id, scopes) => auth.authorization(id, scopes),
-});
-```
-`auth`, `connectionId` and `conversationStore` are your configured instances.
-`start`, `send`, `read`, `watch`, `ack`, `handoff` and `close` manage the lifecycle.
-Retain message IDs for retries; acknowledge durable deliveries after processing.
-[DELIVERY.md](DELIVERY.md) explains cursors, streaming, pagination and retention.
-Use `apiTarget`/`apiFetch` with an existing OpenAPI or MCP client. The final URL
-must be independently authorized; an OpenAPI `servers` entry grants no authority.
-`joinBrowser` accepts a trusted agent-controlled controller separate from human
-consent. `feedback` sends a single `missing` report expecting empty HTTP 202.
-[INTEGRATIONS.md](INTEGRATIONS.md) documents the adapter contracts and examples.
-## Errors, cancellation, retries and limits
-Handle `AuthFailure.code` and `ConversationError.code`; do not parse messages or
-log credential headers/private adapter errors. Pending operations are resumable;
-an uncertain remote exchange requires reconciliation and is never silently replayed.
-Declined upgrades preserve old access; sign-out never automatically reconnects.
-Conversation operations accept `AbortSignal`. Cancellation cannot undo bytes sent.
-Conversation retries retain message IDs/payloads with bounded backoff and Retry-After.
-Auth deadlines persist across restarts. Feedback has no automatic POST retry or
-deduplication promise. Pools, bodies, event/page sizes and reconnects are bounded;
-see [DELIVERY.md](DELIVERY.md). External effects need application idempotency.
-## Storage and production responsibilities
+The packaged [quickstart](examples/quickstart.mjs) also supports `--self-check`
+without a network service.
-Optional `/sqlite` exports `SqliteAuthStore` and `SqliteConversationStore`;
-`/memory` exports non-durable `MemoryConversationStore`. Consumers can implement
-the targeted contracts using their own databases. Store Account Tokens, DPoP keys
-and PKCE in a secure `SecretStore`; Session Tokens stay in memory. SQLite stores
-secret references and private message data, not vault encryption. Database, vault
-and remote exchange are separate boundaries; implement orphan-secret reconciliation
-and deployment ownership checks. [STORAGE.md](STORAGE.md) defines atomicity,
-recovery and explicit development reset.
+## Guides
-## Reference and support
+- [Authentication](AUTH.md): sessions, Direct/Device/Mediated, consent, renewal and revocation.
+- [Storage](STORAGE.md): targeted adapters, secret references, recovery and explicit resets.
+- [Delivery](DELIVERY.md): messages, streaming, cancellation, retries and retention.
+- [Integrations](INTEGRATIONS.md): verified API targets, agent browser and feedback.
+- [Optional provider](PROVIDER.md): operator-hosted signing and callback custody.
+- [API exports](API.md), [contributing](CONTRIBUTING.md), [security](SECURITY.md),
+  [changelog](CHANGELOG.md) and [releasing](RELEASING.md).
-[API.md](API.md) maps public exports and TypeScript declarations to deeper guides.
-This independent draft implementation has deterministic and packaged tests;
-production vaults, browsers, external issuers and hosting need operator validation.
-Individual protocol extensions and application business logic are outside the SDK.
-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; publication remains blocked pending the owner's license decision.
+Keep Account Tokens, DPoP keys and PKCE in a secure SecretStore; never expose them
+to model tools. An uncertain remote result must not be silently replayed. SQLite
+is optional/experimental and is not vault encryption. Production issuers, vaults,
+browsers and hosting require operator validation; individual extensions and
+application business workflows are outside this SDK.

package/RELEASING.md CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,6 +1,6 @@
 # Persistence and recovery
-This unpublished package uses targeted storage contracts. Node 24.12.0
+Use targeted storage contracts. Node 24.12.0
 or later is required. The optional `@poppykit/client/sqlite` entry point exports
 `SqliteAuthStore` and `SqliteConversationStore`; importing the client core does not
 load SQLite. `node:sqlite` is experimental in the tested Node 24.12.0 runtime.
@@ -44,8 +44,8 @@ records its endpoint. Retry rejects an endpoint change before sending. Preparati
 returns the existing record instead of replacing content; terminal outcomes cannot
 be overwritten by a late sender. Checkpoints include endpoint, conversation and
 consumer. Receipts remain available for retries: the old `keepCompleted` deletion
-behavior is removed. J3 owns retention with preserved message identity and bounded
-payload cleanup; no automatic age-based deletion is currently performed.
+behavior is removed. Retention preserves message identity and bounds payload cleanup; no automatic
+age-based deletion is performed.
 `MemoryConversationStore` from `@poppykit/client/memory` is non-durable and confined
 to one process. The SQLite adapters also accept `:memory:` for non-durable tests;
@@ -84,11 +84,8 @@ aside its database and WAL/SHM files and the matching host-managed secret namesp
 before creating a fresh store. Never reset live credentials by deleting a database
 behind a running process. Old stores are not silently deleted or reinterpreted.
-`tests/storage.test.mts` uses actual child processes, SQLite contention and forced
-termination. It covers rollback, durable prepare, live-owner recovery and an external
-synthetic effect followed by owner death. The latter becomes uncertain, not an
-exactly-once execution claim. Auth unit tests also retain staged-secret, generation,
-revocation-race and vault-failure coverage.
+Contract tests cover real child-process contention, crash recovery, uncertain
+external effects, staged secrets and revocation races; see [contributing](CONTRIBUTING.md).
 ## Conversation delivery lifetime

package/package.json CHANGED Viewed

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