theorum 0.1.13 → 0.1.14

package/docs/presets-google.md

@@ -0,0 +1,91 @@
+# Google preset (`theorum/presets/google`)
+
+Google / Gemini convenience pack: grounding builtins plus typed vocabularies
+for image and speech-adjacent profile fields.
+
+## Export
+
+| Field | Value |
+| --- | --- |
+| Import | `theorum/presets/google` / `jsr:@theorum/core/presets/google` |
+| Module | `src/presets/google.ts` |
+
+## Ownership
+
+| Path | Role |
+| --- | --- |
+| `src/presets/google.ts` | Google builtins + vocabularies |
+
+## Builtins
+
+`registerGooglePreset()` registers:
+
+| Id | Notes |
+| --- | --- |
+| `googleSearch` | Interactions `google_search`; OpenRouter plugin `web` |
+| `googleMaps` | Interactions `google_maps`; conflicts with `googleSearch` and `urlContext` |
+| `urlContext` | Interactions `url_context` |
+
+All are `kind: 'builtin'` with `ui: true`. Profiles must allowlist ids they use;
+`conflictsWith` drops maps when search/urlContext are also requested.
+
+## Vocabularies
+
+Constants (and matching types) for host profile authoring:
+
+| Constant | Purpose |
+| --- | --- |
+| `GOOGLE_IMAGE_INPUT_MIMES` | png / jpeg / webp / heic / heif |
+| `GOOGLE_VOICE_INPUT_MIMES` | webm / wav / mpeg / mp4 |
+| `GOOGLE_IMAGE_ASPECT_RATIOS` / `GOOGLE_IMAGE_SIZES` | Image output pins |
+| `GOOGLE_SPEECH_VOICES` | TTS voice names for `outputs.speech.voice` |
+| `GoogleImageAspectRatio`, `GoogleImageInputMime`, `GoogleImageSize`, `GoogleVoiceInputMime` | Typed vocabulary unions |
+| `GoogleImagePins`, `GoogleSpeechPins`, `GoogleSpeechVoice` | Typed pins assignable to kernel specs |
+
+Kernel types stay stringly; these packs make Google hosts typed when they opt in.
+
+## Exported API
+
+| Export | Role |
+| --- | --- |
+| `registerGooglePreset` | Register builtins into catalog |
+| `GOOGLE_BUILTIN_TOOLS` | Static catalog entries |
+| `GOOGLE_IMAGE_ASPECT_RATIOS`, `GOOGLE_IMAGE_INPUT_MIMES`, `GOOGLE_IMAGE_SIZES`, `GOOGLE_VOICE_INPUT_MIMES`, `GOOGLE_SPEECH_VOICES` | Typed profile authoring constants |
+| `GoogleImageAspectRatio`, `GoogleImageInputMime`, `GoogleImageSize`, `GoogleVoiceInputMime`, `GoogleImagePins`, `GoogleSpeechPins`, `GoogleSpeechVoice` | Typed pins and vocabularies |
+
+```theorum-evidence
+{
+  "sections": {
+    "Export": {
+      "supports": [
+        { "kind": "source", "path": "src/presets/google.ts" },
+        { "kind": "config", "path": "package.json" }
+      ]
+    },
+    "Ownership": {
+      "supports": [
+        { "kind": "source", "path": "src/presets/google.ts" },
+        { "kind": "graph", "path": "docs/_map.mjs" }
+      ]
+    },
+    "Builtins": {
+      "supports": [
+        { "kind": "source", "path": "src/presets/google.ts" },
+        { "kind": "contract_test", "path": "tests/kernel/theorum.test.ts" }
+      ]
+    },
+    "Vocabularies": {
+      "supports": [
+        { "kind": "source", "path": "src/presets/google.ts" },
+        { "kind": "contract_test", "path": "tests/kernel/theorum.test.ts" }
+      ]
+    },
+    "Exported API": {
+      "supports": [
+        { "kind": "source", "path": "src/presets/google.ts" },
+        { "kind": "source", "path": "src/presets/mod.ts" }
+      ]
+    }
+  }
+}
+```

package/docs/presets.md

@@ -0,0 +1,88 @@
+# Presets (`theorum/presets`)
+
+Optional convenience packs. Presets register host-convenience catalogs
+(provider builtins, media vocabularies) without baking product opinions into the
+kernel.
+
+## Export
+
+| Field | Value |
+| --- | --- |
+| Import | `theorum/presets` / `jsr:@theorum/core/presets` |
+| Module | `src/presets/mod.ts` |
+
+## Ownership
+
+| Path | Role |
+| --- | --- |
+| `src/presets/mod.ts` | Barrel re-exporting the Google pack |
+| `src/presets/google.ts` | Documented in [`GOOGLE.md`](./GOOGLE.md) |
+
+## Role in the package
+
+| Concern | Kernel | Preset |
+| --- | --- | --- |
+| Tool ids | `string` allowlist | Registers `googleSearch`, `googleMaps`, `urlContext` |
+| Image/speech pins | Open `string` fields | Typed constants (`GOOGLE_IMAGE_SIZES`, voices, …) |
+| Registration | `registerTools` API | `registerGooglePreset()` at host startup |
+
+Call preset registration **before** registering profiles that allowlist preset
+builtins. Import `theorum/presets/google` when you only need the Google pack.
+
+Presets are optional — the kernel runs without them when hosts register their
+own tools and vocabularies directly via `registerTools`.
+
+## When to use
+
+| Use preset | Skip preset |
+| --- | --- |
+| Google Gemini hosts wanting typed pins + search/maps/url builtins | Custom tool catalog entirely host-owned |
+| Quick start matching Google Interactions wire types | Non-Google providers only |
+
+## Exported API
+
+This barrel re-exports the Google pack:
+
+| Export | Role |
+| --- | --- |
+| `registerGooglePreset` | Register Google builtins into `CATALOG` |
+| `GOOGLE_BUILTIN_TOOLS` | Catalog entries |
+| `GOOGLE_IMAGE_ASPECT_RATIOS`, `GOOGLE_IMAGE_INPUT_MIMES`, `GOOGLE_IMAGE_SIZES`, `GOOGLE_VOICE_INPUT_MIMES` | Profile authoring constants |
+| `GoogleImageAspectRatio`, `GoogleImageInputMime`, `GoogleImagePins`, `GoogleImageSize`, `GoogleVoiceInputMime` | Typed pins and vocabularies |
+
+```theorum-evidence
+{
+  "sections": {
+    "Export": {
+      "supports": [
+        { "kind": "source", "path": "src/presets/mod.ts" },
+        { "kind": "config", "path": "package.json" }
+      ]
+    },
+    "Ownership": {
+      "supports": [
+        { "kind": "source", "path": "src/presets/mod.ts" },
+        { "kind": "graph", "path": "docs/_map.mjs" }
+      ]
+    },
+    "Role in the package": {
+      "supports": [
+        { "kind": "source", "path": "src/presets/mod.ts" },
+        { "kind": "contract_test", "path": "tests/kernel/theorum.test.ts" }
+      ]
+    },
+    "When to use": {
+      "supports": [
+        { "kind": "source", "path": "src/presets/google.ts" },
+        { "kind": "contract_test", "path": "tests/kernel/theorum.test.ts" }
+      ]
+    },
+    "Exported API": {
+      "supports": [
+        { "kind": "source", "path": "src/presets/mod.ts" },
+        { "kind": "doc", "path": "src/presets/GOOGLE.md" }
+      ]
+    }
+  }
+}
+```

package/docs/providers.md

@@ -0,0 +1,201 @@
+# Providers (`theorum/providers`)
+
+Single door for constructing a `ModelProvider` bound to a profile. Credentials
+and runtime endpoints are always host-supplied arguments — THEORUM does not read
+environment variables and does not ship `.env` files.
+
+## Export
+
+| Field | Value |
+| --- | --- |
+| Import | `theorum/providers` / `jsr:@theorum/core/providers` |
+| Module | `src/providers/mod.ts` |
+| Also on | Root `theorum` re-exports `createProvider` |
+
+## Ownership
+
+Owns every module under `src/providers/` **except** OpenRouter-specific modules
+in [`OPENROUTER.md`](./OPENROUTER.md).
+
+| Module | Role (internal) |
+| --- | --- |
+| `create-provider.ts` | Public factory + lazy OpenRouter chat wrapper |
+| `provider.ts` | Google Interactions streaming adapter |
+| `interactions.ts` | Interactions payload / step wiring |
+| `speech.ts` | OpenRouter `/audio/speech` + Interactions audio paths |
+| `local.ts` | OpenAI-compat SSE for Ollama / llama.cpp / vLLM / LM Studio |
+| `keys.ts` | Gemini vault transport types |
+| `sse.ts` | Shared SSE line parser |
+| `pcm.ts` | PCM → WAV for Interactions speech output |
+| `gemini-tape.ts` / `google-tap.ts` | Test / tap hooks (not public exports) |
+| `expose-for-tests.ts` | `THEORUM_TEST_INTERNALS=1` gated test surface |
+
+## Package boundary
+
+| Rule | Detail |
+| --- | --- |
+| No `.env` in repo | Hosts pass credentials explicitly |
+| No ambient env reads | `OLLAMA_HOST` resolved by host → `local.baseUrl` |
+| No key templates | Business apps own secret storage |
+| Traces | Host-injected on `runTurn`, not here |
+
+## createProvider
+
+```ts
+const provider = createProvider(profile, {
+  gemini: { vault: { freeA, freeB, freeC, paid }, fetch? },
+  openRouter: { apiKey, baseUrl?, siteUrl?, siteName?, fetch?, modelMap?, voice? },
+  local: { baseUrl?, fetch? },
+})
+```
+
+Routing table:
+
+| protocol | provider | Requires | Transport |
+| --- | --- | --- | --- |
+| `geminiInteractions` | `google` | `options.gemini` | Interactions API (chat / image / speech) |
+| `openAi` | `openrouter` | `options.openRouter` | Lazy chat adapter or `speech.ts` when `outputs.speech` |
+| `openAi` | `local` | optional `options.local` | `POST /v1/chat/completions` SSE |
+
+Errors:
+
+- Missing credential block → `TheorumError` naming the required option.
+- Unsupported pair → `TheorumError` with protocol/provider in the message.
+
+OpenRouter Vercel AI SDK loads **only** on first `complete` for `openAi` +
+`openrouter` chat. Google and local never import it.
+
+## Google Interactions
+
+`createInteractionsProvider(geminiTransport)` streams normalized `TurnEvent`s.
+
+| Concern | Behavior |
+| --- | --- |
+| History | `user_input` / `model_output` steps |
+| Multimodal | `image` / `audio` / `video` / `document` parts |
+| Structured | `responseFormat` JSON schema when enforced |
+| Output modes | Image / speech / structured are mutually exclusive |
+| Tools | Catalog `interactionsType` + plugins |
+| Stop | `turnStopFromInteractionStatus` on terminal status |
+
+## Local provider
+
+`createLocalProvider` / `DEFAULT_LOCAL_BASE_URL` (`http://127.0.0.1:11434`). Hosts
+resolve `OLLAMA_HOST` (or similar) themselves and pass `baseUrl` here — THEORUM
+does not read environment variables for local endpoints (see module header in
+`local.ts`, not `docs/SECRETS.md`).
+
+```ts
+local: {
+  baseUrl: "http://127.0.0.1:11434", // no trailing slash
+  fetch: customFetch,
+}
+```
+
+- Raw `fetch` + `sse.ts` — no SDK.
+- Accumulates streaming tool calls; maps `finish_reason` through
+  `turnStopFromOpenRouter`.
+- Supports multimodal user content when the server accepts OpenAI-style parts.
+
+## Speech roles
+
+When `profile.outputs.speech` is defined and protocol/provider is OpenRouter
+OpenAI, `createProvider` returns `createSpeechProvider`:
+
+| Transport | Path | Notes |
+| --- | --- | --- |
+| OpenAI | `/audio/speech` | `mp3` allowed via `response_format` |
+| Interactions | audio `responseFormat` | PCM → WAV; `mp3` rejected at resolve |
+
+Fallback `openRouter.voice` when `outputs.speech.voice` omitted.
+
+## Gemini transport
+
+```ts
+createProvider(profile, {
+  gemini: { vault: { freeA, freeB, freeC, paid } },
+})
+```
+
+| Piece | Role |
+| --- | --- |
+| `GeminiTransport` | Vault + optional `fetch` |
+| Buckets | `freeA`, `freeB`, `freeC`, `paid` |
+| Selection | `model.key` / `ModelSpec.key` / `keyBuiltins` |
+
+Overflow to `paid` is host policy, not inferred here.
+
+## Exported API
+
+From `src/providers/mod.ts` only:
+
+| Export | Kind |
+| --- | --- |
+| `createProvider` | function |
+| `CreateProviderOptions` | type |
+| `GeminiTransport`, `GeminiVault` | types |
+| `createLocalProvider` | function |
+| `LocalProviderConfig` | type |
+| `DEFAULT_LOCAL_BASE_URL` | const |
+
+```theorum-evidence
+{
+  "sections": {
+    "Export": {
+      "supports": [
+        { "kind": "source", "path": "src/providers/mod.ts" },
+        { "kind": "config", "path": "package.json" }
+      ]
+    },
+    "Ownership": {
+      "supports": [
+        { "kind": "source", "path": "src/providers/mod.ts" },
+        { "kind": "graph", "path": "docs/_map.mjs" }
+      ]
+    },
+    "Package boundary": {
+      "supports": [
+        { "kind": "source", "path": "src/providers/create-provider.ts" },
+        { "kind": "contract_test", "path": "tests/providers/create-provider.test.ts" }
+      ]
+    },
+    "createProvider": {
+      "supports": [
+        { "kind": "source", "path": "src/providers/create-provider.ts" },
+        { "kind": "contract_test", "path": "tests/providers/create-provider.test.ts" }
+      ]
+    },
+    "Google Interactions": {
+      "supports": [
+        { "kind": "source", "path": "src/providers/provider.ts" },
+        { "kind": "source", "path": "src/providers/interactions.ts" },
+        { "kind": "contract_test", "path": "tests/providers/interactions.test.ts" }
+      ]
+    },
+    "Local provider": {
+      "supports": [
+        { "kind": "source", "path": "src/providers/local.ts" },
+        { "kind": "contract_test", "path": "tests/providers/local.test.ts" }
+      ]
+    },
+    "Speech roles": {
+      "supports": [
+        { "kind": "source", "path": "src/providers/speech.ts" },
+        { "kind": "contract_test", "path": "tests/providers/speech.test.ts" }
+      ]
+    },
+    "Gemini transport": {
+      "supports": [
+        { "kind": "source", "path": "src/providers/keys.ts" },
+        { "kind": "contract_test", "path": "tests/providers/keys.test.ts" }
+      ]
+    },
+    "Exported API": {
+      "supports": [
+        { "kind": "source", "path": "src/providers/mod.ts" },
+        { "kind": "contract_test", "path": "tests/providers/create-provider.test.ts" }
+      ]
+    }
+  }
+}
+```

package/docs/streaming.md

@@ -0,0 +1,96 @@
+# Streaming (`theorum/streaming`)
+
+Structured-output streaming helpers and turn-stop classification re-exports for
+hosts that want a narrow import without taking the full kernel barrel.
+
+## Export
+
+| Field | Value |
+| --- | --- |
+| Import | `theorum/streaming` / `jsr:@theorum/core/streaming` |
+| Module | `src/streaming/mod.ts` |
+
+## Ownership
+
+| Path | Role |
+| --- | --- |
+| `src/streaming/readStreamingJsonStringField.ts` | Incomplete JSON string preview |
+| `src/streaming/mod.ts` | Barrel + stop re-exports |
+
+Stop source of truth: [`../kernel/CONTRACT.md`](../kernel/CONTRACT.md)
+(`src/kernel/stop.ts`).
+
+## Streaming JSON preview
+
+`readStreamingJsonStringField(jsonText, key)` reads one string field from
+**incomplete** JSON while structured output streams as text deltas.
+
+```ts
+const preview = readStreamingJsonStringField(buffer, "mermaid");
+// returns decoded prefix even before closing quote
+```
+
+| Behavior | Detail |
+| --- | --- |
+| Locator | `"key": "` pattern |
+| Escapes | `\n`, `\t`, `\uXXXX`, … |
+| Incomplete buffer | Returns prefix for live UI preview |
+| Missing key | `null` |
+
+Does not validate full JSON documents.
+
+## Stop re-exports
+
+| Category | Exports |
+| --- | --- |
+| Types | `TurnStop`, `TurnStopKind`, `TurnContinueFrom`, `ProfileResumeSpec` |
+| Constants | `CONTINUE_INSTRUCTION`, `DEFAULT_AUTO_CONTINUE`, `AUTO_CONTINUE_DELAY_MS` |
+| Helpers | `isResumeableStop`, `shouldAutoContinue`, `isUserCancelledStop`, mappers |
+| Errors | `GenerationStopError`, `isGenerationStopError` |
+
+Behavioral contract: kernel **Stop and resume** section.
+
+## Exported API
+
+| Group | Symbols |
+| --- | --- |
+| Streaming JSON | `readStreamingJsonStringField` |
+| Stop / resume (re-export from `kernel/stop.ts`) | `ProfileResumeSpec`, `TurnContinueFrom`, `TurnStop`, `TurnStopKind`, `AUTO_CONTINUE_DELAY_MS`, `CONTINUE_INSTRUCTION`, `DEFAULT_AUTO_CONTINUE`, `GenerationStopError`, `isGenerationStopError`, `isResumeableStop`, `isUserCancelledStop`, `shouldAutoContinue`, `turnStopFromClientStreamEnd`, `turnStopFromInteractionStatus`, `turnStopFromOpenRouter` |
+
+```theorum-evidence
+{
+  "sections": {
+    "Export": {
+      "supports": [
+        { "kind": "source", "path": "src/streaming/mod.ts" },
+        { "kind": "config", "path": "package.json" }
+      ]
+    },
+    "Ownership": {
+      "supports": [
+        { "kind": "source", "path": "src/streaming/mod.ts" },
+        { "kind": "graph", "path": "docs/_map.mjs" }
+      ]
+    },
+    "Streaming JSON preview": {
+      "supports": [
+        { "kind": "source", "path": "src/streaming/readStreamingJsonStringField.ts" },
+        { "kind": "contract_test", "path": "tests/streaming/readStreamingJsonStringField.test.ts" }
+      ]
+    },
+    "Stop re-exports": {
+      "supports": [
+        { "kind": "source", "path": "src/streaming/mod.ts" },
+        { "kind": "source", "path": "src/kernel/stop.ts" },
+        { "kind": "contract_test", "path": "tests/streaming/turnStop.test.ts" }
+      ]
+    },
+    "Exported API": {
+      "supports": [
+        { "kind": "source", "path": "src/streaming/mod.ts" },
+        { "kind": "contract_test", "path": "tests/streaming/readStreamingJsonStringField.test.ts" }
+      ]
+    }
+  }
+}
+```

package/esm/mod.d.ts

@@ -44,7 +44,7 @@ export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, }
 export type { CompactionSplit, CompactionTokens } from './src/kernel/engine/compaction.js';
 export { compactionMeter, compactionNeeded, estimateHistoryTokens, HISTORY_MEDIA_TOKENS, HISTORY_TEXT_ENCODING, resolveCompactionTokens, resolveHistoryTokens, shouldCompact, splitForCompaction, } from './src/kernel/engine/compaction.js';
 export { runTurn } from './src/kernel/engine/runner.js';
-export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, geminiKindForMime, getTool, listBuiltinIds, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './src/kernel/registry/catalog.js';
+export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, getTool, listBuiltinIds, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './src/kernel/registry/catalog.js';
 export type { ProfileDefinition } from './src/kernel/registry/profiles.js';
 export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './src/kernel/registry/profiles.js';
 export { projectProfile, resolveTurn } from './src/kernel/registry/resolve.js';

package/esm/mod.js

@@ -42,7 +42,7 @@ export { clientIp, quotaMessage, releaseSlot, resetSlots, skipQuota, takeSlot, }
 export { PROJECT_ID_MAX, sanitizeProjectId, sanitizeText, sanitizeTurnRequest, } from './src/guardrails/sanitize.js';
 export { compactionMeter, compactionNeeded, estimateHistoryTokens, HISTORY_MEDIA_TOKENS, HISTORY_TEXT_ENCODING, resolveCompactionTokens, resolveHistoryTokens, shouldCompact, splitForCompaction, } from './src/kernel/engine/compaction.js';
 export { runTurn } from './src/kernel/engine/runner.js';
-export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, geminiKindForMime, getTool, listBuiltinIds, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './src/kernel/registry/catalog.js';
+export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, getTool, listBuiltinIds, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './src/kernel/registry/catalog.js';
 export { clearProfiles, defineProfile, getProfile, hasProfile, listProfiles, registerProfile, registerProfiles, } from './src/kernel/registry/profiles.js';
 export { projectProfile, resolveTurn } from './src/kernel/registry/resolve.js';
 export { getStructured, registerStructured } from './src/kernel/registry/schemas.js';

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

@@ -11,7 +11,7 @@ import "../../_dnt.polyfills.js";
 export type { CompactionSplit, CompactionTokens } from './engine/compaction.js';
 export { compactionMeter, compactionNeeded, estimateHistoryTokens, HISTORY_MEDIA_TOKENS, HISTORY_TEXT_ENCODING, resolveCompactionTokens, resolveHistoryTokens, shouldCompact, splitForCompaction, } from './engine/compaction.js';
 export { runTurn } from './engine/runner.js';
-export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, geminiKindForMime, getTool, listBuiltinIds, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './registry/catalog.js';
+export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, getTool, listBuiltinIds, mediaKindForMime, mimeAllowed, mimeEssence, 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';

package/esm/src/kernel/mod.js

@@ -10,7 +10,7 @@
 import "../../_dnt.polyfills.js";
 export { compactionMeter, compactionNeeded, estimateHistoryTokens, HISTORY_MEDIA_TOKENS, HISTORY_TEXT_ENCODING, resolveCompactionTokens, resolveHistoryTokens, shouldCompact, splitForCompaction, } from './engine/compaction.js';
 export { runTurn } from './engine/runner.js';
-export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, geminiKindForMime, getTool, listBuiltinIds, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, } from './registry/catalog.js';
+export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, getTool, listBuiltinIds, mediaKindForMime, mimeAllowed, mimeEssence, 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';

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

@@ -6,7 +6,7 @@
  *
  * @module
  */
-import type { BuiltinToolId, Catalog, GeminiInputKind, ModelId, ModelSpec, Profile, ThinkingLevel, ToolCatalogEntry, ToolId } from '../types.js';
+import type { BuiltinToolId, Catalog, MediaInputKind, 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). */
@@ -19,7 +19,7 @@ declare function listBuiltinIds(): BuiltinToolId[];
 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 function mediaKindForMime(mime: string): MediaInputKind | undefined;
 /** 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. */
@@ -28,4 +28,4 @@ declare function clampThinkingLevel(spec: ModelSpec, level: ThinkingLevel): Thin
 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, };
+export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, getTool, listBuiltinIds, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, };

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

@@ -45,8 +45,8 @@ function resetTools() {
     }
     Object.assign(CATALOG.tools, HARNESS_TOOLS);
 }
-/** Gemini Interactions inline MIME → part type (adapter wire map). */
-const GEMINI_INPUT_KINDS = {
+/** MIME essence → normalized media part category (shared ingress map). */
+const MEDIA_INPUT_KINDS = {
     'image/png': 'image',
     'image/jpeg': 'image',
     'image/jpg': 'image',
@@ -95,8 +95,8 @@ function mimeAllowed(accept, mime) {
         return allowed === actual;
     });
 }
-function geminiKindForMime(mime) {
-    return GEMINI_INPUT_KINDS[mimeEssence(mime)];
+function mediaKindForMime(mime) {
+    return MEDIA_INPUT_KINDS[mimeEssence(mime)];
 }
 /** Require a host-declared model spec for an allowed profile model id. */
 function requireModelSpec(profile, modelId) {
@@ -132,4 +132,4 @@ function modelEntryByApiId(specs, apiId) {
 function clampThinkingLevelForApiId(specs, apiId, level) {
     return clampLevels(modelEntryByApiId(specs, apiId), level);
 }
-export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, geminiKindForMime, getTool, listBuiltinIds, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, };
+export { CATALOG, clampThinkingLevel, clampThinkingLevelForApiId, getTool, listBuiltinIds, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, };

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

@@ -9,7 +9,7 @@ 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';
+import { mediaKindForMime, mimeAllowed, mimeEssence } from './catalog.js';
 function listedValue(allowed, value) {
     if (!value) {
         return undefined;
@@ -83,10 +83,10 @@ function resolveImageFormat(profile, _model, slots) {
         size,
     };
 }
-function assertGeminiMime(mime) {
-    const kind = geminiKindForMime(mime);
+function assertMediaMime(mime) {
+    const kind = mediaKindForMime(mime);
     if (!kind) {
-        throw new TheorumError(`MIME '${mime}' is not a Gemini input type`);
+        throw new TheorumError(`MIME '${mime}' is not a supported media input type`);
     }
     return kind;
 }
@@ -96,12 +96,12 @@ function mediaParts(profile, model, blobs, channel) {
         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;
+    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}`);
     }
     return blobs.map((blob) => {
-        const kind = assertGeminiMime(blob.mimeType);
+        const kind = assertMediaMime(blob.mimeType);
         if (!mimeAllowed(accept, blob.mimeType)) {
             throw new TheorumError(`MIME '${blob.mimeType}' is not accepted on ${profile.id}`);
         }

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

@@ -21,8 +21,8 @@ export type CustomToolId = HarnessToolId | (string & Record<never, never>);
 export type ToolId = BuiltinToolId | CustomToolId;
 /** Id of a host-registered structured output schema. */
 export type StructuredSchemaId = string;
-/** Interactions inline part types Gemini accepts besides text. */
-export type GeminiInputKind = 'image' | 'audio' | 'video' | 'document';
+/** Normalized multimodal part category (image, audio, video, document). */
+export type MediaInputKind = 'image' | 'audio' | 'video' | 'document';
 /** Host-owned profile identifier. */
 export type ProfileId = string;
 /** Named Gemini key bucket used by host-provided transports. */
@@ -354,7 +354,7 @@ export interface InteractionTextPart {
 }
 /** Inline media part sent to provider adapters after MIME validation. */
 export interface InteractionMediaPart {
-    type: GeminiInputKind;
+    type: MediaInputKind;
     mimeType: string;
     data: string;
 }

package/esm/src/providers/local.d.ts

@@ -6,7 +6,7 @@
  * normalized `TurnEvent` objects. No external SDK dependency — raw fetch + SSE.
  *
  * Hosts pass `baseUrl` explicitly. THEORUM does not read `OLLAMA_HOST` or other
- * environment variables (see docs/SECRETS.md).
+ * environment variables (see src/providers/CONTRACT.md).
  *
  * @module
  */

package/esm/src/providers/local.js

@@ -6,7 +6,7 @@
  * normalized `TurnEvent` objects. No external SDK dependency — raw fetch + SSE.
  *
  * Hosts pass `baseUrl` explicitly. THEORUM does not read `OLLAMA_HOST` or other
- * environment variables (see docs/SECRETS.md).
+ * environment variables (see src/providers/CONTRACT.md).
  *
  * @module
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "theorum",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, dynamic tools, provider adapters, guardrails, and host-injected traces.",
   "keywords": [
     "agent",