@bongos/core 1.17.0

package/modules/economy/cost-classify.js

@@ -0,0 +1,331 @@
+// Cost-attribution audit + correction pass — V3.R83 (#303), criterion C3.
+// Pure function over db.costSummary() (exposed at /api/gds/public/cost-summary),
+// so it runs against live prod with no DB creds. Flags MIS-attributed spend
+// (a proxy masquerading as a real builder, or an orphaned builder_id); treats
+// NULL/unattributed shared+historical spend as correct, not a bug.
+
+// infra/domain are paid once for the whole project — NULL builder_id is correct.
+const OWNERLESS_CATEGORIES = new Set(['infra', 'domain']);
+
+// #485 (audit F3): a coarse honesty tripwire for MISSING api spend — the gap the
+// original orphan-only audit could not see (it returned a false all-clear while
+// the api category sat at $0.60 project-wide, #482 F1). If real shipping has
+// happened (credits shipped past a floor) but recorded api spend is ~$0, the
+// automatic LLM-cost capture (ADR 0028: grader source=grader, session
+// source=session) is probably not running or not deployed. Deliberately NOT
+// proportional to credits — credits have no fixed dollar value (F2), so this is
+// a coarse "essentially nothing recorded" trip, not a credits→$ ratio. Cost
+// calibration (idea_inbox #132) refines this once real data accumulates.
+const COMPLETENESS_MIN_CREDITS = 500;    // "substantial shipping has happened"
+const COMPLETENESS_API_FLOOR_USD = 1.0;  // below this = essentially nothing recorded
+
+// Code-path enumeration (the "audit every code path that writes cost_log" half
+// of the AC). cost_log has exactly ONE writer — db.logCost() — reached only
+// through the surfaces below. Grep `INSERT INTO cost_log` / `logCost(` to keep
+// it honest: a writer not listed here is itself the finding.
+const COST_WRITE_SURFACES = [
+  {
+    surface: 'POST /api/gds/cost → db.logCost()',
+    file: 'src/bongos/routes/cost.js',
+    builder_id: 'defaults to the authed builder; a provided value must equal the caller or 403s. A builder can only attribute to themselves.',
+  },
+  {
+    surface: 'scripts/gds/backfill-cost.js → POST /api/gds/cost',
+    file: 'scripts/gds/backfill-cost.js',
+    builder_id: 'inherits the POST /cost rule. Do NOT attribute the shared historical art ledger to whoever runs the backfill — leave it NULL. The audit flags it if it happens.',
+  },
+  {
+    // ADR 0028 path 1 (#486): the 4-worker grader panel logs its own cost.
+    surface: 'scripts/gds/ship.js (grader) → POST /api/gds/cost (source=grader)',
+    file: 'scripts/gds/ship.js',
+    builder_id: 'the authed shipper; category=api, source_ref=grade-<task>-<sha>. Idempotent per HEAD.',
+  },
+  {
+    // ADR 0028 path 2 (#560): the interactive session logs its own cost.
+    surface: 'scripts/gds/session-cost.js (SessionEnd hook) → POST /api/gds/cost (source=session)',
+    file: 'scripts/gds/session-cost.js',
+    builder_id: 'the authed builder; category=api, source_ref=<session-id>, task_id=null. Idempotent per session.',
+  },
+  {
+    surface: 'migrations / direct DB',
+    file: '—',
+    builder_id: 'none — no migration writes cost rows. Any future direct write must set builder_id explicitly.',
+  },
+];
+
+/**
+ * Audit cost attribution from a costSummary() payload.
+ * @param {object} summary - the object returned by db.costSummary() /
+ *   GET /api/gds/public/cost-summary (needs total_usd, by_builder, by_category).
+ * @returns {object} structured report: { total_usd, attributed_usd,
+ *   unattributed_usd, unattributed_pct, builders[], flags[], ok }.
+ */
+function auditCostAttribution(summary) {
+  const byBuilder = Array.isArray(summary?.by_builder) ? summary.by_builder : [];
+  const byCategory = Array.isArray(summary?.by_category) ? summary.by_category : [];
+  const totalUsd = Number(summary?.total_usd) || 0;
+
+  let attributedUsd = 0;
+  let unattributedUsd = 0;
+  const builders = [];
+  for (const b of byBuilder) {
+    const usd = Number(b?.total_usd) || 0;
+    if (b?.builder_id == null) {
+      unattributedUsd += usd;
+    } else {
+      attributedUsd += usd;
+      builders.push({
+        builder_id: b.builder_id,
+        label: b.display_name || b.github_login || `builder #${b.builder_id}`,
+        named: !!(b.display_name || b.github_login),
+        total_usd: usd,
+      });
+    }
+  }
+  builders.sort((a, b) => b.total_usd - a.total_usd);
+
+  const flags = [];
+
+  // Orphan attribution: a row attributed to a builder_id the builders table no
+  // longer names. ON DELETE SET NULL should prevent this, but verify rather
+  // than assume — an orphan means a deleted builder's spend is mislabeled.
+  for (const b of builders) {
+    if (!b.named) {
+      flags.push({
+        level: 'warn',
+        kind: 'orphan_attribution',
+        detail: `$${b.total_usd.toFixed(2)} attributed to builder #${b.builder_id}, which has no github_login/display_name — orphaned attribution.`,
+      });
+    }
+  }
+
+  // Honesty note (not a flag): how much of total spend is unattributed, and
+  // how much of THAT is owner-less-by-design (infra/domain) vs historical.
+  const ownerlessUsd = byCategory
+    .filter((c) => OWNERLESS_CATEGORIES.has(c.category))
+    .reduce((s, c) => s + (Number(c.total_usd) || 0), 0);
+
+  const unattributedPct = totalUsd > 0 ? (unattributedUsd / totalUsd) * 100 : 0;
+
+  // #485 (audit F3): COMPLETENESS check — detect MISSING api spend, not just
+  // mis-attribution. This is the gap that made the original audit return a false
+  // all-clear at the #482 baseline ($0.60 api). See the constants above for why
+  // it trips on credits-shipped × api-floor rather than a credits→$ ratio.
+  // This check is the enforcement arm of the GDS-V3 'honest-spend-accounting'
+  // done-when criterion (criterion_ref proposal-146; ADR 0028): "the cost
+  // self-audit detects MISSING api spend, not only mis-attribution."
+  const apiUsd = byCategory
+    .filter((c) => c.category === 'api')
+    .reduce((s, c) => s + (Number(c.total_usd) || 0), 0);
+  const creditsShipped = Number(summary?.total_value_credits) || 0;
+  if (creditsShipped >= COMPLETENESS_MIN_CREDITS && apiUsd < COMPLETENESS_API_FLOOR_USD) {
+    flags.push({
+      level: 'warn',
+      kind: 'api_spend_implausibly_low',
+      detail: `recorded api spend $${apiUsd.toFixed(2)} is implausibly low for ${creditsShipped} credits shipped — automatic LLM-cost capture (ADR 0028: grader source=grader, session source=session) is likely not running or not deployed.`,
+    });
+  }
+
+  // Backfill decision (the "backfill any rows that need correction" half of the
+  // AC), made explicit so the audit logs WHY rather than burying it in a code
+  // comment. Correction is needed only if attribution is actually WRONG — i.e.
+  // an orphaned builder_id. Unattributed (NULL) spend is correct-by-design for
+  // shared/historical cost and is never "corrected" by attributing it to a
+  // proxy. So: backfill needed ⟺ there is an orphan_attribution flag.
+  const orphanFlags = flags.filter((f) => f.kind === 'orphan_attribution');
+  const backfillNeeded = orphanFlags.length > 0;
+  const backfillReason = backfillNeeded
+    ? `${orphanFlags.length} row-group(s) attributed to a builder_id with no name — reconcile or NULL them.`
+    : 'none — no mis-attribution found. Unattributed spend is shared/historical (correctly NULL); attributed spend maps to a named builder.';
+
+  // --- task 1346: fold the System-1 dimensions into the audit -----------------
+  // by_source (call-site split), the cache_read share of LLM-priced spend (the
+  // marathon cost sink — the number System 2 must move), and per-system
+  // eliminated_usd from the savings ledger. All defensive: a summary from a
+  // pre-deploy prod (no by_source/by_tier/savings keys) just reports zeros.
+  const bySource = (Array.isArray(summary?.by_source) ? summary.by_source : [])
+    .map((s) => ({ source: String(s?.source ?? '(unattributed)'), total_usd: round2(s?.total_usd) }));
+  const byTier = summary?.by_tier && typeof summary.by_tier === 'object' ? summary.by_tier : null;
+  const cacheReadUsd = byTier ? round2(byTier.cache_read_usd) : 0;
+  const tierTotalUsd = byTier ? round2(byTier.tier_total_usd) : 0;
+  const cacheReadPct = byTier && byTier.cache_read_pct != null
+    ? round2(byTier.cache_read_pct)
+    : (tierTotalUsd > 0 ? round2((cacheReadUsd / tierTotalUsd) * 100) : 0);
+
+  const savings = summary?.savings && typeof summary.savings === 'object' ? summary.savings : null;
+  const savingsBySystem = savings && Array.isArray(savings.by_system) ? savings.by_system : [];
+  const eliminatedBySystem = savingsBySystem.map((s) => ({
+    system: String(s?.system ?? '(unknown)'),
+    eliminated_usd: round2(s?.saved_usd),
+    baseline_usd: round2(s?.baseline_usd),
+    amount_usd: round2(s?.amount_usd),
+  }));
+  const totalEliminatedUsd = savings && savings.total_saved_usd != null
+    ? round2(savings.total_saved_usd)
+    : round2(eliminatedBySystem.reduce((s, e) => s + e.eliminated_usd, 0));
+
+  // Tripwire: a system in the savings ledger with no real counterfactual behind
+  // it (baseline_usd ≤ 0). saved = baseline − amount, so such a row can never be
+  // an honest saving — it means a system is recorded as "saving" without the
+  // priceUsage()-computed baseline the contract requires. Warn, don't hard-fail.
+  for (const s of eliminatedBySystem) {
+    if (s.baseline_usd <= 0) {
+      flags.push({
+        level: 'warn',
+        kind: 'savings_without_baseline',
+        detail: `system '${s.system}' is in the savings ledger but has no priceUsage baseline (baseline_usd=$${s.baseline_usd.toFixed(2)}) — its claimed saving ($${s.eliminated_usd.toFixed(2)}) cannot be verified.`,
+      });
+    }
+  }
+
+  // The audit never hard-fails at this stage: orphan attribution is reported as
+  // a 'warn' (no 'error'-level flags are emitted yet), so `ok` is informational
+  // headroom for a future hard gate. It is true today by construction.
+  const ok = flags.every((f) => f.level !== 'error');
+
+  return {
+    total_usd: round2(totalUsd),
+    attributed_usd: round2(attributedUsd),
+    unattributed_usd: round2(unattributedUsd),
+    unattributed_pct: round2(unattributedPct),
+    // Category-dimension figure (NOT a subset of unattributed_usd, which is the
+    // builder_id dimension): how much total spend sits in owner-less-by-design
+    // categories. Reported alongside so a high unattributed % can be read as
+    // "mostly shared infra" at a glance.
+    ownerless_category_usd: round2(ownerlessUsd),
+    // #485: completeness inputs — recorded api spend vs shipping activity.
+    api_usd: round2(apiUsd),
+    credits_shipped: creditsShipped,
+    builder_count: builders.length,
+    builders,
+    write_surfaces: COST_WRITE_SURFACES,
+    backfill_needed: backfillNeeded,
+    backfill_reason: backfillReason,
+    // task 1346: System-1 dimensions (zeros when the summary predates the deploy).
+    by_source: bySource,
+    cache_read_usd: cacheReadUsd,
+    tier_total_usd: tierTotalUsd,
+    cache_read_pct: cacheReadPct,
+    eliminated_by_system: eliminatedBySystem,
+    total_eliminated_usd: totalEliminatedUsd,
+    flags,
+    ok,
+  };
+}
+
+function round2(n) {
+  return Math.round((Number(n) || 0) * 100) / 100;
+}
+
+// --- Per-builder monthly budget (V3.R84 #302, criterion C3; default cap removed
+// --- in ADR 0085) ------------------------------------------------------------
+//
+// Builders are UNCAPPED by default. There is deliberately no project-wide
+// default ceiling: when builders.monthly_budget_usd IS NULL (the normal case)
+// a builder's spend is still tracked + reported, but it never blocks them.
+// The original $50 default (ADR 0085 reverses it) auto-capped every builder and
+// blocked the very work it was meant to enable — a fresh builder's own
+// interactive-session API cost crossed $50 within a day or two and froze
+// /builder-ship + the art pipeline. An Archon can still set an explicit positive
+// ceiling on a specific builder via PATCH /builders/:id/budget — the manual
+// emergency brake — and that override still engages the warn/over thresholds.
+
+// Soft cap: warn the builder once they cross this fraction of an explicit budget.
+const SOFT_CAP_FRACTION = 0.8;
+
+// Pure classification of a builder's month-to-date spend against their budget.
+// Kept pure (no DB) so it's unit-testable and so the same level thresholds drive
+// the /me payload, the CLI session-start ping, the hall banner, and the ship/
+// art-pipeline hard-cap refusal — one source of truth for "warn" vs "over".
+//
+//   level: 'ok'   — uncapped (no explicit budget) OR under the soft cap
+//          'warn' — at/over the soft cap (80%) but under an explicit budget → ping + banner
+//          'over' — at/over an explicit budget (100%)                       → hard refuse
+//
+// No explicit budget (NULL / non-finite / <= 0) → uncapped: level is always
+// 'ok', budget_mtd_usd is null, pct_used is 0, and nothing blocks. Only a
+// positive budget set by an Archon engages the warn/over thresholds. Treating a
+// stray 0 as uncapped (rather than always-over) means a bad value can never
+// silently brick every cost path.
+function classifyCostStatus(spendUsd, budgetRaw) {
+  const spend = Math.max(0, Number(spendUsd) || 0);
+  const budget = Number(budgetRaw);
+  // Uncapped — no cap set. Spend is surfaced (the dashboard cares about the $5K
+  // pool) but never gates a builder. budget_mtd_usd === null is the "no cap"
+  // signal every consumer reads (CLI ping, hall banner, ship/art refusal).
+  if (!Number.isFinite(budget) || budget <= 0) {
+    return {
+      spend_mtd_usd: round2(spend),
+      budget_mtd_usd: null,
+      pct_used: 0,
+      level: 'ok',
+    };
+  }
+  const pct = (spend / budget) * 100;
+  let level = 'ok';
+  if (spend >= budget) level = 'over';
+  else if (pct >= SOFT_CAP_FRACTION * 100) level = 'warn';
+  return {
+    spend_mtd_usd: round2(spend),
+    budget_mtd_usd: round2(budget),
+    pct_used: round2(pct),
+    level,
+  };
+}
+
+/** Render an audit report as plain text for a CLI. */
+function formatAuditReport(report) {
+  const lines = [];
+  lines.push('Cost-attribution audit + correction pass (V3.R83 #303)');
+  lines.push('  write surfaces (every code path that writes cost_log):');
+  for (const s of report.write_surfaces || []) {
+    lines.push(`    • ${s.surface}`);
+    lines.push(`        ${s.builder_id}`);
+  }
+  lines.push(`  total spend:        $${report.total_usd.toFixed(2)}`);
+  lines.push(`  attributed:         $${report.attributed_usd.toFixed(2)} across ${report.builder_count} builder(s)`);
+  lines.push(`  unattributed:       $${report.unattributed_usd.toFixed(2)} (${report.unattributed_pct.toFixed(1)}% of total, by builder_id)`);
+  lines.push(`  owner-less categories (infra/domain, by category): $${report.ownerless_category_usd.toFixed(2)}`);
+  lines.push(`  api spend (auto-captured: grader + session): $${(report.api_usd ?? 0).toFixed(2)}  ·  credits shipped: ${report.credits_shipped ?? 0}`);
+  if (report.builders.length) {
+    lines.push('  per builder:');
+    for (const b of report.builders) {
+      lines.push(`    - ${b.label}: $${b.total_usd.toFixed(2)}`);
+    }
+  }
+  // task 1346 — System-1 dimensions. Only render when the summary carried them.
+  if (Array.isArray(report.by_source) && report.by_source.length) {
+    lines.push('  by call-site source (cost_log.source):');
+    for (const s of report.by_source.slice(0, 8)) {
+      lines.push(`    - ${s.source}: $${s.total_usd.toFixed(2)}`);
+    }
+  }
+  if ((report.tier_total_usd ?? 0) > 0) {
+    lines.push(`  cache_read tier: $${(report.cache_read_usd ?? 0).toFixed(2)} = ${(report.cache_read_pct ?? 0).toFixed(1)}% of LLM-priced spend ($${report.tier_total_usd.toFixed(2)}) — the marathon cost sink`);
+  }
+  if (Array.isArray(report.eliminated_by_system) && report.eliminated_by_system.length) {
+    lines.push(`  savings (per-system eliminated_usd; total $${(report.total_eliminated_usd ?? 0).toFixed(2)}):`);
+    for (const e of report.eliminated_by_system) {
+      lines.push(`    - ${e.system}: $${e.eliminated_usd.toFixed(2)} (baseline $${e.baseline_usd.toFixed(2)} − actual $${e.amount_usd.toFixed(2)})`);
+    }
+  }
+  if (report.flags.length) {
+    lines.push('  flags:');
+    for (const f of report.flags) {
+      lines.push(`    [${f.level}] ${f.kind}: ${f.detail}`);
+    }
+  } else {
+    lines.push('  flags: none — attribution is healthy (live writes attributed, unattributed spend is owner-less/historical).');
+  }
+  lines.push(`  backfill needed:    ${report.backfill_needed ? 'YES' : 'NO'} — ${report.backfill_reason}`);
+  lines.push(`  verdict: ${report.ok ? 'OK' : 'NEEDS ATTENTION'}`);
+  return lines.join('\n');
+}
+
+module.exports = {
+  auditCostAttribution,
+  formatAuditReport,
+  OWNERLESS_CATEGORIES,
+  classifyCostStatus,
+  SOFT_CAP_FRACTION,
+};

package/modules/economy/cost-summary-shape.js

@@ -0,0 +1,90 @@
+// src/bongos/cost-summary-shape.js — pure shapers for the cost-summary dimensions
+// added by System 1 / task 1345 (by_source, by_tier, savings). Kept pure (no DB,
+// no I/O) so db.costSummary() stays a thin SQL+shape layer and the aggregation
+// math is unit-testable DB-free (tests/cost_summary_shape.mjs). The audit
+// (cost.js, task 1346) reuses these shapes.
+
+function num(n) {
+  return Number(n) || 0;
+}
+function round2(n) {
+  return Math.round(num(n) * 100) / 100;
+}
+
+// by_source: cost_log rows grouped by source. NULL/empty source → '(unattributed)'
+// so the dimension always reconciles to total_usd. Rows arrive pre-sorted by SQL.
+function shapeBySource(rows) {
+  return (rows || []).map((r) => ({
+    source: r.source == null || r.source === '' ? '(unattributed)' : String(r.source),
+    total_usd: round2(r.total_usd),
+  }));
+}
+
+// by_tier: a single SUM row over the four per-tier columns (migration 123).
+// Returns the four tiers + their total + the cache_read share of total (the
+// marathon cost sink — the headline number System 2 must move). Tiers only sum
+// to total over rows that HAVE the split (session/cron rows); legacy/manual rows
+// are NULL and contribute 0, so tier_total ≤ overall cost_log total — expected.
+function shapeByTier(row) {
+  const r = row || {};
+  const fresh = round2(r.fresh_input_usd);
+  const cacheRead = round2(r.cache_read_usd);
+  const cacheWrite = round2(r.cache_write_usd);
+  const output = round2(r.output_usd);
+  const total = round2(fresh + cacheRead + cacheWrite + output);
+  return {
+    fresh_input_usd: fresh,
+    cache_read_usd: cacheRead,
+    cache_write_usd: cacheWrite,
+    output_usd: output,
+    tier_total_usd: total,
+    cache_read_pct: total > 0 ? round2((cacheRead / total) * 100) : 0,
+  };
+}
+
+// savings: cost_baseline grouped by system tag. saved = baseline - amount.
+// Returns per-system rows + roll-up totals. Negative saved (a system that cost
+// MORE than its counterfactual) is preserved, not clamped — that's a real signal.
+function shapeSavings(rows) {
+  const bySystem = (rows || []).map((r) => {
+    const baseline = round2(r.baseline_usd);
+    const amount = round2(r.amount_usd);
+    return {
+      system: String(r.system),
+      baseline_usd: baseline,
+      amount_usd: amount,
+      saved_usd: round2(baseline - amount),
+      events: r.events == null ? undefined : Number(r.events),
+    };
+  });
+  return {
+    by_system: bySystem,
+    total_baseline_usd: round2(bySystem.reduce((s, r) => s + r.baseline_usd, 0)),
+    total_amount_usd: round2(bySystem.reduce((s, r) => s + r.amount_usd, 0)),
+    total_saved_usd: round2(bySystem.reduce((s, r) => s + r.saved_usd, 0)),
+  };
+}
+
+// cost_calibration: rows from cost_calibration_summary() (migration 143) — one
+// per task kind plus an overall '(all)' row. The SQL already ROUNDs to 4dp; we
+// normalize numeric strings to numbers and preserve a NULL median_cost_per_credit
+// (a kind with no credit-bearing samples) as null rather than coercing it to 0,
+// so the dashboard can tell "0 cost per credit" from "no data". The overall row
+// (kind '(all)') is also surfaced separately for convenience.
+function num4(n) {
+  return n == null ? null : Math.round(Number(n) * 10000) / 10000;
+}
+function shapeCostCalibration(rows) {
+  const by_kind = (rows || []).map((r) => ({
+    kind: String(r.kind),
+    median_cost_per_task: num4(r.median_cost_per_task),
+    median_cost_per_credit: num4(r.median_cost_per_credit),
+    sample_size: Number(r.sample_size) || 0,
+  }));
+  return {
+    by_kind,
+    overall: by_kind.find((r) => r.kind === '(all)') || null,
+  };
+}
+
+module.exports = { shapeBySource, shapeByTier, shapeSavings, shapeCostCalibration };