@lsctech/polaris 0.5.7 → 0.5.8

package/dist/loop/parent.js

@@ -2031,35 +2031,40 @@ async function runParentLoop(options) {
             };
         }
         // ── Step 05 (post-dispatch): Re-check budget before next iteration ───
-        const postBudgetCheck = (0, budget_js_1.checkBudget)({
-            childrenCompleted: state.context_budget.children_completed,
-            lastChildStatus: workerStatus,
-            policy: budgetPolicy,
-        });
-        if (postBudgetCheck.status === 'exhausted') {
-            const nextPending = state.open_children[0] ?? null;
-            if (!dryRun) {
-                (0, checkpoint_js_1.writeStateAtomic)(stateFile, {
-                    ...state,
-                    status: "budget-exhausted",
-                    step_cursor: "budget-check",
-                    next_open_child: nextPending,
-                });
-                appendTelemetry(telemetryFile, {
-                    event: "budget-exhausted",
-                    run_id: state.run_id,
-                    children_completed: state.context_budget.children_completed,
-                    next_child: nextPending,
-                    reason: postBudgetCheck.reason,
-                    timestamp: new Date().toISOString(),
-                });
+        // Skip when open_children is empty: the cluster is complete and the
+        // top-of-loop nextChild === null path handles cluster-complete and QC
+        // repair-loop. Halting here would bypass QC repair on final-child completion.
+        if (state.open_children.length > 0) {
+            const postBudgetCheck = (0, budget_js_1.checkBudget)({
+                childrenCompleted: state.context_budget.children_completed,
+                lastChildStatus: workerStatus,
+                policy: budgetPolicy,
+            });
+            if (postBudgetCheck.status === 'exhausted') {
+                const nextPending = state.open_children[0] ?? null;
+                if (!dryRun) {
+                    (0, checkpoint_js_1.writeStateAtomic)(stateFile, {
+                        ...state,
+                        status: "budget-exhausted",
+                        step_cursor: "budget-check",
+                        next_open_child: nextPending,
+                    });
+                    appendTelemetry(telemetryFile, {
+                        event: "budget-exhausted",
+                        run_id: state.run_id,
+                        children_completed: state.context_budget.children_completed,
+                        next_child: nextPending,
+                        reason: postBudgetCheck.reason,
+                        timestamp: new Date().toISOString(),
+                    });
+                }
+                return {
+                    haltReason: 'budget-exhausted',
+                    childrenDispatched,
+                    haltingChild: nextPending ?? undefined,
+                    message: postBudgetCheck.reason,
+                };
             }
-            return {
-                haltReason: 'budget-exhausted',
-                childrenDispatched,
-                haltingChild: nextPending ?? undefined,
-                message: postBudgetCheck.reason,
-            };
         }
         // ── Step 06: CONTINUE (back to step 02) ─────────────────────────────
     }

package/dist/qc/artifacts.js

@@ -37,6 +37,7 @@ exports.getQcArtifactDir = getQcArtifactDir;
 exports.writeQcArtifact = writeQcArtifact;
 exports.readQcArtifact = readQcArtifact;
 exports.listQcArtifactIds = listQcArtifactIds;
+exports.validateQcArtifactPointers = validateQcArtifactPointers;
 const node_fs_1 = require("node:fs");
 const path = __importStar(require("node:path"));
 const schemas_js_1 = require("./schemas.js");
@@ -115,3 +116,29 @@ function listQcArtifactIds(clusterId, repoRoot) {
         throw error;
     }
 }
+/**
+ * Validate that the artifacts referenced by QC run pointers still exist.
+ * Returns a list of missing primary artifacts and unavailable raw audit
+ * artifacts so callers can warn, prune, or mark pointers consistently.
+ */
+function validateQcArtifactPointers(qcRuns) {
+    const missing = [];
+    const unavailable = [];
+    if (!qcRuns) {
+        return { ok: true, missing, unavailable };
+    }
+    for (const pointer of Object.values(qcRuns)) {
+        if (!(0, node_fs_1.existsSync)(pointer.artifact_path)) {
+            missing.push(pointer.artifact_path);
+        }
+        for (const rawPath of pointer.raw_artifact_paths ?? []) {
+            if (!(0, node_fs_1.existsSync)(rawPath)) {
+                unavailable.push(rawPath);
+            }
+        }
+        if (pointer.provider_attempt_artifact_path && !(0, node_fs_1.existsSync)(pointer.provider_attempt_artifact_path)) {
+            unavailable.push(pointer.provider_attempt_artifact_path);
+        }
+    }
+    return { ok: missing.length === 0 && unavailable.length === 0, missing, unavailable };
+}

package/dist/qc/orchestration.js

@@ -20,7 +20,7 @@ const attribution_js_1 = require("./attribution.js");
 const autofix_js_1 = require("./autofix.js");
 const routing_js_1 = require("./routing.js");
 function buildAttributionContext(options) {
-    const { repoRoot, clusterId, branch, state } = options;
+    const { repoRoot, clusterId, branch, baseRef, state } = options;
     const dispatchRecords = {};
     if (state?.open_children_meta) {
         for (const [childId, meta] of Object.entries(state.open_children_meta)) {
@@ -31,7 +31,7 @@ function buildAttributionContext(options) {
     }
     return {
         repoRoot,
-        baseBranch: branch ?? state?.branch ?? "main",
+        baseBranch: baseRef ?? branch ?? state?.branch ?? "main",
         completedResults: state?.completed_children_results,
         dispatchRecords,
         clusterState: repoRoot ? ((0, store_js_1.readClusterStateSync)(clusterId, repoRoot) ?? undefined) : undefined,
@@ -99,6 +99,7 @@ async function runQcAtTrigger(options) {
             clusterId,
             runId,
             ...(trigger === "pr" ? { prUrl } : { branch }),
+            ...(options.baseRef ? { baseRef: options.baseRef } : {}),
         };
         try {
             const rawResult = await (0, runner_js_1.executeQcProvider)(provider, scope, {

package/dist/qc/providers/coderabbit.js

@@ -16,6 +16,79 @@ function pickString(...candidates) {
     }
     return undefined;
 }
+const FINDING_LOCATION_KEYS = ["file", "filePath", "path"];
+const FINDING_REVIEW_KEYS = [
+    "severity",
+    "message",
+    "title",
+    "summary",
+    "description",
+    "body",
+    "rule",
+    "category",
+    "suggestion",
+    "suggestedAction",
+    "fix",
+    "providerFindingId",
+    "id",
+    "findingId",
+];
+const PROGRESS_SHAPE_KEYS = new Set(["event", "progress", "heartbeat", "complete", "review_context"]);
+const PROGRESS_TYPE_VALUES = new Set([
+    "progress",
+    "status",
+    "heartbeat",
+    "complete",
+    "review_context",
+    "reviewcontext",
+]);
+const PROGRESS_STATUS_VALUES = new Set([
+    "in_progress",
+    "running",
+    "pending",
+    "complete",
+    "completed",
+    "done",
+    "heartbeat",
+    "ok",
+    "success",
+]);
+function hasFindingLocation(record) {
+    return FINDING_LOCATION_KEYS.some((key) => record[key] !== undefined);
+}
+function hasFindingReviewContent(record) {
+    return FINDING_REVIEW_KEYS.some((key) => record[key] !== undefined);
+}
+function isProgressRecord(record) {
+    // Check progress/status indicators FIRST before the generic finding-content guard
+    const keys = Object.keys(record);
+    if (keys.length === 0)
+        return false;
+    if (keys.some((key) => PROGRESS_SHAPE_KEYS.has(key)))
+        return true;
+    if (typeof record.type === "string" && PROGRESS_TYPE_VALUES.has(record.type.toLowerCase()))
+        return true;
+    if (typeof record.status === "string" && PROGRESS_STATUS_VALUES.has(record.status.toLowerCase()))
+        return true;
+    // Status-only records with category="status" are progress records even if they have message/title fields
+    if (typeof record.category === "string" && record.category.toLowerCase() === "status")
+        return true;
+    // Only reject as progress if it has both location AND review content (true finding shape)
+    if (hasFindingLocation(record) && hasFindingReviewContent(record)) {
+        return false;
+    }
+    return false;
+}
+function isActionableFinding(record) {
+    if (isProgressRecord(record))
+        return false;
+    return hasFindingLocation(record) || hasFindingReviewContent(record);
+}
+function makeUnusableOutputError(message) {
+    const err = new Error(message);
+    err.qcFailureReason = "unusable-output";
+    return err;
+}
 function buildRange(raw) {
     const startLine = coerceNumber(raw.startLine ?? raw.line) ?? 1;
     const endLine = coerceNumber(raw.endLine);
@@ -37,18 +110,16 @@ function parseFindingsFromPayload(payload) {
     }
     const record = payload;
     if (Array.isArray(record.findings)) {
-        return record.findings;
+        return record.findings.filter((item) => typeof item === "object" && item !== null && isActionableFinding(item));
     }
     if (Array.isArray(record.issues)) {
-        return record.issues;
+        return record.issues.filter((item) => typeof item === "object" && item !== null && isActionableFinding(item));
     }
     if (Array.isArray(record.results)) {
-        return record.results;
+        return record.results.filter((item) => typeof item === "object" && item !== null && isActionableFinding(item));
     }
     // Single finding wrapped in an object
-    if (record.severity !== undefined ||
-        record.message !== undefined ||
-        record.title !== undefined) {
+    if (isActionableFinding(record)) {
         return [record];
     }
     return [];
@@ -77,10 +148,21 @@ function parseReport(output, format, parser) {
         try {
             const parsed = JSON.parse(text);
             if (Array.isArray(parsed)) {
-                return { findings: parsed };
+                const findings = parsed.filter((item) => typeof item === "object" && item !== null && isActionableFinding(item));
+                if (findings.length === 0 && parsed.length > 0) {
+                    const progressCount = parsed.filter((item) => typeof item === "object" && item !== null && isProgressRecord(item)).length;
+                    if (progressCount > 0) {
+                        throw makeUnusableOutputError(`CodeRabbit output contained only progress/status/heartbeat records (${progressCount} items)`);
+                    }
+                }
+                return { findings };
+            }
+            const findings = parseFindingsFromPayload(parsed);
+            if (findings.length === 0 && isProgressRecord(parsed)) {
+                throw makeUnusableOutputError("CodeRabbit output was a progress/status/heartbeat record");
             }
             return {
-                findings: parseFindingsFromPayload(parsed),
+                findings,
                 ...(typeof parsed?.prUrl === "string"
                     ? { prUrl: parsed.prUrl }
                     : {}),
@@ -97,10 +179,23 @@ function parseReport(output, format, parser) {
     // JSONL or generic line scanning: one finding per line
     const lines = text.split("\n").filter((line) => line.trim().length > 0);
     const lineFindings = [];
+    let progressLineCount = 0;
+    let parsedLineCount = 0;
     for (const line of lines) {
         try {
             const parsed = JSON.parse(line);
-            lineFindings.push(parsed);
+            parsedLineCount++;
+            if (!parsed || typeof parsed !== "object") {
+                continue;
+            }
+            const record = parsed;
+            if (isProgressRecord(record)) {
+                progressLineCount++;
+                continue;
+            }
+            if (isActionableFinding(record)) {
+                lineFindings.push(parsed);
+            }
         }
         catch {
             // Ignore unparseable lines.
@@ -109,6 +204,12 @@ function parseReport(output, format, parser) {
     if (lineFindings.length > 0) {
         return { findings: lineFindings };
     }
+    if (progressLineCount > 0) {
+        throw makeUnusableOutputError(`CodeRabbit output contained only progress/status/heartbeat records (${progressLineCount} lines)`);
+    }
+    if (parsedLineCount > 0) {
+        throw new Error("CodeRabbit output contained no actionable findings");
+    }
     throw new Error("CodeRabbit output could not be parsed as JSON, JSONL, or metrics payload");
 }
 function normalizeFinding(raw, index) {
@@ -217,20 +318,22 @@ class CodeRabbitQcProvider {
             if (execution.configPath) {
                 args.push("--config", execution.configPath);
             }
+            const baseRef = scope.baseRef ?? scope.branch ?? "main";
             if (scope.prUrl) {
                 args.push("--pr-url", scope.prUrl);
             }
             else {
-                args.push("--branch", scope.branch ?? "HEAD");
+                args.push("--base", baseRef);
             }
             return { command: execution.command, args };
         }
         if (scope.prUrl) {
             return { command: "coderabbit", args: ["review", "--agent", "--pr-url", scope.prUrl] };
         }
+        const baseRef = scope.baseRef ?? scope.branch ?? "main";
         return {
             command: "coderabbit",
-            args: ["review", "--agent", "--branch", scope.branch ?? "HEAD"],
+            args: ["review", "--agent", "--base", baseRef],
         };
     }
     parse(output) {

package/dist/qc/repair-loop.js

@@ -33,6 +33,43 @@ function appendTelemetry(telemetryFile, event) {
     (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(telemetryFile), { recursive: true });
     (0, node_fs_1.appendFileSync)(telemetryFile, JSON.stringify(event) + "\n", "utf-8");
 }
+async function persistQcRepairOutcome(clusterId, repoRoot, outcome) {
+    try {
+        const clusterState = (0, store_js_1.readClusterStateSync)(clusterId, repoRoot);
+        if (!clusterState)
+            return;
+        await (0, store_js_1.writeClusterState)(clusterId, {
+            ...clusterState,
+            state_generation: clusterState.state_generation + 1,
+            qc_repair_outcome: outcome,
+        }, repoRoot);
+    }
+    catch {
+        // Best-effort: the loop outcome is already returned to the caller and
+        // recorded in the loop checkpoint. Do not block finalization on a
+        // cluster-state write race.
+    }
+}
+async function persistQcRepairManifest(clusterId, repoRoot, round, manifestPath) {
+    try {
+        const clusterState = (0, store_js_1.readClusterStateSync)(clusterId, repoRoot);
+        if (!clusterState)
+            return;
+        const manifests = { ...(clusterState.qc_repair_manifests ?? {}), [round]: manifestPath };
+        if (clusterState.qc_repair_manifests &&
+            clusterState.qc_repair_manifests[round] === manifestPath) {
+            return;
+        }
+        await (0, store_js_1.writeClusterState)(clusterId, {
+            ...clusterState,
+            state_generation: clusterState.state_generation + 1,
+            qc_repair_manifests: manifests,
+        }, repoRoot);
+    }
+    catch {
+        // Best-effort durability for repair-round manifest pointer.
+    }
+}
 /** Returns true when any finding in the results routes to repair-worker. */
 function hasRepairableFindings(results) {
     return results.some((r) => r.findings.some((f) => (f.routingDecision === "repair-worker" || f.routingDecision === "original-worker") &&
@@ -109,6 +146,7 @@ async function runQcRepairLoop(options) {
         });
         state.terminal_outcome = "qc-disabled";
         state.updated_at = new Date().toISOString();
+        await persistQcRepairOutcome(clusterId, repoRoot, "qc-disabled");
         return {
             outcome: "qc-disabled",
             rounds_completed: 0,
@@ -147,6 +185,7 @@ async function runQcRepairLoop(options) {
                 round,
                 timestamp: new Date().toISOString(),
             });
+            await persistQcRepairOutcome(clusterId, repoRoot, "all-providers-failed");
             return {
                 outcome: "all-providers-failed",
                 rounds_completed: roundsCompleted,
@@ -165,6 +204,7 @@ async function runQcRepairLoop(options) {
                 round,
                 timestamp: new Date().toISOString(),
             });
+            await persistQcRepairOutcome(clusterId, repoRoot, "operator-review");
             return {
                 outcome: "operator-review",
                 rounds_completed: roundsCompleted,
@@ -189,19 +229,7 @@ async function runQcRepairLoop(options) {
             });
             manifest = compiled.manifest;
             // Update cluster state with manifest path.
-            try {
-                const clusterState = (0, store_js_1.readClusterStateSync)(clusterId, repoRoot);
-                if (clusterState) {
-                    const repairManifests = {
-                        ...(clusterState.qc_repair_manifests ?? {}),
-                        [round]: compiled.manifestPath,
-                    };
-                    await (0, store_js_1.writeClusterState)(clusterId, { ...clusterState, state_generation: clusterState.state_generation + 1, qc_repair_manifests: repairManifests }, repoRoot);
-                }
-            }
-            catch {
-                // Non-fatal: cluster state update is best-effort.
-            }
+            await persistQcRepairManifest(clusterId, repoRoot, round, compiled.manifestPath);
             loopState = {
                 ...loopState,
                 current_round: round,
@@ -221,13 +249,16 @@ async function runQcRepairLoop(options) {
             });
         }
         else {
+            const existingManifestPath = loopState.manifest_path ??
+                (0, node_path_1.join)(repoRoot, ".polaris", "clusters", clusterId, "qc", "repair-rounds", String(round), "repair-packets.json");
             loopState = {
                 ...loopState,
                 current_round: round,
-                manifest_path: loopState.manifest_path ?? (0, node_path_1.join)(repoRoot, ".polaris", "clusters", clusterId, "qc", "repair-rounds", String(round), "repair-packets.json"),
+                manifest_path: existingManifestPath,
                 updated_at: new Date().toISOString(),
             };
             onStateUpdate?.(loopState);
+            await persistQcRepairManifest(clusterId, repoRoot, round, existingManifestPath);
         }
         // ── Check for repairable packets ────────────────────────────────────────
         const repairablePackets = manifest.packets.filter((p) => p.routingTarget === "repair-worker" &&
@@ -243,6 +274,7 @@ async function runQcRepairLoop(options) {
                 round,
                 timestamp: new Date().toISOString(),
             });
+            await persistQcRepairOutcome(clusterId, repoRoot, "no-repairable");
             return {
                 outcome: "no-repairable",
                 rounds_completed: roundsCompleted,
@@ -309,6 +341,7 @@ async function runQcRepairLoop(options) {
                 failed_count: failedWorkers.length,
                 timestamp: new Date().toISOString(),
             });
+            await persistQcRepairOutcome(clusterId, repoRoot, "medic-referral");
             return {
                 outcome: "medic-referral",
                 rounds_completed: roundsCompleted + 1,
@@ -394,6 +427,7 @@ async function runQcRepairLoop(options) {
                 round,
                 timestamp: new Date().toISOString(),
             });
+            await persistQcRepairOutcome(clusterId, repoRoot, "pass");
             return {
                 outcome: "pass",
                 rounds_completed: roundsCompleted,
@@ -413,6 +447,7 @@ async function runQcRepairLoop(options) {
         rounds_completed: roundsCompleted,
         timestamp: new Date().toISOString(),
     });
+    await persistQcRepairOutcome(clusterId, repoRoot, "max-rounds");
     return {
         outcome: "max-rounds",
         rounds_completed: roundsCompleted,

package/dist/qc/runner.js

@@ -298,8 +298,16 @@ async function runSingleProvider(provider, scope, options, fallbackSource) {
                 resolve({ result, success: true });
             }
             catch (parseError) {
-                const result = buildFailedResult(provider, scope, startedAt, "parse-failed", output, { parserResult: "failed" });
-                emitProviderFailed(options.telemetryFile, scope.runId, scope.clusterId, provider.name, "parse-failed", output.exitCode);
+                const reason = typeof parseError === "object" &&
+                    parseError !== null &&
+                    "qcFailureReason" in parseError &&
+                    typeof parseError.qcFailureReason === "string"
+                    ? parseError.qcFailureReason
+                    : "parse-failed";
+                const result = buildFailedResult(provider, scope, startedAt, reason, output, {
+                    parserResult: "failed",
+                });
+                emitProviderFailed(options.telemetryFile, scope.runId, scope.clusterId, provider.name, reason, output.exitCode);
                 resolve({ result, success: false });
             }
         });

package/dist/qc/schemas.js

@@ -42,6 +42,7 @@ exports.qcFailureReasonSchema = zod_1.z.enum([
     "nonzero-exit",
     "parse-failed",
     "empty-output",
+    "unusable-output",
     "unsupported-mode",
     "unavailable-provider",
 ]);

package/dist/types/sol-metrics.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * SOL raw metric event contracts.
+ *
+ * Typed contracts for the raw metric events that the SOL scoring pipeline
+ * distinguishes when building evidence and scorecards. These types name the
+ * six metric categories defined in the POL-487 acceptance criteria:
+ *
+ *   1. Provider startup failure
+ *   2. Router fallback
+ *   3. Worker execution failure
+ *   4. Validation failure
+ *   5. QC findings
+ *   6. User / Foreman intervention
+ *
+ * These are read-model types — they normalize the raw telemetry events and
+ * result packet signals into a typed contract that scoring functions consume.
+ * Nothing in this file writes to artifacts or triggers side effects.
+ *
+ * Relationship to SolEvidence:
+ *   SolMetricEvent records are materialized by the evidence loader into the
+ *   SolEvidence structure. The SolEvidence fields (foreman, worker, router,
+ *   qc, intervention) already carry the aggregated versions; these typed
+ *   event contracts let callers reason about individual metric records and
+ *   construct per-scope scorecards.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isProviderStartupFailure = isProviderStartupFailure;
+exports.isRouterFallback = isRouterFallback;
+exports.isWorkerExecutionFailure = isWorkerExecutionFailure;
+exports.isValidationFailure = isValidationFailure;
+exports.isQcFinding = isQcFinding;
+exports.isIntervention = isIntervention;
+exports.summarizeMetricEvents = summarizeMetricEvents;
+// ──────────────────────────────────────────────
+// Type guards
+// ──────────────────────────────────────────────
+function isProviderStartupFailure(e) {
+    return e.category === "provider-startup-failure";
+}
+function isRouterFallback(e) {
+    return e.category === "router-fallback";
+}
+function isWorkerExecutionFailure(e) {
+    return e.category === "worker-execution-failure";
+}
+function isValidationFailure(e) {
+    return e.category === "validation-failure";
+}
+function isQcFinding(e) {
+    return e.category === "qc-finding";
+}
+function isIntervention(e) {
+    return e.category === "user-intervention" || e.category === "foreman-intervention";
+}
+/**
+ * Compute a SolMetricSummary from a list of metric events.
+ */
+function summarizeMetricEvents(events) {
+    let providerStartupFailures = 0;
+    let routerFallbacks = 0;
+    let routerFallbackSuccesses = 0;
+    let workerExecutionFailures = 0;
+    let validationFailures = 0;
+    let qcFindingsTotal = 0;
+    let qcFindingsBlocking = 0;
+    let qcFindingsUnvalidated = 0;
+    let userInterventions = 0;
+    let foremanInterventions = 0;
+    for (const e of events) {
+        if (isProviderStartupFailure(e))
+            providerStartupFailures++;
+        else if (isRouterFallback(e)) {
+            routerFallbacks++;
+            if (e.fallback_succeeded)
+                routerFallbackSuccesses++;
+        }
+        else if (isWorkerExecutionFailure(e))
+            workerExecutionFailures++;
+        else if (isValidationFailure(e))
+            validationFailures++;
+        else if (isQcFinding(e)) {
+            qcFindingsTotal++;
+            if (e.blocking)
+                qcFindingsBlocking++;
+            if (e.unvalidated)
+                qcFindingsUnvalidated++;
+        }
+        else if (isIntervention(e)) {
+            if (e.actor === "user")
+                userInterventions++;
+            else
+                foremanInterventions++;
+        }
+    }
+    return {
+        provider_startup_failures: providerStartupFailures,
+        router_fallbacks: routerFallbacks,
+        router_fallback_successes: routerFallbackSuccesses,
+        worker_execution_failures: workerExecutionFailures,
+        validation_failures: validationFailures,
+        qc_findings_total: qcFindingsTotal,
+        qc_findings_blocking: qcFindingsBlocking,
+        qc_findings_unvalidated: qcFindingsUnvalidated,
+        user_interventions: userInterventions,
+        foreman_interventions: foremanInterventions,
+    };
+}