@oscharko-dev/keiko-workflows 0.2.0

package/dist/qualityIntelligence/modelRoutedTestDesign.js

@@ -0,0 +1,620 @@
+// Quality Intelligence model-routed test-design run entry (Epic #270, Issue #272/#273/#279).
+//
+// The live generation path: real source evidence → Keiko Model Gateway → generated test-case
+// candidates → pure-domain dedup / coverage / validation → evidence + candidate-artifact persist.
+// Shares the run-lifecycle runtime with the scripted entries via `runtimeCommon.ts`. The model call
+// is injected as an abstract `generate` port so this module stays free of provider SDKs and the
+// server tier owns the gateway wiring (ADR-0023 D5/D6).
+import { QualityIntelligence as QI } from "@oscharko-dev/keiko-contracts";
+import { buildAtomCoverageStatuses, buildCoverageMap, buildRequirementExcerpt, computeCandidateEquivalenceSignature, deduplicateCandidates, deriveIntent, designTestCaseCandidates, scoreFromDimensions, TEST_QUALITY_WEAK_THRESHOLD, verdictFromDimensions, validateCandidates, QualityIntelligenceGeneration, } from "@oscharko-dev/keiko-quality-intelligence";
+import { sha256Hex } from "@oscharko-dev/keiko-security";
+import { QI_TEST_DESIGN_WORKFLOW_DESCRIPTOR } from "./descriptors.js";
+import { emit, emitCandidateProposed, emitFindingsRecorded, emitQueuedAndStarted, finaliseFailureOrCancellation, makeContext, persistRun, safeReasonSummary, StageCancelledError, toCoverageMatrixRows, truncateCandidates, truncateFindings, withStage, } from "./runtimeCommon.js";
+import { isCancelled } from "./cancellation.js";
+class EmptyEvidenceError extends Error {
+    constructor() {
+        super("No usable evidence atoms were ingested for the run");
+        this.name = "EmptyEvidenceError";
+    }
+}
+class UnparseableModelOutputError extends Error {
+    constructor() {
+        super("Model output could not be parsed into test cases");
+        this.name = "UnparseableModelOutputError";
+    }
+}
+function evidenceRefsFor(ingestedAtoms) {
+    return Object.freeze(ingestedAtoms.map((a) => Object.freeze({
+        envelopeId: String(a.atom.sourceEnvelopeId),
+        atomId: String(a.atom.id),
+        lifecycleStatus: a.atom.lifecycleStatus,
+    })));
+}
+function atomFingerprintsFor(ingestedAtoms) {
+    return Object.freeze(ingestedAtoms.map((entry) => Object.freeze({
+        atomId: String(entry.atom.id),
+        envelopeId: String(entry.atom.sourceEnvelopeId),
+        canonicalHashSha256Hex: entry.atom.canonicalHashSha256Hex,
+        ...(entry.replacementGroupId !== undefined
+            ? { replacementGroupId: entry.replacementGroupId }
+            : {}),
+        ...(entry.replacementOrdinal !== undefined
+            ? { replacementOrdinal: entry.replacementOrdinal }
+            : {}),
+    })));
+}
+/**
+ * Map each ingested atom's id to a short, redacted excerpt of its canonical text (#790) so
+ * coverage rows and gap findings can name the requirement, not just its opaque id. Atoms whose
+ * text collapses to nothing are omitted (the optional field is simply absent downstream).
+ */
+export function excerptsByAtomId(ingestedAtoms) {
+    const map = new Map();
+    for (const entry of ingestedAtoms) {
+        const excerpt = buildRequirementExcerpt(entry.canonicalText);
+        if (excerpt !== undefined)
+            map.set(String(entry.atom.id), excerpt);
+    }
+    return map;
+}
+function buildCoverageGapFinding(runId, atomStatus, ordinal, excerpt) {
+    const payload = ["v1-cov-gap", String(runId), String(atomStatus.atomId), String(ordinal)].join("");
+    const idStr = `qi-finding-${sha256Hex(payload).slice(0, 32)}`;
+    // An atom with zero tracing tests is the headline audit gap (high); an atom covered only weakly
+    // (incidentally, by broad tests) is a softer "strengthen this" signal (low). This keeps the gap
+    // list honest: a flood of low-severity weak findings never drowns out the genuine zero-coverage
+    // requirements, and severity-ordered truncation (below) protects the high ones.
+    const severity = atomStatus.status === "uncovered" ? "high" : "low";
+    // Name the requirement, not just its id (#790): the excerpt is already redacted (and persist
+    // redacts every leaf again), so the finding stays evidence-safe while becoming auditor-readable.
+    const atomLabel = excerpt === undefined
+        ? `Atom ${String(atomStatus.atomId)}`
+        : `Atom ${String(atomStatus.atomId)} ("${excerpt}")`;
+    const summary = atomStatus.status === "uncovered"
+        ? `${atomLabel} hat keinen zugeordneten Test (uncovered).`
+        : `${atomLabel} ist nur schwach abgedeckt (kein dedizierter Test referenziert dieses Atom).`;
+    return Object.freeze({
+        kind: "coverage-gap",
+        id: QI.asQualityIntelligenceValidationFindingId(idStr),
+        runId,
+        severity,
+        summary,
+        evidenceAtomIds: Object.freeze([atomStatus.atomId]),
+    });
+}
+const MODEL_DELTA_CANDIDATE_CEILING = 16;
+const MODEL_DELTA_CANDIDATE_FLOOR = 3;
+function modelDeltaCandidateLimit(evidenceCount, runLimit) {
+    const boundedRunLimit = Math.max(1, Math.trunc(runLimit));
+    const evidenceAwareLimit = Math.max(MODEL_DELTA_CANDIDATE_FLOOR, Math.max(1, Math.trunc(evidenceCount)) * 2);
+    return Math.max(1, Math.min(boundedRunLimit, MODEL_DELTA_CANDIDATE_CEILING, evidenceAwareLimit));
+}
+function deterministicBaselineCandidates(ctx, input) {
+    const atomTextById = new Map(input.ingestedAtoms.map((entry) => [String(entry.atom.id), entry.canonicalText]));
+    const candidates = designTestCaseCandidates({
+        runId: input.plan.id,
+        intent: deriveIntent(input.envelopes, ctx.profile),
+        atoms: input.ingestedAtoms.map((entry) => entry.atom),
+        atomTextById,
+        profile: ctx.profile,
+    });
+    return truncateCandidates(deduplicateCandidates(candidates), ctx.limits.maxCandidatesPerRun);
+}
+function parseModelCandidates(result, ctx, input, maxCandidates) {
+    const parsed = QualityIntelligenceGeneration.parseGeneratedCandidates(result.rawText, {
+        runId: input.plan.id,
+        atomIds: input.ingestedAtoms.map((a) => a.atom.id),
+        profile: ctx.profile,
+        maxCandidates,
+    });
+    if (!parsed.recovered) {
+        throw new UnparseableModelOutputError();
+    }
+    return truncateCandidates(deduplicateCandidates(parsed.candidates), maxCandidates);
+}
+function appendModelDelta(baseline, delta, limit) {
+    const baselineLimit = delta.length > 0 && limit > 0 ? Math.max(0, limit - 1) : limit;
+    const out = [...baseline].slice(0, baselineLimit);
+    const seen = new Set(out.map((candidate) => computeCandidateEquivalenceSignature(candidate)));
+    let appendedDelta = 0;
+    for (const candidate of delta) {
+        const signature = computeCandidateEquivalenceSignature(candidate);
+        if (seen.has(signature))
+            continue;
+        seen.add(signature);
+        out.push(candidate);
+        appendedDelta += 1;
+        if (out.length >= limit)
+            break;
+    }
+    if (appendedDelta === 0) {
+        for (let index = baselineLimit; index < baseline.length && out.length < limit; index += 1) {
+            const candidate = baseline[index];
+            if (candidate === undefined)
+                continue;
+            out.push(candidate);
+        }
+    }
+    return Object.freeze(out);
+}
+function selectReviewCandidates(persisted, baseline, delta) {
+    if (delta.length === 0) {
+        return Object.freeze([]);
+    }
+    const persistedIds = new Set(persisted.map((candidate) => String(candidate.id)));
+    const persistedDelta = delta.filter((candidate) => persistedIds.has(String(candidate.id)));
+    return persistedDelta.length > 0 ? Object.freeze(persistedDelta) : baseline;
+}
+function modelGenerationOutput(result, ctx, input, runCandidateLimit, modelDeltaLimit) {
+    const baseline = deterministicBaselineCandidates(ctx, input);
+    const delta = parseModelCandidates(result, ctx, input, modelDeltaLimit);
+    const candidates = appendModelDelta(baseline, delta, runCandidateLimit);
+    return {
+        candidates,
+        reviewCandidates: selectReviewCandidates(candidates, baseline, delta),
+        ...(result.modelId !== undefined ? { modelId: result.modelId } : {}),
+        ...(result.modelId !== undefined
+            ? { seedUsed: result.seedUsed ?? null }
+            : result.seedUsed !== undefined
+                ? { seedUsed: result.seedUsed }
+                : {}),
+        modelParameters: result.modelParameters,
+    };
+}
+function baselineFallbackGenerationOutput(ctx, input, reasonSummary) {
+    const candidates = deterministicBaselineCandidates(ctx, input);
+    return {
+        candidates,
+        reviewCandidates: candidates,
+        skipJudge: true,
+        fallbackReason: reasonSummary,
+        modelParameters: { generationFallbackReason: reasonSummary },
+    };
+}
+function hasQiCode(error, code) {
+    if (!(error instanceof Error))
+        return false;
+    const coded = error;
+    return typeof coded.code === "string" && coded.code === code;
+}
+function shouldCountRejectedGenerationDispatch(error) {
+    return !hasQiCode(error, "QI_PROMPT_TOO_LARGE");
+}
+async function generateCandidates(ctx, input, deps) {
+    if (input.ingestedAtoms.length === 0) {
+        throw new EmptyEvidenceError();
+    }
+    const evidence = input.ingestedAtoms.map((a, i) => ({
+        index: i + 1,
+        kind: a.atom.kind,
+        text: a.canonicalText,
+    }));
+    const runCandidateLimit = ctx.limits.maxCandidatesPerRun;
+    const modelDeltaLimit = modelDeltaCandidateLimit(evidence.length, runCandidateLimit);
+    const instruction = QualityIntelligenceGeneration.buildTestDesignInstruction({
+        evidenceCount: evidence.length,
+        profile: ctx.profile,
+        maxTestCases: modelDeltaLimit,
+    });
+    // Count the generation gateway dispatch as an ATTEMPT, mirroring the judge contract
+    // (judgeOneCandidate counts before its await). The generation port makes at most one gateway
+    // dispatch per call, so a rejection (Azure 5xx / timeout / network / abort) still means one call
+    // was attempted and billed. Counting only result.modelCallCount AFTER a successful await
+    // under-reported a failed run's audit trail as 0 gateway calls (#273 audit; #843 undercount class).
+    // The deterministic baseline port never rejects and reports modelCallCount 0, so it is unaffected.
+    let result;
+    let countedGatewayDispatch = false;
+    try {
+        result = await deps.generate.generate({
+            systemPrompt: QualityIntelligenceGeneration.QI_TEST_DESIGN_SYSTEM_PROMPT,
+            instruction,
+            evidence,
+            maxCandidates: modelDeltaLimit,
+            signal: ctx.signal,
+        });
+        ctx.modelGatewayCallCount += result.modelCallCount;
+        countedGatewayDispatch = result.modelCallCount > 0;
+        if (result.modelId === undefined && result.modelCallCount === 0) {
+            const candidates = deterministicBaselineCandidates(ctx, input);
+            return {
+                candidates,
+                reviewCandidates: candidates,
+                ...(result.seedUsed !== undefined ? { seedUsed: result.seedUsed } : {}),
+                modelParameters: result.modelParameters,
+            };
+        }
+        return modelGenerationOutput(result, ctx, input, runCandidateLimit, modelDeltaLimit);
+    }
+    catch (error) {
+        if (isCancellationError(ctx, error))
+            throw new StageCancelledError();
+        if (!countedGatewayDispatch && shouldCountRejectedGenerationDispatch(error)) {
+            ctx.modelGatewayCallCount += 1;
+        }
+        return baselineFallbackGenerationOutput(ctx, input, safeReasonSummary(error));
+    }
+}
+function candidateSummaryText(candidate) {
+    const parts = [
+        `Titel: ${candidate.title}`,
+        `Vorbedingungen: ${candidate.preconditions.join("; ")}`,
+        `Schritte: ${candidate.steps.join("; ")}`,
+        `Erwartetes Ergebnis: ${candidate.expectedResults.join("; ")}`,
+    ];
+    return parts.join("\n");
+}
+const JUDGE_SUMMARY_DIMENSION_LIMIT = 2;
+const FINDING_KIND_TRUNCATION_PRIORITY = {
+    "test-quality": 0,
+};
+const JUDGE_DIMENSION_LABEL = {
+    verifiability: "Prüfbarkeit",
+    atomicity: "Atomarität",
+    determinism: "Determinismus",
+    "ac-fidelity": "AC-Treue",
+};
+function sourceContextForCandidate(candidate, ingestedAtoms) {
+    const byAtomId = new Map(ingestedAtoms.map((entry) => [
+        String(entry.atom.id),
+        Object.freeze({
+            atomId: String(entry.atom.id),
+            text: entry.canonicalText,
+        }),
+    ]));
+    const matched = candidate.derivedFromAtomIds
+        .map((atomId) => byAtomId.get(String(atomId)))
+        .filter((entry) => entry !== undefined);
+    if (matched.length > 0)
+        return Object.freeze(matched);
+    return Object.freeze(ingestedAtoms.map((entry) => Object.freeze({
+        atomId: String(entry.atom.id),
+        text: entry.canonicalText,
+    })));
+}
+function judgeRationaleSummary(verdict) {
+    const weakDimensions = verdict.dimensions
+        .filter((dimension) => dimension.score < TEST_QUALITY_WEAK_THRESHOLD)
+        .sort((left, right) => left.score - right.score);
+    const dimensionsToDescribe = weakDimensions.length > 0
+        ? weakDimensions
+        : [...verdict.dimensions].sort((a, b) => a.score - b.score);
+    return dimensionsToDescribe
+        .slice(0, JUDGE_SUMMARY_DIMENSION_LIMIT)
+        .map((dimension) => `${JUDGE_DIMENSION_LABEL[dimension.name]}: ${dimension.rationale}`)
+        .join("; ");
+}
+function buildTestQualityFinding(runId, candidate, score, rationale, ordinal) {
+    const payload = ["v1-tq", String(runId), String(candidate.id), String(ordinal)].join("");
+    const idStr = `qi-finding-${sha256Hex(payload).slice(0, 32)}`;
+    const severity = score < 30 ? "high" : "medium";
+    return Object.freeze({
+        kind: "test-quality",
+        id: QI.asQualityIntelligenceValidationFindingId(idStr),
+        runId,
+        candidateId: candidate.id,
+        severity,
+        summary: rationale,
+        evidenceAtomIds: Object.freeze([...candidate.derivedFromAtomIds]),
+    });
+}
+function findingTruncationPriority(finding) {
+    return FINDING_KIND_TRUNCATION_PRIORITY[finding.kind] ?? 1;
+}
+const EMPTY_JUDGE_RESULT = Object.freeze({
+    findings: Object.freeze([]),
+    qualityScore: null,
+    candidateQualityVerdicts: new Map(),
+});
+// Bounded concurrency for the per-candidate judge calls: cuts the wall-clock of judging a large run
+// (one gateway call per candidate) without flooding the gateway, which applies its own per-call
+// retry/timeout. Findings are written into a candidate-indexed slot array so the persisted finding
+// order stays deterministic regardless of which judge call completes first.
+const JUDGE_CONCURRENCY = 4;
+function isCancellationError(ctx, error) {
+    return error instanceof StageCancelledError || isCancelled(ctx.signal);
+}
+const JUDGE_ERROR_RATIONALE = "Der Quality-Judge konnte diesen Kandidaten nicht bewerten; er wird für das Audit als schwach behandelt.";
+const JUDGE_BUDGET_RATIONALE = "Das Quality-Judge-Budget war vor der Bewertung dieses Kandidaten ausgeschöpft; er wird für das Audit als schwach behandelt.";
+function buildSyntheticWeakJudgeOutcome(ctx, candidate, ordinal, rationale) {
+    return {
+        strong: false,
+        finding: buildTestQualityFinding(ctx.plan.id, candidate, 0, rationale, ordinal),
+        qualityVerdict: syntheticWeakQualityVerdict(rationale),
+    };
+}
+function cloneDimensions(dimensions) {
+    return Object.freeze(dimensions.map((dimension) => Object.freeze({ ...dimension })));
+}
+function qualityVerdictFromJudge(verdict) {
+    const score = scoreFromDimensions(verdict.dimensions);
+    return Object.freeze({
+        verdict: verdictFromDimensions(verdict.dimensions),
+        score,
+        dimensions: cloneDimensions(verdict.dimensions),
+        overallRationale: verdict.overallRationale,
+    });
+}
+function syntheticWeakQualityVerdict(rationale) {
+    const dimensions = QI.TEST_QUALITY_RUBRIC_DIMENSIONS.map((name) => Object.freeze({
+        name,
+        score: 0,
+        rationale,
+    }));
+    return Object.freeze({
+        verdict: "weak",
+        score: 0,
+        dimensions: Object.freeze(dimensions),
+        overallRationale: rationale,
+    });
+}
+/**
+ * Judge one candidate. Counts actual gateway dispatches reported by the judge port, then returns
+ * its outcome. A transient judge error (rate-limit / 5xx / timeout / network) remains
+ * run-fail-soft but becomes an explicit weak judge outcome; cancellation is re-raised as
+ * `StageCancelledError` so the whole stage aborts. Legacy/test ports that throw without returning
+ * dispatch metadata are counted as one attempted gateway call, preserving the audit contract.
+ */
+async function judgeOneCandidate(ctx, candidate, ordinal, ingestedAtoms, judge) {
+    let verdict;
+    try {
+        verdict = await judge.judge({
+            candidateText: candidateSummaryText(candidate),
+            sourceContext: sourceContextForCandidate(candidate, ingestedAtoms),
+        }, ctx.signal);
+        ctx.modelGatewayCallCount += verdict.gatewayCallCount ?? 1;
+    }
+    catch (error) {
+        if (isCancellationError(ctx, error))
+            throw new StageCancelledError();
+        ctx.modelGatewayCallCount += 1;
+        return buildSyntheticWeakJudgeOutcome(ctx, candidate, ordinal, JUDGE_ERROR_RATIONALE);
+    }
+    const score = scoreFromDimensions(verdict.dimensions);
+    const qualityVerdict = qualityVerdictFromJudge(verdict);
+    if (qualityVerdict.verdict === "strong") {
+        return { strong: true, finding: null, qualityVerdict };
+    }
+    return {
+        strong: false,
+        finding: buildTestQualityFinding(ctx.plan.id, candidate, score, judgeRationaleSummary(verdict), ordinal),
+        qualityVerdict,
+    };
+}
+function makeJudgeSlots(candidateCount) {
+    return {
+        findingSlots: Array.from({ length: candidateCount }, () => undefined),
+        verdictSlots: Array.from({ length: candidateCount }, () => undefined),
+    };
+}
+function recordJudgeOutcome(slots, index, outcome) {
+    slots.verdictSlots[index] = outcome.qualityVerdict;
+    if (outcome.finding !== null)
+        slots.findingSlots[index] = outcome.finding;
+    return outcome.strong;
+}
+async function judgeCandidates(ctx, candidates, ingestedAtoms, judge, slots) {
+    let strongCount = 0;
+    let verdictCount = 0;
+    let cursor = 0;
+    const worker = async () => {
+        for (;;) {
+            const i = cursor;
+            cursor += 1;
+            if (i >= candidates.length)
+                return;
+            const candidate = candidates[i];
+            if (candidate === undefined)
+                continue;
+            const outcome = await judgeOneCandidate(ctx, candidate, i, ingestedAtoms, judge);
+            verdictCount += 1;
+            if (recordJudgeOutcome(slots, i, outcome))
+                strongCount += 1;
+        }
+    };
+    if (candidates.length > 0) {
+        await Promise.all(Array.from({ length: Math.min(JUDGE_CONCURRENCY, candidates.length) }, () => worker()));
+    }
+    return { strongCount, verdictCount };
+}
+function recordBudgetOverflow(ctx, candidates, startIndex, slots) {
+    let verdictCount = 0;
+    for (let i = startIndex; i < candidates.length; i += 1) {
+        const candidate = candidates[i];
+        if (candidate === undefined)
+            continue;
+        const outcome = buildSyntheticWeakJudgeOutcome(ctx, candidate, i, JUDGE_BUDGET_RATIONALE);
+        verdictCount += 1;
+        recordJudgeOutcome(slots, i, outcome);
+    }
+    return verdictCount;
+}
+function candidateQualityVerdictMap(candidates, slots) {
+    const candidateQualityVerdicts = new Map();
+    for (let i = 0; i < candidates.length; i += 1) {
+        const candidate = candidates[i];
+        const qualityVerdict = slots.verdictSlots[i];
+        if (candidate !== undefined && qualityVerdict !== undefined) {
+            candidateQualityVerdicts.set(String(candidate.id), qualityVerdict);
+        }
+    }
+    return candidateQualityVerdicts;
+}
+function buildJudgeStageResult(candidates, slots, counts) {
+    const findings = slots.findingSlots.filter((f) => f !== undefined);
+    const qualityScore = counts.verdictCount === 0 ? null : (counts.strongCount / counts.verdictCount) * 100;
+    return {
+        findings: Object.freeze(findings),
+        qualityScore,
+        candidateQualityVerdicts: candidateQualityVerdictMap(candidates, slots),
+    };
+}
+/**
+ * Adversarially judge every candidate via the model-judge port (Epic #736, Issue #747).
+ *
+ * Resilience contract: the judge AUGMENTS generation and must never fail an otherwise successful
+ * run — a transient per-candidate error becomes an explicit weak test-quality finding and only
+ * cancellation aborts the stage. Audit contract: every dispatch is counted into
+ * `ctx.modelGatewayCallCount`. Budget contract: at most `ctx.limits.maxJudgeCallsPerRun` candidates
+ * make gateway calls; any overflow candidates receive deterministic weak findings so the persisted
+ * run still accounts for every candidate. Bounded-concurrency workers share a cursor; findings land
+ * in candidate-indexed slots so the persisted order stays deterministic regardless of completion
+ * order.
+ */
+async function runJudgeStage(ctx, candidates, ingestedAtoms, judge) {
+    if (candidates.length === 0)
+        return EMPTY_JUDGE_RESULT;
+    const budget = Math.max(0, ctx.limits.maxJudgeCallsPerRun);
+    const judgeable = budget >= candidates.length ? candidates : candidates.slice(0, budget);
+    const slots = makeJudgeSlots(candidates.length);
+    const judged = await judgeCandidates(ctx, judgeable, ingestedAtoms, judge, slots);
+    const overflowVerdictCount = recordBudgetOverflow(ctx, candidates, judgeable.length, slots);
+    // Per-run quality score = share of candidates with a strong judge outcome, as a percentage (#747).
+    // Gateway errors and budget overflow produce explicit weak outcomes so unverified candidates cannot
+    // be indistinguishable from strong candidates or inflate the run score.
+    return buildJudgeStageResult(candidates, slots, {
+        strongCount: judged.strongCount,
+        verdictCount: judged.verdictCount + overflowVerdictCount,
+    });
+}
+function candidatesWithQualityVerdicts(candidates, verdicts) {
+    if (verdicts.size === 0)
+        return candidates;
+    return Object.freeze(candidates.map((candidate) => {
+        const qualityVerdict = verdicts.get(String(candidate.id));
+        if (qualityVerdict === undefined)
+            return candidate;
+        return Object.freeze({
+            ...candidate,
+            qualityVerdict,
+        });
+    }));
+}
+/**
+ * Execute a model-routed QI test-design run end to end. Emits the standard QI run-event envelope,
+ * fails the run with a safe reason when the model output is unusable (rather than silently emitting
+ * zero candidates), and persists both the run manifest and the generated candidate bodies.
+ */
+// eslint-disable-next-line max-lines-per-function -- strict QI lifecycle: linear stage audit trail.
+export async function runQualityIntelligenceModelRoutedTestDesign(input, deps) {
+    const ctx = makeContext({
+        descriptor: QI_TEST_DESIGN_WORKFLOW_DESCRIPTOR,
+        plan: input.plan,
+        sink: deps.sink,
+        clock: deps.clock,
+        limits: deps.limits,
+        policyProfile: input.profile,
+        signal: deps.signal,
+    });
+    ctx.modelGatewayCallCount += deps.initialModelGatewayCallCount ?? 0;
+    const evidenceRefs = evidenceRefsFor(input.ingestedAtoms);
+    emitQueuedAndStarted(ctx);
+    try {
+        await withStage(ctx, "plan", async () => Promise.resolve());
+        const generation = await withStage(ctx, "candidates", async () => generateCandidates(ctx, input, deps));
+        const candidates = generation.candidates;
+        const reviewCandidates = generation.reviewCandidates;
+        // A provider/parser failure is caught inside generateCandidates and degrades to the deterministic
+        // baseline (skipJudge), keeping the run alive. That degradation MUST stay visible: the redacted
+        // reason is threaded into the terminal summary (and surfaced on the wire `done` frame as
+        // `degraded` + `reasonSummary`) so the run is never presented as an authoritative model-backed
+        // result (regulated-delivery audit, QI-DEG-01).
+        const degradedReason = generation.skipJudge === true
+            ? (generation.fallbackReason ?? "qi-generation-fallback")
+            : undefined;
+        emitCandidateProposed(ctx, candidates);
+        const judge = deps.judge;
+        const judgeResult = await withStage(ctx, "judge", async () => {
+            if (judge === undefined || generation.skipJudge === true)
+                return EMPTY_JUDGE_RESULT;
+            try {
+                return await runJudgeStage(ctx, reviewCandidates, input.ingestedAtoms, judge);
+            }
+            catch (error) {
+                // Cancellation must still abort the run; anything else is fail-soft so an optional judge
+                // can never turn a successful generation into a failed run (Epic #736 augments-not-harms).
+                if (isCancellationError(ctx, error))
+                    throw error;
+                return EMPTY_JUDGE_RESULT;
+            }
+        });
+        const atoms = input.ingestedAtoms.map((a) => a.atom);
+        const coverageMap = await withStage(ctx, "coverage", async () => Promise.resolve(buildCoverageMap({ runId: input.plan.id, atoms, candidates })));
+        const atomStatuses = buildAtomCoverageStatuses(atoms, coverageMap);
+        const excerptByAtomId = excerptsByAtomId(input.ingestedAtoms);
+        const coverageMatrix = toCoverageMatrixRows(atomStatuses, excerptByAtomId);
+        const gapFindings = [];
+        for (let i = 0; i < atomStatuses.length; i += 1) {
+            const s = atomStatuses[i];
+            if (s !== undefined && s.status !== "covered") {
+                gapFindings.push(buildCoverageGapFinding(input.plan.id, s, i, excerptByAtomId.get(String(s.atomId))));
+            }
+        }
+        const rawFindings = await withStage(ctx, "validate", async () => Promise.resolve(validateCandidates(input.plan.id, candidates)));
+        // Order by severity (critical -> low) BEFORE truncation so that, if the run hits the
+        // per-run findings cap, the most severe findings — uncovered-requirement gaps included —
+        // always survive the cut rather than being dropped by array position. Within a severity tier,
+        // keep test-quality findings first because #748 weak-test flags are projected exclusively from
+        // those candidate-scoped findings; stable sort preserves original order for all remaining ties.
+        const allFindings = [
+            ...gapFindings,
+            ...rawFindings,
+            ...judgeResult.findings,
+        ]
+            .slice()
+            .sort((a, b) => QI.QUALITY_INTELLIGENCE_SEVERITY_RANK[a.severity] -
+            QI.QUALITY_INTELLIGENCE_SEVERITY_RANK[b.severity] ||
+            findingTruncationPriority(a) - findingTruncationPriority(b));
+        const findings = truncateFindings(allFindings, ctx.limits.maxFindingsPerRun);
+        emitFindingsRecorded(ctx, findings);
+        const evidence = await withStage(ctx, "finalize", async () => {
+            const completedAt = ctx.clock.nowIso();
+            const sourceFingerprints = input.envelopes.map((e) => ({
+                envelopeId: String(e.id),
+                integrityHashSha256Hex: e.provenance.integrityHashSha256Hex,
+            }));
+            const atomFingerprints = atomFingerprintsFor(input.ingestedAtoms);
+            const result = persistRun({
+                ctx,
+                status: "succeeded",
+                candidatesCount: candidates.length,
+                findings,
+                evidenceRefs,
+                provenanceRefs: input.provenanceRefs,
+                completedAt,
+                evidenceStore: deps.evidenceStore,
+                coverageMatrix,
+                qualityScore: judgeResult.qualityScore,
+                ...(deps.redaction !== undefined ? { redaction: deps.redaction } : {}),
+                ...(sourceFingerprints.length > 0 ? { sourceFingerprints } : {}),
+                ...(atomFingerprints.length > 0 ? { atomFingerprints } : {}),
+                ...(generation.modelId !== undefined ? { modelId: generation.modelId } : {}),
+                ...(generation.seedUsed !== undefined ? { seedUsed: generation.seedUsed } : {}),
+                ...(generation.modelParameters !== undefined
+                    ? { modelParameters: generation.modelParameters }
+                    : {}),
+            });
+            deps.candidatesSink.record(candidatesWithQualityVerdicts(candidates, judgeResult.candidateQualityVerdicts), completedAt);
+            return Promise.resolve(result);
+        });
+        emit(ctx, { kind: "run:succeeded" });
+        return Object.freeze({
+            runId: input.plan.id,
+            workflowId: ctx.descriptor.workflowId,
+            status: "succeeded",
+            eventsEmitted: ctx.sequence,
+            modelGatewayCallCount: ctx.modelGatewayCallCount,
+            evidence,
+            qualityScore: judgeResult.qualityScore,
+            ...(degradedReason !== undefined ? { reasonSummary: degradedReason } : {}),
+        });
+    }
+    catch (caught) {
+        return finaliseFailureOrCancellation(ctx, caught, {
+            candidatesCount: 0,
+            findings: Object.freeze([]),
+            evidenceRefs,
+            provenanceRefs: input.provenanceRefs,
+            evidenceStore: deps.evidenceStore,
+        });
+    }
+}

package/dist/qualityIntelligence/runEntries.d.ts

@@ -0,0 +1,60 @@
+import { QualityIntelligence as QI, type ModelCapability, type NormalizedResponse } from "@oscharko-dev/keiko-contracts";
+import { type PolicyProfile } from "@oscharko-dev/keiko-quality-intelligence";
+import { type QualityIntelligenceBudgetState, type QualityIntelligenceDispatcherArgs, type QualityIntelligenceDispatcherResult, type QualityIntelligenceReplayCachePort } from "@oscharko-dev/keiko-model-gateway";
+import { type QualityIntelligenceLocalStore } from "@oscharko-dev/keiko-evidence";
+import { type QualityIntelligenceClock, type QualityIntelligenceProvenanceRefs, type QualityIntelligenceRunEventSink, type QualityIntelligenceRunSummary } from "./runtimeCommon.js";
+import type { QualityIntelligenceWorkflowLimits } from "./descriptors.js";
+export type { QualityIntelligenceClock, QualityIntelligenceProvenanceRefs, QualityIntelligenceRunEventSink, QualityIntelligenceRunStatus, QualityIntelligenceRunSummary, } from "./runtimeCommon.js";
+/**
+ * Optional model-routed dispatch surface. When omitted, judges/refinements skip the model call and
+ * fall through to the pure-domain validators only. When supplied, the dispatcher is invoked through
+ * the gateway seam from #279.
+ */
+export interface QualityIntelligenceDispatchPort {
+    readonly dispatch: (args: QualityIntelligenceDispatcherArgs) => Promise<QualityIntelligenceDispatcherResult>;
+}
+export interface QualityIntelligenceModelRoutedDeps {
+    readonly dispatch: QualityIntelligenceDispatchPort;
+    readonly model: ModelCapability;
+    readonly providerConfig: QualityIntelligenceDispatcherArgs["providerConfig"];
+    readonly port: QualityIntelligenceDispatcherArgs["port"];
+    readonly cache: QualityIntelligenceReplayCachePort<NormalizedResponse>;
+    readonly initialBudget: QualityIntelligenceBudgetState;
+}
+export interface QualityIntelligenceRunEntryDeps {
+    readonly sink: QualityIntelligenceRunEventSink;
+    readonly evidenceStore: QualityIntelligenceLocalStore;
+    readonly clock?: QualityIntelligenceClock | undefined;
+    readonly signal?: AbortSignal | undefined;
+    readonly limits?: QualityIntelligenceWorkflowLimits | undefined;
+    readonly policyProfile?: PolicyProfile | undefined;
+    readonly modelRouted?: QualityIntelligenceModelRoutedDeps | undefined;
+}
+export interface QualityIntelligenceTestDesignInput {
+    readonly plan: QI.QualityIntelligenceRunPlan;
+    readonly envelopes: readonly QI.QualityIntelligenceSourceEnvelope[];
+    readonly atoms: readonly QI.QualityIntelligenceEvidenceAtom[];
+    readonly provenanceRefs: QualityIntelligenceProvenanceRefs;
+}
+export interface QualityIntelligenceCoverageReviewInput {
+    readonly plan: QI.QualityIntelligenceRunPlan;
+    readonly atoms: readonly QI.QualityIntelligenceEvidenceAtom[];
+    readonly candidates: readonly QI.QualityIntelligenceTestCaseCandidate[];
+    readonly provenanceRefs: QualityIntelligenceProvenanceRefs;
+}
+export interface QualityIntelligenceValidationInput {
+    readonly plan: QI.QualityIntelligenceRunPlan;
+    readonly candidates: readonly QI.QualityIntelligenceTestCaseCandidate[];
+    readonly provenanceRefs: QualityIntelligenceProvenanceRefs;
+}
+export interface QualityIntelligenceArtifactRefinementInput {
+    readonly plan: QI.QualityIntelligenceRunPlan;
+    readonly atoms: readonly QI.QualityIntelligenceEvidenceAtom[];
+    readonly candidates: readonly QI.QualityIntelligenceTestCaseCandidate[];
+    readonly provenanceRefs: QualityIntelligenceProvenanceRefs;
+}
+export declare function runQualityIntelligenceTestDesign(input: QualityIntelligenceTestDesignInput, deps: QualityIntelligenceRunEntryDeps): Promise<QualityIntelligenceRunSummary>;
+export declare function runQualityIntelligenceCoverageReview(input: QualityIntelligenceCoverageReviewInput, deps: QualityIntelligenceRunEntryDeps): Promise<QualityIntelligenceRunSummary>;
+export declare function runQualityIntelligenceValidation(input: QualityIntelligenceValidationInput, deps: QualityIntelligenceRunEntryDeps): Promise<QualityIntelligenceRunSummary>;
+export declare function runQualityIntelligenceArtifactRefinement(input: QualityIntelligenceArtifactRefinementInput, deps: QualityIntelligenceRunEntryDeps): Promise<QualityIntelligenceRunSummary>;
+//# sourceMappingURL=runEntries.d.ts.map