substrate-ai 0.9.0 → 0.11.0

package/dist/routing-BVrxrM6v.js

@@ -1,832 +0,0 @@
-import { createLogger } from "./logger-D2fS2ccL.js";
-import { dump, load } from "js-yaml";
-import { z } from "zod";
-import { readFileSync, writeFileSync } from "node:fs";
-
-//#region src/modules/routing/routing-policy.ts
-/**
-* API billing configuration for a provider.
-*/
-const ApiBillingConfigSchema = z.object({
-	enabled: z.boolean().default(false),
-	api_key_env: z.string().optional()
-});
-/**
-* Rate limit configuration for a provider.
-*/
-const RateLimitConfigSchema = z.object({
-	tokens_per_window: z.number().int().positive(),
-	window_seconds: z.number().int().positive()
-});
-/**
-* Per-provider configuration.
-*/
-const ProviderPolicySchema = z.object({
-	enabled: z.boolean().default(true),
-	cli_path: z.string().default(""),
-	subscription_routing: z.boolean().default(false),
-	max_concurrent: z.number().int().min(1).max(32).default(1),
-	rate_limit: RateLimitConfigSchema.optional(),
-	api_billing: ApiBillingConfigSchema.optional()
-});
-/**
-* Per-task-type routing configuration.
-* Specifies which agents are preferred for a given task type and optional model preferences.
-*/
-const TaskTypePolicySchema = z.object({
-	preferred_agents: z.array(z.string()).min(1),
-	model_preferences: z.record(z.string(), z.string()).optional()
-});
-/**
-* Default routing configuration (used when no task-type-specific policy applies).
-*/
-const DefaultRoutingPolicySchema = z.object({
-	preferred_agents: z.array(z.string()).min(1),
-	billing_preference: z.enum([
-		"subscription_first",
-		"api_only",
-		"subscription_only"
-	]).default("subscription_first"),
-	use_monitor_recommendations: z.boolean().default(false)
-});
-/**
-* Global routing settings.
-*/
-const GlobalRoutingSettingsSchema = z.object({
-	max_concurrent_workers: z.number().int().min(1).max(100).default(5),
-	fallback_enabled: z.boolean().default(true)
-});
-/**
-* Complete routing policy document schema.
-* Supports optional fields gracefully (AC6 — extensibility).
-*/
-const RoutingPolicySchema = z.object({
-	default: DefaultRoutingPolicySchema,
-	task_types: z.record(z.string(), TaskTypePolicySchema).optional().default({}),
-	providers: z.record(z.string(), ProviderPolicySchema).refine((providers) => Object.keys(providers).length > 0, { message: "Routing policy must have at least one provider configured" }),
-	global: GlobalRoutingSettingsSchema.optional().default({
-		max_concurrent_workers: 5,
-		fallback_enabled: true
-	})
-});
-
-//#endregion
-//#region src/modules/routing/routing-engine-impl.ts
-const logger = createLogger("routing");
-
-//#endregion
-//#region src/errors/substrate-error.ts
-/**
-* SubstrateError — structured error base class with code and optional context.
-*
-* All substrate module errors should extend this class to provide
-* machine-readable codes and structured context for upstream error handling.
-*
-* Constructor signature: (message: string, code: string, context?: Record<string, unknown>)
-*/
-var SubstrateError = class extends Error {
-	/** Machine-readable error code */
-	code;
-	/** Structured context carried alongside the error */
-	context;
-	constructor(message, code, context) {
-		super(message);
-		this.name = "SubstrateError";
-		this.code = code;
-		this.context = context;
-		Object.setPrototypeOf(this, new.target.prototype);
-	}
-};
-
-//#endregion
-//#region src/modules/routing/model-routing-config.ts
-const MODEL_NAME_PATTERN = /^[a-zA-Z0-9._-]+$/;
-/**
-* Per-phase model configuration.
-*/
-const ModelPhaseConfigSchema = z.object({
-	model: z.string().regex(MODEL_NAME_PATTERN, "Model name contains invalid characters (must match /^[a-zA-Z0-9._-]+$/)"),
-	max_tokens: z.number().int().positive().optional()
-});
-/**
-* Complete model routing configuration document.
-*
-* All three phase keys (explore, generate, review) are optional — an absent
-* phase causes resolveModel() to return null, signalling callers to use their
-* own default model.
-*/
-const ModelRoutingConfigSchema = z.object({
-	version: z.literal(1),
-	phases: z.object({
-		explore: ModelPhaseConfigSchema.optional(),
-		generate: ModelPhaseConfigSchema.optional(),
-		review: ModelPhaseConfigSchema.optional()
-	}),
-	baseline_model: z.string().regex(MODEL_NAME_PATTERN, "Baseline model name contains invalid characters (must match /^[a-zA-Z0-9._-]+$/)"),
-	overrides: z.record(z.string(), ModelPhaseConfigSchema).optional(),
-	auto_tune: z.boolean().optional()
-});
-/**
-* Error thrown by loadModelRoutingConfig() for all failure modes.
-*
-* Extends SubstrateError so callers can use `instanceof SubstrateError`
-* to catch any substrate structured error.
-*/
-var RoutingConfigError = class extends SubstrateError {
-	constructor(message, code, context) {
-		super(message, code, context);
-		this.name = "RoutingConfigError";
-		Object.setPrototypeOf(this, new.target.prototype);
-	}
-};
-/**
-* Load and validate a model routing config YAML file.
-*
-* @param filePath - Absolute or relative path to substrate.routing.yml
-* @returns Parsed and validated ModelRoutingConfig object
-* @throws {RoutingConfigError} with code CONFIG_NOT_FOUND if the file cannot be read
-* @throws {RoutingConfigError} with code INVALID_YAML if the file contains invalid YAML
-* @throws {RoutingConfigError} with code SCHEMA_INVALID if validation fails
-*
-* @example
-* const config = loadModelRoutingConfig('.substrate/routing.yml')
-*/
-function loadModelRoutingConfig(filePath) {
-	let rawContent;
-	try {
-		rawContent = readFileSync(filePath, "utf-8");
-	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err);
-		throw new RoutingConfigError(`Cannot read routing config file at "${filePath}": ${message}`, "CONFIG_NOT_FOUND", { filePath });
-	}
-	let rawObject;
-	try {
-		rawObject = load(rawContent);
-	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err);
-		throw new RoutingConfigError(`Invalid YAML in routing config file at "${filePath}": ${message}`, "INVALID_YAML", { filePath });
-	}
-	const result = ModelRoutingConfigSchema.safeParse(rawObject);
-	if (!result.success) {
-		const issues = result.error.issues;
-		const details = issues.map((e) => `  - ${e.path.join(".")}: ${e.message}`).join("\n");
-		throw new RoutingConfigError(`Routing config validation failed for "${filePath}":\n${details}`, "SCHEMA_INVALID", { filePath });
-	}
-	return result.data;
-}
-
-//#endregion
-//#region src/modules/routing/model-routing-resolver.ts
-/**
-* Maps known task types to their corresponding pipeline phase.
-* Unknown task types fall through to the 'generate' default.
-*/
-const TASK_TYPE_PHASE_MAP = {
-	"create-story": "generate",
-	"dev-story": "generate",
-	"code-review": "review",
-	"explore": "explore"
-};
-const DEFAULT_PHASE = "generate";
-/**
-* Resolves which model to use for each pipeline task type.
-*
-* Constructed with a ModelRoutingConfig and a logger. Use the static
-* createWithFallback() factory to construct from a file path with graceful
-* handling of missing config files.
-*/
-var RoutingResolver = class RoutingResolver {
-	config;
-	logger;
-	constructor(config, logger$1) {
-		this.config = config;
-		this.logger = logger$1;
-	}
-	/**
-	* Resolve the model for a given task type.
-	*
-	* Resolution order:
-	*  1. config.overrides[taskType] (source: 'override')
-	*  2. config.phases[phase] via TASK_TYPE_PHASE_MAP (source: 'phase')
-	*  3. null if the phase key is absent in config.phases
-	*
-	* @returns ModelResolution if a model is configured, null if in fallback mode
-	*/
-	resolveModel(taskType) {
-		const override = this.config.overrides?.[taskType];
-		if (override) {
-			const phase$1 = TASK_TYPE_PHASE_MAP[taskType] ?? DEFAULT_PHASE;
-			const resolution$1 = {
-				model: override.model,
-				phase: phase$1,
-				source: "override",
-				...override.max_tokens !== void 0 ? { maxTokens: override.max_tokens } : {}
-			};
-			this.logger.debug({
-				taskType,
-				phase: resolution$1.phase,
-				model: resolution$1.model,
-				source: "override"
-			}, "Resolved model");
-			return resolution$1;
-		}
-		const phase = TASK_TYPE_PHASE_MAP[taskType] ?? DEFAULT_PHASE;
-		const phaseConfig = this.config.phases[phase];
-		if (!phaseConfig) return null;
-		const resolution = {
-			model: phaseConfig.model,
-			phase,
-			source: "phase",
-			...phaseConfig.max_tokens !== void 0 ? { maxTokens: phaseConfig.max_tokens } : {}
-		};
-		this.logger.debug({
-			taskType,
-			phase,
-			model: resolution.model,
-			source: "phase"
-		}, "Resolved model");
-		return resolution;
-	}
-	/**
-	* Static factory that loads a routing config from a file with graceful fallback.
-	*
-	* If the config file does not exist (CONFIG_NOT_FOUND), emits a single warn
-	* log and returns a resolver in fallback mode where all resolveModel() calls
-	* return null. Other errors are rethrown.
-	*
-	* @param filePath - Path to the substrate.routing.yml file
-	* @param logger - Logger instance (recommend createLogger('routing:model-resolver'))
-	*/
-	static createWithFallback(filePath, logger$1) {
-		try {
-			const config = loadModelRoutingConfig(filePath);
-			return new RoutingResolver(config, logger$1);
-		} catch (err) {
-			if (err instanceof RoutingConfigError && err.code === "CONFIG_NOT_FOUND") {
-				logger$1.debug({
-					configPath: filePath,
-					component: "routing",
-					reason: "config not found"
-				}, `Model routing config not found at "${filePath}"; using fallback mode (all resolveModel calls will return null)`);
-				const fallbackConfig = {
-					version: 1,
-					phases: {},
-					baseline_model: ""
-				};
-				return new RoutingResolver(fallbackConfig, logger$1);
-			}
-			throw err;
-		}
-	}
-};
-
-//#endregion
-//#region src/modules/routing/routing-token-accumulator.ts
-/**
-* Accumulates per-dispatch routing decisions and agent token usage, then
-* flushes an aggregated `PhaseTokenBreakdown` to the StateStore at run end.
-*
-* Thread-safety: all methods are synchronous accumulators; `flush` is async
-* but should only be called once per run after all dispatches settle.
-*/
-var RoutingTokenAccumulator = class {
-	_config;
-	_stateStore;
-	_logger;
-	/** Maps dispatchId → { phase, model } registered from routing:model-selected events */
-	_dispatchMap = new Map();
-	/**
-	* Bucket key = `"${phase}::${model}"`.
-	* Separate entries per (phase, model) combination so mixed-model runs
-	* produce distinct rows in the breakdown.
-	*/
-	_buckets = new Map();
-	constructor(config, stateStore, logger$1) {
-		this._config = config;
-		this._stateStore = stateStore;
-		this._logger = logger$1;
-	}
-	/**
-	* Register the routing decision for a dispatch.
-	* A second event for the same `dispatchId` overwrites the prior entry (last-writer-wins).
-	*
-	* @param event - payload from `routing:model-selected`
-	*/
-	onRoutingSelected(event) {
-		this._dispatchMap.set(event.dispatchId, {
-			phase: event.phase,
-			model: event.model
-		});
-		this._logger.debug({
-			dispatchId: event.dispatchId,
-			phase: event.phase,
-			model: event.model
-		}, "routing:model-selected registered");
-	}
-	/**
-	* Attribute token usage to the phase bucket for this dispatch.
-	* Unknown `dispatchId` values are attributed to `phase: 'default', model: 'unknown'`.
-	*
-	* @param event - payload from `agent:completed` (must include inputTokens / outputTokens)
-	*/
-	onAgentCompleted(event) {
-		const mapping = this._dispatchMap.get(event.dispatchId);
-		const phase = mapping?.phase ?? "default";
-		const model = mapping?.model ?? "unknown";
-		this._upsertBucket(phase, model, event.inputTokens, event.outputTokens);
-		this._logger.debug({
-			dispatchId: event.dispatchId,
-			phase,
-			model,
-			inputTokens: event.inputTokens
-		}, "agent:completed attributed");
-	}
-	/**
-	* Construct the `PhaseTokenBreakdown` from the accumulated buckets and
-	* persist it to the StateStore via `setMetric`.
-	* Clears all in-memory state afterwards so a second call writes an empty entry.
-	*
-	* @param runId - the pipeline run ID used to scope the metric key
-	*/
-	async flush(runId) {
-		const entries = Array.from(this._buckets.values());
-		const breakdown = {
-			entries,
-			baselineModel: this._config.baseline_model,
-			runId
-		};
-		await this._stateStore.setMetric(runId, "phase_token_breakdown", breakdown);
-		this._logger.debug({
-			runId,
-			entryCount: entries.length
-		}, "Phase token breakdown flushed to StateStore");
-		this._dispatchMap.clear();
-		this._buckets.clear();
-	}
-	_upsertBucket(phase, model, inputTokens, outputTokens) {
-		const key = `${phase}::${model}`;
-		const existing = this._buckets.get(key);
-		if (existing) {
-			existing.inputTokens += inputTokens;
-			existing.outputTokens += outputTokens;
-			existing.dispatchCount += 1;
-		} else this._buckets.set(key, {
-			phase,
-			model,
-			inputTokens,
-			outputTokens,
-			dispatchCount: 1
-		});
-	}
-};
-
-//#endregion
-//#region src/modules/routing/routing-telemetry.ts
-/**
-* Emits `routing.model_resolved` OTEL spans via a TelemetryPersistence instance.
-*
-* Injected into the run command alongside RoutingResolver. When telemetry is
-* not configured, pass null to the run command; no spans are emitted.
-*/
-var RoutingTelemetry = class {
-	_telemetry;
-	_logger;
-	constructor(telemetry, logger$1) {
-		this._telemetry = telemetry;
-		this._logger = logger$1;
-	}
-	/**
-	* Emit a `routing.model_resolved` span for a single routing decision.
-	*
-	* @param attrs - span attributes including dispatchId, taskType, phase, model, source, latencyMs
-	*/
-	recordModelResolved(attrs) {
-		this._telemetry.recordSpan({
-			name: "routing.model_resolved",
-			attributes: attrs
-		});
-		this._logger.debug(attrs, "routing.model_resolved span emitted");
-	}
-};
-
-//#endregion
-//#region src/modules/routing/routing-recommender.ts
-/**
-* Ordered tier list: index 0 = cheapest / smallest, index N = most expensive / largest.
-* Tiers are determined by substring matching — e.g. 'claude-haiku-4-5' → tier 1.
-*/
-const TIER_KEYWORDS$1 = [
-	{
-		keyword: "haiku",
-		tier: 1
-	},
-	{
-		keyword: "sonnet",
-		tier: 2
-	},
-	{
-		keyword: "opus",
-		tier: 3
-	}
-];
-/** Minimum historical breakdowns required before any recommendations are generated. */
-const MIN_BREAKDOWNS = 3;
-/** Output ratio below this threshold triggers a downgrade recommendation. */
-const DOWNGRADE_THRESHOLD = .15;
-/** Output ratio above this threshold triggers an upgrade recommendation. */
-const UPGRADE_THRESHOLD = .4;
-/** Ordered list of model name fragments by tier (cheapest → most expensive). */
-const TIER_TO_MODEL_FRAGMENT = {
-	1: "haiku",
-	2: "sonnet",
-	3: "opus"
-};
-/**
-* Analyzes phase-level token breakdown history and produces routing
-* recommendations based on observed output ratios.
-*
-* This class is stateless: call `analyze()` with historical breakdowns to
-* get fresh recommendations each time.
-*/
-var RoutingRecommender = class {
-	_logger;
-	constructor(logger$1) {
-		this._logger = logger$1;
-	}
-	/**
-	* Determine the model tier (1=haiku, 2=sonnet, 3=opus) for a given model name.
-	* Defaults to tier 2 (sonnet) when no keyword matches.
-	*/
-	_getTier(model) {
-		const lower = model.toLowerCase();
-		for (const { keyword, tier } of TIER_KEYWORDS$1) if (lower.includes(keyword)) return tier;
-		return 2;
-	}
-	/**
-	* Get the canonical model keyword fragment for a given tier.
-	*/
-	_getTierKeyword(tier) {
-		return TIER_TO_MODEL_FRAGMENT[tier] ?? "sonnet";
-	}
-	/**
-	* Compute the output ratio for a set of phase token entries:
-	*   outputRatio = sum(outputTokens) / (sum(inputTokens) + sum(outputTokens))
-	*
-	* Returns 0.5 when the total token count is zero to avoid division by zero.
-	*/
-	_computeOutputRatio(entries) {
-		let totalInput = 0;
-		let totalOutput = 0;
-		for (const entry of entries) {
-			totalInput += entry.inputTokens;
-			totalOutput += entry.outputTokens;
-		}
-		const total = totalInput + totalOutput;
-		if (total === 0) return .5;
-		return totalOutput / total;
-	}
-	/**
-	* Analyze historical phase token breakdowns and produce routing recommendations.
-	*
-	* @param breakdowns - Historical PhaseTokenBreakdown records (one per pipeline run)
-	* @param config     - Current model routing configuration
-	* @returns RoutingAnalysis with recommendations and per-phase output ratios
-	*/
-	analyze(breakdowns, config) {
-		if (breakdowns.length < MIN_BREAKDOWNS) {
-			this._logger.debug({
-				dataPoints: breakdowns.length,
-				threshold: MIN_BREAKDOWNS,
-				reason: "insufficient_data"
-			}, "Insufficient data for routing analysis");
-			return {
-				recommendations: [],
-				analysisRuns: breakdowns.length,
-				insufficientData: true,
-				phaseOutputRatios: {}
-			};
-		}
-		const phaseEntries = {};
-		for (const breakdown of breakdowns) for (const entry of breakdown.entries) {
-			const phase = entry.phase;
-			if (phaseEntries[phase] === void 0) phaseEntries[phase] = [];
-			phaseEntries[phase].push(entry);
-		}
-		const phaseOutputRatios = {};
-		for (const [phase, entries] of Object.entries(phaseEntries)) phaseOutputRatios[phase] = this._computeOutputRatio(entries);
-		const recommendations = [];
-		const confidence = Math.min(breakdowns.length / 10, 1);
-		for (const [phase, outputRatio] of Object.entries(phaseOutputRatios)) {
-			const currentModel = config.phases[phase]?.model ?? config.baseline_model;
-			const currentTier = this._getTier(currentModel);
-			if (outputRatio < DOWNGRADE_THRESHOLD) {
-				const suggestedTier = currentTier - 1;
-				if (suggestedTier < 1) {
-					this._logger.debug({
-						phase,
-						currentTier
-					}, "Already at minimum tier — skipping downgrade");
-					continue;
-				}
-				const suggestedKeyword = this._getTierKeyword(suggestedTier);
-				const suggestedModel = this._substituteTierKeyword(currentModel, currentTier, suggestedKeyword);
-				const estimatedSavingsPct = (currentTier - suggestedTier) / currentTier * 50;
-				recommendations.push({
-					phase,
-					currentModel,
-					suggestedModel,
-					estimatedSavingsPct,
-					confidence,
-					dataPoints: breakdowns.length,
-					direction: "downgrade"
-				});
-				this._logger.debug({
-					phase,
-					currentModel,
-					suggestedModel,
-					outputRatio,
-					estimatedSavingsPct
-				}, "Downgrade recommendation generated");
-			} else if (outputRatio > UPGRADE_THRESHOLD) {
-				const suggestedTier = currentTier + 1;
-				if (suggestedTier > 3) {
-					this._logger.debug({
-						phase,
-						currentTier
-					}, "Already at maximum tier — skipping upgrade");
-					continue;
-				}
-				const suggestedKeyword = this._getTierKeyword(suggestedTier);
-				const suggestedModel = this._substituteTierKeyword(currentModel, currentTier, suggestedKeyword);
-				const estimatedSavingsPct = (currentTier - suggestedTier) / currentTier * 50;
-				recommendations.push({
-					phase,
-					currentModel,
-					suggestedModel,
-					estimatedSavingsPct,
-					confidence,
-					dataPoints: breakdowns.length,
-					direction: "upgrade"
-				});
-				this._logger.debug({
-					phase,
-					currentModel,
-					suggestedModel,
-					outputRatio,
-					estimatedSavingsPct
-				}, "Upgrade recommendation generated");
-			}
-		}
-		return {
-			recommendations,
-			analysisRuns: breakdowns.length,
-			insufficientData: false,
-			phaseOutputRatios
-		};
-	}
-	/**
-	* Replace the tier keyword in a model name string with a new keyword.
-	*
-	* e.g. ('claude-haiku-4-5', 1, 'sonnet') → 'claude-sonnet-4-5'
-	*
-	* If the current tier keyword is not found in the model name, returns
-	* a synthesised name like 'claude-sonnet' using the new keyword.
-	*/
-	_substituteTierKeyword(currentModel, currentTier, newKeyword) {
-		const currentKeyword = this._getTierKeyword(currentTier);
-		if (currentModel.toLowerCase().includes(currentKeyword)) return currentModel.replace(new RegExp(currentKeyword, "i"), newKeyword);
-		const dashIdx = currentModel.indexOf("-");
-		const prefix = dashIdx !== -1 ? currentModel.slice(0, dashIdx) : currentModel;
-		return `${prefix}-${newKeyword}`;
-	}
-};
-
-//#endregion
-//#region src/modules/routing/model-tier.ts
-/**
-* Shared model tier resolution utility.
-*
-* Determines whether a model string belongs to the haiku (1), sonnet (2),
-* or opus (3) tier based on substring matching against well-known keywords.
-*
-* Used by both RoutingRecommender and RoutingTuner to ensure consistent
-* tier comparisons — in particular the one-step guard in RoutingTuner.
-*/
-/** Ordered tier keywords: index 0 = cheapest, index N = most expensive. */
-const TIER_KEYWORDS = [
-	{
-		keyword: "haiku",
-		tier: 1
-	},
-	{
-		keyword: "sonnet",
-		tier: 2
-	},
-	{
-		keyword: "opus",
-		tier: 3
-	}
-];
-/**
-* Get the model tier for a given model name string.
-*
-* Returns:
-*  - 1  for haiku-tier models
-*  - 2  for sonnet-tier models (also the default when unrecognized)
-*  - 3  for opus-tier models
-*
-* Matching is case-insensitive substring search.
-*/
-function getModelTier(model) {
-	const lower = model.toLowerCase();
-	for (const { keyword, tier } of TIER_KEYWORDS) if (lower.includes(keyword)) return tier;
-	return 2;
-}
-
-//#endregion
-//#region src/modules/routing/routing-tuner.ts
-/** Minimum number of breakdowns required before auto-tuning is attempted. */
-const MIN_BREAKDOWNS_FOR_TUNING = 5;
-/** Key used to store the list of known run IDs in the StateStore. */
-const RUN_INDEX_KEY = "phase_token_breakdown_runs";
-/** Key used to store the tune log in the StateStore. */
-const TUNE_LOG_KEY = "routing_tune_log";
-/**
-* Auto-applies a single conservative model downgrade per invocation when
-* `config.auto_tune` is `true` and sufficient historical data is available.
-*
-* The tuner reads the current routing YAML config, applies the change in memory,
-* and writes it back to disk synchronously. It also appends a `TuneLogEntry`
-* to the StateStore for audit purposes, and emits a `routing:auto-tuned` event.
-*/
-var RoutingTuner = class {
-	_stateStore;
-	_recommender;
-	_eventEmitter;
-	_configPath;
-	_logger;
-	constructor(stateStore, recommender, eventEmitter, configPath, logger$1) {
-		this._stateStore = stateStore;
-		this._recommender = recommender;
-		this._eventEmitter = eventEmitter;
-		this._configPath = configPath;
-		this._logger = logger$1;
-	}
-	/**
-	* Called at the end of a pipeline run. When auto_tune is enabled and sufficient
-	* historical data exists, applies a single conservative model downgrade to the
-	* routing config YAML file.
-	*
-	* @param runId  - ID of the just-completed pipeline run
-	* @param config - Current model routing config (already loaded from disk)
-	*/
-	async maybeAutoTune(runId, config) {
-		if (config.auto_tune !== true) {
-			this._logger.debug({ runId }, "auto_tune_disabled — skipping RoutingTuner");
-			return;
-		}
-		await this._registerRunId(runId);
-		const breakdowns = await this._loadRecentBreakdowns(10);
-		if (breakdowns.length < MIN_BREAKDOWNS_FOR_TUNING) {
-			this._logger.debug({
-				runId,
-				available: breakdowns.length,
-				required: MIN_BREAKDOWNS_FOR_TUNING
-			}, "insufficient_data — not enough breakdowns for auto-tuning");
-			return;
-		}
-		const analysis = this._recommender.analyze(breakdowns, config);
-		if (analysis.insufficientData) {
-			this._logger.debug({ runId }, "Recommender returned insufficientData");
-			return;
-		}
-		const downgradeCandidates = analysis.recommendations.filter((rec) => {
-			if (rec.direction !== "downgrade") return false;
-			const tierDiff = Math.abs(getModelTier(rec.currentModel) - getModelTier(rec.suggestedModel));
-			return tierDiff === 1;
-		});
-		if (downgradeCandidates.length === 0) {
-			this._logger.debug({ runId }, "no_safe_recommendation");
-			return;
-		}
-		const topRec = downgradeCandidates.sort((a, b) => b.confidence - a.confidence)[0];
-		let rawContent;
-		try {
-			rawContent = readFileSync(this._configPath, "utf-8");
-		} catch (err) {
-			const msg = err instanceof Error ? err.message : String(err);
-			this._logger.warn({
-				err: msg,
-				configPath: this._configPath
-			}, "Failed to read routing config for auto-tune");
-			return;
-		}
-		let rawObject;
-		try {
-			rawObject = load(rawContent);
-		} catch (err) {
-			const msg = err instanceof Error ? err.message : String(err);
-			this._logger.warn({ err: msg }, "Failed to parse routing config YAML for auto-tune");
-			return;
-		}
-		const configObj = rawObject;
-		if (configObj.phases === void 0) configObj.phases = {};
-		const existingPhase = configObj.phases[topRec.phase];
-		if (existingPhase !== void 0) existingPhase.model = topRec.suggestedModel;
-		else configObj.phases[topRec.phase] = { model: topRec.suggestedModel };
-		try {
-			writeFileSync(this._configPath, dump(rawObject, { lineWidth: 120 }), "utf-8");
-		} catch (err) {
-			const msg = err instanceof Error ? err.message : String(err);
-			this._logger.warn({
-				err: msg,
-				configPath: this._configPath
-			}, "Failed to write updated routing config");
-			return;
-		}
-		const tuneEntry = {
-			id: crypto.randomUUID(),
-			runId,
-			phase: topRec.phase,
-			oldModel: topRec.currentModel,
-			newModel: topRec.suggestedModel,
-			estimatedSavingsPct: topRec.estimatedSavingsPct,
-			appliedAt: new Date().toISOString()
-		};
-		await this._appendTuneLog(tuneEntry);
-		this._eventEmitter.emit("routing:auto-tuned", {
-			runId,
-			phase: topRec.phase,
-			oldModel: topRec.currentModel,
-			newModel: topRec.suggestedModel,
-			estimatedSavingsPct: topRec.estimatedSavingsPct
-		});
-		this._logger.info({
-			runId,
-			phase: topRec.phase,
-			oldModel: topRec.currentModel,
-			newModel: topRec.suggestedModel
-		}, "Auto-tuned routing config — applied downgrade");
-	}
-	/**
-	* Register a run ID in the stored run index so future calls can discover
-	* all historical breakdowns without a separate run listing endpoint.
-	*/
-	async _registerRunId(runId) {
-		const existing = await this._stateStore.getMetric("__global__", RUN_INDEX_KEY);
-		const runIds = Array.isArray(existing) ? existing : [];
-		if (!runIds.includes(runId)) {
-			runIds.push(runId);
-			await this._stateStore.setMetric("__global__", RUN_INDEX_KEY, runIds);
-		}
-	}
-	/**
-	* Load the most recent `lookback` PhaseTokenBreakdown records from the StateStore.
-	*
-	* Each breakdown is stored by RoutingTokenAccumulator under the key
-	* `'phase_token_breakdown'` scoped to the run ID. The run IDs themselves are
-	* tracked in a global index stored under `('__global__', RUN_INDEX_KEY)`.
-	*
-	* @param lookback - Maximum number of recent runs to inspect
-	*/
-	async _loadRecentBreakdowns(lookback) {
-		const existing = await this._stateStore.getMetric("__global__", RUN_INDEX_KEY);
-		const allRunIds = Array.isArray(existing) ? existing : [];
-		const recentRunIds = allRunIds.slice(-lookback);
-		const breakdowns = [];
-		for (const runId of recentRunIds) try {
-			const raw = await this._stateStore.getMetric(runId, "phase_token_breakdown");
-			if (raw !== void 0 && raw !== null) {
-				const parsed = typeof raw === "string" ? JSON.parse(raw) : raw;
-				breakdowns.push(parsed);
-			}
-		} catch (err) {
-			const msg = err instanceof Error ? err.message : String(err);
-			this._logger.debug({
-				runId,
-				err: msg
-			}, "Failed to load breakdown for run — skipping");
-		}
-		return breakdowns;
-	}
-	/**
-	* Append a TuneLogEntry to the persisted tune log in the StateStore.
-	*
-	* NOTE: This uses `'__global__'` as the scope key (codebase convention) rather
-	* than the literal `'global'` mentioned in AC6. The tune log is stored as a raw
-	* array (not a JSON-stringified string) for internal consistency with how other
-	* array values are stored in this StateStore. Story 28-9's
-	* `substrate routing --history` command MUST use the same `'__global__'` scope
-	* key and `'routing_tune_log'` metric key when reading this log.
-	*/
-	async _appendTuneLog(entry) {
-		const existing = await this._stateStore.getMetric("__global__", TUNE_LOG_KEY);
-		const log = Array.isArray(existing) ? existing : [];
-		log.push(entry);
-		await this._stateStore.setMetric("__global__", TUNE_LOG_KEY, log);
-	}
-};
-
-//#endregion
-export { ModelRoutingConfigSchema, ProviderPolicySchema, RoutingConfigError, RoutingRecommender, RoutingResolver, RoutingTelemetry, RoutingTokenAccumulator, RoutingTuner, TASK_TYPE_PHASE_MAP, getModelTier, loadModelRoutingConfig };
-//# sourceMappingURL=routing-BVrxrM6v.js.map