@arnilo/prism 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [0.2.2] - 2026-08-13
+
+### Changed
+- **Release 0.2.2 (plan 022)** is the concurrent-state-and-durability-integrity cut on the 0.2.x review-remediation line. API surface **additive-only** vs 0.2.1 (plain reviewed compat gate at 0.2.2: deltas are the version literal plus `ModelRouterStateStore.reserveBudget`/`commitBudget`/`releaseBudget`, `ModelRouterReservation`, `ModelRouterBudgets.reservationTtlMs`, `ModelRouterLimits.maxRateKeys`/`maxBudgetKeys`, `SessionRecord.version` with `appendSession` `expectedVersion`, `EventMultiplexerError` `ERR_PRISM_EVENT_MULTIPLEXER_SINGLE_CONSUMER`, and the `@arnilo/prism/testing/state-concurrency-conformance` subpath; no removal; no `--allow-break`), four behavior tightenings documented in `docs/migration.md` `0.2.1 → 0.2.2`: (1) **atomic model-budget reservation** (`budget-reservation`, `@arnilo/prism-model-router` + `@arnilo/prism-enterprise-postgres`) — admission now runs `reserveBudget` (used + reserved + requested <= window max, `{reservationId, fencingToken, admitted, retryAfterMs?}`) and outcomes run `commitBudget` (actuals; a TTL-expired late commit charges the reserved amount with `unknownUsage: true`) or `releaseBudget`; reservations expire after `reservationTtlMs` (default 60 s, bounded to 31 days) so a crashed request never holds capacity forever; 0.2.1 `readBudget`/`addUsage` remain for cap-less requests and retrospective accounting, no longer admission authority; rate/budget key maps are capped (`maxRateKeys`/`maxBudgetKeys` 4,096 default / 65,536 hard; circuits unchanged) with LRU eviction that never drops a held-reservation row (capacity-exhausted fail-closed otherwise); durable store keeps reservations in a `reservations` JSONB column (enterprise migration 003, forward-only, checksummed). (2) **atomic conversation metadata** (`conversation-metadata-cas`, `@arnilo/prism-session-store-postgres` + `@arnilo/prism-session-store-sqlite`) — `SessionRecord.version` (fresh rows start at 1; migration 008 backfills legacy rows) and `appendSession` `expectedVersion` (`0` create-only, `N>0` exact-CAS update-only, omitted = 0.2.1 last-write-wins); stale writes throw `SessionMetadataConflictError` `metadata_conflict` carrying only `{id, expectedVersion, currentVersion}` (never metadata content), HTTP 409; concurrent create/branch/archive are single-statement with branch caps enforced inside the CAS write, archive wins over stale writers, retention-deleted rows are never resurrected. (3) **single-consumer EventMultiplexer** (`single-consumer`, core) — a second concurrent `subscribe()` throws `EventMultiplexerError` `ERR_PRISM_EVENT_MULTIPLEXER_SINGLE_CONSUMER` instead of silently sharing one queue and losing events; slot frees on completion/return-at-yield/close; in-repo consumers (workflow bus, supervisor) already single-subscriber. (4) **restart-stable NATS durable identity + bounded non-durable active-run registries** (`nats-durable`, `@arnilo/prism-session-store-nats`; `active-runs`, `@arnilo/prism-workflows`) — the durable consumer name is exactly `prism_<hmac16 of tenantId|sessionId|runId>` (random suffix removed) so a crash-resumed subscribe continues from the last ack; clean stops delete the consumer (cursor resume), orphaned 0.2.1 `prism_<digest>_<random>` consumers are reclaimed by the existing cleanup; the workflow active-run registry sweeps aborted/leaked entries on register and fails closed at the 512 cap (`ERR_PRISM_WORKFLOW_RUN_REGISTRY_OVERFLOW`), documented non-durable. New regression surface: `scripts/phase22-security.test.mjs` (5 tests: 4 blockers + gate accounting, built public entrypoints, wired into `security:threat-suites`), the packed plain-JS `security22.mjs` consumer in install-smoke, the `@arnilo/prism/testing/state-concurrency-conformance` harness (7 probes — approval, cursor, checkpoint CAS, idempotency, router reservation, conversation metadata, unknown-outcome — memory leg in npm test, durable legs in `test:postgres`/NATS seam, zero timing-only sleeps), and the `scripts/phase22-conformance.test.mjs` gate in the `test:postgres` chain; phase-22 evidence in `scripts/phase22-baseline.json` + `scripts/phase22-freeze-manifest.json`. Release graph stays **50** publishable manifests at exact **0.2.2**; zero new runtime dependency names (core remains dependency-free). Store compatibility with 0.2.1: **forward-only migrations** (`prism_sessions.version` migration 008, `prism_model_router_budgets.reservations` enterprise migration 003; 0.2.1 databases migrate in place, 0.2.1 binaries read 0.2.2 databases but ignore the new columns — see `docs/migration.md` rollback-risk). Exit gate green (core + script gates incl. phase21-freeze + phase22 conformance, `sdk:ready`, audit 0 moderate, pack dry-run 50/50 twice byte-identical, plain reviewed compat gate at 0.2.2, protected OIDC/OPA + durable state-concurrency evidence, evidence in `scripts/phase22-baseline.json`). **Publication remains the operator handoff** (`docs/release-and-install.md` `0.2.2 publish handoff` — signed `v0.2.2` tag + npm OIDC).
+
 ## [0.2.1] - 2026-08-13
 
 ### Changed

package/dist/contracts-core.d.ts

@@ -823,6 +823,27 @@ export interface SessionBranchHandle {
 }
 /** Stable error code carried by `SessionAppendConflictError`. */
 export declare const SESSION_APPEND_CONFLICT_CODE: "session_append_conflict";
+/** CAS conflict code for `appendSession` metadata writes. Stable and message-independent. */
+export declare const SESSION_METADATA_CONFLICT_CODE: "metadata_conflict";
+/** Conflict details carried by `SessionMetadataConflictError`. Versions only; never metadata content. */
+export interface SessionMetadataConflict {
+    readonly code: typeof SESSION_METADATA_CONFLICT_CODE;
+    readonly id: string;
+    readonly expectedVersion: number;
+    readonly currentVersion: number;
+}
+/**
+ * Thrown when `appendSession` is called with an `expectedVersion` CAS guard and the
+ * stored session's version no longer matches (concurrent create/branch/archive, or a
+ * delete raced the write). Recognize via the stable `code` or `isSessionMetadataConflict`.
+ */
+export declare class SessionMetadataConflictError extends Error {
+    readonly conflict: SessionMetadataConflict;
+    readonly code: "metadata_conflict";
+    constructor(conflict: SessionMetadataConflict);
+}
+/** Type guard keyed off the stable `code` (works across bundles; not message text). */
+export declare function isSessionMetadataConflict(error: unknown): error is SessionMetadataConflictError;
 /** Conflict details carried by `SessionAppendConflictError`. Carries no secrets. */
 export interface SessionAppendConflict {
     readonly code: typeof SESSION_APPEND_CONFLICT_CODE;
@@ -954,6 +975,8 @@ export interface SessionRecord extends OwnershipScope {
     readonly expiresAt?: string;
     readonly retentionPolicyId?: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
+    /** Write version for optimistic metadata CAS; undefined on legacy/never-written rows. */
+    readonly version?: number;
 }
 /** Stored branch handle / leaf pointer. The leaf is the current entry id for the branch. */
 export interface BranchRecord {
@@ -1182,8 +1205,15 @@ export interface ProductionPersistenceStore {
     queryRetentionPolicies(query: RetentionPolicyQuery): Promise<PersistencePage<RetentionPolicy>>;
     queryMigrations(query: MigrationQuery): Promise<PersistencePage<MigrationRecord>>;
     /** Optional session-record write capability (conversation threads, host-managed sessions).
-     *  Upserts by id; ownership columns are set on create, `metadata`/`updatedAt` on update. */
-    appendSession?(record: SessionRecord): Promise<void>;
+     *  Upserts by id; ownership columns are set on create, `metadata`/`updatedAt` on update.
+     *  Additive CAS: pass `expectedVersion` to require the stored version to match before the
+     *  write (0 = create-only, a positive number = exact current version); omit it for legacy
+     *  last-write-wins. Returns the new `version` when the underlying store supports it. */
+    appendSession?(record: SessionRecord & {
+        readonly expectedVersion?: number;
+    }): Promise<{
+        readonly version: number;
+    } | void>;
     /** DB-friendly branch read (mirrors `SessionStore.readBranchPath`): one ancestor-chain
      *  query instead of `queryEntries({ sessionId })` + in-memory walk. Optional. */
     readBranchPath?(query: SessionBranchRead): Promise<PersistencePage<SessionEntry>>;

package/dist/contracts-core.js

@@ -84,6 +84,26 @@ export function isSessionSearchUnsupported(error) {
 }
 /** Stable error code carried by `SessionAppendConflictError`. */
 export const SESSION_APPEND_CONFLICT_CODE = "session_append_conflict";
+/** CAS conflict code for `appendSession` metadata writes. Stable and message-independent. */
+export const SESSION_METADATA_CONFLICT_CODE = "metadata_conflict";
+/**
+ * Thrown when `appendSession` is called with an `expectedVersion` CAS guard and the
+ * stored session's version no longer matches (concurrent create/branch/archive, or a
+ * delete raced the write). Recognize via the stable `code` or `isSessionMetadataConflict`.
+ */
+export class SessionMetadataConflictError extends Error {
+    conflict;
+    code = SESSION_METADATA_CONFLICT_CODE;
+    constructor(conflict) {
+        super(`session metadata conflict: expected version ${conflict.expectedVersion}, current ${conflict.currentVersion}`);
+        this.conflict = conflict;
+        this.name = "SessionMetadataConflictError";
+    }
+}
+/** Type guard keyed off the stable `code` (works across bundles; not message text). */
+export function isSessionMetadataConflict(error) {
+    return error instanceof Error && error.code === SESSION_METADATA_CONFLICT_CODE;
+}
 /**
  * Thrown when `SessionStore.append` rejects an entry under `SessionAppendOptions`
  * (dangling/stale `expectedParentId`, stricter adapter CAS failure, or duplicate

package/dist/conversations.d.ts

@@ -21,6 +21,8 @@ export interface ConversationThread extends OwnershipScope {
     readonly updatedAt: string;
     /** Branch leaves recorded by the conversation service; the entry tree remains the content source of truth. */
     readonly branches: readonly ConversationBranchRef[];
+    /** CAS write version (stored `SessionRecord.version`); undefined on legacy rows. */
+    readonly version?: number;
     /** Host-supplied create metadata; never credentials or raw transcripts. */
     readonly metadata?: Readonly<Record<string, unknown>>;
 }

package/dist/conversations.js

@@ -80,6 +80,7 @@ export function conversationThreadFromRecord(record) {
         createdAt: record.createdAt,
         updatedAt: record.updatedAt,
         branches: Object.freeze(branches),
+        version: record.version ?? 0,
         ...(metadata === undefined ? {} : { metadata }),
     };
 }

package/dist/event-multiplexer.d.ts

@@ -1,4 +1,10 @@
 export type EventOverflowPolicy = "close" | "drop_oldest" | "drop_newest";
+export declare const EVENT_MULTIPLEXER_SINGLE_CONSUMER_CODE = "ERR_PRISM_EVENT_MULTIPLEXER_SINGLE_CONSUMER";
+/** Thrown when a second consumer subscribes while one is active (single-consumer contract). */
+export declare class EventMultiplexerError extends Error {
+    readonly code = "ERR_PRISM_EVENT_MULTIPLEXER_SINGLE_CONSUMER";
+    constructor(message?: string);
+}
 export interface EventOverflowInfo {
     readonly droppedEvents: number;
     readonly maxQueuedEvents: number;
@@ -14,6 +20,13 @@ export interface EventMultiplexerOptions<T> {
 export interface EventMultiplexer<T> {
     publish(event: T): void;
     observe<S>(source: AsyncIterable<S>, map: (event: S) => T): () => void;
+    /**
+     * Single-consumer subscription. A second concurrent subscriber is rejected with
+     * `EventMultiplexerError` (ERR_PRISM_EVENT_MULTIPLEXER_SINGLE_CONSUMER); the slot
+     * frees when the active consumer's iterator completes or is `return()`ed at a
+     * yield, or when the multiplexer closes. A consumer parked awaiting an event is
+     * released by the next `publish`/`close` — `return()` while parked waits for it.
+     */
     subscribe(): AsyncIterable<T>;
     close(): void;
     readonly droppedEvents: number;

package/dist/event-multiplexer.js

@@ -1,3 +1,12 @@
+export const EVENT_MULTIPLEXER_SINGLE_CONSUMER_CODE = "ERR_PRISM_EVENT_MULTIPLEXER_SINGLE_CONSUMER";
+/** Thrown when a second consumer subscribes while one is active (single-consumer contract). */
+export class EventMultiplexerError extends Error {
+    code = EVENT_MULTIPLEXER_SINGLE_CONSUMER_CODE;
+    constructor(message = "Event multiplexer already has an active subscriber") {
+        super(message);
+        this.name = "EventMultiplexerError";
+    }
+}
 /** Bounded single-consumer fan-in for arbitrary async event sources. */
 export function createEventMultiplexer(options = {}) {
     const maxQueuedEvents = Math.max(1, options.maxQueuedEvents ?? 1024);
@@ -8,6 +17,9 @@ export function createEventMultiplexer(options = {}) {
     let isClosed = false;
     let droppedEvents = 0;
     let overflowNotified = false;
+    // Single-consumer contract: the parked-waiter design corrupts the queue when two
+    // consumers iterate concurrently, so a second active consumer is rejected instead.
+    let activeConsumer = false;
     const abort = () => close();
     if (options.signal?.aborted)
         isClosed = true;
@@ -108,6 +120,9 @@ export function createEventMultiplexer(options = {}) {
         options.signal?.removeEventListener("abort", abort);
         finishSources();
         queue.length = 0;
+        // Free the single-consumer slot: a consumer suspended at a yield may never pull
+        // again, and after close a fresh subscriber terminates immediately anyway.
+        activeConsumer = false;
         if (waiter) {
             const resolve = waiter;
             waiter = undefined;
@@ -115,23 +130,31 @@ export function createEventMultiplexer(options = {}) {
         }
     }
     async function* subscribe() {
-        while (true) {
-            if (queue.length > 0) {
-                if (options.compare)
-                    queue.sort(options.compare);
-                yield queue.shift();
-                continue;
+        if (activeConsumer)
+            throw new EventMultiplexerError();
+        activeConsumer = true;
+        try {
+            while (true) {
+                if (queue.length > 0) {
+                    if (options.compare)
+                        queue.sort(options.compare);
+                    yield queue.shift();
+                    continue;
+                }
+                if (isClosed)
+                    return;
+                const next = await new Promise((resolve) => {
+                    waiter = resolve;
+                });
+                if (next.done)
+                    return;
+                if (next.value === WAKE)
+                    continue;
+                yield next.value;
             }
-            if (isClosed)
-                return;
-            const next = await new Promise((resolve) => {
-                waiter = resolve;
-            });
-            if (next.done)
-                return;
-            if (next.value === WAKE)
-                continue;
-            yield next.value;
+        }
+        finally {
+            activeConsumer = false;
         }
     }
     return {

package/dist/index.d.ts

@@ -27,7 +27,7 @@ export type { ContextBudget, ContextBudgetMessageGroups, ContextBudgetOmission,
 export { applyContextBudget, CONTEXT_BUDGET_ERROR_CODE, CONTEXT_BUDGET_REPORT_METADATA_KEY, ContextBudgetError, DEFAULT_MAX_CONTEXT_BUDGET_OMISSIONS, estimateAssemblyTokens, estimateMessageBytes, estimateMessageTokens, estimateTextBytes, estimateTextTokens, getContextBudgetReport, HARD_MAX_CONTEXT_BUDGET_BYTES, HARD_MAX_CONTEXT_BUDGET_OMISSIONS, HARD_MAX_CONTEXT_BUDGET_TOKENS, isContextBudgetError, resolveContextBudget, } from "./context-budget.js";
 export type * from "./contracts.js";
 export type { ApprovalOutcome, DecisionScope, NestedRunApproval, NestedRunOutcome, NestedRunRef, PendingDecision, PendingDecisionKind, ProviderResolver, RealtimeCaps, RealtimeEvent, RealtimeSession, RealtimeSessionFactory, RealtimeSessionOptions, ResumeNestedRun, RunDecision, RunLimitCounters, RunLimitName, SecureAgentOptions, StickyDecision, ToolCallAuthority, ToolEffectClassifier, ToolEffectDeclaration, ToolEffectIdempotency, ToolEffectKey, ToolEffectKind, ToolEffectRecord, ToolEffectStatus, ToolEffectStore, ToolEffectTransition, ToolElicitationRequest, } from "./contracts.js";
-export { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, AgentRunError, AgentRunStateError, assertSessionMetadataKey, DEFAULT_MAX_PENDING_DECISIONS, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_MAX_STICKY_DECISIONS, DEFAULT_SESSION_SEARCH_LIMIT, HARD_MAX_ACTION_CONSTRAINT_BYTES, HARD_MAX_ACTION_CONSTRAINTS, HARD_MAX_DECISION_REASON_BYTES, HARD_MAX_ELICITATION_BYTES, HARD_MAX_PENDING_DECISIONS, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, HARD_MAX_STICKY_DECISIONS, isSessionAppendConflict, isSessionEntryKind, isSessionSearchUnsupported, MAX_ACTION_CONSTRAINT_BYTES, MAX_ACTION_CONSTRAINTS, MAX_ATTRIBUTION_DEPTH, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionSearchUnsupportedError, } from "./contracts.js";
+export { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, AgentRunError, AgentRunStateError, assertSessionMetadataKey, DEFAULT_MAX_PENDING_DECISIONS, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_MAX_STICKY_DECISIONS, DEFAULT_SESSION_SEARCH_LIMIT, HARD_MAX_ACTION_CONSTRAINT_BYTES, HARD_MAX_ACTION_CONSTRAINTS, HARD_MAX_DECISION_REASON_BYTES, HARD_MAX_ELICITATION_BYTES, HARD_MAX_PENDING_DECISIONS, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, HARD_MAX_STICKY_DECISIONS, isSessionAppendConflict, isSessionEntryKind, isSessionMetadataConflict, isSessionSearchUnsupported, MAX_ACTION_CONSTRAINT_BYTES, MAX_ACTION_CONSTRAINTS, MAX_ATTRIBUTION_DEPTH, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_METADATA_CONFLICT_CODE, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionMetadataConflictError, SessionSearchUnsupportedError, } from "./contracts.js";
 export { parseAgentFile, parseSkillFile } from "./contribution-parsing.js";
 export type { ContributionRegistries, ContributionRegistriesOptions, ContributionRegistry, ContributionRegistryOptions, } from "./contributions.js";
 export { createContributionRegistries, createContributionRegistry, registerDiscoveredContributions } from "./contributions.js";
@@ -38,7 +38,7 @@ export { createChainedCredentialResolver, createEnvCredentialResolver, createExp
 export type { DeviceAdapter, DeviceAdmitRequest, DeviceChunkResult, DeviceConformanceResult, DeviceKind, DevicePolicyErrorCode, DevicePolicyOptions, DeviceStreamLimits, ResolvedDevicePolicy, } from "./devices.js";
 export { acceptDeviceChunk, assertDeviceAdmit, DEFAULT_DEVICE_MAX_CHUNK_BYTES, DEFAULT_DEVICE_MAX_CONCURRENT_SESSIONS, DevicePolicyError, HARD_DEVICE_MAX_CHUNK_BYTES, HARD_DEVICE_MAX_CONCURRENT_SESSIONS, redactDeviceTelemetry, resolveDevicePolicy, runDevicePolicyConformance, } from "./devices.js";
 export type { EventMultiplexer, EventMultiplexerOptions, EventOverflowInfo, EventOverflowPolicy } from "./event-multiplexer.js";
-export { createEventMultiplexer } from "./event-multiplexer.js";
+export { createEventMultiplexer, EVENT_MULTIPLEXER_SINGLE_CONSUMER_CODE, EventMultiplexerError } from "./event-multiplexer.js";
 export type { ExecutionAction, ExecutionDecision, ExecutionPolicy, ExecutionRisk } from "./execution-policy.js";
 export { applyExecutionDecision, assertExecutionAllowed, checkExecution, ExecutionDeniedError } from "./execution-policy.js";
 export type { ExtensionErrorPolicy, ExtensionEventBus, ExtensionEventHandler, ExtensionKernel, ExtensionKernelOptions, ExtensionLoadPolicy, LoadedExtension, } from "./extensions.js";
@@ -109,5 +109,5 @@ export { createToolParameterValidator, createToolRegistry, dispatchToolCall, fil
 export type { ResolvedUseCaseModel, ResolveUseCaseModelInput, UseCaseModelBinding, } from "./use-case-model.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export declare const name = "prism";
-export declare const version = "0.2.1";
+export declare const version = "0.2.2";
 export declare const description = "Agent harness for AI providers, agents, sessions, and tools.";

package/dist/index.js

@@ -14,13 +14,13 @@ export { createDefaultCompactionStrategy, isCompactionEntryData } from "./compac
 export { assertJsonObject, isJsonObject, loadConfigLayers, mergeConfigLayers } from "./config.js";
 export { assertDeclaredMediaTypeMatches, assertMediaBlocksWithinBounds, assertMessagesSupportModelCapabilities, assertModelSupportsContentBlocks, assertSsrfAllowedUrl, collectMessageContentBlocks, contentBlockInputModality, DEFAULT_MAX_AUDIO_DURATION_MS, DEFAULT_MAX_MEDIA_ITEM_BYTES, DEFAULT_MAX_MEDIA_ITEMS_PER_REQUEST, DEFAULT_MAX_MEDIA_REQUEST_BYTES, DEFAULT_MEDIA_FETCH_TIMEOUT_MS, loadBoundedBinaryResource, MediaContentError, MODEL_INPUT_CAPABILITIES, resolveMediaContentBlock, resolveMediaContentBlocks, sniffMediaMimeType, UnsupportedModalityError, } from "./content.js";
 export { applyContextBudget, CONTEXT_BUDGET_ERROR_CODE, CONTEXT_BUDGET_REPORT_METADATA_KEY, ContextBudgetError, DEFAULT_MAX_CONTEXT_BUDGET_OMISSIONS, estimateAssemblyTokens, estimateMessageBytes, estimateMessageTokens, estimateTextBytes, estimateTextTokens, getContextBudgetReport, HARD_MAX_CONTEXT_BUDGET_BYTES, HARD_MAX_CONTEXT_BUDGET_OMISSIONS, HARD_MAX_CONTEXT_BUDGET_TOKENS, isContextBudgetError, resolveContextBudget, } from "./context-budget.js";
-export { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, AgentRunError, AgentRunStateError, assertSessionMetadataKey, DEFAULT_MAX_PENDING_DECISIONS, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_MAX_STICKY_DECISIONS, DEFAULT_SESSION_SEARCH_LIMIT, HARD_MAX_ACTION_CONSTRAINT_BYTES, HARD_MAX_ACTION_CONSTRAINTS, HARD_MAX_DECISION_REASON_BYTES, HARD_MAX_ELICITATION_BYTES, HARD_MAX_PENDING_DECISIONS, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, HARD_MAX_STICKY_DECISIONS, isSessionAppendConflict, isSessionEntryKind, isSessionSearchUnsupported, MAX_ACTION_CONSTRAINT_BYTES, MAX_ACTION_CONSTRAINTS, MAX_ATTRIBUTION_DEPTH, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionSearchUnsupportedError, } from "./contracts.js";
+export { AgentDecisionError, AgentDelegationSuspendedError, AgentLoopStateError, AgentRunError, AgentRunStateError, assertSessionMetadataKey, DEFAULT_MAX_PENDING_DECISIONS, DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_MAX_SESSION_SEARCH_CURSOR_BYTES, DEFAULT_MAX_SESSION_SEARCH_FTS_CANDIDATES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_QUERY_BYTES, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, DEFAULT_MAX_STICKY_DECISIONS, DEFAULT_SESSION_SEARCH_LIMIT, HARD_MAX_ACTION_CONSTRAINT_BYTES, HARD_MAX_ACTION_CONSTRAINTS, HARD_MAX_DECISION_REASON_BYTES, HARD_MAX_ELICITATION_BYTES, HARD_MAX_PENDING_DECISIONS, HARD_MAX_PENDING_STEER_BYTES, HARD_MAX_PENDING_STEERS, HARD_MAX_SESSION_SEARCH_CURSOR_BYTES, HARD_MAX_SESSION_SEARCH_FTS_CANDIDATES, HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_LINEAR_BYTES, HARD_MAX_SESSION_SEARCH_LINEAR_ENTRIES, HARD_MAX_SESSION_SEARCH_LINEAR_SESSIONS, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, HARD_MAX_SESSION_SEARCH_SNIPPET_BYTES, HARD_MAX_STICKY_DECISIONS, isSessionAppendConflict, isSessionEntryKind, isSessionMetadataConflict, isSessionSearchUnsupported, MAX_ACTION_CONSTRAINT_BYTES, MAX_ACTION_CONSTRAINTS, MAX_ATTRIBUTION_DEPTH, MAX_DECISION_REASON_BYTES, MAX_ELICITATION_BYTES, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_ENTRY_KINDS, SESSION_ENTRY_SCHEMA_VERSION, SESSION_METADATA_CONFLICT_CODE, SESSION_SEARCH_UNSUPPORTED_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionMetadataConflictError, SessionSearchUnsupportedError, } from "./contracts.js";
 export { parseAgentFile, parseSkillFile } from "./contribution-parsing.js";
 export { createContributionRegistries, createContributionRegistry, registerDiscoveredContributions } from "./contributions.js";
 export { CONVERSATION_METADATA_KEY, ConversationError, conversationMarkerMetadata, conversationThreadFromRecord, DEFAULT_MAX_CONVERSATION_CURSOR_BYTES, decodeConversationReplayCursor, encodeConversationReplayCursor, HARD_MAX_CONVERSATION_CURSOR_BYTES, } from "./conversations.js";
 export { createChainedCredentialResolver, createEnvCredentialResolver, createExplicitCredentialResolver, createMemoryCredentialStore, refreshOAuthCredential, resolveCredentialValue, revokeOAuthCredential, } from "./credentials.js";
 export { acceptDeviceChunk, assertDeviceAdmit, DEFAULT_DEVICE_MAX_CHUNK_BYTES, DEFAULT_DEVICE_MAX_CONCURRENT_SESSIONS, DevicePolicyError, HARD_DEVICE_MAX_CHUNK_BYTES, HARD_DEVICE_MAX_CONCURRENT_SESSIONS, redactDeviceTelemetry, resolveDevicePolicy, runDevicePolicyConformance, } from "./devices.js";
-export { createEventMultiplexer } from "./event-multiplexer.js";
+export { createEventMultiplexer, EVENT_MULTIPLEXER_SINGLE_CONSUMER_CODE, EventMultiplexerError } from "./event-multiplexer.js";
 export { applyExecutionDecision, assertExecutionAllowed, checkExecution, ExecutionDeniedError } from "./execution-policy.js";
 export { createExtensionEventBus, createExtensionKernel } from "./extensions.js";
 export { createMemoryRunFeedbackStore, prepareRunFeedback, RunFeedbackError, requireRunFeedbackOwnership, runFeedbackPageLimit, } from "./feedback.js";
@@ -60,6 +60,6 @@ export { DEFAULT_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES, DEFAULT_TOOL_RESULT_FOLD_MI
 export { createToolParameterValidator, createToolRegistry, dispatchToolCall, filterTools } from "./tools.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export const name = "prism";
-export const version = "0.2.1";
+export const version = "0.2.2";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map

package/dist/testing/persistence-schema.d.ts

@@ -1,6 +1,6 @@
 import type { PersistencePage, SessionEntry, SessionEntryQuery } from "../contracts.js";
 /** Current shared persistence schema version for production database adapters. */
-export declare const PERSISTENCE_SCHEMA_VERSION = 7;
+export declare const PERSISTENCE_SCHEMA_VERSION = 8;
 export type PersistenceTableName = "prism_tenants" | "prism_accounts" | "prism_users" | "prism_agent_definitions" | "prism_sessions" | "prism_branches" | "prism_session_entries" | "prism_session_append_idempotency" | "prism_runs" | "prism_agent_events" | "prism_agent_event_streams" | "prism_tool_calls" | "prism_usage" | "prism_run_feedback" | "prism_retention_policies" | "prism_legal_holds" | "prism_tenant_quotas" | "prism_migrations";
 export type PersistenceColumnType = "text" | "integer" | "number" | "boolean" | "json" | "timestamp";
 export interface PersistenceColumnDefinition {

package/dist/testing/persistence-schema.js

@@ -4,7 +4,7 @@ import { createHash } from "node:crypto";
 // this module defines the shared table/index/pagination/migration expectations
 // adapter authors implement and test against before shipping dialect-specific DDL.
 /** Current shared persistence schema version for production database adapters. */
-export const PERSISTENCE_SCHEMA_VERSION = 7;
+export const PERSISTENCE_SCHEMA_VERSION = 8;
 /** Guidance adapters must follow: values are bound parameters, never interpolated. */
 export const PARAMETERIZED_QUERY_GUIDANCE = "Bind every user-supplied value (session ids, idempotency keys, tenant ids, timestamps, JSON payloads) as a query parameter. Quote/validate schema and table identifiers only; never interpolate untrusted strings into SQL text.";
 const TENANT_COLUMNS = [
@@ -81,6 +81,7 @@ export function createPersistenceSchemaModel() {
                     { name: "expires_at", type: "timestamp", nullable: true },
                     { name: "retention_policy_id", type: "text", nullable: true },
                     { name: "metadata", type: "json", nullable: true },
+                    { name: "version", type: "integer", defaultValue: "0" },
                 ],
             },
             {
@@ -499,33 +500,35 @@ function migrationStep(version, name, description) {
         }
         : version === 7
             ? { indexes: ["prism_agent_events_owner_timestamp_sequence_idx"] }
-            : version === 6
-                ? {
-                    tables: ["prism_agent_event_streams"],
-                    indexes: ["prism_agent_events_run_sequence_idx"],
-                }
-                : version === 2
-                    ? { table: "prism_usage", columns: ["scope", "turn", "attempt"], indexes: ["prism_usage_session_scope_recorded_idx"] }
-                    : version === 3
-                        ? {
-                            tables: ["prism_run_feedback"],
-                            indexes: model.indexes.filter((index) => index.name.startsWith("prism_run_feedback_")).map((index) => index.name),
-                        }
-                        : version === 4
-                            ? // Adapter-local FTS objects (SQLite FTS5 / Postgres tsvector) map to this canonical name.
-                                { search: ["prism_session_search"], indexes: ["prism_sessions_updated_id_idx"] }
-                            : version === 5
-                                ? {
-                                    tables: ["prism_legal_holds", "prism_tenant_quotas"],
-                                    indexes: [
-                                        "prism_legal_holds_owner_resource_idx",
-                                        "prism_legal_holds_created_id_idx",
-                                        "prism_tenant_quotas_owner_kind_idx",
-                                    ],
-                                }
-                                : (() => {
-                                    throw new Error(`Unknown migration version ${version}`);
-                                })();
+            : version === 8
+                ? { table: "prism_sessions", columns: ["version"] }
+                : version === 6
+                    ? {
+                        tables: ["prism_agent_event_streams"],
+                        indexes: ["prism_agent_events_run_sequence_idx"],
+                    }
+                    : version === 2
+                        ? { table: "prism_usage", columns: ["scope", "turn", "attempt"], indexes: ["prism_usage_session_scope_recorded_idx"] }
+                        : version === 3
+                            ? {
+                                tables: ["prism_run_feedback"],
+                                indexes: model.indexes.filter((index) => index.name.startsWith("prism_run_feedback_")).map((index) => index.name),
+                            }
+                            : version === 4
+                                ? // Adapter-local FTS objects (SQLite FTS5 / Postgres tsvector) map to this canonical name.
+                                    { search: ["prism_session_search"], indexes: ["prism_sessions_updated_id_idx"] }
+                                : version === 5
+                                    ? {
+                                        tables: ["prism_legal_holds", "prism_tenant_quotas"],
+                                        indexes: [
+                                            "prism_legal_holds_owner_resource_idx",
+                                            "prism_legal_holds_created_id_idx",
+                                            "prism_tenant_quotas_owner_kind_idx",
+                                        ],
+                                    }
+                                    : (() => {
+                                        throw new Error(`Unknown migration version ${version}`);
+                                    })();
     return {
         version,
         name,
@@ -546,6 +549,7 @@ export function createPersistenceMigrationContract() {
             migrationStep(5, "005_lifecycle_hold_quota", "Add legal-hold and tenant-quota tables for retention lifecycle."),
             migrationStep(6, "006_agent_event_source", "Add transactional per-run event counters and unique durable event sequencing."),
             migrationStep(7, "007_agent_event_retention_index", "Add an exact-owner durable-event retention cleanup index."),
+            migrationStep(8, "008_session_version", "Add a NOT NULL DEFAULT 0 version column to prism_sessions for appendSession metadata CAS."),
         ],
         lockGuidance: "Acquire a dialect-specific migration lock before applying steps (PostgreSQL advisory lock; SQLite exclusive transaction). Only one process should migrate at a time.",
         leastPrivilegeGuidance: "Run migrations with a DDL-capable role; use a separate least-privilege runtime role limited to INSERT/SELECT/UPDATE on adapter tables. Never grant migration credentials to the agent runtime.",

package/dist/testing/state-concurrency-conformance.d.ts

@@ -0,0 +1,145 @@
+import type { AgentEventSource, AgentIdentity, CheckpointStore, ProductionPersistenceStore } from "../contracts.js";
+/**
+ * Narrow router-state seam (structurally satisfied by
+ * `@arnilo/prism-model-router`'s `ModelRouterStateStore`). Core stays
+ * dependency-free; adapter packages pass their real stores.
+ */
+export interface StateConcurrencyRouterKey {
+    readonly tenantId: string;
+    readonly accountId?: string;
+    readonly userId?: string;
+    readonly principalId: string;
+    readonly provider: string;
+    readonly model: string;
+}
+export interface StateConcurrencyRouterStore {
+    reserveBudget(input: {
+        readonly key: StateConcurrencyRouterKey;
+        readonly tokens?: number;
+        readonly costUsd?: number;
+        readonly maxTokens?: number;
+        readonly maxCostUsd?: number;
+        readonly windowMs: number;
+        readonly reservationTtlMs: number;
+        readonly now: number;
+        readonly maxBudgetKeys?: number;
+    }): Promise<{
+        readonly admitted: boolean;
+        readonly reservationId?: string;
+        readonly fencingToken?: string;
+        readonly retryAfterMs?: number;
+    }>;
+    commitBudget(input: {
+        readonly key: StateConcurrencyRouterKey;
+        readonly reservationId: string;
+        readonly fencingToken: string;
+        readonly tokens?: number;
+        readonly costUsd?: number;
+        readonly windowMs: number;
+        readonly now: number;
+    }): Promise<{
+        readonly unknownUsage: boolean;
+    }>;
+    releaseBudget(input: {
+        readonly key: StateConcurrencyRouterKey;
+        readonly reservationId: string;
+        readonly fencingToken: string;
+        readonly windowMs: number;
+        readonly now: number;
+    }): Promise<void>;
+    readBudget(input: {
+        readonly key: StateConcurrencyRouterKey;
+        readonly windowMs: number;
+        readonly now: number;
+    }): Promise<{
+        readonly tokens: number;
+        readonly costUsd: number;
+    }>;
+}
+export interface StateConcurrencyRouterFactory {
+    readonly create: () => StateConcurrencyRouterStore | Promise<StateConcurrencyRouterStore>;
+    /**
+     * True when the store derives reservation expiry from the caller-supplied
+     * `now` (in-memory stores). Durable stores compute expiry from their own
+     * clock (`clock_timestamp()`), so the deterministic unknown-outcome probe
+     * only runs when this is set; the durable leg is exercised by the Task 1
+     * enterprise-conformance integration probe (real 1ms TTL, `test:postgres`).
+     */
+    readonly nowInjected?: boolean;
+}
+/** Narrow idempotency seam (structurally satisfied by `@arnilo/prism-work-tools`'s `IdempotencyStore`). */
+export interface StateConcurrencyIdempotencyStore {
+    get(input: StateConcurrencyIdempotencyKey): Promise<StateConcurrencyIdempotencyRecord | undefined>;
+    begin(input: StateConcurrencyIdempotencyKey): Promise<{
+        readonly outcome: "acquired" | "existing";
+        readonly record: StateConcurrencyIdempotencyRecord;
+    }>;
+    complete(input: StateConcurrencyIdempotencyKey & {
+        readonly claimToken: string;
+        readonly expectedVersion: number;
+        readonly result: {
+            readonly draftId: string;
+            readonly resourceId?: string;
+        };
+    }): Promise<StateConcurrencyIdempotencyRecord>;
+}
+export interface StateConcurrencyIdempotencyKey {
+    readonly identity: AgentIdentity;
+    readonly key: string;
+    readonly op: string;
+    readonly signal?: AbortSignal;
+}
+export interface StateConcurrencyIdempotencyRecord {
+    readonly tenantId?: string;
+    readonly accountId?: string;
+    readonly userId?: string;
+    readonly principalId: string;
+    readonly key: string;
+    readonly op: string;
+    readonly status: "in_progress" | "completed" | "failed_retryable" | "failed_terminal" | "unknown";
+    readonly attempt: number;
+    readonly version: number;
+    readonly claimToken?: string;
+    readonly result?: {
+        readonly draftId: string;
+        readonly resourceId?: string;
+    };
+    readonly failure?: {
+        readonly code: string;
+        readonly reference?: string;
+    };
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly expiresAt?: string;
+}
+export type StateConcurrencyEventSource = AgentEventSource & {
+    readonly close?: () => void | Promise<void>;
+};
+export interface StateConcurrencyEventSourceFactory {
+    readonly create: () => StateConcurrencyEventSource | Promise<StateConcurrencyEventSource>;
+    /**
+     * True when the factory can re-open against the same backend (durable
+     * stores). Memory stores are process-local; their probe covers cursor
+     * resume on the same instance and durable factories additionally re-open.
+     */
+    readonly reopenable?: boolean;
+}
+export interface StateConcurrencyFactories {
+    /** Checkpoint seam: approval-determinism and checkpoint-CAS probes. */
+    readonly checkpoints?: () => CheckpointStore | Promise<CheckpointStore>;
+    /** Durable event seam: replay-cursor resume probe (memory and NATS/Postgres). */
+    readonly events?: StateConcurrencyEventSourceFactory;
+    /** Session-record seam: conversation metadata CAS probe (appendSession). */
+    readonly sessions?: () => ProductionPersistenceStore | Promise<ProductionPersistenceStore>;
+    /** Work idempotency seam: retry-same-key probe. */
+    readonly idempotency?: () => StateConcurrencyIdempotencyStore | Promise<StateConcurrencyIdempotencyStore>;
+    /** Router budget reservation seam: oversubscription + unknown-outcome probes. */
+    readonly routerState?: StateConcurrencyRouterFactory;
+}
+/**
+ * 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 declare function assertStateConcurrencyConforms(factories: StateConcurrencyFactories): Promise<readonly string[]>;