《互联网产品的 AI 架构·平台化与治理》2.1 一条能力条目的最小字段

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

import { compareSemver, parseSemver } from "../orch/platform.ts";

export type QualityTier = "frontier" | "standard" | "economy";
export type FailureMode = "retry-safe" | "retry-idempotent" | "no-retry" | "human-escalation";
export type BillingUnit =
  | "micros-per-call"
  | "micros-per-1k-input-tokens"
  | "micros-per-1k-output-tokens";
export type Responsibility = "provider" | "consumer" | "shared";

export interface Sla {
  /** Success rate in (0, 1]; the denominator is written into window. */
  availability: number;
  p95LatencyMs: number;
  /** Human-readable denominator, for example "per version per rolling 28d". */
  window: string;
}

export interface OverridableParam {
  name: string;
  allowed: readonly (string | number)[];
  responsibility: Responsibility;
}

export interface CapabilityContract {
  /** Must equal contract:<id>@<version>; a version can never swap contracts. */
  ref: string;
  inputs: readonly string[];
  outputs: readonly string[];
  /** Fields that must appear in a consumer cache key. */
  cacheKey: readonly string[];
}

export interface CapabilityEntry {
  id: string;
  provider: string;
  version: string;
  contract: CapabilityContract;
  defaultTier: QualityTier;
  overridable: readonly OverridableParam[];
  failure: FailureMode;
  billingUnit: BillingUnit;
  sla: Sla;
  dependsOn: readonly string[];
  /** "none" or an ISO date (YYYY-MM-DD). */
  retireAt: string;
}

export type EntryIssueCode =
  | "invalid-id"
  | "invalid-version"
  | "missing-provider"
  | "contract-ref-mismatch"
  | "empty-contract"
  | "cache-key-not-input"
  | "invalid-tier"
  | "invalid-override"
  | "duplicate-override"
  | "invalid-failure"
  | "invalid-billing-unit"
  | "invalid-sla"
  | "invalid-retirement-date"
  | "self-dependency"
  | "unknown-dependency"
  | "dependency-cycle"
  | "dependency-retired"
  | "duplicate-version";

export interface EntryIssue {
  id: string;
  version: string;
  code: EntryIssueCode;
  detail: string;
}

export const MINIMUM_FIELDS = [
  "id",
  "provider",
  "version",
  "contract",
  "defaultTier",
  "overridable",
  "failure",
  "billingUnit",
  "sla",
  "dependsOn",
  "retireAt",
] as const;

const ID = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)+$/;
const DATE = /^\d{4}-\d{2}-\d{2}$/;
const TIERS: readonly QualityTier[] = ["frontier", "standard", "economy"];
const FAILURES: readonly FailureMode[] = [
  "retry-safe",
  "retry-idempotent",
  "no-retry",
  "human-escalation",
];
const BILLING: readonly BillingUnit[] = [
  "micros-per-call",
  "micros-per-1k-input-tokens",
  "micros-per-1k-output-tokens",
];
const RESPONSIBILITIES: readonly Responsibility[] = ["provider", "consumer", "shared"];

export function isIsoDate(value: string): boolean {
  if (!DATE.test(value)) return false;
  const parsed = new Date(`${value}T00:00:00Z`);
  return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
}

/** Report fields a caller forgot, before type-level validation runs. */
export function missingFields(raw: Record<string, unknown>): string[] {
  const missing: string[] = [];
  for (const field of MINIMUM_FIELDS) {
    const value = raw[field];
    if (value === undefined || value === null) {
      missing.push(field);
    } else if (typeof value === "string" && value.trim() === "") {
      missing.push(field);
    }
  }
  return missing;
}

/** One entry's own schema. Cross-entry rules live in validateCatalog. */
export function validateEntry(entry: CapabilityEntry): EntryIssue[] {
  const issues: EntryIssue[] = [];
  const add = (code: EntryIssueCode, detail: string): void => {
    issues.push({ id: entry.id, version: entry.version, code, detail });
  };
  if (!ID.test(entry.id)) add("invalid-id", `bad capability id ${entry.id}`);
  if (parseSemver(entry.version) === null) add("invalid-version", `bad version ${entry.version}`);
  if (entry.provider.trim() === "") add("missing-provider", "provider is empty");
  if (entry.contract.ref !== `contract:${entry.id}@${entry.version}`) {
    add("contract-ref-mismatch", `expected contract:${entry.id}@${entry.version}`);
  }
  if (entry.contract.inputs.length === 0 || entry.contract.outputs.length === 0) {
    add("empty-contract", "inputs and outputs are required");
  }
  const cacheKey = entry.contract.cacheKey;
  const unknownKey = cacheKey.find((field) => !entry.contract.inputs.includes(field));
  if (unknownKey !== undefined || new Set(cacheKey).size !== cacheKey.length) {
    add("cache-key-not-input", `cache key ${unknownKey ?? "has duplicates"} is not an input`);
  }
  if (!TIERS.includes(entry.defaultTier)) add("invalid-tier", `unknown tier ${entry.defaultTier}`);
  const names = new Set<string>();
  for (const param of entry.overridable) {
    if (param.name.trim() === "" || param.allowed.length === 0
      || !RESPONSIBILITIES.includes(param.responsibility)) {
      add("invalid-override", `bad override ${param.name}`);
    }
    if (names.has(param.name)) add("duplicate-override", `duplicate override ${param.name}`);
    names.add(param.name);
  }
  if (!FAILURES.includes(entry.failure)) add("invalid-failure", `unknown failure ${entry.failure}`);
  if (!BILLING.includes(entry.billingUnit)) {
    add("invalid-billing-unit", `unknown billing unit ${entry.billingUnit}`);
  }
  if (!(entry.sla.availability > 0 && entry.sla.availability <= 1)) {
    add("invalid-sla", `availability ${entry.sla.availability}`);
  }
  if (!(Number.isFinite(entry.sla.p95LatencyMs) && entry.sla.p95LatencyMs > 0)) {
    add("invalid-sla", `p95 ${entry.sla.p95LatencyMs}`);
  }
  if (entry.sla.window.trim() === "") add("invalid-sla", "SLA window has no denominator");
  if (entry.retireAt !== "none" && !isIsoDate(entry.retireAt)) {
    add("invalid-retirement-date", `bad retirement date ${entry.retireAt}`);
  }
  return issues;
}

function latest(entries: readonly CapabilityEntry[], id: string): CapabilityEntry | undefined {
  return entries
    .filter((entry) => entry.id === id && parseSemver(entry.version) !== null)
    .sort((a, b) => compareSemver(b.version, a.version))[0];
}

/** Validate the whole catalog, including dependencies and duplicate versions. */
export function validateCatalog(entries: readonly CapabilityEntry[]): EntryIssue[] {
  const issues: EntryIssue[] = [];
  const ids = new Set(entries.map((entry) => entry.id));
  const counts = new Map<string, number>();
  for (const entry of entries) {
    issues.push(...validateEntry(entry));
    const key = `${entry.id}@${entry.version}`;
    counts.set(key, (counts.get(key) ?? 0) + 1);
  }
  for (const [key, count] of counts) {
    if (count > 1) {
      const at = key.lastIndexOf("@");
      issues.push({
        id: key.slice(0, at),
        version: key.slice(at + 1),
        code: "duplicate-version",
        detail: `${count} entries for ${key}`,
      });
    }
  }
  for (const entry of entries) {
    for (const dep of entry.dependsOn) {
      if (dep === entry.id) {
        issues.push({ id: entry.id, version: entry.version, code: "self-dependency", detail: dep });
        continue;
      }
      if (!ID.test(dep) || !ids.has(dep)) {
        issues.push({
          id: entry.id, version: entry.version, code: "unknown-dependency", detail: dep,
        });
        continue;
      }
      const target = latest(entries, dep);
      if (target !== undefined && isIsoDate(target.retireAt)
        && (entry.retireAt === "none" || entry.retireAt > target.retireAt)) {
        issues.push({
          id: entry.id, version: entry.version, code: "dependency-retired",
          detail: `${dep} retires at ${target.retireAt}`,
        });
      }
    }
  }
  const graph = new Map<string, string[]>();
  for (const entry of entries) {
    graph.set(entry.id, entry.dependsOn.filter((dep) => ids.has(dep) && dep !== entry.id));
  }
  const state = new Map<string, 1 | 2>();
  const reported = new Set<string>();
  const visit = (id: string): void => {
    state.set(id, 1);
    for (const dep of graph.get(id) ?? []) {
      if (state.get(dep) === 1 && !reported.has(id)) {
        const entry = entries.find((item) => item.id === id)!;
        issues.push({
          id, version: entry.version, code: "dependency-cycle", detail: `cycle via ${dep}`,
        });
        reported.add(id);
      } else if (state.get(dep) === undefined) {
        visit(dep);
      }
    }
    state.set(id, 2);
  };
  for (const entry of entries) {
    if (state.get(entry.id) === undefined) visit(entry.id);
  }
  return issues;
}

/** Why a missing field hurts, used by the catalog review checklist. */
export const FIELD_CONSEQUENCES: Record<EntryIssueCode, string> = {
  "invalid-id": "callers cannot address the capability or join metrics by name",
  "invalid-version": "range resolution and rollback have no anchor",
  "missing-provider": "no team owns incidents, upgrades or retirement",
  "contract-ref-mismatch": "a version may silently change its payload",
  "empty-contract": "callers guess fields and only fail at runtime",
  "cache-key-not-input": "cache hits mix tenants or reuse stale inputs",
  "invalid-tier": "routing falls back to an implicit default nobody reviewed",
  "invalid-override": "an allowed value cannot be explained or audited",
  "duplicate-override": "two owners claim the same parameter",
  "invalid-failure": "retry and escalation policy cannot be derived",
  "invalid-billing-unit": "quota and chargeback use incompatible units",
  "invalid-sla": "capacity planning compares numbers with different denominators",
  "invalid-retirement-date": "downstream plans cannot schedule a migration",
  "self-dependency": "the dependency graph never reaches a leaf",
  "unknown-dependency": "retirement order cannot be computed",
  "dependency-cycle": "no safe retirement or rollout order exists",
  "dependency-retired": "the caller outlives a capability it still needs",
  "duplicate-version": "two payloads claim one immutable version",
};