@theoremjs/agents 0.0.0-stage → 0.3.0

package/esm/src/kernel/engine/usage.d.ts

@@ -0,0 +1,30 @@
+import type { TurnCost, TurnEvent, TurnGroundingCount, TurnTokens } from '../types.js';
+/** Provider usage already mapped to the OpenTelemetry GenAI meanings. */
+export interface ReportedUsage {
+    /** Everything the model read. `undefined` = not reported. */
+    input?: number;
+    /** Everything the model wrote, reasoning included. `undefined` = not reported. */
+    output?: number;
+    thinking?: number;
+    toolUse?: number;
+    cached?: number;
+    cacheWrite?: number;
+    cost?: TurnCost;
+    byModality?: TurnTokens['byModality'];
+    grounding?: TurnGroundingCount[];
+}
+export declare function usageCount(value: unknown): number | undefined;
+/**
+ * `TurnTokens` from reported usage, or `undefined` when the provider reported
+ * nothing. A missing side is 0 and listed in `estimated`. Input 0 counts as
+ * missing, since every model call reads a prompt; an all-zero row (a
+ * placeholder some servers stream) reports nothing.
+ */
+export declare function reportedTokens(usage: ReportedUsage): TurnTokens | undefined;
+/** A turn's usage: the sum of its `tokens` events. `done.tokens` and the turn's span both read it. */
+export declare function sumEventTokens(events: readonly TurnEvent[]): TurnTokens | undefined;
+/**
+ * A side is `estimated` when any call estimated it. Cost is `partial` when some call reported none;
+ * a missing `upstreamUsd` is not missing data (OpenRouter reports it only for BYOK).
+ */
+export declare function sumTokens(calls: TurnTokens[]): TurnTokens | undefined;

package/esm/src/kernel/engine/usage.js

@@ -0,0 +1,134 @@
+export function usageCount(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+/**
+ * `TurnTokens` from reported usage, or `undefined` when the provider reported
+ * nothing. A missing side is 0 and listed in `estimated`. Input 0 counts as
+ * missing, since every model call reads a prompt; an all-zero row (a
+ * placeholder some servers stream) reports nothing.
+ */
+export function reportedTokens(usage) {
+    const reportedInput = usage.input ? usage.input : undefined;
+    if (reportedInput === undefined && !usage.output)
+        return undefined;
+    const estimated = [];
+    if (reportedInput === undefined)
+        estimated.push('input');
+    if (usage.output === undefined)
+        estimated.push('output');
+    const input = reportedInput ?? 0;
+    const output = usage.output ?? 0;
+    return {
+        input,
+        output,
+        ...(usage.thinking ? { thinking: usage.thinking } : {}),
+        ...(usage.toolUse ? { toolUse: usage.toolUse } : {}),
+        ...(usage.cached ? { cached: usage.cached } : {}),
+        ...(usage.cacheWrite ? { cacheWrite: usage.cacheWrite } : {}),
+        total: input + output,
+        ...(usage.cost ? { cost: usage.cost } : {}),
+        ...(estimated.length > 0 ? { estimated } : {}),
+        ...(usage.byModality ? { byModality: usage.byModality } : {}),
+        ...(usage.grounding ? { grounding: usage.grounding } : {}),
+    };
+}
+function sumCost(calls) {
+    const costs = calls.flatMap((call) => (call.cost ? [call.cost] : []));
+    if (costs.length === 0)
+        return undefined;
+    const upstream = costs.flatMap((cost) => cost.upstreamUsd === undefined ? [] : [cost.upstreamUsd]);
+    const partial = costs.length < calls.length || costs.some((cost) => cost.partial);
+    return {
+        usd: costs.reduce((sum, cost) => sum + cost.usd, 0),
+        ...(upstream.length > 0 ? { upstreamUsd: upstream.reduce((sum, usd) => sum + usd, 0) } : {}),
+        ...(partial ? { partial: true } : {}),
+    };
+}
+/**
+ * A modality's share summed across calls, kept only when every call reported
+ * that modality: a partial sum would read as exact and be wrong.
+ */
+function sumByModality(calls) {
+    const sides = ['input', 'output'];
+    const summed = {};
+    for (const side of sides) {
+        const [first, ...rest] = calls.map((call) => call.byModality?.[side]);
+        const modalities = Object.keys(first ?? {}).filter((modality) => rest.every((counts) => counts?.[modality] !== undefined));
+        if (modalities.length === 0)
+            continue;
+        summed[side] = Object.fromEntries(modalities.map((modality) => [
+            modality,
+            calls.reduce((sum, call) => sum + (call.byModality?.[side]?.[modality] ?? 0), 0),
+        ]));
+    }
+    return Object.keys(summed).length > 0 ? summed : undefined;
+}
+/**
+ * Grounding use summed per tool over the calls that reported it; a call that
+ * ran no grounding tool reports none. `searchQueryCount` sums only when every
+ * report of that tool carried it.
+ */
+function sumGrounding(calls) {
+    const byType = new Map();
+    for (const entry of calls.flatMap((call) => call.grounding ?? [])) {
+        byType.set(entry.type, [...(byType.get(entry.type) ?? []), entry]);
+    }
+    if (byType.size === 0)
+        return undefined;
+    return [...byType].map(([type, entries]) => {
+        const queries = entries.every((entry) => entry.searchQueryCount !== undefined);
+        return {
+            type,
+            count: entries.reduce((sum, entry) => sum + entry.count, 0),
+            ...(queries
+                ? {
+                    searchQueryCount: entries.reduce((sum, entry) => sum + (entry.searchQueryCount ?? 0), 0),
+                }
+                : {}),
+        };
+    });
+}
+/** A turn's usage: the sum of its `tokens` events. `done.tokens` and the turn's span both read it. */
+export function sumEventTokens(events) {
+    return sumTokens(events.flatMap((event) => (event.type === 'tokens' ? [event.tokens] : [])));
+}
+/**
+ * A side is `estimated` when any call estimated it. Cost is `partial` when some call reported none;
+ * a missing `upstreamUsd` is not missing data (OpenRouter reports it only for BYOK).
+ */
+export function sumTokens(calls) {
+    if (calls.length === 0)
+        return undefined;
+    const add = (pick) => calls.reduce((sum, call) => sum + (pick(call) ?? 0), 0);
+    const input = add((call) => call.input);
+    const output = add((call) => call.output);
+    const thinking = add((call) => call.thinking);
+    const toolUse = add((call) => call.toolUse);
+    const cached = add((call) => call.cached);
+    const cacheWrite = add((call) => call.cacheWrite);
+    const cost = sumCost(calls);
+    const byModality = sumByModality(calls);
+    const grounding = sumGrounding(calls);
+    const sides = ['input', 'output'];
+    const estimated = sides.filter((side) => calls.some((call) => call.estimated?.includes(side)));
+    const unknownMedia = {};
+    for (const side of sides) {
+        const count = add((call) => call.unknownMedia?.[side]);
+        if (count > 0)
+            unknownMedia[side] = count;
+    }
+    return {
+        input,
+        output,
+        ...(thinking ? { thinking } : {}),
+        ...(toolUse ? { toolUse } : {}),
+        ...(cached ? { cached } : {}),
+        ...(cacheWrite ? { cacheWrite } : {}),
+        total: input + output,
+        ...(cost ? { cost } : {}),
+        ...(estimated.length > 0 ? { estimated } : {}),
+        ...(Object.keys(unknownMedia).length > 0 ? { unknownMedia } : {}),
+        ...(byModality ? { byModality } : {}),
+        ...(grounding ? { grounding } : {}),
+    };
+}

package/esm/src/kernel/interaction-parts.d.ts

@@ -0,0 +1,10 @@
+import type { InteractionMediaRefPart, InteractionPart, TurnHistoryMessage } from './types.js';
+/** `toGoogleValue` snake-cases `mimeType` to the documented Interactions `mime_type`. */
+export declare function wireInteractionPart(part: InteractionPart): Record<string, string>;
+export declare function isMediaRefPart(part: InteractionPart): part is InteractionMediaRefPart;
+/**
+ * Everything a history message says, in the one order every provider adapter
+ * sends it: `content` first as a text part (when non-empty), then `parts`.
+ * Neither field replaces the other.
+ */
+export declare function historyMessageParts(msg: TurnHistoryMessage): InteractionPart[];

package/esm/src/kernel/interaction-parts.js

@@ -0,0 +1,22 @@
+/** `toGoogleValue` snake-cases `mimeType` to the documented Interactions `mime_type`. */
+export function wireInteractionPart(part) {
+    if (part.type === 'text') {
+        return { type: 'text', text: part.text };
+    }
+    if ('uri' in part) {
+        return { type: part.type, mimeType: part.mimeType, uri: part.uri };
+    }
+    return { type: part.type, mimeType: part.mimeType, data: part.data };
+}
+export function isMediaRefPart(part) {
+    return part.type !== 'text' && 'uri' in part;
+}
+/**
+ * Everything a history message says, in the one order every provider adapter
+ * sends it: `content` first as a text part (when non-empty), then `parts`.
+ * Neither field replaces the other.
+ */
+export function historyMessageParts(msg) {
+    const parts = msg.parts ?? [];
+    return msg.content ? [{ type: 'text', text: msg.content }, ...parts] : [...parts];
+}

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

@@ -0,0 +1,47 @@
+/**
+ * Profile, turn, tool, provider, egress, and event contracts for THEOREM.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export * from './auth/mod.js';
+export { clearProfiles, compactHistory, getProfile, getStructured, getTool, hasProfile, hasTool, invokeTool, listProfiles, listTools, projectProfile, registerProfile, registerProfiles, registerStructured, registerTool, registerTools, requireTool, resetTools, resolveTurn, runDecision, runSession, runTurn, } from './default-scope.js';
+export type { CompactionSplit, CompactionTokens } from './engine/compaction.js';
+export { compactionMeter, compactionNeeded, resolveCompactionTokens, resolveHistoryTokens, shouldCompact, splitForCompaction, } from './engine/compaction.js';
+export type { RunDecisionOptions } from './engine/decision.js';
+export { DecisionError, validateDecisionRequest } from './engine/decision.js';
+export type { LiveIngressChannel } from './engine/live-ingress.js';
+export { assertLiveIngress, assertLiveIngressConfigured, hasAnyLiveIngress, liveIngressChannelDefault, liveIngressEnabled, liveIngressEnabledFromSpec, } from './engine/live-ingress.js';
+export type { RunSessionOptions, SignInGatePolicy } from './engine/session/mod.js';
+export type { MediaPayload, MediaTokenFamily, TokenCount, TokenEstimator, } from './engine/token-estimate.js';
+export { loadTokenEstimator, mediaTokenFamily, TOKEN_TEXT_ENCODING, } from './engine/token-estimate.js';
+export { sumTokens } from './engine/usage.js';
+export { isMediaRefPart, wireInteractionPart } from './interaction-parts.js';
+export type { ProfileGraphEditor, ProfileGraphFacet, ProfileGraphFacetId, ProfileGraphRole, } from './profile-graph.js';
+export { PROFILE_GRAPH, profileGraphFacet, spineFacetsForProfileType, } from './profile-graph.js';
+export type { MediaInputChannel } from './registry/catalog.js';
+export { clampThinkingLevel, clampThinkingLevelForApiId, mediaChannelForMime, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, requireModelBinding, } from './registry/catalog.js';
+export type { KernelRegistry } from './registry/kernel-registry.js';
+export { createKernelRegistry } from './registry/kernel-registry.js';
+export type { DecisionProfileDefinition, HostProfileDefinition, ImageProfileDefinition, LiveProfileDefinition, ProfileDefinition, ProfileDefinitionBase, ProfileRegistry, SpeechProfileDefinition, TextProfileDefinition, } from './registry/profiles.js';
+export { createProfileRegistry, defineProfile } from './registry/profiles.js';
+export { projectProfileObject, requireModelProfile } from './registry/resolve.js';
+export type { SchemaRegistry } from './registry/schemas.js';
+export { createSchemaRegistry } from './registry/schemas.js';
+export type { AuthUnauthenticatedPolicy, CustomToolType, HttpMethod, PlaygroundAuthType, ToolAccess, ToolAuthType, ToolPermission, ToolType, } from './schema.js';
+export { ATTACHMENT_ACCEPT_MIMES, AUTH_UNAUTHENTICATED_POLICIES, AWAITING_USER_INPUT_KINDS, AWAITING_USER_INPUT_STATUS, CACHE_MODES, CACHE_TTLS, COMPACTION_METERS, COMPACTION_OUTCOMES, COMPACTION_TIMINGS, CONTINUE_STOP_KINDS, catalogPathFor, coerceProtocol, coerceProvider, EXTRA_FIELDS, fieldMeta, HTTP_METHODS, IMAGE_ATTACHMENT_ACCEPT_MIMES, isKeySlotName, isToolGateKind, isTurnInjectStage, isTurnStage, isValidPair, isValidProfileProtocol, KEY_SLOT_NAME, MEDIA_INPUT_KIND_VALUES, MEDIA_INPUT_KINDS, MEDIA_WILDCARDS, PLAYGROUND_AUTH_TYPES, PROFILE_FIELDS, PROFILE_TYPE_PROTOCOLS, PROFILE_TYPES, PROTOCOL_PROVIDERS, PROTOCOLS, PROVIDERS, protocolsFor, protocolsForProfileType, providersFor, SPEECH_AUDIO_FORMATS, STREAM_MODES, SUMMARY_MODES, THINKING_LEVELS, TOOL_ACCESS, TOOL_AUTH_TYPES, TOOL_GATE_KINDS, TOOL_LOAD_TIERS, TOOL_PERMISSION, TOOL_TYPES, TURN_INJECT_STAGES, TURN_STAGES, TURN_STOP_KINDS, VOICE_ACCEPT_MIMES, } from './schema.js';
+export type { KernelScope } from './scope.js';
+export { createKernelScope, defaultKernelScope } from './scope.js';
+export type { AwaitingUserInput, StageAffordance, StageApplyInput, StageApplyOutput, StageApplyWarning, StageApplyWarningCode, StageContext, StageEventExtra, StageHandler, StageMutate, StageResult, } from './stages.js';
+export { applyStageResult, isAwaitingUserInput, STAGE_AFFORDANCE_MATRIX, STAGE_AFFORDANCES, stageAllowsAffordance, stageEventFields, } from './stages.js';
+export type { MediaTurnBehaviourSpec, ProfileTurnBehaviourSpec, ProfileTurnResumptionSpec, TurnContinueFrom, TurnStop, } from './stop.js';
+export { AUTO_CONTINUE_DELAY_MS, DEFAULT_ALLOW_CONTINUE, DEFAULT_AUTO_CONTINUE, GenerationStopError, isContinueStopKind, isGenerationStopError, isResumeableStop, isUserCancelledStop, profileAllowsInject, profileAllowsSteering, profileTurnResumption, shouldAutoContinue, turnStopFromClientStreamEnd, turnStopFromInteractionStatus, turnStopFromOpenAiFinishReason, } from './stop.js';
+export { type AnsweredGate, answerGatedCall, GATE_DECISIONS, type GateAnswerRequest, type GateDecision, gateExpired, type HeldGatedCall, resolveGateTtlMs, sessionPermissionsAfterApproval, type ToolGateAuth, } from './tools/gate-answer.js';
+export type { McpProtocolVersion, McpRpcResponse, ToolRegistry } from './tools/mod.js';
+export { askUserTool, coerceToolResultParts, createToolRegistry, executeHttpTool, executeMcpTool, executeRegisteredTool, formatToolResult, isUnsupportedMcpProtocolError, leanToolResultData, MCP_PROTOCOL_VERSIONS, parseMcpRpcResponse, prepareTurnToolSnapshot, projectForModel, registerHarnessTools, resolveToolAuth, } from './tools/mod.js';
+export { CredentialRefusedError } from './tools/signed-in-fetch.js';
+export { awaitingUserInputSchema, TURN_EVENT_SCHEMAS, toolGateSchema, turnDoneOf, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, } from './turn-events.js';
+export type * from './types.js';
+export { base64ToBytes, bytesToBase64 } from './util/base64.js';
+export type { Equals } from './util/exact-type.js';
+export { isRecord } from './util/record.js';

package/esm/src/kernel/mod.js

@@ -0,0 +1,30 @@
+/**
+ * Profile, turn, tool, provider, egress, and event contracts for THEOREM.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export * from './auth/mod.js';
+export { clearProfiles, compactHistory, getProfile, getStructured, getTool, hasProfile, hasTool, invokeTool, listProfiles, listTools, projectProfile, registerProfile, registerProfiles, registerStructured, registerTool, registerTools, requireTool, resetTools, resolveTurn, runDecision, runSession, runTurn, } from './default-scope.js';
+export { compactionMeter, compactionNeeded, resolveCompactionTokens, resolveHistoryTokens, shouldCompact, splitForCompaction, } from './engine/compaction.js';
+export { DecisionError, validateDecisionRequest } from './engine/decision.js';
+export { assertLiveIngress, assertLiveIngressConfigured, hasAnyLiveIngress, liveIngressChannelDefault, liveIngressEnabled, liveIngressEnabledFromSpec, } from './engine/live-ingress.js';
+export { loadTokenEstimator, mediaTokenFamily, TOKEN_TEXT_ENCODING, } from './engine/token-estimate.js';
+export { sumTokens } from './engine/usage.js';
+export { isMediaRefPart, wireInteractionPart } from './interaction-parts.js';
+export { PROFILE_GRAPH, profileGraphFacet, spineFacetsForProfileType, } from './profile-graph.js';
+export { clampThinkingLevel, clampThinkingLevelForApiId, mediaChannelForMime, mediaKindForMime, mimeAllowed, mimeEssence, modelEntryByApiId, requireModelBinding, } from './registry/catalog.js';
+export { createKernelRegistry } from './registry/kernel-registry.js';
+export { createProfileRegistry, defineProfile } from './registry/profiles.js';
+export { projectProfileObject, requireModelProfile } from './registry/resolve.js';
+export { createSchemaRegistry } from './registry/schemas.js';
+export { ATTACHMENT_ACCEPT_MIMES, AUTH_UNAUTHENTICATED_POLICIES, AWAITING_USER_INPUT_KINDS, AWAITING_USER_INPUT_STATUS, CACHE_MODES, CACHE_TTLS, COMPACTION_METERS, COMPACTION_OUTCOMES, COMPACTION_TIMINGS, CONTINUE_STOP_KINDS, catalogPathFor, coerceProtocol, coerceProvider, EXTRA_FIELDS, fieldMeta, HTTP_METHODS, IMAGE_ATTACHMENT_ACCEPT_MIMES, isKeySlotName, isToolGateKind, isTurnInjectStage, isTurnStage, isValidPair, isValidProfileProtocol, KEY_SLOT_NAME, MEDIA_INPUT_KIND_VALUES, MEDIA_INPUT_KINDS, MEDIA_WILDCARDS, PLAYGROUND_AUTH_TYPES, PROFILE_FIELDS, PROFILE_TYPE_PROTOCOLS, PROFILE_TYPES, PROTOCOL_PROVIDERS, PROTOCOLS, PROVIDERS, protocolsFor, protocolsForProfileType, providersFor, SPEECH_AUDIO_FORMATS, STREAM_MODES, SUMMARY_MODES, THINKING_LEVELS, TOOL_ACCESS, TOOL_AUTH_TYPES, TOOL_GATE_KINDS, TOOL_LOAD_TIERS, TOOL_PERMISSION, TOOL_TYPES, TURN_INJECT_STAGES, TURN_STAGES, TURN_STOP_KINDS, VOICE_ACCEPT_MIMES, } from './schema.js';
+export { createKernelScope, defaultKernelScope } from './scope.js';
+export { applyStageResult, isAwaitingUserInput, STAGE_AFFORDANCE_MATRIX, STAGE_AFFORDANCES, stageAllowsAffordance, stageEventFields, } from './stages.js';
+export { AUTO_CONTINUE_DELAY_MS, DEFAULT_ALLOW_CONTINUE, DEFAULT_AUTO_CONTINUE, GenerationStopError, isContinueStopKind, isGenerationStopError, isResumeableStop, isUserCancelledStop, profileAllowsInject, profileAllowsSteering, profileTurnResumption, shouldAutoContinue, turnStopFromClientStreamEnd, turnStopFromInteractionStatus, turnStopFromOpenAiFinishReason, } from './stop.js';
+export { answerGatedCall, GATE_DECISIONS, gateExpired, resolveGateTtlMs, sessionPermissionsAfterApproval, } from './tools/gate-answer.js';
+export { askUserTool, coerceToolResultParts, createToolRegistry, executeHttpTool, executeMcpTool, executeRegisteredTool, formatToolResult, isUnsupportedMcpProtocolError, leanToolResultData, MCP_PROTOCOL_VERSIONS, parseMcpRpcResponse, prepareTurnToolSnapshot, projectForModel, registerHarnessTools, resolveToolAuth, } from './tools/mod.js';
+export { CredentialRefusedError } from './tools/signed-in-fetch.js';
+export { awaitingUserInputSchema, TURN_EVENT_SCHEMAS, toolGateSchema, turnDoneOf, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, } from './turn-events.js';
+export { base64ToBytes, bytesToBase64 } from './util/base64.js';
+export { isRecord } from './util/record.js';

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

@@ -0,0 +1,140 @@
+import type { ProfileType } from './schema.js';
+export type ProfileGraphEditor = 'schema' | 'structural';
+export type ProfileGraphRole = 'root' | 'spine' | 'branch';
+/**
+ * Adding a profile section? Add it to PROFILE_FIELDS and a row here, never a FacetKind in the
+ * frontend. Each facet's `profileTypes` come from `PROFILE_FIELD_SCOPE` via its `profilePath`.
+ */
+declare const PROFILE_GRAPH_DEF: readonly [{
+    readonly id: "identity";
+    readonly profilePath: "identity";
+    readonly role: "root";
+    readonly optional: false;
+    readonly editor: "structural";
+    readonly label: "Identity";
+    readonly ownsFields: readonly ["id", "type"];
+}, {
+    readonly id: "models";
+    readonly profilePath: "models";
+    readonly role: "spine";
+    readonly optional: false;
+    readonly editor: "structural";
+    readonly label: "Models";
+    readonly ownsFields: readonly ["defaultModel", "allowModelSelect", "maxSteps", "key", "fallbackKey"];
+}, {
+    readonly id: "modelBinding";
+    readonly profilePath: "models.*";
+    readonly role: "branch";
+    readonly parent: "models";
+    readonly optional: false;
+    readonly editor: "structural";
+    readonly label: "Model binding";
+}, {
+    readonly id: "decision";
+    readonly profilePath: "decision";
+    readonly role: "spine";
+    readonly optional: false;
+    readonly editor: "structural";
+    readonly label: "Decision";
+    readonly ownsFields: readonly ["inputs"];
+}, {
+    readonly id: "image";
+    readonly profilePath: "image";
+    readonly role: "spine";
+    readonly optional: false;
+    readonly editor: "structural";
+    readonly label: "Image";
+}, {
+    readonly id: "speech";
+    readonly profilePath: "speech";
+    readonly role: "spine";
+    readonly optional: false;
+    readonly editor: "structural";
+    readonly label: "Speech";
+}, {
+    readonly id: "live";
+    readonly profilePath: "live";
+    readonly role: "spine";
+    readonly optional: false;
+    readonly editor: "structural";
+    readonly label: "Live";
+}, {
+    readonly id: "tools";
+    readonly profilePath: "tools";
+    readonly role: "spine";
+    readonly optional: false;
+    readonly editor: "structural";
+    readonly label: "Tools";
+}, {
+    readonly id: "toolSpec";
+    readonly profilePath: "tools.allow";
+    readonly role: "branch";
+    readonly parent: "tools";
+    readonly optional: true;
+    readonly editor: "structural";
+    readonly label: "Tool";
+}, {
+    readonly id: "inputs";
+    readonly profilePath: "inputs";
+    readonly role: "spine";
+    readonly optional: false;
+    readonly editor: "structural";
+    readonly label: "Inputs";
+}, {
+    readonly id: "outputs";
+    readonly profilePath: "outputs";
+    readonly role: "spine";
+    readonly optional: true;
+    readonly editor: "structural";
+    readonly label: "Outputs";
+}, {
+    readonly id: "turnBehaviour";
+    readonly profilePath: "turnBehaviour";
+    readonly role: "spine";
+    readonly optional: true;
+    readonly editor: "structural";
+    readonly label: "Turn behaviour";
+}, {
+    readonly id: "guardrails";
+    readonly profilePath: "guardrails";
+    readonly role: "spine";
+    readonly optional: true;
+    readonly editor: "structural";
+    readonly label: "Guardrails";
+}, {
+    readonly id: "observability";
+    readonly profilePath: "observability";
+    readonly role: "spine";
+    readonly optional: true;
+    readonly editor: "structural";
+    readonly label: "Observability";
+}, {
+    readonly id: "wording";
+    readonly profilePath: "lexicon";
+    readonly role: "spine";
+    readonly optional: true;
+    readonly editor: "structural";
+    readonly label: "Wording";
+}];
+export type ProfileGraphFacetId = (typeof PROFILE_GRAPH_DEF)[number]['id'];
+/** `profilePath` is a PROFILE_FIELDS key (section root) or a dynamic path (`models.*`). */
+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[];
+declare function profileGraphFacet(id: ProfileGraphFacetId): ProfileGraphFacet | undefined;
+export { profileGraphFacet, spineFacetsForProfileType };

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

@@ -0,0 +1,151 @@
+import { ALL_PROFILE_TYPES, profileTypesForField } from './profile-scope.js';
+/**
+ * Adding a profile section? Add it to PROFILE_FIELDS and a row here, never a FacetKind in the
+ * frontend. Each facet's `profileTypes` come from `PROFILE_FIELD_SCOPE` via its `profilePath`.
+ */
+const PROFILE_GRAPH_DEF = [
+    {
+        id: 'identity',
+        profilePath: 'identity',
+        role: 'root',
+        optional: false,
+        editor: 'structural',
+        label: 'Identity',
+        ownsFields: ['id', 'type'],
+    },
+    {
+        id: 'models',
+        profilePath: 'models',
+        role: 'spine',
+        optional: false,
+        editor: 'structural',
+        label: 'Models',
+        ownsFields: ['defaultModel', 'allowModelSelect', 'maxSteps', 'key', 'fallbackKey'],
+    },
+    {
+        id: 'modelBinding',
+        profilePath: 'models.*',
+        role: 'branch',
+        parent: 'models',
+        optional: false,
+        editor: 'structural',
+        label: 'Model binding',
+    },
+    {
+        id: 'decision',
+        profilePath: 'decision',
+        role: 'spine',
+        optional: false,
+        editor: 'structural',
+        label: 'Decision',
+        ownsFields: ['inputs'],
+    },
+    {
+        id: 'image',
+        profilePath: 'image',
+        role: 'spine',
+        optional: false,
+        editor: 'structural',
+        label: 'Image',
+    },
+    {
+        id: 'speech',
+        profilePath: 'speech',
+        role: 'spine',
+        optional: false,
+        editor: 'structural',
+        label: 'Speech',
+    },
+    {
+        id: 'live',
+        profilePath: 'live',
+        role: 'spine',
+        optional: false,
+        editor: 'structural',
+        label: 'Live',
+    },
+    {
+        id: 'tools',
+        profilePath: 'tools',
+        role: 'spine',
+        optional: false,
+        editor: 'structural',
+        label: 'Tools',
+    },
+    {
+        id: 'toolSpec',
+        profilePath: 'tools.allow',
+        role: 'branch',
+        parent: 'tools',
+        optional: true,
+        editor: 'structural',
+        label: 'Tool',
+    },
+    {
+        id: 'inputs',
+        profilePath: 'inputs',
+        role: 'spine',
+        optional: false,
+        editor: 'structural',
+        label: 'Inputs',
+    },
+    {
+        id: 'outputs',
+        profilePath: 'outputs',
+        role: 'spine',
+        optional: true,
+        editor: 'structural',
+        label: 'Outputs',
+    },
+    {
+        id: 'turnBehaviour',
+        profilePath: 'turnBehaviour',
+        role: 'spine',
+        optional: true,
+        editor: 'structural',
+        label: 'Turn behaviour',
+    },
+    {
+        id: 'guardrails',
+        profilePath: 'guardrails',
+        role: 'spine',
+        optional: true,
+        editor: 'structural',
+        label: 'Guardrails',
+    },
+    {
+        id: 'observability',
+        profilePath: 'observability',
+        role: 'spine',
+        optional: true,
+        editor: 'structural',
+        label: 'Observability',
+    },
+    {
+        id: 'wording',
+        profilePath: 'lexicon',
+        role: 'spine',
+        optional: true,
+        editor: 'structural',
+        label: 'Wording',
+    },
+];
+/** The facets whose types differ from their `profilePath`'s scope. */
+const FACET_PROFILE_TYPES = {
+    // The root holds `id` and `type`, which every profile has.
+    identity: ALL_PROFILE_TYPES,
+    // A decision's inputs belong to its Decision facet.
+    inputs: profileTypesForField('inputs').filter((type) => type !== 'decision'),
+};
+export const PROFILE_GRAPH = PROFILE_GRAPH_DEF.map((facet) => ({
+    ...facet,
+    profileTypes: FACET_PROFILE_TYPES[facet.id] ?? profileTypesForField(facet.profilePath),
+}));
+/** 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));
+}
+function profileGraphFacet(id) {
+    return PROFILE_GRAPH.find((facet) => facet.id === id);
+}
+export { profileGraphFacet, spineFacetsForProfileType };

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

@@ -0,0 +1,9 @@
+/** lexicon-exempt-file: authoring field-meta presence notes — not runtime user or model copy (P2) */
+export interface ProfileFieldPresence {
+    /** The profile must set the field: always (`true`), or only in the case named. */
+    required?: true | string;
+    /** What leaving the field out does, as a short phrase a blank control can show. */
+    unset?: string;
+}
+/** Presence for profile paths, keyed like `PROFILE_FIELDS` (`models.*` matches every binding). */
+export declare const PROFILE_FIELD_PRESENCE: Readonly<Record<string, ProfileFieldPresence>>;