AI エージェントのカナリアデプロイと自動ロールバック — Antigravity と Burn-Rate SLO で本番を守る

// src/lib/canary-router.ts
// AI エージェントのバージョンをユーザーIDのハッシュで決定的に振り分ける
// 同一ユーザーは常に同じバージョンに振られる(スティッキー)
import { createHash } from "node:crypto";
 
export type AgentVersion = "stable" | "canary";
 
export interface CanaryConfig {
  canaryPercent: number;  // 0-100 のカナリア割合
  forceFlag?: AgentVersion; // 緊急時の強制指定(自動ロールバック発火時に使う)
}
 
export function selectAgentVersion(
  userId: string,
  config: CanaryConfig
): AgentVersion {
  // 緊急ロールバック中なら強制的に stable に倒す
  if (config.forceFlag === "stable") return "stable";
  if (config.canaryPercent <= 0) return "stable";
  if (config.canaryPercent >= 100) return "canary";
 
  // userId をハッシュして 0-99 の整数に変換
  // ハッシュ関数は安定したものを使うこと(Math.random は禁止)
  const h = createHash("sha256").update(userId).digest();
  const bucket = h.readUInt16BE(0) % 100;
  return bucket < config.canaryPercent ? "canary" : "stable";
}
 
// 期待する動作:
// canaryPercent=10 なら、約10%のユーザーが安定的に canary に振られる
// 同一userIdは常に同じバージョンに振られる(セッション中ブレない)

// src/lib/canary-config.ts
// カナリア設定をCloudflare KVから読み込み、エッジで即時反映する
export async function getCanaryConfig(
  env: { CANARY_KV: KVNamespace }
): Promise<CanaryConfig> {
  const raw = await env.CANARY_KV.get("agent:image-gen:canary");
  if (!raw) {
    // フェイルセーフ: KV接続失敗時は安全側(stable 100%)に倒す
    return { canaryPercent: 0 };
  }
  try {
    return JSON.parse(raw) as CanaryConfig;
  } catch {
    return { canaryPercent: 0 };
  }
}
 
// 期待する動作:
// KV書き換えから約60秒以内(Cloudflareのキャッシュ無効化挙動に依存)で
// 全エッジに反映される

// src/lib/agent-telemetry.ts
// エージェント実行の結果を AnalyticsEngine に送る
// バージョン別に成功率・レイテンシ・コストを分けて集計可能にする
export interface AgentExecutionResult {
  version: AgentVersion;
  userId: string;
  success: boolean;
  latencyMs: number;
  costUsd: number;
  errorCode?: string;
}
 
export function recordAgentExecution(
  env: { TELEMETRY: AnalyticsEngineDataset },
  result: AgentExecutionResult
): void {
  env.TELEMETRY.writeDataPoint({
    indexes: [result.version], // バージョン別に高速集計するためのインデックス
    blobs: [
      result.userId,
      result.success ? "success" : "failure",
      result.errorCode ?? "",
    ],
    doubles: [result.latencyMs, result.costUsd],
  });
}
 
// 期待する動作:
// SELECT _sample_interval, blob2, AVG(double1), AVG(double2)
// FROM telemetry WHERE index1 = 'canary' AND timestamp > NOW() - INTERVAL 5 MINUTE
// で 5 分間の canary 系統の平均レイテンシ・平均コストを取得できる

// src/lib/burn-rate.ts
// カナリア系統の Burn-Rate を計算する
// 短期(5分)と長期(1時間)の両方で閾値を超えたときにアラート発火
export interface SLOTarget {
  windowDays: number;       // 例: 30(月次SLO)
  successRateTarget: number; // 例: 0.985(98.5%)
}
 
export interface MetricsWindow {
  totalRequests: number;
  failedRequests: number;
  windowSeconds: number;
}
 
/**
 * 指定ウィンドウでのBurn-Rateを計算する
 * Burn-Rate = (実測失敗率 / 許容失敗率) を 月単位に正規化
 * 値が1なら、月のエラーバジェットをちょうど1ヶ月で使い切るペース
 * 値が10なら、月のバジェットを3日で使い切るペース(危険)
 */
export function computeBurnRate(
  metrics: MetricsWindow,
  slo: SLOTarget
): number {
  if (metrics.totalRequests === 0) return 0;
  const observedErrorRate = metrics.failedRequests / metrics.totalRequests;
  const allowedErrorRate = 1 - slo.successRateTarget;
  if (allowedErrorRate <= 0) return Number.POSITIVE_INFINITY;
  return observedErrorRate / allowedErrorRate;
}
 
/**
 * 短期と長期の両方で閾値超過したらロールバック判定
 * Page-level alert(SRE本)の閾値: 短期5分で14.4, 長期1時間で6
 */
export function shouldRollback(
  short: MetricsWindow,  // 5分窓
  long: MetricsWindow,   // 1時間窓
  slo: SLOTarget
): boolean {
  const shortBR = computeBurnRate(short, slo);
  const longBR = computeBurnRate(long, slo);
  return shortBR > 14.4 && longBR > 6.0;
}
 
// 期待する動作:
// SLO 99% で、直近5分で2%失敗・直近1時間で1.5%失敗していると
// shortBR=14.4超 && longBR=6超 となり true を返す(即時ロールバック判定)

// src/agents/canary-watchdog.ts
// Antigravity Background Agent として5分ごとに実行
// カナリアの Burn-Rate を監視し、危険水域なら自動ロールバックする
import { queryAnalyticsEngine } from "./telemetry-query";
import { computeBurnRate, shouldRollback } from "../lib/burn-rate";
import { setCanaryConfig } from "../lib/canary-config";
 
const SLO = { windowDays: 30, successRateTarget: 0.985 };
 
export async function canaryWatchdogTick(env: Env): Promise<void> {
  const short = await queryAnalyticsEngine(env, "canary", 300); // 5分窓
  const long = await queryAnalyticsEngine(env, "canary", 3600); // 1時間窓
 
  // サンプル数が少なすぎる場合は判定保留(誤発火を防ぐ)
  if (short.totalRequests < 50 || long.totalRequests < 500) {
    console.log(`[watchdog] insufficient samples, skipping`);
    return;
  }
 
  if (shouldRollback(short, long, SLO)) {
    const shortBR = computeBurnRate(short, SLO);
    const longBR = computeBurnRate(long, SLO);
    console.error(
      `[watchdog] ROLLBACK triggered: shortBR=${shortBR.toFixed(1)} longBR=${longBR.toFixed(1)}`
    );
 
    // カナリア割合を 0% に倒し、強制的に stable に戻す
    await setCanaryConfig(env, {
      canaryPercent: 0,
      forceFlag: "stable",
    });
 
    // 通知(Slack/メール/Discordなど運用に合わせて)
    await notifyRollback(env, { shortBR, longBR });
  }
}
 
// 期待する動作:
// 5分ごとに実行され、Burn-Rate閾値を超えたら canary を即停止
// 50リクエスト未満は判定スキップ(統計的有意性を担保)

// src/lib/deploy-state.ts
// カナリアデプロイの状態を有限状態機械として表現する
// 不正な状態遷移をコンパイル時に防ぐ
export type DeployState =
  | { kind: "idle" }
  | { kind: "canary"; percent: 1 | 10 | 50; startedAt: number }
  | { kind: "promoting"; from: number; to: 100; startedAt: number }
  | { kind: "live"; deployedAt: number }
  | { kind: "rolling-back"; reason: string; startedAt: number }
  | { kind: "rolled-back"; reason: string; rolledBackAt: number };
 
export type DeployEvent =
  | { type: "start"; initialPercent: 1 }
  | { type: "advance"; nextPercent: 10 | 50 }
  | { type: "promote" }
  | { type: "complete" }
  | { type: "rollback"; reason: string }
  | { type: "rollback-complete" };
 
export function transition(
  state: DeployState,
  event: DeployEvent
): DeployState | null {
  // idle → canary(1%)
  if (state.kind === "idle" && event.type === "start") {
    return { kind: "canary", percent: 1, startedAt: Date.now() };
  }
  // canary(N%) → canary(N+%)
  if (state.kind === "canary" && event.type === "advance") {
    return { kind: "canary", percent: event.nextPercent, startedAt: Date.now() };
  }
  // canary(50%) → promoting(50→100)
  if (state.kind === "canary" && state.percent === 50 && event.type === "promote") {
    return { kind: "promoting", from: 50, to: 100, startedAt: Date.now() };
  }
  // promoting → live
  if (state.kind === "promoting" && event.type === "complete") {
    return { kind: "live", deployedAt: Date.now() };
  }
  // any → rolling-back(緊急時はどの状態からでも戻せる)
  if (event.type === "rollback") {
    return { kind: "rolling-back", reason: event.reason, startedAt: Date.now() };
  }
  // rolling-back → rolled-back
  if (state.kind === "rolling-back" && event.type === "rollback-complete") {
    return {
      kind: "rolled-back",
      reason: state.reason,
      rolledBackAt: Date.now(),
    };
  }
  // 上記以外の遷移は許可しない
  return null;
}
 
// 期待する動作:
// transition({kind:"idle"}, {type:"start", initialPercent:1})
//   => {kind:"canary", percent:1, startedAt:1715... }
// transition({kind:"canary", percent:1, ...}, {type:"promote"})
//   => null (50%を経由していないのでpromote不可)

// src/lib/synthetic-failure.ts
// カナリア演習用の人為的エラー注入
// 本番では FAILURE_RATE_KV が未設定のため発動しない設計
export function maybeInjectFailure(
  version: AgentVersion,
  env: { FAILURE_RATE_KV: KVNamespace }
): Promise<void> {
  if (version !== "canary") return Promise.resolve();
  return env.FAILURE_RATE_KV.get("drill:failure-rate").then(rateStr => {
    const rate = parseFloat(rateStr ?? "0");
    if (rate > 0 && Math.random() < rate) {
      throw new Error("synthetic_canary_failure");
    }
  });
}
 
// 期待する動作:
// drill:failure-rate に "0.03" を入れると約3%のカナリア要求が失敗扱いになり
// 2ティック以内にウォッチドッグが発火する

// src/lib/cost-burn-rate.ts
// コストを第一級SLOとして扱う
// 持続的なコスト劣化は失敗と同じ重さで扱う
export interface CostWindow {
  totalRequests: number;
  totalCostUsd: number;
  windowSeconds: number;
}
 
export function computeCostRatio(
  canary: CostWindow,
  stable: CostWindow
): number {
  if (canary.totalRequests === 0 || stable.totalRequests === 0) return 1;
  const canaryAvg = canary.totalCostUsd / canary.totalRequests;
  const stableAvg = stable.totalCostUsd / stable.totalRequests;
  if (stableAvg === 0) return Number.POSITIVE_INFINITY;
  return canaryAvg / stableAvg;
}
 
// 期待する動作:
// 1.0 はコスト/リクエストが変化していない
// 2.5 はカナリア要求が stable の 2.5 倍のコストになっている
// 私の運用では 30 分窓で ratio > 1.5 が続いたらロールバック