agentic-qe 3.11.0 → 3.11.2

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/c4-model/confidence.d.ts

@@ -0,0 +1,38 @@
+/**
+ * ADR-112 — Deterministic C4 confidence gate.
+ *
+ * Pure, code-only (NO LLM in the gate — same discipline as ADR-111's accept
+ * gate). Turns the code-intelligence detector's known limits (the
+ * qe-code-intelligence skill records ~18% success on complex queries and
+ * degradation above ~50K LOC) into an explicit, surfaced signal so a
+ * confident-but-wrong diagram is never presented as ground truth.
+ */
+export type C4Confidence = 'high' | 'medium' | 'low';
+export interface C4ConfidenceInputs {
+    /** Number of components the detector found. */
+    componentsDetected: number;
+    /** Number of component relationships (edges) detected. */
+    relationshipsDetected: number;
+    /** Number of external systems detected. */
+    externalSystemsDetected: number;
+    /** Number of source files analyzed. */
+    filesAnalyzed: number;
+    /** Total lines of code, if known (e.g. from MetricCollector). Optional. */
+    totalLoc?: number;
+}
+export interface C4ConfidenceAssessment {
+    /** Bucketed level for quick display. */
+    level: C4Confidence;
+    /** Continuous score in [0,1] the level is derived from. */
+    score: number;
+    /** Human-readable reasons (always populated). */
+    reasons: string[];
+}
+/** Repo size (LOC) beyond which the skill records detection degradation. */
+export declare const C4_LOC_DEGRADE_THRESHOLD = 50000;
+/**
+ * Assess how much to trust an auto-generated C4 diagram. Deterministic: the same
+ * inputs always yield the same level + reasons.
+ */
+export declare function assessC4Confidence(inputs: C4ConfidenceInputs): C4ConfidenceAssessment;
+//# sourceMappingURL=confidence.d.ts.map

package/dist/shared/c4-model/confidence.js

@@ -0,0 +1,69 @@
+/**
+ * ADR-112 — Deterministic C4 confidence gate.
+ *
+ * Pure, code-only (NO LLM in the gate — same discipline as ADR-111's accept
+ * gate). Turns the code-intelligence detector's known limits (the
+ * qe-code-intelligence skill records ~18% success on complex queries and
+ * degradation above ~50K LOC) into an explicit, surfaced signal so a
+ * confident-but-wrong diagram is never presented as ground truth.
+ */
+/** Repo size (LOC) beyond which the skill records detection degradation. */
+export const C4_LOC_DEGRADE_THRESHOLD = 50_000;
+const clamp01 = (x) => Math.max(0, Math.min(1, x));
+/**
+ * Assess how much to trust an auto-generated C4 diagram. Deterministic: the same
+ * inputs always yield the same level + reasons.
+ */
+export function assessC4Confidence(inputs) {
+    const { componentsDetected, relationshipsDetected, externalSystemsDetected, totalLoc } = inputs;
+    const reasons = [];
+    // Empty diagram — nothing to trust.
+    if (componentsDetected === 0) {
+        return {
+            level: 'low',
+            score: 0,
+            reasons: ['No components detected — the diagram is effectively empty; verify against the source.'],
+        };
+    }
+    let score = 0.5;
+    // Relationships are the weakest link in heuristic detection. Their presence is
+    // the strongest signal that the STRUCTURE (not just a node list) is real.
+    const relDensity = relationshipsDetected / Math.max(1, componentsDetected);
+    if (relationshipsDetected === 0 && componentsDetected > 1) {
+        score -= 0.25;
+        reasons.push('No relationships detected between components — edges are heuristic-only or missing; the structure is unverified.');
+    }
+    else if (relDensity >= 0.5) {
+        score += 0.2;
+        reasons.push(`${relationshipsDetected} relationship(s) detected across ${componentsDetected} components.`);
+    }
+    else {
+        score += 0.05;
+        reasons.push(`${relationshipsDetected} relationship(s) detected (sparse) across ${componentsDetected} components.`);
+    }
+    // External systems detected → the Platform/Interfaces picture is grounded.
+    if (externalSystemsDetected > 0) {
+        score += 0.1;
+        reasons.push(`${externalSystemsDetected} external system(s) detected from dependencies.`);
+    }
+    // Repo size vs the known degradation threshold.
+    if (totalLoc !== undefined && totalLoc > C4_LOC_DEGRADE_THRESHOLD) {
+        score -= 0.3;
+        reasons.push(`Repository is large (${totalLoc.toLocaleString()} LOC > ~${C4_LOC_DEGRADE_THRESHOLD / 1000}K) — detection accuracy degrades; treat the diagram as a draft.`);
+    }
+    // A healthy component count adds confidence; a single component is thin.
+    if (componentsDetected >= 5) {
+        score += 0.1;
+    }
+    else if (componentsDetected === 1) {
+        score -= 0.05;
+        reasons.push('Only one component detected — likely an under-segmented view.');
+    }
+    score = clamp01(score);
+    const level = score >= 0.7 ? 'high' : score >= 0.4 ? 'medium' : 'low';
+    if (level !== 'high' && !reasons.some((r) => r.includes('draft') || r.includes('verify'))) {
+        reasons.push('Auto-generated draft — verify against the source before relying on it.');
+    }
+    return { level, score: Math.round(score * 1000) / 1000, reasons };
+}
+//# sourceMappingURL=confidence.js.map

package/dist/shared/c4-model/index.d.ts

@@ -8,6 +8,8 @@
  * Based on the C4 Model by Simon Brown:
  * https://c4model.com/
  */
+export * from './confidence';
+import type { C4ConfidenceAssessment } from './confidence';
 /**
  * C4 Diagrams container for all diagram levels
  */
@@ -52,6 +54,8 @@ export interface C4AnalysisMetadata {
     externalSystemsDetected: number;
     /** Analysis duration in milliseconds */
     analysisTimeMs: number;
+    /** ADR-112: deterministic confidence gate for the generated diagrams */
+    confidence?: C4ConfidenceAssessment;
 }
 /**
  * C4 Person element - represents a user of the system

package/dist/shared/c4-model/index.js

@@ -8,6 +8,7 @@
  * Based on the C4 Model by Simon Brown:
  * https://c4model.com/
  */
+export * from './confidence';
 /**
  * Check if a cache entry is still valid
  */

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

package/dist/verification/adversarial-verify/calibrate.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @ruvector/adversarial-verify — calibration (plan 05 / A2 step 5).
+ *
+ * Measure the verifier against a LABELED set (findings tagged real/false) to get
+ * the operating point: false-kill (a REAL finding wrongly refuted — the costly
+ * error) and false-keep (a FALSE finding that survives). Works with any `Judge`
+ * — a deterministic stub (characterize the k-of-n aggregation) or a real LLM
+ * (empirical false-kill on a labeled corpus).
+ */
+import type { AdversarialVerifyOptions, Finding } from './types.js';
+export interface LabeledFinding {
+    finding: Finding;
+    /** Ground truth: is this a genuine, actionable problem? */
+    isReal: boolean;
+}
+export interface CalibrationReport {
+    total: number;
+    realCount: number;
+    falseCount: number;
+    /** REAL findings wrongly refuted (the costly error). */
+    falseKill: number;
+    falseKillRate: number;
+    /** FALSE findings wrongly upheld (survived verification). */
+    falseKeep: number;
+    falseKeepRate: number;
+    correctConfirm: number;
+    correctKill: number;
+    uncertain: number;
+}
+/** Run the verifier over a labeled set and report the confusion vs ground truth. */
+export declare function calibrate(labeled: LabeledFinding[], opts: AdversarialVerifyOptions): Promise<CalibrationReport>;
+//# sourceMappingURL=calibrate.d.ts.map

package/dist/verification/adversarial-verify/calibrate.js

@@ -0,0 +1,33 @@
+import { adversarialVerify } from './verify.js';
+/** Run the verifier over a labeled set and report the confusion vs ground truth. */
+export async function calibrate(labeled, opts) {
+    const verdicts = await adversarialVerify(labeled.map((l) => l.finding), opts);
+    const r = {
+        total: labeled.length, realCount: 0, falseCount: 0,
+        falseKill: 0, falseKillRate: 0, falseKeep: 0, falseKeepRate: 0,
+        correctConfirm: 0, correctKill: 0, uncertain: 0,
+    };
+    labeled.forEach((l, i) => {
+        const v = verdicts[i].verdict;
+        if (v === 'uncertain')
+            r.uncertain++;
+        if (l.isReal) {
+            r.realCount++;
+            if (v === 'refuted')
+                r.falseKill++;
+            else if (v === 'upheld')
+                r.correctConfirm++;
+        }
+        else {
+            r.falseCount++;
+            if (v === 'upheld')
+                r.falseKeep++;
+            else if (v === 'refuted')
+                r.correctKill++;
+        }
+    });
+    r.falseKillRate = r.realCount ? r.falseKill / r.realCount : 0;
+    r.falseKeepRate = r.falseCount ? r.falseKeep / r.falseCount : 0;
+    return r;
+}
+//# sourceMappingURL=calibrate.js.map

package/dist/verification/adversarial-verify/gate.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @ruvector/adversarial-verify — output gate (plan 05 / A5).
+ *
+ * An opt-in "verify before you emit" gate any vertical/harness can embed: route
+ * emitted findings/claims through the blind refuters and DROP the refuted ones
+ * before acting. Default-off-able and cost-neutral when disabled (no Judge calls).
+ * Surfaces every verdict for witness/telemetry, and reports the gate's overhead.
+ *
+ * Vendor-ready: zero dependencies beyond this module, so MetaHarness (or any host)
+ * can embed it as a per-vertical `verify` hook.
+ */
+import type { AdversarialVerifyOptions, Finding, FindingVerdict } from './types.js';
+export interface VerifyGateOptions extends AdversarialVerifyOptions {
+    /** Off ⇒ no-op pass-through, ZERO Judge calls (cost-neutral). Default true. */
+    enabled?: boolean;
+    /** Also block `uncertain` verdicts (all refuters failed), not just `refuted`. Default false. */
+    dropUncertain?: boolean;
+}
+export interface VerifyGateResult {
+    enabled: boolean;
+    /** Findings that PASS the gate — emit these. */
+    emitted: FindingVerdict[];
+    /** Findings the gate blocked (refuted, + uncertain when `dropUncertain`). */
+    blocked: FindingVerdict[];
+    /** All verdicts (for witness/telemetry). */
+    all: FindingVerdict[];
+    /** Gate wall-clock overhead in ms (A5 (d) — measured cost). */
+    latencyMs: number;
+    /** Judge invocations the gate made (0 when disabled). Token cost ∝ this. */
+    judgeCalls: number;
+}
+/**
+ * Verify findings before emitting them. Returns the survivors (`emitted`), the
+ * killed (`blocked`), every verdict (`all`), and the gate's overhead. When
+ * `enabled === false` it is a no-op: no Judge calls, everything passes through.
+ */
+export declare function verifyGate(findings: Finding[], opts: VerifyGateOptions): Promise<VerifyGateResult>;
+//# sourceMappingURL=gate.d.ts.map

package/dist/verification/adversarial-verify/gate.js

@@ -0,0 +1,32 @@
+import { adversarialVerify } from './verify.js';
+/** A finding passed through un-verified (gate disabled): honest `uncertain`. */
+function passthrough(f) {
+    return {
+        contract: 'finding-verdict@1',
+        id: f.id, title: f.title,
+        ...(f.file !== undefined ? { file: f.file } : {}),
+        severity: f.severity, confidence: f.confidence, evidence: f.evidence,
+        verdict: 'uncertain', refutations: [],
+    };
+}
+const isBlocked = (v, dropUncertain) => v.verdict === 'refuted' || (dropUncertain && v.verdict === 'uncertain');
+/**
+ * Verify findings before emitting them. Returns the survivors (`emitted`), the
+ * killed (`blocked`), every verdict (`all`), and the gate's overhead. When
+ * `enabled === false` it is a no-op: no Judge calls, everything passes through.
+ */
+export async function verifyGate(findings, opts) {
+    const t0 = Date.now();
+    if (opts.enabled === false) {
+        const emitted = findings.map(passthrough);
+        return { enabled: false, emitted, blocked: [], all: emitted, latencyMs: Date.now() - t0, judgeCalls: 0 };
+    }
+    let judgeCalls = 0;
+    const countingJudge = (prompt) => { judgeCalls++; return opts.judge(prompt); };
+    const all = await adversarialVerify(findings, { ...opts, judge: countingJudge });
+    const dropUncertain = opts.dropUncertain ?? false;
+    const blocked = all.filter((v) => isBlocked(v, dropUncertain));
+    const emitted = all.filter((v) => !isBlocked(v, dropUncertain));
+    return { enabled: true, emitted, blocked, all, latencyMs: Date.now() - t0, judgeCalls };
+}
+//# sourceMappingURL=gate.js.map

package/dist/verification/adversarial-verify/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @ruvector/adversarial-verify (plan 05 / A2).
+ *
+ * Host-agnostic blind-refuter verification: turn raw findings into adversarially
+ * verified finding-verdict@1 envelopes. N blind refuters per finding (anti-
+ * sycophancy, default-refuted on uncertainty) → deterministic majority-kill.
+ * The LLM is injected as a `Judge`, so this has ZERO AQE/Claude-Code dependency
+ * and is publishable as `@ruvector/adversarial-verify`.
+ *
+ * @example
+ *   const verdicts = await adversarialVerify(findings, { judge, refuters: 3 });
+ *   const { confirmed, killed } = partitionVerdicts(verdicts);
+ */
+export type { Finding, FindingVerdict, FindingSeverity, FindingOutcome, RefuterVote, Judge, AdversarialVerifyOptions, } from './types.js';
+export { adversarialVerify, partitionVerdicts } from './verify.js';
+export { synthesizeVerdict, majorityKill, isFindingVerdict } from './synthesize.js';
+export { refuterPrompt, DEFAULT_LENSES } from './prompts.js';
+export { calibrate, type LabeledFinding, type CalibrationReport } from './calibrate.js';
+export { verifyGate, type VerifyGateOptions, type VerifyGateResult } from './gate.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/verification/adversarial-verify/index.js

@@ -0,0 +1,6 @@
+export { adversarialVerify, partitionVerdicts } from './verify.js';
+export { synthesizeVerdict, majorityKill, isFindingVerdict } from './synthesize.js';
+export { refuterPrompt, DEFAULT_LENSES } from './prompts.js';
+export { calibrate } from './calibrate.js';
+export { verifyGate } from './gate.js';
+//# sourceMappingURL=index.js.map