@arnilo/prism 0.0.5 → 0.0.7

package/dist/run-limits.js

@@ -0,0 +1,163 @@
+export const DEFAULT_RUN_LIMITS = Object.freeze({
+    maxTurns: 16,
+    maxProviderAttempts: 24,
+    maxToolRounds: 8,
+    maxToolCalls: 32,
+    maxWallTimeMs: 120_000,
+    maxRequestBytes: 8 * 1024 * 1024,
+    maxResponseBytes: 8 * 1024 * 1024,
+    maxInputTokens: 40_000,
+    maxOutputTokens: 10_000,
+    maxTotalTokens: 50_000,
+});
+export const HARD_MAX_RUN_COST = 10_000;
+export const HARD_RUN_LIMITS = Object.freeze({
+    maxTurns: 64,
+    maxProviderAttempts: 256,
+    maxToolRounds: 64,
+    maxToolCalls: 256,
+    maxWallTimeMs: 30 * 60_000,
+    maxRequestBytes: 64 * 1024 * 1024,
+    maxResponseBytes: 64 * 1024 * 1024,
+    maxInputTokens: 1_000_000,
+    maxOutputTokens: 250_000,
+    maxTotalTokens: 1_000_000,
+});
+const LIMIT_NAMES = Object.keys(DEFAULT_RUN_LIMITS);
+const COUNTER_FOR = {
+    maxTurns: "turns",
+    maxProviderAttempts: "providerAttempts",
+    maxToolRounds: "toolRounds",
+    maxToolCalls: "toolCalls",
+    maxWallTimeMs: "wallTimeMs",
+    maxRequestBytes: "requestBytes",
+    maxResponseBytes: "responseBytes",
+    maxInputTokens: "inputTokens",
+    maxOutputTokens: "outputTokens",
+    maxTotalTokens: "totalTokens",
+    maxCost: "cost",
+};
+export class RunLimitError extends Error {
+    breach;
+    code = "ERR_PRISM_RUN_LIMIT";
+    constructor(breach) {
+        super(`Run limit exceeded: ${breach.limit}`);
+        this.breach = breach;
+        this.name = "RunLimitError";
+    }
+}
+/** Validate one host-authored layer. Defaults are applied only after inheritance is resolved. */
+export function resolveRunLimits(agent, run) {
+    const base = agent ? validateLimits(agent) : undefined;
+    const override = run ? validateLimits(run) : undefined;
+    const resolved = { ...DEFAULT_RUN_LIMITS };
+    for (const name of LIMIT_NAMES) {
+        if (base?.[name] !== undefined)
+            resolved[name] = base[name];
+        if (override?.[name] !== undefined)
+            resolved[name] = base ? Math.min(resolved[name], override[name]) : override[name];
+    }
+    const maxCost = override?.maxCost ?? base?.maxCost;
+    return Object.freeze({ ...resolved, ...(maxCost ? { maxCost: base?.maxCost && override?.maxCost ? { amount: Math.min(base.maxCost.amount, override.maxCost.amount), currency: base.maxCost.currency === override.maxCost.currency ? base.maxCost.currency : failCurrency() } : maxCost } : {}) });
+}
+function failCurrency() { throw new TypeError("Run limit currencies must match when narrowed"); }
+function validateLimits(input) {
+    for (const name of LIMIT_NAMES) {
+        const value = input[name];
+        if (value === undefined)
+            continue;
+        if (!Number.isSafeInteger(value) || value < 1 || value > HARD_RUN_LIMITS[name]) {
+            throw new TypeError(`${name} must be a positive safe integer at most ${HARD_RUN_LIMITS[name]}`);
+        }
+    }
+    if (input.maxCost) {
+        const { amount, currency } = input.maxCost;
+        if (!Number.isFinite(amount) || amount < 0 || amount > HARD_MAX_RUN_COST || !currency.trim())
+            throw new TypeError(`maxCost requires a finite amount from 0 through ${HARD_MAX_RUN_COST} and currency`);
+    }
+    return input;
+}
+export class RunLimitTracker {
+    options;
+    limits;
+    startedAt = performance.now();
+    deadlineAt;
+    counters;
+    timer;
+    exceeded;
+    constructor(limits, options = {}) {
+        this.options = options;
+        this.limits = limits;
+        this.counters = { turns: 0, providerAttempts: 0, toolRounds: 0, toolCalls: 0, wallTimeMs: 0, requestBytes: 0, responseBytes: 0, inputTokens: 0, outputTokens: 0, totalTokens: 0, cost: 0, ...options.snapshot };
+        for (const [key, value] of Object.entries(this.counters)) {
+            if (!Number.isFinite(value) || value < 0 || (key !== "cost" && !Number.isSafeInteger(value))) {
+                throw new TypeError("Run limit snapshot must contain finite non-negative counters");
+            }
+        }
+        const deadline = options.deadlineAt ? Date.parse(options.deadlineAt) : Date.now() + limits.maxWallTimeMs;
+        if (!Number.isFinite(deadline))
+            throw new TypeError("Run limit deadlineAt is invalid");
+        this.deadlineAt = new Date(deadline).toISOString();
+        const remaining = Math.max(0, deadline - Date.now());
+        this.timer = setTimeout(() => this.exceed("maxWallTimeMs", limits.maxWallTimeMs), remaining);
+        this.timer.unref?.();
+        if (remaining === 0)
+            this.exceed("maxWallTimeMs", limits.maxWallTimeMs);
+    }
+    get breach() { return this.exceeded; }
+    snapshot() { return { ...this.counters, wallTimeMs: Math.min(this.limits.maxWallTimeMs, Math.ceil(performance.now() - this.startedAt)) }; }
+    dispose() { if (this.timer)
+        clearTimeout(this.timer); this.timer = undefined; }
+    charge(limit, delta = 1) {
+        if (!Number.isSafeInteger(delta) || delta < 0)
+            throw new TypeError("Run limit delta must be a non-negative safe integer");
+        const counter = COUNTER_FOR[limit];
+        const observed = this.counters[counter] + delta;
+        if (!Number.isSafeInteger(observed))
+            this.exceed(limit, Number.MAX_SAFE_INTEGER + 1);
+        this.counters[counter] = observed;
+        if (observed > this.limits[limit])
+            this.exceed(limit, observed);
+    }
+    recordUsage(usage) {
+        if (!usage) {
+            if (this.limits.maxCost)
+                this.exceed("maxCost", Number.POSITIVE_INFINITY);
+            return;
+        }
+        for (const key of ["inputTokens", "outputTokens", "totalTokens", "cacheReadTokens", "cacheWriteTokens"]) {
+            const value = usage[key];
+            if (value !== undefined && (!Number.isSafeInteger(value) || value < 0))
+                throw new TypeError(`Provider usage ${key} must be a non-negative safe integer`);
+        }
+        const total = usage.totalTokens ?? ((usage.inputTokens ?? 0) + (usage.outputTokens ?? 0));
+        if (!Number.isSafeInteger(total))
+            throw new TypeError("Provider usage totalTokens is invalid");
+        this.charge("maxInputTokens", usage.inputTokens ?? 0);
+        this.charge("maxOutputTokens", usage.outputTokens ?? 0);
+        this.charge("maxTotalTokens", total);
+        if (usage.cost !== undefined && (!Number.isFinite(usage.cost) || usage.cost < 0))
+            throw new TypeError("Provider usage cost must be finite and non-negative");
+        if (!this.limits.maxCost)
+            return;
+        if (usage.cost === undefined || usage.currency !== this.limits.maxCost.currency)
+            this.exceed("maxCost", Number.POSITIVE_INFINITY);
+        const observed = this.counters.cost + usage.cost;
+        this.counters.cost = observed;
+        if (observed > this.limits.maxCost.amount)
+            this.exceed("maxCost", observed);
+    }
+    exceed(limit, observed) {
+        if (!this.exceeded) {
+            const maximum = limit === "maxCost" ? this.limits.maxCost?.amount ?? 0 : this.limits[limit];
+            this.exceeded = { limit, maximum, observed, ...(limit === "maxCost" && this.limits.maxCost ? { currency: this.limits.maxCost.currency } : {}) };
+            this.options.onExceeded?.(this.exceeded);
+        }
+        if (limit !== "maxWallTimeMs")
+            throw new RunLimitError(this.exceeded);
+    }
+}
+export function createRunLimitTracker(limits, options) {
+    return new RunLimitTracker(resolveRunLimits(undefined, limits), options);
+}
+//# sourceMappingURL=run-limits.js.map

package/dist/secure-agent.d.ts

@@ -0,0 +1,3 @@
+import type { Agent, SecureAgentOptions } from "./contracts.js";
+/** Build an opt-in agent whose security-critical defaults cannot be replaced per run. */
+export declare function createSecureAgent(options: SecureAgentOptions): Agent;

package/dist/secure-agent.js

@@ -0,0 +1,63 @@
+import { createAgent } from "./agents.js";
+import { validateRunStateOptions } from "./agent-run-state.js";
+import { resolveRunLimits } from "./run-limits.js";
+import { createToolParameterValidator, createToolRegistry } from "./tools.js";
+/** Build an opt-in agent whose security-critical defaults cannot be replaced per run. */
+export function createSecureAgent(options) {
+    if (!options.id.trim())
+        throw new TypeError("Secure agent requires a non-empty id");
+    if (!options.definitionRevision.trim())
+        throw new TypeError("Secure agent requires a non-empty definitionRevision");
+    if (!options.redactor || typeof options.redactor.redact !== "function")
+        throw new TypeError("Secure agent requires a redactor");
+    if (!options.permission || typeof options.permission.check !== "function")
+        throw new TypeError("Secure agent requires a permission policy");
+    if (!options.trust || typeof options.trust.check !== "function")
+        throw new TypeError("Secure agent requires a trust policy");
+    if (!options.toolArgumentValidator || typeof options.toolArgumentValidator.validate !== "function")
+        throw new TypeError("Secure agent requires a tool argument validator");
+    if (!options.limits || Object.keys(options.limits).length === 0)
+        throw new TypeError("Secure agent requires explicit limits");
+    if (!options.ownership || !Object.values(options.ownership).some((value) => typeof value === "string" && value.trim()))
+        throw new TypeError("Secure agent requires non-empty ownership");
+    for (const tool of options.tools) {
+        if (!tool.name.trim())
+            throw new TypeError("Secure agent tool names must be non-empty");
+        if (!tool.parameters || Object.keys(tool.parameters).length === 0)
+            throw new TypeError(`Secure agent tool ${tool.name} requires a non-empty parameters schema`);
+    }
+    resolveRunLimits(options.limits);
+    const runState = Object.freeze({ ...options.runState, definitionRevision: options.definitionRevision, interruptBeforeTool: true });
+    validateRunStateOptions(runState);
+    const config = Object.freeze({
+        ...withoutSecureFields(options),
+        id: options.id,
+        tools: createToolRegistry(options.tools, { duplicate: "error" }),
+        validator: createToolParameterValidator(options.toolArgumentValidator, { missingSchema: "reject" }),
+        redactor: options.redactor,
+        permission: options.permission,
+        trust: options.trust,
+        ownership: Object.freeze({ ...options.ownership }),
+        limits: Object.freeze({ ...options.limits }),
+        guardrails: freezeGuardrails(options.guardrails),
+        runState,
+        secure: true,
+    });
+    return createAgent(config);
+}
+function withoutSecureFields(options) {
+    const { tools: _tools, toolArgumentValidator: _validator, redactor: _redactor, permission: _permission, trust: _trust, ownership: _ownership, limits: _limits, guardrails: _guardrails, definitionRevision: _revision, runState: _runState, ...config } = options;
+    return config;
+}
+function freezeGuardrails(guardrails) {
+    if (!guardrails)
+        return undefined;
+    return Object.freeze({
+        ...guardrails,
+        input: Object.freeze([...(guardrails.input ?? [])]),
+        output: Object.freeze([...(guardrails.output ?? [])]),
+        toolInput: Object.freeze([...(guardrails.toolInput ?? [])]),
+        toolOutput: Object.freeze([...(guardrails.toolOutput ?? [])]),
+    });
+}
+//# sourceMappingURL=secure-agent.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;