@aid-framework/ir 0.0.0-stage → 0.1.39

package/dist/build.js

@@ -0,0 +1,1079 @@
+/**
+ * The builder: a validated spec document value -> IR v0.1.
+ *
+ * The builder never throws for a user-recoverable condition. It applies Phase 0
+ * defaults (so generated code never supplies a default of its own), sorts every
+ * object-derived collection by stable id (so YAML key order cannot change the IR),
+ * and reports `ir/*` diagnostics through the same shape every other gate uses.
+ */
+import { SPEC_VERSION } from '@aid-framework/spec';
+import { deriveRequiredCapabilities, isModelCapability, SPEC_MODEL_CAPABILITY_MAP, } from './capabilities.js';
+import { catalogCostProfile, catalogModel } from './catalog/index.js';
+import { parsePolicyExpr } from './policy/index.js';
+import { parsePredicateExpr } from './predicate/index.js';
+import { AGENT_ENGINES, AGENT_ON_BUDGET_EXHAUSTED, DEFAULT_MAX_CONTEXT_TOKENS, DEFAULT_OBSERVABILITY, DEFAULT_RUNTIME, IR_VERSION, isGuardrailPolicyKind, isIndexMetric, isProvider, isVectorStoreKind, modelIdentity, PRIMITIVE_TYPES, pipelineIdentity, promptIdentity, RETRIEVAL_TRAITS, toolIdentity, } from './shapes.js';
+export const DEFAULT_TARGET = 'py-fastapi';
+export const DEFAULT_TOOL_TIMEOUT_MS = 30_000;
+export const DEFAULT_TOOL_RETRIES = 0;
+export const DEFAULT_IDEMPOTENCY = 'none';
+export const DEFAULT_EVAL_MAX_REGRESSION = 0;
+export const DEFAULT_EVAL_SAMPLES = 5;
+/**
+ * Retrieval defaults. The spec schema requires every one of these fields, so they
+ * are only reached by a value that skipped validation; they mirror the §6 example
+ * rather than inventing a policy a valid spec could disagree with.
+ */
+export const DEFAULT_SOURCE_KIND = 'file';
+export const DEFAULT_CHUNK_STRATEGY = 'recursive';
+export const DEFAULT_CHUNK_SIZE = 800;
+export const DEFAULT_CHUNK_OVERLAP = 0;
+export const DEFAULT_INDEX_METRIC = 'cosine';
+export const DEFAULT_RETRIEVER_TOP_K = 5;
+export const DEFAULT_REFRESH_MODE = 'full';
+/** Same posture as the retrieval defaults: reached only by a value that skipped validation. */
+export const DEFAULT_MEMORY_TOKEN_BUDGET = 4096;
+const BINDING_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+const TYPE_NAME_PATTERN = /^([A-Za-z][A-Za-z0-9]*)(\[\])?$/;
+const EVAL_TARGET_PATTERN = /^([a-z][a-z0-9-]*):([a-z][a-z0-9_]{0,63})$/;
+const SOLE_PLACEHOLDER_PATTERN = /^\s*\{\{\s*([A-Za-z_][A-Za-z0-9_.]*)\s*\}\}\s*$/;
+export function buildIR(value, options = {}) {
+    const root = asRecord(value) ?? {};
+    const context = {
+        file: options.file,
+        diagnostics: [],
+        typeNames: new Set(Object.keys(asRecord(root.types) ?? {})),
+    };
+    const project = buildProject(root.project);
+    const types = buildTypes(root.types, context);
+    const models = buildModels(root.models);
+    const prompts = buildPrompts(root.prompts, context);
+    const tools = buildTools(root.tools, context);
+    const stores = buildStores(root.stores);
+    const retrievers = buildRetrievers(root.retrievers);
+    const memory = buildMemory(root.memory);
+    const guardrails = buildGuardrails(root.guardrails);
+    const agents = buildAgents(root.agents, context);
+    const deployments = buildDeployments(root.deployments);
+    const embeddings = buildEmbeddings(models);
+    const sensitive = sensitiveNames({ types, prompts });
+    const observability = buildObservability(root.observability, sensitive);
+    const promptModels = new Map(prompts.map((prompt) => [prompt.id, prompt.model]));
+    const pipelines = buildPipelines(root.pipelines, observability, sensitive, promptModels, context);
+    const evals = buildEvals(root.evals, context);
+    const ir = {
+        irVersion: IR_VERSION,
+        specVersion: asString(root.specVersion) ?? SPEC_VERSION,
+        project,
+        types,
+        models,
+        prompts,
+        tools,
+        retrievers,
+        embeddings,
+        stores,
+        memory,
+        agents,
+        pipelines,
+        evals,
+        guardrails,
+        deployments,
+        observability,
+        runtime: { ...DEFAULT_RUNTIME },
+        requiredCapabilities: [],
+    };
+    ir.requiredCapabilities = deriveRequiredCapabilities(ir);
+    return { ir, diagnostics: context.diagnostics };
+}
+function buildProject(raw) {
+    const record = asRecord(raw) ?? {};
+    const name = asString(record.name) ?? '';
+    const namespace = asString(record.namespace) ?? name;
+    const targets = asStringArray(record.targets);
+    return {
+        name,
+        namespace,
+        description: asString(record.description),
+        targets: targets.length === 0 ? [DEFAULT_TARGET] : targets,
+    };
+}
+function buildTypes(raw, context) {
+    const record = asRecord(raw) ?? {};
+    return sortedKeys(record).map((id) => {
+        const entry = asRecord(record[id]) ?? {};
+        const fields = asRecord(entry.fields) ?? {};
+        return {
+            id,
+            kind: 'struct',
+            description: asString(entry.description),
+            fields: sortedKeys(fields).map((fieldName) => buildTypeField(fieldName, asRecord(fields[fieldName]), context)),
+        };
+    });
+}
+function buildTypeField(name, raw, context) {
+    const record = asRecord(raw) ?? {};
+    const field = {
+        name,
+        type: buildTypeRef(record.type, context),
+        required: asBoolean(record.required) ?? false,
+        description: asString(record.description),
+        minimum: asNumber(record.minimum),
+        maximum: asNumber(record.maximum),
+    };
+    const values = Array.isArray(record.enum)
+        ? record.enum.filter((item) => typeof item === 'string' || typeof item === 'number' || typeof item === 'boolean')
+        : undefined;
+    if (values !== undefined)
+        field.enum = values;
+    if (record.sensitive === true || isSensitiveName(name))
+        field.sensitive = true;
+    return field;
+}
+/**
+ * Resolves a `fieldType` string against the spec's declared type names. An
+ * unresolvable name is kept as `resolved: false`; the referential gate reports it
+ * with the document path, so this stays a pure projection.
+ */
+export function buildTypeRef(raw, context) {
+    const text = asString(raw) ?? '';
+    const match = TYPE_NAME_PATTERN.exec(text);
+    if (match === null) {
+        return { kind: 'named', name: text, list: false, resolved: false };
+    }
+    const name = match[1];
+    const list = match[2] === '[]';
+    if (PRIMITIVE_TYPES.includes(name)) {
+        return { kind: 'primitive', name: name, list };
+    }
+    return { kind: 'named', name, list, resolved: context.typeNames.has(name) };
+}
+function buildModels(raw) {
+    const record = asRecord(raw) ?? {};
+    return sortedKeys(record).map((id) => {
+        const entry = asRecord(record[id]) ?? {};
+        const modelId = asString(entry.modelId) ?? id;
+        const explicitCostProfile = asString(entry.costProfile);
+        const resolved = catalogCostProfile(modelId, explicitCostProfile);
+        const catalog = catalogModel(modelId);
+        const model = {
+            id,
+            identity: modelIdentity(id),
+            provider: asProvider(entry.provider),
+            modelId,
+            capabilities: asStringArray(entry.capabilities)
+                // The spec's `capabilities` enum is closed to four spellings that all map onto the
+                // model vocabulary, so no spec-derived caller reaches this filter: `checkSpecText`
+                // rejects anything else first, and `lowerSpec` returns before calling `buildIR`.
+                // It stays because `buildIR` takes `unknown` and promises `ModelCapability[]`, so a
+                // caller that skips validation gets a silent drop rather than a mistyped IR.
+                .map(mapSpecCapability)
+                .filter(isModelCapability),
+            params: buildParams(entry.params),
+            limits: buildLimits(entry.limits, catalog?.limits),
+            fallbacks: asStringArray(entry.fallbacks),
+            traits: [],
+        };
+        if (resolved !== undefined) {
+            model.costProfile = resolved.profile;
+            model.costProfileId = resolved.id;
+        }
+        else if (explicitCostProfile !== undefined) {
+            model.costProfileId = explicitCostProfile;
+        }
+        const cache = buildCache(entry.cache);
+        if (cache !== undefined)
+            model.cache = cache;
+        const baseUrl = asString(entry.baseUrl);
+        const apiKeyEnv = asString(entry.apiKeyEnv);
+        const description = asString(entry.description);
+        if (baseUrl !== undefined)
+            model.baseUrl = baseUrl;
+        if (apiKeyEnv !== undefined)
+            model.apiKeyEnv = apiKeyEnv;
+        if (description !== undefined)
+            model.description = description;
+        return model;
+    });
+}
+function buildCache(raw) {
+    const record = asRecord(raw);
+    if (record === undefined)
+        return undefined;
+    const prompt = asBoolean(record.prompt);
+    const semantic = buildSemanticCache(record.semantic);
+    return prompt === undefined && semantic === undefined ? undefined : { prompt, semantic };
+}
+function buildSemanticCache(raw) {
+    const record = asRecord(raw);
+    if (record === undefined)
+        return undefined;
+    const threshold = asNumber(record.threshold);
+    const ttlSeconds = asNumber(record.ttlSeconds);
+    if (threshold === undefined || ttlSeconds === undefined)
+        return undefined;
+    return { threshold, ttlSeconds };
+}
+function mapSpecCapability(value) {
+    const mapped = SPEC_MODEL_CAPABILITY_MAP;
+    return mapped[value] ?? value;
+}
+function asProvider(raw) {
+    const value = asString(raw);
+    return value !== undefined && isProvider(value) ? value : 'fake';
+}
+function buildParams(raw) {
+    const record = asRecord(raw) ?? {};
+    const params = {};
+    const temperature = asNumber(record.temperature);
+    const topP = asNumber(record.topP);
+    const maxTokens = asNumber(record.maxTokens);
+    const seed = asNumber(record.seed);
+    if (temperature !== undefined)
+        params.temperature = temperature;
+    if (topP !== undefined)
+        params.topP = topP;
+    if (maxTokens !== undefined)
+        params.maxTokens = maxTokens;
+    if (seed !== undefined)
+        params.seed = seed;
+    const stop = asStringArray(record.stop);
+    if (stop.length > 0)
+        params.stop = stop;
+    return params;
+}
+function buildLimits(raw, catalogLimits) {
+    const record = asRecord(raw) ?? {};
+    const limits = {
+        contextTokens: asNumber(record.maxInputTokens) ?? catalogLimits?.contextTokens ?? DEFAULT_MAX_CONTEXT_TOKENS,
+    };
+    const maxOutputTokens = asNumber(record.maxOutputTokens) ?? catalogLimits?.maxOutputTokens;
+    const rpm = asNumber(record.rpm) ?? catalogLimits?.rpm;
+    const tpm = asNumber(record.tpm) ?? catalogLimits?.tpm;
+    if (maxOutputTokens !== undefined)
+        limits.maxOutputTokens = maxOutputTokens;
+    if (rpm !== undefined)
+        limits.rpm = rpm;
+    if (tpm !== undefined)
+        limits.tpm = tpm;
+    return limits;
+}
+function buildPrompts(raw, context) {
+    const record = asRecord(raw) ?? {};
+    return sortedKeys(record).map((id) => {
+        const entry = asRecord(record[id]) ?? {};
+        const outputRecord = asRecord(entry.output) ?? {};
+        const kind = asString(outputRecord.kind) ?? 'text';
+        const version = asNumber(entry.version) ?? 1;
+        return {
+            id,
+            version,
+            identity: promptIdentity(id, version),
+            model: asString(entry.model) ?? '',
+            template: asString(entry.template) ?? '',
+            variables: buildPromptVariables(entry.variables, context),
+            output: buildPromptOutput(kind, outputRecord.schema, context),
+            params: {},
+            examples: [],
+            guardrails: [],
+            evals: [],
+            traits: [],
+        };
+    });
+}
+/** `schema` is declared only for `structured`, so no other kind carries a TypeRef. */
+function buildPromptOutput(kind, schema, context) {
+    if (kind === 'structured')
+        return { kind: 'structured', schema: buildTypeRef(schema, context) };
+    if (kind === 'json')
+        return { kind: 'json' };
+    return { kind: 'text' };
+}
+function buildPromptVariables(raw, context) {
+    const record = asRecord(raw) ?? {};
+    return sortedKeys(record).map((name) => {
+        const entry = asRecord(record[name]) ?? {};
+        const variable = {
+            name,
+            type: buildTypeRef(entry.type ?? 'string', context),
+            required: asBoolean(entry.required) ?? false,
+        };
+        const description = asString(entry.description);
+        if (description !== undefined)
+            variable.description = description;
+        if (entry.sensitive === true || isSensitiveName(name))
+            variable.sensitive = true;
+        if ('default' in entry && isJsonValue(entry.default))
+            variable.default = entry.default;
+        return variable;
+    });
+}
+/** Guards against `undefined`/functions leaking into the IR via a hand-written document. */
+function isJsonValue(value) {
+    if (value === null || typeof value === 'boolean' || typeof value === 'string')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJsonValue);
+    if (typeof value !== 'object')
+        return false;
+    return Object.values(value).every(isJsonValue);
+}
+function buildTools(raw, context) {
+    const record = asRecord(raw) ?? {};
+    return sortedKeys(record).map((id) => {
+        const entry = asRecord(record[id]) ?? {};
+        const handlerRecord = asRecord(entry.handler) ?? {};
+        const authSource = asString(entry.auth);
+        const sideEffects = asSideEffects(entry.sideEffects);
+        const tool = {
+            id,
+            identity: toolIdentity(id),
+            name: id,
+            description: asString(entry.description) ?? '',
+            input: buildTypeRef(entry.input, context),
+            output: buildTypeRef(entry.output, context),
+            sideEffects,
+            // A destructive tool requires confirmation unless the spec says otherwise.
+            requiresConfirmation: asBoolean(entry.requiresConfirmation) ?? sideEffects === 'destructive',
+            timeoutMs: asNumber(entry.timeoutMs) ?? DEFAULT_TOOL_TIMEOUT_MS,
+            retries: asNumber(entry.retries) ?? DEFAULT_TOOL_RETRIES,
+            idempotency: asIdempotency(entry.idempotency),
+            handler: buildToolHandler(handlerRecord),
+            traits: [],
+        };
+        if (authSource !== undefined) {
+            const parsed = parsePolicyExpr(authSource, {
+                path: ['tools', id, 'auth'],
+                file: context.file,
+            });
+            context.diagnostics.push(...parsed.diagnostics);
+            if (parsed.ast !== undefined)
+                tool.auth = parsed.ast;
+        }
+        return tool;
+    });
+}
+function buildToolHandler(record) {
+    const kind = asString(record.kind);
+    if (kind === 'generated' || kind === 'mcp') {
+        const handler = { kind };
+        const symbol = asString(record.symbol);
+        if (symbol !== undefined)
+            handler.symbol = symbol;
+        const mcp = asRecord(record.mcp);
+        if (mcp !== undefined) {
+            handler.mcp = { server: asString(mcp.server) ?? '', tool: asString(mcp.tool) ?? '' };
+        }
+        return handler;
+    }
+    const handler = { kind: 'business' };
+    const symbol = asString(record.symbol);
+    if (symbol !== undefined)
+        handler.symbol = symbol;
+    return handler;
+}
+function asSideEffects(raw) {
+    const value = asString(raw);
+    return value === 'read' || value === 'write' || value === 'destructive' || value === 'none'
+        ? value
+        : 'none';
+}
+function buildStores(raw) {
+    const record = asRecord(raw) ?? {};
+    return sortedKeys(record).map((id) => {
+        const entry = asRecord(record[id]) ?? {};
+        const store = {
+            id,
+            kind: asStoreKind(entry.kind),
+            traits: [],
+        };
+        const uri = asString(entry.uri);
+        const dimensions = asNumber(entry.dimensions);
+        if (uri !== undefined)
+            store.uri = uri;
+        if (dimensions !== undefined)
+            store.dimensions = dimensions;
+        return store;
+    });
+}
+function asStoreKind(raw) {
+    const value = asString(raw);
+    return value !== undefined && isVectorStoreKind(value) ? value : 'memory';
+}
+function buildRetrievers(raw) {
+    const record = asRecord(raw) ?? {};
+    return sortedKeys(record).map((id) => {
+        const entry = asRecord(record[id]) ?? {};
+        const source = asRecord(entry.source) ?? {};
+        const chunking = asRecord(entry.chunking) ?? {};
+        const index = asRecord(entry.index) ?? {};
+        const refresh = asRecord(entry.refresh) ?? {};
+        const retriever = {
+            id,
+            source: buildRetrieverSource(source),
+            chunking: {
+                strategy: asChunkStrategy(chunking.strategy),
+                size: asNumber(chunking.size) ?? DEFAULT_CHUNK_SIZE,
+                overlap: asNumber(chunking.overlap) ?? DEFAULT_CHUNK_OVERLAP,
+                keepMetadata: asStringArray(chunking.keepMetadata),
+            },
+            embedModel: asString(entry.embedModel) ?? '',
+            store: asString(entry.store) ?? '',
+            index: {
+                metric: asIndexMetric(index.metric),
+                hybrid: asBoolean(index.hybrid) ?? false,
+            },
+            topK: asNumber(entry.topK) ?? DEFAULT_RETRIEVER_TOP_K,
+            refresh: buildRefresh(refresh),
+            traits: buildRetrievalTraits(entry.traits),
+        };
+        const rerank = asRecord(entry.rerank);
+        if (rerank !== undefined) {
+            retriever.rerank = {
+                model: asString(rerank.model) ?? '',
+                topN: asNumber(rerank.topN) ?? retriever.topK,
+            };
+        }
+        const filters = asStringArray(entry.filters);
+        if (filters.length > 0)
+            retriever.filters = filters;
+        const params = asRecord(index.params);
+        if (params !== undefined)
+            retriever.index.params = params;
+        return retriever;
+    });
+}
+function buildRetrieverSource(raw) {
+    const value = asString(raw.kind);
+    const kind = value === 's3' || value === 'http' || value === 'db' || value === 'mcp' ? value : 'file';
+    const source = { kind, uri: asString(raw.uri) ?? '' };
+    const glob = asString(raw.glob);
+    if (glob !== undefined)
+        source.glob = glob;
+    return source;
+}
+function buildRefresh(raw) {
+    const mode = asString(raw.mode);
+    const refresh = {
+        mode: mode === 'incremental' ? 'incremental' : DEFAULT_REFRESH_MODE,
+    };
+    const schedule = asString(raw.schedule);
+    if (schedule !== undefined)
+        refresh.schedule = schedule;
+    return refresh;
+}
+function asChunkStrategy(raw) {
+    const value = asString(raw);
+    return value === 'fixed' || value === 'semantic' || value === 'code'
+        ? value
+        : DEFAULT_CHUNK_STRATEGY;
+}
+function asIndexMetric(raw) {
+    const value = asString(raw);
+    return value !== undefined && isIndexMetric(value) ? value : DEFAULT_INDEX_METRIC;
+}
+function buildRetrievalTraits(raw) {
+    return asStringArray(raw)
+        .filter((name) => RETRIEVAL_TRAITS.includes(name))
+        .map((name) => ({ name }));
+}
+/**
+ * One entry per model declaring `embeddings`, keyed by the model alias so
+ * `retriever.embedModel` and `store.dimensions` can be checked against it.
+ */
+function buildEmbeddings(models) {
+    return models
+        .filter((model) => model.capabilities.includes('embeddings'))
+        .map((model) => {
+        const embedding = {
+            id: model.id,
+            provider: model.provider,
+            modelId: model.modelId,
+            traits: [],
+        };
+        const dimensions = catalogModel(model.modelId)?.dimensions;
+        if (dimensions !== undefined)
+            embedding.dimensions = dimensions;
+        if (model.costProfile !== undefined)
+            embedding.costProfile = model.costProfile;
+        return embedding;
+    });
+}
+function asIdempotency(raw) {
+    const value = asString(raw);
+    return value === 'key' || value === 'natural' || value === 'none' ? value : DEFAULT_IDEMPOTENCY;
+}
+function buildPipelines(raw, observability, sensitive, promptModels, context) {
+    const record = asRecord(raw) ?? {};
+    return sortedKeys(record).map((id) => {
+        const entry = asRecord(record[id]) ?? {};
+        const trigger = asRecord(asRecord(entry.trigger)?.http) ?? {};
+        const pipeline = {
+            id,
+            identity: pipelineIdentity(id),
+            trigger: {
+                kind: 'http',
+                method: asString(trigger.method) ?? 'post',
+                path: asString(trigger.path) ?? '/',
+            },
+            steps: buildStepList(entry.steps, promptModels, context, ['pipelines', id, 'steps']),
+            errorPolicy: buildErrorPolicy(entry.errorPolicy),
+            observability: buildObservability(entry.observability, sensitive, observability),
+        };
+        const description = asString(entry.description);
+        if (description !== undefined)
+            pipeline.description = description;
+        return pipeline;
+    });
+}
+function buildErrorPolicy(raw) {
+    const record = asRecord(raw) ?? {};
+    return {
+        retries: asNumber(record.retries) ?? 0,
+        fallback: asString(record.fallback),
+        deadLetter: asString(record.deadLetter),
+    };
+}
+function buildStepList(raw, promptModels, context, path) {
+    return asArray(raw).map((step, index) => buildStep(step, promptModels, context, [...path, index]));
+}
+function buildStep(raw, promptModels, context, path) {
+    const record = asRecord(raw) ?? {};
+    const generate = asRecord(record.generate);
+    if (generate !== undefined) {
+        const prompt = asString(generate.prompt) ?? '';
+        const step = {
+            kind: 'generate',
+            prompt,
+            model: promptModels.get(prompt) ?? '',
+            input: buildStepInput(generate.input),
+            as: asString(generate.as) ?? '',
+        };
+        const contextName = asString(generate.context);
+        if (contextName !== undefined)
+            step.context = contextName;
+        return step;
+    }
+    const retrieve = asRecord(record.retrieve);
+    if (retrieve !== undefined) {
+        return buildRetrieveStep(retrieve);
+    }
+    const tool = asRecord(record.tool);
+    if (tool !== undefined) {
+        return {
+            kind: 'tool',
+            tool: asString(tool.tool) ?? '',
+            input: buildStepInput(tool.input),
+            as: asString(tool.as) ?? '',
+        };
+    }
+    const branch = asRecord(record.branch);
+    if (branch !== undefined) {
+        return buildBranchStep(branch, promptModels, context, [...path, 'branch']);
+    }
+    const parallel = asRecord(record.parallel);
+    if (parallel !== undefined) {
+        const arms = asArray(parallel.branches);
+        return {
+            kind: 'parallel',
+            branches: arms.map((arm, index) => buildStepList(arm, promptModels, context, [...path, 'parallel', 'branches', index])),
+        };
+    }
+    const map = asRecord(record.map);
+    if (map !== undefined) {
+        const body = asRecord(map.step) ?? {};
+        const mapStep = {
+            kind: 'map',
+            over: asString(map.over) ?? '',
+            as: asString(map.as) ?? '',
+            step: buildStep(body, promptModels, context, [...path, 'map', 'step']),
+        };
+        return mapStep;
+    }
+    const reduce = asRecord(record.reduce);
+    if (reduce !== undefined) {
+        const prompt = asString(reduce.prompt) ?? '';
+        return {
+            kind: 'reduce',
+            over: asString(reduce.over) ?? '',
+            prompt,
+            model: promptModels.get(prompt) ?? '',
+            as: asString(reduce.as) ?? '',
+        };
+    }
+    const rerank = asRecord(record.rerank);
+    if (rerank !== undefined) {
+        return {
+            kind: 'rerank',
+            over: asString(rerank.over) ?? '',
+            query: asString(rerank.query) ?? '',
+            model: asString(rerank.model) ?? '',
+            topN: asNumber(rerank.topN) ?? 0,
+            as: asString(rerank.as) ?? '',
+        };
+    }
+    const guard = asRecord(record.guard);
+    if (guard !== undefined) {
+        return {
+            kind: 'guard',
+            guardrail: asString(guard.guardrail) ?? '',
+            stage: (asString(guard.stage) ?? 'input'),
+            text: asString(guard.text) ?? '',
+        };
+    }
+    const agent = asRecord(record.agent);
+    if (agent !== undefined) {
+        return {
+            kind: 'agent',
+            agent: asString(agent.agent) ?? '',
+            text: asString(agent.text) ?? '',
+            as: asString(agent.as) ?? '',
+        };
+    }
+    const emit = asRecord(record.emit);
+    return { kind: 'emit', event: asString(emit?.event) ?? '' };
+}
+/**
+ * The spec layer already rejected a `when` the grammar cannot parse, so a parse failure
+ * here means the two layers disagree. It still has to yield a `BranchStep`, because
+ * `StepShape` has no "broken" variant: an unparsable predicate becomes the constant
+ * `false`, so the failure closes the arm rather than opening it.
+ */
+function buildBranchStep(branch, promptModels, context, path) {
+    const source = asString(branch.when) ?? '';
+    const parsed = parsePolicyExpr(source, { path: [...path, 'when'], file: context.file });
+    context.diagnostics.push(...parsed.diagnostics);
+    return {
+        kind: 'branch',
+        when: parsed.ast ?? { kind: 'boolean', value: false },
+        // biome-ignore lint/suspicious/noThenProperty: the branch shape names its taken arm `then`.
+        then: buildStepList(branch.then, promptModels, context, [...path, 'then']),
+        else: buildStepList(branch.else, promptModels, context, [...path, 'else']),
+    };
+}
+/** `query` stays as declared: the runtime interpolates it per request. */
+export function buildRetrieveStep(retrieve) {
+    return {
+        kind: 'retrieve',
+        retriever: asString(retrieve.retriever) ?? '',
+        query: asString(retrieve.query) ?? '',
+        as: asString(retrieve.as) ?? '',
+    };
+}
+function buildStepInput(raw) {
+    const record = asRecord(raw) ?? {};
+    const input = {};
+    for (const key of sortedKeys(record)) {
+        input[key] = buildStepInputValue(record[key]);
+    }
+    return input;
+}
+/**
+ * `{{ name }}` alone is a reference; a string with several placeholders is kept
+ * as a template. The gate resolves the roots, so nothing is guessed here.
+ */
+function buildStepInputValue(raw) {
+    if (raw === null)
+        return { kind: 'literal', value: null };
+    if (typeof raw === 'number' || typeof raw === 'boolean')
+        return { kind: 'literal', value: raw };
+    if (typeof raw !== 'string')
+        return { kind: 'literal', value: String(raw) };
+    const sole = SOLE_PLACEHOLDER_PATTERN.exec(raw);
+    if (sole !== null)
+        return { kind: 'reference', path: sole[1].split('.') };
+    if (raw.includes('{{'))
+        return { kind: 'template', template: raw };
+    return { kind: 'literal', value: raw };
+}
+const MEMORY_KINDS = ['buffer', 'window', 'summary', 'semantic', 'episodic', 'vector'];
+const MEMORY_SCOPES = ['thread', 'user', 'global'];
+const GUARDRAIL_STAGES = ['input', 'output', 'retrieval', 'tool-call'];
+const GUARDRAIL_ACTIONS = ['block', 'redact', 'flag', 'escalate'];
+const DEPLOY_TARGETS = ['serverless', 'container', 'batch', 'edge'];
+function buildMemory(raw) {
+    const record = asRecord(raw) ?? {};
+    return sortedKeys(record).map((id) => {
+        const entry = asRecord(record[id]) ?? {};
+        const memory = {
+            id,
+            kind: asMemoryKind(entry.kind),
+            scope: asMemoryScope(entry.scope),
+            tokenBudget: asNumber(entry.tokenBudget) ?? DEFAULT_MEMORY_TOKEN_BUDGET,
+            redact: asStringArray(entry.redact),
+            traits: [],
+        };
+        const summarizeModel = asString(entry.summarizeModel);
+        const store = asString(entry.store);
+        const backend = asString(entry.backend);
+        const ttl = asString(entry.ttl);
+        if (summarizeModel !== undefined)
+            memory.summarizeModel = summarizeModel;
+        if (store !== undefined)
+            memory.store = store;
+        if (backend !== undefined)
+            memory.backend = backend;
+        if (ttl !== undefined)
+            memory.ttl = ttl;
+        return memory;
+    });
+}
+/** Unknown kinds collapse to the cheapest tier rather than passing through. */
+function asMemoryKind(raw) {
+    const value = asString(raw);
+    return MEMORY_KINDS.includes(value ?? '')
+        ? value
+        : 'buffer';
+}
+function asMemoryScope(raw) {
+    const value = asString(raw);
+    return MEMORY_SCOPES.includes(value ?? '')
+        ? value
+        : 'thread';
+}
+function buildGuardrails(raw) {
+    const record = asRecord(raw) ?? {};
+    return sortedKeys(record).map((id) => {
+        const entry = asRecord(record[id]) ?? {};
+        const onFailRecord = asRecord(entry.onFail) ?? {};
+        const onFail = {
+            message: asString(onFailRecord.message) ?? '',
+            log: asBoolean(onFailRecord.log) ?? false,
+        };
+        const fallbackPrompt = asString(onFailRecord.fallbackPrompt);
+        if (fallbackPrompt !== undefined)
+            onFail.fallbackPrompt = fallbackPrompt;
+        const stages = asStringArray(entry.stages).filter((stage) => GUARDRAIL_STAGES.includes(stage));
+        const action = asString(entry.action);
+        return {
+            id,
+            stages,
+            policies: asStringArray(entry.policies).filter(isGuardrailPolicyKind),
+            action: GUARDRAIL_ACTIONS.includes(action ?? '')
+                ? action
+                : 'block',
+            redact: asStringArray(entry.redact),
+            tools: asStringArray(entry.tools),
+            onFail,
+            traits: [],
+        };
+    });
+}
+function buildAgents(raw, context) {
+    const record = asRecord(raw) ?? {};
+    return sortedKeys(record).map((id) => {
+        const entry = asRecord(record[id]) ?? {};
+        const agent = {
+            id,
+            name: asString(entry.name) ?? id,
+            instructions: asString(entry.instructions) ?? '',
+            model: asString(entry.model) ?? '',
+            tools: asStringArray(entry.tools),
+            retrievers: asStringArray(entry.retrievers),
+            memory: asStringArray(entry.memory),
+            guardrails: asStringArray(entry.guardrails),
+            maxSteps: asNumber(entry.maxSteps) ?? 1,
+            handoffs: asStringArray(entry.handoffs),
+            delegates: asStringArray(entry.delegates),
+            engine: asAgentEngine(entry.engine),
+            traits: [],
+        };
+        const structuredOutput = asString(entry.structuredOutput);
+        if (structuredOutput !== undefined) {
+            agent.structuredOutput = buildTypeRef(structuredOutput, context);
+        }
+        const maxTokensBudget = asNumber(entry.maxTokensBudget);
+        if (maxTokensBudget !== undefined)
+            agent.maxTokensBudget = maxTokensBudget;
+        const maxCostBudget = asNumber(entry.maxCostBudget);
+        if (maxCostBudget !== undefined)
+            agent.maxCostBudget = maxCostBudget;
+        const onBudgetExhausted = asAgentOnBudgetExhausted(entry.onBudgetExhausted);
+        if (onBudgetExhausted !== undefined)
+            agent.onBudgetExhausted = onBudgetExhausted;
+        const engineVersion = asString(entry.engineVersion);
+        if (engineVersion !== undefined)
+            agent.engineVersion = engineVersion;
+        const humanInTheLoop = asRecord(entry.humanInTheLoop);
+        if (humanInTheLoop !== undefined) {
+            const parsed = parsePolicyExpr(asString(humanInTheLoop.when) ?? '', {
+                path: ['agents', id, 'humanInTheLoop', 'when'],
+                file: context.file,
+            });
+            context.diagnostics.push(...parsed.diagnostics);
+            if (parsed.ast !== undefined) {
+                agent.humanInTheLoop = {
+                    when: parsed.ast,
+                    channel: asString(humanInTheLoop.channel) ?? '',
+                };
+            }
+        }
+        return agent;
+    });
+}
+function asAgentEngine(raw) {
+    const value = asString(raw);
+    return AGENT_ENGINES.includes(value ?? '')
+        ? value
+        : 'native';
+}
+function asAgentOnBudgetExhausted(raw) {
+    const value = asString(raw);
+    return AGENT_ON_BUDGET_EXHAUSTED.includes(value ?? '')
+        ? value
+        : undefined;
+}
+function buildDeployments(raw) {
+    const record = asRecord(raw) ?? {};
+    return sortedKeys(record).map((id) => {
+        const entry = asRecord(record[id]) ?? {};
+        const target = asString(entry.target);
+        const deployment = {
+            id,
+            target: DEPLOY_TARGETS.includes(target ?? '')
+                ? target
+                : 'serverless',
+            streaming: asBoolean(entry.streaming) ?? false,
+            secrets: asStringArray(entry.secrets),
+            env: buildDeploymentEnv(entry.env),
+            traits: [],
+        };
+        const concurrency = asNumber(entry.concurrency);
+        if (concurrency !== undefined)
+            deployment.concurrency = concurrency;
+        const autoscale = asRecord(entry.autoscale);
+        if (autoscale !== undefined) {
+            deployment.autoscale = {
+                min: asNumber(autoscale.min) ?? 0,
+                max: asNumber(autoscale.max) ?? 1,
+                metric: asString(autoscale.metric) ?? '',
+            };
+        }
+        return deployment;
+    });
+}
+function buildDeploymentEnv(raw) {
+    const env = [];
+    for (const item of asArray(raw)) {
+        const record = asRecord(item);
+        const name = asString(record?.name);
+        if (record === undefined || name === undefined)
+            continue;
+        const entry = { name };
+        const value = asString(record.value);
+        const secret = asBoolean(record.secret);
+        if (value !== undefined)
+            entry.value = value;
+        if (secret !== undefined)
+            entry.secret = secret;
+        env.push(entry);
+    }
+    return env;
+}
+function buildEvals(raw, context) {
+    const record = asRecord(raw) ?? {};
+    return sortedKeys(record).map((id) => {
+        const entry = asRecord(record[id]) ?? {};
+        const metrics = asArray(entry.metrics)
+            .map((metric, index) => buildMetric(metric, context, ['evals', id, 'metrics', index]))
+            .filter((metric) => metric !== undefined);
+        const gate = asRecord(entry.gate) ?? {};
+        const dataset = asRecord(entry.dataset) ?? {};
+        const budgets = metrics
+            .filter((metric) => metric.kind === 'cost')
+            .map((metric) => metric.max);
+        const latencies = metrics
+            .filter((metric) => metric.kind === 'latency')
+            .map((metric) => metric.maxMs);
+        const evalShape = {
+            id,
+            description: asString(entry.description),
+            target: buildEvalTarget(entry.target),
+            dataset: { source: 'file', uri: asString(dataset.uri) ?? '' },
+            metrics,
+            gate: {
+                ci: asBoolean(gate.ci) ?? false,
+                maxRegression: asNumber(gate.maxRegression) ?? DEFAULT_EVAL_MAX_REGRESSION,
+                samples: asNumber(gate.samples) ?? DEFAULT_EVAL_SAMPLES,
+            },
+            traits: [],
+        };
+        // Written only when declared, so every eval that predates `minMean` serializes
+        // byte-identically.
+        const minMean = asNumber(gate.minMean);
+        if (minMean !== undefined)
+            evalShape.gate.minMean = minMean;
+        if (budgets.length > 0)
+            evalShape.costBudget = Math.min(...budgets);
+        if (latencies.length > 0)
+            evalShape.latencyBudgetP95Ms = Math.min(...latencies);
+        return evalShape;
+    });
+}
+/** Parses the qualified `kind:id` target form; `valid` is false when it is not one. */
+export function buildEvalTarget(raw) {
+    const qualified = asString(raw) ?? '';
+    const match = EVAL_TARGET_PATTERN.exec(qualified);
+    if (match === null) {
+        return { kind: 'pipeline', id: qualified, qualified, valid: false };
+    }
+    const kind = match[1];
+    const id = match[2];
+    if (kind !== 'pipeline' && kind !== 'prompt') {
+        return { kind: 'pipeline', id, qualified, valid: false };
+    }
+    return { kind, id, qualified, valid: true };
+}
+function buildMetric(raw, context, path) {
+    const record = asRecord(raw) ?? {};
+    const kind = asString(record.kind);
+    const field = asString(record.field);
+    switch (kind) {
+        case 'exact':
+            return field === undefined ? undefined : { kind: 'exact', field };
+        case 'contains': {
+            if (field === undefined)
+                return undefined;
+            const value = asString(record.value);
+            return value === undefined ? { kind: 'contains', field } : { kind: 'contains', field, value };
+        }
+        case 'json-schema':
+            return { kind: 'json-schema', schema: buildTypeRef(record.schema, context) };
+        case 'tool-trace':
+            return {
+                kind: 'tool-trace',
+                expect: asStringArray(record.expect),
+                ordered: asBoolean(record.ordered) ?? false,
+            };
+        case 'cost': {
+            const max = asNumber(record.max);
+            return max === undefined ? undefined : { kind: 'cost', max };
+        }
+        case 'latency': {
+            const maxMs = asNumber(record.maxMs);
+            return maxMs === undefined ? undefined : { kind: 'latency', maxMs };
+        }
+        case 'retrieval':
+            return {
+                kind: 'retrieval',
+                expectDocs: asStringArray(record.expectDocs),
+                // The cut-off is what the metric scores against; 1 is the narrowest reading
+                // of a k the spec must declare anyway.
+                k: asNumber(record.k) ?? 1,
+            };
+        case 'llm-judge': {
+            const rubric = asString(record.rubric);
+            if (rubric === undefined)
+                return undefined;
+            const metric = { kind: 'llm-judge', rubric };
+            const model = asString(record.model);
+            const threshold = asNumber(record.threshold);
+            if (field !== undefined)
+                metric.field = field;
+            if (model !== undefined)
+                metric.model = model;
+            if (threshold !== undefined)
+                metric.threshold = threshold;
+            return metric;
+        }
+        case 'assert': {
+            const message = asString(record.message);
+            if (message === undefined)
+                return undefined;
+            const parsed = parsePredicateExpr(asString(record.expr) ?? '', {
+                path: [...path, 'expr'],
+                file: context.file,
+            });
+            context.diagnostics.push(...parsed.diagnostics);
+            // An unparsable predicate is already an error diagnostic; dropping the metric
+            // keeps the IR closed, and the caller treats the diagnostics as the failure.
+            if (parsed.ast.kind === 'invalid')
+                return undefined;
+            return { kind: 'assert', expr: parsed.ast, message };
+        }
+        default:
+            return undefined;
+    }
+}
+/** Rejects a binding name that is not a lower-case identifier. */
+export function isBindingName(value) {
+    return BINDING_PATTERN.test(value);
+}
+/**
+ * Sensitivity is declared, or inferred from a name deny-list. Inference is
+ * fail-closed on purpose: over-redacting a trace is recoverable, leaking one is
+ * not, and spec v0.1 has no `sensitive` marker of its own.
+ */
+const SENSITIVE_NAME_PATTERN = /(pass(word|phrase)|secret|token|api_?key|private_?key|credential|ssn|social_security|credit_?card|card_?number|cvv|iban|email|phone|address|birth|dob)/i;
+export function isSensitiveName(name) {
+    return SENSITIVE_NAME_PATTERN.test(name);
+}
+/** Sorted names of every field and variable the IR marks as sensitive. */
+export function sensitiveNames(ir) {
+    const names = new Set();
+    for (const type of ir.types) {
+        for (const field of type.fields) {
+            if (field.sensitive === true)
+                names.add(field.name);
+        }
+    }
+    for (const prompt of ir.prompts) {
+        for (const variable of prompt.variables) {
+            if (variable.sensitive === true)
+                names.add(variable.name);
+        }
+    }
+    return [...names].sort();
+}
+const PLACEHOLDER_PATTERN = /\{\{\s*([A-Za-z_][A-Za-z0-9_.]*)\s*\}\}/g;
+/** Every `{{ path }}` placeholder a prompt template references, deduplicated. */
+export function templatePlaceholders(template) {
+    const names = new Set();
+    for (const match of template.matchAll(PLACEHOLDER_PATTERN)) {
+        names.add(match[1].split('.')[0]);
+    }
+    return [...names].sort();
+}
+/**
+ * A declared `observability` is honoured as written; a synthesized one defaults
+ * `redact` to the sensitive set. An explicit `redact` therefore wins, which is
+ * what lets the security gate catch a trace config that narrows it too far.
+ */
+function buildObservability(raw, sensitive, inherited) {
+    const fallbackRedact = inherited === undefined ? [...sensitive] : [...inherited.redact];
+    const record = asRecord(raw);
+    if (record === undefined) {
+        return { trace: inherited?.trace ?? DEFAULT_OBSERVABILITY.trace, redact: fallbackRedact };
+    }
+    return {
+        trace: asBoolean(record.trace) ?? inherited?.trace ?? DEFAULT_OBSERVABILITY.trace,
+        redact: Array.isArray(record.redact) ? asStringArray(record.redact) : fallbackRedact,
+    };
+}
+export function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+export function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+export function asString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+export function asNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+export function asBoolean(value) {
+    return typeof value === 'boolean' ? value : undefined;
+}
+export function asStringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === 'string')
+        : [];
+}
+/** Object keys in a deterministic order, so YAML key order never reaches the IR. */
+export function sortedKeys(record) {
+    return Object.keys(record).sort();
+}
+//# sourceMappingURL=build.js.map