@cs2dak/cohort 1.0.0 → 2.0.0

package/LICENSE

@@ -1,3 +1,10 @@
+Licensing note / 适用范围
+-------------------------
+The MIT License below applies to this repository EXCEPT apps/dak-studio/,
+which is licensed under the GNU AGPL-3.0-only (see apps/dak-studio/LICENSE).
+Ecosystem packages (@cs2dak/*, python exporter) are MIT; the DAK Studio
+product is AGPL. Third-party attributions: THIRD-PARTY-NOTICES.md.
+
 MIT License
 
 Copyright (c) 2026 Starfie1d

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@cs2dak/cohort",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "type": "module",
   "license": "MIT",
   "exports": {
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@rivalhub/rival-rating": "^0.1.0",
-    "@cs2dak/contract": "1.0.0",
-    "@cs2dak/core": "1.0.0"
+    "@rivalhub/rival-rating": "^0.3.0",
+    "@cs2dak/contract": "1.1.0",
+    "@cs2dak/core": "2.0.0"
   },
   "files": [
-    "src/index.ts"
+    "src"
   ],
   "publishConfig": {
     "access": "public"

package/src/index.test.ts

@@ -0,0 +1,150 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { beforeAll, describe, expect, it } from "vitest";
+import { derivePlayerWeaponHighlights, deriveRRIndicators, loadDemoPackageFromZip } from "@cs2dak/core";
+import type { DemoPackage } from "@cs2dak/contract";
+import { buildSeasonCohort } from "./index";
+
+const fixtureDir = fileURLToPath(new URL("../../../fixtures/input/cohort", import.meta.url));
+const integrationTimeoutMs = 90_000; // CI 2-core runner 加载 3 场 ZIP + cohort 分析比本机慢 5–10×
+let demos: Awaited<ReturnType<typeof loadCohortFixtures>> | null = null;
+let baselineBundle: ReturnType<typeof buildSeasonCohort> | null = null;
+
+async function loadCohortFixtures() {
+  const names = (await readdir(fixtureDir)).filter((name) => name.endsWith(".zip")).sort();
+  return Promise.all(
+    names.map(async (name) => ({
+      matchId: name.replace(/\.zip$/, ""),
+      pkg: await loadDemoPackageFromZip(await readFile(join(fixtureDir, name)))
+    }))
+  );
+}
+
+beforeAll(async () => {
+  demos = await loadCohortFixtures();
+  baselineBundle = buildSeasonCohort(demos);
+}, integrationTimeoutMs);
+
+describe("buildSeasonCohort", () => {
+  it("builds a season bundle from multiple sanitized demo packages", () => {
+    const bundle = baselineBundle!;
+    const uniquePlayers = new Set(demos!.flatMap((demo) => demo.pkg.players.map((player) => player.steamId64)));
+
+    expect(demos!).toHaveLength(3);
+    expect(bundle.matchCount).toBe(3);
+    expect(bundle.version).toBe("cs2-demo-analysis-kit/cohort-1.0");
+    expect(bundle.provenance.matches).toHaveLength(3);
+    expect(bundle.players).toHaveLength(uniquePlayers.size);
+    expect(bundle.players.length).toBeGreaterThan(10);
+    expect(bundle.players.every((row) => row.prism?.mapCount === row.mapCount)).toBe(true);
+    expect(bundle.players.every((row) => row.playerKey.startsWith("steam:"))).toBe(true);
+  });
+
+  it("merges the same steamId64 across matches and sums season counts", () => {
+    const bundle = baselineBundle!;
+    const repeated = bundle.players.find((row) => row.mapCount > 1);
+    expect(repeated).toBeDefined();
+
+    const expectedKills = demos!.reduce((total, demo) => {
+      const row = deriveRRIndicators(demo.pkg).find((indicator) => repeated!.steamIds.includes(indicator.steamId64));
+      return total + (row?.kills ?? 0);
+    }, 0);
+    const expectedRounds = demos!.reduce((total, demo) => {
+      const row = deriveRRIndicators(demo.pkg).find((indicator) => repeated!.steamIds.includes(indicator.steamId64));
+      return total + (row?.totalRounds ?? 0);
+    }, 0);
+
+    expect(repeated!.indicators.kills).toBe(expectedKills);
+    expect(repeated!.indicators.totalRounds).toBe(expectedRounds);
+    expect(repeated!.perMatch).toHaveLength(repeated!.mapCount);
+  });
+
+  it("can merge borrowed Steam accounts through an external identity map", () => {
+    const firstSteamId = demos![0]!.pkg.players[0]!.steamId64;
+    const borrowedSteamId = demos!
+      .slice(1)
+      .flatMap((demo) => demo.pkg.players.map((player) => player.steamId64))
+      .find((steamId) => steamId !== firstSteamId)!;
+    const bundle = buildSeasonCohort(demos!, {
+      identityMap: {
+        [firstSteamId]: {
+          playerKey: "user:rivalhub-user-1",
+          userId: "rivalhub-user-1",
+          displayName: "Unified Player"
+        },
+        [borrowedSteamId]: {
+          playerKey: "user:rivalhub-user-1",
+          userId: "rivalhub-user-1",
+          displayName: "Unified Player"
+        }
+      }
+    });
+    const merged = bundle.players.find((row) => row.playerKey === "user:rivalhub-user-1");
+
+    expect(bundle.players).toHaveLength(baselineBundle!.players.length - 1);
+    expect(merged).toBeDefined();
+    expect(merged!.name).toBe("Unified Player");
+    expect(merged!.externalUserId).toBe("rivalhub-user-1");
+    expect(merged!.steamIds).toEqual([borrowedSteamId, firstSteamId].sort());
+    expect([...new Set(merged!.perMatch.map((row) => row.steamId64))].sort()).toEqual([borrowedSteamId, firstSteamId].sort());
+    expect(merged!.indicators.steamId64).toBe("user:rivalhub-user-1");
+    expect(merged!.prism?.steamId64).toBe("user:rivalhub-user-1");
+  });
+
+  it("scores season accountRR against the same frozen pro baseline as single matches", () => {
+    const mean = baselineBundle!.players.reduce((sum, row) => sum + row.accountRR, 0) / baselineBundle!.players.length;
+
+    expect(mean).toBeGreaterThan(0);
+    expect(mean).not.toBeCloseTo(1, 2);
+    expect(baselineBundle!.players.some((row) => row.accountRR > 1)).toBe(true);
+    expect(baselineBundle!.players.some((row) => row.accountRR < 1)).toBe(true);
+  });
+
+  it("recomputes rate fields from summed counts and rounds", () => {
+    const bundle = baselineBundle!;
+    const repeated = bundle.players.find((row) => row.mapCount > 1);
+    expect(repeated).toBeDefined();
+
+    const sourceRows = demos!
+      .flatMap((demo) => deriveRRIndicators(demo.pkg))
+      .filter((row) => repeated!.steamIds.includes(row.steamId64));
+    const damage = sourceRows.reduce((sum, row) => sum + row.adr * row.totalRounds, 0);
+    const rounds = sourceRows.reduce((sum, row) => sum + row.totalRounds, 0);
+    const plainAverageAdr = sourceRows.reduce((sum, row) => sum + row.adr, 0) / sourceRows.length;
+
+    expect(repeated!.indicators.adr).toBeCloseTo(damage / rounds, 2);
+    expect(repeated!.indicators.adr).not.toBeCloseTo(plainAverageAdr, 4);
+  });
+
+  it("lowers confidence when context sources are missing", () => {
+    const complete = baselineBundle!;
+    const stripped = buildSeasonCohort(
+      demos!.map((demo) => ({
+        matchId: demo.matchId,
+        pkg: { ...demo.pkg, playerEconomies: [], rounds: [] } satisfies DemoPackage
+      }))
+    );
+
+    expect(complete.players[0]?.confidence).toBeGreaterThan(stripped.players[0]?.confidence ?? 1);
+    expect(stripped.players.every((row) => row.confidence >= 0 && row.confidence <= 1)).toBe(true);
+  });
+
+  it("sums weapon distributions and highlight counts across identities", () => {
+    const bundle = baselineBundle!;
+    const repeated = bundle.players.find((row) => row.mapCount > 1)!;
+    const source = demos!
+      .flatMap((demo) => derivePlayerWeaponHighlights(demo.pkg))
+      .filter((row) => repeated.steamIds.includes(row.steamId64));
+    const expectedTotalKills = source.reduce((sum, row) => sum + row.totalKills, 0);
+    const expectedNoScopes = source.reduce((sum, row) => sum + (row.highlights.noScopeKills ?? 0), 0);
+    const expectedWeaponHeadshots = source
+      .flatMap((row) => row.weapons)
+      .reduce((sum, weapon) => sum + weapon.headshotKills, 0);
+
+    expect(repeated.weaponHighlights.totalKills).toBe(expectedTotalKills);
+    expect(repeated.weaponHighlights.weapons.reduce((sum, row) => sum + row.kills, 0)).toBe(expectedTotalKills);
+    expect(repeated.weaponHighlights.weapons.reduce((sum, row) => sum + row.headshotKills, 0)).toBe(expectedWeaponHeadshots);
+    expect(repeated.weaponHighlights.highlights.noScopeKills).toBe(expectedNoScopes);
+  });
+});

package/src/index.ts

@@ -1,33 +1,77 @@
 import {
-  deriveAccountSignalsV2,
+  deriveRRSignals,
   derivePlayerWeaponHighlights,
-  deriveRRIndicators,
-  computeAccountRatingsV2
+  deriveRRIndicators
 } from "@cs2dak/core";
 import {
   seasonCohortBundleSchema,
   type AccountContextAvailability,
-  type AccountSignalsV2,
   type DemoPackage,
   type RRIndicators,
+  type RRSignals,
   type PlayerWeaponHighlightFacts,
   type SeasonCohortBundle,
   type TeamKey,
-  type ValueAccountsWeights
+  type RRSixAccountWeights
 } from "@cs2dak/contract";
 import {
-  computeCohortAccountsRR,
+  computeFrozenProBaselineRR,
   computePrism,
   computeRR,
   prismWeightsV1,
+  rrSixAccountProBaselineV0,
   rrToPercentile,
-  rrValueAccountsV2Lite,
-  rrWeightsV1,
+  hltv2BaselineWeightsV1,
+  rrSixAccountWeightsV1,
+  type ProBaselineConfig,
   type PrismComputeInput,
   type PrismWeights,
   type RRWeights
 } from "@rivalhub/rival-rating";
 
+export { buildOpeningPatternClusters } from "./patterns.js";
+export type { OpeningPatternCluster, OpeningPatternInput, OpeningPatternOptions } from "./patterns.js";
+export {
+  advancedBasisKey,
+  buildTacticalClusters,
+  chokeComboOf,
+  defaultsBasisKey,
+  economyEntryOf,
+  entryEvidenceKey,
+  openingIntentKey,
+  openingPatternKey,
+  positionGroupSetKey,
+  tacticalClusterKey,
+} from "./tactical-clusters.js";
+export type {
+  EconomyEntry,
+  TacticalCluster,
+  TacticalEntryEvidence,
+  TacticalEntryEvidenceRoute,
+  TacticalExecuteBucket,
+  TacticalPatternRow,
+} from "./tactical-clusters.js";
+export {
+  buildPlayerMapRoleEvidence,
+  buildTeamMapResponsibilityEvidence,
+  MAP_ROLE_MODEL_VERSION,
+  MAP_ROLE_THRESHOLDS,
+  type MapRoleEvidenceFacts,
+  type MapRoleEvidenceOptions,
+} from "./map-role-evidence.js";
+export {
+  buildTResponsibilityResearchProjections,
+  scoreFrozenTResponsibilityFeatures,
+  T_RESPONSIBILITY_RESEARCH_MODEL_ID,
+  T_RESPONSIBILITY_RESEARCH_THRESHOLD,
+} from "./t-role-research-projection.js";
+
+
+/**
+ * "Season" 是历史命名：cohort = 任意一组比赛的跨场聚合，不限于赛季。
+ * 同一 API 服务于赛季排行（RivalHub）、单赛事统计（主办方）、个人全量复盘（玩家）
+ * 与自选职业 demo 集（分析师）；范围筛选由调用方决定（如 DAK Studio 的聚合范围过滤）。
+ */
 export interface SeasonCohortInput {
   matchId: string;
   pkg: DemoPackage;
@@ -35,11 +79,22 @@ export interface SeasonCohortInput {
 
 export interface SeasonCohortOptions {
   rrWeights?: RRWeights;
-  valueWeights?: ValueAccountsWeights;
+  valueWeights?: RRSixAccountWeights;
   prismWeights?: PrismWeights;
   identityMap?: PlayerIdentityMap;
 }
 
+export interface SeasonCohortFactRow {
+  matchId: string;
+  sourceDemoHash: string | null;
+  steamId64: string;
+  playerName: string;
+  teamKey: TeamKey;
+  signals: RRSignals;
+  indicators: RRIndicators;
+  weaponHighlight: PlayerWeaponHighlightFacts | null;
+}
+
 export interface PlayerIdentity {
   playerKey: string;
   displayName?: string;
@@ -57,7 +112,7 @@ interface PlayerAccumulator {
   names: Map<string, number>;
   teamKeys: Set<TeamKey>;
   mapCount: number;
-  signals: AccountSignalsV2[];
+  signals: RRSignals[];
   indicators: RRIndicators[];
   weaponHighlights: PlayerWeaponHighlightFacts[];
   perMatch: Array<{ matchId: string; steamId64: string; accountRR: number; rrV1: number }>;
@@ -67,59 +122,87 @@ export function buildSeasonCohort(
   demos: SeasonCohortInput[],
   opts: SeasonCohortOptions = {}
 ): SeasonCohortBundle {
-  const rrWeights = opts.rrWeights ?? (rrWeightsV1 as unknown as RRWeights);
-  const valueWeights = opts.valueWeights ?? (rrValueAccountsV2Lite as unknown as ValueAccountsWeights);
-  const prismWeights = opts.prismWeights ?? (prismWeightsV1 as unknown as PrismWeights);
-  const identityMap = opts.identityMap ?? {};
-  const players = new Map<string, PlayerAccumulator>();
-
+  const rrWeights = opts.rrWeights ?? (hltv2BaselineWeightsV1 as unknown as RRWeights);
+  const valueWeights = opts.valueWeights ?? (rrSixAccountWeightsV1 as unknown as RRSixAccountWeights);
+  const rows: SeasonCohortFactRow[] = [];
   for (const demo of demos) {
-    const signals = deriveAccountSignalsV2(demo.pkg);
+    const signals = deriveRRSignals(demo.pkg);
     const indicators = deriveRRIndicators(demo.pkg);
     const weaponHighlights = derivePlayerWeaponHighlights(demo.pkg);
-    const matchAccounts = computeAccountRatingsV2(demo.pkg);
-    const matchAccountBySteamId = new Map(matchAccounts.map((row) => [row.signals.steamId64, row.rr]));
-    const rrBySteamId = new Map(indicators.map((row) => [row.steamId64, computeRR(row, rrWeights)]));
-
+    const signalBySteamId = new Map(signals.map((row) => [row.steamId64, row]));
+    const indicatorBySteamId = new Map(indicators.map((row) => [row.steamId64, row]));
+    const weaponHighlightBySteamId = new Map(weaponHighlights.map((row) => [row.steamId64, row]));
     for (const player of demo.pkg.players) {
-      const signal = signals.find((row) => row.steamId64 === player.steamId64);
-      const indicator = indicators.find((row) => row.steamId64 === player.steamId64);
+      const signal = signalBySteamId.get(player.steamId64);
+      const indicator = indicatorBySteamId.get(player.steamId64);
       if (!signal || !indicator) continue;
-      const identity = resolveIdentity(player.steamId64, identityMap);
-
-      const acc = getOrInit(players, identity.playerKey, () => ({
-        playerKey: identity.playerKey,
-        steamIds: new Set<string>(),
-        primarySteamId64: player.steamId64,
-        externalUserId: identity.userId ?? null,
-        displayName: identity.displayName ?? null,
-        names: new Map<string, number>(),
-        teamKeys: new Set<TeamKey>(),
-        mapCount: 0,
-        signals: [],
-        indicators: [],
-        weaponHighlights: [],
-        perMatch: []
-      }));
-
-      acc.steamIds.add(player.steamId64);
-      if (!acc.externalUserId && identity.userId) acc.externalUserId = identity.userId;
-      if (!acc.displayName && identity.displayName) acc.displayName = identity.displayName;
-      acc.names.set(player.name, (acc.names.get(player.name) ?? 0) + 1);
-      acc.teamKeys.add(player.teamKey);
-      acc.mapCount += 1;
-      acc.signals.push(signal);
-      acc.indicators.push(indicator);
-      const weaponHighlight = weaponHighlights.find((row) => row.steamId64 === player.steamId64);
-      if (weaponHighlight) acc.weaponHighlights.push(weaponHighlight);
-      acc.perMatch.push({
+      rows.push({
         matchId: demo.matchId,
+        sourceDemoHash: demo.pkg.manifest.demo?.hash ?? null,
         steamId64: player.steamId64,
-        accountRR: round(matchAccountBySteamId.get(player.steamId64)?.rr ?? 0, 3),
-        rrV1: round(rrBySteamId.get(player.steamId64)?.rr ?? 0, 3)
+        playerName: player.name,
+        teamKey: player.teamKey,
+        signals: signal,
+        indicators: indicator,
+        weaponHighlight: weaponHighlightBySteamId.get(player.steamId64) ?? null
       });
     }
   }
+  return buildSeasonCohortFromRows(rows, {
+    ...opts,
+    rrWeights,
+    valueWeights,
+    matchCount: demos.length
+  });
+}
+
+export function buildSeasonCohortFromRows(
+  rows: SeasonCohortFactRow[],
+  opts: SeasonCohortOptions & { matchCount?: number } = {}
+): SeasonCohortBundle {
+  const rrWeights = opts.rrWeights ?? (hltv2BaselineWeightsV1 as unknown as RRWeights);
+  const valueWeights = opts.valueWeights ?? (rrSixAccountWeightsV1 as unknown as RRSixAccountWeights);
+  const proBaseline = rrSixAccountProBaselineV0 as unknown as ProBaselineConfig;
+  const prismWeights = opts.prismWeights ?? (prismWeightsV1 as unknown as PrismWeights);
+  const identityMap = opts.identityMap ?? {};
+  const players = new Map<string, PlayerAccumulator>();
+
+  for (const row of rows) {
+    const identity = resolveIdentity(row.steamId64, identityMap);
+
+    const acc = getOrInit(players, identity.playerKey, () => ({
+      playerKey: identity.playerKey,
+      steamIds: new Set<string>(),
+      primarySteamId64: row.steamId64,
+      externalUserId: identity.userId ?? null,
+      displayName: identity.displayName ?? null,
+      names: new Map<string, number>(),
+      teamKeys: new Set<TeamKey>(),
+      mapCount: 0,
+      signals: [],
+      indicators: [],
+      weaponHighlights: [],
+      perMatch: []
+    }));
+
+    acc.steamIds.add(row.steamId64);
+    if (!acc.externalUserId && identity.userId) acc.externalUserId = identity.userId;
+    if (!acc.displayName && identity.displayName) acc.displayName = identity.displayName;
+    acc.names.set(row.playerName, (acc.names.get(row.playerName) ?? 0) + 1);
+    acc.teamKeys.add(row.teamKey);
+    acc.mapCount += 1;
+    acc.signals.push(row.signals);
+    acc.indicators.push(row.indicators);
+    if (row.weaponHighlight) acc.weaponHighlights.push(row.weaponHighlight);
+    const accountRR = computeFrozenProBaselineRR(row.signals, valueWeights, proBaseline);
+    const rrV1 = computeRR(row.indicators, rrWeights);
+    acc.perMatch.push({
+      matchId: row.matchId,
+      steamId64: row.steamId64,
+      accountRR: round(accountRR.rr, 3),
+      rrV1: round(rrV1.rr, 3)
+    });
+  }
 
   const seasonRows = [...players.values()].map((acc) => {
     const signals = aggregateAccountSignals(acc.playerKey, acc.signals);
@@ -128,15 +211,11 @@ export function buildSeasonCohort(
     return { acc, signals, indicators, rrV1 };
   });
 
-  // 账户平衡（标准化 + 残差化）由 rival-rating 的 computeCohortAccountsRR 拥有（公式归属）。
-  // scale 对齐到 rrV1 的离散度，使 v2 与已被 HLTV 逆向验证的 v1 量纲可比。详见该库 docs/rr-v2.md
-  // 与本仓库 docs/design/cohort.md。
-  const targetStd = stdev(seasonRows.map((row) => row.rrV1.rr));
   const balancedByKey = new Map(
-    computeCohortAccountsRR(seasonRows.map((row) => row.signals), valueWeights, { targetStd }).map((b) => [
-      b.steamId64,
-      b
-    ])
+    seasonRows.map((row) => {
+      const scored = computeFrozenProBaselineRR(row.signals, valueWeights, proBaseline);
+      return [scored.steamId64, scored] as const;
+    })
   );
   const rrV1Scores = seasonRows.map((row) => row.rrV1.rr);
   const prismInputs: PrismComputeInput[] = seasonRows.map((row) => ({
@@ -148,15 +227,15 @@ export function buildSeasonCohort(
 
   return seasonCohortBundleSchema.parse({
     version: "cs2-demo-analysis-kit/cohort-1.0",
-    matchCount: demos.length,
+    matchCount: opts.matchCount ?? new Set(rows.map((row) => row.matchId)).size,
     weightsVersion: `${rrWeights.version}+${valueWeights.version}+${prismWeights.version}`,
     provenance: {
       cohortVersion: "cs2-demo-analysis-kit/cohort-1.0",
-      sourceSchemaVersion: "cs2-demo-format/2.0",
-      matches: demos.map((demo) => ({
-        matchId: demo.matchId,
-        sourceDemoHash: demo.pkg.manifest.demo?.hash ?? null
-      }))
+      sourceSchemaVersion: "cs2-demo-format/3.0",
+      matches: [...new Map(rows.map((row) => [row.matchId, {
+        matchId: row.matchId,
+        sourceDemoHash: row.sourceDemoHash
+      }])).values()]
     },
     players: seasonRows
       .map((row) => {
@@ -180,6 +259,7 @@ export function buildSeasonCohort(
           accountBreakdown: {
             combat: round(balanced.accounts.combat, 4),
             trade: round(balanced.accounts.trade, 4),
+            mapControl: round(balanced.accounts.mapControl, 4),
             clutch: round(balanced.accounts.clutch, 4),
             objective: round(balanced.accounts.objective, 4),
             utility: round(balanced.accounts.utility, 4)
@@ -200,7 +280,7 @@ function resolveIdentity(steamId64: string, identityMap: PlayerIdentityMap): Pla
   return value;
 }
 
-function aggregateAccountSignals(steamId64: string, rows: AccountSignalsV2[]): AccountSignalsV2 {
+function aggregateAccountSignals(steamId64: string, rows: RRSignals[]): RRSignals {
   return {
     steamId64,
     rounds: sum(rows, (row) => row.rounds),
@@ -227,7 +307,15 @@ function aggregateAccountSignals(steamId64: string, rows: AccountSignalsV2[]): A
       tradeKills: sum(rows, (row) => row.trade.tradeKills),
       tradedDeaths: sum(rows, (row) => row.trade.tradedDeaths),
       deaths: sum(rows, (row) => row.trade.deaths),
-      tradedOpeningDeaths: sumNullable(rows.map((row) => row.trade.tradedOpeningDeaths))
+      tradedOpeningDeaths: sumNullable(rows.map((row) => row.trade.tradedOpeningDeaths)),
+      strategicIsolationDeaths: sumNullable(rows.map((row) => row.trade.strategicIsolationDeaths))
+    },
+    mapControl: {
+      uniqueStrategicControlSeconds: sumNullable(rows.map((row) => row.mapControl.uniqueStrategicControlSeconds)),
+      contestedFrontierControlSeconds: sumNullable(rows.map((row) => row.mapControl.contestedFrontierControlSeconds)),
+      routeDenialSeconds: sumNullable(rows.map((row) => row.mapControl.routeDenialSeconds)),
+      teammateAdvanceUnits: sumNullable(rows.map((row) => row.mapControl.teammateAdvanceUnits)),
+      firstControlEvents: sumNullable(rows.map((row) => row.mapControl.firstControlEvents))
     },
     clutch: {
       vsOne: sumSplit(rows, (row) => row.clutch.vsOne),
@@ -243,8 +331,13 @@ function aggregateAccountSignals(steamId64: string, rows: AccountSignalsV2[]): A
     },
     utility: {
       flashAssists: sum(rows, (row) => row.utility.flashAssists),
-      enemyFlashDurationSeconds: sum(rows, (row) => row.utility.enemyFlashDurationSeconds),
-      teamFlashDurationSeconds: sumNullable(rows.map((row) => row.utility.teamFlashDurationSeconds)),
+      effectiveEnemyFlashSeconds: sumNullable(rows.map((row) => row.utility.effectiveEnemyFlashSeconds)),
+      teamFlashSuppressionSeconds: sumNullable(rows.map((row) => row.utility.teamFlashSuppressionSeconds)),
+      smokeProtectedCrossings: sumNullable(rows.map((row) => row.utility.smokeProtectedCrossings)),
+      smokeSightlineDenialSeconds: sumNullable(rows.map((row) => row.utility.smokeSightlineDenialSeconds)),
+      smokeIsolationSeconds: sumNullable(rows.map((row) => row.utility.smokeIsolationSeconds)),
+      incendiaryPathDelayUnits: sumNullable(rows.map((row) => row.utility.incendiaryPathDelayUnits)),
+      incendiaryDisplacementEvents: sumNullable(rows.map((row) => row.utility.incendiaryDisplacementEvents)),
       utilityDamage: sum(rows, (row) => row.utility.utilityDamage)
     }
   };
@@ -389,15 +482,7 @@ function aggregateWeaponHighlights(
   };
 }
 
-// 账户平衡的数学（标准化 + 残差化）已迁入 rival-rating 的 computeCohortAccountsRR（公式归属）。
-// 本层只负责把 std(rrV1) 作为 targetStd 传进去，对齐 v2 与 HLTV 逆向的量纲。
-function stdev(xs: number[]): number {
-  if (xs.length === 0) return 0;
-  const m = sum(xs, (x) => x) / xs.length;
-  return Math.sqrt(sum(xs, (x) => (x - m) ** 2) / xs.length);
-}
-
-function accountContextStatus(rows: AccountSignalsV2[]): { buyDelta: AccountContextAvailability; manState: AccountContextAvailability } {
+function accountContextStatus(rows: RRSignals[]): { buyDelta: AccountContextAvailability; manState: AccountContextAvailability } {
   return {
     buyDelta: availability(rows.map((row) => row.combat.killsByBuyDelta != null)),
     manState: availability(rows.map((row) => row.combat.killsByManState != null))
@@ -423,7 +508,7 @@ function availabilityScore(value: AccountContextAvailability): number {
   return 0;
 }
 
-function sumBuyDelta(values: AccountSignalsV2["combat"]["killsByBuyDelta"][]): AccountSignalsV2["combat"]["killsByBuyDelta"] {
+function sumBuyDelta(values: RRSignals["combat"]["killsByBuyDelta"][]): RRSignals["combat"]["killsByBuyDelta"] {
   const present = values.filter((value): value is NonNullable<typeof value> => value != null);
   if (present.length === 0) return null;
   return {
@@ -433,7 +518,7 @@ function sumBuyDelta(values: AccountSignalsV2["combat"]["killsByBuyDelta"][]): A
   };
 }
 
-function sumManState(values: AccountSignalsV2["combat"]["killsByManState"][]): AccountSignalsV2["combat"]["killsByManState"] {
+function sumManState(values: RRSignals["combat"]["killsByManState"][]): RRSignals["combat"]["killsByManState"] {
   const present = values.filter((value): value is NonNullable<typeof value> => value != null);
   if (present.length === 0) return null;
   return {

package/src/map-role-evidence.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest";
+import type { PlayerPositionRoundFact, TeamShapeRoundFact } from "@cs2dak/contract";
+import { buildPlayerMapRoleEvidence, buildTeamMapResponsibilityEvidence } from "./index.js";
+
+function row(playerIndex: number, roundNumber: number, overrides: Partial<PlayerPositionRoundFact> = {}): PlayerPositionRoundFact {
+  return {
+    analysisVersion: 6, matchId: "m1", mapName: "de_ancient", roundNumber, teamKey: "teamA", side: "ct",
+    playerIndex, steamId64: `7656119800000000${playerIndex + 1}`, eligibleSeconds: 20,
+    economyType: "full", openingWindow: { version: 1, startTick: 100, endTick: 1380, configuredSeconds: 20 },
+    openingEligibleSeconds: 20, openingPositionGroupDwell: [{ positionGroupId: playerIndex === 0 ? "a_anchor" : "b_anchor", seconds: 16, share: 0.8 }],
+    openingMeanComponentSize: 3, openingIsolationSeconds: 0, openingUtilityUseCount: 0,
+    openingPath: [],
+    positionGroupDwell: [{ positionGroupId: playerIndex === 0 ? "a_anchor" : "b_anchor", seconds: 16, share: 0.8 }],
+    unresolvedCalloutSeconds: 0, calloutCoverage: 1, meanNearestTeammateDistance: 200, meanTeamCentroidDistance: 300,
+    meanComponentSize: 3, isolationSegments: [], rejoinTicks: [], delayedConvergences: [], movementSync: 0.6, utilityUseCount: 0,
+    freezeAwpOwnership: playerIndex === 0, activeAwpSeconds: playerIndex === 0 ? 12 : 0, awpShots: playerIndex === 0 ? 2 : 0, awpKills: playerIndex === 0 ? 1 : 0,
+    availability: { replay: "available", nav: "available", callouts: "available", shots: "available" },
+    ...overrides,
+  };
+}
+
+describe("map role evidence", () => {
+  it("merges identities, computes team-relative AWP duty, and keeps unsupported maps out", () => {
+    const rows = Array.from({ length: 6 }, (_, index) => [row(0, index + 1), row(1, index + 1)]).flat();
+    rows.push(row(2, 1, { mapName: "de_vertigo" }));
+    const options = {
+      identityMap: { "76561198000000001": { playerKey: "player:one" } },
+      teamIdentityMap: { "m1:teamA": "Team One" },
+    };
+    const players = buildPlayerMapRoleEvidence({ playerPositionRounds: rows, teamShapeRounds: [] }, options);
+    const awper = players.find((player) => player.playerKey === "player:one")!;
+    expect(players).toHaveLength(2);
+    expect(awper.teamKey).toBe("Team One");
+    expect(awper.awp.duty).toBe("secondary_awper");
+    expect(awper.spatial.teamRelativeGroupShare).toBeGreaterThan(0);
+
+    const teams = buildTeamMapResponsibilityEvidence({ playerPositionRounds: rows, teamShapeRounds: [] }, options);
+    expect(teams).toHaveLength(1);
+    expect(teams[0]?.players).toHaveLength(2);
+  });
+
+  it("keeps missing replay data unknown and null instead of making a zero-valued role", () => {
+    const missing = row(0, 1, {
+      eligibleSeconds: null, positionGroupDwell: [], activeAwpSeconds: null, awpShots: null, awpKills: null,
+      availability: { replay: "missing", nav: "missing", callouts: "missing", shots: "missing" },
+    });
+    const evidence = buildPlayerMapRoleEvidence({ playerPositionRounds: [missing], teamShapeRounds: [] });
+    expect(evidence[0]).toMatchObject({ status: "unknown", awp: { activeSeconds: null, teamActiveShare: null } });
+  });
+
+  it("consumes opening component membership and formation continuity from TeamShapeRoundFact", () => {
+    const rows = Array.from({ length: 6 }, (_, index) => [row(0, index + 1), row(4, index + 1)]).flat();
+    const shapes: TeamShapeRoundFact[] = Array.from({ length: 6 }, (_, index) => ({
+      analysisVersion: 6, matchId: "m1", mapName: "de_ancient", roundNumber: index + 1, teamKey: "teamA", side: "ct",
+      openingWindow: { version: 1, startTick: 100, endTick: 1380, configuredSeconds: 20 },
+      openingWindows: [{ startTick: 100, endTick: 1380, coverageSeconds: 20, componentSizes: [4, 1], partition: "4+1", componentPlayerIndices: [[0, 1, 2, 3], [4]] }],
+      coverageSeconds: 40, windows: [{ startTick: 100, endTick: 2660, coverageSeconds: 40, componentSizes: [4, 1], partition: "4+1", componentPlayerIndices: [[0, 1, 2, 3], [4]] }],
+      availability: { replay: "available", nav: "available", callouts: "available", shots: "available" },
+    }));
+    const evidence = buildPlayerMapRoleEvidence({ playerPositionRounds: rows, teamShapeRounds: shapes });
+    expect(evidence.find((item) => item.playerKey.endsWith("1"))?.spatial).toMatchObject({ openingMainComponentShare: 1, formationShares: { "4+1": 1 } });
+    expect(evidence.find((item) => item.playerKey.endsWith("5"))?.spatial.openingIsolatedShare).toBe(1);
+  });
+
+  it("does not assign main-component credit when the opening has no unique majority core", () => {
+    const rows = Array.from({ length: 6 }, (_, index) => row(0, index + 1));
+    const shapes: TeamShapeRoundFact[] = Array.from({ length: 6 }, (_, index) => ({
+      analysisVersion: 6, matchId: "m1", mapName: "de_ancient", roundNumber: index + 1, teamKey: "teamA", side: "ct",
+      openingWindow: { version: 1, startTick: 100, endTick: 1380, configuredSeconds: 20 },
+      openingWindows: [{ startTick: 100, endTick: 1380, coverageSeconds: 20, componentSizes: [2, 2, 1], partition: "2+2+1", componentPlayerIndices: [[0, 1], [2, 3], [4]] }],
+      coverageSeconds: 20, windows: [], availability: { replay: "available", nav: "available", callouts: "available", shots: "available" },
+    }));
+    const evidence = buildPlayerMapRoleEvidence({ playerPositionRounds: rows, teamShapeRounds: shapes })[0]!;
+    expect(evidence.spatial.openingMainComponentShare).toBe(0);
+    expect(evidence.spatial.openingNoUniqueCoreShare).toBe(1);
+  });
+
+  it("aggregates team matrices to one row per unique player before overlap", () => {
+    const sameGroup = { openingPositionGroupDwell: [{ positionGroupId: "a_anchor", seconds: 16, share: 0.8 }], positionGroupDwell: [{ positionGroupId: "a_anchor", seconds: 16, share: 0.8 }] };
+    const rows = Array.from({ length: 6 }, (_, index) => [
+      row(0, index + 1, sameGroup), row(1, index + 1, sameGroup),
+      row(0, index + 1, { ...sameGroup, matchId: "m2" }), row(1, index + 1, { ...sameGroup, matchId: "m2" }),
+    ]).flat();
+    const teams = buildTeamMapResponsibilityEvidence({ playerPositionRounds: rows, teamShapeRounds: [] }, { teamIdentityMap: { "m1:teamA": "Team One", "m2:teamA": "Team One" } });
+    expect(teams[0]?.players).toHaveLength(2);
+    expect(teams[0]?.positionOverlap[0]?.playerKeys).toHaveLength(2);
+    expect(new Set(teams[0]?.positionOverlap[0]?.playerKeys).size).toBe(2);
+  });
+
+  it("produces support responsibilities only from observable utility timing and team coordination", () => {
+    const shapes: TeamShapeRoundFact[] = Array.from({ length: 6 }, (_, index) => ({
+      analysisVersion: 6, matchId: "m1", mapName: "de_ancient", roundNumber: index + 1, teamKey: "teamA", side: "t",
+      openingWindow: { version: 1, startTick: 100, endTick: 1380, configuredSeconds: 20 },
+      openingWindows: [{ startTick: 100, endTick: 1380, coverageSeconds: 20, componentSizes: [5], partition: "5", componentPlayerIndices: [[0, 1, 2, 3, 4]] }],
+      coverageSeconds: 20, windows: [], availability: { replay: "available", nav: "available", callouts: "available", shots: "available" },
+    }));
+    const supported = Array.from({ length: 6 }, (_, index) => row(0, index + 1, { side: "t", utilityUseCount: 1, openingUtilityUseCount: 1 }));
+    expect(buildPlayerMapRoleEvidence({ playerPositionRounds: supported, teamShapeRounds: shapes })[0]?.modifiers).toContain("utility_supportive");
+    expect(buildPlayerMapRoleEvidence({ playerPositionRounds: supported.map((item) => ({ ...item, utilityUseCount: 0, openingUtilityUseCount: 0 })), teamShapeRounds: shapes })[0]?.modifiers).not.toContain("utility_supportive");
+    expect(buildPlayerMapRoleEvidence({ playerPositionRounds: supported.map((item) => ({ ...item, side: "ct" })), teamShapeRounds: shapes })[0]?.modifiers).toContain("utility_supportive");
+  });
+});