《互联网产品的 AI 架构·模型接入与能力边界》9.2 失效、隐私与多租户隔离

// file: src/cache/invalidation.ts
// tier: L1
// verify: node --test test/cache/invalidation.test.ts

import type { CapabilityId, TenantId } from "../core/types.ts";
import type { CacheEntry, CacheScope, CacheWriteOptions, ResultCache } from "./cache.ts";

export type InvalidationReason =
  | "prompt-version"
  | "model-version"
  | "permission-change"
  | "user-deletion"
  | "tenant-purge"
  | "manual";

/** 作用域当前有效的版本组合，旧版本写入会被拒绝。 */
export interface ScopeEpoch {
  promptVersion: string;
  modelId: string;
  permissionScope: string;
}

export interface InvalidationReport {
  reason: InvalidationReason;
  removed: number;
  remaining: number;
  /** 只记录作用域标签，不记录键原文与缓存值。 */
  scopes: string[];
  at: number;
}

export interface InvalidatorOptions {
  now?: () => number;
}

function epochKey(tenantId: TenantId, capability: CapabilityId): string {
  return `${tenantId}\u0000${capability}`;
}

export class ScopeGuard {
  private epochs = new Map<string, ScopeEpoch>();

  seed(scope: CacheScope): ScopeEpoch {
    const key = epochKey(scope.tenantId, scope.capability);
    const existing = this.epochs.get(key);
    if (existing) {
      return existing;
    }
    const epoch: ScopeEpoch = {
      promptVersion: scope.promptVersion,
      modelId: scope.modelId,
      permissionScope: scope.permissionScope,
    };
    this.epochs.set(key, epoch);
    return epoch;
  }

  current(tenantId: TenantId, capability: CapabilityId): ScopeEpoch | undefined {
    return this.epochs.get(epochKey(tenantId, capability));
  }

  /** 没有登记过的作用域放行，登记过则三项必须完全一致。 */
  admit(scope: CacheScope): boolean {
    const epoch = this.current(scope.tenantId, scope.capability);
    if (!epoch) {
      return true;
    }
    return (
      epoch.promptVersion === scope.promptVersion &&
      epoch.modelId === scope.modelId &&
      epoch.permissionScope === scope.permissionScope
    );
  }

  advance(scope: CacheScope, patch: Partial<ScopeEpoch>): ScopeEpoch {
    const next: ScopeEpoch = { ...this.seed(scope), ...patch };
    this.epochs.set(epochKey(scope.tenantId, scope.capability), next);
    return next;
  }
}

export class CacheInvalidator<T> {
  private cache: ResultCache<T>;
  private guard: ScopeGuard;
  private now: () => number;
  private reports: InvalidationReport[] = [];
  /** 删除过的用户不能通过迟到的请求把数据写回缓存。 */
  private deletedUsers = new Map<TenantId, Set<string>>();

  constructor(cache: ResultCache<T>, options: InvalidatorOptions = {}) {
    this.cache = cache;
    this.guard = new ScopeGuard();
    this.now = options.now ?? (() => Date.now());
  }

  write(
    scope: CacheScope,
    input: string,
    value: T,
    options: CacheWriteOptions = {},
  ): CacheEntry<T> | undefined {
    if (!this.guard.admit(scope)) {
      return undefined;
    }
    const deleted = this.deletedUsers.get(scope.tenantId);
    if (deleted && (options.subjectIds ?? []).some((id) => deleted.has(id))) {
      return undefined;
    }
    return this.cache.set(scope, input, value, options);
  }

  /** 提示换版：同一租户同一能力下，旧提示版本的结果全部作废。 */
  invalidatePrompt(scope: CacheScope, nextPromptVersion: string): InvalidationReport {
    this.guard.advance(scope, { promptVersion: nextPromptVersion });
    return this.purge(
      (entry) =>
        entry.scope.tenantId === scope.tenantId &&
        entry.scope.capability === scope.capability &&
        entry.scope.promptVersion !== nextPromptVersion,
      "prompt-version",
    );
  }

  /** 换模型：只作废该能力的结果，不牵连其他能力。 */
  invalidateModel(scope: CacheScope, nextModelId: string): InvalidationReport {
    this.guard.advance(scope, { modelId: nextModelId });
    return this.purge(
      (entry) =>
        entry.scope.tenantId === scope.tenantId &&
        entry.scope.capability === scope.capability &&
        entry.scope.modelId !== nextModelId,
      "model-version",
    );
  }

  /** 权限边界调整后，该能力的全部分区都要重算，不能只换一个标签。 */
  invalidatePermission(scope: CacheScope, nextPermissionScope: string): InvalidationReport {
    this.guard.advance(scope, { permissionScope: nextPermissionScope });
    return this.purge(
      (entry) =>
        entry.scope.tenantId === scope.tenantId &&
        entry.scope.capability === scope.capability,
      "permission-change",
    );
  }

  /** 用户删除权：按结果里出现过的 subjectIds 传播，跨能力生效。 */
  invalidateUser(tenantId: TenantId, userId: string): InvalidationReport {
    let deleted = this.deletedUsers.get(tenantId);
    if (!deleted) {
      deleted = new Set();
      this.deletedUsers.set(tenantId, deleted);
    }
    deleted.add(userId);
    return this.purge(
      (entry) => entry.scope.tenantId === tenantId && entry.subjectIds.includes(userId),
      "user-deletion",
    );
  }

  invalidateTenant(tenantId: TenantId): InvalidationReport {
    return this.purge((entry) => entry.scope.tenantId === tenantId, "tenant-purge");
  }

  invalidateCapability(tenantId: TenantId, capability: CapabilityId): InvalidationReport {
    return this.purge(
      (entry) =>
        entry.scope.tenantId === tenantId && entry.scope.capability === capability,
      "manual",
    );
  }

  history(): InvalidationReport[] {
    return [...this.reports];
  }

  private purge(
    predicate: (entry: CacheEntry<T>) => boolean,
    reason: InvalidationReason,
  ): InvalidationReport {
    const matched = this.cache.list().filter(predicate);
    for (const entry of matched) {
      this.cache.remove(entry.key);
    }
    const scopes = [
      ...new Set(matched.map((entry) => `${entry.scope.tenantId}/${entry.scope.capability}`)),
    ];
    const report: InvalidationReport = {
      reason,
      removed: matched.length,
      remaining: this.cache.size,
      scopes,
      at: this.now(),
    };
    this.reports.push(report);
    return report;
  }
}