@arnilo/prism 0.2.0 → 0.2.2

package/dist/pinned-fetch.d.ts

@@ -0,0 +1,25 @@
+import { type MediaHostAddress, type MediaHostnameResolver, type SsrfPolicy } from "./content.js";
+export interface PinnedFetchOptions {
+    /** Prefix for request-level error messages ("redirects are not allowed", "response exceeds", ...). Default "Request". */
+    readonly errorPrefix?: string;
+    /** Prefix for hostname-resolution error messages. Default: `errorPrefix`. */
+    readonly hostnameErrorPrefix?: string;
+    /** Custom resolver; defaults to `node:dns/promises` lookup (all answers, verbatim). */
+    readonly resolver?: MediaHostnameResolver;
+    /** Allow loopback destinations only when the requested hostname is itself loopback AND this is true. */
+    readonly allowLoopback?: boolean;
+    /** SSRF policy applied to the URL precheck and to every resolved candidate. */
+    readonly ssrf?: SsrfPolicy;
+    /** Byte ceiling for the response stream (content-length precheck + streaming bound). */
+    readonly maxResponseBytes?: number;
+}
+/** One DNS-pinned, redirect-free, byte-bounded fetch. See module comment. */
+export declare function pinnedFetch(url: URL, init: RequestInit | undefined, options?: PinnedFetchOptions): Promise<Response>;
+export declare function resolvePinnedAddress(url: URL, resolver: MediaHostnameResolver, signal: AbortSignal | null | undefined, allowLoopback: boolean, ssrf: SsrfPolicy | undefined, hostnameErrorPrefix?: string): Promise<MediaHostAddress>;
+export declare function defaultResolver(hostname: string): Promise<readonly MediaHostAddress[]>;
+export declare function requestPinned(url: URL, address: MediaHostAddress, init: RequestInit | undefined, errorPrefix?: string): Promise<Response>;
+export declare function boundResponse(response: Response, maxBytes: number, errorPrefix?: string): Response;
+export declare function raceAbort<T>(promise: Promise<T>, signal: AbortSignal | null | undefined): Promise<T>;
+export declare function normalizeHostname(value: string): string;
+export declare function isLoopbackHostname(value: string): boolean;
+export declare function isLoopbackAddress(value: string): boolean;

package/dist/pinned-fetch.js

@@ -0,0 +1,246 @@
+/**
+ * DNS-pinned outbound fetch primitive (0.2.1 task 4).
+ *
+ * One resolve per request, bounded to 1..32 addresses, family-verified, and
+ * every candidate checked against `assertSsrfAllowedUrl` BEFORE the connect —
+ * the connect itself uses a node lookup hook that returns exactly the pinned
+ * address, so the socket cannot re-resolve (DNS-rebinding defense). Redirects
+ * are rejected outright (3xx), and the response stream is byte-bounded.
+ *
+ * Throws `MediaContentError` (`ssrf_denied` for address violations, `redirect`
+ * for 3xx). Error messages are parameterized by `errorPrefix` so each caller
+ * (MCP, OIDC, OPA, content) keeps its own taxonomy and message text.
+ *
+ * NOTE: imports from ./content.js and is imported by it (content's default
+ * media fetch routes through here) — a deliberate ESM cycle; both modules only
+ * reference the other's exports inside function bodies, never at module scope.
+ */
+import { lookup as dnsLookup } from "node:dns/promises";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { isIP } from "node:net";
+import { assertSsrfAllowedUrl, MediaContentError } from "./content.js";
+/** One DNS-pinned, redirect-free, byte-bounded fetch. See module comment. */
+export async function pinnedFetch(url, init, options) {
+    const errorPrefix = options?.errorPrefix ?? "Request";
+    const hostnameErrorPrefix = options?.hostnameErrorPrefix ?? errorPrefix;
+    if (url.username || url.password)
+        throw new MediaContentError("ssrf_denied", `${errorPrefix} URL must not embed credentials`);
+    if (url.hash)
+        throw new MediaContentError("ssrf_denied", `${errorPrefix} URL must not contain a fragment`);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new MediaContentError("ssrf_denied", `${errorPrefix} URL must use https: (got ${url.protocol})`);
+    }
+    if (url.protocol === "http:" && !(options?.allowLoopback === true && isLoopbackHostname(url.hostname))) {
+        throw new MediaContentError("ssrf_denied", `Plaintext ${errorPrefix} is allowed only for an explicitly enabled loopback endpoint`);
+    }
+    if (!(options?.allowLoopback === true && isLoopbackHostname(url.hostname))) {
+        try {
+            assertSsrfAllowedUrl(url.href, options?.ssrf);
+        }
+        catch (error) {
+            if (error instanceof MediaContentError && error.code === "unsupported_url_scheme")
+                throw error;
+            throw new MediaContentError("ssrf_denied", `${errorPrefix} URL is not public`, { cause: error });
+        }
+    }
+    const signal = init?.signal;
+    const address = await resolvePinnedAddress(url, options?.resolver ?? defaultResolver, signal, options?.allowLoopback === true, options?.ssrf);
+    const response = await requestPinned(url, address, init, errorPrefix);
+    if (response.status >= 300 && response.status < 400) {
+        await response.body?.cancel();
+        throw new MediaContentError("redirect", `${errorPrefix} redirects are not allowed (status ${response.status})`);
+    }
+    return options?.maxResponseBytes === undefined ? response : boundResponse(response, options.maxResponseBytes, errorPrefix);
+}
+export async function resolvePinnedAddress(url, resolver, signal, allowLoopback, ssrf, hostnameErrorPrefix = "Request") {
+    signal?.throwIfAborted();
+    const hostname = normalizeHostname(url.hostname);
+    const family = isIP(hostname);
+    const addresses = family
+        ? [{ address: hostname, family: family }]
+        : await raceAbort(resolver(hostname, signal ?? new AbortController().signal), signal);
+    if (addresses.length < 1 || addresses.length > 32)
+        throw new MediaContentError("fetch_failed", `${hostnameErrorPrefix} hostname returned an invalid address count`);
+    for (const candidate of addresses) {
+        const normalized = normalizeHostname(candidate.address);
+        if (isIP(normalized) !== candidate.family)
+            throw new MediaContentError("fetch_failed", `${hostnameErrorPrefix} hostname resolver returned an invalid address`);
+        if (allowLoopback && isLoopbackHostname(hostname)) {
+            if (!isLoopbackAddress(normalized))
+                throw new MediaContentError("ssrf_denied", `${hostnameErrorPrefix} loopback hostname resolved outside loopback`);
+            continue;
+        }
+        const literal = candidate.family === 6 ? `[${normalized}]` : normalized;
+        // Fail closed on resolved candidates: an explicit hostname allow-list is honored
+        // for the URL itself, but every resolved address is still private-checked.
+        const candidatePolicy = ssrf?.allowedHostnames?.length ? { denyPrivateHosts: ssrf.denyPrivateHosts } : ssrf;
+        try {
+            assertSsrfAllowedUrl(`${url.protocol}//${literal}`, candidatePolicy);
+        }
+        catch (error) {
+            throw new MediaContentError("ssrf_denied", `${hostnameErrorPrefix} hostname resolved to a private or non-public address`, {
+                cause: error,
+            });
+        }
+    }
+    // ponytail: pin first validated address; add bounded public-address retry only if availability data requires it.
+    const selected = addresses[0];
+    return { address: normalizeHostname(selected.address), family: selected.family };
+}
+export async function defaultResolver(hostname) {
+    return dnsLookup(hostname, { all: true, verbatim: true });
+}
+export async function requestPinned(url, address, init, errorPrefix = "Request") {
+    const body = await requestBody(init?.body, errorPrefix);
+    const headers = new Headers(init?.headers);
+    const method = init?.method ?? "GET";
+    const request = url.protocol === "https:" ? httpsRequest : httpRequest;
+    return new Promise((resolve, reject) => {
+        const nodeRequest = request(url, {
+            method,
+            headers: Object.fromEntries(headers.entries()),
+            signal: init?.signal ?? undefined,
+            lookup: ((_hostname, options, callback) => {
+                if (options.all)
+                    callback(null, [{ address: address.address, family: address.family }]);
+                else
+                    callback(null, address.address, address.family);
+            }),
+        }, (incoming) => {
+            const responseHeaders = new Headers();
+            for (const [name, value] of Object.entries(incoming.headers)) {
+                if (Array.isArray(value))
+                    for (const item of value)
+                        responseHeaders.append(name, item);
+                else if (value !== undefined)
+                    responseHeaders.set(name, value);
+            }
+            const noBody = method === "HEAD" || incoming.statusCode === 204 || incoming.statusCode === 304;
+            const iterator = incoming[Symbol.asyncIterator]();
+            const stream = noBody
+                ? null
+                : new ReadableStream({
+                    async pull(controller) {
+                        try {
+                            const next = await iterator.next();
+                            if (next.done)
+                                controller.close();
+                            else
+                                controller.enqueue(new Uint8Array(next.value));
+                        }
+                        catch (error) {
+                            controller.error(error);
+                        }
+                    },
+                    cancel(reason) {
+                        incoming.destroy(reason instanceof Error ? reason : undefined);
+                    },
+                });
+            resolve(new Response(stream, {
+                status: incoming.statusCode ?? 500,
+                statusText: incoming.statusMessage,
+                headers: responseHeaders,
+            }));
+        });
+        nodeRequest.on("error", reject);
+        if (body)
+            nodeRequest.end(body);
+        else
+            nodeRequest.end();
+    });
+}
+async function requestBody(body, errorPrefix) {
+    if (body === undefined || body === null)
+        return undefined;
+    if (typeof body === "string")
+        return new TextEncoder().encode(body);
+    if (body instanceof URLSearchParams)
+        return new TextEncoder().encode(body.toString());
+    if (body instanceof ArrayBuffer)
+        return new Uint8Array(body);
+    if (ArrayBuffer.isView(body))
+        return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+    if (body instanceof Blob)
+        return new Uint8Array(await body.arrayBuffer());
+    throw new MediaContentError("ssrf_denied", `${errorPrefix} request body type is not supported by the pinned transport`);
+}
+export function boundResponse(response, maxBytes, errorPrefix = "Request") {
+    const declared = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > maxBytes) {
+        void response.body?.cancel();
+        throw new MediaContentError("ssrf_denied", `${errorPrefix} response exceeds ${maxBytes} bytes`);
+    }
+    if (!response.body)
+        return response;
+    const reader = response.body.getReader();
+    let bytes = 0;
+    const body = new ReadableStream({
+        async pull(controller) {
+            try {
+                const next = await reader.read();
+                if (next.done) {
+                    reader.releaseLock();
+                    controller.close();
+                    return;
+                }
+                bytes += next.value.byteLength;
+                if (bytes > maxBytes) {
+                    await reader.cancel();
+                    reader.releaseLock();
+                    controller.error(new MediaContentError("ssrf_denied", `${errorPrefix} response exceeds ${maxBytes} bytes`));
+                    return;
+                }
+                controller.enqueue(next.value);
+            }
+            catch (error) {
+                try {
+                    reader.releaseLock();
+                }
+                catch {
+                    /* Already released after EOF/overflow. */
+                }
+                controller.error(error);
+            }
+        },
+        async cancel(reason) {
+            await reader.cancel(reason);
+            try {
+                reader.releaseLock();
+            }
+            catch {
+                /* Already released after EOF/overflow. */
+            }
+        },
+    });
+    return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+}
+export async function raceAbort(promise, signal) {
+    if (!signal)
+        return promise;
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(signal.reason);
+        signal.addEventListener("abort", abort, { once: true });
+        promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+    });
+}
+export function normalizeHostname(value) {
+    return value
+        .toLowerCase()
+        .replace(/^\[|\]$/g, "")
+        .replace(/\.$/, "");
+}
+export function isLoopbackHostname(value) {
+    const hostname = normalizeHostname(value);
+    return hostname === "localhost" || hostname.endsWith(".localhost") || isLoopbackAddress(hostname);
+}
+export function isLoopbackAddress(value) {
+    const address = normalizeHostname(value);
+    if (address === "::1")
+        return true;
+    if (isIP(address) !== 4)
+        return false;
+    return Number(address.split(".", 1)[0]) === 127;
+}
+//# sourceMappingURL=pinned-fetch.js.map

package/dist/providers/openai-compatible.d.ts

@@ -21,7 +21,7 @@ export interface OpenAICompatibleProviderOptions {
     readonly extraHeaders?: (request: ProviderRequest) => Record<string, string>;
     /** Final body transform applied last (token limits, compat stripping). Wins over everything. */
     readonly transformBody?: (body: JsonObject, request: ProviderRequest) => JsonObject;
-    /** Require `[DONE]` and a `finish_reason` before emitting `done`; truncated streams yield an error. `done` then carries the final usage. */
+    /** Require `[DONE]` and a `finish_reason` before emitting `done`; truncated streams yield an error. `done` then carries the final usage. Default `true` (fail-closed); set `false` explicitly to accept streams that end without completion evidence. */
     readonly strictCompletion?: boolean;
     /** Emit the final stream usage on the `done` event (without strict completion checks). */
     readonly doneUsage?: boolean;
@@ -34,7 +34,7 @@ export interface OpenAICompatibleProviderOptions {
 }
 export interface OpenAIChatEventsOptions {
     readonly signal?: AbortSignal;
-    /** Require `[DONE]` and a `finish_reason`; `done` then carries the final usage. */
+    /** Require `[DONE]` and a `finish_reason`; `done` then carries the final usage. Default `true` (fail-closed); set `false` explicitly to accept streams that end without completion evidence. */
     readonly strictCompletion?: boolean;
     /** Emit the final stream usage on the `done` event. */
     readonly doneUsage?: boolean;

package/dist/providers/openai-compatible.js

@@ -72,7 +72,7 @@ export async function* openAIChatEvents(body, options = {}) {
         yield providerError(new ProviderTransportError("incomplete_delta", `Incomplete tool call delta at index ${incomplete[0]}`));
         return;
     }
-    if (options.strictCompletion && (!sawDoneMarker || !sawFinishReason)) {
+    if ((options.strictCompletion ?? true) && (!sawDoneMarker || !sawFinishReason)) {
         // Truncated streams must fail loudly — emitting done would mark partial output as succeeded.
         yield providerError(new Error(`Chat stream ended without completion evidence ` +
             `([DONE]: ${sawDoneMarker ? "received" : "missing"}, ` +
@@ -82,7 +82,7 @@ export async function* openAIChatEvents(body, options = {}) {
     for (const call of tools.values()) {
         yield providerToolCall(toolCallFromArgumentsText(call.id, call.name, call.argumentsText));
     }
-    yield providerDone(options.strictCompletion || options.doneUsage ? usage : undefined);
+    yield providerDone((options.strictCompletion ?? true) || options.doneUsage ? usage : undefined);
 }
 export function createOpenAICompatibleProvider(options) {
     const providerId = options.id ?? "openai-compatible";

package/dist/providers/transport.d.ts

@@ -14,7 +14,7 @@ export interface SseEvent {
     readonly data: string;
     readonly comments?: readonly string[];
 }
-export type ProviderTransportErrorCode = "sse_buffer_overflow" | "sse_event_overflow" | "response_body_overflow" | "aborted" | "invalid_json_arguments" | "incomplete_delta";
+export type ProviderTransportErrorCode = "sse_buffer_overflow" | "sse_event_overflow" | "response_body_overflow" | "aborted" | "invalid_json_arguments" | "incomplete_delta" | "response_body_shape";
 export declare class ProviderTransportError extends Error {
     readonly code: ProviderTransportErrorCode;
     readonly limitBytes?: number;
@@ -32,6 +32,15 @@ export interface ReadSseEventsOptions extends BoundedStreamLimits {
 export interface ReadBoundedResponseTextOptions extends BoundedStreamLimits {
     readonly secrets?: readonly (string | undefined)[];
 }
+export interface ReadBoundedResponseJsonOptions extends ReadBoundedResponseTextOptions {
+    /** Max JSON nesting depth. Default: 32. */
+    readonly maxDepth?: number;
+    /** Max object properties / array elements per container. Default: 4_096. */
+    readonly maxProperties?: number;
+    /** Caller-supplied shape gate; failure throws `response_body_shape`. */
+    readonly shape?: (value: unknown) => boolean;
+    readonly signal?: AbortSignal;
+}
 export interface ParseJsonObjectArgumentsOptions {
     readonly toolName?: string;
     readonly maxBytes?: number;
@@ -42,6 +51,10 @@ export declare function readSseEvents(body: ReadableStream<Uint8Array>, options?
 export declare function readSseData(body: ReadableStream<Uint8Array>, options?: ReadSseEventsOptions): AsyncGenerator<string>;
 /** Read a response body with a hard byte ceiling; redacts optional secrets. */
 export declare function readBoundedResponseText(response: Response, options?: ReadBoundedResponseTextOptions): Promise<string>;
+/** Read a success body with the same byte ceiling as {@link readBoundedResponseText}, then parse it as JSON
+ *  with depth/property caps and an optional caller-supplied shape gate. Malformed JSON, over-limit nesting,
+ *  or shape failure throw `ProviderTransportError` with code `response_body_shape`. */
+export declare function readBoundedResponseJson<T>(response: Response, options?: ReadBoundedResponseJsonOptions): Promise<T>;
 export type ParseJsonObjectArgumentsResult = {
     readonly ok: true;
     readonly value: JsonObject;

package/dist/providers/transport.js

@@ -218,6 +218,49 @@ export async function readBoundedResponseText(response, options) {
         }
     }
 }
+function assertJsonBounds(value, maxDepth, maxProperties, depth = 0) {
+    if (depth > maxDepth) {
+        throw new ProviderTransportError("response_body_shape", `JSON nesting exceeded ${maxDepth} levels`);
+    }
+    if (value === null || typeof value !== "object")
+        return;
+    if (Array.isArray(value)) {
+        if (value.length > maxProperties) {
+            throw new ProviderTransportError("response_body_shape", `JSON array exceeded ${maxProperties} elements`);
+        }
+        for (const entry of value)
+            assertJsonBounds(entry, maxDepth, maxProperties, depth + 1);
+        return;
+    }
+    const keys = Object.keys(value);
+    if (keys.length > maxProperties) {
+        throw new ProviderTransportError("response_body_shape", `JSON object exceeded ${maxProperties} properties`);
+    }
+    for (const key of keys)
+        assertJsonBounds(value[key], maxDepth, maxProperties, depth + 1);
+}
+/** Read a success body with the same byte ceiling as {@link readBoundedResponseText}, then parse it as JSON
+ *  with depth/property caps and an optional caller-supplied shape gate. Malformed JSON, over-limit nesting,
+ *  or shape failure throw `ProviderTransportError` with code `response_body_shape`. */
+export async function readBoundedResponseJson(response, options) {
+    throwIfAborted(options?.signal);
+    const text = await readBoundedResponseText(response, options);
+    throwIfAborted(options?.signal);
+    const maxDepth = options?.maxDepth ?? 32;
+    const maxProperties = options?.maxProperties ?? 4_096;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new ProviderTransportError("response_body_shape", "Response body is not valid JSON");
+    }
+    assertJsonBounds(parsed, maxDepth, maxProperties);
+    if (options?.shape && !options.shape(parsed)) {
+        throw new ProviderTransportError("response_body_shape", "Response body does not match the expected shape");
+    }
+    return parsed;
+}
 /** Parse streamed tool arguments without throwing; prefer this for recoverable tool-call recovery. */
 export function tryParseJsonObjectArguments(text, options) {
     const maxBytes = options?.maxBytes ?? DEFAULT_MAX_ARGUMENT_BYTES;

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[]>;