avorelo 0.1.0

package/scripts/lib/proof-record.js

@@ -0,0 +1,461 @@
+"use strict";
+
+/**
+ * Shared Proof Record Model (ProofRecordV1).
+ *
+ * A ProofRecordV1 is composed per-run from existing metrics + outcome events.
+ * This is a derivation layer - it reads existing JSONL and composes a structured
+ * proof object. No new storage format is introduced.
+ *
+ * All 4 proof surfaces (micro-proof, receipt, drilldown, scorecard) derive from this model.
+ */
+
+const { readSessionMetrics } = require("./metrics");
+const { readOutcomeEvents } = require("./unified-events");
+const { countByDimension, countByFamily } = require("./proof-events");
+const { validateProofRecord } = require("./anti-gaming");
+const {
+  buildBoundedStateContext,
+  extractCanonicalProofEntries,
+  latestCanonicalEntriesByFamily,
+  latestTerminalCanonicalSignal,
+  formatNextBoundedAction,
+  normalizeTaskContractSummary,
+} = require("./proof-canonical");
+
+function uniqueStrings(values) {
+  return [...new Set((values || []).map((value) => String(value || "").trim()).filter(Boolean))];
+}
+
+function latestValue(signals, field) {
+  const values = (signals || []).map((signal) => signal?.[field]).filter((value) => value !== undefined && value !== null && value !== "");
+  return values.length > 0 ? values[values.length - 1] : null;
+}
+
+function signalReasonCodes(signal) {
+  return Array.isArray(signal?.reason_codes) ? signal.reason_codes : [];
+}
+
+function buildCanonicalContext(metrics, outcomeEvents, boundedState) {
+  const entries = [...(metrics || []), ...(outcomeEvents || [])];
+  const canonicalEntries = extractCanonicalProofEntries(entries);
+  const latestByFamily = latestCanonicalEntriesByFamily(entries);
+  const taskContractSignal = latestByFamily.get("task_contract")?.signal || null;
+  const safeStopSignal = latestByFamily.get("safe_stop")?.signal || null;
+  const completionSignal = latestByFamily.get("completion_truth")?.signal || null;
+  const terminalSignal = latestTerminalCanonicalSignal(entries);
+  const controlSignals = canonicalEntries
+    .filter((entry) => entry.signal.family === "control_decision")
+    .map((entry) => entry.signal);
+  const materialSignals = canonicalEntries
+    .filter((entry) => entry.signal.family === "material_step")
+    .map((entry) => entry.signal);
+  const embeddedTaskContract = canonicalEntries
+    .map((entry) => normalizeTaskContractSummary(entry.signal.task_contract))
+    .filter(Boolean)
+    .at(-1) || null;
+  const taskContract = normalizeTaskContractSummary(taskContractSignal) || embeddedTaskContract || null;
+
+  return {
+    canonicalEntries,
+    controlSignals,
+    materialSignals,
+    taskContract,
+    safeStopSignal,
+    completionSignal,
+    terminalSignal,
+    boundedState: boundedState || null,
+    evidenceRefs: uniqueStrings([
+      ...(taskContract?.evidence_refs || []),
+      ...(safeStopSignal?.evidence_refs || []),
+      ...(completionSignal?.evidence_refs || []),
+      ...(boundedState?.evidence_refs || []),
+      ...materialSignals.flatMap((signal) => signal.evidence_refs || []),
+      ...controlSignals.flatMap((signal) => signal.evidence_refs || []),
+    ]),
+    artifactRefs: uniqueStrings([
+      ...(boundedState?.artifact_refs || []),
+      safeStopSignal?.progress_ref,
+      completionSignal?.artifact_ref,
+      completionSignal?.output_artifact_reference,
+      ...materialSignals.map((signal) => signal.artifact_ref || signal.output_artifact_reference),
+      boundedState?.artifact_path,
+    ]),
+  };
+}
+
+function fallbackCompletionStatus(metrics, allCodes) {
+  const hasTaskCompleted = allCodes.includes("TASK_COMPLETED");
+  const hasStopSnapshot = allCodes.includes("STOP_SNAPSHOT");
+  const hasFailRetry = allCodes.includes("FAIL_RETRY_GUARD");
+
+  if (hasTaskCompleted) return "completed";
+  if (hasStopSnapshot) return "safe_stop";
+  if (hasFailRetry) return "partial";
+  if ((metrics || []).length > 0) return "ended_without_completion";
+  return "unknown";
+}
+
+function fallbackOutcomeType(allCodes) {
+  if (allCodes.includes("TASK_COMPLETED")) return "useful_result";
+  if (allCodes.includes("STOP_SNAPSHOT")) return "safe_stop_with_next_action";
+  if (allCodes.includes("FAIL_RETRY_GUARD")) return "partial_with_recovery";
+  return "indeterminate";
+}
+
+/**
+ * Build a ProofRecordV1 for a given session.
+ *
+ * @param {string} cwd - workspace root
+ * @param {string} sessionId - session identifier
+ * @returns {object} ProofRecordV1
+ */
+function buildProofRecord(cwd, sessionId) {
+  const metrics = readSessionMetrics(cwd, sessionId);
+  const outcomeEvents = readOutcomeEvents(cwd).filter((e) => e.session_id === sessionId);
+
+  return composeProofRecord(sessionId, metrics, outcomeEvents, {
+    boundedState: buildBoundedStateContext(cwd),
+  });
+}
+
+/**
+ * Compose a proof record from pre-loaded data (useful for testing).
+ */
+function composeProofRecord(sessionId, metrics, outcomeEvents, options = {}) {
+  const allCodes = metrics.flatMap((m) => m.reasonCodes || []);
+  const timestamps = metrics.map((m) => Date.parse(m.ts || 0)).filter((t) => Number.isFinite(t));
+  const startedAt = timestamps.length ? new Date(Math.min(...timestamps)).toISOString() : null;
+  const endedAt = timestamps.length ? new Date(Math.max(...timestamps)).toISOString() : null;
+
+  const dimensionCounts = countByDimension(metrics);
+  const familyCounts = countByFamily(metrics);
+  const canonical = buildCanonicalContext(metrics, outcomeEvents, options.boundedState || null);
+
+  const core = buildCoreIdentity(sessionId, metrics, allCodes, startedAt, endedAt, canonical);
+  const outcome = buildOutcomeProof(metrics, allCodes, outcomeEvents, canonical, core);
+  const efficiency = buildEfficiencyProof(metrics, allCodes, canonical);
+  const trust = buildTrustProof(metrics, allCodes, canonical, core, outcome);
+  const control = buildControlProof(metrics, allCodes, canonical);
+  const ux = buildUxExposure(metrics, allCodes);
+  const repoTruth = buildRepoTruth(canonical, core, outcome);
+
+  const record = {
+    version: 1,
+    ...core,
+    outcome,
+    efficiency,
+    trust,
+    control,
+    ux,
+    task_contract: canonical.taskContract,
+    repo_truth: repoTruth,
+    dimension_counts: dimensionCounts,
+    family_counts: familyCounts,
+  };
+
+  const validation = validateProofRecord(record);
+  record.anti_gaming = validation;
+
+  return record;
+}
+
+function buildCoreIdentity(sessionId, metrics, allCodes, startedAt, endedAt, canonical) {
+  const terminal = canonical.completionSignal || canonical.safeStopSignal || canonical.terminalSignal;
+  const completionStatus =
+    canonical.completionSignal?.completion_status ||
+    (canonical.safeStopSignal ? "safe_stop" : null) ||
+    fallbackCompletionStatus(metrics, allCodes);
+
+  const finalOutcomeType =
+    canonical.completionSignal?.final_outcome_type ||
+    (canonical.safeStopSignal ? "safe_stop_with_next_action" : null) ||
+    fallbackOutcomeType(allCodes);
+
+  const reentryStatus =
+    terminal?.reentry_status ||
+    canonical.boundedState?.reentry_status ||
+    (completionStatus === "safe_stop" ? "reentry_available" : "not_applicable");
+
+  return {
+    run_id: sessionId,
+    session_id: sessionId,
+    workspace_id: null,
+    task_type: inferTaskType(metrics),
+    user_id: metrics[0]?.meta?.userId || "local-user",
+    started_at: startedAt,
+    ended_at: endedAt,
+    completion_status: completionStatus,
+    final_outcome_type: finalOutcomeType,
+    bounded_or_unbounded: "bounded",
+    reentry_status: reentryStatus,
+  };
+}
+
+function buildOutcomeProof(metrics, allCodes, outcomeEvents, canonical, core) {
+  const hasTaskCompleted = allCodes.includes("TASK_COMPLETED");
+  const hasStopSnapshot = allCodes.includes("STOP_SNAPSHOT");
+  const hasReport = allCodes.includes("REPORT_WRITTEN");
+  const completionSignal = canonical.completionSignal;
+  const safeStopSignal = canonical.safeStopSignal;
+  const boundedState = canonical.boundedState;
+
+  let usefulResultState = "unknown";
+  if (completionSignal?.useful_result_state) usefulResultState = completionSignal.useful_result_state;
+  else if (boundedState?.artifact_truth_status === "meaningful") usefulResultState = "useful";
+  else if (boundedState?.artifact_truth_status === "weak_but_structurally_valid") usefulResultState = "bounded_useful";
+  else if (hasTaskCompleted) usefulResultState = "useful";
+  else if (core.completion_status === "safe_stop") usefulResultState = "bounded_useful";
+  else usefulResultState = "not_determined";
+
+  let completionQualityState = "unknown";
+  if (completionSignal?.completion_quality_state) completionQualityState = completionSignal.completion_quality_state;
+  else if (boundedState?.readiness_status === "pass") completionQualityState = "high";
+  else if (boundedState?.readiness_status === "internal_only") completionQualityState = "bounded";
+  else if (hasTaskCompleted && hasReport) completionQualityState = "high";
+  else if (hasTaskCompleted) completionQualityState = "medium";
+  else if (core.completion_status === "safe_stop") completionQualityState = "bounded";
+  else completionQualityState = "low";
+
+  const nextBoundedAction =
+    formatNextBoundedAction(completionSignal?.next_bounded_action) ||
+    formatNextBoundedAction(safeStopSignal?.next_bounded_action) ||
+    formatNextBoundedAction(boundedState?.next_bounded_action) ||
+    (core.completion_status === "safe_stop" ? "review_snapshot_and_resume" : null);
+
+  const artifactRef =
+    completionSignal?.output_artifact_reference ||
+    completionSignal?.artifact_ref ||
+    canonical.artifactRefs[0] ||
+    null;
+
+  const artifactType =
+    completionSignal?.output_artifact_type ||
+    (hasReport ? "session_report" : artifactRef ? "runtime_artifact" : null);
+
+  const evidenceBackedCompletion =
+    typeof completionSignal?.evidence_backed_completion === "boolean"
+      ? completionSignal.evidence_backed_completion
+      : (core.completion_status === "completed" || core.completion_status === "safe_stop") &&
+        canonical.evidenceRefs.length > 0;
+
+  return {
+    output_artifact_type: artifactType,
+    output_artifact_reference: artifactRef,
+    useful_result_state: usefulResultState,
+    completion_quality_state: completionQualityState,
+    evidence_backed_completion: evidenceBackedCompletion,
+    evidence_status: canonical.evidenceRefs.length > 0 ? "related_evidence_present" : "no_evidence",
+    partial_completion_reason:
+      completionSignal?.partial_completion_reason ||
+      (!hasTaskCompleted && core.completion_status === "safe_stop" ? "safe_stop_reached" : null),
+    safe_stop_reason:
+      safeStopSignal?.safe_stop_reason ||
+      (core.completion_status === "safe_stop" || hasStopSnapshot ? "bounded_execution_limit" : null),
+    next_bounded_action: nextBoundedAction,
+    unresolved_items:
+      Array.isArray(completionSignal?.unresolved_items) && completionSignal.unresolved_items.length > 0
+        ? completionSignal.unresolved_items
+        : [],
+    evidence_refs: canonical.evidenceRefs,
+    claim_boundary: completionSignal?.claim_boundary || boundedState?.claim_boundary || null,
+    where_am_i_now: completionSignal?.where_am_i_now || boundedState?.where_am_i_now || null,
+    readiness_status: boundedState?.readiness_status || null,
+    exposure_scope: boundedState?.exposure_scope || null,
+    artifact_truth_status: boundedState?.artifact_truth_status || null,
+    counts_as_meaningful_output:
+      typeof boundedState?.counts_as_meaningful_output === "boolean"
+        ? boundedState.counts_as_meaningful_output
+        : null,
+    progress_ref: safeStopSignal?.progress_ref || boundedState?.artifact_path || null,
+  };
+}
+
+function buildEfficiencyProof(metrics, allCodes, canonical) {
+  const largeOutputMetrics = metrics.filter((m) => (m.reasonCodes || []).includes("CTX_LARGE_OUTPUT"));
+  const canonicalLargeOutputs = canonical.materialSignals.filter(
+    (signal) => signal.step_type === "large_output_managed"
+  );
+  const largeOutputBytes = largeOutputMetrics.reduce((sum, m) => {
+    const bytes = Number(m.meta?.bytes || 0);
+    return sum + (Number.isFinite(bytes) ? bytes : 0);
+  }, 0) || canonicalLargeOutputs.reduce((sum, signal) => sum + Number(signal.bytes || 0), 0);
+
+  const largeOutputEvents = largeOutputMetrics.length || canonicalLargeOutputs.length;
+  const scanSkips =
+    allCodes.filter((code) => code === "CTX_SCAN_SKIPPED_UNCHANGED").length ||
+    canonical.materialSignals.filter((signal) => signal.step_type === "scan_skipped").length;
+  const loopInterrupts = allCodes.filter((code) => code === "LOOP_REPEATED_TOOL").length;
+  const failRetries =
+    allCodes.filter((code) => code === "FAIL_RETRY_GUARD").length ||
+    canonical.materialSignals.filter((signal) => signal.step_type === "retry_guard").length;
+  const permFatigueConsolidated = allCodes.filter((code) => code === "PERM_FATIGUE_CONSOLIDATED").length;
+  const toolCalls = metrics.filter((m) => m.event === "PreToolUse").length;
+
+  const timeSavedMinutes = loopInterrupts * 3 + largeOutputEvents;
+  const timeSavedConfidence = loopInterrupts + largeOutputEvents >= 3 ? "medium" : "low";
+
+  return {
+    large_output_bytes_managed: largeOutputBytes || 0,
+    large_output_events: largeOutputEvents,
+    tools_considered: toolCalls,
+    tools_loaded: toolCalls,
+    tools_skipped: scanSkips,
+    retries_count: failRetries + loopInterrupts,
+    dead_end_count: 0,
+    recovery_count: failRetries,
+    approval_interruptions_avoided: permFatigueConsolidated,
+    time_saved_estimate:
+      timeSavedMinutes > 0
+        ? { minutes: timeSavedMinutes, confidence: timeSavedConfidence, basis: "heuristic" }
+        : null,
+  };
+}
+
+function buildTrustProof(metrics, allCodes, canonical, core, outcome) {
+  const securityEvidence = canonical.evidenceRefs.filter((ref) => ref.includes("/security/") || ref.includes("\\security\\"));
+  const evidenceBundleReference =
+    securityEvidence[0] ||
+    (canonical.evidenceRefs.length > 0 ? canonical.evidenceRefs[0] : null) ||
+    (allCodes.some((code) => code === "SEC_TRUST_AUDIT" || code === "SEC_REMEDIATION_JOB_CREATED")
+      ? ".claude/cco/security/"
+      : null);
+  const safeStopSignal = canonical.safeStopSignal;
+  const boundedState = canonical.boundedState;
+  const trustUnknownHigh = allCodes.filter((code) => code === "SEC_TRUST_UNKNOWN_HIGH").length;
+
+  return {
+    evidence_bundle_reference: evidenceBundleReference,
+    has_related_evidence: canonical.evidenceRefs.length > 0,
+    has_suppression_audit:
+      allCodes.includes("SEC_SUPPRESSION_AUDIT") ||
+      canonical.materialSignals.some((signal) => signal.step_type === "suppression_audit"),
+    unverified_claim_count: trustUnknownHigh,
+    uncertainty_annotations_count: trustUnknownHigh,
+    traceability_status: metrics.length > 0 ? "traceable" : "no_data",
+    rollback_available:
+      safeStopSignal?.rollback_available ??
+      boundedState?.rollback_available ??
+      (core.completion_status === "safe_stop"),
+    rollback_trigger: boundedState?.rollback_trigger || null,
+    readiness_status: boundedState?.readiness_status || null,
+    artifact_truth_status: boundedState?.artifact_truth_status || null,
+    progress_preserved:
+      safeStopSignal?.progress_preserved ??
+      (core.completion_status === "safe_stop" && Boolean(outcome.progress_ref)),
+    reentry_anchor_saved:
+      safeStopSignal?.reentry_anchor_saved ??
+      (core.completion_status === "safe_stop" && Boolean(outcome.progress_ref)),
+  };
+}
+
+function buildRepoTruth(canonical, core, outcome) {
+  const boundedState = canonical.boundedState || null;
+  if (!boundedState && !outcome?.claim_boundary && !outcome?.where_am_i_now) return null;
+
+  return {
+    where_am_i_now: outcome?.where_am_i_now || boundedState?.where_am_i_now || null,
+    what_can_i_honestly_claim: outcome?.claim_boundary || boundedState?.claim_boundary || null,
+    readiness_status: outcome?.readiness_status || boundedState?.readiness_status || null,
+    exposure_scope: outcome?.exposure_scope || boundedState?.exposure_scope || null,
+    artifact_truth_status: outcome?.artifact_truth_status || boundedState?.artifact_truth_status || null,
+    counts_as_meaningful_output:
+      typeof outcome?.counts_as_meaningful_output === "boolean"
+        ? outcome.counts_as_meaningful_output
+        : typeof boundedState?.counts_as_meaningful_output === "boolean"
+          ? boundedState.counts_as_meaningful_output
+          : null,
+    reentry_status: core?.reentry_status || boundedState?.reentry_status || null,
+    rollback_available: Boolean(boundedState?.rollback_available),
+    rollback_trigger: boundedState?.rollback_trigger || null,
+    next_bounded_action: outcome?.next_bounded_action || formatNextBoundedAction(boundedState?.next_bounded_action),
+    reason_summary: boundedState?.reentry_reason_summary || null,
+    evidence_refs: boundedState?.evidence_refs || [],
+    artifact_refs: boundedState?.artifact_refs || [],
+  };
+}
+
+function mapScopeStatus(scopeStatus, riskyBlocked, policyHits) {
+  if (scopeStatus === "no_violations_detected" || scopeStatus === "violations_handled") {
+    return scopeStatus;
+  }
+  if (scopeStatus === "within_policy") return "no_violations_detected";
+  if (scopeStatus === "unknown" || !scopeStatus) {
+    return riskyBlocked === 0 && policyHits === 0 ? "no_violations_detected" : "violations_handled";
+  }
+  return riskyBlocked === 0 && policyHits === 0 ? "no_violations_detected" : "violations_handled";
+}
+
+function buildControlProof(metrics, allCodes, canonical) {
+  const secMetrics = metrics.filter((m) =>
+    (m.reasonCodes || []).some((code) => String(code).startsWith("SEC_"))
+  );
+  const canonicalRiskSignals = canonical.controlSignals.filter(
+    (signal) =>
+      signal.decision === "deny" ||
+      signal.decision === "ask" ||
+      signal.approval_required === true ||
+      signalReasonCodes(signal).some((code) => String(code).startsWith("SEC_")) ||
+      signal.source === "policy"
+  );
+
+  const riskyAttempts = Math.max(secMetrics.length, canonicalRiskSignals.length);
+  const riskyBlocked = Math.max(
+    secMetrics.filter((m) => m.action === "deny").length,
+    canonicalRiskSignals.filter((signal) => signal.decision === "deny").length
+  );
+  const riskyDowngraded = Math.max(
+    secMetrics.filter((m) => m.action === "ask").length,
+    canonicalRiskSignals.filter((signal) => signal.decision === "ask").length
+  );
+
+  const approvalTriggered = Math.max(
+    metrics.filter((m) => m.event === "PermissionRequest").length,
+    canonical.controlSignals.filter((signal) => signal.approval_required === true).length
+  );
+  const approvalAvoided = allCodes.filter((code) => code === "PERM_FATIGUE_CONSOLIDATED").length;
+  const policyHits = Math.max(
+    allCodes.filter((code) => code === "TEAM_BLOCK_PATTERN").length,
+    canonical.controlSignals.filter((signal) => signal.policy_boundary && signal.decision !== "allow").length
+  );
+  const latestScopeStatus = latestValue(canonical.controlSignals, "scope_status");
+  const safeStopCount = canonical.safeStopSignal ? 1 : allCodes.filter((code) => code === "STOP_SNAPSHOT").length;
+
+  return {
+    risky_action_attempts: riskyAttempts,
+    risky_actions_blocked: riskyBlocked,
+    risky_actions_downgraded: riskyDowngraded,
+    approval_requests_triggered: approvalTriggered,
+    approval_requests_avoided: approvalAvoided,
+    policy_boundary_hits: policyHits,
+    trusted_scope_preserved: mapScopeStatus(latestScopeStatus, riskyBlocked, policyHits),
+    safe_stop_count: safeStopCount,
+  };
+}
+
+function buildUxExposure(metrics, allCodes) {
+  const microProofCount = allCodes.filter((code) => code === "PROOF_MICRO_RENDERED").length;
+  const receiptGenerated = allCodes.includes("PROOF_RECEIPT_GENERATED");
+  const receiptOpened = allCodes.includes("PROOF_RECEIPT_OPENED");
+  const drilldownOpened = allCodes.includes("PROOF_DRILLDOWN_OPENED");
+
+  return {
+    micro_proof_rendered_count: microProofCount,
+    receipt_generated: receiptGenerated,
+    receipt_opened: receiptOpened,
+    drilldown_opened: drilldownOpened,
+  };
+}
+
+function inferTaskType(metrics) {
+  const tools = metrics.map((m) => m.tool).filter(Boolean);
+  if (tools.includes("Write") || tools.includes("Edit")) return "coding";
+  if (tools.includes("Bash")) return "command";
+  if (tools.includes("Read") || tools.includes("Grep") || tools.includes("Glob")) return "exploration";
+  return "general";
+}
+
+module.exports = {
+  buildProofRecord,
+  composeProofRecord,
+};