agentic-qe 3.11.0 → 3.11.1

package/dist/mcp/tool-scoping.d.ts

@@ -9,13 +9,19 @@ export type AgentRole = 'test-generator' | 'coverage-analyzer' | 'security-scann
  * Tool scope definition for an agent role
  */
 export interface ToolScope {
-    /** Tools the agent can use (if empty/undefined, uses allowAll) */
+    /**
+     * Tools the agent can use. DEFAULT-DENY: if this is empty/undefined and
+     * `allowAll` is not set, the role is denied EVERY tool (`isToolAllowed`
+     * falls through to `return false`). It does NOT grant allowAll.
+     */
     allowed?: string[];
     /** Tools explicitly denied (overrides allowed) */
     denied?: string[];
-    /** Allow all tools (default for fleet-admin and unrestricted) */
+    /** Allow all tools — admin tiers only (fleet-admin, unrestricted). */
     allowAll?: boolean;
 }
+/** Every agent role, in declaration order — for governance/policy iteration. */
+export declare const ALL_AGENT_ROLES: AgentRole[];
 /**
  * Check if an agent role is allowed to use a specific tool
  */

package/dist/mcp/tool-scoping.js

@@ -4,6 +4,19 @@
  * Restricts MCP tool access by agent role for security isolation.
  * Each agent type has a defined set of tools it can invoke.
  */
+/** Every agent role, in declaration order — for governance/policy iteration. */
+export const ALL_AGENT_ROLES = [
+    'test-generator',
+    'coverage-analyzer',
+    'security-scanner',
+    'quality-assessor',
+    'defect-predictor',
+    'contract-validator',
+    'accessibility-tester',
+    'chaos-engineer',
+    'fleet-admin',
+    'unrestricted',
+];
 /**
  * Default tool scopes per agent role
  */

package/dist/routing/free-tier/coordinator-support.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Coordinator free-tier support (cross-pollination plan 06 — broadening the
+ * opt-in beyond test generation; ADR-111 escalation lane).
+ *
+ * Extracts the generic "build a FreeTierEscalatingExecutor from a coordinator's
+ * config + router" wiring that was inline in the test-generation coordinator, so
+ * ANY domain coordinator can opt in with a few lines instead of duplicating it.
+ *
+ * The opt-in lane is justified only for tasks that match the D3 criterion:
+ * BOUNDED generation graded by an OBJECTIVE oracle (a test+assertion, valid
+ * Gherkin, a schema). Do NOT wire it into analysis/judgement coordinators — the
+ * §11 "coder binds" finding means a cheap model can't carry open-ended reasoning.
+ */
+import { FreeTierEscalatingExecutor, type QeExecutionResult, type QeVerifier } from './executor.js';
+import { type RoutingFeedbackLike } from './feedback-sink.js';
+import type { FreeTierProviderConfig } from './types.js';
+/** Default cheap tier. qwen3:30b-a3b, NOT qwen3:8b — D3 (2026-06-23) measured the
+ *  8B below the QE generation floor (0/3 baseline-valid); the 30B MoE clears it. */
+export declare const DEFAULT_FREE_TIER_MODEL = "qwen3:30b-a3b";
+/** Per-coordinator config knobs (mix into a coordinator's CoordinatorConfig). */
+export interface FreeTierCoordinatorConfig {
+    /** Opt-in the cheap-first free local tier. Also via env `AQE_FREE_TIER=1`. */
+    enableFreeTier?: boolean;
+    /** Local model id (default {@link DEFAULT_FREE_TIER_MODEL} or env AQE_FREE_TIER_MODEL). */
+    freeTierModel?: string;
+    /** Default same-tier D8 repair retries before escalating. Benchmarked at 2 (D3). */
+    freeTierRepairAttempts?: number;
+    /**
+     * Best-of-k diverse attempts per tier's first round (06 §12). D3 validated k=2
+     * (lifted cheap composite +16.7, baseline-valid 50%→70%). Costs an extra local
+     * call ONLY when variant 0 fails (the loop breaks on first pass). Default 2.
+     */
+    freeTierBestOfK?: number;
+    /**
+     * Cross-model best-of-k generator pool (A12, measured +6 composite over single-
+     * model via mutual validity rescue). When set, round-0 best-of-k draws candidates
+     * across these providers (e.g. local qwen + an OpenRouter model) instead of one
+     * model's variants. Omit ⇒ single-model. Set `freeTierBestOfK ≥ pool size`.
+     */
+    freeTierCandidateProviders?: FreeTierProviderConfig[];
+}
+/** Structural view of the HybridRouter — avoids a hard import (decoupling). */
+export interface FreeTierLlmRouter {
+    chat(args: {
+        messages: Array<{
+            role: 'system' | 'user' | 'assistant';
+            content: string;
+        }>;
+        agentType: string;
+        complexity: 'low' | 'medium' | 'high';
+    }): Promise<{
+        content: string;
+    }>;
+}
+export interface BuildFreeTierExecutorOptions {
+    config: FreeTierCoordinatorConfig;
+    /** Router agentType hint for escalated (paid) tiers, e.g. 'qe-test-architect'. */
+    agentType: string;
+    /** D9 sink label, e.g. 'test-generation'. */
+    taskKind: string;
+    /** Delegate Claude tiers to the host router; omit → local-only (no escalation). */
+    llmRouter?: FreeTierLlmRouter | null;
+    /** D9: feed cheap-vs-escalated outcomes into routing-feedback. */
+    routingFeedback?: RoutingFeedbackLike | null;
+    env?: NodeJS.ProcessEnv;
+    logger?: {
+        info: (m: string) => void;
+    };
+}
+/**
+ * Build a cheap-first escalating executor from coordinator config + (optional)
+ * router. Returns `null` when the free tier is not opted in — callers store the
+ * result and fall through to their normal path when it is null.
+ */
+export declare function buildFreeTierExecutor(opts: BuildFreeTierExecutorOptions): FreeTierEscalatingExecutor | null;
+/**
+ * Run one bounded generation task cheap-first: best-of-k diverse attempts +
+ * D8 repair on the local tier, escalating the hard tail. Returns `null` when no
+ * executor (not opted in). The `verify` MUST be an objective oracle (06 §10).
+ */
+export declare function runFreeTierTextTask(executor: FreeTierEscalatingExecutor | null, args: {
+    agentId: string;
+    system: string;
+    user: string;
+    verify: QeVerifier;
+    repairAttempts?: number;
+    escalate?: boolean;
+    bestOfK?: number;
+}): Promise<QeExecutionResult | null>;
+//# sourceMappingURL=coordinator-support.d.ts.map

package/dist/routing/free-tier/coordinator-support.js

@@ -0,0 +1,78 @@
+/**
+ * Coordinator free-tier support (cross-pollination plan 06 — broadening the
+ * opt-in beyond test generation; ADR-111 escalation lane).
+ *
+ * Extracts the generic "build a FreeTierEscalatingExecutor from a coordinator's
+ * config + router" wiring that was inline in the test-generation coordinator, so
+ * ANY domain coordinator can opt in with a few lines instead of duplicating it.
+ *
+ * The opt-in lane is justified only for tasks that match the D3 criterion:
+ * BOUNDED generation graded by an OBJECTIVE oracle (a test+assertion, valid
+ * Gherkin, a schema). Do NOT wire it into analysis/judgement coordinators — the
+ * §11 "coder binds" finding means a cheap model can't carry open-ended reasoning.
+ */
+import { FreeTierEscalatingExecutor } from './executor.js';
+import { defaultFreeTierLadder } from './ladder.js';
+import { createRoutingFeedbackSink } from './feedback-sink.js';
+/** Default cheap tier. qwen3:30b-a3b, NOT qwen3:8b — D3 (2026-06-23) measured the
+ *  8B below the QE generation floor (0/3 baseline-valid); the 30B MoE clears it. */
+export const DEFAULT_FREE_TIER_MODEL = 'qwen3:30b-a3b';
+/**
+ * Build a cheap-first escalating executor from coordinator config + (optional)
+ * router. Returns `null` when the free tier is not opted in — callers store the
+ * result and fall through to their normal path when it is null.
+ */
+export function buildFreeTierExecutor(opts) {
+    const env = opts.env ?? process.env;
+    const on = opts.config.enableFreeTier === true || env.AQE_FREE_TIER === '1';
+    if (!on)
+        return null;
+    const model = opts.config.freeTierModel || env.AQE_FREE_TIER_MODEL || DEFAULT_FREE_TIER_MODEL;
+    // Paid escalation: map the ladder tier to a complexity hint so the host router
+    // picks that tier. No router → executor stays local-only (Claude tiers unavailable).
+    const claudeRunner = opts.llmRouter
+        ? async (tier, msgs) => {
+            const complexity = tier === 'opus' ? 'high' : tier === 'sonnet' ? 'medium' : 'low';
+            const resp = await opts.llmRouter.chat({
+                messages: msgs.map((m) => ({ role: m.role, content: m.content })),
+                agentType: opts.agentType,
+                complexity,
+            });
+            return { content: resp.content };
+        }
+        : undefined;
+    const exec = new FreeTierEscalatingExecutor({
+        ladder: defaultFreeTierLadder(model),
+        claudeRunner,
+        defaultRepairAttempts: opts.config.freeTierRepairAttempts ?? 1,
+        candidateProviders: opts.config.freeTierCandidateProviders, // A12 cross-model (off unless set)
+        onOutcome: opts.routingFeedback
+            ? createRoutingFeedbackSink(opts.routingFeedback, { taskKind: opts.taskKind })
+            : undefined,
+    });
+    opts.logger?.info(`Free-tier enabled for ${opts.taskKind} (model=${model}, ` +
+        `${claudeRunner ? 'escalation→router' : 'local-only'})`);
+    return exec;
+}
+/**
+ * Run one bounded generation task cheap-first: best-of-k diverse attempts +
+ * D8 repair on the local tier, escalating the hard tail. Returns `null` when no
+ * executor (not opted in). The `verify` MUST be an objective oracle (06 §10).
+ */
+export async function runFreeTierTextTask(executor, args) {
+    if (!executor)
+        return null;
+    return executor.execute({
+        agentId: args.agentId,
+        messages: [
+            { role: 'system', content: args.system },
+            { role: 'user', content: args.user },
+        ],
+        verify: args.verify,
+        repairAttempts: args.repairAttempts,
+        escalate: args.escalate ?? true,
+        bestOfK: args.bestOfK,
+        oracleKind: 'objective',
+    });
+}
+//# sourceMappingURL=coordinator-support.js.map

package/dist/routing/free-tier/executor.d.ts

@@ -16,7 +16,7 @@
  */
 import { type ChatMessage } from './provider.js';
 import { AutoEscalationTracker } from '../escalation/auto-escalation-tracker.js';
-import type { QeRoutingLadder } from './types.js';
+import type { QeRoutingLadder, FreeTierProviderConfig } from './types.js';
 import type { AgentTier } from '../routing-config.js';
 /** Serves a Claude tier. Injected by the host (e.g. delegates to HybridRouter). */
 export type ClaudeTierRunner = (claudeTier: AgentTier, messages: ChatMessage[]) => Promise<{
@@ -43,12 +43,30 @@ export interface QeTaskRequest {
     escalate?: boolean;
     /** Cap on tiers tried for one task (default: full ladder). */
     maxEscalations?: number;
+    /**
+     * Best-of-k diverse attempts at each tier's first round (06 §12 correction).
+     * Ruv's ablation: a single repro-gated shot Goodharts the oracle (0 gold); k>1
+     * diverse attempts picked by the objective verifier are what convert. Default 1.
+     */
+    bestOfK?: number;
+    /**
+     * Goodhart guard (06 §10). `objective` = the verifier is a deterministic
+     * ground-truth oracle (arena/coverage/schema). `self-authored` = the verifier
+     * is the model's own test — an unreliable selection target, so its outcomes are
+     * NOT recorded into routing-feedback (they must not lift confidence). Default
+     * `objective` (existing callers inject real oracles, e.g. a coverage/test run).
+     */
+    oracleKind?: 'objective' | 'self-authored';
 }
 export interface TierAttempt {
     tier: string;
     provider: 'free-tier' | 'claude';
     /** 0 = first try at this tier; 1.. = repair rounds (D8). */
     repairRound: number;
+    /** Best-of-k variant index within round 0 (0 = primary, 1.. = diversified). */
+    variant?: number;
+    /** Generator model that produced this candidate (set for cross-model best-of-k). */
+    model?: string;
     ok: boolean;
     passed: boolean;
     latencyMs: number;
@@ -66,6 +84,13 @@ export interface QeExecutionResult {
     escalated: boolean;
     /** True iff a same-tier repair round produced the passing output. */
     repaired: boolean;
+    /** True iff best-of-k (k>1) diversity at a round produced the passing output. */
+    bestOf: boolean;
+    /**
+     * True iff the outcome was withheld from routing-feedback because the gate was
+     * a self-authored oracle (06 §10 Goodhart guard) — it cannot lift confidence.
+     */
+    goodhartGuarded: boolean;
     /** Per-attempt trace, cheapest → most capable. */
     attempts: TierAttempt[];
 }
@@ -79,6 +104,15 @@ export interface FreeTierExecutorOptions {
     env?: NodeJS.ProcessEnv;
     /** Default same-tier repair retries when a request omits `repairAttempts`. */
     defaultRepairAttempts?: number;
+    /**
+     * Cross-model best-of-k (A12, measured +6 composite over single-model). When set
+     * AND the START tier is free-tier, round-0 best-of-k draws each candidate from a
+     * DIFFERENT provider in this pool (e.g. local qwen + an OpenRouter model) instead
+     * of one model's temperature/prompt variants — diverse models cover each other's
+     * failures and raise the union. Selection stays the objective verifier (first-pass).
+     * Omit ⇒ single-model best-of-k (unchanged).
+     */
+    candidateProviders?: FreeTierProviderConfig[];
     /** D9 sink: record each completed task outcome (→ routing-feedback). */
     onOutcome?: (o: {
         agentId: string;
@@ -103,11 +137,19 @@ export declare class FreeTierEscalatingExecutor {
     private readonly baseTier;
     private readonly defaultRepairAttempts;
     private readonly onOutcome?;
+    /** Resolved cross-model generator pool (A12); undefined ⇒ single-model best-of-k. */
+    private readonly candidateProviders?;
     constructor(opts: FreeTierExecutorOptions);
     /** Expose the tracker so a coordinator can inspect/share adaptation state. */
     getTracker(): AutoEscalationTracker<string>;
     /** Run ONE tier once; never throws — failure becomes `{ok:false}` so we repair/escalate. */
     private runTier;
+    /**
+     * Best-of-k diversity turn (06 §12): nudge the model toward a structurally
+     * different valid solution. Deterministic by `variant` index (no RNG) so runs
+     * replay identically.
+     */
+    private diversify;
     /** Build the D8 repair turn: show the model its rejected output + why. */
     private repairMessages;
     /**

package/dist/routing/free-tier/executor.js

@@ -14,7 +14,7 @@
  * its HybridRouter). No runner → local-only. `escalate:false` = repair-only,
  * never leaves the start tier (the "no escalation yet" mode).
  */
-import { freeTierChat } from './provider.js';
+import { freeTierChat, resolveFreeTierProvider } from './provider.js';
 import { resolveTier } from './ladder.js';
 import { AutoEscalationTracker } from '../escalation/auto-escalation-tracker.js';
 function normalizeVerdict(v) {
@@ -32,6 +32,8 @@ export class FreeTierEscalatingExecutor {
     baseTier;
     defaultRepairAttempts;
     onOutcome;
+    /** Resolved cross-model generator pool (A12); undefined ⇒ single-model best-of-k. */
+    candidateProviders;
     constructor(opts) {
         this.ladder = opts.ladder;
         this.claudeRunner = opts.claudeRunner;
@@ -39,6 +41,9 @@ export class FreeTierEscalatingExecutor {
         this.onOutcome = opts.onOutcome;
         this.defaultRepairAttempts = opts.defaultRepairAttempts ?? 0;
         this.baseTier = opts.ladder.tierOrder[0];
+        this.candidateProviders = opts.candidateProviders?.length
+            ? opts.candidateProviders.map((c) => resolveFreeTierProvider(c, this.env))
+            : undefined;
         this.tracker =
             opts.tracker ??
                 new AutoEscalationTracker({
@@ -71,6 +76,21 @@ export class FreeTierEscalatingExecutor {
             return { ok: false, content: '', latencyMs: Date.now() - started, error: e.message };
         }
     }
+    /**
+     * Best-of-k diversity turn (06 §12): nudge the model toward a structurally
+     * different valid solution. Deterministic by `variant` index (no RNG) so runs
+     * replay identically.
+     */
+    diversify(base, variant) {
+        return [
+            ...base,
+            {
+                role: 'user',
+                content: `Alternative approach #${variant}: produce a different valid solution from any ` +
+                    `previous attempt — vary the structure/strategy, not just naming. Return the full output only.`,
+            },
+        ];
+    }
     /** Build the D8 repair turn: show the model its rejected output + why. */
     repairMessages(base, lastOutput, feedback) {
         return [
@@ -92,6 +112,8 @@ export class FreeTierEscalatingExecutor {
         const order = this.ladder.tierOrder;
         const escalate = req.escalate ?? true;
         const repairAttempts = req.repairAttempts ?? this.defaultRepairAttempts;
+        const bestOfK = Math.max(1, req.bestOfK ?? 1);
+        const objectiveOracle = (req.oracleKind ?? 'objective') === 'objective';
         const startTier = this.tracker.getCurrentTier(req.agentId) ?? this.baseTier;
         const startIdx = Math.max(0, order.indexOf(startTier));
         const maxIdx = order.indexOf(this.ladder.maxTier ?? order[order.length - 1]);
@@ -101,38 +123,59 @@ export class FreeTierEscalatingExecutor {
         const attempts = [];
         let passedAtStart = false;
         const t0 = Date.now();
-        let result = { ok: false, content: '', tierUsed: startTier, escalated: false, repaired: false, attempts };
+        let result = { ok: false, content: '', tierUsed: startTier, escalated: false, repaired: false, bestOf: false, goodhartGuarded: false, attempts };
         outer: for (let idx = startIdx; idx <= topIdx; idx++) {
             const tier = order[idx];
             const resolved = resolveTier(this.ladder, tier, this.env);
-            // first try (round 0) + up to `repairAttempts` repair rounds
+            // round 0 = best-of-k diverse attempts (06 §12); rounds 1..repairAttempts = single repair turns (D8)
+            // A12: at the START free tier, round-0 candidates draw from a CROSS-MODEL pool
+            // (diverse models cover each other's failures) instead of one model's variants.
+            const pool = this.candidateProviders;
+            const xModelHere = !!pool && idx === startIdx && resolved.provider === 'free-tier';
             for (let round = 0; round <= repairAttempts; round++) {
-                const messages = round === 0 ? req.messages : this.repairMessages(req.messages, result.content, attempts[attempts.length - 1]?.feedback);
-                const run = await this.runTier(resolved, messages);
-                const verdict = run.ok ? normalizeVerdict(await Promise.resolve(req.verify(run.content))) : { passed: false, feedback: run.error };
-                attempts.push({ tier, provider: resolved.provider, repairRound: round, ok: run.ok, passed: verdict.passed, latencyMs: run.latencyMs, feedback: verdict.feedback, error: run.error });
-                if (idx === startIdx && round === 0)
-                    passedAtStart = verdict.passed;
-                if (verdict.passed) {
-                    result = { ok: true, content: run.content, tierUsed: tier, escalated: idx > startIdx, repaired: round > 0, attempts };
-                    break outer;
+                const attemptsThisRound = round === 0 ? bestOfK : 1;
+                for (let k = 0; k < attemptsThisRound; k++) {
+                    const candProvider = round === 0 && xModelHere && pool ? pool[k % pool.length] : undefined;
+                    const candResolved = candProvider ? { provider: 'free-tier', resolved: candProvider } : resolved;
+                    const messages = round !== 0
+                        ? this.repairMessages(req.messages, result.content, attempts[attempts.length - 1]?.feedback)
+                        : candProvider
+                            // model difference IS the diversity; only nudge when k wraps past the pool
+                            ? (pool && k < pool.length ? req.messages : this.diversify(req.messages, k))
+                            : (k === 0 ? req.messages : this.diversify(req.messages, k));
+                    const run = await this.runTier(candResolved, messages);
+                    const verdict = run.ok ? normalizeVerdict(await Promise.resolve(req.verify(run.content))) : { passed: false, feedback: run.error };
+                    attempts.push({ tier, provider: candResolved.provider, repairRound: round, variant: round === 0 ? k : undefined, model: candProvider?.model, ok: run.ok, passed: verdict.passed, latencyMs: run.latencyMs, feedback: verdict.feedback, error: run.error });
+                    // start-tier capability for adaptation: did ANY round-0 attempt pass?
+                    if (idx === startIdx && round === 0 && verdict.passed)
+                        passedAtStart = true;
+                    if (verdict.passed) {
+                        result = { ok: true, content: run.content, tierUsed: tier, escalated: idx > startIdx, repaired: round > 0, bestOf: round === 0 && k > 0, goodhartGuarded: false, attempts };
+                        break outer;
+                    }
+                    result = { ok: false, content: run.content || result.content, tierUsed: tier, escalated: idx > startIdx, repaired: round > 0, bestOf: false, goodhartGuarded: false, attempts };
                 }
-                result = { ok: false, content: run.content || result.content, tierUsed: tier, escalated: idx > startIdx, repaired: round > 0, attempts };
             }
         }
-        // Cross-task adaptation: feed the START-tier verdict to the tracker so the
-        // base tier drifts up when the cheap tier keeps failing, down when it wins.
-        this.tracker.recordOutcome(req.agentId, passedAtStart, this.baseTier);
-        this.onOutcome?.({
-            agentId: req.agentId,
-            startTier,
-            tierUsed: result.tierUsed,
-            passed: result.ok,
-            escalated: result.escalated,
-            repaired: result.repaired,
-            durationMs: Date.now() - t0,
-            attempts: attempts.length,
-        });
+        // Goodhart guard (06 §10): only an OBJECTIVE ground-truth oracle may move
+        // routing-feedback. A self-authored gate is an unreliable selection target —
+        // record nothing, so a Goodharted self-test pass can never lift confidence.
+        result.goodhartGuarded = !objectiveOracle;
+        if (objectiveOracle) {
+            // Cross-task adaptation: feed the START-tier verdict to the tracker so the
+            // base tier drifts up when the cheap tier keeps failing, down when it wins.
+            this.tracker.recordOutcome(req.agentId, passedAtStart, this.baseTier);
+            this.onOutcome?.({
+                agentId: req.agentId,
+                startTier,
+                tierUsed: result.tierUsed,
+                passed: result.ok,
+                escalated: result.escalated,
+                repaired: result.repaired,
+                durationMs: Date.now() - t0,
+                attempts: attempts.length,
+            });
+        }
         return result;
     }
 }

package/dist/routing/free-tier/index.d.ts

@@ -11,4 +11,5 @@ export { FREE_TIER_PRESETS, resolveFreeTierProvider, freeTierChat, freeTierHealt
 export { defaultFreeTierLadder, validateLadder, createFreeTierEscalation, resolveTier, type ResolvedTier, } from './ladder.js';
 export { FreeTierEscalatingExecutor, type ClaudeTierRunner, type QeVerifier, type QeVerdict, type QeTaskRequest, type QeExecutionResult, type TierAttempt, type FreeTierExecutorOptions, } from './executor.js';
 export { createRoutingFeedbackSink, type RoutingFeedbackLike, type FreeTierOutcomeEvent, type RoutingFeedbackSinkOptions, } from './feedback-sink.js';
+export { buildFreeTierExecutor, runFreeTierTextTask, DEFAULT_FREE_TIER_MODEL, type FreeTierCoordinatorConfig, type FreeTierLlmRouter, type BuildFreeTierExecutorOptions, } from './coordinator-support.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/routing/free-tier/index.js

@@ -2,4 +2,5 @@ export { FREE_TIER_PRESETS, resolveFreeTierProvider, freeTierChat, freeTierHealt
 export { defaultFreeTierLadder, validateLadder, createFreeTierEscalation, resolveTier, } from './ladder.js';
 export { FreeTierEscalatingExecutor, } from './executor.js';
 export { createRoutingFeedbackSink, } from './feedback-sink.js';
+export { buildFreeTierExecutor, runFreeTierTextTask, DEFAULT_FREE_TIER_MODEL, } from './coordinator-support.js';
 //# sourceMappingURL=index.js.map

package/dist/routing/value-score.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Cost-Pareto Value Score (plan 05 / A13).
+ *
+ * Ruv's leaderboard lesson (ADR-179): rank by quality-PER-DOLLAR, not absolute
+ * quality. This operationalizes ADR-111's "competitive QE quality cheaper than
+ * frontier" — pure functions to (a) compute a tunable value score, (b) rank a
+ * candidate pool, and (c) extract the cost-Pareto frontier (the non-dominated set
+ * a router should choose from). Pure + dependency-free.
+ *
+ * Companion: model→QE-role fit must be MEASURED, not assumed (the qwen3-coder
+ * leaderboard-rank-did-not-transfer lesson). {@link MEASURED_QE_TEST_GEN} is a
+ * dated snapshot from D3/A12; the router should refresh it from routing-feedback.
+ */
+export interface ModelEconomics {
+    model: string;
+    /** Measured QE quality on the role, 0..1 (e.g. ADR-104 composite). NOT a vendor claim. */
+    quality: number;
+    /** USD per instance (0 for free/local tiers). */
+    costPerInstance: number;
+}
+export interface ValueScoreOptions {
+    /** 0 = rank by pure quality, 1 = pure cost-efficiency. Default 0.5 (the slider). */
+    costWeight?: number;
+    /** USD ceiling to normalize cost into [0,1]. Default = max cost in the set (or the value's own cost). */
+    costCap?: number;
+}
+/**
+ * Value score in [0,1]: a `costWeight`-weighted blend of quality and cost-
+ * efficiency (1 − normalizedCost). A $0 tier has perfect cost-efficiency, so its
+ * value is dominated by its quality.
+ */
+export declare function valueScore(m: ModelEconomics, opts?: ValueScoreOptions): number;
+/** Rank a candidate pool by value score (desc). Cost is normalized across the pool. */
+export declare function rankByValue<T extends ModelEconomics>(models: T[], opts?: ValueScoreOptions): Array<T & {
+    value: number;
+}>;
+/**
+ * The cost-Pareto frontier: models NOT dominated by another (none is both
+ * cheaper AND ≥ quality). These are the only rational router choices — everything
+ * else is strictly worse on both axes. Sorted cheapest → most expensive.
+ */
+export declare function paretoFrontier<T extends ModelEconomics>(models: T[]): T[];
+/**
+ * MEASURED QE test-generation economics (snapshot 2026-06-24, D3/A12). Quality =
+ * composite (0.6·killRate + 0.3·coverage) on the 5-module corpus; cost is the
+ * per-instance estimate. NOT vendor claims — refresh from routing-feedback.
+ */
+export declare const MEASURED_QE_TEST_GEN: readonly ModelEconomics[];
+//# sourceMappingURL=value-score.d.ts.map

package/dist/routing/value-score.js

@@ -0,0 +1,54 @@
+/**
+ * Cost-Pareto Value Score (plan 05 / A13).
+ *
+ * Ruv's leaderboard lesson (ADR-179): rank by quality-PER-DOLLAR, not absolute
+ * quality. This operationalizes ADR-111's "competitive QE quality cheaper than
+ * frontier" — pure functions to (a) compute a tunable value score, (b) rank a
+ * candidate pool, and (c) extract the cost-Pareto frontier (the non-dominated set
+ * a router should choose from). Pure + dependency-free.
+ *
+ * Companion: model→QE-role fit must be MEASURED, not assumed (the qwen3-coder
+ * leaderboard-rank-did-not-transfer lesson). {@link MEASURED_QE_TEST_GEN} is a
+ * dated snapshot from D3/A12; the router should refresh it from routing-feedback.
+ */
+const clamp01 = (x) => Math.max(0, Math.min(1, x));
+/**
+ * Value score in [0,1]: a `costWeight`-weighted blend of quality and cost-
+ * efficiency (1 − normalizedCost). A $0 tier has perfect cost-efficiency, so its
+ * value is dominated by its quality.
+ */
+export function valueScore(m, opts = {}) {
+    const costWeight = clamp01(opts.costWeight ?? 0.5);
+    const cap = opts.costCap && opts.costCap > 0 ? opts.costCap : Math.max(m.costPerInstance, 1e-9);
+    const costEfficiency = clamp01(1 - m.costPerInstance / cap);
+    return clamp01((1 - costWeight) * clamp01(m.quality) + costWeight * costEfficiency);
+}
+/** Rank a candidate pool by value score (desc). Cost is normalized across the pool. */
+export function rankByValue(models, opts = {}) {
+    const cap = opts.costCap && opts.costCap > 0 ? opts.costCap : Math.max(...models.map((m) => m.costPerInstance), 1e-9);
+    return models
+        .map((m) => ({ ...m, value: valueScore(m, { ...opts, costCap: cap }) }))
+        .sort((a, b) => b.value - a.value);
+}
+/**
+ * The cost-Pareto frontier: models NOT dominated by another (none is both
+ * cheaper AND ≥ quality). These are the only rational router choices — everything
+ * else is strictly worse on both axes. Sorted cheapest → most expensive.
+ */
+export function paretoFrontier(models) {
+    const dominated = (m) => models.some((o) => o !== m && o.costPerInstance <= m.costPerInstance && o.quality >= m.quality &&
+        (o.costPerInstance < m.costPerInstance || o.quality > m.quality));
+    return models.filter((m) => !dominated(m)).sort((a, b) => a.costPerInstance - b.costPerInstance);
+}
+/**
+ * MEASURED QE test-generation economics (snapshot 2026-06-24, D3/A12). Quality =
+ * composite (0.6·killRate + 0.3·coverage) on the 5-module corpus; cost is the
+ * per-instance estimate. NOT vendor claims — refresh from routing-feedback.
+ */
+export const MEASURED_QE_TEST_GEN = [
+    { model: 'qwen3:8b', quality: 0.0, costPerInstance: 0 }, // D3: below the generation floor (0/3 valid)
+    { model: 'qwen3:30b-a3b', quality: 0.62, costPerInstance: 0 }, // D3: clears the floor (best-of-k ~0.673 on judged)
+    { model: 'z-ai/glm-5.2', quality: 0.71, costPerInstance: 0.0065 }, // A12: diverse, higher per-model best
+    { model: 'claude-sonnet-4-6', quality: 0.83, costPerInstance: 0.045 }, // D3: frontier ceiling
+];
+//# sourceMappingURL=value-score.js.map

package/dist/shared/optional-module.d.ts

@@ -0,0 +1,23 @@
+export interface OptionalModuleAvailable<T> {
+    available: true;
+    degraded: false;
+    module: T;
+}
+export interface OptionalModuleDegraded {
+    available: false;
+    degraded: true;
+    name: string;
+    reason: string;
+}
+export type OptionalModuleResult<T> = OptionalModuleAvailable<T> | OptionalModuleDegraded;
+/** True iff `err` means the module is genuinely NOT INSTALLED (vs. failed to load). */
+export declare function isModuleAbsent(err: unknown): boolean;
+/**
+ * Load an optional module. Returns `{available:true, module}` when present,
+ * `{available:false, degraded:true}` when genuinely absent, and RE-THROWS on any
+ * other load error (so real failures are never masked). Inject `req` for testing.
+ */
+export declare function loadOptionalModule<T = unknown>(name: string, req?: NodeRequire): OptionalModuleResult<T>;
+/** Convenience: the module if available, else `undefined` (degradation is silent here). */
+export declare function optionalModule<T = unknown>(name: string, req?: NodeRequire): T | undefined;
+//# sourceMappingURL=optional-module.d.ts.map

package/dist/shared/optional-module.js

@@ -0,0 +1,46 @@
+/**
+ * Graceful optional-module loading (plan 05 / A9; ADR-150 pattern).
+ *
+ * AQE has many native/optional deps (@ruvector/{gnn,attention,sona,...},
+ * hnswlib-node, rvlite) declared in `optionalDependencies`, so a platform without
+ * a prebuilt binary (or a Dependabot-pruned lockfile) must DEGRADE, not crash.
+ *
+ * The hazard (AQE #528 lesson): the ad-hoc `try { require(x) } catch {}` scattered
+ * across the wrappers swallows EVERY error — so a binary that is PRESENT but fails
+ * to load (ABI mismatch, corrupt .node) is silently reported "unavailable",
+ * masking a real failure. This helper degrades ONLY on genuine absence
+ * (MODULE_NOT_FOUND) and RE-THROWS any other load error.
+ */
+import { createRequire } from 'node:module';
+const ABSENT_CODES = new Set(['MODULE_NOT_FOUND', 'ERR_MODULE_NOT_FOUND']);
+/** True iff `err` means the module is genuinely NOT INSTALLED (vs. failed to load). */
+export function isModuleAbsent(err) {
+    const e = err;
+    if (e?.code && ABSENT_CODES.has(e.code))
+        return true;
+    // Some loaders throw a plain Error; fall back to the canonical message shape.
+    return typeof e?.message === 'string' && /Cannot find module/.test(e.message);
+}
+const defaultRequire = createRequire(import.meta.url);
+/**
+ * Load an optional module. Returns `{available:true, module}` when present,
+ * `{available:false, degraded:true}` when genuinely absent, and RE-THROWS on any
+ * other load error (so real failures are never masked). Inject `req` for testing.
+ */
+export function loadOptionalModule(name, req = defaultRequire) {
+    try {
+        return { available: true, degraded: false, module: req(name) };
+    }
+    catch (err) {
+        if (isModuleAbsent(err)) {
+            return { available: false, degraded: true, name, reason: `optional module "${name}" not installed (running degraded)` };
+        }
+        throw err; // present but broken — do NOT mask a real failure (#528)
+    }
+}
+/** Convenience: the module if available, else `undefined` (degradation is silent here). */
+export function optionalModule(name, req) {
+    const r = loadOptionalModule(name, req);
+    return r.available ? r.module : undefined;
+}
+//# sourceMappingURL=optional-module.js.map