theorum 0.1.15 → 1.1.3

package/esm/src/kernel/profile-graph.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Profile graph — playground / authoring topology projected from PROFILE_FIELDS.
+ *
+ * This is not runtime policy. It declares which profile sections are graph
+ * facets, for which ProfileType, whether they may be omitted, and whether the
+ * host UI uses a schema form or a structural editor. The playground must import
+ * this catalog; it must not invent FacetKind unions.
+ *
+ * @module
+ */
+import type { ProfileType } from './schema.js';
+/** How the playground (or other host UI) should edit this facet. */
+export type ProfileGraphEditor = 'schema' | 'structural';
+/** Where the facet sits in the authoring graph. */
+export type ProfileGraphRole = 'root' | 'spine' | 'branch';
+/**
+ * Authoring-graph catalog. Adding a profile section? Add PROFILE_FIELDS and a row
+ * here — never a FacetKind in the frontend.
+ *
+ * `ProfileGraphFacetId` is derived from this array; do not maintain a union by hand.
+ */
+declare const PROFILE_GRAPH_DEF: readonly [{
+    readonly id: "identity";
+    readonly profilePath: "identity";
+    readonly role: "root";
+    readonly profileTypes: readonly ("text" | "image" | "speech" | "live" | "host")[];
+    readonly optional: false;
+    readonly editor: "structural";
+    readonly label: "Identity";
+    readonly ownsFields: readonly ["id", "type"];
+}, {
+    readonly id: "models";
+    readonly profilePath: "models";
+    readonly role: "spine";
+    readonly profileTypes: readonly ("text" | "image" | "speech" | "live" | "host")[];
+    readonly optional: false;
+    readonly editor: "structural";
+    readonly label: "Models";
+    readonly ownsFields: readonly ["defaultModel", "allowModelSelect", "maxSteps", "key"];
+}, {
+    readonly id: "modelBinding";
+    readonly profilePath: "models.*";
+    readonly role: "branch";
+    readonly parent: "models";
+    readonly profileTypes: readonly ("text" | "image" | "speech" | "live" | "host")[];
+    readonly optional: false;
+    readonly editor: "structural";
+    readonly label: "Model binding";
+}, {
+    readonly id: "image";
+    readonly profilePath: "image";
+    readonly role: "spine";
+    readonly profileTypes: readonly ["image"];
+    readonly optional: false;
+    readonly editor: "structural";
+    readonly label: "Image";
+}, {
+    readonly id: "speech";
+    readonly profilePath: "speech";
+    readonly role: "spine";
+    readonly profileTypes: readonly ["speech"];
+    readonly optional: false;
+    readonly editor: "structural";
+    readonly label: "Speech";
+}, {
+    readonly id: "live";
+    readonly profilePath: "live";
+    readonly role: "spine";
+    readonly profileTypes: readonly ["live"];
+    readonly optional: false;
+    readonly editor: "structural";
+    readonly label: "Live";
+}, {
+    readonly id: "tools";
+    readonly profilePath: "tools";
+    readonly role: "spine";
+    readonly profileTypes: readonly ["text", "image", "live", "host"];
+    readonly optional: false;
+    readonly editor: "structural";
+    readonly label: "Tools";
+}, {
+    readonly id: "toolSpec";
+    readonly profilePath: "tools.allow";
+    readonly role: "branch";
+    readonly parent: "tools";
+    readonly profileTypes: readonly ["text", "image", "live", "host"];
+    readonly optional: true;
+    readonly editor: "structural";
+    readonly label: "Tool";
+}, {
+    readonly id: "inputs";
+    readonly profilePath: "inputs";
+    readonly role: "spine";
+    readonly profileTypes: readonly ["text", "image"];
+    readonly optional: false;
+    readonly editor: "structural";
+    readonly label: "Inputs";
+}, {
+    readonly id: "outputs";
+    readonly profilePath: "outputs";
+    readonly role: "spine";
+    readonly profileTypes: readonly ["text", "image", "speech"];
+    readonly optional: true;
+    readonly editor: "structural";
+    readonly label: "Outputs";
+}, {
+    readonly id: "turnBehaviour";
+    readonly profilePath: "turnBehaviour";
+    readonly role: "spine";
+    readonly profileTypes: readonly ["text", "image", "speech", "live"];
+    readonly optional: true;
+    readonly editor: "structural";
+    readonly label: "Turn behaviour";
+}, {
+    readonly id: "guardrails";
+    readonly profilePath: "guardrails";
+    readonly role: "spine";
+    readonly profileTypes: readonly ("text" | "image" | "speech" | "live" | "host")[];
+    readonly optional: true;
+    readonly editor: "structural";
+    readonly label: "Guardrails";
+}, {
+    readonly id: "observability";
+    readonly profilePath: "observability";
+    readonly role: "spine";
+    readonly profileTypes: readonly ("text" | "image" | "speech" | "live" | "host")[];
+    readonly optional: true;
+    readonly editor: "structural";
+    readonly label: "Observability";
+}];
+/** Stable facet ids — derived from PROFILE_GRAPH; never hand-maintained. */
+export type ProfileGraphFacetId = (typeof PROFILE_GRAPH_DEF)[number]['id'];
+/**
+ * One node kind on the profile authoring graph.
+ *
+ * `profilePath` is a PROFILE_FIELDS key (section root) or a dynamic path
+ * (`models.*`). Branch facets nest under `parent`.
+ */
+export interface ProfileGraphFacet {
+    id: ProfileGraphFacetId;
+    profilePath: string;
+    role: ProfileGraphRole;
+    parent?: ProfileGraphFacetId;
+    profileTypes: readonly ProfileType[];
+    optional: boolean;
+    editor: ProfileGraphEditor;
+    label: string;
+    /**
+     * Extra PROFILE_FIELDS top-level keys owned by this facet (not 1:1 with id).
+     * Used by the drift gate so `defaultModel` / `id` / `type` are not orphaned.
+     */
+    ownsFields?: readonly string[];
+}
+export declare const PROFILE_GRAPH: readonly ProfileGraphFacet[];
+/** Spine (and root) facets visible for a profile type, in catalog order. */
+declare function spineFacetsForProfileType(type: ProfileType): ProfileGraphFacet[];
+/** Look up a graph facet by id. */
+declare function profileGraphFacet(id: ProfileGraphFacetId): ProfileGraphFacet | undefined;
+export { profileGraphFacet, spineFacetsForProfileType };

package/esm/src/kernel/profile-graph.js

@@ -0,0 +1,156 @@
+/**
+ * Profile graph — playground / authoring topology projected from PROFILE_FIELDS.
+ *
+ * This is not runtime policy. It declares which profile sections are graph
+ * facets, for which ProfileType, whether they may be omitted, and whether the
+ * host UI uses a schema form or a structural editor. The playground must import
+ * this catalog; it must not invent FacetKind unions.
+ *
+ * @module
+ */
+/**
+ * Mirrors PROFILE_TYPES — value import would cycle through schema re-exports.
+ * Drift is gated by tests/kernel/profile-graph.test.ts.
+ */
+const ALL = ['text', 'image', 'speech', 'live', 'host'];
+/** Types that bind models — `host` never runs a model. */
+const MODEL_TYPES = ['text', 'image', 'speech', 'live'];
+/**
+ * Authoring-graph catalog. Adding a profile section? Add PROFILE_FIELDS and a row
+ * here — never a FacetKind in the frontend.
+ *
+ * `ProfileGraphFacetId` is derived from this array; do not maintain a union by hand.
+ */
+const PROFILE_GRAPH_DEF = [
+    {
+        id: 'identity',
+        profilePath: 'identity',
+        role: 'root',
+        profileTypes: ALL,
+        optional: false,
+        editor: 'structural',
+        label: 'Identity',
+        ownsFields: ['id', 'type'],
+    },
+    {
+        id: 'models',
+        profilePath: 'models',
+        role: 'spine',
+        profileTypes: MODEL_TYPES,
+        optional: false,
+        editor: 'structural',
+        label: 'Models',
+        ownsFields: ['defaultModel', 'allowModelSelect', 'maxSteps', 'key'],
+    },
+    {
+        id: 'modelBinding',
+        profilePath: 'models.*',
+        role: 'branch',
+        parent: 'models',
+        profileTypes: MODEL_TYPES,
+        optional: false,
+        editor: 'structural',
+        label: 'Model binding',
+    },
+    {
+        id: 'image',
+        profilePath: 'image',
+        role: 'spine',
+        profileTypes: ['image'],
+        optional: false,
+        editor: 'structural',
+        label: 'Image',
+    },
+    {
+        id: 'speech',
+        profilePath: 'speech',
+        role: 'spine',
+        profileTypes: ['speech'],
+        optional: false,
+        editor: 'structural',
+        label: 'Speech',
+    },
+    {
+        id: 'live',
+        profilePath: 'live',
+        role: 'spine',
+        profileTypes: ['live'],
+        optional: false,
+        editor: 'structural',
+        label: 'Live',
+    },
+    {
+        id: 'tools',
+        profilePath: 'tools',
+        role: 'spine',
+        profileTypes: ['text', 'image', 'live', 'host'],
+        optional: false,
+        editor: 'structural',
+        label: 'Tools',
+    },
+    {
+        id: 'toolSpec',
+        profilePath: 'tools.allow',
+        role: 'branch',
+        parent: 'tools',
+        profileTypes: ['text', 'image', 'live', 'host'],
+        optional: true,
+        editor: 'structural',
+        label: 'Tool',
+    },
+    {
+        id: 'inputs',
+        profilePath: 'inputs',
+        role: 'spine',
+        profileTypes: ['text', 'image'],
+        optional: false,
+        editor: 'structural',
+        label: 'Inputs',
+    },
+    {
+        id: 'outputs',
+        profilePath: 'outputs',
+        role: 'spine',
+        profileTypes: ['text', 'image', 'speech'],
+        optional: true,
+        editor: 'structural',
+        label: 'Outputs',
+    },
+    {
+        id: 'turnBehaviour',
+        profilePath: 'turnBehaviour',
+        role: 'spine',
+        profileTypes: ['text', 'image', 'speech', 'live'],
+        optional: true,
+        editor: 'structural',
+        label: 'Turn behaviour',
+    },
+    {
+        id: 'guardrails',
+        profilePath: 'guardrails',
+        role: 'spine',
+        profileTypes: ALL,
+        optional: true,
+        editor: 'structural',
+        label: 'Guardrails',
+    },
+    {
+        id: 'observability',
+        profilePath: 'observability',
+        role: 'spine',
+        profileTypes: ALL,
+        optional: true,
+        editor: 'structural',
+        label: 'Observability',
+    },
+];
+export const PROFILE_GRAPH = PROFILE_GRAPH_DEF;
+/** Spine (and root) facets visible for a profile type, in catalog order. */
+function spineFacetsForProfileType(type) {
+    return PROFILE_GRAPH.filter((facet) => (facet.role === 'root' || facet.role === 'spine') && facet.profileTypes.includes(type));
+}
+/** Look up a graph facet by id. */
+function profileGraphFacet(id) {
+    return PROFILE_GRAPH.find((facet) => facet.id === id);
+}
+export { profileGraphFacet, spineFacetsForProfileType };

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

@@ -1,16 +1,18 @@
-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;
+import type { MediaLimits, MimeInputs, Profile, TurnBlob, TurnMediaRef } from '../types.js';
+declare function resolveMediaLimits(inputs: MimeInputs): MediaLimits | undefined;
+declare function maxBytesForMime(mimeType: string, limits: MediaLimits): number;
+/** Attachment supplied by provider file reference — no bytes to size-check or sanitize. */
+declare function isTurnMediaRef(item: TurnBlob | TurnMediaRef): item is TurnMediaRef;
 declare function requireMediaLimits(profile: Profile): MediaLimits;
 declare function sanitizeCsvText(text: string): string;
-declare function assertAttachmentLimits(blobs: TurnBlob[], limits: MediaLimits): void;
-declare function sanitizeTurnBlobs(attachments: TurnBlob[] | undefined, voice: TurnBlob[] | undefined, limits: MediaLimits | undefined): {
-    attachments?: TurnBlob[];
+/** Enforce file count on every attachment; base64 and byte limits only on inline blobs. */
+declare function assertAttachmentLimits(attachments: Array<TurnBlob | TurnMediaRef>, limits: MediaLimits): void;
+declare function sanitizeTurnBlobs(attachments: Array<TurnBlob | TurnMediaRef> | undefined, voice: TurnBlob[] | undefined, limits: MediaLimits | undefined): {
+    attachments?: Array<TurnBlob | TurnMediaRef>;
     voice?: TurnBlob[];
 };
-declare function sanitizeTurnBlobsForProfile(profileId: string, attachments: TurnBlob[] | undefined, voice: TurnBlob[] | undefined): {
-    attachments?: TurnBlob[];
+declare function sanitizeTurnBlobsForProfile(profileId: string, attachments: Array<TurnBlob | TurnMediaRef> | undefined, voice: TurnBlob[] | undefined): {
+    attachments?: Array<TurnBlob | TurnMediaRef>;
     voice?: TurnBlob[];
 };
-export { assertAttachmentLimits, fileTooLargeMessage, requireMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, sanitizeTurnBlobsForProfile, tooManyFilesMessage, turnTooLargeMessage, };
+export { assertAttachmentLimits, isTurnMediaRef, maxBytesForMime, requireMediaLimits, resolveMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, sanitizeTurnBlobsForProfile, };

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

@@ -1,5 +1,6 @@
 import { TheorumError } from '../../guardrails/error.js';
 import { injectionSpans } from '../../guardrails/injection.js';
+import { lexiconText } from '../../guardrails/lexicon.js';
 import { sensitiveSpans } from '../../guardrails/sensitive.js';
 import { applySpans } from '../../observability/spans.js';
 import { getProfile } from './profiles.js';
@@ -9,23 +10,7 @@ const B64_TRIPLET = 3;
 const CSV_FORMULA = /(^|,)(\s*)("?)(?:([=@])|([+-])(?![0-9."]))/gm;
 const B64_BODY = /^[A-Za-z0-9+/]*={0,2}$/;
 const TEXT_MIMES = new Set(['text/csv', 'text/plain', 'text/markdown']);
-const BYTES_PER_KIB = 1024;
-function formatMb(bytes) {
-    const mb = bytes / (BYTES_PER_KIB * BYTES_PER_KIB);
-    return Number.isInteger(mb) ? `${String(mb)} MB` : `${mb.toFixed(1)} MB`;
-}
-function tooManyFilesMessage(maxFiles) {
-    return maxFiles === 1
-        ? 'Only 1 file per message.'
-        : `Only ${String(maxFiles)} files per message.`;
-}
-function fileTooLargeMessage(maxBytes) {
-    return `Each file must be ${formatMb(maxBytes)} or smaller.`;
-}
-function turnTooLargeMessage(maxTurnBytes) {
-    return `Those files together are too large for one message (${formatMb(maxTurnBytes)} max).`;
-}
-function mediaLimits(inputs) {
+function resolveMediaLimits(inputs) {
     const { maxFiles, maxBytes, maxTurnBytes, limitsByMime } = inputs;
     if (maxFiles && maxBytes && maxTurnBytes) {
         return { maxFiles, maxBytes, maxTurnBytes, limitsByMime };
@@ -46,10 +31,23 @@ function maxBytesForMime(mimeType, limits) {
     }
     return limits.maxBytes;
 }
+/** Attachment supplied by provider file reference — no bytes to size-check or sanitize. */
+function isTurnMediaRef(item) {
+    return 'uri' in item;
+}
 function requireMediaLimits(profile) {
-    const limits = mediaLimits(profile.inputs);
+    if (profile.type === 'speech') {
+        throw new TheorumError(`Profile ${profile.id} (speech) does not accept media input`); // lexicon-exempt: developer contract error
+    }
+    if (profile.type === 'live') {
+        throw new TheorumError(`Profile ${profile.id} (live) does not accept turn attachment input`); // lexicon-exempt: developer contract error
+    }
+    if (profile.type === 'host') {
+        throw new TheorumError(`Profile ${profile.id} (host) does not accept turn input`); // lexicon-exempt: developer contract error
+    }
+    const limits = resolveMediaLimits(profile.inputs ?? {});
     if (!limits) {
-        throw new TheorumError(`Profile ${profile.id} must set maxFiles, maxBytes, and maxTurnBytes`);
+        throw new TheorumError(`Profile ${profile.id} must set maxFiles, maxBytes, and maxTurnBytes`); // lexicon-exempt: developer contract error
     }
     return limits;
 }
@@ -99,28 +97,36 @@ function sanitizeTextBytes(mime, bytes) {
     }
     return new TextEncoder().encode(applySpans(text, [...injectionSpans(text), ...sensitiveSpans(text)]));
 }
-function assertAttachmentLimits(blobs, limits) {
-    if (blobs.length > limits.maxFiles) {
-        throw new TheorumError(tooManyFilesMessage(limits.maxFiles));
+/** Enforce file count on every attachment; base64 and byte limits only on inline blobs. */
+function assertAttachmentLimits(attachments, limits) {
+    if (attachments.length > limits.maxFiles) {
+        throw new TheorumError(lexiconText('attachments.too_many_files', { maxFiles: limits.maxFiles }));
     }
     let total = 0;
-    for (const blob of blobs) {
+    for (const blob of attachments) {
+        if (isTurnMediaRef(blob)) {
+            continue;
+        }
         const { data, mimeType } = blob;
         if (!B64_BODY.test(data)) {
+            // lexicon-exempt: developer-facing wire-format diagnostic, not product copy
             throw new TheorumError('attachment data must be base64');
         }
         const size = b64DecodedLen(data);
         const maxAllowed = maxBytesForMime(mimeType, limits);
         if (size > maxAllowed) {
-            throw new TheorumError(fileTooLargeMessage(maxAllowed));
+            throw new TheorumError(lexiconText('attachments.file_too_large', { maxBytes: maxAllowed }));
         }
         total += size;
     }
     if (total > limits.maxTurnBytes) {
-        throw new TheorumError(turnTooLargeMessage(limits.maxTurnBytes));
+        throw new TheorumError(lexiconText('attachments.turn_too_large', { maxTurnBytes: limits.maxTurnBytes }));
     }
 }
 function sanitizeAttachment(blob) {
+    if (isTurnMediaRef(blob)) {
+        return blob;
+    }
     const { mimeType, data } = blob;
     if (!TEXT_MIMES.has(mimeType.split(';')[0]?.trim().toLowerCase() ?? '')) {
         return blob;
@@ -138,7 +144,7 @@ function sanitizeTurnBlobs(attachments, voice, limits) {
     const files = attachments ?? [];
     const clips = voice ?? [];
     if (!limits) {
-        throw new TheorumError('This profile does not accept files.');
+        throw new TheorumError(lexiconText('attachments.not_accepted', { channel: 'file' }));
     }
     assertAttachmentLimits([...files, ...clips], limits);
     return {
@@ -153,4 +159,4 @@ function sanitizeTurnBlobsForProfile(profileId, attachments, voice) {
     const limits = requireMediaLimits(getProfile(profileId));
     return sanitizeTurnBlobs(attachments, voice, limits);
 }
-export { assertAttachmentLimits, fileTooLargeMessage, requireMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, sanitizeTurnBlobsForProfile, tooManyFilesMessage, turnTooLargeMessage, };
+export { assertAttachmentLimits, isTurnMediaRef, maxBytesForMime, requireMediaLimits, resolveMediaLimits, sanitizeCsvText, sanitizeTurnBlobs, sanitizeTurnBlobsForProfile, };

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

@@ -1,31 +1,32 @@
 /**
- * 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.
+ * MIME helpers and model binding utilities.
  *
  * @module
  */
-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). */
-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;
+import type { MediaInputKind, ModelBinding, ModelId, ModelProfile, Profile, ThinkingLevel } from '../types.js';
+/** `TurnInput` field a media file rides in. */
+type MediaInputChannel = 'attachments' | 'voice';
 declare function mimeEssence(mime: string): string;
 declare function mimeAllowed(accept: string[], mime: string): boolean;
 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. */
-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, getTool, listBuiltinIds, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, registerTools, requireModelSpec, resetTools, };
+/** The `accept` list a profile declares for one input channel, if it declares one. */
+declare function profileAccept(profile: Profile, channel: MediaInputChannel): string[] | undefined;
+/**
+ * Which `TurnInput` channel of a profile accepts this MIME, or `undefined` when
+ * the profile accepts it nowhere (or the kernel cannot classify it at all).
+ *
+ * The one public answer to "does this profile take this file". Hosts route and
+ * filter channel ingress with it instead of keeping their own MIME table: the
+ * profile's `accept` lists are the whole declaration.
+ */
+declare function mediaChannelForMime(profile: Profile, mime: string): MediaInputChannel | undefined;
+/** Require a host-declared model binding for a profile model id. */
+declare function requireModelBinding(profile: ModelProfile, modelId: ModelId): ModelBinding;
+/** Clamp a requested thinking level to what the model binding accepts. */
+declare function clampThinkingLevel(binding: ModelBinding, level: ThinkingLevel): ThinkingLevel;
+/** Look up a model binding by provider-native API id within a host map. */
+declare function modelEntryByApiId(bindings: Record<string, ModelBinding>, apiId: string): ModelBinding | undefined;
+/** Clamp thinking level using a provider-native API id within a host map. */
+declare function clampThinkingLevelForApiId(bindings: Record<string, ModelBinding>, apiId: string, level: ThinkingLevel): ThinkingLevel;
+export type { MediaInputChannel };
+export { clampThinkingLevel, clampThinkingLevelForApiId, mediaChannelForMime, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, profileAccept, requireModelBinding, };