《互联网产品的 AI 架构·平台化与治理》2.3 能力退役与迁移

// file: src/gov/catalog-retirement.ts
// tier: L2
// verify: node --test test/gov/catalog.test.ts

import { isIsoDate } from "./catalog.ts";

export type RetirementStage = "active" | "announced" | "dual-run" | "retired";

export interface MigrationEntry {
  consumer: string;
  monthlyCalls: number;
  /** Share of this consumer's calls already on the replacement, 0..1. */
  migratedRatio: number;
  hasOwnerApproval: boolean;
}

export interface RetirementPlan {
  capability: string;
  version: string;
  stage: RetirementStage;
  announcedAt: string;
  dualRunStart: string;
  retireAt: string;
  migrationTool: string;
  consumers: readonly MigrationEntry[];
}

export interface RetirementPolicy {
  minNoticeDays: number;
  minDualRunDays: number;
  /** Maximum share of old-version traffic allowed at shutdown, 0..1. */
  residualShareLimit: number;
}

export const DEFAULT_RETIREMENT_POLICY: RetirementPolicy = {
  minNoticeDays: 90,
  minDualRunDays: 30,
  residualShareLimit: 0.005,
};

export type RetirementPlanIssueCode =
  | "bad-date"
  | "date-order"
  | "notice-too-short"
  | "dual-run-too-short"
  | "missing-tool"
  | "no-consumers"
  | "duplicate-consumer"
  | "invalid-calls"
  | "invalid-ratio"
  | "invalid-stage";

export interface RetirementPlanIssue {
  field: string;
  code: RetirementPlanIssueCode;
  detail: string;
}

const STAGES: readonly RetirementStage[] = ["active", "announced", "dual-run", "retired"];

export function daysBetween(from: string, to: string): number | null {
  if (!isIsoDate(from) || !isIsoDate(to)) return null;
  return (Date.parse(`${to}T00:00:00Z`) - Date.parse(`${from}T00:00:00Z`)) / 86_400_000;
}

export function validateRetirementPlan(
  plan: RetirementPlan,
  policy: RetirementPolicy = DEFAULT_RETIREMENT_POLICY,
): RetirementPlanIssue[] {
  const issues: RetirementPlanIssue[] = [];
  const add = (field: string, code: RetirementPlanIssueCode, detail: string): void => {
    issues.push({ field, code, detail });
  };
  if (!STAGES.includes(plan.stage)) add("stage", "invalid-stage", plan.stage);
  const dates = [plan.announcedAt, plan.dualRunStart, plan.retireAt];
  if (dates.some((date) => !isIsoDate(date))) {
    add("dates", "bad-date", dates.join(", "));
  } else if (plan.announcedAt >= plan.dualRunStart || plan.dualRunStart >= plan.retireAt) {
    add("dates", "date-order", "announcedAt < dualRunStart < retireAt is required");
  } else {
    const notice = daysBetween(plan.announcedAt, plan.dualRunStart)!;
    if (notice < policy.minNoticeDays) {
      add("dualRunStart", "notice-too-short", `${notice} < ${policy.minNoticeDays} days`);
    }
    const dual = daysBetween(plan.dualRunStart, plan.retireAt)!;
    if (dual < policy.minDualRunDays) {
      add("retireAt", "dual-run-too-short", `${dual} < ${policy.minDualRunDays} days`);
    }
  }
  if ((plan.stage === "dual-run" || plan.stage === "retired") && plan.migrationTool.trim() === "") {
    add("migrationTool", "missing-tool", "dual-run needs a migration tool");
  }
  if (plan.consumers.length === 0 && plan.stage !== "active") {
    add("consumers", "no-consumers", "no consumer can be migrated");
  }
  const seen = new Set<string>();
  for (const consumer of plan.consumers) {
    if (seen.has(consumer.consumer)) {
      add("consumers", "duplicate-consumer", consumer.consumer);
    }
    seen.add(consumer.consumer);
    if (!Number.isInteger(consumer.monthlyCalls) || consumer.monthlyCalls <= 0) {
      add("monthlyCalls", "invalid-calls", `${consumer.consumer}: ${consumer.monthlyCalls}`);
    }
    if (!(consumer.migratedRatio >= 0 && consumer.migratedRatio <= 1)) {
      add("migratedRatio", "invalid-ratio", `${consumer.consumer}: ${consumer.migratedRatio}`);
    }
  }
  return issues;
}

export interface RetirementMetrics {
  totalConsumers: number;
  migratedConsumers: number;
  migrationRatePct: number;
  residualSharePct: number;
  noticeDays: number;
  dualRunDays: number;
  daysUntilRetire: number;
}

const round1 = (value: number): number => Math.round(value * 10) / 10;

/** Weighted by calls so a tiny but stubborn consumer cannot dominate the view. */
export function retirementMetrics(
  plan: RetirementPlan,
  today: string = plan.retireAt,
): RetirementMetrics {
  const totalCalls = plan.consumers.reduce((sum, item) => sum + item.monthlyCalls, 0);
  const residual = plan.consumers.reduce(
    (sum, item) => sum + item.monthlyCalls * (1 - item.migratedRatio), 0,
  );
  const migrated = plan.consumers.filter((item) => item.migratedRatio >= 0.999).length;
  return {
    totalConsumers: plan.consumers.length,
    migratedConsumers: migrated,
    migrationRatePct: plan.consumers.length === 0
      ? 0 : round1((migrated / plan.consumers.length) * 100),
    residualSharePct: totalCalls === 0 ? 0 : round1((residual / totalCalls) * 100),
    noticeDays: daysBetween(plan.announcedAt, plan.dualRunStart) ?? 0,
    dualRunDays: daysBetween(plan.dualRunStart, plan.retireAt) ?? 0,
    daysUntilRetire: daysBetween(today, plan.retireAt) ?? 0,
  };
}

export type RetirementBlocker =
  | "invalid-plan"
  | "already-retired"
  | "notice-not-started"
  | "dual-run-not-started"
  | "missing-tool"
  | "no-consumers"
  | "not-due"
  | "unmigrated-consumers"
  | "residual-traffic"
  | "missing-approval";

export interface ForceOffDecision {
  allowed: boolean;
  blockers: RetirementBlocker[];
  metrics: RetirementMetrics;
}

/** Hard gate for the final switch: all four conditions must hold. */
export function evaluateForceOff(
  plan: RetirementPlan,
  today: string,
  policy: RetirementPolicy = DEFAULT_RETIREMENT_POLICY,
): ForceOffDecision {
  const blockers: RetirementBlocker[] = [];
  const metrics = retirementMetrics(plan);
  if (plan.migrationTool.trim() === "") blockers.push("missing-tool");
  if (plan.consumers.length === 0) blockers.push("no-consumers");
  if (!isIsoDate(today) || today < plan.retireAt) blockers.push("not-due");
  if (metrics.migratedConsumers < metrics.totalConsumers) blockers.push("unmigrated-consumers");
  if (metrics.residualSharePct / 100 > policy.residualShareLimit) blockers.push("residual-traffic");
  if (plan.consumers.some((item) => !item.hasOwnerApproval)) blockers.push("missing-approval");
  return { allowed: blockers.length === 0, blockers, metrics };
}

export interface RetirementDecision {
  ok: boolean;
  from: RetirementStage;
  to: RetirementStage;
  blockers: RetirementBlocker[];
  issues: RetirementPlanIssue[];
  metrics: RetirementMetrics;
}

/** Forward-only state machine: active -> announced -> dual-run -> retired. */
export function nextStage(
  plan: RetirementPlan,
  today: string,
  policy: RetirementPolicy = DEFAULT_RETIREMENT_POLICY,
): RetirementDecision {
  const issues = validateRetirementPlan(plan, policy);
  const metrics = retirementMetrics(plan);
  if (issues.length > 0) {
    return {
      ok: false, from: plan.stage, to: plan.stage, blockers: ["invalid-plan"], issues, metrics,
    };
  }
  if (plan.stage === "retired") {
    return {
      ok: false, from: plan.stage, to: plan.stage, blockers: ["already-retired"], issues, metrics,
    };
  }
  if (plan.stage === "active") {
    const reached = isIsoDate(today) && today >= plan.announcedAt;
    return {
      ok: reached, from: "active", to: reached ? "announced" : "active",
      blockers: reached ? [] : ["notice-not-started"], issues, metrics,
    };
  }
  if (plan.stage === "announced") {
    if (!isIsoDate(today) || today < plan.dualRunStart) {
      return {
        ok: false, from: "announced", to: "announced",
        blockers: ["dual-run-not-started"], issues, metrics,
      };
    }
    if (plan.migrationTool.trim() === "") {
      return {
        ok: false, from: "announced", to: "announced", blockers: ["missing-tool"], issues, metrics,
      };
    }
    return { ok: true, from: "announced", to: "dual-run", blockers: [], issues, metrics };
  }
  const gate = evaluateForceOff(plan, today, policy);
  return {
    ok: gate.allowed,
    from: "dual-run",
    to: gate.allowed ? "retired" : "dual-run",
    blockers: gate.blockers,
    issues,
    metrics,
  };
}