《互联网产品的 AI 架构·平台化与治理》10.2 SDK、CLI 与配置分发

// file: src/gov/config-dist.ts
// tier: L2
// verify: node --test test/gov/platform-eng.test.ts

import { AiError } from "../core/errors.ts";

/** 配置从默认值到请求级覆盖共六层，数字越大优先级越高。 */
export type ConfigSource = "default" | "platform" | "capability" | "tenant" | "team" | "request";
export type ConfigValue = string | number | boolean;

export const SOURCE_RANK: Record<ConfigSource, number> = {
  default: 0, platform: 1, capability: 2, tenant: 3, team: 4, request: 5,
};

export interface ConfigField {
  type: "string" | "number" | "boolean";
  /** 允许覆盖到哪一层；更高的层会被拒绝，而不是静默生效。 */
  overridableTo: ConfigSource;
  min?: number; max?: number; enum?: readonly string[];
}

export type ConfigSchema = Record<string, ConfigField>;
export interface ConfigLayer { source: ConfigSource; values: Record<string, ConfigValue> }

export type ConfigIssueCode =
  | "unknown-key" | "type-mismatch" | "out-of-range"
  | "invalid-enum" | "not-overridable" | "unknown-source";

export interface ConfigIssue { key: string; source: string; code: ConfigIssueCode; detail: string }
export interface ResolvedConfig {
  values: Record<string, ConfigValue>;
  provenance: Record<string, ConfigSource>;
  issues: ConfigIssue[];
}

function invalidValue(field: ConfigField, value: ConfigValue): ConfigIssue | null {
  if (field.type === "number") {
    if (typeof value !== "number" || !Number.isFinite(value)) {
      return { key: "", source: "", code: "type-mismatch", detail: "expected number" };
    }
    if ((field.min !== undefined && value < field.min) || (field.max !== undefined && value > field.max)) {
      return { key: "", source: "", code: "out-of-range", detail: `expected [${field.min ?? "-inf"}, ${field.max ?? "inf"}]` };
    }
    return null;
  }
  if (field.type === "boolean") {
    return typeof value === "boolean" ? null : { key: "", source: "", code: "type-mismatch", detail: "expected boolean" };
  }
  if (typeof value !== "string") {
    return { key: "", source: "", code: "type-mismatch", detail: "expected string" };
  }
  return field.enum !== undefined && !field.enum.includes(value)
    ? { key: "", source: "", code: "invalid-enum", detail: `expected one of ${field.enum.join("|")}` }
    : null;
}

/**
 * 按 source 从低到高叠加。非法值只记 issue 并保留上一层结果，
 * 一次下发要能报告全部问题，而不是遇到第一个错误就中断。
 */
export function resolveConfig(schema: ConfigSchema, layers: readonly ConfigLayer[]): ResolvedConfig {
  const values: Record<string, ConfigValue> = {};
  const provenance: Record<string, ConfigSource> = {};
  const issues: ConfigIssue[] = [];
  const ordered = layers
    .map((layer, index) => ({ layer, index, rank: SOURCE_RANK[layer.source] }))
    .sort((left, right) => left.rank - right.rank || left.index - right.index);
  for (const { layer, rank } of ordered) {
    if (rank === undefined) {
      issues.push({ key: "*", source: String(layer.source), code: "unknown-source", detail: "unknown config source" });
      continue;
    }
    for (const [key, value] of Object.entries(layer.values)) {
      const field = schema[key];
      if (field === undefined) {
        issues.push({ key, source: layer.source, code: "unknown-key", detail: "not in schema" });
        continue;
      }
      if (layer.source !== "default" && rank > SOURCE_RANK[field.overridableTo]) {
        issues.push({ key, source: layer.source, code: "not-overridable", detail: `highest allowed source is ${field.overridableTo}` });
        continue;
      }
      const invalid = invalidValue(field, value);
      if (invalid !== null) {
        issues.push({ ...invalid, key, source: layer.source });
        continue;
      }
      values[key] = value;
      provenance[key] = layer.source;
    }
  }
  return { values, provenance, issues };
}

// ---- 灰度下发：同一主体在同一配置版本下的分桶必须稳定 ----

export interface CanaryStage { percent: number; hours: number }
export interface CanaryPlan {
  configVersion: string;
  baselineVersion: string;
  stages: readonly CanaryStage[];
}

export const DEFAULT_CANARY: readonly CanaryStage[] = [
  { percent: 5, hours: 2 }, { percent: 25, hours: 24 },
  { percent: 50, hours: 24 }, { percent: 100, hours: 0 },
];

export function validateCanary(plan: CanaryPlan): string[] {
  const issues: string[] = [];
  if (plan.configVersion.trim() === "") issues.push("configVersion is empty");
  if (plan.stages.length === 0) issues.push("stages is empty");
  let previous = 0;
  plan.stages.forEach((stage, index) => {
    if (!Number.isInteger(stage.percent) || stage.percent <= previous || stage.percent > 100) {
      issues.push(`stage ${index}: percent must increase within 1..100`);
    }
    if (!Number.isFinite(stage.hours) || stage.hours < 0) {
      issues.push(`stage ${index}: hours must be non-negative`);
    }
    previous = stage.percent;
  });
  if (plan.stages.length > 0 && plan.stages[plan.stages.length - 1].percent !== 100) {
    issues.push("last stage must be 100");
  }
  return issues;
}

/** 32 位 FNV-1a 只做稳定分桶，不作为安全摘要。 */
export function canaryBucket(subjectId: string, configVersion: string): number {
  let hash = 0x811c9dc5;
  const input = `${configVersion}:${subjectId}`;
  for (let index = 0; index < input.length; index += 1) {
    hash ^= input.charCodeAt(index);
    hash = Math.imul(hash, 0x01000193) >>> 0;
  }
  return hash % 100;
}

export interface CanarySnapshot {
  stageIndex: number; percent: number; elapsedHours: number; complete: boolean;
  canarySubjects: string[]; baselineSubjects: string[]; buckets: Record<string, number>;
}

/** 分桶只看主体与配置版本；百分比变大时，已进入灰度的主体不会退回基线。 */
export function canarySnapshot(
  plan: CanaryPlan, startMs: number, nowMs: number, subjects: readonly string[],
): CanarySnapshot {
  const problems = validateCanary(plan);
  if (problems.length > 0) throw new AiError("invalid-request", `config-dist: ${problems.join("; ")}`);
  let remaining = Math.max(0, nowMs - startMs) / 3_600_000;
  let stageIndex = 0;
  let percent = plan.stages[0].percent;
  let complete = false;
  for (let index = 0; index < plan.stages.length; index += 1) {
    const stage = plan.stages[index];
    if (index === plan.stages.length - 1 || remaining < stage.hours) {
      stageIndex = index;
      percent = stage.percent;
      complete = index === plan.stages.length - 1 && remaining >= stage.hours;
      break;
    }
    remaining -= stage.hours;
  }
  const buckets: Record<string, number> = {};
  const canarySubjects: string[] = [];
  const baselineSubjects: string[] = [];
  for (const subject of subjects) {
    const bucket = canaryBucket(subject, plan.configVersion);
    buckets[subject] = bucket;
    if (bucket < percent) canarySubjects.push(subject);
    else baselineSubjects.push(subject);
  }
  return {
    stageIndex, percent, elapsedHours: Math.max(0, nowMs - startMs) / 3_600_000,
    complete, canarySubjects, baselineSubjects, buckets,
  };
}

// ---- 向后兼容：只允许新增字段与放宽约束 ----

/** 删除字段、改类型、收窄枚举或数值范围都会破坏已在用的配置。 */
export function schemaCompatibility(
  before: ConfigSchema, after: ConfigSchema,
): { breaking: boolean; reasons: string[] } {
  const reasons: string[] = [];
  for (const key of Object.keys(before)) {
    const left = before[key];
    const right = after[key];
    if (right === undefined) {
      reasons.push(`${key}:removed`);
      continue;
    }
    if (left.type !== right.type) reasons.push(`${key}:type-changed`);
    if (right.enum !== undefined) {
      const beforeEnum = left.enum;
      if (beforeEnum === undefined || beforeEnum.some((value) => !right.enum!.includes(value))) {
        reasons.push(`${key}:enum-narrowed`);
      }
    }
    if (right.min !== undefined && (left.min === undefined || right.min > left.min)) {
      reasons.push(`${key}:range-narrowed`);
    }
    if (right.max !== undefined && (left.max === undefined || right.max < left.max)) {
      reasons.push(`${key}:range-narrowed`);
    }
  }
  return { breaking: reasons.length > 0, reasons };
}

/** SDK 负责运行时正确，CLI 负责变更时可见；两者共用同一份 schema。 */
export const SURFACE_DUTY = {
  sdk: ["类型与默认值", "重试、超时与幂等", "配置解析与来源标注", "调用指标埋点"],
  cli: ["目录与版本查询", "配置校验与 schema diff", "灰度状态与放量", "回滚与审计导出"],
} as const;