@substrate-ai/core 0.19.54

package/dist/routing/routing-telemetry.js

@@ -0,0 +1,39 @@
+/**
+ * RoutingTelemetry — emits OTEL spans for model routing decisions.
+ *
+ * Call `recordModelResolved()` immediately after `RoutingResolver.resolveModel()`
+ * returns a non-null result to capture per-dispatch routing latency and metadata.
+ *
+ * References:
+ *  - Epic 28, Story 28-6: Routing Telemetry — Per-Phase Token Tracking and OTEL Spans
+ */
+// ---------------------------------------------------------------------------
+// RoutingTelemetry
+// ---------------------------------------------------------------------------
+/**
+ * Emits `routing.model_resolved` OTEL spans via an IRoutingTelemetryPersistence instance.
+ *
+ * Injected into the run command alongside RoutingResolver. When telemetry is
+ * not configured, pass null to the run command; no spans are emitted.
+ */
+export class RoutingTelemetry {
+    _telemetry;
+    _logger;
+    constructor(telemetry, logger) {
+        this._telemetry = telemetry;
+        this._logger = logger;
+    }
+    /**
+     * 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');
+    }
+}
+//# sourceMappingURL=routing-telemetry.js.map

package/dist/routing/routing-telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-telemetry.js","sourceRoot":"","sources":["../../src/routing/routing-telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,OAAO,gBAAgB;IACV,UAAU,CAA8B;IACxC,OAAO,CAAS;IAEjC,YAAY,SAAuC,EAAE,MAAe;QAClE,IAAI,CAAC,UAAU,GAAG,SAAS,CAAA;QAC3B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;IACvB,CAAC;IAED;;;;OAIG;IACH,mBAAmB,CAAC,KAOnB;QACC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;YACzB,IAAI,EAAE,wBAAwB;YAC9B,UAAU,EAAE,KAAK;SAClB,CAAC,CAAA;QACF,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,qCAAqC,CAAC,CAAA;IAClE,CAAC;CACF"}

package/dist/routing/routing-token-accumulator.d.ts

@@ -0,0 +1,68 @@
+/**
+ * RoutingTokenAccumulator — collects per-dispatch routing metadata and
+ * attributes agent token usage to pipeline phase buckets.
+ *
+ * Usage:
+ *  1. Subscribe `onRoutingSelected` to `routing:model-selected` events.
+ *  2. Subscribe `onAgentCompleted` to `agent:completed` events.
+ *  3. Call `flush(runId)` at pipeline completion to persist the breakdown.
+ *
+ * References:
+ *  - Epic 28, Story 28-6: Routing Telemetry — Per-Phase Token Tracking and OTEL Spans
+ */
+import type { ILogger } from '../dispatch/types.js';
+import type { ModelRoutingConfig } from './model-routing-config.js';
+import type { IStateStore } from './types.js';
+/**
+ * Accumulates per-dispatch routing decisions and agent token usage, then
+ * flushes an aggregated `PhaseTokenBreakdown` to the IStateStore 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.
+ */
+export declare class RoutingTokenAccumulator {
+    private readonly _config;
+    private readonly _stateStore;
+    private readonly _logger;
+    /** Maps dispatchId → { phase, model } registered from routing:model-selected events */
+    private readonly _dispatchMap;
+    /**
+     * Bucket key = `"${phase}::${model}"`.
+     * Separate entries per (phase, model) combination so mixed-model runs
+     * produce distinct rows in the breakdown.
+     */
+    private readonly _buckets;
+    constructor(config: ModelRoutingConfig, stateStore: IStateStore, logger: ILogger);
+    /**
+     * 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: {
+        dispatchId: string;
+        phase: string;
+        model: string;
+    }): void;
+    /**
+     * 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: {
+        dispatchId: string;
+        inputTokens: number;
+        outputTokens: number;
+    }): void;
+    /**
+     * Construct the `PhaseTokenBreakdown` from the accumulated buckets and
+     * persist it to the IStateStore 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
+     */
+    flush(runId: string): Promise<void>;
+    private _upsertBucket;
+}
+//# sourceMappingURL=routing-token-accumulator.d.ts.map

package/dist/routing/routing-token-accumulator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-token-accumulator.d.ts","sourceRoot":"","sources":["../../src/routing/routing-token-accumulator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AACnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AACnE,OAAO,KAAK,EAAE,WAAW,EAAwC,MAAM,YAAY,CAAA;AAMnF;;;;;;GAMG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,uFAAuF;IACvF,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA2D;IAExF;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0C;gBAEvD,MAAM,EAAE,kBAAkB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO;IAUhF;;;;;OAKG;IACH,iBAAiB,CAAC,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAQpF;;;;;OAKG;IACH,gBAAgB,CAAC,KAAK,EAAE;QACtB,UAAU,EAAE,MAAM,CAAA;QAClB,WAAW,EAAE,MAAM,CAAA;QACnB,YAAY,EAAE,MAAM,CAAA;KACrB,GAAG,IAAI;IAeR;;;;;;OAMG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBzC,OAAO,CAAC,aAAa;CAsBtB"}

package/dist/routing/routing-token-accumulator.js

@@ -0,0 +1,111 @@
+/**
+ * RoutingTokenAccumulator — collects per-dispatch routing metadata and
+ * attributes agent token usage to pipeline phase buckets.
+ *
+ * Usage:
+ *  1. Subscribe `onRoutingSelected` to `routing:model-selected` events.
+ *  2. Subscribe `onAgentCompleted` to `agent:completed` events.
+ *  3. Call `flush(runId)` at pipeline completion to persist the breakdown.
+ *
+ * References:
+ *  - Epic 28, Story 28-6: Routing Telemetry — Per-Phase Token Tracking and OTEL Spans
+ */
+// ---------------------------------------------------------------------------
+// RoutingTokenAccumulator
+// ---------------------------------------------------------------------------
+/**
+ * Accumulates per-dispatch routing decisions and agent token usage, then
+ * flushes an aggregated `PhaseTokenBreakdown` to the IStateStore 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.
+ */
+export class RoutingTokenAccumulator {
+    _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) {
+        this._config = config;
+        this._stateStore = stateStore;
+        this._logger = logger;
+    }
+    // ---------------------------------------------------------------------------
+    // Event handlers
+    // ---------------------------------------------------------------------------
+    /**
+     * 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');
+    }
+    // ---------------------------------------------------------------------------
+    // Flush
+    // ---------------------------------------------------------------------------
+    /**
+     * Construct the `PhaseTokenBreakdown` from the accumulated buckets and
+     * persist it to the IStateStore 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');
+        // Clear in-memory state — a subsequent flush() will write an empty breakdown.
+        this._dispatchMap.clear();
+        this._buckets.clear();
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    _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: phase,
+                model,
+                inputTokens,
+                outputTokens,
+                dispatchCount: 1,
+            });
+        }
+    }
+}
+//# sourceMappingURL=routing-token-accumulator.js.map

package/dist/routing/routing-token-accumulator.js.map

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

package/dist/routing/routing-tuner.d.ts

@@ -0,0 +1,69 @@
+/**
+ * RoutingTuner — automatically applies conservative model downgrades based on
+ * historical phase token breakdown data.
+ *
+ * When `config.auto_tune` is true and enough historical data exists, RoutingTuner
+ * selects the highest-confidence downgrade recommendation, updates the YAML config
+ * file in place, and appends an audit log entry to the IStateStore.
+ *
+ * At most one phase is changed per invocation.
+ *
+ * References:
+ *  - Epic 28, Story 28-8: Feedback Loop — Telemetry-Driven Routing Tuning
+ */
+import type { ILogger } from '../dispatch/types.js';
+import type { TypedEventBus } from '../events/event-bus.js';
+import type { CoreEvents } from '../events/core-events.js';
+import type { ModelRoutingConfig } from './model-routing-config.js';
+import type { IStateStore } from './types.js';
+import { RoutingRecommender } from './routing-recommender.js';
+/**
+ * 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 IStateStore for audit purposes, and emits a `routing:auto-tuned` event.
+ */
+export declare class RoutingTuner {
+    private readonly _stateStore;
+    private readonly _recommender;
+    private readonly _eventEmitter;
+    private readonly _configPath;
+    private readonly _logger;
+    constructor(stateStore: IStateStore, recommender: RoutingRecommender, eventEmitter: TypedEventBus<CoreEvents>, configPath: string, logger: ILogger);
+    /**
+     * 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)
+     */
+    maybeAutoTune(runId: string, config: ModelRoutingConfig): Promise<void>;
+    /**
+     * Register a run ID in the stored run index so future calls can discover
+     * all historical breakdowns without a separate run listing endpoint.
+     */
+    private _registerRunId;
+    /**
+     * Load the most recent `lookback` PhaseTokenBreakdown records from the IStateStore.
+     *
+     * 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
+     */
+    private _loadRecentBreakdowns;
+    /**
+     * Append a TuneLogEntry to the persisted tune log in the IStateStore.
+     *
+     * 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 IStateStore.
+     */
+    private _appendTuneLog;
+}
+//# sourceMappingURL=routing-tuner.d.ts.map

package/dist/routing/routing-tuner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-tuner.d.ts","sourceRoot":"","sources":["../../src/routing/routing-tuner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAC1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AACnE,OAAO,KAAK,EAAE,WAAW,EAAqC,MAAM,YAAY,CAAA;AAChF,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAoB7D;;;;;;;GAOG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoB;IACjD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2B;IACzD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAG/B,UAAU,EAAE,WAAW,EACvB,WAAW,EAAE,kBAAkB,EAC/B,YAAY,EAAE,aAAa,CAAC,UAAU,CAAC,EACvC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,OAAO;IAajB;;;;;;;OAOG;IACG,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsH7E;;;OAGG;YACW,cAAc;IAS5B;;;;;;;;OAQG;YACW,qBAAqB;IA0BnC;;;;;;;OAOG;YACW,cAAc;CAM7B"}

package/dist/routing/routing-tuner.js

@@ -0,0 +1,217 @@
+/**
+ * RoutingTuner — automatically applies conservative model downgrades based on
+ * historical phase token breakdown data.
+ *
+ * When `config.auto_tune` is true and enough historical data exists, RoutingTuner
+ * selects the highest-confidence downgrade recommendation, updates the YAML config
+ * file in place, and appends an audit log entry to the IStateStore.
+ *
+ * At most one phase is changed per invocation.
+ *
+ * References:
+ *  - Epic 28, Story 28-8: Feedback Loop — Telemetry-Driven Routing Tuning
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { load as yamlLoad, dump as yamlDump } from 'js-yaml';
+import { getModelTier } from './model-tier.js';
+// ---------------------------------------------------------------------------
+// Internal constants
+// ---------------------------------------------------------------------------
+/** 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 IStateStore. */
+const RUN_INDEX_KEY = 'phase_token_breakdown_runs';
+/** Key used to store the tune log in the IStateStore. */
+const TUNE_LOG_KEY = 'routing_tune_log';
+// ---------------------------------------------------------------------------
+// RoutingTuner
+// ---------------------------------------------------------------------------
+/**
+ * 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 IStateStore for audit purposes, and emits a `routing:auto-tuned` event.
+ */
+export class RoutingTuner {
+    _stateStore;
+    _recommender;
+    _eventEmitter;
+    _configPath;
+    _logger;
+    constructor(stateStore, recommender, eventEmitter, configPath, logger) {
+        this._stateStore = stateStore;
+        this._recommender = recommender;
+        this._eventEmitter = eventEmitter;
+        this._configPath = configPath;
+        this._logger = logger;
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /**
+     * 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;
+        }
+        // Register the current run in the run index
+        await this._registerRunId(runId);
+        // Load recent breakdowns
+        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;
+        }
+        // Compute recommendations
+        const analysis = this._recommender.analyze(breakdowns, config);
+        if (analysis.insufficientData) {
+            this._logger.debug({ runId }, 'Recommender returned insufficientData');
+            return;
+        }
+        // Filter to downgrade-only, one-step transitions (|currentTier - suggestedTier| === 1).
+        // The one-step check uses getModelTier() to prevent opus→haiku two-step jumps even
+        // if a recommender were to emit such a recommendation.
+        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;
+        }
+        // Pick the highest-confidence candidate
+        const topRec = downgradeCandidates.sort((a, b) => b.confidence - a.confidence)[0];
+        // Apply the change to the YAML config
+        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 = yamlLoad(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;
+        }
+        // Mutate the phase model
+        const configObj = rawObject;
+        if (configObj.phases === undefined) {
+            configObj.phases = {};
+        }
+        const existingPhase = configObj.phases[topRec.phase];
+        if (existingPhase !== undefined) {
+            existingPhase.model = topRec.suggestedModel;
+        }
+        else {
+            configObj.phases[topRec.phase] = { model: topRec.suggestedModel };
+        }
+        // Write the updated config back to disk
+        try {
+            writeFileSync(this._configPath, yamlDump(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;
+        }
+        // Append audit log entry
+        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);
+        // Emit event
+        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');
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * 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 IStateStore.
+     *
+     * 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 : [];
+        // Take the most recent `lookback` run IDs
+        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 !== undefined && raw !== null) {
+                    // The value may be stored as an object or as a JSON string
+                    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 IStateStore.
+     *
+     * 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 IStateStore.
+     */
+    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);
+    }
+}
+//# sourceMappingURL=routing-tuner.js.map

package/dist/routing/routing-tuner.js.map

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