@theoremjs/agents 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,158 @@
+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: ['profile.id', 'profile.type'],
+    },
+    {
+        id: 'models',
+        profilePath: 'models',
+        role: 'spine',
+        optional: false,
+        editor: 'structural',
+        label: 'Models',
+        ownsFields: [
+            'profile.defaultModel',
+            'profile.allowModelSelect',
+            'profile.maxSteps',
+            'providerContinuation',
+        ],
+    },
+    {
+        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: 'labels',
+        profilePath: 'labels',
+        role: 'spine',
+        optional: true,
+        editor: 'structural',
+        label: 'Labels',
+    },
+];
+/** The facets whose types differ from their `profilePath`'s scope. */
+const FACET_PROFILE_TYPES = {
+    // why: The root holds `id` and `type`, which every profile has.
+    identity: ALL_PROFILE_TYPES,
+    // why: A decision's inputs belong to its Decision facet.
+    inputs: profileTypesForField('inputs').filter((type) => type !== 'decision'),
+};
+/** The profile graph: each facet, with the profile types it applies to. */
+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));
+}
+/** The facet with this id, or `undefined`. */
+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,18 @@
+/** labels-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;
+    /**
+     * The value leaving the field out stands for, where one value says it: a profile that writes
+     * this value and one that leaves the field out are the same profile.
+     */
+    value?: unknown;
+}
+/** The most model calls a turn makes when its profile sets no `maxSteps`. */
+export declare const DEFAULT_MAX_STEPS = 20;
+/** Presence for profile paths, keyed like `PROFILE_FIELDS` (`models.*` matches every binding). */
+export declare const PROFILE_FIELD_PRESENCE: Readonly<Record<string, ProfileFieldPresence>>;
+/** The value leaving the field at `path` out stands for, or nothing when no one value says it. */
+export declare function unsetValue(path: readonly string[]): unknown;

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

@@ -0,0 +1,158 @@
+/** The most model calls a turn makes when its profile sets no `maxSteps`. */
+export const DEFAULT_MAX_STEPS = 20;
+/** Presence for profile paths, keyed like `PROFILE_FIELDS` (`models.*` matches every binding). */
+export const PROFILE_FIELD_PRESENCE = {
+    'profile.id': { required: true },
+    'profile.type': { required: true },
+    identity: { required: true },
+    'identity.handle': { required: true },
+    'identity.system': { unset: "Only the kernel's notes" },
+    tools: { required: true },
+    'tools.allow': { required: true },
+    image: { required: true },
+    speech: { required: true },
+    live: { required: true },
+    decision: { required: true },
+    'decision.contract': { required: true },
+    models: { required: true },
+    'profile.defaultModel': {
+        required: 'when more than one model is declared',
+        unset: 'The only model',
+    },
+    'profile.allowModelSelect': { unset: 'Off', value: false },
+    'profile.maxSteps': { unset: `${DEFAULT_MAX_STEPS} model calls`, value: DEFAULT_MAX_STEPS },
+    'models.*.protocol': { required: true },
+    'models.*.provider': { required: true },
+    'models.*.options': { unset: "The protocol's defaults" },
+    'models.*.keySlot': { unset: 'Provider primary slot' },
+    'models.*.fallbackKeySlot': { unset: 'Provider fallback slot, when configured' },
+    providerContinuation: { unset: 'The host keeps the history' },
+    'providerContinuation.history': { unset: 'host', value: 'host' },
+    'models.*.apiId': { required: true },
+    'models.*.builtInTools': { unset: 'None', value: [] },
+    'models.*.maxOutputTokens': { unset: 'Provider default' },
+    'models.*.temperature': { unset: 'Provider default' },
+    'models.*.summaries': { unset: 'Provider default' },
+    'models.*.efforts': { unset: 'Provider default' },
+    'models.*.defaultEffort': {
+        required: 'when more than one effort is declared',
+        unset: 'The only effort',
+    },
+    'models.*.allowEffortSelect': { unset: 'Off', value: false },
+    'models.*.timeoutMs': { unset: 'No timeout' },
+    'models.*.compaction': { unset: 'Off' },
+    'models.*.compaction.maxTokens': { required: true },
+    'models.*.compaction.compactAt': { required: true },
+    'models.*.compaction.previousExchanges': { required: true },
+    'models.*.compaction.profile': { unset: 'The agent itself, on a text profile' },
+    'models.*.compaction.trigger': { unset: 'compactAt of maxTokens' },
+    'models.*.compaction.timing': { required: true },
+    'models.*.compaction.meter': { unset: 'history', value: 'history' },
+    inputs: { required: 'on every type that takes it but live', unset: 'No slots or context' },
+    'inputs.text': { unset: 'Accepted', value: true },
+    'inputs.attachments.accept': { unset: 'No attachments' },
+    'inputs.voice.accept': { unset: 'No voice' },
+    'inputs.maxFiles': { required: 'when attachments or voice is set' },
+    'inputs.maxBytes': { required: 'when attachments or voice is set' },
+    'inputs.maxTurnBytes': { required: 'when attachments or voice is set' },
+    'inputs.state': { required: true },
+    'inputs.maxStateBytes': { unset: 'No cap' },
+    'inputs.limitsByMime': { unset: 'maxBytes for every type' },
+    'inputs.slots': { unset: 'No slots' },
+    'inputs.context': { unset: 'No context' },
+    'inputs.context.from': { required: true },
+    'inputs.context.maxChars': { required: true },
+    'outputs.structured': { unset: 'Free text', value: null },
+    'outputs.validation.maxRetries': { unset: '0', value: 0 },
+    'outputs.streaming.mode': { unset: 'sse', value: 'sse' },
+    'outputs.streaming.streamThoughts': { unset: 'On', value: true },
+    'turnBehaviour.resumption.allowContinue': {
+        unset: 'All three',
+        value: ['length', 'stream_incomplete', 'provider_error'],
+    },
+    'turnBehaviour.resumption.autoContinue': {
+        unset: 'length and stream_incomplete',
+        value: ['length', 'stream_incomplete'],
+    },
+    'turnBehaviour.resumption.maxContinues': { unset: 'No cap' },
+    'turnBehaviour.allowSteering': { unset: 'On', value: true },
+    'turnBehaviour.atStepLimit': { unset: 'stop', value: 'stop' },
+    'guardrails.quota': { unset: 'No limit' },
+    'guardrails.detect': { unset: 'Redacts what goes to the model' },
+    'guardrails.detect.ungiven_images.allow.fromTools': { unset: 'On', value: true },
+    'guardrails.detect.ungiven_links.allow.fromTools': { unset: 'On', value: true },
+    'guardrails.blockedReply': { unset: 'One rewrite' },
+    'guardrails.blockedReply.onBlock': { unset: 'retry', value: 'retry' },
+    'guardrails.blockedReply.maxRetries': { unset: '1', value: 1 },
+    'guardrails.network.allowPrivateNetworks': { unset: 'Off', value: false },
+    'guardrails.network.allowedHosts': { unset: 'None', value: [] },
+    'guardrails.network.allowedSchemes': {
+        unset: 'https, plus http when allowPrivateNetworks is on',
+    },
+    'guardrails.taint.afterRemoteRead': { unset: 'off', value: 'off' },
+    'guardrails.taint.remoteDestination': { unset: 'off', value: 'off' },
+    'guardrails.disclosure': { unset: 'No check' },
+    'observability.writeTo': { unset: 'No traces, unless runTurn is given a sink' },
+    'observability.sampleRate': { unset: '1', value: 1 },
+    'observability.include.upstreamLog': { unset: 'On', value: true },
+    'observability.include.outboundWire': {
+        unset: 'Off; on when the profile has no observability block',
+    },
+    'observability.include.evidenceRaw': {
+        unset: 'Off; on when the profile has no observability block',
+    },
+    'observability.include.usage': { unset: 'On', value: true },
+    'observability.include.guardrailDecisions': { unset: 'On', value: true },
+    'observability.include.guardrailMatchPreview': { unset: 'Off', value: false },
+    'observability.resource': { unset: 'None' },
+    'observability.scrub.sensitive': { unset: 'On', value: true },
+    'observability.scrub.injection': { unset: 'On', value: true },
+    'observability.scrub.canary': { unset: 'On', value: true },
+    'observability.retainForDays': { unset: '14', value: 14 },
+    'observability.rotateAfterMiB': { unset: '32', value: 32 },
+    'observability.onWriteError': { unset: 'Errors are dropped' },
+    'image.aspectRatio': { unset: 'Provider default' },
+    'image.resolution': { unset: 'Provider default' },
+    'image.mimeType': { unset: 'Provider default' },
+    'image.quality': { unset: 'Provider default' },
+    'image.background': { unset: 'Provider default' },
+    'image.n': { unset: 'Provider default' },
+    'image.seed': { unset: 'Provider default' },
+    'image.outputCompression': { unset: 'Provider default' },
+    'image.references': { unset: 'None' },
+    'image.includeText': { unset: 'Off', value: false },
+    'speech.voice': { unset: "The turn's speech.voice; Gemini refuses speech without one" },
+    'speech.style': { unset: "The turn's speech.style, else no direction" },
+    'speech.speed': { unset: "The turn's speech.speed, else the voice's own pace" },
+    'speech.format': { unset: 'Provider default' },
+    'live.ingress.audio': { unset: 'On', value: true },
+    'live.ingress.video': { unset: 'On', value: true },
+    'live.ingress.text': { unset: 'Off', value: false },
+    'live.voice': { unset: 'Provider default' },
+    'live.vad.activityHandling': { unset: 'Provider default' },
+    'live.vad.startSensitivity': { unset: 'Provider default' },
+    'live.vad.endSensitivity': { unset: 'Provider default' },
+    'live.vad.prefixPaddingMs': { unset: 'Provider default' },
+    'live.vad.silenceDurationMs': { unset: 'Provider default' },
+    'live.sessionResumption': { unset: 'Off', value: false },
+    'live.greeting': { unset: 'The agent waits for the visitor' },
+    'live.resumed': { unset: 'A resumed call is silent' },
+    'live.resumed.prompt': { required: true },
+    'live.resumed.afterMs': { unset: '3000' },
+    'live.contextCompression': { unset: 'Off' },
+    'live.contextCompression.triggerTokens': { unset: 'Provider default' },
+    'live.contextCompression.slidingWindow': { required: true },
+    'live.contextCompression.slidingWindow.targetTokens': { unset: 'Provider default' },
+    'live.transcription.input': { unset: 'Off' },
+    'live.transcription.output': {
+        unset: 'Off; on with a detector at live_reply',
+    },
+};
+/** The value leaving the field at `path` out stands for, or nothing when no one value says it. */
+export function unsetValue(path) {
+    const held = Object.entries(PROFILE_FIELD_PRESENCE).find(([known]) => {
+        const keys = known.replace(/^profile\./, '').split('.');
+        return keys.length === path.length && keys.every((key, at) => key === '*' || key === path[at]);
+    });
+    return held?.[1].value;
+}

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

@@ -0,0 +1,40 @@
+import type { ProfileType } from './schema.js';
+/**
+ * Mirrors `PROFILE_TYPES` — a value import would cycle through `schema.ts`.
+ * Drift is gated by tests/kernel/profile-scope.test.ts.
+ */
+export declare const ALL_PROFILE_TYPES: readonly ProfileType[];
+export interface ProfileFieldScope {
+    profileTypes: readonly ProfileType[];
+    /** Why other types can't take it — shown in `defineProfile` errors and authoring UIs. */
+    reason: string;
+    /**
+     * The one value other types may still carry: the field's "off" value
+     * (`outputs.structured: null` asks for no schema).
+     */
+    offValue?: null;
+}
+/** Whether a top-level profile key is one of the profile's own settings. */
+export declare function isProfileRootField(key: string): boolean;
+/** The keys of the profile object that a catalog path names: `profile.maxSteps` is `maxSteps`. */
+export declare function profileKeysOf(catalogPath: string): string[];
+/** Keyed like `PROFILE_FIELDS`; `models.*` matches every model binding. */
+export declare const PROFILE_FIELD_SCOPE: Readonly<Record<string, ProfileFieldScope>>;
+/**
+ * The scope entry that governs `path`: its own, else its nearest ancestor's.
+ * `undefined` means every profile type.
+ */
+export declare function profileFieldScope(path: string): ProfileFieldScope | undefined;
+export declare function profileTypesForField(path: string): readonly ProfileType[];
+export interface OutOfScopeField {
+    /** e.g. `models.fast.compaction` for the `models.*.compaction` scope. */
+    path: string;
+    scope: ProfileFieldScope;
+}
+/**
+ * Every field `profile` sets that its type may not, ancestors before their
+ * children. A scope's off value is not reported.
+ */
+export declare function outOfScopeFields(profile: {
+    readonly type: ProfileType;
+}): OutOfScopeField[];

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

@@ -0,0 +1,274 @@
+// invariant: Leaf module: `schema.ts` and `profile-graph.ts` read it at load time.
+/** labels-exempt-file: authoring field-meta scope reasons — not runtime user or model copy (P2) */
+import { HOST_GUARDRAIL_FIELDS } from '../guardrails/types.js';
+/**
+ * Mirrors `PROFILE_TYPES` — a value import would cycle through `schema.ts`.
+ * Drift is gated by tests/kernel/profile-scope.test.ts.
+ */
+export const ALL_PROFILE_TYPES = [
+    'text',
+    'image',
+    'speech',
+    'live',
+    'decision',
+    'embedding',
+    'host',
+];
+const MODEL_PROFILE_TYPES = [
+    'text',
+    'image',
+    'speech',
+    'live',
+    'decision',
+    'embedding',
+];
+const TURN_TYPES = ['text', 'image', 'speech', 'live'];
+/** Types whose `inputs` are turn inputs (text, files, slots) rather than decision state. */
+const TURN_INPUT_TYPES = ['text', 'image'];
+const TURN_INPUT_REASON = 'a decision takes JSON state, not turn text, files, or slots';
+/** Types that take slots and context: the turn types, and a call. */
+const SLOT_TYPES = ['text', 'image', 'live'];
+const SLOT_REASON = 'a decision takes JSON state, and speech reads its transcript only';
+/** Guardrails a host profile may set keep `host`; the rest guard a model turn. */
+function turnGuardrailTypes(key) {
+    return HOST_GUARDRAIL_FIELDS.includes(key)
+        ? [...TURN_TYPES, 'host']
+        : TURN_TYPES;
+}
+/**
+ * The profile's own settings, which no section holds. The catalog names each `profile.<key>`, as
+ * a section's fields carry their section's name.
+ */
+const PROFILE_ROOT_FIELDS = ['id', 'type', 'defaultModel', 'allowModelSelect', 'maxSteps'];
+/** Whether a top-level profile key is one of the profile's own settings. */
+export function isProfileRootField(key) {
+    return PROFILE_ROOT_FIELDS.includes(key);
+}
+/** The keys of the profile object that a catalog path names: `profile.maxSteps` is `maxSteps`. */
+export function profileKeysOf(catalogPath) {
+    return catalogPath.replace(/^profile\./, '').split('.');
+}
+/** Keyed like `PROFILE_FIELDS`; `models.*` matches every model binding. */
+export const PROFILE_FIELD_SCOPE = {
+    providerContinuation: {
+        profileTypes: TURN_TYPES,
+        reason: 'only model turns and live sessions use provider continuation',
+    },
+    ...Object.fromEntries([
+        'efforts',
+        'defaultEffort',
+        'allowEffortSelect',
+        'summaries',
+        'maxOutputTokens',
+        'temperature',
+        'builtInTools',
+    ].map((field) => [
+        `models.*.${field}`,
+        {
+            profileTypes: TURN_TYPES,
+            reason: 'only model turns use this setting; decisions send state and questions',
+        },
+    ])),
+    'models.*.timeoutMs': {
+        profileTypes: ['decision'],
+        reason: 'only decision bindings configure a request timeout here',
+    },
+    identity: {
+        profileTypes: MODEL_PROFILE_TYPES,
+        reason: 'a host profile has no agent identity — it runs no model',
+    },
+    'identity.system': {
+        profileTypes: ['text', 'image', 'live'],
+        reason: 'speech has no system channel (the input text is the transcript) and a decision is asked only through its questions',
+    },
+    'identity.systemByRole': {
+        profileTypes: ['text', 'image', 'live'],
+        reason: 'speech has no system channel (the input text is the transcript) and a decision is asked only through its questions',
+    },
+    models: { profileTypes: MODEL_PROFILE_TYPES, reason: 'a host profile runs no model' },
+    'models.*.protocol': {
+        profileTypes: MODEL_PROFILE_TYPES,
+        reason: 'a host profile runs no model',
+    },
+    'models.*.provider': {
+        profileTypes: MODEL_PROFILE_TYPES,
+        reason: 'a host profile runs no model',
+    },
+    'models.*.compaction': {
+        profileTypes: ['text', 'image', 'speech'],
+        reason: 'live compacts with live.contextCompression',
+    },
+    'profile.defaultModel': {
+        profileTypes: [...TURN_TYPES, 'embedding'],
+        reason: 'a host profile runs no model and a decision declares exactly one',
+    },
+    'profile.allowModelSelect': {
+        profileTypes: [...TURN_TYPES, 'embedding'],
+        reason: 'a host profile runs no model and a decision declares exactly one',
+    },
+    'profile.maxSteps': {
+        profileTypes: TURN_TYPES,
+        reason: 'only model turns take tool-loop steps',
+    },
+    decision: { profileTypes: ['decision'], reason: 'only decision profiles carry a contract' },
+    image: { profileTypes: ['image'], reason: 'only image profiles generate images' },
+    speech: { profileTypes: ['speech'], reason: 'only speech profiles synthesize audio' },
+    live: { profileTypes: ['live'], reason: 'only live profiles open a realtime session' },
+    tools: {
+        profileTypes: ['text', 'image', 'live', 'host'],
+        reason: 'speech and decision profiles call no tools',
+    },
+    'tools.t1Policy': {
+        profileTypes: ['text', 'image'],
+        reason: 'live wires every allowed tool once at session setup, and a host profile can execute every allowed tool',
+    },
+    'tools.t2Loader': {
+        profileTypes: ['text', 'image'],
+        reason: 'live function declarations are fixed at session setup, and a host profile can execute every allowed tool',
+    },
+    inputs: {
+        profileTypes: ['text', 'image', 'live', 'decision', 'embedding'],
+        reason: 'speech input is the transcript, and a host profile takes no turns',
+    },
+    'inputs.voice': {
+        profileTypes: ['text'],
+        reason: 'no image model reads audio, and a decision takes JSON state',
+    },
+    'inputs.text': {
+        profileTypes: [...TURN_INPUT_TYPES, 'embedding'],
+        reason: TURN_INPUT_REASON,
+    },
+    'inputs.attachments': {
+        profileTypes: [...TURN_INPUT_TYPES, 'embedding'],
+        reason: TURN_INPUT_REASON,
+    },
+    'inputs.maxFiles': {
+        profileTypes: [...TURN_INPUT_TYPES, 'embedding'],
+        reason: TURN_INPUT_REASON,
+    },
+    'inputs.maxBytes': {
+        profileTypes: [...TURN_INPUT_TYPES, 'embedding'],
+        reason: TURN_INPUT_REASON,
+    },
+    'inputs.maxTurnBytes': {
+        profileTypes: [...TURN_INPUT_TYPES, 'embedding'],
+        reason: TURN_INPUT_REASON,
+    },
+    'inputs.limitsByMime': {
+        profileTypes: [...TURN_INPUT_TYPES, 'embedding'],
+        reason: TURN_INPUT_REASON,
+    },
+    'inputs.slots': {
+        profileTypes: SLOT_TYPES,
+        reason: SLOT_REASON,
+    },
+    'inputs.context': {
+        profileTypes: SLOT_TYPES,
+        reason: SLOT_REASON,
+    },
+    'inputs.state': {
+        profileTypes: ['decision'],
+        reason: 'only a decision reads JSON state; a turn takes text, files, and slots',
+    },
+    'inputs.maxStateBytes': {
+        profileTypes: ['decision'],
+        reason: 'only a decision reads JSON state; a turn takes text, files, and slots',
+    },
+    outputs: {
+        profileTypes: ['text', 'image', 'speech'],
+        reason: 'live output is the realtime session, and decision and host profiles produce no turn output',
+    },
+    'outputs.structured': {
+        profileTypes: ['text'],
+        reason: 'only a text reply has a JSON shape; image and speech turns return media',
+        offValue: null,
+    },
+    'outputs.validation': {
+        profileTypes: ['text'],
+        reason: 'validation checks a structured reply, which only text profiles make',
+    },
+    turnBehaviour: {
+        profileTypes: TURN_TYPES,
+        reason: 'only model turns can be continued or steered',
+    },
+    'turnBehaviour.resumption': {
+        profileTypes: ['text', 'image', 'speech'],
+        reason: 'live resumes through live.sessionResumption',
+    },
+    'turnBehaviour.allowSteering': {
+        profileTypes: ['text', 'live'],
+        reason: 'image and speech turns take no mid-turn input',
+    },
+    'turnBehaviour.atStepLimit': {
+        profileTypes: ['text'],
+        reason: 'only a text turn writes an answer after its tools',
+    },
+    'guardrails.quota': {
+        profileTypes: turnGuardrailTypes('quota'),
+        reason: 'quota counts model turns',
+    },
+    'guardrails.detect': {
+        profileTypes: turnGuardrailTypes('detect'),
+        reason: 'the decision path runs none of the turn guardrails',
+    },
+    'guardrails.blockedReply': {
+        profileTypes: ['text', 'image', 'live'],
+        reason: 'only a reply can be blocked, and speech, decision, and host profiles write none',
+    },
+    'guardrails.network': {
+        profileTypes: ['text', 'image', 'live', 'host'],
+        reason: 'speech and decision profiles call no tools',
+    },
+    'guardrails.taint': {
+        profileTypes: ['text', 'image', 'live'],
+        reason: 'speech and decision profiles call no tools, and a host profile runs no turn to taint',
+    },
+    'guardrails.disclosure': {
+        profileTypes: ['decision'],
+        reason: 'disclosure gates state leaving a decision profile for its model',
+    },
+};
+/**
+ * The scope entry that governs `path`: its own, else its nearest ancestor's.
+ * `undefined` means every profile type.
+ */
+export function profileFieldScope(path) {
+    const segments = path.split('.');
+    for (let end = segments.length; end > 0; end--) {
+        const scope = PROFILE_FIELD_SCOPE[segments.slice(0, end).join('.')];
+        if (scope)
+            return scope;
+    }
+    return undefined;
+}
+export function profileTypesForField(path) {
+    return profileFieldScope(path)?.profileTypes ?? ALL_PROFILE_TYPES;
+}
+/** Every set value under `segments`, keyed by concrete path; `*` walks each key of a map. */
+function valuesAt(root, segments, at = '') {
+    if (!segments.length)
+        return root === undefined ? [] : [[at, root]];
+    if (root === null || typeof root !== 'object')
+        return [];
+    const [head, ...rest] = segments;
+    const record = root;
+    const keys = head === '*' ? Object.keys(record) : [head];
+    return keys.flatMap((key) => valuesAt(record[key], rest, at ? `${at}.${key}` : key));
+}
+/**
+ * Every field `profile` sets that its type may not, ancestors before their
+ * children. A scope's off value is not reported.
+ */
+export function outOfScopeFields(profile) {
+    const out = [];
+    for (const [path, scope] of Object.entries(PROFILE_FIELD_SCOPE)) {
+        if (scope.profileTypes.includes(profile.type))
+            continue;
+        for (const [at, value] of valuesAt(profile, profileKeysOf(path))) {
+            if (scope.offValue !== undefined && value === scope.offValue)
+                continue;
+            out.push({ path: at, scope });
+        }
+    }
+    return out;
+}