Cost Attribution

Per-tenant cost attribution from day one. Cryptographically signed audit
trail.

Tradeoff: Every billable op needs a ledger entry. Worth it: client
invoicing is automatic, surprise bills are caught early, and cost-by-feature
guides optimization.

---

How it works

1. OTel baggage carries tenant.id and user.id on every span.
2. LLM calls auto-add cost_usd via OpenInference instrumentation.
3. The cost-attribution exporter aggregates costs by tenant.id per hour.
4. Aggregates are written to:
   • File: .workflow/state/cost-ledger.jsonl (per-project)
   • Stratum: billing_records table (HMAC-signed, append-only) if configured
5. Reports generated by scripts/cost-report.ts.

---

Ledger entry shape

{
  "ts": 1716372013,
  "tenant_id": "client-abc",
  "user_id": "user-123",
  "session_id": "s-7f3a",
  "operation": "llm.call",
  "provider": "anthropic",
  "model": "claude-sonnet-4-6",
  "input_tokens": 1234,
  "output_tokens": 567,
  "cost_usd": 0.0231,
  "hmac": "sha256:..."  // Stratum signs server-side
}

---

Reports

devops cost-report --client client-abc --month 2026-05:

Client: client-abc
Period: 2026-05-01 to 2026-05-31

Total spend:        $124.37
By provider:
  Anthropic:        $118.42
  OpenAI:             $5.95
By model:
  claude-opus-4-7:   $42.18  (12% of calls)
  claude-sonnet-4-6: $63.71  (44% of calls)
  claude-haiku-4-5:  $12.53  (44% of calls)
By feature:
  /api/auth:         $34.21
  /api/payments:     $18.42
  /api/search:       $71.74
Cost per session:   avg $0.34, p95 $1.21
Cost per request:   avg $0.0023, p95 $0.012

---

Hard caps integration

The cost-ledger feeds budget-brake.sh:

• Per-session cap (default $5)
• Per-hour cap (default $20)
• Per-day cap (default $100)

When any cap is hit, the session halts. The agent cannot override.

---

Anomaly detection

scripts/cost-anomaly.ts runs daily and flags:

• Day-over-day spend > 3x weekly average
• Per-client spend exceeding contract terms
• Calls with token counts > 90th percentile (potential prompt bloat)

Anomalies are written to governance/telemetry/cost-anomalies.jsonl.

---

Anti-patterns

Tagging by session only: lose per-feature breakdown. Always include
endpoint or skill name in span attributes.

No HMAC: ledger entries can be tampered. Always sign server-side.

No retention policy: ledger grows unbounded. Roll up to monthly aggregates
after 90 days; archive raw to cold storage.

---

This skill is working when: client invoices reconcile to ledger entries
exactly, and cost-anomaly alerts fire before manual review notices the spike.