theorum 0.1.2 → 0.1.3

package/esm/src/kernel/mod.d.ts

@@ -9,7 +9,9 @@
  */
 import "../../_dnt.polyfills.js";
 export { runTurn } from './engine/runner.js';
-export { defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './registry/profiles.js';
+export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, getTool, listBuiltinIds, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './registry/catalog.js';
+export type { ProfileDefinition } from './registry/profiles.js';
+export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './registry/profiles.js';
 export { projectProfile, resolveTurn } from './registry/resolve.js';
 export { getStructured, registerStructured } from './registry/schemas.js';
 export { executeTool } from './registry/tools.js';

package/esm/src/kernel/mod.js

@@ -9,7 +9,8 @@
  */
 import "../../_dnt.polyfills.js";
 export { runTurn } from './engine/runner.js';
-export { defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './registry/profiles.js';
+export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, getTool, listBuiltinIds, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './registry/catalog.js';
+export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './registry/profiles.js';
 export { projectProfile, resolveTurn } from './registry/resolve.js';
 export { getStructured, registerStructured } from './registry/schemas.js';
 export { executeTool } from './registry/tools.js';

package/esm/src/{providers → kernel/registry}/attachments.d.ts

@@ -1,8 +1,7 @@
-import type { MediaLimits, MimeInputs, Profile, TurnBlob } from '../kernel/types.js';
+import type { MediaLimits, Profile, TurnBlob } from '../types.js';
 declare function tooManyFilesMessage(maxFiles: number): string;
 declare function fileTooLargeMessage(maxBytes: number): string;
 declare function turnTooLargeMessage(maxTurnBytes: number): string;
-declare function mediaLimits(inputs: MimeInputs): MediaLimits | undefined;
 declare function requireMediaLimits(profile: Profile): MediaLimits;
 declare function sanitizeCsvText(text: string): string;
 declare function assertAttachmentLimits(blobs: TurnBlob[], limits: MediaLimits): void;
@@ -14,4 +13,4 @@ declare function sanitizeTurnBlobsForProfile(profileId: string, attachments: Tur
     attachments?: TurnBlob[];
     voice?: TurnBlob[];
 };
-export { assertAttachmentLimits, fileTooLargeMessage, mediaLimits, requireMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, sanitizeTurnBlobsForProfile, tooManyFilesMessage, turnTooLargeMessage, };
+export { assertAttachmentLimits, fileTooLargeMessage, requireMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, sanitizeTurnBlobsForProfile, tooManyFilesMessage, turnTooLargeMessage, };

package/esm/src/{providers → kernel/registry}/attachments.js

@@ -1,8 +1,8 @@
-import { TheorumError } from '../guardrails/error.js';
-import { injectionSpans } from '../guardrails/injection.js';
-import { sensitiveSpans } from '../guardrails/sensitive.js';
-import { getProfile } from '../kernel/registry/profiles.js';
-import { applySpans } from '../observability/spans.js';
+import { TheorumError } from '../../guardrails/error.js';
+import { injectionSpans } from '../../guardrails/injection.js';
+import { sensitiveSpans } from '../../guardrails/sensitive.js';
+import { applySpans } from '../../observability/spans.js';
+import { getProfile } from './profiles.js';
 const B64_PAD = 2;
 const B64_WORD = 4;
 const B64_TRIPLET = 3;
@@ -153,4 +153,4 @@ function sanitizeTurnBlobsForProfile(profileId, attachments, voice) {
     const limits = requireMediaLimits(getProfile(profileId));
     return sanitizeTurnBlobs(attachments, voice, limits);
 }
-export { assertAttachmentLimits, fileTooLargeMessage, mediaLimits, requireMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, sanitizeTurnBlobsForProfile, tooManyFilesMessage, turnTooLargeMessage, };
+export { assertAttachmentLimits, fileTooLargeMessage, requireMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, sanitizeTurnBlobsForProfile, tooManyFilesMessage, turnTooLargeMessage, };

package/esm/src/kernel/registry/catalog.d.ts

@@ -1,24 +1,31 @@
-import type { Catalog, GeminiInputKind, ImageAspectRatio, ImageSize, ModelCatalogEntry, ThinkingLevel } from '../types.js';
-declare const IMAGE_INPUT_MIMES: string[];
-declare const VOICE_INPUT_MIMES: string[];
-/** Default chat media caps. Host profiles may copy or override these limits. */
-declare const CHAT_MEDIA_LIMITS: {
-    readonly maxFiles: 10;
-    readonly maxBytes: number;
-    readonly maxTurnBytes: number;
-};
-/** Gemini Interactions inline MIME → part type. Profiles allowlist from this set. */
-declare const GEMINI_INPUT_KINDS: Record<string, GeminiInputKind>;
+/**
+ * Tool catalog and MIME helpers.
+ *
+ * Model wire metadata is host-owned on `profile.model.config`. This module only
+ * keeps builtin/custom tool descriptors and shared MIME utilities.
+ *
+ * @module
+ */
+import type { BuiltinToolId, Catalog, GeminiInputKind, ModelId, ModelSpec, Profile, ThinkingLevel, ToolCatalogEntry, ToolId } from '../types.js';
+/** Live tool catalog. Starts with harness tools; presets/hosts register more. */
+declare const CATALOG: Catalog;
+/** Register or replace tool descriptors (idempotent per id). */
+declare function registerTools(entries: Record<string, ToolCatalogEntry>): void;
+/** Look up one registered tool descriptor. */
+declare function getTool(id: ToolId): ToolCatalogEntry | undefined;
+/** Ids of all registered provider builtins. */
+declare function listBuiltinIds(): BuiltinToolId[];
+/** Restore harness-only tools (tests / host reloads). */
+declare function resetTools(): void;
 declare function mimeEssence(mime: string): string;
 declare function mimeAllowed(accept: string[], mime: string): boolean;
 declare function geminiKindForMime(mime: string): GeminiInputKind | undefined;
-declare const IMAGE_FLASH_LITE_ASPECT_RATIOS: ImageAspectRatio[];
-declare const IMAGE_FLASH_LITE_SIZES: ImageSize[];
-declare const CATALOG: Catalog;
-export { CATALOG, CHAT_MEDIA_LIMITS, GEMINI_INPUT_KINDS, geminiKindForMime, IMAGE_FLASH_LITE_ASPECT_RATIOS, IMAGE_FLASH_LITE_SIZES, IMAGE_INPUT_MIMES, mimeAllowed, mimeEssence, VOICE_INPUT_MIMES, };
-export declare const MODEL_CATALOG: Record<import("../types.js").ModelId, ModelCatalogEntry>;
-export declare function modelEntry(modelId: string): ModelCatalogEntry;
-/** Clamp a requested thinking level to what the selected model accepts. */
-export declare function clampThinkingLevel(modelId: string, level: ThinkingLevel): ThinkingLevel;
-export declare function modelEntryByApiId(apiId: string): ModelCatalogEntry | undefined;
-export declare function clampThinkingLevelForApiId(apiId: string, level: ThinkingLevel): ThinkingLevel;
+/** Require a host-declared model spec for an allowed profile model id. */
+declare function requireModelSpec(profile: Profile, modelId: ModelId): ModelSpec;
+/** Clamp a requested thinking level to what the model spec accepts. */
+declare function clampThinkingLevel(spec: ModelSpec, level: ThinkingLevel): ThinkingLevel;
+/** Look up a model spec by provider-native API id within a host specs map. */
+declare function modelEntryByApiId(specs: Record<string, ModelSpec>, apiId: string): ModelSpec | undefined;
+/** Clamp thinking level using a provider-native API id within a host specs map. */
+declare function clampThinkingLevelForApiId(specs: Record<string, ModelSpec>, apiId: string, level: ThinkingLevel): ThinkingLevel;
+export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, geminiKindForMime, getTool, listBuiltinIds, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, };

package/esm/src/kernel/registry/catalog.js

@@ -1,3 +1,12 @@
+/**
+ * Tool catalog and MIME helpers.
+ *
+ * Model wire metadata is host-owned on `profile.model.config`. This module only
+ * keeps builtin/custom tool descriptors and shared MIME utilities.
+ *
+ * @module
+ */
+import { TheorumError } from '../../guardrails/error.js';
 const ASK_USER_SCHEMA = {
     type: 'object',
     properties: {
@@ -7,23 +16,36 @@ const ASK_USER_SCHEMA = {
     },
     required: ['kind', 'prompt'],
 };
-const DEFAULT_TEMPERATURE = 1;
-const FLASH_LITE_MAX_OUTPUT_TOKENS = 8192;
-const PRO_PREVIEW_MAX_OUTPUT_TOKENS = 64_000;
-const IMAGE_FLASH_LITE_MAX_OUTPUT_TOKENS = 4096;
-const TTS_FLASH_MAX_OUTPUT_TOKENS = 2048;
-const SONAR_MAX_OUTPUT_TOKENS = 8192;
-const IMAGE_INPUT_MIMES = ['image/png', 'image/jpeg', 'image/webp', 'image/heic', 'image/heif'];
-const VOICE_INPUT_MIMES = ['audio/webm', 'audio/wav', 'audio/mpeg', 'audio/mp4'];
-const KIB = 1024;
-const MIB = KIB * KIB;
-/** Default chat media caps. Host profiles may copy or override these limits. */
-const CHAT_MEDIA_LIMITS = {
-    maxFiles: 10,
-    maxBytes: 8 * MIB,
-    maxTurnBytes: 32 * MIB,
+/** Harness tools that always ship with THEORUM. */
+const HARNESS_TOOLS = {
+    askUser: { kind: 'custom', ui: true, schema: ASK_USER_SCHEMA },
 };
-/** Gemini Interactions inline MIME → part type. Profiles allowlist from this set. */
+/** Live tool catalog. Starts with harness tools; presets/hosts register more. */
+const CATALOG = {
+    tools: { ...HARNESS_TOOLS },
+};
+/** Register or replace tool descriptors (idempotent per id). */
+function registerTools(entries) {
+    Object.assign(CATALOG.tools, entries);
+}
+/** Look up one registered tool descriptor. */
+function getTool(id) {
+    return CATALOG.tools[id];
+}
+/** Ids of all registered provider builtins. */
+function listBuiltinIds() {
+    return Object.entries(CATALOG.tools)
+        .filter(([, entry]) => entry.kind === 'builtin')
+        .map(([id]) => id);
+}
+/** Restore harness-only tools (tests / host reloads). */
+function resetTools() {
+    for (const id of Object.keys(CATALOG.tools)) {
+        delete CATALOG.tools[id];
+    }
+    Object.assign(CATALOG.tools, HARNESS_TOOLS);
+}
+/** Gemini Interactions inline MIME → part type (adapter wire map). */
 const GEMINI_INPUT_KINDS = {
     'image/png': 'image',
     'image/jpeg': 'image',
@@ -76,115 +98,13 @@ function mimeAllowed(accept, mime) {
 function geminiKindForMime(mime) {
     return GEMINI_INPUT_KINDS[mimeEssence(mime)];
 }
-const IMAGE_FLASH_LITE_ASPECT_RATIOS = [
-    '1:1',
-    '3:2',
-    '2:3',
-    '3:4',
-    '4:3',
-    '4:5',
-    '5:4',
-    '9:16',
-    '16:9',
-    '21:9',
-];
-const IMAGE_FLASH_LITE_SIZES = ['1K'];
-const FLASH_LITE_THINKING_LEVELS = ['minimal', 'low', 'medium', 'high'];
-const PRO_PREVIEW_THINKING_LEVELS = ['low', 'medium', 'high'];
-const IMAGE_FLASH_LITE_THINKING_LEVELS = ['minimal', 'high'];
-const TTS_THINKING_LEVELS = ['minimal'];
-const OPENROUTER_SEARCH_THINKING_LEVELS = ['low', 'medium', 'high'];
-const GENERIC_MODEL_ENTRY = {
-    apiId: '',
-    thinking: { on: 'high', off: 'low' },
-    thinkingLevels: ['low', 'medium', 'high'],
-    summaries: { on: 'auto', off: 'none' },
-    maxOutputTokens: FLASH_LITE_MAX_OUTPUT_TOKENS,
-    temperature: DEFAULT_TEMPERATURE,
-    freeBuiltins: [],
-};
-const CATALOG = {
-    models: {
-        gemini31FlashLite: {
-            apiId: 'gemini-3.1-flash-lite',
-            thinking: { on: 'high', off: 'minimal' },
-            thinkingLevels: FLASH_LITE_THINKING_LEVELS,
-            summaries: { on: 'auto', off: 'none' },
-            maxOutputTokens: FLASH_LITE_MAX_OUTPUT_TOKENS,
-            temperature: DEFAULT_TEMPERATURE,
-            freeBuiltins: ['googleMaps', 'urlContext'],
-        },
-        gemini31ProPreview: {
-            apiId: 'gemini-3.1-pro-preview',
-            thinking: { on: 'high', off: 'low' },
-            thinkingLevels: PRO_PREVIEW_THINKING_LEVELS,
-            summaries: { on: 'auto', off: 'none' },
-            maxOutputTokens: PRO_PREVIEW_MAX_OUTPUT_TOKENS,
-            temperature: DEFAULT_TEMPERATURE,
-            freeBuiltins: [],
-        },
-        gemini35FlashLite: {
-            apiId: 'gemini-3.5-flash-lite',
-            thinking: { on: 'high', off: 'minimal' },
-            thinkingLevels: FLASH_LITE_THINKING_LEVELS,
-            summaries: { on: 'auto', off: 'none' },
-            maxOutputTokens: FLASH_LITE_MAX_OUTPUT_TOKENS,
-            temperature: DEFAULT_TEMPERATURE,
-            freeBuiltins: ['googleMaps', 'urlContext'],
-        },
-        gemini31FlashLiteImage: {
-            apiId: 'gemini-3.1-flash-lite-image',
-            thinking: { on: 'high', off: 'minimal' },
-            thinkingLevels: IMAGE_FLASH_LITE_THINKING_LEVELS,
-            summaries: { on: 'none', off: 'none' },
-            maxOutputTokens: IMAGE_FLASH_LITE_MAX_OUTPUT_TOKENS,
-            temperature: DEFAULT_TEMPERATURE,
-            freeBuiltins: [],
-            image: {
-                maxInputImages: 14,
-                inputMimes: IMAGE_INPUT_MIMES,
-                sizes: IMAGE_FLASH_LITE_SIZES,
-                aspectRatios: IMAGE_FLASH_LITE_ASPECT_RATIOS,
-                outputMime: 'image/jpeg',
-                allowsGrounding: false,
-            },
-        },
-        gemini31FlashTts: {
-            apiId: 'gemini-3.1-flash-tts-preview',
-            thinking: { on: 'minimal', off: 'minimal' },
-            thinkingLevels: TTS_THINKING_LEVELS,
-            summaries: { on: 'none', off: 'none' },
-            maxOutputTokens: TTS_FLASH_MAX_OUTPUT_TOKENS,
-            temperature: DEFAULT_TEMPERATURE,
-            freeBuiltins: [],
-        },
-        sonar: {
-            apiId: 'sonar',
-            openRouterId: 'perplexity/sonar',
-            thinking: { on: 'high', off: 'low' },
-            thinkingLevels: OPENROUTER_SEARCH_THINKING_LEVELS,
-            summaries: { on: 'none', off: 'none' },
-            maxOutputTokens: SONAR_MAX_OUTPUT_TOKENS,
-            temperature: DEFAULT_TEMPERATURE,
-            freeBuiltins: [],
-        },
-    },
-    // Off until the turn sets tools[id]. Profile allow is only the ceiling.
-    tools: {
-        googleSearch: { kind: 'builtin', ui: true },
-        googleMaps: { kind: 'builtin', ui: true },
-        urlContext: { kind: 'builtin', ui: true },
-        askUser: { kind: 'custom', ui: true, schema: ASK_USER_SCHEMA },
-    },
-};
-export { CATALOG, CHAT_MEDIA_LIMITS, GEMINI_INPUT_KINDS, geminiKindForMime, IMAGE_FLASH_LITE_ASPECT_RATIOS, IMAGE_FLASH_LITE_SIZES, IMAGE_INPUT_MIMES, mimeAllowed, mimeEssence, VOICE_INPUT_MIMES, };
-export const MODEL_CATALOG = CATALOG.models;
-export function modelEntry(modelId) {
-    return (MODEL_CATALOG[modelId] ?? {
-        ...GENERIC_MODEL_ENTRY,
-        apiId: modelId,
-        openRouterId: modelId,
-    });
+/** Require a host-declared model spec for an allowed profile model id. */
+function requireModelSpec(profile, modelId) {
+    const spec = profile.model.config[modelId];
+    if (!spec) {
+        throw new TheorumError(`Profile ${profile.id} has no model spec for '${modelId}'`);
+    }
+    return spec;
 }
 function clampLevels(entry, level) {
     if (!entry?.thinkingLevels || entry.thinkingLevels.length === 0) {
@@ -200,14 +120,16 @@ function clampLevels(entry, level) {
     const first = entry.thinkingLevels[0];
     return first ?? level;
 }
-/** Clamp a requested thinking level to what the selected model accepts. */
-export function clampThinkingLevel(modelId, level) {
-    return clampLevels(modelEntry(modelId), level);
+/** Clamp a requested thinking level to what the model spec accepts. */
+function clampThinkingLevel(spec, level) {
+    return clampLevels(spec, level);
 }
-export function modelEntryByApiId(apiId) {
-    return Object.values(MODEL_CATALOG).find((m) => m.apiId === apiId);
+/** Look up a model spec by provider-native API id within a host specs map. */
+function modelEntryByApiId(specs, apiId) {
+    return Object.values(specs).find((m) => m.apiId === apiId);
 }
-export function clampThinkingLevelForApiId(apiId, level) {
-    const entry = modelEntryByApiId(apiId);
-    return clampLevels(entry, level);
+/** Clamp thinking level using a provider-native API id within a host specs map. */
+function clampThinkingLevelForApiId(specs, apiId, level) {
+    return clampLevels(modelEntryByApiId(specs, apiId), level);
 }
+export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, geminiKindForMime, getTool, listBuiltinIds, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, };

package/esm/src/kernel/registry/ingress.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Kernel ingress: input parts, image pins, and speech-role checks.
+ *
+ * Owned by the kernel so `resolveTurn` does not import provider adapters.
+ *
+ * @module
+ */
+import type { BuiltinToolId, ImageResponseFormat, InteractionPart, ModelId, Profile, TurnRequest } from '../types.js';
+declare function assertSpeechRole(profile: Profile): void;
+declare function resolveImageFormat(profile: Profile, _model: ModelId, slots?: Record<string, string>): ImageResponseFormat | null;
+declare function resolveInputParts(profile: Profile, model: ModelId, req: TurnRequest): InteractionPart[];
+declare function assertImageGrounding(profile: Profile, model: ModelId, builtins: BuiltinToolId[]): void;
+export { assertImageGrounding, assertSpeechRole, resolveImageFormat, resolveInputParts };

package/esm/src/kernel/registry/ingress.js

@@ -0,0 +1,163 @@
+/**
+ * Kernel ingress: input parts, image pins, and speech-role checks.
+ *
+ * Owned by the kernel so `resolveTurn` does not import provider adapters.
+ *
+ * @module
+ */
+import { TheorumError } from '../../guardrails/error.js';
+import { wrapUserData } from '../engine/boundary.js';
+import { synthesizeRepairPrompt } from '../engine/repair.js';
+import { assertAttachmentLimits, requireMediaLimits } from './attachments.js';
+import { geminiKindForMime, mimeAllowed, mimeEssence } from './catalog.js';
+function listedValue(allowed, value) {
+    if (!value) {
+        return undefined;
+    }
+    if (!allowed || allowed.length === 0) {
+        return value;
+    }
+    if (allowed.includes(value)) {
+        return value;
+    }
+    return undefined;
+}
+function resolveSlotOrPin(profileId, label, slotValue, pin, allow) {
+    if (slotValue !== undefined) {
+        const fromSlot = listedValue(allow, slotValue);
+        if (!fromSlot) {
+            throw new TheorumError(`Unknown image ${label} for ${profileId}`);
+        }
+        return fromSlot;
+    }
+    if (pin === undefined) {
+        return undefined;
+    }
+    const fromPin = listedValue(allow, pin);
+    if (!fromPin) {
+        throw new TheorumError(`Unknown image ${label} for ${profileId}`);
+    }
+    return fromPin;
+}
+function assertImageRole(profile) {
+    const pins = profile.outputs.image;
+    if (!pins) {
+        throw new TheorumError(`Profile ${profile.id} requests image output but does not set outputs.image`);
+    }
+    assertExclusiveNativeOutput(profile, 'image');
+    return pins;
+}
+function assertSpeechRole(profile) {
+    if (!profile.outputs.speech) {
+        return;
+    }
+    assertExclusiveNativeOutput(profile, 'speech');
+    if (profile.outputs.speech.format === 'mp3' && profile.model.protocol === 'geminiInteractions') {
+        throw new TheorumError(`Profile ${profile.id}: outputs.speech.format 'mp3' requires protocol 'openAi' ` +
+            `(geminiInteractions speech returns PCM and emits WAV)`);
+    }
+}
+function assertExclusiveNativeOutput(profile, kind) {
+    const other = kind === 'image' ? 'speech' : 'image';
+    if (profile.outputs[other]) {
+        throw new TheorumError(`Profile ${profile.id} cannot mix outputs.${kind} with outputs.${other}`);
+    }
+    if (profile.outputs.structured !== null && profile.outputs.structured !== undefined) {
+        throw new TheorumError(`Profile ${profile.id} cannot mix structured JSON with native ${kind} output`);
+    }
+}
+function resolveImageFormat(profile, _model, slots) {
+    if (!profile.outputs.image) {
+        return null;
+    }
+    const pins = assertImageRole(profile);
+    const aspectRatio = resolveSlotOrPin(profile.id, 'aspect', slots?.aspectRatio, pins.aspectRatio, profile.inputs.slots?.aspectRatio);
+    const size = resolveSlotOrPin(profile.id, 'size', slots?.size, pins.size, profile.inputs.slots?.size);
+    if (!(aspectRatio && size)) {
+        throw new TheorumError(`Unknown image aspect or size for ${profile.id}`);
+    }
+    return {
+        type: 'image',
+        mimeType: pins.mimeType ?? 'image/jpeg',
+        aspectRatio,
+        size,
+    };
+}
+function assertGeminiMime(mime) {
+    const kind = geminiKindForMime(mime);
+    if (!kind) {
+        throw new TheorumError(`MIME '${mime}' is not a Gemini input type`);
+    }
+    return kind;
+}
+function mediaParts(profile, model, blobs, channel) {
+    const accept = channel === 'voice' ? profile.inputs.voice?.accept : profile.inputs.attachments?.accept;
+    if (!accept) {
+        throw new TheorumError(`Profile ${profile.id} does not accept ${channel}`);
+    }
+    const maxInputImages = profile.outputs.image?.maxInputImages;
+    const imageCount = blobs.filter((blob) => geminiKindForMime(blob.mimeType) === 'image').length;
+    if (maxInputImages !== undefined && imageCount > maxInputImages) {
+        throw new TheorumError(`At most ${maxInputImages} reference images on ${model}`);
+    }
+    return blobs.map((blob) => {
+        const kind = assertGeminiMime(blob.mimeType);
+        if (!mimeAllowed(accept, blob.mimeType)) {
+            throw new TheorumError(`MIME '${blob.mimeType}' is not accepted on ${profile.id}`);
+        }
+        const essence = mimeEssence(blob.mimeType);
+        return {
+            type: kind,
+            mimeType: essence === 'image/jpg' ? 'image/jpeg' : essence,
+            data: blob.data,
+        };
+    });
+}
+function extractTextPart(profile, req) {
+    const { text, repair, history } = req.input ?? {};
+    if (profile.inputs.text === false) {
+        if (text) {
+            throw new TheorumError(`Profile ${profile.id} does not accept text input`);
+        }
+        return null;
+    }
+    let promptText = text;
+    if (repair) {
+        promptText = synthesizeRepairPrompt({ profile, repair, history });
+    }
+    if (!promptText) {
+        return null;
+    }
+    return { type: 'text', text: wrapUserData(promptText) };
+}
+function extractMediaParts(profile, model, req) {
+    const { attachments, voice } = req.input ?? {};
+    const files = attachments ?? [];
+    const clips = voice ?? [];
+    if (files.length + clips.length > 0) {
+        assertAttachmentLimits([...files, ...clips], requireMediaLimits(profile));
+    }
+    const parts = [];
+    if (files.length > 0) {
+        parts.push(...mediaParts(profile, model, files, 'attachments'));
+    }
+    if (clips.length > 0) {
+        parts.push(...mediaParts(profile, model, clips, 'voice'));
+    }
+    return parts;
+}
+function resolveInputParts(profile, model, req) {
+    const parts = [];
+    const textPart = extractTextPart(profile, req);
+    if (textPart) {
+        parts.push(textPart);
+    }
+    parts.push(...extractMediaParts(profile, model, req));
+    return parts;
+}
+function assertImageGrounding(profile, model, builtins) {
+    if (profile.outputs.image?.allowsGrounding === false && builtins.length > 0) {
+        throw new TheorumError(`Grounding tools are not valid on ${model}`);
+    }
+}
+export { assertImageGrounding, assertSpeechRole, resolveImageFormat, resolveInputParts };

package/esm/src/kernel/registry/profiles.d.ts

@@ -11,16 +11,14 @@ import type { Profile } from '../types.js';
 export type ProfileDefinition = {
     id: Profile['id'];
     identity?: Partial<Profile['identity']>;
-    model: Partial<Profile['model']> & Pick<Profile['model'], 'allow'>;
+    model: Partial<Profile['model']> & Pick<Profile['model'], 'allow' | 'config'>;
     tools?: Partial<Profile['tools']>;
     inputs?: Partial<Profile['inputs']>;
     outputs?: Partial<Profile['outputs']>;
     guardrails?: Partial<Profile['guardrails']>;
 };
-/** Backwards-compatible alias for callers using the older name. */
-export type DefineProfileInput = ProfileDefinition;
 /** Define a typed profile with stable defaults for optional properties. */
-declare function defineProfile(input: DefineProfileInput): Profile;
+declare function defineProfile(input: ProfileDefinition): Profile;
 /** Register one host-owned profile in the process-local registry. */
 declare function registerProfile(profileInput: Profile | ProfileDefinition): void;
 /** Register several host-owned profiles in order. */

package/esm/src/kernel/registry/profiles.js

@@ -8,6 +8,13 @@
  */
 import { TheorumError } from '../../guardrails/error.js';
 const profiles = new Map();
+function assertModelSpecs(profileId, allow, config) {
+    for (const id of allow) {
+        if (!config[id]) {
+            throw new TheorumError(`Profile ${profileId} allowlists '${id}' without a model spec`);
+        }
+    }
+}
 function buildDefaultIdentity(id, identity) {
     return {
         handle: identity?.handle ?? id,
@@ -16,17 +23,18 @@ function buildDefaultIdentity(id, identity) {
         systemByRole: identity?.systemByRole,
     };
 }
-function buildDefaultModel(model) {
+function buildDefaultModel(profileId, model) {
+    assertModelSpecs(profileId, model.allow, model.config);
     return {
         protocol: model.protocol ?? 'geminiInteractions',
         provider: model.provider ?? 'google',
         allow: model.allow,
+        config: model.config,
         thinking: model.thinking ?? 'minimal',
         controls: model.controls ?? [],
         maxSteps: model.maxSteps ?? 1,
         key: model.key ?? 'freeA',
         select: model.select,
-        override: model.override,
     };
 }
 function buildDefaultInputs(inputs) {
@@ -44,8 +52,8 @@ function buildDefaultInputs(inputs) {
 function buildDefaultOutputs(outputs) {
     return {
         structured: outputs?.structured ?? null,
-        media: outputs?.media ?? false,
-        voice: outputs?.voice,
+        image: outputs?.image,
+        speech: outputs?.speech,
         validation: outputs?.validation,
         streaming: outputs?.streaming,
     };
@@ -64,7 +72,7 @@ function defineProfile(input) {
     return {
         id: input.id,
         identity: buildDefaultIdentity(input.id, input.identity),
-        model: buildDefaultModel(input.model),
+        model: buildDefaultModel(input.id, input.model),
         tools: { allow: input.tools?.allow ?? [] },
         inputs: buildDefaultInputs(input.inputs),
         outputs: buildDefaultOutputs(input.outputs),
@@ -74,6 +82,7 @@ function defineProfile(input) {
 /** Register one host-owned profile in the process-local registry. */
 function registerProfile(profileInput) {
     const profile = defineProfile(profileInput);
+    assertModelSpecs(profile.id, profile.model.allow, profile.model.config);
     const { attachments, voice, maxFiles, maxBytes, maxTurnBytes } = profile.inputs;
     if (attachments || voice) {
         if (!(maxFiles && maxBytes && maxTurnBytes)) {

package/esm/src/kernel/registry/provider-request.d.ts

@@ -0,0 +1,4 @@
+import type { ProviderCompleteRequest, ResolvedGeneration } from '../types.js';
+/** Build the provider request projection shared by execution and tracing. */
+declare function providerCompleteRequest(generation: ResolvedGeneration, system: string): ProviderCompleteRequest;
+export { providerCompleteRequest };

package/esm/src/kernel/registry/provider-request.js

@@ -0,0 +1,25 @@
+/** Build the provider request projection shared by execution and tracing. */
+function providerCompleteRequest(generation, system) {
+    return {
+        model: generation.model,
+        apiId: generation.apiId,
+        openRouterId: generation.openRouterId,
+        previousInteractionId: generation.previousInteractionId,
+        store: generation.store,
+        thinking: generation.thinking,
+        summaries: generation.summaries,
+        maxOutputTokens: generation.maxOutputTokens,
+        temperature: generation.temperature,
+        builtins: generation.builtins,
+        system,
+        input: generation.input,
+        history: generation.history,
+        dynamicTools: generation.dynamicTools,
+        dynamicToolLoader: generation.dynamicToolLoader,
+        structured: generation.structured,
+        image: generation.image,
+        speech: generation.speech,
+        geminiBucket: generation.geminiBucket,
+    };
+}
+export { providerCompleteRequest };

package/esm/src/kernel/registry/resolve.d.ts

@@ -13,7 +13,6 @@ declare function resolveTurn(req: TurnRequest): {
     profile: Profile;
     generation: ResolvedGeneration;
 };
-/** UI projection: catalog ∩ profile. Swatches are not included. */
 /** Project a registered profile into a safe host/UI inspection object. */
 declare function projectProfile(id: Profile['id']): ProjectedProfile;
 declare function pickSystemRole(profile: Profile, requested?: string): string;