avorelo 0.1.0 → 0.2.0

package/scripts/lib/proof-drilldown.js

@@ -1,383 +0,0 @@
-"use strict";
-
-/**
- * Explainability Drill-Down (Surface 3).
- */
-
-const { REASON_CODE_PROOF_MAP } = require("./proof-events");
-const { getCanonicalProofFromEntry, formatNextBoundedAction } = require("./proof-canonical");
-
-function buildDrilldown(proofRecord, sessionMetrics) {
-  const timeline = buildProofTimeline(sessionMetrics);
-  const decisions = buildKeyDecisions(sessionMetrics, proofRecord);
-  const boundaries = buildBoundaries(proofRecord);
-
-  return {
-    version: 1,
-    session_id: proofRecord.session_id,
-    started_at: proofRecord.started_at,
-    ended_at: proofRecord.ended_at,
-    completion_status: proofRecord.completion_status,
-    timeline,
-    decisions,
-    boundaries,
-    dimension_counts: proofRecord.dimension_counts,
-  };
-}
-
-function canonicalTimelineStep(metric, signal) {
-  if (!signal) return null;
-  if (signal.family === "control_decision") {
-    return {
-      ts: metric.ts,
-      event: metric.event,
-      tool: metric.tool || null,
-      action: metric.action || null,
-      reason_code: (signal.reason_codes || [])[0] || null,
-      dimension: "control",
-      family: signal.family,
-      description: `${signal.decision} via ${signal.source || "runtime"}${signal.policy_boundary ? ` (${signal.policy_boundary})` : ""}.`,
-    };
-  }
-  if (signal.family === "material_step") {
-    return {
-      ts: metric.ts,
-      event: metric.event,
-      tool: metric.tool || null,
-      action: metric.action || null,
-      reason_code: (signal.reason_codes || [])[0] || null,
-      dimension: signal.value_type === "efficiency" ? "efficiency" : signal.value_type === "control" ? "control" : "trust",
-      family: signal.family,
-      description: signal.notes || signal.step_type || "Material runtime step recorded.",
-    };
-  }
-  if (signal.family === "safe_stop") {
-    return {
-      ts: metric.ts,
-      event: metric.event,
-      tool: metric.tool || null,
-      action: metric.action || null,
-      reason_code: (signal.reason_codes || [])[0] || "STOP_SNAPSHOT",
-      dimension: "trust",
-      family: signal.family,
-      description: `Safe stop recorded${signal.safe_stop_reason ? `: ${signal.safe_stop_reason}` : ""}.`,
-    };
-  }
-  if (signal.family === "completion_truth") {
-    return {
-      ts: metric.ts,
-      event: metric.event,
-      tool: metric.tool || null,
-      action: metric.action || null,
-      reason_code: (signal.reason_codes || [])[0] || "TASK_COMPLETED",
-      dimension: "outcome",
-      family: signal.family,
-      description: `Completion recorded as ${signal.completion_status || "unknown"}.`,
-    };
-  }
-  return null;
-}
-
-function buildProofTimeline(metrics) {
-  const timeline = [];
-
-  for (const metric of metrics || []) {
-    const canonical = getCanonicalProofFromEntry(metric);
-    if (canonical) {
-      const step = canonicalTimelineStep(metric, canonical);
-      if (step) timeline.push(step);
-      continue;
-    }
-
-    const codes = metric.reasonCodes || [];
-    const materialCodes = codes.filter((code) => {
-      const mapping = REASON_CODE_PROOF_MAP[code];
-      return mapping && mapping.proofWorthy;
-    });
-
-    for (const code of materialCodes) {
-      const mapping = REASON_CODE_PROOF_MAP[code];
-      timeline.push({
-        ts: metric.ts,
-        event: metric.event,
-        tool: metric.tool || null,
-        action: metric.action || null,
-        reason_code: code,
-        dimension: mapping.dimension,
-        family: mapping.family,
-        description: mapping.calmCopy,
-      });
-    }
-  }
-
-  return timeline;
-}
-
-function buildKeyDecisions(metrics, proofRecord) {
-  const decisions = [];
-
-  for (const metric of metrics || []) {
-    const canonical = getCanonicalProofFromEntry(metric);
-    if (!canonical) continue;
-
-    if (canonical.family === "control_decision" && canonical.decision !== "allow") {
-      decisions.push({
-        category: "control",
-        what: `${canonical.decision} ${metric.tool || "tool"} request.`,
-        why: canonical.policy_boundary || canonical.source || "Runtime policy decision.",
-        risk_factor: canonical.risk_level || "unknown",
-        alternative_avoided: "Proceeding without review would have reduced control.",
-        evidence:
-          (canonical.evidence_refs || [])[0] ||
-          (canonical.reason_codes || []).join(", ") ||
-          "No additional evidence recorded.",
-      });
-    }
-
-    if (canonical.family === "material_step") {
-      decisions.push({
-        category: canonical.value_type === "efficiency" ? "efficiency" : canonical.value_type || "trust",
-        what: canonical.step_type || "material step",
-        why: canonical.notes || "Runtime intervention recorded.",
-        risk_factor: canonical.value_type || "runtime",
-        alternative_avoided: "Leaving this unhandled would have reduced trust, control, or efficiency.",
-        evidence:
-          canonical.artifact_ref ||
-          (canonical.evidence_refs || [])[0] ||
-          (canonical.reason_codes || []).join(", ") ||
-          "No additional evidence recorded.",
-      });
-    }
-
-    if (canonical.family === "safe_stop") {
-      decisions.push({
-        category: "trust",
-        what: "Recorded a safe stop boundary.",
-        why: canonical.safe_stop_reason || "Runtime requested a bounded stop.",
-        risk_factor: "progress_loss",
-        alternative_avoided: "Continuing without a safe stop could have lost progress or exceeded the boundary.",
-        evidence: canonical.progress_ref || (canonical.evidence_refs || [])[0] || "Stop snapshot saved.",
-      });
-    }
-  }
-
-  if (decisions.length > 0) return decisions;
-
-  return buildFallbackDecisions(metrics);
-}
-
-function buildFallbackDecisions(metrics) {
-  const decisions = [];
-  const loopInterrupts = (metrics || []).filter((metric) =>
-    (metric.reasonCodes || []).includes("LOOP_REPEATED_TOOL")
-  );
-  if (loopInterrupts.length > 0) {
-    decisions.push({
-      category: "efficiency",
-      what: `Interrupted ${loopInterrupts.length} repeated tool loop${loopInterrupts.length > 1 ? "s" : ""}.`,
-      why: "Identical tool sequence detected, indicating a likely unproductive loop.",
-      risk_factor: "wasted_cycles",
-      alternative_avoided: "Continuing the loop would have consumed tokens and time without progress.",
-      evidence: `Tool sequence repeated ${loopInterrupts.length} time${loopInterrupts.length > 1 ? "s" : ""}.`,
-    });
-  }
-  return decisions;
-}
-
-function buildBoundaries(proofRecord) {
-  const boundaries = {
-    did_not_do: [],
-    unresolved: [],
-    requires_human_judgment: [],
-    can_retry_safely: [],
-    recovery_path: null,
-    task_contract: null,
-    repo_truth: null,
-  };
-
-  const ctrl = proofRecord.control || {};
-  const trust = proofRecord.trust || {};
-  const outcome = proofRecord.outcome || {};
-  const taskContract = proofRecord.task_contract || null;
-  const repoTruth = proofRecord.repo_truth || null;
-
-  if (ctrl.risky_actions_blocked > 0) {
-    boundaries.did_not_do.push(
-      `Did not execute ${ctrl.risky_actions_blocked} blocked risky action${ctrl.risky_actions_blocked > 1 ? "s" : ""}.`
-    );
-  }
-  if (ctrl.safe_stop_count > 0) {
-    boundaries.did_not_do.push("Did not continue past safe-stop boundary.");
-  }
-
-  if (trust.unverified_claim_count > 0) {
-    boundaries.unresolved.push(
-      `${trust.unverified_claim_count} claim${trust.unverified_claim_count > 1 ? "s" : ""} could not be verified.`
-    );
-  }
-  if (proofRecord.completion_status === "partial" || proofRecord.completion_status === "ended_without_completion") {
-    boundaries.unresolved.push("Task did not reach full completion.");
-  }
-
-  if (ctrl.risky_actions_downgraded > 0) {
-    boundaries.requires_human_judgment.push(
-      `${ctrl.risky_actions_downgraded} flagged action${ctrl.risky_actions_downgraded > 1 ? "s" : ""} await${ctrl.risky_actions_downgraded > 1 ? "" : "s"} human review.`
-    );
-  }
-  if (outcome.claim_boundary) {
-    boundaries.requires_human_judgment.push(`Claim boundary: ${outcome.claim_boundary}`);
-  }
-
-  if (trust.rollback_available) {
-    boundaries.can_retry_safely.push("Session snapshot available for safe re-entry.");
-  }
-  if (proofRecord.completion_status === "partial") {
-    boundaries.can_retry_safely.push("Partial progress preserved. Can resume from last known good state.");
-  }
-
-  if (taskContract) {
-    const knownEvidenceRefs = new Set([
-      ...(outcome.evidence_refs || []),
-      ...(repoTruth?.evidence_refs || []),
-    ]);
-    const missingExpectedEvidence = (taskContract.evidence_refs || []).filter((ref) => !knownEvidenceRefs.has(ref));
-
-    boundaries.task_contract = {
-      objective: taskContract.objective || null,
-      allowed_paths: taskContract.allowed_paths || [],
-      requested_outputs: taskContract.requested_outputs || [],
-      stop_conditions: taskContract.stop_conditions || [],
-      expected_evidence_refs: taskContract.evidence_refs || [],
-      review_reasons: taskContract.review_reasons || [],
-    };
-
-    if ((taskContract.review_reasons || []).length > 0) {
-      boundaries.requires_human_judgment.push(
-        `Task contract review triggers: ${taskContract.review_reasons.join(", ")}`
-      );
-    }
-    if (missingExpectedEvidence.length > 0) {
-      boundaries.unresolved.push(
-        `Expected evidence refs still missing for bounded claims: ${missingExpectedEvidence.join(", ")}`
-      );
-    }
-  }
-
-  if (repoTruth) {
-    boundaries.repo_truth = {
-      where_am_i_now: repoTruth.where_am_i_now || null,
-      what_can_i_honestly_claim: repoTruth.what_can_i_honestly_claim || null,
-      readiness_status: repoTruth.readiness_status || null,
-      artifact_truth_status: repoTruth.artifact_truth_status || null,
-      rollback_trigger: repoTruth.rollback_trigger || null,
-    };
-
-    if (repoTruth.what_can_i_honestly_claim) {
-      boundaries.requires_human_judgment.push(`Honest claim boundary: ${repoTruth.what_can_i_honestly_claim}`);
-    }
-    if (repoTruth.readiness_status) {
-      boundaries.requires_human_judgment.push(`Readiness status: ${repoTruth.readiness_status}`);
-    }
-    if (repoTruth.rollback_trigger) {
-      boundaries.can_retry_safely.push(`Rollback trigger is explicit: ${repoTruth.rollback_trigger}.`);
-    }
-  }
-
-  boundaries.recovery_path = formatNextBoundedAction(outcome.next_bounded_action);
-  return boundaries;
-}
-
-function renderDrilldownMarkdown(drilldown) {
-  const lines = [
-    "## Wuz Run Details",
-    "",
-    `Session: ${drilldown.session_id}`,
-    `Status: ${drilldown.completion_status}`,
-    drilldown.started_at ? `Started: ${drilldown.started_at}` : "",
-    drilldown.ended_at ? `Ended: ${drilldown.ended_at}` : "",
-    "",
-  ];
-
-  if (drilldown.timeline.length > 0) {
-    lines.push("### Proof Timeline");
-    for (const step of drilldown.timeline) {
-      lines.push(`- [${step.ts}] **${step.dimension}**: ${step.description}`);
-    }
-    lines.push("");
-  }
-
-  if (drilldown.decisions.length > 0) {
-    lines.push("### Key Decisions");
-    for (const decision of drilldown.decisions) {
-      lines.push(`#### ${decision.what}`);
-      lines.push(`- **Why**: ${decision.why}`);
-      lines.push(`- **Risk factor**: ${decision.risk_factor}`);
-      lines.push(`- **Alternative avoided**: ${decision.alternative_avoided}`);
-      lines.push(`- **Evidence**: ${decision.evidence}`);
-      lines.push("");
-    }
-  }
-
-  const boundaries = drilldown.boundaries;
-  if (boundaries) {
-    lines.push("### Boundaries");
-    if (boundaries.did_not_do.length > 0) {
-      lines.push("**What Wuz did not do:**");
-      boundaries.did_not_do.forEach((line) => lines.push(`- ${line}`));
-    }
-    if (boundaries.unresolved.length > 0) {
-      lines.push("**Unresolved:**");
-      boundaries.unresolved.forEach((line) => lines.push(`- ${line}`));
-    }
-    if (boundaries.requires_human_judgment.length > 0) {
-      lines.push("**Requires human judgment:**");
-      boundaries.requires_human_judgment.forEach((line) => lines.push(`- ${line}`));
-    }
-    if (boundaries.can_retry_safely.length > 0) {
-      lines.push("**Can retry safely:**");
-      boundaries.can_retry_safely.forEach((line) => lines.push(`- ${line}`));
-    }
-    if (boundaries.task_contract) {
-      lines.push("**Task contract:**");
-      if (boundaries.task_contract.objective) lines.push(`- Objective: ${boundaries.task_contract.objective}`);
-      if (boundaries.task_contract.allowed_paths.length > 0) {
-        lines.push(`- Allowed scope: ${boundaries.task_contract.allowed_paths.join(", ")}`);
-      }
-      if (boundaries.task_contract.requested_outputs.length > 0) {
-        lines.push(`- Requested outputs: ${boundaries.task_contract.requested_outputs.join(", ")}`);
-      }
-      if (boundaries.task_contract.stop_conditions.length > 0) {
-        lines.push(`- Stop conditions: ${boundaries.task_contract.stop_conditions.join(" | ")}`);
-      }
-    }
-    if (boundaries.repo_truth) {
-      lines.push("**Canonical state:**");
-      if (boundaries.repo_truth.where_am_i_now) {
-        lines.push(`- Where am I now: ${boundaries.repo_truth.where_am_i_now}`);
-      }
-      if (boundaries.repo_truth.what_can_i_honestly_claim) {
-        lines.push(`- Honest claim: ${boundaries.repo_truth.what_can_i_honestly_claim}`);
-      }
-      if (boundaries.repo_truth.readiness_status) {
-        lines.push(`- Readiness: ${boundaries.repo_truth.readiness_status}`);
-      }
-      if (boundaries.repo_truth.artifact_truth_status) {
-        lines.push(`- Artifact truth: ${boundaries.repo_truth.artifact_truth_status}`);
-      }
-      if (boundaries.repo_truth.rollback_trigger) {
-        lines.push(`- Rollback trigger: ${boundaries.repo_truth.rollback_trigger}`);
-      }
-    }
-    if (boundaries.recovery_path) {
-      lines.push(`**Recovery path:** ${boundaries.recovery_path}`);
-    }
-    lines.push("");
-  }
-
-  return lines.filter((line) => line !== undefined).join("\n");
-}
-
-module.exports = {
-  buildDrilldown,
-  renderDrilldownMarkdown,
-};