@arnilo/prism 0.4.0 → 0.5.1

package/dist/testing/provider-conformance.js

@@ -1,3 +1,4 @@
+import { BatchJobsError, EmbeddingsError, ImageGenerationError, ModerationError, pollBatch, SpeechError, TranscriptionError, VideoGenerationError, } from "../contracts.js";
 import { reconstructToolCallDeltas } from "../provider-events.js";
 import { canonicalizeJsonSchema } from "../providers/schema.js";
 export async function collectProviderEvents(provider, request) {
@@ -194,4 +195,345 @@ function jsonPrimitives(value) {
 function textFrom(events) {
     return events.map((event) => (event.type === "content_delta" && event.content.type === "text" ? event.content.text : "")).join("");
 }
+/** Offline conformance for any `EmbeddingsProvider` (plan 061): typed empty-input
+ *  error, typed oversized-batch error, and input-order vector mapping with finite
+ *  coordinates. No network — the caller supplies the provider (real adapter with a
+ *  fake transport, or a fake provider). */
+export async function runEmbeddingsConformance(options) {
+    await assertEmbeddingsErrorCode(() => options.provider.embedMany({ model: options.model, inputs: [] }), "empty_input", "empty inputs must reject with EmbeddingsError(empty_input)");
+    if (options.maxBatchSize !== undefined) {
+        const inputs = Array.from({ length: options.maxBatchSize + 1 }, (_, i) => `input-${i}`);
+        await assertEmbeddingsErrorCode(() => options.provider.embedMany({ model: options.model, inputs }), "batch_too_large", `batches over ${options.maxBatchSize} must reject with EmbeddingsError(batch_too_large)`);
+    }
+    if (!options.sample)
+        return undefined;
+    const result = await options.provider.embedMany({ model: options.model, inputs: options.sample.inputs });
+    if (result.vectors.length !== options.sample.inputs.length)
+        throw new Error(`vector count ${result.vectors.length} must match input count ${options.sample.inputs.length}`);
+    for (const vector of result.vectors) {
+        if (!Array.isArray(vector) || vector.length === 0 || !vector.every(Number.isFinite))
+            throw new Error("vectors must be non-empty arrays of finite numbers");
+    }
+    if (!(result.dimensions > 0))
+        throw new Error("result.dimensions must be positive");
+    if (options.sample.dimensions !== undefined && result.dimensions !== options.sample.dimensions)
+        throw new Error(`result.dimensions ${result.dimensions} must match expected ${options.sample.dimensions}`);
+    return result;
+}
+async function assertEmbeddingsErrorCode(run, code, label) {
+    let error;
+    try {
+        await run();
+    }
+    catch (caught) {
+        error = caught;
+    }
+    if (!(error instanceof EmbeddingsError))
+        throw new Error(`${label}; got ${error === undefined ? "a successful result" : String(error)}`);
+    if (error.code !== code)
+        throw new Error(`${label}; got code ${error.code} (${error.message})`);
+}
+/** Offline conformance for any `SpeechProvider` (plan 061): typed empty-input and
+ *  oversized-input errors, byte results, and stream ordering — the stream must emit
+ *  at least one chunk before closing. Asserts event order, never wall clock. */
+export async function runSpeechConformance(options) {
+    const input = options.sample?.input ?? "conformance";
+    await assertSpeechErrorCode(() => options.provider.synthesize({ model: options.model, input: "" }), "empty_input", "empty input must reject with SpeechError(empty_input)");
+    if (options.maxInputChars !== undefined) {
+        await assertSpeechErrorCode(() => options.provider.synthesize({ model: options.model, input: "x".repeat(options.maxInputChars + 1) }), "input_too_large", `inputs over ${options.maxInputChars} chars must reject with SpeechError(input_too_large)`);
+    }
+    if (!options.sample)
+        return undefined;
+    const request = {
+        model: options.model,
+        input,
+        ...(options.sample.voice ? { voice: options.sample.voice } : {}),
+        ...(options.sample.format ? { format: options.sample.format } : {}),
+    };
+    const result = await options.provider.synthesize(request);
+    if (!(result.audio instanceof Uint8Array) || result.audio.byteLength === 0)
+        throw new Error("synthesize must return non-empty audio bytes");
+    if (typeof result.format !== "string" || result.format.length === 0)
+        throw new Error("result.format must be a non-empty string");
+    const streamed = await options.provider.synthesizeStream(request);
+    const reader = streamed.audio.getReader();
+    let chunks = 0;
+    let firstChunkBeforeClose = false;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (chunks === 0 && value.byteLength > 0)
+            firstChunkBeforeClose = true;
+        chunks += 1;
+    }
+    if (chunks === 0 || !firstChunkBeforeClose)
+        throw new Error("synthesizeStream must emit at least one non-empty chunk before closing");
+    return result;
+}
+async function assertSpeechErrorCode(run, code, label) {
+    let error;
+    try {
+        await run();
+    }
+    catch (caught) {
+        error = caught;
+    }
+    if (!(error instanceof SpeechError))
+        throw new Error(`${label}; got ${error === undefined ? "a successful result" : String(error)}`);
+    if (error.code !== code)
+        throw new Error(`${label}; got code ${error.code} (${error.message})`);
+}
+/** Offline conformance for any `TranscriptionProvider` (plan 061): typed empty-audio
+ *  and oversized-audio errors, one-shot text, and stream ordering — at least one
+ *  `transcript_delta` partial, then exactly one `done` terminal event. */
+export async function runTranscriptionConformance(options) {
+    const audio = options.sample?.audio ?? new Uint8Array([1, 2, 3]);
+    await assertTranscriptionErrorCode(() => options.provider.transcribe({ model: options.model, audio: new Uint8Array(0) }), "empty_input", "empty audio must reject with TranscriptionError(empty_input)");
+    if (options.maxAudioBytes !== undefined) {
+        await assertTranscriptionErrorCode(() => options.provider.transcribe({ model: options.model, audio: new Uint8Array(options.maxAudioBytes + 1) }), "audio_too_large", `audio over ${options.maxAudioBytes} bytes must reject with TranscriptionError(audio_too_large)`);
+    }
+    if (!options.sample)
+        return undefined;
+    const request = {
+        model: options.model,
+        audio,
+        ...(options.sample.format ? { format: options.sample.format } : {}),
+    };
+    const result = await options.provider.transcribe(request);
+    if (typeof result.text !== "string")
+        throw new Error("transcribe must return string text");
+    if (options.sample.textIncludes !== undefined && !result.text.includes(options.sample.textIncludes))
+        throw new Error(`transcript ${JSON.stringify(result.text)} must include ${JSON.stringify(options.sample.textIncludes)}`);
+    let deltas = 0;
+    let doneEvents = 0;
+    for await (const event of options.provider.transcribeStream(request)) {
+        if (event.type === "transcript_delta") {
+            if (typeof event.text !== "string")
+                throw new Error("transcript_delta must carry string text");
+            deltas += 1;
+        }
+        else if (event.type === "done") {
+            doneEvents += 1;
+            if (typeof event.text !== "string")
+                throw new Error("done must carry string text");
+        }
+        else {
+            throw new Error(`unexpected transcript event ${event.type}`);
+        }
+    }
+    if (deltas === 0)
+        throw new Error("transcribeStream must yield at least one transcript_delta before done");
+    if (doneEvents !== 1)
+        throw new Error(`transcribeStream must yield exactly one done event; got ${doneEvents}`);
+    return result;
+}
+async function assertTranscriptionErrorCode(run, code, label) {
+    let error;
+    try {
+        await run();
+    }
+    catch (caught) {
+        error = caught;
+    }
+    if (!(error instanceof TranscriptionError))
+        throw new Error(`${label}; got ${error === undefined ? "a successful result" : String(error)}`);
+    if (error.code !== code)
+        throw new Error(`${label}; got code ${error.code} (${error.message})`);
+}
+/** Offline conformance for any `ImageGenerationProvider` (plan 061): typed empty-input
+ *  and oversized-prompt errors, plus image shape — non-empty bytes, an `image/*` mime
+ *  type, and preserved provenance (`provider`/`model`) on every image. */
+export async function runImageGenerationConformance(options) {
+    await assertImageGenerationErrorCode(() => options.provider.generate({ model: options.model, prompt: "" }), "empty_input", "empty prompts must reject with ImageGenerationError(empty_input)");
+    if (options.maxPromptChars !== undefined) {
+        await assertImageGenerationErrorCode(() => options.provider.generate({ model: options.model, prompt: "x".repeat(options.maxPromptChars + 1) }), "input_too_large", `prompts over ${options.maxPromptChars} chars must reject with ImageGenerationError(input_too_large)`);
+    }
+    if (!options.sample)
+        return undefined;
+    const result = await options.provider.generate({
+        model: options.model,
+        prompt: options.sample.prompt ?? "conformance cube",
+        ...(options.sample.size ? { size: options.sample.size } : {}),
+        ...(options.sample.count ? { count: options.sample.count } : {}),
+    });
+    if (result.images.length === 0)
+        throw new Error("generate must return at least one image");
+    if (options.sample.count !== undefined && result.images.length !== options.sample.count)
+        throw new Error(`image count ${result.images.length} must match requested ${options.sample.count}`);
+    for (const image of result.images) {
+        if (!(image.bytes instanceof Uint8Array) || image.bytes.byteLength === 0)
+            throw new Error("generated images must carry non-empty bytes");
+        if (typeof image.mimeType !== "string" || !image.mimeType.startsWith("image/"))
+            throw new Error(`image mime type ${image.mimeType} must be image/*`);
+        if (image.provider !== options.provider.id)
+            throw new Error(`image provenance provider ${image.provider} must be preserved (${options.provider.id})`);
+        if (image.model !== options.model)
+            throw new Error(`image provenance model ${image.model} must be preserved (${options.model})`);
+    }
+    return result;
+}
+async function assertImageGenerationErrorCode(run, code, label) {
+    let error;
+    try {
+        await run();
+    }
+    catch (caught) {
+        error = caught;
+    }
+    if (!(error instanceof ImageGenerationError))
+        throw new Error(`${label}; got ${error === undefined ? "a successful result" : String(error)}`);
+    if (error.code !== code)
+        throw new Error(`${label}; got code ${error.code} (${error.message})`);
+}
+/** Offline conformance for any `VideoGenerationProvider` (plan 061): typed
+ *  empty-input and oversized-prompt errors, plus the submit→status lifecycle —
+ *  a job id is returned, polling reaches a terminal state, and succeeded jobs
+ *  carry a video with provenance (`provider`/`model`) and at least one source
+ *  (`bytes` or `url`). */
+export async function runVideoGenerationConformance(options) {
+    await assertVideoGenerationErrorCode(() => options.provider.submit({ model: options.model, prompt: "" }), "empty_input", "empty prompts must reject with VideoGenerationError(empty_input)");
+    if (options.maxPromptChars !== undefined) {
+        await assertVideoGenerationErrorCode(() => options.provider.submit({ model: options.model, prompt: "x".repeat(options.maxPromptChars + 1) }), "input_too_large", `prompts over ${options.maxPromptChars} chars must reject with VideoGenerationError(input_too_large)`);
+    }
+    if (!options.sample)
+        return undefined;
+    const { jobId } = await options.provider.submit({ model: options.model, prompt: options.sample.prompt ?? "conformance clip" });
+    if (typeof jobId !== "string" || jobId.length === 0)
+        throw new Error("submit must return a non-empty job id");
+    const maxPolls = options.sample.maxPolls ?? 10;
+    let job;
+    for (let poll = 0; poll < maxPolls; poll += 1) {
+        job = await options.provider.status(jobId);
+        if (!job)
+            throw new Error("status must return a job");
+        if (job.state === "succeeded" || job.state === "failed")
+            break;
+    }
+    if (!job || (job.state !== "succeeded" && job.state !== "failed"))
+        throw new Error(`status did not reach a terminal state within ${maxPolls} polls`);
+    if (job.state === "failed")
+        return job;
+    const video = job.video;
+    if (!video)
+        throw new Error("succeeded jobs must carry a video");
+    if (!video.bytes && !video.url)
+        throw new Error("generated videos must carry bytes or a url");
+    if (video.provider !== options.provider.id)
+        throw new Error(`video provenance provider ${video.provider} must be preserved (${options.provider.id})`);
+    if (video.model !== options.model)
+        throw new Error(`video provenance model ${video.model} must be preserved (${options.model})`);
+    return job;
+}
+async function assertVideoGenerationErrorCode(run, code, label) {
+    let error;
+    try {
+        await run();
+    }
+    catch (caught) {
+        error = caught;
+    }
+    if (!(error instanceof VideoGenerationError))
+        throw new Error(`${label}; got ${error === undefined ? "a successful result" : String(error)}`);
+    if (error.code !== code)
+        throw new Error(`${label}; got code ${error.code} (${error.message})`);
+}
+/** Offline conformance for any `ModerationProvider` (plan 061): typed empty-input
+ *  and oversized-input errors, plus a classification probe — every category
+ *  verdict carries a numeric score in [0,1], a boolean `flagged`, and the
+ *  top-level `flagged` boolean is present. Scores are provider output; conformance
+ *  asserts no local policy decisions are baked in. */
+export async function runModerationConformance(options) {
+    await assertModerationErrorCode(() => options.provider.moderate({ input: "", model: options.model }), "empty_input", "empty inputs must reject with ModerationError(empty_input)");
+    if (options.maxInputChars !== undefined) {
+        await assertModerationErrorCode(() => options.provider.moderate({ input: "x".repeat(options.maxInputChars + 1), model: options.model }), "input_too_large", `inputs over ${options.maxInputChars} chars must reject with ModerationError(input_too_large)`);
+    }
+    if (!options.sample)
+        return undefined;
+    const classified = await options.provider.moderate({ input: options.sample.input ?? "conformance probe", model: options.model });
+    if (Array.isArray(classified))
+        throw new Error("single-string input must classify to one ModerationResult, not a batch");
+    const result = classified;
+    if (typeof result.flagged !== "boolean")
+        throw new Error("moderation results must carry a top-level flagged boolean");
+    const entries = Object.entries(result.categories);
+    if (entries.length === 0)
+        throw new Error("moderation results must expose at least one category verdict");
+    for (const [name, verdict] of entries) {
+        if (typeof verdict.score !== "number" || !(verdict.score >= 0 && verdict.score <= 1))
+            throw new Error(`category ${name} score ${verdict.score} must be a number in [0,1]`);
+        if (typeof verdict.flagged !== "boolean")
+            throw new Error(`category ${name} verdict must carry a flagged boolean`);
+    }
+    return result;
+}
+async function assertModerationErrorCode(run, code, label) {
+    let error;
+    try {
+        await run();
+    }
+    catch (caught) {
+        error = caught;
+    }
+    if (!(error instanceof ModerationError))
+        throw new Error(`${label}; got ${error === undefined ? "a successful result" : String(error)}`);
+    if (error.code !== code)
+        throw new Error(`${label}; got code ${error.code} (${error.message})`);
+}
+/** Offline conformance for any `BatchJobsProvider` (plan 061): typed empty/oversized
+ *  submit errors, opaque job ids, status returning members of the neutral state
+ *  union, terminal resolution via `pollBatch` (plain utility), and paged results
+ *  that walk to exhaustion with cursor continuity. Failure/cancel terminal
+ *  transitions are covered by provider fakes in adapter test suites. */
+export async function runBatchJobsConformance(options) {
+    await assertBatchJobsErrorCode(() => options.provider.submit({ model: "batch-model", requests: [] }), "empty_requests", "empty submits must reject with BatchJobsError(empty_requests)");
+    if (options.maxRequests !== undefined) {
+        await assertBatchJobsErrorCode(() => options.provider.submit({ model: "batch-model", requests: Array.from({ length: options.maxRequests + 1 }, () => ({ body: {} })) }), "too_many_requests", `submits over ${options.maxRequests} requests must reject with BatchJobsError(too_many_requests)`);
+    }
+    if (!options.sample)
+        return;
+    const submitted = await options.provider.submit({ model: options.sample.model, requests: options.sample.requests });
+    if (typeof submitted.id !== "string" || submitted.id.length === 0)
+        throw new Error("submit must return an opaque non-empty job id");
+    const status = await options.provider.status(submitted.id);
+    if (typeof status.state !== "string")
+        throw new Error("status must return a typed job state");
+    const terminal = await pollBatch(options.provider, submitted.id, { intervalMs: 1, maxAttempts: 10 });
+    if (terminal.state !== "completed")
+        throw new Error(`sample job must reach completed; got ${terminal.state}`);
+    const seen = [];
+    let cursor = null;
+    let pages = 0;
+    while (pages < 10) {
+        const page = await options.provider.results(submitted.id, { cursor: cursor ?? null });
+        for (const item of page.items) {
+            if (typeof item.customId !== "string" || item.customId.length === 0)
+                throw new Error("result items must carry non-empty custom ids");
+            seen.push(item.customId);
+        }
+        if (!page.nextCursor)
+            break;
+        if (page.nextCursor === cursor)
+            throw new Error("results cursor must advance between pages");
+        cursor = page.nextCursor;
+        pages += 1;
+    }
+    if (seen.length === 0)
+        throw new Error("completed job must expose at least one result item");
+    if (new Set(seen).size !== seen.length)
+        throw new Error("result paging must not duplicate items across pages");
+}
+async function assertBatchJobsErrorCode(run, code, label) {
+    let error;
+    try {
+        await run();
+    }
+    catch (caught) {
+        error = caught;
+    }
+    if (!(error instanceof BatchJobsError))
+        throw new Error(`${label}; got ${error === undefined ? "a successful result" : String(error)}`);
+    if (error.code !== code)
+        throw new Error(`${label}; got code ${error.code} (${error.message})`);
+}
 //# sourceMappingURL=provider-conformance.js.map

package/dist/testing/tool-effect-store-conformance.d.ts

@@ -6,4 +6,3 @@ export interface ToolEffectStoreConformanceOptions {
 }
 /** Assert core claim/CAS, duplicate, reconciliation, and cleanup semantics without a test framework. */
 export declare function assertToolEffectStoreConforms(factory: () => ToolEffectStore | Promise<ToolEffectStore>, options?: ToolEffectStoreConformanceOptions): Promise<void>;
-export declare function runToolEffectStoreConformance(factory: () => ToolEffectStore | Promise<ToolEffectStore>, options?: ToolEffectStoreConformanceOptions): Promise<void>;

package/dist/testing/tool-effect-store-conformance.js

@@ -44,9 +44,6 @@ export async function assertToolEffectStoreConforms(factory, options = {}) {
     if (cleanup.deleted < 1)
         throw new Error("store cleanup must remove terminal effects");
 }
-export async function runToolEffectStoreConformance(factory, options = {}) {
-    await assertToolEffectStoreConforms(factory, options);
-}
 function key(identity, ownership, value, toolCallId = "call") {
     return {
         identity,

package/dist/thinking.d.ts

@@ -9,8 +9,16 @@ 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 type ThinkingCompatFamily = "openai_reasoning" | "reasoning_effort" | "thinking_type" | "google" | "output_config_effort" | "noop";
 export declare function isThinkingLevel(value: unknown): value is ThinkingLevel;
+/**
+ * Parse a host thinking-level value without guessing: known levels canonicalize to
+ * `ThinkingLevel`, unknown non-empty strings pass through as opaque `{ opaque }`
+ * (forward-compat passthrough), invalid/empty/non-string input fails closed.
+ */
+export declare function parseThinkingLevel(value: unknown): ThinkingLevel | {
+    readonly opaque: string;
+} | undefined;
 /**
  * Normalize a host thinkingLevel string. Known levels are lowercased; other non-empty
  * strings pass through as opaque effort values for forward-compatible provider fields.
@@ -26,17 +34,48 @@ export declare function thinkingCompatFor(family: ThinkingCompatFamily, level: T
  * Per-turn patches win over prior compat via {@link mergeProviderRequestOptions}.
  */
 export declare function applyThinkingLevel(options: ProviderRequestOptions | undefined, level: ThinkingLevel | string, family?: ThinkingCompatFamily): ProviderRequestOptions;
+/**
+ * Declared portable thinking levels for a model, if any (ascending ladder order).
+ * `undefined` means the provider declares no subset — forward-compat passthrough.
+ */
+export declare function thinkingLevelsForModel(model: Pick<ModelConfig, "provider" | "compat" | "capabilities">): readonly string[] | undefined;
+/**
+ * Strict declared-set membership (hosts fail closed on unknown levels).
+ * A model that declares no levels supports any value (forward-compat passthrough).
+ */
+export declare function isSupportedThinkingLevel(model: Pick<ModelConfig, "provider" | "compat" | "capabilities">, level: unknown): boolean;
+/**
+ * Snap a portable level to a model's declared set (design record §2):
+ * in-set → unchanged; below the declared minimum → up to the minimum
+ * (never silently disable what cannot be disabled); otherwise nearest declared
+ * level by ladder distance with ties breaking up; undeclared levels and
+ * undeclared sets pass through. Provider-documented snap tables
+ * (deepseek, Z.AI GLM-5.2, clinepass slots) override this generic fallback
+ * inside their own resolvers.
+ */
+export declare function snapThinkingLevel(model: Pick<ModelConfig, "provider" | "compat" | "capabilities">, level: ThinkingLevel | string): ThinkingLevel | string;
+/**
+ * Model-aware thinking-level application (design record §5). Resolves the family
+ * stamp-first (`compat.thinkingFamily` → inference → `capabilities.reasoning`),
+ * snaps the level to the model's declared set, and merges the compat patch
+ * per-turn-wins. Returns options unchanged for non-reasoning models — never
+ * invents a field where the model declares no thinking support.
+ */
+export declare function applyThinkingLevelForModel(options: ProviderRequestOptions | undefined, level: ThinkingLevel | string, model: Pick<ModelConfig, "provider" | "compat" | "capabilities">): 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.
+ * Prefer an explicit `compat.thinkingFamily` stamp in host/use-case workers when
+ * the provider is known; inference is the fallback (stamp-first).
  *
  * 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`
+ * 1. `compat.thinkingFamily` stamp → itself
+ * 2. Existing `compat.thinking` object → `thinking_type`
+ * 3. Existing `compat.thinkingConfig` object/boolean → `google`
+ * 4. Existing `compat.reasoning` → `openai_reasoning`
+ * 5. Existing `compat.reasoning_effort` → `reasoning_effort`
+ * 6. Provider id starting with `openai` → `openai_reasoning`
+ * 7. Provider id `neuralwatt` → `reasoning_effort`
+ * 8. `capabilities.reasoning` → `reasoning_effort` (portable string field)
+ * 9. Else `noop`
  */
 export declare function thinkingFamilyForModel(model: Pick<ModelConfig, "provider" | "compat" | "capabilities">): ThinkingCompatFamily;

package/dist/thinking.js

@@ -7,6 +7,40 @@ export const THINKING_LEVELS = ["none", "minimal", "low", "medium", "high", "xhi
 export function isThinkingLevel(value) {
     return typeof value === "string" && THINKING_LEVELS.includes(value);
 }
+const LEVEL_RANK = {
+    none: 0,
+    minimal: 1,
+    low: 2,
+    medium: 3,
+    high: 4,
+    xhigh: 5,
+    max: 6,
+};
+function isThinkingFamily(value) {
+    return (typeof value === "string" &&
+        (value === "openai_reasoning" ||
+            value === "reasoning_effort" ||
+            value === "thinking_type" ||
+            value === "google" ||
+            value === "output_config_effort" ||
+            value === "noop"));
+}
+function thinkingLevelRank(level) {
+    return isThinkingLevel(level) ? LEVEL_RANK[level] : undefined;
+}
+/**
+ * Parse a host thinking-level value without guessing: known levels canonicalize to
+ * `ThinkingLevel`, unknown non-empty strings pass through as opaque `{ opaque }`
+ * (forward-compat passthrough), invalid/empty/non-string input fails closed.
+ */
+export function parseThinkingLevel(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const normalized = normalizeThinkingLevel(value);
+    if (!normalized)
+        return undefined;
+    return isThinkingLevel(normalized) ? normalized : { opaque: normalized };
+}
 /**
  * Normalize a host thinkingLevel string. Known levels are lowercased; other non-empty
  * strings pass through as opaque effort values for forward-compatible provider fields.
@@ -32,6 +66,10 @@ export function thinkingCompatFor(family, level) {
             return { reasoning_effort: normalized };
         case "thinking_type":
             return { thinking: { type: normalized === "none" ? "disabled" : "enabled" } };
+        case "google":
+            return { thinkingLevel: normalized };
+        case "output_config_effort":
+            return { output_config: { effort: normalized } };
         default: {
             const _exhaustive = family;
             return _exhaustive;
@@ -62,23 +100,111 @@ export function applyThinkingLevel(options, level, family = "reasoning_effort")
     }
     return mergeProviderRequestOptions(options, { compat: patch });
 }
+/**
+ * Declared portable thinking levels for a model, if any (ascending ladder order).
+ * `undefined` means the provider declares no subset — forward-compat passthrough.
+ */
+export function thinkingLevelsForModel(model) {
+    return model.capabilities?.thinkingLevels;
+}
+/**
+ * Strict declared-set membership (hosts fail closed on unknown levels).
+ * A model that declares no levels supports any value (forward-compat passthrough).
+ */
+export function isSupportedThinkingLevel(model, level) {
+    const parsed = parseThinkingLevel(level);
+    if (!parsed)
+        return false;
+    const declared = thinkingLevelsForModel(model);
+    if (!declared || declared.length === 0)
+        return true;
+    const value = typeof parsed === "string" ? parsed : parsed.opaque;
+    return declared.includes(value);
+}
+/**
+ * Snap a portable level to a model's declared set (design record §2):
+ * in-set → unchanged; below the declared minimum → up to the minimum
+ * (never silently disable what cannot be disabled); otherwise nearest declared
+ * level by ladder distance with ties breaking up; undeclared levels and
+ * undeclared sets pass through. Provider-documented snap tables
+ * (deepseek, Z.AI GLM-5.2, clinepass slots) override this generic fallback
+ * inside their own resolvers.
+ */
+export function snapThinkingLevel(model, level) {
+    const normalized = normalizeThinkingLevel(String(level));
+    if (!normalized)
+        return String(level);
+    const declared = thinkingLevelsForModel(model);
+    if (!declared || declared.length === 0)
+        return normalized;
+    if (declared.includes(normalized))
+        return normalized;
+    const rank = thinkingLevelRank(normalized);
+    const ranked = declared
+        .map((entry) => ({ entry, rank: thinkingLevelRank(entry) }))
+        .filter((entry) => entry.rank != null);
+    if (rank == null || ranked.length === 0)
+        return normalized;
+    const minRank = Math.min(...ranked.map(({ rank: r }) => r));
+    if (rank < minRank)
+        return ranked.find(({ rank: r }) => r === minRank).entry;
+    let best = ranked[0].entry;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    let bestRank = Number.NEGATIVE_INFINITY;
+    for (const { entry, rank: candidateRank } of ranked) {
+        const distance = Math.abs(candidateRank - rank);
+        if (distance < bestDistance || (distance === bestDistance && candidateRank > bestRank)) {
+            best = entry;
+            bestDistance = distance;
+            bestRank = candidateRank;
+        }
+    }
+    return best;
+}
+/**
+ * Model-aware thinking-level application (design record §5). Resolves the family
+ * stamp-first (`compat.thinkingFamily` → inference → `capabilities.reasoning`),
+ * snaps the level to the model's declared set, and merges the compat patch
+ * per-turn-wins. Returns options unchanged for non-reasoning models — never
+ * invents a field where the model declares no thinking support.
+ */
+export function applyThinkingLevelForModel(options, level, model) {
+    const normalized = normalizeThinkingLevel(String(level));
+    if (!normalized)
+        return options ?? {};
+    const family = model.compat?.thinkingFamily != null && isThinkingFamily(model.compat.thinkingFamily)
+        ? model.compat.thinkingFamily
+        : thinkingFamilyForModel(model);
+    if (family === "noop")
+        return options ?? {};
+    return applyThinkingLevel(options, snapThinkingLevel(model, normalized), family);
+}
 /**
  * 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.
+ * Prefer an explicit `compat.thinkingFamily` stamp in host/use-case workers when
+ * the provider is known; inference is the fallback (stamp-first).
  *
  * 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`
+ * 1. `compat.thinkingFamily` stamp → itself
+ * 2. Existing `compat.thinking` object → `thinking_type`
+ * 3. Existing `compat.thinkingConfig` object/boolean → `google`
+ * 4. Existing `compat.reasoning` → `openai_reasoning`
+ * 5. Existing `compat.reasoning_effort` → `reasoning_effort`
+ * 6. Provider id starting with `openai` → `openai_reasoning`
+ * 7. Provider id `neuralwatt` → `reasoning_effort`
+ * 8. `capabilities.reasoning` → `reasoning_effort` (portable string field)
+ * 9. Else `noop`
  */
 export function thinkingFamilyForModel(model) {
+    const stamp = model.compat?.thinkingFamily;
+    if (isThinkingFamily(stamp))
+        return stamp;
     const compat = model.compat ?? {};
     if (compat.thinking != null && typeof compat.thinking === "object")
         return "thinking_type";
+    if (compat.thinkingConfig != null && (typeof compat.thinkingConfig === "object" || typeof compat.thinkingConfig === "boolean")) {
+        return "google";
+    }
     if (compat.reasoning != null)
         return "openai_reasoning";
     if (compat.reasoning_effort != null)

package/docs/0.1.0-readiness.md

@@ -1,6 +1,6 @@
 # 0.1.0 / 1.0 Readiness Gates
 
-Status: **0.4.0** is the current release line (plan 054 package consolidation: 11 active packages, family subpaths, `^0.4.0` peers); **0.3.3** was the terminal 0.3.x cut; **0.1.7** was the terminal 0.1.x baseline; **1.0** readiness remains operator-gated, not automatic.
+Status: **0.5.1** is the current release line (provider request construction cut: 10 active packages, family subpaths, `^0.5.1` peers); **0.3.3** was the terminal 0.3.x cut; **0.1.7** was the terminal 0.1.x baseline; **1.0** readiness remains operator-gated, not automatic.
 
 This page distills runnable readiness gates into one command-per-gate table.
 The **Last evidence** column records the 0.1.0-tree snapshot (plan 012 Tasks
@@ -20,7 +20,7 @@ Historical release lines (0.0.16 floor → 0.0.27 Phase 10 ACP interop → 0.1.0
 keep their per-phase evidence in the pages above; this page records the 0.2.6
 snapshot (plan 026) with the 0.1.x tables below as the historical record.
 
-## Current line (0.4.0)
+## Current line (0.5.1)
 
 | Item | Status |
 |---|---|
@@ -66,7 +66,7 @@ snapshot (plan 026) with the 0.1.x tables below as the historical record.
 | Publish order + tarball validation | `node scripts/release.mjs publish --version 0.1.0 --dry-run --allow-dirty --allow-untagged` | 49/49 packages `dry-run` twice with byte-identical reports, deterministic dependency order, no failures (Task 7) | Operator (dry-run), CI |
 | Node 20 compatibility | CI `node20-compat` (build + public-import smoke) | all 21 root exports import cleanly on Node 20.20.2 | CI |
 | PostgreSQL suite | `PRISM_TEST_POSTGRES_URL="$DATABASE_URL" npm run test:postgres` | 0.1.0: Phase 7 conformance + Phase 12 restart-recovery + 74 workspace checks green against PostgreSQL 16 (Task 4 recording, re-run green at 0.1.0 on 2026-08-09); operator-gated | Operator |
-| Keychain suite | `PRISM_TEST_KEYCHAIN=1 npm test --workspace @arnilo/prism-credentials-node` (protected) | 28/28 green incl. native keychain round-trip against the OS secret-service backend (gnome-keyring, 2026-08-09) | Operator host |
+| Keychain suite | `PRISM_TEST_KEYCHAIN=1 npm test --workspace @arnilo/prism-core/credentials/node` (protected) | 28/28 green incl. native keychain round-trip against the OS secret-service backend (gnome-keyring, 2026-08-09) | Operator host |
 | Live-provider suites | `npm run test:live` (protected) | **operator-gated** (requires credentials; `live-canaries.yml` blocked gate, `canary-report.json` retained) | Operator |
 | SAST | GitHub CodeQL | **operator-gated** (runs in CI workflow) | CI |
 | Signed, provenance publication | `npm run release:publish` (clean tagged tree, OIDC) | **operator-gated** (see "Remaining for 1.0") | Operator |

package/docs/a2a.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`@arnilo/prism-supervisor` implements bounded A2A 1.0 over the JSON-RPC/HTTPS binding. Supported operations: `SendMessage`, `SendStreamingMessage`, `GetTask`, `ListTasks`, `CancelTask`, `SubscribeToTask`, push-notification-config create/get/list/delete, and `GetExtendedAgentCard`. `client.streamMessage()` additionally exposes verified rich task/message events for frontend adapters while legacy `stream()` remains text-compatible. Agent Cards retain explicit ES256 verification. gRPC, HTTP+JSON, discovery registries, automatic JWK/OAuth fetching, and an internal task worker/store are absent.
+`@arnilo/prism-core/runtime/supervisor` implements bounded A2A 1.0 over the JSON-RPC/HTTPS binding. Supported operations: `SendMessage`, `SendStreamingMessage`, `GetTask`, `ListTasks`, `CancelTask`, `SubscribeToTask`, push-notification-config create/get/list/delete, and `GetExtendedAgentCard`. `client.streamMessage()` additionally exposes verified rich task/message events for frontend adapters while legacy `stream()` remains text-compatible. Agent Cards retain explicit ES256 verification. gRPC, HTTP+JSON, discovery registries, automatic JWK/OAuth fetching, and an internal task worker/store are absent.
 
 ## When to use it
 
@@ -41,7 +41,7 @@ Parts, messages, artifacts, histories, metadata, and aggregate responses are unt
 
 ## AG-UI server-side exposure (Task 13, 0.0.26)
 
-`createAgUiA2AServer()` in `@arnilo/prism-ag-ui` fronts one host-selected **local AG-UI agent** as an A2A 1.0 server, the reverse direction of `createAgUiA2AAdapter()`: remote A2A clients start and stream local runs through the same AG-UI input allow-list and event mapper as the AG-UI SSE path (same projection, redaction, and byte caps). It reuses this package's `createA2AHandler` transport/lifecycle; it creates no second runtime, task store, or worker. Requires the optional `@arnilo/prism-supervisor` peer (imported lazily; plain `@arnilo/prism-ag-ui` imports keep working without it).
+`createAgUiA2AServer()` in `@arnilo/prism-ag-ui` fronts one host-selected **local AG-UI agent** as an A2A 1.0 server, the reverse direction of `createAgUiA2AAdapter()`: remote A2A clients start and stream local runs through the same AG-UI input allow-list and event mapper as the AG-UI SSE path (same projection, redaction, and byte caps). It reuses this package's `createA2AHandler` transport/lifecycle; it creates no second runtime, task store, or worker. Requires the optional `@arnilo/prism-core/runtime/supervisor` peer (imported lazily; plain `@arnilo/prism-ag-ui` imports keep working without it).
 
 ```ts
 import { createAgentEventSourceAgUiReplay, createAgUiA2AServer } from "@arnilo/prism-ag-ui";