@arnilo/prism 0.2.0 → 0.2.2

package/dist/testing/state-concurrency-conformance.js

@@ -0,0 +1,348 @@
+// ponytail: runner-free multi-process state-concurrency probe for memory and
+// durable stores (plan 022 Task 4). Deterministic barriers only: every probe
+// awaits the conflicting op and then asserts state — never setTimeout/sleeps.
+import assert from "node:assert/strict";
+import { isSessionMetadataConflict } from "../contracts-core.js";
+/**
+ * Run the state-concurrency probes for every provided store family. Returns
+ * the executed probe names so gates can assert coverage. Deterministic:
+ * concurrent ops are awaited through `Promise.allSettled` and state is
+ * asserted afterward; no timing-only sleeps anywhere in this file.
+ */
+export async function assertStateConcurrencyConforms(factories) {
+    const executed = [];
+    if (factories.checkpoints) {
+        const checkpoints = await factories.checkpoints();
+        await checkpointCasProbe(checkpoints);
+        executed.push("checkpoint-cas");
+        await approvalDeterminismProbe(checkpoints);
+        executed.push("approval-determinism");
+    }
+    if (factories.events) {
+        await cursorResumeProbe(factories.events);
+        executed.push("cursor-resume");
+    }
+    if (factories.sessions) {
+        await conversationMetadataCasProbe(await factories.sessions());
+        executed.push("conversation-metadata-cas");
+    }
+    if (factories.idempotency) {
+        await idempotencyRetryProbe(await factories.idempotency());
+        executed.push("idempotency-retry");
+    }
+    if (factories.routerState) {
+        await reservationOversubscriptionProbe(await factories.routerState.create());
+        executed.push("router-reservation");
+        if (factories.routerState.nowInjected) {
+            await unknownOutcomeProbe(await factories.routerState.create());
+            executed.push("unknown-outcome");
+        }
+    }
+    return executed;
+}
+const ownership = { tenantId: "tenant-a", accountId: "account-a", userId: "user-a" };
+function identity(tenantId) {
+    return {
+        tenantId,
+        userId: "user-a",
+        principal: { kind: "agent", id: "agent-a" },
+        scopes: ["work:mutate"],
+        issuedAt: "2026-08-03T00:00:00.000Z",
+        verified: true,
+    };
+}
+/**
+ * Checkpoint CAS: exact-version and fencing-token guards. A stale
+ * `expectedVersion` is rejected; a lower `fencingToken` cannot replace a
+ * fenced record; a higher fence wins.
+ */
+async function checkpointCasProbe(checkpoints) {
+    const key = { namespace: "state-concurrency", key: "checkpoint-cas", ...ownership };
+    await checkpoints.saveCheckpoint({ ...key, version: 1, value: { step: 1 } });
+    await checkpoints.saveCheckpoint({ ...key, version: 2, expectedVersion: 1, value: { step: 2 } });
+    await assertRejectsCode(() => checkpoints.saveCheckpoint({ ...key, version: 3, expectedVersion: 1, value: { step: 3 } }), "ERR_PRISM_CHECKPOINT_CONFLICT", "stale expectedVersion must be rejected");
+    await checkpoints.saveCheckpoint({ ...key, version: 3, expectedVersion: 2, fencingToken: 5, value: { step: 3 } });
+    await assertRejectsCode(() => checkpoints.saveCheckpoint({ ...key, version: 4, expectedVersion: 3, fencingToken: 4, value: { step: 4 } }), "ERR_PRISM_CHECKPOINT_CONFLICT", "lower fence must be rejected");
+    const fenced = await checkpoints.saveCheckpoint({ ...key, version: 4, expectedVersion: 3, fencingToken: 6, value: { step: 4 } });
+    assert.equal(fenced.fencingToken, 6, "higher fence must win");
+    const loaded = await checkpoints.loadCheckpoint(key);
+    assert.equal(loaded?.version, 4, "winning version must persist");
+    assert.equal(loaded?.fencingToken, 6, "winning fence must persist");
+    await assertRejects(() => checkpoints.loadCheckpoint({ ...key, tenantId: "tenant-b" }), /ownership|tenant/i, "foreign checkpoint access must fail closed");
+}
+/**
+ * Approval determinism: concurrent approve/deny of the same pending decision
+ * resolves to exactly one terminal state; a stale decision discriminant
+ * (the `expectedVersion` a resumer read) is rejected — the 0.2.0 resume fix
+ * contract: resume requires `record.version === expectedVersion`.
+ */
+async function approvalDeterminismProbe(checkpoints) {
+    const key = { namespace: "state-concurrency", key: "approval", ...ownership };
+    const suspended = {
+        status: "suspended",
+        interruption: {
+            kind: "tool_approval",
+            reason: "review",
+            pendingDecisions: [{ approvalId: "a1", kind: "tool_approval", scope: { toolName: "fs.write", argumentsHash: "h1" } }],
+        },
+    };
+    await checkpoints.saveCheckpoint({ ...key, version: 1, value: suspended });
+    const approve = { status: "running", decision: { approvalId: "a1", outcome: "allow_once" } };
+    const deny = { status: "denied", decision: { approvalId: "a1", outcome: "reject_once" } };
+    const results = await Promise.allSettled([
+        checkpoints.saveCheckpoint({ ...key, version: 2, expectedVersion: 1, fencingToken: 1, value: approve }),
+        checkpoints.saveCheckpoint({ ...key, version: 2, expectedVersion: 1, fencingToken: 1, value: deny }),
+    ]);
+    const fulfilled = results.filter((result) => result.status === "fulfilled");
+    const rejected = results.filter((result) => result.status === "rejected");
+    assert.equal(fulfilled.length, 1, "concurrent approve/deny must admit exactly one terminal write");
+    assert.equal(rejected.length, 1, "concurrent approve/deny must reject exactly one writer");
+    assert.equal(rejected[0].reason?.code, "ERR_PRISM_CHECKPOINT_CONFLICT", "loser must fail with checkpoint conflict");
+    const final = await checkpoints.loadCheckpoint(key);
+    assert.equal(final?.version, 2, "terminal state must be written exactly once");
+    assert.ok(deepEqual(final?.value, approve) || deepEqual(final?.value, deny), "final state must be exactly one winner's payload, never a mix");
+    await assertRejectsCode(() => checkpoints.saveCheckpoint({ ...key, version: 3, expectedVersion: 1, value: { status: "running" } }), "ERR_PRISM_CHECKPOINT_CONFLICT", "a stale decision discriminant (version read before the race) must be rejected");
+}
+/**
+ * Replay-cursor resume: a cursor taken from the last consumed position resumes
+ * at the next event, never the stream head. Durable factories additionally
+ * close and re-open the store (restart) and resume from the same cursor.
+ */
+async function cursorResumeProbe(factory) {
+    const input = { ownership, sessionId: "concurrency-session", runId: "concurrency-run" };
+    const source = await factory.create();
+    await source.append(event("event-1", "agent_started", input));
+    await source.append(event("event-2", "turn_started", input, "2026-01-01T00:00:01.000Z"));
+    await source.append(event("event-3", "agent_finished", input, "2026-01-01T00:00:02.000Z"));
+    const first = await source.page({ ...input, limit: 1 });
+    assert.equal(first.items[0]?.record.id, "event-1", "first page must start at the head");
+    const second = await source.page({ ...input, after: first.items[0].cursor, limit: 1 });
+    assert.equal(second.items[0]?.record.id, "event-2", "second page must continue after the first cursor");
+    const resumed = await source.page({ ...input, after: second.items[0].cursor, limit: 10 });
+    assert.deepEqual(resumed.items.map((envelope) => envelope.record.id), ["event-3"], "resume from the last-acked cursor must not replay the head");
+    assert.equal(resumed.terminal, true, "resumed page must reach the terminal event");
+    const foreign = await source.page({ ...input, ownership: { ...ownership, tenantId: "tenant-b" }, limit: 10 });
+    assert.equal(foreign.items.length, 0, "ownership must never cross tenants");
+    if (factory.reopenable) {
+        await source.close?.();
+        const restarted = await factory.create();
+        const afterRestart = await restarted.page({ ...input, after: second.items[0].cursor, limit: 10 });
+        assert.deepEqual(afterRestart.items.map((envelope) => envelope.record.id), ["event-3"], "reopened store must resume from the last-acked cursor, not the head");
+        assert.equal(afterRestart.terminal, true, "reopened page must reach the terminal event");
+        await restarted.close?.();
+    }
+}
+/** Idempotency: a retry with the same key returns the recorded outcome, never a duplicate effect. */
+async function idempotencyRetryProbe(idempotency) {
+    const mutation = { identity: identity("tenant-a"), key: "idem-1", op: "example.mutate" };
+    const parallel = await Promise.all(Array.from({ length: 8 }, () => idempotency.begin(mutation)));
+    const acquired = parallel.filter((result) => result.outcome === "acquired");
+    const existing = parallel.filter((result) => result.outcome === "existing");
+    assert.equal(acquired.length, 1, "parallel begins must admit exactly one claim");
+    assert.equal(existing.length, 7, "parallel begins must report the rest as existing");
+    const claim = acquired[0].record;
+    assert.ok(claim.claimToken, "acquired claim must carry a token");
+    const completed = await idempotency.complete({
+        ...mutation,
+        claimToken: claim.claimToken,
+        expectedVersion: claim.version,
+        result: { draftId: "draft-1" },
+    });
+    assert.equal(completed.status, "completed", "completed mutation must be terminal");
+    const retry = await idempotency.begin(mutation);
+    assert.equal(retry.outcome, "existing", "retry must never re-acquire");
+    assert.equal(retry.record.result?.draftId, "draft-1", "retry must return the recorded outcome, not a duplicate effect");
+    assert.equal(await idempotency.get({ ...mutation, identity: identity("tenant-b") }), undefined, "ownership must never cross tenants");
+    await assertRejectsCode(() => idempotency.complete({
+        ...mutation,
+        claimToken: claim.claimToken,
+        expectedVersion: claim.version,
+        result: { draftId: "draft-2" },
+    }), "ERR_PRISM_WORK_IDEMPOTENCY_CONFLICT", "a stale-version second complete must be rejected");
+}
+/** Router reservation: parallel admissions cannot oversubscribe; commit/release reconcile actuals. */
+async function reservationOversubscriptionProbe(router) {
+    const key = {
+        tenantId: "tenant-a",
+        accountId: "account-a",
+        userId: "user-a",
+        principalId: "principal-a",
+        provider: "benchmark",
+        model: "reserved",
+    };
+    const parallel = await Promise.all(Array.from({ length: 4 }, () => router.reserveBudget({ key, tokens: 26, maxTokens: 100, windowMs: 60_000, reservationTtlMs: 60_000, now: 0 })));
+    const admitted = parallel.filter((result) => result.admitted);
+    const denied = parallel.filter((result) => !result.admitted);
+    assert.equal(admitted.length, 3, "parallel reservations must admit exactly N-1");
+    assert.equal(denied.length, 1, "parallel reservations must deny exactly one");
+    assert.ok(denied[0].retryAfterMs !== undefined, "denial must carry a retry-after hint");
+    await assertRejectsCode(() => router.commitBudget({
+        key,
+        reservationId: admitted[2].reservationId,
+        fencingToken: "stale",
+        tokens: 1,
+        windowMs: 60_000,
+        now: 1_000,
+    }), "ERR_PRISM_MODEL_ROUTER_STATE", "a stale/foreign fencing token must be rejected");
+    const committed = await router.commitBudget({
+        key,
+        reservationId: admitted[0].reservationId,
+        fencingToken: admitted[0].fencingToken,
+        tokens: 10,
+        windowMs: 60_000,
+        now: 1_000,
+    });
+    assert.equal(committed.unknownUsage, false, "live commit must not report unknown usage");
+    await router.releaseBudget({
+        key,
+        reservationId: admitted[1].reservationId,
+        fencingToken: admitted[1].fencingToken,
+        windowMs: 60_000,
+        now: 1_000,
+    });
+    assert.deepEqual(await router.readBudget({ key, windowMs: 60_000, now: 1_000 }), {
+        tokens: 10,
+        costUsd: 0,
+    });
+}
+/**
+ * Unknown-outcome recovery: an abandoned reservation (crash before commit)
+ * reconciles to the reserved amount with `unknownUsage: true` — never a
+ * silent drop. Deterministic: expiry is driven through the injected `now`
+ * (memory stores); the durable leg runs in the Task 1 enterprise-conformance
+ * integration probe because durable expiry uses the database clock. The
+ * redacted `unknown_usage` diagnostic emission is asserted at router level in
+ * the model-router suite (Task 1) — the store seam reports the flag only.
+ */
+async function unknownOutcomeProbe(router) {
+    const key = {
+        tenantId: "tenant-a",
+        accountId: "account-a",
+        userId: "user-a",
+        principalId: "principal-a",
+        provider: "benchmark",
+        model: "ttl",
+    };
+    const reserved = await router.reserveBudget({ key, tokens: 7, maxTokens: 100, windowMs: 60_000, reservationTtlMs: 60_000, now: 0 });
+    assert.ok(reserved.admitted, "reservation must admit within capacity");
+    const late = await router.commitBudget({
+        key,
+        reservationId: reserved.reservationId,
+        fencingToken: reserved.fencingToken,
+        tokens: 1,
+        windowMs: 60_000,
+        now: 61_001,
+    });
+    assert.equal(late.unknownUsage, true, "a late commit after expiry must reconcile as unknown usage");
+    assert.deepEqual(await router.readBudget({ key, windowMs: 60_000, now: 61_001 }), {
+        tokens: 7,
+        costUsd: 0,
+    });
+}
+/**
+ * Conversation metadata CAS: concurrent create/branch/archive-style writes
+ * admit exactly one winner per version and reject the rest with
+ * `metadata_conflict`; a deleted row is never resurrected; ownership guards
+ * hold inside the same guarded write.
+ */
+async function conversationMetadataCasProbe(sessions) {
+    if (!sessions.appendSession)
+        throw new Error("state-concurrency sessions probe requires appendSession");
+    const base = {
+        id: "conversation-1",
+        tenantId: "tenant-a",
+        accountId: "account-a",
+        userId: "user-a",
+        createdAt: "2026-08-03T00:00:00.000Z",
+        updatedAt: "2026-08-03T00:00:00.000Z",
+        metadata: { prismConversation: { state: "active", title: "root" } },
+    };
+    const created = await sessions.appendSession({ ...base, expectedVersion: 0 });
+    assert.equal(created?.version, 1, "create-only write must land at version 1");
+    const creates = await Promise.allSettled(Array.from({ length: 8 }, (_, index) => sessions.appendSession({
+        ...base,
+        expectedVersion: 0,
+        metadata: { prismConversation: { state: "active", title: `racer-${index}` } },
+    })));
+    const createWinners = creates.filter((result) => result.status === "fulfilled");
+    const createLosers = creates.filter((result) => result.status === "rejected");
+    assert.equal(createWinners.length, 0, "duplicate create-only writes must never overwrite the winner");
+    assert.equal(createLosers.length, 8, "every duplicate create must conflict");
+    for (const result of createLosers) {
+        assert.ok(isSessionMetadataConflict(result.reason), "duplicate create must be metadata_conflict");
+    }
+    const racerMetadata = (index) => ({
+        prismConversation: {
+            state: "active",
+            title: `branch-${index}`,
+            refs: [{ leafId: `leaf-${index}`, createdAt: "2026-08-03T00:00:01.000Z" }],
+        },
+    });
+    const updates = await Promise.allSettled(Array.from({ length: 8 }, (_, index) => sessions.appendSession({ ...base, expectedVersion: 1, metadata: racerMetadata(index) })));
+    const updateWinners = updates.filter((result) => result.status === "fulfilled");
+    const updateLosers = updates.filter((result) => result.status === "rejected");
+    assert.equal(updateWinners.length, 1, "concurrent CAS updates must admit exactly one winner");
+    assert.equal(updateLosers.length, 7, "concurrent CAS updates must reject the rest");
+    const winnerVersion = updateWinners[0].value?.version;
+    assert.equal(winnerVersion, 2, "winner must land at version 2");
+    for (const result of updateLosers) {
+        const reason = result.reason;
+        assert.ok(isSessionMetadataConflict(reason), "CAS loser must be metadata_conflict");
+        assert.equal(reason.conflict?.currentVersion, 2, "conflict must report the current version");
+    }
+    const winnerIndex = updates.findIndex((result) => result.status === "fulfilled");
+    const page = await sessions.querySessions({ id: base.id, tenantId: "tenant-a", accountId: "account-a", userId: "user-a" });
+    assert.equal(page.items.length, 1, "session must resolve to a single record");
+    assert.equal(page.items[0]?.version, 2, "stored version must reflect the winner's write");
+    assert.deepEqual(page.items[0]?.metadata, racerMetadata(winnerIndex), "stored metadata must be exactly the winner's marker");
+    await assertRejectsCode(() => sessions.appendSession({
+        ...base,
+        tenantId: "tenant-b",
+        expectedVersion: 1,
+        metadata: { prismConversation: { state: "archived" } },
+    }), "metadata_conflict", "cross-ownership CAS write must be rejected in the same guarded statement");
+}
+function event(id, type, input, timestamp = "2026-01-01T00:00:00.000Z") {
+    const payload = type === "turn_started"
+        ? { type, sessionId: input.sessionId, runId: input.runId, turn: 1 }
+        : { type, sessionId: input.sessionId, runId: input.runId };
+    return { id, ...input.ownership, sessionId: input.sessionId, runId: input.runId, type, timestamp, event: payload, redacted: true };
+}
+function deepEqual(actual, expected) {
+    if (Object.is(actual, expected))
+        return true;
+    if (typeof actual !== "object" || typeof expected !== "object" || actual === null || expected === null)
+        return false;
+    const actualEntries = Object.entries(actual);
+    const expectedEntries = Object.entries(expected);
+    if (actualEntries.length !== expectedEntries.length)
+        return false;
+    for (const [key, value] of expectedEntries) {
+        if (!deepEqual(actual[key], value))
+            return false;
+    }
+    return true;
+}
+async function assertRejectsCode(action, code, message) {
+    try {
+        await action();
+    }
+    catch (error) {
+        if (error?.code === code)
+            return;
+        throw new Error(`${message}; expected code ${code}, received ${String(error?.code)}: ${String(error)}`);
+    }
+    throw new Error(`${message}; expected a rejection with code ${code}`);
+}
+async function assertRejects(action, pattern, message) {
+    try {
+        await action();
+    }
+    catch (error) {
+        if (pattern.test(String(error)))
+            return;
+        throw new Error(`${message}; rejection did not match ${pattern}: ${String(error)}`);
+    }
+    throw new Error(`${message}; expected a rejection matching ${pattern}`);
+}
+//# sourceMappingURL=state-concurrency-conformance.js.map

package/docs/agent-events.md

@@ -45,7 +45,7 @@ const nc = await connect({ servers: process.env.NATS_URL });
 const source = createNatsAgentEventSource({ connection: await createNatsJetStream(nc), stream: "prism_agent_events" });
 ```
 
-One subject per run (`prism.agent-events.<tenant>.<session>.<run>`); the JetStream per-subject sequence is the per-run event sequence. `append` is idempotent by `record.id` within the stream's dedupe window; `page`/`subscribe` replay per subject from HMAC-signed cursors; `subscribe` uses a durable pull consumer with explicit acks (at-least-once, 30s redelivery, dedupe by `record.id`); `cleanup` deletes ownership-scoped messages older than `before`. The host provisions the stream (subjects `prism.agent-events.>`, retention limits, dedupe window). Inert on import; network-free tests use an in-memory fake of the narrow `NatsJetStream` seam.
+One subject per run (`prism.agent-events.<tenant>.<session>.<run>`); the JetStream per-subject sequence is the per-run event sequence. `append` is idempotent by `record.id` within the stream's dedupe window; `page`/`subscribe` replay per subject from HMAC-signed cursors; `subscribe` uses a durable pull consumer with explicit acks (at-least-once, 30s redelivery, dedupe by `record.id`) and a **restart-stable durable identity** — the consumer name is `prism_<hmac16>` of `tenantId|sessionId|runId` (no random suffix), so a crashed subscribe leaves a consumer that a restarting subscribe reuses at its last-acked position instead of replaying from the stream head. Clean stops still delete the consumer; pre-0.2.2 orphaned random-suffixed consumers are reclaimed by hosts via `deleteConsumer`/consumer enumeration. `cleanup` deletes ownership-scoped messages older than `before`. The host provisions the stream (subjects `prism.agent-events.>`, retention limits, dedupe window). Inert on import; network-free tests use an in-memory fake of the narrow `NatsJetStream` seam.
 
 ## Inputs / request
 

package/docs/conversations.md

@@ -113,13 +113,16 @@ Behavior notes:
 - Replay cursors are thread-bound: a cursor minted for one thread is rejected on another (`cursor_thread_mismatch`).
 - Ledger rows from runs that had no redactor are never served by replay/export (fail-closed skip).
 - Export truncates at page granularity when the next page would exceed `exportBytes`; a single page larger than `exportBytes` cannot be exported (raise the cap or page via `replay`).
-- Branch refs live in thread metadata (read-modify-write); concurrent `branch()` calls can lose a ref, so the cap is approximate and the entry tree remains the content source of truth.
+- Branch refs live in thread metadata; every `branch()`/`archive()` write is an optimistic compare-and-swap against the stored session `version`, so concurrent callers cannot lose a ref or resurrect stale state: the loser of a `branch`+`branch`, `branch`+`archive`, or `create`+`create` race gets `metadata_conflict` (HTTP 409) and re-reads/retries if it chooses.
+- `create` with an explicit `id` writes with `expectedVersion: 0` (create-only): a duplicate create never overwrites the winner's metadata and returns the existing thread.
+- `branch()` enforces `maxActiveBranches` on its read snapshot; the version guard inside the same write makes the cap exact even under concurrency (a concurrent branch cannot slip past the cap), and the marker keeps branch refs append-only.
+- `archive()` on an already-archived thread is a no-op; a stale `branch`/`archive` racing a delete fails `not_found` (the row is gone) and the write path never re-creates a deleted thread — delete wins.
 - Deletion purges the whole session ledger (entries, runs, events, tool calls, usage, branches, search rows) through `lifecycle.applyRetention`; legal holds block deletion and report `held: true`.
 
 ## Security and performance notes
 
 - Every operation starts from host-verified ownership (and optional `AgentIdentity`, which must project onto ownership without widening); wrong-user access returns not-found, never leaked existence.
-- `appendSession` upserts set ownership columns only on create; metadata/`updatedAt` on update — ownership is immutable after create.
+- `appendSession` upserts set ownership columns only on create; metadata/`updatedAt` on update — ownership is immutable after create, and the CAS write additionally rejects a mismatched ownership in the same guarded statement.
 - Replay/export serve `redacted: true` ledger rows only and pass through the service redactor; no local paths, raw tool payloads, or secrets are emitted.
 - All loops are bounded by the frozen caps above; review/agent turns consume shared `RunLimits` via the host's `runOptions`.
 - No new permission surface: conversations reuse session/event/identity/redaction/lifecycle seams (roadmap gate 8).

package/docs/credential-storage.md

@@ -248,6 +248,7 @@ const providers = createOpenAIProviderPackage({ apiKey });
 - Never log passphrases, derived keys, or decrypted credential payloads.
 - Optional host KMS: `encryptWithHostKms` / `decryptWithHostKms` wrap a random AES-256-GCM DEK via host `HostKms.wrapKey`/`unwrapKey` (timeout ≤ 60 s). Envelope sizes reuse vault/file caps. Keys are never logged. `createMemoryHostKms` is for tests only.
 - Storage is not OAuth eligibility. A durable store may persist credentials for a provider only after the host selects a provider-authorized flow; it must not be used to piggyback on a vendor CLI or consumer subscription.
+- OIDC JWKS fetches (0.2.1) are DNS-pinned through the core `pinnedFetch` primitive: one resolve per request, every resolved address SSRF-checked before the connect (rebinding defense), redirects rejected outright, and the JWKS body read under a hard byte ceiling; oversized documents fail closed as a parse error, never as a rotatable transport failure.
 - Live keychain tests are opt-in (`PRISM_TEST_KEYCHAIN=1`); default `npm test` stays offline.
 
 ## MCP authentication boundary

package/docs/credentials-and-redaction.md

@@ -124,6 +124,7 @@ A future provider-local OAuth adapter needs published permission for third-party
 - `resolveCredentialValue()` and `createExplicitCredentialResolver()` do not cache values. Add host-side caching only if a real credential source needs it.
 - `refreshOAuthCredential()` only calls the supplied OAuth provider and optional store; it has no built-in persistence or retry loop.
 - OpenAI Codex device-code OAuth polls inside `createOpenAICodexOAuthProvider().login()` with bounded delays and abort support via `OAuthLoginCallbacks.signal`. Token-endpoint failures redact authorization codes, PKCE verifiers, device/user codes, and access/refresh tokens when those values are known.
+- The shared bounded device/token flow lives in core `pollDeviceCodeToken` (0.2.1) and is used by the OpenAI Codex provider and the credentials-node OAuth 2.0 provider (Microsoft 365 / Google Workspace). It owns the RFC 8628 device-code request and poll loop (`authorization_pending` continue, `slow_down` +5s backoff, expiry deadline, abort), reads every response body under the shared byte ceiling, parses success bodies with a fail-closed shape gate (an `access_token` string is required), and redacts device/user codes, authorization codes, PKCE verifiers, and tokens from every thrown error. Adapter-specific fields (message prefix, extra token params, account binding) are plain options, never subclasses.
 
 ## Related APIs
 

package/docs/database-persistence.md

@@ -76,6 +76,8 @@ Important shapes:
 
 Optional session-record write seam (0.0.14): `appendSession?(record: SessionRecord)` upserts a session row — ownership columns are set on create only, `metadata`/`updatedAt` on update — so hosts (e.g. the [conversation service](conversations.md)) can durably mark and title sessions without entry writes. `SessionQuery` gained two bounded filters for the same seam: `id` (exact session lookup) and `metadataKey` (sessions whose `metadata` object contains a top-level key, validated by `assertSessionMetadataKey`). SQLite implements it with `json_extract`, PostgreSQL with a `jsonb` existence check; both keep ownership filtering intact.
 
+Metadata CAS (0.2.2): the write seam accepts an additive `expectedVersion` guard and returns the new `{ version }`. `expectedVersion: 0` means create-only (a duplicate insert is rejected with `SessionMetadataConflictError`, code `metadata_conflict`), a positive number means the stored `version` must match exactly (update-only — a deleted row is never re-created), and omitting it keeps legacy last-write-wins. Both adapters implement the guard inside the single upsert statement (PostgreSQL `INSERT … SELECT … WHERE … ON CONFLICT … DO UPDATE … WHERE version = $n`; SQLite the same shape with null-safe ownership `IS` comparisons); conflicts carry the id and versions only, never metadata content. The `version` column ships as migration `008_session_version` (`INTEGER NOT NULL DEFAULT 0` plus a one-time backfill to 1) — additive and forward-only, so pre-0.2.2 databases upgrade in place and non-CAS callers behave byte-identically.
+
 Artifact co-work review (0.0.14) reuses the generic `CheckpointStore` rather than adding a dedicated table: the [artifact service](work-artifacts-and-review.md) stores each artifact as a versioned checkpoint value (namespace `prism.artifact`, key `threadId:artifactId`, category `artifact`). The checkpoint `version` is the compare-and-swap counter that resolves concurrent reviewers; revision numbers, approvals, and `lastValidatedVersion` live inside the JSON value. SQLite/Postgres already persist checkpoints durably, so there is no separate artifact schema or migration, and records carry metadata/hashes/refs only — never file bodies.
 
 ## Outputs / response / events
@@ -372,6 +374,7 @@ Recommended migration practices:
 - Use a sequential or timestamped migration naming convention.
 - Store applied migrations in `prism_migrations` with `name`, `version`, `applied_at`, `applied_by`, and `checksum`.
 - Make entry-kind and schema-version changes additive when possible; new kinds and versions fail closed in the JSONL parser, so DB schemas should accept the same additive expansion.
+- Additive columns ship as forward-only migrations (`ALTER TABLE … ADD COLUMN IF NOT EXISTS` + a one-time backfill, e.g. `008_session_version` for the `prism_sessions.version` CAS column).
 - Index new query columns before deploying code that uses them.
 - Back-fill redacted flags and ownership columns before enforcing tenant isolation.
 
@@ -448,6 +451,7 @@ const dbStore: ProductionPersistenceStore = {
 - `ProductionPersistenceStore.feedback?: RunFeedbackStore` exposes immutable append, bounded owned query, and owned deletion. First-party adapters store migration-003 rows in `prism_run_feedback`, FK-link `run_id`, and index owner/run/trace creation cursors.
 - Hosts choose the database, schema, transaction, and indexing strategy. The contracts specify query and checkpoint capability shapes.
 - `SessionStore` (`append`/`list`/`get`/optional `readBranchPath`) can be implemented on top of `ProductionPersistenceStore` or kept separate.
+- **State-concurrency conformance (0.2.2):** durable adapters must pass `assertStateConcurrencyConforms` from `@arnilo/prism/testing/state-concurrency-conformance` against both the memory stores and their own implementation (approval determinism, checkpoint CAS, replay-cursor resume, idempotency retry, router reservation, conversation metadata CAS, unknown-outcome recovery). The harness uses deterministic barriers only — no timing-only sleeps — and runs the memory leg in the default `npm test` and the durable legs in `test:postgres`/`test:nats`; `scripts/phase22-conformance.test.mjs` asserts every store leg executed (missing protected environment records a named BLOCKED GATE, never a green skip).
 - Cursor values and idempotency keys are host-defined and opaque to Prism.
 - First-party SQLite/PostgreSQL adapters expose `persistence.checkpoints` and `persistence.leases`, backed by package-owned `prism_checkpoints` / `prism_leases` tables. `@arnilo/prism-workflows` consumes them for durable resume, human suspension, multi-process coordination, Phase 11 schedule records/fire leases, shared state, and replay lineage; workflow code owns no SQL table. `suspended`/`denied`, schedules, state history, and replay lineage remain namespaces/categories plus bounded checkpoint JSON values, so Phases 8 and 11 need no database migration.
 

package/docs/enterprise-postgres-state.md

@@ -13,7 +13,7 @@
 | Tool effects | `toolEffects` | Durable `ToolEffectStore` claim/CAS for recoverable tool side effects (migration 002). |
 | Tool effects | `toolEffects` | Durable `ToolEffectStore` claim/CAS for recoverable tool side effects (migration 002). |
 
-`createPostgresEnterpriseState()` opens a host-supplied or adapter-owned `pg` pool, verifies/applies checksum-protected enterprise migrations (`001_enterprise_state`, `002_tool_effects`), and returns those stores plus explicit cleanup and close operations. Importing it performs no I/O. It is separate from session/run persistence in [`@arnilo/prism-session-store-postgres`](postgres-persistence.md).
+`createPostgresEnterpriseState()` opens a host-supplied or adapter-owned `pg` pool, verifies/applies checksum-protected enterprise migrations (`001_enterprise_state`, `002_tool_effects`, `003_router_reservations`), and returns those stores plus explicit cleanup and close operations. Importing it performs no I/O. It is separate from session/run persistence in [`@arnilo/prism-session-store-postgres`](postgres-persistence.md).
 
 ## When to use it
 
@@ -85,7 +85,7 @@ Model-router state is asynchronous and owner/principal/provider/model scoped. Su
 }
 ```
 
-A migration creates `prism_policy_decisions`, `prism_evaluations`, `prism_work_idempotency`, three `prism_model_router_*` tables, and its separate `prism_enterprise_migrations` history. Startup serializes per-schema setup with an advisory transaction lock and rejects checksum or catalog drift rather than silently repairing it.
+A migration creates `prism_policy_decisions`, `prism_evaluations`, `prism_work_idempotency`, three `prism_model_router_*` tables, and its separate `prism_enterprise_migrations` history. Migration `003_router_reservations` adds the nullable-by-default `reservations` JSONB column to `prism_model_router_budgets` (atomic reservation slots for router admission; 0.2.1 readers ignore it). Startup serializes per-schema setup with an advisory transaction lock and rejects checksum or catalog drift rather than silently repairing it.
 
 ## Implementation example
 
@@ -152,7 +152,8 @@ export async function recordEnterpriseState(state: PostgresEnterpriseState) {
 
 ## Extension and configuration notes
 
-- `createModelRouter({ resolver, stateStore: state.modelRouter })` keeps allow-list, residency, fallback, and diagnostics behavior in `@arnilo/prism-model-router`; this package only supplies durable state.
+- `createModelRouter({ resolver, stateStore: state.modelRouter })` keeps allow-list, residency, fallback, and diagnostics behavior in `@arnilo/prism-model-router`; this package only supplies durable state. Router admission reservations (`reserveBudget`/`commitBudget`/`releaseBudget` on `state.modelRouter`) live in the `reservations` JSONB column of `prism_model_router_budgets`: one atomic UPSERT per admission, fencing-token-guarded commit/release in a SERIALIZABLE transaction, and TTL reconciliation as unknown usage; see [Model routing](model-routing.md).
+- Rate/budget/circuit tables are capped like the memory store: `consumeRate`/`readBudget`/`addUsage`/`reserveBudget` accept `maxRateKeys`/`maxBudgetKeys` (the router passes its resolved limits) and evict the least-recently-used row on new-key insert — never the row just inserted, never a budget row holding an active reservation — else fail closed with `ERR_PRISM_MODEL_ROUTER_STATE`. Cleanup prunes expired reservations within its bounded batch.
 - Policy/evaluation/query public contracts stay in their owning packages. This package exports only `createPostgresEnterpriseState`, its options/result types, and `EnterprisePostgresError`; it has no SQL, DDL, codec, queryable, or migration subpath.
 - The fixed schema has no generic key/value table and no background cleanup scheduler. Schedule `state.cleanup()` from an authorized host job, size its bounded batch for the deployment, and monitor unknown work rows for reconciliation. Run protected integration checks with `PRISM_TEST_POSTGRES_URL="$DATABASE_URL" npm run test:postgres`; the command rejects an absent URL instead of silently skipping database coverage.
 - The OPA adapter (`@arnilo/prism-policy/opa`, 0.0.28) records decisions into the same `state.policy` store unchanged via `evaluateAndAppend` — see [Policy and audit](policy-and-audit.md#opa-external-policy-adapter-arniloprism-policyopa-008).