theorum 1.0.0 → 1.1.3

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

@@ -8,8 +8,9 @@
 import { wrapUserData } from '../../guardrails/canary.js';
 import { TheorumError } from '../../guardrails/error.js';
 import { synthesizeRepairPrompt } from '../engine/repair.js';
-import { assertAttachmentLimits, requireMediaLimits } from './attachments.js';
-import { mediaKindForMime, mimeAllowed, mimeEssence } from './catalog.js';
+import { isSpeechFormatAllowedForProtocol } from '../schema.js';
+import { assertAttachmentLimits, isTurnMediaRef, requireMediaLimits } from './attachments.js';
+import { mediaKindForMime, mimeAllowed, mimeEssence, profileAccept, } from './catalog.js';
 import { getStructured } from './schemas.js';
 function usesStructuredResponseFormat(structuredId) {
     if (!structuredId) {
@@ -41,22 +42,29 @@ function assertOutputMode(profile, structuredId) {
     if (active.length <= 1) {
         return;
     }
-    throw new TheorumError(`Profile ${profile.id} declares multiple output wire formats (${active.join(', ')}). ` +
-        `Only one of responseFormat JSON schema (outputs.structured with enforced ` +
+    throw new TheorumError(`Profile ${profile.id} declares multiple output wire formats (${active.join(', ')}). ` + // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        `Only one of responseFormat JSON schema (outputs.structured with enforced ` + // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         `'responseFormat'), image, or speech may be active.`);
 }
 function assertImagePins(profile) {
     if (profile.type !== 'image') {
-        throw new TheorumError(`Profile ${profile.id} is not type 'image'`);
+        throw new TheorumError(`Profile ${profile.id} is not type 'image'`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     return profile.image;
 }
+function defaultBinding(profile) {
+    const ids = Object.keys(profile.models);
+    const id = profile.defaultModel ?? (ids.length === 1 ? ids[0] : undefined);
+    return id ? profile.models[id] : undefined;
+}
 function assertSpeechRole(profile) {
     if (profile.type !== 'speech') {
         return;
     }
-    if (profile.speech.format === 'mp3' && profile.model.protocol === 'geminiInteractions') {
-        throw new TheorumError(`Profile ${profile.id}: speech.format 'mp3' requires protocol 'openAi' ` +
+    const format = profile.speech.format;
+    const binding = defaultBinding(profile);
+    if (format && binding && !isSpeechFormatAllowedForProtocol(binding.protocol, format)) {
+        throw new TheorumError(`Profile ${profile.id}: speech.format '${format}' requires protocol 'openAi' ` + // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
             `(geminiInteractions speech returns PCM and emits WAV)`);
     }
 }
@@ -76,45 +84,49 @@ function resolveImageFormat(profile) {
 function assertMediaMime(mime) {
     const kind = mediaKindForMime(mime);
     if (!kind) {
-        throw new TheorumError(`MIME '${mime}' is not a supported media input type`);
+        throw new TheorumError(`MIME '${mime}' is not a supported media input type`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     return kind;
 }
 function profileInputs(profile) {
-    if (profile.type === 'speech') {
+    if (profile.type === 'speech' || profile.type === 'live' || profile.type === 'host') {
         return undefined;
     }
     return profile.inputs;
 }
+/**
+ * Normalize accepted attachments into provider parts. Inline blobs and
+ * references share MIME acceptance and kind resolution; references carry the
+ * uri through untouched (no base64, no byte limits — the host owns the upload).
+ */
 function mediaParts(profile, model, blobs, channel) {
-    const inputs = profileInputs(profile);
-    const accept = channel === 'voice' ? inputs?.voice?.accept : inputs?.attachments?.accept;
+    const accept = profileAccept(profile, channel);
     if (!accept) {
-        throw new TheorumError(`Profile ${profile.id} does not accept ${channel}`);
+        throw new TheorumError(`Profile ${profile.id} does not accept ${channel}`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     const maxInputImages = profile.type === 'image' ? profile.image.maxInputImages : undefined;
     const imageCount = blobs.filter((blob) => mediaKindForMime(blob.mimeType) === 'image').length;
     if (maxInputImages !== undefined && imageCount > maxInputImages) {
-        throw new TheorumError(`At most ${maxInputImages} reference images on ${model}`);
+        throw new TheorumError(`At most ${maxInputImages} reference images on ${model}`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     return blobs.map((blob) => {
         const kind = assertMediaMime(blob.mimeType);
         if (!mimeAllowed(accept, blob.mimeType)) {
-            throw new TheorumError(`MIME '${blob.mimeType}' is not accepted on ${profile.id}`);
+            throw new TheorumError(`MIME '${blob.mimeType}' is not accepted on ${profile.id}`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         }
         const essence = mimeEssence(blob.mimeType);
-        return {
-            type: kind,
-            mimeType: essence === 'image/jpg' ? 'image/jpeg' : essence,
-            data: blob.data,
-        };
+        const mimeType = essence === 'image/jpg' ? 'image/jpeg' : essence;
+        if (isTurnMediaRef(blob)) {
+            return { type: kind, mimeType, uri: blob.uri };
+        }
+        return { type: kind, mimeType, data: blob.data };
     });
 }
 function extractTextPart(profile, req) {
     const { text, repair, history } = req.input ?? {};
     if (profile.type === 'speech') {
         if (!text?.trim()) {
-            throw new TheorumError(`Profile ${profile.id} (speech) requires text input`);
+            throw new TheorumError(`Profile ${profile.id} (speech) requires text input`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         }
         let promptText = text;
         if (repair) {
@@ -125,7 +137,7 @@ function extractTextPart(profile, req) {
     const inputs = profileInputs(profile);
     if (inputs?.text === false) {
         if (text) {
-            throw new TheorumError(`Profile ${profile.id} does not accept text input`);
+            throw new TheorumError(`Profile ${profile.id} does not accept text input`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         }
         return null;
     }
@@ -142,7 +154,7 @@ function extractMediaParts(profile, model, req) {
     if (profile.type === 'speech') {
         const { attachments, voice } = req.input ?? {};
         if ((attachments?.length ?? 0) + (voice?.length ?? 0) > 0) {
-            throw new TheorumError(`Profile ${profile.id} (speech) does not accept media input`);
+            throw new TheorumError(`Profile ${profile.id} (speech) does not accept media input`); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
         }
         return [];
     }

package/esm/src/kernel/registry/profile-outputs.d.ts

@@ -0,0 +1,4 @@
+import type { Profile, ProfileOutputsSpec } from '../types.js';
+/** Turn-based `outputs` pins — absent on `type: 'live'` and `type: 'host'`. */
+declare function profileTurnOutputs(profile: Profile): ProfileOutputsSpec | undefined;
+export { profileTurnOutputs };

package/esm/src/kernel/registry/profile-outputs.js

@@ -0,0 +1,8 @@
+/** Turn-based `outputs` pins — absent on `type: 'live'` and `type: 'host'`. */
+function profileTurnOutputs(profile) {
+    if (profile.type === 'live' || profile.type === 'host') {
+        return undefined;
+    }
+    return profile.outputs;
+}
+export { profileTurnOutputs };

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

@@ -2,45 +2,65 @@
  * Runtime profile registry for host-owned THEORUM profiles.
  *
  * THEORUM ships profile types — not application profiles and not invented defaults.
- * Hosts must pass required fields explicitly (`type`, `model.protocol`, `model.provider`, …).
+ * Hosts must pass required fields explicitly (`type`, `models`, …).
  *
  * @module
  */
-import type { ImageProfile, LiveProfile, LiveProfileModelSpec, Profile, ProfileGuardrailsSpec, ProfileIdentity, ProfileInputsSpec, ProfileModelSpec, ProfileOutputsSpec, ProfileToolsSpec, ProfileTurnResumptionSpec, SpeechProfile, TurnProfileModelSpec } from '../types.js';
-export type ProfileDefinitionBase<P extends ProfileModelSpec = ProfileModelSpec> = {
+import { type HostGuardrailsSpec, type ProfileGuardrailsSpec } from '../../guardrails/types.js';
+import type { ProfileObservabilitySpec } from '../../observability/types.js';
+import type { HostProfile, HostProfileToolsSpec, ImageProfile, LiveProfile, LiveProfileToolsSpec, ModelBinding, ModelId, Profile, ProfileIdentity, ProfileInputsSpec, ProfileModelFields, ProfileOutputsSpec, ProfileToolsSpec, ProfileTurnBehaviourSpec, SpeechProfile } from '../types.js';
+export type ProfileDefinitionBase = {
     id: Profile['id'];
     identity: ProfileIdentity;
-    model: P;
+    models: Record<ModelId, ModelBinding>;
+    defaultModel?: ModelId;
+    allowModelSelect?: boolean;
+    maxSteps?: number;
+    key?: ProfileModelFields['key'];
     outputs?: ProfileOutputsSpec;
     guardrails?: ProfileGuardrailsSpec;
+    observability?: ProfileObservabilitySpec;
 };
-export type TextProfileDefinition = ProfileDefinitionBase<TurnProfileModelSpec> & {
+export type TextProfileDefinition = ProfileDefinitionBase & {
     type: 'text';
     tools: ProfileToolsSpec;
     inputs: ProfileInputsSpec;
-    turnResumption?: ProfileTurnResumptionSpec;
+    turnBehaviour?: ProfileTurnBehaviourSpec;
 };
-export type ImageProfileDefinition = ProfileDefinitionBase<TurnProfileModelSpec> & {
+export type ImageProfileDefinition = ProfileDefinitionBase & {
     type: 'image';
     image: NonNullable<ImageProfile['image']>;
     tools: ProfileToolsSpec;
     inputs: ProfileInputsSpec;
-    turnResumption?: ProfileTurnResumptionSpec;
+    turnBehaviour?: ProfileTurnBehaviourSpec;
 };
-export type SpeechProfileDefinition = ProfileDefinitionBase<TurnProfileModelSpec> & {
+export type SpeechProfileDefinition = ProfileDefinitionBase & {
     type: 'speech';
     speech: NonNullable<SpeechProfile['speech']>;
-    turnResumption?: ProfileTurnResumptionSpec;
+    turnBehaviour?: ProfileTurnBehaviourSpec;
 };
-export type LiveProfileDefinition = ProfileDefinitionBase<LiveProfileModelSpec> & {
+export type LiveProfileDefinition = ProfileDefinitionBase & {
     type: 'live';
     live: NonNullable<LiveProfile['live']>;
-    tools: ProfileToolsSpec;
-    inputs?: ProfileInputsSpec;
+    tools: LiveProfileToolsSpec;
+    /** Inject gate only — resumption is `live.sessionResumption`. */
+    turnBehaviour?: Pick<ProfileTurnBehaviourSpec, 'allowSteering'>;
+};
+/** Host-driven tool ceiling — no models, identity, inputs, outputs, turnBehaviour, key, or maxSteps. */
+export type HostProfileDefinition = {
+    type: 'host';
+    id: Profile['id'];
+    tools: HostProfileToolsSpec;
+    /** Only the guards that fire on the `invokeTool` path — see {@link HostGuardrailsSpec}. */
+    guardrails?: HostGuardrailsSpec;
+    observability?: ProfileObservabilitySpec;
 };
 /** Host-authored profile definition — discriminated on `type`. No THEORUM defaults. */
-export type ProfileDefinition = TextProfileDefinition | ImageProfileDefinition | SpeechProfileDefinition | LiveProfileDefinition;
+export type ProfileDefinition = TextProfileDefinition | ImageProfileDefinition | SpeechProfileDefinition | LiveProfileDefinition | HostProfileDefinition;
 /** Define a typed profile. Required fields must be set explicitly; optional fields stay optional. */
+declare function defineProfile(input: LiveProfileDefinition): LiveProfile;
+declare function defineProfile(input: HostProfileDefinition): HostProfile;
+declare function defineProfile(input: Exclude<ProfileDefinition, LiveProfileDefinition | HostProfileDefinition>): Exclude<Profile, LiveProfile | HostProfile>;
 declare function defineProfile(input: ProfileDefinition): Profile;
 /** Register one host-owned profile in the process-local registry. */
 declare function registerProfile(profileInput: Profile | ProfileDefinition): void;