theorum 0.1.15 → 1.1.3

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

@@ -0,0 +1,231 @@
+/**
+ * Runtime vocabulary and field catalog for THEORUM profile types.
+ *
+ * Closed unions live here as `as const` arrays; TypeScript types are derived
+ * from those arrays. Host UIs and docs import this module (no Deno APIs) so
+ * dropdowns and hover tips stay in lockstep with the kernel.
+ *
+ * @module
+ */
+/** lexicon-exempt-file: authoring field-meta / closed unions — not runtime user or model copy (P2) */
+import { EGRESS_ON_BLOCK, type EgressOnBlock } from '../guardrails/types.js';
+export { EGRESS_ON_BLOCK, type EgressOnBlock };
+/** Primary profile archetype. Discriminated union key for `ProfileDefinition` and `Profile`. */
+export declare const PROFILE_TYPES: readonly ["text", "image", "speech", "live", "host"];
+export type ProfileType = (typeof PROFILE_TYPES)[number];
+/** Model reasoning effort level normalized across provider adapters. */
+export declare const THINKING_LEVELS: readonly ["none", "minimal", "low", "medium", "high", "xhigh", "max"];
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+/** Wire protocol for a profile. */
+export declare const PROTOCOLS: readonly ["geminiInteractions", "geminiLive", "openAi"];
+export type Protocol = (typeof PROTOCOLS)[number];
+/** Transport provider for a profile. */
+export declare const PROVIDERS: readonly ["google", "openrouter", "local"];
+export type Provider = (typeof PROVIDERS)[number];
+/**
+ * Legal `createProvider` pairs. Keep this table in lockstep with the factory.
+ * Keys are protocols; values are the providers that protocol may bind.
+ */
+export declare const PROTOCOL_PROVIDERS: {
+    readonly geminiInteractions: readonly ["google"];
+    readonly geminiLive: readonly ["google"];
+    readonly openAi: readonly ["openrouter", "local"];
+};
+/**
+ * Legal wire protocols for each profile archetype.
+ * 'live' profiles require 'geminiLive'; turn-based archetypes require turn protocols;
+ * 'host' never runs a model and binds no protocol.
+ */
+export declare const PROFILE_TYPE_PROTOCOLS: {
+    readonly text: readonly ["geminiInteractions", "openAi"];
+    readonly image: readonly ["geminiInteractions", "openAi"];
+    readonly speech: readonly ["geminiInteractions", "openAi"];
+    readonly live: readonly ["geminiLive"];
+    readonly host: readonly [];
+};
+export type ProfileTypeProtocol<T extends ProfileType> = (typeof PROFILE_TYPE_PROTOCOLS)[T][number];
+/** Protocols allowed for a profile archetype (`type`). */
+export declare function protocolsForProfileType(type: ProfileType): readonly Protocol[];
+/** True when the protocol is valid for the given profile archetype. */
+export declare function isValidProfileProtocol(type: ProfileType, protocol: Protocol): boolean;
+/** Named vault key slots for host-supplied credentials (provider-neutral). */
+export declare const KEY_SLOTS: readonly ["slotA", "slotB", "slotC", "paid"];
+export type KeySlot = (typeof KEY_SLOTS)[number];
+/** Key slots that may overflow to `paid` after quota backoff. */
+export declare const OVERFLOW_KEY_SLOTS: readonly ["slotA", "slotB", "slotC"];
+export type OverflowKeySlot = (typeof OVERFLOW_KEY_SLOTS)[number];
+/** Host vault: one optional credential string per key slot. */
+export type KeyVault = Record<KeySlot, string | undefined>;
+/** Profile-level control a caller may toggle at turn time. */
+/** Normalized multimodal part category. */
+export declare const MEDIA_INPUT_KIND_VALUES: readonly ["image", "audio", "video", "document"];
+export type MediaInputKind = (typeof MEDIA_INPUT_KIND_VALUES)[number];
+/** Provider thinking-summary behavior. */
+export declare const SUMMARY_MODES: readonly ["auto", "none"];
+export type SummaryMode = (typeof SUMMARY_MODES)[number];
+/** Stream delivery mode. */
+export declare const STREAM_MODES: readonly ["sse", "buffered"];
+export type StreamMode = (typeof STREAM_MODES)[number];
+/** Audio container for speech generation output. */
+export declare const SPEECH_AUDIO_FORMATS: readonly ["pcm", "mp3"];
+export type SpeechAudioFormat = (typeof SPEECH_AUDIO_FORMATS)[number];
+/** Speech `format` values legal for a wire protocol (`assertSpeechRole` / UI). */
+export declare function speechFormatsForProtocol(protocol: Protocol): readonly SpeechAudioFormat[];
+export declare function isSpeechFormatAllowedForProtocol(protocol: Protocol, format: SpeechAudioFormat): boolean;
+/** Snap an illegal or omitted format to the first legal value for the protocol. */
+export declare function coerceSpeechFormat(protocol: Protocol, format: SpeechAudioFormat | undefined): SpeechAudioFormat;
+/** Live session activity handling (barge-in behavior). */
+export declare const LIVE_ACTIVITY_HANDLINGS: readonly ["START_OF_ACTIVITY_INTERRUPTS", "NO_INTERRUPTION"];
+export type LiveActivityHandling = (typeof LIVE_ACTIVITY_HANDLINGS)[number];
+/** Live session voice activity detection sensitivity. */
+export declare const LIVE_SPEECH_SENSITIVITIES: readonly ["START_SENSITIVITY_LOW", "START_SENSITIVITY_HIGH", "END_SENSITIVITY_LOW", "END_SENSITIVITY_HIGH"];
+export type LiveSpeechSensitivity = (typeof LIVE_SPEECH_SENSITIVITIES)[number];
+/** Live session context window compression mode. */
+export declare const LIVE_CONTEXT_COMPRESSIONS: readonly ["slidingWindow", "none"];
+export type LiveContextCompression = (typeof LIVE_CONTEXT_COMPRESSIONS)[number];
+/** Structured-output enforcement mode. */
+export declare const SCHEMA_ENFORCEMENTS: readonly ["responseFormat", "prompt"];
+export type SchemaEnforcement = (typeof SCHEMA_ENFORCEMENTS)[number];
+/** Compaction threshold meter. */
+export declare const COMPACTION_METERS: readonly ["history", "input"];
+export type CompactionMeter = (typeof COMPACTION_METERS)[number];
+/** When compaction runs relative to the primary turn. */
+export declare const COMPACTION_TIMINGS: readonly ["before", "after"];
+export type CompactionTiming = (typeof COMPACTION_TIMINGS)[number];
+/** OpenRouter prompt-cache mode (models.*.cache.mode). */
+export declare const CACHE_MODES: readonly ["automatic", "system"];
+export type CacheMode = (typeof CACHE_MODES)[number];
+/** OpenRouter ephemeral cache TTL (models.*.cache.ttl). */
+export declare const CACHE_TTLS: readonly ["5m", "1h"];
+export type CacheTtl = (typeof CACHE_TTLS)[number];
+/** Why a turn ended (provider-neutral). */
+export declare const TURN_STOP_KINDS: readonly ["completed", "length", "tool", "gate", "filtered", "provider_error", "cancelled", "stream_incomplete", "interrupted", "generation_complete"];
+export type TurnStopKind = (typeof TURN_STOP_KINDS)[number];
+/**
+ * Stop kinds eligible for `continueFrom` / resumption allowlists.
+ * Excludes terminal-success, user abort, tool/gate suspension, filter, and live-only
+ * boundaries — those use other host paths (or are not resumeable).
+ */
+export declare const CONTINUE_STOP_KINDS: readonly ["length", "stream_incomplete", "provider_error"];
+export type ContinueStopKind = (typeof CONTINUE_STOP_KINDS)[number];
+/**
+ * Turn / utterance-cycle timeline stages (`docs/contracts/stages.md`).
+ * Replaces the former steer barriers (`pre_llm` / `pre_tool_followup`).
+ */
+export declare const TURN_STAGES: readonly ["pre_turn", "pre_tool", "post_tool", "before_end", "post_turn"];
+export type TurnStage = (typeof TURN_STAGES)[number];
+/** True when `value` is a known `TurnStage`. */
+export declare function isTurnStage(value: unknown): value is TurnStage;
+/** Stages where inject is physically meaningful (still requires inject gate). */
+export declare const TURN_INJECT_STAGES: readonly ["pre_turn", "post_tool", "before_end"];
+export type TurnInjectStage = (typeof TURN_INJECT_STAGES)[number];
+/** True when inject is physically meaningful at this stage (gate still required). */
+export declare function isTurnInjectStage(value: unknown): value is TurnInjectStage;
+/** `pre_tool` gate kinds — confirm-to-run / permission / auth. Not awaiting. */
+export declare const TOOL_GATE_KINDS: readonly ["confirmation", "permission", "auth"];
+export type ToolGateKind = (typeof TOOL_GATE_KINDS)[number];
+/** True when `value` is a known tool-gate kind. */
+export declare function isToolGateKind(value: unknown): value is ToolGateKind;
+/** `awaiting_user_input.kind` — harness ask_user / human-as-product completions. */
+export declare const AWAITING_USER_INPUT_KINDS: readonly ["confirm", "choice", "text"];
+export type AwaitingUserInputKind = (typeof AWAITING_USER_INPUT_KINDS)[number];
+/** Discriminator on tool output for awaiting completions. */
+export declare const AWAITING_USER_INPUT_STATUS: "awaiting_user_input";
+/** Per-tool visibility tier — enforced by the kernel at resolve time. */
+export declare const TOOL_LOAD_TIERS: readonly ["T0", "T1", "T2"];
+export type ToolLoadTier = (typeof TOOL_LOAD_TIERS)[number];
+/** HTTP verbs supported by declarative HTTP tools. */
+export declare const HTTP_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE"];
+export type HttpMethod = (typeof HTTP_METHODS)[number];
+/** When remote tool auth is missing or expired. */
+export declare const AUTH_UNAUTHENTICATED_POLICIES: readonly ["pause", "report_to_model"];
+export type AuthUnauthenticatedPolicy = (typeof AUTH_UNAUTHENTICATED_POLICIES)[number];
+/** Registered tool discriminant (`registerTool`). */
+export declare const TOOL_TYPES: readonly ["builtin", "function", "http", "mcp"];
+/** Semantic access level — host policy / UI; not enforced by execute. */
+export declare const TOOL_ACCESS: readonly ["read-only", "read-write", "destructive"];
+export type ToolAccess = (typeof TOOL_ACCESS)[number];
+/** Execution authorization tier for registered tools. */
+export declare const TOOL_PERMISSION: readonly ["auto", "session_consent", "always_confirm"];
+export type ToolPermission = (typeof TOOL_PERMISSION)[number];
+/** Credential attachment modes for HTTP and MCP tools (`auth.type`). */
+export declare const TOOL_AUTH_TYPES: readonly ["bearer", "api_key", "oauth2"];
+export type ToolAuthType = (typeof TOOL_AUTH_TYPES)[number];
+/** Playground auth select — includes UI-only `none` (omits auth at compile time). */
+export declare const PLAYGROUND_AUTH_TYPES: readonly ["none", "bearer", "api_key", "oauth2"];
+export type PlaygroundAuthType = (typeof PLAYGROUND_AUTH_TYPES)[number];
+export type ToolType = (typeof TOOL_TYPES)[number];
+/** Custom registerTool discriminants (excludes provider builtins). */
+export type CustomToolType = Exclude<ToolType, 'builtin'>;
+/**
+ * MIME essence → normalized media part category.
+ *
+ * This table is the complete media-input vocabulary of the package: every MIME
+ * any supported transport may carry on a turn appears here exactly once, and
+ * nothing else is a media input type. `assertMediaMime` (`registry/ingress.ts`)
+ * refuses anything absent from it, so hosts declare what they accept in
+ * `inputs.attachments.accept` / `inputs.voice.accept` and keep no second table.
+ *
+ * Contents are the union of the documented provider input lists:
+ * - Google Interactions / Live (image, audio, video, document lists verified
+ *   2026-09-12) — the widest of the three and therefore the table's shape. The
+ *   document row is Google's document-understanding list in full: PDF, plain
+ *   text, HTML, CSS, Markdown (`text/md`), CSV, XML, RTF, JavaScript
+ *   (`text/javascript`, `application/x-javascript`) and Python
+ *   (`text/x-python`, `application/x-python`); `application/json` is an
+ *   established row alongside it. TypeScript, `application/xml` and
+ *   `application/rtf` are NOT on Google's list and are therefore not rows.
+ * - OpenRouter / OpenAI-compat (`providers/openrouter/openai/compat.ts`,
+ *   `sdk-messages.ts`): the adapters wire every `MediaInputKind` (image →
+ *   `image_url`/`image`, audio → `input_audio`, video and document → `file`)
+ *   and forward the part's MIME verbatim, so their accepted set is open-ended
+ *   and adds no rows. What they cannot carry — a `uri` reference part — is
+ *   refused at request time with `TheorumError`, not by a second MIME list.
+ *
+ * Alias essences that providers also emit (`image/jpg`, `video/mov`,
+ * `audio/x-wav`, `video/x-ms-wmv`, …) are rows here; `resolveInputParts`
+ * canonicalizes `image/jpg` to `image/jpeg` on the wire.
+ */
+export declare const MEDIA_INPUT_KINDS: Record<string, MediaInputKind>;
+/** Type-prefix wildcards accepted by `mimeAllowed`. */
+export declare const MEDIA_WILDCARDS: readonly ["image/*", "audio/*", "video/*"];
+/** Attachment `accept` values the kernel can classify (wildcards + known types). */
+export declare const ATTACHMENT_ACCEPT_MIMES: readonly string[];
+/** Voice `accept` values the kernel can classify (wildcard + known audio types). */
+export declare const VOICE_ACCEPT_MIMES: readonly string[];
+/** Providers allowed for a protocol. */
+export declare function providersFor(protocol: Protocol): readonly Provider[];
+/** Protocols allowed for a provider. */
+export declare function protocolsFor(provider: Provider): readonly Protocol[];
+/** True when `createProvider` will accept this pair. */
+export declare function isValidPair(protocol: Protocol, provider: Provider): boolean;
+/** When protocol changes, snap provider to a valid partner. */
+export declare function coerceProvider(protocol: Protocol, provider: Provider): Provider;
+/** When provider changes, snap protocol to a valid partner. */
+export declare function coerceProtocol(protocol: Protocol, provider: Provider): Protocol;
+/** Metadata for one profile (or adjacent) field, used by docs/UI hover. */
+export type FieldMeta = {
+    type: string;
+    doc: string;
+    options?: readonly string[];
+    optionDescriptions?: Record<string, string>;
+    optionNote?: string;
+};
+/**
+ * Parents whose next key is a host-owned map key (model id, slot name, …).
+ * The annotator substitutes `*` so `models.flash.apiId` → `models.*.apiId`.
+ */
+export declare const DYNAMIC_FIELD_PARENTS: ReadonlySet<string>;
+/** Resolve a key stack from authored source into a catalog path. */
+export declare function catalogPathFor(keys: readonly string[]): string;
+/**
+ * Authoring-surface catalog for `Profile` / `defineProfile`.
+ * Hover UIs look up dotted paths. Adding a profile field? Add it here.
+ */
+export declare const PROFILE_FIELDS: Record<string, FieldMeta>;
+/** Adjacent tool catalog fields that appear next to profile examples. */
+export declare const EXTRA_FIELDS: Record<string, FieldMeta>;
+/** Look up hover metadata for a dotted path (profile first, then extra). */
+export declare function fieldMeta(path: string): FieldMeta | undefined;
+export type { ProfileGraphEditor, ProfileGraphFacet, ProfileGraphFacetId, ProfileGraphRole, } from './profile-graph.js';
+export { PROFILE_GRAPH, profileGraphFacet, spineFacetsForProfileType, } from './profile-graph.js';