avorelo 0.1.0

package/scripts/lib/proof-drilldown.js

@@ -0,0 +1,383 @@
+"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,
+};