《互联网产品的 AI 架构·平台化与治理》1.2 治理的四个对象：能力、调用方、租户、版本

tenant 1 ─── n caller
capability 1 ─── n version
caller n ─── n capability   （经由 call relation，带 tenant 与 version）

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

/** 治理只认四类对象：能力、调用方、租户、版本。其余都是属性或关系。 */
export type GovernanceObjectKind = "capability" | "caller" | "tenant" | "version";

export interface CapabilityObject {
  kind: "capability";
  /** 稳定的能力标识，例如 "chat.reply"。 */
  id: string;
  /** 业务功能键；同一个功能键只应有一个在役能力。 */
  functionKey: string;
  owner: string;
  status: "active" | "deprecated" | "retired";
  /** 当前推荐版本，调用方漂移以它为主版本基准。 */
  currentVersion: string;
  /** 被哪个能力替代；仅用于合并期，不能用来掩盖重复建设。 */
  supersedes?: string;
}

export interface CallerObject {
  kind: "caller";
  /** 调用方标识，通常是团队内的一个产品入口或服务。 */
  id: string;
  team: string;
  tenantId: string;
  /** 该调用方在租户额度内分到的月度份额，整数微元。 */
  monthlyQuotaMicros: number;
}

export interface TenantObject {
  kind: "tenant";
  id: string;
  name: string;
  /** 租户月度总额，整数微元。 */
  monthlyQuotaMicros: number;
}

export interface VersionObject {
  kind: "version";
  /** 固定写成 "capabilityId@semver"，不允许另起别名。 */
  id: string;
  capabilityId: string;
  semver: string;
  /** 必须等于 "contract:capabilityId@semver"，把契约钉在版本上。 */
  contractRef: string;
  owner: string;
}

/** 一次「谁在什么租户下用哪个能力的哪个版本」的声明。 */
export interface CallRelation {
  callerId: string;
  tenantId: string;
  capabilityId: string;
  versionId: string;
  monthlyCalls: number;
}

export interface GovernanceSnapshot {
  capabilities: readonly CapabilityObject[];
  callers: readonly CallerObject[];
  tenants: readonly TenantObject[];
  versions: readonly VersionObject[];
  calls: readonly CallRelation[];
}

export type GovernanceIssueCode =
  | "duplicate-id"
  | "missing-owner"
  | "invalid-semver"
  | "invalid-version-id"
  | "contract-mismatch"
  | "unknown-tenant"
  | "unknown-caller"
  | "unknown-capability"
  | "unknown-version"
  | "call-tenant-mismatch"
  | "call-capability-mismatch"
  | "invalid-quota"
  | "retired-capability-in-use";

export interface GovernanceIssue {
  object: GovernanceObjectKind;
  id: string;
  code: GovernanceIssueCode;
  detail: string;
}

const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/;

function issue(
  object: GovernanceObjectKind,
  id: string,
  code: GovernanceIssueCode,
  detail: string,
): GovernanceIssue {
  return { object, id, code, detail };
}

function isQuota(value: number): boolean {
  return Number.isInteger(value) && value >= 0;
}

function majorOf(semver: string): number {
  return Number.parseInt(semver.split(".")[0], 10);
}

/**
 * 关系校验按「对象存在 → 引用一致 → 语义合法」三层执行。
 * 一次返回全部问题，避免修一个报一个。
 */
export function validateGovernance(snapshot: GovernanceSnapshot): GovernanceIssue[] {
  const issues: GovernanceIssue[] = [];

  const tenantIds = new Set<string>();
  for (const tenant of snapshot.tenants) {
    if (tenantIds.has(tenant.id)) {
      issues.push(issue("tenant", tenant.id, "duplicate-id", "tenant id appears twice"));
    }
    tenantIds.add(tenant.id);
    if (tenant.name.trim() === "") issues.push(issue("tenant", tenant.id, "missing-owner", "tenant name is empty"));
    if (!isQuota(tenant.monthlyQuotaMicros)) {
      issues.push(issue("tenant", tenant.id, "invalid-quota", `quota ${tenant.monthlyQuotaMicros}`));
    }
  }

  const callerIds = new Set<string>();
  for (const caller of snapshot.callers) {
    if (callerIds.has(caller.id)) {
      issues.push(issue("caller", caller.id, "duplicate-id", "caller id appears twice"));
    }
    callerIds.add(caller.id);
    if (caller.team.trim() === "") issues.push(issue("caller", caller.id, "missing-owner", "team is empty"));
    if (!tenantIds.has(caller.tenantId)) {
      issues.push(issue("caller", caller.id, "unknown-tenant", caller.tenantId));
    }
    if (!isQuota(caller.monthlyQuotaMicros)) {
      issues.push(issue("caller", caller.id, "invalid-quota", `quota ${caller.monthlyQuotaMicros}`));
    }
  }

  const capabilityIds = new Set<string>();
  for (const capability of snapshot.capabilities) {
    if (capabilityIds.has(capability.id)) {
      issues.push(issue("capability", capability.id, "duplicate-id", "capability id appears twice"));
    }
    capabilityIds.add(capability.id);
    if (capability.owner.trim() === "") issues.push(issue("capability", capability.id, "missing-owner", "owner is empty"));
    if (!SEMVER.test(capability.currentVersion)) {
      issues.push(issue("capability", capability.id, "invalid-semver", capability.currentVersion));
    }
  }

  const versionIds = new Set<string>();
  const versions = new Map<string, VersionObject>();
  for (const version of snapshot.versions) {
    if (versionIds.has(version.id)) {
      issues.push(issue("version", version.id, "duplicate-id", "version id appears twice"));
    }
    versionIds.add(version.id);
    versions.set(version.id, version);
    if (!capabilityIds.has(version.capabilityId)) {
      issues.push(issue("version", version.id, "unknown-capability", version.capabilityId));
    }
    if (!SEMVER.test(version.semver)) {
      issues.push(issue("version", version.id, "invalid-semver", version.semver));
    }
    const expectedId = `${version.capabilityId}@${version.semver}`;
    if (version.id !== expectedId) {
      issues.push(issue("version", version.id, "invalid-version-id", `expected ${expectedId}`));
    }
    const expectedContract = `contract:${expectedId}`;
    if (version.contractRef !== expectedContract) {
      issues.push(issue("version", version.id, "contract-mismatch", `expected ${expectedContract}`));
    }
    if (version.owner.trim() === "") issues.push(issue("version", version.id, "missing-owner", "owner is empty"));
  }

  const capabilities = new Map(snapshot.capabilities.map((item) => [item.id, item]));
  for (const call of snapshot.calls) {
    const caller = snapshot.callers.find((item) => item.id === call.callerId);
    const version = versions.get(call.versionId);
    if (caller === undefined) {
      issues.push(issue("caller", call.callerId, "unknown-caller", "call references an unknown caller"));
      continue;
    }
    if (!capabilityIds.has(call.capabilityId)) {
      issues.push(issue("capability", call.capabilityId, "unknown-capability", "call references an unknown capability"));
    }
    if (version === undefined) {
      issues.push(issue("version", call.versionId, "unknown-version", "call references an unknown version"));
      continue;
    }
    if (caller.tenantId !== call.tenantId) {
      issues.push(issue("caller", caller.id, "call-tenant-mismatch", `${caller.tenantId} != ${call.tenantId}`));
    }
    if (version.capabilityId !== call.capabilityId) {
      issues.push(issue("version", version.id, "call-capability-mismatch", `${version.capabilityId} != ${call.capabilityId}`));
    }
    const capability = capabilities.get(call.capabilityId);
    if (capability?.status === "retired") {
      issues.push(issue("capability", capability.id, "retired-capability-in-use", caller.id));
    }
    if (!Number.isInteger(call.monthlyCalls) || call.monthlyCalls < 0) {
      issues.push(issue("caller", caller.id, "invalid-quota", `monthlyCalls ${call.monthlyCalls}`));
    }
  }

  return issues;
}

/** 同一能力被多个主版本同时调用时，返回这些主版本号，供规模化冲突统计使用。 */
export function majorsInUse(snapshot: GovernanceSnapshot, capabilityId: string): number[] {
  const vers = new Map(snapshot.versions.map((item) => [item.id, item]));
  const majors = new Set<number>();
  for (const call of snapshot.calls) {
    if (call.capabilityId !== capabilityId) continue;
    const version = vers.get(call.versionId);
    if (version !== undefined && SEMVER.test(version.semver)) majors.add(majorOf(version.semver));
  }
  return [...majors].sort((left, right) => left - right);
}