@poppykit/server 0.0.0-stage → 0.1.0

package/RELEASING.md

@@ -0,0 +1,193 @@
+# 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.

package/SECURITY.md

@@ -0,0 +1,13 @@
+# Security reporting
+
+Do not put credentials, tokens, private keys, personal records or exploit details
+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.
+
+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,
+proxy routing and deployment policy remain operator responsibilities. Redaction
+and scoped authority do not isolate an unrestricted same-user program.

package/STORAGE.md

@@ -0,0 +1,119 @@
+# 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.
+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.
+The tested Node 24.12.0 runtime marks `node:sqlite` experimental.
+
+```ts
+import { SqliteCompanyDatabase } from '@poppykit/server/sqlite';
+const database = new SqliteCompanyDatabase('/private/path/company.db');
+const issuer = 'https://company.example/issuer';
+const issuerStore = database.issuer(issuer);
+const conversationStore = database.conversations(issuer);
+// Reference issuer options: store: issuerStore, coordinator: database.
+// Conversation options: store: conversationStore, policy: referenceIssuer.authority.policy.
+// Close database only after all in-flight requests/work have ended.
+```
+
+Use the same database instance for the reference issuer, its coordinator, and its
+conversation storage. A policy check and the protected conversation mutation join
+one SQLite transaction. Revocation/rotation/acceptance cannot interleave between
+authorization and commit. External issuers still supply their own policy and must
+state revocation latency and how their checks are ordered with protected writes.
+Never replace the coordinator with a process-local mutex for a multi-process service.
+
+SQLite uses WAL and FULL synchronous commits. A database serializes writers; this
+reference adapter does not promise parallel SQLite writers. The short per-instance
+queue protects its single connection, and SQLite coordinates separate processes.
+There is no application-wide static lock: separate databases are independent. The
+coordinator is a database transaction boundary, not a lock held during external
+model, vault, or HTTP calls. SQL busy retries are bounded. Use a local filesystem
+with correct SQLite locks; network-mounted multi-host SQLite is unsupported.
+
+## Domain records and guarantees
+
+Every primary key includes a namespace (use the exact full issuer). Sessions,
+grants, current/previous token hashes, authorization requests, codes, access-token
+hashes, replay keys, conversation metadata, shared account bindings, message
+receipts and work intent are separate records. Ordered events are a separate table
+keyed by namespace/conversation/sequence. Indexes cover client, account, grant,
+conversation, binding, phase and expiry. User identity and authorization checks
+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:
+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.
+
+Issuer selections address metadata, token admission, a principal, a token hash, an
+authorization, or a client/account disconnect. Session and authorization limits
+use indexed counts rather than loading other clients' records. Related grant
+sessions are loaded when revocation must sign them out atomically.
+
+All mutations run synchronous callbacks over detached domain records. Async
+callbacks and non-JSON values are rejected. Exceptions roll back; domain savepoints
+also roll back if an enclosing policy caller catches an error. Returned values and
+retained callback objects cannot mutate persisted state after commit. Only changed
+rows and newly appended events are written. Conversation deletion, event rewriting,
+and generation reset are not silently accepted through a targeted transaction.
+
+Acceptance, event append, message deduplication receipt and pending work commit in
+one transaction. There is no second outbox. The same message ID with different
+content/target conflicts. Claim recovery can execute application work again after
+a lease expires: the fence prevents stale SDK publication, but cannot undo or
+deduplicate arbitrary external effects. The application's downstream system needs
+its own idempotency key (such as the stable work ID), or the application must retain
+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 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
+per selected conversation binding group; unrelated conversation growth cannot
+force another conversation's receipts out of storage.
+
+## Non-durable use and resets
+
+`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
+non-durable and is not evidence of database atomicity.
+
+No old whole-state files are migrated or deleted automatically. For a disposable
+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.
+
+## Bounded conversation delivery and retention
+
+`ConversationSelection.events` loads a cursor-relative, count/byte-bounded event
+window without work/history aggregates; it is read-only inside transactions.
+`append` loads operational records without historical event payloads. `cursorCheck`
+checks retained cursor identities for waited POSTs. These selectors preserve the
+shared authority coordinator. Custom adapters must implement equivalent targeted
+reads before claiming the same operation-count guarantees.
+
+SQLite `pruneEvents(conversationId, beforeUnixMilliseconds, limit=100)` deletes at
+most 1000 old payloads per call and refuses active held/pending/claimed work.
+Message receipts, event cursor identities and the latest user message/context stay
+with the conversation for its lifetime. Closure is not deletion. Retention uses
+one database transaction; concurrent writers/readers see a coherent before/after
+state. Default payload retention is indefinite; operators should retain at least
+30 days and explicitly choose any shorter policy. See [DELIVERY.md](DELIVERY.md)
+for distinct lifetimes and client recovery behavior. No automatic destructive
+reset or history deletion was added.

package/dist/adapter-contract.d.ts

@@ -0,0 +1,12 @@
+import type { ConversationOptions } from './conversation/service.js';
+type Store = ConversationOptions['store'] & {
+    inspect(): Promise<import('./conversation/service.js').ConversationStoreState>;
+    adminTransaction<T>(change: (draft: import('./conversation/service.js').ConversationStoreState) => T): Promise<T>;
+};
+export type ConversationAdapterFixture = () => Promise<{
+    store: Store;
+    second: Store;
+    close(): Promise<void>;
+}>;
+export declare function runConversationAdapterContract(fixture: ConversationAdapterFixture): void;
+export {};

package/dist/adapter-contract.js

@@ -0,0 +1,140 @@
+// Contract tests for a host's conversation storage adapter. Call runConversationAdapterContract(fixture) from a
+// node:test file; each case gets a fresh fixture: two handles (e.g. two connections) on one fresh namespace that the
+// host created from initialConversationState. Process kill and engine atomicity stay the host's own tests.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { AuthorityError } from './auth/authority.js';
+import { createConversationService, resetConversationState } from './conversation/service.js';
+const endpoint = 'https://contract.example.test/poppy/conversations';
+const base = { issuer: 'https://auth.contract.test', clientId: 'https://agent.contract.test/client', sessionId: 's1', userId: 'u_1', scopes: [], tokenExpiresAt: 9e12, sessionVersion: 1 };
+const principals = {
+    signedOut: base,
+    account1: { ...base, accountId: 'acct_1', scopes: ['poppy:read'] },
+    account2: { ...base, accountId: 'acct_2', scopes: ['poppy:read'] },
+};
+const message = { id: 'msg_1', sender: 'agent', text: 'Where is order 1042?' };
+const reply = { id: 'msg_r1', sender: 'agent', text: 'Shipped.' };
+function check(held, needed, action) {
+    if (!needed.every(scope => held.includes(scope)))
+        return Promise.reject(new AuthorityError('insufficient_scope'));
+    return action();
+}
+const policy = {
+    withCurrent: (principal, scopes, action) => check(principal.scopes, scopes, action),
+    withAccepted: (authority, scopes, action) => check(authority.principal.scopes, scopes, action),
+};
+function serviceOn(store, clock) {
+    const authenticator = {
+        async authenticate(request) {
+            const principal = principals[request.headers.get('authorization')?.slice('DPoP '.length) ?? ''];
+            if (!principal)
+                throw new AuthorityError('invalid_token');
+            return principal;
+        },
+    };
+    return createConversationService({ endpoint, store, authenticator, policy, clock, leaseMs: 1000 });
+}
+async function call(service, path, as, body, query = '') {
+    const response = await service.handle(new Request(`${endpoint}${path}${query}`, {
+        method: body === undefined ? 'GET' : 'POST', headers: { authorization: `DPoP ${as}` }, body: body === undefined ? undefined : JSON.stringify(body),
+    }));
+    return { status: response.status, body: await response.json() };
+}
+export function runConversationAdapterContract(fixture) {
+    const clock = { t: Date.UTC(2026, 9, 19, 12), now: () => clock.t };
+    async function withFixture(body) {
+        const opened = await fixture();
+        try {
+            await body(opened);
+        }
+        finally {
+            await opened.close();
+        }
+    }
+    test('adapter contract: reads and results are detached; failed, non-JSON and async changes roll back', () => withFixture(async ({ store, second }) => {
+        const snapshot = await store.inspect();
+        snapshot.bindings.leaked = {};
+        assert.deepEqual((await store.inspect()).bindings, {});
+        let draftAfterCommit;
+        const result = await store.adminTransaction(draft => { draft.bindings.kept = {}; draftAfterCommit = draft; return draft.bindings; });
+        result.kept.accountId = 'leaked';
+        draftAfterCommit.bindings.late = {};
+        assert.deepEqual((await second.inspect()).bindings, { kept: {} });
+        await assert.rejects(store.adminTransaction(draft => { draft.bindings.thrown = {}; throw new Error('abort'); }), { message: 'abort' });
+        await assert.rejects(store.adminTransaction(draft => { draft.bindings.undefinedField = { accountId: undefined }; }));
+        await assert.rejects(store.adminTransaction((async (draft) => { draft.bindings.async = {}; })));
+        assert.deepEqual((await second.inspect()).bindings, { kept: {} });
+    }));
+    test('adapter contract: concurrent transactions on both handles lose no update', () => withFixture(async ({ store, second }) => {
+        await Promise.all(Array.from({ length: 20 }, (_, i) => (i % 2 ? store : second).adminTransaction(draft => { draft.bindings[`b${i}`] = {}; })));
+        assert.equal(Object.keys((await store.inspect()).bindings).length, 20);
+    }));
+    test('adapter contract: simultaneous first-message retries on both handles start one conversation and one job', () => withFixture(async ({ store, second }) => {
+        const [a, b] = [serviceOn(store, clock), serviceOn(second, clock)];
+        const results = await Promise.all([a, b, a, b].map(service => call(service, '', 'signedOut', { message })));
+        assert.ok(results.every(result => result.status === 201));
+        assert.equal(new Set(results.map(result => result.body.conversation_id)).size, 1);
+        const state = await second.inspect();
+        assert.equal(Object.keys(state.conversations).length, 1);
+        assert.equal(state.work.length, 1);
+    }));
+    test('adapter contract: racing account use across handles binds parent and Direct Conversation to exactly one account', () => withFixture(async ({ store, second }) => {
+        const [a, b] = [serviceOn(store, clock), serviceOn(second, clock)];
+        const parent = (await call(a, '', 'account1', { message })).body.conversation_id;
+        const parentWork = (await a.claim());
+        const outcome = (promise) => promise.then(value => value.accountId, error => String(error.code));
+        const results = await Promise.all([
+            outcome(a.requireAccount(parentWork, ['poppy:read'])),
+            (async () => {
+                const opened = await call(b, '', 'account2', { parent_conversation_id: parent, message: { id: 'msg_c', sender: 'human', text: 'Hi.' } });
+                if (opened.status !== 201)
+                    return String(opened.body.error);
+                return outcome(b.claim().then(work => b.requireAccount(work, ['poppy:read'])));
+            })(),
+        ]);
+        const winners = results.filter(result => result.startsWith('acct_'));
+        assert.equal(winners.length, 1, String(results));
+        const state = await store.inspect();
+        assert.ok(Object.values(state.conversations).every(conversation => conversation.bindingId === parent));
+        assert.deepEqual(state.bindings[parent], { accountId: winners[0] });
+        const loser = winners[0] === 'acct_1' ? 'account2' : 'account1';
+        for (const id of Object.keys(state.conversations))
+            assert.deepEqual((await call(b, `/${id}/events`, loser)).body, { error: 'sign_in_required' });
+    }));
+    test('adapter contract: lease reclaim on the other handle fences the old worker; output IDs dedupe', () => withFixture(async ({ store, second }) => {
+        const [a, b] = [serviceOn(store, clock), serviceOn(second, clock)];
+        const id = (await call(a, '', 'signedOut', { message })).body.conversation_id;
+        const old = (await a.claim());
+        clock.t += 1000;
+        const fresh = (await b.claim());
+        assert.deepEqual([fresh.workId === old.workId, fresh.fence === old.fence], [true, false]);
+        await assert.rejects(a.reply(old, 'out_1', reply), { code: 'stale_work' });
+        await b.reply(fresh, 'out_1', reply);
+        await a.reply(fresh, 'out_1', reply);
+        await assert.rejects(a.reply(fresh, 'out_1', { ...reply, text: 'changed' }), { code: 'output_conflict' });
+        const events = (await call(b, `/${id}/events`, 'signedOut')).body.events;
+        assert.equal(events.filter(event => event.message?.id === reply.id).length, 1);
+    }));
+    test('adapter contract: a waited POST committed before a crash is recovered unchanged on the other handle', () => withFixture(async ({ store, second }) => {
+        const crashing = serviceOn({ read: () => store.inspect(), transaction: (_selection, change) => store.adminTransaction(change).then(() => { throw new Error('crash after commit'); }) }, clock);
+        await assert.rejects(call(crashing, '', 'signedOut', { message }, '?wait=10'), { message: 'crash after commit' });
+        const b = serviceOn(second, clock);
+        const recovered = await call(b, '', 'signedOut', { message }, '?wait=1');
+        assert.equal(recovered.status, 201);
+        assert.equal(recovered.body.events.length, 2);
+        await b.reply((await b.claim()), 'out_1', reply);
+        assert.deepEqual(await call(b, '', 'signedOut', { message }), recovered);
+        assert.equal((await store.inspect()).work.length, 1);
+    }));
+    test('adapter contract: a reset through one handle invalidates fences and conversations used through the other', () => withFixture(async ({ store, second }) => {
+        const a = serviceOn(store, clock);
+        const id = (await call(a, '', 'signedOut', { message })).body.conversation_id;
+        const work = (await a.claim());
+        const { generation } = await store.inspect();
+        await second.adminTransaction(resetConversationState);
+        assert.notEqual((await store.inspect()).generation, generation);
+        await assert.rejects(a.reply(work, 'out_1', reply), { code: 'stale_work' });
+        assert.equal(await a.claim(), null);
+        assert.equal((await call(a, `/${id}/events`, 'signedOut')).status, 404);
+    }));
+}

package/dist/auth/authenticator.d.ts

@@ -0,0 +1,6 @@
+import type { ExternalAuthorityAdapter, RequestAuthenticator, ResourceEndpoint } from './authority.js';
+export declare function createRequestAuthenticator(options: {
+    authority: Pick<ExternalAuthorityAdapter, 'introspect'>;
+    endpoints: ResourceEndpoint[];
+    now: () => number;
+}): RequestAuthenticator;

package/dist/auth/authenticator.js

@@ -0,0 +1,51 @@
+import { secureUrl } from '../network/transport.js';
+import { AuthorityError } from './authority.js';
+import { verifyDpopProof } from './dpop.js';
+const DPOP_AUTHORIZATION = /^DPoP ([A-Za-z0-9\-._~+/]+=*)$/i;
+// Only introspect is used here; the policy half of the adapter is consumed by the conversation service.
+export function createRequestAuthenticator(options) {
+    for (const endpoint of options.endpoints) {
+        if (secureUrl(endpoint.origin).origin !== endpoint.origin || !endpoint.pathPrefix.startsWith('/'))
+            throw new TypeError('Invalid resource endpoint');
+        if (endpoint.mcp && (endpoint.resource !== `${endpoint.origin}${endpoint.pathPrefix}` || secureUrl(endpoint.mcp.metadataUrl).href !== endpoint.mcp.metadataUrl))
+            throw new TypeError('Invalid MCP resource');
+    }
+    return {
+        async authenticate(request) {
+            // The Request URL must already be the trusted public URL; forwarding headers are never read.
+            const url = new URL(request.url);
+            const endpoint = options.endpoints
+                .filter(item => url.origin === item.origin && (url.pathname === item.pathPrefix || (!item.mcp && url.pathname.startsWith(item.pathPrefix.endsWith('/') ? item.pathPrefix : `${item.pathPrefix}/`))))
+                .sort((a, b) => b.pathPrefix.length - a.pathPrefix.length)[0];
+            if (!endpoint)
+                throw new AuthorityError('invalid_token');
+            if (endpoint.mcp && request.url !== endpoint.resource)
+                throw new AuthorityError('invalid_token');
+            if (endpoint.mcp && /^Bearer /i.test(request.headers.get('authorization') ?? '')) {
+                const bearer = /^Bearer ([A-Za-z0-9\-._~+/]+=*)$/i.exec(request.headers.get('authorization') ?? '')?.[1];
+                if (!bearer || bearer.length > 4096)
+                    throw new AuthorityError('invalid_token');
+                const { principal, dpopJkt } = await options.authority.introspect(bearer, endpoint.resource);
+                // Ordinary MCP issuers return null only for unbound Bearer tokens. A bound token never downgrades.
+                if (dpopJkt !== null || principal.tokenExpiresAt <= options.now())
+                    throw new AuthorityError('invalid_token');
+                if (!principal.userId && !principal.accountId)
+                    throw new AuthorityError('invalid_token');
+                return principal;
+            }
+            if (endpoint.mcp && !endpoint.mcp.dpop)
+                throw new AuthorityError('invalid_token');
+            const token = DPOP_AUTHORIZATION.exec(request.headers.get('authorization') ?? '')?.[1];
+            if (!token || token.length > 4096)
+                throw new AuthorityError('invalid_token');
+            const nowMs = options.now();
+            const proof = await verifyDpopProof(request.headers.get('dpop'), { method: request.method, url: `${url.origin}${url.pathname}`, nowMs, accessToken: token });
+            const { principal, dpopJkt } = await options.authority.introspect(token, endpoint.resource);
+            if (principal.tokenExpiresAt <= nowMs)
+                throw new AuthorityError('invalid_token');
+            if (dpopJkt !== proof.jkt)
+                throw new AuthorityError('invalid_dpop_proof');
+            return principal;
+        }
+    };
+}

package/dist/auth/authority.d.ts

@@ -0,0 +1,55 @@
+export interface Principal {
+    issuer: string;
+    clientId: string;
+    userId: string;
+    sessionId: string;
+    accountId?: string;
+    grantId?: string;
+    scopes: string[];
+    tokenExpiresAt: number;
+    sessionVersion: number;
+    issuerGeneration?: string;
+}
+export type WorkRevocationPolicy = 'stop-account-work' | 'allow-accepted-work-to-finish';
+export interface AcceptedAuthority {
+    principal: Principal;
+    acceptedAt: number;
+    revocationPolicy: WorkRevocationPolicy;
+}
+export interface AuthorityCoordinator {
+    run<T>(action: () => Promise<T>): Promise<T>;
+}
+export interface AuthorityPolicy {
+    withCurrent<T>(principal: Principal, scopes: readonly string[], action: () => Promise<T>): Promise<T>;
+    withAccepted<T>(authority: AcceptedAuthority, scopes: readonly string[], action: () => Promise<T>): Promise<T>;
+}
+export interface RequestAuthenticator {
+    authenticate(request: Request): Promise<Principal>;
+}
+export interface ResourceEndpoint {
+    origin: string;
+    pathPrefix: string;
+    resource?: string;
+    mcp?: {
+        dpop: boolean;
+        metadataUrl: string;
+    };
+}
+export interface ExternalAuthorityAdapter {
+    issuer: string;
+    revocationVisibility: string;
+    introspect(token: string, resource?: string): Promise<{
+        principal: Principal;
+        dpopJkt: string | null;
+    }>;
+    policy: AuthorityPolicy;
+}
+export type AuthorityErrorCode = 'invalid_token' | 'invalid_dpop_proof' | 'use_dpop_nonce' | 'sign_in_required' | 'insufficient_scope';
+export declare class AuthorityError extends Error {
+    readonly code: AuthorityErrorCode;
+    readonly status: 401 | 403;
+    readonly headers: Headers;
+    constructor(code: AuthorityErrorCode, options?: {
+        scope?: string;
+    });
+}

package/dist/auth/authority.js

@@ -0,0 +1,16 @@
+// Resource-side error (spec section 6): carried in WWW-Authenticate, never echoing tokens or peer values.
+export class AuthorityError extends Error {
+    code;
+    status;
+    headers;
+    constructor(code, options = {}) {
+        super(`Authorization failed: ${code}`);
+        this.code = code;
+        this.name = 'AuthorityError';
+        this.status = code === 'sign_in_required' || code === 'insufficient_scope' ? 403 : 401;
+        if (options.scope !== undefined && !/^[\x21\x23-\x5B\x5D-\x7E ]*$/.test(options.scope))
+            throw new TypeError('scope');
+        const scope = options.scope === undefined ? '' : `, scope="${options.scope}"`;
+        this.headers = new Headers({ 'WWW-Authenticate': `DPoP error="${code}"${scope}, algs="ES256"` });
+    }
+}

package/dist/auth/dpop.d.ts

@@ -0,0 +1,15 @@
+import type { DpopClaims } from '../protocol/wire.js';
+export declare const PROOF_WINDOW_SECONDS = 60;
+export declare const CLOCK_SKEW_SECONDS = 30;
+export declare function base64urlSha256(value: string): string;
+export declare function canonicalHtu(url: string): string;
+export declare function assertUniqueJwtMembers(jwt: string): void;
+export declare function verifyDpopProof(proof: string | null, expected: {
+    method: string;
+    url: string;
+    nowMs: number;
+    accessToken?: string;
+}): Promise<{
+    claims: DpopClaims;
+    jkt: string;
+}>;