@lsctech/polaris 0.5.7 → 0.5.8

package/dist/autoresearch/sol-scorecard-calculator.js

@@ -0,0 +1,865 @@
+"use strict";
+/**
+ * SOL scorecard calculator.
+ *
+ * Computes durable, versioned scorecards for SOL evaluation subjects:
+ * Foreman, worker, provider, model, and routing decisions.
+ *
+ * Design rules:
+ *   - Reuses the existing SolScoreReport scoring logic where available to
+ *     avoid conflicting formulas (POL-481).
+ *   - Each scorecard preserves raw metrics and carries formula versions.
+ *   - Missing evidence results in skipped subscores with reasons.
+ *   - No routing policy or provider selection behavior is changed.
+ *
+ * Scope: src/autoresearch/**
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildForemanRawMetrics = buildForemanRawMetrics;
+exports.buildWorkerRawMetrics = buildWorkerRawMetrics;
+exports.buildProviderRawMetrics = buildProviderRawMetrics;
+exports.buildModelRawMetrics = buildModelRawMetrics;
+exports.buildRoutingRawMetrics = buildRoutingRawMetrics;
+exports.computeForemanScorecard = computeForemanScorecard;
+exports.computeWorkerScorecard = computeWorkerScorecard;
+exports.computeProviderScorecard = computeProviderScorecard;
+exports.computeModelScorecard = computeModelScorecard;
+exports.computeRoutingScorecard = computeRoutingScorecard;
+exports.computeAllScorecards = computeAllScorecards;
+const sol_scorecard_js_1 = require("../types/sol-scorecard.js");
+const sol_scorer_js_1 = require("./sol-scorer.js");
+// ──────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────
+function clamp01(v) {
+    return Math.max(0, Math.min(1, v));
+}
+function subscore(dimension, formulaVersion, score, confidence, opts = {}) {
+    return { dimension, formula_version: formulaVersion, score, confidence, ...opts };
+}
+function skippedSubscore(dimension, formulaVersion, reason) {
+    return subscore(dimension, formulaVersion, null, "none", { skipped_reason: reason });
+}
+function toSolSubscore(dim, formulaVersion) {
+    return {
+        dimension: dim.dimension,
+        formula_version: formulaVersion,
+        score: dim.score,
+        confidence: dim.confidence,
+        skipped_reason: dim.skipped_reason,
+        detail: dim.detail,
+    };
+}
+function confidenceFromCount(count) {
+    if (count >= 5)
+        return "high";
+    if (count >= 2)
+        return "medium";
+    return "low";
+}
+function makeWindow(ev) {
+    return {
+        run_id: ev.run_id,
+        cluster_id: ev.cluster_id ?? undefined,
+        sample_count: ev.run.total_children > 0 ? ev.run.total_children : undefined,
+    };
+}
+function defaultSourceRefs(ev) {
+    const refs = [
+        { kind: "run-state", path: ".taskchain_artifacts/polaris-run/current-state.json", available: ev.run.status !== null },
+        { kind: "telemetry", path: `.taskchain_artifacts/polaris-run/runs/${ev.run_id}/telemetry.jsonl`, available: ev.tokens.total_worker_heartbeats > 0 },
+    ];
+    if (ev.cluster_id) {
+        refs.push({ kind: "cluster-state", path: `.polaris/clusters/${ev.cluster_id}/cluster-state.json`, available: true });
+    }
+    return refs;
+}
+// ──────────────────────────────────────────────
+// Raw metric builders
+// ──────────────────────────────────────────────
+function emptyRawMetrics() {
+    return {
+        max_bootstrap_tokens: null,
+        worker_tokens_used: null,
+        dispatch_epoch: null,
+        continue_epoch: null,
+        total_children: null,
+        workers_succeeded: null,
+        workers_failed: null,
+        redispatch_count: null,
+        validation_outcome: null,
+        passed_commands: [],
+        qc_total_findings: null,
+        qc_blocking_findings: null,
+        qc_repaired_findings: null,
+        qc_repair_loop_status: null,
+        qc_repair_rounds: null,
+        escalation_count: null,
+        out_of_scope_count: null,
+        user_intervened: null,
+        foreman_intervened: null,
+        state_repair_required: null,
+        provider_selected: null,
+        router_fallback_used: null,
+        router_exhausted: null,
+        router_exhausted_reason: null,
+        provider_decisions: null,
+        provider_startup_failures: null,
+        provider_exhausted_decisions: null,
+        provider_fallback_attempts: null,
+        provider_successful_fallbacks: null,
+        model_decisions: null,
+        model_startup_failures: null,
+        model_exhausted_decisions: null,
+        model_fallback_attempts: null,
+        model_successful_fallbacks: null,
+        router_candidates_count: null,
+        router_child_status: null,
+        router_child_validation: null,
+        heartbeat_count: null,
+    };
+}
+function buildForemanRawMetrics(ev) {
+    const run = ev.run;
+    const foreman = ev.foreman;
+    const worker = ev.worker;
+    const intervention = ev.intervention;
+    return {
+        ...emptyRawMetrics(),
+        max_bootstrap_tokens: foreman.max_bootstrap_tokens,
+        dispatch_epoch: run.dispatch_epoch,
+        continue_epoch: run.continue_epoch,
+        total_children: run.total_children,
+        workers_succeeded: worker.workers_succeeded,
+        workers_failed: worker.workers_failed,
+        redispatch_count: foreman.redispatch_count,
+        qc_total_findings: ev.qc.total_findings,
+        qc_blocking_findings: ev.qc.blocking_findings,
+        qc_repaired_findings: ev.qc.repaired_findings,
+        qc_repair_loop_status: ev.qc.repair_loop?.status ?? null,
+        qc_repair_rounds: ev.qc.repair_loop
+            ? { completed: ev.qc.repair_loop.rounds_completed, max: ev.qc.repair_loop.max_rounds }
+            : null,
+        escalation_count: foreman.escalation_events,
+        out_of_scope_count: intervention.out_of_scope_count,
+        user_intervened: intervention.user_intervened,
+        foreman_intervened: intervention.foreman_intervened,
+        state_repair_required: intervention.state_repair_required,
+        heartbeat_count: worker.total_heartbeats,
+    };
+}
+function buildWorkerRawMetrics(ev, child) {
+    const validation = ev.validation.find((v) => v.child_id === child.child_id);
+    return {
+        ...emptyRawMetrics(),
+        worker_tokens_used: ev.tokens.tokens_by_child[child.child_id] ?? null,
+        validation_outcome: validation?.outcome ?? child.validation,
+        passed_commands: validation?.passed_commands ?? [],
+        qc_total_findings: ev.qc.total_findings,
+        qc_blocking_findings: ev.qc.blocking_findings,
+        qc_repaired_findings: ev.qc.repaired_findings,
+        qc_repair_loop_status: ev.qc.repair_loop?.status ?? null,
+        escalation_count: child.escalation_count,
+        user_intervened: child.user_intervened,
+        foreman_intervened: child.foreman_intervened,
+        heartbeat_count: child.heartbeat_count,
+    };
+}
+function aggregateForProvider(ev, provider) {
+    const children = ev.children.filter((c) => c.provider === provider);
+    const decisions = ev.router.decisions.filter((d) => d.selected_provider === provider || d.providers_tried.includes(provider));
+    let startupFailures = 0;
+    let exhaustedDecisions = 0;
+    let fallbackAttempts = 0;
+    let successfulFallbacks = 0;
+    for (const d of decisions) {
+        if (d.exhausted && (d.selected_provider ?? d.providers_tried[d.providers_tried.length - 1]) === provider) {
+            startupFailures++;
+            exhaustedDecisions++;
+        }
+        else if (d.exhausted && d.providers_tried.includes(provider)) {
+            exhaustedDecisions++;
+        }
+        if (d.fallback_used && d.providers_tried.includes(provider)) {
+            fallbackAttempts++;
+            const child = ev.children.find((c) => c.child_id === d.child_id);
+            if (child && child.status === "done")
+                successfulFallbacks++;
+        }
+    }
+    let succeeded = 0;
+    let failed = 0;
+    let blocked = 0;
+    let totalHeartbeats = 0;
+    let totalTokens = 0;
+    let tokenEvidenceMissing = false;
+    let validationPasses = 0;
+    let validationFailures = 0;
+    for (const c of children) {
+        if (c.status === "done")
+            succeeded++;
+        else if (c.status === "failed" || c.status === "error")
+            failed++;
+        else if (c.status === "blocked")
+            blocked++;
+        totalHeartbeats += c.heartbeat_count;
+        if (!Object.prototype.hasOwnProperty.call(ev.tokens.tokens_by_child, c.child_id)) {
+            tokenEvidenceMissing = true;
+        }
+        else {
+            totalTokens += ev.tokens.tokens_by_child[c.child_id] ?? 0;
+        }
+        const v = ev.validation.find((val) => val.child_id === c.child_id);
+        const outcome = v?.outcome ?? c.validation;
+        if (outcome === "passed")
+            validationPasses++;
+        else if (outcome === "failed")
+            validationFailures++;
+    }
+    return {
+        children,
+        decisions,
+        startupFailures,
+        exhaustedDecisions,
+        fallbackAttempts,
+        successfulFallbacks,
+        succeeded,
+        failed,
+        blocked,
+        totalHeartbeats,
+        totalTokens: children.length > 0 && !tokenEvidenceMissing ? totalTokens : null,
+        validationPasses,
+        validationFailures,
+    };
+}
+function buildProviderRawMetrics(ev, provider) {
+    const agg = aggregateForProvider(ev, provider);
+    // For provider/model scorecards, store mean-per-child tokens so over_token_budget
+    // comparisons against WORKER_TOKEN_EFFICIENCY_SPEC.budget remain valid (POL-509).
+    const meanTokensPerChild = agg.totalTokens !== null && agg.children.length > 0
+        ? Math.round(agg.totalTokens / agg.children.length)
+        : null;
+    return {
+        ...emptyRawMetrics(),
+        total_children: agg.children.length,
+        workers_succeeded: agg.succeeded,
+        workers_failed: agg.failed,
+        worker_tokens_used: meanTokensPerChild,
+        validation_outcome: agg.validationPasses > 0 || agg.validationFailures > 0
+            ? agg.validationFailures === 0
+                ? "passed"
+                : "failed"
+            : null,
+        passed_commands: agg.validationFailures === 0 && agg.validationPasses > 0 ? ["aggregate"] : [],
+        qc_total_findings: ev.qc.total_findings,
+        qc_blocking_findings: ev.qc.blocking_findings,
+        provider_selected: provider,
+        provider_decisions: agg.decisions.length,
+        provider_startup_failures: agg.startupFailures,
+        provider_exhausted_decisions: agg.exhaustedDecisions,
+        provider_fallback_attempts: agg.fallbackAttempts,
+        provider_successful_fallbacks: agg.successfulFallbacks,
+        heartbeat_count: agg.totalHeartbeats > 0 ? agg.totalHeartbeats : null,
+    };
+}
+function aggregateForModel(ev, model) {
+    const children = ev.children.filter((c) => c.grouping_keys.model === model);
+    // Model attribution on router decisions is best-effort via child grouping keys.
+    const childIds = new Set(children.map((c) => c.child_id));
+    const decisions = ev.router.decisions.filter((d) => childIds.has(d.child_id));
+    let startupFailures = 0;
+    let exhaustedDecisions = 0;
+    let fallbackAttempts = 0;
+    let successfulFallbacks = 0;
+    for (const d of decisions) {
+        if (d.exhausted) {
+            startupFailures++;
+            exhaustedDecisions++;
+        }
+        if (d.fallback_used) {
+            fallbackAttempts++;
+            const child = ev.children.find((c) => c.child_id === d.child_id);
+            if (child && child.status === "done")
+                successfulFallbacks++;
+        }
+    }
+    let succeeded = 0;
+    let failed = 0;
+    let blocked = 0;
+    let totalHeartbeats = 0;
+    let totalTokens = 0;
+    let tokenEvidenceMissing = false;
+    let validationPasses = 0;
+    let validationFailures = 0;
+    for (const c of children) {
+        if (c.status === "done")
+            succeeded++;
+        else if (c.status === "failed" || c.status === "error")
+            failed++;
+        else if (c.status === "blocked")
+            blocked++;
+        totalHeartbeats += c.heartbeat_count;
+        if (!Object.prototype.hasOwnProperty.call(ev.tokens.tokens_by_child, c.child_id)) {
+            tokenEvidenceMissing = true;
+        }
+        else {
+            totalTokens += ev.tokens.tokens_by_child[c.child_id] ?? 0;
+        }
+        const v = ev.validation.find((val) => val.child_id === c.child_id);
+        const outcome = v?.outcome ?? c.validation;
+        if (outcome === "passed")
+            validationPasses++;
+        else if (outcome === "failed")
+            validationFailures++;
+    }
+    return {
+        children,
+        decisions,
+        startupFailures,
+        exhaustedDecisions,
+        fallbackAttempts,
+        successfulFallbacks,
+        succeeded,
+        failed,
+        blocked,
+        totalHeartbeats,
+        totalTokens: children.length > 0 && !tokenEvidenceMissing ? totalTokens : null,
+        validationPasses,
+        validationFailures,
+    };
+}
+function buildModelRawMetrics(ev, model) {
+    const agg = aggregateForModel(ev, model);
+    // For provider/model scorecards, store mean-per-child tokens so over_token_budget
+    // comparisons against WORKER_TOKEN_EFFICIENCY_SPEC.budget remain valid (POL-509).
+    const meanTokensPerChild = agg.totalTokens !== null && agg.children.length > 0
+        ? Math.round(agg.totalTokens / agg.children.length)
+        : null;
+    return {
+        ...emptyRawMetrics(),
+        total_children: agg.children.length,
+        workers_succeeded: agg.succeeded,
+        workers_failed: agg.failed,
+        worker_tokens_used: meanTokensPerChild,
+        validation_outcome: agg.validationPasses > 0 || agg.validationFailures > 0
+            ? agg.validationFailures === 0
+                ? "passed"
+                : "failed"
+            : null,
+        passed_commands: agg.validationFailures === 0 && agg.validationPasses > 0 ? ["aggregate"] : [],
+        qc_total_findings: ev.qc.total_findings,
+        qc_blocking_findings: ev.qc.blocking_findings,
+        model_decisions: agg.decisions.length,
+        model_startup_failures: agg.startupFailures,
+        model_exhausted_decisions: agg.exhaustedDecisions,
+        model_fallback_attempts: agg.fallbackAttempts,
+        model_successful_fallbacks: agg.successfulFallbacks,
+        heartbeat_count: agg.totalHeartbeats > 0 ? agg.totalHeartbeats : null,
+    };
+}
+function buildRoutingRawMetrics(ev, decision) {
+    const child = ev.children.find((c) => c.child_id === decision.child_id);
+    const validation = ev.validation.find((v) => v.child_id === decision.child_id);
+    return {
+        ...emptyRawMetrics(),
+        total_children: child ? 1 : 0,
+        workers_succeeded: child?.status === "done" ? 1 : 0,
+        workers_failed: child && (child.status === "failed" || child.status === "error") ? 1 : 0,
+        worker_tokens_used: child ? ev.tokens.tokens_by_child[child.child_id] ?? null : null,
+        validation_outcome: validation?.outcome ?? child?.validation ?? null,
+        passed_commands: validation?.passed_commands ?? [],
+        qc_total_findings: ev.qc.total_findings,
+        qc_blocking_findings: ev.qc.blocking_findings,
+        provider_selected: decision.selected_provider,
+        router_fallback_used: decision.fallback_used,
+        router_exhausted: decision.exhausted,
+        router_exhausted_reason: decision.exhausted_reason,
+        router_candidates_count: decision.providers_tried.length,
+        router_child_status: child?.status ?? null,
+        router_child_validation: validation?.outcome ?? child?.validation ?? null,
+        heartbeat_count: child?.heartbeat_count ?? null,
+    };
+}
+// ──────────────────────────────────────────────
+// Scorecard assembly
+// ──────────────────────────────────────────────
+function buildScorecard(subject, subjectKey, ev, rawMetrics, subscores, sourceRefs, groupingKeys) {
+    const aggregateScore = (0, sol_scorecard_js_1.computeAggregateScore)(subscores);
+    const availability = (0, sol_scorecard_js_1.determineScorecardAvailability)(subscores);
+    const availabilityReason = availability === "unavailable"
+        ? "No scoreable dimensions were produced"
+        : availability === "skipped"
+            ? "All dimensions were skipped due to missing evidence"
+            : undefined;
+    const scoredConfidences = subscores
+        .filter((s) => s.score !== null)
+        .map((s) => s.confidence);
+    const aggregateConfidence = scoredConfidences.length === 0
+        ? "none"
+        : (scoredConfidences.reduce((worst, c) => {
+            const rank = { high: 3, medium: 2, low: 1, none: 0 };
+            return rank[c] < rank[worst] ? c : worst;
+        }, "high"));
+    return {
+        schema_version: "1.0",
+        scorecard_id: `${subject}-${subjectKey}-${ev.run_id}`,
+        subject,
+        subject_key: subjectKey,
+        window: makeWindow(ev),
+        grouping_keys: groupingKeys ?? ev.grouping_keys,
+        generated_at: new Date().toISOString(),
+        availability,
+        availability_reason: availabilityReason,
+        raw_metrics: rawMetrics,
+        subscores,
+        aggregate_score: aggregateScore,
+        aggregate_confidence: aggregateConfidence,
+        source_refs: sourceRefs,
+        recommendation_inputs: (0, sol_scorecard_js_1.buildRecommendationInputs)(subscores, rawMetrics, aggregateScore),
+        aggregate_formula_version: sol_scorecard_js_1.SOL_FORMULA_VERSIONS.COMPOSITE_MEAN_V1,
+    };
+}
+// ──────────────────────────────────────────────
+// Foreman scorecard
+// ──────────────────────────────────────────────
+/**
+ * Compute a scorecard for the Foreman subject.
+ */
+function computeForemanScorecard(ev, sourceRefs, groupingKeys) {
+    const report = (0, sol_scorer_js_1.computeForemanScore)(ev);
+    const rawMetrics = buildForemanRawMetrics(ev);
+    const subscores = [
+        toSolSubscore(report.token, sol_scorecard_js_1.SOL_FORMULA_VERSIONS.TOKEN_EFFICIENCY_V1),
+        toSolSubscore(report.duration, sol_scorecard_js_1.SOL_FORMULA_VERSIONS.RUNTIME_PROXY_V1),
+        toSolSubscore(report.intervention, sol_scorecard_js_1.SOL_FORMULA_VERSIONS.INTERVENTION_BINARY_V1),
+        toSolSubscore(report.dependency, sol_scorecard_js_1.SOL_FORMULA_VERSIONS.DISPATCH_RATE_V1),
+        toSolSubscore(report.dispatch, sol_scorecard_js_1.SOL_FORMULA_VERSIONS.DISPATCH_RATE_V1),
+        toSolSubscore(report.evidence_validation, sol_scorecard_js_1.SOL_FORMULA_VERSIONS.VALIDATION_BINARY_V1),
+        toSolSubscore(report.scope, sol_scorecard_js_1.SOL_FORMULA_VERSIONS.SCOPE_ADHERENCE_V1),
+        toSolSubscore(report.completion, sol_scorecard_js_1.SOL_FORMULA_VERSIONS.QUALITY_OUTCOMES_V1),
+        toSolSubscore(report.recovery, sol_scorecard_js_1.SOL_FORMULA_VERSIONS.INTERVENTION_BINARY_V1),
+        toSolSubscore(report.qc_repair_loop, sol_scorecard_js_1.SOL_FORMULA_VERSIONS.QC_REPAIR_LOOP_V1),
+    ];
+    // Quality-per-token is a synthetic dimension for the Foreman scorecard.
+    const qpt = computeQualityPerToken(rawMetrics, report.composite_score, sol_scorecard_js_1.FOREMAN_QUALITY_PER_TOKEN_SPEC.budget_denominator);
+    if (qpt)
+        subscores.push(qpt);
+    return buildScorecard("foreman", ev.run_id, ev, rawMetrics, subscores, sourceRefs ?? defaultSourceRefs(ev), groupingKeys);
+}
+// ──────────────────────────────────────────────
+// Worker scorecard
+// ──────────────────────────────────────────────
+/**
+ * Compute a scorecard for a single worker child.
+ * Returns null when the child is not found in evidence.
+ */
+function computeWorkerScorecard(ev, childId, sourceRefs, groupingKeys) {
+    const child = ev.children.find((c) => c.child_id === childId);
+    if (!child)
+        return null;
+    const report = (0, sol_scorer_js_1.computeWorkerScore)(childId, ev);
+    if (!report)
+        return null;
+    const rawMetrics = buildWorkerRawMetrics(ev, child);
+    const subscores = [
+        toSolSubscore(report.token, sol_scorecard_js_1.SOL_FORMULA_VERSIONS.TOKEN_EFFICIENCY_V1),
+        toSolSubscore(report.duration, sol_scorecard_js_1.SOL_FORMULA_VERSIONS.RUNTIME_PROXY_V1),
+        toSolSubscore(report.validation, sol_scorecard_js_1.SOL_FORMULA_VERSIONS.VALIDATION_BINARY_V1),
+        toSolSubscore(report.qc, sol_scorecard_js_1.SOL_FORMULA_VERSIONS.QC_REPAIR_LOOP_V1),
+        toSolSubscore(report.repair_iterations, sol_scorecard_js_1.SOL_FORMULA_VERSIONS.QC_REPAIR_LOOP_V1),
+        toSolSubscore(report.scope_adherence, sol_scorecard_js_1.SOL_FORMULA_VERSIONS.SCOPE_ADHERENCE_V1),
+        toSolSubscore(report.acceptance_criteria, sol_scorecard_js_1.SOL_FORMULA_VERSIONS.VALIDATION_BINARY_V1),
+        toSolSubscore(report.first_pass, sol_scorecard_js_1.SOL_FORMULA_VERSIONS.INTERVENTION_BINARY_V1),
+    ];
+    const qpt = computeQualityPerToken(rawMetrics, report.composite_score, sol_scorecard_js_1.WORKER_QUALITY_PER_TOKEN_SPEC.budget_denominator);
+    if (qpt)
+        subscores.push(qpt);
+    return buildScorecard("worker", childId, ev, rawMetrics, subscores, sourceRefs ?? defaultSourceRefs(ev), groupingKeys ?? child.grouping_keys);
+}
+function computeQualityPerToken(rawMetrics, compositeScore, budget) {
+    const tokens = rawMetrics.worker_tokens_used ?? rawMetrics.max_bootstrap_tokens;
+    if (tokens === null || compositeScore === null)
+        return null;
+    if (tokens <= 0)
+        return null;
+    const normalizedCost = tokens / budget;
+    const value = compositeScore / normalizedCost;
+    // Cap quality-per-token at 2.0 (twice the budget efficiency) and map to 0–1
+    const score = clamp01(value / 2.0);
+    const confidence = rawMetrics.worker_tokens_used !== null ? "high" : rawMetrics.max_bootstrap_tokens !== null ? "medium" : "low";
+    return subscore("quality_per_token", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.QUALITY_PER_TOKEN_V1, Number(score.toFixed(4)), confidence, {
+        detail: `composite_score=${compositeScore}, tokens=${tokens}, budget=${budget}`,
+    });
+}
+// ──────────────────────────────────────────────
+// Provider scorecard
+// ──────────────────────────────────────────────
+function scoreProviderStartupFailure(metrics) {
+    const total = metrics.provider_decisions ?? 0;
+    if (total === 0)
+        return skippedSubscore("startup_failure", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.STARTUP_FAILURE_RATE_V1, "no routing decisions for provider");
+    const failures = metrics.provider_startup_failures ?? 0;
+    const rate = failures / total;
+    const score = clamp01(1.0 - rate);
+    return subscore("startup_failure", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.STARTUP_FAILURE_RATE_V1, Number(score.toFixed(4)), confidenceFromCount(total), {
+        detail: `startup_failures=${failures}, decisions=${total}`,
+    });
+}
+function scoreProviderQuotaExhaustion(metrics) {
+    const total = metrics.provider_decisions ?? 0;
+    if (total === 0)
+        return skippedSubscore("quota_exhaustion", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.QUOTA_EXHAUSTION_RATE_V1, "no routing decisions for provider");
+    const exhausted = metrics.provider_exhausted_decisions ?? 0;
+    const rate = exhausted / total;
+    const score = clamp01(1.0 - rate);
+    return subscore("quota_exhaustion", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.QUOTA_EXHAUSTION_RATE_V1, Number(score.toFixed(4)), confidenceFromCount(total), {
+        detail: `exhausted_decisions=${exhausted}, decisions=${total}`,
+    });
+}
+function scoreProviderFallbackFrequency(metrics) {
+    const total = metrics.provider_decisions ?? 0;
+    if (total === 0)
+        return skippedSubscore("fallback_frequency", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.FALLBACK_FREQUENCY_V1, "no routing decisions for provider");
+    const fallbacks = metrics.provider_fallback_attempts ?? 0;
+    const rate = fallbacks / total;
+    // More fallbacks = lower score (provider needed help)
+    const score = clamp01(1.0 - rate);
+    return subscore("fallback_frequency", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.FALLBACK_FREQUENCY_V1, Number(score.toFixed(4)), confidenceFromCount(total), {
+        detail: `fallback_attempts=${fallbacks}, successful_fallbacks=${metrics.provider_successful_fallbacks ?? 0}, decisions=${total}`,
+    });
+}
+function scoreProviderRoleSuitability(metrics) {
+    const total = metrics.total_children ?? 0;
+    if (total === 0)
+        return skippedSubscore("role_suitability", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROLE_SUITABILITY_V1, "no children assigned to provider");
+    const succeeded = metrics.workers_succeeded ?? 0;
+    const score = clamp01(succeeded / total);
+    return subscore("role_suitability", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROLE_SUITABILITY_V1, Number(score.toFixed(4)), confidenceFromCount(total), {
+        detail: `succeeded=${succeeded}, total=${total}`,
+    });
+}
+function scoreProviderRuntime(metrics) {
+    const hb = metrics.heartbeat_count;
+    const total = metrics.total_children ?? 0;
+    if (hb === null || total === 0) {
+        return skippedSubscore("runtime", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.RUNTIME_PROXY_V1, "no heartbeat evidence for provider");
+    }
+    const mean = hb / total;
+    // Same proxy as worker duration: 1–10 heartbeats per child ideal
+    const EXPECTED_MAX = 10;
+    const score = clamp01(mean <= EXPECTED_MAX ? 1.0 : 1.0 - (mean - EXPECTED_MAX) * 0.05);
+    return subscore("runtime", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.RUNTIME_PROXY_V1, Number(score.toFixed(4)), confidenceFromCount(total), {
+        detail: `mean_heartbeats_per_child=${mean.toFixed(1)}`,
+    });
+}
+function scoreProviderTokenEfficiency(metrics) {
+    const tokens = metrics.worker_tokens_used;
+    const total = metrics.total_children ?? 0;
+    if (tokens === null || total === 0) {
+        return skippedSubscore("token_efficiency", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.TOKEN_EFFICIENCY_V1, "no token evidence for provider");
+    }
+    const mean = tokens / total;
+    const BUDGET = sol_scorecard_js_1.WORKER_TOKEN_EFFICIENCY_SPEC.budget;
+    const MAX_PENALIZED = sol_scorecard_js_1.WORKER_TOKEN_EFFICIENCY_SPEC.max_penalized;
+    const score = mean <= BUDGET ? 1.0 : clamp01(1.0 - (mean - BUDGET) / (MAX_PENALIZED - BUDGET));
+    return subscore("token_efficiency", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.TOKEN_EFFICIENCY_V1, Number(score.toFixed(4)), "high", {
+        detail: `mean_tokens_per_child=${Math.round(mean)}`,
+    });
+}
+function scoreProviderQualityOutcomes(metrics) {
+    const total = metrics.total_children ?? 0;
+    if (total === 0)
+        return skippedSubscore("quality_outcomes", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.QUALITY_OUTCOMES_V1, "no children assigned to provider");
+    const succeeded = metrics.workers_succeeded ?? 0;
+    const validationOutcome = metrics.validation_outcome;
+    const score = validationOutcome === "passed" ? clamp01(succeeded / total) : clamp01(succeeded / total) * 0.8;
+    return subscore("quality_outcomes", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.QUALITY_OUTCOMES_V1, Number(score.toFixed(4)), confidenceFromCount(total), {
+        detail: `succeeded=${succeeded}, total=${total}, validation_outcome=${validationOutcome ?? "unknown"}`,
+    });
+}
+/**
+ * Compute a scorecard for a provider.
+ */
+function computeProviderScorecard(ev, provider, sourceRefs, groupingKeys) {
+    const rawMetrics = buildProviderRawMetrics(ev, provider);
+    const subscores = [
+        scoreProviderStartupFailure(rawMetrics),
+        scoreProviderQuotaExhaustion(rawMetrics),
+        scoreProviderFallbackFrequency(rawMetrics),
+        scoreProviderRoleSuitability(rawMetrics),
+        scoreProviderRuntime(rawMetrics),
+        scoreProviderTokenEfficiency(rawMetrics),
+        scoreProviderQualityOutcomes(rawMetrics),
+    ];
+    return buildScorecard("provider", provider, ev, rawMetrics, subscores, sourceRefs ?? defaultSourceRefs(ev), groupingKeys);
+}
+// ──────────────────────────────────────────────
+// Model scorecard
+// ──────────────────────────────────────────────
+function scoreModelStartupFailure(metrics) {
+    const total = metrics.model_decisions ?? 0;
+    if (total === 0)
+        return skippedSubscore("startup_failure", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.STARTUP_FAILURE_RATE_V1, "no routing decisions for model");
+    const failures = metrics.model_startup_failures ?? 0;
+    const rate = failures / total;
+    const score = clamp01(1.0 - rate);
+    return subscore("startup_failure", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.STARTUP_FAILURE_RATE_V1, Number(score.toFixed(4)), confidenceFromCount(total), {
+        detail: `startup_failures=${failures}, decisions=${total}`,
+    });
+}
+function scoreModelQuotaExhaustion(metrics) {
+    const total = metrics.model_decisions ?? 0;
+    if (total === 0)
+        return skippedSubscore("quota_exhaustion", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.QUOTA_EXHAUSTION_RATE_V1, "no routing decisions for model");
+    const exhausted = metrics.model_exhausted_decisions ?? 0;
+    const rate = exhausted / total;
+    const score = clamp01(1.0 - rate);
+    return subscore("quota_exhaustion", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.QUOTA_EXHAUSTION_RATE_V1, Number(score.toFixed(4)), confidenceFromCount(total), {
+        detail: `exhausted_decisions=${exhausted}, decisions=${total}`,
+    });
+}
+function scoreModelFallbackFrequency(metrics) {
+    const total = metrics.model_decisions ?? 0;
+    if (total === 0)
+        return skippedSubscore("fallback_frequency", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.FALLBACK_FREQUENCY_V1, "no routing decisions for model");
+    const fallbacks = metrics.model_fallback_attempts ?? 0;
+    const rate = fallbacks / total;
+    const score = clamp01(1.0 - rate);
+    return subscore("fallback_frequency", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.FALLBACK_FREQUENCY_V1, Number(score.toFixed(4)), confidenceFromCount(total), {
+        detail: `fallback_attempts=${fallbacks}, successful_fallbacks=${metrics.model_successful_fallbacks ?? 0}, decisions=${total}`,
+    });
+}
+function scoreModelRoleSuitability(metrics) {
+    const total = metrics.total_children ?? 0;
+    if (total === 0)
+        return skippedSubscore("role_suitability", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROLE_SUITABILITY_V1, "no children assigned to model");
+    const succeeded = metrics.workers_succeeded ?? 0;
+    const score = clamp01(succeeded / total);
+    return subscore("role_suitability", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROLE_SUITABILITY_V1, Number(score.toFixed(4)), confidenceFromCount(total), {
+        detail: `succeeded=${succeeded}, total=${total}`,
+    });
+}
+function scoreModelRuntime(metrics) {
+    const hb = metrics.heartbeat_count;
+    const total = metrics.total_children ?? 0;
+    if (hb === null || total === 0) {
+        return skippedSubscore("runtime", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.RUNTIME_PROXY_V1, "no heartbeat evidence for model");
+    }
+    const mean = hb / total;
+    const EXPECTED_MAX = 10;
+    const score = clamp01(mean <= EXPECTED_MAX ? 1.0 : 1.0 - (mean - EXPECTED_MAX) * 0.05);
+    return subscore("runtime", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.RUNTIME_PROXY_V1, Number(score.toFixed(4)), confidenceFromCount(total), {
+        detail: `mean_heartbeats_per_child=${mean.toFixed(1)}`,
+    });
+}
+function scoreModelTokenEfficiency(metrics) {
+    const tokens = metrics.worker_tokens_used;
+    const total = metrics.total_children ?? 0;
+    if (tokens === null || total === 0) {
+        return skippedSubscore("token_efficiency", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.TOKEN_EFFICIENCY_V1, "no token evidence for model");
+    }
+    const mean = tokens / total;
+    const BUDGET = sol_scorecard_js_1.WORKER_TOKEN_EFFICIENCY_SPEC.budget;
+    const MAX_PENALIZED = sol_scorecard_js_1.WORKER_TOKEN_EFFICIENCY_SPEC.max_penalized;
+    const score = mean <= BUDGET ? 1.0 : clamp01(1.0 - (mean - BUDGET) / (MAX_PENALIZED - BUDGET));
+    return subscore("token_efficiency", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.TOKEN_EFFICIENCY_V1, Number(score.toFixed(4)), "high", {
+        detail: `mean_tokens_per_child=${Math.round(mean)}`,
+    });
+}
+function scoreModelQualityOutcomes(metrics) {
+    const total = metrics.total_children ?? 0;
+    if (total === 0)
+        return skippedSubscore("quality_outcomes", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.QUALITY_OUTCOMES_V1, "no children assigned to model");
+    const succeeded = metrics.workers_succeeded ?? 0;
+    const validationOutcome = metrics.validation_outcome;
+    const score = validationOutcome === "passed" ? clamp01(succeeded / total) : clamp01(succeeded / total) * 0.8;
+    return subscore("quality_outcomes", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.QUALITY_OUTCOMES_V1, Number(score.toFixed(4)), confidenceFromCount(total), {
+        detail: `succeeded=${succeeded}, total=${total}, validation_outcome=${validationOutcome ?? "unknown"}`,
+    });
+}
+/**
+ * Compute a scorecard for a model.
+ */
+function computeModelScorecard(ev, model, sourceRefs, groupingKeys) {
+    const rawMetrics = buildModelRawMetrics(ev, model);
+    const subscores = [
+        scoreModelStartupFailure(rawMetrics),
+        scoreModelQuotaExhaustion(rawMetrics),
+        scoreModelFallbackFrequency(rawMetrics),
+        scoreModelRoleSuitability(rawMetrics),
+        scoreModelRuntime(rawMetrics),
+        scoreModelTokenEfficiency(rawMetrics),
+        scoreModelQualityOutcomes(rawMetrics),
+    ];
+    return buildScorecard("model", model, ev, rawMetrics, subscores, sourceRefs ?? defaultSourceRefs(ev), groupingKeys);
+}
+// ──────────────────────────────────────────────
+// Routing scorecard
+// ──────────────────────────────────────────────
+function scoreRouteSelected(metrics) {
+    if (metrics.router_exhausted) {
+        return subscore("route_selected", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_SELECTED_V1, 0.0, "high", {
+            detail: "router exhausted all providers",
+        });
+    }
+    if (metrics.provider_selected === null) {
+        return skippedSubscore("route_selected", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_SELECTED_V1, "no selected provider");
+    }
+    const status = metrics.router_child_status;
+    const score = status === "done" ? 1.0 : status === "blocked" ? 0.0 : 0.5;
+    return subscore("route_selected", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_SELECTED_V1, score, "high", {
+        detail: `selected_provider=${metrics.provider_selected}, child_status=${status ?? "unknown"}`,
+    });
+}
+function scoreRouteCandidates(metrics) {
+    const count = metrics.router_candidates_count;
+    if (count === null)
+        return skippedSubscore("candidates", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_CANDIDATES_V1, "no candidate count");
+    if (count === 0) {
+        return subscore("candidates", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_CANDIDATES_V1, 0.0, "low", {
+            detail: "candidates=0",
+        });
+    }
+    // 1 candidate = 0.5; 2 = 0.75; 3+ = 1.0
+    const score = count >= 3 ? 1.0 : count === 2 ? 0.75 : 0.5;
+    return subscore("candidates", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_CANDIDATES_V1, score, count > 0 ? "high" : "low", {
+        detail: `candidates=${count}`,
+    });
+}
+function scoreRouteFallbackPath(metrics) {
+    if (metrics.router_exhausted) {
+        return subscore("fallback_path", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_FALLBACK_PATH_V1, 0.0, "high", {
+            detail: "fallback exhausted",
+        });
+    }
+    if (!metrics.router_fallback_used) {
+        return subscore("fallback_path", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_FALLBACK_PATH_V1, 1.0, "high", {
+            detail: "no fallback used",
+        });
+    }
+    const status = metrics.router_child_status;
+    const score = status === "done" ? 0.5 : 0.0;
+    return subscore("fallback_path", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_FALLBACK_PATH_V1, score, "high", {
+        detail: `fallback_used=true, child_status=${status ?? "unknown"}`,
+    });
+}
+function scoreRouteOutcomeQuality(metrics) {
+    const status = metrics.router_child_status;
+    const validation = metrics.router_child_validation;
+    if (status === null && validation === null) {
+        return skippedSubscore("outcome_quality", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_OUTCOME_QUALITY_V1, "no child outcome for routing decision");
+    }
+    if (status === "done" && validation === "passed")
+        return subscore("outcome_quality", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_OUTCOME_QUALITY_V1, 1.0, "high", { detail: "status=done, validation=passed" });
+    if (status === "done")
+        return subscore("outcome_quality", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_OUTCOME_QUALITY_V1, 0.75, "high", { detail: `status=done, validation=${validation ?? "unknown"}` });
+    if (status === "blocked")
+        return subscore("outcome_quality", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_OUTCOME_QUALITY_V1, 0.0, "high", { detail: "status=blocked" });
+    return subscore("outcome_quality", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_OUTCOME_QUALITY_V1, 0.25, "high", { detail: `status=${status ?? "unknown"}, validation=${validation ?? "unknown"}` });
+}
+function scoreRouteTokenBurn(metrics) {
+    const tokens = metrics.worker_tokens_used;
+    if (tokens === null) {
+        return skippedSubscore("token_burn", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_TOKEN_BURN_V1, "no token data for routed child");
+    }
+    const BUDGET = sol_scorecard_js_1.WORKER_TOKEN_EFFICIENCY_SPEC.budget;
+    const MAX_PENALIZED = sol_scorecard_js_1.WORKER_TOKEN_EFFICIENCY_SPEC.max_penalized;
+    const score = tokens <= BUDGET ? 1.0 : clamp01(1.0 - (tokens - BUDGET) / (MAX_PENALIZED - BUDGET));
+    return subscore("token_burn", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_TOKEN_BURN_V1, Number(score.toFixed(4)), "high", {
+        detail: `tokens=${tokens}`,
+    });
+}
+function scoreRouteQcResult(metrics) {
+    const total = metrics.qc_total_findings;
+    if (total === null)
+        return skippedSubscore("qc_result", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_QC_RESULT_V1, "no QC evidence");
+    const blocking = metrics.qc_blocking_findings ?? 0;
+    if (blocking > 0) {
+        return subscore("qc_result", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_QC_RESULT_V1, 0.0, "high", {
+            detail: `blocking_findings=${blocking}`,
+        });
+    }
+    if (total > 0) {
+        return subscore("qc_result", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_QC_RESULT_V1, 0.5, "high", {
+            detail: `total_findings=${total}, blocking=0`,
+        });
+    }
+    return subscore("qc_result", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_QC_RESULT_V1, 1.0, "high", { detail: "no QC findings" });
+}
+function scoreRouteValidationResult(metrics) {
+    const outcome = metrics.router_child_validation ?? metrics.validation_outcome;
+    if (outcome === null) {
+        return skippedSubscore("validation_result", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_VALIDATION_RESULT_V1, "no validation outcome for routed child");
+    }
+    if (outcome === "passed")
+        return subscore("validation_result", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_VALIDATION_RESULT_V1, 1.0, "high", { detail: "validation=passed" });
+    if (outcome === "failed")
+        return subscore("validation_result", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_VALIDATION_RESULT_V1, 0.0, "high", { detail: "validation=failed" });
+    return subscore("validation_result", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_VALIDATION_RESULT_V1, 0.5, "medium", { detail: `validation=${outcome}` });
+}
+function scoreRouteConfirmedSignal(metrics) {
+    const status = metrics.router_child_status;
+    const validation = metrics.router_child_validation;
+    if (status === null || validation === null) {
+        return skippedSubscore("confirmed_signal", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_CONFIRMED_SIGNAL_V1, "no child outcome to confirm");
+    }
+    // A "confirmed" signal = selected route led to done+passed.
+    // A "contradicted" signal = selected route exists but child failed/blocked.
+    const confirmed = status === "done" && validation === "passed";
+    const contradicted = status === "blocked" || validation === "failed";
+    if (confirmed) {
+        return subscore("confirmed_signal", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_CONFIRMED_SIGNAL_V1, 1.0, "high", { detail: "outcome confirmed: done+passed" });
+    }
+    if (contradicted) {
+        return subscore("confirmed_signal", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_CONFIRMED_SIGNAL_V1, 0.0, "high", { detail: "outcome contradicted" });
+    }
+    return subscore("confirmed_signal", sol_scorecard_js_1.SOL_FORMULA_VERSIONS.ROUTE_CONFIRMED_SIGNAL_V1, 0.5, "medium", { detail: "outcome inconclusive" });
+}
+/**
+ * Compute a scorecard for one routing decision.
+ */
+function computeRoutingScorecard(ev, decision, sourceRefs, groupingKeys) {
+    const rawMetrics = buildRoutingRawMetrics(ev, decision);
+    const subscores = [
+        scoreRouteSelected(rawMetrics),
+        scoreRouteCandidates(rawMetrics),
+        scoreRouteFallbackPath(rawMetrics),
+        scoreRouteOutcomeQuality(rawMetrics),
+        scoreRouteTokenBurn(rawMetrics),
+        scoreRouteQcResult(rawMetrics),
+        scoreRouteValidationResult(rawMetrics),
+        scoreRouteConfirmedSignal(rawMetrics),
+    ];
+    const key = decision.child_id || `${decision.selected_provider ?? "unknown"}-${decision.providers_tried.join(",")}`;
+    return buildScorecard("routing", key, ev, rawMetrics, subscores, sourceRefs ?? defaultSourceRefs(ev), groupingKeys);
+}
+/**
+ * Compute the full set of scorecards for a run.
+ */
+function computeAllScorecards(ev, sourceRefs) {
+    const refs = sourceRefs ?? defaultSourceRefs(ev);
+    const foreman = computeForemanScorecard(ev, refs);
+    const workers = ev.children
+        .map((c) => computeWorkerScorecard(ev, c.child_id, refs))
+        .filter((s) => s !== null);
+    const providerKeys = new Set();
+    for (const child of ev.children) {
+        if (child.provider)
+            providerKeys.add(child.provider);
+    }
+    for (const decision of ev.router.decisions) {
+        if (decision.selected_provider)
+            providerKeys.add(decision.selected_provider);
+        for (const provider of decision.providers_tried) {
+            if (provider)
+                providerKeys.add(provider);
+        }
+    }
+    const providers = Array.from(providerKeys).map((provider) => computeProviderScorecard(ev, provider, refs));
+    const models = Array.from(new Set(ev.children.map((c) => c.grouping_keys.model).filter((m) => !!m)))
+        .map((model) => computeModelScorecard(ev, model, refs));
+    const routing = ev.router.availability === "available"
+        ? ev.router.decisions.map((d) => computeRoutingScorecard(ev, d, refs))
+        : [];
+    return { foreman, workers, providers, models, routing };
+}