@lsctech/polaris 0.5.5 → 0.5.7

package/dist/qc/runner.js

@@ -2,15 +2,29 @@
 /**
  * QC provider execution runner.
  *
- * Runs a provider-specific review command, handles timeouts, and normalizes
- * the raw output into a Polaris QcResult with runtime fields populated.
+ * Runs a provider-specific review command, classifies non-finding failures, and
+ * normalizes the outcome into a Polaris QcResult with a durable providerAttempt
+ * record. Supports optional fallback chains driven by per-provider failure policy.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.executeQcProvider = executeQcProvider;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-function makeSyntheticResult(provider, scope, startedAt, status, summary) {
+const policy_js_1 = require("./policy.js");
+function makeProviderAttempt(providerName, status, output, overrides) {
+    return {
+        provider: providerName,
+        status,
+        rawOutputAvailable: (output.stdout?.length ?? 0) > 0 || (output.stderr?.length ?? 0) > 0,
+        rawOutputRetained: false,
+        stdoutLength: output.stdout?.length ?? 0,
+        stderrLength: output.stderr?.length ?? 0,
+        exitCode: output.exitCode,
+        ...overrides,
+    };
+}
+function makeSyntheticResult(provider, scope, startedAt, status, summary, providerAttempt) {
     const completedAt = new Date().toISOString();
     return {
         schemaVersion: "1.0",
@@ -28,11 +42,12 @@ function makeSyntheticResult(provider, scope, startedAt, status, summary) {
         rawArtifactPaths: [],
         parserVersion: `${provider.name}-synthetic`,
         policyDecision: {
-            blocksDelivery: false,
-            requiresOperatorReview: status !== "passed",
+            blocksDelivery: status === "blocked" || status === "failed",
+            requiresOperatorReview: status !== "passed" && status !== "skipped",
             routedToRepair: false,
             summary,
         },
+        providerAttempt,
     };
 }
 function appendTelemetry(telemetryFile, event) {
@@ -46,30 +61,131 @@ function appendTelemetry(telemetryFile, event) {
         // Telemetry is best-effort.
     }
 }
-function resolveExecutionFailure(provider, scope, options, startedAt, output, reason) {
-    const result = makeSyntheticResult(provider, scope, startedAt, "failed", reason);
-    appendTelemetry(options.telemetryFile, {
-        event: "qc-provider-execution-failed",
-        run_id: scope.runId,
-        cluster_id: scope.clusterId,
-        provider: provider.name,
-        exit_code: output.exitCode,
+function resolveMode(scope) {
+    return scope.prUrl ? "pr" : "local";
+}
+function isModeSupported(provider, scope) {
+    const mode = resolveMode(scope);
+    return provider.supportedModes.includes(mode);
+}
+function getProviderConfig(name, config) {
+    return config?.providers?.[name];
+}
+function classifyTerminalFailure(error, output) {
+    const execError = error;
+    if (execError?.killed && execError?.signal === "SIGTERM") {
+        return "timeout";
+    }
+    if (execError?.code === "ENOENT") {
+        return "command-not-found";
+    }
+    // Only scan output for failure keywords if the command actually failed
+    if (!error && output.exitCode === 0) {
+        return undefined;
+    }
+    const text = `${output.stdout ?? ""}\n${output.stderr ?? ""}`.toLowerCase();
+    if (text.includes("rate limit") ||
+        text.includes("429") ||
+        text.includes("too many requests")) {
+        return "rate-limited";
+    }
+    if (text.includes("unauthorized") ||
+        text.includes("authentication failed") ||
+        text.includes("invalid token") ||
+        text.includes("401") ||
+        text.includes("forbidden") ||
+        text.includes("403")) {
+        return "auth-failure";
+    }
+    if (text.includes("unavailable") ||
+        text.includes("service unavailable") ||
+        text.includes("503") ||
+        text.includes("connection refused") ||
+        text.includes("econnrefused")) {
+        return "unavailable-provider";
+    }
+    return undefined;
+}
+function classifyPostParseFailure(output, parsed) {
+    if (parsed.findings.length > 0) {
+        return undefined;
+    }
+    const stdout = output.stdout ?? "";
+    const stderr = output.stderr ?? "";
+    if (stdout.trim().length === 0 && stderr.trim().length === 0) {
+        if (output.exitCode !== 0) {
+            return "empty-output";
+        }
+        return undefined;
+    }
+    if (output.exitCode !== 0) {
+        return "nonzero-exit";
+    }
+    return undefined;
+}
+function emitProviderAttempted(telemetryFile, runId, clusterId, providerName, fallbackSource) {
+    appendTelemetry(telemetryFile, {
+        event: fallbackSource ? "qc-fallback-attempted" : "qc-provider-attempted",
+        run_id: runId,
+        cluster_id: clusterId,
+        provider: providerName,
+        fallback_source: fallbackSource,
+        timestamp: new Date().toISOString(),
+    });
+}
+function emitProviderFailed(telemetryFile, runId, clusterId, providerName, reason, exitCode) {
+    appendTelemetry(telemetryFile, {
+        event: "qc-provider-failed",
+        run_id: runId,
+        cluster_id: clusterId,
+        provider: providerName,
         reason,
-        timestamp: result.completedAt,
+        exit_code: exitCode,
+        timestamp: new Date().toISOString(),
     });
-    return result;
 }
-/**
- * Execute a provider review command for the given scope.
- *
- * Timeouts produce a synthetic "failed" result so that policy logic downstream
- * can decide whether to block, follow-up, or report passively.
- */
-async function executeQcProvider(provider, scope, options) {
+function emitFallbackSucceeded(telemetryFile, runId, clusterId, providerName, fallbackSource) {
+    appendTelemetry(telemetryFile, {
+        event: "qc-fallback-succeeded",
+        run_id: runId,
+        cluster_id: clusterId,
+        provider: providerName,
+        fallback_source: fallbackSource,
+        timestamp: new Date().toISOString(),
+    });
+}
+function emitAllProvidersFailed(telemetryFile, runId, clusterId, attempted) {
+    appendTelemetry(telemetryFile, {
+        event: "qc-all-providers-failed",
+        run_id: runId,
+        cluster_id: clusterId,
+        attempted_providers: attempted,
+        timestamp: new Date().toISOString(),
+    });
+}
+function buildFailedResult(provider, scope, startedAt, reason, output, overrides) {
+    const providerAttempt = makeProviderAttempt(provider.name, "failure", output, {
+        failureReason: reason,
+        ...overrides,
+    });
+    return makeSyntheticResult(provider, scope, startedAt, "failed", `QC provider ${provider.name} failed: ${reason}`, providerAttempt);
+}
+async function runSingleProvider(provider, scope, options, fallbackSource) {
     const startedAt = new Date().toISOString();
     const command = provider.buildReviewCommand(scope);
     const execFn = options.execFileImpl ?? node_child_process_1.execFile;
     const timeoutMs = options.timeoutMs ?? 300_000; // 5 minutes default
+    const providerConfig = getProviderConfig(provider.name, options.config);
+    emitProviderAttempted(options.telemetryFile, scope.runId, scope.clusterId, provider.name, fallbackSource);
+    if (!isModeSupported(provider, scope)) {
+        const output = {
+            provider: provider.name,
+            exitCode: 1,
+        };
+        const result = buildFailedResult(provider, scope, startedAt, "unsupported-mode", output);
+        emitProviderFailed(options.telemetryFile, scope.runId, scope.clusterId, provider.name, "unsupported-mode");
+        return { result, success: false };
+    }
     return new Promise((resolve) => {
         let stdout = "";
         let stderr = "";
@@ -81,28 +197,77 @@ async function executeQcProvider(provider, scope, options) {
         }, (error, out, err) => {
             stdout = out ?? "";
             stderr = err ?? "";
-            // Detect timeout: execFile kills with SIGTERM on timeout.
-            if (error && error.killed && error.signal === "SIGTERM") {
-                const result = makeSyntheticResult(provider, scope, startedAt, "failed", `QC provider ${provider.name} timed out after ${timeoutMs}ms`);
+            const output = {
+                provider: provider.name,
+                stdout,
+                stderr,
+                exitCode: error ? (typeof error.code === "number" ? error.code : 1) : 0,
+            };
+            const terminalReason = classifyTerminalFailure(error, output);
+            if (terminalReason) {
+                const result = buildFailedResult(provider, scope, startedAt, terminalReason, output);
+                emitProviderFailed(options.telemetryFile, scope.runId, scope.clusterId, provider.name, terminalReason, output.exitCode);
+                resolve({ result, success: false });
+                return;
+            }
+            // Empty output combined with a nonzero exit is an explicit failure.
+            if (output.exitCode !== 0 && stdout.trim().length === 0 && stderr.trim().length === 0) {
+                const result = buildFailedResult(provider, scope, startedAt, "empty-output", output);
+                emitProviderFailed(options.telemetryFile, scope.runId, scope.clusterId, provider.name, "empty-output", output.exitCode);
+                resolve({ result, success: false });
+                return;
+            }
+            // Empty success output is a valid "no findings" result.
+            if (output.exitCode === 0 && stdout.trim().length === 0 && stderr.trim().length === 0) {
+                const completedAt = new Date().toISOString();
+                const result = {
+                    schemaVersion: "1.0",
+                    qcRunId: `${provider.name}-${Date.now()}`,
+                    runId: scope.runId,
+                    clusterId: scope.clusterId,
+                    trigger: scope.prUrl ? "pr" : "completed-cluster",
+                    provider: provider.name,
+                    providerMode: scope.prUrl ? "pr" : "local",
+                    prUrl: scope.prUrl,
+                    startedAt,
+                    completedAt,
+                    status: "passed",
+                    findings: [],
+                    rawArtifactPaths: [],
+                    parserVersion: `${provider.name}-1.0`,
+                    policyDecision: {
+                        blocksDelivery: false,
+                        requiresOperatorReview: false,
+                        routedToRepair: false,
+                        summary: "No findings",
+                    },
+                    providerAttempt: makeProviderAttempt(provider.name, "success", output, {
+                        parserResult: "success",
+                    }),
+                };
                 appendTelemetry(options.telemetryFile, {
-                    event: "qc-provider-timeout",
+                    event: "qc-provider-executed",
                     run_id: scope.runId,
                     cluster_id: scope.clusterId,
                     provider: provider.name,
-                    timeout_ms: timeoutMs,
-                    timestamp: new Date().toISOString(),
+                    trigger: result.trigger,
+                    status: result.status,
+                    findings_count: 0,
+                    exit_code: 0,
+                    timestamp: completedAt,
                 });
-                resolve(result);
+                resolve({ result, success: true });
                 return;
             }
-            const output = {
-                provider: provider.name,
-                stdout,
-                stderr,
-                exitCode: error ? (typeof error.code === "number" ? error.code : 1) : 0,
-            };
             try {
                 const parsed = provider.parse(output);
+                const postParseReason = classifyPostParseFailure(output, parsed);
+                if (postParseReason) {
+                    const result = buildFailedResult(provider, scope, startedAt, postParseReason, output);
+                    emitProviderFailed(options.telemetryFile, scope.runId, scope.clusterId, provider.name, postParseReason, output.exitCode);
+                    resolve({ result, success: false });
+                    return;
+                }
                 const completedAt = new Date().toISOString();
                 const result = {
                     ...parsed,
@@ -115,6 +280,9 @@ async function executeQcProvider(provider, scope, options) {
                     prUrl: scope.prUrl,
                     startedAt,
                     completedAt,
+                    providerAttempt: makeProviderAttempt(provider.name, "success", output, {
+                        parserResult: "success",
+                    }),
                 };
                 appendTelemetry(options.telemetryFile, {
                     event: "qc-provider-executed",
@@ -127,11 +295,126 @@ async function executeQcProvider(provider, scope, options) {
                     exit_code: output.exitCode,
                     timestamp: completedAt,
                 });
-                resolve(result);
+                resolve({ result, success: true });
             }
             catch (parseError) {
-                resolve(resolveExecutionFailure(provider, scope, options, startedAt, output, `QC provider ${provider.name} parse failed: ${parseError instanceof Error ? parseError.message : String(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);
+                resolve({ result, success: false });
             }
         });
     });
 }
+/**
+ * Execute a provider review command for the given scope.
+ *
+ * Timeouts, parse failures, and other non-finding outcomes are normalized
+ * into QcResult objects that carry a providerAttempt classification. When a
+ * QcConfig and QcProviderRegistry are supplied, the runner follows each
+ * provider's fallback list according to its failurePolicy.
+ */
+async function executeQcProvider(provider, scope, options) {
+    const visited = new Set();
+    const attempted = [];
+    async function attemptChain(currentProvider, fallbackSource) {
+        if (visited.has(currentProvider.name)) {
+            return {
+                result: buildFailedResult(currentProvider, scope, new Date().toISOString(), "unavailable-provider", { provider: currentProvider.name, exitCode: 1 }),
+                success: false,
+                sourceProvider: currentProvider.name,
+            };
+        }
+        visited.add(currentProvider.name);
+        attempted.push(currentProvider.name);
+        const { result, success } = await runSingleProvider(currentProvider, scope, options, fallbackSource);
+        if (success) {
+            return { result, success, sourceProvider: currentProvider.name };
+        }
+        const providerConfig = getProviderConfig(currentProvider.name, options.config);
+        const failureAction = (0, policy_js_1.decideProviderFailureAction)(result.providerAttempt?.failureReason ?? "nonzero-exit", providerConfig?.failurePolicy);
+        if (failureAction === "ignore") {
+            const skippedResult = {
+                ...result,
+                status: "skipped",
+                providerAttempt: result.providerAttempt
+                    ? { ...result.providerAttempt, status: "skipped" }
+                    : undefined,
+                policyDecision: {
+                    ...result.policyDecision,
+                    blocksDelivery: false,
+                    requiresOperatorReview: false,
+                    summary: `QC provider ${currentProvider.name} skipped per failure policy`,
+                },
+            };
+            return { result: skippedResult, success: true, sourceProvider: currentProvider.name };
+        }
+        if (failureAction === "block") {
+            const blockedResult = {
+                ...result,
+                status: "blocked",
+                policyDecision: {
+                    ...result.policyDecision,
+                    blocksDelivery: true,
+                    summary: `QC provider ${currentProvider.name} blocked per failure policy`,
+                },
+            };
+            return { result: blockedResult, success: false, sourceProvider: currentProvider.name };
+        }
+        if (failureAction !== "fallback" || !options.registry || !options.config) {
+            return { result, success: false, sourceProvider: currentProvider.name };
+        }
+        const fallbackNames = providerConfig?.fallback ?? [];
+        for (const fallbackName of fallbackNames) {
+            const fallbackProvider = options.registry.get(fallbackName);
+            if (!fallbackProvider) {
+                attempted.push(fallbackName);
+                continue;
+            }
+            const chainResult = await attemptChain(fallbackProvider, currentProvider.name);
+            if (chainResult.success) {
+                // Only emit telemetry and set fallbackSource if not already set by a deeper level
+                const existingFallbackSource = chainResult.result.providerAttempt?.fallbackSource;
+                if (!existingFallbackSource) {
+                    emitFallbackSucceeded(options.telemetryFile, scope.runId, scope.clusterId, chainResult.sourceProvider, currentProvider.name);
+                }
+                const finalResult = {
+                    ...chainResult.result,
+                    providerAttempt: chainResult.result.providerAttempt
+                        ? {
+                            ...chainResult.result.providerAttempt,
+                            fallbackSource: existingFallbackSource ?? currentProvider.name,
+                        }
+                        : undefined,
+                };
+                return { result: finalResult, success: true, sourceProvider: chainResult.sourceProvider };
+            }
+        }
+        return { result, success: false, sourceProvider: currentProvider.name };
+    }
+    const { result, success, sourceProvider } = await attemptChain(provider);
+    if (success) {
+        return result;
+    }
+    // If the primary provider (or its fallback chain) failed and no fallback
+    // succeeded, emit an all-providers-failed result and telemetry event when a
+    // registry/config was supplied so the chain was actually resolvable.
+    if (options.registry && options.config) {
+        emitAllProvidersFailed(options.telemetryFile, scope.runId, scope.clusterId, attempted);
+        const allFailedResult = {
+            ...result,
+            status: "failed",
+            allProvidersFailed: true,
+            providerAttempt: result.providerAttempt
+                ? { ...result.providerAttempt, status: "failure" }
+                : undefined,
+            policyDecision: {
+                ...result.policyDecision,
+                blocksDelivery: true,
+                requiresOperatorReview: true,
+                summary: `All QC providers failed for ${provider.name}`,
+            },
+        };
+        return allFailedResult;
+    }
+    return result;
+}

package/dist/qc/schemas.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.qcResultSchema = exports.qcPolicyDecisionSchema = exports.qcFindingSchema = exports.qcAttributionSchema = exports.qcCodeRangeSchema = exports.qcAttributionReasonSchema = exports.qcAttributionConfidenceSchema = exports.qcRoutingDecisionSchema = exports.qcFindingStatusSchema = exports.qcSeveritySchema = void 0;
+exports.qcRepairPacketManifestSchema = exports.qcRepairPacketSchema = exports.qcRepairPacketStatusSchema = exports.qcResultSchema = exports.qcPolicyDecisionSchema = exports.qcFindingSchema = exports.qcAttributionSchema = exports.qcCodeRangeSchema = exports.qcProviderAttemptSchema = exports.qcProviderAttemptStatusSchema = exports.qcParserResultSchema = exports.qcFailureReasonSchema = exports.qcAttributionReasonSchema = exports.qcAttributionConfidenceSchema = exports.qcRoutingDecisionSchema = exports.qcFindingStatusSchema = exports.qcSeveritySchema = void 0;
 exports.validateQcResult = validateQcResult;
 exports.validateQcFinding = validateQcFinding;
+exports.validateRepairPacketManifest = validateRepairPacketManifest;
 const zod_1 = require("zod");
 exports.qcSeveritySchema = zod_1.z.enum(["critical", "high", "medium", "low", "info"]);
 exports.qcFindingStatusSchema = zod_1.z.enum([
@@ -33,6 +34,37 @@ exports.qcAttributionReasonSchema = zod_1.z.enum([
     "provider-uncertain",
     "unattributed",
 ]);
+exports.qcFailureReasonSchema = zod_1.z.enum([
+    "timeout",
+    "rate-limited",
+    "auth-failure",
+    "command-not-found",
+    "nonzero-exit",
+    "parse-failed",
+    "empty-output",
+    "unsupported-mode",
+    "unavailable-provider",
+]);
+exports.qcParserResultSchema = zod_1.z.enum(["success", "partial", "failed"]);
+exports.qcProviderAttemptStatusSchema = zod_1.z.enum([
+    "success",
+    "failure",
+    "fallback",
+    "skipped",
+]);
+exports.qcProviderAttemptSchema = zod_1.z.object({
+    provider: zod_1.z.string(),
+    status: exports.qcProviderAttemptStatusSchema,
+    failureReason: exports.qcFailureReasonSchema.optional(),
+    fallbackSource: zod_1.z.string().optional(),
+    rawOutputAvailable: zod_1.z.boolean(),
+    rawOutputRetained: zod_1.z.boolean(),
+    rawOutputArtifactPath: zod_1.z.string().optional(),
+    parserResult: exports.qcParserResultSchema.optional(),
+    exitCode: zod_1.z.number().optional(),
+    stdoutLength: zod_1.z.number().int().min(0),
+    stderrLength: zod_1.z.number().int().min(0),
+});
 exports.qcCodeRangeSchema = zod_1.z.object({
     startLine: zod_1.z.number().int().positive(),
     startColumn: zod_1.z.number().int().positive().optional(),
@@ -86,6 +118,8 @@ exports.qcResultSchema = zod_1.z.object({
     rawArtifactPaths: zod_1.z.array(zod_1.z.string()),
     parserVersion: zod_1.z.string(),
     policyDecision: exports.qcPolicyDecisionSchema,
+    providerAttempt: exports.qcProviderAttemptSchema.optional(),
+    allProvidersFailed: zod_1.z.boolean().optional(),
 });
 /**
  * Validate an unknown value as a normalized QC result.
@@ -108,3 +142,46 @@ function validateQcFinding(value) {
     }
     return { success: false, errors: parsed.error.issues.map((issue) => issue.message) };
 }
+exports.qcRepairPacketStatusSchema = zod_1.z.enum([
+    "pending",
+    "dispatched",
+    "completed",
+    "failed",
+    "escalated",
+]);
+exports.qcRepairPacketSchema = zod_1.z.object({
+    packetId: zod_1.z.string(),
+    round: zod_1.z.number().int().min(0),
+    clusterId: zod_1.z.string(),
+    sourceQcRunIds: zod_1.z.array(zod_1.z.string()),
+    findingIds: zod_1.z.array(zod_1.z.string()),
+    severityFloor: exports.qcSeveritySchema,
+    rootCauseHint: zod_1.z.string(),
+    allowedScope: zod_1.z.array(zod_1.z.string()),
+    prohibitedScope: zod_1.z.array(zod_1.z.string()),
+    validationCommands: zod_1.z.array(zod_1.z.string()),
+    routingTarget: exports.qcRoutingDecisionSchema,
+    parallelGroup: zod_1.z.string().nullable(),
+    conflicts: zod_1.z.array(zod_1.z.string()),
+    medic: zod_1.z.boolean(),
+    status: exports.qcRepairPacketStatusSchema,
+    createdAt: zod_1.z.string().datetime(),
+});
+exports.qcRepairPacketManifestSchema = zod_1.z.object({
+    schemaVersion: zod_1.z.string(),
+    clusterId: zod_1.z.string(),
+    round: zod_1.z.number().int().min(0),
+    compiledAt: zod_1.z.string().datetime(),
+    sourceQcRunIds: zod_1.z.array(zod_1.z.string()),
+    packets: zod_1.z.array(exports.qcRepairPacketSchema),
+});
+/**
+ * Validate an unknown value as a compiled repair packet manifest.
+ */
+function validateRepairPacketManifest(value) {
+    const parsed = exports.qcRepairPacketManifestSchema.safeParse(value);
+    if (parsed.success) {
+        return { success: true, manifest: parsed.data };
+    }
+    return { success: false, errors: parsed.error.issues.map((issue) => issue.message) };
+}

package/dist/types/sol-evidence.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * SOL evidence schema.
+ *
+ * Typed inputs for the Self-Optimization Loop (SOL) scoring pipeline.
+ * These types represent the normalized read model over existing durable
+ * run artifacts: state, telemetry, result packets, QC results, and
+ * (future) router decision evidence.
+ *
+ * Design rules:
+ *   - All top-level inputs are optional unless the field documents a
+ *     required identity key (run_id, cluster_id).
+ *   - Future fields from POL-469 (router evidence) and POL-476 (QC
+ *     metrics) are marked with an `availability` tag explaining when
+ *     they will be populated.
+ *   - Nothing in this file mutates run artifacts or triggers side effects.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/sol-score.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * SOL scoring model types.
+ *
+ * Defines the typed output of the SOL score reports for Foremen and Workers.
+ * Each dimension has a score, confidence, and optional skipped reason so that
+ * callers can preserve the full diagnostic signal rather than a single opaque
+ * number.
+ *
+ * Design rules:
+ *   - score is 0.0–1.0 where 1.0 = optimal and 0.0 = worst observed behavior.
+ *   - confidence reflects how trustworthy the score is given the evidence.
+ *   - skipped_reason is set when evidence was absent or insufficient.
+ *   - All dimensions are optional at the top level; only present when the
+ *     relevant evidence was observed for this run.
+ *   - The existing binary gate diagnosis is preserved alongside SOL scores.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lsctech/polaris",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "Polaris — standalone taskchain orchestration framework for governed AI agent workflows",
   "bin": {
     "polaris": "dist/cli/index.js",