増えた枠を基線に混ぜない — 週次上限+50%の期限付きウィンドウでバックログを片づける設計

# Before: cron に「一時的な」エントリを直接足す
# 増枠が来たので統合処理を1日3回に増やす（つもり）
0 9,14,21 * * * /usr/local/bin/run-integration-batch.sh

// After: 期限を知っているバーストキュー
// - 期限を過ぎたら新規ジョブを受け付けない
// - 完了見込みが期限を超えるジョブは入口で拒否する
// - 一回性ジョブの種別だけを許可リストで通す
 
type BurstJobKind =
  | "integration-queue"      // 統合キューの消化
  | "link-audit"             // 内部リンク一括監査
  | "reference-consistency"; // 参照データ整合点検
 
interface BurstJob {
  id: string;
  kind: BurstJobKind;
  estimatedMinutes: number; // 過去の同種ジョブの実測から見積もる
}
 
const ALLOWED_KINDS: ReadonlySet<BurstJobKind> = new Set([
  "integration-queue",
  "link-audit",
  "reference-consistency",
]);
 
export class BurstWindow {
  private queue: BurstJob[] = [];
 
  constructor(private readonly expiresAt: Date) {}
 
  /** 入口での受け入れ判定。理由付きで返すとログが読みやすくなります */
  admit(job: BurstJob, now: Date = new Date()): { ok: boolean; reason: string } {
    if (now >= this.expiresAt) {
      return { ok: false, reason: "window-expired" };
    }
    if (!ALLOWED_KINDS.has(job.kind)) {
      // 繰り返し系のジョブ種別はコンパイル時ではなく実行時にも弾く
      return { ok: false, reason: `kind-not-allowed: ${job.kind}` };
    }
    const remainingMinutes =
      (this.expiresAt.getTime() - now.getTime()) / 60_000;
    if (job.estimatedMinutes > remainingMinutes) {
      // 期限をまたぐ見込みのジョブは最初から入れない。
      // 「途中まで進めば得」に見えても、中断状態の後始末コストのほうが高くつきます
      return { ok: false, reason: "would-cross-expiry" };
    }
    this.queue.push(job);
    return { ok: true, reason: "admitted" };
  }
 
  /** 期限到達後は残りを通常レーンへ払い出して空にする */
  drainAfterExpiry(now: Date = new Date()): BurstJob[] {
    if (now < this.expiresAt) return [];
    const leftovers = [...this.queue];
    this.queue = [];
    return leftovers; // 呼び出し側で低優先の通常レーンへ積み直す
  }
}

// 実行1件ごとに lane を付けて記録する最小の台帳
type Lane = "baseline" | "burst";
 
interface RunRecord {
  at: Date;
  lane: Lane;
  taskId: string;
}
 
export class LaneLedger {
  private records: RunRecord[] = [];
 
  record(taskId: string, lane: Lane, at: Date = new Date()): void {
    this.records.push({ at, lane, taskId });
  }
 
  /** 指定期間の lane 別実行数 */
  countByLane(from: Date, to: Date): Record<Lane, number> {
    const out: Record<Lane, number> = { baseline: 0, burst: 0 };
    for (const r of this.records) {
      if (r.at >= from && r.at < to) out[r.lane] += 1;
    }
    return out;
  }
 
  /**
   * 漏れ膨張の点検: 窓の前の週を1.00として、対象週の基線実行数の比を返す。
   * 1.05 を超えたら「基線に何かが混ざった」サインとして警告します
   */
  baselineDriftRatio(refWeek: [Date, Date], targetWeek: [Date, Date]): number {
    const ref = this.countByLane(...refWeek).baseline;
    const target = this.countByLane(...targetWeek).baseline;
    if (ref === 0) return Number.POSITIVE_INFINITY;
    return target / ref;
  }
}