@cs2dak/core 0.2.1 → 2.0.0

package/src/signals.ts

@@ -1,11 +1,16 @@
 import {
-  computeLeagueMeanV2,
-  computeValueAccountsRR,
-  rrValueAccountsV2Lite
+  computeFrozenProBaselineRR,
+  computeRRSixAccounts,
+  rrSixAccountProBaselineV0,
+  rrSixAccountWeightsV1
 } from "@rivalhub/rival-rating";
-import type { AccountSignalsV2, DemoPackage, ValueAccountsWeights } from "@cs2dak/contract";
-import type { RRResultV2 } from "@rivalhub/rival-rating";
+import type { DemoPackage, RRSignals, RRSixAccountWeights } from "@cs2dak/contract";
+import type { CohortAccountResult, ProBaselineConfig, RRSixAccountResult } from "@rivalhub/rival-rating";
 import { normalizeDemoPackage } from "./normalize.js";
+import { loadSpatialAssets } from "./spatial/annotate.js";
+import { buildOfficialMapControl } from "./spatial/mapcontrol.js";
+import { createResolverFromPackage, type PlayerResolver } from "./resolve.js";
+import { buildPlayerRoundUtilityFacts } from "./utility-facts.js";
 import {
   type BuyDeltaBuckets,
   type ManStateBuckets,
@@ -15,7 +20,7 @@ import {
   getOrInit,
   zeroBuyDelta,
   zeroManState,
-  clutchSplitV2,
+  clutchSplit,
   sumDamageForPlayer,
   openingKillsForPlayer,
   openingDeathsForPlayer,
@@ -24,38 +29,44 @@ import {
   firstKillMap
 } from "./utils.js";
 
-export function deriveAccountSignalsV2(input: unknown): AccountSignalsV2[] {
+export type AccountRatingResult = CohortAccountResult & Pick<RRSixAccountResult, "combatContextFactor" | "weightsVersion" | "model">;
+
+export function deriveRRSignals(input: unknown): RRSignals[] {
   const pkg = normalizeDemoPackage(input);
-  const statsBySteamId = new Map(pkg.playerStats.map((row) => [row.steamId64, row]));
-  const killsByBuyDelta = buildKillsByBuyDelta(pkg);
-  const killsByManState = buildKillsByManState(pkg);
-  const tradedOpeningDeaths = buildTradedOpeningDeaths(pkg);
-  const objective = buildObjectiveSignals(pkg);
-  const utility = buildUtilitySignals(pkg);
-
-  // context 分桶的"数据源是否存在"。源缺失 → 发 null（模型降级为乘子 1.0），
-  // 而非零桶——零桶语义是"源在、但该选手无相关样本"。区分二者是 v2 可信展示的前提。
+  const resolver = createResolverFromPackage(pkg);
+  const statsMap = new Map(pkg.playerStats.map((row) => [row.playerIndex, row]));
+  const killsByBuyDelta = buildKillsByBuyDelta(pkg, resolver);
+  const killsByManState = buildKillsByManState(pkg, resolver);
+  const tradedOpeningDeaths = buildTradedOpeningDeaths(pkg, resolver);
+  const objective = buildObjectiveSignals(pkg, resolver);
+  const utility = buildUtilitySignals(pkg, statsMap);
+
   const buyDeltaAvailable = pkg.playerEconomies.length > 0;
   const manStateAvailable = pkg.rounds.length > 0;
 
-  return pkg.players.map((player) => {
-    const stats = statsBySteamId.get(player.steamId64);
-    const playerKills = pkg.kills.filter((kill) => kill.killerSteamId64 === player.steamId64);
-    const playerDeaths = pkg.kills.filter((kill) => kill.victimSteamId64 === player.steamId64);
-    const playerClutches = pkg.clutches.filter((row) => row.clutcherSteamId64 === player.steamId64);
+  const spatialAssets = loadSpatialAssets(pkg.match?.mapName ?? pkg.manifest?.mapName ?? "");
+  const officialMapControl = buildOfficialMapControl(pkg, spatialAssets);
+  // replay-based spatial re-impl (step 3)
+  const spatialObservable = spatialAssets.routes != null && (pkg.replay?.rounds?.length ?? 0) > 0;
+
+  return pkg.players.map((player, playerIdx) => {
+    const stats = statsMap.get(playerIdx);
+    const playerKills = pkg.kills.filter((kill) => kill.killerIndex === playerIdx);
+    const playerDeaths = pkg.kills.filter((kill) => kill.victimIndex === playerIdx);
+    const playerClutches = pkg.clutches.filter((row) => row.clutcherIndex === playerIdx);
     const rounds = Math.max(stats?.rounds ?? pkg.rounds.length, 0);
 
     return {
       steamId64: player.steamId64,
       rounds,
-      sourceVersion: "cs2-demo-analysis-kit/0.3",
+      sourceVersion: "cs2-demo-analysis-kit/1.0",
       combat: {
         kills: stats?.kills ?? playerKills.length,
         deaths: stats?.deaths ?? playerDeaths.length,
         assists: stats?.assists ?? 0,
-        effectiveDamage: stats?.damageHealth ?? sumDamageForPlayer(pkg, player.steamId64),
-        openingKills: stats?.firstKillCount ?? openingKillsForPlayer(pkg, player.steamId64),
-        openingDeaths: stats?.firstDeathCount ?? openingDeathsForPlayer(pkg, player.steamId64),
+        effectiveDamage: stats?.damageHealth ?? sumDamageForPlayer(pkg, playerIdx),
+        openingKills: stats?.firstKillCount ?? openingKillsForPlayer(pkg, playerIdx),
+        openingDeaths: stats?.firstDeathCount ?? openingDeathsForPlayer(pkg, playerIdx),
         multiKills: {
           two: stats?.twoKillCount ?? multiKillRounds(playerKills, 2),
           three: stats?.threeKillCount ?? multiKillRounds(playerKills, 3),
@@ -71,55 +82,78 @@ export function deriveAccountSignalsV2(input: unknown): AccountSignalsV2[] {
         tradeKills: stats?.tradeKillCount ?? playerKills.filter((kill) => kill.tradeKill).length,
         tradedDeaths: stats?.tradeDeathCount ?? playerDeaths.filter((kill) => kill.tradeDeath).length,
         deaths: stats?.deaths ?? playerDeaths.length,
-        tradedOpeningDeaths: tradedOpeningDeaths.get(player.steamId64) ?? 0
+        tradedOpeningDeaths: tradedOpeningDeaths.get(player.steamId64) ?? 0,
+        strategicIsolationDeaths: spatialObservable
+          ? (officialMapControl.get(player.steamId64)?.strategicIsolationDeaths ?? 0)
+          : null
+      },
+      mapControl: {
+        uniqueStrategicControlSeconds: null,
+        contestedFrontierControlSeconds: null,
+        routeDenialSeconds: null,
+        teammateAdvanceUnits: null,
+        firstControlEvents: null
       },
       clutch: {
-        vsOne: clutchSplitV2(stats?.vsOneCount, stats?.vsOneWonCount, playerClutches, 1),
-        vsTwo: clutchSplitV2(stats?.vsTwoCount, stats?.vsTwoWonCount, playerClutches, 2),
-        vsThree: clutchSplitV2(stats?.vsThreeCount, stats?.vsThreeWonCount, playerClutches, 3),
-        vsFour: clutchSplitV2(stats?.vsFourCount, stats?.vsFourWonCount, playerClutches, 4),
-        vsFive: clutchSplitV2(stats?.vsFiveCount, stats?.vsFiveWonCount, playerClutches, 5)
+        vsOne: clutchSplit(stats?.vsOneCount, stats?.vsOneWonCount, playerClutches, 1),
+        vsTwo: clutchSplit(stats?.vsTwoCount, stats?.vsTwoWonCount, playerClutches, 2),
+        vsThree: clutchSplit(stats?.vsThreeCount, stats?.vsThreeWonCount, playerClutches, 3),
+        vsFour: clutchSplit(stats?.vsFourCount, stats?.vsFourWonCount, playerClutches, 4),
+        vsFive: clutchSplit(stats?.vsFiveCount, stats?.vsFiveWonCount, playerClutches, 5)
       },
       objective: objective.get(player.steamId64) ?? { plants: 0, defuses: 0, plantsConverted: 0 },
-      utility: utility.get(player.steamId64) ?? {
-        flashAssists: stats?.flashAssistCount ?? 0,
-        enemyFlashDurationSeconds: stats?.enemyFlashDurationSeconds ?? 0,
-        teamFlashDurationSeconds: stats?.teamFlashDurationSeconds ?? 0,
-        utilityDamage: stats?.utilityDamage ?? 0
+      utility: {
+        ...(utility.get(player.steamId64) ?? {
+          flashAssists: stats?.flashAssistCount ?? 0,
+          effectiveEnemyFlashSeconds: stats?.enemyFlashDurationSeconds ?? 0,
+          teamFlashSuppressionSeconds: stats?.teamFlashDurationSeconds ?? 0,
+          smokeProtectedCrossings: null,
+          smokeSightlineDenialSeconds: null,
+          smokeIsolationSeconds: null,
+          incendiaryPathDelayUnits: null,
+          incendiaryDisplacementEvents: null,
+          utilityDamage: stats?.utilityDamage ?? 0
+        })
       }
-    } satisfies AccountSignalsV2;
+    } satisfies RRSignals;
   });
 }
 
-export function computeAccountRatingsV2(input: unknown): Array<{ signals: AccountSignalsV2; rr: RRResultV2 }> {
-  const weights = rrValueAccountsV2Lite as unknown as ValueAccountsWeights;
-  const rated = deriveAccountSignalsV2(input).map((signals) => ({
-    signals,
-    rr: computeValueAccountsRR(signals, weights)
-  }));
+export function computeAccountRatingsV2(input: unknown): Array<{ signals: RRSignals; rr: AccountRatingResult }> {
+  const weights = rrSixAccountWeightsV1 as unknown as RRSixAccountWeights;
+  const baseline = rrSixAccountProBaselineV0 as unknown as ProBaselineConfig;
+  const signals = deriveRRSignals(input);
+  const rawBySteamId = new Map(signals.map((row) => [row.steamId64, computeRRSixAccounts(row, weights)]));
+  const balanced = signals.map((signal) => computeFrozenProBaselineRR(signal, weights, baseline));
 
-  // 联赛锚定（weights.anchor.mode === "league_mean"）：整体乘 (1.0 / mean)，
-  // 使 1.00 = 本场均值。本层一次只处理单场，故"联赛均值"= 本场均值（per-match）；
-  // 真正的赛季级锚定属于上游跨场聚合层，详见 docs/design/rr-v2-lite.md。
-  const mean = computeLeagueMeanV2(rated.map((row) => row.rr));
-  const factor = mean > 0 ? 1.0 / mean : 1.0;
-  return rated.map((row) => ({
-    signals: row.signals,
-    rr: { ...row.rr, rr: row.rr.rr * factor }
-  }));
+  return balanced.map((rr, index) => {
+    const signal = signals[index]!;
+    const raw = rawBySteamId.get(signal.steamId64);
+    return {
+      signals: signal,
+      rr: {
+        ...rr,
+        combatContextFactor: raw?.combatContextFactor ?? 1,
+        weightsVersion: raw?.weightsVersion ?? weights.version,
+        model: raw?.model ?? "rr-six-accounts"
+      }
+    };
+  });
 }
 
-function buildKillsByBuyDelta(pkg: DemoPackage): Map<string, BuyDeltaBuckets> {
+function buildKillsByBuyDelta(pkg: DemoPackage, resolver: PlayerResolver): Map<string, BuyDeltaBuckets> {
   const out = new Map<string, BuyDeltaBuckets>();
-  const economyByPlayerRound = new Map(pkg.playerEconomies.map((row) => [`${row.roundNumber}:${row.steamId64}`, row]));
+  const economyByPlayerRound = new Map(pkg.playerEconomies.map((row) => [`${row.roundNumber}:${row.playerIndex}`, row]));
 
   for (const kill of pkg.kills) {
-    if (!kill.killerSteamId64) continue;
-    const killerEconomy = economyByPlayerRound.get(`${kill.roundNumber}:${kill.killerSteamId64}`);
-    const victimEconomy = economyByPlayerRound.get(`${kill.roundNumber}:${kill.victimSteamId64}`);
+    if (kill.killerIndex === null) continue;
+    const killerEconomy = economyByPlayerRound.get(`${kill.roundNumber}:${kill.killerIndex}`);
+    const victimEconomy = economyByPlayerRound.get(`${kill.roundNumber}:${kill.victimIndex}`);
     if (!killerEconomy || !victimEconomy) continue;
 
-    const buckets = getOrInit(out, kill.killerSteamId64, zeroBuyDelta);
+    const killerSteamId = resolver.steamIdOf(kill.killerIndex);
+    if (!killerSteamId) continue;
+    const buckets = getOrInit(out, killerSteamId, zeroBuyDelta);
     const delta = killerEconomy.equipmentValue - victimEconomy.equipmentValue;
     if (delta <= -BUY_DELTA_EVEN_THRESHOLD) {
       buckets.disadvantage += 1;
@@ -133,63 +167,68 @@ function buildKillsByBuyDelta(pkg: DemoPackage): Map<string, BuyDeltaBuckets> {
   return out;
 }
 
-function buildKillsByManState(pkg: DemoPackage): Map<string, ManStateBuckets> {
+function buildKillsByManState(pkg: DemoPackage, resolver: PlayerResolver): Map<string, ManStateBuckets> {
   const out = new Map<string, ManStateBuckets>();
-  const playersByTeam = {
-    teamA: pkg.players.filter((player) => player.teamKey === "teamA").map((player) => player.steamId64),
-    teamB: pkg.players.filter((player) => player.teamKey === "teamB").map((player) => player.steamId64)
-  };
+  const teamAIndices = new Set(pkg.players.flatMap((p, i) => p.teamKey === "teamA" ? [i] : []));
+  const teamBIndices = new Set(pkg.players.flatMap((p, i) => p.teamKey === "teamB" ? [i] : []));
 
   for (const roundRow of pkg.rounds) {
-    const alive = {
-      teamA: new Set(playersByTeam.teamA),
-      teamB: new Set(playersByTeam.teamB)
-    };
+    const aliveA = new Set(teamAIndices);
+    const aliveB = new Set(teamBIndices);
     const roundKills = pkg.kills
       .filter((kill) => kill.roundNumber === roundRow.roundNumber)
       .sort((a, b) => a.tick - b.tick);
 
     for (const kill of roundKills) {
-      if (kill.killerSteamId64 && kill.killerTeamKey && kill.killerTeamKey !== kill.victimTeamKey) {
-        const buckets = getOrInit(out, kill.killerSteamId64, zeroManState);
-        const killerAlive = alive[kill.killerTeamKey].size;
-        const victimAlive = alive[kill.victimTeamKey].size;
-        const diff = killerAlive - victimAlive;
-        if (diff < 0) {
-          buckets.manDown += 1;
-        } else if (diff > 0) {
-          buckets.manUp += 1;
-        } else {
-          buckets.even += 1;
-        }
+      if (kill.killerIndex === null) continue;
+      const killerPlayer = resolver.byIndexOrNull(kill.killerIndex);
+      const victimPlayer = resolver.byIndexOrNull(kill.victimIndex);
+      if (!killerPlayer || !victimPlayer || killerPlayer.teamKey === victimPlayer.teamKey) continue;
+
+      const killerSteamId = killerPlayer.steamId64;
+      const buckets = getOrInit(out, killerSteamId, zeroManState);
+      const killerAlive = killerPlayer.teamKey === "teamA" ? aliveA.size : aliveB.size;
+      const victimAlive = victimPlayer.teamKey === "teamA" ? aliveA.size : aliveB.size;
+      const diff = killerAlive - victimAlive;
+      if (diff < 0) {
+        buckets.manDown += 1;
+      } else if (diff > 0) {
+        buckets.manUp += 1;
+      } else {
+        buckets.even += 1;
       }
-      alive[kill.victimTeamKey].delete(kill.victimSteamId64);
+
+      if (victimPlayer.teamKey === "teamA") aliveA.delete(kill.victimIndex);
+      else aliveB.delete(kill.victimIndex);
     }
   }
 
   return out;
 }
 
-function buildTradedOpeningDeaths(pkg: DemoPackage): Map<string, number> {
+function buildTradedOpeningDeaths(pkg: DemoPackage, resolver: PlayerResolver): Map<string, number> {
   const out = new Map<string, number>();
   for (const kill of firstKillMap(pkg).values()) {
     if (kill.tradeDeath) {
-      out.set(kill.victimSteamId64, (out.get(kill.victimSteamId64) ?? 0) + 1);
+      const victimSteamId = resolver.steamIdOf(kill.victimIndex);
+      if (victimSteamId) out.set(victimSteamId, (out.get(victimSteamId) ?? 0) + 1);
     }
   }
   return out;
 }
 
-function buildObjectiveSignals(pkg: DemoPackage): Map<string, ObjectiveBuckets> {
+function buildObjectiveSignals(pkg: DemoPackage, resolver: PlayerResolver): Map<string, ObjectiveBuckets> {
   const out = new Map<string, ObjectiveBuckets>();
   const roundWinner = new Map(pkg.rounds.map((round) => [round.roundNumber, round.winnerTeamKey]));
 
   for (const bomb of pkg.bombs) {
-    if (!bomb.actorSteamId64) continue;
-    const buckets = getOrInit(out, bomb.actorSteamId64, () => ({ plants: 0, defuses: 0, plantsConverted: 0 }));
+    if (bomb.actorIndex === null) continue;
+    const actorPlayer = resolver.byIndexOrNull(bomb.actorIndex);
+    if (!actorPlayer) continue;
+    const buckets = getOrInit(out, actorPlayer.steamId64, () => ({ plants: 0, defuses: 0, plantsConverted: 0 }));
     if (bomb.type === "planted") {
       buckets.plants += 1;
-      if (bomb.actorTeamKey && roundWinner.get(bomb.roundNumber) === bomb.actorTeamKey) {
+      if (roundWinner.get(bomb.roundNumber) === actorPlayer.teamKey) {
         buckets.plantsConverted = (buckets.plantsConverted ?? 0) + 1;
       }
     } else if (bomb.type === "defused") {
@@ -200,33 +239,31 @@ function buildObjectiveSignals(pkg: DemoPackage): Map<string, ObjectiveBuckets>
   return out;
 }
 
-function buildUtilitySignals(pkg: DemoPackage): Map<string, UtilityBuckets> {
-  const out = new Map<string, UtilityBuckets>();
-  const statsBySteamId = new Map(pkg.playerStats.map((row) => [row.steamId64, row]));
-
-  for (const player of pkg.players) {
-    const stats = statsBySteamId.get(player.steamId64);
-    out.set(player.steamId64, {
-      flashAssists: stats?.flashAssistCount ?? pkg.kills.filter((kill) => kill.flashAssisterSteamId64 === player.steamId64).length,
-      enemyFlashDurationSeconds: stats?.enemyFlashDurationSeconds ?? 0,
-      teamFlashDurationSeconds: stats?.teamFlashDurationSeconds ?? 0,
-      utilityDamage: stats?.utilityDamage ?? 0
-    });
+function buildUtilitySignals(pkg: DemoPackage, statsMap: Map<number, DemoPackage["playerStats"][number]>): Map<string, UtilityBuckets> {
+  const utilityFacts = buildPlayerRoundUtilityFacts(pkg);
+  const totals = new Map<string, { flashAssists: number; enemyBlindSeconds: number; teamBlindSeconds: number; utilityDamage: number }>();
+  for (const fact of utilityFacts) {
+    const total = totals.get(fact.steamId64) ?? { flashAssists: 0, enemyBlindSeconds: 0, teamBlindSeconds: 0, utilityDamage: 0 };
+    total.flashAssists += fact.flashAssists;
+    total.enemyBlindSeconds += fact.enemyBlindSeconds;
+    total.teamBlindSeconds += fact.teamBlindSeconds;
+    total.utilityDamage += fact.utilityDamage;
+    totals.set(fact.steamId64, total);
   }
 
-  for (const blind of pkg.blinds) {
-    const buckets = getOrInit(out, blind.flasherSteamId64, () => ({
-      flashAssists: 0,
-      enemyFlashDurationSeconds: 0,
-      teamFlashDurationSeconds: 0,
-      utilityDamage: 0
-    }));
-    if (blind.flasherTeamKey !== blind.flashedTeamKey) {
-      buckets.enemyFlashDurationSeconds = round(buckets.enemyFlashDurationSeconds + blind.durationSeconds, 3);
-    } else if (blind.flashedSteamId64 !== blind.flasherSteamId64) {
-      buckets.teamFlashDurationSeconds = round((buckets.teamFlashDurationSeconds ?? 0) + blind.durationSeconds, 3);
-    }
-  }
-
-  return out;
+  return new Map(pkg.players.map((player, playerIdx) => {
+    const stats = statsMap.get(playerIdx);
+    const fact = totals.get(player.steamId64) ?? { flashAssists: 0, enemyBlindSeconds: 0, teamBlindSeconds: 0, utilityDamage: 0 };
+    return [player.steamId64, {
+      flashAssists: stats?.flashAssistCount ?? fact.flashAssists,
+      effectiveEnemyFlashSeconds: stats?.enemyFlashDurationSeconds ?? round(fact.enemyBlindSeconds, 3),
+      teamFlashSuppressionSeconds: stats?.teamFlashDurationSeconds ?? round(fact.teamBlindSeconds, 3),
+      smokeProtectedCrossings: null,
+      smokeSightlineDenialSeconds: null,
+      smokeIsolationSeconds: null,
+      incendiaryPathDelayUnits: null,
+      incendiaryDisplacementEvents: null,
+      utilityDamage: stats?.utilityDamage ?? fact.utilityDamage
+    } satisfies UtilityBuckets];
+  }));
 }

package/src/spatial/annotate.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from "vitest";
+import type { DemoPackage, Replay } from "@cs2dak/contract";
+import type { MapZones } from "@cs2dak/maps";
+import { annotatePositions, groupSamplesByRoundTick, loadSpatialAssets, type SpatialAssets } from "./annotate.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 replay round with one (or more) player tracks at a single tick. */
+function replayRound(
+  tick: number,
+  tracks: { playerIdx: number; x: number; y: number; z: number; placeIdx: number }[],
+): Replay["rounds"][number] {
+  return {
+    roundNumber: 1,
+    startTick: tick,
+    tickStep: 8,
+    frameCount: 1,
+    players: tracks.map((t) => ({
+      playerIndex: t.playerIdx,
+      x: deltaArr([t.x]), y: deltaArr([t.y]), z: deltaArr([t.z]),
+      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: [],
+  };
+}
+
+function pkgWith(mapName: string, rows: { place: string; x: number; y: number; z: number }[]): DemoPackage {
+  const placeDict = [...new Set(rows.map((r) => r.place))];
+  const placeMap = new Map(placeDict.map((p, i) => [p, i]));
+  const tracks = rows.map((r, i) => ({
+    playerIdx: Math.min(i, 1), // player 0 or 1
+    x: r.x, y: r.y, z: r.z,
+    placeIdx: placeMap.get(r.place) ?? -1,
+  }));
+  return {
+    match: { mapName, tickrate: 64 },
+    players: [
+      { steamId64: "T1", teamKey: "teamA" },
+      rows.length > 1 ? { steamId64: "T2", teamKey: "teamA" } : { steamId64: "T2", teamKey: "teamA" },
+    ],
+    rounds: [{ roundNumber: 1, startTick: 1, freezeEndTick: 100, endTick: 2000, teamASide: "t", teamBSide: "ct" }],
+    replay: {
+      meta: { sampleRate: 8, tickrate: 64, coordScale: 1, angleScale: 10 },
+      weaponDict: [],
+      placeDict,
+      rounds: [replayRound(120, tracks)],
+    },
+  } as unknown as DemoPackage;
+}
+
+/** Create a package with no replay data (simulates unobservable positions). */
+function pkgWithoutReplay(): DemoPackage {
+  return {
+    match: { mapName: "de_dust2", tickrate: 64 },
+    players: [{ steamId64: "T1", teamKey: "teamA" }],
+    rounds: [{ roundNumber: 1, startTick: 1, freezeEndTick: 100, endTick: 2000, teamASide: "t", teamBSide: "ct" }],
+  } as unknown as DemoPackage;
+}
+
+describe("loadSpatialAssets", () => {
+  it("reports availability per asset for an active-duty map", () => {
+    const assets = loadSpatialAssets("de_dust2");
+    expect(assets.available.routes).toBe(true);
+    expect(assets.available.nav).toBe(true);
+    expect(assets.available.visibility).toBe(false); // no .tri passed
+  });
+
+  it("reports everything missing for an unknown map", () => {
+    const assets = loadSpatialAssets("de_unknown");
+    expect(assets.available.routes).toBe(false);
+    expect(assets.available.nav).toBe(false);
+  });
+});
+
+describe("annotatePositions", () => {
+  it("attaches callout and position from replay when nav is available", () => {
+    const assets = loadSpatialAssets("de_dust2");
+    const samples = annotatePositions(pkgWith("de_dust2", [{ place: "LongA", x: 760, y: 1660, z: 0 }]), assets);
+    expect(samples).toHaveLength(1);
+    expect(samples[0]!.callout).toBe("LongA");
+    expect(samples[0]!.position).toEqual({ x: 760, y: 1660, z: 0 });
+  });
+
+  it("leaves navAreaId null when nav is unavailable", () => {
+    const assets = loadSpatialAssets("de_unknown");
+    const samples = annotatePositions(pkgWith("de_unknown", [{ place: "Somewhere", x: 0, y: 0, z: 0 }]), assets);
+    expect(samples).toHaveLength(1);
+    expect(samples[0]!.navAreaId).toBeNull();
+    expect(samples[0]!.callout).toBe("Somewhere");
+  });
+
+  it("returns an empty array without positions", () => {
+    const assets = loadSpatialAssets("de_dust2");
+    expect(annotatePositions(pkgWithoutReplay(), assets)).toEqual([]);
+  });
+
+  it("groups samples by round then tick", () => {
+    const assets = loadSpatialAssets("de_dust2");
+    const samples = annotatePositions(
+      pkgWith("de_dust2", [{ place: "LongA", x: 760, y: 1660, z: 0 }, { place: "TSpawn", x: -500, y: -850, z: 96 }]),
+      assets,
+    );
+    const grouped = groupSamplesByRoundTick(samples);
+    expect(grouped.get(1)!.get(120)!).toHaveLength(2);
+  });
+
+  it("populates zoneId/zoneRole/zoneBombsite via zoneAt when zones are available", () => {
+    const TEST_ZONES: MapZones = {
+      mapName: "de_test",
+      version: "t",
+      zones: [{ id: "a_site", name: "A", role: "site", bombsite: "a", polygon: [[0, 0], [100, 0], [100, 100], [0, 100]] }],
+    };
+    const assets: SpatialAssets = {
+      mapName: "de_test", routes: null, zones: TEST_ZONES, nav: null, visibility: null,
+      available: { routes: false, zones: true, nav: false, visibility: false },
+    };
+    const samples = annotatePositions(pkgWith("de_test", [{ place: "A", x: 50, y: 50, z: 0 }]), assets);
+    expect(samples).toHaveLength(1);
+    expect(samples[0]!.zoneId).toBe("a_site");
+    expect(samples[0]!.zoneRole).toBe("site");
+    expect(samples[0]!.zoneBombsite).toBe("a");
+  });
+});

package/src/spatial/annotate.ts

@@ -0,0 +1,163 @@
+/**
+ * Raw evidence 地基：位置标注 + 空间资产装载（严格重建 SP1）。
+ * 设计见 docs/design/rr-model.md §3、§5（计算流程）。
+ *
+ * 当前控图/战术语义真相源是 replay place 生成的 callout grid，不是手标 zone polygon。
+ * zone 字段只保留给旧 shadow spatial/utility 几何路径；新增控图 finding 不应消费 zoneId。
+ * 这些是 official MapControl gate（SP2：solo pressure 的 nav 距离、denial 的 LOS）的输入底座。
+ *
+ * v3 replay 8Hz 流替代了 v2 的 positions-1s。每帧解码后转换：
+ * - track.tick（差分编码 → decodeDelta）
+ * - track.x/y/z（差分编码 × coordScale → 游戏单位）
+ * - track.place（索引 → placeDict）
+ * - track.flags（FLAG_ALIVE）
+ * - track.hp（原始值）
+ */
+import type { DemoPackage } from "@cs2dak/contract";
+import { decodeDelta, FLAG_ALIVE } from "@cs2dak/contract";
+import { createResolverFromPackage } from "../resolve.js";
+import {
+  getMapNav,
+  getMapRoutes,
+  getMapZones,
+  zoneAt,
+  type CompactNav,
+  type MapRoutes,
+  type MapZones,
+  type TriangleBvh,
+  type Vec3,
+  type ZoneRole,
+} from "@cs2dak/maps";
+
+export interface SpatialAssets {
+  mapName: string;
+  routes: MapRoutes | null;
+  zones: MapZones | null;
+  nav: CompactNav | null;
+  /** 静态视线 BVH；Node 下经 tri-assets 装载，浏览器降级为 null。 */
+  visibility: TriangleBvh | null;
+  available: {
+    routes: boolean;
+    zones: boolean;
+    nav: boolean;
+    visibility: boolean;
+  };
+}
+
+export function loadSpatialAssets(mapName: string, triBvh?: TriangleBvh | null): SpatialAssets {
+  const routes = getMapRoutes(mapName);
+  const zones = getMapZones(mapName);
+  const nav = getMapNav(mapName);
+  const visibility = triBvh ?? null;
+  return {
+    mapName,
+    routes,
+    zones,
+    nav,
+    visibility,
+    available: {
+      routes: routes != null,
+      zones: zones != null,
+      nav: nav != null,
+      visibility: visibility != null,
+    },
+  };
+}
+
+export interface AnnotatedSample {
+  roundNumber: number;
+  tick: number;
+  steamId64: string;
+  teamKey: string;
+  side: string | null;
+  alive: boolean;
+  position: Vec3;
+  /** callout（replay placeDict）；缺失为 null。 */
+  callout: string | null;
+  /** legacy 手标 zone id；当前控图/战术语义不要把它当真相源。 */
+  zoneId: string | null;
+  /** zone 语义角色（site/mid/connector/lane…）；无 zone 为 null。 */
+  zoneRole: ZoneRole | null;
+  /** zone 关联包点；无则 null。 */
+  zoneBombsite: "a" | "b" | null;
+  /** 最近 nav area id；无 nav 资产为 null。 */
+  navAreaId: number | null;
+  /** 当前血量（火焰逼退掉血判定用）；缺失为 100。 */
+  health: number;
+}
+
+/**
+ * 从 replay 8Hz 流标注位置样本（v3 替代 v2 positions-1s）。
+ * 返回所有存活/阵亡玩家的逐帧标注，zone/nav 判定暂缺（需 maps 包导出 zoneAt/nearestNavArea）。
+ */
+export function annotatePositions(pkg: DemoPackage, assets: SpatialAssets): AnnotatedSample[] {
+  const resolver = createResolverFromPackage(pkg);
+  const replay = pkg.replay;
+  if (!replay) return [];
+
+  const coordScale = replay.meta.coordScale;
+  const placeDict = replay.placeDict ?? [];
+  const samples: AnnotatedSample[] = [];
+
+  const roundByNumber = new Map(pkg.rounds.map((r) => [r.roundNumber, r]));
+
+  for (const round of replay.rounds) {
+    const roundRow = roundByNumber.get(round.roundNumber);
+    if (!roundRow) continue;
+    const tickStep = round.tickStep;
+
+    for (const track of round.players) {
+      const player = resolver.byIndexOrNull(track.playerIndex);
+      if (!player) continue;
+
+      const xs = decodeDelta(track.x);
+      const ys = decodeDelta(track.y);
+      const zs = decodeDelta(track.z);
+      const side: string | null =
+        player.teamKey === "teamA" ? roundRow.teamASide : roundRow.teamBSide;
+
+      for (let i = 0; i < xs.length; i++) {
+        const placeIdx = track.place[i] ?? -1;
+        const px = (xs[i] ?? 0) * coordScale;
+        const py = (ys[i] ?? 0) * coordScale;
+        const pz = (zs[i] ?? 0) * coordScale;
+        const zone = assets.zones ? zoneAt(assets.zones, px, py, pz) : null;
+        samples.push({
+          roundNumber: round.roundNumber,
+          tick: round.startTick + i * tickStep,
+          steamId64: player.steamId64,
+          teamKey: player.teamKey,
+          side,
+          alive: ((track.flags[i] ?? 0) & FLAG_ALIVE) !== 0,
+          position: { x: px, y: py, z: pz },
+          callout: placeIdx >= 0 && placeIdx < placeDict.length ? placeDict[placeIdx] : null,
+          zoneId: zone?.id ?? null,
+          zoneRole: (zone?.role as ZoneRole | undefined) ?? null,
+          zoneBombsite: (zone?.bombsite as "a" | "b" | undefined) ?? null,
+          navAreaId: null,
+          health: track.hp[i] ?? 100,
+        });
+      }
+    }
+  }
+
+  return samples;
+}
+
+/** 按 (round, tick) 分组的标注样本，供逐帧 gate 消费。 */
+export function groupSamplesByRoundTick(
+  samples: AnnotatedSample[],
+): Map<number, Map<number, AnnotatedSample[]>> {
+  const out = new Map<number, Map<number, AnnotatedSample[]>>();
+  for (const s of samples) {
+    let byTick = out.get(s.roundNumber);
+    if (!byTick) {
+      byTick = new Map();
+      out.set(s.roundNumber, byTick);
+    }
+    const arr = byTick.get(s.tick) ?? [];
+    arr.push(s);
+    byTick.set(s.tick, arr);
+  }
+  return out;
+}