@cs2dak/core 1.0.0 → 2.0.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);
+  });
+});

package/src/spatial/phase.ts

@@ -0,0 +1,179 @@
+/**
+ * 回合阶段推导（严格重建 SP1）。设计见 docs/design/rr-model.md §3.1。
+ *
+ * MVP 确定性派生 freeze / default / take / execute / postPlant / clutch：
+ * - freeze     : [startTick, freezeEndTick)
+ * - postPlant  : [plantTick, endTick)（双方通用窗口；side-aware gate 自行区分守包/retake）
+ * - clutch     : 一方仅剩 1 人存活（另一方 ≥ 1）起，覆盖战斗类阶段
+ * - take       : T 首次推进出生区外（routeIndex ≥ 1）
+ * - execute    : 某条动线上 ≥ 2 名 T 逼近包点入口（routeIndex ≥ len-2）
+ *
+ * 无 positions / routes 时 take/execute 为 null（降级为 default），并在
+ * RoundPhaseModel.hasPositions/hasRoutes 标注，供 evidenceQuality 使用。
+ */
+import type { DemoPackage } from "@cs2dak/contract";
+import { getMapRoutes, routeIndex, type MapRoutes } from "@cs2dak/maps";
+import { createResolverFromPackage } from "../resolve.js";
+import { groupBy } from "../utils.js";
+import type { RoundPhase, RoundPhaseModel } from "./types.js";
+
+type Round = DemoPackage["rounds"][number];
+type PositionRow = { roundNumber: number; tick: number; steamId64: string; lastPlaceName?: string | null };
+type Kill = DemoPackage["kills"][number];
+
+export function inferRoundPhases(pkg: DemoPackage): Map<number, RoundPhaseModel> {
+  const routes = getMapRoutes(pkg.match?.mapName ?? "");
+  // Build positions from replay 8Hz stream (v3 replaces positions-1s)
+  const positions = buildPositionRows(pkg);
+  const hasPositions = positions.length > 0;
+  const hasRoutes = routes != null;
+
+  const teamByPlayer = new Map(pkg.players.map((p) => [p.steamId64, p.teamKey]));
+  const teamSize = countByTeam(pkg);
+
+  const posByRound = groupBy(positions, (row) => row.roundNumber);
+  const killsByRound = groupBy(pkg.kills, (k) => k.roundNumber);
+  const playerTeams = pkg.players.map((p) => p.teamKey);
+  const plantByRound = new Map<number, number>();
+  for (const bomb of pkg.bombs) {
+    if (bomb.type === "planted" && !plantByRound.has(bomb.roundNumber)) {
+      plantByRound.set(bomb.roundNumber, bomb.tick);
+    }
+  }
+
+  const out = new Map<number, RoundPhaseModel>();
+  for (const round of pkg.rounds) {
+    const tTeam = round.teamASide === "t" ? "teamA" : round.teamBSide === "t" ? "teamB" : null;
+    const plantTick = plantByRound.get(round.roundNumber) ?? null;
+    const clutchStartTick = computeClutchStart(killsByRound.get(round.roundNumber) ?? [], teamSize, playerTeams);
+    const { takeTick, executeTick } = computeTakeExecute(
+      round,
+      tTeam,
+      routes,
+      posByRound.get(round.roundNumber) ?? [],
+      teamByPlayer,
+      plantTick,
+    );
+    out.set(round.roundNumber, {
+      roundNumber: round.roundNumber,
+      startTick: round.startTick,
+      freezeEndTick: round.freezeEndTick,
+      endTick: round.endTick,
+      plantTick,
+      takeTick,
+      executeTick,
+      clutchStartTick,
+      hasPositions,
+      hasRoutes,
+    });
+  }
+  return out;
+}
+
+export function phaseAtTick(model: RoundPhaseModel, tick: number): RoundPhase {
+  if (tick < model.freezeEndTick) return "freeze";
+  if (model.clutchStartTick != null && tick >= model.clutchStartTick) return "clutch";
+  if (model.plantTick != null && tick >= model.plantTick) return "postPlant";
+  if (model.executeTick != null && tick >= model.executeTick) return "execute";
+  if (model.takeTick != null && tick >= model.takeTick) return "take";
+  return "default";
+}
+
+function countByTeam(pkg: DemoPackage): { teamA: number; teamB: number } {
+  let teamA = 0;
+  let teamB = 0;
+  for (const p of pkg.players) {
+    if (p.teamKey === "teamA") teamA += 1;
+    else if (p.teamKey === "teamB") teamB += 1;
+  }
+  return { teamA, teamB };
+}
+
+/** 一方存活降到 1（另一方 ≥ 1）的首个 tick。 */
+function computeClutchStart(kills: Kill[], teamSize: { teamA: number; teamB: number }, playerTeams: string[]): number | null {
+  let aliveA = teamSize.teamA;
+  let aliveB = teamSize.teamB;
+  if (aliveA === 0 || aliveB === 0) return null;
+  for (const kill of [...kills].sort((a, b) => a.tick - b.tick)) {
+    const victimTeam = playerTeams[kill.victimIndex];
+    if (victimTeam === "teamA") aliveA = Math.max(0, aliveA - 1);
+    else if (victimTeam === "teamB") aliveB = Math.max(0, aliveB - 1);
+    if ((aliveA === 1 && aliveB >= 1) || (aliveB === 1 && aliveA >= 1)) {
+      return kill.tick;
+    }
+  }
+  return null;
+}
+
+function computeTakeExecute(
+  round: Round,
+  tTeam: "teamA" | "teamB" | null,
+  routes: MapRoutes | null,
+  rows: PositionRow[],
+  teamByPlayer: Map<string, string>,
+  plantTick: number | null,
+): { takeTick: number | null; executeTick: number | null } {
+  if (!routes || !tTeam || rows.length === 0) return { takeTick: null, executeTick: null };
+
+  // 按 tick 聚合本回合 freeze 后、plant 前的 T 方 callout。
+  const placesByTick = new Map<number, string[]>();
+  for (const row of rows) {
+    if (teamByPlayer.get(row.steamId64) !== tTeam) continue;
+    if (row.tick < round.freezeEndTick) continue;
+    if (plantTick != null && row.tick >= plantTick) continue;
+    if (!row.lastPlaceName) continue;
+    const arr = placesByTick.get(row.tick) ?? [];
+    arr.push(row.lastPlaceName);
+    placesByTick.set(row.tick, arr);
+  }
+
+  let takeTick: number | null = null;
+  let executeTick: number | null = null;
+  for (const tick of [...placesByTick.keys()].sort((a, b) => a - b)) {
+    const places = placesByTick.get(tick)!;
+    let advanced = false;
+    for (const route of routes.routes) {
+      const threshold = Math.max(1, route.zones.length - 2);
+      let nearSite = 0;
+      for (const place of places) {
+        const idx = routeIndex(route, place);
+        if (idx >= 1) advanced = true;
+        if (idx >= threshold) nearSite += 1;
+      }
+      if (nearSite >= 2 && executeTick == null) executeTick = tick;
+    }
+    if (advanced && takeTick == null) takeTick = tick;
+    if (takeTick != null && executeTick != null) break;
+  }
+  // execute 蕴含 take
+  if (executeTick != null && (takeTick == null || takeTick > executeTick)) takeTick = executeTick;
+  return { takeTick, executeTick };
+}
+
+/** 从 replay 8Hz 流提取回合阶段推导所需的简化位置行。 */
+function buildPositionRows(pkg: DemoPackage): PositionRow[] {
+  const resolver = createResolverFromPackage(pkg);
+  const replay = pkg.replay;
+  if (!replay) return [];
+  const placeDict = replay.placeDict ?? [];
+  const out: PositionRow[] = [];
+  for (const round of replay.rounds) {
+    const tickStep = round.tickStep;
+    for (const track of round.players) {
+      const player = resolver.byIndexOrNull(track.playerIndex);
+      if (!player) continue;
+      for (let i = 0; i < track.x.length; i++) {
+        const placeIdx = track.place[i] ?? -1;
+        const lastPlaceName =
+          placeIdx >= 0 && placeIdx < placeDict.length ? placeDict[placeIdx] : null;
+        out.push({
+          roundNumber: round.roundNumber,
+          tick: round.startTick + i * tickStep,
+          steamId64: player.steamId64,
+          lastPlaceName,
+        });
+      }
+    }
+  }
+  return out;
+}

package/src/spatial/trade-closure.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { loadDemoPackageFromZip } from "../loader.js";
+import { deriveRRSignals } from "../signals.js";
+
+/**
+ * SP2 Trade 闭环端到端：de_ancient fixture 含 replay + 现役图动线，
+ * 故 strategicIsolationDeaths 应可观测（非 null），接入 rival-rating 的
+ * effectiveUntradedDeaths（rr-model.md §3.3）。
+ */
+describe("strategicIsolationDeaths wiring (de_ancient fixture)", () => {
+  it("derives an observable (non-null, >= 0) credit for every player", async () => {
+    const zip = await readFile(
+      fileURLToPath(new URL("../../../../fixtures/input/sample-2026-05-17_de_ancient_Team_Spirit_13-10_Team_Falcons.zip", import.meta.url)),
+    );
+    const pkg = await loadDemoPackageFromZip(zip);
+    const signals = deriveRRSignals(pkg);
+
+    expect(signals).toHaveLength(10);
+    for (const s of signals) {
+      expect(s.trade.strategicIsolationDeaths).not.toBeNull();
+      expect(s.trade.strategicIsolationDeaths as number).toBeGreaterThanOrEqual(0);
+      // credit 不应超过该选手的死亡数（抵扣项语义上界）
+      expect(s.trade.strategicIsolationDeaths as number).toBeLessThanOrEqual(s.trade.deaths);
+    }
+  });
+
+  it("returns null strategicIsolationDeaths when replay is absent (unobservable)", async () => {
+    const zip = await readFile(
+      fileURLToPath(new URL("../../../../fixtures/input/sample-2026-05-17_de_ancient_Team_Spirit_13-10_Team_Falcons.zip", import.meta.url)),
+    );
+    const pkg = await loadDemoPackageFromZip(zip);
+    const { replay: _, ...stripped } = pkg;
+    const signals = deriveRRSignals(stripped);
+    for (const s of signals) expect(s.trade.strategicIsolationDeaths).toBeNull();
+  });
+});