@aid-framework/ir 0.0.0 → 0.1.39

package/dist/diagnostics.js

@@ -0,0 +1,103 @@
+/**
+ * The IR layer's diagnostic codes and factories. Codes are namespaced `ir/<slug>`
+ * and are part of the public contract, exactly like the spec layer's `spec/*`.
+ */
+import { errorDiagnostic, warningDiagnostic, } from '@aid-framework/spec';
+/** Every diagnostic code this package emits. */
+export const IR_DIAGNOSTIC_CODES = {
+    typeUnresolved: 'ir/type-unresolved',
+    typeCycle: 'ir/type-cycle',
+    refUnresolved: 'ir/ref-unresolved',
+    refKindMismatch: 'ir/ref-kind-mismatch',
+    evalTargetInvalid: 'ir/eval-target-invalid',
+    fallbackCycle: 'ir/fallback-cycle',
+    metricToolUnresolved: 'ir/metric-tool-unresolved',
+    promptVariableUndeclared: 'ir/prompt-variable-undeclared',
+    promptVariableUnused: 'ir/prompt-variable-unused',
+    promptInputMissing: 'ir/prompt-input-missing',
+    bindingDuplicate: 'ir/binding-duplicate',
+    bindingForwardReference: 'ir/binding-forward-reference',
+    normalizationIncomplete: 'ir/normalization-incomplete',
+    dimensionMismatch: 'ir/dimension-mismatch',
+    indexMetricUnknown: 'ir/index-metric-unknown',
+    paramExceedsLimit: 'ir/param-exceeds-limit',
+    providerUnsupported: 'ir/provider-unsupported',
+    targetUnknown: 'ir/target-unknown',
+    capabilityUnknown: 'ir/capability-unknown',
+    capabilityMissing: 'ir/capability-missing',
+    modelCapabilityMissing: 'ir/model-capability-missing',
+    costProfileUnknown: 'ir/cost-profile-unknown',
+    costBudgetExceeded: 'ir/cost-budget-exceeded',
+    securityMissingAuth: 'ir/security-missing-auth',
+    securityMissingConfirmation: 'ir/security-missing-confirmation',
+    securityRedactionIncomplete: 'ir/security-redaction-incomplete',
+    securityUnauthenticatedPath: 'ir/security-unauthenticated-path',
+    securityStoreSecret: 'ir/security-store-secret',
+    securityInputGuardrail: 'ir/security-input-guardrail',
+    agentsRefUnresolved: 'ir/agents-ref-unresolved',
+    agentsHandoffCycle: 'ir/agents-handoff-cycle',
+    agentsBudget: 'ir/agents-budget',
+    agentsBudgetDegrade: 'ir/agents-budget-degrade',
+    guardrailCoverage: 'ir/guardrail-coverage',
+    guardrailPolicy: 'ir/guardrail-policy',
+    hitlSideEffect: 'ir/hitl-side-effect',
+    memoryRef: 'ir/memory-ref',
+    deployStreaming: 'ir/deploy-streaming',
+    orchestrationDeepagents: 'ir/orchestration-deepagents',
+    evalUncovered: 'ir/eval-uncovered',
+    gateFailed: 'ir/gate-failed',
+    policyEmpty: 'ir/policy-empty',
+    policySyntax: 'ir/policy-syntax',
+    policyUnknownBuiltin: 'ir/policy-unknown-builtin',
+    policyUnknownIdentifier: 'ir/policy-unknown-identifier',
+    policyUnterminatedString: 'ir/policy-unterminated-string',
+    policyUnclosedParen: 'ir/policy-unclosed-paren',
+    policyTrailingToken: 'ir/policy-trailing-token',
+    policyArity: 'ir/policy-arity',
+    policyArgumentType: 'ir/policy-argument-type',
+    policyExpected: 'ir/policy-expected',
+    predicateEmpty: 'ir/predicate-empty',
+    predicateSyntax: 'ir/predicate-syntax',
+    predicateUnknownBuiltin: 'ir/predicate-unknown-builtin',
+    predicateUnknownPath: 'ir/predicate-unknown-path',
+    predicateUnterminatedString: 'ir/predicate-unterminated-string',
+    predicateUnclosedParen: 'ir/predicate-unclosed-paren',
+    predicateTrailingToken: 'ir/predicate-trailing-token',
+    predicateArity: 'ir/predicate-arity',
+    predicateExpected: 'ir/predicate-expected',
+    predicateNotBoolean: 'ir/predicate-not-boolean',
+};
+/** `C` infers from the `code` field, so call sites need no explicit type argument. */
+export function irError(init) {
+    return errorDiagnostic(init);
+}
+export function irWarning(init) {
+    return warningDiagnostic(init);
+}
+/**
+ * The shared init carries only what a factory needs, so the source position a
+ * policy error points at is attached to the finished diagnostic instead.
+ */
+export function withPosition(diagnostic, position) {
+    const located = { ...diagnostic };
+    if (position.file !== undefined)
+        located.file = position.file;
+    if (position.line !== undefined)
+        located.line = position.line;
+    if (position.column !== undefined)
+        located.column = position.column;
+    return located;
+}
+/** 1-based line/column of a 0-based offset, for position-bearing policy errors. */
+export function offsetPosition(source, offset) {
+    let line = 1;
+    let lineStart = 0;
+    for (let index = 0; index < offset && index < source.length; index += 1) {
+        if (source[index] === '\n') {
+            line += 1;
+            lineStart = index + 1;
+        }
+    }
+    return { line, column: offset - lineStart + 1 };
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"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"}

package/dist/gates/agents.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Agents — four separate gates, because they answer four different questions.
+ *
+ * `agents/refs-resolve`: every name an agent uses exists. An agent whose tool or
+ * guardrail does not resolve is not a partially-working agent; it is a runtime
+ * failure that would surface only on the first request that reaches the missing
+ * branch, so it fails at build time instead.
+ *
+ * `agents/handoff-cycles`: handoffs form a graph, and a cycle in it is an unbounded
+ * transfer loop. Lexical cycles are reported once per cycle, at the agent that closes
+ * it, because reporting every member would multiply one defect into N diagnostics.
+ *
+ * `agents/budgets`: an agent that can take more than one step must say what stops it.
+ * Phase 2 L1 has no runtime, so this is the only place a runaway loop can be caught,
+ * and "no budget declared" is read as "unbounded", never as "some default".
+ *
+ * `agents/budget-degrade`: `onBudgetExhausted: degrade` is a promise that a budget
+ * breach has somewhere cheaper to go. Degrade only helps against a *cost* ceiling
+ * (switching aliases does not make tokens cheaper), and it can only be proven if the
+ * model's declared fallbacks contain one whose pinned cost is strictly lower. An
+ * agent that asks for degrade without either would fail at run time, on the one path
+ * the field was added to survive, so it fails here instead.
+ */
+import type { IR } from '../shapes.js';
+import { type GateOptions, type GateResult } from './contract.js';
+export declare function agentsRefsGate(ir: IR, options: GateOptions): GateResult;
+export declare function agentsHandoffGate(ir: IR, options: GateOptions): GateResult;
+export declare function agentsBudgetGate(ir: IR, options: GateOptions): GateResult;
+/**
+ * A degrade request must have somewhere cheaper to go, and that somewhere must be
+ * provable from the pinned cost profiles rather than assumed.
+ */
+export declare function agentsBudgetDegradeGate(ir: IR, options: GateOptions): GateResult;
+//# sourceMappingURL=agents.d.ts.map

package/dist/gates/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/gates/agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAc,EAAE,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAA6B,MAAM,eAAe,CAAC;AAe7F,wBAAgB,cAAc,CAAC,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,WAAW,GAAG,UAAU,CAuCvE;AAoBD,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,WAAW,GAAG,UAAU,CAyC1E;AAED,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,WAAW,GAAG,UAAU,CAmDzE;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,WAAW,GAAG,UAAU,CAkChF"}

package/dist/gates/agents.js

@@ -0,0 +1,233 @@
+/**
+ * Agents — four separate gates, because they answer four different questions.
+ *
+ * `agents/refs-resolve`: every name an agent uses exists. An agent whose tool or
+ * guardrail does not resolve is not a partially-working agent; it is a runtime
+ * failure that would surface only on the first request that reaches the missing
+ * branch, so it fails at build time instead.
+ *
+ * `agents/handoff-cycles`: handoffs form a graph, and a cycle in it is an unbounded
+ * transfer loop. Lexical cycles are reported once per cycle, at the agent that closes
+ * it, because reporting every member would multiply one defect into N diagnostics.
+ *
+ * `agents/budgets`: an agent that can take more than one step must say what stops it.
+ * Phase 2 L1 has no runtime, so this is the only place a runaway loop can be caught,
+ * and "no budget declared" is read as "unbounded", never as "some default".
+ *
+ * `agents/budget-degrade`: `onBudgetExhausted: degrade` is a promise that a budget
+ * breach has somewhere cheaper to go. Degrade only helps against a *cost* ceiling
+ * (switching aliases does not make tokens cheaper), and it can only be proven if the
+ * model's declared fallbacks contain one whose pinned cost is strictly lower. An
+ * agent that asks for degrade without either would fail at run time, on the one path
+ * the field was added to survive, so it fails here instead.
+ */
+import { IR_DIAGNOSTIC_CODES } from '../diagnostics.js';
+import { NO_SUPPRESSIONS, reporter } from './contract.js';
+/** What each agent field refers to, so one loop can check all six collections. */
+const REF_FIELDS = [
+    { field: 'instructions', section: 'prompts', kind: 'prompt' },
+    { field: 'model', section: 'models', kind: 'model' },
+    { field: 'retrievers', section: 'retrievers', kind: 'retriever' },
+    { field: 'memory', section: 'memory', kind: 'memory tier' },
+    { field: 'guardrails', section: 'guardrails', kind: 'guardrail' },
+    { field: 'handoffs', section: 'agents', kind: 'agent' },
+    { field: 'delegates', section: 'agents', kind: 'agent' },
+];
+export function agentsRefsGate(ir, options) {
+    const diagnostics = [];
+    const report = reporter(options);
+    for (const { field, section, kind } of REF_FIELDS) {
+        const declared = new Set(ir[section].map((entry) => entry.id));
+        const available = [...declared].sort();
+        for (const agent of ir.agents) {
+            const value = agent[field];
+            if (Array.isArray(value)) {
+                for (const ref of value) {
+                    if (declared.has(ref))
+                        continue;
+                    diagnostics.push(report.error({
+                        code: IR_DIAGNOSTIC_CODES.agentsRefUnresolved,
+                        message: `the agents gate rejected "${agent.id}": ${field} names "${ref}", which is not a declared ${kind}`,
+                        path: ['agents', agent.id, field],
+                        hint: `declared ${kind}s: ${available.join(', ') || 'none'}`,
+                    }));
+                }
+                continue;
+            }
+            if (typeof value !== 'string' || value === '' || declared.has(value))
+                continue;
+            diagnostics.push(report.error({
+                code: IR_DIAGNOSTIC_CODES.agentsRefUnresolved,
+                message: `the agents gate rejected "${agent.id}": ${field} names "${value}", which is not a declared ${kind}`,
+                path: ['agents', agent.id, field],
+                hint: `declared ${kind}s: ${available.join(', ') || 'none'}`,
+            }));
+        }
+    }
+    checkToolRefs(ir, diagnostics, report);
+    return { diagnostics, suppressed: NO_SUPPRESSIONS };
+}
+/** Tools are a field of their own: an agent may use none, but never a phantom one. */
+function checkToolRefs(ir, diagnostics, report) {
+    const declared = new Set(ir.tools.map((tool) => tool.id));
+    for (const agent of ir.agents) {
+        for (const ref of agent.tools) {
+            if (declared.has(ref))
+                continue;
+            diagnostics.push(report.error({
+                code: IR_DIAGNOSTIC_CODES.agentsRefUnresolved,
+                message: `the agents gate rejected "${agent.id}": tools names "${ref}", which is not a declared tool`,
+                path: ['agents', agent.id, 'tools'],
+                hint: `declared tools: ${[...declared].sort().join(', ') || 'none'}`,
+            }));
+        }
+    }
+}
+export function agentsHandoffGate(ir, options) {
+    const diagnostics = [];
+    const report = reporter(options);
+    const byId = new Map(ir.agents.map((agent) => [agent.id, agent]));
+    // `visiting` is the DFS stack, `done` the agents whose subtree is proven acyclic.
+    const visiting = [];
+    const done = new Set();
+    const reported = new Set();
+    const walk = (agent) => {
+        if (done.has(agent.id))
+            return;
+        visiting.push(agent.id);
+        for (const next of agent.handoffs) {
+            const target = byId.get(next);
+            // A missing handoff target is `agents/refs-resolve`'s diagnostic, not ours.
+            if (target === undefined)
+                continue;
+            const at = visiting.indexOf(next);
+            if (at !== -1) {
+                const cycle = [...visiting.slice(at), next];
+                const key = [...cycle].sort().join('>');
+                if (reported.has(key))
+                    continue;
+                reported.add(key);
+                diagnostics.push(report.error({
+                    code: IR_DIAGNOSTIC_CODES.agentsHandoffCycle,
+                    message: `the agents gate rejected a handoff cycle: ${cycle.join(' -> ')}; a handoff transfers the conversation and never returns, so a cycle is an unbounded transfer`,
+                    path: ['agents', visiting[at] ?? next, 'handoffs'],
+                    hint: 'use delegates for a sub-task that returns to the caller, or break the cycle',
+                }));
+                continue;
+            }
+            walk(target);
+        }
+        visiting.pop();
+        done.add(agent.id);
+    };
+    for (const agent of ir.agents)
+        walk(agent);
+    return { diagnostics, suppressed: NO_SUPPRESSIONS };
+}
+export function agentsBudgetGate(ir, options) {
+    const diagnostics = [];
+    const report = reporter(options);
+    for (const agent of ir.agents) {
+        if (!Number.isInteger(agent.maxSteps) || agent.maxSteps < 1) {
+            diagnostics.push(report.error({
+                code: IR_DIAGNOSTIC_CODES.agentsBudget,
+                message: `the agents gate rejected "${agent.id}": maxSteps is ${agent.maxSteps}, so the agent can never complete a step`,
+                path: ['agents', agent.id, 'maxSteps'],
+                hint: 'set maxSteps to at least 1',
+            }));
+        }
+        if (agent.maxTokensBudget !== undefined && agent.maxTokensBudget < 1) {
+            diagnostics.push(report.error({
+                code: IR_DIAGNOSTIC_CODES.agentsBudget,
+                message: `the agents gate rejected "${agent.id}": maxTokensBudget is ${agent.maxTokensBudget}, which no run can satisfy`,
+                path: ['agents', agent.id, 'maxTokensBudget'],
+                hint: 'set maxTokensBudget to at least 1, or omit it',
+            }));
+        }
+        if (agent.maxCostBudget !== undefined && !(agent.maxCostBudget > 0)) {
+            diagnostics.push(report.error({
+                code: IR_DIAGNOSTIC_CODES.agentsBudget,
+                message: `the agents gate rejected "${agent.id}": maxCostBudget is ${agent.maxCostBudget}, which no run can satisfy`,
+                path: ['agents', agent.id, 'maxCostBudget'],
+                hint: 'set maxCostBudget above zero, or omit it',
+            }));
+        }
+        const loopable = agent.maxSteps > 1;
+        const bounded = agent.maxTokensBudget !== undefined || agent.maxCostBudget !== undefined;
+        if (loopable && !bounded) {
+            diagnostics.push(report.error({
+                code: IR_DIAGNOSTIC_CODES.agentsBudget,
+                message: `the agents gate rejected "${agent.id}": it may take up to ${agent.maxSteps} steps but declares neither maxTokensBudget nor maxCostBudget, so nothing bounds what one run costs`,
+                path: ['agents', agent.id, 'maxTokensBudget'],
+                hint: 'declare maxTokensBudget or maxCostBudget, or set maxSteps: 1',
+            }));
+        }
+    }
+    return { diagnostics, suppressed: NO_SUPPRESSIONS };
+}
+/**
+ * A degrade request must have somewhere cheaper to go, and that somewhere must be
+ * provable from the pinned cost profiles rather than assumed.
+ */
+export function agentsBudgetDegradeGate(ir, options) {
+    const diagnostics = [];
+    const report = reporter(options);
+    const models = new Map(ir.models.map((model) => [model.id, model]));
+    for (const agent of ir.agents) {
+        if (agent.onBudgetExhausted !== 'degrade')
+            continue;
+        if (agent.maxCostBudget === undefined) {
+            diagnostics.push(report.error({
+                code: IR_DIAGNOSTIC_CODES.agentsBudgetDegrade,
+                message: `the agents gate rejected "${agent.id}": onBudgetExhausted is "degrade" but it declares no maxCostBudget, and switching aliases cannot make a token ceiling cheaper`,
+                path: ['agents', agent.id, 'onBudgetExhausted'],
+                hint: 'declare maxCostBudget, or set onBudgetExhausted: fail',
+            }));
+        }
+        const model = models.get(agent.model);
+        // An unresolved model is `agents/refs-resolve`'s diagnostic, not ours.
+        if (model === undefined)
+            continue;
+        if (cheaperFallbacks(ir, model).length > 0)
+            continue;
+        diagnostics.push(report.error({
+            code: IR_DIAGNOSTIC_CODES.agentsBudgetDegrade,
+            message: `the agents gate rejected "${agent.id}": onBudgetExhausted is "degrade" but model "${model.id}" has no fallback alias that is strictly cheaper, so a budget breach would still be a hard failure at run time`,
+            path: ['agents', agent.id, 'onBudgetExhausted'],
+            hint: degradeHint(model, ir),
+        }));
+    }
+    return { diagnostics, suppressed: NO_SUPPRESSIONS };
+}
+/** Fallback aliases that are strictly cheaper than `model`, in declaration order. */
+function cheaperFallbacks(ir, model) {
+    const models = new Map(ir.models.map((entry) => [entry.id, entry]));
+    const current = aliasCost(models.get(model.id));
+    if (current === undefined)
+        return [];
+    return model.fallbacks.filter((id) => {
+        const candidate = aliasCost(models.get(id));
+        return candidate !== undefined && candidate < current;
+    });
+}
+function aliasCost(model) {
+    if (model?.costProfile === undefined)
+        return undefined;
+    return model.costProfile.inputPerMTok + model.costProfile.outputPerMTok;
+}
+function degradeHint(model, ir) {
+    const models = new Map(ir.models.map((entry) => [entry.id, entry]));
+    if (model.fallbacks.length === 0) {
+        return `declare at least one cheaper alias in models.${model.id}.fallbacks, or set onBudgetExhausted: fail`;
+    }
+    const current = aliasCost(models.get(model.id));
+    if (current === undefined) {
+        return `models.${model.id} has no costProfile, so no fallback can be proven cheaper; declare one, or set onBudgetExhausted: fail`;
+    }
+    const priced = model.fallbacks.map((id) => {
+        const cost = aliasCost(models.get(id));
+        return cost === undefined ? `${id} (unpriced)` : `${id} (${cost})`;
+    });
+    return `fallbacks ${priced.join(', ')} are not cheaper than ${current} (sum of input and output list price); declare a cheaper alias, or set onBudgetExhausted: fail`;
+}
+//# sourceMappingURL=agents.js.map

package/dist/gates/agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.js","sourceRoot":"","sources":["../../src/gates/agents.ts"],"names":[],"mappings":"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"}

package/dist/gates/capability.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Gate 3 — capability.
+ *
+ * A target generator declares the capabilities it implements; the IR derives what it
+ * requires from its own content. The gate intersects the two and fails on any unmet
+ * requirement, so a generator is never handed work it cannot express.
+ *
+ * `packages/generator-sdk` does not exist in layer 2, so the declarations arrive as
+ * an injected parameter. Layer 3 supplies real generator declarations and nothing
+ * else in this module changes.
+ */
+import type { IR } from '../shapes.js';
+import { type GateOptions, type GateResult } from './contract.js';
+export declare function capabilityGate(ir: IR, options: GateOptions): GateResult;
+//# sourceMappingURL=capability.d.ts.map

package/dist/gates/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../src/gates/capability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAkC,MAAM,eAAe,CAAC;AAMlG,wBAAgB,cAAc,CAAC,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,WAAW,GAAG,UAAU,CAoDvE"}

package/dist/gates/capability.js

@@ -0,0 +1,81 @@
+/**
+ * Gate 3 — capability.
+ *
+ * A target generator declares the capabilities it implements; the IR derives what it
+ * requires from its own content. The gate intersects the two and fails on any unmet
+ * requirement, so a generator is never handed work it cannot express.
+ *
+ * `packages/generator-sdk` does not exist in layer 2, so the declarations arrive as
+ * an injected parameter. Layer 3 supplies real generator declarations and nothing
+ * else in this module changes.
+ */
+import { REQUIRED_CAPABILITIES, resolveRequiredCapability, } from '../capabilities.js';
+import { IR_DIAGNOSTIC_CODES } from '../diagnostics.js';
+import { reporter } from './contract.js';
+const SUPPRESSED = [];
+export function capabilityGate(ir, options) {
+    const diagnostics = [];
+    const report = reporter(options);
+    const required = new Set(ir.requiredCapabilities);
+    for (const target of ir.project.targets) {
+        const declared = options.targetCapabilities[target];
+        if (declared === undefined) {
+            diagnostics.push(report.error({
+                code: IR_DIAGNOSTIC_CODES.targetUnknown,
+                message: `the capability gate rejected this target: no capability declaration is registered for "${target}", so nothing it can generate is known`,
+                path: ['project', 'targets'],
+                hint: `Phase 0 declares ${Object.keys(options.targetCapabilities).join(', ') || 'no targets'}`,
+            }));
+            continue;
+        }
+        const capabilities = new Set();
+        for (const entry of declared) {
+            const resolved = resolveRequiredCapability(entry);
+            if (resolved === undefined) {
+                diagnostics.push(report.error({
+                    code: IR_DIAGNOSTIC_CODES.capabilityUnknown,
+                    message: `the capability gate rejected this declaration: "${entry}" is not a capability of the vocabulary (${REQUIRED_CAPABILITIES.join(', ')})`,
+                    path: ['project', 'targets'],
+                    hint: 'declare a capability from the vocabulary, or extend it deliberately',
+                }));
+                continue;
+            }
+            capabilities.add(resolved);
+        }
+        for (const capability of required) {
+            if (capabilities.has(capability))
+                continue;
+            diagnostics.push(report.error({
+                code: IR_DIAGNOSTIC_CODES.capabilityMissing,
+                message: `the capability gate rejected target "${target}": the IR requires "${capability}", which this target does not declare`,
+                path: ['project', 'targets'],
+                hint: `declare "${capability}" for "${target}", or drop the feature that needs it`,
+            }));
+        }
+    }
+    checkStructuredOutputModels(ir, diagnostics, report);
+    return { diagnostics, suppressed: SUPPRESSED };
+}
+/**
+ * A structured-output prompt needs a model that can constrain its output, otherwise
+ * the schema the IR carries is unenforceable at the only layer that could enforce it.
+ */
+function checkStructuredOutputModels(ir, diagnostics, report) {
+    const models = new Map(ir.models.map((model) => [model.id, model]));
+    for (const prompt of ir.prompts) {
+        if (prompt.output.kind !== 'structured')
+            continue;
+        const model = models.get(prompt.model);
+        if (model === undefined)
+            continue;
+        if (model.capabilities.includes('json-schema'))
+            continue;
+        diagnostics.push(report.error({
+            code: IR_DIAGNOSTIC_CODES.modelCapabilityMissing,
+            message: `the capability gate rejected this prompt: "${prompt.id}" declares structured output, but its model "${model.id}" does not declare the "json-schema" capability`,
+            path: ['prompts', prompt.id, 'model'],
+            hint: 'bind a model that declares json-schema, or use a text output',
+        }));
+    }
+}
+//# sourceMappingURL=capability.js.map

package/dist/gates/capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../src/gates/capability.ts"],"names":[],"mappings":"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"}

package/dist/gates/contract.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The contract every build-time gate honours.
+ *
+ * A gate returns diagnostics and never throws for a user-recoverable condition.
+ * A check Phase 0 genuinely cannot enforce is reported in `suppressed` with a
+ * stated reason, because a silently-skipped check is indistinguishable from a
+ * passing one — that is how an unpublished rule becomes a false sense of safety.
+ */
+import type { DiagnosticInit } from '@aid-framework/spec';
+import type { TargetCapabilityDeclarations } from '../catalog/index.js';
+import { type IrDiagnostic, type IrDiagnosticCode } from '../diagnostics.js';
+import type { IR } from '../shapes.js';
+/** A check that is not enforceable yet, and why. Never silent. */
+export interface SuppressedCheck {
+    check: string;
+    reason: string;
+}
+export interface GateResult {
+    diagnostics: IrDiagnostic[];
+    suppressed: SuppressedCheck[];
+}
+export interface GateOptions {
+    /** Target capability declarations, injected so this layer never imports the SDK. */
+    targetCapabilities: TargetCapabilityDeclarations;
+    file?: string;
+}
+export type Gate = (ir: IR, options: GateOptions) => GateResult;
+export interface GateReporter {
+    error(init: DiagnosticInit<IrDiagnosticCode>): IrDiagnostic;
+    warn(init: DiagnosticInit<IrDiagnosticCode>): IrDiagnostic;
+}
+/** Binds the source file into every diagnostic a gate emits. */
+export declare function reporter(options: GateOptions): GateReporter;
+export declare const NO_SUPPRESSIONS: SuppressedCheck[];
+//# sourceMappingURL=contract.d.ts.map

package/dist/gates/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/gates/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAItB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,cAAc,CAAC;AAEvC,kEAAkE;AAClE,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,YAAY,EAAE,CAAC;IAC5B,UAAU,EAAE,eAAe,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,oFAAoF;IACpF,kBAAkB,EAAE,4BAA4B,CAAC;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,IAAI,GAAG,CAAC,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,WAAW,KAAK,UAAU,CAAC;AAEhE,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,IAAI,EAAE,cAAc,CAAC,gBAAgB,CAAC,GAAG,YAAY,CAAC;IAC5D,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,gBAAgB,CAAC,GAAG,YAAY,CAAC;CAC5D;AAED,gEAAgE;AAChE,wBAAgB,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,YAAY,CAM3D;AAED,eAAO,MAAM,eAAe,EAAE,eAAe,EAAO,CAAC"}

package/dist/gates/contract.js

@@ -0,0 +1,19 @@
+/**
+ * The contract every build-time gate honours.
+ *
+ * A gate returns diagnostics and never throws for a user-recoverable condition.
+ * A check Phase 0 genuinely cannot enforce is reported in `suppressed` with a
+ * stated reason, because a silently-skipped check is indistinguishable from a
+ * passing one — that is how an unpublished rule becomes a false sense of safety.
+ */
+import { irError, irWarning, withPosition, } from '../diagnostics.js';
+/** Binds the source file into every diagnostic a gate emits. */
+export function reporter(options) {
+    const file = options.file;
+    return {
+        error: (init) => withPosition(irError(init), { file }),
+        warn: (init) => withPosition(irWarning(init), { file }),
+    };
+}
+export const NO_SUPPRESSIONS = [];
+//# sourceMappingURL=contract.js.map

package/dist/gates/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/gates/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAGL,OAAO,EACP,SAAS,EACT,YAAY,GACb,MAAM,mBAAmB,CAAC;AA2B3B,gEAAgE;AAChE,MAAM,UAAU,QAAQ,CAAC,OAAoB;IAC3C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC1B,OAAO;QACL,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC;QACtD,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC;KACxD,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,eAAe,GAAsB,EAAE,CAAC"}

package/dist/gates/cost.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Gate 4 — cost.
+ *
+ * Cost profiles are resolved from the offline catalog in `src/catalog/models.json`, so
+ * an estimate is deterministic and reproducible on a machine with no network. The gate
+ * fails *closed* on an unpriced model that someone declared a budget for: an unpriced
+ * model cannot be shown to fit a budget, and silently assuming it does is the failure
+ * mode this gate exists to prevent.
+ *
+ * A retrieval path is not free by omission: the candidate chunks a retriever materialises
+ * are charged to the model that embeds them, so a retriever with a wide `topK` over large
+ * chunks shows up in the estimate and can exceed a declared budget on its own.
+ */
+import type { EvalShape, IR } from '../shapes.js';
+import { type GateOptions, type GateResult } from './contract.js';
+/** One model's contribution to a target's estimated per-run cost. */
+export interface ModelCostEstimate {
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    /** Absent when no catalog profile resolved, i.e. the model is unpriced. */
+    cost?: number;
+}
+export interface EvalCostEstimate {
+    inputTokens: number;
+    outputTokens: number;
+    /** Absent when any model on the target's path is unpriced. */
+    cost?: number;
+    models: ModelCostEstimate[];
+    /** The declared budget the estimate is compared against, when there is one. */
+    budget?: number;
+}
+export declare function costGate(ir: IR, options: GateOptions): GateResult;
+/**
+ * The estimated per-run cost of one eval target: the sum over the models on the
+ * target's path of its prompt tokens and its bounded output tokens, plus the work the
+ * target's retrievers do.
+ */
+export declare function estimateEvalCost(ir: IR, evalShape: EvalShape): EvalCostEstimate;
+//# sourceMappingURL=cost.d.ts.map

package/dist/gates/cost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.d.ts","sourceRoot":"","sources":["../../src/gates/cost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAe,SAAS,EAAE,EAAE,EAAsC,MAAM,cAAc,CAAC;AACnG,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAkC,MAAM,eAAe,CAAC;AAUlG,qEAAqE;AACrE,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,QAAQ,CAAC,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,WAAW,GAAG,UAAU,CA6CjE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,SAAS,GAAG,gBAAgB,CAkC/E"}