avorelo 0.1.0

package/scripts/lib/seamless-outcome.js

@@ -0,0 +1,689 @@
+"use strict";
+
+// ── Seamless Customer Outcome Contract ────────────────────────────────────────
+//
+// Internal operating contract that makes Avorelo's foundations work together
+// as a seamless customer outcome layer.
+//
+// Contract: avorelo.seamlessOutcome.v1
+//
+// Non-goals: new dashboard, new orchestrator, pricing decisions, public
+//            positioning, exact billing savings, LLM calls, network calls.
+//
+// The seamless outcome contract has three modes:
+//   automatic      — work silently when safe; interrupt only when required
+//   assisted       — recommend silently, require approval for impactful decisions
+//   manual_debug   — expose full detail for debugging and auditing
+
+const fs = require("fs");
+const path = require("path");
+const { appendProductLearningEvent } = require("./product-learning-events");
+
+const CONTRACT = "avorelo.seamlessOutcome.v1";
+const SCHEMA_VERSION = 1;
+
+const SEAMLESS_OUTCOME_DIR_REL = ".claude/cco/orchestration/seamless-outcome";
+const LATEST_OUTCOME_RECEIPT_REL = ".claude/cco/orchestration/seamless-outcome/latest-outcome.json";
+const LATEST_VALUE_SUMMARY_REL = ".claude/cco/orchestration/seamless-outcome/latest-value-summary.json";
+
+const MODES = Object.freeze(["automatic", "assisted", "manual_debug"]);
+
+// Actions that always require interruption regardless of mode
+const ALWAYS_INTERRUPT_ACTION_TYPES = new Set([
+  "deploy_publish",
+  "auth_billing_ci_prod_change",
+]);
+
+// Actions that require interruption in assisted mode
+const ASSISTED_INTERRUPT_ACTION_TYPES = new Set([
+  "file_write",
+  "command_run",
+  "network_request",
+  "browser_action",
+]);
+
+// Risk levels that require interruption in assisted mode
+const ASSISTED_INTERRUPT_RISK_LEVELS = new Set(["high", "critical"]);
+
+// Risk levels that can be silently reduced in automatic mode
+const AUTO_REDUCIBLE_RISK_LEVELS = new Set(["low", "medium"]);
+
+// ── Mode resolution ───────────────────────────────────────────────────────────
+
+function getSeamlessMode(configOrOptions = {}) {
+  const raw = String(
+    configOrOptions.seamlessMode ||
+    configOrOptions.mode ||
+    process.env.AVORELO_SEAMLESS_MODE ||
+    "automatic"
+  ).toLowerCase().trim();
+
+  if (MODES.includes(raw)) return raw;
+  return "automatic";
+}
+
+// ── Interrupt decision ────────────────────────────────────────────────────────
+
+function shouldInterruptForDecision(input = {}) {
+  const mode = getSeamlessMode(input);
+  const actionType = String(input.actionType || "").toLowerCase().trim();
+  const riskLevel = String(input.riskLevel || "").toLowerCase().trim();
+  const isDestructive = Boolean(input.isDestructive);
+  const isIrreversible = Boolean(input.isIrreversible);
+  const hasSecretsRisk = Boolean(input.hasSecretsRisk);
+  const requiresExplicitApproval = Boolean(input.requiresExplicitApproval);
+
+  // Always interrupt for these categories regardless of mode
+  if (ALWAYS_INTERRUPT_ACTION_TYPES.has(actionType)) {
+    return { interrupt: true, reason: "action_type_always_requires_approval", mode };
+  }
+  if (isDestructive && isIrreversible) {
+    return { interrupt: true, reason: "destructive_irreversible_action", mode };
+  }
+  if (hasSecretsRisk) {
+    return { interrupt: true, reason: "secrets_exposure_risk", mode };
+  }
+  if (requiresExplicitApproval) {
+    return { interrupt: true, reason: "explicit_policy_requires_approval", mode };
+  }
+
+  // Assisted mode interrupts for higher-risk actions
+  if (mode === "assisted") {
+    if (ASSISTED_INTERRUPT_ACTION_TYPES.has(actionType) && ASSISTED_INTERRUPT_RISK_LEVELS.has(riskLevel)) {
+      return { interrupt: true, reason: "assisted_mode_high_risk_action", mode };
+    }
+  }
+
+  // Manual debug mode always exposes, but doesn't necessarily interrupt
+  // (it's about visibility, not blocking)
+
+  return { interrupt: false, reason: "safe_to_apply_silently", mode };
+}
+
+// ── Silent application decision ───────────────────────────────────────────────
+
+function shouldApplySilently(input = {}) {
+  const mode = getSeamlessMode(input);
+  const interruptDecision = shouldInterruptForDecision(input);
+
+  if (interruptDecision.interrupt) {
+    return { silent: false, reason: interruptDecision.reason, mode };
+  }
+
+  if (mode === "manual_debug") {
+    return { silent: false, reason: "manual_debug_exposes_all_decisions", mode };
+  }
+
+  const riskLevel = String(input.riskLevel || "low").toLowerCase().trim();
+  if (!AUTO_REDUCIBLE_RISK_LEVELS.has(riskLevel) && mode === "automatic") {
+    return { silent: false, reason: "risk_level_requires_awareness_in_automatic_mode", mode };
+  }
+
+  return { silent: true, reason: "safe_routine_optimization", mode };
+}
+
+// ── Outcome-preserving safety check ──────────────────────────────────────────
+
+function buildOutcomePreservationCheck(input = {}) {
+  const {
+    originalAction,
+    reductionApplied,
+    riskLevel,
+    actionType,
+    target,
+    taskDescription,
+    taskStillExecutable,
+    qualityRiskIntroduced,
+    fallbackAvailable,
+    escalationRecommended,
+    safeNextAction,
+    interruptRequired,
+    reasonCodes,
+    continuationType,
+    suggestedScope,
+    suggestedCommand,
+    verificationNextStep,
+  } = input;
+
+  const mode = getSeamlessMode(input);
+  const interruptDecision = shouldInterruptForDecision({
+    ...input,
+    actionType: actionType || "unknown",
+    riskLevel: riskLevel || "low",
+  });
+
+  // If reduction may prevent completion, escalate unless fallback exists
+  const needsEscalation =
+    escalationRecommended === true ||
+    (taskStillExecutable === false && fallbackAvailable !== true);
+
+  const effectiveInterruptRequired =
+    interruptRequired === true ||
+    interruptDecision.interrupt ||
+    (needsEscalation && !fallbackAvailable);
+
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    originalAction: originalAction || null,
+    reductionApplied: reductionApplied !== undefined ? Boolean(reductionApplied) : null,
+    riskReduced: riskLevel
+      ? ["medium", "high", "critical"].includes(String(riskLevel).toLowerCase()) && Boolean(reductionApplied)
+      : null,
+    taskStillExecutable: taskStillExecutable !== undefined ? taskStillExecutable : "unknown",
+    qualityRiskIntroduced: qualityRiskIntroduced !== undefined ? qualityRiskIntroduced : "unknown",
+    fallbackAvailable: fallbackAvailable !== undefined ? Boolean(fallbackAvailable) : false,
+    escalationRecommended: needsEscalation,
+    safeNextAction: safeNextAction || null,
+    interruptRequired: effectiveInterruptRequired,
+    reasonCodes: Array.isArray(reasonCodes) ? reasonCodes : [],
+    mode,
+    target: target || null,
+    taskDescription: taskDescription ? String(taskDescription).slice(0, 200) : null,
+    continuationType: continuationType || null,
+    suggestedScope: suggestedScope || null,
+    suggestedCommand: suggestedCommand || null,
+    verificationNextStep: verificationNextStep || null,
+  };
+}
+
+// ── End-of-run value summary ──────────────────────────────────────────────────
+
+function buildEndOfRunValueSummary(input = {}) {
+  const {
+    mode,
+    completedItems,
+    preparedItems,
+    nextAction,
+    completionStatus,
+    estimatedPremiumCallsAvoided,
+    localStagesUsed,
+    estimatedContextTokensAvoided,
+    broadScansAvoided,
+    manualDecisionsAvoided,
+    repeatedWorkAvoided,
+    safePathReductionsApplied,
+    unsafeActionsBlocked,
+    unknownToolsIsolated,
+    secretsExposurePrevented,
+    approvalsRequiredOnlyWhenNecessary,
+    testsRun,
+    proofArtifacts,
+    receiptsWritten,
+    validationStatus,
+    qualityPreserved,
+    qualityRiskIntroduced,
+    escalationRecommended,
+    strongWorkerReservedForCriticalStage,
+    latestProofPath,
+    latestReceiptPaths,
+    eventCounts,
+  } = input;
+
+  const resolvedMode = getSeamlessMode({ mode });
+
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    mode: resolvedMode,
+    completed: {
+      status: completionStatus || "unknown",
+      completedItems: Number(completedItems || 0),
+      preparedItems: Number(preparedItems || 0),
+      nextAction: nextAction || null,
+    },
+    saved: {
+      estimatedPremiumCallsAvoided: Number(estimatedPremiumCallsAvoided || 0),
+      localStagesUsed: Number(localStagesUsed || 0),
+      estimatedContextTokensAvoided: Number(estimatedContextTokensAvoided || 0),
+      broadScansAvoided: Number(broadScansAvoided || 0),
+      manualDecisionsAvoided: Number(manualDecisionsAvoided || 0),
+      repeatedWorkAvoided: Number(repeatedWorkAvoided || 0),
+    },
+    protected: {
+      safePathReductionsApplied: Number(safePathReductionsApplied || 0),
+      unsafeActionsBlocked: Number(unsafeActionsBlocked || 0),
+      unknownToolsIsolated: Number(unknownToolsIsolated || 0),
+      secretsExposurePrevented: Number(secretsExposurePrevented || 0),
+      approvalsRequiredOnlyWhenNecessary: approvalsRequiredOnlyWhenNecessary !== false,
+    },
+    verified: {
+      testsRun: Number(testsRun || 0),
+      proofArtifacts: Number(proofArtifacts || 0),
+      receiptsWritten: Number(receiptsWritten || 0),
+      validationStatus: validationStatus || "unknown",
+    },
+    quality: {
+      qualityPreserved: qualityPreserved !== false,
+      qualityRiskIntroduced: Boolean(qualityRiskIntroduced),
+      escalationRecommended: Boolean(escalationRecommended),
+      strongWorkerReservedForCriticalStage: Boolean(strongWorkerReservedForCriticalStage),
+    },
+    evidence: {
+      latestProofPath: latestProofPath || null,
+      latestReceiptPaths: Array.isArray(latestReceiptPaths) ? latestReceiptPaths.slice(0, 5) : [],
+      eventCounts: eventCounts && typeof eventCounts === "object" ? eventCounts : {},
+    },
+    caveats: [
+      "Token/cost savings are estimated, not billing-exact",
+      "Premium call avoidance is based on local worker detection, not account billing",
+    ],
+    redacted: true,
+  };
+}
+
+// ── Seamless outcome surface (for status/dashboard) ──────────────────────────
+
+function buildSeamlessOutcomeSurface(cwd) {
+  const abs = path.join(cwd, LATEST_VALUE_SUMMARY_REL);
+  let latestSummary = null;
+  try {
+    if (fs.existsSync(abs)) {
+      latestSummary = JSON.parse(fs.readFileSync(abs, "utf8").replace(/^/, ""));
+    }
+  } catch {
+    latestSummary = null;
+  }
+
+  const mode = getSeamlessMode({});
+
+  if (!latestSummary) {
+    return {
+      contract: CONTRACT,
+      status: "no_summary_yet",
+      mode,
+      lastSummaryPath: null,
+      taskCompletionStatus: "unknown",
+      estimatedSavingsAvailable: false,
+      riskReductionAvailable: false,
+      interruptionsRequired: 0,
+      nextAction: "Run `avorelo route` + `avorelo outcome --json` to generate a value summary.",
+    };
+  }
+
+  return {
+    contract: CONTRACT,
+    status: "available",
+    mode: latestSummary.mode || mode,
+    lastSummaryPath: LATEST_VALUE_SUMMARY_REL,
+    taskCompletionStatus: latestSummary.completed?.status || "unknown",
+    estimatedSavingsAvailable: (
+      (latestSummary.saved?.estimatedPremiumCallsAvoided || 0) > 0 ||
+      (latestSummary.saved?.estimatedContextTokensAvoided || 0) > 0
+    ),
+    riskReductionAvailable: (
+      (latestSummary.protected?.safePathReductionsApplied || 0) > 0 ||
+      (latestSummary.protected?.unsafeActionsBlocked || 0) > 0
+    ),
+    interruptionsRequired: 0,
+    nextAction: latestSummary.completed?.nextAction || null,
+  };
+}
+
+// ── File I/O ──────────────────────────────────────────────────────────────────
+
+function writeValueSummary(cwd, summary) {
+  const dir = path.join(cwd, SEAMLESS_OUTCOME_DIR_REL);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(
+    path.join(cwd, LATEST_VALUE_SUMMARY_REL),
+    JSON.stringify(summary, null, 2),
+    "utf8"
+  );
+  return LATEST_VALUE_SUMMARY_REL;
+}
+
+function readLatestValueSummary(cwd) {
+  try {
+    const abs = path.join(cwd, LATEST_VALUE_SUMMARY_REL);
+    if (!fs.existsSync(abs)) return null;
+    return JSON.parse(fs.readFileSync(abs, "utf8").replace(/^/, ""));
+  } catch {
+    return null;
+  }
+}
+
+// ── Event emission helpers ────────────────────────────────────────────────────
+
+function emitSeamlessEvent(cwd, eventName, payload = {}) {
+  try {
+    appendProductLearningEvent(cwd, {
+      eventName,
+      category: "seamless_outcome",
+      surface: "local",
+      status: "observed",
+      payload: {
+        contract: CONTRACT,
+        ...payload,
+      },
+    });
+  } catch {
+    // product-learning event emission is best-effort
+  }
+}
+
+function buildAndWriteValueSummary(cwd, input = {}) {
+  const summary = buildEndOfRunValueSummary(input);
+  const path_ = writeValueSummary(cwd, summary);
+
+  emitSeamlessEvent(cwd, "value_summary_generated", {
+    mode: summary.mode,
+    completionStatus: summary.completed.status,
+    estimatedPremiumCallsAvoided: summary.saved.estimatedPremiumCallsAvoided,
+    estimatedContextTokensAvoided: summary.saved.estimatedContextTokensAvoided,
+    unsafeActionsBlocked: summary.protected.unsafeActionsBlocked,
+    qualityPreserved: summary.quality.qualityPreserved,
+  });
+
+  return { summary, path: path_ };
+}
+
+// ── Outcome surface builder for context-optimizer / handoff integration ───────
+
+function buildValueSummaryFromReceipts(cwd, opts = {}) {
+  let contextReceipt = null;
+  let orchReceipt = null;
+  let intakeReceipt = null;
+
+  try {
+    const { readLatestContextOptimizationReceipt } = require("./context-optimizer");
+    contextReceipt = readLatestContextOptimizationReceipt(cwd);
+  } catch {}
+
+  try {
+    const { readLatestOrchestrationReceipt } = require("./orchestration");
+    orchReceipt = readLatestOrchestrationReceipt(cwd);
+  } catch {}
+
+  try {
+    const { LATEST_INSTALL_INTAKE_RECEIPT_REL_PATH } = require("./install-intake-risk");
+    const abs = path.join(cwd, LATEST_INSTALL_INTAKE_RECEIPT_REL_PATH);
+    if (fs.existsSync(abs)) {
+      intakeReceipt = JSON.parse(fs.readFileSync(abs, "utf8").replace(/^/, ""));
+    }
+  } catch {}
+
+  const estimatedContextTokensAvoided =
+    contextReceipt?.savings?.estimatedTokensAvoided || 0;
+  const localStagesUsed =
+    orchReceipt?.localStagesUsed || orchReceipt?.stageList?.filter((s) => s?.quotaSignal === "local").length || 0;
+  const estimatedPremiumCallsAvoided =
+    orchReceipt?.premiumCallsAvoided || (localStagesUsed > 0 ? localStagesUsed : 0);
+  const unknownToolsIsolated =
+    intakeReceipt?.summary?.unknownItems || 0;
+  const highRiskItems =
+    intakeReceipt?.summary?.highRiskItems || 0;
+
+  // Read orchestration proof for proof path
+  let latestProofPath = null;
+  try {
+    const { LATEST_ORCHESTRATION_RECEIPT_REL_PATH } = require("./orchestration");
+    latestProofPath = LATEST_ORCHESTRATION_RECEIPT_REL_PATH;
+  } catch {}
+
+  return buildAndWriteValueSummary(cwd, {
+    mode: opts.mode,
+    completionStatus: orchReceipt?.status || "unknown",
+    completedItems: orchReceipt?.stagesCompleted || 0,
+    preparedItems: orchReceipt?.stageList?.length || 0,
+    nextAction: orchReceipt?.nextAction || opts.nextAction || null,
+    estimatedPremiumCallsAvoided,
+    localStagesUsed,
+    estimatedContextTokensAvoided,
+    broadScansAvoided: contextReceipt?.savings?.broadScansAvoided || 0,
+    manualDecisionsAvoided: opts.manualDecisionsAvoided || 0,
+    repeatedWorkAvoided: contextReceipt?.savings?.repeatedWorkAvoided || 0,
+    safePathReductionsApplied: opts.safePathReductionsApplied || 0,
+    unsafeActionsBlocked: opts.unsafeActionsBlocked || 0,
+    unknownToolsIsolated,
+    secretsExposurePrevented: opts.secretsExposurePrevented || 0,
+    approvalsRequiredOnlyWhenNecessary: true,
+    testsRun: opts.testsRun || 0,
+    proofArtifacts: opts.proofArtifacts || 0,
+    receiptsWritten: opts.receiptsWritten || 0,
+    validationStatus: opts.validationStatus || "unknown",
+    qualityPreserved: opts.qualityPreserved !== false,
+    qualityRiskIntroduced: Boolean(opts.qualityRiskIntroduced),
+    escalationRecommended: Boolean(opts.escalationRecommended),
+    strongWorkerReservedForCriticalStage: Boolean(opts.strongWorkerReservedForCriticalStage),
+    latestProofPath,
+    latestReceiptPaths: [
+      contextReceipt ? ".claude/cco/orchestration/context-optimizer/latest-receipt.json" : null,
+      intakeReceipt ? ".claude/cco/security/install-intake/latest-receipt.json" : null,
+      latestProofPath,
+    ].filter(Boolean),
+    eventCounts: opts.eventCounts || {},
+  });
+}
+
+// ── Value Evidence Collection ─────────────────────────────────────────────────
+//
+// Reads real receipts and returns structured evidence for each value field.
+// Each field carries evidenceBacked + estimateMethod so consumers can check
+// whether a summary entry is supported by observed data or is just a default.
+//
+// Rules:
+// - no network calls, no LLM calls, purely computational
+// - never throws; returns defaults with estimateMethod:"not_available" on error
+// - no optimistic defaults: if a receipt is absent, value stays 0/not_available
+
+function collectValueEvidence(cwd) {
+  let contextReceipt = null;
+  let orchReceipt = null;
+  let intakeReceipt = null;
+  let safePathReceipt = null;
+  let guardReceipt = null;
+  let proofReceipt = null;
+
+  try {
+    const { readLatestContextOptimizationReceipt } = require("./context-optimizer");
+    contextReceipt = readLatestContextOptimizationReceipt(cwd);
+  } catch {}
+
+  try {
+    const { readLatestOrchestrationReceipt } = require("./orchestration");
+    orchReceipt = readLatestOrchestrationReceipt(cwd);
+  } catch {}
+
+  try {
+    const { LATEST_INSTALL_INTAKE_RECEIPT_REL_PATH } = require("./install-intake-risk");
+    const abs = path.join(cwd, LATEST_INSTALL_INTAKE_RECEIPT_REL_PATH);
+    if (fs.existsSync(abs)) {
+      intakeReceipt = JSON.parse(fs.readFileSync(abs, "utf8").replace(/^/, ""));
+    }
+  } catch {}
+
+  try {
+    const abs = path.join(cwd, ".claude", "cco", "security", "safe-path", "latest-receipt.json");
+    if (fs.existsSync(abs)) {
+      safePathReceipt = JSON.parse(fs.readFileSync(abs, "utf8").replace(/^/, ""));
+    }
+  } catch {}
+
+  try {
+    const abs = path.join(cwd, ".claude", "cco", "evidence", "agent-security", "latest-enforcement.json");
+    if (fs.existsSync(abs)) {
+      guardReceipt = JSON.parse(fs.readFileSync(abs, "utf8").replace(/^/, ""));
+    }
+  } catch {}
+
+  try {
+    const abs = path.join(cwd, ".claude", "cco", "orchestration", "current-proof.json");
+    if (fs.existsSync(abs)) {
+      proofReceipt = JSON.parse(fs.readFileSync(abs, "utf8").replace(/^/, ""));
+    }
+  } catch {}
+
+  // ── Build evidence-backed field assessments ──────────────────────────────
+
+  // Premium calls avoided: only count when orchestration receipt shows local stages
+  const localStagesUsed = orchReceipt?.localStagesUsed
+    || (Array.isArray(orchReceipt?.stageList)
+      ? orchReceipt.stageList.filter((s) => s?.quotaSignal === "local").length
+      : 0);
+  const premiumCallsAvoided = localStagesUsed > 0 ? localStagesUsed : 0;
+  const premiumCallsEvidence = {
+    value: premiumCallsAvoided,
+    evidenceBacked: orchReceipt != null && localStagesUsed > 0,
+    estimateMethod: orchReceipt
+      ? (localStagesUsed > 0 ? "receipt" : "not_available")
+      : "not_available",
+    caveat: orchReceipt == null
+      ? "No orchestration receipt found; cannot count premium calls avoided."
+      : localStagesUsed === 0
+        ? "No local stages used in latest orchestration receipt."
+        : null,
+  };
+
+  // Context tokens avoided: only count when context receipt has compaction/exclusions
+  const estimatedTokensAvoided = contextReceipt?.savings?.estimatedTokensAvoided || 0;
+  const hasCompactionEvidence =
+    contextReceipt != null &&
+    (contextReceipt.compactionUsed === true ||
+      (contextReceipt.excludedCount != null && contextReceipt.excludedCount > 0) ||
+      estimatedTokensAvoided > 0);
+  const contextTokensEvidence = {
+    value: hasCompactionEvidence ? estimatedTokensAvoided : 0,
+    evidenceBacked: hasCompactionEvidence,
+    estimateMethod: hasCompactionEvidence ? "receipt" : "not_available",
+    caveat: !contextReceipt
+      ? "No context receipt found; cannot estimate tokens avoided."
+      : !hasCompactionEvidence
+        ? "Context receipt present but no compaction or exclusions detected."
+        : "Token count is estimated from context receipt, not billing-exact.",
+  };
+
+  // Unsafe actions blocked: only count when guard/safe-path shows a block/approval_required
+  const guardDecision = guardReceipt?.decision || "unknown";
+  const safePathDecision = safePathReceipt?.safePathDecision || "unknown";
+  const unsafeActionsBlocked =
+    ["block", "approval_required"].includes(guardDecision) ||
+    ["block", "approval_required"].includes(safePathDecision) ? 1 : 0;
+  const unsafeActionsEvidence = {
+    value: unsafeActionsBlocked,
+    evidenceBacked: guardReceipt != null || safePathReceipt != null,
+    estimateMethod: (guardReceipt || safePathReceipt) ? "receipt" : "not_available",
+    caveat: !guardReceipt && !safePathReceipt
+      ? "No guard or safe-path receipt found; cannot count unsafe actions blocked."
+      : unsafeActionsBlocked === 0
+        ? "Guard/safe-path receipts present but no blocked/approval decisions."
+        : null,
+  };
+
+  // Unknown tools isolated: only count from intake receipt
+  const unknownToolsIsolated = intakeReceipt?.summary?.unknownItems || 0;
+  const unknownToolsEvidence = {
+    value: unknownToolsIsolated,
+    evidenceBacked: intakeReceipt != null,
+    estimateMethod: intakeReceipt ? "receipt" : "not_available",
+    caveat: !intakeReceipt
+      ? "No install intake receipt found; cannot count unknown tools isolated."
+      : unknownToolsIsolated === 0
+        ? "Intake receipt present but no unknown items found."
+        : null,
+  };
+
+  // Verification: only count when proof receipt exists and has completed/verified status
+  const proofStatus = proofReceipt?.status || "unknown";
+  const hasVerificationEvidence =
+    proofReceipt != null && ["completed", "verified", "pass"].includes(proofStatus);
+  const verificationEvidence = {
+    evidenceBacked: hasVerificationEvidence,
+    estimateMethod: proofReceipt ? "receipt" : "not_available",
+    status: proofStatus,
+    caveat: !proofReceipt
+      ? "No proof receipt found; cannot confirm verification."
+      : !hasVerificationEvidence
+        ? `Proof receipt present but status is '${proofStatus}', not completed/verified.`
+        : null,
+  };
+
+  return {
+    premiumCallsAvoided: premiumCallsEvidence,
+    contextTokensAvoided: contextTokensEvidence,
+    unsafeActionsBlocked: unsafeActionsEvidence,
+    unknownToolsIsolated: unknownToolsEvidence,
+    verification: verificationEvidence,
+    sourceReceipts: {
+      orchReceipt: orchReceipt != null,
+      contextReceipt: contextReceipt != null,
+      intakeReceipt: intakeReceipt != null,
+      safePathReceipt: safePathReceipt != null,
+      guardReceipt: guardReceipt != null,
+      proofReceipt: proofReceipt != null,
+    },
+  };
+}
+
+// ── Evidence-backed value summary builder ─────────────────────────────────────
+//
+// Builds a value summary that includes evidence-backing metadata.
+// Fields without receipts show 0 / not_available with a caveat instead of
+// optimistic defaults.
+
+function buildEvidenceBackedValueSummary(cwd, opts = {}) {
+  const evidence = collectValueEvidence(cwd);
+
+  const caveats = [
+    "Token/cost savings are estimated, not billing-exact",
+    "Premium call avoidance is based on local worker detection, not account billing",
+  ];
+
+  if (evidence.premiumCallsAvoided.caveat) caveats.push(evidence.premiumCallsAvoided.caveat);
+  if (evidence.contextTokensAvoided.caveat) caveats.push(evidence.contextTokensAvoided.caveat);
+  if (evidence.unsafeActionsBlocked.caveat) caveats.push(evidence.unsafeActionsBlocked.caveat);
+  if (evidence.unknownToolsIsolated.caveat) caveats.push(evidence.unknownToolsIsolated.caveat);
+
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    evidenceBacked: true,
+    mode: getSeamlessMode({ mode: opts.mode }),
+    saved: {
+      estimatedPremiumCallsAvoided: evidence.premiumCallsAvoided.value,
+      estimatedPremiumCallsAvoided_evidence: evidence.premiumCallsAvoided.evidenceBacked,
+      estimatedPremiumCallsAvoided_method: evidence.premiumCallsAvoided.estimateMethod,
+      estimatedContextTokensAvoided: evidence.contextTokensAvoided.value,
+      estimatedContextTokensAvoided_evidence: evidence.contextTokensAvoided.evidenceBacked,
+      estimatedContextTokensAvoided_method: evidence.contextTokensAvoided.estimateMethod,
+    },
+    protected: {
+      unsafeActionsBlocked: evidence.unsafeActionsBlocked.value,
+      unsafeActionsBlocked_evidence: evidence.unsafeActionsBlocked.evidenceBacked,
+      unsafeActionsBlocked_method: evidence.unsafeActionsBlocked.estimateMethod,
+      unknownToolsIsolated: evidence.unknownToolsIsolated.value,
+      unknownToolsIsolated_evidence: evidence.unknownToolsIsolated.evidenceBacked,
+      unknownToolsIsolated_method: evidence.unknownToolsIsolated.estimateMethod,
+    },
+    verified: {
+      verificationStatus: evidence.verification.status,
+      verificationEvidenceBacked: evidence.verification.evidenceBacked,
+      verificationMethod: evidence.verification.estimateMethod,
+    },
+    sourceReceipts: evidence.sourceReceipts,
+    caveats: [...new Set(caveats.filter(Boolean))],
+    redacted: true,
+  };
+}
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  MODES,
+  SEAMLESS_OUTCOME_DIR_REL,
+  LATEST_OUTCOME_RECEIPT_REL,
+  LATEST_VALUE_SUMMARY_REL,
+  getSeamlessMode,
+  shouldInterruptForDecision,
+  shouldApplySilently,
+  buildOutcomePreservationCheck,
+  buildEndOfRunValueSummary,
+  buildSeamlessOutcomeSurface,
+  writeValueSummary,
+  readLatestValueSummary,
+  buildAndWriteValueSummary,
+  buildValueSummaryFromReceipts,
+  collectValueEvidence,
+  buildEvidenceBackedValueSummary,
+  emitSeamlessEvent,
+};