《移动游戏产品的架构·网络、资源与热更新》9.1 首包边界：什么必须进包

// file: src/resource/first-package.ts
// tier: L1
// verify: node --test test/resource/first-package.test.ts

export type AssetKind = "texture" | "audio" | "config" | "other";

export type Criticality = "boot" | "first-session" | "deferred";

export interface AssetEntry {
  readonly id: string;
  readonly kind: AssetKind;
  readonly bytes: number;
  readonly criticality: Criticality;
  readonly references: number;
  readonly hasFallback: boolean;
}

export interface RejectedAsset {
  readonly id: string;
  readonly kind: AssetKind;
  readonly bytes: number;
  readonly reason: "deferred" | "fallback" | "budget";
}

export interface KindBreakdown {
  readonly kind: AssetKind;
  readonly admittedCount: number;
  readonly admittedBytes: number;
  readonly rejectedCount: number;
  readonly rejectedBytes: number;
}

export interface AdmissionPlan {
  readonly admitted: readonly AssetEntry[];
  readonly rejected: readonly RejectedAsset[];
  readonly admittedBytes: number;
  readonly rejectedBytes: number;
  readonly budgetBytes: number;
  readonly remainingBytes: number;
  readonly overBudget: boolean;
  readonly byKind: readonly KindBreakdown[];
  readonly warnings: readonly string[];
}

export const MB = 1024 * 1024;

export const DEFAULT_FIRST_BUDGET = 120 * MB;

const KIND_ORDER: readonly AssetKind[] = ["texture", "audio", "config", "other"];

const CRITICALITY_RANK: Record<Criticality, number> = {
  boot: 0,
  "first-session": 1,
  deferred: 2,
};

function density(asset: AssetEntry): number {
  return asset.references / Math.max(asset.bytes, 1);
}

function validate(assets: readonly AssetEntry[]): void {
  const seen = new Set<string>();
  for (const asset of assets) {
    if (seen.has(asset.id)) throw new Error(`duplicate asset: ${asset.id}`);
    seen.add(asset.id);
    if (!Number.isInteger(asset.bytes) || asset.bytes < 0) {
      throw new Error(`invalid bytes for ${asset.id}: ${asset.bytes}`);
    }
    if (!Number.isInteger(asset.references) || asset.references < 0) {
      throw new Error(`invalid references for ${asset.id}: ${asset.references}`);
    }
  }
}

export function admitFirstPackage(
  assets: readonly AssetEntry[],
  options: { readonly budgetBytes?: number } = {},
): AdmissionPlan {
  const budget = options.budgetBytes ?? DEFAULT_FIRST_BUDGET;
  if (!Number.isInteger(budget) || budget < 0) {
    throw new Error(`invalid budget: ${budget}`);
  }
  validate(assets);

  const ordered = [...assets].sort((a, b) => {
    const rank = CRITICALITY_RANK[a.criticality] - CRITICALITY_RANK[b.criticality];
    if (rank !== 0) return rank;
    const spread = density(b) - density(a);
    if (spread !== 0) return spread;
    if (a.bytes !== b.bytes) return a.bytes - b.bytes;
    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
  });

  const admitted: AssetEntry[] = [];
  const rejected: RejectedAsset[] = [];
  const warnings: string[] = [];
  let admittedBytes = 0;
  let rejectedBytes = 0;

  for (const asset of ordered) {
    if (asset.criticality === "deferred") {
      rejected.push({
        id: asset.id,
        kind: asset.kind,
        bytes: asset.bytes,
        reason: "deferred",
      });
      rejectedBytes += asset.bytes;
      continue;
    }

    const fits = asset.bytes <= budget - admittedBytes;
    if (asset.criticality === "first-session" && !fits) {
      const reason = asset.hasFallback ? "fallback" : "budget";
      rejected.push({
        id: asset.id,
        kind: asset.kind,
        bytes: asset.bytes,
        reason,
      });
      rejectedBytes += asset.bytes;
      if (reason === "budget") {
        warnings.push(
          `${asset.id} (${asset.bytes}B) has no fallback and does not fit the budget`,
        );
      }
      continue;
    }

    admitted.push(asset);
    admittedBytes += asset.bytes;
  }

  const overBudget = admittedBytes > budget;
  if (overBudget) {
    warnings.push(
      `first package ${(admittedBytes / MB).toFixed(2)}MB exceeds budget ${(budget / MB).toFixed(2)}MB`,
    );
  }

  const byKind = KIND_ORDER.map((kind): KindBreakdown => {
    let admittedCount = 0;
    let admittedKindBytes = 0;
    for (const asset of admitted) {
      if (asset.kind !== kind) continue;
      admittedCount += 1;
      admittedKindBytes += asset.bytes;
    }
    let rejectedCount = 0;
    let rejectedKindBytes = 0;
    for (const item of rejected) {
      if (item.kind !== kind) continue;
      rejectedCount += 1;
      rejectedKindBytes += item.bytes;
    }
    return {
      kind,
      admittedCount,
      admittedBytes: admittedKindBytes,
      rejectedCount,
      rejectedBytes: rejectedKindBytes,
    };
  });

  return {
    admitted,
    rejected,
    admittedBytes,
    rejectedBytes,
    budgetBytes: budget,
    remainingBytes: Math.max(0, budget - admittedBytes),
    overBudget,
    byKind,
    warnings,
  };
}

export function formatAdmission(plan: AdmissionPlan): string {
  const lines = ["asset\tkind\tbytes\tdecision"];
  for (const asset of plan.admitted) {
    lines.push(`${asset.id}\t${asset.kind}\t${asset.bytes}\tadmit`);
  }
  for (const item of plan.rejected) {
    lines.push(`${item.id}\t${item.kind}\t${item.bytes}\treject:${item.reason}`);
  }
  for (const item of plan.byKind) {
    lines.push(
      `kind:${item.kind}\t${item.kind}\t${item.admittedBytes}B\tadmit=${item.admittedCount},reject=${item.rejectedCount}`,
    );
  }
  lines.push(
    `summary\tfirst\t${plan.admittedBytes}B\tbudget=${plan.budgetBytes}B,over=${plan.overBudget ? "yes" : "no"}`,
  );
  return lines.join("\n");
}

asset	kind	bytes	decision
boot-ui	texture	10	admit
boot-config	config	5	admit
tutorial	texture	40	admit
home-bg	texture	50	reject:fallback
voice-intro	audio	60	reject:deferred
kind:texture	texture	50B	admit=2,reject=1
kind:audio	audio	0B	admit=0,reject=1
kind:config	config	5B	admit=1,reject=0
kind:other	other	0B	admit=0,reject=0
summary	first	55B	budget=60B,over=no