《移动游戏产品的架构·客户端与移动运行时》5.2 校验、引用完整性与灰度

// file: src/config/table.ts
// tier: L1
// verify: node --test test/config/table.test.ts

import { fail, ok, type Result } from "../core/result.ts";
import {
  acceptsClient,
  type ConfigTableName,
  type SchemaRegistry,
  type SchemaSet,
  type TableSchema,
} from "./schema.ts";

export const CONFIG_TABLES: readonly ConfigTableName[] = ["level", "card", "activity"];

export interface ConfigRow { readonly [key: string]: unknown; }

export interface ConfigSet {
  readonly schemaVersion: number;
  readonly dataVersion: number;
  readonly tables: Readonly<Record<ConfigTableName, readonly ConfigRow[]>>;
  readonly entryLevelIds: readonly string[];
}

export type IssueCode =
  | "missing-required"
  | "wrong-type"
  | "out-of-range"
  | "unknown-enum"
  | "duplicate-id"
  | "unknown-ref"
  | "orphan-row"
  | "invalid-window";

export interface Issue {
  readonly code: IssueCode;
  readonly table: ConfigTableName;
  readonly rowId: string;
  readonly field: string;
  readonly message: string;
}

export interface ValidationReport { readonly ok: boolean; readonly issues: readonly Issue[]; readonly errorCount: number; }

function idOf(row: ConfigRow): string {
  return typeof row.id === "string" && row.id.length > 0 ? row.id : "<missing-id>";
}

function isInt(value: unknown): value is number {
  return typeof value === "number" && Number.isInteger(value);
}

function issue(code: IssueCode, table: ConfigTableName, rowId: string, field: string, message: string): Issue {
  return { code, table, rowId, field, message };
}

function checkField(table: ConfigTableName, rowId: string, field: string, spec: TableSchema["fields"][string], value: unknown, issues: Issue[]): void {
  if (value === undefined || value === null) {
    if (spec.required) issues.push(issue("missing-required", table, rowId, field, `${field} is required`));
    return;
  }
  switch (spec.kind) {
    case "string":
      if (typeof value !== "string" || value.length === 0) issues.push(issue("wrong-type", table, rowId, field, `${field} must be a non-empty string`));
      break;
    case "int":
      if (!isInt(value)) {
        issues.push(issue("wrong-type", table, rowId, field, `${field} must be an integer`));
        break;
      }
      if (spec.min !== undefined && value < spec.min) issues.push(issue("out-of-range", table, rowId, field, `${field}=${value} below ${spec.min}`));
      if (spec.max !== undefined && value > spec.max) issues.push(issue("out-of-range", table, rowId, field, `${field}=${value} above ${spec.max}`));
      break;
    case "bool":
      if (typeof value !== "boolean") issues.push(issue("wrong-type", table, rowId, field, `${field} must be boolean`));
      break;
    case "enum":
      if (typeof value !== "string" || spec.values === undefined || !spec.values.includes(value)) {
        issues.push(issue("unknown-enum", table, rowId, field, `${field}=${String(value)} is not allowed`));
      }
      break;
    case "ref":
      if (typeof value !== "string" || value.length === 0) issues.push(issue("wrong-type", table, rowId, field, `${field} must be a row id`));
      break;
    case "ref-list":
      if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
        issues.push(issue("wrong-type", table, rowId, field, `${field} must be a string array`));
        break;
      }
      if (spec.min !== undefined && value.length < spec.min) issues.push(issue("out-of-range", table, rowId, field, `${field} has fewer than ${spec.min} items`));
      if (spec.max !== undefined && value.length > spec.max) issues.push(issue("out-of-range", table, rowId, field, `${field} has more than ${spec.max} items`));
      break;
  }
}

function idSets(tables: ConfigSet["tables"]): Map<ConfigTableName, Set<string>> {
  const sets = new Map<ConfigTableName, Set<string>>();
  for (const table of CONFIG_TABLES) {
    const ids = new Set<string>();
    for (const row of tables[table]) if (typeof row.id === "string") ids.add(row.id);
    sets.set(table, ids);
  }
  return sets;
}

function checkRefs(table: ConfigTableName, row: ConfigRow, schema: TableSchema, ids: Map<ConfigTableName, Set<string>>, issues: Issue[]): void {
  const rowId = idOf(row);
  for (const [field, spec] of Object.entries(schema.fields)) {
    if (spec.table === undefined) continue;
    const targets = spec.kind === "ref-list" && Array.isArray(row[field]) ? (row[field] as unknown[]) : [row[field]];
    for (const target of targets) {
      if (typeof target === "string" && !ids.get(spec.table)?.has(target)) {
        issues.push(issue("unknown-ref", table, rowId, field, `${field} points to missing ${spec.table} ${target}`));
      }
    }
  }
}

function checkOrphans(set: ConfigSet, issues: Issue[]): void {
  const levels = new Map<string, ConfigRow>();
  for (const row of set.tables.level) if (typeof row.id === "string") levels.set(row.id, row);
  const visited = new Set<string>();
  const queue: string[] = [];
  for (const id of set.entryLevelIds) {
    if (levels.has(id)) queue.push(id);
    else issues.push(issue("unknown-ref", "level", "entryLevelIds", "entryLevelIds", `entry level ${id} does not exist`));
  }
  while (queue.length > 0) {
    const id = queue.shift() as string;
    if (visited.has(id)) continue;
    visited.add(id);
    const next = levels.get(id)?.nextLevelId;
    if (typeof next === "string") queue.push(next);
  }
  for (const id of levels.keys()) {
    if (!visited.has(id)) issues.push(issue("orphan-row", "level", id, "nextLevelId", `level ${id} is unreachable from entry levels`));
  }

  const cards = new Set<string>();
  for (const row of set.tables.card) if (typeof row.id === "string") cards.add(row.id);
  const reached = new Set<string>();
  const pending: string[] = [];
  for (const id of visited) {
    const row = levels.get(id);
    const enemies = row?.enemyCardIds;
    if (Array.isArray(enemies)) for (const enemy of enemies) if (typeof enemy === "string") pending.push(enemy);
    if (typeof row?.bossCardId === "string") pending.push(row.bossCardId);
  }
  for (const row of set.tables.activity) if (typeof row.featuredCardId === "string") pending.push(row.featuredCardId);
  while (pending.length > 0) {
    const id = pending.shift() as string;
    if (reached.has(id) || !cards.has(id)) continue;
    reached.add(id);
    const next = set.tables.card.find((row) => row.id === id)?.evolvesTo;
    if (typeof next === "string") pending.push(next);
  }
  for (const id of cards) {
    if (!reached.has(id)) issues.push(issue("orphan-row", "card", id, "id", `card ${id} is not referenced by any reachable level or activity`));
  }
}

export function validateSet(set: ConfigSet, schemaSet: SchemaSet): Result<ValidationReport, string> {
  if (set.schemaVersion !== schemaSet.version) {
    return fail("schema-version-mismatch", `bundle declares v${set.schemaVersion} but schema set is v${schemaSet.version}`);
  }
  const issues: Issue[] = [];
  const ids = idSets(set.tables);
  for (const table of CONFIG_TABLES) {
    const seen = new Map<string, number>();
    for (const row of set.tables[table]) {
      const rowId = idOf(row);
      if (typeof row.id === "string") {
        const count = (seen.get(row.id) ?? 0) + 1;
        seen.set(row.id, count);
        if (count === 2) issues.push(issue("duplicate-id", table, rowId, "id", `${table} id ${rowId} appears more than once`));
      }
      for (const [field, spec] of Object.entries(schemaSet.tables[table].fields)) {
        checkField(table, rowId, field, spec, row[field], issues);
      }
      checkRefs(table, row, schemaSet.tables[table], ids, issues);
    }
  }
  for (const row of set.tables.activity) {
    if (isInt(row.startAtMs) && isInt(row.endAtMs) && row.endAtMs <= row.startAtMs) {
      issues.push(issue("invalid-window", "activity", idOf(row), "endAtMs", "activity must end after it starts"));
    }
  }
  checkOrphans(set, issues);
  issues.sort((a, b) => `${a.table}/${a.rowId}/${a.field}/${a.code}`.localeCompare(`${b.table}/${b.rowId}/${b.field}/${b.code}`));
  return ok({ ok: issues.length === 0, issues, errorCount: issues.length });
}

export interface MatrixRow { readonly clientBuild: number; readonly schemaVersion: number | null; readonly state: string; readonly accepted: boolean; }

export function compatibilityMatrix(registry: SchemaRegistry, clientBuilds: readonly number[]): readonly MatrixRow[] {
  return clientBuilds.map((clientBuild) => {
    const resolved = registry.resolve(clientBuild);
    if (!resolved.ok) return { clientBuild, schemaVersion: null, state: "unsupported", accepted: false };
    const verdict = acceptsClient(resolved.value, clientBuild);
    return { clientBuild, schemaVersion: resolved.value.version, state: verdict.state, accepted: verdict.accepted };
  });
}

export interface CanaryBaseline { readonly crashBps: number; readonly anrBps: number; }

export interface CanaryPolicy { readonly minClients: number; readonly maxConfigFailureBps: number; readonly maxCrashDeltaBps: number; readonly maxAnrDeltaBps: number; readonly maxLoadP95Ms: number; }

export interface CanarySample { readonly clients: number; readonly configFailures: number; readonly crashes: number; readonly anr: number; readonly loadP95Ms: number; }

export type CanaryDecision = "hold" | "promote" | "rollback";

export interface CanaryVerdict { readonly decision: CanaryDecision; readonly reasons: readonly string[]; readonly configFailureBps: number; readonly crashBps: number; readonly anrBps: number; }

export const ARK_CANARY_POLICY: CanaryPolicy = {
  minClients: 5_000,
  maxConfigFailureBps: 100,
  maxCrashDeltaBps: 5,
  maxAnrDeltaBps: 2,
  maxLoadP95Ms: 1_200,
};

export const ARK_CANARY_BASELINE: CanaryBaseline = { crashBps: 12, anrBps: 3 };

export function rateBps(count: number, total: number): number {
  if (!Number.isInteger(count) || count < 0 || !Number.isInteger(total) || total < 0) {
    throw new RangeError(`rate inputs must be non-negative integers: ${count}/${total}`);
  }
  return total === 0 ? 0 : Math.floor((count * 10_000) / total);
}

export function decideCanary(sample: CanarySample, baseline: CanaryBaseline, policy: CanaryPolicy = ARK_CANARY_POLICY): CanaryVerdict {
  const configFailureBps = rateBps(sample.configFailures, sample.clients);
  const crashBps = rateBps(sample.crashes, sample.clients);
  const anrBps = rateBps(sample.anr, sample.clients);
  const base = { configFailureBps, crashBps, anrBps };
  if (sample.clients < policy.minClients) {
    return { decision: "hold", reasons: [`sample ${sample.clients} is below minimum ${policy.minClients}`], ...base };
  }
  const reasons: string[] = [];
  if (configFailureBps > policy.maxConfigFailureBps) reasons.push(`config failure ${configFailureBps}bps above ${policy.maxConfigFailureBps}bps`);
  if (crashBps - baseline.crashBps > policy.maxCrashDeltaBps) reasons.push(`crash ${crashBps}bps exceeds baseline+${policy.maxCrashDeltaBps}bps`);
  if (anrBps - baseline.anrBps > policy.maxAnrDeltaBps) reasons.push(`anr ${anrBps}bps exceeds baseline+${policy.maxAnrDeltaBps}bps`);
  if (sample.loadP95Ms > policy.maxLoadP95Ms) reasons.push(`config load p95 ${sample.loadP95Ms}ms above ${policy.maxLoadP95Ms}ms`);
  return reasons.length > 0
    ? { decision: "rollback", reasons, ...base }
    : { decision: "promote", reasons: ["all gates passed"], ...base };
}