cost-burn

バーンレート傾向の可観測性。コストトラッカーの将来コストスタックの第4の柱です:

質問	スキル
「しきい値を超えたか?」(リアクティブ)	cost-budget-check
「いつしきい値を超えるか?」(予測)	cost-projection
「もっと少なく使えたか?」(比較)	cost-counterfactual
「日次のバーンは加速しているか?」(傾向)	cost-burn ← これ

アルゴリズム

実装: scripts/burn.mjs。

1. cost-tracking ネームスペースからすべての session-* レコードを読み取ります。
2. --lookback(デフォルト 14d)の範囲で --bucket の期間ウィンドウ(デフォルト 1d)にビニングします。
3. 各バケットについて: {n: sessions, spendUsd: sum(total_cost_usd)}。
4. delta = latest.spendUsd - mean(prior non-empty buckets) を計算します。
5. --alert-on-acceleration-pct N が設定されている場合: deltaPct > N のときに exit 1 とします。

スモークトランスクリプト(5日間 @ $0.10/日、今日 $0.50 — 400% の加速)

| Latest bucket spend | $0.500000 (1 sessions) |
| Prior bucket mean | $0.100000 (4 non-empty buckets) |
| **Delta (latest vs prior mean)** | **+$0.400000 (400.00%)** |

# | Window                              | Sessions | Spend
0 | 2026-06-15 14:16 → 2026-06-16 14:16 | 1        | $0.500000
1 | 2026-06-14 14:16 → 2026-06-15 14:16 | 0        | $0.000000
2 | 2026-06-13 14:16 → 2026-06-14 14:16 | 1        | $0.100000
3 | 2026-06-12 14:16 → 2026-06-13 14:16 | 1        | $0.100000
...

ドリフトアラートの終了コード

$ cost burn --bucket 1d --lookback 7d --alert-on-acceleration-pct 50 ⚠ ALERT: latest bucket $0.500000 is 400.0% above prior mean $0.100000 (threshold +50%) exit 1

$ cost burn --bucket 1d --lookback 7d --alert-on-acceleration-pct 500 ✓ latest bucket within +500% of prior mean (actual delta: 400.0%) — OK exit 0

CI 統合

# Fail the build if today's spend accelerated > 100% over the weekly mean
cost burn --bucket 1d --lookback 7d --alert-on-acceleration-pct 100 || alert-oncall

アラートは予算とは独立しています。総支出が予算をはるかに下回っていても、レートの加速で発火します。「通常の 10 倍を消費するホットループを出荷してしまった」というケースを、予算アラームが鳴る前に捕捉します。

cost-trend との違い

スキル	データソース	質問
cost-trend	docs/benchmarks/runs/*.json	「ベンチマークはドリフトしているか(勝率、レイテンシ)?」
cost-burn	cost-tracking ネームスペース	「本番の支出は加速しているか?」

どちらも有用で、異なるデータに対して異なる質問に答えます。

エッジケース

• 履歴が疎(空でない過去のバケットがない)場合: アラートは理由文字列とともにスキップされ、exit 0 となります。コールドスタート時に誤ったアラートが発せられることはありません。
• 過去のバケットがすべて $0 で最新が $0 超の場合: delta は JSON では Infinity/null となり、テーブルでは new とマークされます。アラートは発火しません(比較対象のベースラインがないため)。
• --bucket > --lookback: ハードエラー、exit 2。