avorelo 0.3.8 → 0.4.0-rc.2

package/scripts/lib/efficiency-receipt.js

@@ -0,0 +1,354 @@
+"use strict";
+
+// Efficiency Receipt — unified per-run composer over the already-wired efficiency levers.
+//
+// COMPOSITION ONLY. This module does not introduce a new telemetry system, a new
+// dashboard, or a duplicate savings engine. It reads existing structured artifacts
+// (the tool-output sandbox latest summary + persisted product-learning events) and
+// composes them into ONE honest per-run view: Found / Fixed / Saved / Proved /
+// Needs attention.
+//
+// Rules enforced here (deterministic-first):
+//   - Receipt is built from structured evidence, never from model self-report.
+//   - Every claim carries a claimType: measured | estimated | heuristic.
+//   - "Saved" and "Proved" are kept in separate buckets.
+//   - No invented token/cost savings. Dollar figures are rejected outright; percent
+//     figures are only allowed when measured with a per_run_measurement basis.
+//   - No raw secrets/logs leak: every surfaced string is run through a secret scrub.
+//
+// Artifacts:
+//   .claude/cco/orchestration/efficiency/latest-receipt.json  — avorelo.efficiencyReceipt.v1
+//   .claude/cco/reports/efficiency-teams-aggregate.json        — avorelo.efficiencyTeamsAggregate.v1
+
+const fs = require("fs");
+const path = require("path");
+const { nowIso } = require("./fsx");
+const { readProductLearningEvents } = require("./product-learning-events");
+const { LATEST_SUMMARY_REL } = require("./tool-output-sandbox");
+
+const CONTRACT = "avorelo.efficiencyReceipt.v1";
+const TEAMS_CONTRACT = "avorelo.efficiencyTeamsAggregate.v1";
+const RECEIPT_REL = ".claude/cco/orchestration/efficiency/latest-receipt.json";
+const TEAMS_REL = ".claude/cco/reports/efficiency-teams-aggregate.json";
+
+const CLAIM_TYPES = ["measured", "estimated", "heuristic"];
+
+// Unsupported-claim detection.
+const MONEY_RE = /\$\s?\d|\b\d+(?:\.\d+)?\s?(?:usd|dollars?|cents?)\b/i;
+const SAVINGS_PCT_RE = /\b\d+(?:\.\d+)?\s?%/;
+
+// Secret scrub applied to every surfaced string (defence-in-depth; the sandbox and
+// product-learning layer already redact, this guarantees the composed view never leaks).
+const SECRET_RE =
+  /(?:sk-[A-Za-z0-9_-]{16,}|ghp_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|AKIA[0-9A-Z]{16}|xox[baprs]-[A-Za-z0-9-]{10,}|eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}|-----BEGIN [A-Z ]+-----|(?:authorization|bearer)\s*[:=]\s*\S+|\b[A-Fa-f0-9]{32,}\b)/i;
+
+function unique(values) {
+  return [...new Set((values || []).filter(Boolean))];
+}
+
+function scrub(text) {
+  const s = String(text == null ? "" : text);
+  return SECRET_RE.test(s) ? "[REDACTED]" : s;
+}
+
+// ── Claim classification + unsupported-claim rejection ────────────────────────
+// A claim: { lever, label, claimType, value?, basis? }
+function classifyClaim(claim) {
+  const errors = [];
+  if (!claim || typeof claim !== "object") {
+    return { valid: false, errors: ["claim must be an object"] };
+  }
+  if (!CLAIM_TYPES.includes(claim.claimType)) {
+    errors.push(`claimType must be one of: ${CLAIM_TYPES.join(", ")}`);
+  }
+  const text = `${claim.label || ""} ${claim.value == null ? "" : JSON.stringify(claim.value)}`;
+  if (MONEY_RE.test(text)) {
+    errors.push("unsupported_savings_claim: dollar/cost figures are not permitted in efficiency claims");
+  }
+  if (SAVINGS_PCT_RE.test(text)) {
+    const ok = claim.claimType === "measured" && claim.basis === "per_run_measurement";
+    if (!ok) {
+      errors.push("unsupported_savings_claim: percent figures require a measured per_run_measurement basis");
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+function readLatestSandboxSummary(cwd) {
+  try {
+    const abs = path.join(cwd, LATEST_SUMMARY_REL);
+    if (!fs.existsSync(abs)) return null;
+    return JSON.parse(fs.readFileSync(abs, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// ── Scope A: unified per-run efficiency receipt ───────────────────────────────
+function buildEfficiencyReceipt(cwd, options = {}) {
+  const events = options.events || readProductLearningEvents(cwd);
+  const sandbox =
+    options.sandbox !== undefined ? options.sandbox : readLatestSandboxSummary(cwd);
+
+  const found = [];
+  const fixed = [];
+  const saved = []; // each: { lever, label, claimType, value, basis }
+  const proved = [];
+  const needsAttention = [];
+  const claims = []; // flat audit list (includes heuristic/estimated not placed in "saved")
+  const evidenceRefs = [];
+
+  const byName = {};
+  for (const e of events) {
+    if (e && e.eventName) byName[e.eventName] = (byName[e.eventName] || 0) + 1;
+  }
+
+  // Lever 6/13 — output compression (measured) + Lever 8 diagnostic nextBestAction.
+  if (sandbox && (sandbox.rawChars != null || sandbox.compressedEvidence)) {
+    const rawChars = sandbox.rawChars ?? sandbox.rawEvidence?.rawChars ?? null;
+    const summaryChars =
+      sandbox.summaryChars ?? sandbox.compressedEvidence?.summaryChars ?? null;
+    const ratio =
+      sandbox.compressedEvidence?.compressionRatio ?? sandbox.compressionRatio ?? null;
+    if (rawChars != null && summaryChars != null) {
+      found.push("noisy tool output");
+      fixed.push("compressed output into a decision-grade summary");
+      const c = {
+        lever: "output_compression",
+        label: `raw output reduced from ${rawChars} to ${summaryChars} chars`,
+        claimType: "measured",
+        value: { rawChars, summaryChars, compressionRatio: ratio },
+        basis: "per_run_measurement",
+      };
+      saved.push(c);
+      claims.push(c);
+    }
+    const ref = sandbox.rawEvidenceRef || sandbox.rawEvidence?.path || null;
+    const sha = sandbox.rawEvidenceSha256 || sandbox.rawEvidence?.sha256 || null;
+    if (ref) {
+      evidenceRefs.push({ type: "raw_evidence", ref: scrub(ref), sha256: sha });
+      proved.push("raw evidence retained and hashed");
+    }
+    const redCount = sandbox.redaction?.secretLikeValuesRemoved;
+    if (redCount != null) {
+      proved.push(`redaction performed (${redCount} secret-like value(s) removed)`);
+    }
+    if (sandbox.nextBestAction) {
+      fixed.push(`next action: ${sandbox.nextBestAction}`);
+    }
+    if (sandbox.failOpen) {
+      needsAttention.push(
+        `output sandbox fell back to metadata-only (fail-open: ${sandbox.failOpenReason || "unknown"})`
+      );
+    }
+  } else {
+    needsAttention.push("no output-compression evidence available this run");
+  }
+
+  // Lever 5 — tool/MCP tax / no-connect governor (measured event counts).
+  const toolLoadAvoided = byName.tool_load_avoided || 0;
+  const noConnect = byName.no_connect_decision || 0;
+  const toolLoadRequired = byName.tool_load_required || 0;
+  if (toolLoadAvoided > 0 || noConnect > 0) {
+    found.push("unnecessary external tool request");
+    fixed.push("used local evidence instead of loading a tool");
+    const c = {
+      lever: "tool_tax",
+      label: `external tool load avoided (${toolLoadAvoided} event(s))`,
+      claimType: "measured",
+      value: { toolLoadAvoided, noConnectDecisions: noConnect },
+      basis: "event_count",
+    };
+    saved.push(c);
+    claims.push(c);
+  }
+  if (toolLoadRequired > 0) {
+    proved.push(`tool load justified ${toolLoadRequired} time(s) (external evidence required)`);
+  }
+
+  // Lever 2 — prompt cache hygiene (heuristic; never presented as measured saving).
+  const cacheVolatile = byName.cache_prefix_volatile_detected || 0;
+  const cacheStable = byName.cache_prefix_stable_confirmed || 0;
+  if (cacheStable > 0) {
+    found.push("cache prefix checked");
+    proved.push("cache prefix confirmed stable across samples");
+  }
+  if (cacheVolatile > 0) {
+    found.push("volatile cache prefix");
+    fixed.push("kept volatile data outside cacheable context");
+    needsAttention.push("cache hygiene flagged volatile prefix content (heuristic)");
+    const c = {
+      lever: "cache_hygiene",
+      label: `volatile prefix detected (${cacheVolatile})`,
+      claimType: "heuristic",
+      value: { volatileEvents: cacheVolatile },
+    };
+    claims.push(c); // heuristic — intentionally NOT in "saved"
+  }
+
+  // Lever 1 — strategic routing / route budget (estimated unless measured).
+  const expensiveRouteAvoided = byName.expensive_route_avoided || 0;
+  if (expensiveRouteAvoided > 0) {
+    found.push("expensive route candidate");
+    fixed.push("selected the cheapest safe route");
+    const c = {
+      lever: "route_budget",
+      label: `expensive route avoided (${expensiveRouteAvoided})`,
+      claimType: "estimated",
+      value: { events: expensiveRouteAvoided },
+    };
+    saved.push(c);
+    claims.push(c);
+  }
+
+  // Lever 3/4/9 — context management / reentry hygiene.
+  const ctxTrimmed = byName.context_trimmed || 0;
+  const staleSuppressed = byName.stale_context_suppressed || 0;
+  if (ctxTrimmed > 0 || staleSuppressed > 0) {
+    fixed.push("used compact reentry / suppressed stale context");
+    proved.push(`context hygiene events persisted (${ctxTrimmed + staleSuppressed})`);
+  }
+
+  // Lever 7 — zero-token observability (always honest: count persisted signals).
+  proved.push(`learning events persisted (${events.length})`);
+
+  // Classification audit + invalid-claim guard.
+  const classification = claims.map((c) => {
+    const v = classifyClaim(c);
+    return { lever: c.lever, label: scrub(c.label), claimType: c.claimType, valid: v.valid };
+  });
+  const invalidClaimCount = classification.filter((c) => !c.valid).length;
+
+  const receipt = {
+    contract: CONTRACT,
+    generatedAt: nowIso(),
+    deterministic: true,
+    source: "structured_evidence",
+    found: unique(found).map(scrub),
+    fixed: unique(fixed).map(scrub),
+    saved: saved.map((c) => ({
+      lever: c.lever,
+      label: scrub(c.label),
+      claimType: c.claimType,
+      value: c.value,
+      basis: c.basis || null,
+    })),
+    proved: unique(proved).map(scrub),
+    needsAttention: unique(needsAttention).map(scrub),
+    claims: classification,
+    invalidClaimCount,
+    evidenceRefs,
+    userLine: null,
+  };
+  receipt.userLine = formatEfficiencyReceiptLine(receipt);
+  return receipt;
+}
+
+function formatEfficiencyReceiptLine(receipt) {
+  // Compact, honest. Only measured savings are counted in the headline; estimated /
+  // heuristic items live in advanced detail (the claims array), never presented as fact.
+  const measuredSaved = receipt.saved.filter((s) => s.claimType === "measured").length;
+  const parts = [];
+  if (receipt.found.length) parts.push(`${receipt.found.length} found`);
+  if (receipt.fixed.length) parts.push(`${receipt.fixed.length} fixed`);
+  if (measuredSaved) parts.push(`${measuredSaved} measured saving${measuredSaved === 1 ? "" : "s"}`);
+  if (receipt.proved.length) parts.push(`${receipt.proved.length} proved`);
+  if (receipt.needsAttention.length) parts.push(`${receipt.needsAttention.length} need attention`);
+  return `Avorelo efficiency: ${parts.join(", ") || "no efficiency signals this run"}`;
+}
+
+function writeEfficiencyReceipt(cwd, receipt) {
+  const abs = path.join(cwd, RECEIPT_REL);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, JSON.stringify(receipt, null, 2), "utf8");
+  return RECEIPT_REL;
+}
+
+// ── Scope B: Teams aggregate / "AI Waste Reduced" (privacy-safe, multi-run) ────
+function buildEfficiencyTeamsAggregate(cwd, options = {}) {
+  const events = options.events || readProductLearningEvents(cwd);
+  const count = (name) => events.filter((e) => e && e.eventName === name).length;
+
+  const metrics = {
+    outputsCompressed: count("output_compressed"),
+    rawOutputRetained: count("raw_output_retained"),
+    noisyOutputArtifactsWritten: count("raw_tool_output_artifact_written"),
+    noConnectDecisions: count("no_connect_decision"),
+    toolLoadAvoided: count("tool_load_avoided"),
+    toolLoadRequired: count("tool_load_required"),
+    mcpLazyLoaded: count("mcp_lazy_loaded"),
+    cachePrefixStable: count("cache_prefix_stable_confirmed"),
+    cachePrefixVolatile: count("cache_prefix_volatile_detected"),
+    contextTrimmed: count("context_trimmed"),
+    staleContextSuppressed: count("stale_context_suppressed"),
+    expensiveRouteAvoided: count("expensive_route_avoided"),
+    routeEscalationsJustified: count("route_escalation_justified"),
+    lifecycleHookInvocations: count("lifecycle_hook_handler_invoked"),
+    sandboxSummariesWritten: count("tool_output_sandbox_summary_written"),
+  };
+
+  // Category breakdown (no payloads — counts only).
+  const byCategory = {};
+  for (const e of events) {
+    if (e && e.category) byCategory[e.category] = (byCategory[e.category] || 0) + 1;
+  }
+
+  // Proof coverage is surfaced BEFORE any cost framing (we never assert money totals).
+  const proofCoverage = {
+    compressionWithRetention: Math.min(
+      metrics.outputsCompressed,
+      metrics.rawOutputRetained + metrics.noisyOutputArtifactsWritten
+    ),
+    redactionEvents: count("redaction_performed"),
+    classificationsPresent: true,
+    moneyClaims: false,
+  };
+
+  const aggregate = {
+    contract: TEAMS_CONTRACT,
+    generatedAt: nowIso(),
+    privacySafe: true,
+    basis: "product_learning_events",
+    totalEvents: events.length,
+    metrics,
+    byCategory,
+    proofCoverage,
+    runsWithMissingEvidence: events.length === 0 ? 1 : 0,
+    customerLine: null,
+  };
+  aggregate.customerLine = buildTeamsCustomerLine(aggregate);
+  return aggregate;
+}
+
+function buildTeamsCustomerLine(aggregate) {
+  const m = aggregate.metrics;
+  return scrub(
+    `AI waste reduced: ${m.outputsCompressed} noisy outputs compressed, ` +
+      `${m.toolLoadAvoided} unnecessary tool loads avoided, ` +
+      `${m.cachePrefixVolatile} volatile cache prefixes caught ` +
+      `(${aggregate.totalEvents} privacy-safe signals; counts only, no raw prompts or logs).`
+  );
+}
+
+function writeEfficiencyTeamsAggregate(cwd, aggregate) {
+  const abs = path.join(cwd, TEAMS_REL);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, JSON.stringify(aggregate, null, 2), "utf8");
+  return TEAMS_REL;
+}
+
+module.exports = {
+  CONTRACT,
+  TEAMS_CONTRACT,
+  RECEIPT_REL,
+  TEAMS_REL,
+  CLAIM_TYPES,
+  classifyClaim,
+  readLatestSandboxSummary,
+  buildEfficiencyReceipt,
+  formatEfficiencyReceiptLine,
+  writeEfficiencyReceipt,
+  buildEfficiencyTeamsAggregate,
+  buildTeamsCustomerLine,
+  writeEfficiencyTeamsAggregate,
+};

package/scripts/lib/entitlements.js

@@ -0,0 +1,100 @@
+"use strict";
+
+const path = require("path");
+const { safeReadJson } = require("./fsx");
+const {
+  getPlan,
+  getCapability,
+  isCapabilityEnabled,
+  comparePlans,
+} = require("./plans");
+
+const PLAN_ENV = "AVORELO_PLAN";
+const SUPPORTED_PUBLIC_PLANS = new Set(["free", "pro"]);
+
+function normalizePlanName(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  if (normalized === "teams") return "pro";
+  if (normalized === "enterprise") return "pro";
+  return normalized;
+}
+
+function resolvePlanFromAccountState(cwd) {
+  const account = safeReadJson(cwd, ".claude/cco/state/account.json", null);
+  const fromAccount = normalizePlanName(account?.plan);
+  if (SUPPORTED_PUBLIC_PLANS.has(fromAccount)) return fromAccount;
+  return null;
+}
+
+function resolvePlanFromProjectConfig(cwd) {
+  const config = safeReadJson(cwd, ".claude/cco/config.json", null);
+  const fromConfig = normalizePlanName(config?.tier);
+  if (SUPPORTED_PUBLIC_PLANS.has(fromConfig)) return fromConfig;
+  if (fromConfig === "teams") return "pro";
+  return null;
+}
+
+function getCurrentPlan(options = {}) {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const explicitPlan = normalizePlanName(options.plan);
+  if (SUPPORTED_PUBLIC_PLANS.has(explicitPlan)) {
+    return explicitPlan;
+  }
+  const envPlan = normalizePlanName(process.env[PLAN_ENV]);
+  if (envPlan) {
+    return SUPPORTED_PUBLIC_PLANS.has(envPlan) ? envPlan : "free";
+  }
+  return resolvePlanFromAccountState(cwd) || resolvePlanFromProjectConfig(cwd) || "free";
+}
+
+function capabilityEnabled(capabilityId, options = {}) {
+  return isCapabilityEnabled(getCurrentPlan(options), capabilityId);
+}
+
+function requireCapability(capabilityId, options = {}) {
+  if (capabilityEnabled(capabilityId, options)) {
+    return getCapability(capabilityId);
+  }
+  const plan = getCurrentPlan(options);
+  const capability = getCapability(capabilityId);
+  const comparison = comparePlans();
+  const unlock = comparison.upgradeUnlocks.find((item) => item.id === capabilityId);
+  const label = capability?.label || capabilityId;
+  const note = unlock ? ` Upgrade to Pro to unlock ${label.toLowerCase()}.` : "";
+  throw new Error(`${label} is not available on the ${getPlan(plan)?.name || plan} plan.${note}`);
+}
+
+function getQuota(capabilityId, options = {}) {
+  const plan = getCurrentPlan(options);
+  const capability = requireCapability(capabilityId, options);
+  if (!capability.quota) return null;
+
+  if (capabilityId === "visual_qa_weekly" && plan === "free") {
+    return { ...capability.quota };
+  }
+  if (capabilityId === "visual_qa_weekly" && plan === "pro") {
+    const advanced = getCapability("visual_qa_advanced");
+    return advanced?.quota ? { ...advanced.quota } : { period: "month", limit: 50 };
+  }
+  return { ...capability.quota };
+}
+
+function getHistoryRetention(planName = getCurrentPlan()) {
+  const plan = getPlan(planName) || getPlan("free");
+  return { ...(plan.historyRetention || { mode: "latest_only", maxReports: 1, retentionDays: 7 }) };
+}
+
+function canExportReports(planName = getCurrentPlan()) {
+  const plan = getPlan(planName) || getPlan("free");
+  return plan.exportReports === true;
+}
+
+module.exports = {
+  PLAN_ENV,
+  getCurrentPlan,
+  capabilityEnabled,
+  requireCapability,
+  getQuota,
+  getHistoryRetention,
+  canExportReports,
+};