avorelo 0.1.0

package/scripts/lib/token-cost-intelligence.js

@@ -0,0 +1,358 @@
+"use strict";
+
+// ── Token / Cost Intelligence ─────────────────────────────────────────────────
+//
+// Contract: avorelo.tokenCostIntelligence.v1
+//
+// Rolls up token/context evidence from existing artifacts.
+// Always distinguishes: exact | estimated | not_available | mixed.
+// Never claims dollar savings without exact source.
+// Never claims guaranteed savings.
+
+const fs = require("fs");
+const path = require("path");
+const { nowIso } = require("./fsx");
+const { appendProductLearningEvent } = require("./product-learning-events");
+const {
+  readImportedTokenCostEvidence,
+  readCapturedTokenCostEvidence,
+  buildTokenCostEvidenceSummary,
+  writeTokenCostEvidenceSummary,
+} = require("./prelaunch-evidence-store");
+
+const CONTRACT = "avorelo.tokenCostIntelligence.v1";
+const SCHEMA_VERSION = 1;
+const INTELLIGENCE_DIR_REL = ".claude/cco/orchestration/prelaunch-intelligence";
+const ARTIFACT_REL = `${INTELLIGENCE_DIR_REL}/latest-token-cost-intelligence.json`;
+
+const TOKEN_EVIDENCE_REL = ".claude/cco/orchestration/token-efficiency/latest-evidence.json";
+const QUALITY_GATE_REL = ".claude/cco/orchestration/token-efficiency/latest-quality-gate.json";
+const CACHE_READINESS_REL = ".claude/cco/orchestration/cache-readiness/latest-readiness.json";
+
+function safeReadJson(absPath) {
+  try {
+    if (!fs.existsSync(absPath)) return null;
+    return JSON.parse(fs.readFileSync(absPath, "utf8").replace(/^/, ""));
+  } catch {
+    return null;
+  }
+}
+
+function classifyEvidenceLevel(evidence, options = {}) {
+  if (!evidence) return "not_available";
+
+  const levels = [];
+
+  // Check token efficiency evidence
+  if (evidence.tokenEvidence) {
+    const te = evidence.tokenEvidence;
+    if (te.evidenceLevel === "exact") levels.push("exact");
+    else if (te.evidenceLevel === "estimated") levels.push("estimated");
+    else levels.push("not_available");
+  }
+
+  // Check cache readiness
+  if (evidence.cacheReadiness && evidence.cacheReadiness.status) {
+    if (evidence.cacheReadiness.status === "ready") levels.push("estimated");
+    else levels.push("not_available");
+  }
+
+  if (evidence.tokenCostEvidenceSummary) {
+    if (evidence.tokenCostEvidenceSummary.evidenceMode === "measured") levels.push("exact");
+    else if (evidence.tokenCostEvidenceSummary.evidenceMode === "estimated") levels.push("estimated");
+    else if (evidence.tokenCostEvidenceSummary.evidenceMode === "heuristic") levels.push("estimated");
+  } else if (Array.isArray(evidence.importedUsage) && evidence.importedUsage.length > 0) {
+    const hasExact = evidence.importedUsage.some((item) =>
+      item &&
+      item.evidenceMode === "measured" &&
+      typeof item.totalTokens === "number" &&
+      (typeof item.measuredCostUsd === "number" || typeof item.costMicros === "number")
+    );
+    const hasEstimated = evidence.importedUsage.some((item) =>
+      item &&
+      typeof item.totalTokens === "number" &&
+      (typeof item.estimatedCostUsd === "number" || typeof item.measuredCostUsd === "number" || typeof item.costMicros === "number")
+    );
+    if (hasExact) levels.push("exact");
+    else if (hasEstimated) levels.push("estimated");
+  }
+
+  if (levels.length === 0) return "not_available";
+  if (levels.every((l) => l === "exact")) return "exact";
+  if (levels.every((l) => l === "not_available")) return "not_available";
+  if (levels.some((l) => l === "exact") && levels.some((l) => l !== "exact")) return "mixed";
+  if (levels.some((l) => l === "estimated")) return "estimated";
+  return "not_available";
+}
+
+function collectTokenCostEvidence(cwd, options = {}) {
+  const tokenEvidencePath = path.join(cwd, TOKEN_EVIDENCE_REL);
+  const qualityGatePath = path.join(cwd, QUALITY_GATE_REL);
+  const cacheReadinessPath = path.join(cwd, CACHE_READINESS_REL);
+
+  const tokenEvidence = safeReadJson(tokenEvidencePath);
+  const qualityGate = safeReadJson(qualityGatePath);
+  const cacheReadiness = safeReadJson(cacheReadinessPath);
+
+  const tokenCostEvidenceSummary = buildTokenCostEvidenceSummary(cwd);
+  writeTokenCostEvidenceSummary(cwd, tokenCostEvidenceSummary);
+
+  return {
+    tokenEvidence,
+    qualityGate,
+    cacheReadiness,
+    importedUsage: readImportedTokenCostEvidence(cwd),
+    capturedUsage: readCapturedTokenCostEvidence(cwd),
+    tokenCostEvidenceSummary,
+    refs: {
+      tokenEvidence: tokenEvidence ? TOKEN_EVIDENCE_REL : null,
+      qualityGate: qualityGate ? QUALITY_GATE_REL : null,
+      cacheReadiness: cacheReadiness ? CACHE_READINESS_REL : null,
+      importedUsage: fs.existsSync(path.join(cwd, ".claude/cco/evidence/token-cost/token-cost.jsonl"))
+        ? ".claude/cco/evidence/token-cost/token-cost.jsonl"
+        : null,
+      capturedUsage: fs.existsSync(path.join(cwd, ".claude/cco/evidence/token-cost/capture.jsonl"))
+        ? ".claude/cco/evidence/token-cost/capture.jsonl"
+        : null,
+    },
+  };
+}
+
+function buildTokenCostRollup(cwd, options = {}) {
+  const evidence = collectTokenCostEvidence(cwd, options);
+  const { tokenEvidence, qualityGate, cacheReadiness, importedUsage, capturedUsage, tokenCostEvidenceSummary } = evidence;
+  const usageRows = [...(capturedUsage || []), ...(importedUsage || [])];
+
+  const evidenceLevel = classifyEvidenceLevel(evidence, options);
+  const evidenceMode = tokenCostEvidenceSummary?.evidenceMode || "missing";
+
+  // Gather available refs
+  const tokenEvidenceRefs = Object.entries(evidence.refs)
+    .filter(([, v]) => v !== null)
+    .map(([k, v]) => ({ label: k, path: v }));
+
+  // Context avoided
+  const contextAvoidedEstimate = tokenEvidence?.contextAvoidedEstimate ?? null;
+  const outputAvoidedEstimate = tokenEvidence?.outputAvoidedEstimate ?? null;
+  const realUsageSamples = usageRows.filter((item) =>
+    item &&
+    item.redacted === true &&
+    typeof item.totalTokens === "number" &&
+    ((typeof item.measuredCostUsd === "number" || typeof item.costMicros === "number") && item.estimatedOnly !== true)
+  );
+  const tokenFieldSamples = usageRows.filter((item) => item && typeof item.totalTokens === "number");
+  const costFieldSamples = usageRows.filter((item) =>
+    item && (typeof item.estimatedCostUsd === "number" || typeof item.measuredCostUsd === "number" || typeof item.costMicros === "number")
+  );
+
+  // Cache readiness summary
+  const cacheReadinessSummary = cacheReadiness
+    ? { status: cacheReadiness.status, artifactPath: CACHE_READINESS_REL }
+    : { status: "not_available", artifactPath: null };
+
+  // Cost evidence from token efficiency
+  const costEvidence = tokenEvidence
+    ? {
+        evidenceLevel: tokenEvidence.evidenceLevel || "not_available",
+        rawRepoEstimateTokens: tokenEvidence.rawRepoEstimateTokens ?? null,
+        selectedContextTokens: tokenEvidence.selectedContextTokens ?? null,
+        rawToolOutputTokens: tokenEvidence.rawToolOutputTokens ?? null,
+        summarizedToolOutputTokens: tokenEvidence.summarizedToolOutputTokens ?? null,
+        noExactCostClaim: tokenEvidence.noExactCostClaim ?? true,
+      }
+    : null;
+
+  // Quality gate summary
+  const qualityGateSummary = qualityGate
+    ? {
+        status: qualityGate.status,
+        verdict: qualityGate.verdict,
+        checksPass: qualityGate.quality?.checksPass ?? null,
+        checksWarn: qualityGate.quality?.checksWarn ?? null,
+        checksFail: qualityGate.quality?.checksFail ?? null,
+      }
+    : null;
+
+  // Runs observed
+  const runsObserved = tokenEvidence ? 1 : (capturedUsage || []).length;
+
+  // Status
+  let status;
+  if (evidenceMode === "measured" || realUsageSamples.length > 0) {
+    status = "ready";
+  } else if (evidenceMode === "estimated" || evidenceMode === "heuristic") {
+    status = "partial";
+  } else if (evidenceLevel === "not_available" && runsObserved === 0) {
+    status = "not_available";
+  } else if (evidenceLevel === "exact") {
+    status = "ready";
+  } else if (evidenceLevel === "estimated" || evidenceLevel === "mixed") {
+    status = "partial";
+  } else {
+    status = "not_available";
+  }
+
+  // Build caveats
+  const caveats = [
+    "Token estimates are approximate and may vary from actual provider billing.",
+    "No exact dollar savings are claimed without a verified billing source.",
+    "Tokenizer mismatch between local estimates and actual API tokenization may cause variance.",
+  ];
+  if (evidenceLevel === "not_available") {
+    caveats.push("No token/cost evidence is currently available. Run avorelo token-efficiency --json to generate.");
+  }
+  if (contextAvoidedEstimate === null) {
+    caveats.push("Context avoided estimate not yet computed. Run a full task to populate.");
+  }
+  if (realUsageSamples.length === 0) {
+    caveats.push("No real measured token/cost usage samples are available yet.");
+  }
+
+  let confidence = tokenCostEvidenceSummary?.confidence || "missing";
+  if (confidence === "missing" && realUsageSamples.length > 0) confidence = "measured";
+  else if (confidence === "missing" && tokenFieldSamples.length > 0) confidence = "estimated";
+  else if (confidence === "missing" && (status === "partial" || evidenceLevel === "estimated" || evidenceLevel === "mixed")) confidence = "heuristic";
+
+  const tokenFieldsAvailable = tokenCostEvidenceSummary?.tokenFieldsAvailable || (tokenFieldSamples.length > 0
+    ? ["totalTokens", "promptTokens", "completionTokens"].filter((field) =>
+        importedUsage.some((item) => typeof item[field] === "number")
+      )
+    : []);
+  const costFieldsAvailable = tokenCostEvidenceSummary?.costFieldsAvailable || (costFieldSamples.length > 0
+    ? ["estimatedCostUsd", "measuredCostUsd", "costMicros", "currency"].filter((field) =>
+        importedUsage.some((item) => item[field] !== null && item[field] !== undefined && item[field] !== "")
+      )
+    : []);
+  const missingEvidence = [...(tokenCostEvidenceSummary?.missingEvidence || [])];
+  if (!tokenEvidence) missingEvidence.push("No local token-efficiency artifact available for heuristic comparison.");
+  const safeNextActions = [...(tokenCostEvidenceSummary?.safeNextActions || [])];
+  if ((capturedUsage || []).length === 0) {
+    safeNextActions.push("Run: node bin/avorelo token-cost capture --json");
+  }
+  if (!tokenEvidence) {
+    safeNextActions.push("Run: node bin/avorelo token-efficiency --json");
+  }
+  if (!safeNextActions.includes("Use imported real usage evidence only for measured cost claims.")) {
+    safeNextActions.push("Use imported real usage evidence only for measured cost claims.");
+  }
+
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: nowIso(),
+    status,
+    readinessStatus: status === "ready" ? "pass" : status === "partial" ? "warn" : "info",
+    evidenceLevel,
+    evidenceMode,
+    evidenceAvailable: tokenCostEvidenceSummary?.evidenceAvailable === true || evidenceLevel !== "not_available",
+    runsObserved,
+    realUsageSamplesCount: realUsageSamples.length,
+    capturedUsageSamplesCount: tokenCostEvidenceSummary?.capturedUsageSamplesCount || 0,
+    importedUsageSamplesCount: tokenCostEvidenceSummary?.importedUsageSamplesCount || 0,
+    source: Object.assign({
+      heuristicArtifact: tokenEvidence ? TOKEN_EVIDENCE_REL : null,
+      importedEvidence: evidence.refs.importedUsage,
+      capturedEvidence: evidence.refs.capturedUsage,
+    }, tokenCostEvidenceSummary?.source || {}),
+    costFieldsAvailable,
+    tokenFieldsAvailable,
+    estimatedOnly: evidenceMode !== "measured",
+    confidence,
+    tokenEvidenceRefs,
+    contextAvoidedEstimate,
+    outputAvoidedEstimate,
+    cacheReadinessSummary,
+    costEvidence,
+    qualityGateSummary,
+    caveats,
+    missingEvidence,
+    safeNextActions,
+    noSavingsClaimUnlessMeasured: true,
+    noExactSavingsClaim: true,
+    redacted: true,
+  };
+}
+
+function writeTokenCostIntelligence(cwd, intelligence) {
+  const dirAbs = path.join(cwd, INTELLIGENCE_DIR_REL);
+  fs.mkdirSync(dirAbs, { recursive: true });
+  const absPath = path.join(cwd, ARTIFACT_REL);
+  fs.writeFileSync(absPath, JSON.stringify(intelligence, null, 2), "utf8");
+  return absPath;
+}
+
+function buildTokenCostIntelligenceSurface(cwd, options = {}) {
+  const absPath = path.join(cwd, ARTIFACT_REL);
+  const existing = safeReadJson(absPath);
+  if (existing) {
+    return {
+      status: existing.status,
+      readinessStatus: existing.readinessStatus,
+      evidenceLevel: existing.evidenceLevel,
+      runsObserved: existing.runsObserved,
+      realUsageSamplesCount: existing.realUsageSamplesCount || 0,
+      noExactSavingsClaim: true,
+      artifactPath: ARTIFACT_REL,
+    };
+  }
+  const intel = buildTokenCostRollup(cwd, options);
+  writeTokenCostIntelligence(cwd, intel);
+  return {
+    status: intel.status,
+    readinessStatus: intel.readinessStatus,
+    evidenceLevel: intel.evidenceLevel,
+    runsObserved: intel.runsObserved,
+    realUsageSamplesCount: intel.realUsageSamplesCount || 0,
+    noExactSavingsClaim: true,
+    artifactPath: ARTIFACT_REL,
+  };
+}
+
+function formatTokenCostIntelligenceText(intelligence, options = {}) {
+  const debug = options.debug === true;
+  const lines = [];
+
+  lines.push(`Token/cost intelligence: ${intelligence.status}`);
+  lines.push(`  Evidence level: ${intelligence.evidenceLevel}`);
+  lines.push(`  Evidence mode: ${intelligence.evidenceMode || "missing"}`);
+  lines.push(`  Runs observed: ${intelligence.runsObserved}`);
+  lines.push(`  Real usage samples: ${intelligence.realUsageSamplesCount || 0}`);
+  lines.push(`  Confidence: ${intelligence.confidence || "missing"}`);
+
+  if (intelligence.contextAvoidedEstimate !== null) {
+    lines.push(`  Context avoided (estimate): ${intelligence.contextAvoidedEstimate} tokens`);
+  }
+  if (intelligence.outputAvoidedEstimate !== null) {
+    lines.push(`  Output avoided (estimate): ${intelligence.outputAvoidedEstimate} tokens`);
+  }
+  lines.push(`  Cache readiness: ${intelligence.cacheReadinessSummary?.status || "not_available"}`);
+  lines.push(`  No exact savings claim: ${intelligence.noExactSavingsClaim}`);
+
+  if (debug) {
+    lines.push("");
+    lines.push("Caveats:");
+    for (const caveat of intelligence.caveats || []) {
+      lines.push(`  - ${caveat}`);
+    }
+    if (intelligence.qualityGateSummary) {
+      lines.push("");
+      lines.push(`Quality gate: ${intelligence.qualityGateSummary.status} (verdict: ${intelligence.qualityGateSummary.verdict})`);
+      lines.push(`  Pass: ${intelligence.qualityGateSummary.checksPass}, Warn: ${intelligence.qualityGateSummary.checksWarn}, Fail: ${intelligence.qualityGateSummary.checksFail}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  ARTIFACT_REL,
+  TOKEN_EVIDENCE_REL,
+  classifyEvidenceLevel,
+  collectTokenCostEvidence,
+  buildTokenCostRollup,
+  writeTokenCostIntelligence,
+  buildTokenCostIntelligenceSurface,
+  formatTokenCostIntelligenceText,
+};

package/scripts/lib/token-efficiency-evidence.js

@@ -0,0 +1,213 @@
+"use strict";
+
+// ── Token Efficiency Evidence ─────────────────────────────────────────────────
+//
+// Builds deterministic, honest token efficiency evidence for Avorelo.
+// Estimates input/context/tool-output token sizes locally.
+// Does NOT claim exact dollar savings. Does NOT call external APIs.
+//
+// Contract: avorelo.tokenEfficiencyEvidence.v1
+//
+// Evidence levels:
+//   exact        — from a real usage measurement source
+//   estimated    — from counted text/context sizes (approximate)
+//   not_available — no evidence source available
+//
+// Non-goals: LLM calls, provider billing, guaranteed savings, external tokenizer.
+
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+const { ensureCcoDirs, nowIso } = require("./fsx");
+const { appendProductLearningEvent } = require("./product-learning-events");
+
+const CONTRACT = "avorelo.tokenEfficiencyEvidence.v1";
+const SCHEMA_VERSION = 1;
+
+const EVIDENCE_DIR_REL = ".claude/cco/orchestration/token-efficiency";
+const LATEST_EVIDENCE_REL = `${EVIDENCE_DIR_REL}/latest-evidence.json`;
+
+// ── Re-use estimateTokens from context-optimizer ──────────────────────────────
+
+function estimateTextTokens(text, options = {}) {
+  if (!text) return { estimatedTokens: 0, estimatedChars: 0, estimateMethod: "heuristic" };
+  try {
+    const { estimateTokens } = require("./context-optimizer");
+    return estimateTokens(String(text));
+  } catch {
+    const s = String(text);
+    return {
+      estimatedTokens: Math.ceil(s.length / 4),
+      estimatedChars: s.length,
+      estimateMethod: "heuristic",
+    };
+  }
+}
+
+function estimateFileTokens(cwd, relPath, options = {}) {
+  try {
+    const abs = path.join(cwd, relPath);
+    if (!fs.existsSync(abs)) return { estimatedTokens: 0, estimatedChars: 0, estimateMethod: "heuristic", path: relPath, missing: true };
+    const stat = fs.statSync(abs);
+    if (stat.size > 1024 * 1024) {
+      // Large file: heuristic only
+      return { estimatedTokens: Math.ceil(stat.size / 4), estimatedChars: stat.size, estimateMethod: "heuristic", path: relPath, largeFile: true };
+    }
+    const content = fs.readFileSync(abs, "utf8");
+    const est = estimateTextTokens(content, options);
+    return { ...est, path: relPath };
+  } catch {
+    return { estimatedTokens: 0, estimatedChars: 0, estimateMethod: "heuristic", path: relPath, error: true };
+  }
+}
+
+// ── Build evidence ────────────────────────────────────────────────────────────
+
+function buildTokenEfficiencyEvidence(cwd, input = {}, options = {}) {
+  const {
+    rawContextText,
+    selectedContextText,
+    rawToolOutputText,
+    summarizedToolOutputText,
+    exactUsageSource,
+  } = input;
+
+  const caveats = ["Token estimates are approximate and may vary from actual provider billing."];
+  let evidenceLevel = "not_available";
+  let status = "not_available";
+
+  let rawRepoEstimateTokens = null;
+  let selectedContextTokens = null;
+  let contextAvoidedEstimate = null;
+  let rawToolOutputTokens = null;
+  let summarizedToolOutputTokens = null;
+  let outputAvoidedEstimate = null;
+
+  if (exactUsageSource) {
+    evidenceLevel = "exact";
+    status = "available";
+    caveats.push("Exact usage from provided source; verify against provider billing.");
+  } else if (rawContextText || selectedContextText || rawToolOutputText || summarizedToolOutputText) {
+    evidenceLevel = "estimated";
+    status = "partial";
+  }
+
+  if (rawContextText) {
+    rawRepoEstimateTokens = estimateTextTokens(rawContextText).estimatedTokens;
+  }
+  if (selectedContextText) {
+    selectedContextTokens = estimateTextTokens(selectedContextText).estimatedTokens;
+  }
+  if (rawRepoEstimateTokens !== null && selectedContextTokens !== null) {
+    contextAvoidedEstimate = Math.max(0, rawRepoEstimateTokens - selectedContextTokens);
+    status = "available";
+  }
+  if (rawToolOutputText) {
+    rawToolOutputTokens = estimateTextTokens(rawToolOutputText).estimatedTokens;
+  }
+  if (summarizedToolOutputText) {
+    summarizedToolOutputTokens = estimateTextTokens(summarizedToolOutputText).estimatedTokens;
+  }
+  if (rawToolOutputTokens !== null && summarizedToolOutputTokens !== null) {
+    outputAvoidedEstimate = Math.max(0, rawToolOutputTokens - summarizedToolOutputTokens);
+  }
+
+  // Read context pack as an evidence source
+  try {
+    const packPath = path.join(cwd, ".claude/cco/orchestration/context-optimizer/latest-receipt.json");
+    if (fs.existsSync(packPath)) {
+      const receipt = JSON.parse(fs.readFileSync(packPath, "utf8"));
+      if (receipt.totalEstimatedTokens && selectedContextTokens === null) {
+        selectedContextTokens = receipt.totalEstimatedTokens;
+        evidenceLevel = evidenceLevel === "not_available" ? "estimated" : evidenceLevel;
+        status = status === "not_available" ? "partial" : status;
+      }
+    }
+  } catch {}
+
+  return {
+    contract: CONTRACT,
+    schemaVersion: SCHEMA_VERSION,
+    createdAt: nowIso(),
+    status,
+    evidenceLevel,
+    rawRepoEstimateTokens,
+    selectedContextTokens,
+    contextAvoidedEstimate,
+    rawToolOutputTokens,
+    summarizedToolOutputTokens,
+    outputAvoidedEstimate,
+    cacheReadinessRef: `.claude/cco/orchestration/cache-readiness/latest-readiness.json`,
+    contextQualityGateRef: `.claude/cco/orchestration/token-efficiency/latest-quality-gate.json`,
+    caveats,
+    noExactCostClaim: true,
+    redacted: true,
+  };
+}
+
+function writeTokenEfficiencyEvidence(cwd, evidence) {
+  const dir = path.join(cwd, EVIDENCE_DIR_REL);
+  fs.mkdirSync(dir, { recursive: true });
+  const abs = path.join(cwd, LATEST_EVIDENCE_REL);
+  fs.writeFileSync(abs, JSON.stringify(evidence, null, 2), "utf8");
+  try {
+    appendProductLearningEvent(cwd, "token_efficiency_evidence_generated", {
+      status: evidence.status,
+      evidenceLevel: evidence.evidenceLevel,
+      contextAvoidedEstimate: evidence.contextAvoidedEstimate,
+      outputAvoidedEstimate: evidence.outputAvoidedEstimate,
+    });
+  } catch {}
+  return abs;
+}
+
+function buildTokenEfficiencySurface(cwd, options = {}) {
+  const abs = path.join(cwd, LATEST_EVIDENCE_REL);
+  if (!fs.existsSync(abs)) {
+    return { status: "not_available", artifactPath: LATEST_EVIDENCE_REL };
+  }
+  try {
+    const evidence = JSON.parse(fs.readFileSync(abs, "utf8"));
+    return {
+      status: evidence.status || "not_available",
+      evidenceLevel: evidence.evidenceLevel,
+      contextAvoidedEstimate: evidence.contextAvoidedEstimate,
+      outputAvoidedEstimate: evidence.outputAvoidedEstimate,
+      artifactPath: LATEST_EVIDENCE_REL,
+    };
+  } catch {
+    return { status: "error", artifactPath: LATEST_EVIDENCE_REL };
+  }
+}
+
+function formatTokenEfficiencyText(evidence, options = {}) {
+  const lines = [];
+  lines.push(`Token Efficiency Evidence (${evidence.evidenceLevel || "not_available"})`);
+  if (evidence.selectedContextTokens != null) {
+    lines.push(`  Context selected: ~${evidence.selectedContextTokens} tokens`);
+  }
+  if (evidence.contextAvoidedEstimate != null) {
+    lines.push(`  Context avoided (est.): ~${evidence.contextAvoidedEstimate} tokens`);
+  }
+  if (evidence.outputAvoidedEstimate != null) {
+    lines.push(`  Tool output avoided (est.): ~${evidence.outputAvoidedEstimate} tokens`);
+  }
+  if (evidence.caveats && evidence.caveats.length > 0) {
+    lines.push(`  Caveats: ${evidence.caveats[0]}`);
+  }
+  lines.push(`  noExactCostClaim: ${evidence.noExactCostClaim}`);
+  return lines.join("\n");
+}
+
+module.exports = {
+  CONTRACT,
+  SCHEMA_VERSION,
+  LATEST_EVIDENCE_REL,
+  EVIDENCE_DIR_REL,
+  estimateTextTokens,
+  estimateFileTokens,
+  buildTokenEfficiencyEvidence,
+  writeTokenEfficiencyEvidence,
+  buildTokenEfficiencySurface,
+  formatTokenEfficiencyText,
+};