avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/cost-evidence.js

@@ -0,0 +1,287 @@
+"use strict";
+
+// Canonical cost-aware preference layer for active/near-active CJS surfaces.
+// Safe rule:
+// - Use cost-specific totals for cost displays/comparisons.
+// - Fall back to measured import summaries only for measured cost/token display.
+// - Never substitute legacy mixed-unit totals for currency comparisons.
+
+function numberOrZero(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : 0;
+}
+
+function numberOrNull(value) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
+function buildCostEvidenceSummary(params = {}) {
+  const aggregation = params.aggregation || {};
+  const weekly = aggregation.weeklyRepoSummary || {};
+  const measuredUsage = params.measuredUsage || null;
+
+  const aggregatedMeasuredCost = numberOrZero(weekly.measuredCostTotal);
+  const aggregatedCounterfactualCost = numberOrZero(weekly.estimatedCostCounterfactualTotal);
+  const aggregatedTokenUsage = numberOrZero(weekly.tokenUsageTotal);
+
+  const importedMeasuredCost = numberOrZero(measuredUsage?.totalCost);
+  const importedTokenUsage = numberOrZero(measuredUsage?.totalTokens);
+
+  const preferredMeasuredCost = aggregatedMeasuredCost > 0 ? aggregatedMeasuredCost : importedMeasuredCost;
+  const preferredEstimatedCostCounterfactual = aggregatedCounterfactualCost > 0 ? aggregatedCounterfactualCost : null;
+  const preferredTokenUsage = aggregatedTokenUsage > 0 ? aggregatedTokenUsage : importedTokenUsage;
+
+  const comparisonAvailable = preferredMeasuredCost > 0 && preferredEstimatedCostCounterfactual !== null;
+  const source = preferredMeasuredCost > 0 ? "measured" : "unavailable";
+  const basis = comparisonAvailable ? "cost-aware" : preferredMeasuredCost > 0 ? "measured-only" : "unavailable";
+
+  return {
+    measuredCostTotal: aggregatedMeasuredCost,
+    estimatedCostCounterfactualTotal: aggregatedCounterfactualCost,
+    tokenUsageTotal: aggregatedTokenUsage,
+    preferredMeasuredCost,
+    preferredEstimatedCostCounterfactual,
+    preferredTokenUsage,
+    source,
+    basis,
+    comparisonAvailable,
+    fallback:
+      aggregatedMeasuredCost <= 0 && importedMeasuredCost > 0
+        ? "usage-import-summary"
+        : "outcome-aggregation",
+  };
+}
+
+function buildImportedVsInternalDelta(params = {}) {
+  const summary = buildCostEvidenceSummary(params);
+  if (!summary.comparisonAvailable) return null;
+
+  const delta = Math.round((summary.preferredMeasuredCost - summary.preferredEstimatedCostCounterfactual) * 100) / 100;
+  return {
+    measuredCost: summary.preferredMeasuredCost,
+    internalCounterfactual: summary.preferredEstimatedCostCounterfactual,
+    delta,
+    unit: "currency",
+    basis: summary.basis,
+  };
+}
+
+// ── Cost Evidence v1 (avorelo.costEvidence.v1) ────────────────────────────────
+//
+// Builds a structured cost evidence object from local pricing + token evidence.
+// Rules:
+//   - No pricing source → all cost fields null
+//   - Token estimate only → confidence cannot be high
+//   - websiteAllowed / pricingAllowed always false for one-off estimated values
+//   - Never show $0 saved unless truly measured zero
+//   - No network fetch. No billing/account integration.
+
+const crypto = require("crypto");
+
+function shortId() {
+  return crypto.randomBytes(4).toString("hex");
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function buildCostEvidenceV1(params = {}) {
+  const {
+    pricingSource = null,
+    pricingEntry = null,
+    tokenEvidence = null,
+    provider = null,
+    model = null,
+  } = params;
+
+  const costEvidenceId = `ce-${Date.now()}-${shortId()}`;
+  const createdAt = nowIso();
+  const currency = (pricingEntry && pricingEntry.currency) || "USD";
+
+  const hasPricing = pricingSource && pricingSource.available && pricingEntry !== null;
+  const hasTokens = tokenEvidence && tokenEvidence.measurements &&
+    tokenEvidence.measurements.candidateTokenReduction !== null;
+
+  if (!hasPricing) {
+    return {
+      schemaVersion: 1,
+      contract: "avorelo.costEvidence.v1",
+      costEvidenceId,
+      createdAt,
+      pricingSource: pricingSource ? pricingSource.source : "unavailable",
+      usageSource: "unavailable",
+      provider,
+      model,
+      currency,
+      tokenInputs: null,
+      costEstimate: null,
+      costAvoidedEstimate: null,
+      formula: null,
+      confidence: "unavailable",
+      valueClass: "unavailable",
+      caveats: [
+        "Cost estimate unavailable: no local pricing source found.",
+        "Run `avorelo pricing --init` to create a local pricing config.",
+        "Token reduction is available without a pricing source.",
+      ],
+      pricingAllowed: false,
+      dashboardAllowed: false,
+      websiteAllowed: false,
+      redacted: true,
+    };
+  }
+
+  if (!hasTokens) {
+    return {
+      schemaVersion: 1,
+      contract: "avorelo.costEvidence.v1",
+      costEvidenceId,
+      createdAt,
+      pricingSource: pricingSource.source,
+      usageSource: "unavailable",
+      provider: pricingEntry.provider,
+      model: pricingEntry.model,
+      currency,
+      tokenInputs: null,
+      costEstimate: null,
+      costAvoidedEstimate: null,
+      formula: null,
+      confidence: "unavailable",
+      valueClass: "unavailable",
+      caveats: [
+        "Pricing source available but token evidence insufficient for cost estimate.",
+        "Run `avorelo token-evidence --json` to generate token evidence.",
+      ],
+      pricingAllowed: false,
+      dashboardAllowed: false,
+      websiteAllowed: false,
+      redacted: true,
+    };
+  }
+
+  const m = tokenEvidence.measurements;
+  const avoidedTokens = m.candidateTokenReduction;
+
+  // Cost calculation: avoided tokens × input token price (per 1M)
+  // Candidate context avoided = input tokens not sent
+  const pricePerMillion = numberOrNull(pricingEntry.inputTokenPrice);
+  if (pricePerMillion === null || avoidedTokens === null) {
+    return {
+      schemaVersion: 1,
+      contract: "avorelo.costEvidence.v1",
+      costEvidenceId,
+      createdAt,
+      pricingSource: pricingSource.source,
+      usageSource: "token_evidence",
+      provider: pricingEntry.provider,
+      model: pricingEntry.model,
+      currency,
+      tokenInputs: { avoidedCandidateTokens: avoidedTokens },
+      costEstimate: null,
+      costAvoidedEstimate: null,
+      formula: "candidate_token_reduction × input_price_per_1m_tokens",
+      confidence: "unavailable",
+      valueClass: "unavailable",
+      caveats: ["Could not compute cost: missing price or token count."],
+      pricingAllowed: false,
+      dashboardAllowed: false,
+      websiteAllowed: false,
+      redacted: true,
+    };
+  }
+
+  const costAvoidedEstimate = Math.round((avoidedTokens / 1_000_000) * pricePerMillion * 10000) / 10000;
+
+  // Confidence: depends on token method and pricing source
+  // provider_usage + local pricing → medium
+  // local_tokenizer + local pricing → medium
+  // chars_div_4 + local pricing → low (unchanged)
+  const pricingConfidence = pricingSource.confidence || "low";
+  const tokenMethod = tokenEvidence.tokenizer ? (tokenEvidence.tokenizer.method || "chars_div_4") : "chars_div_4";
+  const tokenConfidence = tokenEvidence.tokenizer ? (tokenEvidence.tokenizer.confidence || "low") : "low";
+  const tokenIsStrongerThanCharsDiv4 = tokenMethod === "provider_usage" || tokenMethod === "local_tokenizer";
+  // If token evidence is stronger than chars_div_4, cost confidence can be medium even with default_local pricing
+  const overallConfidence = tokenIsStrongerThanCharsDiv4
+    ? "medium"
+    : (pricingConfidence === "low" || tokenConfidence === "low" ? "low" : "medium");
+
+  const caveats = [
+    `Pricing source: ${pricingSource.caveat || pricingSource.source}`,
+    `Token method: ${tokenEvidence.tokenizer.method} - candidate context is estimated, not a measured model load.`,
+    "Cost estimate is based on avoided candidate context tokens, not actual API spend.",
+    "Do not use for billing reconciliation or exact cost claims.",
+    pricingEntry.caveat || null,
+  ].filter(Boolean);
+
+  return {
+    schemaVersion: 1,
+    contract: "avorelo.costEvidence.v1",
+    costEvidenceId,
+    createdAt,
+    pricingSource: pricingSource.source,
+    usageSource: "token_evidence",
+    provider: pricingEntry.provider,
+    model: pricingEntry.model,
+    currency,
+    tokenInputs: {
+      inputTokens: m.inputTokens,
+      cachedInputTokens: m.cachedInputTokens,
+      outputTokens: m.outputTokens,
+      cacheWriteTokens: m.cacheWriteTokens,
+      cacheReadTokens: m.cacheReadTokens,
+      avoidedCandidateTokens: avoidedTokens,
+    },
+    costEstimate: null, // actual session cost not measurable without provider_usage
+    costAvoidedEstimate,
+    formula: `${avoidedTokens.toLocaleString()} avoided tokens / 1,000,000 x $${pricePerMillion}/M input tokens`,
+    confidence: overallConfidence,
+    valueClass: "estimated",
+    caveats,
+    pricingAllowed: false,
+    dashboardAllowed: true,
+    websiteAllowed: false,
+    redacted: true,
+  };
+}
+
+// ── Artifact-based load/write ─────────────────────────────────────────────────
+// These allow proof-savings-report.js to call loadCostEvidence(cwd) and get
+// a cost evidence artifact from disk (written by token-cost-evidence.js or
+// cost-evidence CLI commands).
+
+const fs = require("fs");
+const path = require("path");
+
+const COST_EVIDENCE_PATH_REL = ".claude/cco/evidence/cost-evidence.json";
+
+function writeCostEvidence(cwd, evidence) {
+  const absPath = path.join(cwd, COST_EVIDENCE_PATH_REL);
+  fs.mkdirSync(path.dirname(absPath), { recursive: true });
+  fs.writeFileSync(absPath, JSON.stringify(evidence, null, 2), "utf8");
+  return absPath;
+}
+
+function loadCostEvidence(cwd) {
+  try {
+    const absPath = path.join(cwd, COST_EVIDENCE_PATH_REL);
+    if (!fs.existsSync(absPath)) return null;
+    const raw = JSON.parse(fs.readFileSync(absPath, "utf8"));
+    // Validate it's a cost evidence object (not a stale unrelated artifact)
+    if (!raw || typeof raw !== "object") return null;
+    return raw;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  COST_EVIDENCE_PATH_REL,
+  buildCostEvidenceSummary,
+  buildImportedVsInternalDelta,
+  buildCostEvidenceV1,
+  numberOrNull,
+  writeCostEvidence,
+  loadCostEvidence,
+};