《互联网产品的 AI 架构·平台化与治理》4.3 借用、回收与隔离

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

/** 团队余额只记份额与已用；借入借出由 Loan 列表推导，避免两套账。 */
export interface TeamBalance { teamId: string; shareMicros: number; usedMicros: number }

export interface Loan {
  id: string;
  lenderId: string;
  borrowerId: string;
  micros: number;
  dueTick: number;
}

export interface TenancyState { balances: TeamBalance[]; loans: Loan[] }

export interface BorrowRule {
  /** 借入方最多借到自身份额的比例。 */
  maxBorrowRatio: number;
  /** 借出方使用率低于该比例才算低峰。 */
  lowPeakRatio: number;
  /** 借出方使用率高于该比例触发回收。 */
  highPeakRatio: number;
}

export const DEFAULT_BORROW: BorrowRule = {
  maxBorrowRatio: 0.25,
  lowPeakRatio: 0.5,
  highPeakRatio: 0.8,
};

export type BorrowReason =
  | "ok" | "unknown-team" | "not-low-peak" | "insufficient-free" | "over-borrow-limit";

export interface BorrowCheck {
  ok: boolean;
  reason: BorrowReason;
  freeMicros: number;
  allowedMicros: number;
}

export interface BorrowResult extends BorrowCheck { loan?: Loan }

function findBalance(state: TenancyState, teamId: string): TeamBalance | undefined {
  return state.balances.find((item) => item.teamId === teamId);
}

export function lentBy(state: TenancyState, teamId: string): number {
  return state.loans
    .filter((loan) => loan.lenderId === teamId)
    .reduce((sum, loan) => sum + loan.micros, 0);
}

export function borrowedBy(state: TenancyState, teamId: string): number {
  return state.loans
    .filter((loan) => loan.borrowerId === teamId)
    .reduce((sum, loan) => sum + loan.micros, 0);
}

/** 使用率用整数百分比比较，避免浮点在边界上抖动。 */
function atLeastRatio(balance: TeamBalance, percent: number): boolean {
  return balance.usedMicros * 100 >= balance.shareMicros * percent;
}

export function canBorrow(
  state: TenancyState,
  lenderId: string,
  borrowerId: string,
  micros: number,
  rule: BorrowRule = DEFAULT_BORROW,
): BorrowCheck {
  const lender = findBalance(state, lenderId);
  const borrower = findBalance(state, borrowerId);
  if (lender === undefined || borrower === undefined) {
    return { ok: false, reason: "unknown-team", freeMicros: 0, allowedMicros: 0 };
  }
  const freeMicros = lender.shareMicros - lender.usedMicros - lentBy(state, lenderId);
  const cap = Math.floor(borrower.shareMicros * rule.maxBorrowRatio);
  const allowedMicros = Math.max(0, cap - borrowedBy(state, borrowerId));
  if (atLeastRatio(lender, rule.lowPeakRatio * 100)) {
    return { ok: false, reason: "not-low-peak", freeMicros, allowedMicros };
  }
  if (micros > freeMicros) {
    return { ok: false, reason: "insufficient-free", freeMicros, allowedMicros };
  }
  if (micros > allowedMicros) {
    return { ok: false, reason: "over-borrow-limit", freeMicros, allowedMicros };
  }
  return { ok: true, reason: "ok", freeMicros, allowedMicros };
}

export function borrow(
  state: TenancyState,
  lenderId: string,
  borrowerId: string,
  micros: number,
  dueTick: number,
  rule: BorrowRule = DEFAULT_BORROW,
): BorrowResult {
  const check = canBorrow(state, lenderId, borrowerId, micros, rule);
  if (!check.ok) return check;
  const loan: Loan = {
    id: `loan-${state.loans.length + 1}`,
    lenderId,
    borrowerId,
    micros,
    dueTick,
  };
  state.loans.push(loan);
  return { ...check, loan };
}

export type ReclaimReason = "due" | "high-peak" | "forced";

export interface ReclaimEvent {
  loanId: string;
  lenderId: string;
  borrowerId: string;
  micros: number;
  reason: ReclaimReason;
  /** 回收后借入方超出自身份额的部分，下一窗口优先扣回。 */
  debtMicros: number;
}

/**
 * 回收顺序：先到期，再借出方进入高峰，最后才是强制回收。
 * 同一笔贷款只回收一次，先命中的原因生效。
 */
export function reclaim(
  state: TenancyState,
  tick: number,
  rule: BorrowRule = DEFAULT_BORROW,
  force = false,
): ReclaimEvent[] {
  const ordered: { loan: Loan; reason: ReclaimReason }[] = [];
  const used = new Set<string>();
  const due = state.loans
    .filter((loan) => tick >= loan.dueTick)
    .sort((left, right) => left.dueTick - right.dueTick || left.id.localeCompare(right.id));
  for (const loan of due) {
    ordered.push({ loan, reason: "due" });
    used.add(loan.id);
  }
  const peaked = state.loans
    .filter((loan) => !used.has(loan.id))
    .filter((loan) => {
      const lender = findBalance(state, loan.lenderId);
      return lender !== undefined && atLeastRatio(lender, rule.highPeakRatio * 100);
    })
    .sort((left, right) => left.lenderId.localeCompare(right.lenderId) || left.id.localeCompare(right.id));
  for (const loan of peaked) {
    ordered.push({ loan, reason: "high-peak" });
    used.add(loan.id);
  }
  if (force) {
    for (const loan of state.loans) {
      if (!used.has(loan.id)) ordered.push({ loan, reason: "forced" });
    }
  }
  const events: ReclaimEvent[] = [];
  for (const entry of ordered) {
    const loan = entry.loan;
    state.loans = state.loans.filter((item) => item.id !== loan.id);
    const borrower = findBalance(state, loan.borrowerId);
    const debtMicros = borrower === undefined
      ? 0
      : Math.max(0, borrower.usedMicros - borrower.shareMicros);
    events.push({
      loanId: loan.id, lenderId: loan.lenderId, borrowerId: loan.borrowerId,
      micros: loan.micros, reason: entry.reason, debtMicros,
    });
  }
  return events;
}

/** 缓存键必须含租户；这个函数是唯一允许拼缓存键的入口。 */
export function cacheKey(tenantId: string, capability: string, digest: string): string {
  return `t:${tenantId}:c:${capability}:${digest}`;
}

export interface IsolationSpec {
  tenantId: string;
  cacheKeyTemplate: string;
  vectorNamespace: string;
  objectPrefix: string;
  logSink: string;
  rateLimitBucket: string;
}

export type IsolationIssueCode =
  | "empty-tenant" | "cache-key-without-tenant" | "vector-namespace-without-tenant"
  | "object-prefix-without-tenant" | "shared-log-sink" | "shared-rate-bucket";

export interface IsolationIssue { tenantId: string; code: IsolationIssueCode; detail: string }

function requireTenant(
  issues: IsolationIssue[],
  tenantId: string,
  code: IsolationIssueCode,
  template: string,
): void {
  if (!template.includes("{tenant}")) issues.push({ tenantId, code, detail: template });
}

/** 隔离校验：模板必须含 {tenant}，日志与限流桶不得跨租户复用。 */
export function validateIsolation(specs: readonly IsolationSpec[]): IsolationIssue[] {
  const issues: IsolationIssue[] = [];
  const sinks = new Map<string, string[]>();
  const buckets = new Map<string, string[]>();
  for (const spec of specs) {
    if (spec.tenantId.trim() === "") {
      issues.push({ tenantId: spec.tenantId, code: "empty-tenant", detail: "tenant id is empty" });
    }
    requireTenant(issues, spec.tenantId, "cache-key-without-tenant", spec.cacheKeyTemplate);
    requireTenant(issues, spec.tenantId, "vector-namespace-without-tenant", spec.vectorNamespace);
    requireTenant(issues, spec.tenantId, "object-prefix-without-tenant", spec.objectPrefix);
    sinks.set(spec.logSink, [...(sinks.get(spec.logSink) ?? []), spec.tenantId]);
    buckets.set(spec.rateLimitBucket, [...(buckets.get(spec.rateLimitBucket) ?? []), spec.tenantId]);
  }
  for (const [sink, tenants] of sinks) {
    if (tenants.length > 1) {
      for (const tenantId of tenants) issues.push({ tenantId, code: "shared-log-sink", detail: sink });
    }
  }
  for (const [bucket, tenants] of buckets) {
    if (tenants.length > 1) {
      for (const tenantId of tenants) issues.push({ tenantId, code: "shared-rate-bucket", detail: bucket });
    }
  }
  return issues;
}