@cs2dak/core 0.2.1 → 2.0.0

package/src/spatial/index.ts

@@ -0,0 +1,16 @@
+/**
+ * 空间分析（严格重建）。两层：raw evidence（宽，复盘/shadow） → official gated（窄，进 RR）。
+ * 设计与边界见 docs/design/rr-model.md §3。
+ *
+ * SP1（已落地）：RoundPhase 模型 + 位置标注地基。
+ * SP2/SP3（计划）：official MapControl / UtilitySpatial gates + strategicIsolationDeathCredits。
+ */
+export type { RoundPhase, RoundPhaseModel } from "./types.js";
+export { OFFICIAL_EXCLUDED_PHASES, isOfficialScoringPhase } from "./types.js";
+export { inferRoundPhases, phaseAtTick } from "./phase.js";
+export type { SpatialAssets, AnnotatedSample } from "./annotate.js";
+export { loadSpatialAssets, annotatePositions, groupSamplesByRoundTick } from "./annotate.js";
+export type { OfficialMapControl } from "./mapcontrol.js";
+export { buildOfficialMapControl } from "./mapcontrol.js";
+export type { OfficialUtilitySpatial, UtilityWindow, GrenadeType } from "./utility.js";
+export { buildOfficialUtilitySpatial, buildUtilityWindows } from "./utility.js";

package/src/spatial/mapcontrol.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it } from "vitest";
+import type { DemoPackage, Replay } from "@cs2dak/contract";
+import { loadSpatialAssets } from "./annotate.js";
+import { buildOfficialMapControl } from "./mapcontrol.js";
+
+function deltaArr(values: number[]): number[] {
+  const out: number[] = [];
+  let prev = 0;
+  for (const v of values) { out.push(v - prev); prev = v; }
+  return out;
+}
+
+function replayTracks(t1Places: string[], idxByPlace: Map<string, number>) {
+  return [
+    {
+      playerIndex: 0,
+      x: deltaArr([0, 0, 0, 0]), y: deltaArr([0, 0, 0, 0]), z: deltaArr([0, 0, 0, 0]),
+      yaw: deltaArr([0, 0, 0, 0]), pitch: deltaArr([0, 0, 0, 0]),
+      hp: [100, 100, 100, 100], armor: [100, 100, 100, 100],
+      money: [800, 800, 800, 800], equipValue: [800, 800, 800, 800],
+      weapon: [-1, -1, -1, -1],
+      place: t1Places.map((p) => idxByPlace.get(p) ?? -1),
+      flash: [0, 0, 0, 0], flags: [1, 1, 1, 1],
+    },
+    {
+      playerIndex: 1,
+      x: deltaArr([0, 0, 0, 0]), y: deltaArr([0, 0, 0, 0]), z: deltaArr([0, 0, 0, 0]),
+      yaw: deltaArr([0, 0, 0, 0]), pitch: deltaArr([0, 0, 0, 0]),
+      hp: [100, 100, 100, 100], armor: [100, 100, 100, 100],
+      money: [800, 800, 800, 800], equipValue: [800, 800, 800, 800],
+      weapon: [-1, -1, -1, -1],
+      place: [idxByPlace.get("TSpawn")!, idxByPlace.get("TSpawn")!, idxByPlace.get("TSpawn")!, idxByPlace.get("TSpawn")!],
+      flash: [0, 0, 0, 0], flags: [1, 1, 1, 1],
+    },
+    {
+      playerIndex: 2,
+      x: deltaArr([0, 0, 0, 0]), y: deltaArr([0, 0, 0, 0]), z: deltaArr([0, 0, 0, 0]),
+      yaw: deltaArr([0, 0, 0, 0]), pitch: deltaArr([0, 0, 0, 0]),
+      hp: [100, 100, 100, 100], armor: [100, 100, 100, 100],
+      money: [800, 800, 800, 800], equipValue: [800, 800, 800, 800],
+      weapon: [-1, -1, -1, -1],
+      place: [idxByPlace.get("BombsiteA")!, idxByPlace.get("BombsiteA")!, idxByPlace.get("BombsiteA")!, idxByPlace.get("BombsiteA")!],
+      flash: [0, 0, 0, 0], flags: [1, 1, 1, 1],
+    },
+    {
+      playerIndex: 3,
+      x: deltaArr([0, 0, 0, 0]), y: deltaArr([0, 0, 0, 0]), z: deltaArr([0, 0, 0, 0]),
+      yaw: deltaArr([0, 0, 0, 0]), pitch: deltaArr([0, 0, 0, 0]),
+      hp: [100, 100, 100, 100], armor: [100, 100, 100, 100],
+      money: [800, 800, 800, 800], equipValue: [800, 800, 800, 800],
+      weapon: [-1, -1, -1, -1],
+      place: [idxByPlace.get("CTSpawn")!, idxByPlace.get("CTSpawn")!, idxByPlace.get("CTSpawn")!, idxByPlace.get("CTSpawn")!],
+      flash: [0, 0, 0, 0], flags: [1, 1, 1, 1],
+    },
+  ];
+}
+
+/** T1 独推 a_long（LongDoors→ARamp），T2 留 TSpawn，C1 守 BombsiteA（同线施压），C2 离线。 */
+function makePkg(over: { kills?: unknown[] } = {}): DemoPackage {
+  const t1 = ["LongDoors", "LongA", "ARamp", "ARamp"];
+  const allPlaces = [...new Set([...t1, "TSpawn", "BombsiteA", "CTSpawn"])];
+  const idxByPlace = new Map(allPlaces.map((p, i) => [p, i]));
+  return {
+    match: { mapName: "de_dust2", tickrate: 64 },
+    players: [
+      { steamId64: "T1", teamKey: "teamA" },
+      { steamId64: "T2", teamKey: "teamA" },
+      { steamId64: "C1", teamKey: "teamB" },
+      { steamId64: "C2", teamKey: "teamB" },
+    ],
+    rounds: [{ roundNumber: 1, startTick: 1, freezeEndTick: 100, endTick: 2000, teamASide: "t", teamBSide: "ct" }],
+    bombs: [],
+    kills: over.kills ?? [],
+    replay: {
+      meta: { sampleRate: 1, tickrate: 64, coordScale: 1, angleScale: 10 },
+      weaponDict: [],
+      placeDict: allPlaces,
+      rounds: [{
+        roundNumber: 1,
+        startTick: 150,
+        tickStep: 64,
+        frameCount: 4,
+        players: replayTracks(t1, idxByPlace) as unknown as Replay["rounds"][number]["players"],
+        projectiles: [],
+      }],
+    },
+  } as unknown as DemoPackage;
+}
+
+const untradedDeath = [{ roundNumber: 1, tick: 410, killerIndex: 2, victimIndex: 0, victimSteamId64: "T1", victimTeamKey: "teamA", killerSteamId64: "C1", killerTeamKey: "teamB", tradeDeath: false, weapon: "ak47", headshot: false }];
+
+describe("buildOfficialMapControl", () => {
+  it("accumulates activeSoloPressureSeconds for a lone route pusher with enemy on the lane", () => {
+    const mc = buildOfficialMapControl(makePkg(), loadSpatialAssets("de_dust2"));
+    expect(mc.get("T1")!.activeSoloPressureSeconds).toBe(4); // 4 个 1Hz 样本
+    expect(mc.get("T2")?.activeSoloPressureSeconds ?? 0).toBe(0); // 始终在 TSpawn，未上线
+  });
+
+  it("accumulates denial for the defending anchor and firstControl for the pusher", () => {
+    const mc = buildOfficialMapControl(makePkg(), loadSpatialAssets("de_dust2"));
+    // C1 守 BombsiteA（a_long 末端）、T1 同线施压、无 plant → CT 防守 → C1 计 denial
+    expect(mc.get("C1")!.sidePhaseAwareDenialSeconds).toBeGreaterThan(0);
+    // T1 推进到 a_long 关键段（LongA idx3 ≥ ceil(6×0.4)=3）→ firstControl 一次
+    expect(mc.get("T1")!.firstMeaningfulControlEvents).toBe(1);
+    // T1 是进攻方，非防守 → 无 denial
+    expect(mc.get("T1")!.sidePhaseAwareDenialSeconds).toBe(0);
+  });
+
+  it("awards strategicIsolationDeaths credit for an untraded death after sustained solo pressure", () => {
+    const mc = buildOfficialMapControl(makePkg({ kills: untradedDeath }), loadSpatialAssets("de_dust2"));
+    // credit = clamp(0.25 + 0.10×4, 0, 1) = 0.65
+    expect(mc.get("T1")!.strategicIsolationDeaths).toBeCloseTo(0.65, 3);
+  });
+
+  it("gives no credit when the death was traded", () => {
+    const traded = [{ ...untradedDeath[0], tradeDeath: true }];
+    const mc = buildOfficialMapControl(makePkg({ kills: traded }), loadSpatialAssets("de_dust2"));
+    expect(mc.get("T1")?.strategicIsolationDeaths ?? 0).toBe(0);
+  });
+
+  it("gives no credit when there was no prior solo pressure (TSpawn camper)", () => {
+    const death = [{ roundNumber: 1, tick: 410, killerIndex: 2, victimIndex: 1, victimSteamId64: "T2", victimTeamKey: "teamA", killerSteamId64: "C1", killerTeamKey: "teamB", tradeDeath: false, weapon: "ak47", headshot: false }];
+    const mc = buildOfficialMapControl(makePkg({ kills: death }), loadSpatialAssets("de_dust2"));
+    expect(mc.get("T2")?.strategicIsolationDeaths ?? 0).toBe(0);
+  });
+
+  it("returns an empty map without route assets", () => {
+    const mc = buildOfficialMapControl(makePkg(), loadSpatialAssets("de_unknown"));
+    expect(mc.size).toBe(0);
+  });
+});

package/src/spatial/mapcontrol.ts

@@ -0,0 +1,277 @@
+/**
+ * Official MapControl 派生（严格重建 SP2）。设计见 docs/design/rr-model.md §3.2/§3.3。
+ *
+ * 已落地 official 指标（callout/index-based MVP gates，输入 positions+routes+kills+phase）：
+ * - activeSoloPressureSeconds   独占某动线 + 同线敌方施压 + official phase（cap 8s/round）
+ * - sidePhaseAwareDenialSeconds 防守方在敌方施压的动线上 holding × phaseFactor（cap 10s/round）
+ * - firstMeaningfulControlEvents T 首次推进到动线关键段（neutral/key index），每回合每动线一次
+ * - strategicIsolationDeaths    未交易死亡 × 死前窗口内 solo/denial/firstControl → 0~1 credit
+ *
+ * 这些 official 指标当前进 review/shadow 与 Trade 闭环（strategicIsolationDeaths），
+ * **不进 RR MapControl 评分账户**——后者需 rival-rating schema V2 + 权重（跨仓库 SP4）。
+ * 仍缺：denial 的 LOS/nav 距离精修、nonUtilityAssistedAdvanceUnits、UtilitySpatial
+ * actual-effect（需 zone 多边形标定）。
+ */
+import type { DemoPackage } from "@cs2dak/contract";
+import { routeIndex, type MapRoute, type MapRoutes } from "@cs2dak/maps";
+import { createResolverFromPackage, type PlayerResolver } from "../resolve.js";
+import { clamp, groupBy } from "../utils.js";
+import { annotatePositions, type SpatialAssets, type AnnotatedSample } from "./annotate.js";
+import { inferRoundPhases, phaseAtTick } from "./phase.js";
+import { isOfficialScoringPhase, type RoundPhase, type RoundPhaseModel } from "./types.js";
+
+export interface OfficialMapControl {
+  activeSoloPressureSeconds: number;
+  sidePhaseAwareDenialSeconds: number;
+  firstMeaningfulControlEvents: number;
+  strategicIsolationDeaths: number;
+}
+
+// —— gate 常数（doc §6/§8/§10/§22）——
+const SOLO_PRESSURE_PER_ROUND_CAP = 8; // 秒
+const DENIAL_PER_ROUND_CAP = 10; // 秒（已乘 phaseFactor）
+const ISOLATION_WINDOW_SECONDS = 8; // 死前回看窗口 W
+const ISOLATION_MIN_TRIGGER_SECONDS = 3; // 触发阈值 S
+const DEFAULT_SAMPLE_RATE = 1; // 无 replay 时降级为 1Hz
+
+type Team = string;
+
+interface RoundEvidence {
+  /** tick → solo-pressure 玩家集合。 */
+  soloByTick: Map<number, Set<string>>;
+  /** tick → denial 玩家集合（用于 isolation 触发，未加权）。 */
+  denialByTick: Map<number, Set<string>>;
+}
+
+export function buildOfficialMapControl(
+  pkg: DemoPackage,
+  assets: SpatialAssets,
+  phases?: Map<number, RoundPhaseModel>,
+): Map<string, OfficialMapControl> {
+  const out = new Map<string, OfficialMapControl>();
+  if (!assets.routes) return out; // callout-based，需要动线资产
+  const routes = assets.routes;
+  const resolver = createResolverFromPackage(pkg);
+  const samples = annotatePositions(pkg, assets);
+  if (samples.length === 0) return out;
+  const sampleRate = pkg.replay?.meta.sampleRate ?? DEFAULT_SAMPLE_RATE;
+  const SAMPLE_SECONDS = 1 / sampleRate;
+  const phaseModels = phases ?? inferRoundPhases(pkg);
+  const teamByPlayer = new Map(pkg.players.map((p) => [p.steamId64, p.teamKey]));
+  const sideByTeam = new Map<number, { defendPre: Team | null; t: Team | null; ct: Team | null }>();
+  for (const round of pkg.rounds) {
+    const t = round.teamASide === "t" ? "teamA" : round.teamBSide === "t" ? "teamB" : null;
+    const ct = round.teamASide === "ct" ? "teamA" : round.teamBSide === "ct" ? "teamB" : null;
+    sideByTeam.set(round.roundNumber, { defendPre: ct, t, ct });
+  }
+  const plantByRound = plantTicks(pkg);
+
+  const pressureSeconds = new Map<string, number>();
+  const denialSeconds = new Map<string, number>();
+  const firstControlEvents = new Map<string, number>();
+  const evidenceByRound = new Map<number, RoundEvidence>();
+
+  const byRound = groupBy(samples, (s) => s.roundNumber);
+  for (const [roundNumber, rows] of byRound) {
+    const phase = phaseModels.get(roundNumber);
+    const sides = sideByTeam.get(roundNumber) ?? { defendPre: null, t: null, ct: null };
+    const plantTick = plantByRound.get(roundNumber) ?? null;
+    const evidence: RoundEvidence = { soloByTick: new Map(), denialByTick: new Map() };
+
+    const perRoundSolo = new Map<string, number>();
+    const perRoundDenial = new Map<string, number>();
+    const takenRoutes = new Set<string>(); // firstControl 去重：每回合每动线一次
+
+    for (const [tick, tickRows] of groupBy(rows, (r) => r.tick)) {
+      const ph: RoundPhase = phase ? phaseAtTick(phase, tick) : "default";
+      if (!isOfficialScoringPhase(ph)) continue;
+      const presence = routePresence(tickRows, routes, teamByPlayer);
+      const defenderTeam = plantTick != null && tick >= plantTick ? sides.t : sides.ct;
+
+      const solo = new Set<string>();
+      const denial = new Set<string>();
+      for (const [route, byTeam] of presence) {
+        deriveSoloAndDenial(byTeam, defenderTeam, ph, solo, denial, perRoundSolo, perRoundDenial, SAMPLE_SECONDS);
+        // firstMeaningfulControlEvents：T 首次到达关键段（neutral/key index）
+        recordFirstControl(route, byTeam, sides.t, takenRoutes, firstControlEvents, ph);
+      }
+      if (solo.size) evidence.soloByTick.set(tick, solo);
+      if (denial.size) evidence.denialByTick.set(tick, denial);
+    }
+
+    for (const [id, secs] of perRoundSolo) {
+      pressureSeconds.set(id, (pressureSeconds.get(id) ?? 0) + Math.min(secs, SOLO_PRESSURE_PER_ROUND_CAP));
+    }
+    for (const [id, secs] of perRoundDenial) {
+      denialSeconds.set(id, (denialSeconds.get(id) ?? 0) + Math.min(secs, DENIAL_PER_ROUND_CAP));
+    }
+    evidenceByRound.set(roundNumber, evidence);
+  }
+
+  const credits = buildIsolationCredits(pkg, evidenceByRound, phaseModels, SAMPLE_SECONDS, resolver);
+
+  const ids = new Set<string>([
+    ...pressureSeconds.keys(),
+    ...denialSeconds.keys(),
+    ...firstControlEvents.keys(),
+    ...credits.keys(),
+  ]);
+  for (const id of ids) {
+    out.set(id, {
+      activeSoloPressureSeconds: round3(pressureSeconds.get(id) ?? 0),
+      sidePhaseAwareDenialSeconds: round3(denialSeconds.get(id) ?? 0),
+      firstMeaningfulControlEvents: firstControlEvents.get(id) ?? 0,
+      strategicIsolationDeaths: round3(credits.get(id) ?? 0),
+    });
+  }
+  return out;
+}
+
+/** 每动线 → 每队在线（routeIndex≥1）成员。 */
+function routePresence(
+  tickRows: AnnotatedSample[],
+  routes: MapRoutes,
+  teamByPlayer: Map<string, string>,
+): Map<MapRoute, Map<Team, { id: string; index: number }[]>> {
+  const out = new Map<MapRoute, Map<Team, { id: string; index: number }[]>>();
+  for (const route of routes.routes) {
+    const byTeam = new Map<Team, { id: string; index: number }[]>();
+    for (const row of tickRows) {
+      if (!row.alive) continue;
+      const idx = routeIndex(route, row.callout);
+      if (idx < 1) continue;
+      const team = teamByPlayer.get(row.steamId64) ?? row.teamKey;
+      const arr = byTeam.get(team) ?? [];
+      arr.push({ id: row.steamId64, index: idx });
+      byTeam.set(team, arr);
+    }
+    if (byTeam.size > 0) out.set(route, byTeam);
+  }
+  return out;
+}
+
+function deriveSoloAndDenial(
+  byTeam: Map<Team, { id: string; index: number }[]>,
+  defenderTeam: Team | null,
+  phase: RoundPhase,
+  solo: Set<string>,
+  denial: Set<string>,
+  perRoundSolo: Map<string, number>,
+  perRoundDenial: Map<string, number>,
+  sampleSecs: number,
+): void {
+  if (byTeam.size < 2) return; // 需双方都在该线（敌方施压）
+  for (const [team, members] of byTeam) {
+    const enemyPresent = [...byTeam].some(([t, m]) => t !== team && m.length >= 1);
+    if (!enemyPresent) continue;
+    // solo：本队仅此一人在该线
+    if (members.length === 1 && !solo.has(members[0]!.id)) {
+      solo.add(members[0]!.id);
+      perRoundSolo.set(members[0]!.id, (perRoundSolo.get(members[0]!.id) ?? 0) + sampleSecs);
+    }
+    // denial：防守方在敌方施压的动线上 holding（× phaseFactor）
+    if (defenderTeam != null && team === defenderTeam) {
+      const factor = phaseFactor(phase);
+      if (factor > 0) {
+        for (const m of members) {
+          if (denial.has(m.id)) continue;
+          denial.add(m.id);
+          perRoundDenial.set(m.id, (perRoundDenial.get(m.id) ?? 0) + sampleSecs * factor);
+        }
+      }
+    }
+  }
+}
+
+/** T 首次推进到动线关键段：index ≥ max(1, ceil(len×0.4))，每回合每动线记一次，归 frontier T。 */
+function recordFirstControl(
+  route: MapRoute,
+  byTeam: Map<Team, { id: string; index: number }[]>,
+  tTeam: Team | null,
+  taken: Set<string>,
+  firstControlEvents: Map<string, number>,
+  phase: RoundPhase,
+): void {
+  if (tTeam == null || taken.has(route.id)) return;
+  if (phase !== "default" && phase !== "take" && phase !== "execute") return;
+  const tMembers = byTeam.get(tTeam);
+  if (!tMembers) return;
+  const threshold = Math.max(1, Math.ceil(route.zones.length * 0.4));
+  const frontier = tMembers.filter((m) => m.index >= threshold).sort((a, b) => b.index - a.index)[0];
+  if (!frontier) return;
+  taken.add(route.id);
+  firstControlEvents.set(frontier.id, (firstControlEvents.get(frontier.id) ?? 0) + 1);
+}
+
+function buildIsolationCredits(
+  pkg: DemoPackage,
+  evidenceByRound: Map<number, RoundEvidence>,
+  phases: Map<number, RoundPhaseModel>,
+  sampleSecs: number,
+  resolver: PlayerResolver,
+): Map<string, number> {
+  const tickrate = pkg.match?.tickrate ?? pkg.manifest?.tickrate ?? 64;
+  const windowTicks = ISOLATION_WINDOW_SECONDS * tickrate;
+  const credits = new Map<string, number>();
+
+  for (const kill of pkg.kills) {
+    const killerPlayer = resolver.byIndexOrNull(kill.killerIndex);
+    const victimPlayer = resolver.byIndexOrNull(kill.victimIndex);
+    if (!victimPlayer) continue;
+    if (killerPlayer && killerPlayer.teamKey === victimPlayer.teamKey) continue;
+    if ((kill as { tradeDeath?: boolean }).tradeDeath) continue;
+    const victim = victimPlayer.steamId64;
+    if (!victim) continue;
+    const phase = phases.get(kill.roundNumber);
+    if (phase && !isOfficialScoringPhase(phaseAtTick(phase, kill.tick))) continue;
+    const evidence = evidenceByRound.get(kill.roundNumber);
+    if (!evidence) continue;
+
+    const lo = kill.tick - windowTicks;
+    const pressure = secondsInWindow(evidence.soloByTick, victim, lo, kill.tick, sampleSecs);
+    const denial = secondsInWindow(evidence.denialByTick, victim, lo, kill.tick, sampleSecs);
+    if (pressure < ISOLATION_MIN_TRIGGER_SECONDS && denial < ISOLATION_MIN_TRIGGER_SECONDS) continue;
+
+    // credit = clamp(0.25 + 0.10×pressure + 0.10×denial, 0, 1)（doc §10.3 子集）
+    const credit = clamp(0.25 + 0.1 * pressure + 0.1 * denial, 0, 1);
+    credits.set(victim, (credits.get(victim) ?? 0) + credit);
+  }
+  return credits;
+}
+
+function secondsInWindow(byTick: Map<number, Set<string>>, id: string, lo: number, hi: number, sampleSecs: number): number {
+  let secs = 0;
+  for (const [tick, set] of byTick) {
+    if (tick > hi || tick < lo) continue;
+    if (set.has(id)) secs += sampleSecs;
+  }
+  return secs;
+}
+
+function phaseFactor(phase: RoundPhase): number {
+  switch (phase) {
+    case "execute":
+    case "postPlant":
+    case "retake":
+    case "clutch":
+      return 1.2;
+    case "take":
+      return 1.0;
+    case "default":
+      return 0.5;
+    default:
+      return 0;
+  }
+}
+
+function plantTicks(pkg: DemoPackage): Map<number, number> {
+  const out = new Map<number, number>();
+  for (const bomb of pkg.bombs) {
+    if (bomb.type === "planted" && !out.has(bomb.roundNumber)) out.set(bomb.roundNumber, bomb.tick);
+  }
+  return out;
+}
+
+function round3(v: number): number {
+  return Math.round(v * 1000) / 1000;
+}

package/src/spatial/phase.test.ts

@@ -0,0 +1,171 @@
+import { describe, expect, it } from "vitest";
+import type { DemoPackage, Replay } from "@cs2dak/contract";
+import { inferRoundPhases, phaseAtTick } from "./phase.js";
+import { isOfficialScoringPhase, OFFICIAL_EXCLUDED_PHASES } from "./types.js";
+
+function deltaArr(values: number[]): number[] {
+  const out: number[] = [];
+  let prev = 0;
+  for (const v of values) { out.push(v - prev); prev = v; }
+  return out;
+}
+
+/** Build a single-frame replay round with the given player tracks. */
+function replayFrame(
+  roundNumber: number,
+  tick: number,
+  tracks: { playerIdx: number; placeIdx: number }[],
+): Replay["rounds"][number] {
+  return {
+    roundNumber,
+    startTick: tick,
+    tickStep: 1,
+    frameCount: 1,
+    players: tracks.map((t) => ({
+      playerIndex: t.playerIdx,
+      x: deltaArr([0]), y: deltaArr([0]), z: deltaArr([0]),
+      yaw: deltaArr([0]), pitch: deltaArr([0]),
+      hp: [100], armor: [100], money: [800], equipValue: [800],
+      place: [t.placeIdx], flash: [0], flags: [1], weapon: [-1], grenades: [[]],
+    })),
+    projectiles: [],
+  };
+}
+
+/** Build a two-frame replay round for take+execute detection at different ticks. */
+function replayTwoFrames(
+  roundNumber: number,
+  frame1: { tick: number; tracks: { playerIdx: number; placeIdx: number }[] },
+  frame2: { tick: number; tracks: { playerIdx: number; placeIdx: number }[] },
+): Replay["rounds"][number] {
+  const tickStep = frame2.tick - frame1.tick;
+  const nPlayers = Math.max(frame1.tracks.length, frame2.tracks.length);
+  const players = [];
+  for (let i = 0; i < nPlayers; i++) {
+    const t1 = frame1.tracks.find((t) => t.playerIdx === i);
+    const t2 = frame2.tracks.find((t) => t.playerIdx === i);
+    const place1 = t1?.placeIdx ?? -1;
+    const place2 = t2?.placeIdx ?? -1;
+    players.push({
+      playerIndex: i,
+      x: deltaArr([0, 0]), y: deltaArr([0, 0]), z: deltaArr([0, 0]),
+      yaw: deltaArr([0, 0]), pitch: deltaArr([0, 0]),
+      hp: [100, 100], armor: [100, 100], money: [800, 800], equipValue: [800, 800],
+      place: [place1, place2], flash: [0, 0], flags: [1, 1], weapon: [-1, -1], grenades: [[], []],
+    });
+  }
+  return { roundNumber, startTick: frame1.tick, tickStep, frameCount: 2, players, projectiles: [] };
+}
+
+/** 最小 DemoPackage：phase 推导只读 match/players/rounds/bombs/kills。 */
+function makePkg(over: Partial<{
+  bombs: unknown[];
+  kills: unknown[];
+  replay: unknown;
+}> = {}): DemoPackage {
+  return {
+    match: { mapName: "de_dust2", tickrate: 64 },
+    players: [
+      { steamId64: "T1", teamKey: "teamA" },
+      { steamId64: "T2", teamKey: "teamA" },
+      { steamId64: "C1", teamKey: "teamB" },
+      { steamId64: "C2", teamKey: "teamB" },
+    ],
+    rounds: [
+      { roundNumber: 1, startTick: 1, freezeEndTick: 100, endTick: 1000, teamASide: "t", teamBSide: "ct" },
+    ],
+    bombs: over.bombs ?? [],
+    kills: over.kills ?? [],
+    replay: over.replay,
+  } as unknown as DemoPackage;
+}
+
+describe("inferRoundPhases / phaseAtTick", () => {
+  it("marks the freeze window then default", () => {
+    const m = inferRoundPhases(makePkg()).get(1)!;
+    expect(phaseAtTick(m, 1)).toBe("freeze");
+    expect(phaseAtTick(m, 99)).toBe("freeze");
+    expect(phaseAtTick(m, 100)).toBe("default");
+    expect(phaseAtTick(m, 500)).toBe("default");
+  });
+
+  it("enters postPlant from the plant tick", () => {
+    const m = inferRoundPhases(makePkg({
+      bombs: [{ roundNumber: 1, tick: 300, type: "planted", actorTeamKey: "teamA" }],
+    })).get(1)!;
+    expect(m.plantTick).toBe(300);
+    expect(phaseAtTick(m, 299)).not.toBe("postPlant");
+    expect(phaseAtTick(m, 300)).toBe("postPlant");
+    expect(phaseAtTick(m, 800)).toBe("postPlant");
+  });
+
+  it("enters clutch when a side drops to one alive", () => {
+    // teamB starts at 2; one kill on teamB → 1 alive → clutch
+    const m = inferRoundPhases(makePkg({
+      kills: [{ roundNumber: 1, tick: 250, victimTeamKey: "teamB", victimIndex: 2, killerIndex: 0, weapon: "ak47", headshot: false }],
+    })).get(1)!;
+    expect(m.clutchStartTick).toBe(250);
+    expect(phaseAtTick(m, 249)).toBe("default");
+    expect(phaseAtTick(m, 250)).toBe("clutch");
+  });
+
+  it("clutch overrides postPlant in the same window", () => {
+    const m = inferRoundPhases(makePkg({
+      bombs: [{ roundNumber: 1, tick: 300, type: "planted", actorTeamKey: "teamA" }],
+      kills: [{ roundNumber: 1, tick: 350, victimTeamKey: "teamA", victimIndex: 0, killerIndex: 2, weapon: "ak47", headshot: false }],
+    })).get(1)!;
+    expect(phaseAtTick(m, 320)).toBe("postPlant");
+    expect(phaseAtTick(m, 360)).toBe("clutch");
+  });
+
+  it("detects take when a T advances beyond spawn (routeIndex >= 1)", () => {
+    const placeDict = ["TSpawn", "OutsideLong"];
+    const replay = {
+      meta: { sampleRate: 1, tickrate: 64, coordScale: 1, angleScale: 10 },
+      weaponDict: [], placeDict,
+      rounds: [replayFrame(1, 150, [
+        { playerIdx: 0, placeIdx: 1 }, // T1 → OutsideLong
+        { playerIdx: 1, placeIdx: 0 }, // T2 → TSpawn
+      ])],
+    };
+    const m = inferRoundPhases(makePkg({ replay })).get(1)!;
+    expect(m.hasPositions).toBe(true);
+    expect(m.hasRoutes).toBe(true);
+    expect(m.takeTick).toBe(150);
+    expect(phaseAtTick(m, 150)).toBe("take");
+  });
+
+  it("detects execute when two T near the site entry (routeIndex >= len-2)", () => {
+    // a_long: ARamp=4, BombsiteA=5 → both >= len-2 (=4)
+    const placeDict = ["TSpawn", "OutsideLong", "ARamp", "BombsiteA"];
+    const replay = {
+      meta: { sampleRate: 1, tickrate: 64, coordScale: 1, angleScale: 10 },
+      weaponDict: [], placeDict,
+      rounds: [replayTwoFrames(1,
+        { tick: 140, tracks: [{ playerIdx: 0, placeIdx: 1 }] },   // T1 → OutsideLong
+        { tick: 260, tracks: [{ playerIdx: 0, placeIdx: 2 }, { playerIdx: 1, placeIdx: 3 }] }, // T1→ARamp, T2→BombsiteA
+      )],
+    };
+    const m = inferRoundPhases(makePkg({ replay })).get(1)!;
+    expect(m.takeTick).toBe(140);
+    expect(m.executeTick).toBe(260);
+    expect(phaseAtTick(m, 200)).toBe("take");
+    expect(phaseAtTick(m, 260)).toBe("execute");
+  });
+
+  it("degrades take/execute to null without positions", () => {
+    const m = inferRoundPhases(makePkg()).get(1)!;
+    expect(m.hasPositions).toBe(false);
+    expect(m.takeTick).toBeNull();
+    expect(m.executeTick).toBeNull();
+  });
+
+  it("excludes freeze/save/exit from official scoring", () => {
+    expect(isOfficialScoringPhase("freeze")).toBe(false);
+    expect(isOfficialScoringPhase("save")).toBe(false);
+    expect(isOfficialScoringPhase("exit")).toBe(false);
+    expect(isOfficialScoringPhase("take")).toBe(true);
+    expect(isOfficialScoringPhase("postPlant")).toBe(true);
+    expect(OFFICIAL_EXCLUDED_PHASES.has("clutch")).toBe(false);
+  });
+});