pi-smart-router 0.1.0

package/dist/domain/pipeline/router-pipeline.js

@@ -0,0 +1,807 @@
+/**
+ * Pipeline stage orchestrator — FR-001, FR-006, FR-022.
+ *
+ * Runs stages sequentially with early-exit on decision.
+ * Documented order (SP-119, #69):
+ *   hardware_probe → loop_escalation → turn_envelope → context_fit → low_intensity
+ *   → session_pin → triage → local_zero → triage_cloud_fallback → hydra_match
+ *   → safe_default → context_overflow_fallback
+ * Any stage failure falls back to safeCloudDefault(); never throws to host.
+ */
+import { probeHardware } from '../../infrastructure/hardware/hardware-probe.js';
+import { pingLocalServices } from '../../infrastructure/local/local-zero-tier.js';
+import { triage as triageClassify } from '../triage/triage-engine.js';
+import { classifyTurnEnvelope } from '../triage/turn-envelope.js';
+import { safeCloudDefault } from './safe-default.js';
+import { hasToolCallHistory, isGoogleGeminiProfile, } from '../routing/tool-history-guard.js';
+import { filterFleetByContextFit, needsContextOverflowFallback, resolveContextOverflowFallback, CONTEXT_OVERFLOW_NO_FIT, } from '../routing/context-fit.js';
+import { evaluateLoopEscalation } from '../pinning/loop-escalation.js';
+import { selectLowestCostModel } from '../pinning/sub-route-policy.js';
+import { estimateRoutingCost, enrichRoutingDecisionWithContextFit, enrichRoutingDecisionWithTierSelection, } from '../../infrastructure/telemetry/routing-telemetry.js';
+import { clusterReasonCode } from '../../config/routing-clusters-loader.js';
+import { DEFAULT_OPERATOR_CONFIG } from '../../config/defaults.js';
+import { buildTierFeatures, scoreLowIntensity, } from '../routing/tier-features.js';
+import { predictPSuccessCheapTimed, resolvePSuccessWeights, tierFeaturesToPSuccessFeatures, } from '../routing/p-success-classifier.js';
+import { selectTierByExpectedCost, } from '../routing/expected-cost.js';
+/** Canonical pipeline stage order — keep README/specs in sync (SP-119). */
+export const PIPELINE_STAGE_ORDER = [
+    'hardware_probe',
+    'loop_escalation',
+    'turn_envelope',
+    'context_fit',
+    'low_intensity',
+    'session_pin',
+    'triage',
+    'local_zero',
+    'triage_cloud_fallback',
+    'hydra_match',
+    'safe_default',
+    'context_overflow_fallback',
+];
+/**
+ * Disjunction: triage trivial OR low-intensity zero-tier hint (high confidence)
+ * OR high-confidence zero-tier cluster match.
+ */
+export function resolveLocalEligible(input) {
+    const clusterZeroTier = input.clusterMatch?.confidence === 'high' &&
+        input.clusterMatch.tierBias === 'zero-tier';
+    const lowIntensityZeroTier = input.tierHint === 'zero-tier' &&
+        input.lowIntensityScore !== null &&
+        input.lowIntensityScore >= input.highThreshold;
+    const triageTrivial = input.triageVerdict === 'trivial';
+    if (!triageTrivial && !lowIntensityZeroTier && !clusterZeroTier) {
+        return { eligible: false, reason: null };
+    }
+    if (triageTrivial) {
+        return { eligible: true, reason: 'triage_trivial' };
+    }
+    if (clusterZeroTier) {
+        return {
+            eligible: true,
+            reason: clusterReasonCode(input.clusterMatch.clusterId),
+        };
+    }
+    return { eligible: true, reason: 'low_intensity_structural' };
+}
+// ─── Orchestrator ────────────────────────────────────────────────────────────
+export class RouterPipeline {
+    stages;
+    fleet;
+    options;
+    /** Per-route transient fleet — defaults to constructor fleet. */
+    activeFleet = [];
+    /** Unfiltered fleet for overflow escalation (SP-095). */
+    fullFleet = [];
+    /** Per-route transient state — reset on each route() call. */
+    currentHardwareResult = 'disabled';
+    currentTriageResult = null;
+    currentHydraResult = null;
+    currentClusterMatch = null;
+    currentTierHint = null;
+    currentTierHintReasonCode = null;
+    currentLowIntensityScore = null;
+    currentPSuccessCheap = null;
+    currentPSuccessAlpha = null;
+    currentExpectedCostByTier = null;
+    currentLocalEligibleReason = null;
+    pSuccessWeightsLoaded = false;
+    cachedPSuccessWeights = null;
+    currentContextFitRejected = [];
+    currentContextFitViableCount = 0;
+    contextOverflowPreferredProvider = null;
+    contextOverflowTriggered = false;
+    constructor(fleet, options) {
+        this.fleet = fleet;
+        this.options = options ?? {};
+        this.stages = [
+            { name: 'hardware_probe', run: this.hardwareProbeStage.bind(this) },
+            { name: 'loop_escalation', run: this.loopEscalation.bind(this) },
+            { name: 'turn_envelope', run: this.turnEnvelope.bind(this) },
+            { name: 'context_fit', run: this.contextFitStage.bind(this) },
+            { name: 'low_intensity', run: this.lowIntensityGate.bind(this) },
+            { name: 'session_pin', run: this.sessionPin.bind(this) },
+            { name: 'triage', run: this.triage.bind(this) },
+            { name: 'local_zero', run: this.localZeroTierStage.bind(this) },
+            { name: 'triage_cloud_fallback', run: this.triageCloudFallback.bind(this) },
+            { name: 'hydra_match', run: this.hydraMatcher.bind(this) },
+            { name: 'safe_default', run: this.safeDefaultStage.bind(this) },
+            { name: 'context_overflow_fallback', run: this.contextOverflowFallback.bind(this) },
+        ];
+    }
+    async route(request, fleetOverride) {
+        const start = Date.now();
+        this.activeFleet = this.prioritizeFleetForToolHistory(fleetOverride ?? this.fleet, request);
+        this.fullFleet = this.activeFleet;
+        this.currentHardwareResult = 'disabled';
+        this.currentTriageResult = null;
+        this.currentHydraResult = null;
+        this.currentClusterMatch = null;
+        this.currentTierHint = null;
+        this.currentTierHintReasonCode = null;
+        this.currentLowIntensityScore = null;
+        this.currentPSuccessCheap = null;
+        this.currentPSuccessAlpha = null;
+        this.currentExpectedCostByTier = null;
+        this.currentLocalEligibleReason = null;
+        this.currentContextFitRejected = [];
+        this.currentContextFitViableCount = 0;
+        this.contextOverflowPreferredProvider = null;
+        this.contextOverflowTriggered = false;
+        let currentStage;
+        try {
+            for (const stage of this.stages) {
+                currentStage = stage;
+                const result = await stage.run(request);
+                if (result.decided && result.decision) {
+                    this.persistPinIfNeeded(request, result.decision);
+                    this.emitTelemetry(request, result.decision);
+                    return this.attachFeatures(request, result.decision);
+                }
+            }
+        }
+        catch (error) {
+            // Constitution VI: zero-crash resilience — degrade to safe default
+            const failedStage = this.resolveFailedStage(currentStage);
+            const elapsedMs = Date.now() - start;
+            const fallback = this.buildFallbackDecision(request, elapsedMs);
+            this.logPipelineError(request, failedStage, error);
+            this.emitPipelineErrorTelemetry(request, failedStage, fallback);
+            this.persistPinIfNeeded(request, fallback);
+            return this.attachFeatures(request, fallback);
+        }
+        const fallback = this.buildFallbackDecision(request, Date.now() - start);
+        this.persistPinIfNeeded(request, fallback);
+        this.emitTelemetry(request, fallback);
+        return this.attachFeatures(request, fallback);
+    }
+    /**
+     * SP-080: move Google/Gemini profiles to the end of the fleet when prior tool
+     * calls exist so tier `.find()` passes prefer non-Gemini models first.
+     * Honors `force_model_id` by leaving fleet order unchanged.
+     */
+    prioritizeFleetForToolHistory(fleet, request) {
+        if (request.force_model_id) {
+            return fleet;
+        }
+        const messages = request.messages;
+        if (!messages || messages.length === 0 || !hasToolCallHistory(messages)) {
+            return fleet;
+        }
+        const preferred = [];
+        const deprioritized = [];
+        for (const profile of fleet) {
+            if (isGoogleGeminiProfile(profile)) {
+                deprioritized.push(profile);
+            }
+            else {
+                preferred.push(profile);
+            }
+        }
+        if (deprioritized.length === 0) {
+            return fleet;
+        }
+        return [...preferred, ...deprioritized];
+    }
+    /** Attach privacy-safe dataset features captured during pipeline stages (SP-057, SP-119). */
+    attachFeatures(request, decision) {
+        const features = {
+            triage: this.currentTriageResult
+                ? {
+                    verdict: this.currentTriageResult.verdict,
+                    reason_code: this.currentTriageResult.reason_code,
+                    cyclomatic_score: this.currentTriageResult.cyclomatic_score,
+                }
+                : null,
+            requirements: this.currentHydraResult?.requirements ?? null,
+            candidates: this.mergeFeatureCandidates(),
+            tier_hint: this.currentTierHint,
+            tier_hint_reason_code: this.currentTierHintReasonCode,
+            low_intensity_score: this.currentLowIntensityScore,
+            p_success_cheap: this.currentPSuccessCheap,
+            p_success_alpha: this.currentPSuccessAlpha,
+            local_eligible_reason: this.currentLocalEligibleReason,
+        };
+        const withBaseFeatures = { ...decision, features };
+        const withContextFit = enrichRoutingDecisionWithContextFit(request, withBaseFeatures, this.fullFleet, this.options.contextFitConfig);
+        return enrichRoutingDecisionWithTierSelection(withContextFit);
+    }
+    mergeFeatureCandidates() {
+        const hydraCandidates = this.currentHydraResult?.candidates ?? [];
+        const expectedCostCandidates = this.currentExpectedCostByTier?.map((entry) => ({
+            model_id: `__expected_cost_${entry.tier}__`,
+            score: entry.expectedCostUsd,
+            shortfall: entry.adjustedExpectedCostUsd,
+            rejected_reason: `p_success=${entry.pSuccess.toFixed(4)}`,
+        })) ?? [];
+        if (this.currentContextFitRejected.length === 0 &&
+            hydraCandidates.length === 0 &&
+            expectedCostCandidates.length === 0) {
+            return null;
+        }
+        return [
+            ...this.currentContextFitRejected,
+            ...expectedCostCandidates,
+            ...hydraCandidates,
+        ];
+    }
+    resolveFailedStage(stage) {
+        return stage?.name ?? 'unknown';
+    }
+    logPipelineError(request, stage, error) {
+        console.warn('Router pipeline stage failed; degrading to safe default', {
+            stage,
+            request_id: request.request_id,
+            session_id: request.session_id,
+            error: this.redactPromptFromError(error, request.prompt_text),
+        });
+    }
+    redactPromptFromError(error, promptText) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!promptText || !message.includes(promptText)) {
+            return message;
+        }
+        return message.replaceAll(promptText, '[REDACTED]');
+    }
+    emitPipelineErrorTelemetry(request, failedStage, fallback) {
+        this.options.telemetryEmitter?.emitPipelineError(request, failedStage, fallback);
+    }
+    /** Step 7: emit routing telemetry after decision (T040). */
+    emitTelemetry(request, decision) {
+        this.options.telemetryEmitter?.emit(request, decision);
+    }
+    withEstimatedCost(request, model, decision) {
+        return {
+            ...decision,
+            estimated_cost_usd: estimateRoutingCost(model, request, this.options.priceCatalog ?? null),
+        };
+    }
+    buildFallbackDecision(request, elapsedMs) {
+        if (this.shouldAttemptContextOverflowFallback(request)) {
+            return this.buildContextOverflowFallbackDecision(request, elapsedMs);
+        }
+        const fallbackModel = safeCloudDefault(this.activeFleet, {
+            request,
+            ...(this.options.contextFitConfig !== undefined
+                ? { contextFitConfig: this.options.contextFitConfig }
+                : {}),
+        });
+        const modelId = fallbackModel?.id ?? 'unknown';
+        const tier = fallbackModel?.tier ?? 'economical-cloud';
+        return {
+            request_id: request.request_id,
+            selected_model_id: modelId,
+            tier,
+            stage: 'fallback',
+            reason_code: 'safe_cloud_default',
+            routing_latency_ms: elapsedMs,
+            pin_reason: null,
+        };
+    }
+    shouldAttemptContextOverflowFallback(request) {
+        if (request.force_model_id) {
+            return false;
+        }
+        if (this.contextOverflowTriggered) {
+            return true;
+        }
+        return needsContextOverflowFallback(this.activeFleet, this.currentContextFitRejected, this.fullFleet);
+    }
+    buildContextOverflowFallbackDecision(request, elapsedMs) {
+        const overflow = resolveContextOverflowFallback(this.fullFleet, request, this.contextOverflowPreferredProvider, this.options.contextFitConfig);
+        if (overflow.kind === 'no_fit') {
+            return {
+                request_id: request.request_id,
+                selected_model_id: 'unknown',
+                tier: 'economical-cloud',
+                stage: 'fallback',
+                reason_code: CONTEXT_OVERFLOW_NO_FIT,
+                candidates: this.currentContextFitRejected,
+                routing_latency_ms: elapsedMs,
+                pin_reason: null,
+            };
+        }
+        const model = overflow.model;
+        return this.withEstimatedCost(request, model, {
+            request_id: request.request_id,
+            selected_model_id: model.id,
+            tier: model.tier,
+            stage: 'fallback',
+            reason_code: overflow.reasonCode,
+            candidates: this.currentContextFitRejected,
+            routing_latency_ms: elapsedMs,
+            pin_reason: null,
+        });
+    }
+    /**
+     * SP-095: after safe_default, escalate to largest-fit model when economical
+     * models cannot fit the current context.
+     */
+    async contextOverflowFallback(request) {
+        if (!this.shouldAttemptContextOverflowFallback(request)) {
+            return { decided: false, stage: 'context_overflow_fallback' };
+        }
+        const elapsedMs = 0;
+        const decision = this.buildContextOverflowFallbackDecision(request, elapsedMs);
+        return {
+            decided: true,
+            stage: 'context_overflow_fallback',
+            decision,
+        };
+    }
+    /**
+     * SP-022: economical-cloud default when no earlier stage decides.
+     * Defers to context_overflow_fallback when economical models were context-rejected.
+     */
+    async safeDefaultStage(request) {
+        if (this.shouldAttemptContextOverflowFallback(request)) {
+            return { decided: false, stage: 'safe_default' };
+        }
+        const fallbackModel = safeCloudDefault(this.activeFleet, {
+            request,
+            ...(this.options.contextFitConfig !== undefined
+                ? { contextFitConfig: this.options.contextFitConfig }
+                : {}),
+        });
+        if (!fallbackModel) {
+            return { decided: false, stage: 'safe_default' };
+        }
+        return {
+            decided: true,
+            stage: 'fallback',
+            decision: {
+                request_id: request.request_id,
+                selected_model_id: fallbackModel.id,
+                tier: fallbackModel.tier,
+                stage: 'fallback',
+                reason_code: 'safe_cloud_default',
+                routing_latency_ms: 0,
+                pin_reason: null,
+            },
+        };
+    }
+    markContextOverflowFromPin(request, pinnedModelId) {
+        const pinnedModel = this.fullFleet.find((model) => model.id === pinnedModelId);
+        this.contextOverflowTriggered = true;
+        this.contextOverflowPreferredProvider = pinnedModel?.provider ?? null;
+    }
+    // ─── Implemented stages ─────────────────────────────────────────────────────
+    async hardwareProbeStage(request) {
+        void request;
+        if (!this.options.hardwareConfig || !this.options.systemInfoProvider) {
+            return { decided: false, stage: 'hardware_probe' };
+        }
+        const systemInfo = await this.options.systemInfoProvider();
+        this.currentHardwareResult = probeHardware(this.options.hardwareConfig, systemInfo);
+        return { decided: false, stage: 'hardware_probe' };
+    }
+    /**
+     * SP-093: filter fleet to models whose context window fits estimated input
+     * tokens before session pin and HyDRA matching.
+     */
+    async contextFitStage(request) {
+        const result = filterFleetByContextFit(this.activeFleet, request, this.options.contextFitConfig);
+        this.activeFleet = result.effectiveFleet;
+        this.currentContextFitRejected = result.rejected;
+        this.currentContextFitViableCount = result.effectiveFleet.length;
+        return { decided: false, stage: 'context_fit' };
+    }
+    /**
+     * SC-007: classification_only MUST NOT dispatch full local.
+     * Eligibility: triage trivial OR low-intensity zero-tier hint OR zero-tier cluster (SP-111).
+     */
+    async localZeroTierStage(request) {
+        const lowIntensityConfig = this.options.lowIntensityConfig ?? DEFAULT_OPERATOR_CONFIG.low_intensity;
+        const eligibility = resolveLocalEligible({
+            triageVerdict: this.currentTriageResult?.verdict ?? null,
+            tierHint: this.currentTierHint,
+            lowIntensityScore: this.currentLowIntensityScore,
+            highThreshold: lowIntensityConfig.high_threshold,
+            clusterMatch: this.currentClusterMatch,
+        });
+        if (!eligibility.eligible) {
+            return { decided: false, stage: 'local_zero' };
+        }
+        if (this.currentHardwareResult !== 'full_local') {
+            return { decided: false, stage: 'local_zero' };
+        }
+        const readiness = await pingLocalServices(this.options.localConfig, this.options.httpFetchPort);
+        if (!readiness.anyModelReady) {
+            return { decided: false, stage: 'local_zero' };
+        }
+        const localModel = this.activeFleet.find((m) => m.tier === 'zero-tier' && m.healthy !== false);
+        if (!localModel) {
+            return { decided: false, stage: 'local_zero' };
+        }
+        this.currentLocalEligibleReason = eligibility.reason;
+        return {
+            decided: true,
+            stage: 'local_zero',
+            decision: {
+                request_id: request.request_id,
+                selected_model_id: localModel.id,
+                tier: 'zero-tier',
+                stage: 'local_zero',
+                reason_code: 'local_model_ready',
+                routing_latency_ms: readiness.combinedLatencyMs,
+                pin_reason: null,
+            },
+        };
+    }
+    // ─── Triage stage (FR-003, SC-004 <5ms budget) ──────────────────────────────
+    async triage(request) {
+        const result = triageClassify(request.prompt_text);
+        this.currentTriageResult = result;
+        if (result.verdict === 'ambiguous') {
+            return { decided: false, stage: 'triage' };
+        }
+        // Trivial prompts defer cloud routing until after local zero-tier (PRD Step 4).
+        if (result.verdict === 'trivial') {
+            return { decided: false, stage: 'triage' };
+        }
+        const targetTier = 'frontier-cloud';
+        const model = this.activeFleet.find((m) => m.tier === targetTier && m.healthy !== false);
+        if (!model) {
+            return { decided: false, stage: 'triage' };
+        }
+        return {
+            decided: true,
+            stage: 'triage',
+            decision: {
+                request_id: request.request_id,
+                selected_model_id: model.id,
+                tier: targetTier,
+                stage: 'triage',
+                reason_code: result.reason_code,
+                routing_latency_ms: 0,
+                pin_reason: null,
+            },
+        };
+    }
+    /**
+     * Economical-cloud fallback for trivial prompts after local zero-tier is skipped
+     * or unavailable (PRD Step 4 cloud fallback).
+     */
+    async triageCloudFallback(request) {
+        if (this.currentTriageResult?.verdict !== 'trivial') {
+            return { decided: false, stage: 'triage' };
+        }
+        const model = this.activeFleet.find((m) => m.tier === 'economical-cloud' && m.healthy !== false);
+        if (!model) {
+            return { decided: false, stage: 'triage' };
+        }
+        return {
+            decided: true,
+            stage: 'triage',
+            decision: {
+                request_id: request.request_id,
+                selected_model_id: model.id,
+                tier: 'economical-cloud',
+                stage: 'triage',
+                reason_code: this.currentTriageResult.reason_code,
+                routing_latency_ms: 0,
+                pin_reason: null,
+            },
+        };
+    }
+    // ─── Session pin stage (FR-006, FR-007, FR-008) ──────────────────────────
+    async sessionPin(request) {
+        const pinner = this.options.sessionPinner;
+        if (!pinner) {
+            return { decided: false, stage: 'session_pin' };
+        }
+        const existingPin = pinner.getPin(request.session_id);
+        const result = pinner.lookupPin(request, this.activeFleet);
+        switch (result.action) {
+            case 'use_pin': {
+                const model = result.pinnedModel;
+                const pin = pinner.getPin(request.session_id);
+                return {
+                    decided: true,
+                    stage: 'session_pin',
+                    decision: this.withEstimatedCost(request, model, {
+                        request_id: request.request_id,
+                        selected_model_id: model.id,
+                        tier: model.tier,
+                        stage: 'session_pin',
+                        reason_code: 'session_pinned',
+                        routing_latency_ms: 0,
+                        pin_reason: pin?.pin_reason ?? null,
+                    }),
+                };
+            }
+            case 'sub_route': {
+                const model = result.subRouteModel;
+                const pin = pinner.getPin(request.session_id);
+                return {
+                    decided: true,
+                    stage: 'session_pin',
+                    decision: this.withEstimatedCost(request, model, {
+                        request_id: request.request_id,
+                        selected_model_id: model.id,
+                        tier: model.tier,
+                        stage: 'session_pin',
+                        reason_code: 'tool_result_sub_route',
+                        routing_latency_ms: 0,
+                        pin_reason: pin?.pin_reason ?? null,
+                    }),
+                };
+            }
+            case 'break':
+                if (result.breakReason === 'context_overflow' && existingPin) {
+                    this.markContextOverflowFromPin(request, existingPin.pinned_model_id);
+                }
+                return { decided: false, stage: 'session_pin' };
+            case 'no_pin':
+                if (existingPin) {
+                    const wasContextRejected = this.currentContextFitRejected.some((candidate) => candidate.model_id === existingPin.pinned_model_id);
+                    if (wasContextRejected) {
+                        this.markContextOverflowFromPin(request, existingPin.pinned_model_id);
+                    }
+                }
+                return { decided: false, stage: 'session_pin' };
+            default:
+                return { decided: false, stage: 'session_pin' };
+        }
+    }
+    /**
+     * After a routing decision, persist an initial pin when none exists.
+     * Sub-routes and already-pinned decisions skip persistence.
+     */
+    persistPinIfNeeded(request, decision) {
+        const pinner = this.options.sessionPinner;
+        if (!pinner)
+            return;
+        if (decision.reason_code === 'tool_result_sub_route')
+            return;
+        if (decision.reason_code === 'session_pinned')
+            return;
+        // Turn envelope is a per-turn tier bias — do not overwrite an existing pin (SP-064).
+        if (decision.stage === 'turn_envelope' && pinner.getPin(request.session_id))
+            return;
+        pinner.recordPin(request.session_id, decision.selected_model_id, 'initial');
+    }
+    // ─── Turn envelope stage (Step 2b, <2ms budget) ─────────────────────────
+    static TURN_TIER_MAP = {
+        planning: 'frontier-cloud',
+        tool_result: 'economical-cloud',
+        subagent: 'economical-cloud',
+        main_loop: null,
+        unknown: null,
+    };
+    async turnEnvelope(request) {
+        const turnType = request.turn_type ?? classifyTurnEnvelope(request.messages);
+        const targetTier = RouterPipeline.TURN_TIER_MAP[turnType] ?? null;
+        if (!targetTier) {
+            return { decided: false, stage: 'turn_envelope' };
+        }
+        const tierCandidates = this.activeFleet.filter((m) => m.tier === targetTier && m.healthy !== false);
+        const model = selectLowestCostModel(tierCandidates);
+        if (!model) {
+            return { decided: false, stage: 'turn_envelope' };
+        }
+        return {
+            decided: true,
+            stage: 'turn_envelope',
+            decision: this.withEstimatedCost(request, model, {
+                request_id: request.request_id,
+                selected_model_id: model.id,
+                tier: targetTier,
+                stage: 'turn_envelope',
+                reason_code: `turn_${turnType}`,
+                routing_latency_ms: 0,
+                pin_reason: null,
+            }),
+        };
+    }
+    // ─── Low-intensity tier gate (SP-103, #58) ───────────────────────────────
+    /**
+     * Runs after turn_envelope and context_fit, before session_pin. Computes low-intensity score
+     * from structural signals and optional cluster match; sets tier_hint and constrains
+     * the active fleet for subsequent HyDRA matching when confidence is high.
+     */
+    async lowIntensityGate(request) {
+        const config = this.options.lowIntensityConfig ?? DEFAULT_OPERATOR_CONFIG.low_intensity;
+        const alpha = config.p_success_alpha;
+        this.currentPSuccessAlpha = alpha;
+        const triageResult = triageClassify(request.prompt_text);
+        let clusterMatch;
+        const matcher = this.options.clusterMatcher;
+        if (matcher) {
+            try {
+                const result = await matcher.match(request);
+                this.currentClusterMatch = result;
+                clusterMatch = result;
+            }
+            catch {
+                this.currentClusterMatch = null;
+            }
+        }
+        const tierFeatures = buildTierFeatures(request, triageResult, undefined, clusterMatch);
+        const score = scoreLowIntensity(tierFeatures, config.weights);
+        this.currentLowIntensityScore = score;
+        const weights = this.resolvePSuccessWeights();
+        const pFeatures = tierFeaturesToPSuccessFeatures(tierFeatures);
+        const pResult = predictPSuccessCheapTimed(pFeatures, weights);
+        this.currentPSuccessCheap = pResult.probability;
+        const structuralHint = this.resolveTierHint(score, config.high_threshold, config.low_threshold, clusterMatch);
+        const weightsTrained = weights.trained_sample_count >= weights.min_training_samples;
+        const adjustedHint = weightsTrained
+            ? (() => {
+                const selection = this.selectExpectedCostTierHint(request, pResult.probability, alpha);
+                this.logExpectedCostExplain(pResult.probability, alpha, selection);
+                return {
+                    tierHint: selection.tierHint,
+                    reasonCode: selection.reasonCode,
+                };
+            })()
+            : structuralHint;
+        this.currentTierHint = adjustedHint.tierHint;
+        this.currentTierHintReasonCode = adjustedHint.reasonCode;
+        return { decided: false, stage: 'low_intensity' };
+    }
+    selectExpectedCostTierHint(request, pSuccessCheap, alpha) {
+        const estTokens = request.estimated_input_tokens ?? request.prompt_text.length;
+        const pinner = this.options.sessionPinner;
+        const sessionPin = pinner?.getPin(request.session_id) ?? undefined;
+        const pinnedModel = sessionPin !== undefined
+            ? this.activeFleet.find((model) => model.id === sessionPin.pinned_model_id)
+            : undefined;
+        const selection = selectTierByExpectedCost({
+            fleet: this.activeFleet,
+            priceCatalog: this.options.priceCatalog ?? null,
+            estTokens,
+            pSuccessCheap,
+            alpha,
+            localZeroReady: this.isLocalZeroTierReady(),
+            ...(pinnedModel !== undefined ? { pinnedModel } : {}),
+            ...(sessionPin !== undefined ? { sessionPin } : {}),
+        });
+        this.currentExpectedCostByTier = [...selection.tierCosts];
+        return {
+            tierHint: selection.tierHint,
+            reasonCode: selection.reasonCode,
+            tierCosts: selection.tierCosts,
+            rationale: selection.rationale,
+        };
+    }
+    logExpectedCostExplain(pSuccessCheap, alpha, selection) {
+        console.info('Expected-cost tier gate', {
+            reason: selection.reasonCode,
+            p_success_cheap: pSuccessCheap,
+            alpha,
+            chosen_tier: selection.tierHint,
+            rationale: selection.rationale,
+            expected_cost_by_tier: selection.tierCosts.map((entry) => ({
+                tier: entry.tier,
+                p_success: entry.pSuccess,
+                cost_per_1m: entry.costPer1M,
+                expected_cost_usd: entry.expectedCostUsd,
+                adjusted_expected_cost_usd: entry.adjustedExpectedCostUsd,
+            })),
+        });
+    }
+    resolvePSuccessWeights() {
+        if (this.options.pSuccessWeights) {
+            return this.options.pSuccessWeights;
+        }
+        if (!this.pSuccessWeightsLoaded) {
+            this.cachedPSuccessWeights = resolvePSuccessWeights({
+                ...(this.options.pSuccessWeightsPath !== undefined
+                    ? { filePath: this.options.pSuccessWeightsPath }
+                    : {}),
+            });
+            this.pSuccessWeightsLoaded = true;
+        }
+        return this.cachedPSuccessWeights;
+    }
+    resolveTierHint(score, highThreshold, lowThreshold, clusterMatch) {
+        if (score >= highThreshold) {
+            return {
+                tierHint: this.resolveLowIntensityTierHint(),
+                reasonCode: this.resolveLowIntensityReasonCode(clusterMatch),
+            };
+        }
+        if (score <= lowThreshold) {
+            return {
+                tierHint: 'frontier-cloud',
+                reasonCode: this.resolveHighIntensityReasonCode(clusterMatch),
+            };
+        }
+        return { tierHint: null, reasonCode: null };
+    }
+    resolveLowIntensityTierHint() {
+        if (this.isLocalZeroTierReady()) {
+            return 'zero-tier';
+        }
+        return 'economical-cloud';
+    }
+    isLocalZeroTierReady() {
+        const hasZeroTierModel = this.activeFleet.some((model) => model.tier === 'zero-tier' && model.healthy !== false);
+        if (!hasZeroTierModel) {
+            return false;
+        }
+        return this.currentHardwareResult === 'full_local';
+    }
+    resolveLowIntensityReasonCode(clusterMatch) {
+        if (clusterMatch?.confidence === 'high' &&
+            (clusterMatch.tierBias === 'zero-tier' ||
+                clusterMatch.tierBias === 'economical-cloud')) {
+            return clusterReasonCode(clusterMatch.clusterId);
+        }
+        return 'low_intensity_structural';
+    }
+    resolveHighIntensityReasonCode(clusterMatch) {
+        if (clusterMatch?.confidence === 'high' && clusterMatch.tierBias === 'frontier-cloud') {
+            return clusterReasonCode(clusterMatch.clusterId);
+        }
+        return 'high_intensity_structural';
+    }
+    constrainFleetToTierHint(fleet, tierHint) {
+        const filtered = fleet.filter((model) => model.tier === tierHint && model.healthy !== false);
+        return filtered.length > 0 ? filtered : fleet;
+    }
+    // ─── Loop escalation (Step 3b — FR-014) ─────────────────────────────────
+    /**
+     * Observational loop escalation: detects repeated identical tool failures
+     * and re-pins the session to a frontier-capable tier.
+     *
+     * Runs before turn_envelope and session_pin so it can modify pin state.
+     * Never returns decided: true — turnEnvelope or sessionPin picks up the
+     * (potentially escalated) pin on subsequent stages.
+     */
+    async loopEscalation(request) {
+        const pinner = this.options.sessionPinner;
+        const config = this.options.loopEscalationConfig;
+        if (!pinner || !config) {
+            return { decided: false, stage: 'loop_escalation' };
+        }
+        const pin = pinner.getPin(request.session_id);
+        const result = evaluateLoopEscalation(pin, request, this.activeFleet, config);
+        if (result.updatedPin) {
+            pinner.loadPin(result.updatedPin);
+        }
+        if (result.shouldEscalate && result.escalationTarget) {
+            pinner.breakPin(request.session_id);
+            pinner.recordPin(request.session_id, result.escalationTarget.id, 'loop_escalation');
+        }
+        return { decided: false, stage: 'loop_escalation' };
+    }
+    /**
+     * Step 5: HyDRA embedding matcher for ambiguous prompts (T050).
+     * Scores fleet candidates via embedding cosine similarity with shortfall gate.
+     * Pass-through when no matcher is configured.
+     */
+    async hydraMatcher(request) {
+        const matcher = this.options.hydraMatcher;
+        if (!matcher) {
+            return { decided: false, stage: 'hydra_match' };
+        }
+        const fleetForMatch = this.currentTierHint
+            ? this.constrainFleetToTierHint(this.activeFleet, this.currentTierHint)
+            : this.activeFleet;
+        const result = await matcher.match(request, fleetForMatch);
+        this.currentHydraResult = result;
+        if (!result.selected) {
+            return { decided: false, stage: 'hydra_match' };
+        }
+        const selectedModel = this.activeFleet.find((m) => m.id === result.selected.model_id);
+        if (!selectedModel) {
+            return { decided: false, stage: 'hydra_match' };
+        }
+        return {
+            decided: true,
+            stage: 'hydra_match',
+            decision: this.withEstimatedCost(request, selectedModel, {
+                request_id: request.request_id,
+                selected_model_id: selectedModel.id,
+                tier: selectedModel.tier,
+                stage: 'hydra_match',
+                reason_code: 'hydra_embedding_match',
+                candidates: result.candidates,
+                routing_latency_ms: result.elapsedMs,
+                pin_reason: null,
+            }),
+        };
+    }
+}
+//# sourceMappingURL=router-pipeline.js.map