@arnilo/prism 0.2.1 → 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/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).

package/docs/index.md

@@ -3,19 +3,19 @@
 Prism is a TypeScript/Node.js agent harness. Host apps and extension packages own providers, tools, resources, credentials, storage, UI, and business behavior. Prism supplies contracts, registries, streaming events, and replaceable runtime primitives.
 
 ## Public contracts
-- [Public contracts](public-contracts.md): type shapes for messages, agents, tools, stores, generic `CheckpointStore`, atomic `LeaseStore`, bounded `EventMultiplexer`, resources, credentials, and events.
+- [Public contracts](public-contracts.md): type shapes for messages, agents, tools, stores, generic `CheckpointStore`, atomic `LeaseStore`, bounded single-consumer `EventMultiplexer`, resources, credentials, and events.
 
 ## Identity and governance
 - [Agent identity](agent-identity.md): host-verified `Principal` / `AgentIdentity`, delegation narrowing, ownership projection, and redacted telemetry refs for enterprise runs/tools/MCP/A2A/workflows; optional OIDC/JWKS verifier adapter (`@arnilo/prism-credentials-node/oidc` — pinned issuer/audience/JWKS, bounded claims, fail closed).
 - [Policy and audit](policy-and-audit.md): optional `@arnilo/prism-policy` decision ledger (allow/deny/modify/approval), evidence refs only, cursor-paginated WORM export, and durable PostgreSQL composition; 0.0.28 adds the OPA REST evaluator (`@arnilo/prism-policy/opa` — pinned SSRF-checked endpoint, redacted input, fail-closed deny, optional bundle-revision pin); 0.2.1 makes the OPA decision fetch DNS-pinned (core `pinnedFetch`).
-- [Model routing](model-routing.md): optional `@arnilo/prism-model-router` allow-list/residency/budget/rate/circuit/fallback governance with redacted diagnostics; durable state requires awaited identity-scoped calls; host-configurable selection policies (reference cost/latency policy ranks by `ModelCost` then in-memory latency EMA fed from `recordOutcome`).
+- [Model routing](model-routing.md): optional `@arnilo/prism-model-router` allow-list/residency/budget/rate/circuit/fallback governance with redacted diagnostics; budget admission reserves per-request caps atomically (commit/release/TTL reconciliation); durable state requires awaited identity-scoped calls; host-configurable selection policies (reference cost/latency policy ranks by `ModelCost` then in-memory latency EMA fed from `recordOutcome`).
 
 ## Agent/session runtime
 - [Agent/session runtime](agent-session-runtime.md): create explicit or opt-in secure agents/sessions, get direct `AgentRunResult` values from `run`/`prompt`, mid-run `steer` (turn-boundary or softInterrupt), use integrated `stream()`/`resumeAgentRunStream()`, shared batch pending-decisions / sticky run-scope approvals, subscribe to normalized events, and expose opted-in durable lifecycle capabilities (0.1.6 plan 018 closeout `checkpoint-bodies`: optional `includeSkillBodies` persists the exact loaded-skill instructions with the names-only `persistSessionState`, so resume re-renders bodies registry-independently; ≤64 bodies, `maxStateBytes` refuses oversize; 0.2.0 plan 020 Task 2: durable resume input is validated in core before any side effect — fail-closed durable resume rejects unknown legacy decisions and malformed batches with zero checkpoint writes, tool calls, or resumed events).
 - [Agent definitions](agent-definitions.md): resolve declarative `AgentDefinition` values via `resolveAgentDefinition`, and turn app-config `<configRoot>/agents/<name>/AGENT.md` bundles into runnable agents via `discoverAgentBundles` / `resolveAgentBundle` (explicit tool/skill activation by name, fail-closed omitted capabilities, migration-only `activateAllCapabilities`, strict duplicate scope checks, configurable prompt layers, no auto-discovery).
 - [Agent loops](agent-loops.md): replaceable per-run control loops — `singleShotLoop` default, opt-in bounded artifact-loop tool rounds, and durable custom-loop `revision`/`snapshot`/`restore` hooks with fail-closed resume.
 - [Guardrails](guardrails.md): typed fail-closed input/output/tool checks with buffered provider output and redacted decision records.
-- [Agent events](agent-events.md): live `session.subscribe` plus durable `AgentEventSource` page/subscribe/resume for cross-replica reconnect; message/progress deltas never create spans. Durable sources: PostgreSQL `LISTEN`/`NOTIFY` (reference, `@arnilo/prism-session-store-postgres` root export) and NATS JetStream (`@arnilo/prism-session-store-nats`, FR-5).
+- [Agent events](agent-events.md): live `session.subscribe` plus durable `AgentEventSource` page/subscribe/resume for cross-replica reconnect; message/progress deltas never create spans. Durable sources: PostgreSQL `LISTEN`/`NOTIFY` (reference, `@arnilo/prism-session-store-postgres` root export) and NATS JetStream (`@arnilo/prism-session-store-nats`, FR-5) with restart-stable durable consumer identity (`prism_<hmac16>`) for cursor resume across crash/restart.
 - [Observability](observability.md): OTel GenAI agent/provider/tool hierarchy, host context parenting, bounded trace linkage, safe evaluation events, controlled metrics, and exporter isolation.
 - [Evaluations](evaluations.md): deterministic and bounded trace/model-judge/pairwise scoring, CI thresholds, OTel trace-reference linkage, coding/browser adversarial fixtures, ID-only linkage to immutable owned run feedback, and optional durable PostgreSQL records.
 - [Runs and usage ledger](runs-and-usage.md): durable run/event/tool/usage persistence, optional bounded FIFO durability policies, session snapshot caching, and immutable run/trace feedback.
@@ -28,13 +28,13 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 - [Observational memory compaction package](compaction-observational-memory.md): optional source-backed memory with explicit `attach()` lifecycle — **Recent exact messages**, **Observation log**, **Reflections**, **Raw-source retrieval** (exact-id recall + cursor paging); dual coverage, **nested-only settings** (pre-0.0.19 flat keys and top-level `workerProvider`/`workerModel` aliases removed in 0.1.5; removed keys fail closed naming the nested replacement), branch-isolated `appendEntry`, secrets redaction, and inert import/extension.
 - [Working and semantic memory](working-and-semantic-memory.md): optional `@arnilo/prism-memory` working-memory store, semantic recall, finite Embedder/VectorStore contracts, PostgreSQL/pgvector path, consent lifecycle, identity-bound redacted export, and resumable bounded rebuild.
 - [Session stores](session-stores.md): `SessionStore` contract, `SessionAppendOptions`, `SessionAppendConflictError`, branch handles, `readBranchPath`, optional bounded `searchSessions` / `SessionIndex` (memory linear|unsupported), and dev-vs-production branch reads — start here for session persistence.
-- [Conversations](conversations.md): durable user-scoped conversation threads (create/list/continue/branch/archive/export/delete) on session + event-ledger seams, thread-bound reconnectable replay, frozen caps, and legal-hold-aware deletion.
+- [Conversations](conversations.md): durable user-scoped conversation threads (create/list/continue/branch/archive/export/delete) on session + event-ledger seams, thread-bound reconnectable replay, frozen caps, atomic metadata via version/CAS (`metadata_conflict` on stale writes), and legal-hold-aware deletion.
 - [Work artifacts and review](work-artifacts-and-review.md): durable artifact co-work review — authorized attach (MIME/hash/version, producer run, citations, preview metadata), revision compare, approve/reject with last-validated recovery, and authorized expiring delivery links; records persist as versioned checkpoints, never file bodies. 0.0.28 adds the core `ArtifactBodyStore` contract (put/get/delete/presign by opaque ownership-scoped ref, hash/size/MIME verification, legal-hold-aware idempotent delete) and the reference `@arnilo/prism-server/artifact-bodies` S3-compatible adapter (hand-rolled SigV4, native fetch + WebCrypto, optional host KMS callback); delivery links resolve through `bodies.presign` when wired.
 - [Session stores and branching](session-stores-and-branching.md): detailed branch semantics and helper reference (kept for compatibility; links back to the canonical atomic append / branch-handle sections).
-- [Database persistence](database-persistence.md): production persistence contracts, shared checksummed migration/full-shape catalog primitives (`@arnilo/prism/testing/persistence-schema`), conditional append, indexes, `readBranchPath`, reference relational schema, retention/legal-hold/quota lifecycle (`lifecycle`), and NoSQL mapping.
+- [Database persistence](database-persistence.md): production persistence contracts, shared checksummed migration/full-shape catalog primitives (`@arnilo/prism/testing/persistence-schema`), conditional append, indexes, `readBranchPath`, reference relational schema, retention/legal-hold/quota lifecycle (`lifecycle`), and NoSQL mapping. `appendSession` gains version/CAS (migration `008_session_version`); durable adapters must pass `assertStateConcurrencyConforms` (`@arnilo/prism/testing/state-concurrency-conformance`: approval/checkpoint-CAS/cursor/idempotency/reservation/conversation-metadata/unknown-outcome probes; memory leg in `npm test`, durable legs in `test:postgres`/`test:nats`, `scripts/phase22-conformance.test.mjs` gate accounting).
 - [SQLite persistence](sqlite-persistence.md): optional `better-sqlite3` adapter with session/run storage, checkpoints/leases, feedback, FTS `searchSessions` (migration-v4), and transactionally verified/backfilled migration metadata.
 - [PostgreSQL persistence](postgres-persistence.md): optional pooled `pg` adapter with session/run/checkpoint/lease/feedback storage, FTS `searchSessions` (migration-v4), advisory-locked checksummed/full-shape migrations, and opt-in live conformance.
-- [Enterprise PostgreSQL state](enterprise-postgres-state.md): optional `@arnilo/prism-enterprise-postgres` composition for durable policy/evaluation/work-idempotency/model-router/`toolEffects` state, exact ownership, checksummed migrations, and explicit cleanup.
+- [Enterprise PostgreSQL state](enterprise-postgres-state.md): optional `@arnilo/prism-enterprise-postgres` composition for durable policy/evaluation/work-idempotency/model-router/`toolEffects` state, exact ownership, checksummed migrations (001-003; 003 adds router budget reservation slots), and explicit cleanup.
 - [Migration guide](migration.md): **0.1.4 → 0.1.5** documented breaking cut — deprecated-option removal (the inert provider request knobs, `maxToolRounds` alias, observational-memory flat keys/worker aliases, `autoResizeImages`, `INIT_PROVIDERS`) with exact replacement table, before/after examples, and fail-closed refusal behavior; **0.0.28 → 0.1.0** release-candidate hardening (no migration); **0.0.17 → 0.1.0 upgrade matrix** (store compatibility per release line: compatible / tested migration / tested refusal, plus breaking-default callouts); **0.0.27** ACP coding-host interop (capability advertise-when, session modes/config, MCP select, lifecycle events, elicitation); **0.0.26** coding intelligence, managed processes, forge, and safe egress; **0.0.25** durable custom loops and shared human-in-the-loop decisions; **0.0.24** distributed events and recoverable tool effects; **0.0.23** enterprise PostgreSQL state adapters (async router and work reconciliation); **0.0.22** third-party behavior integrations (Caveman, Ponytail); **0.0.21** coding-tool capability gaps (`outputMode`, glob, read-before-write, delete/move, aggregator 9/4); **0.0.20** progressive skill disclosure, empty registry default, `load_skill`, priority budget demotion, optional tool-result fold; **0.0.19** observational memory lifecycle; **0.0.15** OpenAI hosted tools/continuation/Realtime, exact AI SDK v4 matrix, RAG lifecycle/reranking/trust/status, and memory export/rebuild; **0.0.14** conversations, memory consent/lifecycle, artifact co-work review, AG-UI co-work events, scoped M365/GWS OAuth connectors, browser checkpoints, device contracts, and Alibaba/Ollama providers; plus prior release migrations.
 - [Node JSONL session store](node-jsonl-session-store.md): development-only JSONL file adapter for single-process Node hosts; no cross-process safety; `searchSessions` throws `SessionSearchUnsupportedError`.
 - [Persistence, credentials, and multimodality primitives](persistence-credentials-multimodality-primitives.md): Plan 056 inventory — session/run-ledger/persistence contracts, credential/OAuth seams, content/resource/model capabilities, package dependency matrix, conformance matrix, and threat model for production adapters.
@@ -104,7 +104,7 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 
 ## CLI/RPC
 - [CLI/RPC](cli-rpc.md): Run print/json modes and LF-delimited RPC over the public AgentSession runtime, including mid-run `steer`, branch-handle results, fixed `forkSession`, and `checkout`. `prism init` scaffolds a tiny TypeScript project with one selected provider and an offline mock test; `prism providers add <name>` scaffolds an OpenAI-compatible provider package (manifest, provider, models, cache helpers, conformance test, docs stub).
-- [Workflows](workflows.md): optional `@arnilo/prism-workflows` typed bounded DAG orchestration — explicit recursive definition revisions, exact-owner cancellation/active identity, finite hard limits, durable human suspend/resume, schedules/background execution, revocable proactive schedule capability tokens, nested workflows, replay, coordination, events, and optional RPC/Web bindings. Compose coding plans/checkpoints via workspace Markdown + `state.coding` without a second runtime. Interactive TUI (C-012) deferred.
+- [Workflows](workflows.md): optional `@arnilo/prism-workflows` typed bounded DAG orchestration — explicit recursive definition revisions, exact-owner cancellation/active identity, finite hard limits, durable human suspend/resume, schedules/background execution, revocable proactive schedule capability tokens, nested workflows, replay, coordination, events, and optional RPC/Web bindings. Compose coding plans/checkpoints via workspace Markdown + `state.coding` without a second runtime. Active-run registry is non-durable, in-process only, with bounded sweep/cap cleanup. Interactive TUI (C-012) deferred.
 - [Workflow orchestration primitives](workflow-orchestration-primitives.md): architecture inventory — workflow adapters consume core `CheckpointStore`, `LeaseStore`, and bounded `EventMultiplexer`; run control and optional RPC commands stay package-local.
 - [Workflow/TUI scope](workflow-tui-primitives.md): records why 0.0.5 ships workflow APIs/RPC control but no interactive terminal UI.
 
@@ -129,7 +129,7 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 - [Ponytail behavior integration](ponytail.md): optional `@arnilo/prism-ponytail` — upstream Ponytail skills/commands, `ponytail-mode` injector, session `ponytail-mode` persistence; resolves peer `@dietrichgebert/ponytail` or `upstreamPath`; opt-in (not in code/sdk profiles).
 
 ## Release and install
-- [Release and install](release-and-install.md): current **0.2.1** 50-package graph (root + 49 workspace packages) — plan 021 the provider-completion-and-outbound-trust-boundaries cut: strict stream completion is the shared OpenAI-compatible default (truncated streams fail `incomplete_delta`, explicit `strictCompletion: false` opt-out), bounded success bodies via `readBoundedResponseJson` on all discovery/quota/embeddings/upload/OAuth JSON endpoints (65,536-byte ceiling, depth/property/shape caps), DNS-pinned OIDC JWKS/OPA/content fetches through the core `pinnedFetch` primitive with 3xx redirects rejected outright (private/metadata answers fail closed `ssrf_denied`), shared bounded OAuth device/token polling (`pollDeviceCodeToken`) across provider-openai and credentials-node, and the four edge fixes (Azure/Vertex credential-once, Bedrock duplicate-case/repeated-query SigV4 canonicalization, OpenAI upload failed-DELETE retention, cache `__overflow__` tokens-only); public-entrypoint threat-suite `scripts/phase21-security.test.mjs` + packed plain-JS consumer; additive-only compat (MCP transport helpers re-exported from core, no removals); migration `0.2.0 → 0.2.1`; then plan 020 the fail-closed runtime-and-sandbox-security cut on the 0.2.x review-remediation line: durable-resume decision validation in core (`assertValidAgentRunResume` — unknown decisions/malformed batches fail closed with `ERR_PRISM_DECISION_*` before any state claim, checkpoint write, or tool execution; server parser remains defense in depth), isolated work-tool subprocess environments (`@arnilo/prism-work-tools` — fixed base allow-list + explicit env + forced HOME/telemetry + late-bound per-identity tokens, 64-name/64-KiB caps, absolute binary/configDir, linear output capture), and explicit sandbox capabilities (`@arnilo/prism-coding-security` — `SandboxAdapter.capabilities` with omission-is-false fail-closed resolution, `SandboxCodingComposition.capabilities` from verified wiring, `containmentClaim` deprecated as the conservative projection; Docker reports only verified controls, native reports filesystem/process/privilege `false`); public-entrypoint security conformance (`scripts/phase20-security.test.mjs`, wired into `security:threat-suites`), packed plain-JS consumer regressions, and the sandbox-browser workflow's fail-loud Docker/native capability evidence gate — 0.2.0 never ships while a blocker is skipped; migration and rollback notes in `docs/migration.md` `0.1.7 → 0.2.0`, store-compatible with 0.1.7 in both directions; 0.1.7 was the performance-and-DX patch — dependency-free `createCacheTelemetry()` per-provider/model cache hit/miss aggregator (bounded cardinality with `__overflow__`, token counters/rates only, host-activated), host-configurable `ModelRouterSelectionPolicy` on `createModelRouter` with the reference `createCostLatencySelection` (ModelCost rank then in-memory latency EMA, default ordered behavior byte-identical), `prism providers add <name>` OpenAI-compatible provider scaffold (manifest/provider/models/cache/conformance test/docs stub, npm-name + traversal + symlink-escape validation, placeholders only), and the async `AgUiProjection` verification closeout (plan 009 Task 15 evidence recorded, no new code); plan 017 the documented breaking cut — deprecated-option removal with `docs/migration.md` `0.1.4 → 0.1.5` section and reviewed compat-baseline regeneration via `--allow-break` then `--update-baseline`: the inert provider request knobs, `RunOptions.maxToolRounds`, observational-memory flat settings keys + top-level worker aliases, `ReadToolOptions.autoResizeImages`, `INIT_PROVIDERS`; all removals fail closed naming their replacement; plan 016 internal god-module split — `agents.ts`/`contracts.ts` reorganized behind barrel re-exports with a byte-identical public entry surface, measured tree-shaking improvement in `scripts/phase16-baseline.json`, and additive `@arnilo/prism-browser` Chrome DevTools Protocol capabilities — `browser_evaluate`/`browser_observe` and `block_urls`/`unblock_urls`/`throttle`/`emulate` act actions; plan 015 dead-code and deprecation hygiene on the frozen 0.1.x line — parameterized benchmark runner `scripts/benchmark.mjs` absorbing the per-version runners, archived review-coverage evidence in `docs/_evidence/`, non-blocking unused-code sweep `npm run sweep:unused`, opt-in checkpoint persistence for loaded-skill names and read-path sets; plan 014 Alibaba provider enrichment — embeddings, video input, verified compatible-mode surface decision table; plan 013 post-release hardening — build single-flight, MCP SSE relay test, combined coverage summary, canonical manifest-count narrative, ACP modes/config persistence guidance; Phase 12 release-candidate hardening; plan 012 — freeze manifest, compatibility matrix, upgrade matrix, packed-install e2e journeys, restart-recovery evidence, capacity envelopes, security policy), exact-peer/install/tarball rules, deterministic resumable publication and publish dry-run, frozen 0.1.x compatibility and support matrix (Node/PostgreSQL/platform/provider/protocol pins and unsupported combinations, machine-checked against `scripts/phase12-freeze-manifest.json`), protected PostgreSQL gate, pinned supply-chain gates, offline tests, the 0.0.15 provider/AI-SDK/RAG/memory protected live-canary matrix, and sandbox-browser Docker/Playwright gates.
+- [Release and install](release-and-install.md): current **0.2.2** 50-package graph (root + 49 workspace packages) — plan 022 the concurrent-state-and-durability-integrity cut: atomic model-budget reservation (`ModelRouterStateStore.reserveBudget`/`commitBudget`/`releaseBudget` with fencing tokens, `reservationTtlMs` expiry and unknown-usage reconciliation, rate/budget key-map caps with LRU eviction that never drops a held reservation), atomic conversation metadata (`SessionRecord.version` + `appendSession` `expectedVersion` CAS across Postgres/SQLite — create-only `0`, exact-version `N>0`, legacy last-write-wins when omitted; `SessionMetadataConflictError` `metadata_conflict` with versions only, HTTP 409; concurrent create/branch/archive single-statement with branch caps inside the CAS, archive wins, deleted rows never resurrect), single-consumer `EventMultiplexer` (`EventMultiplexerError` `ERR_PRISM_EVENT_MULTIPLEXER_SINGLE_CONSUMER` instead of silent queue sharing), restart-stable NATS durable consumer identity (`prism_<hmac16>` with no random suffix — crash-resumed subscribe continues from the last ack, orphaned 0.2.1 consumers reclaimed on clean stop), and bounded non-durable active-run registries (sweep + fail-closed 512 cap `ERR_PRISM_WORKFLOW_RUN_REGISTRY_OVERFLOW`); new regression surface `scripts/phase22-security.test.mjs` (4 blockers + gate accounting over built public entrypoints) + packed plain-JS `security22.mjs` consumer + the `@arnilo/prism/testing/state-concurrency-conformance` harness (7 probes across memory/Postgres/SQLite/NATS legs, no timing-only sleeps) + the `scripts/phase22-conformance.test.mjs` gate; additive-only compat (new exports only, no removals); forward-only migrations 008 (`prism_sessions.version`) and 003 (`prism_model_router_budgets.reservations`); migration `0.2.1 → 0.2.2`; then plan 021 the provider-completion-and-outbound-trust-boundaries cut: strict stream completion is the shared OpenAI-compatible default (truncated streams fail `incomplete_delta`, explicit `strictCompletion: false` opt-out), bounded success bodies via `readBoundedResponseJson` on all discovery/quota/embeddings/upload/OAuth JSON endpoints (65,536-byte ceiling, depth/property/shape caps), DNS-pinned OIDC JWKS/OPA/content fetches through the core `pinnedFetch` primitive with 3xx redirects rejected outright (private/metadata answers fail closed `ssrf_denied`), shared bounded OAuth device/token polling (`pollDeviceCodeToken`) across provider-openai and credentials-node, and the four edge fixes (Azure/Vertex credential-once, Bedrock duplicate-case/repeated-query SigV4 canonicalization, OpenAI upload failed-DELETE retention, cache `__overflow__` tokens-only); public-entrypoint threat-suite `scripts/phase21-security.test.mjs` + packed plain-JS consumer; additive-only compat (MCP transport helpers re-exported from core, no removals); migration `0.2.0 → 0.2.1`; then plan 020 the fail-closed runtime-and-sandbox-security cut on the 0.2.x review-remediation line: durable-resume decision validation in core (`assertValidAgentRunResume` — unknown decisions/malformed batches fail closed with `ERR_PRISM_DECISION_*` before any state claim, checkpoint write, or tool execution; server parser remains defense in depth), isolated work-tool subprocess environments (`@arnilo/prism-work-tools` — fixed base allow-list + explicit env + forced HOME/telemetry + late-bound per-identity tokens, 64-name/64-KiB caps, absolute binary/configDir, linear output capture), and explicit sandbox capabilities (`@arnilo/prism-coding-security` — `SandboxAdapter.capabilities` with omission-is-false fail-closed resolution, `SandboxCodingComposition.capabilities` from verified wiring, `containmentClaim` deprecated as the conservative projection; Docker reports only verified controls, native reports filesystem/process/privilege `false`); public-entrypoint security conformance (`scripts/phase20-security.test.mjs`, wired into `security:threat-suites`), packed plain-JS consumer regressions, and the sandbox-browser workflow's fail-loud Docker/native capability evidence gate — 0.2.0 never ships while a blocker is skipped; migration and rollback notes in `docs/migration.md` `0.1.7 → 0.2.0`, store-compatible with 0.1.7 in both directions; 0.1.7 was the performance-and-DX patch — dependency-free `createCacheTelemetry()` per-provider/model cache hit/miss aggregator (bounded cardinality with `__overflow__`, token counters/rates only, host-activated), host-configurable `ModelRouterSelectionPolicy` on `createModelRouter` with the reference `createCostLatencySelection` (ModelCost rank then in-memory latency EMA, default ordered behavior byte-identical), `prism providers add <name>` OpenAI-compatible provider scaffold (manifest/provider/models/cache/conformance test/docs stub, npm-name + traversal + symlink-escape validation, placeholders only), and the async `AgUiProjection` verification closeout (plan 009 Task 15 evidence recorded, no new code); plan 017 the documented breaking cut — deprecated-option removal with `docs/migration.md` `0.1.4 → 0.1.5` section and reviewed compat-baseline regeneration via `--allow-break` then `--update-baseline`: the inert provider request knobs, `RunOptions.maxToolRounds`, observational-memory flat settings keys + top-level worker aliases, `ReadToolOptions.autoResizeImages`, `INIT_PROVIDERS`; all removals fail closed naming their replacement; plan 016 internal god-module split — `agents.ts`/`contracts.ts` reorganized behind barrel re-exports with a byte-identical public entry surface, measured tree-shaking improvement in `scripts/phase16-baseline.json`, and additive `@arnilo/prism-browser` Chrome DevTools Protocol capabilities — `browser_evaluate`/`browser_observe` and `block_urls`/`unblock_urls`/`throttle`/`emulate` act actions; plan 015 dead-code and deprecation hygiene on the frozen 0.1.x line — parameterized benchmark runner `scripts/benchmark.mjs` absorbing the per-version runners, archived review-coverage evidence in `docs/_evidence/`, non-blocking unused-code sweep `npm run sweep:unused`, opt-in checkpoint persistence for loaded-skill names and read-path sets; plan 014 Alibaba provider enrichment — embeddings, video input, verified compatible-mode surface decision table; plan 013 post-release hardening — build single-flight, MCP SSE relay test, combined coverage summary, canonical manifest-count narrative, ACP modes/config persistence guidance; Phase 12 release-candidate hardening; plan 012 — freeze manifest, compatibility matrix, upgrade matrix, packed-install e2e journeys, restart-recovery evidence, capacity envelopes, security policy), exact-peer/install/tarball rules, deterministic resumable publication and publish dry-run, frozen 0.1.x compatibility and support matrix (Node/PostgreSQL/platform/provider/protocol pins and unsupported combinations, machine-checked against `scripts/phase12-freeze-manifest.json`), protected PostgreSQL gate, pinned supply-chain gates, offline tests, the 0.0.15 provider/AI-SDK/RAG/memory protected live-canary matrix, and sandbox-browser Docker/Playwright gates.
 - [0.1.0 / 1.0 readiness gates](0.1.0-readiness.md): command-per-gate 1.0 readiness table — frozen API surface + compat gate, migration/docs tripwires, budget table, live-suite matrix, security matrix, current-line status (**0.0.23** published target), signed-publication/live-canary prerequisites for 1.0, and Phase 12 demand-evidence entry criteria.
 - [Review coverage archive](_evidence/): per-phase evidence freezes (plans 067–079, releases 0.0.4–0.0.16) — traceability matrices, provider validation, capability/primitive/limit matrices, benchmark budgets, and artifact-diet findings; tarball-excluded, kept in-repo for audit.
 

package/docs/migration.md

@@ -1,5 +1,57 @@
 # Migration guide
 
+## 0.2.1 → 0.2.2 concurrent state and durability integrity (plan 022)
+
+Release **0.2.2** (plan 022) makes four concurrency/durability boundaries atomic or fail-loud. The API surface is **additive-only** (plain reviewed compat gate at 0.2.2: expected deltas are the version literal, `ModelRouterStateStore.reserveBudget`/`commitBudget`/`releaseBudget` plus `ModelRouterReservation`/`ModelRouterBudgets.reservationTtlMs`/`ModelRouterLimits.maxRateKeys`/`maxBudgetKeys` (memory + Postgres), `SessionRecord.version` with `appendSession` `expectedVersion`, `EventMultiplexerError` with code `ERR_PRISM_EVENT_MULTIPLEXER_SINGLE_CONSUMER`, and the `@arnilo/prism/testing/state-concurrency-conformance` subpath; no removal, no `--allow-break`). Three of the four changes tighten behavior where 0.2.1 silently accepted a race — concurrent hosts may now see an explicit conflict where 0.2.1 lost an update or oversubscribed a budget:
+
+1. **Atomic model-budget reservation (`model-router`, `enterprise-postgres`).** Admission is now reserve/commit/release: `reserveBudget` runs at admission and fails the request when `used + reserved + requested` would exceed the window max, returning `{ reservationId, fencingToken, admitted, retryAfterMs? }`; `commitBudget` applies the actual usage delta at the outcome (an expired reservation still charges the reserved amount with `unknownUsage: true` so a late commit can never disappear from accounting); `releaseBudget` frees an uncommitted reservation. `readBudget`-based admission stays for requests with no per-request cap, and the 0.2.1 post-hoc `addUsage` remains as retrospective accounting only — it is no longer admission authority.
+
+   ```js
+   // 0.2.1: readBudget then consumeRate then addUsage — concurrent admissions could collectively oversubscribe
+   // 0.2.2: admission reserves the full per-request cap, outcome commits/releases actuals
+   const reservation = await store.reserveBudget({
+     key: { tenantId, principalId, provider, model },
+     tokens: request.maxTokens, costUsd: request.maxCostUsd, // per-request caps, when set
+     windowMs: 24 * 60 * 60 * 1000, reservationTtlMs: 60_000,
+   });
+   if (!reservation.admitted) { /* denied; retry after reservation.retryAfterMs */ }
+   // ... run the request ...
+   await store.commitBudget({
+     key, reservationId: reservation.reservationId,
+     fencingToken: reservation.fencingToken, tokens: actualTokens, windowMs: 24 * 60 * 60 * 1000,
+   });
+   ```
+
+   Reservations expire after `reservationTtlMs` (default 60,000 ms, bounded to 31 days) even if a host never commits, so a crashed request cannot hold capacity forever. Rate/budget/circuit key maps are now capped (`maxRateKeys`/`maxBudgetKeys`, default 4,096, hard cap 65,536; circuits stay 1,024/16,384) with LRU eviction on insert; a budget row holding an active reservation is never evicted (the eviction candidates exclude held rows, and if nothing is evictable the insert fails with `ERR_PRISM_MODEL_ROUTER_STATE` `capacity-exhausted`). The durable Postgres store keeps reservations in a new `reservations` JSONB column on `prism_model_router_budgets` (migration 003, forward-only, applied automatically by `applyEnterpriseMigrations`; existing rows are untouched and read as no reservations).
+
+2. **Atomic conversation metadata (`session-store-postgres`, `session-store-sqlite`, core `SessionRecord`).** `SessionRecord` gains `version` (fresh rows start at 1; migration 008 backfills legacy 0-version rows to 1) and `appendSession` accepts `expectedVersion`: `0` = create-only, `N > 0` = exact-version CAS update-only, omitted = the 0.2.1 last-write-wins behavior for untyped/legacy callers. A stale write throws `SessionMetadataConflictError` (`metadata_conflict`) carrying only `{ id, expectedVersion, currentVersion }` — never metadata content — and the HTTP server maps it to 409. Concurrent create/branch/archive are now single-statement: the branch `maxActiveBranches` cap is enforced inside the CAS write (a concurrent branch at cap-1 fails its version guard instead of silently dropping the oldest ref), archive wins over a stale concurrent write, and a retention-deleted session is never resurrected (the update arm requires the row to still exist).
+
+   ```js
+   // 0.2.1: create could race to the last metadata write; concurrent branch calls could lose a ref
+   // 0.2.2: exactly one concurrent writer wins per version; losers get metadata_conflict
+   const { version } = await persistence.appendSession({
+     id: sessionId, ...ownership, createdAt, updatedAt, metadata: { state: "active" },
+     expectedVersion: 0, // create-only: conflict if the session already exists
+   });
+   try {
+     await persistence.appendSession({ ...record, metadata: { state: "archived" }, expectedVersion: version });
+   } catch (error) {
+     if (error.code === "metadata_conflict") { /* re-read the winning version and retry */ }
+   }
+   ```
+
+3. **Single-consumer `EventMultiplexer` (core).** `createEventMultiplexer().subscribe()` now rejects a second concurrent consumer with `EventMultiplexerError` `ERR_PRISM_EVENT_MULTIPLEXER_SINGLE_CONSUMER` instead of parking both consumers on one queue and silently losing events. The slot frees when the active consumer's iterator completes, is `return()`ed at a yield, or the multiplexer closes. Hosts that previously relied on multiple `subscribe()` calls sharing one multiplexer must either serialize consumption or use the event source's own broadcast `subscribe` (agent-events), which still supports multiple subscribers. `createWorkflowEventBus` and the supervisor (the only in-repo consumers) are unaffected — each already uses a single subscriber.
+
+4. **Restart-stable NATS durable consumer identity (`session-store-nats`).** The durable consumer name is now exactly `prism_<hmac16 of tenantId|sessionId|runId>` — the 0.2.1 random suffix is gone, so a crashed durable subscribe is reused at its last-acked position by a restarting process (cursor resume, at-least-once). Clean stops still delete the durable consumer (resume then relies on the HMAC-signed cursor); only a crash leaves the consumer in place. Pre-0.2.2 consumers minted with the random suffix (`prism_<digest>_<random>`) are orphaned and reclaimed by the existing `deleteConsumer`/consumer-enumeration cleanup path on the next clean stop of a same-subject subscribe.
+
+5. **Bounded, non-durable active-run registries (`workflows`).** The in-process workflow active-run registry is documented as non-durable (no timer, no background service): `registerActiveWorkflowRun` sweeps aborted/leaked entries before every insert and fails closed with `WorkflowRuntimeError` `ERR_PRISM_WORKFLOW_RUN_REGISTRY_OVERFLOW` at the 512 cap instead of evicting a live entry (a live eviction could silently allow a duplicate run). A run whose promise never settles is reclaimed only when it is aborted or the cap forces a sweep — there is no durable recovery of active runs in 0.2.2 (see Further Actions: 0.2.6).
+
+**Store compatibility:** 0.2.2 is **not** rollback-compatible with 0.2.1 in the Postgres/SQLite persisted shape: `prism_sessions` gains a `version` column (migration 008) and `prism_model_router_budgets` gains a `reservations` column (enterprise migration 003). Both migrations are forward-only and additive — 0.2.2 code reads 0.2.1 databases correctly after migration (backfill included); a 0.2.1 binary pointed at a 0.2.2 database still works because the new columns are nullable/defaulted, but it will not maintain versions or reservations. The NATS durable-name change touches no persisted data (consumers are runtime state; orphaned 0.2.1 consumers are reclaimed on the next clean stop).
+
+**Rollout:** upgrade core and the session stores together (migration 008 runs automatically via the existing checksummed `prism_migrations`; the version column must exist before any host writes CAS updates). Then `enterprise-postgres` (migration 003) and `model-router` (reservation admission can be enabled per-host; hosts that never call `recordUsage` rely on TTL expiry). Then `workflows`/`server` (conversation CAS is transparent to clients except new 409 responses), then `session-store-nats`. Branch/archive callers that intentionally lost races in 0.2.1 must now handle `metadata_conflict` (re-read + retry) where they previously accepted last-write-wins.
+
+**Rollback risk:** restoring 0.2.1 against a 0.2.2 database is safe for reads and last-write-wins writes (the new columns are ignored) but silently reopens all four race windows: oversubscription, conversation lost updates, silent multi-subscriber event loss, and non-restart-stable NATS resume. Rollback is therefore only a stopgap, not a mitigation — prefer fixing the failing host on 0.2.2.
+
 ## 0.2.0 → 0.2.1 provider completion and outbound trust boundaries (plan 021)
 
 Release **0.2.1** (plan 021) tightens the streaming-completion, outbound-fetch, and credential/signing/upload boundaries. The API surface is **additive-only** (plain reviewed compat gate at 0.2.1: the only deltas are the version literal and `@arnilo/prism-mcp` transport helpers `boundResponse`/`defaultResolver`/`isLoopbackAddress`/`isLoopbackHostname`/`normalizeHostname`/`raceAbort`/`requestPinned`/`resolvePinnedAddress` becoming re-exports of the lifted core primitives — same names, same signatures, no removal; no `--allow-break`), with five documented security-motivated behavior tightenings. Untyped/legacy callers may now fail where 0.2.0 silently proceeded: