@theoremjs/agents 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,773 @@
+import { TOOL_BOUNDARIES } from '../../guardrails/boundaries.js';
+import { detectProblem } from '../../guardrails/detectors.js';
+import { TheoremError } from '../../guardrails/error.js';
+import { labelText, validateLabelOverrides } from '../../guardrails/labels.js';
+import { BLOCKED_REPLY_ON_BLOCK, } from '../../guardrails/types.js';
+import { resolveObservabilityPolicy } from '../../observability/resolve-policy.js';
+import { providerContinuationSchema } from '../checkpoint.js';
+import { assertLiveIngressConfigured } from '../engine/live-ingress.js';
+import { itemSchemaAt, schemaReaches } from '../engine/runner/schema-validation.js';
+import { outOfScopeFields, profileKeysOf, profileTypesForField } from '../profile-scope.js';
+import { checkBinding, decisionModelBindingSchema, modelBindingSchema, } from '../protocols/binding.js';
+import { CONTEXT_SENDERS, IMAGE_ATTACHMENT_ACCEPT_MIMES, PROFILE_FIELDS, PROFILE_HANDLE_MAX_CHARS, PROFILE_ID_MAX_CHARS, PROFILE_TYPES, THINKING_LEVELS, } from '../schema.js';
+import { isContinueStopKind } from '../stop.js';
+import { assertSystemPrompt } from '../system-parts.js';
+import { profileToolAllow, profileToolsSpec } from '../tools/resolve.js';
+import { isTurnMediaRef } from './attachments.js';
+import { mediaKindForMime, mimeAllowed, profileInputs } from './catalog.js';
+import { soleModelId } from './sole-model.js';
+function assertModelRoute(_profileId, _modelId, binding, _type) {
+    if (!binding.provider?.trim() || !binding.apiId?.trim())
+        throw new TheoremError('config', labelText('provider.binding_identity'));
+}
+function defineEmbeddingProfile(input) {
+    assertModelsNonEmpty(input.id, input.models);
+    assertObservability(input.id, input.observability);
+    assertMediaLimits(input.id, input.inputs);
+    for (const [modelId, binding] of Object.entries(input.models))
+        assertModelBinding(input.id, modelId, binding);
+    return {
+        type: 'embedding',
+        id: input.id,
+        identity: { handle: input.identity.handle },
+        models: input.models,
+        defaultModel: resolveDefaultModel(input.id, input),
+        allowModelSelect: input.allowModelSelect,
+        inputs: input.inputs,
+        guardrails: input.guardrails,
+        observability: input.observability,
+        labels: input.labels,
+    };
+}
+function assertBindingData(profileId, modelId, binding, schema) {
+    const parsed = schema.safeParse(binding);
+    if (!parsed.success)
+        throw new TheoremError('config', `Profile ${profileId} model '${modelId}': ${parsed.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; ')}`);
+}
+function validateDecisionBinding(profileId, modelId, binding) {
+    assertBindingData(profileId, modelId, binding, decisionModelBindingSchema);
+    assertModelRoute(profileId, modelId, binding, 'decision');
+    if ('retry' in binding) {
+        throw new TheoremError('config', 
+        // labels-exempt: developer contract / internal diagnostic
+        `Profile ${profileId} model '${modelId}': decision retry configuration is unsupported; POSTs are never retried`);
+    }
+    if (binding.timeoutMs !== undefined &&
+        (!Number.isFinite(binding.timeoutMs) || binding.timeoutMs <= 0)) {
+        throw new TheoremError('config', `Profile ${profileId} model '${modelId}' timeoutMs must be > 0`);
+    }
+}
+function validateDecisionModel(input) {
+    const modelId = input.models ? soleModelId(input.models) : undefined;
+    if (!modelId) {
+        throw new TheoremError('config', `Profile ${input.id}: type 'decision' must declare exactly one model`);
+    }
+    validateDecisionBinding(input.id, modelId, input.models[modelId]);
+}
+function validateDecisionConfig(input) {
+    if (input.inputs.state !== 'json') {
+        throw new TheoremError('config', `Profile ${input.id}: decision inputs.state must be 'json'`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    const cap = input.inputs.maxStateBytes;
+    if (cap !== undefined && !(Number.isInteger(cap) && cap > 0)) {
+        throw new TheoremError('config', `Profile ${input.id}: decision inputs.maxStateBytes must be a positive integer`);
+    }
+    if (!input.decision.contract.trim()) {
+        throw new TheoremError('config', `Profile ${input.id}: decision.contract must be non-empty`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+}
+function defineDecisionProfile(input) {
+    validateDecisionModel(input);
+    validateDecisionConfig(input);
+    assertObservability(input.id, input.observability);
+    return { ...input, identity: { handle: input.identity.handle } };
+}
+/** `tools.parallel` carried over only when the definition sets it. */
+function optionalParallel(parallel) {
+    return parallel === undefined ? {} : { parallel };
+}
+function defineHostProfile(input) {
+    assertHostTools(input.id, input.tools);
+    assertObservability(input.id, input.observability);
+    return {
+        type: 'host',
+        id: input.id,
+        tools: { allow: input.tools.allow, ...optionalParallel(input.tools.parallel) },
+        guardrails: input.guardrails,
+        observability: input.observability,
+        labels: input.labels,
+    };
+}
+function assertHostTools(profileId, tools) {
+    if (!Array.isArray(tools.allow)) {
+        throw new TheoremError('config', `Profile ${profileId}: type 'host' must set tools.allow`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+}
+function assertModelsNonEmpty(profileId, models) {
+    if (Object.keys(models).length === 0) {
+        throw new TheoremError('config', `Profile ${profileId} must declare at least one model`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+}
+function resolveDefaultModel(profileId, input) {
+    const inferred = input.defaultModel ?? soleModelId(input.models);
+    if (!inferred) {
+        throw new TheoremError('config', `Profile ${profileId} must set defaultModel when more than one model is declared`);
+    }
+    if (!input.models[inferred]) {
+        throw new TheoremError('config', `Profile ${profileId} defaultModel '${inferred}' is not declared`);
+    }
+    return inferred;
+}
+function assertModelBinding(profileId, modelId, binding) {
+    assertModelEfforts(profileId, modelId, binding);
+    assertBindingData(profileId, modelId, binding, modelBindingSchema);
+    assertModelEfforts(profileId, modelId, binding);
+}
+function assertModelEfforts(profileId, modelId, binding) {
+    const efforts = binding.efforts;
+    if (!efforts || Object.keys(efforts).length === 0) {
+        if (binding.defaultEffort || binding.allowEffortSelect) {
+            throw new TheoremError('config', `Profile ${profileId} model '${modelId}': defaultEffort and allowEffortSelect require efforts`);
+        }
+        return;
+    }
+    for (const [alias, level] of Object.entries(efforts)) {
+        if (!THINKING_LEVELS.includes(level)) {
+            throw new TheoremError('config', `Profile ${profileId} model '${modelId}' effort '${alias}': '${level}' is not a thinking level (${THINKING_LEVELS.join(', ')})`);
+        }
+    }
+    const keys = Object.keys(efforts);
+    const defaultAlias = binding.defaultEffort ?? (keys.length === 1 ? keys[0] : undefined);
+    if (!defaultAlias) {
+        throw new TheoremError('config', `Profile ${profileId} model '${modelId}' must set defaultEffort when more than one effort is declared`);
+    }
+    if (!efforts[defaultAlias]) {
+        throw new TheoremError('config', `Profile ${profileId} model '${modelId}' defaultEffort '${defaultAlias}' is not declared`);
+    }
+    if (binding.allowEffortSelect && keys.length < 2) {
+        throw new TheoremError('config', `Profile ${profileId} model '${modelId}' allowEffortSelect requires at least two efforts`);
+    }
+}
+function profileModelFields(input) {
+    return {
+        providerContinuation: input.providerContinuation
+            ? providerContinuationSchema.parse(input.providerContinuation)
+            : {},
+        models: input.models,
+        defaultModel: resolveDefaultModel(input.id, input),
+        allowModelSelect: input.allowModelSelect,
+        maxSteps: input.maxSteps,
+    };
+}
+function assertContinueKindList(profileId, path, kinds) {
+    if (!kinds?.length)
+        return;
+    for (const kind of kinds) {
+        if (!isContinueStopKind(kind)) {
+            throw new TheoremError('config', `Profile ${profileId}: turnBehaviour.resumption.${path} may only include ContinueStopKind ` + // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+                `(length | stream_incomplete | provider_error); got '${kind}'`);
+        }
+    }
+}
+function assertResumption(profileId, resumption) {
+    if (!resumption)
+        return;
+    assertContinueKindList(profileId, 'allowContinue', resumption.allowContinue);
+    assertContinueKindList(profileId, 'autoContinue', resumption.autoContinue);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** `*` spans a map's entries; a path through an absent parent yields nothing. */
+function valuesAt(root, path) {
+    let level = [root];
+    for (const key of path) {
+        level = level.flatMap((value) => {
+            if (!isRecord(value))
+                return [];
+            return key === '*' ? Object.values(value) : [value[key]];
+        });
+    }
+    return level;
+}
+const REQUIRED_PATHS = Object.entries(PROFILE_FIELDS)
+    .filter(([, meta]) => meta.required === true)
+    .map(([path, meta]) => [path, meta.profileTypes])
+    .sort(([a], [b]) => a.split('.').length - b.split('.').length);
+/** A definition may come over the network (a studio draft), so its shape is checked before anything reads it. */
+function assertProfileShape(input) {
+    if (!isRecord(input)) {
+        throw new TheoremError('config', 'Profile definition must be an object'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    const id = typeof input.id === 'string' && input.id.trim() ? input.id : undefined;
+    if (!id) {
+        throw new TheoremError('config', 'Profile definition must set id'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    const type = PROFILE_TYPES.find((known) => known === input.type);
+    if (!type) {
+        throw new TheoremError('config', `Profile ${id}: type must be one of ${PROFILE_TYPES.join(', ')}`);
+    }
+}
+/** A profile's id and its handle each fit their limit. */
+function assertNameLengths(input) {
+    const handle = input.identity?.handle;
+    const names = [
+        ['id', input.id, PROFILE_ID_MAX_CHARS],
+        ['identity.handle', typeof handle === 'string' ? handle : '', PROFILE_HANDLE_MAX_CHARS],
+    ];
+    for (const [path, name, max] of names) {
+        if (Array.from(name).length <= max)
+            continue;
+        throw new TheoremError('config', `Profile ${input.id.slice(0, PROFILE_ID_MAX_CHARS)}: ${path} must be at most ${max} characters`);
+    }
+}
+/** A field under an optional parent the definition leaves out is not required. */
+function assertRequiredFields(input) {
+    const { id, type } = input;
+    const root = input;
+    for (const [path, profileTypes] of REQUIRED_PATHS) {
+        if (profileTypes && !profileTypes.includes(type))
+            continue;
+        const keys = profileKeysOf(path);
+        const parents = valuesAt(root, keys.slice(0, -1));
+        const last = keys[keys.length - 1];
+        const missing = parents.some((parent) => {
+            if (!isRecord(parent))
+                return false;
+            const value = parent[last];
+            return value === undefined || value === null || value === '';
+        });
+        if (missing) {
+            throw new TheoremError('config', `Profile ${id}: type '${type}' must set ${keys.join('.')}`);
+        }
+    }
+}
+/** `inputs` is optional on a live profile only, where it holds slots and context and nothing else. */
+function assertInputsSet(input) {
+    const { id, type } = input;
+    if (type === 'live' || !profileTypesForField('inputs').includes(type))
+        return;
+    const inputs = input.inputs;
+    if (inputs === undefined || inputs === null) {
+        throw new TheoremError('config', `Profile ${id}: type '${type}' must set inputs`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+}
+/** Covers untyped hosts that the definition types can't stop. */
+function assertFieldScope(input) {
+    const [field] = outOfScopeFields(input);
+    if (!field)
+        return;
+    const { offValue, reason } = field.scope;
+    const allowed = offValue === undefined ? '' : ` (other than ${offValue})`;
+    throw new TheoremError('config', `Profile ${input.id}: type '${input.type}' must not set ${field.path}${allowed} — ${reason}`);
+}
+function assertTurnBehaviour(profileId, input) {
+    const tb = input.turnBehaviour;
+    assertResumption(profileId, tb?.resumption);
+}
+function assertValidation(profileId, validation) {
+    const fail = (message) => new TheoremError('config', `Profile ${profileId}: ${message}`);
+    const retries = validation?.maxRetries;
+    if (retries !== undefined && (!Number.isInteger(retries) || retries < 0)) {
+        throw fail('outputs.validation.maxRetries must be a non-negative integer'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+}
+function assertGuardrails(profileId, guardrails) {
+    const fail = (message) => new TheoremError('config', `Profile ${profileId}: ${message}`);
+    // why: A key this does not read would be a check the builder believes is on.
+    const unknown = Object.keys(guardrails ?? {}).find((key) => !GUARDRAIL_KEYS.includes(key));
+    if (unknown !== undefined) {
+        throw fail(`guardrails.${unknown} is not a setting; it takes ${GUARDRAIL_KEYS.join(', ')}`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    assertBlockedReply(guardrails?.blockedReply, fail);
+}
+const GUARDRAIL_KEYS = [
+    'quota',
+    'detect',
+    'blockedReply',
+    'network',
+    'taint',
+];
+const BLOCKED_REPLY_KEYS = ['onBlock', 'maxRetries'];
+function assertBlockedReply(blockedReply, fail) {
+    if (blockedReply === undefined)
+        return;
+    const unknown = Object.keys(blockedReply).find((key) => !BLOCKED_REPLY_KEYS.includes(key));
+    if (unknown !== undefined) {
+        throw fail(
+        // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        `guardrails.blockedReply.${unknown} is not a setting; it takes onBlock and maxRetries`);
+    }
+    const { onBlock, maxRetries } = blockedReply;
+    if (onBlock !== undefined && !BLOCKED_REPLY_ON_BLOCK.includes(onBlock)) {
+        throw fail(
+        // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        `guardrails.blockedReply.onBlock must be one of ${BLOCKED_REPLY_ON_BLOCK.join(', ')}`);
+    }
+    if (maxRetries !== undefined && (!Number.isInteger(maxRetries) || maxRetries < 0)) {
+        throw fail('guardrails.blockedReply.maxRetries must be a non-negative integer'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+}
+/** A host profile runs no model turn, so the tool boundaries are the only ones it has. */
+function assertDetect(input) {
+    const spec = input.guardrails?.detect;
+    const problem = input.type === 'host'
+        ? detectProblem('guardrails.detect', spec, TOOL_BOUNDARIES)
+        : detectProblem('guardrails.detect', spec);
+    if (problem !== undefined)
+        throw new TheoremError('config', `Profile ${input.id}: ${problem}`);
+}
+function assertObservability(profileId, spec) {
+    try {
+        const policy = resolveObservabilityPolicy(spec);
+        if (!Number.isFinite(policy.retainForDays)) {
+            throw new TheoremError('config', `Profile ${profileId}: observability.retainForDays must be a finite number`);
+        }
+        if (policy.rotateAfterMiB <= 0 || !Number.isFinite(policy.rotateAfterMiB)) {
+            throw new TheoremError('config', `Profile ${profileId}: observability.rotateAfterMiB must be a positive number`);
+        }
+    }
+    catch (err) {
+        if (err instanceof TheoremError && err.message.startsWith('Profile ')) {
+            throw err;
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        throw new TheoremError('config', `Profile ${profileId}: ${message}`);
+    }
+}
+function assertIdentitySystem(input) {
+    if (input.type === 'host' ||
+        input.type === 'decision' ||
+        input.type === 'speech' ||
+        input.type === 'embedding')
+        return;
+    const { system, systemByRole } = input.identity;
+    if (system !== undefined)
+        assertSystemPrompt(system, `Profile ${input.id} identity.system`);
+    for (const [role, prompt] of Object.entries(systemByRole ?? {})) {
+        assertSystemPrompt(prompt, `Profile ${input.id} identity.systemByRole.${role}`);
+    }
+}
+/** Validate any definition and return the profile. */
+function defineProfile(input) {
+    assertProfileShape(input);
+    for (const field of ['key', 'fallbackKey', 'protocol', 'provider'])
+        if (field in input)
+            throw new TheoremError('config', labelText('provider.profile_configuration', { profile: input.id, field }));
+    assertFieldScope(input);
+    assertInputsSet(input);
+    assertRequiredFields(input);
+    assertNameLengths(input);
+    if (input.labels)
+        validateLabelOverrides(input.labels, `Profile ${input.id}`);
+    assertIdentitySystem(input);
+    assertDetect(input);
+    if (input.type === 'host') {
+        return defineHostProfile(input);
+    }
+    if (input.type === 'decision') {
+        return defineDecisionProfile(input);
+    }
+    if (input.type === 'embedding') {
+        return defineEmbeddingProfile(input);
+    }
+    assertModelsNonEmpty(input.id, input.models);
+    assertTurnBehaviour(input.id, input);
+    assertGuardrails(input.id, input.guardrails);
+    if (input.type === 'text')
+        assertValidation(input.id, input.outputs?.validation);
+    assertObservability(input.id, input.observability);
+    for (const [modelId, binding] of Object.entries(input.models)) {
+        assertModelBinding(input.id, modelId, binding);
+    }
+    const identity = input.type === 'speech'
+        ? { handle: input.identity.handle }
+        : {
+            handle: input.identity.handle,
+            system: input.identity.system,
+            systemByRole: input.identity.systemByRole,
+        };
+    const guardrails = input.guardrails;
+    const observability = input.observability;
+    const labels = input.labels;
+    const modelFields = profileModelFields(input);
+    let profile;
+    switch (input.type) {
+        case 'text':
+            profile = {
+                type: 'text',
+                id: input.id,
+                identity,
+                ...modelFields,
+                tools: input.tools,
+                inputs: input.inputs,
+                outputs: input.outputs,
+                turnBehaviour: input.turnBehaviour,
+                guardrails,
+                observability,
+                labels,
+            };
+            break;
+        case 'image':
+            profile = {
+                type: 'image',
+                id: input.id,
+                identity,
+                ...modelFields,
+                image: input.image,
+                tools: input.tools,
+                inputs: input.inputs,
+                outputs: input.outputs,
+                turnBehaviour: input.turnBehaviour,
+                guardrails,
+                observability,
+                labels,
+            };
+            assertImageAccept(profile.id, profile.inputs.attachments?.accept);
+            assertImagePinValues(profile.id, profile.image);
+            break;
+        case 'speech':
+            profile = {
+                type: 'speech',
+                id: input.id,
+                identity,
+                ...modelFields,
+                speech: input.speech,
+                outputs: input.outputs,
+                turnBehaviour: input.turnBehaviour,
+                guardrails,
+                observability,
+                labels,
+            };
+            break;
+        case 'live': {
+            profile = {
+                type: 'live',
+                id: input.id,
+                identity,
+                ...modelFields,
+                live: input.live,
+                inputs: input.inputs,
+                tools: { allow: input.tools.allow, ...optionalParallel(input.tools.parallel) },
+                turnBehaviour: input.turnBehaviour,
+                guardrails,
+                observability,
+                labels,
+            };
+            assertLiveIngressConfigured(profile);
+            assertLiveCompression(profile.id, profile.live.contextCompression);
+            assertLiveOpening(profile);
+            break;
+        }
+        default: {
+            const _exhaustive = input;
+            throw new TheoremError('config', `Unknown profile type '${String(_exhaustive)}'`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+    }
+    assertStructuredSlot(profile);
+    assertMaxSteps(profile);
+    assertAnswerStep(profile);
+    return profile;
+}
+/** Only a positive whole number is a cap; left out, the turn gets `DEFAULT_MAX_STEPS`. */
+function assertMaxSteps(profile) {
+    const { maxSteps } = profile;
+    if (maxSteps === undefined || (Number.isInteger(maxSteps) && maxSteps > 0))
+        return;
+    throw new TheoremError('config', `Profile ${profile.id}: maxSteps must be a whole number of 1 or more; leave it out for the default of 20`);
+}
+/** The answering step takes no tools, so with one step the profile's tools could never run. */
+function assertAnswerStep(profile) {
+    if (profile.type !== 'text' || profile.turnBehaviour?.atStepLimit !== 'answer')
+        return;
+    if (profile.maxSteps !== 1)
+        return;
+    throw new TheoremError('config', `Profile ${profile.id}: turnBehaviour.atStepLimit 'answer' with maxSteps 1 leaves no step that can call a tool`);
+}
+/** A turn can pass no value outside the slot's choices, so any other mapped key is dead. */
+function assertStructuredSlot(profile) {
+    if (profile.type === 'live')
+        return;
+    const structured = profile.outputs?.structured;
+    if (!structured || typeof structured === 'string')
+        return;
+    const choices = profileInputs(profile)?.slots?.[structured.by];
+    if (!choices) {
+        throw new TheoremError('config', `Profile ${profile.id}: outputs.structured.by '${structured.by}' is not a slot in inputs.slots`);
+    }
+    const unknown = Object.keys(structured.map).filter((value) => !choices.includes(value));
+    if (unknown.length) {
+        throw new TheoremError('config', `Profile ${profile.id}: outputs.structured.map maps ${unknown.join(', ')}, not a choice of slot '${structured.by}'`);
+    }
+}
+const IMAGE_PIN_RULES = {
+    n: { ok: (v) => Number.isInteger(v) && v >= 1, rule: 'a whole number of 1 or more' }, // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    seed: { ok: Number.isInteger, rule: 'a whole number' }, // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    outputCompression: {
+        ok: (v) => Number.isInteger(v) && v >= 0 && v <= 100,
+        rule: 'a whole number from 0 to 100', // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    },
+};
+function assertImagePinValues(profileId, image) {
+    for (const [name, { ok, rule }] of Object.entries(IMAGE_PIN_RULES)) {
+        const value = image[name];
+        if (value !== undefined && !ok(value)) {
+            throw new TheoremError('config', `Profile ${profileId}: image.${name} must be ${rule}`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+    }
+    image.references?.forEach((reference, index) => {
+        const where = `Profile ${profileId}: image.references[${index}]`;
+        if (mediaKindForMime(reference.mimeType) !== 'image') {
+            throw new TheoremError('config', `${where} must be an image, not '${reference.mimeType}'`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+        const source = isTurnMediaRef(reference) ? reference.uri : reference.data;
+        if (!source) {
+            throw new TheoremError('config', `${where} needs its bytes or its uri`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        }
+    });
+}
+function assertImageAccept(profileId, accept) {
+    const outside = accept?.filter((rule) => !mimeAllowed(IMAGE_ATTACHMENT_ACCEPT_MIMES, rule));
+    if (!outside?.length)
+        return;
+    throw new TheoremError('config', 
+    // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    `Profile ${profileId}: an image profile's attachments take images, video, and PDF only, ` +
+        `not ${outside.join(', ')}`);
+}
+/** A greeting is a prompt, and a resume prompt needs the handles that make a resume. */
+function assertLiveOpening(profile) {
+    const { greeting, resumed, sessionResumption } = profile.live;
+    const tag = `Profile ${profile.id} live`; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    if (greeting !== undefined && (typeof greeting !== 'string' || !greeting.trim())) {
+        throw new TheoremError('config', `${tag}.greeting must be a prompt; leave it out to wait`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    if (!resumed)
+        return;
+    if (typeof resumed.prompt !== 'string' || !resumed.prompt.trim()) {
+        throw new TheoremError('config', `${tag}.resumed.prompt must be a prompt`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    const { afterMs } = resumed;
+    if (afterMs !== undefined && !(Number.isFinite(afterMs) && afterMs >= 0)) {
+        throw new TheoremError('config', `${tag}.resumed.afterMs must be 0 or more milliseconds`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    if (!sessionResumption) {
+        throw new TheoremError('config', `${tag}.resumed needs live.sessionResumption: without it no call resumes`);
+    }
+}
+function assertLiveCompression(profileId, spec) {
+    if (!spec)
+        return;
+    const tag = `Profile ${profileId} live.contextCompression`; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    const trigger = spec.triggerTokens;
+    const target = spec.slidingWindow.targetTokens;
+    assertWholeTokens(`${tag}.triggerTokens`, trigger);
+    assertWholeTokens(`${tag}.slidingWindow.targetTokens`, target);
+    if (trigger !== undefined && target !== undefined && target >= trigger) {
+        throw new TheoremError('config', 
+        // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        `${tag}: slidingWindow.targetTokens must be below triggerTokens`);
+    }
+}
+function assertWholeTokens(tag, value) {
+    if (value === undefined || (Number.isInteger(value) && value > 0))
+        return;
+    throw new TheoremError('config', `${tag} must be a whole number above 0`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+}
+function assertCompactionSpec(registered, owner, modelId, spec) {
+    const tag = `Profile ${owner.id} model ${modelId} compaction`; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    assertCompactionBudget(tag, spec);
+    assertCompactionRetain(tag, spec);
+    if (spec.meter != null && spec.meter !== 'history' && spec.meter !== 'input') {
+        throw new TheoremError('config', `${tag}: meter must be 'history' or 'input'`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    if (spec.profile === undefined) {
+        if (owner.type !== 'text' || owner.inputs.text === false) {
+            throw new TheoremError('config', `${tag}: a profile that compacts itself must be a text profile that takes text`);
+        }
+        return;
+    }
+    const compactor = registered.get(spec.profile);
+    if (!compactor) {
+        throw new TheoremError('config', `${tag}: compaction profile '${spec.profile}' must be registered before '${owner.id}'`);
+    }
+    if (compactor.type !== 'text' || compactor.inputs.text === false) {
+        throw new TheoremError('config', `${tag}: compaction profile '${spec.profile}' must be a text profile that takes text`);
+    }
+}
+function assertCompactionBudget(tag, spec) {
+    if (spec.maxTokens <= 0) {
+        throw new TheoremError('config', `${tag}: maxTokens must be > 0`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    if (spec.compactAt <= 0 || spec.compactAt >= 1) {
+        throw new TheoremError('config', `${tag}: compactAt must be in (0, 1)`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+}
+function assertCompactionRetain(tag, spec) {
+    if (spec.previousExchanges < 0) {
+        throw new TheoremError('config', `${tag}: previousExchanges must be >= 0`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    if (spec.previousExchanges < 1 && spec.previousExchanges >= spec.compactAt) {
+        throw new TheoremError('config', `${tag}: previousExchanges as fraction (${spec.previousExchanges}) must be < compactAt (${spec.compactAt})`);
+    }
+    if (spec.previousExchanges > 1 && !Number.isInteger(spec.previousExchanges)) {
+        throw new TheoremError('config', `${tag}: previousExchanges >= 1 must be an integer`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+}
+function assertCustomToolsOnly(tools, profile) {
+    for (const id of profileToolAllow(profile)) {
+        const tool = tools.get(id);
+        if (tool?.type === 'builtin') {
+            throw new TheoremError('config', profile.type === 'host'
+                ? `Profile ${profile.id} lists builtin '${id}' in tools.allow — type 'host' never runs a model` // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+                : `Profile ${profile.id} lists builtin '${id}' in tools.allow — declare it on models.*.builtInTools instead`);
+        }
+    }
+}
+function assertProfileToolLoader(tools, profile) {
+    const loaderId = profileToolsSpec(profile)?.t2Loader;
+    if (!loaderId) {
+        return;
+    }
+    if (!profileToolAllow(profile).includes(loaderId)) {
+        throw new TheoremError('config', `Profile ${profile.id} tools.t2Loader '${loaderId}' must also be listed in tools.allow`);
+    }
+    const tool = tools.get(loaderId);
+    if (tool?.type !== 'function') {
+        throw new TheoremError('config', `Profile ${profile.id} tools.t2Loader '${loaderId}' must be a registered type: 'function' tool`);
+    }
+}
+function* modelBuiltinIds(profile) {
+    for (const [modelId, binding] of Object.entries(profile.models)) {
+        for (const id of binding.builtInTools ?? []) {
+            yield { modelId, id };
+        }
+    }
+}
+function assertModelBuiltInTools(tools, profile) {
+    for (const { modelId, id } of modelBuiltinIds(profile)) {
+        const tool = tools.get(id);
+        if (tool?.type !== 'builtin') {
+            throw new TheoremError('config', `Profile ${profile.id} model '${modelId}' lists '${id}' in builtInTools — not a registered builtin`);
+        }
+    }
+}
+/** The schema ids `outputs.structured` can pick, by slot and fallback. */
+function structuredIds(profile) {
+    const structured = profile.type === 'text' ? profile.outputs?.structured : undefined;
+    if (!structured)
+        return [];
+    if (typeof structured === 'string')
+        return [structured];
+    return [...new Set([...Object.values(structured.map), structured.fallback])];
+}
+/**
+ * Every schema `outputs.structured` names is registered, and every
+ * `outputs.validation.fields` path reaches a property of one of them.
+ */
+function assertStructuredSchemas(schemas, profile) {
+    const specs = structuredIds(profile).map((id) => {
+        const spec = schemas.find(id);
+        if (!spec) {
+            throw new TheoremError('config', `Profile ${profile.id}: outputs.structured names '${id}', which is not a registered schema; register it before the profile`);
+        }
+        return spec;
+    });
+    const validation = profile.type === 'text' ? profile.outputs?.validation : undefined;
+    const fields = Object.keys(validation?.fields ?? {});
+    const lists = Object.keys(validation?.items ?? {});
+    if (!fields.length && !lists.length)
+        return;
+    if (!specs.length) {
+        throw new TheoremError('config', `Profile ${profile.id}: outputs.validation checks a structured reply, so it needs outputs.structured`);
+    }
+    const notLists = lists.filter((path) => !specs.some((spec) => itemSchemaAt(spec.jsonSchema, path)));
+    if (notLists.length) {
+        throw new TheoremError('config', `Profile ${profile.id}: outputs.validation.items has ${notLists.join(', ')}, which no structured schema reaches as a list with an items schema`);
+    }
+    const unreached = fields.filter((path) => !specs.some((spec) => schemaReaches(spec.jsonSchema, path)));
+    if (unreached.length) {
+        throw new TheoremError('config', `Profile ${profile.id}: outputs.validation.fields has ${unreached.join(', ')}, which no structured schema reaches through object properties`);
+    }
+}
+function assertContextSpec(profile) {
+    const context = profileInputs(profile)?.context;
+    if (!context) {
+        return;
+    }
+    const senders = CONTEXT_SENDERS;
+    if (context.from.length === 0 || context.from.some((sender) => !senders.includes(sender))) {
+        throw new TheoremError('config', `Profile ${profile.id}: inputs.context.from must list ${CONTEXT_SENDERS.join(' or ')}`);
+    }
+    if (!(Number.isInteger(context.maxChars) && context.maxChars > 0)) {
+        throw new TheoremError('config', `Profile ${profile.id}: inputs.context.maxChars must be a positive integer`);
+    }
+}
+function assertMediaLimits(profileId, inputs) {
+    if (!inputs) {
+        return;
+    }
+    const { attachments, voice, maxFiles, maxBytes, maxTurnBytes, limitsByMime } = inputs;
+    const limits = { maxFiles, maxBytes, maxTurnBytes };
+    if ((attachments || voice) && Object.values(limits).some((value) => value === undefined)) {
+        throw new TheoremError('config', `Profile ${profileId} must set maxFiles, maxBytes, and maxTurnBytes`);
+    }
+    for (const [mime, value] of Object.entries(limitsByMime ?? {})) {
+        limits[`limitsByMime['${mime}']`] = value;
+    }
+    for (const [name, value] of Object.entries(limits)) {
+        if (value !== undefined && !(Number.isInteger(value) && value > 0)) {
+            throw new TheoremError('config', `Profile ${profileId}: inputs.${name} must be a positive integer`);
+        }
+    }
+}
+/** Profiles are checked against `tools` and `schemas`, so register a scope's tools and schemas before its profiles. */
+function createProfileRegistry(tools, schemas, providers) {
+    const profiles = new Map();
+    const register = (profileInput) => {
+        const defined = defineProfile(profileInput);
+        const profile = providers && defined.type !== 'host'
+            ? {
+                ...defined,
+                models: Object.fromEntries(Object.entries(defined.models).map(([modelId, binding]) => [
+                    modelId,
+                    checkBinding(providers.require(binding.provider, binding.apiId), binding, defined.type),
+                ])),
+            }
+            : defined;
+        assertCustomToolsOnly(tools, profile);
+        assertProfileToolLoader(tools, profile);
+        if (profile.type !== 'host' && profile.type !== 'decision' && profile.type !== 'embedding') {
+            assertModelBuiltInTools(tools, profile);
+            assertMediaLimits(profile.id, profileInputs(profile));
+            assertContextSpec(profile);
+            assertStructuredSchemas(schemas, profile);
+            for (const [modelId, binding] of Object.entries(profile.models)) {
+                if (binding.compaction) {
+                    assertCompactionSpec(profiles, profile, modelId, binding.compaction);
+                }
+            }
+        }
+        profiles.set(profile.id, profile);
+    };
+    return {
+        register,
+        registerMany(profilesList) {
+            for (const p of profilesList) {
+                register(p);
+            }
+        },
+        get(id) {
+            const profile = profiles.get(id);
+            if (!profile) {
+                throw new TheoremError('config', `Unknown profile '${id}'`);
+            }
+            return profile;
+        },
+        find: (id) => profiles.get(id),
+        has: (id) => profiles.has(id),
+        list: () => [...profiles.values()],
+        clear: () => profiles.clear(),
+    };
+}
+export { createProfileRegistry, defineProfile };