@arnilo/prism 0.0.5 → 0.0.6

package/CHANGELOG.md

@@ -5,7 +5,34 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.0.6] - 2026-07-19
+
+### Added
+
+- Caller-gated model discovery: `listOpenAIModels`, `listKimiModels`, `listZaiModels`, `listOpenRouterModels`, and `listOpenCodeGoModels`. Provider setup remains network-free; hosts explicitly fetch and register current models.
+- Shared `ThinkingLevel` helpers and use-case model bindings. Background compaction and observational-memory jobs can use an explicit provider/model or a supplied session-model fallback.
+- Opt-in sequential artifact-loop tools: `loop: { strategy: "generate-validate-revise", toolCalls: "bounded" }`. Tool rounds use existing authorization/redaction/ledger paths, share `maxToolRounds` across candidates, and fail with `artifact_failed` metadata `{ reason: "tool_round_limit" }` after exhaustion.
+- Checksummed SQLite/PostgreSQL migration histories and catalog-shape verification, bounded JSON Schema compilation LRU, and public `assertFiniteVector` validation.
+
+### Changed
+
+- Provider packages now document and implement current cache, reasoning, streaming, and discovery behavior. OpenAI Responses replay/function-call/SSE argument handling is corrected; Kimi adds optional Moonshot support; Z.AI and OpenCode Go catalogs/routes were refreshed; OpenRouter discovery/reasoning and NeuralWatt thinking controls are hardened. AI SDK remains host-model-owned.
+- Workflow definitions now require a non-empty `revision`; cancellation requires exact ownership and the current workflow definition. All workflow limits have finite hard caps.
+- Coding tools now enforce bounded streamed reads, write/edit inputs, shell wall time, total output, and spill-file lifecycle. Custom coding operation interfaces now receive bounded read/stat/write/edit options and abort signals.
+- Encrypted credential helpers `encryptBytes`, `decryptBytes`, and envelope rotation are asynchronous. Existing credential files must meet restrictive Unix permission requirements. Linux Secret Service/GNOME Keyring byte-array reads are accepted by the keychain store.
+- MCP Streamable HTTP requires HTTPS and explicit `allowedOrigins`; loopback HTTP requires explicit opt-in. Discovery, schemas, results, and response bodies are bounded.
+- Compaction and observational-memory workers now have finite turn/call/transcript/error budgets. A2A streaming uses strict incremental UTF-8 and LF/CRLF SSE parsing.
+- Generated Prism, workflow, and evaluation IDs use cryptographic UUIDs; non-finite embedding vectors now fail before scoring or persistence.
+
+### Security
+
+- Fixed cross-owner workflow cancellation and duplicate active-run overwrite risks.
+- Added fail-closed limits and validation at file, process, credential, MCP, migration, schema, vector, provider-worker, and A2A trust boundaries.
+
+### Upgrade notes
+
+- Finish or deliberately migrate pre-0.0.6 workflow runs/checkpoints before upgrading: their definition hashes lack the required revision.
+- Update workflow definitions with `revision`, cancellation callers with `workflow` plus exact ownership, MCP HTTP configs with `allowedOrigins`, and custom coding/credential integrations for the changed interfaces above.
 
 ## [0.0.5] - 2026-07-16
 

package/dist/agent-loops.d.ts

@@ -6,6 +6,7 @@ export declare function generateValidateReviseLoop(opts: {
     readonly parser?: ArtifactParser<unknown>;
     readonly repairer?: ArtifactRepairer<unknown>;
     readonly maxRevisions?: number;
+    readonly toolCalls?: "disabled" | "bounded";
 }): AgentLoopStrategy;
 export declare function resolveToolConcurrency(options: {
     loop?: AgentLoopStrategy | AgentLoopOptions;

package/dist/agent-loops.js

@@ -1,4 +1,5 @@
 import { inputMessages } from "./input.js";
+import { createId } from "./ids.js";
 function throwIfAborted(signal) {
     if (signal.aborted)
         throw signal.reason instanceof Error ? signal.reason : new Error("Agent run aborted");
@@ -55,10 +56,8 @@ function defaultRepairer() {
     });
 }
 // ponytail: GenerateValidateReviseLoop reuses LoopContext primitives only —
-// no provider/retry/store/event re-implementation. T is host-defined, Prism
-// never instantiates it. No tools in artifact revisions (roadmap scope is
-// generate→validate→revise; tool coupling deferred). Phase 28 fires
-// artifact_* events at the marked seams (noop here).
+// no provider/retry/store/event re-implementation. Bounded artifact tools use
+// same dispatcher at concurrency one; add parallelism only with ordering need.
 export function generateValidateReviseLoop(opts) {
     const max = opts.maxRevisions ?? 3;
     const repairer = opts.repairer ?? defaultRepairer();
@@ -68,12 +67,14 @@ export function generateValidateReviseLoop(opts) {
             let usage;
             let nextInput = ctx.input;
             let pendingHistory = [];
-            for (let turn = 1; turn <= max + 1; turn += 1) {
+            let toolRounds = 0;
+            let attempts = 0;
+            for (let turn = 1; attempts <= max; turn += 1) {
                 throwIfAborted(ctx.signal);
                 ctx.emit({ type: "turn_started", sessionId: ctx.sessionId, runId: ctx.runId, turn });
                 const request = await ctx.assemble(nextInput, undefined, turn);
                 throwIfAborted(ctx.signal);
-                const { content, messageId, started, usage: turnUsage } = await ctx.generate(request);
+                const { content, calls, messageId, started, usage: turnUsage } = await ctx.generate(request);
                 usage = turnUsage ?? usage;
                 if (pendingHistory.length > 0) {
                     ctx.history.push(...pendingHistory);
@@ -88,10 +89,17 @@ export function generateValidateReviseLoop(opts) {
                     ctx.emit({ type: "message_finished", sessionId: ctx.sessionId, runId: ctx.runId, message });
                 }
                 ctx.emit({ type: "turn_finished", sessionId: ctx.sessionId, runId: ctx.runId, turn });
-                const text = content
-                    .filter((b) => b.type === "text")
-                    .map((b) => b.text)
-                    .join("");
+                if (opts.toolCalls === "bounded" && calls.length > 0) {
+                    if (toolRounds >= ctx.maxToolRounds) {
+                        const result = { ok: false, errors: [{ message: "maximum tool rounds exceeded" }], metadata: { reason: "tool_round_limit" } };
+                        ctx.emit({ type: "artifact_failed", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt: attempts + 1, result });
+                        return usage;
+                    }
+                    toolRounds += 1;
+                    await dispatchToolCallsInOrder(calls, { ...ctx, toolConcurrency: 1 });
+                    nextInput = [];
+                    continue;
+                }
                 const artifactCtx = {
                     sessionId: ctx.sessionId,
                     runId: ctx.runId,
@@ -99,13 +107,17 @@ export function generateValidateReviseLoop(opts) {
                     signal: ctx.signal,
                     metadata: ctx.metadata,
                 };
+                const text = content
+                    .filter((b) => b.type === "text")
+                    .map((b) => b.text)
+                    .join("");
                 const parsed = opts.parser
                     ? await opts.parser(text, artifactCtx)
                     : { ok: true, value: text };
                 // Parse failure ends the loop silently (terminal parse errors stay on `error`).
                 if (!parsed.ok || parsed.value === undefined)
                     return usage;
-                const attempt = turn;
+                const attempt = ++attempts;
                 ctx.emit({ type: "artifact_validation_started", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt });
                 const result = await opts.validator(parsed.value, artifactCtx);
                 ctx.emit({ type: "artifact_validation_finished", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt, result });
@@ -113,7 +125,7 @@ export function generateValidateReviseLoop(opts) {
                     ctx.emit({ type: "artifact_finished", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt, result });
                     return usage;
                 }
-                if (turn > max) {
+                if (attempt > max) {
                     ctx.emit({ type: "artifact_failed", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt, result });
                     return usage;
                 }
@@ -124,7 +136,6 @@ export function generateValidateReviseLoop(opts) {
                     await ctx.appendMessage(message);
                 pendingHistory = repairMessages;
                 nextInput = repairMessages;
-                continue;
             }
             return usage;
         },
@@ -195,13 +206,12 @@ export function resolveLoop(options, config) {
                 parser: loop.parser,
                 repairer: loop.repairer,
                 maxRevisions: loop.maxRevisions,
+                toolCalls: loop.toolCalls,
             });
         }
         throw new Error(`Unknown agent loop strategy: ${strategy}`);
     }
     return loop;
 }
-function randomId(prefix) {
-    return `${prefix}_${globalThis.crypto?.randomUUID?.() ?? Math.random().toString(36).slice(2)}`;
-}
+const randomId = createId;
 //# sourceMappingURL=agent-loops.js.map

package/dist/agents.js

@@ -1,5 +1,6 @@
 import { AgentRunError } from "./contracts.js";
 import { resolveLoop, resolveToolConcurrency } from "./agent-loops.js";
+import { createId } from "./ids.js";
 import { createProviderTurnMetadata, readProviderHttpStatus } from "./observability.js";
 import { createDefaultCompactionStrategy, isCompactionEntryData } from "./compaction.js";
 import { assembleProviderInput } from "./input.js";
@@ -800,7 +801,5 @@ function createUsageAccumulator() {
         },
     };
 }
-function randomId(prefix) {
-    return `${prefix}_${globalThis.crypto?.randomUUID?.() ?? Math.random().toString(36).slice(2)}`;
-}
+const randomId = createId;
 //# sourceMappingURL=agents.js.map

package/dist/contracts.d.ts

@@ -1440,6 +1440,8 @@ export type AgentLoopOptions = {
     readonly parser?: ArtifactParser<unknown>;
     readonly repairer?: ArtifactRepairer<unknown>;
     readonly maxRevisions?: number;
+    /** Dispatch provider tool calls in artifact turns. Default `"disabled"`; `"bounded"` uses RunOptions.maxToolRounds sequentially. */
+    readonly toolCalls?: "disabled" | "bounded";
     /** Native provider JSON-schema output. Ignored when `structuredOutputMode` is `artifact-loop`. */
     readonly structuredOutput?: StructuredOutputOptions;
     /** `native` maps schema to capable providers; `artifact-loop` keeps repair turns only. */

package/dist/ids.d.ts

@@ -0,0 +1,2 @@
+/** Cryptographically unpredictable identifier for internal Prism records. */
+export declare function createId(prefix: string): string;

package/dist/ids.js

@@ -0,0 +1,6 @@
+import { randomUUID } from "node:crypto";
+/** Cryptographically unpredictable identifier for internal Prism records. */
+export function createId(prefix) {
+    return `${prefix}_${randomUUID()}`;
+}
+//# sourceMappingURL=ids.js.map

package/dist/index.d.ts

@@ -30,6 +30,10 @@ export { assertStructuredOutputRequestSupported, DEFAULT_MAX_STRUCTURED_OUTPUT_N
 export { createProviderTurnMetadata, readProviderHttpStatus } from "./observability.js";
 export { createProviderRequestPolicyChain, createSessionCachePolicy, mergeProviderRequestOptions } from "./provider-request-policy.js";
 export type { SessionCachePolicyOptions } from "./provider-request-policy.js";
+export { THINKING_LEVELS, applyThinkingLevel, isThinkingLevel, normalizeThinkingLevel, thinkingCompatFor, thinkingFamilyForModel, } from "./thinking.js";
+export type { ThinkingCompatFamily, ThinkingLevel } from "./thinking.js";
+export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
+export type { ResolveUseCaseModelInput, ResolvedUseCaseModel, UseCaseModelBinding, } from "./use-case-model.js";
 export { composeSystemPrompt, mergeSystemPromptConfig } from "./system-prompts.js";
 export type { ComposeSystemPromptOptions } from "./system-prompts.js";
 export type { ModelRegistry, ModelRegistryOptions } from "./models.js";
@@ -67,5 +71,5 @@ export type { DispatchToolCallOptions, ToolArgumentValidationError, ToolArgument
 export type { DuplicateRegistrationOptions, DuplicateRegistrationPolicy } from "./registry-options.js";
 export { dispatchToolCallsInOrder, generateValidateReviseLoop, isAgentLoopOptions, resolveLoop, resolveToolConcurrency, singleShotLoop } from "./agent-loops.js";
 export declare const name = "prism";
-export declare const version = "0.0.5";
+export declare const version = "0.0.6";
 export declare const description = "Agent harness for AI providers, agents, sessions, and tools.";

package/dist/index.js

@@ -18,6 +18,8 @@ export { authMethodKey, defineProviderPackage, systemPromptContributionKey } fro
 export { assertStructuredOutputRequestSupported, DEFAULT_MAX_STRUCTURED_OUTPUT_NAME_LENGTH, DEFAULT_MAX_STRUCTURED_OUTPUT_SCHEMA_BYTES, modelSupportsStructuredOutput, resolveRunProviderOptions, StructuredOutputError, validateStructuredOutputOptions, } from "./structured-output.js";
 export { createProviderTurnMetadata, readProviderHttpStatus } from "./observability.js";
 export { createProviderRequestPolicyChain, createSessionCachePolicy, mergeProviderRequestOptions } from "./provider-request-policy.js";
+export { THINKING_LEVELS, applyThinkingLevel, isThinkingLevel, normalizeThinkingLevel, thinkingCompatFor, thinkingFamilyForModel, } from "./thinking.js";
+export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export { composeSystemPrompt, mergeSystemPromptConfig } from "./system-prompts.js";
 export { definePrismManifest, parsePrismManifest } from "./manifests.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";
@@ -37,6 +39,6 @@ export { resolveInstructionInjectors, runInstructionInjectors } from "./instruct
 export { createToolRegistry, dispatchToolCall, filterTools, createToolParameterValidator } from "./tools.js";
 export { dispatchToolCallsInOrder, generateValidateReviseLoop, isAgentLoopOptions, resolveLoop, resolveToolConcurrency, singleShotLoop } from "./agent-loops.js";
 export const name = "prism";
-export const version = "0.0.5";
+export const version = "0.0.6";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map

package/dist/session-stores.js

@@ -1,4 +1,5 @@
 import { SESSION_APPEND_CONFLICT_CODE, SessionAppendConflictError } from "./contracts.js";
+import { createId } from "./ids.js";
 export function createSessionEntry(options) {
     const { createId, now, ...entry } = options;
     return {
@@ -171,7 +172,5 @@ function indexEntries(entries) {
     }
     return { byId, parentIds };
 }
-function randomId(prefix) {
-    return `${prefix}_${globalThis.crypto?.randomUUID?.() ?? Math.random().toString(36).slice(2)}`;
-}
+const randomId = createId;
 //# sourceMappingURL=session-stores.js.map

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

@@ -7,6 +7,8 @@ export interface PersistenceColumnDefinition {
     readonly name: string;
     readonly type: PersistenceColumnType;
     readonly nullable?: boolean;
+    /** Portable SQL default literal, if the schema requires one. */
+    readonly defaultValue?: string;
     /** Column participates in tenant isolation boundaries when true. */
     readonly tenantScoped?: boolean;
 }
@@ -42,6 +44,8 @@ export interface PersistenceMigrationStep {
     readonly version: number;
     readonly name: string;
     readonly description?: string;
+    /** SHA-256 of the canonical checked-in migration schema content. */
+    readonly checksum: string;
 }
 /** Versioned migration expectations shared by production database adapters. */
 export interface PersistenceMigrationContract {
@@ -74,6 +78,46 @@ export declare function tenantScopedUniqueKey(baseColumns: readonly string[], te
 export declare function assertPersistenceSchemaModel(model: PersistenceSchemaModel): void;
 /** Assert migration steps are strictly increasing and end at the target schema version. */
 export declare function assertPersistenceMigrationContract(contract: PersistenceMigrationContract): void;
+export type PersistenceSchemaDialect = "sqlite" | "postgres";
+export interface PersistenceSchemaShapeColumn {
+    readonly name: string;
+    readonly type: string;
+    readonly nullable: boolean;
+    readonly defaultValue?: string;
+}
+export interface PersistenceSchemaShapeForeignKey {
+    readonly columns: readonly string[];
+    readonly referencesTable: string;
+    readonly referencesColumns: readonly string[];
+}
+export interface PersistenceSchemaShapeTable {
+    readonly name: string;
+    readonly columns: readonly PersistenceSchemaShapeColumn[];
+    readonly primaryKey: readonly string[];
+    readonly uniqueKeys: readonly (readonly string[])[];
+    readonly foreignKeys: readonly PersistenceSchemaShapeForeignKey[];
+}
+export interface PersistenceSchemaShapeIndex {
+    readonly name: string;
+    readonly table: string;
+    readonly columns: readonly string[];
+    readonly unique: boolean;
+}
+export interface PersistenceSchemaShape {
+    readonly tables: readonly PersistenceSchemaShapeTable[];
+    readonly indexes: readonly PersistenceSchemaShapeIndex[];
+}
+/** Compare bounded dialect catalog output against every required schema-v3 detail. */
+export declare function assertPersistenceSchemaShape(shape: PersistenceSchemaShape, dialect: PersistenceSchemaDialect, model?: PersistenceSchemaModel): void;
+export interface AppliedPersistenceMigration {
+    readonly name: string;
+    readonly version: string;
+    readonly checksum: string | null;
+}
+/** Reject altered migration history before any new DDL or runtime write. */
+export declare function assertAppliedPersistenceMigrations(contract: PersistenceMigrationContract, applied: readonly AppliedPersistenceMigration[]): {
+    readonly legacyChecksums: boolean;
+};
 /**
  * Assert a dialect-local adapter exposes the canonical table and index names.
  * Adapters pass the table/index names their migration runner created.
@@ -82,13 +126,7 @@ export declare function assertAdapterSchemaMatchesModel(adapterTables: readonly
 /** Guard adapter SQL tests: reject obvious value interpolation into statement text. */
 export declare function assertParameterizedQuery(sql: string, boundValues: readonly unknown[]): void;
 /** Simulate migration up + reopen: applied steps must match the contract in order. */
-export declare function assertMigrationUpAndReopen(contract: PersistenceMigrationContract, appliedAfterUp: readonly {
-    readonly name: string;
-    readonly version: string;
-}[], appliedAfterReopen: readonly {
-    readonly name: string;
-    readonly version: string;
-}[]): void;
+export declare function assertMigrationUpAndReopen(contract: PersistenceMigrationContract, appliedAfterUp: readonly AppliedPersistenceMigration[], appliedAfterReopen: readonly AppliedPersistenceMigration[]): void;
 export interface PersistenceQueryConformanceFixture {
     readonly seedEntries: (entries: readonly SessionEntry[]) => Promise<void> | void;
     readonly queryEntries: (query: SessionEntryQuery) => Promise<PersistencePage<SessionEntry>>;

package/dist/testing/persistence-schema.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 // ponytail: dialect-neutral persistence schema model and migration contracts for
 // SQLite/PostgreSQL adapter packages (Plan 056 Task 1). SQL stays package-local;
 // this module defines the shared table/index/pagination/migration expectations
@@ -107,7 +108,7 @@ export function createPersistenceSchemaModel() {
                     { name: "run_id", type: "text", nullable: true },
                     { name: "timestamp", type: "timestamp" },
                     { name: "kind", type: "text" },
-                    { name: "schema_version", type: "integer" },
+                    { name: "schema_version", type: "integer", nullable: true },
                     { name: "message", type: "json", nullable: true },
                     { name: "event", type: "json", nullable: true },
                     { name: "model", type: "json", nullable: true },
@@ -156,7 +157,6 @@ export function createPersistenceSchemaModel() {
                     ...TENANT_COLUMNS,
                     { name: "metadata", type: "json", nullable: true },
                 ],
-                uniqueKeys: [["tenant_id", "idempotency_key"]],
                 foreignKeys: [{ columns: ["session_id"], referencesTable: "prism_sessions", referencesColumns: ["id"] }],
             },
             {
@@ -210,7 +210,7 @@ export function createPersistenceSchemaModel() {
                     { name: "session_id", type: "text" },
                     { name: "run_id", type: "text", nullable: true },
                     { name: "entry_id", type: "text", nullable: true },
-                    { name: "scope", type: "text" },
+                    { name: "scope", type: "text", defaultValue: "'run_total'" },
                     { name: "turn", type: "integer", nullable: true },
                     { name: "attempt", type: "integer", nullable: true },
                     { name: "usage", type: "json" },
@@ -235,7 +235,9 @@ export function createPersistenceSchemaModel() {
                     { name: "evaluation_ids", type: "json" },
                     { name: "created_at", type: "timestamp" },
                     { name: "created_by", type: "text", nullable: true },
-                    ...TENANT_COLUMNS,
+                    { name: "tenant_id", type: "text", tenantScoped: true },
+                    { name: "account_id", type: "text", nullable: true, tenantScoped: true },
+                    { name: "user_id", type: "text", nullable: true, tenantScoped: true },
                     { name: "metadata", type: "json", nullable: true },
                 ],
                 foreignKeys: [{ columns: ["run_id"], referencesTable: "prism_runs", referencesColumns: ["id"] }],
@@ -281,7 +283,7 @@ export function createPersistenceSchemaModel() {
             { name: "prism_session_entries_session_run_ts_idx", table: "prism_session_entries", columns: ["session_id", "run_id", "timestamp"], purpose: "run-scoped entry listing" },
             { name: "prism_session_entries_session_ts_id_idx", table: "prism_session_entries", columns: ["session_id", "timestamp", "id"], purpose: "cursor pagination without full scans" },
             { name: "prism_session_entries_session_id_idx", table: "prism_session_entries", columns: ["session_id", "id"], purpose: "append parent validation and recursive branch reads" },
-            { name: "prism_session_append_idempotency_unique", table: "prism_session_append_idempotency", columns: ["session_id", "expected_parent_id", "idempotency_key"], unique: true, purpose: "append retry deduplication" },
+            { name: "prism_session_append_idempotency_unique", table: "prism_session_append_idempotency", columns: ["session_id", "expected_parent_id", "idempotency_key"], purpose: "append retry deduplication (primary key enforces uniqueness)" },
             { name: "prism_runs_session_started_idx", table: "prism_runs", columns: ["session_id", "started_at", "id"], purpose: "run history pagination" },
             { name: "prism_runs_branch_started_idx", table: "prism_runs", columns: ["branch_id", "started_at", "id"], purpose: "branch-scoped runs" },
             { name: "prism_runs_tenant_idempotency_unique", table: "prism_runs", columns: ["tenant_id", "idempotency_key"], unique: true, purpose: "run-level idempotency deduplication per tenant" },
@@ -296,19 +298,40 @@ export function createPersistenceSchemaModel() {
             { name: "prism_run_feedback_run_created_idx", table: "prism_run_feedback", columns: ["run_id", "created_at", "id"], purpose: "run feedback lookup" },
             { name: "prism_run_feedback_trace_created_idx", table: "prism_run_feedback", columns: ["trace_id", "created_at", "id"], purpose: "trace feedback lookup" },
             { name: "prism_agent_definitions_name_version_idx", table: "prism_agent_definitions", columns: ["name", "version"], purpose: "definition lookup" },
-            { name: "prism_migrations_name_version_idx", table: "prism_migrations", columns: ["name", "version"], unique: true, purpose: "applied-migration uniqueness" },
+            { name: "prism_migrations_name_version_idx", table: "prism_migrations", columns: ["name", "version"], purpose: "applied-migration lookup (table constraint enforces uniqueness)" },
         ],
     };
 }
+function migrationStep(version, name, description) {
+    const model = createPersistenceSchemaModel();
+    const content = version === 1
+        ? {
+            tables: model.tables
+                .filter((table) => table.name !== "prism_run_feedback")
+                .map((table) => table.name === "prism_usage"
+                ? { ...table, columns: table.columns.filter((column) => !["scope", "turn", "attempt"].includes(column.name)) }
+                : table),
+            indexes: model.indexes.filter((index) => !index.name.startsWith("prism_usage_session_scope_") && !index.name.startsWith("prism_run_feedback_")),
+        }
+        : version === 2
+            ? { table: "prism_usage", columns: ["scope", "turn", "attempt"], indexes: ["prism_usage_session_scope_recorded_idx"] }
+            : { tables: ["prism_run_feedback"], indexes: model.indexes.filter((index) => index.name.startsWith("prism_run_feedback_")).map((index) => index.name) };
+    return {
+        version,
+        name,
+        description,
+        checksum: createHash("sha256").update(JSON.stringify({ version, name, content })).digest("hex"),
+    };
+}
 /** Canonical migration contract for production adapters. */
 export function createPersistenceMigrationContract() {
     return {
         targetSchemaVersion: PERSISTENCE_SCHEMA_VERSION,
         appliedMigrationsTable: "prism_migrations",
         steps: [
-            { version: 1, name: "001_init", description: "Create core session, branch, entry, idempotency, run, ledger, and migration tables." },
-            { version: 2, name: "002_usage_scope", description: "Distinguish provider-turn usage from aggregate run totals." },
-            { version: 3, name: "003_run_feedback", description: "Add immutable ownership-scoped run/trace feedback and evaluation links." },
+            migrationStep(1, "001_init", "Create core session, branch, entry, idempotency, run, ledger, and migration tables."),
+            migrationStep(2, "002_usage_scope", "Distinguish provider-turn usage from aggregate run totals."),
+            migrationStep(3, "003_run_feedback", "Add immutable ownership-scoped run/trace feedback and evaluation links."),
         ],
         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.",
@@ -387,6 +410,8 @@ export function assertPersistenceMigrationContract(contract) {
             throw new Error(`Migration steps must be strictly increasing; ${step.name} is out of order`);
         if (names.has(step.name))
             throw new Error(`Duplicate migration step name: ${step.name}`);
+        if (!/^[a-f0-9]{64}$/.test(step.checksum))
+            throw new Error(`Migration step ${step.name} must have a SHA-256 checksum`);
         names.add(step.name);
         previous = step.version;
     }
@@ -394,6 +419,101 @@ export function assertPersistenceMigrationContract(contract) {
         throw new Error(`Last migration step version ${previous} must equal targetSchemaVersion ${contract.targetSchemaVersion}`);
     }
 }
+function schemaKey(columns) {
+    return columns.join("\u0000");
+}
+function normalizedDefault(value) {
+    return value?.trim().toLowerCase().replace(/::[a-z_ ]+$/, "");
+}
+function compatibleColumnType(dialect, actual, expected) {
+    const type = actual.trim().toUpperCase();
+    if (dialect === "sqlite") {
+        if (expected === "integer" || expected === "boolean")
+            return type === "INTEGER";
+        if (expected === "number")
+            return type === "REAL";
+        return type === "TEXT";
+    }
+    if (expected === "integer")
+        return type === "INTEGER";
+    if (expected === "boolean")
+        return type === "BOOLEAN";
+    if (expected === "number")
+        return type === "DOUBLE PRECISION";
+    return type === "TEXT";
+}
+/** Compare bounded dialect catalog output against every required schema-v3 detail. */
+export function assertPersistenceSchemaShape(shape, dialect, model = createPersistenceSchemaModel()) {
+    assertPersistenceSchemaModel(model);
+    const actualTables = new Map(shape.tables.map((table) => [table.name, table]));
+    for (const expected of model.tables) {
+        const actual = actualTables.get(expected.name);
+        if (!actual)
+            throw new Error(`Persistence schema missing table ${expected.name}`);
+        if (actual.columns.length !== expected.columns.length)
+            throw new Error(`Persistence schema table ${expected.name} has unexpected columns`);
+        const actualColumns = new Map(actual.columns.map((column) => [column.name, column]));
+        for (const column of expected.columns) {
+            const found = actualColumns.get(column.name);
+            if (!found)
+                throw new Error(`Persistence schema table ${expected.name} missing column ${column.name}`);
+            if (!compatibleColumnType(dialect, found.type, column.type)) {
+                throw new Error(`Persistence schema column ${expected.name}.${column.name} has incompatible type`);
+            }
+            if (found.nullable !== (column.nullable === true)) {
+                throw new Error(`Persistence schema column ${expected.name}.${column.name} has incompatible nullability`);
+            }
+            if (normalizedDefault(found.defaultValue) !== normalizedDefault(column.defaultValue)) {
+                throw new Error(`Persistence schema column ${expected.name}.${column.name} has incompatible default`);
+            }
+        }
+        if (schemaKey(actual.primaryKey) !== schemaKey(expected.primaryKey)) {
+            throw new Error(`Persistence schema table ${expected.name} has incompatible primary key`);
+        }
+        const unique = new Set(actual.uniqueKeys.map(schemaKey));
+        for (const key of expected.uniqueKeys ?? []) {
+            if (!unique.has(schemaKey(key)) && schemaKey(actual.primaryKey) !== schemaKey(key)) {
+                throw new Error(`Persistence schema table ${expected.name} missing unique key (${key.join(", ")})`);
+            }
+        }
+        const foreign = new Set(actual.foreignKeys.map((key) => `${schemaKey(key.columns)}>${key.referencesTable}:${schemaKey(key.referencesColumns)}`));
+        for (const key of expected.foreignKeys ?? []) {
+            if (!foreign.has(`${schemaKey(key.columns)}>${key.referencesTable}:${schemaKey(key.referencesColumns)}`)) {
+                throw new Error(`Persistence schema table ${expected.name} missing foreign key (${key.columns.join(", ")})`);
+            }
+        }
+    }
+    const actualIndexes = new Map(shape.indexes.map((index) => [index.name, index]));
+    for (const expected of model.indexes) {
+        const actual = actualIndexes.get(expected.name);
+        if (!actual)
+            throw new Error(`Persistence schema missing required index ${expected.name}`);
+        if (actual.table !== expected.table || schemaKey(actual.columns) !== schemaKey(expected.columns) || actual.unique !== (expected.unique === true)) {
+            throw new Error(`Persistence schema index ${expected.name} has incompatible definition`);
+        }
+    }
+}
+/** Reject altered migration history before any new DDL or runtime write. */
+export function assertAppliedPersistenceMigrations(contract, applied) {
+    assertPersistenceMigrationContract(contract);
+    if (applied.length > contract.steps.length)
+        throw new Error("Migration history has unknown rows");
+    const legacyChecksums = applied.some((row) => row.checksum === null);
+    if (legacyChecksums && (applied.length !== contract.steps.length || !applied.every((row) => row.checksum === null))) {
+        throw new Error("Migration history has incomplete legacy checksums");
+    }
+    for (let index = 0; index < applied.length; index++) {
+        const row = applied[index];
+        const expected = contract.steps[index];
+        if (row.name !== expected.name || row.version !== String(expected.version)) {
+            throw new Error(`Migration history row ${index} does not match ${expected.name}`);
+        }
+        if (!legacyChecksums && row.checksum !== expected.checksum) {
+            throw new Error(`Migration history checksum mismatch for ${expected.name}`);
+        }
+    }
+    return { legacyChecksums };
+}
 /**
  * Assert a dialect-local adapter exposes the canonical table and index names.
  * Adapters pass the table/index names their migration runner created.
@@ -423,23 +543,17 @@ export function assertParameterizedQuery(sql, boundValues) {
 }
 /** Simulate migration up + reopen: applied steps must match the contract in order. */
 export function assertMigrationUpAndReopen(contract, appliedAfterUp, appliedAfterReopen) {
-    assertPersistenceMigrationContract(contract);
-    if (appliedAfterUp.length !== contract.steps.length) {
-        throw new Error("Migration up did not apply every contract step");
-    }
-    for (let i = 0; i < contract.steps.length; i++) {
-        const step = contract.steps[i];
-        const row = appliedAfterUp[i];
-        if (row.name !== step.name || row.version !== String(step.version)) {
-            throw new Error(`Applied migration row ${i} does not match contract step ${step.name}`);
-        }
+    const first = assertAppliedPersistenceMigrations(contract, appliedAfterUp);
+    if (appliedAfterUp.length !== contract.steps.length || first.legacyChecksums) {
+        throw new Error("Migration up did not apply every checksummed contract step");
     }
-    if (appliedAfterReopen.length !== appliedAfterUp.length) {
-        throw new Error("Reopened adapter must not re-apply migrations; applied row count changed");
+    const second = assertAppliedPersistenceMigrations(contract, appliedAfterReopen);
+    if (second.legacyChecksums || appliedAfterReopen.length !== appliedAfterUp.length) {
+        throw new Error("Reopened adapter migration history diverged");
     }
-    for (let i = 0; i < appliedAfterUp.length; i++) {
-        if (appliedAfterReopen[i].name !== appliedAfterUp[i].name) {
-            throw new Error("Reopened adapter migration history diverged");
+    for (let index = 0; index < appliedAfterUp.length; index++) {
+        if (appliedAfterReopen[index].checksum !== appliedAfterUp[index].checksum) {
+            throw new Error("Reopened adapter migration checksums diverged");
         }
     }
 }

package/dist/thinking.d.ts

@@ -0,0 +1,42 @@
+import type { JsonObject, ModelConfig, ProviderRequestOptions } from "./contracts.js";
+/**
+ * Portable thinking / reasoning effort levels shared across first-party providers.
+ * Model-dependent legality (which values a given model accepts) stays provider-owned.
+ */
+export declare const THINKING_LEVELS: readonly ["none", "minimal", "low", "medium", "high", "xhigh", "max"];
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+/**
+ * Compat mapping families used by ≥2 packages, or explicit no-op for host-owned adapters.
+ * Provider packages keep unique escape hatches (budgets, keep/all, tool_stream) local.
+ */
+export type ThinkingCompatFamily = "openai_reasoning" | "reasoning_effort" | "thinking_type" | "noop";
+export declare function isThinkingLevel(value: unknown): value is ThinkingLevel;
+/**
+ * Normalize a host thinkingLevel string. Known levels are lowercased; other non-empty
+ * strings pass through as opaque effort values for forward-compatible provider fields.
+ */
+export declare function normalizeThinkingLevel(level: string): ThinkingLevel | string | undefined;
+/**
+ * Build the `ProviderRequestOptions.compat` patch for a shared thinking level.
+ * Does not invent a second options tree — providers keep reading official fields from `compat`.
+ */
+export declare function thinkingCompatFor(family: ThinkingCompatFamily, level: ThinkingLevel | string): JsonObject;
+/**
+ * Merge a shared thinking level into `providerOptions.compat` for the given family.
+ * Per-turn patches win over prior compat via {@link mergeProviderRequestOptions}.
+ */
+export declare function applyThinkingLevel(options: ProviderRequestOptions | undefined, level: ThinkingLevel | string, family?: ThinkingCompatFamily): ProviderRequestOptions;
+/**
+ * Best-effort family inference from model metadata without a second options tree.
+ * Prefer an explicit family in hosts/use-case workers when the provider is known.
+ *
+ * Heuristics (ordered):
+ * 1. Existing `compat.thinking` object → `thinking_type`
+ * 2. Existing `compat.reasoning` → `openai_reasoning`
+ * 3. Existing `compat.reasoning_effort` → `reasoning_effort`
+ * 4. Provider id starting with `openai` → `openai_reasoning`
+ * 5. Provider id `neuralwatt` → `reasoning_effort`
+ * 6. `capabilities.reasoning` → `reasoning_effort` (portable string field)
+ * 7. Else `noop`
+ */
+export declare function thinkingFamilyForModel(model: Pick<ModelConfig, "provider" | "compat" | "capabilities">): ThinkingCompatFamily;