ai-runtime-engine 1.1.0

package/dist/comparison/render.js

@@ -0,0 +1,66 @@
+/**
+ * Human-readable rendering of a ComparisonResult for the terminal (REPL + one-shot). Pure: turns the
+ * structured result into lines. It never claims a verdict the ranking did not make — a judge verdict is
+ * labeled as opinion, and a report-only comparison shows no winner.
+ */
+function candidateLine(c) {
+    const dot = c.ok ? '●' : '○';
+    const who = c.selected ? `${c.selected.providerId}/${c.selected.model}` : c.pin.provider ?? '?';
+    if (!c.ok)
+        return `  ${dot} ${c.label.padEnd(16)} ${who.padEnd(22)} [error: ${c.error?.category ?? 'failed'}]`;
+    const conf = c.confidence !== undefined ? `conf ${c.confidence.toFixed(2)}` : '';
+    const lat = c.latencyMs !== undefined ? `${c.latencyMs}ms` : '';
+    return `  ${dot} ${c.label.padEnd(16)} ${who.padEnd(22)} ${conf.padEnd(10)} ${lat}`;
+}
+export function renderComparison(result) {
+    const lines = [];
+    const okCount = result.candidates.filter((c) => c.ok).length;
+    lines.push(`Compared "${result.goal}" across ${result.usage.ran} model(s) — ${okCount} responded:`);
+    for (const c of result.candidates)
+        lines.push(candidateLine(c));
+    const { analysis, ranking } = result;
+    // Agreement.
+    if (analysis.unanimous) {
+        lines.push('Agreement: unanimous (all responses agree).');
+    }
+    else if (analysis.clusters.length > 1) {
+        lines.push(`Agreement: ${analysis.clusters.length} groups — ${analysis.clusters.map((cl) => `{${cl.labels.join(', ')}}`).join(' vs ')}`);
+    }
+    // Differences.
+    if (analysis.differences.length) {
+        lines.push('Differences:');
+        for (const d of analysis.differences.slice(0, 5))
+            lines.push(`  ${d.a} ↔ ${d.b}: ${Math.round(d.similarity * 100)}% similar`);
+    }
+    // Contradictions (structured only).
+    if (analysis.contradictions.length) {
+        lines.push('Contradictions:');
+        for (const ct of analysis.contradictions)
+            lines.push(`  field "${ct.field}": ${ct.values.map((v) => `${v.label}=${v.value}`).join(', ')}`);
+    }
+    // Missing information.
+    for (const m of analysis.missing) {
+        if (!m.points.length)
+            continue;
+        lines.push(`Only in ${m.label}:`);
+        for (const p of m.points.slice(0, 3))
+            lines.push(`  - ${p.length > 100 ? p.slice(0, 97) + '…' : p}`);
+    }
+    // Verdict.
+    if (ranking.method === 'evidence') {
+        const top = ranking.ranked[0];
+        lines.push(ranking.winner ? `Verdict (evidence): ${ranking.winner} — ${whyFor(ranking, ranking.winner)}` : `Verdict (evidence): no candidate passed validation${top ? ` (best: ${top.label}, ${top.why})` : ''}`);
+    }
+    else if (ranking.method === 'judge') {
+        lines.push(`Verdict (judge opinion, not evidence): ${ranking.winner} — ${whyFor(ranking, ranking.winner)}`);
+    }
+    else {
+        lines.push('No verdict: report only (provide a validate() for evidence, or a judge model for an opinion).');
+    }
+    if (result.usage.note)
+        lines.push(`(${result.usage.note})`);
+    return lines;
+}
+function whyFor(ranking, label) {
+    return ranking.ranked.find((r) => r.label === label)?.why ?? '';
+}

package/dist/config/defaults.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Default weights, timeouts, and policy posture. Weights sum to 100 (capabilityFit 30 / quality 20 /
+ * reliability 15 / historicalSuccess 10 / latency 10 / cost 10 / userPreference 5). All are
+ * overridable via config.
+ */
+import type { Evidence, ScoreWeights, Sensitivity, Strategy } from '../types.js';
+import type { RouterConfig } from '../types.js';
+export declare const DEFAULT_WEIGHTS: ScoreWeights;
+export interface ResolvedPrivacy {
+    allowCloud: boolean;
+    allowLocal: boolean;
+    sensitiveDataAllowedOnCloud: boolean;
+    treatUnknownAsSensitive: boolean;
+    defaultSensitivity: Sensitivity;
+}
+export interface ResolvedConfig {
+    providers: RouterConfig['providers'];
+    strategy: Strategy;
+    weights: ScoreWeights;
+    timeoutMs: number;
+    maxFallbacks: number;
+    minEvidence: Evidence;
+    minConfidence: number;
+    privacy: ResolvedPrivacy;
+    telemetry: {
+        enabled: boolean;
+        sink: 'memory' | 'file';
+        storePrompts: false;
+        path?: string;
+    };
+    learning: {
+        enabled: boolean;
+    };
+    verification: {
+        enabled: boolean;
+    };
+    budget: {
+        maxCostUsd?: number;
+        maxCalls?: number;
+    };
+    policy: NonNullable<RouterConfig['policy']>;
+    tasks: NonNullable<RouterConfig['tasks']>;
+}
+export declare const DEFAULTS: {
+    strategy: Strategy;
+    timeoutMs: number;
+    maxFallbacks: number;
+    minEvidence: Evidence;
+    minConfidence: number;
+};
+/** Merge a user config over the defaults into a fully-resolved config the router can rely on. */
+export declare function resolveConfig(cfg: RouterConfig): ResolvedConfig;

package/dist/config/defaults.js

@@ -0,0 +1,56 @@
+/**
+ * Default weights, timeouts, and policy posture. Weights sum to 100 (capabilityFit 30 / quality 20 /
+ * reliability 15 / historicalSuccess 10 / latency 10 / cost 10 / userPreference 5). All are
+ * overridable via config.
+ */
+export const DEFAULT_WEIGHTS = {
+    capabilityFit: 30,
+    quality: 20,
+    reliability: 15,
+    historicalSuccess: 10,
+    latency: 10,
+    cost: 10,
+    userPreference: 5,
+};
+export const DEFAULTS = {
+    strategy: 'best',
+    timeoutMs: 90_000,
+    maxFallbacks: 4,
+    minEvidence: 'documented',
+    minConfidence: 0.7,
+};
+/** Merge a user config over the defaults into a fully-resolved config the router can rely on. */
+export function resolveConfig(cfg) {
+    const privacy = {
+        allowCloud: cfg.privacy?.allowCloud ?? true,
+        allowLocal: cfg.privacy?.allowLocal ?? true,
+        sensitiveDataAllowedOnCloud: cfg.privacy?.sensitiveDataAllowedOnCloud ?? false,
+        treatUnknownAsSensitive: cfg.privacy?.treatUnknownAsSensitive ?? false,
+        defaultSensitivity: cfg.privacy?.defaultSensitivity ?? 'unknown',
+    };
+    const telemetry = {
+        enabled: cfg.telemetry?.enabled ?? true,
+        sink: cfg.telemetry?.sink ?? 'memory',
+        storePrompts: false,
+        ...(cfg.telemetry?.path !== undefined ? { path: cfg.telemetry.path } : {}),
+    };
+    return {
+        providers: cfg.providers,
+        strategy: cfg.strategy ?? DEFAULTS.strategy,
+        weights: { ...DEFAULT_WEIGHTS, ...(cfg.weights ?? {}) },
+        timeoutMs: cfg.defaults?.timeoutMs ?? DEFAULTS.timeoutMs,
+        maxFallbacks: cfg.defaults?.maxFallbacks ?? DEFAULTS.maxFallbacks,
+        minEvidence: cfg.defaults?.minEvidence ?? DEFAULTS.minEvidence,
+        minConfidence: cfg.defaults?.minConfidence ?? DEFAULTS.minConfidence,
+        privacy,
+        telemetry,
+        learning: { enabled: cfg.learning?.enabled ?? true },
+        verification: { enabled: cfg.verification?.enabled ?? false },
+        budget: {
+            ...(cfg.budget?.maxCostUsd !== undefined ? { maxCostUsd: cfg.budget.maxCostUsd } : {}),
+            ...(cfg.budget?.maxCalls !== undefined ? { maxCalls: cfg.budget.maxCalls } : {}),
+        },
+        policy: cfg.policy ?? {},
+        tasks: cfg.tasks ?? [],
+    };
+}

package/dist/config/load.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Load a RouterConfig from a YAML/JSON file and populate the environment from `.env` (dotenv). The
+ * config file carries only structure and env-var NAMES; secret values live in `.env` (gitignored).
+ * Resolution: defaults ← file ← env (env-var values are read later by the credential layer).
+ */
+import type { RouterConfig } from '../types.js';
+export declare function findConfigFile(cwd?: string): string | undefined;
+/** Load config from an explicit path or the first default file found; returns an empty config if none. */
+export declare function loadConfig(path?: string, cwd?: string): RouterConfig;
+/**
+ * Remote configuration. Fetch and validate a config from an http(s) URL. The response is
+ * still run through the same zod validation, so a remote config can no more carry an inline secret
+ * than a local one.
+ */
+export declare function loadRemoteConfig(url: string): Promise<RouterConfig>;
+/** Load from a local path or an http(s) URL. */
+export declare function loadConfigAsync(pathOrUrl?: string, cwd?: string): Promise<RouterConfig>;

package/dist/config/load.js

@@ -0,0 +1,50 @@
+/**
+ * Load a RouterConfig from a YAML/JSON file and populate the environment from `.env` (dotenv). The
+ * config file carries only structure and env-var NAMES; secret values live in `.env` (gitignored).
+ * Resolution: defaults ← file ← env (env-var values are read later by the credential layer).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { config as loadDotenv } from 'dotenv';
+import { parseConfig } from './schema.js';
+import { AIError } from '../core/fallback/errors.js';
+const DEFAULT_FILES = ['ai-runtime.yaml', 'ai-runtime.yml', 'ai-runtime.json'];
+export function findConfigFile(cwd = process.cwd()) {
+    for (const name of DEFAULT_FILES) {
+        const full = resolve(cwd, name);
+        if (existsSync(full))
+            return full;
+    }
+    return undefined;
+}
+/** Load config from an explicit path or the first default file found; returns an empty config if none. */
+export function loadConfig(path, cwd = process.cwd()) {
+    loadDotenv({ quiet: true });
+    const file = path ? resolve(cwd, path) : findConfigFile(cwd);
+    if (!file || !existsSync(file))
+        return { providers: [] };
+    const text = readFileSync(file, 'utf8');
+    const raw = file.endsWith('.json') ? JSON.parse(text) : parseYaml(text);
+    return parseConfig(raw);
+}
+/**
+ * Remote configuration. Fetch and validate a config from an http(s) URL. The response is
+ * still run through the same zod validation, so a remote config can no more carry an inline secret
+ * than a local one.
+ */
+export async function loadRemoteConfig(url) {
+    loadDotenv({ quiet: true });
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new AIError(`failed to fetch remote config (HTTP ${res.status})`, { category: 'CONFIG' });
+    const text = await res.text();
+    const looksJson = url.endsWith('.json') || text.trimStart().startsWith('{');
+    return parseConfig(looksJson ? JSON.parse(text) : parseYaml(text));
+}
+/** Load from a local path or an http(s) URL. */
+export async function loadConfigAsync(pathOrUrl, cwd = process.cwd()) {
+    if (pathOrUrl && /^https?:\/\//i.test(pathOrUrl))
+        return loadRemoteConfig(pathOrUrl);
+    return loadConfig(pathOrUrl, cwd);
+}

package/dist/config/providerDefaults.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Per-vendor transport defaults — base URL, wire shape, privacy class, default models, and the
+ * conventional env var name for the key. Vendor knowledge lives here (config layer), never in core.
+ */
+import type { PrivacyClass, ProviderKind } from '../types.js';
+import type { WireShape } from '../providers/wire/types.js';
+export interface ProviderDefault {
+    name: string;
+    baseUrl?: string;
+    wireShape: WireShape;
+    privacyClass: PrivacyClass;
+    defaultModels: string[];
+    apiKeyEnv?: string;
+    requiresKey: boolean;
+    supportsModelListing: boolean;
+}
+export declare const PROVIDER_DEFAULTS: Record<Exclude<ProviderKind, 'mock'>, ProviderDefault>;

package/dist/config/providerDefaults.js

@@ -0,0 +1,61 @@
+/**
+ * Per-vendor transport defaults — base URL, wire shape, privacy class, default models, and the
+ * conventional env var name for the key. Vendor knowledge lives here (config layer), never in core.
+ */
+export const PROVIDER_DEFAULTS = {
+    gemini: {
+        name: 'Google Gemini',
+        baseUrl: 'https://generativelanguage.googleapis.com/v1beta/openai',
+        wireShape: 'openai',
+        privacyClass: 'cloud',
+        defaultModels: ['gemini-3.6-flash', 'gemini-2.5-flash-lite'],
+        apiKeyEnv: 'GEMINI_API_KEY',
+        requiresKey: true,
+        supportsModelListing: true,
+    },
+    groq: {
+        name: 'Groq',
+        baseUrl: 'https://api.groq.com/openai/v1',
+        wireShape: 'openai',
+        privacyClass: 'cloud',
+        defaultModels: ['llama-3.3-70b'],
+        apiKeyEnv: 'GROQ_API_KEY',
+        requiresKey: true,
+        supportsModelListing: true,
+    },
+    anthropic: {
+        name: 'Anthropic',
+        baseUrl: 'https://api.anthropic.com',
+        wireShape: 'anthropic',
+        privacyClass: 'cloud',
+        defaultModels: ['claude-sonnet-5', 'claude-haiku-4-5'],
+        apiKeyEnv: 'ANTHROPIC_API_KEY',
+        requiresKey: true,
+        supportsModelListing: false,
+    },
+    ollama: {
+        name: 'Ollama (local)',
+        baseUrl: 'http://localhost:11434/v1',
+        wireShape: 'openai',
+        privacyClass: 'local',
+        defaultModels: ['llama3.1'],
+        requiresKey: false,
+        supportsModelListing: true,
+    },
+    'openai-compatible': {
+        name: 'OpenAI-compatible',
+        wireShape: 'openai',
+        privacyClass: 'cloud',
+        defaultModels: [],
+        requiresKey: true,
+        supportsModelListing: true,
+    },
+    custom: {
+        name: 'Custom',
+        wireShape: 'openai',
+        privacyClass: 'cloud',
+        defaultModels: [],
+        requiresKey: true,
+        supportsModelListing: false,
+    },
+};

package/dist/config/schema.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Config validation with zod. Runs at load time so a malformed config fails with an actionable
+ * message instead of a runtime 404 later. Provider blocks are `.strict()` — an unknown key (e.g. a
+ * stray inline `apiKey`) is rejected, which structurally prevents committing a raw secret in config.
+ */
+import type { RouterConfig } from '../types.js';
+/** Canonical strategy names. Exported for reuse by the runtime-config layer (no duplication). */
+export declare const STRATEGIES: readonly ["best", "fastest", "cheapest", "highest-quality", "local-only", "cloud-only", "privacy-first", "provider-specific", "fallback-only"];
+export declare function parseConfig(raw: unknown): RouterConfig;

package/dist/config/schema.js

@@ -0,0 +1,78 @@
+/**
+ * Config validation with zod. Runs at load time so a malformed config fails with an actionable
+ * message instead of a runtime 404 later. Provider blocks are `.strict()` — an unknown key (e.g. a
+ * stray inline `apiKey`) is rejected, which structurally prevents committing a raw secret in config.
+ */
+import { z } from 'zod';
+import { AIError } from '../core/fallback/errors.js';
+/** Canonical strategy names. Exported for reuse by the runtime-config layer (no duplication). */
+export const STRATEGIES = ['best', 'fastest', 'cheapest', 'highest-quality', 'local-only', 'cloud-only', 'privacy-first', 'provider-specific', 'fallback-only'];
+const EVIDENCE = ['unsupported', 'unknown', 'inferred', 'documented', 'verified'];
+const GROUPS = ['input', 'output', 'intelligence', 'agent'];
+const KINDS = ['openai-compatible', 'gemini', 'groq', 'anthropic', 'ollama', 'custom', 'mock'];
+const KEY_LIKE = /^(sk-|gsk_|Bearer\s|[A-Za-z0-9_-]{40,}$)/;
+const capabilityRequirement = z.object({
+    group: z.enum(GROUPS),
+    key: z.string().min(1),
+    minEvidence: z.enum(EVIDENCE).optional(),
+    weight: z.number().optional(),
+});
+const taskDefinition = z
+    .object({
+    id: z.string().min(1),
+    aliases: z.array(z.string()).optional(),
+    description: z.string().optional(),
+    required: z.array(capabilityRequirement),
+    preferred: z.array(capabilityRequirement).optional(),
+    minContextWindow: z.number().optional(),
+    output: z.object({ format: z.enum(['text', 'json', 'structured_output', 'code']), schema: z.unknown().optional() }).optional(),
+    defaultStrategy: z.enum(STRATEGIES).optional(),
+    privacy: z.object({ requireLocal: z.boolean().optional() }).optional(),
+    qualityFloor: z.enum(['frontier', 'strong', 'mid', 'small']).optional(),
+})
+    .strict();
+const providerConfig = z
+    .object({
+    id: z.string().min(1),
+    kind: z.enum(KINDS),
+    baseUrl: z.string().url().optional(),
+    apiKeyEnv: z
+        .string()
+        .optional()
+        .refine((v) => v === undefined || !KEY_LIKE.test(v), { message: 'apiKeyEnv must be an env-var NAME, not a key value' }),
+    enabled: z.boolean().optional(),
+    models: z.union([z.array(z.string()), z.literal('auto')]).optional(),
+    defaultModel: z.string().optional(),
+    capabilities: z
+        .object({ input: z.array(z.string()).optional(), output: z.array(z.string()).optional(), intelligence: z.array(z.string()).optional(), agent: z.array(z.string()).optional(), contextWindow: z.number().optional() })
+        .strict()
+        .optional(),
+    privacyClass: z.enum(['local', 'cloud']).optional(),
+    wireShape: z.enum(['openai', 'anthropic']).optional(),
+    headers: z.record(z.string()).optional(),
+    weightOverrides: z.record(z.number()).optional(),
+})
+    .strict()
+    .refine((p) => !(['openai-compatible', 'custom'].includes(p.kind) && !p.baseUrl), { message: 'openai-compatible/custom providers require a baseUrl' });
+const routerConfig = z
+    .object({
+    providers: z.array(providerConfig),
+    strategy: z.enum(STRATEGIES).optional(),
+    weights: z.record(z.number()).optional(),
+    defaults: z.object({ timeoutMs: z.number().optional(), maxFallbacks: z.number().optional(), minEvidence: z.enum(EVIDENCE).optional(), minConfidence: z.number().optional() }).strict().optional(),
+    privacy: z
+        .object({ allowCloud: z.boolean().optional(), allowLocal: z.boolean().optional(), sensitiveDataAllowedOnCloud: z.boolean().optional(), treatUnknownAsSensitive: z.boolean().optional(), defaultSensitivity: z.enum(['low', 'high', 'unknown']).optional() })
+        .strict()
+        .optional(),
+    telemetry: z.object({ enabled: z.boolean().optional(), sink: z.enum(['memory', 'file']).optional(), storePrompts: z.literal(false).optional(), path: z.string().optional() }).strict().optional(),
+    tasks: z.array(taskDefinition).optional(),
+})
+    .strict();
+export function parseConfig(raw) {
+    const result = routerConfig.safeParse(raw);
+    if (!result.success) {
+        const issues = result.error.issues.map((i) => `  - ${i.path.join('.') || '(root)'}: ${i.message}`).join('\n');
+        throw new AIError(`invalid ai-runtime config:\n${issues}`, { category: 'CONFIG' });
+    }
+    return result.data;
+}

package/dist/context/budget.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Context-budget resolution. Governs the COMPILED CONTEXT size only (system prompt + assembled
+ * context) — distinct from provider input/output/total token usage, call count, and cost. Precedence:
+ * per-run > project config > env (AI_CONTEXT_MAX_TOKENS) > model-aware default.
+ */
+export declare const DEFAULT_CONTEXT_TOKENS = 8000;
+export interface ContextBudgetInputs {
+    perRun?: number;
+    config?: number;
+    env?: string;
+    modelDefault?: number;
+}
+export declare function resolveContextBudget(i: ContextBudgetInputs): number;

package/dist/context/budget.js

@@ -0,0 +1,17 @@
+/**
+ * Context-budget resolution. Governs the COMPILED CONTEXT size only (system prompt + assembled
+ * context) — distinct from provider input/output/total token usage, call count, and cost. Precedence:
+ * per-run > project config > env (AI_CONTEXT_MAX_TOKENS) > model-aware default.
+ */
+export const DEFAULT_CONTEXT_TOKENS = 8000;
+function positive(n) {
+    return n !== undefined && Number.isFinite(n) && n > 0 ? n : undefined;
+}
+function fromEnv(raw) {
+    if (raw === undefined || raw.trim() === '')
+        return undefined;
+    return positive(Number(raw));
+}
+export function resolveContextBudget(i) {
+    return positive(i.perRun) ?? positive(i.config) ?? fromEnv(i.env) ?? positive(i.modelDefault) ?? DEFAULT_CONTEXT_TOKENS;
+}

package/dist/context/compiler.d.ts

@@ -0,0 +1,61 @@
+/**
+ * ContextCompiler — turns RuntimeContext-derived blocks into a compiled model context under a token
+ * budget. Pipeline: rank (by retention, then caller order) → dedupe → protect (critical kept verbatim)
+ * → compress/drop the rest to fit → assemble → validate (task-critical items survived). The output is a
+ * transient model input, NOT a runtime-state abstraction, and input blocks are never mutated
+ * (recoverability). Artifact blocks are inlined only when their full content fits; otherwise a compact
+ * reference is emitted.
+ */
+import { TokenEstimator } from './tokens.js';
+export type RetentionLevel = 'critical' | 'high' | 'normal' | 'discardable';
+export interface ContextBlock {
+    id: string;
+    kind: string;
+    text: string;
+    retention: RetentionLevel;
+    /** Artifact blocks: lazily resolve full content when the compiler decides to inline it. */
+    resolveContent?: () => string;
+    /** Artifact blocks: the compact reference emitted when full content does not fit. */
+    reference?: string;
+}
+export interface CompiledBlock {
+    id: string;
+    kind: string;
+    retention: RetentionLevel;
+    text: string;
+    /** True when the block was truncated or replaced by a reference to fit the budget. */
+    compressed: boolean;
+}
+export interface CompileMetrics {
+    originalTokens: number;
+    compiledTokens: number;
+    budgetTokens: number;
+    ratio: number;
+    protectedCount: number;
+    retrievedCount: number;
+    compressedCount: number;
+    droppedCount: number;
+    /** True when protected (critical) content alone exceeded the budget. */
+    overBudget: boolean;
+}
+export interface ContextValidation {
+    ok: boolean;
+    checks: Array<{
+        name: string;
+        ok: boolean;
+        why?: string;
+    }>;
+}
+export interface CompiledContext {
+    system: string;
+    blocks: CompiledBlock[];
+    dropped: string[];
+    metrics: CompileMetrics;
+    validation: ContextValidation;
+}
+export interface CompileOptions {
+    budgetTokens: number;
+    estimator?: TokenEstimator;
+    separator?: string;
+}
+export declare function compileContext(blocks: ContextBlock[], opts: CompileOptions): CompiledContext;

package/dist/context/compiler.js

@@ -0,0 +1,125 @@
+/**
+ * ContextCompiler — turns RuntimeContext-derived blocks into a compiled model context under a token
+ * budget. Pipeline: rank (by retention, then caller order) → dedupe → protect (critical kept verbatim)
+ * → compress/drop the rest to fit → assemble → validate (task-critical items survived). The output is a
+ * transient model input, NOT a runtime-state abstraction, and input blocks are never mutated
+ * (recoverability). Artifact blocks are inlined only when their full content fits; otherwise a compact
+ * reference is emitted.
+ */
+import { TokenEstimator } from './tokens.js';
+const RANK = { critical: 0, high: 1, normal: 2, discardable: 3 };
+const MIN_COMPRESS_TOKENS = 4; // below this, truncation is useless — drop instead
+/** Extract identifier-like tokens (paths, file.ext, quoted strings, ALL_CAPS ids) for loss validation. */
+function identifiers(text) {
+    const out = new Set();
+    for (const m of text.matchAll(/[A-Za-z0-9_./-]+\.[A-Za-z0-9]+/g))
+        out.add(m[0]); // file.ext / path.seg
+    for (const m of text.matchAll(/\b[A-Z][A-Z0-9_]{2,}\b/g))
+        out.add(m[0]); // ALL_CAPS_IDS
+    return [...out];
+}
+export function compileContext(blocks, opts) {
+    const estimator = opts.estimator ?? new TokenEstimator();
+    const sep = opts.separator ?? '\n\n';
+    const sepTokens = estimator.estimate(sep);
+    const budget = Math.max(0, opts.budgetTokens);
+    const ranked = [...blocks].map((b, i) => ({ b, i })).sort((x, y) => RANK[x.b.retention] - RANK[y.b.retention] || x.i - y.i);
+    // Each kept entry carries its original caller index so assembly restores caller order even when two
+    // blocks happen to share an id (assembly must never key on id — that would collapse/duplicate text).
+    const kept = [];
+    const dropped = [];
+    const seen = new Set();
+    let used = 0;
+    let compressedCount = 0;
+    let overBudget = false;
+    const keep = (order, block, tokens, sepCost) => {
+        kept.push({ order, block });
+        used += sepCost + tokens;
+    };
+    for (const { b, i } of ranked) {
+        const full = b.resolveContent ? b.resolveContent() : b.text;
+        const norm = full.trim();
+        if (norm && seen.has(norm)) {
+            dropped.push(b.id); // redundant duplicate
+            continue;
+        }
+        const sepCost = kept.length ? sepTokens : 0;
+        const fullTokens = estimator.estimate(full);
+        const remaining = budget - used - sepCost;
+        if (b.retention === 'critical') {
+            // Protected: kept verbatim even if it pushes past the budget.
+            keep(i, { id: b.id, kind: b.kind, retention: b.retention, text: full, compressed: false }, fullTokens, sepCost);
+            seen.add(norm);
+            if (used > budget)
+                overBudget = true;
+            continue;
+        }
+        if (fullTokens <= remaining) {
+            keep(i, { id: b.id, kind: b.kind, retention: b.retention, text: full, compressed: false }, fullTokens, sepCost);
+            seen.add(norm);
+            continue;
+        }
+        // Doesn't fit at full size.
+        if (b.retention === 'discardable') {
+            dropped.push(b.id);
+            continue;
+        }
+        // Artifact with a reference that fits → emit the reference.
+        if (b.resolveContent && b.reference && estimator.estimate(b.reference) <= remaining) {
+            keep(i, { id: b.id, kind: b.kind, retention: b.retention, text: b.reference, compressed: true }, estimator.estimate(b.reference), sepCost);
+            compressedCount += 1;
+            continue;
+        }
+        // Truncate to fit, if there's meaningful room; otherwise drop. Re-verify the truncated size fits —
+        // a drifted (sub-1) chars/token ratio can make even "…" exceed `remaining`.
+        if (remaining >= MIN_COMPRESS_TOKENS) {
+            const chars = estimator.charsForTokens(remaining) - 1;
+            const truncated = full.slice(0, Math.max(0, chars)) + '…';
+            const truncTokens = estimator.estimate(truncated);
+            if (chars > 0 && truncTokens <= remaining) {
+                keep(i, { id: b.id, kind: b.kind, retention: b.retention, text: truncated, compressed: true }, truncTokens, sepCost);
+                compressedCount += 1;
+            }
+            else {
+                dropped.push(b.id);
+            }
+        }
+        else {
+            dropped.push(b.id);
+        }
+    }
+    // Assemble in the caller's original order (rank drove inclusion, not layout). Sorted by original index,
+    // not keyed by id, so duplicate ids can never collapse or double a block.
+    const ordered = [...kept].sort((a, z) => a.order - z.order);
+    const system = ordered.map((k) => k.block.text).join(sep);
+    const keptBlocks = ordered.map((k) => k.block);
+    const originalTokens = blocks.reduce((s, b) => s + estimator.estimate(b.resolveContent ? b.resolveContent() : b.text), 0);
+    const compiledTokens = estimator.estimate(system);
+    const metrics = {
+        originalTokens,
+        compiledTokens,
+        budgetTokens: budget,
+        ratio: originalTokens ? compiledTokens / originalTokens : 1,
+        protectedCount: blocks.filter((b) => b.retention === 'critical').length,
+        retrievedCount: blocks.length,
+        compressedCount,
+        droppedCount: dropped.length,
+        overBudget,
+    };
+    return { system, blocks: keptBlocks, dropped, metrics, validation: validate(blocks, system, keptBlocks) };
+}
+/** Deterministic context-loss validation: critical blocks kept verbatim and their identifiers survived. */
+function validate(input, system, kept) {
+    const checks = [];
+    const keptCritical = kept.filter((k) => k.retention === 'critical');
+    const critical = input.filter((b) => b.retention === 'critical');
+    // Validate against the text actually inlined for a critical block (resolved content when present).
+    const criticalText = (b) => (b.resolveContent ? b.resolveContent() : b.text);
+    const noneCompressed = keptCritical.every((k) => !k.compressed);
+    checks.push({ name: 'critical-verbatim', ok: noneCompressed, ...(noneCompressed ? {} : { why: 'a critical block was compressed' }) });
+    const allPresent = critical.every((b) => system.includes(criticalText(b).trim()));
+    checks.push({ name: 'critical-present', ok: allPresent, ...(allPresent ? {} : { why: 'a critical block is missing from the compiled context' }) });
+    const missingId = critical.flatMap((b) => identifiers(criticalText(b))).find((id) => !system.includes(id));
+    checks.push({ name: 'identifiers-preserved', ok: !missingId, ...(missingId ? { why: `identifier "${missingId}" was lost` } : {}) });
+    return { ok: checks.every((c) => c.ok), checks };
+}

package/dist/context/tokens.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Token ESTIMATION for context budgeting. These are heuristic estimates (≈ chars / charsPerToken),
+ * deliberately NOT conflated with provider-reported usage (which is authoritative and separate). The
+ * estimator can be calibrated over time from observed (chars, actualTokens) pairs via an EWMA, so the
+ * ratio drifts toward reality per deployment without ever claiming to be exact.
+ */
+export declare class TokenEstimator {
+    private charsPerToken;
+    constructor(charsPerToken?: number);
+    /** Heuristic token estimate for a string. Always ≥ 0; a non-empty string estimates ≥ 1. */
+    estimate(text: string): number;
+    /** The chars→token ratio a token budget maps to (for compression sizing). */
+    charsForTokens(tokens: number): number;
+    /** Nudge the ratio toward an observed (chars, actualTokens) sample. Ignores degenerate samples. */
+    calibrate(chars: number, actualTokens: number): void;
+    ratio(): number;
+}
+/** Convenience: a one-off estimate with the default ratio. */
+export declare function estimateTokens(text: string): number;