@lsctech/polaris 0.5.8 → 0.5.10

package/dist/medic/run-health-consult.js

@@ -0,0 +1,381 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMedicRunHealthConsult = runMedicRunHealthConsult;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const index_js_1 = require("../run-health/index.js");
+const chart_id_js_1 = require("./chart-id.js");
+const treatment_packets_js_1 = require("./treatment-packets.js");
+function appendTelemetry(telemetryFile, event) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(telemetryFile), { recursive: true });
+    (0, node_fs_1.writeFileSync)(telemetryFile, JSON.stringify(event) + "\n", { flag: "a", encoding: "utf-8" });
+}
+function symptomNeedsTreatment(symptom) {
+    return symptom.severity === "critical" || symptom.severity === "high";
+}
+function deriveQcArtifactRefs(report) {
+    const refs = new Set([
+        ...report.evidence_refs,
+        ...report.symptoms.flatMap((s) => s.evidence_refs),
+    ]);
+    return Array.from(refs);
+}
+function deriveDiagnosis(report) {
+    const codes = report.symptoms.map((s) => s.code);
+    const unique = Array.from(new Set(codes));
+    return `Run-health report for ${report.run_id} recorded ${report.symptoms.length} symptom(s): ${unique.join(", ")}.`;
+}
+function deriveDecision(report) {
+    const treatable = report.symptoms.filter(symptomNeedsTreatment);
+    if (treatable.length === 0) {
+        return {
+            decision: "no-treatment-needed",
+            rationale: "No critical or high-severity symptoms recorded; observation and follow-up are sufficient.",
+        };
+    }
+    const plan = treatable.map((s) => `Round-1 treatment for ${s.id} (${s.code}): address ${s.message}`);
+    return {
+        decision: "treatment-required",
+        rationale: `${treatable.length} symptom(s) require treatment.`,
+        treatmentPlan: plan,
+    };
+}
+function writeChart(chart, runId, repoRoot) {
+    const chartsDir = (0, node_path_1.join)(repoRoot, "smartdocs", "medic", "charts");
+    (0, node_fs_1.mkdirSync)(chartsDir, { recursive: true });
+    const nextId = (0, chart_id_js_1.generateNextChartId)(chartsDir);
+    const chartId = nextId.full;
+    const now = new Date().toISOString();
+    const treatmentPlanText = chart.treatment_plan && chart.treatment_plan.length > 0
+        ? chart.treatment_plan.map((p) => `- ${p}`).join("\n")
+        : "No treatment required.";
+    const followUpText = chart.follow_up_conditions && chart.follow_up_conditions.length > 0
+        ? chart.follow_up_conditions.map((c) => `- ${c}`).join("\n")
+        : "None.";
+    const noTreatmentText = chart.no_treatment_rationale
+        ? chart.no_treatment_rationale
+        : "N/A";
+    const content = `---
+chart_id: ${chartId}
+cluster_id: ${chart.cluster_id}
+route: src/run-health
+status: active
+related_charts: []
+created: ${now}
+updated: ${now}
+---
+
+## Problem
+
+Run-health symptoms were recorded during ${runId}.
+
+## Symptoms
+
+${chart.symptoms.map((s) => `- **${s.code}** (${s.id}): ${s.message}`).join("\n")}
+
+## Root Cause
+
+${chart.diagnosis}
+
+## Affected Files
+
+${chart.evidence_refs.join("\n")}
+
+## Treatment
+
+${treatmentPlanText}
+
+## Validation
+
+Treatment workers must pass their embedded validation commands.
+
+## Prevention
+
+Review run-health symptoms and root causes to prevent recurrence.
+
+## When To Read This Chart
+
+When similar symptoms appear in future runs.
+
+## Decision
+
+**Decision:** ${chart.decision}
+
+**No-treatment rationale:** ${noTreatmentText}
+
+**Follow-up conditions:**
+${followUpText}
+`;
+    const filePath = (0, node_path_1.join)(chartsDir, `${chartId}.md`);
+    (0, node_fs_1.writeFileSync)(filePath, content, "utf-8");
+    return (0, node_path_1.relative)(repoRoot, filePath);
+}
+function markInProgress(report, chartRef, repoRoot) {
+    (0, index_js_1.markMedicDecision)(report.run_id, { status: "in-progress", chartRefs: [chartRef] }, repoRoot);
+}
+function markResolved(report, chartRef, treatmentRefs, outcome, repoRoot) {
+    (0, index_js_1.markMedicDecision)(report.run_id, {
+        status: "resolved",
+        chartRefs: [chartRef],
+        treatmentPacketRefs: treatmentRefs,
+        resolvedAt: new Date().toISOString(),
+        resolutionNotes: `Terminal outcome: ${outcome}`,
+    }, repoRoot);
+}
+async function runMedicRunHealthConsult(input) {
+    const { packet, repoRoot, stateFile, telemetryFile, branch, validationCommands, maxConcurrentWorkers, dryRun, dispatchTreatmentWorkerFn, } = input;
+    const now = new Date().toISOString();
+    appendTelemetry(telemetryFile, {
+        event: "medic-run-health-consult-started",
+        run_id: packet.run_id,
+        cluster_id: packet.cluster_id,
+        dispatch_id: packet.dispatch_id,
+        timestamp: now,
+    });
+    const report = (0, index_js_1.readRunHealthReport)(packet.run_id, repoRoot);
+    if (!report) {
+        const error = `No run-health report found for run "${packet.run_id}"`;
+        appendTelemetry(telemetryFile, {
+            event: "medic-run-health-terminal",
+            run_id: packet.run_id,
+            cluster_id: packet.cluster_id,
+            dispatch_id: packet.dispatch_id,
+            outcome: "error",
+            error,
+            timestamp: new Date().toISOString(),
+        });
+        return {
+            run_id: packet.run_id,
+            cluster_id: packet.cluster_id,
+            dispatch_id: packet.dispatch_id,
+            status: "error",
+            chart_id: null,
+            decision: "terminal",
+            treatment_packet_refs: [],
+            terminal_outcome: "error",
+            error_message: error,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    const decisionInfo = deriveDecision(report);
+    const chart = {
+        chart_id: "", // filled in after write
+        cluster_id: packet.cluster_id,
+        symptoms: report.symptoms.map((s) => ({ id: s.id, code: s.code, message: s.message })),
+        diagnosis: deriveDiagnosis(report),
+        evidence_refs: deriveQcArtifactRefs(report),
+        decision: decisionInfo.decision,
+        treatment_plan: decisionInfo.treatmentPlan,
+        no_treatment_rationale: decisionInfo.rationale,
+        follow_up_conditions: ["Re-check run-health report after next run."],
+        created_at: now,
+    };
+    const chartRef = writeChart(chart, packet.run_id, repoRoot);
+    chart.chart_id = chartRef.replace("smartdocs/medic/charts/", "").replace(".md", "");
+    appendTelemetry(telemetryFile, {
+        event: "medic-run-health-chart-created",
+        run_id: packet.run_id,
+        cluster_id: packet.cluster_id,
+        dispatch_id: packet.dispatch_id,
+        chart_id: chart.chart_id,
+        chart_ref: chartRef,
+        decision: chart.decision,
+        timestamp: new Date().toISOString(),
+    });
+    markInProgress(report, chart.chart_id, repoRoot);
+    if (chart.decision === "no-treatment-needed") {
+        const outcome = "no-treatment-needed";
+        markResolved(report, chart.chart_id, [], outcome, repoRoot);
+        appendTelemetry(telemetryFile, {
+            event: "medic-run-health-terminal",
+            run_id: packet.run_id,
+            cluster_id: packet.cluster_id,
+            dispatch_id: packet.dispatch_id,
+            outcome,
+            chart_id: chart.chart_id,
+            timestamp: new Date().toISOString(),
+        });
+        return {
+            run_id: packet.run_id,
+            cluster_id: packet.cluster_id,
+            dispatch_id: packet.dispatch_id,
+            status: "resolved",
+            chart_id: chart.chart_id,
+            decision: chart.decision,
+            treatment_packet_refs: [],
+            terminal_outcome: outcome,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    if (!dispatchTreatmentWorkerFn) {
+        const error = "dispatchTreatmentWorkerFn is required when treatment is required";
+        appendTelemetry(telemetryFile, {
+            event: "medic-run-health-terminal",
+            run_id: packet.run_id,
+            cluster_id: packet.cluster_id,
+            dispatch_id: packet.dispatch_id,
+            outcome: "error",
+            error,
+            chart_id: chart.chart_id,
+            timestamp: new Date().toISOString(),
+        });
+        return {
+            run_id: packet.run_id,
+            cluster_id: packet.cluster_id,
+            dispatch_id: packet.dispatch_id,
+            status: "error",
+            chart_id: chart.chart_id,
+            decision: "terminal",
+            treatment_packet_refs: [],
+            terminal_outcome: "error",
+            error_message: error,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    const maxRounds = Math.max(1, packet.policy_limits.max_treatment_rounds);
+    let round = 1;
+    let remainingSymptoms = report.symptoms.filter(symptomNeedsTreatment);
+    const allTreatmentRefs = [];
+    const terminalEvent = (outcome) => appendTelemetry(telemetryFile, {
+        event: "medic-run-health-terminal",
+        run_id: packet.run_id,
+        cluster_id: packet.cluster_id,
+        dispatch_id: packet.dispatch_id,
+        outcome,
+        chart_id: chart.chart_id,
+        rounds_completed: round,
+        timestamp: new Date().toISOString(),
+    });
+    while (round <= maxRounds && remainingSymptoms.length > 0) {
+        const syntheticReport = {
+            ...report,
+            symptoms: remainingSymptoms,
+        };
+        const treatmentPackets = (0, treatment_packets_js_1.buildTreatmentPackets)({
+            report: syntheticReport,
+            round,
+            repoRoot,
+            validationCommands: validationCommands ?? treatment_packets_js_1.DEFAULT_TREATMENT_VALIDATION_COMMANDS,
+        });
+        const treatmentRefs = treatmentPackets.map((t) => (0, node_path_1.join)(".polaris", "clusters", t.cluster_id, "medic", `${t.packet_id}.json`));
+        allTreatmentRefs.push(...treatmentRefs);
+        appendTelemetry(telemetryFile, {
+            event: "medic-run-health-treatment-packets-created",
+            run_id: packet.run_id,
+            cluster_id: packet.cluster_id,
+            dispatch_id: packet.dispatch_id,
+            round,
+            packet_count: treatmentPackets.length,
+            packet_refs: treatmentRefs,
+            timestamp: new Date().toISOString(),
+        });
+        const results = [];
+        try {
+            for (const treatment of treatmentPackets) {
+                if (dryRun) {
+                    results.push({ packet_id: treatment.packet_id, status: "success" });
+                    continue;
+                }
+                const result = await dispatchTreatmentWorkerFn({
+                    treatment,
+                    stateFile,
+                    telemetryFile,
+                    branch,
+                    maxConcurrentWorkers,
+                });
+                results.push(result);
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            appendTelemetry(telemetryFile, {
+                event: "medic-run-health-treatment-dispatch-error",
+                run_id: packet.run_id,
+                cluster_id: packet.cluster_id,
+                dispatch_id: packet.dispatch_id,
+                round,
+                error: msg,
+                timestamp: new Date().toISOString(),
+            });
+            const outcome = "dispatch-failure";
+            markResolved(report, chart.chart_id, allTreatmentRefs, outcome, repoRoot);
+            terminalEvent(outcome);
+            return {
+                run_id: packet.run_id,
+                cluster_id: packet.cluster_id,
+                dispatch_id: packet.dispatch_id,
+                status: "error",
+                chart_id: chart.chart_id,
+                decision: "terminal",
+                treatment_packet_refs: allTreatmentRefs,
+                terminal_outcome: outcome,
+                error_message: msg,
+                timestamp: new Date().toISOString(),
+            };
+        }
+        const failed = results.filter((r) => r.status === "failure");
+        const succeeded = results.filter((r) => r.status === "success");
+        appendTelemetry(telemetryFile, {
+            event: "medic-run-health-treatment-completed",
+            run_id: packet.run_id,
+            cluster_id: packet.cluster_id,
+            dispatch_id: packet.dispatch_id,
+            round,
+            success_count: succeeded.length,
+            failure_count: failed.length,
+            failed_packet_ids: failed.map((f) => f.packet_id),
+            timestamp: new Date().toISOString(),
+        });
+        if (failed.length === 0) {
+            const outcome = "treatment-success";
+            markResolved(report, chart.chart_id, allTreatmentRefs, outcome, repoRoot);
+            terminalEvent(outcome);
+            return {
+                run_id: packet.run_id,
+                cluster_id: packet.cluster_id,
+                dispatch_id: packet.dispatch_id,
+                status: "resolved",
+                chart_id: chart.chart_id,
+                decision: "terminal",
+                treatment_packet_refs: allTreatmentRefs,
+                terminal_outcome: outcome,
+                timestamp: new Date().toISOString(),
+            };
+        }
+        if (round < maxRounds) {
+            const failedIds = new Set(failed.map((f) => f.packet_id));
+            remainingSymptoms = remainingSymptoms.filter((s) => failedIds.has((0, treatment_packets_js_1.buildTreatmentPacketId)(report.run_id, round, s.id)));
+            round += 1;
+        }
+        else {
+            const outcome = "max-rounds";
+            markResolved(report, chart.chart_id, allTreatmentRefs, outcome, repoRoot);
+            terminalEvent(outcome);
+            return {
+                run_id: packet.run_id,
+                cluster_id: packet.cluster_id,
+                dispatch_id: packet.dispatch_id,
+                status: "resolved",
+                chart_id: chart.chart_id,
+                decision: "terminal",
+                treatment_packet_refs: allTreatmentRefs,
+                terminal_outcome: outcome,
+                timestamp: new Date().toISOString(),
+            };
+        }
+    }
+    const outcome = remainingSymptoms.length === 0 ? "treatment-success" : "max-rounds";
+    markResolved(report, chart.chart_id, allTreatmentRefs, outcome, repoRoot);
+    terminalEvent(outcome);
+    return {
+        run_id: packet.run_id,
+        cluster_id: packet.cluster_id,
+        dispatch_id: packet.dispatch_id,
+        status: "resolved",
+        chart_id: chart.chart_id,
+        decision: "terminal",
+        treatment_packet_refs: allTreatmentRefs,
+        terminal_outcome: outcome,
+        timestamp: new Date().toISOString(),
+    };
+}

package/dist/medic/treatment-packets.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TREATMENT_PROHIBITED_SCOPE = exports.DEFAULT_TREATMENT_VALIDATION_COMMANDS = void 0;
+exports.getMedicDir = getMedicDir;
+exports.buildTreatmentPacketId = buildTreatmentPacketId;
+exports.buildTreatmentPackets = buildTreatmentPackets;
+exports.compileTreatmentWorkerPacket = compileTreatmentWorkerPacket;
+exports.writeTreatmentPacket = writeTreatmentPacket;
+exports.parseTreatmentWorkerSummary = parseTreatmentWorkerSummary;
+exports.dispatchTreatmentWorker = dispatchTreatmentWorker;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_crypto_1 = require("node:crypto");
+const worker_packet_js_1 = require("../loop/worker-packet.js");
+/** Default validation commands embedded in treatment packets. */
+exports.DEFAULT_TREATMENT_VALIDATION_COMMANDS = [
+    "npm run build",
+    "npm test",
+];
+/** Paths a treatment worker must never touch. */
+exports.DEFAULT_TREATMENT_PROHIBITED_SCOPE = [
+    ".polaris/**",
+    ".taskchain_artifacts/**",
+    "**/telemetry.jsonl",
+];
+/**
+ * Return the cluster-scoped Medic directory where treatment packets are persisted.
+ */
+function getMedicDir(clusterId, repoRoot) {
+    return (0, node_path_1.join)(repoRoot, ".polaris", "clusters", clusterId, "medic");
+}
+/**
+ * Build a deterministic treatment packet id from run id, round, and symptom.
+ */
+function buildTreatmentPacketId(runId, round, symptomId) {
+    const base = `${runId}-r${round}-${symptomId}`;
+    return base.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+/**
+ * Determine whether a symptom should receive a treatment packet.
+ */
+function symptomNeedsTreatment(symptom) {
+    return symptom.severity === "critical" || symptom.severity === "high";
+}
+/**
+ * Derive an allowed file scope from symptom evidence refs.
+ * Falls back to the repository root when no concrete refs are present.
+ */
+function scopeFromEvidenceRefs(refs) {
+    const fileRefs = refs.filter((ref) => ref.includes("/") || ref.includes("."));
+    return fileRefs.length > 0 ? fileRefs : ["."];
+}
+/**
+ * Build treatment packets for every symptom that needs treatment in the report.
+ */
+function buildTreatmentPackets(input) {
+    const { report, round, repoRoot, validationCommands } = input;
+    const treated = report.symptoms.filter(symptomNeedsTreatment);
+    return treated.map((symptom) => {
+        const packetId = buildTreatmentPacketId(report.run_id, round, symptom.id);
+        const dispatchId = (0, node_crypto_1.randomUUID)();
+        const resultFile = (0, node_path_1.join)(getMedicDir(report.cluster_id, repoRoot), `${packetId}-result.json`);
+        return {
+            packet_id: packetId,
+            run_id: report.run_id,
+            cluster_id: report.cluster_id,
+            round,
+            source_symptom_ids: [symptom.id],
+            allowed_scope: scopeFromEvidenceRefs(symptom.evidence_refs),
+            prohibited_scope: exports.DEFAULT_TREATMENT_PROHIBITED_SCOPE,
+            validation_commands: validationCommands ?? exports.DEFAULT_TREATMENT_VALIDATION_COMMANDS,
+            root_cause_hint: `Run-health symptom ${symptom.code}: ${symptom.message}`,
+            dispatch_metadata: {
+                dispatch_id: dispatchId,
+                worker_id: `${report.run_id}:treatment:${packetId}:${Date.now()}`,
+                result_file: resultFile,
+            },
+            status: "pending",
+        };
+    });
+}
+/**
+ * Compile a Medic treatment packet into a normal Foreman WorkerPacket.
+ *
+ * The resulting packet uses `worker_role: "repair"` so it re-enters the same
+ * dispatch path as QC repair workers, with no special implementation behavior.
+ */
+function compileTreatmentWorkerPacket(input) {
+    const { treatment, stateFile, telemetryFile, branch, maxConcurrentWorkers } = input;
+    return (0, worker_packet_js_1.compileRepairWorkerPacket)({
+        runId: treatment.run_id,
+        clusterId: treatment.cluster_id,
+        packetId: treatment.packet_id,
+        branch,
+        stateFile,
+        telemetryFile,
+        round: treatment.round,
+        allowedScope: treatment.allowed_scope,
+        prohibitedScope: treatment.prohibited_scope,
+        validationCommands: treatment.validation_commands,
+        rootCauseHint: treatment.root_cause_hint,
+        resultFile: treatment.dispatch_metadata.result_file,
+        maxConcurrentWorkers,
+    });
+}
+/**
+ * Persist a treatment packet to disk and return its repo-relative path.
+ */
+function writeTreatmentPacket(input) {
+    const { treatment, repoRoot } = input;
+    const dir = getMedicDir(treatment.cluster_id, repoRoot);
+    const filePath = (0, node_path_1.join)(dir, `${treatment.packet_id}.json`);
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    (0, node_fs_1.writeFileSync)(filePath, JSON.stringify(treatment, null, 2), "utf-8");
+    return filePath;
+}
+/**
+ * Parse a treatment worker summary from a dispatch result summary string.
+ */
+function parseTreatmentWorkerSummary(summary) {
+    if (!summary)
+        return null;
+    try {
+        const parsed = JSON.parse(summary);
+        const status = String(parsed["status"] ?? "").toLowerCase();
+        const commit = typeof parsed["commit"] === "string" ? parsed["commit"] : undefined;
+        const error_message = typeof parsed["error_message"] === "string" ? parsed["error_message"] : undefined;
+        if (status === "done" || status === "success") {
+            return { status: "done", commit, error_message };
+        }
+        if (status === "blocked") {
+            return { status: "blocked", commit, error_message };
+        }
+        return { status: "failure", commit, error_message };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Dispatch a single treatment worker through the normal Foreman adapter and
+ * return a normalized treatment result.
+ */
+async function dispatchTreatmentWorker(input) {
+    const { treatment, stateFile, telemetryFile, branch, repoRoot, dispatch, maxConcurrentWorkers } = input;
+    writeTreatmentPacket({ treatment, repoRoot });
+    const workerPacket = compileTreatmentWorkerPacket({
+        treatment,
+        stateFile,
+        telemetryFile,
+        branch,
+        maxConcurrentWorkers,
+    });
+    const result = await dispatch(workerPacket);
+    const summary = parseTreatmentWorkerSummary(result.summary);
+    if (result.exit_code === 0 && summary?.status === "done") {
+        return {
+            packet_id: treatment.packet_id,
+            status: "success",
+            commit_sha: summary.commit,
+        };
+    }
+    return {
+        packet_id: treatment.packet_id,
+        status: "failure",
+        error_message: summary?.error_message ??
+            (result.exit_code === 0 ? "treatment worker returned non-done status" : "dispatch failed"),
+    };
+}